Pittsburgh Supercomputing Center 

Advancing the state-of-the-art in high-performance computing,
communications and data analytics.

The FAR program

far runs on blacklight and operates in one of two modes:

  • Single-line mode, permitting you to execute one far command. This mode is best suited for use within batch jobs.

    Following the single-line link will also take you to documentation describing the error codes returned in single-line mode. We recommend that you use single-line mode in batch jobs and check the error code returned to see if your far command was successful.

  • Command mode, permitting you to start far and execute as many commands as you wish before exiting. This mode is best suited for your interactive work. Since you are not checking error codes to see if your far commands have succeeded you should use other means, such as a far ls command, to check that your far commands have worked.

Regardless of the mode you use, you communicate with the storage resource, PSC's Data Supercell (patent pending), through a variety of far sub-commands.

Type far help for a complete, current list of commands available in the FAR user interface.

Single-line mode

Using far in single-line mode allows you to execute only one far sub-command at a time. It is very useful in batch jobs, when you want to retrieve a file before you begin program execution, or store the output of a job.

To use far in single-line mode, type

far sub-command

You are returned to the machine prompt immediately after the command executes.

There are many far sub-commands available.

I/O redirection is available in single-line mode but not in command mode.

Error codes

In single-line mode, you can trap the exit code returned by far, and act upon any errors you'd like. We recommend that you always check the error return code to see if your far command succeeded.

These are the error codes returned by far:

0 - Successful
1 - Failure, retry necessary.
2 - Unknown far command, don't retry.
3 - Far command argument problem.
4 - File doesn't exit.
5 - Unknown machine type.

Command mode

To use far in command mode, type


You will get an far> prompt. You can then use any of the available commands. When you want to exit far, type quit.

Wildcards can be used in command mode in the ordinary way, without being "escaped" as in line mode.

You cannot use piping or I/O redirection in command mode. Command mode cannot be directly used in a batch job. However, you can use a "here document" in a batch job as input to far:

far <

For more information on here documents, refer to your favorite UNIX reference manual.

far commands

Most of the far commands are standard UNIX commands. They work in the usual way, and all of their switches and options are available. Additional information for the standard commands is available via the man pages.

far commands fall into these categories:

Storing and retrieving files

The put and get commands allow you to store and retrieve archived files:

put source-file target-file
copies a file from the current working directory to the archive. Both source and target filenames are required. The file is archived but not deleted. Existing archived files of the same name are overwritten.
put -R source-directory target-directory
copies an entire subtree from the source directory to the archive. Both source and target directories are required.
get source-file target-file
retrieves a file from the archive and saves it in your current working directory, unless you specify another directory in the target filename. Both source and target filenames are required. The file is not deleted from the archive. Existing files of the same name in the target directory are overwritten.
get -R source-directory target-directory
copies the entire subtree of the source directory to the target directory. Both source and target directories are required.


put output  run1.dat

Saves the file output on the Data Supercell*, naming it run1.dat.

put output run1/data

Copies the file called output to the Data Supercell, storing it in directory run1 and naming it data.

put prog.f inp.dat out.dat  simulation

Copies prog.f, inp.dat, and out.dat to the archiver directory simulation.

get file1 file2 file3 $TMP

Copies file1, file2, and file3 from the current archive directory to your $TMP directory.

Displaying archived files

These commands allow you to display archived files:

prints the first few lines of a file.
prints the last few lines of a file.
displays the contents of a file.
displays a directory listing for the archive. To determine if the file has an ACL associated it with it, type ls -le, which prints an afollowing the permissions strings for files with ACLs.
displays a file in paged mode.

For additional information on any of these commands, refer to the man pages.

These commands allow you to move around within, and modify, your archive hierarchy:

makes another copy of a file in the archive.
changes your working directory in the archive. cd is futile in line mode, since once you are moved to the appropriate directory, far exits. When you invoke far again to issue the next command, you start from your home directory.
creates a new directory in the archive.
renames or moves a file from one archive directory to another.
prints your current directory in the archive.
deletes a file from the archive. Please note that there is no delete recovery provided; a file cannot be restored after it has been deleted.
deletes a empty directory from the archive.

For additional information on any of these commands, refer to the man pages.

Modifying protections on archived files

Files copied into or out of the archive retain their permissions. New versions of files replacing older versions in the archive inherit the protection of the older version.

The file protection scheme used on the archiver matches that used by Unix. Use chmod to change the protections on a file and chgrp to change a file's group ownership. For more information on these commands, see your favorite Unix documentation.

Working with your local directory without leaving far

Two commands allow you to see and change your local directory - your working directory on the machine that you connected to the archiver from - without leaving the far interface.

prints the directory listing of your working directory on your local machine.
changes your working directory on your local machine.

Getting help

Type help for more information on far commands.