Legion has an assortment of context space command-line utility tools, and this section introduces some basic tools for working with contexts and context space. You'll notice that many resemble Unix commands in both name and purpose, which should make Unix users feel more comfortable. Your local file path will not change as you move through context space. Full path syntax can be used as well as relative path syntax in all Legion commands
There are several other sources of information about Legion context space and commands: an alphabetical list (section A-3.0) and a subject list (section A-4.0) of all commands' syntax are in this manual; the Reference Manual documents all commands; all Legion release packages include man pages1; and the Legion web site has on-line tutorials and a quick guide to all commands (<http://legion.virginia.edu/documentation.html>). Finally, you can type
Please note that the sample outputs in this section may not match your own. Your system administrator may have customized your system's context space or limited what parts you can see. If you think there's something wrong, please consult your system administrator.
Just as the ls command in Unix lets you view files located in a directory, the legion_ls command shows all objects contained in a context. The root context of a new system will look something like this:
There are several flags for this command (not all of which will be discussed here -- see page 29 in the Reference Manual for a discussion of all legion_ls flags).
You can use the -l and -a flags to get more information about one or more objects. The -l flag displays object type and description. Objects of unknown type will be listed as (object) and faulty objects will be listed as (not available). The -a flag will list "hidden" objects, i.e. those objects whose name begin with a "." character.
There are two ways to look up LOIDs, both using legion_ls. The output in both cases will be a "dotted hex" LOID.2 If you want to look up an individual object's LOID, use its context name as a parameter.
The legion_set_context command will change the current working context (it is similar to the Unix cd and chdir commands). It sets an environment variable in the shell in which it has been invoked and is implemented as an alias (as supported by your shell) that sources the script legion_set_context.sh or legion_set_context.csh. The example below sets /tmp as the current working context.
You can give an object extra context names with legion_ln (similar to the Unix ln command). Please note that the object must already have a context name. If it doesn't, use legion_context_add to assign it a name (below).
You can place the new name in any context you wish, regardless of where the object's existing name(s) are placed. The example below puts the bootstrap vault object's new name, Foo, in the current working context, even though the object's existing name (/vaults/BootstrapVault) is in the /vaults context.
The legion_context_add command maps a new context name to a LOID. It can be used to name a previously unnamed object or to assign an extra name to a previously named object. Either way, you need to use the object's full LOID as a parameter. In the example below, the name neo is assigned to a LOID.
Whatever object Bar is now pointing to has the same LOID or physical location as before. This command only affects context names. The name Foo is automatically removed from the current context path, but not from any other path. Any other use of the name Foo will be left alone.
There are two commands that list an object's context names, legion_list_names and legion_ls. Both produce a list of all context names pointing to your object. If you don't know any names but do know the object's LOID, use legion_list_names with the -l flag:
You can remove (i.e., destroy) context names and objects with legion_rm. If there are no other names assigned to the object, it will be destroyed. If there are other names assigned to the object, legion_rm will just remove the specified name(s). Be sure to check this with either legion_ls or legion_list_names if you are not sure.
For example, if an object has two names, Foo and Foo2, and you remove just the name Foo the object would remain. However, if you then remove Foo2 the object will be destroyed, since there are no other names.
As discussed in section 4.3, the same context name in different context paths can point to different Legion objects.
That means that the name Bar is used in two different contexts to point to two different objects, Foo and Foo2. If you prefer, you can use the same name in different context paths to refer to the same object:
Use the legion_cp command to copy the contents of a local file into a Legion BasicFileObject and vice cersa as well as to copy between BasicFileObjects. Note that if you copy new material into a previously existing BasicFileObject the new material will write over the old contents. This command only works with BasicFileObjects.
You can use wildcards in the source parameter to copy a group of files into Legion context space. The example below copies all files that start with "Foo" from the local directory into the /home/myContext context.
You can copy the contents of a local file tree from your local file space into context space with the legion_import_tree command. The contents of local files will be automatically copied into new Legion BasicFileObjects.
In the example below, the contents of the Unix directory legion.practice will be copied into the current Legion context. A listing of the Unix tree's contents shows that the tree contains one subdirectory and three files. The subdirectory (/nextlevel) also contains three files:
The default values of legion_import_tree are the current Unix tree and the current Legion context, but you can specify the directory and/or the context paths (see page 28 in the Reference Manual for full usage).
The legion_export_dir command allows a complete local directory tree to be temporarily linked to Legion context space. 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 again.
Legion creates a new context called /Bar, which is linked to local_directory_Foo. This is a read-only context: any changes that you make to /Bar, such as changing or removing context names, will not be reflected in local_directory_Foo (and vice versa). For best results, do not make any changes to either the directory or the context. You should also delete /Bar (with legion_rm) when you are finished.
To pause the command, press ^-C. To resume using the exported files, re-execute the command, specifying the same local directory path and context path. If you try to use your exported files and directories while the command is paused you will get 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. E.g.,
1.Man page usage is man <command name>: ask your system administrator if you are unsure about using man pages on your system. You can also go to <http://legion.virginia.edu/legion_man.html> to see on-line versions of the Legion man pages. back
2.In the interests of space and readability, in this and some of the following examples the entire LOID is not reproduced. back