5.0 Working in context space
Legion has an assortment of context space command-line utility tools, and this section introduces some of the more useful ones for 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 other sources of information for Legion commands:
- An alphabetical list of commands (section A-1.0).
- A subject list of commands (section A-2.0).
- The Reference Manual has usage and descriptions of all command-line tools.
- All Legion packages have man pages for their commands. Man page usage is:
$ man <command tool>
- The Legion web site has on-line tutorials and a quick guide to all commands (<http://legion.virginia.edu/documentation.html>)
- Finally, most commands have a -help flag which prints the command's full usage:
$ <command tool> -help
- If this doesn't work, try just entering the command with no flags.
Please note that the sample outputs in this manual may not match your own. Your system administrator may have customized your system's context space or security considerations may limit your privileges in certain contexts. If you think there's something wrong, please consult your system administrator.
5.1 Viewing contexts
5.1.1 Read a context's contents
Just as the Unix ls command lists files in a directory, the legion_ls command shows all objects contained in a context. You will see something like this:
A context can hold classes, runnable objects, text objects, subcontexts, and any other Legion objects. A new Legion system contains a default context space with context names for existing objects. Please see page 14 for information about the default contents of context space.
Each name listed in a context refers to an object. Use -l to see if the object is a context, a class, or a file object. The -l flag prints object type and description. Objects of unknown type are described as (object) and faulty objects are described as (not available).
$ legion_ls -la
Foo 43 bytes
You can see the contents of a subcontext by using it as a parameter:
$ legion_ls /Bar
You can use an object's path as an argument:
$ legion_ls -l /Bar/Object1
You can also use wildcards to look for a naming pattern. For example, to look for context names containing "foo" you would enter:
$ legion_ls \*foo\*
Please note that you must escape the "*" character.
5.1.2 Look up LOIDs
If you know an object context name and need to know its LOID, you can using legion_ls -L. This flag lists LOIDs associated with the specified object(s). The output in both cases will be a "dotted hex" LOID. You can see the LOIDs of all objects in a context:
$ legion_ls -L
Or look up an individual object's LOID by using its context name as a parameter.
$ legion_ls -L /Bar/Object1
5.1.3 Create a new context
You can create new contexts with the legion_context_create command. It is similar to the Unix mkdir command. The new context will be placed in your current context if you do not provide a full path.
$ legion_context_create /tmp
5.1.4 Change your current context
The legion_cd command will change your 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.
The example below sets /tmp as the current working context.
$ legion_cd /tmp
You can check which context you are in with legion_pwd (below). Note that if you logged in with legion_login you are automatically moved to your /home/<user id> context.
5.1.5 Check your current context
Use legion_pwd (similar to Unix pwd) to check your current working context.
5.2 Naming objects
5.2.1 Assign a context name to a LOID
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.
$ legion_context_add 1.3933cb3f.07.01000000.000001fc0a
5.2.2 Give an object extra context names
You can give an object extra context names with legion_ln (similar to the Unix ln). The object must already have a context name (if it doesn't, use legion_context_add, above, to give it one).
You can place the new name anywhere in context space (anywhere you have permission to use), regardless of where the object's existing name(s) are placed. In the example below the object's existing context name is /vaults/BootstrapVault. We will give it an additional name, Foo. The new name goes in the current context:
$ legion_ln /vaults/BootstrapVault Foo
The two names both point to the same object and thus to the same LOID:
$ legion_ls -L Foo
$ legion_ls -L /vaults/BootstrapVault
Either name can be used to call on the object.
5.2.3 Change an object's context path
An object can be given a different context path with the legion_mv command (similar to the Unix mv command). For example, to change an object's path from Foo to Bar you would enter:
$ legion_mv Foo Bar
The object has the same LOID and physical location as before. The name Foo is automatically removed from the current context. However, any other use of the name Foo (whether with this or another object) will be unchanged.
5.2.4 List context names
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 only know its LOID, use legion_list_names -l:
$ legion_list_names -l 1.360830b6.07.0100000...
You may know a context name for an object but want to know if it has any other names. You can use the same command to see what (if any) other names the object has. The example below shows that BootstrapHost has two context names:
$ legion_list_names /hosts/BootstrapHost
Or, you can use legion_ls with the -A flag. However, you must use an existing context name as an argument:
$ legion_ls -A /hosts/BootstrapHost
These commands will list all context names for the object, including those assigned by other users. Please note, though, that you may not have "read" privileges for viewing other users' contexts and you may get a security error message if the command cannot print all of the object's context paths.
5.2.5 Remove names and objects
Remove (i.e., destroy) context names and objects with legion_rm. Note, though, that 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). (Use legion_list_names or legion_ls -A to check for extra names.)
For example, if an object has the names Foo and Foo2 and you remove Foo the object remains. However, if you then remove Foo2 the object will be destroyed.
You can use -v to run legion_rm in a verbose setting, which will show you whether objects or just context paths are being destroyed:
$ legion_rm -v foo
Removing context name "foo"
$ legion_rm -v foo2
Removing context name "foo2"
Destroying object "foo2" (1.3759173a.690...)
You can use wildcards to remove groups of names or obects. I.e., to remove all context names starting with "Foo" you would enter:
$ legion_rm Foo\*
Please note that you must escape the "*" character. You cannot remove names or objects that you do not own.
5.2.6 Remove an entire context
To remove an entire context, use legion_rm -r. This recursively removes the context and all of its contents.
5.2.7 Use the same name in different contexts
As described on page 23, you can use the same context name in different context paths. For example, suppose that you give object Foo the extra name Bar:
$ legion_ln Foo Bar
The new name goes in the current context but it can still be used in any other context. The example below uses it in the tmp context for object Foo2:
$ legion_ln Foo2 /tmp/Bar
That means that the name Bar is used in your current context and in /tmp to point to two different objects. The two paths could also point to the same object:
$ legion_ln Foo Bar
$ legion_ln Foo /tmp/Bar
5.3 Moving between local files and contexts
Use legion_cp to copy the contents of a local file to a Legion BasicFileObject and vice versa. It will also copy one BasicFileObject to another. This command only works with BasicFileObjects. Note that if you copy material to an existing BasicFileObject the new material will write over the old contents.
22.214.171.124 Copy a local file to Legion
Use -localsrc to copy a local file into Legion. The example below copies the Unix file UnixTextFile.txt from your local directory into Legion.
$ legion_cp -localsrc UnixTextFile.txt newFileObject
Note that this will copy the Unix file's contents into to a new Legion BasicFileObject.
126.96.36.199 Copy from Legion to a local file
Use -localdest to copy a Legion file object to a local file. The example below copies Foo to UnixTextFile.txt.
$ legion_cp -localdest Foo UnixTextFile.txt
Please note that this will overwrite any previously existing files called UnixTextFile.txt.
188.8.131.52 Copy from Legion to another Legion file object
The legion_cp command will also copy the contents of a BasicFileObject to a new file object. Here it copies the contents of Foo to BasicFileObject Foo_copy.
$ legion_cp Foo Foo_copy
184.108.40.206 Using wildcards when copying
You can use wildcards in the source parameter to copy a group of files into Legion context space. The example below copies all local files that start with "Foo" into /home/myContext.
$ legion_cp -localsrc Foo\* /home/myContext
Please note that you must escape the "*" character with a "\". You cannot use wildcards in your destination path: the new Legion objects have the same names as their local originals. So, if Foo\* yields Foo1 and Foo2, the duplicate Legion file objects will be Foo1 and Foo2.
5.3.2 Look at a file object's contents
You can view the contents of a Legion file object with legion_cat (similar to Unix cat). The contents are printed to standard output.
$ legion_cat FileObject
Here are the contents of FileObject.
This only works with text object (BasicFileObjects). If you try to run it with another kind of object (such as a class object) you'll get an error.
5.3.3 Import a local Unix tree
You can copy the contents of a local file tree from your local file space into context space with legion_cp. You'll need to use -r to copy in recursive mode and -localsrc to copy from your local directory. The usage is:
-r -localsrc <Unix directory> <new context path>
If you do not provide a full context path for the directory (e.g., new_stuff instead of /home/me/new_stuff), the new context will be placed in your current context. It will copy the structure of the directory, including creating any necessary subcontexts. The Legion copies will have the same names as your local originals.
For example, say you want to copy your local directory wrk into Legion. The wrk tree contains two subdirectories, /foo and /bar. To copy the directory in to the current context you would enter:
$ legion_cp -r -localsrc wrk tmp
Legion will create a new context in the current context, name it tmp, and copy the contents of wrk. It also creates two new contexts in tmp, called foo and bar. Legion automatically gives all copied objects the same name as the original Unix files and subdirectories.
5.3.4 File sharing: temporarily link files to Legion
You can temporarily link your local files with context space with legion_export_dir temporarily links a local directory tree to 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. For example:
$ legion_export_dir local_directory_Foo \
Legion creates a new context called /Bar, which is linked to local_directory_Foo. Any changes that you make to /Bar, such as changing or removing context names, will be reflected in local_directory_Foo. To see changes you make to the local directory while the command is running, run legion_export_dir_rehash with the temporary context name as a parameter. I.e.:
$ legion_export_dir_rehash /home/myContext/Bar
The command executes only for as long as you wish: you can pause the command so that the new context is temporarily unavailable. Once you resume the command, the context is available. 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 so you should also delete the temporary context with legion_rm -r when you are finished. I.e.:
$ legion_rm -r /home/myContext/Bar