.help utilities May83 "IRAF System Utilities" .sh Basic IRAF System Utilities A number of standard utilities are available as part of the IRAF user interface. These utilities, most of which operate on files, are summarized later in this document. A general discussion of files in the IRAF system follows. The reader is assumed to have some familiarity with the IRAF command language (CL). .sh Virtual File Names File names may be specified in a machine independent fashion, or with OS dependent pathnames. A Virtual File Name (VFN) has the following form: .nf ldir$root.extn where ldir logical directory or device name root root or base file name extn extension denoting the type of file .fi The LDIR and EXTN fields are optional. The ROOT and EXTN fields may contain up to 20 characters selected from the set [a-zA-Z0-9_.+-#]. The EXTN field may not exceed three characters. The EXTN field is separated from the ROOT by the character "." (dot). If the ROOT field contains one or more occurrences of the dot character, the final dot delimited field is understood to be the extension. Logical directories are defined in the CL, using the SET command to associate an OS dependent pathname with a keyword in the environment table. Logical directory prefixes are recursively expanded. A number of standard logical directories and devices are defined by the CL at startup time. Additional logical directories are defined by applications packages upon entry, and become undefined when dictionary space is reclaimed on exit from the package. The user may override environment definitions at will, by issuing SET commands to redefine environment variables. .sh File List Templates Whenever it makes sense, the IRAF utilities are set up to process a list of files, rather than a single file. In the descriptions of the standard utilities in the next section, "files" is a template or pattern specifying a list of files to be processed in some way. The template is a string type parameter to the CL, which is expanded by a procedure (CLGFIL) in the compiled systems or applications task into an EOF terminated list of files. A template may consist of one or more file names, directory names, list file names, or patterns. List elements are delimited by commas. A list file is denoted by prepending the character "@" to the pathname of the list file. A pattern may be applied to the contents of either a list file or a directory. The pattern is separated from the list file or directory name by the character "$". A pattern all by itself is applied to the current directory. Either logical or OS dependent pathnames may be used. A list element may refer only to a single directory. Thus, one cannot specify a pattern such as "*/*.x", as is possible in UNIX. Some examples of templates follow: .nf file "file1, file2" "*.x" "[A-Z]*, *.com, ../$, ../fio/$*.x, lib$*.h, file, @list$*.vs" "sia1:[iraf.lib]$*.h, uparm$cl_*.par" .fi The magic filenames "STDIN", "STDOUT", and "STDERR" have a special meaning. Passing one of these special filenames to a task causes the named stream to be "reopened", transparently to the applications program. Thus, for example, one can reference "STDIN" in a template, and the applications program will read from the standard input when it opens the corresponding file in the template. For example, cl> concat "file1, @STDIN, STDIN, file2", > ofile concatenates the file "file1", the contents of the files named in the standard input (until the first EOF), the contents of the standard input itself (until the second EOF), and the contents of the file "file2", placing the output in the file "ofile". .sh File Protection and Clobber The IRAF file interface (FIO) provides file protection and synchronization facilities, under control of user definable environment variables. File "clobber" refers to the overwriting of an existing file when a new file of the same name is created as an output file. If "clobber" is defined as "no" in the environment, an IRAF task will abort if a new file would clobber an existing file. If file clobber is enabled, FIO will try to overwrite the old file, and will abort if it cannot do so. cl> set clobber = "yes" More explicit file protection is provided by the CL commands PROTECT and UNPROTECT. A protected file cannot be deleted, accidentally or otherwise, until the protection has been removed with the UNPROTECT command or system call. A final form of file protection is provided to prevent a file from being clobbered which is already open by a task. Thus, "COPY file,file" will abort when FIO discovers that "file" is already opened for reading. This holds even if file clobber is enabled. .sh File Synchronization File synchronization is useful when a process requires exclusive access to a file which is already open for exclusive access by another process. When this situation occurs, the second task may abort with a message stating that it cannot access the file, or the task may wait for the file to become available. File waiting is especially important for batch processes. cl> set file_wait = "yes" The file wait option is controlled by the "file_wait" variable in the environment. If file waiting is enabled, and a process finds that it has to wait to access a file, a warning message will be printed on the standard error output before the affected process goes to sleep. .sh Description of the Standard Utility Routines Most of the system utilities are set up to read from either the standard input or a list of files. If not reading from the standard input, and the input file template is not given on the command line, a prompt will be issued for the input file list. If the output is a single file or directory, and output is not redirected, a prompt will be issued for the output file. The following list of system utilities is expected to adequately meet the needs of both general users and programmers. Most notably missing are file editing facilities and the X-compiler. These will be added to the system utilities package at some point in the future. Other more specialized utilities and tools, such as are needed for general image processing, graphics, database management, magtape i/o, and so on, will be provided in the form of new packages in the months to come. .ks .ls 4 ALLOCATE device Allocate a device (e.g., a tape drive). The standard logical tape drive names will probably be "mt0" and "mt1". .le .ke .ks .ls CLEAR Clear the terminal screen. .le .ke .ks .ls COLUMNS [files] [, c = "1,3,5-8"] Breaks the named file or files (or the standard input) up into a stream of words, written one word per line on the standard output. A "word" is any whitespace delimited sequence of characters, or a quoted string. The hidden parameter COLUMNS may be used to extract only a particular column, or any list of columns, from each line. If the list contains only the element "0" (the default) all columns are extracted, and placed on separate output lines. If multiple columns are specified, only those columns given in the list are extracted, and all extracted columns from an input line appear together on a single output line. If the last element in the list is "0", all remaining columns in the input line are extracted and placed on the output line. .nf Hidden params: columns string ["0"] List of columns. .fi .le .ke .ks .ls CONCATENATE [files] [,output_file] Concatenate the input files to the output file. If no input file is given, the standard input is used. If no output file is given, the standard output is used. .nf hidden params: otype string ["*"] text or binary output file append yes/no [no] append to output file .fi .le .ke .ks .ls COPY [file | files] [,output_file | directory] Copy the input file to the output file, or copy each file in the input list to the directory given as the second argument. .nf hidden params: otype string ["*"] text or binary output file append yes/no [no] append to output file .fi .le .ke .ks .ls COUNT [files] Count the number of lines, words, and characters in each file in the input list. Print the totals for each file and for all files. .le .ke .ks .ls DEALLOCATE device Deallocate a previously allocated device (e.g., a tape drive). .le .ke .ks .ls DELETE [files] Delete the named files. A warning message is printed if a file cannot be deleted. It is not considered an error to attempt to delete a file which does not exist. Protected files cannot be deleted. .le .ke .ks .ls DIRECTORY [files] [,op=string] Tabulate information on all files matching the template given as the first argument on the standard output. If no template is given, the contents of the current directory are displayed. .nf hidden params: option string ["c"] 1 one-column format a use time of last access c n-column format l long format s add size in Kb t time sort r reverse sort e.g.: "dir op=l" (show current directory, long form) "dir '*.x',op=lt" (all ".x" files in cwd, long form) .fi .le .ke .ks .ls DISKSPACE Summarize the amount of disk space available on the local system. This command and its output are machine dependent. This command may not be available on all systems. .le .ke .ks .ls ECHO [arglist] Echo any arguments on the standard output. .le .ke .ks .ls HEAD [files] Print the first few lines of each of the named files on the standard output. A brief header is printed to identify each file. .nf hidden params: nlines int [8] number of lines to print .fi .le .ke .ks .ls HELP [task(s)] Retrieve documentation for the named task(s) from the help database, and format it on the standard output. If no task name is given, the tasks comprising the current package are summarized, one line per task (task name followed by a brief description). Help may be obtained for multiple tasks by supplying a template. Tasks not in the current package search path may be referenced by specifying the pathname to the task ("package.task"). .nf Hidden params: option string [h] h full help text u usage section only p program documentation s source code f give file names file fname [""] file containing help text lmargin int [1] rmargin int [75] page yes/no [yes] paginate output nlpp int [24] number of lines per page .fi .le .ke .ks .ls LCASE [file] Copy the named file or the standard input (a text stream) to the standard output, converting all alphabetic characters to lower case. .le .ke .ks .ls MANPAGE [task(s)] Print "manual pages" for each of the named tasks. Manual pages are produced by breaking the help text for a task up into successive pages delimited by formfeed characters. Each page has a header and a page number. To print manual pages, the output of MANPAGE should be piped to PRINT ("manpage task(s) | print"). .nf Hidden params: lmargin int [1] left margin rmargin int [72] right margin nlpp int [60] number of lines per page first_page int [1] first page to be printed last_page int [0] last page to be printed file fname [""] file containing help text .fi .le .ke .ks .ls MATCH pattern [,files] [,rev+] Search each file for the given pattern. Copy a line to the standard output if the pattern can be matched. Match against the standard input if no files are named. .nf hidden params: reverse yes/no [n] print lines NOT matched .fi .le .ke .ks .ls PAGE [files] The named files (or the standard input) are displayed a page at a time on the standard output. .nf Query mode params: continue y/n [y] query mode param, used to provide the pause at the end of each page, or to exit early. hidden params: nlpp int [24] number of lines per page .fi .le .ke .ks .ls PRINT [files] The named files (or the standard output) are printed on the standard line printer device. If a list of files are to be printed, each file is printed started on a new page, and file pages are broken and printed with numbered headers. If PRINT is reading from its standard input, the input stream is copied to the printer without pagination. The input stream may contain ASCII standard control characters (e.g. formfeed), which will be processed if necessary prior to transmission to the output device. .nf hidden params: page yes/no [no] paginate the standard input nlpp int [60] number of lines per page szline int [132] maximum line length device string name of printer device .fi .le .ke .ks .ls PROTECT [files] Protect the named files from deletion or clobber, accidental or otherwise. It is not considered an error to attempt to protect a file which is already protected. Protecting a file only prevents deletion of the file: write permission is not withdrawn. .le .ke .ks .ls RENAME [file | files] [,output_file | directory] Rename a file, or move each file in the input list to the directory given as the second argument. .le .ke .ks .ls SORT [files] [,options] Sort and merge the text files named in the list, or sort the standard input if no list. .nf hidden params: numeric yes/no [n] numeric sort reverse yes/no [n] reverse the sense of the sort column integer [1] column to be sorted whitespace yes/no [y] ignore leading whitespace .fi .le .ke .ks .ls SPY [v+] Get information on who is using the system, what they are up to, how much cpu time, etc., they have used, and so on. This command, and the information it gives, are machine dependent. This command may not be available on all systems. .nf hidden params: verbose yes/no [no] get more information .fi .le .ke .ks .ls TABLE [files] The input, consisting of a list of words, one word per line, is read into a buffer in memory, and organized into a table which is printed on the standard output. The size of the table which can be formatted is limited by the amount of available buffer space. .nf Hidden params: ncols int [0] desired number of columns lmargin int [1] left margin of table rmargin int [75] right margin of table maxch int [0] max chars to print from each word or string in the input. .fi .le .ke .ks .ls TAIL [files] Print the last few lines of each of the named files on the standard output. .nf hidden params: nlines int [8] number of lines to print .fi .le .ke .ks .ls TEE [files] Copy the standard input to the standard output, as well as to each of the named files. .nf hidden params: otype string ["*"] text or binary output file append yes/no [n] append to the named files .fi .le .ke .ks .ls TIME Print the current time and date. .le .ke .ks .ls TYPE [files] Copy the named files to the standard output. A brief header is printed at the beginning of each file, identifying the file. .le .ke .ks .ls UCASE [file] Copy the named file or the standard input (a text stream) to the standard output, converting all alphabetic characters to upper case. .le .ke .ks .ls UNPROTECT [files] Remove delete protection from the named files. It is not considered an error to attempt to remove protection from a file which is not protected. .le .ke .sh CL Directives .ks .ls CHDIR directory Change the current working directory. CHDIR without any arguments prints the name of the current working directory on the standard output. .le .ke .ks .ls SET [param [= value_string]] Set the value of an environment variable. If the variable is not already defined, it becomes defined. If the variable is already defined, the old value is (temporarily and silently) overridden. A variable defined or redefined with SET is discarded when CL dictionary space is reclaimed. SET without any arguments displays the current environment. .le .ke (etc.) .endhelp