6.0 Working in context space

In Unix space you move around directory space with command-line utilities, and Legion provides commands to let you move around in context space. The remainder of this section discusses some basic context-related command line utilities. Most resemble Unix commands in both name and purpose to make them easier to use (e.g., legion_ls, legion_rm).

There are several other sources of information about Legion context space and commands: this manual has an alphabetical list (Alphabetical list of Legion commands) and a subject list (Subject listing of Legion commands) of all commands' syntax; the Reference Manual lists all commands and instructions for using them; the Legion web site has on-line tutorials and postscript documents (<http://legion.virginia.edu>); and the Legion release package includes man pages for all commands.1

6.1 View a context's contents

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:

$ legion_ls /
class
home
hosts
impls
vaults
$

But you might see something different, depending on your individual system:

$ legion_ls /
Fooclass
Foofile
Fooobject
class
home
hosts
impls
vaults
$

To view sub-contexts (similar to sub-directories), use a context's name as argument:2

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

You can use the legion_ls flags to get more specific information. There are eight flags, not all of which are discussed here. Please see legion_ls in the Reference Manual for more information.

You can use the -l and -a flags to get more detailed lists. The -l flag includes objects' type and description.

$ legion_ls -l /
Fooclass	(class)
Foofile	43 bytes
Fooobject	(object)
class	(context)
home	(context)
hosts	(context)
impls	(context)
vaults	(context)
$

Objects of unknown type will be listed as (object) and faulty objects will be listed as (not available).

The legion_ls command will not list the "hidden" objects, i.e. those objects whose name begin with a "." character (such as "." and "..") unless you use the-a flag.

$ legion_ls -a /
.
Fooclass
Foofile
Fooobject
class
home
hosts
impls
vaults
$

The -L flag will list the LOIDs associated with the context's entries:

$ legion_ls -L /
Fooclass 1.35fe7c3d.07..000001fc0a7838d45ed
Foofile 1.01.66000000.02000000.00000...
Fooobject 1.35fe7c3d.66000000.01000000.00
class 1.01.05.02000000.00000...3
home 1.01.05.05000000.00000...
hosts 1.01.05.03000000.00000...
impls 1.01.05.06000000.0000
vaults 1.01.05.04000000.00000...
$

You can also use this command to get specific information about an individual object by using the object's context name as an argument. For example:

$ legion_ls -L Foofile
Foofile 1.01.66000000.02000000.00000...
$
6.2 Looking up an object's LOID

You can look up an object's LOID with the legion_ls command. The output will be a "dotted hex" LOID. You will need to include the object's context space name (its context path) as a parameter.

$ legion_ls -L /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$
6.3 Create a new context

You can create new contexts with the legion_context_create command. This is similar to the Unix mkdir command. Note that the output includes the new context's location and its LOID.

$ legion_context_create /tmp
Creating context "tmp" in parent "/".
New context LOID = "1.01.05.07000000.000001fc0d02..."
$

6.4 Changing the working context

The legion_set_context command will change the current working context.

$ legion_set_context /tmp

The sub-context tmp is now the current working context.

This command 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.

6.5 Checking the current working context

You can use the legion_pwd command to check your current working context. It will print your current context path on the command line. So, for example, the output below tells you that you are in the tmp sub-context.

$ legion_pwd
/tmp
$

This command is similar to the Unix pwd command.

6.6 Assigning alternate names to existing contexts

You can create alternate names for objects with legion_ln, a command similar to the Unix ln command. Note that this works only with objects that already have a context name. If no context name has been assigned, you will need to use a different command (such as legion_context_add: see Assigning a context name to a LOID) to assign a name to the LOID.

Here, the new name Foo is assigned to the BootstrapHost object and placed in the current working context (/tmp).

$ legion_ln /hosts/BootstrapHost Foo

$ legion_ls
Foo                                    
$

Note that BootstrapHost and Foo have different context paths but both names point to the same object (a host object in this case) and thus to the same LOID.

$ legion_ls -L Foo
1.01.07.01000000.000001fc0a8e60138a9...
$

$ legion_ls -L /hosts/BootstrapHost
1.01.07.01000000.000001fc0a8e60138a9...
$

Either name can be used to manipulate the object.

6.7 Assigning a context name to a LOID

The legion_context_add command maps an object's LOID to a new context name. 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 include the object's full LOID as a parameter.

In the example below, the name newName is assigned to a LOID.

$ legion_context_add 1.01.66000000.05... newName
6.8 Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). The object keeps the same LOID but gets a different context path name. In the example below, object Foo is renamed Bar.

$ legion_mv Foo Bar

The name Foo is automatically removed from the current context. This process affects only a specific context path: any other use of the name Foo, whether somewhere else in this user's or any other user's context space, will be unchanged.

6.9 Listing an object's names

There are two commands that will show an object's context names: legion_list_names and legion_ls. Note, though, that you must use a context name as an argument for legion_ls, so you'll need to know at least one of the object's names.

Use the legion_ls command with the -A flag to look up an object's other (if any) name[s]:

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

The legion_list_names command will list all context paths that have been assigned to a given object. If, for example, you knew an object's LOID but not its context name you could use the -l flag to ask Legion to look up the object's name. The output below asks for the context names that have been assigned to a LOID then shows that this is the BootstrapVault's LOID.

$ legion_list_names -l 1.360830b6.07.0100000...
/hosts/BootstrapVault
$

