Legion 1.6.4 Reference Manual: 2.4 Calls on file and context objects

2.4 Calls on file and context objects

legion_activate_instances 
     {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Activates all instances of the class named in <class context path> or <class LOID>. Instances that are already active will be unaffected.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_cat 
     <context path1> <context path2> ... <context pathN> 
     [-debug] [-help]

Prints the contents of the Legion file object(s) named in <context path> to standard output. It is similar to the Unix cat command.

$ legion_cat newFileObject
blah, blah, blah.
$

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_cd 
     <context path> [-debug] [-help]

Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. This command is identical to the legion_set_context command and analogous to the Unix cd command.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_context_add 
     <object LOID> <context name> [-debug] [-help]

Adds a new name <context name> for the object named in <object LOID> to the current context space.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_context_create 
     <context path> [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command. The new context will be placed in your current context.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_cp 
     [-r] [-v] [-m] [-p] [-localsrc] [-localdest]
     [-V <vault context path>] <source path> <destination path> 
     [-debug] [-help]

Copies the file object or tree named in <source path> (named as either a context path or a local path) to a new, duplicate, file object or tree named in <destination path> (named as either a context path or a local path). Use the recursive mode (-r) to export objects to local file space. Analogous to the Unix cp command.

The following optional parameters are supported:

`-v`	Verbose mode. Prints information about which files and directories the command is currently working on.
`-r`	Recursive mode. If the `<source path>` is a directory, all of its contents are copied recursively. Only files and contexts/directories are handled. If other objects are encountered, they are skipped and `legion_cp` prints a warning message. Note that recursive mode automatically detects cycles in context space and prevents the recursive copy from revisiting context nodes in the cycle. A warning message is printed in the event that cycles are detected.
`-localsrc`	Local source mode. Use to indicate that the file or directory to be copied (`<source` `path>`) is in the local file system. By default the `<source path>` is assumed to be in Legion context space.
`-localdest`	Local destination mode. This option indicates that the `<destination path>` is in the local file system. The path is assumed to be a Legion context path.
`-V` `<vault context path>`	Specify a vault restriction for new objects created by this command. Supply the context path of the vault that should manage new objects created as `legion_cp` runs.
`-m`	Match-class mode. This mode indicates that when files or contexts are created by this command, they should match the class of their source context or file. By default, new files and contexts are created using the default file and context classes for your current Legion environment. This mode can only be used when copying within Legion context space (i.e., without `-localsrc` or `-localdest`).
`-p`	Print out the size, transfer time, and transfer rate for each file copied.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_deactivate_instances 
     {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Deactivates all instances of the class named in <class context path> or <class LOID>. Instances that are already deactivated will be unaffected.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_destroy_instances 
     {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Destroys all instances of the class named in <class context path> or <class LOID>. Any active instances are deactivated.

This command will remove the LOIDs of the specified class' instances in all contexts, not just the current context. However, it will not remove any context name associated with this object: you must use the legion_rm command to remove the object's name(s), or you will get binding errors. (You can use legion_ls -A to check for multiple context names.)

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_direct_output 
     {[-c] <object context path> | -l <object LOID>}
     {[-c] <tty context path> | -l <tty LOID>} [-debug] [-help]

Causes the object named in <object path> or <object LOID> to direct its output (standard out and standard error) to the Legion tty object named by <tty context path> or <tty LOID>. Note that this command can only be invoked on objects that have dynamic output redirection enabled. If the command is invoked on an object that does not have redirection enabled, neither the object nor the tty is affected and an error message is displayed.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_export_dir 
     [-v] [-fc] [-cc] 
     <local base directory path> <target base context path> 
     [-debug] [-help]

The legion_export_dir command allows a complete directory tree in the local file system to be linked into Legion context space without requiring the creation of file copies. A new context will be created to match the local directory tree, and new context names will match the local directory's file names. The command executes only during the duration of time that you wish to use the exported files and directories: if you pause the command the tree's context space will not be available. Once you resume the command, the context will be available.

This is a temporary, read-only context: any changes that you make to the new context, such as changing or removing context names, will not be reflected in the local directory tree (and vice versa). For best results, do not make any changes to the exported directory tree or to the tree's context. For this same reason you should delete the tree's context space when you are finished.

To pause the command, press ^-C. To resume using the exported files, re-execute the command, specifying the same local base directory path and target context path. Use of exported files and directories while the command is not active will cause binding errors. The context space will not be automatically removed when the command is paused or stopped. To delete an exported directory tree's context space, use legion_rm -r while legion_export_dir is active.

The following options are supported:

`-v`	Verbose mode. Prints information about which files and directories the command is currently exporting.
`-fc`	Specify the context path of the file object class. This class should be an instance of the metaclass `/class/ProxyBindingMetaClass`, since the style of file object used by `legion_export_dir` requires specialized binding services. The default is `/class/FileProxyClass`.
`-cc`	Specify the context path of the class to use for context objects. This class should also be an instance of `/class/ProxyBindingMetaClass`. The default used is `/class/ContextProxyClass`.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_get_host 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

This command looks up and returns the LOID of the host on which the object named in <object context path> or <object LOID> currently resides.

$ legion_get_host Foo
1.01.07.d49d1a40.000001fc0c04724...
$

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_get_vault 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_import_tree 
     [<unix directory path> [<legion context path>]] [-debug] [-help]

Recursively copies a local directory tree in Unix space, named by <unix directory path>, into a Legion context, named by <legion context path>. The output will include the new context's LOID and location. Pathnames can be relative or absolute. Default values are the current working directory and the current working context.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_list_names 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Lists all of the given object's context names. This includes names assigned by other users. The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_ln 
     <context path> <new alias> [-debug] [-help]

Assigns an additional name, given in <new alias>, to the object named in <context path>. Analogous to the Unix ln command. Path names can be relative or absolute.

An object can have multiple context names, assigned by one or more users. The same context name can be assigned to different objects or to the same object so long as the contexts names are in different contexts (just as the same file names can be used in different levels of a Unix directory).

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_ls 
     [-laLRAdqv] [<context path>] [-debug] [-help]

Lists the contents of a named Legion context in ascii-alphabetical order. Note that the pathname can be relative or absolute. The command is analogous to the Unix ls command. The default setting lists the current context. You can include a context path in the <context path> parameter to list the contents of that context. For example:

$ legion_ls /hosts
BootstrapHost
my.host.DNS.name
$

You can get more specific information (object type, LOID, other context aliases, state) about objects with the flags. For example, you can get more information about a particular context's objects with the -l, -a, and -A flags. The output below shows a complete list of all objects listed in this context, the objects' types, and any context aliases associated with each listed object.

$ legion_ls -laA /hosts
. 	(context)
        /hosts
..	(context)
        /class/..
        /hosts/..
        /vaults/..
        /home/..
BootstrapHost	(object)
        /hosts/BootstrapHost
        /hosts/host.DNS.name
host.DNS.name	(object)
        /hosts/BootstrapHost
        /hosts/host.DNS.name
$

According to this, there are four names listed in /hosts, two referring to contexts and two to objects. We can see from the alternative context names, though, that BootstrapHost and my.host.DNS.name refer to the same object.

Optional parameters do the following:

`-l`	List object type and information, if available. Objects of unknown type will be listed as `object` and faulty objects will be listed as `not available`.
`-a`	List "hidden" objects in the context, i.e. those objects whose names begin with a "." character. Examples would be the "`.`" (current) and "`..`" (parent) contexts.
`-L`	List the LOID associated with each entry.
`-R`	Print a recursive list of the current context.
`-A`	List all known context aliases for each listed object.
`-d`	List contexts like other objects, rather than listing their contents.
`-q`	When creating a long list, do not activate inactive objects.
`-v`	Run command in verbose mode.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_mkdir 
     <context path> [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command (it is also identical to the legion_context_create command). The new context will be placed in your current context. The output will contain the new context's location and its LOID.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_mv 
     <context path> <new context path> [-debug] [-help]

Assigns a new context name, given in <new context path> to the object named in <context path>. Pathnames can be relative or absolute. Analogous to the Unix mv command.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_pwd
     [-debug] [-help]

Prints your current context path. Similar to the Unix pwd command.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_rm 
     [-r] [-f] [-v] <context path list> [-debug] [-help]

Removes the context path[s] named in <context path list> from Legion context space. Pathnames can be relative or absolute. Analogous to the Unix rm command.

If the context path listed is the last (i.e., only) name mapped to a given object, the object will be destroyed.

Optional parameters do the following:

`-r`	Recursively remove one or more contexts and all of their contents.
`-f`	Force faulty objects (those with bad bindings) to be removed.
`-v`	Run this command in a verbose setting. This will indicate when objects are destroyed and when only names are being destroyed.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_set_context 
     <context path> [-debug] [-help]

Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. Analogous to the Unix cd command.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_set_tty 
     <tty context path> [-debug] [-help]

This command will set an environment variable to indicate which tty object should be used by subsequent programs. By selecting a new current tty object, users can redirect the output to any window or file.

$ legion_set_tty /context_path/my-tty

Note that program output does not have to be directed to the same window in which the program is run. By setting a new current tty object, the output can be redirected to any window, or even a file. For example:

$ legion_create_object -c /class/ttyObjectClass my-tty
$ legion_set_tty /log-file

creates a tty object whose output is sent to a file. To view the tty output, use the legion_tty_watch command (below).

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_tty 
     <tty context path> [-debug] [-help]

This command can be used to direct all output from a particular shell back to that shell (i.e., create and set a tty object for a shell) in one step, rather than running legion_create_object, legion_set_tty, and legion_tty_watch. If no tty object exists at the path named in <tty context path> it creates a new object, sets it as the target tty, and starts the legion_tty_watch process in the background of the shell in which the command was run. If a tty object already exists at the named context path, the command sets that tty object as the target.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_tty_off
     [-debug] [-help]

Unsets (stops) the Legion tty object for the current shell so that Legion programs executed in that shell after legion_tty_off is run will not display their output to a Legion tty object. This command also shuts off the background legion_tty_watch process for the current shell. This command only works on tty objects that have been set with the legion_tty command. See legion_tty_watch for information on turning off other tty objects.

Note that this does not destroy the tty object. The object can be reused with legion_tty, legion_set_tty, or legion_tty_watch.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_tty_redirect 
     <object context path> [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stream directly into the file object named in <object context path>. If the file does not already exist the system creates it. Existing files are appended to, not truncated. A single tty object can be simultaneously directed into any number of files (as well as watched from any number of terminal windows).

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_tty_unredirect 
     <object context path> [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stop streaming into the file object named in <object context path>. If the tty object is not currently directing output to the named file the command is ignored.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_tty_watch 
     [[-c] <tty context path> | -l <tty LOID>] [-debug] [-help]

Causes output written to a Legion tty object to be printed to standard output. If no command line parameters are specified, the current tty object set for the shell session is selected. Otherwise, the tty object named in <tty LOID> or <tty context path> is selected. Note, the command will not self-terminate: to stop the program send it a SIGINT (i.e., using ^C or "kill -INT"). Any number of legion_tty_watch sessions may simultaneously watch the same Legion tty object.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

Directory of Legion 1.6.4 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/