Legion 1.8 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_allow_activation
     [-entire_class] [-debug] [-help]
     {[-c] <context path> | -l <LOID>}

Activates the object or instances of the class named in <context path> or <LOID>. It should be used in association with the-stay_down option of legion_deactivate_object or legion_deactivate_instances (page 16 and page 29, respectively).

The following options are supported:

`-entire_class`	Unlock all of the class's instances. You must be the class's owner in order to use this option.
`-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 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. For example, to copy the file object Foo to /home/myContext/Bar, you would enter:

$ legion_cp Foo /home/myContext/Bar

This copies the contents of Foo in the new file object Bar in the /home/myContext path.

You can now use wildcards in the <source path> parameter (for context space or local file space). Please note that you must escape the "*" character. The example below copies all files that start with "Foo" from local directory space into the /home/myContext context.

$ legion_cp -localsrc Foo\* /home/myContext

The new file objects are assigned the same names (e.g., if Foo\* finds Foo1 and Foo2, the duplicate file objects will be at /home/myContext/Foo1 and /home/myContext/Foo2).

Note that you cannot use wildcards in a destination path and you cannot copy multiple files to a single file object.

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 
     [-stay_down] [-debug] [-help]
     {[-c] <class context name> | -l <class LOID>}

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:

`-stay_down`	Forces instances to stay inactive. They can only be reactivated by `legion_allow_activation` (see page 26).
`-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] [-help] [-noserver] [-autorehash]
     <local directory path> <target context path>

The legion_export_dir command allows a complete directory tree in the local file system to be temporarily linked into Legion context space. A new context is created to replicate the local directory tree in context space. The files contained in the shared directory are copied in to Legion objects in the new context. The new context objects have the same names as the original files. For example, if the local directory contains three files called foo.txt, foo.doc, and foo.c, the new context will contain three Legion objects called foo.txt, foo.doc, and foo.c.

The command executes for as long as you wish: if you pause the command the tree's context space will not be available. Once you resume the command, the context will again be available.

To pause the command, run legion_export_dir_quit (below) or (if the command was started in -noserver mode) press ^-C. To resume using the exported files, re-execute the command, specifying the same local base directory path and target context path. You can also run legion_rm -r on the new context, which will recursively delete the context and its contents, to stop the command.

You can make changes to the shared local directory while the command is running, but those changes won't be reflected in context space unless you use the -autorehash flag or run legion_export_dir_rehash (below).

The following parameters are required:

`<local directory path>`	A local directory or directory tree that you wish to export to Legion context space.
`<target context path`>	A new context path which will hold copies of the exported directory tree.

The following options are supported:

`-v`	Verbose mode. Prints information about which files and directories the command is currently exporting.
`-help`	Print command syntax and exit.
`-noserver`	Keep the program attached to a terminal so that it can be shutdown via `^-C` and its output can be monitored.
`-autorehash`	Periodically check the shared local directory so that any changes are reflected in context space.

legion_export_dir_quit
     <target context path>

To be used in conjunction with legion_export_dir (above). Pauses legion_export_dir for the specified context path.

The following parameter is required:

<target context path>

A context path holding copies of an exported directory tree.

legion_export_dir_rehash
     <target context path>

To be used in conjunction with legion_export_dir (page 30). Tells the command to check the shared local directory for any changes and to update the shared context space accordingly.

The following parameter is required:

<target context path>

A context path holding copies of an exported directory tree.

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_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.

You can now use wildcards in the <context path> parameter. Please note that you must escape the "*" character. I.e., to search for context objects containing "foo" in their names you would enter:

$ legion_ls \*foo\*

You cannot use wildcards with the -R flag.

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. You cannot use this flag with wildcards.
`-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.

You can now use wildcards in the <context path list> parameter. Please note that you must escape the "*" character. I.e., to remove all context objects containing "foo" in their names you would enter:

$ legion_rm \*foo\*

Optional parameters do the following:

`-r`	Recursively remove one or more contexts and all of their contents.
`-f`	Forcibly remove faulty objects (those with bad bindings).
`-v`	Run this command in a verbose setting. This is useful for checking whether or not an object is removed.
`-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. (Please see page 75 in the Basic User Manual for a discussion of tty objects.) 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. Please see page 75 in the Basic User Manual for a discussion of tty objects.

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. Please see page 75 in the Basic User Manual for a discussion of 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). Please see page 75 in the Basic User Manual for a discussion of tty objects.

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. Please see page 75 in the Basic User Manual for a discussion of tty objects.

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. Please see page 75 in the Basic User Manual for a discussion of tty objects.

The following options are supported:

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

legion_2drm 
    <file name>

This command removes a 2D file object from Legion. It differs from legion_rm in that the object's subfiles are removed as well. If you use legion_rm to remove a 2D file object, the object's subfiles will not be removed.

The following parameter must be included:

file name

Local path of a 2D file object.

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

Free JavaScripts provided by The JavaScript Source

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