If you already know an object's name you can use the -c flag to see what (if any) other names it has. The example below shows that BootstrapHost has two names, BootstrapHost and my.host.DNS.name:

$ legion_list_names -c /hosts/BootstrapHost
/hosts/BootstrapHost
/hosts/my.host.DNS.name
$
6.10 Removing names

You can remove (i.e., destroy) context names with legion_rm.

$ legion_rm Foo

Note that destroying a context name does not necessarily destroy its associated object. If there are other names assigned to the object legion_rm will just remove the specified name(s). If there are no other names, however, the object will be destroyed. For example, if you gave Foo an additional name:

$ legion_ln Foo Foo2
$ legion_rm Foo

The name Foo would be removed but the object itself would be unaffected. However, if you then ran:

$ legion_rm Foo2

Both the name and the object would be destroyed, since Foo2 is the only remaining context name. You can use the -v flag to run legion_rm in a verbose setting, which will show you whether objects or just context paths are being destroyed.

You can use legion_ls -A to check which names are mapped to an object.

$ legion_ls -A Foo
/Foo
        /Foo
        /Foo2
$

If you want to remove an entire context, use legion_rm -r: the -r flag recursively destroys a context and all of its contents.

6.11 Using the same name in different contexts

As discussed in Organizing context space, the same context name can be used in different context paths to refer to different Legion objects. For example, the name Foo can be assigned to two different objects in two different contexts.

Below, the name Foo is assigned to a LOID with the legion_ln command. Foo is placed in the current context. The same name, in the tmp context, is then assigned to a different object.

$ legion_ln 1.01.05.6e0c2... Foo
$ legion_ln 1.01.66000... /tmp/Foo

Alternatively, the same name can be used in different context paths to refer to the same object:

$ legion_ln 1.01.05.6e0c2... Foo
$ legion_ln 1.01.05.6e0c2... /tmp/Foo
6.12 Copying a local file to a Legion file object

You can copy the contents of a local file to a Legion file object with the legion_cp command. The example below copies the contents of a local Unix file, UnixTextFile.txt, to a new Legion file object, called newFileObject, in the current working context.

$ legion_cp -localsrc UnixTextFile.txt newFileObject

The -localsrc flag indicates that UnixTextFile.txt can be found in the local file system.

Note that if you copy new material into a previously existing file object the new material will write over any old material.

6.13 Copying a Legion file object

The legion_cp command will also copy the contents of a file object to a new file object.

$ legion_cp FileObject FileObject_copy

Use the -localdest flag to copy the contents of a Legion file object to a new text file in the local file system.

$ legion_cp -localdest FileObject anotherTextFile.txt
6.14 Viewing a file object's contents

You can view the contents of a Legion file object with the legion_cat command (similar to the Unix cat command). The contents are printed to standard output.

$ legion_cat FileObject
This is a test, just a test, nothing more.
$
6.15 Importing a local Unix tree

You can copy the contents of a local tree from your local file space into your context space with the legion_import_tree command. The contents of local files will be automatically copied into new Legion file objects.

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 directory's contents shows that the directory contains one sub-directory and three files. The subdirectory /nextlevel also contains three files:

$ ls -Fa legion.practice
./	../	nextlevel/	nothing	nothing2	nothing3
$ ls -Fa legion.practice/nextlevel
./	../	nextnothing	nextnothing2	nextnothing3
$

The default values of legion_import_tree are the current Unix directory and the current Legion context (in this case, the home context "."), but you can specify the directory path and/or the context (see the Reference Manual for full usage).

$ legion_import_tree legion.practice 
Making legion context "./nextlevel"
Creating context "nextlevel" in parent ".".
New context LOID = "1.01.05.47b53908.000001fc0c01650..."
Copying contents of "legion.practice/nextlevel" into 
	"./nextlevel"
Copying unix file "legion.practice/nextlevel/nextnothing" to 
	legion file "./nextlevel/nextnothing"
Copying unix file "legion.practice/nextlevel/nextnothing2" to 
	legion file "./nextlevel/nextnothing2"
Copying unix file "legion.practice/nextlevel/nextnothing3" to 
	legion file "./nextlevel/nextnothing3"
Copying unix file "legion.practice/nothing" to 
	legion file "./nothing"
Copying unix file "legion.practice/nothing2" to 
	legion file "./nothing2"
Copying unix file "legion.practice/nothing3" to 
	legion file "./nothing3"
$

Note that Legion copied the contents of the /nextlevel subdirectory into a new sub-context called /nextlevel:

$ legion_ls -la /
. 	(context)
class	(context)
home 	(context)
hosts	(context)
impls 	(context)
nextlevel	(context)
nothing	43 bytes
nothing2	46 bytes
nothing3 	46 bytes
vaults 	(context)

$ legion_ls -la /nextlevel
nextnothing3	46 bytes
nextnothing2	46 bytes
nextnothing	43 bytes
..	(context)
. 	(context)
$

The legion_cat command shows that the new file objects contain the same information as the Unix files:

$ cat legion.practice/nextlevel/nextnothing3
3: This is a test, just a test, nothing more.
$

$ legion_cat /nextlevel/nextnothing3
3: This is a test, just a test, nothing more.
$

1. Man page usage is man <command name>: ask your system administrator if you are unsure about using man pages on your system.

2. Full path syntax can be used as well as relative path syntax in all Legion commands.

3. In the interests of space and readability, in this and some of the following examples the entire LOID is not reproduced.


Back to Basic User Manual Table of Contents

Directory of Legion 1.5 Manuals