#sun Nr microsystems Commands Reference Manual ^ UT1 Micros y stem s, Inc. • 2550 Garcia Avenue • Mountain View, CA 94043 • 415-960-1300 f -V Part No: 800-1295-02 { Revision Gof 17 February 1986 Credits and Trademarks Sun Workstation® is a registered trademark of Sun Microsystems, Inc. SunStation®, Sun Microsystems®, SunCore®, SunWindows®, DVMA®, and the combination of Sun with a numeric suffix are trademarks-of Sun Microsystems, Inc. UNIX, UNIX/32V, UNIX System III, and UNIX System Y are trademarks of AT&T Bell Laboratories. Intel® and Multibus® are registered trademarks of Intel Corporation. DEC®, PDP®, VT®, and VAX® are registered trademarks of Digital Equipment Corporation. Copyright © 1985 by Sun Microsystems. This publication is protected by Federal Copyright Law, with all rights reserved. No part of this publica- tion may be reproduced, stored in a retrieval system, translated, transcribed, or transmitted, in any form, or by any means manual, electric, electronic, electro-magnetic, mechanical, chemical, optical, or otherwise, without prior explicit written permission from Sun Microsystems. INTRO ( I ) USER COMMANDS INTRO ( 1 ) NAME intro — introduction to commands DESCRIPTION ™ S nSt”.ht£dS g r“ y “ C “ SSib " a,PhabeliC ° rter - Cmai ” disa " cti0ns of (1) Commands of general utility. (1C) Commands for communication with other systems. (1G) Commands used primarily for graphics and computer-aided design. SEE ALSO Section 6 in this manual for computer games. Section 7 in this manual for descriptions of publicly available files and macro packages for docu- ment preparation. 6 Section 8 in this manual for system administration procedures, system maintenance and operation commands, plus descriptions of network services daemons and servers. • Getting Started With UNIX: Beginner' s Guide • Setting Up Your UNIX Environment: Beginner’s Guide • Windows and Window-Based Tools: Be ginner’ s Guide ° U sing the Network: Beginner’ s Guide DIAGNOSTICS Upon termination each command returns two bytes of status, one supplied by the system giving the cause for termination, and (in the case of ‘normal’ termination) one supplied by the program, see wait and exit W- The former byte is 0 for normal termination, the latter is customarily 0 for successful execution, nonzero to indicate troubles such as erroneous parameters, bad or inaccessible data, or other inability to cope with the task at hand. It is called variously ‘exit code’, ‘exit status’ or ‘return code’, and is described only where special conventions are involved. Sun Release 3.0 Last change: 6 April 1985 1 ADB(l) USER COMMANDS ADB(l) NAME adb - debugger SYNOPSIS adb [ -w ] [ -k ] [ -I dir ] [ objfil [ corfil ] ] DESCRIPTION Adb is an interactive, general purpose debugger. It examines files and provides a controlled environment for the execution of UNIX programs. Objfil is normally an executable program file, preferably containing a symbol table. If the file does not con- tain a symbol table, it can still be examined, but the symbolic features of adb cannot be used. The default for objfil is a.out. Corfil is assumed to be a core image file produced after executing objfil. The default for corfil is core. OPTIONS -w Create both objfil and corfil if necessary and open them for reading and writing so that files can be modified using adb. -k Do UNIX kernel memory mapping; should be used when core is a UNIX crash dump or Idev/mem. —I specifies a directory where files to be read with $< or $« (see below) will be sought; the default is lusr/lib/adb. USAGE Refer to Adb in Pro gram Debugging Tools for the Sun Workstation . FILES a.out core SEE ALSO cc(l), dbx(l), ptrace(2), a.out(5), core(5) Using adb to debug the UNIX kernel in the Sun System Internals Guide. DIAGNOSTICS ‘Adb’ when there is no current command or format. Comments about inaccessible files, syntax errors, abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned nonzero status. BUGS There doesn’t seem to be any way to clear all breakpoints. Adb uses the symbolic information in an old and now obsolete format generated by the —go flag of cc(l), it should be changed to use the new format used by the dbx debugger and generated by -g. Since no shell is invoked to interpret the arguments of the :r command, the customary wild-card and vari- able expansions cannot occur. Since there is little type-checking on addresses, using a sourcefile address in an inappropriate context may lead to unexpected results; ‘main?i will almost certainly not do anything useful. 2 Last change: 8 August 1985 Sun Release 3.0 ADDBIB ( 1 ) USER COMMANDS ADDBIB ( 1 ) NAME addbib - create or extend bibliographic database SYNOPSIS addbib [-p promptfile] [-a] database DESCRIPTION When addbib starts up, answering “y” to the initial “Instructions?” prompt yields directions; typing “n” or return skips them. Addbib then prompts for various bibliographic fields, reads responses from the ter- minal, and sends output records to a database. A null response (just RETURN) means to leave out that field. A minus sign (-) means to go back to the previous field. A trailing backslash allows a field to be continued on the next line. The repeating “Continue?” prompt allows the user either to resume by typing “y” or return, to quit the current session by typing “n” or “q”, or to edit the database with any system editor (vi, ex, edit, ed). OPTIONS -a suppress prompting for an abstract; asking for an abstract is the default. Abstracts are ended with a CTRL-d. — p use a new prompting skeleton, defined in promptfile. This file should contain prompt strings, a tab, and the key-letters to be written to the database. BIBLIOGRAPHY KEY LETTERS The most common key-letters and their meanings are given below. Addbib insulates you from these key- letters, since it gives you prompts in English, but if you edit the bibliography file later on, you will need to know this information. %A Author’s name %B Book containing article referenced %C City (place of publication) %D Date of publication %E Editor of book containing article referenced %F Footnote number or label (supplied by refer) %G Government order number %H Header commentary, printed before reference %I Issuer (publisher) %J Journal containing article %K Keywords to use in locating reference %L Label field used by -k option of refer %M Bell Labs Memorandum (undefined) %N Number within volume %o Other commentary, printed at end of reference %P Page number(s) %Q Corporate or Foreign Author (unreversed) %R Report, paper, or thesis (unpublished) %S Series title %T Title of article or book %V Volume number %X Abstract — used by roffbib, not by refer %Y,Z ignored by refer Except for ‘A’, each field should be given just once. Only relevant fields should be supplied. An example is: %A Bill Tuthill %T Refer — A Bibliography System %l Computing Services Sun Release 3.0 Last change: 26 August 1985 3 ADDBIB ( 1 ) USER COMMANDS ADDBIB ( 1 ) %C Berkeley %D 1982 %0 UNX 4.3.5. FILES promptfile optional file to define prompting SEE ALSO "refer" in Formatting Documents on the Sun Workstation refer(l), sortbib(l), roffbib(l), indxbib(l) 4 Last change: 26 August 1985 Sun Release 3.0 ADJACENTSCREENS ( 1 ) USER COMMANDS ADJACENTSCREENS ( 1 ) NAME adjacentscreens — notify the window driver of the physical relationships of screens SYNOPSIS adjacentscreens [ -c | -m ] center screen [ [ — 1 1 — r | — 1 1 — b ] side screen ] [ -x ] DESCRIPTION Adjacentscreens tells the mouse cursor tracking mechanism of the window driver how to move between screens that contain windows. Once properly notified using adjacentscreens , the mouse cursor slides from one screen to another when the user moves the cursor off the edge of a screen. OPTIONS — c center screen The center screen is a frame buffer device name, such as Idevlfb. All the other physical screen positions are relative to this reference point. The -c flag (c for center) is optional. If no further arguments are present on the command line, center screen is set to have no neighbors. — m center screen The -m flag ( m for middle) may be used instead of-c. -1 side screen The side screen is also a frame buffer device name, such as Idev/cgoneO. The -1 flag means that side screen is to the / eft of center screen. Up to four repetitions of “flag side screen” may be specified on the command line to define the four neighbors of center screen. — r side screen Like -1, but means that side screen is to the right of center screen. — t side screen Like -1, but means that side screen is on lop of center screen. -b side screen Like —I, but means that side screen is b elow center screen. -x Suppresses the normal notification to a side screen cursor tracker that center screen is its only neighbor. This option is useful if you have a large number of screens or want strange inter- window cursor movement. EXAMPLE A common configuration would be two screens, a monochrome ( Idevlfb ) and a color screen (/ dev/cgoneO ). Let us assume that the user has set up an instance of suntools on each screen (the window systems must be running before adjacentscreens is run). He would notify the window driver that the color screen was to the right of the monochrome screen by running “% adjacentscreens /dev/fb -r /dev/cgoneO” in a Shelltool (see suntools(l)). This sets up cursor tracking so that the cursor slides from the monochrome screen to the color screen when the cursor moves off the right hand side of the monochrome screen. Similarly, the cursor slides from the color screen to the mono- chrome screen when the cursor moves off the left hand side of the color screen. FILES /usr/suntool/adj acentscreens SEE ALSO suntools(l), login(l) BUGS Window systems on the screens have to be initialized before running adjacentscreens. Sun Release 3.0 Last change: 1 February 1985 5 ADMIN(l) USER COMMANDS ADMIN ( 1 ) NAME admin - create and administer SCCS files SYNOPSIS /usr/sccs/admin [ -n ] [ -i [ name ] ] [ -rrel ] [ -t [ name ] ] [ -f flag [flag-val ] ] . . . [ -d flag [flag-val ] ] . . . [ -a login ] . . . [ -do gin ] . . . [ -m [ mrlist ] ] [-ylcommentW [-h] [-z] filename ... DESCRIPTION Admin creates new SCCS files and changes parameters of existing ones. Options and SCCS file names may appear in any order on the admin command line. SCCS file names must begin with the characters ‘s.’. A named file is created if it doesn’t exist already, and its parameters are initialized according to the specified options. Any parameter not initialized by an option is assigned a default value. If a named file does exist, parameters corresponding to specified options are changed, and other parameters are left as is. If a directory is named, admin behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. A name of - means the standard input — each line of the standard input is taken as the name of an SCCS file to be processed. Again, non-SCCS files and unreadable files are silently ignored. OPTIONS Options are explained as though only one named file is to be processed, since options apply independently to each named file. -n A new SCCS file is being created. -i [name ] Initial text: the file name contains the text of a new SCCS file. The text is the first delta of the file — see -r option for delta numbering scheme. If name is omitted, the text is obtained from the standard input. Omitting the -i option altogether creates an empty SCCS file. You can only create one SCCS file with an admin -i command. Creating more than one SCCS file with a single admin command requires that they be created empty, in which case the -i option should be omitted. Note that the -i option implies the -n option. -r rel Initial release: the rel ease into which the initial delta is inserted, -r may be used only if the -i option is also used. The initial delta is inserted into release 1 if the -r option is not used. The level of the initial delta is always 1, and initial deltas are named 1.1 by default. -t [name ] Descriptive text: The file name contains descriptive text for the SCCS file. The descriptive text file name must be supplied when creating a new SCCS file (either or both -n and -i options) and the -t option is used. In the case of existing SCCS files: 1) a -t option without a file name removes descriptive text (if any) currently in the SCCS file, and 2) a -t option with a file name replaces the descriptive text currently in the SCCS file with any text in the named file. -f flag Set flag: specifies a flag, and, possibly, a value for the flag, to be placed in the SCCS file. Several -f options may be supplied on a single admin command line. Flags and their values appear in the FLAGS section after this list of options. -d flag Delete flag from an SCCS file. The -d option may be specified only when processing existing SCCS files. Several -d options may be supplied on a single admin command. See the FLAGS section below. -1 list Unlock the specified list of releases. See the -f option for a description of the 1 flag and the syntax of a list. -a login Add login name, or numerical UNIX group ID, to the list of users who may make deltas (changes) to the SCCS file. A group ID is equivalent to specifying all login names common to that group ID. Several -a options may appear on a single admin command line. As many logins, or numerical group IDs, as desired may be on the list simultaneously. If the list of users is empty, anyone may add deltas. 6 Last change: 1 February 1985 Sun Release 3.0 ADMIN ( 1 ) USER COMMANDS ADMIN ( 1 ) -e login Erase login name, or numerical group ID, from the list of users allowed to make deltas (changes) to the SCCS file. Specifying a group ID is equivalent to specifying all login names common to that group ID. Several -e options may be used on a single admin command line. -y [ comment ] The comment text is inserted into the SCCS file as a comment for the initial delta in a manner identical to that of delta ( 1). If the -y option is omitted, a default comment line is inserted in the form: date and time created YY/MM/DD HH:MM:SS by login The -y option is valid only if the -i and/or -n options are specified (that is, a new SCCS file is being created). — m [ mrlist ] The list of Modification Requests (MR) numbers is inserted into the SCCS file as the reason for creating the initial delta in a manner identical to delta(l). The v flag must be set and the MR numbers are validated if the v flag has a value (the name of an MR number validation program). Diagnostics are displayed if the v flag is not set or MR validation fails. -h Check the structure of the SCCS file (see sccsfile( 5)), and compare a newly computed check-sum (the sum of all the characters in the SCCS file except those in the first line) with the check-sum that is stored in the first line of the SCCS file. The -h option inhibits writing on the file, so that it nullifies the effect of any other options sup- plied, and is, therefore, only meaningful when processing existing files. -z recompute the SCCS file check-sum and store it in the first line of the SCCS file (see -h, above). Using the -z option on a truly corrupted file may prevent future detection of the corruption. FLAGS The list below is a description of the flags which may appear as arguments to the -f (set flags) and -d (delete flags) options. b When set, the -b option can be used on a get( 1) command to create branch deltas. c ceil The highest release (ceiling) which may be retrieved by a get(l) command for editing. The ceil- ing is a number less than or equal to 9999. The default value for an unspecified c flag is 9999. f floor The lowest release (floor) which may be retrieved by a get(l) command for editing. The floor is a number greater than 0 but less than 9999. The default value for an unspecified f flag is 1. d SID The default delta number (SID) to be used by a get( 1) command. i Treats the ‘No id keywords (ge6)’ message issued by get( 1) or delta (1) as a fatal error. In the absence of the i flag, the message is only a warning. The message is displayed if no SCCS identification keywords (see get(\)) are found in the text retrieved or stored in the SCCS file. j Concurrent get(\) commands for editing may apply to the same SID of an SCCS file. This allows multiple concurrent updates to the same version of the SCCS file. Mist A list of locked releases to which deltas can no longer be made. A get-e fails when applied against one of these locked releases. The list has the following syntax: ::= RELEASE NUMBER | a The character a in the list is equivalent to specifying all releases for the named SCCS file. n The delta (1) command creates a ‘null’ delta in each release (if any) being skipped when a delta is made in a new release. For example, releases 3 and 4 are skipped when making delta 5.1 after delta 2.7. These null deltas serve as ‘anchor points’ so that branch deltas may be created from them later. If the n flag is absent from the SCCS file, skipped releases will be non-existent in the SCCS file, preventing branch deltas from being created from them in the future. Sun Release 3.0 Last change: 1 February 1985 7 ADMIN ( 1 ) USER COMMANDS ADMIN ( 1 ) q text Text is defined by the user. The text is substituted for all occurrences of the %Q% keyword in SCCS file text retrieved by get (1). m module Module name of the SCCS file substituted for all occurrences of the %M% keyword in SCCS file text retrieved by get( 1). If the m flag is not specified, the value assigned is the name of the SCCS file with the leading s. removed. t type Type of module in the SCCS file substituted for all occurrences of %Y% keyword in SCCS file text retrieved by get(l). v [program] Validity checking program', delta(l) prompts for Modification Request (MR) numbers as the rea- son for creating a delta. The optional program specifies the name of an MR number validity checking program (see delta (\)). If this flag is set when creating an SCCS file, the -m option must also be used even if its value is null. FILES The last component of all SCCS file names must be of the form s .file-name. New SCCS files are given mode 444 (see chmod(l)). Write permission in the pertinent directory is, of course, required to create a file. All writing done by admin is to a temporary x-file, called x.file-name, (see get(Vj), created with mode 444 if the admin command is creating a new SCCS file, or with the same mode as the SCCS file if it exists. After successful execution of admin, the SCCS file is removed (if it exists), and the x-file is renamed with the name of the SCCS file. This ensures that changes are made to the SCCS file only if no errors occurred. It is recommended that directories containing SCCS files be mode 755 and that SCCS files themselves be mode 444. The mode of the directories allows only the owner to modify SCCS files contained in the direc- tories. The mode of the SCCS files prevents any modification at all except by SCCS commands. If it should be necessary to patch an SCCS file for any reason, the mode may be changed to 644 by the owner allowing use of a text editor. "Care must be taken! " The edited file should always be processed by an admin -h to check for corruption followed by an admin -z to generate a proper check-sum. Another admin — h is recommended to ensure the SCCS file is valid. Admin also uses a transient lock file (called z.file-name), to prevent simultaneous updates to the SCCS file by different users. See get( 1) for further information. SEE ALSO sccs(l), delta(l), ed(l), get(l), help(l), prs(l), what(l), sccsfile(5). Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help(l) for explanations. 8 Last change: 1 February 1985 Sun Release 3.0 AR(1) USER COMMANDS AR(1) NAME ar - archive and library maintainer SYNOPSIS ar d/m/p/q/r/t/x [ abcilouv ] [ posname ] afile name . . . DESCRIPTION Ar maintains groups of files combined into a single archive/library file. It is normally used to create and update library files used by the loader; it can be used, though, for any similar purpose. One of the mandatory keys (dmpqrtx) must be used; it may be followed by one or more of the modifiers abcilouv. Afile is the archive file. The names are constituent files in the archive file. OPTIONS d Delete the named files from the archive file, m Move the named files to the end of the archive, p Display the named files in the archive. q Quick append. Append the named files to the end of the archive file without searching the archive for duplicate names. Useful only to avoid quadratic behavior when creating a large archive piece-by-piece. r Replace the named files in the archive file. t Display a table of contents of the archive file. If no names are given, all files in the archive are listed; if names are given, only those files are listed. x Extract the named files. If no names are given, all files in the archive are extracted. In neither case does x alter the archive file. MODIFIERS a Place new files after posname (posname argument must be present). Applies only to the r and m options. b Place new files before posname (posname argument must be present). Applies only to the r and m options. c Normally ar creates afile when it needs to, and displays a message to this effect. The c modifier suppresses this message. i Identical to the b modifier. 1 Local. Ar places its temporary files in the directory /tmp. The 1 modifier places them in the local directory instead. o Old date. When files are extracted with the x option, o sets the “last modified” date to the date recorded in the archive. u Replace only those files that have changed since they were put in the archive. Used with the r option. v Verbose. Give a file-by-file description of the creation of a new archive file from the old archive and the constituent files. When used with t, it gives a long listing of all information about the files. When used with p, it precedes each file with a name. FILES /tmp/v* temporaries SEE ALSO lorder(l), ld(l), ranlib(l), ar(5) BUGS If the same file is mentioned twice in an argument list, it is put in the archive twice. Sun Release 3.0 Last change: 1 November 1983 9 AR( 1 ) USER COMMANDS AR( 1 ) The ‘last-modified’ date of a file will not be altered by the o option unless the user is either the owner of the extracted file or the superuser. 10 Last change: 1 November 1983 Sun Release 3.0 AS ( 1 ) USER COMMANDS AS ( 1 ) -10 ] [ — m68020 | —20 ] [ — o objfile ] [ — O ] — d2 -e -h NAME as - Sun-2 and Sun-3 assembler SYNOPSIS as [ -d2 ] [ -e ] [ -h ] [ -j ] [ - J ] [-L] [-m68010 [ — R ] filename DESCRIPTION as translates assembly code in the named filename into executable object code in the specified objfile. All undefined symbols in the assembly are treated as global. The output of the assembly is left in the file objfile. OPTIONS Specifies that instruction offsets involving forward or external references and having sizes unspecified in the assembly language are two bytes long. The default is four bytes. See also the -j option. Allows control sections to begin on any two-byte boundary, rather than only four-byte boundaries. Suppress span-dependent instruction calculations and force all branches to be of medium length, but all calls to take the most general form. This is used when assembly time must be minimized, but program size and run time are not important. This option results in a smaller and faster pro- gram than that produced by the — J option, but some very large programs may not be able to use it because of the limits of the medium-length branches. Use short (pc-relative) branches to resolve jump’s and jsr’s to externals. This is for compact pro- grams which cannot use the — d2 flag because of large program relocation. Suppress span-dependent instruction calculations and force all branches and calls to take the most general form. This is used when assembly time must be minimized, but program size and run time are not important. Save defined labels beginning with an ‘L’, which are normally discarded to save space in the resultant symbol table. The compilers generate such temporary labels. -m68010 -10 Accept only MC68010 instructions and addressing modes, and put the MC68010 machine-type tag in the object file. -m68020 -20 Accept the full MC68020 and MC6888 1 instruction sets and addressing modes, and put the MC68020 machine-type tag in the object file. The next argument is taken as the name of the object file to be produced. If the -o flag isn’t used, the objfile is named a. out. Perform span-dependent instruction resolution over entire files rather than just over individual procedures. Make initialized data segments read-only by concatenating them to the text segments. This elim- inates the need to run editor scripts on assembly code to make inidalized data read-only and shared. -J -J -L -o -O -R FILES /tmp/as* default temporary file SEE ALSO ld(l), nm(l), adb(l), dbx(l), a.out(5) The “Assembler Reference Manual for the Sun Workstation’ ' in the Sun Programming Tools Manual Sun Release 3.0 Last change: 21 December 1985 11 AS ( 1 ) USER COMMANDS AS ( 1 ) BUGS The Pascal compiler, pc, qualifies a nested procedure name by chaining the names of the enclosing pro- cedures. This sometimes results in names long enough to abort the assembler, which currently limits identifiers to 512 characters. 12 Last change: 21 December 1985 Sun Release 3.0 AT ( 1 ) USER COMMANDS AT ( 1 ) NAME at - execute commands at a later time SYNOPSIS at time [ day ] [ file ] DESCRIPTION At squirrels away a copy of the named file (standard input default) to be used as input to sh(l) or csh( 1) at a specified later time. At inserts a cd command to the current directory at the beginning of the copy file, and follows this with assignments to all environment variables (except TERM, which is useless in this con- text.) When the script is run, it uses the user and group ID of the creator of the copy file. Time is specified by from 1 to 4 digits, and may be followed by ‘a’, ‘p’, ‘n’ or ‘m’ for AM, PM, noon, or midnight (letters may be upper or lower case). One and two digit numbers are taken to be hours, three and four digits to be hours and minutes. If no letters follow the digits, a 24 hour clock time is understood. Day may be either a month name followed by a day number — for example, ‘apr 26’ — or a day of the week — ‘weds’, for instance. If you name a day of the week and follow this with the word ‘week’ — ‘weds week’ — invocation is moved seven days further off. Names of months and days may be recogniz- ably truncated. At programs are executed by periodic execution of the command lusrlliblatrun from cron{ 8). The granu- larity of at depends upon how often atrun is executed. Standard output or error output is lost unless redirected. EXAMPLES Examples of legitimate commands are: at8ajan24 at 1530 fr week FILES /usr/lib/atrun in /usr/spool/at: yy.ddd.hhhh.* lasttimedone past SEE ALSO calendar(l), pwd(l), sleep(l), cron(8) BUGS Due to the granularity of the execution of lusrlliblatrun, there may be bugs in scheduling things almost exactly 24 hours into the future. executor (run by cron(8)). activity for year yy, day dd, hour hhhh. last hhhh activities in progress Sun Release 3.0 Last change: 1 November 1983 13 AWK(l) USER COMMANDS AWK(l) NAME awk - pattern scanning and processing language SYNOPSIS awk [ -f program Jile ] [ -Fc ] [ program ] [file . . . ] DESCRIPTION Awk scans each of its input files for lines that match any of a set of patterns specified in program. The input files are read in order; the standard input is read if there are no files. The filename means the standard input. The set of patterns may either appear literally on the command line as program, or, by using the -f option, the set of patterns may be in a program Jile. With each pattern in program there can be an associated action that will be performed when a line of a file matches the pattern. See the discussion below for the format of input lines and the awk language. Each line in each input file is matched against the pattern portion of every pattern-action statement; the associ- ated action is performed for each matched pattern. OPTIONS — f program Jile Use the contents of program Jle as the source for the program. — F c Use the character c as the field separator (FS) character. See the discussion of FS below. LINES, STATEMENTS, AND THE AWK LANGUAGE Input Lines An input line is made up of fields separated by white space. The field separator can be changed by using FS — see below. Fields are denoted $1, $2, ... up to $9; $0 refers to the entire line. Pattern-action Statements A pattern-action statement has the form pattern { action } A missing { action } means copy the line to the output; a missing pattern always matches. An action is a sequence of statements. A statement can be one of the following: if ( conditional ) statement [ else statement ] while ( conditional ) statement for ( expression ; conditional ; expression ) statement break continue { [ statement] ... } variable = expression print [ expression-list ] [ expression ] printf format [ , expression-list ] [ expression ] next # skip remaining patterns on this input line exit # skip the rest of the input Format of the Awk Language Statements are terminated by semicolons, newlines or right braces. An empty expression-list stands for the whole line. Expressions take on string or numeric values as appropriate, and are built using the operators +, %, and concatenation (indicated by a blank). The C operators ++, — , +=, — =, *=, /=, and %= are also avail- able in expressions. Variables may be scalars, array elements (denoted x [ i ]) or fields. Variables are initialized to the null string. Array subscripts may be any string, not necessarily numeric, providing a form of associative memory. String constants are quoted ". . .". 14 Last change: 1 February 1985 Sun Release 3.0 AWK(l) USER COMMANDS AWK(l) The print statement prints its arguments on the standard output (or on a file if >file is present), separated by the current output field separator, and terminated by the output record separator. The printf statement for- mats its expression list according to the format template (see printf(5S) for a description of the formatting control characters). Built In Functions The built-in function length returns the length of its argument taken as a string, or of the whole line if no argument There are also built-in functions exp, log, sqrt, and int, where int truncates its argument to an integer. substr(s,m,n) returns the n -character substring of s that begins at position m. The sprintf (format, expr, expr, ...) function formats the expressions according to the printf OS) format given by format and returns the resulting string. Patterns Patterns are arbitrary Boolean combinations (!, ||, &&, and parentheses) of regular expressions and rela- tional expressions. Regular expressions must be surrounded by slashes and are as in egrep. Isolated regu- lar expressions in a pattern apply to the entire line. Regular expressions may also occur in relational expressions. A pattern may consist of two patterns separated by a comma; in this case, the action is performed for all lines between an occurrence of the first pattern and the next occurrence of the second. A relational expression is one of the following: expression matchop regular-expression expression relop expression where a relop is any of the six relational operators in C, and a matchop is either " (for contains) or !" (for does not contain). A conditional is an arithmetic expression, a relational expression, or a Boolean combi- nation of these. The special pattern BEGIN may be used to capture control before the first input line is read, in which case BEGIN must be the first pattern. The special pattern END may be used to capture control after the last input line is read, in which case END must be the last pattern. Special Variable Names A single character c may be used to separate the fields by starting the program with BEGIN { FS = "c” } or by using the -Fc option. Other variable names with special meanings include NF, the number of fields in the current record; NR, the ordinal number of the current record; FILENAME, the name of the current input file; OFS, the output field separator (default blank); ORS, the output record separator (default newline); and OFMT, the output for- mat for numbers (default "%.6g"). EXAMPLES Print lines longer than 72 characters: length > 72 Print first two fields in opposite order: { print $2, $1 } Add up first column, print sum and average: {s+=$l} END { print "sum is", s, " average is", s/NR } Print fields in reverse order: { for (i = NF; i > 0; — i) print $i } Sun Release 3.0 Last change: 1 February 1985 15 AWK(l) USER COMMANDS AWK(l) Print all lines between start/stop pairs: /start/, /stop/ Print all lines whose first field is different from previous one: $1 != prev { print; prev = $1 } SEE ALSO Using UNIX Text Utilities on the Sun Workstation sed(l), grep(l), lex(l) BUGS There are no explicit conversions between numbers and strings. To force an expression to be treated as a number add 0 to it; to force it to be treated as a string concatenate "" to it Syntax errors result in the cryptic message "awk bailing out near line 1!!." 16 Last change: 1 February 1985 Sun Release 3.0 B ASENAME ( 1 ) USER COMMANDS BASENAME ( 1 ) NAME basename - strip filename affixes SYNOPSIS basename string [ suffix ] DESCRIPTION basename deletes any prefix ending in 7 ’ and the suffix, if present in string, from string, and directs the result to the standard output. It is normally used inside substitution marks ' ' in shell procedures. EXAMPLE This shell procedure invoked with the argument lusrlsrclbinlcat.c compiles the named file and moves the output to cat in the current directory: cc $1 mv a.out 'basename $1 .c' SEE ALSO sh(l) Sun Release 3.0 Last change: 23 September 1985 17 BC( 1 ) USER COMMANDS BC( 1 ) NAME be - arbitrary-precision arithmetic language SYNOPSIS be [ — c ] [ — 1 ] [ file — ] DESCRIPTION Be is an interactive processor for a language which resembles C but provides unlimited precision arith- metic. Be takes input from any files given, then reads the standard input. The syntax for be programs is as follows; L means letter a-z, E means expression, S means statement. Comments are enclosed in /* and */. Names simple variables: L array elements: L [ E ] The words ‘ibase’, ‘obase’, and ‘scale’ Other operands arbitrarily long numbers with optional sign and decimal point (E) sqrt ( E ) length ( E ) number of significant decimal digits scale ( E ) number of digits right of decimal point L(E E) Operators + - * / % A (% is remainder; A is power) ++ — (prefix and postfix; apply to names) == <= >=!=<> = += -= *= /= %= A = Statements E { S ; ; S } if ( E ) S while ( E ) S for ( E ; E ; E ) S null statement break quit Function definitions define L ( L ,. . ., L ) { auto L, . . . , L S; ... S return ( E ) } Functions in - -1 math library s(x) sine c(x) cosine e(x) exponential l(x) log a(x) arctangent j(n,x) Bessel function 18 Last change: 1 April 1981 Sun Release 3.0 BC( 1 ) USER COMMANDS BC( 1 ) All function arguments are passed by value. The value of a statement that is an expression is printed unless the main operator is an assignment Either semicolons or newlines may separate statements. Assignment to scale influences the number of digits to be retained on arithmetic operations in the manner of dc( 1). Assignments to ibase or obase set the input and output number radix respectively. The same letter may be used as an array, a function, and a simple variable simultaneously. All variables are global to the program. ‘Auto’ variables are pushed down during function calls. When using arrays as function arguments or defining them as automatic variables empty square brackets must follow the array name. EXAMPLES Define a function to compute an approximate value of the exponential function: scale = 20 define e(x){ auto a, b, c, i, s a = 1 b = 1 s = 1 for(i=l; 1==1; i++){ a = a*x b = b*i c = a/b if(c == 0) retum(s) s = s+c } } Print approximate values of the exponential function of the first ten integers: for(i=l; i<=10; i++) e(i) OPTIONS -1 is the name of an arbitrary precision math library. -c Compile only: be is actually a preprocessor for dc( 1), which it invokes automatically, unless the -c (compile only) option is present In this case the dc input is sent to the standard output instead. FILES /usr/lib/lib.b mathematical library dc( 1) desk calculator proper SEE ALSO dc(l) L. L. Cherry and R. Morris, BC - An arbitrary precision desk-calculator language BUGS For statement must have all three E’s. Quit is interpreted when read, not when executed. Sun Release 3.0 Last change: 1 April 1981 19 BIFF(l) USER COMMANDS BIFF ( 1 ) NAME biff - mail alarm SYNOPSIS biff [ y|n ] DESCRIPTION biff informs the system whether you want to be notified when mail arrives during the current terminal ses- sion. The command: biffy enables notification; the command: biff n disables it; finally, the command: biff on its own tells you whether the notification is y or n. When mail notification is enabled, the header and first few lines of the message are printed on your screen whenever mail arrives. A biff y command is often included in the file .login or .profile to be executed at each login. biff operates asynchronously. For synchronous notification use the MAIL variable of sh or the mail variable of csh. SEE ALSO csh(l), sh(l), mail(l), comsat(8) 20 Last change: 23 September 1985 Sun Release 3.0 BINMAIL ( 1 ) USER COMMANDS BINMAIL ( 1 ) NAME /bin/mail - send or receive mail among users SYNOPSIS /bin/mail [ — i ] [ — p ] [ — q ] [ — f filename ] /bin/mail address . . . DESCRIPTION Note: This is the old version 7 UNIX system mail program. The default mail command is described in mail(l), and its binary is in the directory lusr/ucb. /bin/mail with no address prints a user’s mail, message-by-message in last-in, first-out order. Ibin/mcdl accepts commands from the standard input to direct disposition messages. When addresses are named, /bin/ mail takes the standard input up to an end-of-file (or a line with just V) and adds it to each person's ‘mail’ file. The message is preceded by the sender’s name and a postmark. Lines that look like postmarks are prepended with “>’. A person is usually a user name recognized by login, or a network address (see mailaddr(7)). If there is any pending mail, login tells you there is mail when you log in. It is also possible to have the C- Shell, or the daemon biff tell you about mail that arrives while you are logged in. OPTIONS Printing Mail -i continue after interrupts — an interrupt normally terminates the lbinlma.il accepts the following interactive commands when printing messages. -p print messages without prompting for commands. Exit immediately upon receiving an interrupt, -q quit immediately upon interrupt. -f filename use filename as if it were the mail file. Sending Mail — d deliver mail directly, don’t route the message through sendmail. This option is often used by pro- grams that send mail. -i continue after interrupts — an interrupt normally terminates the /bin/mail command and leaves the mail file unchanged. — r name specify a string to appear as the name of the sender. COMMANDS ? print a command summary. EOT (control-D) put unexamined mail back in the mail file and quit. ! command escape to the Shell to do command. - go back to previous message. + go on to next message, newline go on to next message, d delete message and go on to the next, dq delete message and quit, m [ person ] ... mail the message to the named persons (yourself is default). Sun Release 3.0 Last change: 23 September 1985 21 BINMAIL(l) USER COMMANDS BINMAIL ( 1 ) n go on to next message, p print message (again), q same as EOT. s [file ] ... save the message in the named files (‘mbox’ default). If saved successfully, remove it from the list and go on to the next message. w [file ] ... save the message, without a header, in the named files (‘mbox’ default). If saved successfully, remove it from the list and go on to the next message. x exit without changing the mail file. FILES /etc/passwd to identify sender and locate address /usr/spool/mail/* incoming mail for user * mbox saved mail /tmp/ma* temp file /usr/spool/mail/ * .lock lock for mail directory dead.letter unmailable text is saved here SEE ALSO mail(l), biff(l), write(l), uucp(lC), uux(lC), xsend(l), sendmail(8), mailaddr(7), csh(l) BUGS Race conditions sometimes result in a failure to remove a lock file. The superuser can read your mail, unless it is encrypted by des, encrypt, or xsend. Even if you encrypt it, the superuser can delete it. 22 Last change: 23 September 1985 Sun Release 3.0 CAL(l) USER COMMANDS CAL(l) NAME cal - display calendar SYNOPSIS cal [ month ] year DESCRIPTION Cal displays a calendar for the specified year. If a month is also specified, a calendar for that month only is displayed. Year can be between 1 and 9999. Be aware that ‘cal 78’ refers to the early Christian era, not the 20th cen- tury. Also, the year is always considered to start in January, even though this is historically naive. Month is a number between 1 and 12. The calendar produced is that for England and her colonies. Try September 1752. Sun Release 3.0 Last change: 26 April 1983 23 CALENDAR ( 1 ) USER COMMANDS CALENDAR ( 1 ) NAME calendar - reminder service SYNOPSIS calendar [ - ] DESCRIPTION Calendar consults the file calendar in the current directory and displays lines that contain today’s or tomorrow’s date anywhere in the line. Most reasonable month-day dates — such as ‘Dec. 7,’ ‘december 7,’ and ‘12/7’ — are recognized; but ‘7 December’ or ‘7/12’ are not. If you give the month as with a date — for example, “* 1” — that day in any month will do. On weekends ‘tomorrow’ extends through Monday. When the optional - argument is present, calendar does its job for every user who has a file calendar in his login directory and sends him any positive results by mail{\)- Normally this is done daily in the wee hours under control of cron (8). The file calendar is first run through the C preprocessor, llib/cpp, to include any other calendar files specified with the usual “finclude” syntax. Included calendars are usually shared by all users, and main- tained by the system administrator. FILES '/calendar /usr/lib/calendar to figure out today’s and tomorrow’s dates /etc/passwd /tmp/cal* /lib/cpp subprocess /usr/bin/egrep subprocess /bin/sed subprocess /bin/mail subprocess SEE ALSO at(l), cron(8), mail(l) BUGS Calendar’s extended idea of ‘tomorrow’ doesn’t account for holidays. 24 Last change: 8 March 1984 Sun Release 3.0 CAT ( 1 ) USER COMMANDS CAT ( 1 ) NAME cat - concatenate and display SYNOPSIS cat [ -u ] [ -n ] [ -b ] [ -s ] [ -v ] [-e] [ -t ] [-] [file...] DESCRIPTION Cat reads each file in sequence and displays it on the standard output. Thus % cat goodies displays the contents of goodies on the standard output, and % cat filel flle2 >file3 concatenates the first two files and places the result on the third. If no filename argument is given, or if the argument is given, cat reads from the standard input file. If the standard input is a terminal, input is terminated by a A D. OPTIONS -u makes the output completely unbuffered. If -u is not used, output is buffered in 1024-byte blocks, or line-buffered if standard output is a terminal. -n precedes each line output with its line number. — b numbers the lines, as — n, but omits the line numbers from blank lines. — s substitutes a single blank line for multiple adjacent blank lines. -v displays non-printing characters so that they are visible. Control characters print like "X for control-x; the delete character (octal 0177) prints as *?. Non-ASCH characters (with the high bit set) are displayed as M- (for meta) followed by the character of the low 7 bits. -e displays non-printing characters, as -v, and in addition displays a *$’ character at the end of each line. -t displays non-printing characters, as -v, and in addition displays tab characters as ‘T. SEE ALSO cp(l), ex(l), more(l), pr(l), tail(l) BUGS Beware of ‘cat a b >a’ and ‘cat a b >b’, which destroy the input files before reading them. Sun Release 3.0 Last change: 2 June 1983 25 CB( 1) USER COMMANDS CB(1) NAME cb - C program beautifier SYNOPSIS cb DESCRIPTION cb places a copy of the C program from the standard input on the standard output with spacing and indenta- tion that displays the structure of the program. SEE ALSO indent(l) BUGS indent(\) is preferred. 26 Last change: 23 September 1985 Sun Release 3.0 CC(1) USER COMMANDS CC(1) NAME cc - C compiler SYNOPSIS cc [ c ] [-g] [-o output] [ -O ] [-a] [ -Aasmflags ] [ -C ] [ -D name ] [-D name=def] [-E] [ -fsingle ] [ float _option ] [ -go ] [ -I dir ] [ -p ] [ -pg ] [ -R ] [ -S ] [ ~t [ p|0|2|a|c|l ] ] [ -B string ] [ -U name ] [ -v ] [ -w ] filename . . . DESCRIPTION Cc is the UNIX C compiler which translates programs written in the C programming language into execut- able load modules, or into relocatable binary programs for subsequent loading with the ld( 1) linker. In addition to the many options, cc accepts several types of files. Files whose names end with .c are taken to be C source programs; they are compiled, and each resulting object program is left in the current direc- tory, with the same name as the source file, except that the .c suffix is replaced by .o. In the same way, files whose names end with ^ are taken to be assembly source programs and are assembled, producing a .o file. Other arguments are taken to be loader option arguments, object programs, or libraries of object programs. Unless -c, -S, or -E is specified, these programs and libraries, together with the results of any compila- tions or assemblies specified, are loaded (in the order given) to produce an executable program named a. out. The name a. out can be overridden with the loader’s -o option. If a single C program is compiled and loaded all at once, the intermediate .0 file is deleted. OPTIONS The following options are interpreted by cc. See ld{ 1) for load-time options. -c Compile only — suppress the loading phase, and force an object file to be produced even if only one program is compiled. -g Produce additional symbol table information for dbx(l) and pass the -Ig flag to ld( 1). -o output Name the final output file output. If this option is used, the file a. out is left undisturbed. -O Invoke the object code optimizer to improve the generated code. This option should be used for all production code, though not during development, since it slows the compiler down. -a Insert code into the program to count how many times each basic block in the program is exe- cuted. This process is performed after the C preprocessor cpp has run but before compilation takes place. After the program is compiled with this option, there will be a .d file for every .c file. The A file accumulates execution data for the corresponding source file. The fcov(l) utility can then be run on the source file to generate statistics about the program. The -a option must be used when linking with the cc(l) or W(l) command also. —Aasmflags Pass asmflags to the assembler as in its command line. For example, -A-j would pass the -j option to tell the assembler to use short PC-relative instructions for subroutine calls. -C Prevent the C preprocessor from removing comments. — D name —Dname=def Define name to the preprocessor, as if by ‘tdefine’. If no definition is given, the name is defined as "1". -E Run only the C preprocessor on the named C programs, and send the result to the standard out- put. -fsingle Use single-precision arithmetic in computations involving only float numbers — that is, do not convert everything to double, which is the default. Note that floating-point parameters are still converted to double precision, and functions which return values still return double precision values. Certain programs ran much faster using this option, but be aware that some significance Sun Release 3.0 Last change: 21 December 1985 27 CC(1) USER COMMANDS CC(1) can be lost due to lower precision intermediate values. float_option Floating point code generation option. Can be one of: — fsoft software floating-point calls (this is the default). —fsky in-line code for Sky floating-point processor (supported only on Sun-2). -f68881 in-line code for Motorola MC6888 1 floating-point processor (supported only on Sun-3). -fswitch run-time-switched floating-point calls. The compiled object code is linked at run- time to routines that support one of the above types of floating point code. This was the default in previous releases. Only for use with programs that are floating-point intensive, and must be portable to machines with various floating-point options. When invoked without float option, the compiler interrogates the FLOAT_OPTION environ- ment variable to determine the type of floating-point code to generate. Legal values for FLOAT OPTION are: ‘fsoft’, ‘fsky’, ‘f68881’, ‘ffpa’ and ‘fswitch’. -go Produce additional symbol table information in an older format used by the adb debugger and pass the -lg flag to ld( 1). -I dir ‘#include’ files whose names do not begin with 7’ are always sought first in the directory of the file argument, then in directories named in -I options, then in the lusr/include directory. -p Produce profiling code to count the number of times each routine is called. If loading takes place, replace the standard startup routine by one that automatically calls monitor (3) and use a special profiling library in lieu of the standard C library. When the program is run, the file mon. out is created. An execution profile can then be generated by use of prof. -pg Produce profiling code in the manner of -p, but invoke a run-time recording mechanism that keeps more extensive statistics and produces a gmon.out file at normal termination, gprof(l) generates an execution profile. -R Passed on to as(l), making initialized variables shared and read-only. -S Compile the named C programs and leave the assembly language output on corresponding files suffixed .j. -t[p012acl] Use the designated compiler components in the directory named in the -B option. In the absence of a -B option, the directory is taken to be lusrlnew. The combinations that can be specified for the -t option are: p cpp — the C preprocessor. 0 ccom — the C compiler proper. 2 c2 — the assembly code optimizer, a as — the assembler, c libc — the C library. 1 Id — the loader. -B string Find substitute compiler components in the directory string, which must be a pathname ter- minated with a slash (/). -Vname Remove any initial definition of name for the C preprocessor. -v Display a message on standard error indicating the argument string that invoked each phase of the compiler. -w Suppress warning messages. 28 Last change: 21 December 1985 Sun Release 3.0 CC(1) USER COMMANDS CC(1) FILES file.c C source file file.s assembler source file file.o object file file.a library of object files a.out executable output file /tmp/ctm? compiler temporary file /lib/Fcrtl.o startup code for -fsoft option /lib/Mcrtl.o startup code for -f68881 option /lib/Scrtl.o startup code for — fsky option /lib/cpp macro preprocessor /usr/lib/bb count block counting preprocessor /lib/ccom compiler /lib/c2 optional optimizer /lib/crtO.o runtime startoff /lib/mcrtO.o startoff for profiling /usr/lib/gcrtO.o startoff for gprof-profiling /usr/lib/bb_link.o basic block counting routine /lib/fcrtO.o SKY runtime startoff /lib/fmcrtO.o SKY startoff for profiling /usr/lib/fgcrtO.o SKY startoff for gprof-profiling /lib/libc.a standard library, see intro (3) /usr/lib/libc_p.a profiling library, see intro (3) /usr/include standard directory for ‘#include’ files mon.out file produced for analysis by prof{ 1) gmon.out file produced for analysis by gprof(l) /usr/new default directory for components listed in the -t option SEE ALSO B. W. Kemighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978 UNIX Programming in Programming Tools for the Sun Workstation monitor(3), prof(l), gprof(l), tcov(l), adb(l), ar(l), ld(l), dbx(l), as(l), diff(l), cpp(l) DIAGNOSTICS The diagnostics produced by C itself are intended to be self-explanatory. Occasional obscure messages may be produced by the preprocessor, assembler, or loader. BUGS Options that are identical to cc options cannot be passed to the assembler, optimizer or loader. The program context given in syntax error messages is taken from the input text after the C preprocessor has performed substitutions. Therefore, error messages involving syntax errors in or near macro references or manifest constants may be misleading. Sun Release 3.0 Last change: 21 December 1985 29 CD( 1 ) USER COMMANDS CD( 1 ) NAME cd - change working directory SYNOPSIS cd [ directory ] DESCRIPTION Directory becomes the new working directory. The process must have execute (search) permission in directory. If cd is used without arguments, it returns you to your login directory. In cj7i(1) you may specify a list of directories in which directory is to be sought as a subdirectory if it is not a subdirectory of the current directory; see the description of the cdpath variable in csfc(l). SEE ALSO csh(l), sh(l), pwd(l) 30 Last change; 26 April 1983 Sun Release 3.0 CDC(l) USER COMMANDS CDC(l) NAME cdc - change the delta commentary of an SCCS delta SYNOPSIS /usr/ucb/sccs/cdc -r SID [ -m [ mrlist ] ] [ -y [ comment ] ] filename . . . DESCRIPTION cdc changes the delta commentary, for the SID specified by the -r option, of each named SCCS filename. Delta commentary is defined to be the Modification Request (MR) and comment information normally specified via the delta command (-m and -y options). If a directory is named, cdc behaves as though each file in the directory were specified as a named filename, except that non-SCCS files (last component of the path name does not begin with s.) and unread- able files are silently ignored. If a name of - is given, the standard input is read (see WARNINGS); each line of the standard input is taken to be the name of an SCCS file to be processed. Arguments to cdc, which may appear in any order, consist of options and file names. OPTIONS All the described options apply independently to each named file: -tSID Specifies the SCCS /Identification (S/D) string of a delta for which the delta commentary is to be changed. -m[ mrlist) If the SCCS file has the v flag set (see admin(\)), a list of MR numbers to be added and/or deleted in the delta commentary of the SID specified by the -r option may be supplied. A null MR list has no effect. MR entries are added to the list of MRs in the same manner as that of delta. In order to delete an MR, precede the MR number with the character ! (see EXAMPLES). If the MR to be deleted is currendy in the list of MRs, it is removed and changed into a “comment” line. A list of all deleted MRs is placed in the comment section of the delta commentary and preceded by a comment line stating that they were deleted. If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the stan- dard output before the standard input is read; if the standard input is not a terminal, no prompt is issued. The MRs? prompt always precedes the comments? prompt (see -y option). MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character terminates the MR list. Note that if the v flag has a value (see admin (l)), it is taken to be the name of a program (or shell procedure) which validates the correctness of the MR numbers. If a non-zero exit status is returned from the MR number validation program, cdc terminates and the delta commen- tary remains unchanged. -y [comment] Arbitrary text used to replace the comment (s) already existing for the delta specified by the -r option. The previous comments are kept and preceded by a comment line stating that they were changed. A null comment has no effect. If -y is not specified and the standard input is a terminal, the prompt comments? is issued on the standard output before the standard input is read; if the standard input is not a terminal, no prompt is issued. An unescaped new-line character terminates the comment text The exact permissions necessary to modify the SCCS file are documented in Source Code Control System. Simply stated, they are either (1) if you made the delta, you can change its delta commentary; or (2) if you own the file and directory you can modify the delta commentary. EXAMPLES Sun Release 3.0 Last change; 23 September 1985 31 CDC(l) USER COMMANDS CDC(l) tutorial cdc -rl.6 -m"bl78-12345 !bl77-54321 bI79-00001" -ytrouble s.file adds bl78- 12345 and bl79-00001 to the MR list, removes bl77-54321 from the MR list, and adds the com- ment trouble to delta 1.6 of s.file. tutorial% cdc -rl.6 s.file MRs? !bl77-54321 bl78-12345 bl79-00001 comments? trouble does the same thing. WARNINGS If SCCS file names are supplied to the cdc command via the standard input (- on the command line), then the -m and -y options must also be used. FILES x-file (see delta( 1)) z-file (see delta(l)) SEE ALSO admin(l), comb(l), delta(l), get(l), help(l), prs(l), sccs(l), sccsdiff(l), sccsfile(5), val(l), what(l) Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help for explanations. 32 Last change: 23 September 1985 Sun Release 3.0 CHECKNR ( 1 ) USER COMMANDS CHECKNR ( 1 ) NAME checknr - check nroff/troff files SYNOPSIS checknr [ -s ] [ -f ] [ -a jd.yljc2.y2 . . . jcn.yn ] [ -c jc1jc2jc3 ...jc n] [filename ... ] DESCRIPTION Checknr checks a list of nroff(l) or tr off ( 1 ) input files for certain kinds of errors involving mismatched opening and closing delimiters and unknown commands. If no files are specified, checknr checks the stan- dard input. Delimiters checked are: (1) Font changes using \fic . . . \fP. (2) Size changes using \sx . . . \s0. (3) Macros that come in open . . . close forms, for example, the .TS and .TE macros which must always come in pairs. Checknr knows about the ms(J) and me (7) macro packages. Checknr is intended to be used on documents that are prepared with checknr in mind. It expects a certain document writing style for \f and \s commands, in that each \fx must be terminated with \fP and each \sx must be terminated with \s0. While it will work to directly go into the next font or explicitly specify the original font or point size, and many existing documents actually do this, such a practice will produce com- plaints from checknr. Since it is probably better to use the \fP and \s0 forms anyway, you should think of this as a contribution to your document preparation style. OPTIONS -s Ignore \s size changes. -f Ignore \f font changes. -a Add pairs of macros to the list The pairs of macros are assumed to be those (such as .DS and X)E) that should be checked for balance. The —a option must be followed by groups of six char- acters, each group defining a pair of macros. The six characters are a period, the first macro name, another period, and the second macro name. For example, to define a pair .BS and .ES, use -a.BSJES -c define commands which checknr would otherwise complain about as undefined. SEE ALSO nroff(l), troff(l), ms(7), me(7), checkeq(l) BUGS There is no way to define a 1 character macro name using -a Sun Release 3.0 Last change: 13 March 1984 33 CHGRP(l) USER COMMANDS CHGRP(l) NAME chgrp - change group SYNOPSIS chgrp [ -f ] group file ... DESCRIPTION Chgrp changes the group-ID of the files to group. The group may be either a decimal GID or a group name found in the group-ID file. The user invoking chgrp must belong to the specified group and be the owner of the file, or be the super- user. No errors are reported when the — f (force) option is given. FILES /etc/group SEE ALSO passwd(5), group(5) 34 Last change: 3 December 1985 Sun Release 3.0 CHMOD(l) USER COMMANDS CHMOD(l) NAME chmod - change mode SYNOPSIS chmod mode file . . . DESCRIPTION The mode of each named file is changed according to mode, which may be absolute or symbolic. An abso- lute mode is an octal number constructed from the OR of the following modes: 4000 set user ID on execution 2000 set group ID on execution 1000 sticky bit, see chmod(2) 0400 read by owner 0200 write by owner 0100 execute (search in directory) by owner 0070 read, write, execute (search) by group 0007 read, write, execute (search) by others A symbolic mode has the form: [ who ] op permission [ op permission ]. . . The who part is a combination of the letters u (for user’s permissions), g (group) and o (other). The letter a stands for all, or ugo. If who is omitted, the default is a but the setting of the file creation mask (see umask in sh{ 1) or csh (l]for moreinformation ) is Op can be + to add permission to the file’s mode, - to take away permission and = to assign permission absolutely (all other bits for that category, owner, group, or others, will be reset). Permission is any combination of the letters r (read), w (write), x (execute), s (set owner or group id) and t (save text - sticky). Letters u, g or o indicate that permission is to be taken from the current mode. Omit- ting permission is only useful with = to take away all permissions. EXAMPLES The first example denies write permission to others, the second makes a file executable: chmod o-w file chmod +x file Multiple symbolic modes separated by commas may be given. Operations are performed in the order specified. The letter s is only useful with u or g. Only the owner of a file (or the super-user) may change its mode. SEE ALSO ls(l), chmod(2), chown(8) Sun Release 3.0 Last change: 3 December 1985 35 CHSH(l) USER COMMANDS CHSH(l) NAME chsh - change default login shell SYNOPSIS chsh username [ shell ] DESCRIPTION Chsh changes the login shell field of the user’s password file entry. If no shell is specified, the shell reverts to the default login shell Ibinlsh. To specify a shell other than Ibinlcsh, you must be the super-user. EXAMPLES angel% chsh bill /bin/csh SEE ALSO csh(l), passwd(l), passwd(5) 36 Last change: 22 December 1983 Sun Release 3.0 CLEAR ( 1 ) USER COMMANDS CLEAR ( 1 ) NAME clear — clear screen SYNOPSIS clear DESCRIPTION Clear clears your screen if this is possible. It looks in the environment for the terminal type and then in letcltermcap to figure out how to clear the screen. FILES /etc/termcap terminal capability data base Sun Release 3.0 Last change: 12 February 1985 37 CUE ARCOLORMAP ( 1 ) USER COMMANDS CUE AR_COLORMAP ( 1 ) NAME clearcolormap - clear the color map SYNOPSIS clear_colormap DESCRIPTION Clear colormap clears your hardware colormap. 38 Last change: 21 August 1985 Sun Release 3.0 CLICK(l) USER COMMANDS CLICK(l) NAME click - control the keyboard keystroke click sound SYNOPSIS click [ -y ] [ -n ] [ -d keyboard device ] DESCRIPTION Change the setting of the audible keyboard click. The default is no keyboard click. If you want to turn clicking on then a good place to do it is in /etc/rc.local. Only keyboards that support a clicker respond to this command. At the time of this writing, the only key- board known to have a clicker is the Sun 3 keyboard. OPTIONS -y Yes, enable clicking. -n No, disable clicking. — d keyboard device Specify the keyboard device being set. The default is Idevlkbd. SEE ALSO kb(4s) DIAGNOSTICS A short help message is printed if an unknown flag is specified or if the -d switch is used and the keyboard device name is not supplied. A diagnostic is printed if the keyboard device name can’t be opened or is not a keyboard type device. BUGS There is no way to determine the state of the keyboard click setting. Sun Release 3.0 Last change: 18 December 1985 39 CLOCK(l) USER COMMANDS aOCK(l) NAME clock - display the time in a window SYNOPSIS clock [-s] [ — t ] [-r] [-dmdyaw] [-f] DESCRIPTION clock is a standard tool provided with the SunView environment. clock displays the current time in its own window. In its open state, clock shows the date and time textual form. In its closed state, clock appears as a clock face which keeps time. Note: In previous releases clock was known as clocktool. In the current release, clocktool is retained as a symbolic link to clock. OPTIONS -r causes clock to use a square face with roman numerals in the iconic state. This replaces the default round clock face. -d display date information in a small area just below the clock face. The date information to be displayed may include: m the month, d the day of the month (1-31), y the year, a the string AM or PM, as appropriate, w the day of the week (Sun-Sat). There is only room for 3 of these, but any 3 may be displayed in any sequence. -f Display the date and day of week on the clock face. -s start clock with the seconds turned on. By default, the clock starts with seconds turned off, and updates every minute. With seconds turned on, it updates every second, and, if iconic, displays a second hand. -t Test mode — ignore the real time, and instead run in a loop continuously incrementing the time by one minute and displaying it. clock also accepts all of the generic tool arguments discussed in suntools(l). When open, clock listens for keyboard input, toggling its state on four characters: s or S toggles the display of seconds. t or T toggles the ‘test’ mode. SEE ALSO suntools(l), date(l) FILES /usr/lib/fonts/fixedwidthfonts/sail.r.6 BUGS If you reset the system time, clock will not reflect the new time until you change its state open it if closed, close it if open. To reset the system time, see date( 1). The date display doesn’t go well with the round clock face. The clock sometimes freezes. Bringing up the Frame Menu will unstick it. 40 Last change: 25 December 1985 Sun Release 3.0 CMDTOOL ( 1 ) USER COMMANDS CMDTOOL ( 1 ) NAME cmdtool - Run a shell (or other program) from the SunView text facility SYNOPSIS cmdtool [ -C ] [ program [ args ] ] DESCRIPTION cmdtool is a standard tool provided with the SunView environment. When invoked, cmdtool runs a program (usually a shell) in a text-based command subwindow. Typed characters are inserted at the caret. If this program is a shell, it accepts commands and runs programs in the usual way. (See BUGS below). Text can be edited anywhere on the command line the same way as in any other text subwindow. Com- mands and their output are kept in a log which can be scrolled using the scrollbar. The log file can also be edited, or even saved using the Save command in the text facility’s pop-up menu. The Split command, also in the pop-up menu, can be used to create two or more independently scrolling views of the log. DEFAULTS OPTIONS /Tty/Append_only_log TRUE is the standard default; it means that only the command line may be editted. FALSE per- mits editting of the entire log. See the descripton of Edit On below. /Tty/Insert_makes_caret_visible This entry describes how hard the command subwindow should try to keep the caret visible. Same_as_for_text Is the standard default; it means that the setting for Insert_makes_caret_visible will be taken from the Text category instead of Tty when a command subwindow is created. If_auto_scroll If the caret is showing, and an inserted newline would position it below the bottom of the screen as determined by /Text/Lower_context, the text is scrolled to keep it showing. The amount scrolled is controlled by /Text/Auto_scroll_by. See textedit (1) for more information. Always Upon any input action, if the caret is positioned off the screen, it is scrolled back into view. /Text/Edit_back_char Set the character for deleting the character preceding the caret. Note: Stty erase has no effect ; text based tools only refer to the defaults database. The standard default is the del key. /Text/Edit_back_word Set the character for deleting the word preceding the caret Note: Stty werase has no effect-, text based tools only refer to the defaults database. The standard default is ctrl-w. /Text/Edit_back_line Set the character for deleting from the newline preceding the caret to the caret. Note: Stty kill has no effect-, text based tools only refer to the defaults database. The standard default is ctrl-u. COMMANDLINE OPTIONS -C Redirect system console output to this instance of the cmdtool. This will prevent system error messages from being printed in unexpected places on the screen. Moreover, since a cmdtool win- dow is scrollable, messages that go off the top of the window can be scrolled back for re- examination. cmdtool also takes generic tool arguments; see suntools (1) for a list of these arguments. program [ args ] If a program argument is present, cmdtool executes it. Subsequent arguments will be assumed to be arguments of the program argument, and will be passed to it for execution. If there are no arguments, cmdtool runs the program corresponding to the SHELL environment variable. If this environment variable is not available, then cmdtool runs /bin/sh. Sun Release 3.0 Last change: 30 September 1985 41 CMDTOOL ( 1 ) USER COMMANDS CMDTOOL ( 1 ) THE COMMAND SUBWINDOW The subwindow of cmdtool is a command subwindow, which is also found in dbxtool and potentially in other tools as well. The command subwindow is based on the text facility. For more information about the text facility, see Windows and Window-Based Tools: Beginner’s Guide. The pop-up menu associated with command subwindow is the same as that for the text facility (see textedit (1)), with one additional item, Edit On. The generic text menu items will not be described here except for Put, then Get, as it approxi- mates the functionality of Stuff in shelltool (1), and is also implemented for shelltool. Put, then Get When there is a selection, this item reads Put, then Get. It causes the selection to be copied both to the shelf and to the caret. Put, then Get When there is no selection but there is text on the shelf, Put, then is grayed out, though Get remains active. Selecting this item causes the contents of the shelf to be copied to the caret. When there is no selection and nothing is on the shelf, this item is inactive. Edit On If the defaults entry Append_only_log is set to TRUE, but at some point you want to edit the log, selecting this menu item makes editting the log possible. When the log is editable, this item reads Edit Off, and selecting it makes the log read-only before the start of the command line. Certain text facility accelerators that are especially useful in command subwindows are described here. See textedit (1) for more information. CTRL-RETURN Holding down the control key while typing newline (carriage return) positions the caret at the bot- tom and scrolls it into view, as determined by the defaults option /Text/Lower_context. CTRL-P is an accelerator for the Put, then Get menu item described above. CAPS-lock Bound to FI, it causes subsequent keyboard input to be uppercase. This key is a toggle; striking it a second time undoes the effect of the first strike. FILES /tmp/tty.txtnnnnnn "/.texts wrc SEE ALSO shelltool(l), suntools(l), textedit(l), defaultsedit(l), Windows and Window-Based Tools: Beginner’s Guide BUGS Full terminal emulation is not yet supported. Programs that use cbreak or raw mode, no echo, or curses do not work as expected. Some examples of manifestations of this deficiency include: • To send a command to more other than newline, the desired command must be followed by ctrl-d. • v/ comes up in open mode. • The ~h command in mail doesn’ t work. • The password to su is echoed. o ctrl-c from a cmdtool running su but not started from a shell owned by root doesn’t work. • The select system call never notices input on stdin. • rlogin double echos and CTRL-D kills rlogin, not just the program running from it Occasionally the program run from cmdtool unexplainably hangs. 42 Last change: 30 September 1985 Sun Release 3.0 CMP(l) USER COMMANDS CMP(l) NAME cmp - compare two files SYNOPSIS cmp [ -1 ] [ -s ] filel file2 DESCRIPTION Cmp compares filel and Jile2. If filel is cmp reads from the standard input. Under default options cmp makes no comment if the files are the same; if they differ, it announces the byte and line number at which the difference occurred. If one file is an initial subsequence of the other, that fact is noted. OPTIONS -1 Print the byte number (decimal) and the differing bytes (octal) for each difference. -s Print nothing for differing files; return codes only. SEE ALSO diff(l), comm(l) DIAGNOSTICS Exit code 0 is returned for identical files, 1 for different files, and 2 for an inaccessible or missing argu- ment. Sun Release 3.0 Last change: 29 April 1983 43 COL ( 1 ) USER COMMANDS COL ( 1 ) NAME col - filter reverse paper motions SYNOPSIS col [ -bfh ] DESCRIPTION col copies the standard input to the standard output and performs line overlays implied by reverse line feeds (ESC-7 in ASCII) and by forward and reverse half line feeds (ESC-9 and ESC-8). col is particularly useful for filtering multicolumn output made with the ‘.rt’ command of nr off and output resulting from use of the tbl preprocessor. The control characters SO (ASCII code 017), and SI (016) are assumed to start and end text in an alternate character set. The character set (primary or alternate) associated with each printing character read is remembered; on output, SO and SI characters are generated where necessary to maintain the correct treat- ment of each character. All control characters are removed from the input except space, backspace, tab, return, newline, ESC (033) followed by one of 7, 8, 9, SI, SO, and VT (013). This last character is an alternate form of full reverse line feed, for compatibility with some other hardware conventions. All other non-printing characters are ignored. OPTIONS -f Fine: although col accepts half line motions in its input, it normally does not emit them on output. Instead, text that would appear between lines is moved to the next lower full line boundary. The -f option suppresses this treatment — in this case the output from col may contain forward half line feeds (ESC-9), but will still never contain either kind of reverse line motion. -b col assumes that the output device in use is not capable of backspacing. In this case, if several characters are to appear in the same place, only the last one read will be taken. -h Convert strings of blanks to tabs (this increases printing time). SEE ALSO troff(l), tbl(l) BUGS Can’t back up more than 128 lines. No more than 800 characters, including backspaces, on a line. 44 Last change: 23 September 1985 Sun Release 3.0 COLCRT ( 1 ) USER COMMANDS COLCRT ( 1 ) NAME colcrt - filter nroff output for CRT previewing SYNOPSIS colcrt [-] [-2] [file... ] DESCRIPTION Colcrt provides virtual half-line and reverse line feed sequences for terminals without such capability, and on which overstriking is destructive. Half-line characters and underlining (changed to dashing * ") are placed on new lines in between the normal output lines. OPTIONS - Suppress all underlining — especially useful for previewing allboxed tables from tbl(l). -2 Print all half-lines, effectively double spacing the output Normally, a minimal space output for- mat is used which suppresses empty lines. Colcrt never suppresses two consecutive empty lines, however. The -2 option is useful for sending output to the line printer when the output contains superscripts and subscripts which would otherwise be invisible. EXAMPLE A typical use of colcrt would be tbl exum2.n | nroff -ms | colcrt - 1 more SEE ALSO nroff(l), troff(l), col(l), more(l), ul(l) BUGS Can’t back up more than 102 lines. General overstriking is lost; as a special case T overstruck with or underline becomes V. Lines are trimmed to 132 characters. Some provision should be made for processing superscripts and subscripts in documents which are already double-spaced. Sun Release 3.0 Last change: 13 April 1983 45 COLRM(l) USER COMMANDS COLRM(l) NAME colrm - remove columns from a file SYNOPSIS colrm [ started [ endcol ] ] DESCRIPTION Colrm removes selected columns from a text file. The text is is taken from standard input and copied to the standard output with the specified columns removed. If only started is specified, the columns of each line are removed starting with startcol and extending to the end of the line. If both startcol and endcol are specified, all columns between startcol and endcol, inclusive, are removed. Column numbering starts with column 1. SEE ALSO expand(l) 46 Last change: 13 April 1983 Sun Release 3.0 COMB ( 1 ) USER COMMANDS COMB ( 1 ) NAME comb - combine SCCS deltas SYNOPSIS /usr/sccs/comb [ -o ] [ -s ] [ -p SID ] [ -c list ] filename . . . DESCRIPTION Comb generates a shell procedure (see sh( 1)) which, when run, will reconstruct the given SCCS files. If a directory is named, comb behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is taken to be the name of an SCCS file to be processed; non-SCCS files and unreadable files are silently ignored. The generated shell procedure is written on the standard output. OPTIONS Options are explained as though only one named file is to be processed, but the effects of any option apply independently to each named file. -p SID The SCCS Identification string (SID) of the oldest delta to be preserved. All older deltas are dis- carded in the reconstructed file. -c list A list of deltas to be preserved. All other deltas are discarded. See get(l) for the syntax of a list. -o For each get -e generated, the reconstructed file is accessed at the release of the delta to be created. In the absence of the — o option, the reconstructed file is accessed at the most recent ancestor. Use of the -o option may decrease the size of the reconstructed SCCS file. It may also alter the shape of the delta tree of the original file. -s Generate a shell procedure which, when run, will produce a report giving, for each file: the file name, size (in blocks) after combining, original size (also in blocks), and percentage change com- puted by: 100 * (original - combined) / original It is recommended that before any SCCS files are actually combined, you should use this option to determine exactly how much space is saved by the combining process. If no options are specified, comb preserves only leaf deltas and the minimal number of ancestors needed to preserve the tree. FILES s.COMB The name of the reconstructed SCCS file, comb????? Temporary. SEE ALSO sccs(l), admin(l), delta(l), get(l), help(l), prs(l), sccsfile(5). Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help(\) for explanations. BUGS Comb may rearrange the shape of the tree of deltas. It may not save any space; in fact, it is possible for the reconstructed file to actually be larger than the original. Sun Release 3.0 Last change: 6 March 1984 47 COMM ( 1 ) USER COMMANDS COMM ( 1 ) NAME comm - select or reject lines common to two sorted files SYNOPSIS comm [ - [ 123 ] ] filel file2 DESCRIPTION Comm reads filel and file2, which should be ordered in ASCII collating sequence, and produces a three column output: lines only in filel; lines only in file2; and lines in both files. The filename means the standard input. Flags 1, 2, or 3 suppress printing of the corresponding column. Thus comm -12 prints only the lines com- mon to the two files; comm -23 prints only lines in the first file but not in the second; comm -123 does nothing. SEE ALSO cmp(l), diff(l), uniq(l) 48 Last change: 15 March 1983 Sun Release 3.0 COMPACT ( 1 ) USER COMMANDS COMPACT ( 1 ) NAME compact, uncompact, ccat - compress and uncompress files, and cat them SYNOPSIS compact [ filename . . . ] uncompact [ filename . . . ] ccat [ filename ... ] DESCRIPTION Compact compresses the named files using an adaptive Huffman code. If no file names are given, the stan- dard input is compacted to the standard output. Compact operates as an on-line algorithm. Each time a byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huff- man code for the set of frequencies seen so far. It is unnecessary to prepend a decoding tree to the compressed file since the encoder and the decoder start in the same state and stay synchronized. Further- more, compact and uncompact can operate as filters. In particular: ... | compact | uncompact | . . . operates as a (very slow) no-op. When an argument file is given, it is compacted and the resulting file is placed in file.C; file is removed. The first two bytes of the compacted file code the fact that the file is compacted. This code is used to prohibit recompaction. The amount of compression to be expected depends on the type of file being compressed. Typical values of compression are: Text (38%), Pascal Source (43%), C Source (36%) and Binary (19%). These values are the percentages of file bytes reduced. Uncompact restores the original file from a file called file.C which was compressed by compact. If no file names are given, the standard input is uncompacted to the standard output Ccat cats the original file from a file compressed by compact, without uncompressing the file. FILES *C compacted file created by compact, removed by uncompact SEE ALSO Gallager, Robert G., Variations on a Theme of Huffman’, I.E.E.E. Transactions on Information Theory, vol. IT-24, no. 6, November 1978, pp. 668 - 674. Sun Release 3.0 Last change: 1 November 1983 49 CP(1) USER COMMANDS CP(1) NAME cp - copy files SYNOPSIS cp [ — i ] [ -r ] filel file2 cp [ -i ] [ -r ] file . . . directory DESCRIPTION Filel is copied onto file2 . The mode and owner of file2 are preserved if it already existed; the mode of the source file is used otherwise. In the second form, one or more files are copied into the directory with their original file-names. Cp refuses to copy a file onto itself. OPTIONS -i Interactive: prompt the user with the name of the file whenever the copy would overwrite an old file. Answering with ’y’ means that cp should go ahead and copy the file. Any other answer will prevent cp from overwriting the file. -r Recursive: if any of the source files are directories, cp copies each subtree rooted at that name; in this case the destination must be a directory. EXAMPLES To make a backup copy of goodies : % cp goodies old.goodies To copy an entire directory hierarchy: % cp -r /usr/wendy/src /usr/wendy/backup However, BEWARE of a recursive copy like this one: % cp -r /usr/wendy/src /usr/wendy/src/backup which keeps copying files until it fills the entire file system. SEE ALSO cat(l), pr(l), mv(l), rcp(lC) BUGS An option to copy timestamps to the new files — for instance, when copying a whole hierarchy from one file system to another file system, or when making a backup copy, would be welcome. 50 Last change: 16 February 1984 Sun Release 3.0 CPIO(l) USER COMMANDS CPIO(l) NAME cpio - copy file archives in and out SYNOPSIS cpio -o [ acBvs ] cpio -i [ Bcdmrtuv6s ] [ patterns ] cpio -p [ adlmruvs ] directory DESCRIPTION cpio -o (copy out) reads the standard input to get a list of pathnames, and then copies those files onto the standard output, together with pathname and status information. cpio -i (copy in) reads the standard input (which is assumed to be the product of a previous cpio -o com- mand), to get a list of files selected by zero or more patterns as defined in the name-generating notation of sh or csh. In patterns, the meta-characters ?, *, and [. . .] match the slash (/) character. The default for patterns is * (select all files). cpio -p (pass) copies out and in in a single operation. Destination pathnames are interpreted relative to the named directory. OPTIONS a Reset the access times of input files after they have been copied. B Input/output is to be blocked at 5120 bytes to the record. This does not apply to the pass option. This option is only meaningful with data directed to or from /dev/rmt? d Directories should be created as needed. c Write header information in ASCII character form for portability. r Interactively rename files. If the user types a null line, the file is skipped. t Print a Table of contents of the input. No files are created. u Copy unconditionally . Normally, an older file will not replace a newer file with the same name. v Verbose option. A list of filenames is displayed. When used with the t option, the table of con- tents looks like the output of an Is -I command (see /s(l)). 1 Whenever possible, link files rather than copying them. Usable only with the -p option. m Retain previous file modification time. This option is ineffective on directories that are being copied. 6 Process an old (version 6 UNIX system) file. This is only useful with -i (copy in), s Swaps pairs of data bytes. Note that the s option cannot be used with the c option. EXAMPLES To copy the contents of a directory into an archive: tutorial% Is | cpio -o > /dev/mtO To duplicate the olddir directory hierarchy in the newdir directory: tutorial% cd olddir tutorial% find . -print | cpio -pdl newdir Some forms of cpio tapes from other sites have the bytes swapped in the file. The s option doesn’t help since it only swaps the data bytes and not the header. To overcome this problem, use dd with the conv=swab option to swap all pairs of bytes (including the header), then pipe the output of dd through cpio with the s option to swap the data bytes back again: tutorial% dd if =filename conv=swab | cpio —is Sun Release 3.0 Last change: 23 September 1985 51 CPIO(l) USER COMMANDS CPIO(l) SEE ALSO ar(l), find(l), cpio(5), tar(l) BUGS Pathnames are restricted to 128 characters. If there are too many unique linked files, cpio runs out of memory to keep track of them and linking information is lost thereafter. Only the super-user can copy spe- cial files. 52 Last change: 23 September 1985 Sun Release 3.0 CPP(l) USER COMMANDS CPP(l) NAME cpp - the C language preprocessor SYNOPSIS /lib/ cpp [ -P ] [ -C ] [ -U name ] [ -D name ] [ -D name=def ] [ -Mr ] [ ifile [ ofile ] ] DESCRIPTION Cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the cc(l) command ( cpp may optionally be invoked as the first pass of a FORTRAN 77 or Pascal compilation — see /77(1) orpc(l)). Thus the output of cpp is designed to be in a form acceptable as input to the next pass of the compiler. The preferred way to invoke cpp is through the cc(l) command. See m4( 1) for a general macro processor. Cpp optionally accepts two file names as arguments. Ifile and ofile are respectively the input and output for the preprocessor. They default to standard input and standard output if not supplied. OPTIONS -P Preprocess the input without producing the line control information used by the next pass of the C compiler. -C Pass all comments (except those which appear on cpp directive lines) through the preprocessor. By default, cpp strips out C-style comments. -U name Remove any initial definition of name, where name is a reserved symbol that is predefined by the particular preprocessor. The current list of these possibly reserved symbols includes unix, sun and either mc68010 or mc68020 (depending on whether you are running on a Sun-2 or Sun-3 sys- tem, respectively). — D name Define name as 1 (one). This is the same as if a — D name=l option appeared on the cpp command line, or as if a #define name 1 line appeared in the source file that cpp is processing. -Dname=def Define name as if by a #define directive. This is the same as if a #define name def line appeared in the source file that cpp is processing. -Idir Change the algorithm for searching for #include files whose names do not begin with / to look in dir before looking in the directories on the standard list. Thus, #include files whose names are enclosed in " " will be searched for first in the directory of the current source file, then in direc- tories named in -I options, and last in directories on a standard list. For #include files whose names are enclosed in <>, the directory of the ifile argument is not searched. See the section enti- tled details below, for exact details of the search order. -R Allow recursive macros. DIRECTIVES All cpp directives start with lines begun by #. White space (blanks or tabs) can appear after the #. The directives are: #define name token-string Replace subsequent instances of name with token-string. #define name ( arg, arg ) token-string There can be no space between name and the ‘(’. Replace subsequent instances of name followed by a ‘(’> a list of comma-separated tokens, and a ‘(’ by token-string where each occurrence of an arg in the token-string is replaced by the corresponding token in the comma-separated list. #undef name Forget the definition of name (if any) from now on. #include "filename" #include Sun Release 3.0 Last change: 21 December 1985 53 CPP(l) USER COMMANDS CPP(l) Include at this point the contents of filename (which is then run through cpp). When the notation is used, filename is only searched for in the standard places. See DETAILS below. #Iine integer-constant "filename" Generate line control information for the next pass of the C compiler. Integer-constant is inter- preted as the line number of the next line and filename is interpreted as the file where it comes from. If "filename" is not given, the current filename is unchanged. #endif comment Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must have a matching #endif. The comment can be used to associate the #endif with its opening #if. #ifdef name The lines following will appear in the output if and only if name has been the subject of a previous #define or a -D option without being the subject of an intervening #undef. #ifndef name The lines following will not appear in the output if and only if name has been the subject of a pre- vious tdefine or a -D option without being the subject of an intervening #undef. #if constant-expression Lines following will appear in the output if and only if the constant-expression evaluates to nonzero. All binary non-assignment C operators, including &&, 1 1, and „ are legal in constant- expression. The ?: operator, and the unary -, !, and ' operators, are also legal in constant- expression . The precedence of the operators is the same as defined by the C language. There is also a unary operator defined, which can be used in constant-expression in these two forms: defined ( name ) or defined name. This allows the effect of #ifdef and #ifndef in a #if directive. Only these operators, integer constants, and names which are known by cpp should be used in constant-expression. In particular, the sizeof operator is not available. #else comment Reverses for the following lines the notion of the test directive currently in effect. So if lines pre- vious to this directive are ignored, the following lines will appear in the output, and vice versa. The comment can be used to associate the #else with its opening #if. The test directives and corresponding #else directives can be nested. DETAILS Directory search order for #include files is: 1. the directory of the file which contains the #include request (that is, #include is relative to the file being scanned when the request is made) 2. the directories specified by -I options, in left-to-right order. 3. the standard directory(s) ( lusrlinclude for the Sun system). Special Names : Two special names are understood by cpp. The name LINE is defined as the current line number (a decimal integer) as known by cpp, and FILE is defined as the current filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other defined name. A newline terminates a character constant or quoted string. An escaped newline (that is, a backslash immediately followed by a newline) may be used in the body of a #define statement to continue the definition onto the next line. The escaped newline is not included in the macro body. Comments are removed (unless the — C option is used on the command line). Comments are also ignored, except that a comment terminates a token. 54 Last change: 21 December 1985 Sun Release 3.0 CPP(l) USER COMMANDS CPP(l) Macro formal parameters are recognized in #define bodies even inside character constants and quoted strings. The output from: #define abc(a) ’\a’ abc(xyz) is the seven characters ’\xyz’ (space, single-quote, escape character, x, y, z, single-quote). Macro names are not recognized inside character constants or quoted strings during the regular scan. Thus: #define abc xyz printf("abc"); does not expand ‘abc’ in the second line, because it is inside a quoted string which is not part of a #define macro definition. Macros are not expanded while processing a#define or#undef. Thus: #define abc bletch #define xyz abc #undef abc xyz produces ‘abc’. The token appearing immediately after a#ifdef or #ifndef is not expanded. Macros are not expanded during the scan which determines the actual parameters to another macro call. Thus: #define reverse(first,second)second first #define greeting hello reverse(greeting, #define greeting goodbye ) produces ‘ goodbye’ (and warns about the redefinition of ‘greeting’). Output consists of a copy of the input file, with modifications, plus lines of the form: ttlineno "filename " — indicating the original source line number and filename of the following output line. FILES lusr/include standard directory for #include files SEE ALSO cc(l), m4(l), f77(l), pc(l). DIAGNOSTICS The error messages produced by cpp are intended to be self-explanatory. The line number and filename where the error occurred are printed along with the diagnostic. NOTES When newline characters were found in argument lists for macros to be expanded, some previous versions of cpp put out the newlines as they were found and expanded. The current version of cpp replaces these newlines with blanks. Sun Release 3.0 Last change: 21 December 1985 55 CRYPT ( 1 ) USER COMMANDS CRYPT ( 1 ) NAME crypt - encode/decode SYNOPSIS crypt [ password ] DESCRIPTION crypt encrypts and decrypts the contents of a file, crypt reads from the standard input and writes on the standard output. The password is a key that selects a particular transformation. If no password is given, crypt demands a key from the terminal and turns off printing while the key is being typed in. crypt encrypts and decrypts with the same key: tutorial% crypt key encrypted.file tutorial% crypt key ‘>\ ‘(’> and *)’ form separate words. If doubled in *&&’, ‘| |’, *«’, or *»’ these pairs form single words. These parser metacharacters may be made part of other words, or prevented their special meaning, by preceding them with ‘W A newline preceded by a ‘V is equivalent to a blank. In addition strings enclosed in matched pairs of quotations, "’, *' ’ or form parts of a word; metachar- acters in these strings, including blanks and tabs, do not form separate words. These quotations have semantics to be described subsequently. Within pairs of "’ or characters a newline preceded by a ‘V gives a true newline character. When the shell’s input is not a terminal, the character *#’ introduces a comment which continues to the end of the input line. The *#’ character does not introduce a comment when preceded by ‘V and in quotations using*'’, “'’.and"”. Commands A simple command is a sequence of words, the first of which specifies the command to be executed. A simple command or a sequence of simple commands separated by T (vertical bar) characters forms a pipeline. The output of each command in a pipeline is connected to the input of the next. Sequences of pipelines may be separated by *;’, and are then executed sequentially. A sequence of pipelines may be exe- cuted without immediately waiting for it to terminate by following it with an *&’. Any of the above may be placed in *(’ *)’ to form a simple command (which may be a component of a pipeline, etc.) It is also possible to separate pipelines with *| |’ or *&&’ indicating, as in the C language, that the second is to be executed only if the first fails or succeeds respectively. (See Expressions). Jobs The shell associates a job with each pipeline. It keeps a table of current jobs, which you can display with the jobs command, and assigns them small integer numbers. When a job is started asynchronously with *&’, the shell prints a line which looks like: [1] 1234 Sun Release 3.0 Last change: 15 November 1985 57 CSH(l) USER COMMANDS CSH(l) indicating that this job is job number 1 and has one (top-level) process, whose process id is 1234. If you are running a job and wish to do something else you may hit the key A Z (control-Z) which sends a STOP signal to the current job. The shell then normally indicates that the job has been ‘Stopped’, and displays another prompt. You can then manipulate the state of this job, putting it in the background with the bg command, or run some other commands and then eventually bring the job back into the foreground with the foreground command fg. A A Z takes effect immediately and is like an interrupt in that pending output and unread input are discarded when it is typed. There is another special key A Y which does not generate a STOP signal until a program attempts to read (2) it. This can usefully be typed ahead when you have prepared some commands for a job which you wish to stop after it has read them. A job being run in the background will stop if it tries to read from the terminal. Background jobs are nor- mally allowed to produce output, but this can be disabled by giving the command stty tostop. If you set this tty option, background jobs will stop when they try to produce output like they do when they try to read input. There are several ways to refer to jobs in the shell. The character introduces a job name. If you wish to refer to job number 1, you can name it as ‘%1’. Just naming a job brings it to the foreground; thus ‘%V is a synonym for ‘fg %V, which brings job 1 back into the foreground. Similarly, typing ‘%1 &’ resumes job 1 in the background. Jobs can also be named by prefixes of the string typed in to start them, if these prefixes are unambiguous; thus, for example, ‘%ex’ normally restarts a suspended ex job, if there is only one suspended job whose name begins with the string ‘ex’. It is also possible to use ‘%?string’ to specify a job whose text contains string, if there is only one such job. The shell maintains a notion of the current and previous jobs. In output pertaining to jobs, the current job is marked with a V and the previous job with a The abbreviation ‘%+’ refers to the current job and *%-’ refers to the previous job. For close analogy with the syntax of the history mechanism (described below), *%%’ is also a synonym for the current job. Status reporting The shell learns immediately whenever a process changes state. It normally informs you whenever a job becomes blocked so that no further progress is possible, but only just before it prints a prompt. This is done so that it does not otherwise disturb your work. If, however, you set the shell variable notify, the shell will notify you immediately of changes of status in background jobs. There is also a shell command notify which marks a single process so that its status changes will be immediately reported. By default notify marks the current process; simply say ‘notify’ after starting a background job to mark it. When you try to leave the shell while jobs are stopped, you will be warned that ‘You have stopped jobs.’ You may use the jobs command to see what they are. If you do this or immediately try to exit again, the shell will not warn you a second time, and the suspended jobs will be terminated. Substitutions We now describe the various transformations the shell performs on the input in the order in which they occur. History substitutions History substitutions place words from previous command input as portions of new commands, making it easy to repeat commands, repeat arguments of a previous command in the current command, or fix spelling mistakes in the previous command with little typing and a high degree of confidence. History substitutions begin with the character “!’ and may begin anywhere in the input stream (with the proviso that they do not nest.) This “!’ may be preceded by an ‘V to prevent its special meaning; for convenience, a '!’ is passed unchanged when it is followed by a blank, tab, newline, “=’ or ‘(’. History substitutions also occur when an input line begins with ‘ A ’ (circumflex) — this special abbreviation is described later. Any input line which contains history substitution is echoed on the terminal before it is executed as it could have been typed without history substitution. 58 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) Commands input from the terminal which consist of one or more words are saved on the history list, the size of which is controlled by the history variable; the previous command is always retained, regardless of its value. The history substitutions reintroduce sequences of words from these saved commands into the input stream. Commands are numbered sequentially from 1. For definiteness, consider the following output from the history command: 9 write michael 10 exwrite.c 11 cat oldwrite.c 12 diff *write.c The commands are shown with their event numbers. It is not usually necessary to use event numbers, but the current event number can be made part of the prompt by placing an ‘ !’ in the prompt string. With the current event 13 we can refer to previous events by event number Mil’, relatively as in M-2’ (referring to the same event), by a prefix of a command word as in Md’ for event 12 or Mwri’ for event 9, or by a string contained in a word in the command as in M?mic?’ also referring to event 9. These forms, without further modification, simply reintroduce the words of the specified events, each separated by a sin- gle blank. As a special case M!’ refers to the previous command; thus M!’ alone is essentially a redo. To select words from an event we can follow the event specification by a and a designator for the desired words. The words of an input line are numbered from 0, the first (usually command) word being 0, the second word (first argument) being 1, etc. The basic word designators are: # the entire command line typed so far 0 first (command) word n n ’th argument first argument, that is, ‘1’ $ last argument % word matched by (immediately preceding) Is ? search x-y range of words -y abbreviates ‘0 -y ’ * abbreviates **-$’, or nothing if only 1 word in event x* abbreviates ‘x-$’ x - like ‘x * ’ but omitting word *$’ The separating the event specification from the word designator can be omitted if the argument selector begins with a * A ’, *$’, or After the optional word designator can be placed a sequence of modifiers, each preceded by a M’. The following modifiers are defined: h Remove a trailing pathname component, leaving the head, r Remove a trailing ‘.xxx’ component, leaving the root name, e Remove all but the extension ‘.xxx’ part. s/l/rl Substitute r for / t Remove all leading pathname components, leaving the tail. & Repeat the previous substitution. g Apply the change globally, prefixing the above, for example, ‘g&’. p Print the new command but do not execute it. q Quote the substituted words, preventing further substitutions, x Like q, but break into words at blanks, tabs and newlines. Unless preceded by a ‘g’ the modification is applied only to the first modifiable word. With substitutions, it is an error for no word to be applicable. The left hand side of substitutions are not regular expressions in the sense of the editors, but rather strings. Any character may be used as the delimiter in place of 7’; a V quotes the delimiter into the l and r strings. The character *&’ in the right hand side is replaced by the text from the left A ‘V quotes *&’ also. A null l uses the previous string either from a / or from a contextual scan string s in M Is ?’. The trailing delimiter in the substitution may be omitted if a newline follows immediately as may the trailing '?’ in a contextual Sun Release 3.0 Last change: 15 November 1985 59 CSH(l) USER COMMANDS CSH(l) scan. A history reference may be given without an event specification, for example, In this case the refer- ence is to the previous command unless a previous history reference occurred on the same line in which case this form repeats the previous reference. Thus ‘!?foo?“ !$’ gives the first and last arguments from the command matching ‘?foo?’. A special abbreviation of a history reference occurs when the first non-blank character of an input line is a This is equivalent to ‘!:s A ’ providing a convenient shorthand for substitutions on the text of the previ- ous line. Thus ‘ A lb A lib’ fixes the spelling of ‘lib’ in the previous command. Finally, a history substitution may be surrounded with and *}’ if necessary to insulate it from the characters which follow. Thus, after ‘Is -Id 'paul’ we might do ‘!{l}a’ to do ‘Is -Id 'paula’, while ‘!la’ would look for a command starting ‘la’. Quotations with ' and " The quotation of strings by "’ and ‘"’ can be used to prevent all or some of the remaining substitutions. Strings enclosed in "’ are prevented any further interpretation. Strings enclosed in are yet variable and command expanded as described below. In both cases the resulting text becomes (all or part of) a single word; only in one special case (see Com- mand Substitution below) does a ‘"’ quoted string yield parts of more than one word; "’ quoted strings never do. Alias substitution The shell maintains a list of aliases which can be established, displayed and modified by the alias and unalias commands. After a command line is scanned, it is parsed into distinct commands and the first word of each command, left-to-right, is checked to see if it has an alias. If it does, the text which is the alias for that command is reread with the history mechanism available as though that command were the previous input line. The resulting words replace the command and argument list. If no reference is made to the his- tory list, the argument list is left unchanged. Thus if the alias for ‘Is’ is ‘Is -1’ the command ‘Is /usr’ would map to ‘Is -1 /usr’, the argument list here being undisturbed. Similarly if the alias for ‘lookup’ was ‘grep ! A /etc/passwd’, ‘lookup bill’ would map to ‘grep bill /etc/passwd’. If an alias is found, the word transformation of the input text is performed and the aliasing process begins again on the reformed input line. Looping is prevented if the first word of the new text is the same as the old by flagging it to prevent further aliasing. Other loops are detected and cause an error. Note that the mechanism allows aliases to introduce parser metasyntax. Thus we can ‘alias print 'pr \!* | lpr'’ to make a command which pr’ s its arguments to the line printer. Variable substitution The shell maintains a set of variables, each of which has as value a list of zero or more words. Some of these variables are set by the shell or referred to by it For instance, the argv variable is an image of the shell’s argument list, and words of this variable’s value are referred to in special ways. Values of variables may be displayed and changed by using the set and unset commands. Of the variables referred to by the shell a number are toggles; the shell does not care what their value is, only whether they are set or not. For instance, the verbose variable is a toggle which causes command input to be echoed. The setting of this variable results from the -v command line option. Other operations treat variables numerically. The ‘@’ command permits numeric calculations to be per- formed and the result assigned to a variable. Variable values are, however, always represented as (zero or more) strings. For the puiposes of numeric operations, the null string is considered to be zero, and the second and subsequent words of multiword values are ignored. After the input line is aliased and parsed, and before each command is executed, variable substitution is performed keyed by *$’ characters. This expansion can be prevented by preceding the *$’ with a ‘V except within ‘"’s where it always occurs, and within ‘"s where it never occurs. Strings quoted by " ’ are inter- preted later (see Command substitution below) so ‘$’ substitution does not occur there until later, if at all. 60 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) A *$’ is passed unchanged if followed by a blank, tab, or end-of-line. Input/output redirections are recognized before variable expansion, and are variable expanded separately. Otherwise, the command name and entire argument list are expanded together. It is thus possible for the first (command) word to this point to generate more than one word, the first of which becomes the com- mand name, and the rest of which become arguments. Unless enclosed in or given the ‘:q’ modifier the results of variable substitution may eventually be com- mand and filename substituted. Within a variable whose value consists of multiple words expands to a (portion of) a single word, with the words of the variables value separated by blanks. When the ‘:q’ modifier is applied to a substitution the variable expands to multiple words with each word separated by a blank and quoted to prevent later command or filename substitution. The following metasequences are provided for introducing variable values into the shell input Except as noted, it is an error to reference a variable which is not set. $name ${name} Are replaced by the words of the value of variable name, each separated by a blank. Braces insulate name from following characters which would otherwise be part of it. Shell variables have names consisting of up to 20 letters and digits starting with a letter. The underscore character is considered a letter. If name is not a shell variable, but is set in the environment, that value is returned (but : modifiers and the other forms given below are not available in this case). $name[selector] ${name[selector]} May be used to select only some of the words from the value of name. The selector is subjected to “$’ substitution and may consist of a single number or two numbers separated by a The first word of a variables value is numbered ‘1’. If the first number of a range is omitted it defaults to T. If the last member of a range is omitted it defaults to ‘$#name’. The selector selects all words. It is not an error for a range to be empty if the second argument is omitted or in range. $#name ${#name} Gives the number of words in the variable. This is useful for later use in a ‘[selector]’. $0 Substitutes the name of the file from which command input is being read. An error occurs if the name is not known. $number $ {number} Equivalent to ‘$argv[number]\ $* Equivalent to ‘$argv[*]\ The modifiers ‘:h’, ‘:t’, ‘:r’, ‘:q’ and ‘:x’ may be applied to the substitutions above as may ‘:gh’, ‘:gt’ and ‘:gr’. If braces ’}’ appear in the command form then the modifiers must appear within file braces. The current implementation allows only one modifier on each *$’ expansion. The following substitutions may not be modified with modifiers. $?name ${?name} Substitutes the string ‘1’ if name is set, ‘0’ if it is not. $?0 Substitutes ‘1’ if the current input filename is known, ‘O’ if it is not. Sun Release 3.0 Last change: 15 November 1985 61 CSH(l) USER COMMANDS CSH(l) $$ Substitute the (decimal) process number of the (parent) shell. $< Substitutes a line from the standard input, with no further interpretation thereafter. It can be used to read from the keyboard in a shell script. Command and filename substitution The remaining substitutions, command and filename substitution, are applied selectively to the arguments of builtin commands. This means that portions of expressions which are not evaluated are not subjected to these expansions. For commands which are not internal to the shell, the command name is substituted separately from the argument list. This occurs very late, after input-output redirection is performed, and in a child of the main shell. Command substitution Command substitution is indicated by a command enclosed in *' ’. The standard output from such a com- mand (but not the diagnostic output) is normally broken into separate words at blanks, tabs and newlines, with null words being discarded, this text then replacing the original string. Within ‘"’s, only newlines force new words; blanks and tabs are preserved. In any case, the single final newline does not force a new word. Note that it is thus possible for a command substitution to yield only part of a word, even if the command outputs a complete line. Filename substitution If a word contains any of the characters ‘*\ *?’, *[’ or ‘{’ or begins with the character “’, that word is a candidate for filename substitution, also known as ‘globbing’. This word is then regarded as a pattern, and replaced with an alphabetically sorted list of file names which match the pattern. In a list of words specify- ing filename substitution it is an error for no pattern to match an existing file name, but it is not required for each pattern to match. Only the metacharacters T and T imply pattern matching, the characters “’ and ‘{’ being more akin to abbreviations. In matching filenames, the character V at the beginning of a filename or immediately following a 7’, as well as the character 7’ must be matched explicitly. The character matches any string of characters, including the null string. The character *?’ matches any single character. The sequence ‘ [...]’ matches any one of the characters enclosed. Within ‘[...]\ a pair of characters separated by matches any character lexically between the two. The character at the beginning of a filename is used to refer to home directories. Standing alone — that is, — it expands to the invoker’s home directory as reflected in the value of the variable home. When followed by a name consisting of letters, digits and characters the shell searches for a user with that name and substitutes their home directory; thus ‘”ken’ might expand to 7usr/ken’ and ‘”ken/chmach’ to 7usr/ken/chmach’. If the character is followed by a character other than a letter or 7’ or appears not at the beginning of a word, it is left undisturbed. The metanotation ‘a{b,c,d}e’ is a shorthand for ‘abe ace ade’. Left to right order is preserved, with results of matches being sorted separately at a low level to preserve this order. This construct may be nested. Thus l 'source/sl/{oldls,ls}.c’ expands to 7usr/source/sl/oldls.c /usr/source/sl/ls.c’ whether or not these files exist without any chance of error if the home directory for ‘source’ is ‘/usr/ source . Similarly ‘../{memo,*box}’ might expand to ‘../memo ../box ../mbox’. (Note that ‘memo’ was not sorted with the results of matching ‘*box’.) As a special case ‘{\ *}’ and *{}’ are passed undisturbed. Input/output The standard input and standard output of a command may be redirected with the following syntax: < name Open file name (which is first variable, command and filename expanded) as the standard input. 62 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) « word Read the shell input up to a line which is identical to word. Word is not subjected to variable, filename or command substitution, and each input line is compared to word before any substitutions are done on this input line. Unless a quoting ‘V, *'* or ‘ v ’ appears in word variable and com- mand substitution is performed on the intervening lines, allowing ‘V to quote ‘$\ V and Com- mands which are substituted have all blanks, tabs, and newlines preserved, except for the final new- line which is dropped. The resultant text is placed in an anonymous temporary file which is given to the command as standard input. >name >! name >& name >&! name The file name is used as standard output. If the file does not exist, it is created. If the file exists, it is truncated; its previous contents are lost If the variable noclobber is set, the file must not exist or be a character special file (for example, a terminal or ‘/dev/null’) or an error results. This helps prevent accidental destruction of files. In this case the M’ forms can be used and suppress this check. The forms involving *&’ route the diagnostic output into the specified file as well as the standard out- put. Name is expanded in the same way as “<’ input filenames are. » name »& name »! name »&! name Uses file name as standard output like V but places output at the end of the file. If the variable noclobber is set, it is an error for the file not to exist unless one of the T forms is given. Otherwise similar to V. A command receives the environment in which the shell was invoked as modified by the input-output parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, commands run from a file of shell commands have no access to the text of the commands by default; rather they receive the original standard input of the shell. The ‘«’ mechanism should be used to present inline data. This permits shell command scripts to function as components of pipelines and allows the shell to block read its input Note that the default standard input for a command run detached is not modified to be the empty file ‘/dev/null’ ; rather the standard input remains as the original standard input of the shell. If this is a terminal and if the process attempts to read from the terminal, the process blocks and the user is notified (see Jobs above.) Diagnostic output may be directed through a pipe with the standard output. Simply use the form ‘| &’ rather than just ‘|\ Expressions A number of the builtin commands (to be described subsequently) take expressions, in which the operators are similar to those of C, with the same precedence. These expressions appear in the @, exit, if, and while commands. The following operators are available: | | && | "&==!==' !”<=>=<>«» + -*/ % ! " ( ) Here the precedence increases to the right, ‘==’ *!=’ ‘="’ and T\ “<=’ ‘>=’ *<’ and V, *«’ and *»’, V and 7’ and *%’ being, in groups, at the same level. The “==’ ‘!=’ ‘=" and T’ operators compare their arguments as strings; all others operate on numbers. The operators *="’ and T’ are like ‘==’ and *!=’ except that the right hand side is a pattern (containing, for example, ‘*’s, ‘?’s and instances of *[...]’) against which the left hand operand is matched. This reduces the need for use of the switch statement in shell scripts when all that is really needed is pattern matching. Sun Release 3.0 Last change: 15 November 1985 63 CSH(l) USER COMMANDS CSH(l) Strings which begin with ‘0’ are considered octal numbers. Null or missing arguments are considered ‘O’. The result of aU expressions are strings, which represent decimal numbers. It is important to note that no two components of an expression can appear in the same word; except when adjacent to components of expressions which are syntactically significant to the parser (“&’ T *<’ V ‘(’ “)’) they should be sur- rounded by spaces. Variables whose names appear in expressions must have their names preceded by a dollar ( $ ) sign, for example: @ grab = $grab + 2 Also available in expressions as primitive operands are command executions enclosed in ‘{’ and *}’ and file enquiries of the form *-/ name’ where / is one of: r read access w write access x execute access e existence o ownership z zero size f plain file d directory The specified name is command and filename expanded and then tested to see if it has the specified rela- tionship to the real user. If the file does not exist or is inaccessible then all enquiries return false, that is, ‘O’. Command executions succeed, returning true, that is, ‘1’, if the command exits with status 0, other- wise they fail, returning false, that is, ‘O’. If more detailed status information is required, the command should be executed outside of an expression and the variable status examined. Control flow The shell contains a number of commands which can be used to regulate the flow of control in command files (shell scripts) and (in limited but useful ways) from terminal input These commands all operate by forcing the shell to reread or skip in its input and, due to the implementation, restrict the placement of some of the commands. The foreach, switch, and while statements, as well as the if-then-else form of the if statement require that the major keywords appear in a single simple command on an input line as shown below. If the shell’s input is not seekable, the shell buffers up input whenever a loop is being read and performs seeks in this internal buffer to accomplish the rereading implied by the loop. (To the extent that this allows, backward goto’s will succeed on non-seekable inputs.) Builtin commands Builtin commands are executed within the shell. If a builtin command occurs as any component of a pipe- line except the last, it is executed in a subshell. alias alias name alias name wordlist The first form prints all aliases. The second form prints the alias for name. The final form assigns the specified wordlist as the alias of name ; wordlist is command and filename substituted. Name is not allowed to be alias or unalias. Putting single quote signs (apostrophes) around wordlist and plac- ing a \ character in front of any *!’ signs in wordlist often solves any obscure problems with aliases. alloc Shows the amount of dynamic core in use, broken down into used and free core, and address of the last location in the heap. With an argument shows each used and free block on the internal dynamic memory chain indicating its address, size, and whether it is used or free. This is a debugging com- mand and may not work in production versions of the shell; it requires a modified version of the sys- tem memory allocator. 64 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) bg bg %job ... Puts the current or specified jobs into the background, continuing them if they were stopped. break Resumes execution after the end of the nearest enclosing foreach or while. The remaining com- mands on the current line are executed. Multi-level breaks are thus possible by writing them all on one line. breaksw Breaks from a switch, resuming after the endsw. case label: A label in a switch statement as discussed below, cd cd name chdir cfadir name Change the shell’s working directory to directory name. If no argument is given, change to the home directory of the user. If name is not found as a subdirectory of the current directory (and does not begin with 7\ ‘J’ or each component of the variable cdpath is checked to see if it has a subdirectory name. Finally, if all else fails but name is a shell variable whose value begins with 7’, this is tried to see if it is a directory. continue Continue execution of the nearest enclosing while or foreach. The rest of the commands on the current line are executed. default: Labels the default case in a switch statement The default should come after all case labels. dirs dirs -1 Prints the directory stack; the top of the stack is at the left, the first directory in the stack being the current directory. The second form produces an unabbreviated printout; use of the notation is suppressed. echo wordlist echo -n wordlist The specified words are written to the shell’s standard output, separated by spaces, and terminated with a newline unless the -n option is specified. else end endif endsw See the description of the foreach, if, switch, and while statements below, eval arg ... (As in sh.) The arguments are read as input to the shell and the resulting command(s) executed. This is usually used to execute commands generated as the result of command or variable substitu- tion, since parsing occurs before these substitutions. See tset{\) for an example of using eval. exec command The specified command is executed in place of the current shell. Sun Release 3.0 Last change: 15 November 1985 65 CSH(l) USER COMMANDS CSH(l) exit exit(expr) The shell exits either with the value of the status variable (first form) or with the value of the specified expr (second form). fg fg %job ... Brings the current or specified jobs into the foreground, continuing them if they were stopped, foreach name (wordlist) end The variable name is successively set to each member of wordlist and the sequence of commands between this command and the matching end are executed. (Both foreach and end must appear alone on separate lines.) The builtin command continue may be used to continue the loop prematurely and the builtin com- mand break to terminate it prematurely. When this command is read from the terminal, the loop is read up once prompting with *?’ before any statements in the loop are executed. If you make a mis- take typing in a loop at the terminal you can rub it out glob wordlist Like echo but no ‘V escapes are recognized and words are delimited by null characters in the output. Useful for programs which wish to use the shell to filename expand a list of words. goto word The specified word is filename and command expanded to yield a string of the form ‘label’. The shell rewinds its input as much as possible and searches for a line of the form ‘label:’ possibly pre- ceded by blanks or tabs. Execution continues after the specified line. hashstat Print a statistics line indicating how effective the internal hash table has been at locating commands (and avoiding exec’s). An exec is attempted for each component of the path where the hash function indicates a possible hit, and in each component which does not begin with a 7’. history history n history -r n history -h n Displays the history event list; if n is given, display only the n most recent events. The -r option reverses the order of printout to be most recent first rather than oldest first The -h option means display the history list without leading numbers. This is used to produce files suitable for sourcing using the -h option to source. if (expr) command If the specified expression evaluates true, the single command with arguments is executed. Variable substitution on command happens early, at the same time it does for the rest of the if command. Command must be a simple command, not a pipeline, a command list, or a parenthesized command list. Input/output redirection occurs even if expr is false, when command is not executed (this is a bug). if (expr) then else if (expf2) then else 66 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) endif If the specified expr is true, the commands to the first else are executed; else if expr2 is true, the commands to the second else are executed, etc. Any number of else-if pairs are possible; only one endif is needed. The else part is likewise optional. (The words else and endif must appear at the beginning of input lines; the i/ must appear alone on its input line or after an else.) jobs jobs -1 Lists the active jobs; given the -1 options lists process id’s in addition to the normal information, kill %job kill -sig %job ... kill pid kill -sig pid ... kill -1 Sends either the TERM (terminate) signal or the specified signal to the specified jobs or processes. Signals are either given by number or by names (as given in l usrlincludel signal. h, stripped of the prefix “SIG”). The signal names are listed by “kill -1”. There is no default, saying just ‘kill’ does not send a signal to the current job. If the signal being sent is TERM (terminate) or HUP (hangup), then the job or process is sent a CONT (continue) signal as well. limit limit resource limit resource maximum-use Limits the consumption by the current process and each process it creates to not individually exceed maximum-use on the specified resource. If no maximum-use is given, the current limit is printed; if no resource is given, all limitations are given. Resources controllable currently include cputime (the maximum number of cpu-seconds to be used by each process), filesize (the largest single file which can be created), datasize (the maximum growth of the data+stack region via sbrk{ 2) beyond the end of the program text), stacksize (the max- imum size of the automatically-extended stack region), and coredumpsize (the size of the largest core dump that will be created). The maximum-use may be given as a (floating point or integer) number followed by a scale factor. For all limits other than cputime the default scale is ‘k’ or ‘kilobytes’ (1024 bytes); a scale factor of ‘m’ or ‘megabytes’ may also be used. For cputime the default scaling is ‘seconds’, while ‘m’ for minutes or ‘h’ for hours, or a time of the form ‘mm:ss’ giving minutes and seconds may be used. For both resource names and scale factors, unambiguous prefixes of the names suffice. login Terminate a login shell, replacing it with an instance of /bin/login. This is one way to log off, included for compatibility with sh . logout Terminate a login shell. Especially useful if ignoreeof is set. nice nice +number nice command nice +number command The first form sets the nice for this shell to 4. The second form sets the nice to the given number. The final two forms run command at priority 4 and number respectively. The super-user may specify negative niceness by using ‘nice -number ...’. Command is always executed in a sub-shell, and the restrictions placed on commands in simple if statements apply. nohup Sun Release 3.0 Last change: 15 November 1985 67 CSH ( 1 ) USER COMMANDS CSH ( 1 ) nohup command The first form can be used in shell scripts to cause hangups to be ignored for the remainder of the script. The second form runs the specified command with hangups ignored. All processes detached with *&’ are effectively nohup’ ed. notify notify %job ... Notify the user asynchronously when the status of the current or specified jobs changes; normally notification is presented before a prompt. This is automatic if the shell variable notify is set onintr onintr - onintr label Control the action of the shell on interrupts. The first form restores the default action of the shell on interrupts (terminates shell scripts and returns to the terminal command input level). The second form ‘onintr ignores all interrupts. The final form makes the shell execute a ‘goto label’ when an interrupt is received or a child process terminates because it was interrupted. In any case, if the shell is running detached and interrupts are being ignored, all forms of onintr have no meaning and interrupts continue to be ignored by the shell and all invoked commands. popd popd +n Pops the directory stack, returning to the new top directory. With an argument ‘+n’ discards the nth entry in the stack. The elements of the directory stack are numbered from 0 starting at the top. pushd pushd name pushd +n With no arguments, pushd exchanges the top two elements of the directory stack. Given a name argument, pushd changes to the new directory (as in cd) and pushes the old current working directory (as in cwd) onto the directory stack. With a numeric argument, rotates the nth argument of the direc- tory stack around to be the top element and changes to it The members of the directory stack are numbered from the top starting at 0. rehash Recompute the internal hash table of the contents of the directories in the path variable. This is needed if new commands are added to directories in the path while you are logged in. This should only be necessary if you add commands to one of your own directories, or if a systems programmer changes the contents of one of the system directories. repeat count command The specified command which is subject to the same restrictions as the command in the one line if statement above, is executed count times. I/O redirections occur exactly once, even if count is 0. set set name set name=word set name [index] = word set name=(wordlist) The first form of the command shows the value of all shell variables. Variables which have other than a single word as value print as a parenthesized word list. The second form sets name to the null string. The third form sets name to the single word. The fourth form sets the index’ th component of name to word; this component must already exist The final form sets name to the list of words in wordlist. In all cases the value is command and filename expanded. These arguments may be repeated to set multiple values in a single set command. Note however, that variable expansion happens for all arguments before any setting occurs. 68 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) setenv name value Sets the value of environment variable name to be value, a single string. The most commonly used environment variables, USER, TERM, and PATH, are automatically imported to and exported from the csh variables user, term, and path; there is no need to use setenv for these. shift shift variable The members of argv are shifted to the left, discarding argvfl ]. It is an error for argv not to be set or to have less than one word as value. The second form performs the same function on the specified variable. source name source -h name The shell reads commands from name. Source commands may be nested; if they are nested too dee- ply the shell may run out of file descriptors. An error in a source at any level terminates all nested source commands. Normally, input during source commands is not placed on the history list; the -h option places the commands in the history list without being executed. stop stop %job ... Stops the current or specified job which is executing in the background, suspend Stops the shell in its tracks, much as if it had been sent a stop signal with “Z. This is most often used to stop shells started by su. switch (string) case strl: breaksw default: breaksw endsw Each case label is successively matched, against the specified string which is first command and filename expanded. The file metacharacters **’, “?’ and “[...]’ may be used in the case labels, which are variable expanded. If none of the labels match before a ‘default’ label is found, execution begins after the default label. Each case label and the default label must appear at the beginning of a line. The command breaksw continues execution after the endsw. Otherwise control may fall through case labels and default labels as in C. If no label matches and there is no default, execution contin- ues after the endsw. time time command With no argument, a summary of time used by this shell and its children is printed. If arguments are given the specified simple command is timed and a time summary as described under the time vari- able is printed. If necessary, an extra shell is created to print the time statistic when the command completes. umask umask value The file creation mask is displayed (first form) or set to the specified value (second form). The mask is given in octal. Common values for the mask are 002 giving all access to the group and read and execute access to others or 022 giving all access except no write access for users in the group or oth- ers. Sun Release 3.0 Last change: 15 November 1985 69 CSH(l) USER COMMANDS CSH(l) unalias pattern All aliases whose names match the specified pattern are discarded. Thus all aliases are removed by ‘unalias It is not an error for nothing to be unaliased. unhash Use of the internal hash table to speed location of executed programs is disabled. unlimit resource unlimit Removes the limitation on resource. If no resource is specified, all resource limitations are removed. unset pattern All variables whose names match the specified pattern are removed. Thus all variables are removed by ‘unset this has noticeably distasteful side-effects. It is not an error for nothing to be unset. unsetenv pattern Removes all variables whose name match the specified pattern from the environment. See also the setenv command above and printenv( 1). wait All background jobs are waited for. It the shell is interactive, an interrupt can disrupt the wait, at which time the shell prints names and job numbers of all jobs known to be outstanding. while (expr) end While the specified expression evaluates non-zero, the commands between the while and the match- ing end are evaluated. Break and continue may be used to terminate or continue the loop prema- turely. (The while and end must appear alone on their input lines.) Prompting occurs here the first time through the loop as for the foreach statement if the source of input is a terminal. %job Brings the specified job into the foreground. %job & Continues the specified job in the background. @ @ name = expr @ name[index] = expr The first form prints the values of all the shell variables. The second form sets the specified name to the value of expr. If the expression contains *<’, *>’, or T then at least this part of the expres- sion must be placed within ‘(’ *)’. The third form assigns the value of expr to the index’ th argument of name. Both name and its index' th component must already exist. The operators ‘*=’, *+=’, etc are available as in C. The space separating the name from the assign- ment operator is optional. Spaces are, however, mandatory in separating components of expr which would otherwise be single words. Special postfix *++’ and ‘ — ’ operators increment and decrement name respectively, that is, ‘@ i++’. Note that there must be a space after the ‘@’ sign. Pre-defined and environment variables The following variables have special meaning to the shell. Of these, argv, cwd, home, path, prompt, shell and status are always set by the shell. Except for cwd and status this setting occurs only at initialization; these variables will not then be modified unless this is done explicitly by the user. 70 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) This shell copies the environment variable USER into the variable user, TERM into term, and HOME into home, and copies these back into the environment whenever the normal shell variables are reset The environment variable PATH is similarly handled; it is only necessary to worry about its setting in the file .cshrc, as inferior csh processes will import the definition of path from the environment and re-export it if you then change it. It could be set once in the .login except that commands through the network would not see the definition. argv cdpath cwd echo hardpaths histchars history home ignoreeof mail noclobber noglob nonomatch notify Set to the arguments to the shell. Positional parameters are substituted from this vari- able: ‘$1’ is replaced by ‘$argv[l]’ ( etc. Gives a list of alternate directories searched to find subdirectories in chdir commands. The full pathname of the current directory. If the variable hardpaths is set, cwd is resolved to contain a pathname with no embedded symbolic link components. Set when the -x command line option is given. Echoes each command and its argu- ments just before execution. For non-builtin commands all expansions occur before echoing. Builtin commands are echoed before command and filename substitution, since these substitutions are then done selectively. If set, the paths contained in the cwd variable and printed by the cd, chdir, dirs, popd, and pushd commands are resolved to contain no symbolic link components. Can be given a string value to change the characters used in history substitution. The first character of its value is used as the history substitution character, replacing the default character !. The second character of its value replaces the character t in quick substitutions. Can be given a numeric value to control the size of the history list. Any command which has been referenced in this many events will not be discarded. If you use an overly-large value for history, the shell may run out of memory. The last executed com- mand is always saved on the history list. The home directory of the invoker, initialized from the environment. The filename expansion of refers to this variable. If set, the shell ignores end-of-file signals from terminals. This prevents shells from being accidentally killed by control-D’s. The files where the shell checks for mail. This is done after each command completion which will result in a prompt, if a specified interval has elapsed. The shell says ‘You have new mail’ if the file exists with an access time not greater than its modify time. If the first word of the value of mail is numeric it specifies a different mail checking interval, in seconds, than the default, which is 5 minutes. If multiple mail files are specified, the shell says ‘New mail in name ’ when there is mail in the file name. As described in the section on Input/output, restrictions are placed on output redirection to insure that files are not accidentally destroyed, and that *»’ redirections refer to existing files. If set, filename expansion is inhibited. This is most useful in shell scripts which are not dealing with filenames, or after a list of filenames has been obtained and further expan- sions are not desirable. If set, it is not an error for a filename expansion to not match any existing files; rather the primitive pattern is returned. It is still an error for the primitive pattern to be malformed, that is, ‘echo [’ still gives an error. If set, the shell notifies asynchronously of job completions. The default is to rather present job completions just before printing a prompt. Sun Release 3.0 Last change: 15 November 1985 71 CSH(l) USER COMMANDS CSH(l) path prompt savehist shell status time Each word of the path variable specifies a directory in which commands are to he sought for execution. A null word specifies the current directory. If there is no path variable, only full path names will execute. The usual search path is V, ‘/bin’ and ‘/usr/bin’, but this may vary from system to system. For the super-user the default search path is ‘/etc’, ‘/bin’ and ‘/usr/bin’. A shell which is given neither the -c nor the -t option will nor- mally hash the contents of the directories in the path variable after reading .cshrc, and each time the path variable is reset. If new commands are added to these directories while the shell is active, it may be necessary to give the rehash or the commands may not be found. The string which is printed before each command is read from an interactive terminal input. Subshells are non-interactive, and therefore their prompt variable is unset For this reason, and because subshells read the .cshrc file upon being spawned, if is some- times convenient to collect aliases and other commands which do not need to be exe- cuted by subshells at the end of the ‘.cshrc’ file, and to precede them by the test: if ($?prompt == 0) then exit endif If a “!’ appears in the prompt string it is replaced by the current event number unless a preceding ‘\’ is given. Default is or ‘# ’ for the super-user. is given a numeric value to control the number of entries of the history list that are saved in "/.history when the user logs out. Any command which has been referenced in this many events will be saved. During start up the shell sources '/.history into the history list enabling history to be saved across logins. Overly-large values of savehist will slow down the shell during start up. The file in which the shell resides. This is used in forking shells to interpret files which have execute bits set, but which are not executable by the system. (See the description of Non-builtin Command Execution below.) Initialized to the (system-dependent) home of the shell. The status returned by the last command. If it terminated abnormally, then 0200 is added to the status. Builtin commands which fail return exit status ‘T, all other builtin commands set status ‘O’. Controls automatic timing of commands. The time variable can be supplied with one or two values, such as ‘set time=3’ or ‘set time=(3 "%E %P")’. The first value is a number — n for instance. The shell displays a resource-usage summary for any command run- ning for more than n CPU seconds. The second value is optional and is a character string which determines which resources the user wishes displayed. The character string can be any string of text with embedded control key-letters in it. A control key-letter is a percent sign ( % ) followed by a single upper-case letter. Unrecognized key-letters are simply printed. The control key-letters are: D Average amount of unshared data space used in Kilobytes. E Elapsed (wallclock) time for the command. F Page faults. I Number of block input operations. K Average amount of unshared stack space used in Kilobytes. M Maximum real memory used during execution of the process. O Number of block output operations . P Total CPU time — U (user) plus S (system) — as a percentage of E (elapsed) time. S Number of seconds of CPU time consumed by the kernel on behalf of the user’s process. U Number of seconds of CPU time devoted to the user’s process. 72 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) W Number of swaps. X Average amount of shared memory used in Kilobytes. The default resource-usage summary is a line of the form: uuu.u u sss.s s ee:ee pp % xxx +dddk iii +000 iojffpf+ww w where uuu.u is the user time (U), sss.s is the system time (S), ee :ee is the elapsed time (E), pp is the percentage of CPU time versus elapsed time (P), xxt is the average shared memory in Kilobytes (X), ddd is the average unshared data space in Kilobytes (D), iii and 000 are the number of block input and output operations respectively (I and the number of page faults (F), and ww is the number of swaps (W). verbose Set by the -v command line option, displays the words of each command after history substitution. Non-builtin command execution When a command to be executed is found to not be a builtin command the shell attempts to execute the command via execve (2). Each word in the variable path names a directory from which the shell will attempt to execute the command. If it is given neither a -c nor a -t option, the shell hashes the names in these directories into an internal table so that it will only try an exec in a directory if there is a possibility that the command resides there. This greatly speeds command location when a large number of directories are present in the search path. If this mechanism has been turned off (via unhash), or if the shell was given a -c or -t argument, and in any case for each directory component of path which does not begin with a 7’, the shell concatenates with the given command name to form a path name of a file which it then attempts to execute. Parenthesized commands are always executed in a subshell. Thus ‘(cd ; pwd) ; pwd’ prints the home direc- tory; leaving you where you were (printing this after the home directory), while ‘cd ; pwd’ leaves you in the home directory. Parenthesized commands are most often used to prevent chdir from affecting the current shell. If the file has execute permissions but is not an executable binary to the system, it is assumed to be a file containing shell commands and a new shell is spawned to read it If there is an alias for shell then the words of the alias are prepended to the argument list to form the shell command. The first word of the alias should be the full path name of the shell (for example, ‘$shell’). Note that this is a special, late occurring, case of alias substitution, and only allows words to be prepended to the argument list without modification. Argument list processing If argument 0 to the shell is ’ then this is a login shell. The flag arguments are interpreted as follows: -c Commands are read from the (single) following argument which must be present. Any remaining arguments are placed in argv. -e The shell exits if any invoked command terminates abnormally or yields a non-zero exit status. -f The shell will start faster, because it will neither search for nor execute commands from the file ‘.cshrc’ in the invoker’s home directory. -i The shell is interactive and prompts for its top-level input, even if it appears to not be a terminal. Shells are interactive without this option if their inputs and outputs are terminals. — n Commands are parsed, but not executed. This may aid in syntactic checking of shell scripts. -s Command input is taken from the standard input. -t A single line of input is read and executed. A V may be used to escape the newline at the end of this line and continue onto another line. -v Sets the verbose variable, so that command input is echoed after history substitution. Sun Release 3.0 Last change: 15 November 1985 73 CSH(l) USER COMMANDS CSH(l) -x Sets the echo variable, so that commands are echoed immediately before execution. -V Sets the verbose variable even before ‘.cshrc’ is executed. -X Is to -x as -V is to -v. After processing of flag arguments if arguments remain but none of the -c, -i, -s, or -t options was given the first argument is taken as the name of a file of commands to be executed. The shell opens this file, and saves its name for possible resubstitution by ‘$0’. Since many systems use either the standard version 6 or version 7 shells whose shell scripts are not compatible with this shell, the shell will execute such a ‘stan- dard’ shell if the first character of a script is not a “#’, that is, if the script does not start with a comment. Remaining arguments initialize the variable argv. Signal handling The shell normally ignores quit signals. Jobs running detached (either by *&’ or the bg or %... & com- mands) are immune to signals generated from the keyboard, including hangups. Other signals have the values which the shell inherited from its parent. The shell’s handling of interrupts and terminate signals in shell scripts can be controlled by onintr. Login shells catch the terminate signal; otherwise this signal is passed on to children from the state in the shell’s parent In no case are interrupts allowed when a login shell is reading the file ‘.logout’. FILES '/.cshrc '/.login '/.logout "/.history /bin/sh /tmp/sh* /etc/passwd LIMITATIONS Words can be no longer than 1024 characters. The system limits argument lists to 10240 characters. The number of arguments to a command which involves filename expansion is limited to 1/6’ th the number of characters allowed in an argument list. Command substitutions may substitute no more characters than are allowed in an argument list. To detect looping, the shell restricts the number of alias substitutions on a sin- gle line to 20. SEE ALSO sh(l), access(2), execve(2), fork(2), killpg(2), pipe(2), umask(2), getrlimit(2), setrlimit(2), sigvec(2), wait(2), tty(4), a.out(5), environ(5) Using the C-Shell in the Beginner’ s Guide to the Sun Workstation BUGS When a command is restarted from a stop, the shell prints the directory it started in if this is different from the current directory; this can be misleading (that is, wrong) as the job may have changed directories inter- nally. Shell builtin functions are not stoppable/restartable. Command sequences of the form ‘a ; b ; c’ are also not handled gracefully when stopping is attempted. If you suspend ‘b’, the shell will then immediately execute ‘c’. This is especially noticeable if this expansion results from an alias. It suffices to place the sequence of commands in ()’s to force it to a subshell, that is, ‘( a ; b ; c )’. Control over tty output after processes are started is primitive; use the Sun Window system if you need better output control. Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be pro- vided rather than aliases. Commands within loops, prompted for by *?’, are not placed in the history list. Control structures should be parsed rather than being recognized as built-in commands. This would allow control commands to be placed anywhere, to be combined with T, and to be used with ‘&’ and *;’ metasyntax. Read at beginning of execution by each shell. Read by login shell, after ‘.cshrc’ at login. Read by login shell, at logout. Saved history for use at next login. Standard shell, for shell scripts not starting with a ‘#’. Temporary file for ‘«’. Source of home directories for "name’. 74 Last change: 15 November 1985 Sun Release 3.0 CSH(l) USER COMMANDS CSH(l) It should be possible to use the *:’ modifiers on the output of command substitutions. There are two prob- lems with *:’ modifier usage on *$’ substitutions: not all of the modifiers are available; only one modifier per variable substitution is allowed. Quoting conventions are contradictory and confusing. Symbolic links fool the shell. In particular, ‘cd ..’ doesn’t work properly once you’ve crossed through a symbolic link. set path should remove duplicate pathnames from the pathname list. These often occur because a shell script or a .cshrc file does something like set path=(/usr/local /usr/hosts $path) to ensure that the named directories are in the pathname list. There is no way to direct error output to one place and standard output to another place, except by invoking a sub-shell as follows: tutorial% ( command. > outfile ) >& errorfile Sun Release 3.0 Last change: 15 November 1985 75 CTAGS(l) USER COMMANDS CTAGS(l) NAME ctags - create a tags file SYNOPSIS ctags [ -BFatuwvx ] file . . . DESCRIPTION Ctags makes a tags file for ex(l) from the specified C, Pascal and FORTRAN sources. A tags file gives the locations of specified objects (in this case functions and typedefs) in a group of files. Each line of the tags file contains the object name, the file in which it is defined, and an address specification for the object definition. Functions are searched with a pattern, typedefs with a line number. Specifiers are given in separate fields on the line, separated by blanks or tabs. Using the tags file, ex can quickly find these objects definitions. Files whose name ends in .c or .h are assumed to be C source files and are searched for C routine and macro definitions. Others are first examined to see if they contain any Pascal or FORTRAN routine definitions; if not, they are processed again looking for C definitions. The tag main is treated specially in C programs. The tag formed is created by prepending M to the name of the file, with a trailing .c removed, if any, and leading pathname components also removed. This makes use of ctags practical in directories with more than one program. OPTIONS —x -F -B -a -t -w -u FILES tags SEE ALSO ex(l), vi(l) BUGS Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very sim- pleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures in dif- ferent blocks with the same name you lose. Does not know about #ifdefs. produce a list of object names, the line number and file name on which each is defined, as well as the text of that line and prints this on the standard output. This is a simple index which can be printed out as an off-line readable function index. use forward searching patterns (/.../) (default), use backward searching patterns (?...?). append to tags file, create tags for typedefs. suppress warning diagnostics. update the specified files in tags, that is, all references to them are deleted, and the new values are appended to the file. Beware: this option is implemented in a way which is rather slow; it is usu- ally faster to simply rebuild the tags file. output tags file 76 Last change: 6 March 1984 Sun Release 3.0 DATE ( 1 ) USER COMMANDS DATE ( 1 ) NAME date - display or set the date SYNOPSIS date [ -u ] [ yymmddhhmm [ .ss ] ] DESCRIPTION Date displays the current date and time when used without an argument. Only the super-user may set the date, yy is the last two digits of the year; the first mm is the month number; dd is the day number in the month; hh is the hour number (24 hour system); the second mm is the minute number; .ss (optional) specifies seconds. The year, month and day may be omitted; the current values are supplied as defaults. OPTIONS -u Display the date in GMT (universal time). The system operates in GMT; date normally takes care of the conversion to and from local standard and daylight time, -u may also be used to set GMT time. EXAMPLE date 10080045 sets the date to Oct 8, 12:45 AM. FILES /usr/adm/wtmp to record time-setting SEE ALSO utmp(5) DIAGNOSTICS ‘Failed to set date: Not owner’ if you try to change the date but are not the super-user. Sun Release 3.0 Last change: 16 July 1983 77 DBX(l) USER COMMANDS DBX(l) NAME dbx - source-level debugger for C, FORTRAN 77 and Pascal programs SYNOPSIS dbx [ -r ] [ -i ] [ -I dir ] [ -k ] [ -kbd ] [ objfile [ corefile ] ] DESCRIPTION dbx is a utility for source-level debugging and execution of programs written in C, FORTRAN 77 and Pascal. It accepts the same commands as dbxtool( 1), using a standard terminal interface rather than the window system. Objfile is an object file produced by cc(l),/77(l) or pc{ 1) (or a combination of them) with the appropriate flag (— g) specified to produce symbol information in the object file. IMPORTANT: every stage of the com- pilation process, including the linking phase, must include the — g option. If no objfile is specified, use the debug command to specify the program to be debugged. The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it. These files are available for perusal while using the debugger. If a file named core exists in the current directory or a corefile is specified, dbx can be used to examine the state of the program when it faulted. Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory. OPTIONS -r Executes objfile immediately. Parameters follow the object file name (redirection is handled prop- erly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for ter- mination and waits for user response. Dbx reads from ! dev! tty when -r is specified and standard input is a file or pipe. -i Forces dbx to act as though standard input is a terminal or terminal emulator. -I dir Adds dir to the list of directories that are searched when looking for a source file. Normally dbx looks for source files in the current directory and in the directory where objfile is located. The directory search path can also be set with the use command. -k Kernel debugging. -kbd Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if the program you are debugging uses up/down encoding. USAGE Refer to Dbx in Program Debugging Tools for the Sun FILES a.out default object file core default core file '/.dbxinit initial commands SEE ALSO cc(l) C compiler f77(l) FORTRAN compiler pc(l) Pascal compiler Program Debugging Tools for the Sun BUGS Dbx does not correctly handle C variables that are local to compound statements. When printing these variables it often gives incorrect results. 78 Last change: 21 December 1985 Sun Release 3.0 DBX(l) USER COMMANDS DBX(l) Dbx does not handle FORTRAN entry points well — it treats them as if they were independent routines. Dbx does not handle assigning to FORTRAN complex types correctly (see the assign/set command). Some operations behave differently in dbx than in C. Dbx has two division operators — / always yields a floating-point result and div always yields an integral result. - An array or function name does not signify the address of the array or function in dbx. An array name signifies the entire array, and a function name signifies a call to the function with no argu- ments. The address of an array can be obtained by taking the address of its first element, and the address of a function can be obtained by taking the address of its name. Casts do not work with FORTRAN 77 or Pascal. Executable code incorporated into a source file using an #include preprocessor directive confuses dbx . Using both the — R and the — g compiler options when compiling programs causes dbx to access incorrect addresses for variables which -R stores in the text segment. dbx is confused by the output of program generators such as yacc and lex. Sun Release 3.0 Last change: 21 December 1985 79 DBXTOOL ( 1 ) USER COMMANDS DBXTOOL ( 1 ) NAME dbxtool - window- and mouse-based source-level debugger for C, FORTRAN 77, and Pascal programs SYNOPSIS dbxtool [ -i ] [ -I dir ] [ -k ] [ -kbd ] [ objfile [ corefile ] ] DESCRIPTION dbxtool, a source-level debugger for C, Pascal and FORTRAN 77 programs, is a standard tool that runs within the SunView environment. It accepts the same commands as dbx, but provides a more convenient user interface. You can use the mouse to set breakpoints, examine the values of variables, control execution, peruse source files, and so on. dbxtool has separate subwindows for viewing source code, entering commands and other uses. objfile is an object file produced by cc(l),/77(l), or pc{ 1) (or a combination of them) with the appropriate flag (-g) specified to produce symbol information in the object file. IMPORTANT: every stage of the com- pilation process, including the linking phase, must include the -g option. If no objfile is specified, you can use the debug command to specify the program to be debugged. The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it. These files are avail- able for perusal while using the debugger. If a file named core exists in the current directory or a corefile is specified, dbxtool can be used to examine the state of the program when it faulted. Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory. OPTIONS -i Force dbxtool to act as though standard input were a terminal. -I dir Add dir to the list of directories that are searched when looking for a source file. Normally dbxtool looks for source files in the current directory and then in the directory where objfile is located. The directory search path can also be set with the use command. Multiple -I options may be given. -k Kernel debugging. -kbd Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if you are debugging a program that uses up/down encoding. USAGE Refer to Program Debugging Tools for the Sun FILES a.out default object file core default core file SEE ALSO dbx(l), cc(l) C compiler f77(l) FORTRAN compiler pc(l) Pascal compiler Programm Debugging Tools for the Sun Workstation The SunView Application Programmer’ s Guide 80 Last change: 21 December 1985 Sun Release 3.0 DBXTOOL ( 1 ) USER COMMANDS DBXTOOL ( 1 ) BUGS The bugs for dbx(l) apply to dbxtool as well. The interaction between scrolling in the source subwindow and dbx’s regular expression search commands is wrong. Scrolling should affect where the next search begins, but it does not. Sun Release 3.0 Last change: 21 December 1985 81 DC( 1 ) USER COMMANDS DC(1) NAME dc - desk calculator SYNOPSIS dc [ file ] DESCRIPTION Dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may specify an input base, output base, and a number of fractional digits to be maintained. The overall structure of dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its end, then from the standard input. The following constructions are recognized: number The value of the number is pushed on the stack. A number is an unbroken string of the digits 0-9. It may be preceded by an underscore _ to input a negative number. Numbers may contain decimal points. + -/*%* The top two values on the stack are added (+), subtracted (-), multiplied (*), divided (/), remain- dered (%), or exponentiated Q. The two entries are popped off the stack; the result is pushed on the stack in their place. Any fractional part of an exponent is ignored. sx The top of the stack is popped and stored into a register named x, where x may be any character. If the s is capitalized, x is treated as a stack and the value is pushed on it. lx The value in register x is pushed on the stack. The register x is not altered. All registers start with zero value. If the 1 is capitalized, register x is treated as a stack and its top value is popped onto the main stack. d The top value on the stack is duplicated. p The top value on the stack is printed. The top value remains unchanged. P interprets the top of the stack as an ascii string, removes it, and prints it f All values on the stack and in registers are printed. q exits the program. If executing a string, the recursion level is popped by two. If q is capitalized, the top value on the stack is popped and the string execution level is popped by that value. x treats the top element of the stack as a character string and executes it as a string of dc commands. X replaces the number on the top of the stack with its scale factor. [ ... ] puts the bracketed ascii string onto the top of the stack. x =x The top two elements of the stack are popped and compared. Register x is executed if they obey the stated relation. v replaces the top element on the stack by its square root. Any existing fractional part of the argu- ment is taken into account, but otherwise the scale factor is ignored. ! interprets the rest of the line as a UNIX command. c All values on the stack are popped. i The top value on the stack is popped and used as the number radix for further input. I pushes the input base on the top of the stack. o The top value on the stack is popped and used as the number radix for further output. O pushes the output base on the top of the stack. k the top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate number of places are printed on output, and maintained during multiplication, division, and exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all 82 Last change: 2 June 1983 Sun Release 3.0 DC( 1 ) USER COMMANDS DC(1) are changed together. z The stack level is pushed onto the stack. Z replaces the number on the top of the stack with its length. ? A line of input is taken from the input source (usually the terminal) and executed. ; : are used by be for array operations. EXAMPLE Print the first ten values of n! [lal+dsa*plalO>y]sy Osal lyx SEE ALSO bc(l), which is a preprocessor for dc providing infix notation and a C-like syntax which implements func- tions and reasonable control structures for programs. DIAGNOSTICS ‘x is unimplemented’ where x is an octal number. ‘stack empty’ for not enough elements on the stack to do what was asked. ‘Out of space’ when the free list is exhausted (too many digits). ‘Out of headers’ for too many numbers being kept around. ‘Out of pushdown’ for too many items on the stack. ‘Nesting Depth’ for too many levels of nested execution. Sun Release 3.0 Last change: 2 June 1983 83 DD( 1 ) USER COMMANDS DD(1) NAME dd - convert and copy a file SYNOPSIS dd [option= value] . . . DESCRIPTION dd copies a specified input file to a specified output with possible conversions. The standard input and out- put are used by default. The input and output block size may be specified to take advantage of raw physi- cal I/O. OPTION if =name of-name ibs=n obs=n bs=n cbs=n VALUES input file is taken from name ; standard input is default. output file is taken from name ; standard output is default Note that dd creates an expli- cit output file; therefore the seek option is usually useless with explicit output except in special cases such as using magnetic tape or raw disk files. input block size n bytes (default 512). output block size n bytes (default 512). set both input and output block size, superseding ibs and obs; also, if no conversion is specified, it is particularly efficient since no copy need be done conversion buffer size skip=n files=n seek=/t count=n conv=ascii ebcdic ibm block unblock lease ucase swab noerror sync skip n input records before starting copy copy n input files before terminating (makes sense only when input is a magtape or simi- lar device). seek n records from beginning of output file before copying. This option generally only works with magnetic tapes and raw disk files and is otherwise usually useless if the explicit output file was named with the of option. copy only n input records convert EBCDIC to ASCII convert ASCII to EBCDIC slightly different map of ASCII to EBCDIC convert variable length records to fixed length convert fixed length records to variable length map alphabetics to lower case map alphabetics to upper case swap every pair of bytes do not stop processing on an error pad every input record to ibs several comma-separated conversions Where sizes are specified, a number of bytes is expected. A number may end with k (kilobytes) to specify multiplication by 1024, b (blocks of 512 bytes) to specify multiplication by 512, or w (words) to specify multiplication by 4; a pair of numbers may be separated by x to indicate a product. Cbs is used only if ascii, unblock, ebcdic, ibm, or block conversion is specified. In the first two cases, ebs characters are placed into the conversion buffer, any specified character mapping is done, trailing blanks trimmed and new-line added before sending the line to the output. In the latter three cases, characters are read into the conversion buffer, and blanks added to make up an output record of size cbs. After completion, dd reports the number of whole and partial input and output blocks. EXAMPLE 84 Last change: 23 September 1985 Sun Release 3.0 DD( 1 ) USER COMMANDS DD(1) To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file*: tutorial% dd if=/dev/rmtO of=x ibs=800 cbs=80 conv=ascii, lease Note the use of raw magtape: dd is especially suited to I/O on the raw physical devices because it allows reading and writing in arbitrary record sizes. SEE ALSO cp(l), tr(l) DIAGNOSTICS f+p records in(out): numbers of full and partial records read( written) BUGS The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 1968. The ibm conversion, while less blessed as a standard, corresponds better to certain IBM print train conven- tions. There is no universal solution. The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Invalid combinations silently ignore all but the last mutually-exclusive keyword. Sun Release 3.0 Last change: 23 September 1985 85 DEFAULTSEDIT ( 1 ) USER COMMANDS DEFAULTSEDIT ( 1 ) NAME defaultsedit - window- and mouse-based default parameters editor SYNOPSIS defaultsedit DESCRIPTION defaultsedit is a standard tool provided with the SunView environment. defaultsedit presents a convenient user interface for inspecting and setting default parameters. It can be viewed as a replacement for the traditional UNIX defaultsedit to manipulate options to the programs indent, mail and mailtool, stty, and defaultsedit, as well as the Menu, scrollbar, text subwindow and tty subwindow packages and the SunView environment. Any program or package which a user can customize by setting or changing a parameter could be written such that it gets its options from the database manipulated through defaultsedit. For information on how to do this see the chapter on the Defaults Database in the SunView System Programmer’ s Guide. OPTIONS defaultsedit accepts all of the generic tool arguments discussed in suntools(l). SUB WINDOWS defaultsedit consists of five subwindows. From top to bottom they are: buttons contains buttons labeled SAVE, QUIT, RESET, and EDIT ITEM. categories contains the names of all packages and programs currently in the master defaults database, with the current category indicated. message a small text subwindow where messages from defaultsedit are displayed. parameters shows all current default parameter names with corresponding values. edit a small text subwindow which enables text editing of parameter values. This is useful for very long text values, such as a long mailing list USING DEFAULTSEDIT SAVE Saves the current values for all categories in your private database — that is, the .defaults file in your home directory. QUIT exits without automatically saving anything. RESET resets the default parameters of the current category to the values in your private database. This is useful if you change some values, then change your mind and want to restore the ori- ginal values. EDIT ITEM Pressing the right mouse button over the EDIT ITEM button brings up a menu with three choices: COPY ITEM, DELETE ITEM and EDIT LABEL. Only text or numeric items can be edited. Also, note that edits made using this menu will appear only in your private defaults database, not in the master database. The three editing operations are described below. COPY ITEM Selecting COPY ITEM causes the current item to be duplicated. You can then edit both the label and the value of the the newly created item. Only items with text or numeric values can be copied in this way. COPY ITEM is useful when you want to change the number of instances of a certain type of item — for example, to insert a new mail alias into your defaults database. DELETE ITEM Selecting DELETE ITEM will delete the current item from your private database. It cannot be permanently deleted if the corresponding node is present in the master database. How- ever, you can make it behave like an undefined node by giving it the special value \255Undefned\255 . The first and last byte of this string have the ASCII code 255. 86 Last change: 26 December 1985 Sun Release 3.0 DEFAULTSEDIT ( 1 ) USER COMMANDS DEFAULTSEDIT ( 1 ) EDIT LABEL Selecting EDIT LABEL allows you to edit the label of the current item. When you select EDIT LABEL, the label of the current item changes from bold to normal face. Then you can select the label and edit it as a normal panel text item. FILES "/.defaults /usr/lib/defaults/*.d SEE ALSO Windows and Window-Based Tools: Beginner' s Guide The SuriView System Programmer’ s Guide BUGS Editing of choice items or categories is not supported by defaultsedit. Neither is editing of the master defaults database — to add a new program to the master defaults database, you have to edit a master defaults textfile. Sun Release 3.0 Last change: 26 December 1985 87 DELTA ( 1 ) USER COMMANDS DELTA ( 1 ) NAME delta — make a delta (change) to an SCCS file SYNOPSIS /usr/sccs/delta [ -r SID ] [ -s ] [ -n ] [ -g list ] [ -m [ mrlist ] ] [ -y [ comment ] ] [ -p ] file . . . DESCRIPTION Delta permanently introduces into the named SCCS file changes that were made to the file retrieved by get( 1) (called the g-file, or generated file). Delta makes a delta to each named SCCS file. If a directory is named, delta behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read (see WARNINGS ); each line of the standard input is taken to be the name of an SCCS file to be pro- cessed. Delta may issue prompts on the standard output depending upon certain options specified and flags (see admin (l)) that may be present in the SCCS file (see -m and -y options below). OPTIONS Options apply independendy to each named file. -r SID Uniquely identifies which delta is to be made to the SCCS file. The use of this option is necessary only if two or more outstanding get’s for editing (get -e) on the same SCCS file were done by the same person (login name). The SID value specified with the -r option can be either the SID specified on the get command line or the SID to be made as reported by the get command (see get{ 1)). A diagnostic results if the specified SID is ambiguous, or, if necessary and omitted on the command line. -s Do not display the created delta’s SID, number of lines inserted, deleted and unchanged in the SCCS file. -n Retain the edited g-file which is normally removed at completion of delta processing. -g list Specifies a list of deltas to be ignored when the file is accessed at the change level (SID) created by this delta. See get{ 1) for the definition of list. -m [mrlist] If the SCCS file has the v flag set (see admin(\)), a Modification Request (MR) number must be supplied as the reason for creating the new delta. If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the standard output before the standard input is read; if the standard input is not a terminal, no prompt is issued. The MRs? prompt always precedes the comments? prompt (see -y option). MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character ter- minates the MR list. Note that if the v flag has a value (see admin ( 1)), it is taken to be the name of a program (or shell procedure) which will validate the correctness of the MR numbers. If a non-zero exit status is returned from MR number validation program, delta terminates (it is assumed that the MR numbers were not all valid). -y [comment] Arbitrary text to describe the reason for making the delta. A null string is considered a valid com- ment. If -y is not specified and the standard input is a terminal, the prompt comments? is issued on the standard output before the standard input is read; if the standard input is not a terminal, no prompt is issued. An unescaped new-line character terminates the comment text. -p Display (on the standard output) the SCCS file differences before and after the delta is applied in a diff(l) format. 88 Last change: 6 March 1984 Sun Release 3.0 DELTA(l) USER COMMANDS DELTA ( 1 ) FILES All files of the form ?-file are explained in the Source Code Control System User’s Guide. The naming convention for these files is also described there. g-file Existed before the execution of delta ; removed after completion of delta . p-file Existed before the execution of delta ; may exist after completion of delta. q-file Created during the execution of delta ; removed after completion of delta . x-file Created during the execution of delta ; renamed to SCCS file after completion of delta. z-file Created during the execution of delta ; removed during the execution of delta. d-file Created during the execution of delta ; removed after completion of delta . /bin/diff Program to compute differences between the “gotten” file and the g-file . WARNINGS Lines beginning with an SOH ASCII character (binary 001) cannot be placed in the SCCS file unless the SOH is escaped. This character has special meaning to SCCS (see sccsfile( 5)) and will cause an error. A get of many SCCS files, followed by a delta of those files, should be avoided when the get generates a large amount of data. Instead, multiple get/delta sequences should be used. If the standard input (-) is specified on the delta command line, the -m (if necessary) and -y options must also be present. Omission of these options is an error. SEE ALSO sccs(l), admin(l), get(l), help(l), prs(l), sccsfile(5). Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help(l ) for explanations. Sun Release 3.0 Last change: 6 March 1984 89 DEROFF ( 1 ) USER COMMANDS DEROFF ( 1 ) NAME deroff - remove nroff, troff, tbl and eqn constructs SYNOPSIS deroff [ -w ] file . . . DESCRIPTION Deroff reads each file in sequence and removes all nroff and troff command lines, backslash constructions, macro definitions, eqn constructs (between ‘.EQ’ and ‘.EN’ lines or between delimiters), and table descrip- tions and writes the remainder on the standard output. Deroff follows chains of included files (‘.so’ and ‘.nx’ commands); if a file has already been included, a ‘.so’ is ignored and a ‘.nx’ terminates execution. If no input file is given, deroff reads from the standard input file. OPTIONS -w Generate a word list, one word per line. A ‘word’ is a string of letters, digits, and apostrophes, beginning with a letter; apostrophes are removed. All other characters are ignored. SEE ALSO troff(l), eqn(l), tbl(l) BUGS Deroff is not a complete troff interpreter, so it can be confused by subtle constructs. Most errors result in too much rather than too little output. Deroff does not work well with files that use .so to source in the standard macro package files. 90 Last change: 1 February 1985 Sun Release 3.0 DES(l) USER COMMANDS DES(l) NAME des - encrypt/decrypt with Data Encryption Standard SYNOPSIS des -e | -d [ -b ] [ -f ] [ -k key ] [ -s ] [ infile [ outfile ] ] DESCRIPTION des encrypts and decrypts data using the NBS Data Encryption Standard algorithm. One of -e (for encrypt) or -d (for decrypt) must be specified. The des command is provided to promote secure exchange of data in a standard fashion. OPTIONS -b Select ECB (eight bytes at a time) encryption mode. -f Suppress warning message when software implementation is used. — k key Use the encryption key specified. -s Selects software implementation for the encryption algorithm. Two standard encryption modes are supported by the des program, Cipher Block Chaining (CBC - the default) and Electronic Code Book (ECB - specified with -b). CBC mode treats an entire file as a unit of encryption, i.e., if insertions or deletions are made to the encrypted file then decryption will not succeed. CBC mode also ensures that regularities in clear data do not appear in the encrypted data. ECB mode treats each 8 bytes as units of encryptions, so if parts of the encrypted file are modified then other parts may still be decrypted. Identical values of clear text encrypt to identical values of cipher text The key used for the DES algorithm is obtained by prompting the user unless the -k key option is given. If the key is an argument to the des command, it is potentially visible to users executing ps(l) or a derivative. To minimize this possibility, des takes care to destroy the key argument immediately upon entry. The des command attempts to use DES hardware for its job, but will use a software implementation of the DES algorithm if the hardware is unavailable. Normally, a warning message is printed if the DES hardware is unavailable since the software is only about l/50th as fast. However, the -f option will suppress the warning. The -s option may be used to force use of software instead of hardware DES. The des command reads from standard input unless infile is specified and writes to standard output unless outfile is given. The following sections give information required to implement compatible facilities in other environments. Since the CBC and ECB modes of DES require units of 8 bytes to be encrypted, files being encrypted by the des command have 1 to 8 bytes appended to them to cause them to be a multiple of 8 bytes. The last byte, when decrypted, gives the number of bytes (0 to 7) which are to be saved of the last 8 bytes. The other bytes of those appended to the input are randomized before encryption. If, when decrypting, the last byte is not in the range of 0 to 7 then either the encrypted file has been corrupted or an incorrect key was provided for decryption and an error message is printed. The DES algorithm requires an 8 byte key whose low order bits are assumed to be odd-parity bits. The ASCII key supplied by the user is zero padded to 8 bytes and the high order bits are set to be odd-parity bits. The DES algorithm then ignores the low bit of each ASCII character, but that bit’s information has been preserved in the high bit due to the parity. The CBC mode of operation always uses an initial value of all zeros for the initialization vector, so the first 8 bytes of a file are encrypted the same whether in CBC or ECB mode. FILES /dev/des? BUGS It would be better to use a real 56-bit key rather than an ASCII-based 56-bit pattern. Knowing that the key was derived from ASCII radically reduces the time necessary for a brute-force crytographic attack. Sun Release 3.0 Last change: 23 September 1985 91 DES(l) USER COMMANDS DES(l) RESTRICTIONS This program is not available on software shipped outside the U.S. 92 Last change: 23 September 1985 Sun Release 3.0 DF(1) USER COMMANDS DF(1 ) NAME df- report free disk space on file systems SYNOPSIS df [ -i ] [ -t type ] [filesystem . . . ] [filename . . . ] DESCRIPTION df displays the amount of disk space occupied by currently mounted file systems, the amount of used and available space, and how much of the file system’s total capacity has been used. Used without arguments, df reports on all mounted file systems, producing something like: tutorial% df Filesystem kbytes used avail capacity Mounted on /dev/ipOa 7445 4714 1986 70% / /dev/ipOg 42277 35291 2758 93% /usr Note that used+avail is less than the amount of space in the file system (kbytes); this is because the system reserves a fraction of the space in the file system to allow its file system allocation routines to work well. The amount reserved is typically about 10%; this may be adjusted using tunefs. When all the space on a file system except for this reserve is in use, only the super-user can allocate new files and data blocks to existing files. When a file system is overallocated in this way, df may report that the file system is more than 100% utilized. If arguments to df are disk partitions (for example, IdevlipOa ) or UNIX path names, ^produces a report on the file system containing the named file. Thus “df .” shows the amount of space on the file system con- taining the current directory. OPTIONS -i Report the number of used and free inodes. -t type Report on filesystems of a given type (for example, nfs or 4.2). FILES /etc/mtab list of currently mounted filesystems SEE ALSO du(l), mtab(5), quot(8), tunefs(8) Sun Release 3.0 Last change: 23 September 1985 93 DEFF(l) USER COMMANDS DIFF(l) NAME diff - show differences between the contents of files or directories SYNOPSIS diff [ — b ] [ -c[#] | e | f | h ] filenamel filename2 diff [ -b ] [ -D string ] filenamel filename2 diff [ -b ] [ — c[#] | e | f | h ] [ -1 ] [ -r ] [ -s ] [ -S name ] dirl dir2 DESCRIPTION diff is a differential file comparator. When run on regular files, and when comparing text files that differ during directory comparison (see the notes below on comparing directories), diff tells what lines must be changed in the files to bring them into agreement. Except in rare circumstances, diff finds a smallest sufficient set of differences. If neither filenamel nor filename2 is a directory, either may be given as in which case the standard input is used. If filenamel is a directory, a file in that directory whose filename is the same as the filename of filename2 is used (and vice versa). There are several options for output format; the default output format contains lines of these forms: nl a n3,n4 nl,n2 d n3 nl,n2 c n3,n4 These lines resemble ed commands to convert filenamel into filename2 . The numbers after the letters per- tain to filename2 . In fact, by exchanging ‘a’ for ‘d’ and reading backward one may ascertain equally how to convert filename2 into filenamel . As in ed, identical pairs where nl = n2 or n3 = n4 are abbreviated as a single number. Following each of these lines come all the lines that are affected in the first file flagged by ‘<’, then all the lines that are affected in the second file flagged by V. If both arguments are directories, diff sorts the contents of the directories by name, and then runs the regu- lar file diff program as described above on text files which are different Binary files which differ, common subdirectories, and files which appear in only one directory are listed. OPTIONS -b ignore trailing blanks (spaces and tabs); other strings of blanks compare equal. The following four options are mutually exclusive: -c[#] produces a diff with lines of context. The default is to present 3 lines of context and may be changed, (to 10, for example), by -clO. With -c the output format is modified slightly: output begins with identification of the files involved and their creation dates, then each change is separated by a line with a dozen *’s. The lines removed from filenamel are marked with those added to filename2 are marked V. Lines which are changed from one file to the other are marked in both files with *!*. — e produce a script of a, c and d commands for the editor ed, which will recreate filename2 from filenamel . In connection with -e, the following shell program may help maintain multiple versions of a file. Only an ancestral file ($1) and a chain of version-to-version ed scripts ($2,$3,...) made by diff need be on hand. A ‘latest version’ appears on the standard output (shift; cat $*; echo T,$p') | ed - $1 Extra commands are added to the output when comparing directories with — e, so that the result is a sft(l) script for converting text files which are common to the two directories from their state in dirl to their state in dir2. -f produces a script similar to that of -e, not useful with ed, and in the opposite order. -fa does a fast, half-hearted job. It works only when changed stretches are short and well separated, but does work on files of unlimited length. 94 Last change: 23 September 1985 Sun Release 3.0 DIFF(l) USER COMMANDS DEFF(l) Options for the second form of diff ait as follows: -D string create a merged version of filenamel and filename! on the standard output, with C preprocessor controls included so that a compilation of the result without defining string is equivalent to com- piling filenamel, while defining string will yield filename!. Options when comparing directories are: -1 long output format; each text file diff is piped through pr to paginate it, other differences are remembered and summarized after all text file differences are reported. -r apply ^recursively to common subdirectories encountered. -s report files which are the same, which are otherwise not mentioned. -S name starts a directory diff in the middle, beginning with file name. FILES /tmp/d????? /usr/lib/diffh for -h /usr/bin/pr SEE ALSO crnp(l), cc(l), cotnm(l), ed(l), diff3(l), cpp(l) DIAGNOSTICS Exit status is 0 for no differences, 1 for some, 2 for trouble. BUGS Editing scripts produced under the — e or — f option are naive about creating lines consisting of a single When comparing directories with the -b option specified, diff first compares the files (as in cmp), and then runs the regular diff algorithm if they are not equal. This may cause a small amount of spurious output if the the only differences are in the placement of blank strings. The -D option ignores existing preprocessor controls in the source files, and can generate #ifdefs’s with overlapping scope. The output should be checked by hand, or run through cc -E and then diffed with the original source files. Discrpancies revealed should be corrected before compilation. Sun Release 3.0 Last change: 23 September 1985 95 DIFF3 ( 1 ) USER COMMANDS DIFF3 ( 1 ) NAME diff3 - 3-way differential file comparison SYNOPSIS diff3 [ -ex3 ] filel file2 file3 DESCRIPTION Diff3 compares three versions of a file, and publishes disagreeing ranges of text flagged with these codes: ==== all three files differ ====1 filel is different ====2 file2 is different ====3 file3 is different The type of change suffered in converting a given range of a given file to some other is indicated in one of these ways: f :nl a Text is to be appended after line number nl in file/, where/ = 1, 2, or 3. / : nl ,n2 c Text is to be changed in the range line nl to line n2. If nl = n2, the range may be abbreviated to nl . The original contents of the range follows immediately after a c indication. When the contents of two files are identical, the contents of the lower-numbered file is suppressed. Under the -e option, dijJ3 publishes a script for the editor ed that will incorporate into filel all changes between file2 and file3, i.e. the changes that normally would be flagged ==== and ====3. Option -x (-3) produces a script to incorporate only changes flagged ==== (====3). The following command will apply the resulting script to ‘filel’. (cat script; echo 'l,$p') | ed - filel FILES /tmp/d3????? /usr/lib/diff3 SEE ALSO diff(l) BUGS Text lines that consist of a single V will defeat -e. 96 Last change: 18 January 1983 Sun Release 3.0 DOMAINNAME ( 1 ) USER COMMANDS DOMAINNAME ( 1 ) NAME domainname - set or display name of current domain system SYNOPSIS domainname [ nameofdomain ] DESCRIPTION Without an argument, domainname displays the name of the current domain. Only the super-user can set the domainname by giving an argument; this is usually done in the startup script ietc/rc. local. Currendy, domains are only used by the yellow pages, to refer collectively to a group of hosts. SEE ALSO ypinit(8) Sun Release 3.0 Last change: 23 September 1985 97 DU ( 1 ) USER COMMANDS DU ( 1 ) NAME du — summarize disk usage SYNOPSIS du [ -s ] [ -a ] [ name . . . ] DESCRIPTION Du gives the number of kilobytes contained in all files and, recursively, directories within each specified directory or file name. If name is missing, V (the current directory) is used. A file which has multiple links to it is only counted once. OPTIONS -s Only display the grand total. -a Generate an entry for each file. Entries are generated only for each directory in the absence of options. EXAMPLE Here is an example of using du in a directory. We used the pwd command to identify the directory, then used du to show the usage of all the subdirectories in that directory. The grand total for the directory is the last entry in the display: % pwd /usr/henry/misc % du 5 ./jokes 33 ./squash 44 ytech.papers/lpr.document 217 Vtech.papers/new.manager 401 ytech.papers 144 ./memos 80 ./letters 388 ./window 93 ./messages 15 yuseful.news 1211 . % SEE ALSO df(l), quot(8) BUGS Filename arguments that are not directory names are ignored, unless you use -a . If there are too many distinct linked files, du counts the excess files multiply. Sun Release 3.0 98 Last change: 1 November 1983 ECHO ( 1 ) USER COMMANDS ECHO ( 1 ) NAME echo - echo arguments SYNOPSIS echo [ -n ] [ argument . . . ] DESCRIPTION Echo writes its arguments on the standard output. Arguments must be separated by spaces or tabs, and ter- minated by a newline. Echo is useful for producing diagnostics in shell programs and for writing constant data on pipes. If you are using the Bourne Shell (sfc(l)), you can send diagnostics to the standard error file by typing: ‘echo ... 1 >& 2 \ OPTIONS -n Don’t add the newline to the output. Sun Release 3.0 Last change: 26 April 1983 99 ED(1) USER COMMANDS EDO ) NAME ed - text editor SYNOPSIS ed [ - ] [ -x ] [filename ] DESCRIPTION ed is the basic line editor in the UNIX system. Although superseded by ex and vi for most purposes, ed is still used by system utilities such as sees. You can tell ed to perform various operations on the lines you specify, (see Line Addressing , below, for a discussion of how to form line-addresses for ed). You can print (display) lines, change lines, insert new lines into the buffer, delete existing lines, you can move or copy lines to a different place in the buffer, or you can substitute character strings within lines. (See List of Operations, below, for a guide. Also, see Regular Expressions for string-matching metacharacters.) ed does not operate directly on the contents of a file — when editing a file, ed reads the contents of the file into a buffer or scratchpad. All changes made during an editing session are made on the contents of the buffer. The copy must be ‘saved’ or ‘written’ — using the w (write) command — to save changes. The command-line shown in the synopsis above invokes ed. If filename is given, ed reads a copy of filename into its buffer so that it can be edited (simulates an e operation on filename). ed commands have a simple and regular structure: commands consist of an optional line-address, or two optional line-addresses separated by a comma, then a single letter operation, optionally followed by some other parameter: [line-address [ , line-address ] ] operation [ parameter ] For example, ‘l,10p’ means ‘print (display) lines 1 through 10’ (two line-addresses), ‘5a’ means ‘append after line 5’ (one line-address), and d means ‘delete the current line’ (no line-address with the current line used as default). Parameter varies for each operation — for the move and transfer operations, for exam- ple, it is the line that the addressed lines are to be moved or transferred after. These operations actually have three line-addresses. For reading and writing a file, parameter specifies the name of the file that is to be read. ed is extremely terse in its interaction with the user — ed’s normal response to just about any problem is simply a question mark ?. You get this response when, for instance, ed can’t find a specified line in the buffer, or if a search for a regular expression fails in a substitute (s) operation. OPTIONS - Don’t display character counts normally given by the e, r, and w operations — can be used when the standard input is an editor script. -x Simulate an x operation on the named file before reading it into the buffer, to handle encryption. LINE ADDRESSING The format of ed operations above shows that an operation can be preceded by one or two line-addresses, both of which are optional. If only one line-address is specified, operations are performed on that specific line. If two line-addresses are supplied, ed operates on the inclusive range of lines between them. Line-addresses are usually separated from each other by a comma — for instance: l,10p prints (displays) lines 1 thru 10. Line addresses may also be separated by a semicolon. Whereas the starting position for line-addresses separated by a comma is the same place in the buffer, when a line-address is followed by a semicolon, the current line is set to the line-address preceding the semicolon before any subsequent line-addresses are interpreted. For example: /Domaine Chandon/ ;//p sets the current line to the first occurrence of the string ‘Domaine Chandon’ before starting the search for the second occurrence. This feature can be used to determine the starting line for forward and backward 100 Last change: 5 December 1985 Sun Release 3.0 ED(1) USER COMMANDS ED(1) searches (7\ “?’). Lines can be accessed (addressed, in ed terminology) in several ways, but the most easily understood way of addressing lines is by line number. Line numbers in ed are relative to the start of the buffer. In practice, addressing lines by number proves to be the most awkward to use, so ed provides other mechanisms for line-addressing. Note that the line numbers associated with lines in the buffer are not physically present with the text of the lines — they are just an addressing mechanism. While ed is working on the buffer, it keeps track of the line on which you last performed some operation. This line is called the ‘current line’. As described below, you can indicate the current line by typing a period character (,). If you don’t specify a line for an operation to operate on, most ed operations work on the line addressed by the current line. When ed starts working on a file, the current line is positioned at the last line in the buffer. Thereafter, the current line usually changes when any operation is performed. In general, the current line sits at the last line affected by whatever ed operation you used. For instance, if you print lines 1 through 10 of the buffer, after the lines are displayed, the current line will be positioned at line 10. Line-addresses are constructed from elements as shown in the list below. Some special characters are used as a shorthand for certain line-addresses: . (‘dot’) addresses the current line. $ addresses the last line of the buffer. nnn A decimal number nnn addresses the nnn-th line of the buffer. 'x addresses the line marked with the name x, which must be a lower-case letter. Mark lines with the k operation described below. / regular expression / A regular expression enclosed in slashes 7’ searches forward from the current line and stops at the first line containing a string that matches the regular expression. If necessary, the search wraps around to the beginning of the buffer. Iregular expression ? A regular expression enclosed in question marks *?’ searches backward from the current line and stops at the first line containing a string that matches the regular expression. If necessary the search wraps around to the end of the buffer. address±nnn An address followed by a plus sign V or a minus sign followed by a decimal number specifies that line-address plus or minus the indicated number of lines. Plus is assumed if no signs are given. ±address An address beginning with V or ‘-’ is taken relative to the current line; in other words, ‘-5’ is understood to mean ‘.-5’. address ± An address ending with V or adds or subtracts 1. As a consequence of this rule and the pre- vious rule, the line-address ‘— ’ refers to the line before the current line. Moreover, trailing *+’ and ‘— ’ characters have cumulative effect, so ‘ — ’ refers to the current line less 2. To maintain compatibility with earlier versions of ed, the character “’ in line-addresses is equivalent to ed operations do not necessarily use line-addresses; they may use one or two. Operations which don’t use line-addresses regard the presence of a line-address as an error. Operations which accept one or two line- addresses assume default line-addresses if these are not specified. If more line-addresses are given than such an operation requires, the last one or two (depending on what is accepted) are used. The second line- Sun Release 3.0 Last change: 5 December 1985 101 ED(1) USER COMMANDS ED(1) address of any two-address sequence must be greater than the first line-address — that is, the second line must follow the first line in the buffer. LIST OF OPERATIONS ed operates in one of two major modes: command mode and text input mode, ed always starts up in com- mand mode. While you are typing commands at ed, you are in command mode. Some commands — a for append, c for change, and i for insert — provide for adding new text to the buffer. While ed is accepting new text, you are in text input mode. You exit from text input mode by typing a period V alone at the beginning of a line, ed then reverts to command mode. For example, here is a very short illustration of command mode versus text mode: tutorial% ed winelist ( tell ed to edit a file called winelist) 42 {ed states there are 42 characters in the file) l,$p (in command mode — tell ed to print all lines) 1978 Chateau Chunder 1979 Redeye Canyon a {in command mode — tell ed to append text) 1980 Doomsday Special {text input mode — add a new line ) . ( period ends text input mode) p ( back in command mode — print last line entered) 1980 Doomsday Special w {command mode — write the file) 65 {ed displays the number of characters written) q ( command mode — quit the edit session ) tutorial% ( back in the Shell) If you interrupt ed, it displays ‘?interrupted’ and returns to command mode. a Append Text. Reads the text entered in input mode and appends it to the buffer after the addressed line, a accepts one line-address — default line-address is the current line. The new current line is the last line input, or at the addressed line if no text is entered. Address ‘0’ is a valid place to append text, in which case text is placed at the beginning of the buffer. c Change Lines. Deletes the addressed lines, then accepts input text which replaces these lines, c accepts two line-addresses — default line-address is the current line. The current line is left on the last line input, or at the line preceding the deleted lines if no text is entered. d Delete Lines. Delete the addressed lines from the buffer, d accepts two line-addresses — default line-address is the current line. The line originally after the last line deleted becomes the current line; if the lines deleted were originally at the end, the new last line becomes the current line. e filename Edit a file. Deletes the entire contents of the buffer, and then reads in the named file, e sets the current line to the last line of the buffer, and reports the number of characters read into the buffer, e remembers filename for possible use as a default file name in a subsequent r or w operations. If no filename is given, the remembered filename is used, e displays a ? if the buffer has not been written out since the last change made — a second e operation says you really mean it E filename Same as e, but will silently allow you to quit an editing session without warning you if you have not written your file, e, on the other hand, reminds you to save your changes if you have altered the buffer at all. f filename Display Remembered Filename. Display the currently ‘remembered filename’. If filename is given, the currently ‘remembered 102 Last change: 5 December 1985 Sun Release 3.0 ED(1) USER COMMANDS ED(1 ) filename’ is changed to filename, g/regular expression! operation list This is the global operation: perform operation list on all lines in the range of line-addresses con- taining regular expression, g accepts two line-addresses — default is all lines in the buffer. Also see the v operation, which inverts the sense of regular expression. If your operation list actually takes up more than a single line, you must end every line except the last (the true ‘end’ of the global operation) with an escape character, ‘\\ For example, if you want to substitute jimjams’ for ‘frammis’, then append several lines of text to every line containing the string ‘widget’ and print those lines, you would type this sequence: g/widget/s/frammis/jimj amsA a\ new line of text\ another new line of text\ •\ P Note that the a, i, and c operations, which put ed in input mode, are permitted in the operation list ; the final . terminating input may be omitted if it is the last line of the operation list. The g and v operations are not permitted in the operation list. i Insert Text. Insert lines of text into the buffer before the addressed line, i accepts one line-address — default line-address is the current line. The current line is placed at the last line input; if no text is input, the current line is left at the line before the addressed line, i differs from a only in the placement of the text. j Join Lines. Joins the addressed lines into a single line; intermediate newlines simply disappear, j accepts two line-addresses — default is the current line and the following line. The current line is placed at the resulting line. kx Mark Line. Marks the addressed line with name * (the name must be a lower-case letter). The line-address form x then addresses this line, k accepts one line-address — default line-address is the current line. 1 Display Non-printing Characters. Displays non-graphic characters in the addressed lines such that they are displayed in two-digit octal, and long lines are folded. 1 accepts two line-addresses — default line-address is the current line. I may be placed on the same line after any non-I/O operation. m address Move lines. Reposition the addressed lines after the line-addressed by address, m accepts two line-addresses to specify the range of lines to be moved — default line-address is the current line. The last of the moved lines becomes the current line. p Print (display) Lines. Displays the addressed lines, p accepts two line-addresses — default line-address is the current line. The current line is placed at the last line printed, p may be placed on the same line after any non-I/O operation. P Synonym for p. q Quit Edit Session. Exit from the editing session. Note, however, that the buffer is not automatically written out (do a ‘w’ to write if you want to save your changes), ed warns you once if you haven’t saved your file — a second q says you really mean it. Q Same as q, but you don’t get any warning if you haven’t previously written out the buffer. Sun Release 3.0 Last change: 5 December 1985 103 ED(1) USER COMMANDS ED( 1 ) r filename Read from file. Reads the contents of filename into the buffer after the addressed line. If filename is not given, the ‘remembered filename’, if any, is used (see e and f). r accepts one line-address — default line- address is $. If line-address ‘0’ is used, r reads the file in at the beginning of the buffer. If the read is successful, r displays the number of characters read in. The current line is left at the last line read in from the file. s /regular expression/replacement string / or, s/regular expressionlreplacement string/g Substitute the replacement string for the first occurrence of regular expression on each line where the regular expression occurs. In the first form of the s operation, only the first occurrence of the matched string on each line is replaced. If you use the g (global) suffix, all occurrences of the regu- lar expression are replaced in the line. Keep the g suffix of the s operation distinct from the g opera- tion itself — they are completely different, s accepts two line-addresses to delimit the range of lines wi thin which the substitutions should be done — default line-address is the current line. The current line is left at the last line substituted. Special Characters : Any punctuation character may be used instead of V to delimit the regular expression and the replacement string. An ampersand ‘&’ appearing in the replacement string is replaced by the string matching the regular expression. The special meaning of in this context may be suppressed by preceding it by ‘W The characters \n where n is a digit, are replaced by the text matched by the n-th regular subexpression enclosed between ‘\(’ and ‘\)\ When nested, parenthesized subexpressions are present, n is determined by counting occurrences of ‘\(’ starting from the left. Lines may be split by substituting new-line characters into them. The new-line in the replacement string must be escaped by preceding it by ‘\\ taddress Transfer Lines. Transfers a copy of the addressed lines to after line address, transfer is like move, but it makes copies of the lines, leaving the original text where it was. t accepts two line-addresses preceeding the operation letter — default line-address is default. The current line is left on the last line of the copy. ‘0’ is a legal line-address for the destination. u Undo. Undo previous substitute. undo undoes the effect of the the last substitute operation, providing that the current line has not been moved since the substitute operation . v/regular expression/operation list Like a negative of the global operation, g: perform operation list on all lines except those containing regular expression, v accepts two line-addresses — default is all lines in the file. w Write Lines. Write the addressed lines from the buffer into the file specified by the ‘remembered filename’, w accepts two line-addresses — default is all lines in the file. The current line is unchanged. If the write is successful, ed displays the number of characters written. w filename Write Lines. Write the addressed lines into filename. Filename is created if it does not already exist. Filename becomes the ‘remembered filename’ (see the e and f operations), w accepts two line-addresses — default is all lines in the file. The current line is unchanged. If the write is successful, ed displays the number of characters written. W filename Same as w, but appends the addressed lines to the named file instead of overwriting the file. W accepts two line-addresses — default is all lines in the file. x Encrypt File. 104 Last change: 5 December 1985 Sun Release 3.0 ED(1) USER COMMANDS ED(1 ) When x is used, ed demands a key string from the standard input. Later r, e, and w operations will encrypt and decrypt the text with this key by the algorithm of crypt. An explicitly empty key turns off encryption. = Display Line Number. Display the line number of the addressed line. = accepts one line-address — default line-address is $. The current line is unchanged by this operation. ! The remainder of the line after the M’ is sent to sh to be interpreted as a shell command. The current line is unchanged. address Display the addressed line. If you type a line-address and type return, ed displays the addressed line. If you simply type RETURN, the line following the current line is displayed (equivalent to ‘. +lp’). This is useful for stepping through text REGULAR EXPRESSIONS ed supports a limited form of regular expression notation. A regular expression (also known as a pattern ) specifies a set of strings of characters — such as ‘any string containing digits 5 through 9’ or ‘only lines containing uppercase letters’. A member of this set of strings is said to be matched by the regular expres- sion. Regular expressions or patterns are used to address lines in the buffer (see Line Addressing, above), and also for selecting strings to be substituted in the s (substitute) operation described previously. An empty regular expression, indicated by two regular expression delimiters in a row, stands for a copy of the last regular expression encountered. Any given regular expression matches the the longest among the leftmost matches in a line. In the following specification for regular expressions, the notation c stands for any single ordinary charac- ter, where a character is anything except a newline character. c any ordinary character except a special character matches itself. Special characters are the delim- iters that actually surround the regular expression, plus \ (the escape character), [ (the opening bracket for a character class as described below), . (period which matches any single character), and sometimes the * (closure) ' and $ characters. If you want a literal occurrence of one of these special characters you must escape them with the \ character. at the very start of the regular expression constrains the match to the beginning of the line. A match of this type is called an ‘anchored match’ because it is ‘anchored’ to a specific place in the line. The A character loses its special meaning if it appears in any position other than at the very start of the regular expression. $ at the very end of the regular expression constrains the match to the end of the line. A match of this type is called an ‘anchored match’ because it is ‘anchored’ to a specific place in the line. The $ character loses its special meaning if it appears in any position other than at the very end of the regular expression. . (period) matches any single character except a newline character. [string] A string of characters enclosed in brackets matches any one of the characters in the brackets. For example, [abcxyz] matches any single character from the set ‘abcxyz’. If the first character inside the bracket is a \ the string matches any character not inside the brackets. For instance, ["456787] matches any character except ‘45678’. You can use a shorthand notation to refer to an inclusive range of characters: a-b. Such a bracketed string of characters is known as a character class. xy When two regular expressions are concatenated, they match the leftmost and then the longest pos- sible string that can be divided with the first part of the string matching the first regular expression, followed by the second string matching the second regular expression. * Any regular expression followed by * matches a sequence of 0 or more matches of the regular Sun Release 3.0 Last change: 5 December 1985 105 ED(1) USER COMMANDS ED( 1 ) expression. Such a pattern is called a closure. For example: [ a-z ] [ a-z ] * matches any string of one or more lower case letters. \( regular expression \) The regular expression within the \( and \) brackets essentially ‘remembers’ whatever the regular expression matches. This provides a mechanism for extracting parts of strings. There can be up to nine such partial matches in a string. Parenthesized regular expressions can be nested. \n where n is in the range 1 thru 9, matches a copy of the string that the bracketed regular expression beginning with the nth \( matched, as described in the previous paragraph on matching parts of strings. When nested, parenthesized subexpressions are present, n is determined by counting occurrences of \( starting from the left. Regular expressions are used in line-addresses to specify lines and in one operation (see s for substitute above) to specify a portion of a line which is to be replaced. If it is desired to use one of the regular expression metacharacters as an ordinary character, that character may be preceded by ‘V. This also applies to the character bounding the regular expression (often 7’) and to *V itself. FILES /tmp/e* ed.hup: work is saved here if telephone hangs up SEE ALSO Using the crypt(l) ex(l) sed(l) vi(l) BUGS The 1 operation mishandles del. The undo operation removes marks from affected lines. Because 0 is an illegal line-address for a w operation, it is not possible to create an empty file with ed. Use cat (1) to create an empty file. RESTRICTIONS Some size limitations: 512 characters per line, 256 characters per global command list, 64 characters per file name, and 128K characters in the temporary file. Since each line uses two bytes of memory, the limit on the number of lines should not be exceeded in practice. When reading a file, ed discards ascii nul characters and all characters after the last newline, ed refuses to read files containing non-ASCII characters. The encryption facilities of ed are not available on software shipped outside the U.S. ed Line Editor in Editing Text Files on the Sun Workstation. encode and decode extended line editor (part of vi) stream editor visual (display) editor 106 Last change: 5 December 1985 Sun Release 3.0 EQN(l) USER COMMANDS EQN(l) NAME eqn, neqn, checkeq - typeset mathematics SYNOPSIS eqn [ -dry ] [ -p n ] [ -sn ] [ -in ] [filename ] . . . neqn [ filename ] . . . checkeq [ filename ] . . . DESCRIPTION Eqn (and neqn ) are language processors to assist in describing equations. Eqn is a preprocessor for troff{ 1) and is intended for devices that can print tr off's output. Neqn is a preprocessor for nroff( 1) and is intended for use with terminals. Usage is almost always: tutorials, eqn file ... | troff tutorial% neqn file ... | nroff If no files are specified, eqn and neqn read from the standard input A line beginning with ‘.EQ’ marks the start of an equation; the end of an equation is marked by a line beginning with ‘.EN’. Neither of these lines is altered, so they may be defined in macro packages to get centering, numbering, etc. It is also possible to set two characters as ‘delimiters’; subsequent text between delimiters is also treated as eqn input Checkeq reports missing or unbalanced delimiters and .EQ/.EN pairs. OPTIONS -dxy Set equation delimiters set to characters x and y with the command-line argument. The more common way to do this is with ‘delim xy’ between .EQ and .EN. The left and right delimiters may be identical. Delimiters are turned off by ‘delim off’ appearing in the text. All text that is neither between delimiters nor between .EQ and .EN is passed through untouched. — pn Reduce subscripts and superscripts by n point sizes from the previous size. In the absence of the -p option, subscripts and superscripts are reduced by 3 point sizes from the previous size. -sn Change point size to n globally in the document. The point size can also be changed globally in the body of the document by using the gsize directive. -fn Change font to n globally in the document. The font can also be changed globally in the body of the document by using the gfont directive. EQN LANGUAGE Tokens within eqn are separated by spaces, tabs, newlines, braces, double quotes, tildes or circumflexes. Braces { } are used for grouping; generally speaking, anywhere a single character like x could appear, a complicated construction enclosed in braces may be used instead. Tilde (') represents a full space in the output, circumflex (') half as much. Subscripts and superscripts are produced with the keywords sub and sup. Thus x sub i makes x /( a sub i sup 2 produces a; 2 , and e sup {x sup 2 + y sup 2} gives «**+•>*. Fractions are made with over: a over b yields %■. sqrt makes square roots: 1 over sqrt {ax sup 2 +bx+c } results in • The keywords from and to introduce lower and upper limits on arbitrary things: is made with lim from { n-> inf } sum from 0 to nx sub i. Left and right brackets, braces, etc. over alpha right ] ~=~1 produces and right are braces, brackets, bai^s, c and right-side-only bracket). r of the right height are made with left and right: left [ x sup 2 +y sup 2 X2+# = 1. The right clause is optional. Legal characters after left f for ceiling and floor, and "" for nothing at all (useful for a Vertical piles of things are made with pile, lpile, cpile, and rpile: pile {a above b above c) produces There can be an arbitrary number of elements in a pile, lpile left-justifies, pile and cpile center, with Sun Release 3.0 Last change: 1 February 1985 107 EQN(l) USER COMMANDS EQN(l) different vertical spacing, and rpile right justifies. Matrices are made with matrix: matrix { Icol { x sub i above y sub 2 } ccol { 1 above 2} } produces y‘ 2 \. In addition, there is rcol for a right-justified column. Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and under: x dot = f(t) bar is x=f (t),y dotdot bar ~= " n under is y = n, and x vec ~=~y dyad is ?=f. Sizes and font can be changed with size n or size ±n, roman, italic, bold, and font n. Size and fonts can be changed globally in a document by gsize n and gfont n, or by the command-line arguments — s n and — f h. Successive display arguments can be lined up. Place mark before the desired lineup point in the first equa- tion; place lineup at the place that is to line up vertically in subsequent equations. Shorthands may be defined or existing keywords redefined with define; define thing % replacement % defines a new token called thing which will be replaced by replacement whenever it appears thereafter. The % may be any character that does not occur in replacement. Keywords like sum (£), int (J), inf (°°), and shorthands like >= (>), — > (— »), and != (^) are recognized. Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathematical words like sin, cos, log are made Roman automatically, troff(l) four-character escapes like \(bu (•) can be used anywhere. Strings enclosed in double quotes "..." are passed through untouched; this permits keywords to be entered as text, and can be used to communicate with tr off when all else fails. SEE ALSO Formatting Documents on the Sun Workstation troff(l), tbl(l), ms(7), eqnchar(7) BUGS To embolden digits, parens, etc., it is necessary to quote them, as in ‘bold "12.3"’. 108 Last change: 1 February 1985 Sun Release 3.0 ERROR ( 1 ) USER COMMANDS ERROR ( 1 ) NAME error - analyze and disperse compiler error messages SYNOPSIS error [ — n ] [ — s ] [ — q ] [ — v ] [ — t suffixlist ] [ -I ignorefile ] [ name ] DESCRIPTION Error analyzes error messages produced by a number of compilers and language processors. It replaces the painful, traditional methods of scribbling abbreviations of errors on paper, and permits error messages and source code to be viewed simultaneously. Error looks at error messages, either from the specified file name or from the standard input, and: • Determines which language processor produced each error message, ° Determines the file name and line number of the erroneous line, and, ■ Inserts the error message into the source file immediately preceding the erroneous line. Error messages which can’t be categorized by language processor or content are not inserted into any file, but are sent to the standard output. Error touches source files only after all input has been read. Options are explained later on in this manual entry. Error is intended to be run with its standard input connected via a pipe to the error message source. Some language processors put error messages on their standard error file; others put their messages on the stan- dard output. Hence, both error sources should be piped together into error. For example, when using the csh syntax, tutorial% make -s lint | & error -q -v will analyze all the error messages produced by whatever programs make runs when makin g lint. Error knows about the error messages produced by: make, cc, cpp, ccom, as. Id, lint, pi, pc, and/77. For all languages except Pascal, error messages are restricted to one line. Some error messages refer to more than one line in more than one file, in which case error duplicates the error message and inserts it at all of the places referenced. Error does one of six things with error messages. synchronize Some language processors produce short errors describing which file they are processing. Error uses these to determine the file name for languages that don’t include the file name in each error message. These synchronization messages are consumed entirely by error. discard Error messages from lint that refer to one of the two lint libraries, /usrllib/llib-lc and lusr/liblllib- port are discarded, to prevent accidently touching these libraries. Again, these error messages are consumed entirely by error. nullify Error messages from lint can be nullified if they refer to a specific function, which is known to generate diagnostics which are not interesting. Nullified error messages are not inserted into the source file, but are written to the standard output The names of functions to ignore are taken from either the file named .errorrc in the user’s home directory, or from the file named by the —I option. If the file does not exist no error messages are nullified. If the file does exist there must be one function name per line. not file specific Error messages that can’t be intuited are grouped together, and written to the standard output before any files are touched. They are not inserted into any source file. file specific Error messages that refer to a specific file but to no specific line are written to the standard output when that file is touched. true errors Sun Release 3.0 Last change: 13 March 1984 109 ERROR(l) USER COMMANDS ERROR ( 1 ) Error messages that can be intuited are candidates for insertion into the file to which they refer. Only true error messages are inserted into source files. Other error messages are consumed entirely by error or are written to the standard output. Error inserts the error messages into the source file on the line preceeding the line number in the error message. Each error message is turned into a one line comment for the language, and is internally flagged with the string *###’ at the beginning of the error, and “%%%’ at the end of the error. This makes pattern searching for errors easier with an editor, and allows the messages to be easily removed. In addition, each error message contains the source line number for the line the mes- sage refers to. A reasonably formatted source program can be recompiled with the error messages still in it, without having the error messages themselves cause future errors. For poorly formatted source pro- grams in free format languages, such as C or Pascal, it is possible to insert a comment into another com- ment, which can wreak havoc with a future compilation. To avoid this, format the source program so there are no language statements on the same line as the end of a comment. OPTIONS -n Do not touch any files; all error messages are sent to the standard output. -q Error asks whether the file should be touched. A ‘y’ or ‘n’ to the question is necessary to continue. Absence of the -q option implies that all referenced files (except those refering to discarded error messages) are to be touched. -v After all files have been touched, overlay the visual editor vi with it set up to edit all files touched, and positioned in the first touched file at the first error. If vi can’t be found, try ex or ed from stan- dard places. -t Take the following argument as a suffix list. Files whose suffices do not appear in the suffix list are not touched. The suffix list is dot seperated, and wildcards work. Thus the suffix list; ”.c.y.f*.h" allows error to touch files ending with ‘.c’, ‘.y’, ‘.f*’ and ‘.y’. -s Print out statistics regarding the error categorization. Not too useful. Error catches interrupt and terminate signals, and if in the insertion phase, will orderly terminate what it is doing. FILES '/.errorrc /dev/tty BUGS Opens the teletype directly to do user querying. Source files with links make a new copy of the file with only one link to it. Changing a language processor’s format of error messages may cause error to not understand the error message. Error, since it is purely mechanical, will not filter out subsequent errors caused by ‘floodgating’ initiated by one syntactically trivial error. Humans are still much better at discarding these related errors. Pascal error messages belong after the lines affected (error puts them before). The alignment of the ‘ | ’ marking the point of error is also disturbed by error. Error was designed for work on CRT’s at reasonably high speed. It is less pleasant on slow speed termi- nals, and has never been used on hardcopy terminals. function names to ignore for lint error messages user’s teletype 110 Last change: 13 March 1984 Sun Release 3.0 EX(1) USER COMMANDS EX(1 ) NAME ex, edit — text editor SYNOPSIS ex[-] [-R] [ -r ] [ -t tag ] [+ command ] [-v] [-x ] [ -wnnn ] [ . .. edit [ options ] DESCRIPTION ex, a line editor, is the root of a family of editors that includes edit, ex, and vi (the display editor). In most cases vi is preferred for interactive use. OPTIONS supress all interactive feedback to the user — useful for processing ex scripts in shell files. -R Read only. Do not overwrite the original file. — r recover the indicated files after a system crash. -t tag edit the file containing the tag tag. A tags database must first be created using the ctags{ 1) com- mand. + command start the editing session by executing command. -v start up in display editing state using vi(l). You can achieve the same effect by simply typing the vi command itself. -x prompt for a key to be used in encrypting the file being edited. -wnnn set the default window (number of lines on your terminal) to nnn — this is useful if you are dial- ling into the system over a slow ’phone line. -1 set up for editing LISP programs. FILES /usr/lib/ex?.?strings /usr/lib/ex?.?recover /usr/lib/ex?.?preserve /etc/termcap '/.exrc /tmp/Exnnnnn /tmp/Rxrtrtrtrtrt /usr/preserve SEE ALSO error messages recover command preserve command describes capabilities of terminals editor startup file editor temporary named buffer temporary preservation directory Editing Text Files on the Sun awk(l), ed(l), grep(l), sed(l), grep(l), vi(l), termcap(5), environ(5) BUGS The undo command causes all marks to be lost on lines changed and then restored if the marked lines were changed. Undo never clears the buffer modified condition. The z command prints a number of logical rather than physical lines. More than a screen full of output may result if long lines are present. File input/output errors don’t print a name if the command line option is used. There is no easy way to do a single scan ignoring case. The editor does not warn if text is placed in named buffers and not used before exiting the editor. Null characters are discarded in input files, and cannot appear in resultant files. Sun Release 3.0 Last change: 24 October 1984 111 EX(1) USER COMMANDS EX( 1 ) The editor checks the first five lines of the text file for commands of the form "zwcommand." or "vi:command ." This feature can result in unexpected behavior, and is not recommended in any case. RESTRICTIONS The encryption facilities of ex are not available on software shipped outside the U.S. 112 Last change: 24 October 1984 Sun Release 3.0 EXPAND ( 1 ) USER COMMANDS EXPAND ( 1 ) NAME expand, unexpand - expand tabs to spaces, and vice versa SYNOPSIS expand [ — tabstop ] [ —tabl,tab2,. . ,,tabn \ [filename . . . ] unexpand [ -a ] [filename ... ] DESCRIPTION expand copies the named files, (or the standard input) to the standard output, with tabs changed into spaces (blanks). Backspace characters are preserved into the output and decrement the column count for tab cal- culations. expand is useful for pre-processing character files (before sorting, looking at specific columns etc.) that contain tabs. Unexpand copies the named files (or the standard input) to the standard output, putting tabs back into the data. By default only leading spaces (blanks) and tabs are converted to strings of tabs, but this can be over- ridden by the —a option (see the options section below). EXPAND OPTIONS -tabstop Specified as a single argument sets tabs tabstop spaces apart instead of the default 8. —tabl.ta.b2,. . ,,tabn Set tabs at the columns specified by tabl. . . UNEXPAND OPTIONS —a Insert tabs when replacing a run of two or more spaces would produce a smaller output file. Sun Release 3.0 Last change: 23 September 1985 113 EXPR(l) USER COMMANDS EXPR(l) NAME expr - evaluate arguments as an expression SYNOPSIS expr arg . . . DESCRIPTION Expr evaluates expressions as specified by its arguments. Each token of the expression is a separate argu- ment. After evaluation, the result is written on the standard output. The operators and keywords are listed below. The list is in order of increasing precedence, with equal pre- cedence operators grouped. expr / expr yields the first expr if it is neither null nor ‘O’, otherwise yields the second expr. expr & expr yields the first expr if neither expr is null or ‘O’, otherwise yields ‘O’. expr relop expr yields ‘1’ if the indicated comparison is true, ‘0’ if false. The comparison is numeric if both expr are integers, otherwise the comparison is lexicographic, relop is one of < (less than), <= (less than or equal to), = (equal to), != (not equal to), >= (greater than or equal to), and > (greater than). expr + expr expr — expr addition or subtraction of the arguments. expr * expr expr / expr expr % expr multiplication, division, or remainder of the arguments. expr : expr match string regular-expression The two forms of the matching operator above are synonymous. The matching operator compares the string first argument with the regular expression second argument; regular expression syntax is the same as that of ed( 1). The \(...\) pattern symbols can be used to select a portion of the first argument. Otherwise, the matching operator yields the number of characters matched (‘0’ on failure). substr string integer-1 integer-2 extracts the subtring of string starting at position integer-1 and of length integer-2 characters. If integer-1 has a value greater than string, expr returns a null string. If you try to extract more characters than there are in string , expr returns all the remaining characters from string . Beware of using negative values for either integer-1 or integer-2 as expr tends to run forever in these cases. index string character-list reports the first position in string at which any one of the characters in character-list matches a character in string . length siring returns the length (that is, the number of characters) of string. ( expr ) parentheses for grouping. EXAMPLES To add 1 to the Shell variable a: a='expr $a + V 114 Last change: 26 March 1984 Sun Release 3.0 EXPR(l) USER COMMANDS EXPR(l) To find the filename part (least significant part) of the pathname stored in variable a, which may or may not contain 7’: expr $a : '.*A(.*\)' T$a Note the quoted Shell metacharacters. SEE ALSO sh(l), test(l) DIAGNOSTICS Expr returns the following exit codes: 0 if the expression is neither null nor ‘0’ , 1 if the expression is null or ‘O’, 2 for invalid expressions. BUGS Note that the match, substr, length, and index operators cannot themselves be used as ordinary strings. That is, the expression: tutorial% expr index expurgatorious length syntax error tutorial% generates the syntax error’ message as shown instead of the value 1 as you might expect Sun Release 3.0 Last change: 26 March 1984 115 EYACC(l) USER COMMANDS EYACC(l) NAME eyacc - modified yacc allowing much improved error recovery SYNOPSIS eyacc [ -v ] [ grammar ] DESCRIPTION Eyacc is a version of yacc(l), that produces tables used by the Pascal system and its error recovery rou- tines. Eyacc fully enumerates test actions in its parser when an error token is in the look-ahead set This prevents the parser from making undesirable reductions when an error occurs before the error is detected. The table format is different in eyacc than it was in the old yacc, as minor changes had been made for efficiency reasons. SEE ALSO yacc(l) Practical LR Error Recovery by Susan L. Graham, Charles B. Haley and W. N. Joy; SIGPLAN Conference on Compiler Construction, August 1979. BUGS Pc and its error recovery routines should be made into a library of routines for the new yacc. 116 Last change: 25 April 1983 Sun Release 3.0 F77 ( 1 ) USER COMMANDS F77 ( 1 ) NAME f77 - FORTRAN 77 compiler SYNOPSIS f77 [ — c ] [ — g ] [ — a ] [ -o output ] [ -O ] [ -C ] [ -D name ] [ -D name [ =def ]] [float _option ] [ — F ] [ — i2 ] [- Idir ] [-m] [-N[qxscn]nnn ] [-onetrip] [ — p ] [-pg] [ -Rx] [ — S ] [ — u ] [ — U ] [— v ] [— w[66 ]] filename ... DESCRIPTION f77 is the UNIX FORTRAN 77 compiler, which translates programs written in the FORTRAN 77 program- ming language into executable load modules or into relocatable binary programs for subsequent linking with ld( 1). In addition to the many flag arguments (options), f77 accepts several types of files. Filenames ending in ./ are taken to be FORTRAN 77 source programs; they are compiled, and each object program is left in the file (in the current directory) whose name is that of the source with .o substituted for ./. Filenames ending in .F are also taken to be FORTRAN 77 source programs, but they are preprocessed by the C preprocessor (equivalent to a cc -E command) before they are compiled by the/77 compiler. Filenames ending in .r are taken to be Ratfor source programs; these are first transformed by the ratflor{ 1) preprocessor, then compiled by f77 . In the same way, filenames ending in .c or are taken to be C or assembly source programs and are com- piled or assembled, producing .o files. OPTIONS The following options have the same meanings as for cc(l). See ld( 1) for link-time options. -c Suppress linking and produce a .o file for each source file. -g Produce additional symbol table information for dbx{ 1). Also pass the -lg flag to ld( 1). -a Insert code into the program to count how many times each basic block in the program is exe- cuted. After the program is compiled with this option, there will be a .d file for every ./file com- piled with the -a option. The .d file accumulates execution data for the corresponding source file. The tcov( 1) utility can then be run on the source file to generate statistics about the program. — o output Name the final output file output instead of a. out. The following options are peculiar to /77: -O Optimize the object code. This invokes both the global intermediate code optimizer and the object code optimizer. — C Compile code to check that subscripts are within the declared array bounds. -Dname -Dname= definition Define name to the C preprocessor, as if by ‘#define’. If no definition is given, the name is defined as "1". ( .F suffix files only). float _option Floating-point code generation option. Can be one of: -fsoft software floating-point calls (This is the default). -fsky in-line code for Sky floating-point processor (supported only on Sun-2 systems). -f68881 in-line code for Motorola 68881 floating-point processor (supported only on Sun-3 systems). -fswitch run-time-switched floating-point calls. The compiled object code is linked at run- time to routines that support one of the above types of floating-point code. This was the default in previous releases. Only for use with programs that are floating-point intensive and which must be portable to machines with various floating-point Sun Release 3.0 Last change: 21 December 1985 117 F77 ( 1 ) USER COMMANDS F77 ( 1 ) options. When invoked without float _option, the compiler interrogates the FLOAT_OPTION environment variable to determine the type of floating-point code to generate. Legal values for FLOATOPTION are: ‘fsoft’, ‘fsky’, l f68881’, and ‘fswitch’. -F Apply the C preprocessor to .F files and the Ratfor preprocessor to .r files, putting the results in the corresponding / files, but do not compile them. No linking is done. However, any .c or .s files are compiled or assembled. -i2 Make the default size of integer and logical constants and variables two bytes rather than four bytes. -Idir ‘#include’ files whose names do not begin with 7’ are always sought by the C preprocessor first in the directory of the file argument, then in directories named in -I options, then in the Iusrlincludelf77 directory (applies to processing of .F suffix files only). -m Apply the M4 preprocessor to each .r file before transforming it with the Ratfor preprocessor. -N[qxscn]rt«« Make static tables in the compiler bigger. J77 complains if tables overflow and suggests you apply one or more of these flags. These flags have the following meanings: q Maximum number of equivalenced variables. Default is 150. x Maximum number of external names (common block, subroutine, and function names). Default is 200. s Maximum number of statement numbers. Default is 401. c Maximum depth of nesting for control statements (for example, DO loops). Default is 20 . n Maximum number of identifiers. Default is 1009. One may use multiple -N options to increase the sizes of multiple tables. -onetrip Compile DO loops so that they are performed at least once if reached. FORTRAN 77 DO loops are not performed at all if the upper limit is smaller than the lower limit. -p Produce code to count the number of times each routine is called and estimate the fraction of time spent in each routine. The results of this profiling appear in a file called mon.out when the pro- gram being profiled terminates normally. An execution profile of the program can then be pro- duced using the prof{ 1) utility. -pg Produce counting code in the manner of -p, but invoke a run-time recording mechanism that keeps more extensive statistics and produces a gmon.out file at normal termination. An execution profile can then be generated by use of gprof( 1). -Rx Use the string x as a Ratfor option in processing ,r files. -S Compile the named programs, and leave the assembly language output on corresponding files suffixed .s (no .o file is created). -u Make the default type of a variable ‘undefined’ rather than using the FORTRAN default rules. -U Do not convert upper case letters to lower case. The default is to convert upper case letters to lower case, except within character string constants. -v Print the version number of the compiler and the name of each pass as it executes. -w[66] Suppress all warning messages, or if the option is -w66, supress only FORTRAN 66 compatibility warnings. Other arguments are taken to be either linker option arguments, or /77-compatible object programs, typi- cally produced by an earlier run, or libraries of /77-compatible routines. These programs, together with the results of any compilations specified, are linked (in the order given) to produce an executable program in the file specified by the -o option, or in a file named a. out if the -o option is not specified. 118 Last change: 21 December 1985 Sun Release 3.0 F77 ( 1 ) USER COMMANDS F77 ( 1 ) FILES file.[fFrsc] input file file.o object file a.out linked output ,/fort[pid].? temporary /usr/include/f77 directory searched by the FORTRAN 77 include statement /usr/lib/f77passl parser /lib/fl code generator /lib/c2 optional optimizer /lib/cpp C preprocessor /lib/bin/ratfor Ratfor preprocessor /usr/lib/li bf77 . a Fortran library /lib/libc.a C library, see Section 3 mon.out file produced for analysis by prof(l) gmon.out file produced for analysis by gprof(l) SEE ALSO FORTRAN Programmer’s Guide for the Sun Workstation cc(l), gprof(l), ld(l), prof(l), ratfor(l) DIAGNOSTICS The diagnostics produced by f77 itself are intended to be self-explanatory. Occasional messages may be produced by the linker. Sun Release 3.0 Last change: 21 December 1985 119 FALSE ( 1 ) USER COMMANDS FALSE ( 1 ) NAME false, true - provide truth values SYNOPSIS true false DESCRIPTION True and false are usually used in a Bourne shell script. They test for the appropriate status "true" or "false” before running (or failing to run) a list of commands. EXAMPLE while false do command list done SEE ALSO csh(l), sh(l), true(l) DIAGNOSTICS False has exit status nonzero. 120 Last change: 11 January 1982 Sun Release 3.0 FILE ( 1 ) USER COMMANDS FILE ( 1 ) NAME file - determine file type SYNOPSIS file [-f ] file ... DESCRIPTION File performs a series of tests on each file in an attempt to determine what its contents are. If an argument appears to be ASCII, file examines the first 512 bytes and tries to guess its language. OPTIONS -f If the -f flag is used, file assumes that the filename given next on the command line is a file con- taining a list of files, and operates on each file listed. EXAMPLE The example illustrates the use of file on all the files in a specific user’s directory: % pwd /usr/henry/misc %ls bensusan fortran.mss messages romero toolkit.tr command.list jokes pascalmss squash useful.news counts letters play.msstech.papers v7 .stuff deuter memos roadmap.mss titles window % file * bensusan: roff, nroff, or eqn input text command.list: roff, nroff, or eqn input text counts: ascii text deuter: roff, nroff, or eqn input text fortran.mss: roff, nroff, or eqn input text jokes: directory letters: directory memos: directory messages: directory pascal.mss: roff, nroff, or eqn input text play.mss: roff, nroff, or eqn input text roadmap.mss: roff, nroff, or eqn input text romero: roff, nroff, or eqn input text squash: directory tech.papers: directory titles: ascii text toolkit.tr: roff, nroff, or eqn input text useful.news: directory v7. stuff: archive window: directory % BUGS file often makes mistakes. In particular, it often suggests that command files are C programs. Does not recognize Pascal or LISP. Sun Release 3.0 Last change: 13 November 1984 121 FIND(l) USER COMMANDS FIND ( 1 ) NAME find - find files SYNOPSIS find pathname-list expression DESCRIPTION find, recursively descends the directory hierarchy for each pathname in the pathname-list (that is, one or more pathnames) seeking files that match a boolean expression written in the primaries given below. In the descriptions, the argument n is used as a decimal integer where +n means more than n, -n means less than n, and n means exactly n. -fstype type True if the filesystem to which the the file belongs is of type type, where type is typically 4.2 or nfs -name filename True if the filename argument matches the current file name. Normal Shell argument syntax may be used if escaped (watch out for ‘[\ *?’ and “*’)• -perm onum True if the file permission flags exactly match the octal number onum (see chmod(l)). If onum is prefixed by a minus sign, more flag bits (017777, see chmod{ 1)) become significant and the flags are compared: (flags&onum)==onum . -prune Always returns true. Has the side effect of pruning the search tree at the file. That is, if the current path name is a directory, find will not descend into that directory. -type c True if the type of the file is c, where c is one of: b for block special file, c for character special file, d for directory, f for plain file, or 1 for symbolic link. -links n True if the file has n links. -user uname True if the file belongs to the user unarm (login name or numeric user ID). -group gname True if the file belongs to group gname (group name or numeric group ID). -size n True if the file is n blocks long (512 bytes per block). -inum n True if the file has inode number n. -atime n True if the file has been accessed in n days. -mtime n True if the file has been modified in n days. -exec command True if the executed command returns a zero value as exit status. The end of the com- mand must be punctuated by an escaped semicolon. A command argument *{}’ is replaced by the current pathname. -ok command Like -exec except that the generated command is written on the standard output, then the standard input is read and the command executed only upon response y. -print Always true; the current pathname is printed. " .nr )I file"n -newer True if the current file has been modified more recently than the argument file. The primaries may be combined using the following operators (in order of decreasing precedence): (...) A parenthesized group of primaries and operators (parentheses are special to the Shell and must be escaped). Iprimary The negation of a primary (‘P is the unary not operator). 122 Last change: 23 September 1985 Sun Release 3.0 FIND(l) USER COMMANDS FIND ( 1 ) primary primary Concatenation of primaries (the and operation is implied by the juxtaposition of two primaries). primary -o primary Alternation of primaries (‘-o’ is the or operator). EXAMPLE In our local development system, we keep a file called TIMESTAMP in all the manual page directories. Here is how to find all entries that have been updated since TIMESTAMP was created: angel% find /usi7man/man2 -newer /usr/man/man2/TIMESTAMP -print /usr/man/man2 /usr/man/man2/sockeL2 /usr/man/man2/mmap.2 angel% To find all the files called intro.ms starting from the current directory: angel% find . -name intro.ms -print ./manuals/assembler/intro.ms 7manuals/sun.core/intro.ms ./manuals/driver.tut/intro.ms ./manuals/sys.manager/uucp.impl/intro.mss ,/supplements/general.works/unix.introduction/intro.mss ./supplements/programming.tools/sccs/intro.mss angel% To recursively print all files names in the current directory and below, but skipping SCCS directories: angel% find . -name SCCS -prune -o -print angel% To recursively print all files names in the current directory and below, skipping the contents of SCCS direc- tories, but printing out the SCCS directory name: angel% find . -print -name SCCS -prune angel% To remove all files named ‘a.out’ or ‘*.o’ that have not been accessed for a week: angel% find / \( —name a.out — o —name ’*.o’ \) — atime +7 —exec rm ’0’ \; angel% Note that the brace ({ }) characters must be quoted when using the C-Shell. FILES /etc/passwd /etc/group SEE ALSO sh(l), test(l) Sun Release 3.0 Last change: 23 September 1985 123 FMT(l) USER COMMANDS FMT(l) NAME fmt - simple text formatter SYNOPSIS fmt [ -width ] [ — c ] [filename . . . ] DESCRIPTION Fmt is a simple text formatter which reads the concatenation of input files (or standard input if none are given) and produces on standard output a version of its input with lines as long as possible without execeeding width characters. Width defaults to 72. Blank lines and interword spacing is preserved in the output. OPTIONS -width Fill output lines to within width columns. -c Crown margin mode - the first two lines following an empty line retain their indention. Subse- quent non-blank lines are aligned with the second. In normal mode, the spacing at the beginning of the input lines is preserved in the output. Lines retain their separation if the input indenting increases, but may be concatenated otherwise. Fmt is meant to format mail messages prior to sending, but may also be useful for other simple tasks. For instance, in the vi text editor, the command: !}fmt reformats a paragraph, making the lines reasonably even in length. SEE ALSO nroff(l), mail(l) 124 Last change: 3 December 1985 Sun Release 3.0 FOLD ( 1 ) USER COMMANDS FOLD ( 1 ) NAME fold - fold long lines for finite width output device SYNOPSIS fold [ -width ] [ file . • . ] DESCRIPTION Fold the contents of the specified files, or the standard input if no files are specified, breaking the lines to have maximum width width. The default for width is 80. Width should be a multiple of 8 if tabs are present, or the tabs should be expanded using expand (l) before using fold. SEE ALSO expand(l) BUGS Folding may not work correctly if underlining is present Sun Release 3.0 Last change: 27 April 1983 125 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) NAME fontedit - a vfont screen-font editor SYNOPSIS fontedit [ - W [generic_tool_arg ] ] [fontjiame ] DESCRIPTION fontedit is an editor for fixed-width fonts in vfont format whose characters are no taller than 24 pixels (larger characters will not fit completely onto the screen). For a description of y font format, see vfont(5). OPTIONS — W generic Jool_arg fontedit accepts any generic tool argument as described in suntools(l). Otherwise, you can mani- pulate the tool via the Tool Manager Menu. COMMANDS To edit a font, type ‘fontedit’ . A. fontjiame may be supplied on the command line or may be typed into the option subwindow once the program has started. If it exists, the fontjiame file must be in vfont format. When the program starts, it displays a single large window containing four subwindows. >From top to bot- tom, the four subwindows are: 1) The top subwindow, a message subwindow, displays messages, prompts, and warnings. 2) The second subwindow from the top, an option subwindow, allows you to set global parameters for the entire font and specify operations for editing any single character. The options are: (Read) Read in the font specified in the file name field. The program will warn you if you try to read over a modified font. (Save) Write the current font onto disk with the name in file name field. (Exit) Quit the program; warns you if you have modified the font. Font name: The name of the font. Max Width and Max Height: The size, in pixels, of the largest character in the font. If you edit an existing font, these parameters are set automatically; you must set them if you are creating a new font. Changing either of these values for an existing font may alter the glyph of some charac- ters of the font. If the glyph size of a character is larger than the new max size, then that character is clipped to the new size (its bottom and right edges are moved in). However, if a glyph’s size is smaller than the new size, the glyph is left alone. Caps Height and X-Height: The distance, in pixels, between the top of a capital and lowercase letter and the baseline. When an existing font is edited, the values of Caps Height and X-Height are estimated by fontedit, and may require some adjustment. Baseline: The number of pixels from the top (i.e., the upper left comer) of the character to the base- line. For an existing font, the value of the largest baseline distance is used. For a new font, each character will have the same baseline distance. If this value is changed, then the baseline distance for all characters in the font will be the new value. (Apply) Apply the current values of Max Width, Max Height, Caps Height, X-Height, and Baseline to the font. That is, changes made to these values do not take effect until Apply is selected. Operation: This is a list of drawing and editing operations that you can perform on a character. For drawing, the left mouse button draws in black, and the middle draws in white. Operations are: 126 Last change: 10 October 1985 Sun Release 3.0 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) Single Pt Press a mouse button down and a grey cell will appear; move the mouse and the cell will follow it. Releasing the the button will draw. Pt Wipe Pressing a button down will draw and moving with the button down will con- tinue drawing until the button is released. Line Button down marks the end point of a line; moving with the button down rubber bands a line; releasing button draws the line. Rect Like Line except draws a rectangle. Cut Button down marks one end of rectangle, and moving rubber bands the out- line of the rectangle. Button up places the contents of the rectangle into a buffer and then “cuts” (draws in white) the rectangular region from the character. The Paste operation (below) gets the data from the buffer. Copy Like Cut except that the region is just copied; no change is made to the char- acter. Paste Button down displays a rectangle the size of the region in the buffer. Moving with the button down moves the rectangle. Button up pastes the contents of the buffer into the character. The contents of the paste buffer cannot be transferred between tools. In Copy or Cut mode, holding down the shift key while pressing the left or middle mouse button will perform a Paste action. For best results, after plac- ing a region in the buffer, press down the shift key and hold it down, then press down the mouse button. Release the mouse key to paste the region and then release the shift key. 3) The third subwindow echoes the characters in the current font as they are typed. Note that the cursor must be in this window in order to see the characters. Your character delete key will delete the echoed characters. 4) The bottom subwindow, the editing subwindow, displays eight smaller squares at its top; these are called edit buttons. The top section of each of these buttons contains a line of text in the form nnn: c, where nnn is the hexadecimal number of the character and c is the standard ASCII character corresponding to that number. In the lower section of the button the character of the current font, if it exists, is displayed. Clicking once over an editing button selects its character for editing. Just below this row of buttons is a box with the characters “0 9 A Z a z” in it This box is called a slider. The slider allows you to scroll around in the font and select which section of the font you want displayed in the edit buttons. The black rectangle near “a” is an indicator which shows the section of the font that is displayed in the buttons above. To move the indicator, select it by pressing the left or middle mouse button down over the indicator and then move the mouse to the left or right with the button down; the indicator will slide along with the cursor. Releasing the button selects the new sec- tion of the font. A faster method of moving about in the font is to just press down and release the mouse button above the area you want without bothering to drag the indicator. Another method of scrolling through the characters of the font is to press a key on the keyboard when the cursor is in the bottom window; that character is the first one displayed in die edit buttons. EDITING CHARACTERS: To edit a character, click once over the edit button where the character is displayed. When you do this, an edit pad will appear in the bottom subwindow. The edit pad consists of an editing area bordered by scales, a proof area, and 3 command buttons. The edit- ing area is Max Width by Max Height when the pad opens, and displays a magnified view of the selected character. Black squares indicate foreground pixels. The editing area is surrounded by scales which show the current Caps Height, X-Height and Baseline in reverse video. Sun Release 3.0 Last change: 10 October 1985 127 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) Just outside the scales, on the top, right side, and bottom of the pad, are three small boxes with the capital letters "R", "B", and "A" in them. These boxes are movable sliders that change the right edge, bottom edge, and x-axis advance of the character respectively. In a fixed-width font, these values are usually the same for all characters; however, in a variable- width font these controls can be used to set these properties for each character. To the right of the pad is the proof area where the character is displayed at normal (that is, screen) resolu- tion and three buttons. The three buttons are: Undo Clicking the left or middle mouse button undoes the last operation. Save Stores the current representation of the character in the font. Quit Closes the edit pad. In the bottom subwindow, the right mouse button displays a menu of operations. These operations are the same as those in the option subwindow discussed above; you can select the current operation by either picking the operation in the option subwindow or by selecting the appropriate menu with the left button of the mouse. When the cursor is in the other subwindows, the left button displays the standard tool menu. FILES /usrlliblfontslfixedwidthfonts- Sun-supplied screen fonts SEE ALSO suntools(l), vfont (5), vswap(l) BUGS Results are unpredictable with variable-width fonts. The baseline should be greater than 0 or else the font cannot be read in by fontedit or by suntools. 128 Last change: 10 October 1985 Sun Release 3.0 FPR(l) USER COMMANDS FPR(l) NAME fpr - print FORTRAN file SYNOPSIS fpr DESCRIPTION fpr transforms files formatted according to FORTRAN’S carriage control conventions into files formatted according to UNIX line printer conventions. Fpr copies its input onto its output, replacing the carriage control characters with characters that will pro- duce the intended effects when printed using lpr( 1). The first character of each line determines the vertical spacing as follows: (blank) one line 0 two lines 1 to first line of next page + no advance A blank line (that is, an empty line) is treated as if its first character is a blank. A blank that appears as a carriage control character is deleted. A zero is changed to a newline. A one is changed to a form feed. The effects of a "+" are simulated using backspaces. Note that fpr is known as asa in UNIX System V. EXAMPLES a.out | fpr | lpr fpr < f77. output | lpr BUGS Results are undefined for input lines longer than 170 characters. Sun Release 3.0 Last change: 24 October 1983 129 FROta(l) USER COMMANDS FROM ( 1 ) NAME from - who is my mail from? SYNOPSIS from [ -s sender ] [ user ] DESCRIPTION From prints out the mail header lines in your mailbox file to show you who your mail is from. If user is specified, then user’s mailbox is examined instead of your own. OPTIONS -s sender Only display headers for mail sent by sender. FILES /usr/spool/mail/* SEE ALSO biff(l), mail(l), prmail(l) 130 Last change: 27 April 1983 Sun Release 3.0 FSPLIT ( 1 ) USER COMMANDS FSPLIT ( 1 ) NAME fsplit - split a multi-routine FORTRAN file into individual files SYNOPSIS fsplit [ -e efile] ... [ file ] DESCRIPTION Fsplit takes as input either a file or standard input containing FORTRAN source code. It attempts to split the input into separate routine files of the form name.f, where name is the name of the program unit (func- tion, subroutine, block data or program). The name for unnamed block data subprograms has the form blkdtaNNN.f where NNN is three digits and a file of this name does not already exist. For unnamed main programs the name has the form mainNNN.f. If there is an error in classifying a program unit, or if name.f already exists, the program unit will be put in a file of the form zzzNNN.f where zzzNNN.f does not already exist. Normally each subprogram unit is split into a separate file. When the -e option is used, only the specified subprogram units are split into separate files. E.g.: fsplit -e readit -e doit prog.f will split readit and doit into separate files. DIAGNOSTICS If names specified via the -e option are not found, a diagnostic is written to standard error. BUGS Fsplit assumes the subprogram name is on the first noncomment line of the subprogram unit Nonstandard source formats may confuse fsplit. It is hard to use -e for unnamed main programs and block data subprograms since you must predict the created file name. Sun Release 3.0 Last change: 24 August 1983 131 FTP(IC) USER COMMANDS FTP(IC) NAME ftp - file transfer program SYNOPSIS ftp [ -v ] [-d] [ -i ] [ -n ] [ -g ] [ -t ] [ host ] DESCRIPTION ftp is the user interface to the ARPANET standard File Transfer Protocol, ftp transfers files to and from a remote network site. The client host with which ftp is to communicate may be specified on the command line. If this is done,///? immediately attempts to establish a connection to an FTP server on that host; otherwise,///? enters its com- mand interpreter and awaits instructions from the user. When ftp is awaiting commands from the user, it displays the prompt “ftp>”. OPTIONS Options may be specified at the command line, or to the command interpreter. -v show all responses from the remote server, as well as report on data transfer statistics. This is turned on by default if ftp is running interactively with its input coming from the user’s terminal. -n do not attempt “auto-login” upon initial connection. If auto-login is enabled, ftp checks the .netrc file in the user’s home directory for an entry describing an account on the remote machine. If no entry exists, ftp uses the login name on the local machine as the user identity on the remote machine, and prompts for a password and, optionally, an account with which to login. -i turn off interactive prompting during multiple file transfers. -g disable filename "globbing." -d enable debugging. -t enable packet tracing (unimplemented). COMMANDS ! [ command ] Run command as a shell command on the local machine. If no command is given, invoke an interactive shell. append local-file [ remote-file ] Append a local file to a file on the remote machine. If remote-file is left unspecified, the local file name is used in naming the remote file. File transfer uses the current settings for “representation type”, “file structure”, and “transfer mode”. ascii Set the “representation type” to “network ASCII”. This is the default type. bell Arrange that a bell be sounded after each file transfer command is completed. binary Set the ‘ ‘representation type’ ’ to ‘ ‘image’ ’ . bye Terminate the FTP session with the remote server and exit ftp. cd remote-directory Change the working directory on the remote machine to remote-directory . close Terminate the FTP session with the remote server, and return to the command interpreter, delete remote-file Delete the file remote-file on the remote machine, debug [ debug-value ] Toggle debugging mode. If an optional debug-value is specified it is used to set the debugging level. When debugging is on, ftp prints each command sent to the remote machine, preceded by the string dir [ remote-directory ] [ local-file ] 132 Last change: 5 December 1985 Sun Release 3.0 FTP ( 1C ) USER COMMANDS FTP(IC) Print a listing of the directory contents in the directory, remote-directory, and, optionally, placing the output in local-file. If no directory is specified, the current working directory on the remote machine is used. If no local file is specified, or local-file is — , output comes to the terminal, form [ format-name ] Set the carriage control format subtype of the “representation type” to format-name . The only vaMformat-name is non-print, which corresponds to the default “non-print” subtype. get remote-file [ local-file ] Retrieve the remote-file and store it on the local machine. If the local file name is not specified, it is given the same name it has on the remote machine. The current settings for “representation type”, “file structure”, and “transfer mode” are used while transferring the file. glob Toggle filename expansion, or "globbing", for mdelete, mget and input. If globbing is turned off, filenames are taken literally. Globbing for input is done as in csfi(l). For mdelete and mget, each remote file name is expanded separately on the remote machine, and the lists are not merged. Expansion of a directory name is likely to be radically different from expansion of the name of an ordinary file: the exact result depends on the remote operating system and FTP server, and can be previewed by doing ‘mis remote-files mget and mput are not meant to transfer entire directory subtrees of files. You can do this by transferring a tar{ 1) archive of the subtree (using a “representation type” of “image” as set by the binary command). hash Toggle hash-sign (“#”) printing for each data block transferred. The size of a data block is 1024 bytes. help [ command ] Print an informative message about the meaning of command. If no argument is given, ftp prints a list of the known commands. led [ directory ] Change the working directory on the local machine. If no directory is specified, the user’s home directory is used. Is [ remote-directory ] [ local-file ] Print an abbreviated listing of the contents of a directory on the remote machine. If remote- directory is left unspecified, the current working directory is used. If no local file is specified, or if local-file is -, the output is sent to the terminal. mdelete [ remote-files ] Delete the remote-files on the remote machine. mdir remote-files local-file Like dir, except multiple remote files may be specified, mget remote-files Expand the remote-files on the remote machine and do a get for each file name thus produced. See glob for details on the filename expansion. Files are transferred into the local working direc- tory, which can be changed with ‘led directory’-, new local directories can be created with ‘! mkdir directory ’ . mkdir directory-name Make a directory on the remote machine. mis remote-files local-file Like Is, except multiple remote files may be specified, mode [ mode-name ] Set the “transfer mode” to mode-name. The only valid mode-name is stream, which Sun Release 3.0 Last change: 5 December 1985 133 FTP(IC) USER COMMANDS FTP(IC) corresponds to the default “stream” mode, mput local-files Expand wild cards in the list of local files given as arguments and do a put for each file in the resulting list See glob for details of filename expansion. open host [ port ] Establish a connection to the specified host FTP server. An optional port number may be sup- plied, in which case, ftp will attempt to contact an FTP server at that port. If the auto-login option is on (default), ftp will also attempt to automatically log the user in to the FTP server (see below). prompt Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to allow the user to selectively retrieve or store files. By default, prompting is turned on. If prompting is turned off, any mget or mput will transfer all files, and any mdelete will delete all files. put local-file [ remote-file ] Store a local file on the remote machine. If remote-file is left unspecified, the local file name is used in naming the remote file. File transfer uses the current settings for “representation type”, “file structure”, and “transfer mode”. pwd Print the name of the current working directory on the remote machine, quit A synonym for bye. quote argl arg2 ... Send the arguments specified, verbatim, to the remote FTP server. A single FTP reply code is expected in return. recv remote-file [ local-file ] A synonym for get. remotehelp [ command-name ] Request help from the remote FTP server. If a command-name is specified it is supplied to the server as well. rename from to Rename the file from on the remote machine to have the name to. rmdir directory-name Delete a directory on the remote machine. send local-file [ remote-file ] A synonym for put. sendport Toggle the use of PORT commands. By default, ftp will attempt to use a PORT command when establishing a connection for each data transfer. If the PORT command fails, ftp will use the default data port When the use of PORT commands is disabled, no attempt will be made to use PORT commands for each data transfer. This is useful for certain FTP implementations which ignore PORT commands but incorrectly indicate they’ve been accepted. status Show the current status of ftp . struct [ struct-name ] Set the “file structure” to struct-name. The only valid struct-name is file, which corresponds to the default “file” structure. tenex Set the ‘ ‘representation type’ ’ to that needed to talk to TENEX machines, trace Toggle packet tracing (unimplemented), type [ type-name ] Set the “representation type” to type-name. The valid type-names are ascii for “network ASCII”, binary or image for “image”, and tenex for “local byte size” with a byte size of 8 134 Last change: 5 December 1985 Sun Release 3.0 FTP(IC) USER COMMANDS FTP(IC) (used to talk to TENEX machines). If no type is specified, the current type is printed. The default type is “network ASCII”. user user-name [ password ] [ account ] Identify yourself to the remote FTP server. If the password is not specified and the server requires it, ftp will prompt the user for it (after disabling local echo). If an account field is not specified, and the FTP server requires it, the user will be prompted for it. Unless/t/? is invoked with “auttv login” disabled, this process is done automatically on initial connection to the FTP server. verbose Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the user. In addition, if verbose mode is on, when a file transfer completes, statistics regarding the efficiency of the transfer are reported. By default, verbose mode is on \f ftp’s commands are com- ing from a terminal, and off otherwise. ? [ command ] A synonym for help. Command arguments which have embedded spaces may be quoted with quote (") marks. If any command argument which is not indicated as being optional is not specified, ftp will prompt for that argument. FILE NAMING CONVENTIONS Local files specified as arguments to ftp commands are processed according to the following rales. 1) If the file name is specified, the standard input (for reading) or standard output (for writing) is used. 2) If the first character of the file name is the remainder of the argument is interpreted as a shell command, ftp then forks a shell, using popen (3S) with the argument supplied, and reads (writes) from the standard output (standard input) of that shell. If the shell command includes spaces, the argument must be quoted; e.g. | Is -It"”. A particularly useful example of this mechanism is: “dir|more”. 3) Failing the above checks, if “globbing” is enabled, local file names are expanded according to the rales used in the cj/j(1); c.f. the glob command. Note that remote file names are not processed, but are passed just as they are typed, except for the mdelete, mdir, mget, and mis commands, where they are expanded according to the rales of the remote host’s operating system, if any. FILE TRANSFER PARAMETERS The FTP specification specifies many parameters which may affect a file transfer. The “representation type” may be one of “network ASCII”, “EBCDIC”, “image”, or “local byte size” with a specified byte size (for PDP-lO’s and PDP-20’s mostly). The “network ASCII” and “EBCDIC” types have a further subtype which specifies whether vertical format control (newlines, form feeds, etc.) are to be passed through (“non-print”), provided in TELNET format (“TELNET format controls”), or pro- vided in ASA (FORTRAN) (“carriage control (ASA)”) format, ftp supports the “network ASCII” (sub- type non-print” only) and “image” types, plus “local byte size” with a byte size of 8 for communicat- ing with TENEX machines. The “file structure” may be one of “file” (no record structure), “record”, or “page”, ftp supports only the default value, which is “file”. The “transfer mode” may be one of “stream”, “block”, or “compressed”, ftp supports only the default value, which is “stream”. SEE ALSO rcp(l), ftpd(8c) Sun Release 3.0 Last change: 5 December 1985 135 FTP(IC) USER COMMANDS FTP(IC) BUGS Many FTP server implementations do not support experimental operations such as print working directory. VAX sites running the BBN FTP server appear to ignore the PORT command while indicating complicity; this locks up all file transfers. 136 Last change: 5 December 1985 Sun Release 3.0 GCORE(l) USER COMMANDS GCORE(l) NAME gcore - get core images of running processes SYNOPSIS gcore process-id. . . . DESCRIPTION gcore creates a core image of each specified process. Such an image can be used with adb or dbx. For best results, stop the process before running gcore to avoid confusion from paging activity. FILES core. core images SEE ALSO kill(l), csh(l), adb(l), dbx(l) Sun Release 3.0 Last change: 3 December 1985 137 GET ( 1 ) USER COMMANDS GET ( 1 ) NAME get - get a version of an SCCS file SYNOPSIS /usr/sccs/get [ -r SID ] [ -c cutoff] [ -i list ] [ -x list ] [ -a seq-no. ] [ -k ] [ -e ] [ -1 [ p ] ] [ -p ] [ -m ] [ -n ] [ -s ] [ -b ] [ -g ] [ -t ] filename . . . DESCRIPTION get generates an ASCII text file from each named SCCS file according to the specified option. Arguments may be specified in any order, options apply to all named SCCS files. If a directory is named, get behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last com- ponent of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is taken to be the name of an SCCS file to be processed. Again, non-SCCS files and unreadable files are silendy ignored. The generated text is normally written into a file called the g-file whose name is derived from the SCCS file name by simply removing the leading s.; (see also FILES, below). OPTIONS Opdons are explained below as though only one SCCS file is to be processed, but the effects of any opdon argument applies independently to each named file. -r SID The 5 CCS TDentification string (SID) of the version (delta) of an SCCS file to be retrieved. Table 1 below shows, for the most useful cases, what version of an SCCS file is retrieved (as well as the SID of the version to be eventually created by delta if the -e option is also used), as a function of the SID specified. -c cutoff Cutoff date-time, in the form; YY[ MM[ DD[ HH[ MM[ SS ] ] ] ] ] No changes (deltas) to the SCCS file which were created after the specified cutoff date-time are included in the generated ASCII text file. Units omitted from the date-time default to their max- imum possible values; that is, — c7502 is equivalent to — c750228235959. Any number of non- numeric characters may separate the various 2 digit pieces of the cutoff date-time. This feature allows one to specify a cutoff date in the form: -ell 1212 9:22:25. Note that this implies that one may use the %E% and %U% identification keywords. -e This get is for editing or making a change (delta) to the SCCS file via a subsequent use of delta . A /usr/sccs/get — e applied to a particular version (SID) of the SCCS file prevents further /usr/sccs/get -e commands on the same SID until delta is run or the j (joint edit) flag is set in the SCCS file (see admin{ 1)). Concurrent use of /usr/sccs/get -e for different SIDs is always allowed. If the g-file generated by a /usr/sccs/get -e is accidentally ruined in the process of editing it, it may be regenerated by re-running a get with the — k option in place of the — e option. SCCS file protection specified via the ceiling, floor, and authorized user list stored in the SCCS file (see adminll)) are enforced when the -e option is used. -b Used with the -e option to indicate that the new delta should have an SID in a new branch as shown in Table 1. This option is ignored if the b flag is not present in the file (see admin{ 1)) or if the retrieved delta is not a leaf delta. (A leaf delta is one that has no successors on the SCCS file tree.) Note: A branch delta may always be created from a non-leaf delta. -Hist A list of deltas to be included (forced to be applied) in the creation of the generated file. The list has the following syntax: ::= | , ::= SID | SID - SID SID, the SCCS Identification of a delta, may be in any form shown in the ‘SID Specified’ column of 138 Last change: 23 September 1985 Sun Release 3.0 GET(l) USER COMMANDS GET ( 1 ) Table 1. Partial SIDs are interpreted as shown in the ‘SID Retrieved’ column of Table 1. -x list A to of deltas to be excluded (forced not to be applied) in the creation of the generated file. See the — i option for the list format. -k Suppress replacement of identification keywords (see below) in the retrieved text by their value The -k option is implied by the -e option. -1 [ p ] Write a delta summary into an l-file . If -Ip is used, the delta summary is written on the standard output and the l-file is not created. See FILES for the format of the l-file. -P Write the text retrieved from the SCCS file to the standard output No g-file is created. All output which normally goes to the standard output goes to the standard error file instead, unless the -s option is used, in which case it disappears. -s Suppress all output normally written on the standard output. However, fatal error messages (which always go to the standard error file) remain unaffected. -m Precede each text line retrieved from the SCCS file with the SID of the delta that inserted the text line in the SCCS file. The format is: SID, followed by a horizontal tab, followed by the text line. — n Precede each generated text line with the %M% identification keyword value (see below). The format is: %M% value, followed by a horizontal tab, followed by the text line. When both the -m and -n options are used, the format is: %M% value, followed by a horizontal tab, followed by the -m option generated format. -g Do not actually retrieve text from the SCCS file. It is primarily used to generate an l-file , or to ver- ify the existence of a particular SID. -t Access the most recently created (‘top’) delta in a given release (for example, -rl), or release and level (for example, -rl.2). —a seq-no. The delta sequence number of the SCCS file delta (version) to be retrieved (see sccsfile (5)). This option is used by the comb command; it is not a generally useful option, and users should not use it If both the -r and -a options are specified, the -a option is used. Care should be taken when using the -a option in conjunction with the -e option, as the SID of the delta to be created may not be what one expects. The — r option can be used with the —a and — e options to control the naming of the SID of the delta to be created. For each file processed, get responds (on the standard output) with the SID being accessed and with the number of lines retrieved from the SCCS file. If the -e option is used, the SID of the delta to be made appears after the SID accessed and before the number of lines generated. If there is more than one named file or if a directory or standard input is named, each file name is printed (preceded by a new-line) before it is processed. If the -i option is used included deltas are listed following the notation ‘Included’; if the — x option is used, excluded deltas are listed fol- lowing the notation ‘Excluded’. Sun Release 3.0 Last change: 23 September 1985 139 GET ( 1 ) USER COMMANDS GET ( 1 ) TABLE 1. Determination of SCCS Identification String SID* -b Option Other SID SID of Delta Specified Usedt Conditions Retrieved to be Created none! no R defaults to mR mR.mL mR.(mL+l) none$ yes R defaults to mR mR.mL mR.mL.(mB+l).l R no R > mR mR.mL R.l*** R no R = mR mR.mL mR.(mL+l) R yes R > mR mR.mL mR.mL.(mB+l).l R yes R = mR mR.mL mR.mL.(mB+l).l R - R < mR and R does not exist hR.mL** hR.mL.(mB+l).l R — Trunk succ.# in release > R and R exists R.mL R.mL.(mB+l).l R.L no No trunk succ. R.L R.(L+1) R.L yes No trunk succ. R.L R.L.(mB+l).l R.L - Trunk succ. in release > R R.L R.L.(mB+l).l R.L.B no No branch succ. RU.B.mS R.L.B.(mS+l) R.L.B yes No branch succ. R.L.B.mS R.L.(mB+l).l R.L.B.S no No branch succ. R.L.B.S R.L.B.(S+1) R.L.B.S yes No branch succ. R.L.B.S R.L.(mB+l).l R.L.B.S - Branch succ. R.L.B.S R.L.(mB+l).l * ‘R’ ‘L’, ‘B’, and ‘S’ are the ‘release’, ‘level’, ‘branch’, and ‘sequence’ components of the SID, respectively; ‘m’ means ‘maximum’. Thus, for example, ‘R.mL’ means ‘the maximum level number within release R’; ‘R.L.(mB+l).l’ means ‘the first sequence number on the new branch (that is, maximum branch number plus one) of level L within release R’. Note that if the SID specified is of the form ‘R.L’, ‘R.L.B’, or ‘R.L.B.S’, each of the specified components must exist ** ‘hR’ is the highest existing release that is lower than the specified, nonexistent, release R. *** Forces creation of the first delta in a new release. # Successor. f The — b option is effective only if the b flag (see admin (l)) is present in the file. An entry of — means ‘irrelevant’. $ This case applies if the d (default SID) flag is not present in the file. If the d flag is present in the file, the SID obtained from the d flag is interpreted as if it had been specified on the command line. Thus, one of the other cases in this table applies. IDENTIFICATION KEYWORDS Identifying information is inserted into the text retrieved from the SCCS file by replacing identification key- words with their value wherever they occur. The following keywords may be used in the text stored in an SCCS file: Keyword Value %M% Module name: either the value of the m flag in the file (see admin( 1)), or if absent, the name of the SCCS file with the leading s. removed. %l% SCCS identification (SID) (%R%.%L%.%B%.%S%) of the retrieved text. %R% Release. %L% Level. 140 Last change: 23 September 1985 Sun Release 3.0 GET ( 1 ) USER COMMANDS GET ( 1 ) %B% Branch. %S% Sequence. % D % Current date ( YY/MM/DD). %H% Current date (MM/DD/YY). %T% Current time (HH:MM:SS). %E% Date newest applied delta was created (YY/MM/DD). %G% Date newest applied delta was created (MM/DD/YY). % U% Time newest applied delta was created (HH:MM:SS). % Y % Module type: value of the t flag in the SCCS file (see admin(l)). % F % SCCS file name. %P% Fully qualified SCCS file name. %Q% The value of the q flag in the file (see admin (1)). %C% Current line number. This keyword is intended for identifying messages output by the program such as ‘this shouldn’t have happened’ type errors. It is not intended to be used on every line to provide sequence numbers. % Z % The 4-character string @(#) recognizable by what. %W% A shorthand notation for constructing what strings for UNIX program files. %W% = %Z%%M%%I% %A% Another shorthand notation for constructing what strings for non-UNIX program files %A% = %Z%%Y% %M% %1%%Z% FILES Several auxiliary files may be created by get, These files are known generically as the g-file, l-file, p-file, and z-file. The letter before the hyphen is called the tag. An auxiliary file name is formed from the SCCS file name, the last component of all SCCS file names must be of the form sjnodule-name, the auxiliary files are named by replacing the leading s with the tag. The g-file is an exception to this scheme: the g-file is named by removing the s. prefix. For example, s.xyz.c, the auxiliary file names would be xyz.c, ljcyz.c, p.xyz.c, and z.xyz.c, respectively. The g-file, which contains the generated text, is created in the current directory (unless the -p option is used). A g-file is created in all cases, whether or not any lines of text were generated by the get. It is owned by the real user. If the -k option is used or implied its mode is 644; otherwise its mode is 444. Only the real user need have write permission in the current directory. The l-file contains a table showing which deltas were applied in generating the retrieved text The l-file is created in the current directory if the -1 option is used; its mode is 444 and it is owned by the real user. Only the real user need have write permission in the current directory. Lines in the l-file have the following format: a. A blank character if the delta was applied; * otherwise. b. A blank character if the delta was applied or wasn’t applied and ignored; * if the delta wasn’t applied and wasn’t ignored. c. A code indicating a ‘special’ reason why the delta was or was not applied: ‘I’: Included. ‘X’: Excluded. ‘C’: Cut off (by a -c option). d. Blank. e. SCCS identification (SID). f. Tab character. g. Date and time (in the form YY/MM/DD HH:MM:SS) of creation. h. Blank. i. Login name of person who created delta. The comments and MR data follow on subsequent lines, indented one horizontal tab character. A blank line terminates each entry. Sun Release 3.0 Last change: 23 September 1985 141 GET ( 1 ) USER COMMANDS GET ( 1 ) The p-file passes information resulting from a /usr/sccs/get -e along to delta. Its contents are also used to prevent a subsequent execution of a /usr/sccs/get -e for the same SID until delta is executed or the joint edit flag, j, (see admin( 1)) is set in the SCCS file. The p-file is created in the directory containing the SCCS file and the effective user must have write permission in that directory. Its mode is 644 and it is owned by the effective user. The format of the p-file is: the gotten SID, followed by a blank, followed by the SID that the new delta will have when it is made, followed by a blank, followed by the login name of the real user, followed by a blank, followed by the date-time the get was executed, followed by a blank and the — i option if it was present, followed by a blank and the — x option if it was present, followed by a new-line. There can be an arbitrary number of lines in the p-file at any time; no two lines can have the same new delta SID. The 2 -file serves as a lock-out mechanism against simultaneous updates. Its contents are the binary (2 bytes) process ID of the command (that is, get) that created it. The z-file is created in the directory contain- ing the SCCS file for the duration of get. The same protection restrictions as those for the p-file apply for the z-file. The z-file is created mode 444. SEE ALSO sccs(l), admin(l), delta(l), help(l), prs(l), what(l), sccsfile(5) Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help for explanations. BUGS If the effective user has write permission (either explicitly or implicitly) in the directory containing the SCCS files, but the real user doesn’t, only one file may be named when the -e option is used. 142 Last change: 23 September 1985 Sun Release 3.0 GETSELECTION ( 1 ) USER COMMANDS GETjSELECTION ( 1 ) NAME get_selection - copy the contents of a SunView selection to standard out SYNOPSIS get_selection [1 1 2 1 3 ] DESCRIPTION get ^selection prints the contents of the indicated selection on standard out A selection is a collection of objects (e.g. characters) picked with the mouse in the SunView window system. OPTIONS The optional argument indicates which selection is to be printed: -1 is primary, -2 is secondary -3 is shelf. The default is primary. EXAMPLE The following line in a SunView root menu file provides a menu command to print the primary selection on the user’s default printer: "Print It" csh -c "get_selection 1 1 lpr" (Specify your SunView root menu as the value of the Rootmenu Jilename parameter in defaultsedit(l)). Sun Release 3.0 Last change: 26 December 1985 143 GFXTOOL ( 1 ) USER COMMANDS GFXTOOL ( 1 ) NAME gfxtool - Run graphics programs in the SunWindows environment SYNOPSIS gfxtool [ -C ] [ program [ arguments ] ] OPTIONS -C Redirect system console output to this instance of gfxtool. gfxtool also accepts all of the generic tool arguments; see suntools(l) for a list of these arguments. If a program argument is present, gfxtool runs it. If there are no arguments, gfxtool runs the program corresponding to your shell environment variable. If this environment variable is not available, then gfxtool runs /bin/sh. DESCRIPTION gfxtool is a standard tool provided with SunWindows. It allows you to run graphics programs that don’t overwrite the terminal emulator from which they run. gfxtool has two subwindows: a terminal subwindow and an empty subwindow. The terminal subwindow contains a running shell, just like the shelltool (see shelltool(l)). Programs invoked in the terminal subwin- dow can run in the empty sub window. You can move the boundary between these two subwindows as described in suntools(l) under The Tool Manager. If you wish, you can make gfxtool your console by entering a first argument of -C. Normally you can use the mouse and keyboard anywhere in the empty subwindow to access Tool Manager functions. However, some graphics programs which run in this window may take over inputs directed to it. For example, SunCore uses the mouse and keyboard for its own input. When you run such tools, access the Tool Manager menu from the tool boundaries or namestripe. Most of the graphics demo programs in /usr/demo will run in gfxtool. In particular, the following demos run in gfxtool: /usr/demo/bouncedemo Displays a bouncing square. Place a -n followed by a decimal number on the command line to indicate how many repetitions of the bounce sequence should be done. /usr/demo/spheresdemo Laboriously computes a random collection of shaded spheres. Place a -n followed by a decimal number on the command line to indicate how many spheres should be drawn. Colored spheres are drawn on color displays. /usr/demo/jumpdemo Simulates the famous Star Wars jump to light-speed sequence using vector drawing. Place a -n followed by a decimal number up to 500 to indicate how many stars should be used in the star field. Colored stars are drawn on color displays. A -c on the command line directs the program to rotate the color map, thus producing a sparkling effect /usr/demo/framedemo Displays a series of frames, each of which contains a 256 by 256 image formed of pixels one deep (that is, the image is a square monochrome bitmap, with 256 bits on a side). The frames must be in the files framed through frame. n on the current working directory, and are displayed in numeri- cal order. A set of sample frames is available to you in the directory lusrldemol globeframes/* . Put a -n followed by a decimal number on the command line to indicate how many times to cycle through the frames. If you move the cursor into the image window, you can type certain charac- ters to affects the rate at which the frames are displayed. The initial rate is one frame per second. Typing “S” causes an additional one second delay between frames. Typing “F” removes one second from the inter-frame delay. Typing “s” adds l/20th of a second. Typing “f ’ removes l/20th of a second. Typing “Ff” makes the delay as small as possible. 144 Last change: 29 March 1985 Sun Release 3.0 GFXTOOL ( 1 ) USER COMMANDS GFXTOOL ( 1 ) For all these demos the following is true: if no -n flag appears on the command line then the program runs continuously until you interrupt it. A -r flag on the command line turns the window into a retained win- dow. This allows the image to reappear when uncovered instead of restarting the demo. You can also invoke all these demos from the workstation console, i.e., outside of the suntools window environment. A -d flag followed by a display device name as in "bouncedemo -d /dev/cgoneO” directs the demo to run on a display other than the console. SEE ALSO suntools (1) shelltool{ 1) FILES '/.ttyswrc /usr/bin/gfxtool /usr/bin/suntools /usr/demo/* /usr/src/sun/suntool/gfxtool.c BUGS If more than 256 characters are input to a terminal emulator subwindow without an intervening newline, the terminal emulator may hang. If this occurs, display the Tool Manager Menu; the "TTY Hung?" sub- menu there has one item, "Flush input", that you can invoke to correct the problem. Sun Release 3.0 Last change: 29 March 1985 145 GPROF(l) USER COMMANDS GPROF(l) NAME gprof — display call-graph profile data SYNOPSIS gprof [ -a ] [ -b ] [ -c ] [ -e name ] [ -E name ] [ -f name ] [ -F name ] [ — s ] [ — z ] [ object-file [ profile-file . . . ] ] DESCRIPTION Gprof produces an execution profile of C, Pascal, or FORTRAN 77 programs. The effect of called routines is incorporated in the profile of each caller. The profile data is taken from the call-graph profile file (gmon.out default) which is created by programs compiled with the -pg option of cc, pc, and/77. That option also links in versions of the library routines which are compiled for profiling. The symbol table in the named object file (a.out default) is read and correlated with the call-graph profile file. If more than one profile file is specified, the gprof output shows the sum of the profile information in the given profile files. First, a flat profile is given, similar to that provided by prof( 1). This listing gives the total execution times and call counts for each of the functions in the program, sorted by decreasing time. Next, these times are propagated along the edges of the call-graph. Cycles are discovered, and calls into a cycle are made to share the time of the cycle. A second listing shows the functions sorted according to the time they represent, including the time of their call graph descendants. Below each function entry is shown its (direct) call-graph children, and how their times are propagated to this function. A similar display above the function shows how this function’s time and the time of its descendants is propagated to its (direct) call-graph parents. Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and their contributions to the time and call counts of the cycle. Beware of quantization errors. The granularity of the sampling is shown, but remains statistical at best. It is assumed that the time for each execution of a function can be expressed by the total time for the function divided by the number of times the function is called. Thus the time propagated along the call-graph arcs to parents of that function is directly proportional to the number of times that arc is traversed. The profiled program must call exit (2) or return normally for the profiling information to be saved in the gmon.out file. OPTIONS -a suppress printing statically declared functions. If this option is given, all relevant information about the static function (for instance, time samples, calls to other functions, calls from other func- tions) belongs to the function loaded just before the static function in the a. out file. -b display a description of each field in the profile. -c the static call-graph of the program is discovered by a heuristic which examines the text space of the object file. Static-only parents or children are indicated with call counts of 0. -e name suppress printing the graph profile entry for routine name and all its descendants (unless they have other ancestors that aren’t suppressed). More than one — e option may be given. Only one name may be given with each -e option. -E name suppress printing the graph profile entry for routine name (and its descendants) as -e, above, and also exclude the time spent in name (and its descendants) from the total and percentage time com- putations. More than one -E option may be given. For example, -E mcount -E mcleanup is the default. -f name print the graph profile entry only for routine name and its descendants. More than one — f option may be given. Only one name may be given with each — f option. 146 Last change: 8 October 1984 Sun Release 3.0 GPROF(l) USER COMMANDS GPROF(l) — F name print the graph profile entry only for routine name and its descendants (as -f, above) and also use only the times of the printed routines in total time and percentage computations. More than one -F option may be given. Only one name may be given with each -F option. The -F option over- rides the -E option. produce a profile file gmon.sum which represents the sum of the profile information in all the specified profile files. This summary profile file may be given to subsequent executions of gprcf (probably also with a -s) option to accumulate profile data across several runs of an a. out file. display routines which have zero usage (as indicated by call counts and accumulated time). This is useful in conjunction with the -c option for discovering which routines were never called. the namelist and text space gmon.out dynamic call-graph and profile gmon.sum summarized dynamic call-graph and profile SEE ALSO monitor(3), profil(2), cc(l), prof(l) Graham, S.L., Kessler, P.B., McKusick, M.K., ‘gprof: A Call Graph Execution Profiler’, Proceedings of the SIGPLAN ’82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No 6 pp 120-126 June 1982. ’ BUGS Parents which are not themselves profiled will have the time of their profiled children propagated to them, but they will appear to be spontaneously invoked in the call-graph listing, and will not have their time pro- pagated further. Similarly, signal catchers, even though profiled, will appear to be spontaneous (although for more obscure reasons). Any profiled children of signal catchers should have their times propagated properly, unless the signal catcher was invoked during the execution of the profiling routine, in which case all is lost -s -z FILES a.out Sun Release 3.0 Last change: 8 October 1984 147 GRAPH (1G) USER COMMANDS GRAPH (1G) NAME graph - draw a graph SYNOPSIS graph [ -a spacing [ start ] ] [ -b ] [ -c string ] [ -g gridstyle ] [ -I label ] [ -m connectmode ] [ -s ] [ -x [ 1 ] lower [ upper [ spacing ] ] ] [ -y [ 1 ] lower [ upper [ spacing ] ] ] [ -h fraction ] [ -w fraction ] [ -r fraction ] [ -u fraction ] [ -t ] . . . DESCRIPTION Graph with no options takes pairs of numbers from the standard input as abscissas and ordinates of a graph. Successive points are connected by straight lines. The graph is encoded on the standard output for display by the plot( 1G) filters. If the coordinates of a point are followed by a nonnumeric string, that string is printed as a label beginning on the point. Labels may be surrounded with quotes in which case they may be empty or contain blanks and numbers; labels never contain newlines. A legend indicating grid range is produced with a grid unless the -s option is present. OPTIONS Each option is recognized as a separate argument. -a spacing [ start ] Supply abscissas automatically (they are missing from the input); spacing is the spacing (default 1). start is the starting point for automatic abscissas (default 0 or lower limit given by -x). -b Break (disconnect) the graph after each label in the input — c string String is the default label for each point. — g gridstyle Gridstyle is the grid style: 0 no grid, 1 frame with ticks, 2 full grid (default). -1 label is label for graph. -m connectmode is mode (style) of connecting lines: 0 disconnected, 1 connected (default). Some devices give dis- tinguishable line styles for other small integers. -s Save screen, don’t erase before plotting. -x [ 1 ] lower [ upper [ spacing ] ] If 1 is present x axis is logarithmic, lower mdupper are lower (and upper) x limits, spacing, if present is grid spacing on x axis. Normally these quantities are determined automatically. — y [ I ] lower [ upper [ spacing ] ] If 1 is present y axis is logarithmic, lower mdupper are lower (and upper) y limits, spacing, if present is grid spacing on y axis. Normally these quantities are determined automatically. — h fraction is fraction of space for height. — w fraction is fraction of space for width. -r fraction is fraction of space to move right before plotting. -u fraction is fraction of space to move up before plotting. -t Transpose horizontal and vertical axes. (Option -x now applies to the vertical axis.) 148 Last change: 1 June 1983 Sun Release 3.0 GRAPH (1G) USER COMMANDS GRAPH (1G) If a specified lower limit exceeds the upper limit, the axis is reversed. SEE ALSO spline(lG), plot(lG) BUGS Graph stores all points internally and drops those for which there isn’t room. Segments that run out of bounds are dropped, not windowed. Logarithmic axes may not be reversed. Sun Release 3.0 Last change: 1 June 1983 149 GREP(l) USER COMMANDS GREP(l) NAME grep, egrep, fgrep - search a file for a pattern SYNOPSIS grep [ -v ] [ -c ] [ -1 ] [ -n ] [ -b ] [ -i ] [ -s ] [ -h ] [ -w ] [ -e ] expression filename . . . egrep [ — v ] [ — c ] [ — 1 ] [ — n ] [ — b ] [ — s ] [ — h ] [ expression \ -e expression | -f file ] filename . . . fgrep [ v ] [-x] [ — c ] [ — 1 ] [ — n ] [ — b ] [ — i ] [ — s ] [-h] strings \ -e strings | -f file ] filename . . . DESCRIPTION Commands of the grep family search the input files (standard input default) for lines matching a pattern. Normally, each line found is copied to the standard output Grep patterns are limited regular expressions in the style of ed( 1). Egrep patterns are full regular expressions including alternation. Fgrep searches for lines that contain one of the (newline-separated) strings. Fgrep patterns are fixed strings — no regular expression metacharacters are supported. In general, egrep is the fastest of these programs. Take care when using the characters $ * [ * | ( ) and \ in the expression as these characters are also mean- ingful to the Shell. Enclose the entire expression argument in single quotes ' ' if you need any of the above special characters in the expression. When any of the grep utilities is applied to more than one input file, the name of the file is displayed preceding each line which matches the pattern. The filename is not displayed when processing a single file, so if you actually want the filename to appear, use Idev/null as a second file in the list. OPTIONS -v Invert the search to only display lines that do not match. -x Display only those lines which match exactly — that is, only lines which match in their entirety ( fgrep only). -c Display a count of matching lines. -1 List the names of files with matching lines (once) separated by newlines. -n Precede each line by its relative line number in the file. -b Precede each line by the block number on which it was found. This is sometimes useful in locat- ing disk block numbers by context. -i Ignore the case of letters in making comparisons — that is, upper and lower case are considered identical. This applies to grep and fgrep only. -s Work silently, that is, display nothing except error messages. This is useful for checking the error status. -h Do not display filenames. -w search for the expression as a word as if surrounded by ‘\<’ and ‘\>’, see ex(l). grep only. -e expression Same as a simple expression argument, but useful when the expression begins with a -. -f file Take the regular expression (egrep) or string list (fgrep ) from file. REGULAR EXPRESSIONS In the following description ‘character’ excludes newline: \ Is an escape character: \ followed by any single character other than newline matches that charac- ter. Anchored match: matches the beginning of a line. 150 Last change: 12 February 1985 Sun Release 3.0 GREP(l) USER COMMANDS GREP(l) $ Anchored match: matches the end of a line. 0 (period) matches any character. c Where c is any single character not otherwise endowed with special meaning matches that charac- ter. [ string ] Character class: match any single character from string. Ranges of ASCII character codes may be abbreviated as in ‘a-zO-9’. A ] may occur only as the first character of the string. A literal - must be placed where it can’t be mistaken as a range indicator. A A (circumflex) character immediately after the open bracket negates the sense of the character class, that is, the pattern matches any character except those in the character class. * Closure: a regular expression followed by an * (asterisk) matches a sequence of 0 or more matches of the regular expression. + Closure: a regular expression followed by a + (plus) matches a sequence of 1 or more matches of the regular expression. ? Closure: a regular expression followed by a ? (question mark) matches a sequence of 0 or 1 matches of the regular expression. concatenation Two regular expressions concatenated match a match of the first followed by a match of the second. 1 Alternation: two regular expressions separated by | or newline match either a match for the first or a match for the second ( egrep only). () A regular expression enclosed in parentheses matches a match for the regular expression. The order of precedence of operators at the same parenthesis level is [ ] (character classes), then * + ? (clo- sures), then concatenation, then | (alternation) and newline. EXAMPLES Search a file for a fixed string using fgrep: tutorial% fgrep intro /usr/man/man3/*.3* Look for character classes using grep: tutorial% grep ’[1-8]([CJMSNX])’ /usr/man/manl/*.l Look for alternative patterns using egrep: tutorial% egrep ’(Sally|Fred) (Smith|Jones|Parker)’ telephone.list To get the filename displayed when only processing a single file, use /dev/null as the second file in the list tutorial% grep ’Sally Parker’ telephone.list /dev/null SEE ALSO vi(l) visual display-oriented editor based on ex(l) ex(l) line-oriented text editor based on ed(l) ed(l) primitive line-oriented text editor sed(l) stream editor awk(l) pattern scanning and text processing language sh(l) Bourne Shell DIAGNOSTICS Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files. BUGS Lines are limited to 256 characters; longer lines are truncated. Sun Release 3.0 Last change: 12 February 1985 151 GREP(l) USER COMMANDS GREP(l) Ideally there should be only one grep. 152 Last change: 12 February 1985 Sun Release 3.0 GROUPS ( 1 ) USER COMMANDS GROUPS ( 1 ) NAME groups - show group memberships SYNOPSIS groups DESCRIPTION Groups displays the groups to which you belong. Each user belongs to a group specified in the password file letc/passwd and possibly to other groups as specified in the file letcl group. If you do not own a file but belong to the group which it is owned by then you are granted group access to the file. When a new file is created it is given the group of the containing directory. SEE ALSO setgroups(2) FILES /etc/passwd, /etc/group Sun Release 3.0 Last change: 20 June 1983 153 HEAD ( 1 ) USER COMMANDS HEAD(l) NAME head - display first few lines of specified files SYNOPSIS head [ -count] [file ... ] DESCRIPTION Head copies the first count lines of the specified file(s), or of the standard input if no filename is given, to the standard output. The default value of count is 10 lines. When more than one file is specified, head places a marker at the start of each file which looks like: ==> filename <== Thus, a common way to display a set of short files, identifying each one, is: gaia% head -9999 filel file2 . . . EXAMPLE gaia% head -4 /usr/man/manl/{cat, head, tail}. 1 ==> /usr/man/manl/cat.l <== .TH CAT 1"2 June 1983" .SHNAME cat - concatenate and display .SH SYNOPSIS ==>/usr/man/manl/head.l <== .TH HEAD 1 "24 August 1983” .SHNAME head - display first few lines of specified files .SH SYNOPSIS ==>/usr/man/manl/tail.l <== .TH TAIL 1 ”27 April 1983" .SHNAME tail - display the last part of a file .SH SYNOPSIS SEE ALSO more(l), tail(l), cat(l) 154 Last change: 24 October 1983 Sun Release 3.0 HELP(l) USER COMMANDS HELP(l) NAME help - ask for help SYNOPSIS /usr/sccs/help [args] DESCRIPTION Help finds information to explain a message from a command or explain the use of a command. Zero or more arguments may be supplied. If no arguments are given, help will prompt for one. The arguments may be either message numbers (which normally appear in parentheses following mes- sages) or command names, of one of the following types: type 1 Begins with non-numerics, ends in numerics. The non-numeric prefix is usually an abbreviation for the program or set of routines which produced the message (for example, ge6, for message 6 from the get command). type 2 Does not contain numerics (as a command, such as get) type 3 Is all numeric (for example, 212) The response of the program will be the explanatory information related to the argument, if there is any. When all else fails, try /usr/sccs/help stuck. FILES /usr/lib/help directory containing files of message text DIAGNOSTICS Use help 1 1) for explanations. Sun Release 3.0 Last change: 27 October 1983 155 HOSTID ( 1 ) USER COMMANDS HOSTID ( 1 ) NAME hostid - print identifier of current host system SYNOPSIS hostid DESCRIPTION The hostid command prints the identifier of the current host in hexadecimal. This numeric value is unique across all Sun hosts. SEE ALSO gethostid(2) 156 Last change: 1 February 1985 Sun Release 3.0 HOSTNAME ( 1 ) USER COMMANDS HOSTNAME ( 1 ) NAME hostname - set or print name of current host system SYNOPSIS hostname [ nameofhost ] DESCRIPTION The hostname command prints the name of the current host, as given before the “login” prompt. The super-user can set the hostname by giving an argument; this is usually done in the startup script /etc/rc.local. SEE ALSO gethostname(2), sethostname(2) Sun Release 3.0 Last change: 22 March 1983 157 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) NAME iconedit — create and edit icons and cursors SYNOPSIS iconedit [filename ] OPTIONS iconedit accepts the SunWindows generic tool arguments; see suntools(l) for a list of these arguments. DESCRIPTION iconedit is a bitmap editor that allows you to create small images such as icons and cursors, iconedit runs in the SunWindows environment and can be positioned and manipulated in the same way as any other SunWindows tool. For general hints on using SunWindows tools, see suntools( 1). When invoked, iconedit displays a window consisting of several subwindows: • A large drawing area or canvas (on the left). • A small proof area for previewing a life-size version of the image being edited (at the lower right). • A control panel showing the options available and their current state. • An area for status messages (at the upper right). Instructions for the use of the mouse appear above the canvas. Move the cursor to the canvas, press and hold the left mouse button, and move the mouse as desired to draw an image. As you draw, an enlarged version of the image appears in the canvas, while a life-sized version of the image appears in the preview area. To “erase” any unwanted portions of the image, press and hold the center mouse button while moving the mouse as desired. Clicking the right mouse button inside the canvas will undo the previous operation. If you are editing a cursor image, move the cursor into the proof area to turn the proof image into the mouse cursor. This effect only lasts while you are in the proof area; it allows you to test how the new cur- sor looks during “real” use. Note that in this writeup, the term “cursor” refers to the mouse cursor, while the term “caret” indicates the current type-in position. CONTROL PANEL The control panel at the center right of the tool window lists the options available to you. To select an option, position the cursor on the desired item and click the left mouse button. To display a menu for an item, position the cursor on the desired item, then press and hold the right mouse button. To select an alternative from the menu, point at the desired alternative and release the mouse but- ton. If you are just starting out, you may want to use the menus until you become familiar with the tool. Some of the panel options are buttons which you press, in effect, by pointing to them and clicking the left mouse button. Load and Store are two examples of buttons. A small capsule-shaped box encloses each button. Other choices give you a set of alternatives from which to select. You can cycle through a set of alterna- tives for a given item by pointing to the item label and repeatedly clicking the left mouse button. The “painting hand” indicates the current painting mode. Small triangular carets indicate the current state of the Size and grid options as well as the proof background pattern. A triangular caret points to the current type-in position; this can be either the File field or the Fill field corresponding to the Text (“abc”) painting mode (see below). In detail, the control panel options are: File Contains the name of the file where the current image resides. To use a different file from the one shown, point at the file name, click the left mouse button, and type a new file name. The filename defaults to the filename given on the command line. 158 Last change: 17 September 1985 Sun Release 3.0 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) Entenng an alphabetic string terminated by requests filename completion, iconedit searches the current directory for files whose names begin with the string you entered. If the filename search locates only one file, that file will be loaded in. In addition, typing CTRL-L, CTRL-S, or CTRL-Q are equivalent to pressing the Load, Store, or Quit buttons, respectively. Load (Button) Load the canvas from the file named in the File field. Store (Button) Store the current image in the file named in the File field. Quit (Button) Terminate processing. Quitting requires a confirming click of the left mouse button. Size Alter the canvas size. Choices are icon size (64 x 64 pixels) or cursor size (16 x 16 pixels). Default is icon size. Grid Display a grid over the drawing canvas, or turn the grid off. Default is ‘ ‘grid off ’ . Clear (Button) Clear the canvas. Fill (Button) Fill canvas with current rectangular fill pattern. Invert (Button) Invert each pixel represented on the canvas. Paintbrush Select from among five modes of painting. The painting hand indicates the current painting mode. Point at the desired mode and click the left mouse button to move the painting hand. The current painting mode remains until you change it. Instructions for each painting mode appear above the canvas. The painting modes are: dot Paint a single dot at a time. line Draw a line. To draw a line on the canvas, point to the first endpoint of the line, and press and hold the left mouse button. While holding the button down, drag the cursor to the second endpoint of the line. Release the mouse button. rectangle Draw a rectangle. To draw a rectangle on the canvas, point to the first comer of the rec- tangle and press and hold the left mouse button. While holding the button down, drag the cursor to the diagonally opposite comer of the rectangle. Release the mouse button. In the control panel, the Fill field to the right of the rectangle indicates the current rectan- gle fill pattern. Any rectangles you paint on the canvas will be filled with this pattern. circle Draw a circle. To draw a circle on the canvas, point to the center of the circle, and press and hold the left mouse button. While holding the button down, drag the cursor to the desired edge of the circle. Release the mouse button. In the control panel, the Fill field to the right of the circle indicates the current circle fill pattern. Any circles you paint on the canvas will be filled with this pattern. abc Insert text. To insert text, move the painting hand to “abc” and type the desired text. Then move the cursor to the canvas and press and hold the left mouse button. A box will appear where the text is to go. Position the box as desired and release the mouse button. In addition, you can choose the font in which to draw the text. Point at the Fill field to the right of the “abc” and either click the left mouse button to cycle through the fonts available (watch the “abc” change as you do this), or press and hold the right mouse button to summon up a menu of fonts. Load This is the rasterop to be used when loading a file in from disk. See the SunWindows Reference Manual for more details on rasterops. Fill This is the rasterop to be used when filling the canvas. The source for this operation is the rectan- gle fill pattern, and the destination is the canvas. Proof This is the rasterop to be used when rendering the proof image. The source for this operation is the proof image, and the destination is the proof background. Sun Release 3.0 Last change: 17 September 1985 159 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) Proof background The proof background can be changed to allow you to preview how the image will appear against a variety of patterns. The squares just above the proof area show the patterns available for use as the proof background pattern. To change the proof background, point at the desired pattern and click the left mouse button. SEE ALSO suntools(l) FILES /usr/bin/iconedit 160 Last change: 17 September 1985 Sun Release 3.0 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) NAME indent - indent and format C program source SYNOPSIS indent [ input-file [ output-file ] ] [-bad|-nbad] [-bap|-nbap] [-bbb|-nbbb] [~bc|-nbc] [ — bl ] [-br] [-cn] [-cdn] [-cdb|-ncdb] [-ce|-nce] [ -cin ] [ -clin ] [-dn] [ — di« ] [ -fcl | -nfcl ] [-in] [ -ip | -nip ] [-In] [-lcn] [ -lp | -nip ] [-pcs|-npcs] [-npro] [ — psl | -npsl ] [ -sc | -nsc ] [ -sob | -nsob ] [ -st ] [ -troff ] [ — v | -nv ] DESCRIPTION Indent is a C program formatter. It reformats the C program in the input-file according to the switches. The switches which can be specified are described below. They may appear before or after the file names. NOTE: If you only specify an input-file, the formatting is done ‘in-place’, that is, the formatted file is writ- ten back into input-file and a backup copy of input-file is written in the current directory. If input-file is named ‘/blah/blah/file’, the backup file is named file.IMA'. If output-file is specified, indent checks to make sure it is different from input-file. OPTIONS The options listed below control the formatting style imposed by indent. -bap,-nbap If -bap is specified, a blank line is forced after every procedure body. Default -nbap. -bad,-nbad If -bad is specified, a blank line is forced after every block of declarations. Default: -nbad. — bbb,— nbbb If — bbb is specified, a blank line is forced before every block comment. Default: -nbbb. -bc,-nbc If -be is specified, then a newline is forced after each comma in a declaration, -nbc turns off this option. The default is -be. -br,-bl Specifying -bl lines up compound statements like this: if (...) { code } Specifying -br (the default) makes them look like this: if (...) { code ) -cn The column in which comments on code start. The default is 33. -cd n The column in which comments on declarations start. The default is for these comments to start in the same column as those on code. -cdb,-ncdb Enables (disables) the placement of comment delimiters on blank lines. With this option enabled, comments look like this: /* * this is a comment */ Rather than like this: /* this is a comment */ This only affects block comments, not comments to the right of code. The default is -cdb . — ce,— nee Enables (disables) forcing ‘else’s to cuddle up to the immediady preceeding *}’. The default is -ce . -tin Sets the continuation indent to be n. Continuation lines will be indented that far from the beginning of the first line of the statement Parenthesized expressions have extra Sun Release 3.0 Last change: 14 June 1985 161 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) -clin -drt -di/2 -fcl-nfcl -irt -ip, -nip -irt -npro -lp,-nlp -pcs , -npcs — psl , -npsl -sc,-nsc -sob,-nsob -st -T typename -troff indentation added to indicate the nesting, unless — lp is in effect — ci defaults to the same value as -i. Causes case labels to be indented n tab stops to the right of the containing switch state- ment. -cli0.5 causes case labels to be indented half a tab stop. The default is — cliO . Controls the placement of comments which are not to the right of code. The default -dl means that such comments are placed one indentation level to the left of code. Specify- ing -dO lines up these comments with the code. See the section on comment indentation below. Specifies the indentation, in character positions, from a declaration keyword to the fol- lowing identifier. The default is -dil6 . Enables (disables) the formatting of comments that start in column 1. Often, comments whose leading 7’ is in column 1 have been carefully hand formatted by the programmer. In such cases, -nfcl should be used. The default is -fcl. The number of spaces for one indentation level. The default is 4. Enables (disables) the indentation of parameter declarations from the left margin. The default is -ip . Maximum length of an output line. The default is 75. Causes the profile files, ‘7.indent.pro’ and ‘7.indent.pro’, to be ignored. Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren which is not closed on that line, then continuation lines will be lined up to start at the character position just after the left paren. For example, here is how a piece of contin- ued code looks with -nip in effect: pi = first_procedure (second_procedure (p2, p3) , third_j3rocedure (p4, p5) ) ; With -lp in effect (the default) the code looks somewhat clearer: pi = firstj>rocedure (second_procedure (p2, p3), third_procedure (p4, p5) ) ; Inserting a couple more newlines we get: pi = f irst_procedure (second_procedure (p2, p3) , third__procedure (p4, p5) ) ; If true (-pcs) all procedure calls will have a space inserted between the name and the ’(’. The default is -npcs If true (-psl) the names of procedures being defined are placed in column 1 - their types, if any, will be left on the previous lines. The default is -psl Enables (disables) the placement of asterisks (‘*’s) at the left edge of all comments. If -sob is specified, indent will swallow optional blank lines. You can use this to get rid of blank lines after declarations. Default: -nsob Causes indent to take its input from stdin, and put its output to stdout. Adds typename to the list of type keywords. Names accumulate: -T can be specified more than once. You need to specify all the typenames that appear in your program that are defined by typedefs - nothing will be harmed if you miss a few, but the program won’t be formatted as nicely as it should. This sounds like a painful thing to have to do, but it’s really a symptom of a problem in C: typedef causes a syntactic change in the laguage and indent can’t find all typedefs. Causes indent to format the program for processing by troff. It will produce a fancy 162 Last change: 14 June 1985 Sun Release 3.0 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) listing in much the same spirit as vgrind. If the output file is not specified, the default is standard output, rather than formatting in place. -v,-nv -v turns on ‘verbose’ mode, -nv turns it off. When in verbose mode, indent reports when it splits one line of input into two or more lines of output, and gives some size statistics at completion. The default is -nv. FURTHER DESCRIPTION You may set up your own ‘profile’ of defaults to indent by creating a file called undent. pro in either your login directory or the current directory and including whatever switches you like. A ‘.indentpro’ in the current directory takes precedence over the one in your login directory. If indent is run and a profile file exists, then it is read to set up the program’s defaults. Switches on the command line, though, always over- ride profile switches. The switches should be separated by spaces, tabs or newlines. Comments Box comments. Indent assumes that any comment with a dash or star immediately after the start of com- ment (that is, 7*-’ or 7**’) is a comment surrounded by a box of stars. Each line of such a comment is left unchanged, except that its indentation may be adjusted to account for the change in indentation of the first line of the comment. Straight text. All other comments are treated as straight text. Indent fits as many words (separated by blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. Comment indentation If a comment is on a line with code it is started in the ‘comment column’, which is set by the -c n command line parameter. Otherwise, the comment is started at n indentation levels less than where code is currently being placed, where n is specified by the -dn command line parameter. If the code on a line extends past the comment column, the comment starts further to the right, and the right margin may be automatically extended in extreme cases. Preprocessor lines In general, indent leaves preprocessor lines alone. The only reformmatting that it will do is to straighten up trailing comments. It leaves imbedded comments alone. Conditional compilation (#ifdef...#endif) is recognized and indent attempts to correctly compensate for the syntactic peculiarites introduced. C syntax Indent understands a substantial amount about the syntax of C, but it has a ‘forgiving’ parser. It attempts to cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros lifov tdefine forever for(;;) is handled properly. FILES ./.indent.pro profile file 7.indent.pro profile file BUGS Indent has even more switches than Is. A common mistake that often causes grief is typing: indent * . c to the shell in an attempt to indent all the C programs in a directory. This is probably a bug, not a feature. Sun Release 3.0 Last change: 14 June 1985 163 INDXBIB ( 1 ) USER COMMANDS ESTDXBIB ( 1 ) NAME indxbib — make inverted index to a bibliography SYNOPSIS indxbib database ... DESCRIPTION Indxbib makes an inverted index to the named databases (or files) for use by lookbib(\) and refer (l). These files contain bibliographic references (or other kinds of information) separated by blank lines. A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts on a line beginning with a followed by a key-letter, then a blank, and finally the contents of the field, which may continue until the next line starting with Indxbib is a shell script that calls two programs: lusrlliblreferlmkey and lusr/lib/refer/inv. mkey truncates words to 6 characters, and maps upper case to lower case. It also discards words shorter than 3 characters, words among the 100 most common English words, and numbers (dates) < 1900 or > 2000. These parame- ters can be changed — see Refer — a Bibliography System in the Editing and Text Processing on the Sun Workstation document inv creates an entry file (.ia), a posting file (.ib), and a tag file (.ic), all in the work- ing directory. FILES x.ia, x.ib, x.ic, where x is the first argument, or if these are not present, then x.ig, x SEE ALSO " r e f e r " in Formatting Documents on the Sun Workstation refer(l), addbib(l), sortbib(l), roffbib(l), lookbib(l) BUGS Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or ear- lier. 164 Last change: 6 April 1985 Sun Release 3.0 INSTALL(l) USER COMMANDS INSTALL ( 1 ) NAME install - install files SYNOPSIS install [ — c ] [ -m mode ] [ -o owner ] [ -g group ] [ — s ] binary destination DESCRIPTION binary is copied to destination. If destination already exists, it is removed before binary is copied. If the destination is a directory then binary is copied into file destination/binary. install refuses to move a file onto itself. Note: install has no special privileges since it simply uses cp to copy files from one place to another. The implications of this are: • You must have permission to read binary. • You must have permission to copy into destination. • You must have permission to change the modes on the final copy of the file if you want to use the -m option to change modes. • You must be super-user if you want to use the -o option to change ownership. OPTIONS -c Copy binary instead of moving it. In fact, install always copies the file, but the -c option is retained for backwards compatibility with old system shell scripts which might otherwise break. — m mode Specifies a different mode for binary: the mode for destination is set to 755 by default -o owner Set the owner of the destination file to owner, destination is changed to owner root by default. -g group Set the group ownership of the destination file to group, destination is changed to group staff by default. -s Strip binary files after it is installed — only applicable to binary files in a.out( 5) format. SEE ALSO chmod(l), cp(l), mv(l), strip(l), chown(8) BUGS Should be possible to move multiple files at a time, like mv or cp. When the destination is a directory, install simply appends the entire source file name to the directory name, instead of using the source file name’s last component like mv or cp. Sun Release 3.0 Last change: 23 September 1985 165 JOIN ( 1 ) USER COMMANDS JOIN ( 1 ) NAME join - relational database operator SYNOPSIS join [ -an ] [ -e string ] [ -j [1 1 2] m ] [ -o list ] [ -tc ] filenamel filename2 DESCRIPTION join forms, on the standard output, a join of the two relations specified by the lines of filenamel and filename2 . If filenamel is the standard input is used. Filel and filenamel must be sorted in increasing ASCII collating sequence on the fields on which they are to be joined, normally the first in each line. There is one line in the output for each pair of lines in filenamel and filename2 that have identical join fields. The output line normally consists of the common field, then the rest of the line from filenamel , then the rest of the line from filename2 . Fields are separated by blanks, tabs or newlines. Multiple separators count as one, and leading separators are discarded. OPTIONS -an The parameter n can be one of the values: 1 produce a line for each unpayable line in filenamel . 2 produce a line for each unpairable line in filename2 . 3 produce a line for each unpairable line in both filenamel and filename2 . The normal output is also produced. -e s Replace empty output fields by string . -jU\2]m The j may be immediately followed by n, which is either a ‘1’ or a ‘2’. If n is missing, the join is on the m’th field of both files. If n is present, the join is on the nz’th field of file n, and the first field of the other. Note that join counts fields from 1 instead of 0 like sort does. -o list Each output line comprises the fields specified in list, each element of which has the form n.m, where n is a file number and m is a field number. Note that join counts fields from 1 instead of 0 like sort does. -tc Use character c as a separator (tab character). Every appearance of c in a line is significant. SEE ALSO sort(l), comm(l), awk(l), uniq(l), look(l) BUGS With default field separation, the collating sequence is that of sort -b ; with -t, the sequence is that of a plain sort. The conventions of join, sort, comm, uniq, look, and awk are wildly incongruous. 166 Last change: 23 September 1985 Sun Release 3.0 KILL(l) USER COMMANDS KILL ( 1 ) NAME kill - send a signal to a process, or terminate a process SYNOPSIS kill [ -sig ] processid . . . kill —I DESCRIPTION Kill | sends the TERM (terminate, 15) signal to the specified processes. If a signal name or number preceded by is given as first argument, that signal is sent instead of terminate. The signal names are listed by using the -1 option, and are as given in /usr/include/signal.h, stripped of the common SIG prefix. The terminate signal will kill processes that do not catch the signal, so kill -9 ... is a sure kill, as the KILL (9) signal cannot be caught. By convention, if process number 0 is specified, all members in the pro- cess group (that is, processes resulting from the current login) are signaled (but beware: this works only if you use sA(l); not if you use c$ft(l).) The killed processes must belong to the current user unless he is the super-user. To shut the system down and bring it up single user the super-user may send the initialization process a TERM (terminate) signal by ‘kill 1’; see init( 8). To force init to close and open terminals according to what is currently in /etc/ttys use ‘kill -HUP 1 ’ (sending a hangup, signal 1). The shell reports the process number of an asynchronous process started with (run in the background). Process numbers can also be found by using ps(l). Kill is built in to csh(iy, it allows job specifiers, such as kill % .... in place of kill arguments. See csA(l) for details. OPTIONS -1 Display a list of signal names. SEE ALSO csh(l), ps(l), kill(2), sigvec(2) BUGS An option to kill process groups should be provided; a replacement for kill 0 for csh(l) users should be provided. Sun Release 3.0 Last change: 24 October 1983 167 LAST ( 1 ) USER COMMANDS LAST ( 1 ) NAME last - indicate last logins of users and teletypes SYNOPSIS last [ —number ][ — f filename ] [ name ...] [tty ... ] DESCRIPTION last looks back in the wtmp file which records all logins and logouts for information about a user, a teletype or any group of users and teletypes. Arguments specify names of users or teletypes of interest. Names of teletypes may be given fully or abbreviated. For example ‘last 0’ is the same as ‘last ttyO’. If multiple arguments are given, the information which applies to any of the arguments is printed. For example ‘last root console’ would list all of "root’s" sessions as well as all sessions on the console terminal, last displays the sessions of the specified users and teletypes, most recent first, indicating the times at which the session began, the duration of the session, and the teletype which the session took place on. If the session is still continuing or was cut short by a reboot, last so indicates. The pseudo-user reboot logs in at reboots of the system, thus last reboot will give an indication of mean time between reboot. last with no arguments displays a record of all logins and logouts, in reverse order. If last is interrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit signal (generated by a controls) last indicates how far the search has progressed so far, and the search continues. OPTIONS —number limit the number of entries displayed to that specified by number. — f filename Use filename as the name of the accounting file instead of lusrladmlwtmp. FILES /usr/adm/wtmp login data base SEE ALSO utmp(5), ac(8), lastcomm(l) 168 Last change: 23 September 1985 Sun Release 3.0 LASTCOMM ( 1 ) USER COMMANDS LASTCOMM ( 1 ) NAME lastcomm - show last commands executed in reverse order SYNOPSIS lastcomm [ command name ] ... [user name] ... [terminal name] ... DESCRIPTION Lastcomm gives information on previously executed commands. Lastcomm with no arguments displays information about all the commands recorded during the current accounting file’s lifetime. If called with arguments, lastcomm only displays accounting entries with a matching command name, user name, or ter- minal name. EXAMPLES tutorial% lastcomm a.out root ttydO would produce a listing of all the executions of commands named a. out, by user root while using the termi- nal ttydO. and tutorial% lastcomm root would produce a listing of all the commands executed by user root. For each process entry, lastcomm displays the following items of information: • The command name under which the process was called. • One or more flags indicating special information about the process. The flags have the following mean- ings: F The process performed a fork but not an exec . S The process ran as a set-user-id program. D The process dumped memory. X The process was killed by some signal. • The name of the user who ran the process. • The terminal which the user was logged in on at the time (if applicable). • The amount of CPU time used by the process (in seconds). • The date and time the process exited. FILES /usr/adm/acct accounting file SEE ALSO last(l), acct(5), core(5) Sun Release 3.0 Last change: 1 February 1985 169 LD( 1 ) USER COMMANDS LD( 1 ) NAME Id - link editor SYNOPSIS Id [ -A name ] [ -D hex ] [ -d ] [ -e entry ] [ -Lx ] [ -M ] [ -N ] [ -n ] [ -o name ] [ -r ] [ -S ] [ -s ] [ -Ttext hex ] [ -Tdata hex ] [ -t ] [ -u name ] [ -X ] [ -x ] [ -y sym ] [ -z ] filename . . . DESCRIPTION Id combines several object programs into one, resolves external references, and searches libraries. In the simplest case several object filename s are given, and Id combines them, producing an object module which can either be executed or become the input for a subsequent Id run. In the latter case, the -r option must be given to preserve the relocation bits. The output of Id is left on a file called a. out if not otherwise specified. The output file is made executable only if no errors occurred during link editing. Files specified by the argument filename ... are concatenated in the order specified. The entry point of the output is the beginning of the first routine, unless the -e option is specified. If a named file is a library, it is searched exactly once at the point it is encountered in the argument list. Only those routines defining an unresolved external reference are loaded. If a routine from a library refer- ences another routine in the same library, and the library has not been processed by ranlib, the referenced routine must appear after the referencing routine in the library. Thus the order of programs within libraries may be important. The first member of a library should be a file named ‘ .SYMDEF’, which is under- stood to be a dictionary for the library as produced by ranlib ; the dictionary is searched iteratively to satisfy as many references as possible. The symbols _etext, _edata and _end (etext, edata and end in C) are reserved, and if referred to, are set to the first location above the program, the first location above initialized data, and the first location above all data, respectively. It is erroneous to define these symbols. OPTIONS Options should appear before the filenames, except abbreviated library names specified by the -1 option, which can appear anywhere. -A name Incremental loading: linking is to be done in a manner so that the resulting object may be read into an already executing program. Name is the name of a file whose symbol table is taken as a basis on which to define additional symbols. Only newly linked material is entered into the text and data portions of a. out, but the new symbol table will reflect all symbols defined before and after the incremental load. This argument must appear before any other object file in the argument list. One or both of the -T option may be used as well, and will be taken to mean that the newly linked segment will commence at the corresponding addresses (which must be a multiple of the page size). The default value is the old value of _end. -D hex Pad the data segment with zero bytes to make it hex bytes long. -d Force definition of common storage even if the -r flag is present. — e entry Define the entry point: the entry argument is made the name of the entry point of the loaded pro- gram. -lx This option is an abbreviation for the library name ‘/lib/libx.a’, where x is a string. If that does not exist, Id tries ‘/usr/lib/libx.a’. A library is searched when its name is encountered, so the place- ment of a -1 is significant. -M Produce a primitive load map, listing the names of the files which will be loaded. -N Do not make the text portion read-only or sharable. (Use ‘magic number’ 0407.) -n Arrange (by giving the output file a 0410 ‘magic number’) that when the output file is executed, the text portion will be read-only and shared among all processes executing the file. This involves 170 Last change: 23 September 1985 Sun Release 3.0 LD( 1 ) USER COMMANDS LD( 1 ) moving the data areas up to the first possible segment boundary following the end of the text. -o name Name is made the name of the Id output file, instead of a.out. — r Generate relocation bits in the output file so that it can be the subject of another Id run. This flag also prevents final definitions from being given to common symbols, and suppresses the ‘undefined symbol’ diagnostics. — S Strip the output by removing all symbols except locals and globals. -s Strip the output, that is, remove the symbol table and relocation bits to save space (but impair the usefulness of the debuggers). This information can also be removed by strip( 1). — Ttext hex Start the text segment at location hex. Specifying a bare -T is the same as using the -Ttext option. — Tdata hex Start the data segment at location hex. This option is only of use to programmers wishing to write code for PROM s, since the resulting code cannot be executed by the UNIX system. -t Trace: display the name of each file as it is processed. — u name Enter name as an undefined symbol. This is useful for loading wholly from a library, since ini- tially the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. -X Record local symbols, except for those whose names begin with ‘L’. This option is used by cc to discard internally-generated labels while retaining symbols local to routines. -x Preserve only global (non- .globl) symbols in the output symbol table; only enter external sym- bols. This option saves some space in the output file. -ysym Display each file in which sym appears, its type and whether the file defines or references it. Many such options may be given to trace many symbols. It is usually necessary to begin sym with an as external C, FORTRAN and Pascal variables begin with underscores. -z Arrange for the process to be loaded on demand from the resulting executable file (0413 ‘magic number’) rather than preloaded. This is the default Results in a page-sized header on the output file followed by a text and data segment, each of which has a multiple of page-size bytes (being padded out with nulls in the file if necessary). With this format the first few BSS segment symbols may actually end up in the data segment; this is to avoid wasting the space resulting from round- ing the data segment size. The text is read-only and shared among all processes executing the file. FILES /lib/lib*. a libraries /usr/lib/lib* .a more libraries /usr/local/lib/lib*.a still more libraries a.out output file SEE ALSO as(l), ar(l), cc(l), ranlib(l), strip(l) BUGS There is no way to force data to be page-aligned. Sun Release 3.0 Last change: 23 September 1985 171 LEAVE ( 1 ) USER COMMANDS LEAVE ( 1 ) NAME leave - remind you when you have to leave SYNOPSIS leave [[+]hhmm] DESCRIPTION Leave sets an alarm to a time you specify and will tell you when the time is up. Leave waits until the specified time, then reminds you that you have to leave. You are reminded 5 minutes and 1 minute before the actual time, at the time, and every minute thereafter. Leave disappears after you log off. You can specify the time in on of two ways, namely as an absolute time of day in the form hhmm where hh is a time in hours (on a 12 or 24 hour clock), or you can place a + sign in front of the time, in which case the time is relative to the current time, that is, the specified number of hours and minutes from now. All times are converted to a 12 hour clock, and assumed to be in the next 12 hours. If no argument is given, leave prompts with "When do you have to leave?”. Leave exits if you just type a newline, otherwise the reply is assumed to be a time. This form is suitable for inclusion in a .login or .profile. Leave ignores interrupts, quits, and terminates. To get rid of it you should either log off or use kill -9 and its process id. SEE ALSO calendar(l) EXAMPLES The first example sets the alarm to an absolute time of day: tutorial% leave 1535 Alarm set for Wed Mar 7 15:35:07 1984 work work work work tutorial% Time to leave! The second example sets the alarm for 10 minutes in the future: tutorial% leave +10 Alarm set for Wed Mar 7 15:45:24 1984 work work work work tutorials Time to leave! work work work work tutorial% You’re going to be late! BUGS Relative time does not work as described. Currently you must specify relative time in the form +mmmm. It is not checked against a 12 hour clock. 172 Last change: 7 March 1984 Sun Release 3.0 LEX ( 1 ) USER COMMANDS LEX(l) NAME lex - generator of lexical analysis programs SYNOPSIS lex [ -tvfn ] [ file ] . . . DESCRIPTION Lex generates programs to be used in simple lexical analyis of text The input files (standard input default) contain regular expressions to be searched for, and actions written in C to be executed when expressions are found. A C source program, ’lex.yy.c’ is generated, to be compiled thus: cc lex.yy.c This program, when run, copies unrecognized portions of the input to the output, and executes the associ- ated C action for each regular expression that is recognized. OPTIONS -t Place the result on the standard output instead of in file lex.yy.c . -v Print a one-line summary of statistics of the generated analyzer. — n Opposite of — v; — n is default. -f ‘Faster’ compilation: don’t bother to pack the resulting tables; limited to small programs. EXAMPLE lex lexcommands would draw lex instructions from the file lexcommands, and place the output in lex.yy.c %% [A-Z] putchar(yytext[0]+V-'A'); []+$ [ ]+ putchar(' '); is an example of lex . This program converts upper case to lower, removes blanks at the end of lines, and replaces multiple blanks by single blanks. SEE ALSO yacc(l), sed(l) The paper, LEX — A Lexical Analyzer Generator, in the Sun Programming Tools Manual. Sun Release 3.0 Last change: 1 November 1983 173 LINT ( 1 ) USER COMMANDS LINT ( 1 ) NAME lint — a C program verifier SYNOPSIS lint [ — abchnuvxz ] [ — D name=def\ [ — D name ] [ — U name ] [ —I dir ] filename . . . lint [ -C lib ] filename . . . DESCRIPTION lint attempts to detect features of the C program files that are likely to be bugs, non-portable, or wasteful. lint also checks the type usage of the program more strictly than the C compiler, lint runs the C preproces- sor as its first phase. Among the things which are currently found are unreachable statements, loops not entered at the top, automatic variables declared and not used, and logical expressions whose values are constant. Moreover, the usage of functions is checked to find functions which return values in some places and not in others, functions called with varying numbers of arguments, and functions whose values are not used. By default, it is assumed that all the files are to be loaded together; they are checked for mutual compatibil- ity. Function definitions for certain libraries are available to lint; these libraries are referred to by a con- ventional name, such as -lm, in the style of W( 1). The standard C library (-lc) is lint’s d by default. Arguments ending in .In are also treated as library files. To create lint libraries, use the -C option. For example tutorial% lint -Ccongress files . . . where files are the C sources of library congress, produces a file llib-lcongress .In in the current directory in the correct library format suitable for lint’ ing programs using -lcongress. General Comments The routine exit (2) and other functions which do not return are not understood; this causes various lies. Certain conventional comments in the C source will change the behavior of lint: /*NOTREACHED*/ at appropriate points stops comments about unreachable code. /*VARARGSn*/ suppresses the usual checking for variable numbers of arguments in the following function declaration. The data types of the first n arguments are checked; a missing n is taken to be 0. /*ARGSUSED*/ turns on the -v option for the next function. /*LINTLIBR ARY */ at the beginning of a file, shuts off complaints about unused functions in this file. OPTIONS a Report assignments of long values to int variables. b Report break statements that cannot be reached. This is not the default because, unfortunately, most lex(\) and many yacc(l) outputs produce dozens of such messages. c Complain about casts which have questionable portability. h Apply a number of heuristic tests to attempt to intuit bugs, improve style, and reduce waste, n Do not check compatibility against the standard library. u Do not complain about functions and variables used and not defined, or defined and not used (this is suitable for running lint on a subset of files comprising part of a larger program). v Suppress complaints about unused arguments in functions. x Report variables referred to by extern declarations, but never used. z Do not complain about structures that are never defined (for example, using a structure pointer 174 Last change: 23 September 1985 Sun Release 3.0 LINT ( 1 ) USER COMMANDS LINT ( 1 ) without knowing its contents). — D name-def —Dname Define name to the preprocessor, as if by ‘#define’. If no definition is given, the name is defined as "1". -U name Remove any initial definition of name in the preprocessor. “I dir ‘tinclude’ files whose names do not begin with 7’ are always sought first in the directory of the file argument, then in directories named in -I options, then in the lusr/include directory. -Clib create a lint library with name lib (see DESCRIPTION section). -1 Hb use lint library lib from the lusrllib/lint directory. EXAMPLE The following lint call: tutorial% lint -b myfile checks the consistency of the file ‘myfile’. The -b option indicates that unreachable break statements are to be checked for. FILES /usr/lib/lint/lint[l 2] programs / usr/lib/lint/llib-1* . In Various prebuilt lint libraries. /usr/lib/lint/llib-1* Sources of the prebuilt lint libraries. These libraries exist for -lc, -lcore, -Icurses, -lm, -Imp, -lpixrect, -lsuntool and -lsunwindow. SEE ALSO cc(l), cpp(l) Lint, a C Program Checker, in Programming Tools for the Sun Workstation BUGS There are some things you just can’t get lint to shut up about. Sun Release 3.0 Last change: 23 September 1985 175 LN ( 1 ) USER COMMANDS LN ( 1 ) NAME In - make links SYNOPSIS In [ -f ] [ -s ] filename [ linkname ] In [ -f ] [ -s ] filename . . . directory DESCRIPTION In assigns an additional name (directory entry), called a link, to a file or directory. Several links may be assigned to a file at any one time. The number of links does not affect other attributes such as size, protec- tions, data, etc. There are two kinds of links: hard links and symbolic links. A hard link, which is the default, can only be made to an existing file. Only the superuser can make a hard link to a directory. To remove a file with more than one hard link, all such links (including the name by which it was created) must be removed. Hard links may not span file systems. In can also make symbolic links. A symbolic link contains the name of the file or directory to which it is linked. The referenced file or directory is used when an open( 2) operation is performed on the link. A stat on a symbolic link returns the linked-to file; an lstat( 2) must be done to obtain information about the link itself. The readlink(2) call may be used to read the contents of a symbolic link. Symbolic links may span file systems and may refer to directories. Filename is the original name of the file or directory to be linked. Linkname is the new name to be associ- ated with the file or filename. If linkname is omitted, the last component of the original pathname is used. Directory is a directory in which to place the link. When a directoiy is specified, In uses the last com- ponent of each original pathname as the name of each link. OPTIONS -f Force a hard link to a directory, — this option is only available to the superuser. -s create symbolic links. EXAMPLES The commands below illustrate the effects of the tutorial% Is -F grab jones/ tutorial% Is -F jones house tutorial% In grab ./grab: File exists tutorial% In jones/house tutorial% Is -F grab house jones/ tutorial% In grab hold tutorial% Is -F grab hold house jones/ tutorial^ In grab hold jones tutorial% Is -F jones grab hold house tutorial% different forms of the In command. See what files we’ve got See what files there are in jones One file try to link a file in the same directory Sorry — can’t link a file to itself link a file from another directory to here link a file to another name in this directory link files from here to jones SEE ALSO rm(l), cp(l), mv(l), link(2), readlink(2), stat(2), symlink(2), lstat(2) BUGS Error messages print the wrong file name when the -s option is used. 176 Last change: 23 September 1985 Sun Release 3.0 LOCKSCREEN ( 1 ) USER COMMANDS LOCKSCREEN ( 1 ) NAME lockscreen - maintain window context until “login” SYNOPSIS lockscreen [ — e ] [ — n ] [ — r ] DESCRIPTION Lockscreen preserves the user’s window setup and context when the machine is not in use. When run, the dark lockscreen display and constantly moving Sun Microsystems logo limit phosphorus bum of the video display that might otherwise occur from running the same window configuration for a long time. Lockscreen is executed from a terminal emulator running inside the SunWindows system. When any key- board or mouse button is pressed, the dark screen is replaced by an option panel that displays the user name, a dark box, and a prompt for the user’s password. If the user has no password, or if the — n option is used, the user’s window setup is immediately restored. When the option screen appears: 1) Enter the user’s password to return to the Sunwindows environment; this password is not echoed on the screen, or, 2) Point to the black box and click the left button to return to the dark display. The panel also allows you to enter a different user name by pointing to the Name: field, clicking the left button, and typing in the name. You must then supply the appropriate password. OPTIONS -e Add the Exit Desktop choice to the options panel. If pointed to and clicked, the Sunwindows environment is exited and the cunrent user is logged out. — n No password is required to reenter the window environment. -r Allows use of the user name root. Normally, root is not accepted as a valid user name. SEE ALSO suntools(l), login(l) Sun Release 3.0 Last change: 25 March 1985 177 LOGIN ( 1 ) USER COMMANDS LOGIN ( 1 ) NAME login - sign on SYNOPSIS login [ username ] DESCRIPTION login signs username on to the system initially; login may also be used at any time to change from one userid to another. When used with no argument, login requests a user name and password (if appropriate). Echoing is turned off (if possible) while typing the password. When successful, login updates accounting files, informs you of the existence of any mail, prints the mes- sage of the day, and displays the time you last logged in (unless you have a .hushlogin file in your home directory — mainly used by nonhuman users, such as uucp). login initializes the user and group IDs and the working directory, then starts a command interpreter shell (usually either Ibinlsh or Ibinlcsh according to specifications found in the file letc/passwd. (Argument 0 of the command interpreter is “-sh”, or more generally, the name of the command interpreter with a leading dash (“-”) prepended.) login also initializes the environment with information specifying home directory, command interpreter, terminal-type (if available) and username. If the file letc/nologin exists, login prints its contents on the user’s terminal and exits. This is used by shut- down^) to stop logins when the system is about to go down. The login command, recognized by sh and csh, is executed directly (without forking), and terminates that shell. To resume working, you must log in. login times out and exits if its prompt for input is not answered within a reasonable time. When the Bourne Shell (sh) starts up, it reads a file called .profile from your home directory (that of the username you use to log in). When the C-Shell (csh) starts up, it reads a file called .cshrc from your home directory, and then reads a file called .login. The Shells read these files only if they are owned by the person logging in. FILES letclutmp lusrladmlwtmp lusrladmllastlog lusrlttytype lusrlspoollmaill* letc/motd letc/passwd I etc! nolo gin 7 . hushlogin accounting accounting time of last login terminal types mail message-of-the-day password file stop login, print message makes login quieter SEE ALSO init(8), getty(8), mail(l), passwd(l), passwd(5), environ(5), shutdown(8), utmp(5) DIAGNOSTICS “Login incorrect,” if the name or the password is bad (or mistyped). “No Shell”, “cannot open password file”, “no directory”: ask your system administrator for assistance. 178 Last change: 25 November 1985 Sun Release 3.0 LOOK ( 1 ) USER COMMANDS LOOK(l) NAME look - find lines in a sorted list SYNOPSIS look [ -df ] string [ file ] DESCRIPTION Look consults a sorted file and prints all lines that begin with string. OPTIONS -d ‘Dictionary’ order: only letters, digits, tabs and blanks participate in comparisons, -f Fold: Upper case letters compare equal to lower case. If no file is specified, look uses lusr/dictlwords with collating sequence -df. FILES /usr/dict/words SEE ALSO sort(l), grep(l) Sun Release 3.0 Last change: 13 April 1983 179 LOOKBIB ( 1 ) USER COMMANDS LOOKBIB ( 1 ) NAME lookbib - find references in a bibliography SYNOPSIS lookbib database DESCRIPTION A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts on a line beginning with a followed by a key-letter, then a blank, and finally the contents of the field, which may continue until the next line starting with Lookbib uses an inverted index made by indxbib to find sets of bibliographic references. It reads keywords typed after the “>” prompt on the terminal, and retrieves records containing all these keywords. If nothing matches, nothing is returned except another “>” prompt. It is possible to search multiple databases, as long as they have a common index made by indxbib. In that case, only the first argument given to indxbib is specified to lookbib. If lookbib does not find the index files (the .i[abc] files), it looks for a reference file with the same name as the argument, without the suffixes. It creates a file with a ’.ig’ suffix, suitable for use with fgrep. Lookbib then uses this fgrep file to find references. This method is simpler to use, but the .ig file is slower to use than the .i[abc] files, and does not allow the use of multiple reference files. FILES x.ia, jc.ib, r.ic, where x is the first argument, or if these are not present, then x.ig, x SEE ALSO "refer" in Formatting Documents on the Sun Workstation refer(l), addbib(l), sortbib(l), roffbib(l), indxbib(l) BUGS Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or ear- lier. 180 Last change: 6 April 1985 Sun Release 3.0 LORDER(l) USER COMMANDS LORDER ( 1 ) NAME lorder - find ordering relation for an object library SYNOPSIS lorder file... DESCRIPTION Give lorder one or more object or library archive (see ar(l)) files, and it lists pairs of object file names — meaning that the first file of the pair refers to external identifiers defined in the second — to the standard output. Lorder ’s output may be processed by tsort( 1) to find an ordering of a library suitable for one-pass access by ld( 1). EXAMPLE This brash one-liner intends to build a new library from existing .o files, ar cr library ' lorder *.o | tsort' The ranlib(l), command converts an ordered archive into a randomly accessed library and makes lorder unnecessary. SEE ALSO tsort(l), ld(l), ar(l), ranlib(l) BUGS The names of object files, in and out of libraries, must end with ‘ .o’ ; otherwise, nonsense results. Sun Release 3.0 Last change: 11 November 1983 181 LPQ(l) USER COMMANDS LPQ(l) NAME lpq — spool queue examination program SYNOPSIS *pq [ +[ num ] ] [ — 1 ] [ — P printer ] [ job #...][ user . . . ] DESCRIPTION lpq examines the spooling area used by lpd{ 8) for printing files on the line printer, and reports the status of the specified jobs or all jobs associated with a user. lpq reports on any jobs currently in the queue when invoked without any options. Arguments supplied that are not recognized as options are interpreted as user names or job numbers to filter out only those jobs of interest. For each job submitted (that is, each invocation of Ipr) lpq reports the user’s name, current rank in the queue, the names of files comprising the job, the job identifier (a number which may be supplied to Iprm for removing a specific job), and the total size in bytes. Normally, only as much information as will fit on one line is displayed. Job ordering is dependent on the algorithm used to scan the spooling directory and is supposed to be FIFO (First in First Out). File names comprising a job may be unavailable (when Ipr is used as a sink in a pipeline) in which case the file is indicated as ‘(standard input)’. If lpq warns that there is no daemon present (that is, due to some malfunction), the /pc (8) command can be used to restart the printer daemon. OPTIONS — P printer report the state of the queue to the specified printer. In the absence of the -P option, the queue to the printer specified by the PRINTER variable in the environment is reported on. If the PRINTER variable isn’t set, the default line printer queue is reported. -1 job#... causes information about each of the files comprising the job to be printed. +nnn display the spool queue until it empties. Supplying a number nnn immediately after the + sign indicates that lpq should sleep nnn seconds in between scans of the queue. FILES /etc/termcap /etc/printcap /usr/spool/* /usr/spool/*/cf* /usr/spool/ */lock for manipulating the screen for repeated display to determine printer characteristics the spooling directory, as determined from printcap control files specifying jobs the lock file to obtain the currently active job SEE ALSO lpr(l), lprm(l), lpc(8), lpd(8) BUGS The + option doesn’t wait until the entire queue is empty; it only waits until the local machine’s queue is empty. lpq may report unreliably. The status, as reported, may not always reflect the actual state of the printer. Output formatting is sensitive to the line length of the terminal; this can result in widely-spaced columns. lpq is sometimes unable to open various files because the lock file is malformed. DIAGNOSTICS Waiting for printer to become ready (offline ?) The daemon could not open the printer device. This can happen for a number of reasons; the most common is that the printer is turned off-line. This message can also be generated if the printer is out of paper, the paper is jammed, and so on. The actual reason is dependent on the meaning of error codes returned by system device driver. Not all printers supply sufficient information to dis- tinguish when a printer is off-line or having trouble (for example, a printer connected through a 182 Last change: 23 September 1985 Sun Release 3.0 LPQ(l) USER COMMANDS LPQ(l) serial line). Another possible cause of this message is some other process, such as an output filter, has an exclusive open on the device. Your only recourse here is to kill off the offending program(s) and restart the printer with Ipc. printer is ready and printing The Ipq program checks to see if a daemon process exists for printer and prints the file status. If the daemon is hung, a super user can use Ipc to abort the current daemon and start a new one. waiting for host to come up Indicates that there is a daemon trying to connect to the remote machine named host in order to send the files in the local queue. If the remote machine is up, Ipd on the remote machine is prob- ably dead or hung and should be restarted as mentioned for Ipr. sending to host The files should be in the process of being transferred to the remote host. If not, the local daemon should be aborted and started with Ipc. Warning: printer is down The printer has been marked as being unavailable with Ipc. Warning: no daemon present The Ipd process overseeing the spooling queue, as indicated in the “lock” file in that directory, does not exist This normally occurs only when the daemon has unexpectedly died. The error log file for the printer should be checked for a diagnostic from the deceased process. To restart an Ipd, use % /usr/etc/Ipc restart printer Sun Release 3.0 Last change: 23 September 1985 183 LPR(l) USER COMMANDS LPR(l) NAME lpr - off line print SYNOPSIS lpr [ -P printer ] [ —ttnum ] [ -C class ] [ -J job ] [ -T title ] [ -i [ num] ] [ -1234/on/ ] [-wnum ] [ -r ] [ -m ] [ -h ] [ -s ] [ -filter _option ] [filename . . . ] DESCRIPTION lpr uses a spooling daemon to print the named files when facilities become available, lpr reads the stndard input if no files are specified. OPTIONS -P printer Force output to the named printer . Normally, the default printer is used (site dependent), or the value of the PRINTER environment variable is used. -#num Produce multiple copies of output, using num as the number of copies for each file named. For example, tutorial% lpr -#3 new.index.c print.index.c more.c produces three copies of the file new. index. c , followed by three copies of print. index. c , etc. On the other hand, tutorial% cat new.index.c print.index.c more.c | lpr -#3 generates three copies of the concatenation of the files. -C Print class as the job classification on the burst page. For example, tutorial% lpr -C Operations new.index.c replaces the system name (the name returned by hostname) with ‘Operations’ on the burst page, and prints the file new. index. c . —3 job Print job as the job name on the burst page. Normally, lpr uses the first file’s name. -T title Use title instead of the file name for the title used by pr. -i [num] Indent output num spaces. If num is not given, eight spaces are used as default -1 -2 -3 -4 Mount the specified font on font position 1, 2, 3, or 4. The daemon will construct a .railmag file in the spool directory that indicates the mount by referencing lusrlliblvfontlfont. -y/num Use num as the page width for pr. -r Remove the file upon completion of spooling. -m Send mail upon completion. -h Suppress printing the burst page. -s Create a symbolic link from the spool area to the data files rather than trying to copy them (so large files can be printed). This means the data files should not be modified or removed until they have been printed. In the absence of this option, files larger than 1 Megabyte in length are trun- cated. Note that the -s option only works if you are specifically naming data files — it doesn’t work if lpr is at the end of a pipeline. filter _option The following single letter options notify the line printer spooler that the files are not standard text files. The spooling daemon will use the appropriate filters to print the data accordingly. -p Use pr to format the files (lpr -p is very much like pr | lpr). -1 Print control characters and suppress page breaks. -t The files contain data from troffi cat phototypesetter commands). 184 Last change: 23 September 1985 Sun Release 3.0 LPR(l) USER COMMANDS LPR(l) -n The files contain data from ditroff (device independent troff). -d The files contain data from tex (DVI format from Stanford). -g The files contain standard plot data as produced by the plot (3X) routines (see also plot (1G) for the filters used by the printer spooler). -v The files contain a raster image, see rasterfile(5). -c This option currently is unassigned. -f Interpret the first character of each line as a standard FORTRAN carriage control charac- ter. -h Postscript data. FILES /etc/passwd /etc/printcap /usr/lib/lpd* /usr/spool/* /usr/spool/ */cf* /usr/spool/*/df* /usr/spool/ */tf* personal identification printer capabilities data base line printer daemons directories used for spooling daemon control files data files specified in “cf” files temporary copies of “cf ’ files SEE ALSO lpq(l), lprm(l), pr(l), printcap(5), lpc(8), lpd(8), rasterfile(5), screendump(l) DIAGNOSTICS Ipr: copy file is too large A file is determined to be too ‘large’ to print by copying into the spool area. Use the -s option as defined above to make a symbolic link to the file instead of copying it. A ‘large’ file is approxi- mately 1 Megabyte in this system. Ipr: printer : unknown printer The printer was not found in the printcap database. Usually this is a typing mistake; however, it may indicate a missing or incorrect entry in the letclprintcap file. Ipr: printer : jobs queued, but cannot start daemon. The connection to Ipd on the local machine failed. This usually means the printer server started at boot time has died or is hung. Check the local socket Idevlprinter to be sure it still exists (if it does not exist, there is no Ipd process running). Ipr: printer : printer queue is disabled This means the queue was turned off with tutorial% /usr/etc/lpc disable printer to prevent Ipr from putting files in the queue. This is normally done by the system manager when a printer is going to be down for a long time. The printer can be turned back on by a super-user with Ipc. If the -f and -s flags are combined as follows: Ipr -fs filename copies the file to the spooling directory rather than making a symbolic link. Placing the -s flag first, or writing each as separate arguments makes a link as expected. BUGS Ipr -p is not equivalent to pr | Ipr. Ipr -p puts the current date at the top of each page, rather than the date last modified, and inserts a header page between each file printed. The — p and — # options don’t work well together; the second and subsequent copies do not include the file name in each page’s title. Sun Release 3.0 Last change: 23 September 1985 185 LPR(l) USER COMMANDS LPR(l) Fonts for troff and tex reside on the host with the printer. It is currently not possible to use local font libraries. 186 Last change: 23 September 1985 Sun Release 3.0 LPRM(l) USER COMMANDS LPRM(l) NAME lprm - remove jobs from the line printer spooling queue SYNOPSIS lprm [ — P printer ] [ — ] [job # . . . ] [ username . . . ] DESCRIPTION lprm removes a job, or jobs, from a printer’s spool queue. Since the spooling directory is protected from users, using lprm is normally the only method by which a user may remove a job. lprm without any arguments will delete the currently active job if it is owned by the user who invoked lprm. If the - flag is specified, lprm will remove all jobs which a user owns. If the super-user employs this flag, the spool queue will be emptied entirely. The owner is determined by the user’s login name and host name on the machine where the Ipr command was invoked. Specifying a user’s name, or list of user names, will cause lprm to attempt to remove any jobs queued belonging to that user (or users). This form of invoking lprm is useful only to the super-user. A user may dequeue an individual job by specifying its job number. This number may be obtained from Ipq. For example: tutorial% Ipq -Pimagen imagen is ready and printing Rank Owner lob Files Total Size active wendy 385 standard input 35501 bytes tutorial% lprm -Pimagen 305 lprm announces the names of any files it removes and is silent if there are no jobs in the queue which match the request list. lprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon is killed, a new one is automatically restarted upon completion of file removals. The -P option may be used to specify the queue associated with a specific printer (otherwise the default printer, or the value of the PRINTER variable in the environment is used). FILES /etc/printcap printer characteristics file /usr/spool/* spooling directories /usr/spool/*/Iock lock file used to obtain the pid of the current daemon and the job number of the currently active job SEE ALSO lpr(l), lpq(l), lpd(8) DIAGNOSTICS lprm: printer: cannot restart printer daemon The connection to Ipd on the local machine failed. This usually means the printer server started at boot time has died or is hung. Check the local socket /dev/printer to be sure it still exists (if it does not exist, there is no Ipd process running). Use tutorial% ps ax | fgrep Ipd to get a list of process identifiers of running lpd’s. The Ipd to kill is the one which is not listed in any of the “lock" files (the lock file is contained in the spool directory of each printer). Kill the master daemon using the following commands: tutorial% su Password: tutorial# kill pid Sun Release 3.0 Last change: 23 September 1985 187 LPRM(l) USER COMMANDS LPRM(l) Then remove Idevlprinter and restart the daemon (and printer) with the following commands. tutorial# rm /dev/printer tutorial# /usr/lib/lpd Another possibility is that the Ipr program is not setuid root, setgid daemon. This can be checked with tutorial# Is -Ig /usr/ucb/lpr BUGS Since there are race conditions possible in the update of the lock file, the currently active job may be incorrectly identified. 188 Last change: 23 September 1985 Sun Release 3.0 LS(1) USER COMMANDS LS(1) NAME Is — list contents of directory SYNOPSIS Is [ -acdfgilqrstulACLFR ] filename . . . DESCRIPTION For each filename which is a directory, Is lists the contents of the directory; for each filename which is a file, Is repeats its name and any other information requested. By default, the output is sorted alphabetically. When no argument is given, the current directory is listed. When several arguments are given, the argu- ments are first sorted appropriately, but file arguments are processed before directories and their contents. OPTIONS -a List all entries; in the absence of this option, entries whose names begin with a V are not listed (except for the super-user, for whom Is normally prints even files that begin with a V). -c Use time of last edit (or last mode change) for sorting or printing. -d If argument is a directory, list only its name; often used with -1 to get the status of a directory. -f Force each argument to be interpreted as a directory and list the name found in each slot. This option turns off —I, — t, — s, and — r, and turns on —a; the order is the order in which entries appear in the directory. -g Show the group ownership of the file in a long output. — i For each file, print the i-number in the first column of the report. -1 List in long format, giving mode, number of links, owner, size in bytes, and time of last modification for each file. (See below.) If the file is a special file the size field will instead contain the major and minor device numbers. If the file is a symbolic link the pathname of the linked-to file is printed preceded by -q Display non-graphic characters in filenames as the character *?’; this is the default when output is to a terminal. -r Reverse the order of sort to get reverse alphabetic or oldest first as appropriate. -s Give size in kilobytes of each file. -t Sort by time modified (latest first) instead of by name. -u Use time of last access instead of last modification for sorting (with the -t option) and/or printing (with the -I option). -1 Force one entry per line output format; this is the default when output is not to a terminal. -A Same as -a, except that V and are not listed. -C Force multi-column output; this is the default when output is to a terminal. -F Mark directories with a trailing 7’, executable files with a trailing symbolic links with a trail- ing and AF_UNIX domain sockets with a trailing *=’. -L If argument is a symbolic link, list the file or directory the link references rather than the link itself. -R Recursively list subdirectories encountered. INTERPRETATION OF LISTING The mode printed under the -I option contains 11 characters interpreted as follows. If the first character is: d entry is a directory; b entry is a block-type special file; c entry is a character-type special file; 1 entry is a symbolic link s entry is an AF UNIX domain socket, or Sun Release 3.0 Last change: 23 September 1985 189 LS( 1 ) USER COMMANDS LS(1 ) FILES BUGS - entry is a plain file. The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner permis- sions; the next to permissions to others in the same user-group; and the last to all others. Within each set the three characters indicate permission respectively to read, to write, or to execute the file as a program. For a directory, ‘execute’ permission is interpreted to mean permission to search the directory. The per- missions are indicated as follows: r the file is readable; w the file is writable; x the file is executable; - the indicated permission is not granted. The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the owner-execute permission character is given as s if the file has the set-user-id bit set. The last character of the mode (normally ‘x’ or *-’) is t if the 1000 bit of the mode is on. See chmod(\) for the meaning of this mode. When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is printed. /etc/pass wd to get user id’ s for ‘Is -V. /etc/group to get group id’ s for ‘Is- g’ . Newline and tab are considered printing characters in filenames. The output device is assumed to be 80 columns wide. The option setting based on whether the output is a teletype is undesirable as l ls -s’ is much different than ‘Is - s | lpr’. On the other hand, not doing this setting would make old shell scripts which used Is almost certain losers. 190 Last change: 23 September 1985 Sun Release 3.0 M4(l) USER COMMANDS M4(l) NAME m4 - macro processor SYNOPSIS m4 [file ... ] DESCRIPTION M4 is a macro processor intended as a front end for Ratfor, C, and other languages. Each argument file is processed in order; the standard input is read if there are no arguments or if an argument is The pro- cessed text is written on the standard output. Macro calls have the form name(argl,arg2, . . . , argn) The ‘(’ must immediately follow the name of the macro. If a defined macro name is not followed by a ‘(’, it is deemed to have no arguments. Leading unquoted blanks, tabs, and newlines are ignored while collect- ing arguments. Potential macro names consist of letters, digits, and underscore *_*, where the first charac- ter is not a digit. Left and right single quotes (' ') are used to quote strings. The value of a quoted string is the string stripped of the quotes. When a macro name is recognized, its arguments are collected by searching for a matching right parenthesis. Macro evaluation proceeds normally during the collection of the arguments, and any commas or right parentheses which happen to turn up within the value of a nested call are as effective as those in the original input text. After argument collection, the value of the macro is pushed back onto the input stream and rescanned. M4 makes available the following built-in macros. They may be redefined, but once this is done the origi- nal meaning is lost. Their values are null unless otherwise stated. define The second argument is installed as the value of the macro whose name is the first argument. Each occurrence of $n in the replacement text, where n is a digit, is replaced by the n ’th argu- ment. Argument 0 is the name of the macro; missing arguments are replaced by null strings. undefine removes the definition of the macro named in its argument. ifdef If the first argument is defined, the value is the second argument, otherwise the third. If there is no third argument, the value is null. The word unix is predefined on UNIX versions of m4. changequote Change quote characters to the first and second arguments. Changequote without arguments restores the original values (that is, ' '). M4 maintains 10 output streams, numbered 0-9. The final output is the concatenation of the streams in numerical order; initially stream 0 is the current stream. The divert macro changes the current output stream to its (digit-string) argument. Output diverted to a stream other than 0 through 9 is discarded. undivert causes immediate output of text from diversions named as arguments, or all diversions if no argument. Text may be undiverted into another diversion. Undiverting discards the diverted text. divnum dnl ifelse incr returns the value of the current output stream. reads and discards characters up to and including the next newline. has three or more arguments. If the first argument is the same string as the second, then the value is the third argument. If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6, 7 and so on. Otherwise, the value is either the last string not used by the above process, or, if it is not present, null. returns the value of its argument incremented by 1. The value of the argument is calculated by Sun Release 3.0 Last change: 23 October 1983 191 M4 ( 1 ) USER COMMANDS M4(l) interpreting an initial digit-string as a decimal number. eval evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators include +, *, /, %, ' (exponentiation); relational; parentheses. len returns the number of characters in its argument. index returns the position in its first argument where the second argument begins (zero origin), or -1 if the second argument does not occur. substr returns a substring of its first argument. The second argument is a zero origin number select- ing the first character; the third argument indicates the length of the substring. A missing third argument is taken to be large enough to extend to the end of the first string. translit transliterates the characters in its first argument from the set given by the second argument to the set given by the third. No abbreviations are permitted. include returns the contents of the file named in the argument. sinclude is identical to include, except that it says nothing if the file is inaccessible. syscmd executes the UNIX command given in the first argument. No value is returned. maketemp fills in a string of the form XXXXX in its argument with the current process id. errprint prints its argument on the diagnostic output file. dumpdef prints current names and definitions, for the named items, or for all if no arguments are given. SEE ALSO M4 — A Macro Processor , in Programming Tools for the Sun System. 192 Last change: 23 October 1983 Sun Release 3.0 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) NAME Mail - interactive message processing system SYNOPSIS Mail [ -d ] [ -e ] [ -f [filename | +folder ] ] [ — F ] [ — h number] [ — H ] [ — i ] [ — n ] [ -N ] [-r address] [-s subject] [ -T file ] [ -u user ] [-U] [-v] [name... ] DESCRIPTION mail provides a comfortable, flexible environment for sending and receiving messages electronically. When reading mail, mail provides commands to facilitate saving, deleting, and responding to messages. When sending mail, mail allows editing, reviewing and other modification of the message as it is entered. Incoming mail is stored in a standard file for each user, called the system mailbox for that user. When mail is called to read messages, the mailbox is the default place to find them. As messages are read, they are marked to be moved to a secondary file for storage, unless specific action is taken, so that the messages need not be seen again. This secondary file is called the mbox and is normally located in the user’s HOME directory (see ‘MBOX’ ( variables ) for a description of this file). Messages remain in this file until forcibly removed. OPTIONS On fire command line, options start with a dash (-) and any other arguments are taken to be destinations (recipients). If no recipients are specified, mail attempts to read messages from the mailbox. Command line options are: -d -e -f [ filename ] -f [+folder]" -F — h number -H -i -n -N — r address -s subject -T file — u user -U -v SENDING MAIL When sending mail, mail is in input mode. If no subject is specified on the command line, a prompt for the subject is printed. As the message is typed, mail reads the message and stores it in a temporary file. Com- mands may be entered by beginning a line with the tilde (') escape character followed by a single com- mand letter and optional arguments. See tilde escapes for a summary of these commands. READING MAIL When reading mail, mail is in command mode. A header summary of the first several messages is displayed, followed by a prompt indicating mail can accept regular commands (see commands below). Turn on debugging output. Neither particularly interesting nor recommended. Test for presence of mail. Mail prints nothing and exits with a successful return code if there is mail to read. Read messages from filename instead of mailbox. If no filename is specified, the mbox is used. Use the fil & folder in the ‘folders’ directory (as with the folder command). Record the message in a file named after the first recipient. Overrides the ‘record’ vari- able, if set (see variables). The number of network ‘hops’ made so far. This is provided for network software to avoid infinite delivery loops. Print header summary only. Ignore interrupts. See also ‘ignore’ ( variables ). Do not initialize from the system default Mail.rc file. Do not print initial header summary. Pass address to network delivery software. All tilde commands are disabled. Set the Subject header field to subject. Print the contents of the article-id fields of all messages that were read or deleted on file (for the use of network news programs if available). Read user’s mailbox. This is only effective if user’s mailbox is not read protected. Convert uucp style addresses to internet standards. Overrides the ‘conv’ environment variable. Pass the -v flag to sendmail($). Sun Release 3.0 Last change: 23 September 1985 193 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) At any time, the behavior of mail is governed by a set of environment variables. These are flags and valued parameters which are set and cleared via the set and unset commands. See variables below for a summary of these parameters. Recipients listed on the command line may be of three types: login names, shell commands, or alias groups. Login names may be any network address, including mixed network addressing. If the recipient name begins with a pipe symbol (|), the rest of the name is taken to be a shell command to pipe the message through. This provides an automatic interface with any program that reads the standard input, such as Ipr for recording outgoing mail on paper. Alias groups are set by the alias command (see commands below) and are lists of recipients of any type. Regular commands are of the form [ command ] [ msglist ] [ arguments ] If no command is specified in command mode , that is, you just type a carriage-return, print is assumed. In input mode, commands are recognized by the escape character, and lines not treated as commands are taken as input for the message. Each message is assigned a sequential number, and there is at any time the notion of a ‘current’ message, marked by a V in the header summary. Many commands take an optional list of messages ( msglist ) to operate on, which defaults to the current message. A msglist is a list of message specifications separated by spaces, which may include: n Message number n. . The current message. The first undeleted message. $ The last message. + The next undeleted message. - The previous undeleted message. * All messages. n-m An inclusive range of message numbers, user All messages from user. /string All messages with string in the subject line (case ignored). :c All messages of type c, where c is one of: d deleted messages n new messages o old messages r read messages u unread messages Note that the context of the command determines whether this type of message specification makes sense. Other arguments are usually arbitrary strings whose usage depends on the command involved. File names, where expected, are expanded via the normal shell conventions (see cj/z( 1) and sh( 1)). Special characters are recognized by certain commands and are documented with the commands below. STARTING MAIL At start-up time, mail reads commands from a system-wide file (/usr/lib/Mail.rc) to initialize certain parameters, then from a private start-up file ($HOME/.mailrc) for personalized variables. Most regular commands are legal inside start-up files, the most common use being to set up initial display options and alias lists. The following commands are not legal in the start-up file: !, Copy, edit, followup, Followup, hold, mail, preserve, reply, Reply, replyall, replysender, shell, and visual. Any errors in the start-up file cause the remaining lines in the file to be ignored. COMMANDS The following is a complete list of mail commands: 194 Last change: 23 September 1985 Sun Release 3.0 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) '.shell-command Escape to the shell. See ‘SHELL’ ( variables ). # comment Null command (comment). This may be useful in .mailrc files. = Print the current message number. ? Prints a summary of commands. alias [alias name . . .] group [alias name . . .] Declare an alias for the given names. The names will be substituted when alias is used as a recipient. Useful in the .mailrc file. With no arguments, alias prints the current list of aliases. alternates name . . . Declares a list of alternate names for your login. When responding to a message, these names are removed from the list of recipients for the response. With no arguments, alternates prints the current list of alternate names. See also ‘allnet’ ( variables ). cd [ directory ] chdir [ directory ] Change directory. If directory is not specified, $home is used. copy [filename] copy [ms glist] filename Copy messages to the file without marking the messages as saved. Otherwise equivalent to the save command. Copy [mjgZwt] Save the specified messages in a file whose name is derived from the author of the message to be saved, without marking the messages as saved. Otherwise equivalent to the Save command. delete [ms glist] Delete messages from the mailbox. If ‘autoprint’ is set, the next message after the last one deleted is printed (see variables). discard [header-field ...] ignore [header-field . . .] Suppresses printing of the specified header fields when displaying messages on the screen. Examples of header fields to ignore are ‘status’ and ‘received’. The fields are included when the message is saved unless ‘alwaysignore’ is set (see variables). The Print and Type commands override any ignoring of header fields and display all header fields. dp [msglist] dt [msglist] Delete the specified messages from the mailbox and print the next message after the last one deleted. Roughly equivalent to a delete command followed by a print com- mand. echo string . . . Echo the given strings (like echo). edit [msglist] Edit the given messages. The messages are placed in a temporary file and the ‘EDI- TOR’ variable is used to get the name of the editor (see variables). Default editor is ex. exit x it Exit from mail, without changing the mailbox. No messages are saved in the mbox (see also quit). file [filename ] folder [filename ] Quit from the current file of messages and read in the specified file. Several special characters are recognized when used as file names, with the following substitutions: % the current mailbox. %user the mailbox for user. # the previous file. & the current mbox. Sun Release 3.0 Last change: 23 September 1985 195 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) -i -folder the file folder in the folders directory. With no arguments, file prints the name of the current file and the number of messages and characters in that file. folders Print the names of the files in the directory set by the ‘folder’ variable (see variables). followup [ message ] Respond to a message, recording the response in a file whose name is derived from the author of the message. Overrides the ‘record’ variable, if set See also the Followup, Save, and Copy commands and ‘outfolder’ ( variables ). Followup [msglist] Respond to the first message in the msglist, sending the message to the author of each message in the msglist. The subject line is taken from the first message and the response is recorded in a file whose name is derived from the author of the first mes- sage. See also the followup. Save, and Copy commands and ‘outfolder’ ( variables ). from [msglist] Prints the header summary for the specified messages. group alias name . . . alias alias name . . . Declare an alias for the given names. The names will be substituted when alias is used as a recipient Useful in the .mailrc file. With no arguments, alias prints the current list of aliases. headers [ message ] Prints the page of headers which includes the message specified. The ‘screen’ variable sets the number of headers per page (see variables). See also the z command. help Prints a summary of commands. hold [msglist] preserve [msglist] Holds the specified messages in the mailbox, if s\r\t mail-commands else mail-commands endif Conditional execution, where s will execute following mail-commands, up to an else or endif, if the program is in send mode, r executes the mail-commands only in receive mode, and t executes the mail-commands only if mail is being run from a tty. Useful in the .mailrc file. ignore header-field . . . discard header-field . . . Suppress printing the specified header fields when displaying messages on the screen. Examples of header fields to ignore are ‘status’ and ‘received’. The fields are included when the message is saved unless ‘alwaysignore’ is set (see variables). The Print and Type commands override any ignoring of header fields and display all header fields. list Prints all commands available. No explanation is given, mail name . . . Mail a message to the specified users. mbox [msglist] Arrange for the given messages to end up in the standard mbox save file when mail ter- minates normally. See ‘mbox’ ( variables ) for a description of this file. See also the exit and quit commands. next [message] Go to next message matching message. A msglist may be specified, but in this case the first valid message in the list is the only one used. This is useful for jumping to the next message from a specific user, since the name would be taken as a command in the absence of a real command. See the discussion of msglists above for a description of 196 Last change: 23 September 1985 Sun Release 3.0 MAIL(l) USER COMMANDS MAJL(l) possible message specifications. pipe [msglist] [ shell-command ] | [msglist] [ shell-command '] Pipe the message through the given shell-command. The message is treated as if it were read. If no arguments are given, the current message is piped through the com- mand specified by the value of the ‘cmd’ variable. If the ‘page’ variable is set, a form feed character is inserted after each message (see variables). preserve [msglist] hold [ msglist ] Print [msglist] Type [ffwgfi'st] print [msglist] type [msglist] quit Reply [message] Respond [message] replyall [ message ] Reply to the specified message, including all other recipients of the message. If ‘record’ is set to a filename, the response is saved at the end of that file (see vari- ables). If the ‘replyall’ variable is set, the actions of Reply/ Respond and reply/ respond are reversed. The replyall command always has the action described above; it is not affected by the ‘replyall’ variable. reply [msglist] respond [wiyg/z'sf] replysender [msglist] Send a response to the author of each message in the msglist. The subject line is taken from the first message. If ‘record’ is set to a filename, the response is saved at the end of that file (see variables). If the ‘replyall’ variable is set, the actions of Reply/ Respond and reply/ respond are reversed. The replysender command always has the action described above; it is not affected by the ‘replyall’ variable. Save [msglist] Save the specified messages in a file whose name is derived from the author of the first message. The name of the file is taken to be the author’s name with all network addressing stripped off. See also the Copy, followup, and Followup commands and ‘outfolder’ ( variables ). save [filename] save [msglist] filename Save the specified messages in the given file. The file is created if it does not exist. The message is deleted from the mailbox when mail terminates unless ‘keepsave’ is set (see also variables and the exit and quit commands). Default file is the user’s mbox. set set name set name=string set name=number Define a variable called name. The variable may be given a null, string, or numeric value. Set by itself prints all defined variables and their values. See variables for Preserve the specified messages in the mailbox. Print the specified messages on the screen, including all header fields. Overrides suppression of fields by the ignore command. Print the specified messages. If ‘crt’ is set, the messages longer than the number of lines specified by the ‘crt’ variable are paged through the command specified by the ‘ pager ’ variable. The default command is more (see variables). Exit from mail, storing messages that were read in mbox and unread messages in the mailbox. Messages that have been explicitly saved in a file are deleted. Sun Release 3.0 Last change: 23 September 1985 197 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) shell size [msglist] source filename top [msglist] touch [msglist] Type [tfwg/wf] Print [msglist] type [tfiyg/isf] print [msglist] undelete [msglist] unset name . . . version visual [msg/isr] detailed descriptions of the mail variables. Invoke an interactive shell (see also ‘shell’ (variables)). Print the size in characters of the specified messages. Read commands from the given file and return to command mode. Print the top few lines of the specified messages. If the ‘toplines’ variable is set, it is taken as the number of lines to print (see variables). The default is 5. Touch the specified messages. If any message in msglist is not specifically saved in a file, it will be placed in the mbox upon normal termination. See exit and quit Print the specified messages on the screen, including all header fields. Overrides suppression of fields by the ignore command. Print the specified messages. If ‘crt’ is set, the messages longer than the number of lines specified by the ‘crt’ variable are paged through the command specified by the ‘PAGER’ variable. The default command is more (see VARIABLES). Restore the specified deleted messages. Will only restore messages deleted in the current mail session. If ‘autoprint’ is set, the last message of those restored is printed (see VARIABLES). Erases the specified variables. If the variable was imported from the execution environment (that is, a shell variable) then it cannot be erased. Prints the current version and release date. Edit the given messages with a screen editor. The messages are placed in a temporary file and the ‘visual’ variable is used to get the name of the editor (see variables). Default screen editor is vi. write [msglist] filename Write the given messages on the specified file, minus the header and trailing blank line. Otherwise equivalent to the save command. xit ex *t Exit from mail, without changing the mailbox. No messages are saved in the mbox (see also quit). Z t+H Scroll the header display forward or backward one screen-full. The number of headers displayed is set by the ‘screen’ variable (see variables). TILDE ESCAPES The following commands may be entered only from input mode, by beginning a line with the tilde escape character ( ). See ‘escape’ ( variables ) for changing this special character. The tilde escape character may be entered as text by typing it twice (for example, typing " is the tilde escape character enters the line ' is the tilde escape character into the message). '! shell-command Escape to the shell. Simulate end of file (terminate message input). mail-command mail-command Perform the command-level request. Valid only when sending a message while read- 198 Last change: 23 September 1985 Sun Release 3.0 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) -? "A "a "b name . . . 'c name . . . 'd "e "f [ttwg/Lr] ing mail. Print a summary of tilde escapes. Insert the autograph string ‘Sign’ into the message (see variables). Insert the autograph string ‘sign’ into the message (see variables). Add the names to the blind carbon copy (Bcc) list. Add the names to the carbon copy (Cc) list. Read in the dead.letter file. See ‘dead’ ( variables ) for a description of this file. Invoke the editor on the partial message. See also ‘editor’ (variables). Forward the specified messages. The messages are inserted into the message, without alteration, as opposed to the “m command. Valid only when sending a message while reading mail. "h “i string "m [msglist] P q Prompt for Subject line and To, Cc, and Bcc lists. If the field is displayed with an ini- tial value, it may be edited as if you had just typed it. Insert the value of the named variable into the text of the message. For example, 'A is equivalent to ‘"i Sign.’ Insert the specified messages into the letter, shifting the new text to the right one tab stop. Valid only when sending a message while reading mail. Print the message being entered. Quit from input mode by simulating an interrupt. If the body of the message is not null, the partial message is saved in the dead.letter file. See ‘dead’ (variables) for a description of this file. "r filename ~< filename < \shell-command Read in the specified file. If the argument begins with an exclamation point (!), the rest of the string is taken as an arbitrary shell command and is executed, with the stan- dard output inserted into the message. "s string ... Set the subject line to string. t name . . . Add the given names to the To list. v ”w filename ”| shell-command VARIABLES Invoke a preferred screen editor on the partial message. See also ‘visual’ (vari- ables). Write the partial message onto the given file, without the header. Exit as with 'q except the message is not saved in the dead.letter file. Pipe the body of the message through the given shell-command. If the shell-command returns a successful exit status, the output of the command replaces the message. The following are environment variables taken from the execution environment and are not alterable within mail. HOME=directory The user’s base of operations. M.PJLRC=filename The name of the start-up file. Default is $HOME/.mailrc. The following variables are internal mail variables. They may be imported from the execution environ- ment or set via the set command at any time. The unset command may be used to erase variables. Using the set command with a no prepended to the variable name has the same effect as using the unset com- Sun Release 3.0 Last change: 23 September 1985 199 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) mand with the variable name. allnet All network names whose last component (login name) match are treated as identical. This causes the msglist message specifications to behave similarly. Default is noallnet. See also the alternates command and the ‘metoo’ variable. alwaysignore append askcc asksub autoprint bang Ignores header fields with ignore everywhere, not just during print or type. Affects the save, Save, copy, Copy, top, pipe, and write commands, and the "m and ~f tilde escapes. Upon termination, append messages to the end of the mbox file instead of prepending them. Default is noappend but append is set in the global start-up file (which can be suppressed with the -n command line option). Prompt for the Cc list after message is entered. Default is noaskcc. Prompt for subject if it is not specified on the command line with the -s option. Enabled by default. Enable automatic printing of messages after delete and undelete commands. Default is noautoprint. Enable the special-casing of exclamation points (!) in shell escape command lines as in vz. Default is nobang. cmd =shell-command Set the default command for the pipe command. No default value. con \=conversion Convert uucp addresses to the specified address style. The only valid conversion now is internet, which requires a mail delivery program conforming to the RFC822 stan- dard for electronic mail addressing. Conversion is disabled by default. See also ‘sendmail’ and the -U command line option. CTt=number DEAI>=filename debug dot Pipe messages having more than number lines through the command specified by the value of the ‘pager’ variable ( more by default). Disabled by default The name of the file in which to save partial letters in case of untimely interrupt or delivery errors. Default is $HOME/dead.letter. Enable verbose diagnostics for debugging. Messages are not delivered. Default is nodebug. Take a period on a line by itself during input from a terminal as end-of-file. Default is nodot but dot is set in the global start-up file (which can be suppressed with the -n command line option). EDITOR =shell-command The command to run when the edit or "e command is used. Default is ex. escap e=c folder ^directory header hold ignore ignoreeof Substitute c for the ' escape character. The directory for saving standard mail files. User specified file names beginning with a plus (+) are expanded by preceding the filename with this directory name to obtain the real filename. If directory does not start with a slash (/), $HOME is prepended to it. There is no default for the ‘folder’ variable. See also ‘outfolder’ below. Enable printing of the header summary when entering mail. Enabled by default. Preserve all messages that are read in the mailbox instead of putting them in the stan- dard mbox save file. Default is nohold. Ignore interrupts while entering messages. Handy for noisy dial-up lines. Default is noignore. Ignore end-of-file during message input. Input must be terminated by a period (.) on a 200 Last change: 23 September 1985 Sun Release 3.0 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) line by itself or by the command. Default is noignoreeof. See also ‘dot’ above. kee P When the mailbox is empty, truncate it to zero length instead of removing it Disabled by default. keepsave Keep messages that have been saved in other files in the mailbox instead of deleting them. Default is nokeepsave. LISTER =shell-command The command (and options) to use when listing the contents of the ‘folder’ directory. The default is Is. MBOX=filename The name of the file to save messages which have been read. The xit command over- rides this function, as does saving the message explicitly in another file. Default is $HOME/mbox. met0 ° If your login appears as a recipient, do not delete it from the list. Default is nometoo. no When used as a prefix to a variable name, has the effect of unsetting the variable. onehop When responding to a message that was originally sent to several recipients, the other recipient addresses are normally forced to be relative to the originating author’s machine for the response. This flag disables alteration of the recipients’ addresses, improving efficiency in a network where all machines can send directly to all other machines (that is, one hop away). outfolder Locates the files used to record outgoing messages in the directory specified by the ‘folder’ variable unless the pathname is absolute. Default is nooutfolder. See ‘folder’ above and the Save, Copy, followup, and Followup commands. P a 8 e Used with the pipe command to insert a form feed after each message sent through the pipe. Default is nopage. PAGER =shell-command The command to use as a filter for paginating output. This can also be used to specify the options to be used. Default is more. prompt=s/n'rtg Set the command mode prompt to string. Default is ‘& ’. Refrain from printing the opening message and version when entering mail. Default is noquiet. record=filename Record all outgoing mail in filename. Disabled by default See also ‘outfolder’ above, replyall Reverses the effect of the reply and Reply commands. save Enable saving of messages in the dead.letter file on interrupt or delivery error. See ‘dead’ for a description of this file. Enabled by default. screen =number Sets the number of lines in a screen— full of headers for the headers command, sendmai \=shell-command Alternate command for delivering messages. Default is sendmail. sendwait Wait for background mailer to finish before returning. Default is nosendwait. SHELL =shell-command The name of a preferred command interpreter. Default is sh. Normally inherited from the environment. showto When displaying the header summary and the message is from you, print the recipient’s name instead of the author’s name. sign=string The variable inserted into the text of a message when the "a (autograph) command is Sun Release 3.0 Last change: 23 September 1985 201 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) given. No default (see also 'i (tilde escapes)). Sign =string The variable inserted into the text of a message when the "A command is given. No default (see also “i (tilde escapes)). toplines=/iwm6er The number of lines of header to print with the top command. Default is 5. verbose Invoke sendmail with the -v flag. VISUAL =shell-command The name of a preferred screen editor. Default is vi. FILES SHOME/.mailrc $HOME/mbox /usr/spool/mail/* /usr/lib/Mail.help* /usr/lib/Mail.rc /tmp/R[emqsx]* personal start-up file secondary storage file post office directory help message files global start-up file temporary files SEE ALSO binmail(l), sendmail(8), mailaddr(7) biff(l), fmt(l), aliases(5), newaliases(8). Mail is found in lusr/ucblMail, as a link to lusrlucblma.il. If you wish to use the original (version 7) UNIX mail program, you can find it in /bin/mail. Its man page is named binmail( 1). BUGS Where shell-command is shown as valid, arguments are not always allowed. Experimentation is recom- mended. Internal variables imported from the execution environment cannot be unset The full internet addressing is not fully supported by mail. The new standards need some time to settle down. 202 Last change: 23 September 1985 Sun Release 3.0 M AILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) NAME mailtool - window- and mouse-based interface for mail SYNOPSIS mailtool [ -x ] [ -i seconds ] DESCRIPTION mailtool is a standard tool provided with the SunView environment. mailtool manages your mail in much the same manner as mail, but provides a more convenient and power- ful user interface. Scrollable windows allow easy access to your mailbox and mail folders. Software "but- tons make the most frequently used commands readily available. Less used commands are accessable from menus and keyboard accelerators are provided for the more experienced user. The full editing capa- bilities of textedit( 1) and the SunView selection service are available for modifying and composing mail. In addition, the behavior of mailtool may be customized by setting parameters with defaultsedit{\). Users who are not familiar with the mail program should read mail(l) and Mail User’s Guide in the Beginner’s Guide to the Sun Workstation. For more information on mailtool, text editing, and use of the selection ser- vice see Windows and Window-Based Tools: Beginner’ s Guide. OPTIONS —x expert mode — don t ask for confirmation after potentially damaging mail commands - off by default — i seconds check for new mail every seconds seconds - default is 300 (5 minutes) mailtool also accepts all of the generic tool arguments discussed in suntools{ 1). SUB WINDOWS mailtool consists of four scrollable subwindows. From top to bottom they are: header a read-only text subwindow which lists the header information {From: and Subject: and so on) for mail messages in the current folder or system mailbox command a panel subwindow with software buttons corresponding to the most frequently used mail commands, and two text items for directory and file names message a text subwindow that allows reading and the editing of messages that you have received composition a text subwindow in which to compose and reply to messages (this subwindow appears only when composing or replying) COMMAND BUTTONS All buttons except next and undelete operate on the currently selected message. To select a message, make a selection anywhere on the line in the header subwindow corresponding to the desired message. This is accomplished by positioning the cursor anywhere on the line, and clicking the select mouse button (the leftmost one). The set of command buttons in the command panel is as follows, abort quit the tool without modifying your system mailbox cd change to the directory specified in the Directory: text field cancel abort the message being composed in the composition subwindow commit commit changes to your system mailbox compose open the composition subwindow to compose (or forward - see below) a message copy copy the selected message to the file or folder specified in the File: text field deliver send the message being composed in the composition subwindow delete delete the selected message done commit changes and close the tool Sun Release 3.0 Last change: 26 December 1985 203 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) folder new mail next preserve print quit reply save show undelete .mailrc commit changes and switch to the file or folder specified in the File: text field commit changes and reread the system mailbox to see new mail show the next message in the message subwindow hold the selected message in the system mailbox after the next commit print the selected message on a hardcopy printer commit changes and quit the tool open the composition subwindow to reply to the selected message save the selected message in the file or folder specified in the File: text field show the selected message in the message subwindow undelete the most recently deleted message(s) - this may be used repeatedly source your '/.mailrc file and thereby aquire the current option settings COMMAND MENUS All buttons in the command panel have menus behind them. Depress the right mouse button over a com- mand button to see its menu. Variations on a button command or related commands in mailtool have been grouped on these menus. For example, the reply buttton has menu items that reply to all recipients of the original message, reply including the original message, and reply to all recipients including the message. The compose button has the function forward grouped with it. All menus have corresponding keyboard acclerators - i.e. you may hold down a key while clicking the left mouse button to achieve the same effect without popping-up the menu. Two keys are used: shift and CTRL. In general, if a command has an "inverse" function like reversed direction, the shift key is used, and CTRL is used to "strengthen" a com- mand or invoke a related function. When a menu has actions corresponding to all four combinations of shift and CTRL, the order of the menu items is as follows: simply clicking on the command button, holding shift while clicking on the button, holding CTRL while clicking on the button, holding both shift and CTRL when clicking on the button. With this organization of commands, the keyboard accelerators for these command menu items may be quickly learned. Simply browse the button menus to discover what additional commands are available. There are two special file menus in the command panel. The menu behind the folder button will show you all your folders. The menu behind the File: text field holds the most recently used file (and folder) names. Selecting a name from these menus replaces the contents of the File: item just as if you typed the name. This name is used for the save, copy, and folder commands. Folder names are of the form +folder and are relative to the directory specified by the mail’s folder variable. Filenames typed into the File: field are relative to the directory specified in the Directory: field. To switch to a folder, select it from one of the file menus or type directly into the File: text field, and press the folder button. To return to your system mailbox, use the new mail button. MAIL VARIABLES mailtool interprets several variables in addition to those of mail. All can be set in your .mailrc file by using defaultsedit(l). allowreversescan allows you to work through your mailbox in the reverse, as well as forward, directions. This will affect which message is next - if the sense of direction is reverse then the message displayed by next is actually the previous one. autoprint display the next message when the current message is deleted or saved bell number of times to ring the bell when new mail arrives cmdlines number of lines in command panel expert sets expert mode - no confirmations required (same as the -x flag) 204 Last change: 26 December 1985 Sun Release 3.0 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) list of files to initialize the File: menu, (e.g. "+mbox +trash”) specifies the maximum size of the File: menu number of times to flash the window or icon when new mail arrives number of lines in header subwindow interval in seconds to check for new mail (same as the -i flag) number of lines in mail message subwindow percent of the message subwindow to remain visible during a reply or compose the command to use when printing mail — the default is Ipr -p. name of trash bin (if set to "+trash", this may be accessed like any other folder) If the trash variable is set, all deleted messages will be moved to the trash bin. You can look at the trash bin as with any other folder by typing its name to the File: item and hitting the folder button. The trash bin is emptied when you hit done. In addition, you can make your .mailrc conditionally set mail variables depending on whether it is running in the tty environment or the window environment. The command if t tests if you are in the tty environ- ment. For example: ift else set autoprint cd endif will set the variable autoprint and change to your home directory when mail is started in the SunView environment. FILES /usr/spool/mail/* post office / .mailrc file giving initial mail commands SEE ALSO binmail(l), defaultsedit{\), mail{\), suntools(l), textedit( 1) aliases (5), mailaddrfl), newaliases( 8), sendmail (8) Mail User’s Guide in the Beginner's Guide to the Sun Workstation, Windows and Window-Based Tools: Beginner’ s Guide BUGS If mail receives an error then mailtool may hang and you must kill it. New mail status is only approximate, therefore the presence of new mail is not always accurately reflected in the icon image and tool namestripe. If you press done and immediately interact with another window, a few interactions may be lost while mailtool is becoming iconic. filemenu filemenusize flash header lines interval maillines msgpercent printmail trash Sun Release 3.0 Last change: 26 December 1985 205 MAKE(l) USER COMMANDS MAKE(l) NAME make - maintain, update, and regenerate groups of programs SYNOPSIS make [-f makefile ] [— p] [— i] [-k] [-s] [— r] [-n] [— b] [— e] [-m] [— t] [-d] [— q] [-S] [ name ... ] OPTIONS — f makefile Description file name, makefile is assumed to be the name of a description file. A file name of - denotes the standard input. The contents of makefile override the built-in rules if they are present. -p Print out the complete set of macro definitions and target descriptions. -i Ignore error codes returned by invoked commands. This mode is entered if the fake target name JGNORE appears in the description file. -k Abandon work on the current entry, but continue on other branches that do not depend on that entry. -s Silent mode. Do not print command lines before executing. This mode is also entered if the fake target name .SILENT appears in the description file. -r Do not use the built-in rules. -n No execute mode. Print commands, but do not execute them. Even lines beginning with an @ are printed. -b Compatibility mode for old makefiles, -b is on by default. -e Environment variables override assignments within makefiles. -t Touch the target files (bringing them up-to-date) rather than issue the usual commands. -d Debug mode. Print out detailed information on files and times examined. -q Question. The make command returns a zero or non-zero status code depending on whether the target file is or is not up-to-date. -S Undoes the effect of the -k option. SPECIAL TARGET NAMES .DEFAULT If a file must be made but there are no explicit commands or relevant built-in rules, the com- mands associated with the name .DEFAULT are used if it exists. .PRECIOUS Dependents of this target will not be removed when quit or interrupt are hit. •SILENT Same effect as the -s option. .IGNORE Same effect as the -i option. DESCRIPTION make executes commands in makefile to update one or more target names. Name is typically a program. If no -f option is present, makefile, Makefile, s.makefile, s.Makefile, SCCS/s.makefiIe, and SCCS/s.Makefile are tried in order. If makefile is -, the standard input is taken. More than one -f makefile argument pair may appear. make updates a target only if its dependents are newer than the target. All prerequisite files of a target are added recursively to the list of targets. Missing files are deemed to be out of date. Include Files Make has an include file capability. If the string include appears as the first seven letters of a line in a makefile and is followed by a space or a tab, the string following the word include is taken as a filename which the current invocation of make will read, include files can be nested to a depth of no more than about 16 . 206 Last change: 23 September 1985 Sun Release 3.0 MAKE(l) USER COMMANDS MAKE(l) Make Entries Other than include lines, comments, and macro definitions, a Makefile contains a sequence of entries that specify dependencies. The first line of an entry is a blank-separated, non-null list of targets, then a :, then a (possibly null) list of prerequisite files or dependencies. Text following a ; and all following lines that begin with a tab are shell commands to be executed to update the target. The first line that does not begin with a tab or # begins a new dependency or macro definition. Shell commands may be continued across lines with the sequence. Everything printed by make (except the initial tab) is passed directly to the shell as is. Thus, echo a\ b will produce ab exactly the same as the shell would. Comments Sharp (#) and new-line surround comments. Example The following makefile says that pgm depends on two files a.o and b.o, and that they in turn depend on their corresponding source files (a.c and b.c) and a common file incLh: pgm: a.o b.o cc a.o b.o -o pgm a. o: incl.h a.c cc -c a.c b. o: incl.h b.c cc -c b.c Executing Command Lines Command lines are executed one at a time, each by its own shell. The first one or two characters in a com- mand can be the following: -, @, or If @ is present, the command is not printed before it is exe- cuted. If - is present, make ignores an error. A line is printed when it is executed unless the -s option is present, or the entry .SILENT: is in makefile, or unless the initial character sequence contains a @. The -n option specifies printing without execution; however, if the command line has the string $(MAKE) in it, the line is always executed (see discussion of the MAKEFLAGS macro under Environment). The -t (touch) option updates the modified date of a file without executing any commands. Commands returning non-zero status normally terminate make. If the -i option is present, or the entry JGNORE: appears in makefile, or the initial character sequence of the command contains -. the error is ignored. If the -k option is present, work is abandoned on the current entry, but continues on other branches that do not depend on that entry. The -b option allows old makefiles (those written for the old version of make) to run without errors. The difference between the old version of make and this version is that this version requires all dependency lines to have a (possibly null or implicit) command associated with them. The previous version of make assumed, if no command was specified explicitly, that the command was null. The -b option is on by default. Interrupt and quit cause the target to be deleted unless the target is a dependent of the special name .PRE- CIOUS. Environment make reads the environment. All environment variables are assumed to be macro definitions and are pro- cessed as such. Environment variables are processed before any makefile and after the internal rules; thus, macro assignments in a makefile override environment variables. The -e option makes the environment Sun Release 3.0 Last change: 23 September 1985 207 MAKE(l) USER COMMANDS MAKE ( 1 ) override the macro assignments in a makefile. make processes MAKEFLAGS environment variable as containing any legal input option (except -f, -p, and -d) defined for the command line. Further, upon invocation, make “invents” the variable if it is not in the environment, puts the current options into it, and passes it on to invocations of commands. Thus, MAKEFLAGS always contains the current input options. This proves very useful for “super-makes”. In fact, as noted above, when the -n option is used, die command $(MAKE) is executed anyway; hence, one can perform a make -n recursively on a whole software system to see what would have been executed. This is because the -n is put in MAKEFLAGS and passed to further invocations of $(MAKE). This is one way of debugging all of the makefiles for a software project without actually doing anything. For compatibility with the 4.2bsd make, the MFLAGS variable is set from the MAKEFLAGS variable by prepending a MFLAGS is not exported. Macros Entries of the form stringl = string2 are macro definitions. String2 is defined as all characters up to a com- ment character or an unescaped new-line. Subsequent appearances of $(stringl [:substl =[subst2]]) are replaced by string2. The parentheses are optional if a single character macro name is used and there is no substitute sequence. The optional :substl =subst2 is a substitute sequence. If it is specified, all non- overlapping occurrences of substl in the named macro are replaced by subst2. Strings (for the purposes of this type of substitution) are delimited by blanks, tabs, new-line characters, and beginnings of lines. An example of the use of the substitute sequence is shown under Libraries. Internal Macros There are five internally maintained macros which are useful for writing rules for building targets. $* The macro $* stands for the file name part of the current dependent with the suffix deleted. It is evaluated only for inference rules. $@ The $@ macro stands for the full target name of the current target. It is evaluated only for explicitly named dependencies. $< The $< macro is only evaluated for inference rules or the .DEFAULT rule. It is the module which is out-of-date with respect to the target (that is, the “manufactured” dependent file name). Thus, in the .c.o rule, the $< macro would evaluate to the .c file. An example for making optimized .0 files from •c files is: .c.o: cc -c -O $*.c or: .c.o: cc -c -0 $< $? The $? macro is evaluated when explicit rules from the makefile are evaluated. It is the list of prere- quisites that are out of date with respect to the target; essentially, those modules which must be rebuilt. $% The $% macro is only evaluated when the target is an archive library member of the form Iib(ffie.o). In this case, $@ evaluates to lib and $% evaluates to the library member, file.o. Four of the five macros can have alternative forms. When an upper case D or F is appended to any of the four macros, the meaning is changed to “directory part” for D and “file part” for F. Thus, $(@D) refers to the directory part of the string $@. If there is no directory part, J is generated. The only macro excluded from this alternative form is $?. Suffixes Certain names (for instance, those ending with . 0 ) have inferable prerequisites such as .c, .s, etc. If no update commands for such a file appear in makefile, and if an inferable prerequisite exists, that prerequisite is compiled to make the target In this case, make has inference rules which allow building files from other 208 Last change: 23 September 1985 Sun Release 3.0 MAKE(l) USER COMMANDS MAKE ( 1 ) files by examining the suffixes and determining an appropriate inference rule to use. Default inference rules exist for the following suffixes: .c .c' .f .f .F .F' .r s' .sh .sh' •C.o .c .0 .c .c .f.o .r.f .F.o .F.o .F.F .r.o .r'.o ,r'.r .s.o .s'.o .y.o .y'.o .l.o .l'.o .y.c .y'.c .l.c .c.a .c'.a .s'.a .h'.h To print out make ’ s internal rules, use the following command (note that this command only works with the Bourne Shell): $ make — fp — 2>/dev/nuIl /dev/tty) >&/dev/nulI A tilde in the above rules refers to an SCCS file (see ^ccs(l)). Thus, the rule .c".o would transform an SCCS C source file into an object file (.o). Because the s. of the SCCS files is a prefix, it is incompatible with make’s suffix point-of-view. Hence, the tilde is a way of changing any file reference into an SCCS file reference. The SCCS subdirectory scheme of the sees command is supported by make by looking for SCCSIs.file if it can’t find s.file. A rule with only one suffix (that is, .c:) is the definition of how to build x from xx. In effect, the other suffix is null. This is useful for building targets from only one source file (for example, shell procedures, simple C programs). Additional suffixes are given as the dependency list for .SUFFIXES. Order is significant; the first possible name for which both a file and a rule exist is inferred as a prerequisite. The default list is: > .SUFFIXES: .o .c .c‘ .f .f .F .F .r .r' .p .p' .y .y' .1 .1" , s .s' .sh .sh' .h .h' Here again, the above command for printing the internal rules will display the list of suffixes implemented on the current machine. Multiple suffix lists accumulate; .SUFFIXES: with no dependencies clears the list of suffixes. Inference Rules The first example can be done more briefly. pgm: a.o b.o cc a.o b.o -o pgm a.o b.o: incl.h This is because make has a set of internal rules for building files. The user may add rules to this list by simply putting them in the makefile. Certain macros are used by the default inference rules to permit the inclusion of optional matter in any resulting commands. For example, CFLAGS, LFLAGS, and YFLAGS are used for compiler options to cc, lex, and yacc, respectively. Again, the previous method for examining the current rules is recommended. The inference of prerequisites can be controlled. The rule to create a file with suffix .o from a file with suffix .c is specified as an entry with .c.o: as the target and no dependents. Shell commands associated with the target define the rule for making a .o file from a .c file. Any target that has no slashes in it and starts with a dot is identified as a rule and not a true target. Libraries If a target or dependency name contains parentheses, it is assumed to be an archive library, the string within parentheses referring to a member within the library. Thus lib(file.o) and $(LIB)(file.o) both refer to an archive library which contains fiIe.o. (This assumes the LIB macro has been previously defined.) The expression $(LIB)(filel.o fi!e2.o) is not legal. Rules pertaining to archive libraries have the form Jff.a where the XX is the suffix from which the archive member is to be made. An unfortunate byproduct of the current implementation requires the XX to be different from the suffix of the archive member. Thus, one Sun Release 3.0 Last change: 23 September 1985 209 MAKE(l) USER COMMANDS MAKE ( 1 ) cannot have lib(file.o) depend upon file.o explicitly. The most common use of the archive interface fol- lows. Here, we assume the source files are all C type source: lib: lib(filel.o) lib(file2.o) lib(file3.o) @echo lib is now up-to-date .c.a: $(CC) -c $(CFLAGS) $< ar rv $@ $*.o rm -f $*.o In fact, the .c.a rule listed above is built into make and is unnecessary in this example. A more interesting, but more limited example of an archive library maintenance construction follows: lib: lib(filel.o) lib(file2.o) lib(file3.o) $(CC) -c $(CFLAGS) $(?:.o=.c) ar rv lib $? rm $? @echo lib is now up-to-date .c.a:; Here the substitution mode of the macro expansions is used. The $? list is defined to be the set of object file names (inside lib) whose C source files are out-of-date. The substitution mode translates the .o to .c. Unfortunately, one cannot as yet transform to .c"; however, this may become possible in the future. Note also, the disabling of the .c.a: rule, which would have created each object file, one by one. This particular construct speeds up archive library maintenance considerably. This type of construct becomes very cumbersome if the archive library contains a mix of assembly programs and C programs. FILES [Mmjakefile and s.[Mm]akefile and SCCS/s.[mM]akefile SEE ALSO cc(l), cd(l), lex(l), sh(l), yacc(l), sccss(l) in Commands Reference for the Sun Workstation. UNIX System Programmer Reference Manual. BUGS Some commands return non-zero status inappropriately; use -i to overcome the difficulty. File names with the characters = : @ will not work. Commands that are directly executed by the shell, notably cd, are ineffectual across new-lines in make. The syntax (lib(filel.o file2.o file3.o) is illegal. You cannot build Iib(file.o) from file.o. In fact, the current version of make does not support references to objects in libraries (using the libe(file.o) notation) at all. The macro $(a:.o=.c') does not work. 210 Last change: 23 September 1985 Sun Release 3.0 MAN ( 1 ) USER COMMANDS MAN ( 1 ) NAME man - print out manual pages; find manual information by keywords SYNOPSIS man [ - ] [ -t ] [ -P path ] [ section ] title . . . man — k keyword . . . man -f file ... DESCRIPTION Man displays information from the UNIX System manual pages. Man can be asked for one line descrip- tions of commands specified by name, or for all commands whose description contains any of a set of key- words. Man can also provide on-line access to the sections of the printed manual. Man’s standard behavior when neither the -k nor -f option is specified (see OPTIONS below) is to format a specified set of manual pages. In the absence of any specific options to the contrary, man looks for already formatted manuals in the lusrlmanlcatl directories and uses the information cached there. Otherwise, man must format the pages on the fly — in this case you get a message asking you to wait patiently. If section is omitted, man searches all sections of the manual, giving preference to commands over subrou- tines in system libraries, and prints the first section it finds, if any. If a section is specified, man looks in that section of the manual for the given titles. Section is an arabic section number (‘3’ for instance); the number may be followed by a single letter classifier (‘lg’, for instance, indicating a graphics program in Section 1). Finally, section can be one of the keywords ‘public’, ‘local’, ‘old’, or ‘new’. If the standard output is a terminal, or if you use the - flag, man pipes its output through car(l) with the -s option to crush out useless blank lines, u/(l) to create proper underlines for different terminals, and through more( 1) to stop after each page on the screen. Type a space to continue, and a control-D to scroll 11 more lines when the output stops. OPTIONS -P path Use path as the starting pathname for the manual pages. Manual page sections must reside in pathlmml instead of in lusrlmanl man? — k keywords Display a one line synopsis of each manual section whose listing in the table of contents contains any of the keywords. — f filenames Attempt to locate manual sections related to those files, and display the table of contents lines for those sections. -t Use troff to format the specified section, assuming you have a suitable raster output device which can actually handle troff s output. FILES /usr/man/man?/* manual pages in nr off! troff source /usr/man/cat?/* formatted manual pages SEE ALSO more(l), ul(l), whereis(l), catman(8) Sun Release 3.0 Last change: 5 November 1984 211 MESG(l) USER COMMANDS MESG(l) NAME mesg - permit or deny messages SYNOPSIS mesg [ n ] [ y ] DESCRIPTION Mesg with argument n forbids messages via write (l) by revoking non-user write permission on the user’s terminal. Mesg with argument y reinstates permission. All by itself, mesg reports the current state without changing it. FILES /dev/tty* SEE ALSO write(l), talk(l) DIAGNOSTICS Exit status is 0 if messages are receivable, 1 if not, 2 on error. 212 Last change: 16 February 1984 Sun Release 3.0 MKDIR(l) USER COMMANDS MKDIR(l) NAME mkdir - make a directory SYNOPSIS mkdir dirname . . . DESCRIPTION Mkdir creates directories. Standard entries, V, for the directory itself, and ‘.. 1 automatically. The current umask( 2) setting determines the mode in which directories are modified after creation by using chmod{ 1). Mkdir requires write permission in the parent directory. SEE ALSO chmod(l), rmdir(l), rm(l) for its parent, are made created. Modes may be Sun Release 3.0 Last change: 15 March 1983 213 MKSTR(l) USER COMMANDS MKSTR ( 1 ) NAME mkstr — create an error message file by massaging C source SYNOPSIS mkstr [ - ] messagefile prefix file . . . DESCRIPTION Mkstr creates files of error messages. You can use mkstr to make programs with large numbers of error diagnostics much smaller, and to reduce system overhead in running the program — as the error messages do not have to be constantly swapped in and out. Mkstr processes each of the specified files, placing a massaged version of the input file in a file whose name consists of the specified prefix and the original name. A typical example of using mkstr would be: mkstr pistrings xx *.c This command would cause all the error messages from the C source files in the current directory to be placed in the file pistrings and processed copies of the source for these files to be placed in files whose names are prefixed with xx. To process the error messages in the source to the message file, mkstr keys on the string ‘error(’” in the input stream. Each time it occurs, the C string starting at the is placed in the message file followed by a null character and a new-line character; the null character terminates the message so it can be easily used when retrieved, the new-line character makes it possible to sensibly cat the error message file to see its contents. The massaged copy of the input file then contains a Iseek pointer into the file which can be used to retrieve the message, that is: char efilnameQ = "/usr/lib/pi_strings"; int efil = -1 ; error(al, a2, a3, a4) { char buf[256]; if (efil < 0) { efil = open(efilname, 0); if (efil < 0) { oops: perror(efilname); exit(l); } } if (lseek(efil, (long) al, 0) 1 1 read(efil, buf, 256) <= 0) goto oops; printf(buf, a2, a3, a4); } OPTIONS - Place error messages at the end of the specified message file for recompiling part of a large mkstr ’d program. SEE ALSO xstr(l) 214 Last change: 1 November 1983 Sun Release 3.0 MORE ( 1 ) USER COMMANDS MORE ( 1 ) NAME more, page - browse through a text file SYNOPSIS more [ -cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ name . . . ] page [ -cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ name . . . ] DESCRIPTION More is a filter which displays the contents of a text file one screenful at a time on a video terminal. It nor- mally pauses after each screenful, and prints ‘--More-’ at the bottom of the screen. More displays another line if you type a carriage-return; more displays another screenful if you type a space. If you use the page command instead of the more command, the screen is cleared before each screenful is displayed (but only if a full screenful is being displayed), and k-\ rather than k- 2 lines are displayed in each screenful, where k is the number of lines the terminal can display. More looks in the file lelcltermcap to determine terminal characteristics, and to determine the default win- dow size. On a terminal capable of displaying 24 lines, the default window size is 22 lines. More looks in the environment variable MORE to pre-set any flags desired. For example, if you prefer to view files using the -c mode of operation, the csh command "setenv MORE -c" or the sh command sequence "MORE= -c' ; export MORE" would cause all invocations of more , including invocations by programs such as man to use this mode. Normally, the user will place the command sequence which sets up the MORE environment variable in the .login or .profile file. If more is reading from a file, rather than a pipe, a percentage is displayed along with the -More- prompt. This gives the fraction of the file (in characters, not lines) that has been read so far. Other sequences which may be typed when more pauses, and their effects, are as follows (i is an optional integer argument, defaulting to 1) : i display i more lines, (or another screenful if no argument is given) T> display 1 1 more lines (a “scroll’ ’). If i is given, the scroll size is set to i . d same as "D (control-D) i z same as typing a space except that i , if present, becomes the new window size. i s skip i lines and print a screenful of lines i f skip i screenfuls and print a screenful of lines q or Q Exit from more. = Display the current line number. v Start up the editor vi at the current line. h Help command; give a description of all the more commands. i/expr search for the i-th occurrence of the regular expression expr. If there are less than i occurrences of expr , and the input is a file (rather than a pipe), the position in the file remains unchanged. Otherwise, a screenful is displayed, starting two lines before the place where the expression was found, or the end of the pipe, whichever comes first. The user’s erase and kill characters may be used to edit the regular expression. Erasing back past the first column cancels the search com- mand. i n search for the i -th occurrence of the last regular expression entered. (single quote) Go to the point from which the last search started. If no search has been performed in the current file, this command goes back to the beginning of the file. Sun Release 3.0 Last change: 13 March 1984 215 MORE ( 1 ) USER COMMANDS MORE ( 1 ) Icommand invoke a shell with command. The characters *%’ and *!’ in "command" are replaced with the current file name and the previous shell command respectively. If there is no current file name, is not expanded. The sequences "\%" and "V!" are replaced by "%" and "!" respectively. i :n skip to the i -th next file given in the command line (skips to last file if n doesn’t make sense) i :p skip to the i -th previous file given in the command line. If this command is given in the middle of printing out a file, more goes back to the beginning of the file. If i doesn’t make sense, more skips back to the first file. If more is not reading from a file, the bell is rung and nothing else happens. :f display the current file name and line number. :q or :Q exit from more (same as q or Q). (dot) repeat the previous command. The commands take effect immediately; it is not necessary to type a carriage return. Up to the time when the command character itself is given, the user may type the line kill character to cancel the numerical argument being formed. In addition, the user may type the erase character to redisplay the -More-(xx%) message. At any time when output is being sent to the terminal, the user can type the quit key (normally controM). More stops sending output, and displays the usual -More-- prompt. The user may then enter one of the above commands in the normal manner. Unfortunately, some output is lost when this is done, due to the fact that any characters waiting in the terminal’s output queue are flushed when the quit signal occurs. More sets the terminal to noecho mode so that the output can be continuous. Thus what you type does not show on your terminal, except for the / and ! commands. If the standard output is not a terminal, more acts just like cat, except that a header is printed before each file in a series. OPTIONS -lines Set the size of the window to lines lines long instead of the default -c Display each page by redrawing the screen instead of scrolling. This makes it easier to read text while more is writing. This option is ignored if the terminal does not have the ability to clear to the end of a line. -d Display the message ‘Hit space to continue, Rubout to abort’ at the end of each screenful. This is useful if more is being used as a filter in some setting, such as a class, where users are unsophisti- cated. -f Count logical rather than screen lines. That is, long lines are not folded. This option is recom- mended if nroff output is being piped through ul, since the latter may generate escape sequences. These escape sequences contain characters which would ordinarily occupy screen postions, but which do not print when they are sent to the terminal as part of an escape sequence. Thus more may think that lines are longer than they actually are, and fold lines erroneously. -1 Do not treat X (form feed) specially. If -l is not used, more pauses after any line that contains a X, as if the end of a screenful had been reached. Also, if a file begins with a form feed, the screen is cleared before the file is printed. -s Squeeze multiple blank lines from the output, and replace them with single blank lines. Especially helpful when viewing nroff output, this option maximizes the useful information present on the screen. -u Normally, more handles underlining such as produced by nroff in a manner appropriate to the par- ticular terminal: if the terminal can perform underlining or has a stand-out mode, more outputs appropriate escape sequences to enable underlining or stand-out mode for underlined information in the source file. The -u option suppresses this processing. +linenumber 216 Last change: 13 March 1984 Sun Release 3.0 MORE ( 1 ) USER COMMANDS MORE ( 1 ) Start up at linenumber. +lpattern Start up two lines before the line containing the regular expression pattern. EXAMPLES A sample usage of more in previewing nroff output would be nroff -ms +2 doc.n | more -s FILES /etc/termcap Terminal data base /usr/lib/more.helpHelp file SEE ALSO csh(l), man(l), script(l), sh(l), environ(5), termcap(5) Sun Release 3.0 Last change: 13 March 1984 217 MT ( 1 ) USER COMMANDS MT ( 1 ) NAME mt - magnetic tape manipulating program SYNOPSIS mt [ -f tapename ] command [ count ] DESCRIPTION mt sends commands to a magnetic tape drive. If tapename is not specified, the environment variable TAPE is used; if TAPE does not exist, mt uses the device Idev/rmtl2. Note that tapename must reference a raw (not block) tape device. By default mt performs the requested operation once. Operations may be per- formed multiple times by specifying count. The available commands are listed below. Only as many characters as are required to uniquely identify a command need be specified. eof, weof Write count end-of-file marks at the current position on the tape, fsf Forward space count files, fsr Forward space count records, bsf Back space count files, bsr Back space count records. For the following commands, count is ignored; rewind Rewind the tape, offline, rewoffl Rewind the tape and place the tape unit off-line, status Print status information about the tape unit retension Wind the tape to the end of the reel and then rewind it, smoothing out the tape tension. ( count is ignored.) erase Erase the entire tape. mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2 if an operation failed. FILES /dev/rmt* Raw magnetic tape interface /dev/rar* Raw Archive cartridge tape interface /dev/rst*Raw SCSI tape interface /dev/rxt* Raw Xylogics tape interface SEE ALSO mtio(4), dd(l), environ(5) BUGS Not all devices support all options. For example, ar(4s) and st(4s) currently do not support the fsr, bsf, or bsr options; but they are the only only ones that currently support the retension and rewind options. Nine-track tapes, in particular, do not support the retension option. 218 Last change; 23 September 1985 Sun Release 3.0 MV ( 1 ) USER COMMANDS MV ( 1 ) NAME mv - move or rename files SYNOPSIS mv [ — i ] [ — f ] [ — ] filename 1 filename2 mv [ -i ] [ -f ] [ - ] directoryl directory2 mv [ — i ] [ — f ] [ — ] filename . . . directory . . . directory DESCRIPTION mv moves files and directories around in the file system. A side effect of mv is to rename a file or direc- tory. The three major forms of mv are shown in the synopsis above. The first form of mv moves (changes the name of) filename! to filename2 . \ffilename2 already exists, it is removed before filename 1 is moved, \ffilename2 has a mode which forbids writing, mv prints the mode (see chmod( 2)) and reads the standard input to obtain a line; if the line begins with y, the move takes place otherwise mv exits. ’ The second form of mv moves (changes the name of) directoryl to directory2, ONLY if directory2 does not already exist — if it does, the third form applies. The third form of mv moves one or mor e files and directories, with their original names, into the last direc- tory in the list. mv refuses to move a file or directory onto itself. OPTIONS -i interactive mode: mv displays the name of the file or directory followed by a question mark when- ever a move would replace an existing file or directory. If you type a line starting with ’y’, mv moves the specified file or directory, otherwise mv does nothing with that file or directory. — f force, override any mode restrictions and the — i switch. The — f option also suppresses any warn- ing messages about modes which would potentially restrict overwriting. Interpret all the following arguments to mv as file names. This allows file names starting with minus. SEE ALSO cp(l), ln(l) BUGS If filename 1 andfilename2 are on different file systems, then mv must copy the file and delete the original. In this case the owner name becomes that of the copying process and any linking relationship with other files is lost. mv will not move a directory from one file system to another. Sun Release 3.0 Last change: 23 September 1985 219 NICE ( 1 ) USER COMMANDS NICE ( 1 ) NAME nice, nohup - run a command at low priority ( sh only) SYNOPSIS nice [ -number ] command [ arguments ] nohup command [ arguments ] DESCRIPTION Nice executes command with low scheduling priority. If the number argument is present, the priority is incremented (higher numbers mean lower priorities) by that amount up to a limit of 20. The default number is 10. The super-user may run commands with priority higher than normal by using a negative priority, e.g. ‘— 10 ’. Nohup executes command immune to hangup and terminate signals from the controlling terminal. The priority is incremented by 5. Nohup should be invoked from the shell with *&’ in order to prevent it from responding to interrupts by or stealing the input from the next person who logs in on the same terminal. The syntax of nice is also different. FILES nohup.out standard output and standard error file under nohup SEE ALSO csh(l), nice(3C), renice(8) DIAGNOSTICS Nice returns the exit status of the subject command. BUGS Nice and nohup are particular to s/i(l). If you use csh(l), then commands executed with “&” are automatically immune to hangup signals while in the background. There is a builtin command nohup which provides immunity from terminate, but it does not redirect output to nohup.out. Nice is built into c^(l) with a slightly different syntax than described here. The form “nice +10” nices to positive nice, and “nice -10” can be used by the super-user to give a process more of the processor. 220 Last change: 9 June 1983 Sun Release 3.0 NM( 1 ) USER COMMANDS NM(1 ) NAME nm - print name list SYNOPSIS nm [ -gnoprua ] [file...] DESCRIPTION Nm prints the name list (symbol table) of each object file in the argument list If an argument is an archive a listing for each object file in the archive will be produced. If no file is given, the symbols in a out are listed. Each symbol name is preceded by its value (blanks if undefined) and one of the letters: U undefined A absolute T text segment symbol D data segment symbol B bss segment symbol C common symbol f file name, debug, giving symbol table entries (see -a below). If the symbol is local (non-external) the type letter is in lower case. The output is sorted alphabetically. OPTIONS -g Print only global (external) symbols. -n Sort numerically rather than alphabetically. -o Prepend file or archive element name to each output line rather than only once. -p Don’t sort; print in symbol-table order. — r Sort in reverse order. — u Print only undefined symbols. -a Print all symbols. EXAMPLE nm prints the symbol list of a. out, the default output file for the C, FORTRAN 77 and Pascal compilers. SEE ALSO ar(l), ar(5), a.out(5) Sun Release 3.0 Last change: 9 June 1983 221 NROFF(l) USER COMMANDS NROFF(l) NAME nroff - text formatting SYNOPSIS nroff [ -o pagelist ] [ -n N ] [ -s N ] [ -m name ] [ -raN ] [ -i ] [ -q ] [ -T name ] [ -e ] [ -fa ] [filename ] . . . DESCRIPTION nroff formats text in the named files for typewriter-like devices. See also troff{\). The full capabilities of nroff and troff are described in Formatting Documents with Nroff and Troff. If no file argument is present, nroff reads the standard input. An argument consisting of a single minus (-) is taken to be a file name corresponding to the standard input. OPTIONS Options may appear in any order so long as they appear before the files. -o list Print only pages whose page numbers appear in the comma-separated list of numbers and ranges. A range N-M means pages N through M ; an initial -N means from the beginning to page N ; and a final N- means from N to the end. -niV Number first generated page N . -s N Stop every N pages, nroff will halt prior to every N pages (default JV=1) to allow paper loading or changing, and will resume upon receipt of a newline. — m name Prepend the macro file lusrllibltmacltmac.name to the input files. -raN Set register a (one-character) to N. -i Read standard input after the input files are exhausted. -q Invoke the simultaneous input-output mode of the rd request. — T name Prepare output for a device of the specified name . Known names are: 37 Teletype Corporation Model 37 terminal — this is the default tn300 GE TermiNet 300 (or any terminal without half-line capability). 300 DASI-300. 300-12 DASI-300 — 12-pitch. 300S DASI-300S (or 302). 300S-12 DASI-300S (or 302-12). 300X DASI-300X. 382 DASI-382 (fancy DTC 382). 382-12 DASI-82 (fancy DTC 382 — 12-pitch). 450 DASI-450 (Diablo Hyterm). 450-12 DASI-450 (Diablo Hyterm) — 12-pitch. 450-12-8 DASI-450 (Diablo Hyterm) — 12-pitch and 8 lines-per-inch. 450X DASI-450X (Diablo Hyterm). 833 AJ 833 or AJ 832. 833-12 AJ 833 or AJ 832 — 12-pitch, itoh C:ITOH Prowriter. itoh- 12 C:ITOH Prowriter — 12-pitch. nec NEC 55?0 or NEC 77?0 Spinwriter. nec 12 NEC 5570 or NEC 7770 Spinwriter — 12-pitch. nec-t NEC 5570/7770 Spinwriter — Tech-Math/Times-Roman thimble. qume Qume Sprint — 5 or 9. qumel2 Qume Sprint — 5 or 9, 12-pitch. xerox Xerox 1770 or Diablo 1670. 222 Last change: 23 September 1985 Sun Release 3.0 NROFF(l) USER COMMANDS NROFF(l) xerox 12 Xerox 17?0 or Diablo 16?0 — 12-pitch, x-ecs Xerox/Diablo 1730/630 — Extended Character Set. x-ecsl2 Xerox/Diablo 1730/630 — Extended Character Set, 12-pitch, lpr Line printer. -e Produce equally-spaced words in adjusted lines, using full terminal resolution. -h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every 8 nominal character widths. EXAMPLE gaia% nroff — s4 —me users.guide Formats users.guide using the -me macro package, and stopping every 4 pages. FILES /tmp/ta* temporary file /usr/lib/ tmac/tmac. * standard macro files /usr/lib/term/* terminal driving tables for nroff /usr/lib/term/READMEindex to terminal description files SEE ALSO Formatting Documents on the Sun Workstation Using nroff and trof f on the Sun Workstation troff(l), eqn(l), tbl(l), ms(7), me(7), man(7), col(l), checknr(l) Sun Release 3.0 Last change: 23 September 1985 223 OD ( 1 ) USER COMMANDS OD ( 1 ) NAME od - octal, decimal, hex, ascii dump SYNOPSIS od [ -format ] [ file ] [ [+]offset[.][b] [label] ] DESCRIPTION Od displays file, or it’s standard input, in one or more dump formats as selected by the first argument. If the first argument is missing, -o (octal) is the default. Dumping continues until end-of-file. The meanings of the format argument characters are: a Interpret bytes as characters and display them with their ASCII names. If the p character is given also, bytes with even parity are underlined. If the P character is given, bytes with odd parity are underlined. Otherwise the parity bit is ignored. b Interpret bytes as unsigned octal. c Interpret bytes as ASCII characters. Certain non-graphic characters appear as C escapes: null=\0, backspace=\b, formfeed=\f, newline=\n, retum=\r, tab=\t; others appear as 3-digit octal numbers. Bytes with the parity bit set are displayed in octal. d Interpret (short) words as unsigned decimal, f Interpret long words as floating point, h Interpret (short) words as unsigned hexadecimal, i Interpret (short) words as signed decimal. 1 Interpret long words as signed decimal, o Interpret (short) words as unsigned octal. s[n] Look for strings of ASCII graphic characters, terminated with a null byte. N specifies the minimum length string to be recognized. By default, the minimum length is 3 characters. v Show all data. By default, display lines that are identical to the last line shown are not output, but are indicated with an in column 1. w[n] Specifies the number of input bytes to be interpreted and displayed on each output line. If w is not specified, 16 bytes are read for each display line. If n is not specified, it defaults to 32. x Interpret (short) words as hexadecimal. An upper case format character implies the long or double precision form of the object The offset argument specifies the byte offset into the file where dumping is to commence. By default this argument is interpreted in octal. A different radix can be specified; If is appended to the argument, then offset is interpreted in decimal. If offset begins with “x” or “Ox”, it is interpreted in hexadecimal. If “b” (“B”) is appended, the offset is interpreted as a block count, where a block is 512 (1024) bytes. If the file argument is omitted, an offset argument must be preceded by “+”. The radix of the displayed address will be the same as the radix of the offset, if specified; otherwise it will be octal. Label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in “()” follow- ing the file offset. It is intended to be used with core images to indicate the real memory address. The syn- tax for label is identical to that for offset. SEE ALSO adb(l), dbxtool(l), dbx(l) BUGS A file name argument can’t start with “+”. A hexadecimal offset can’t be a block count. Only one file name argument can be given. 224 Last change: 8 March 1984 Sun Release 3.0 0D( 1 ) USER COMMANDS OD(l ) It is an historical botch to require specification of object, radix, and sign representation in a single character argument Sun Release 3.0 Last change: 8 March 1984 225 OVERVIEW ( 1 ) USER COMMANDS OVERVIEW ( 1 ) NAME overview - run a program from SunView that takes over the screen SYNOPSIS overview [ generic tool Jlags ] programjiame [ arguments ] . . . DESCRIPTION Bitmap graphics based programs that are not SunView based can be run from SunView using overview. Overview shows an icon in SunView when overview is brought up iconic (-Wi flag) or when the program being run by overview is suspended (for example using ctrl-Z). Opening the overview icon, or starting overview non-iconic, starts the program named on the command line. Overview supresses SunView so that SunView window applications won’t interfere with the program’s display output or input devices. Overview is mainly designed to ran programs that fit the following profile: own display The program needs to own the bits on the screen. It doesn’t use the sunwindow or suntool libraries to arbitrate the use of the display and input devices between processes. keyboard input from stdin The program takes keyboard input from stdin directly. mouse input from Idevlmouse The program takes locator input from the mouse directly. SEE ALSO Windows and Window-Based Tools: Beginner’s Guide 226 Last change: 24 December 1985 Sun Release 3.0 PASSWD ( 1 ) USER COMMANDS PASSWD ( 1 ) NAME passwd — change login password SYNOPSIS passwd [ — f filename ] [ username ] DESCRIPTION This command changes (or installs) a password associated with the username (your own by default). passwd prompts for the old password and then for the new one. You must supply both, and the new pass- word must be typed twice to forestall mistakes. New passwords should be at least five characters long, if they combine upper and lower-case characters, or at least six characters long if in monocase. Users that persist in entering shorter passwords are compromis- ing their own security. Only the owner of the name or the super-user may change a password; the owner must prove he knows the old password. Use yppasswd to change your password in the network yellow pages. This will not affect your local pass- word, or your password on any remote machines on which you have accounts. OPTIONS -f Treat file as the password file. FILES /etc/passwd /etc/yp/passwd SEE ALSO login(l), passwd(5), yppasswd(l) Robert Morris and Ken Thompson, UNIX Password Security BUGS passwd will change a local password, but not a password in the network Yellow Pages. Refer to yppasswd (1) for information on how to change a Yellow Pages password. Sun Release 3.0 Last change: 23 September 1985 227 PC(1) USER COMMANDS PC(1) NAME pc — Pascal compiler SYNOPSIS pc [ — c ] [ — g ] [ — o output ] [ — O ] [ — b ] [ — C ] [ -Dname[=def] ] \_float_option ] [ — H ] [ — i name . . . ] [ — I dir ] [ — 1 ] [ — lpfc ] [ — L ] [ — p ] [ — P ] [ — pg ] [ — s ] [ — S ] [ -U name ] [ -w ] [ -z ] [ -l]filename.p . . . DESCRIPTION Pc is the Sun Pascal compiler. If given an argument file ending with .p, pc compiles the file and leaves the result in an executable file called a. out by default. A program may be separated into more than one .p file. Pc will compile a number of .p files into object files (with the extension .o in place of .p). Object files may then be loaded into an executable a. out file. Exactly one object file must supply a program statement to successfully create an executable a. out file. The rest of the files must consist only of declarations which logically nest within the program. References to objects shared between separately compiled files are allowed if the objects are declared in included header files, whose names must end with .h. Header files may only be included at the outermost level, and thus declare only globally available objects. To allow external functions and procedures to be declared, an external directive has been added, whose use is similar to the forward directive but restricted to appear only in .h files. Function and procedure bodies may not appear in .h files. A binding phase of the com- piler checks that declarations are used consistently, to enforce the type checking rules of Pascal. Object files created by other language processors may be loaded together with object files created by pc. The functions and procedures they define must have been declared in .h files included by all the .p files which call those routines. Pascal’s calling conventions are compatible with those of C, with var parameters passed by address and other parameters passed by value. pc supports ISO Level 1 Standard Pascal, including conformant array parameters. Deviations from the ISO Standard are noted under BUGS below. See the Pascal User' s Manual for details. OPTIONS See ld(l) for load- time options. — c Suppress loading and produce .o file(s) from source file(s). -g Produce additional symbol table information for the symbolic debugger dbx( 1). -o name Name the final output file name instead of a.out. -O Optimize the object code. -b Buffer the file output in units of disk blocks, rather than lines — C Compile code to perform subscript and subrange checks and verify assert statements. Note that pointers are not checked. This option differs significantly from the -C option of the cc compiler. — D name[=def] Define name to the preprocessor, as if by a #define directive. If no def is given, name is defined as 1. float_option Floating-point code generation option. Can be one of: -fsoft software floating-point calls (This is the default). -fsky in-line code for Sky floating-point processor (supported only on Sun-2). -f6888I in-line code for Motorola 6888 1 floating-point processor supported only on Sun-3), -fswitch run-time-switched floating-point calls. The compiled object code is linked at run- 228 Last change: 21 December 1985 Sun Release 3.0 PC(1) USER COMMANDS PC(1) time to routines that support one of the above types of floating-point code. This was the default in previous releases. Only for use with programs that are floating-point intensive, and which must be portable to machines with various floating-point options. When invoked without floatation, the compiler interrogates the FLOATOPTION environment variable to determine the type of floating-point code to generate. Legal values for FLOATOPTION are: ‘fsoft’, ‘fsky’, ‘f68881’ and ‘fswitch’. -H Compile code to perform range checking on pointers into the heap. -i name Produce a listing for the specified procedures, functions and include files. -Idz'r Add dir to the list of directories in which to search for #include files with names not beginning with slash The preprocessor first searches for #include in the directory containing filename. p, then in directories named with -I options (if any), and finally, in /usr/include . -1 Make a program listing during translation. -Ipfc Load common startup code for programs containing mixed Pascal and FORTRAN 77 object files. Such programs should also be loaded with the FORTRAN 77 libraries (see files below). -L Map upper case letters in keywords and identifiers to lower case. -p Prepare object files for profiling with gprof(l). -P Use partial evaluation semantics for the boolean operators and and or. For these operators only, left-to-right evaluation is guaranteed, and the second operand is evaluated only if necessary to determine the result. -pg Produce counting code in the manner of -p, but invoke a run-time recording mechanism that keeps more extensive statistics and produces a gmon.out at normal termination. An execution profile can then be generated using gprof{ 1). -s Accept standard Pascal only; nonstandard constructs and extensions cause warning diagnostics. -S Compile the named program, and leave the assembly language output on the corresponding file suffixed ‘.s’. No ‘.o’ is created. — U name Remove any initial definition of name. -w Suppress warning messages. -z Allow execution profiling with pxp(l) by generating statement counters, and arranging for the creation of the profile data file pmon.out when the resulting object is executed. -Z Initialize local variables to zero. Other arguments are taken to be loader option arguments or libraries of pc -compatible routines. Certain flags can also be controlled by comments within the program, as described in the Pascal User’s Manual in the Sun Pascal Manual. FILES file.p /lib/cpp /usr/lib/pcO /lib/fl /usr/lib/pc2 /lib/c2 /usr/lib/pc3 /usr/lib/pc3.2strings /usr/lib/how_pc /usr/lib/libpc.a Pascal source files macro preprocessor compiler front end code generator inline expander of library calls peephole optimizer separate compilation consistency checker text of the error messages basic usage explanation intrinsic functions and I/O library Sun Release 3.0 Last change: 21 December 1985 229 PC(1) USER COMMANDS PC(1) /usr/lib/libpfc.a /usr/lib/libF7 7 . a /usr/lib/libI77.a /usr/lib/libU77.a /usr/lib/libm.a /lib/libc.a SEE ALSO The Pascal User's Manual pi(l), pxp(l), pxref(l) DIAGNOSTICS For a basic explanation do tutorial% pc In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be able to continue parsing. Some diagnostics indicate only that the input is ‘malformed.’ This occurs if the recovery can find no simple correction to make the input syntactically valid. Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis The first character of each error message indicates its class: E Fatal error; no code will be generated, e Nonfatal error, w Warning - a potential problem, s Nonstandard Pascal construct warning. If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then ‘QUIT’. Names whose definitions conflict with library definitions draw a warning. The library definition will be replaced by the one supplied in the Pascal program. Note that this can have unpleasant side effects. BUGS The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked structures to be distinguished for portability reasons. Binary set operators are required to have operands with identical types; the ISO standard allows different types, as long as the underlying base types are compatible. The -z flag doesn’t work for separately compiled files. Because the -s option is usurped by the compiler, it is not possible to pass the strip option to the loader. Thus programs which are to be stripped, must be run through strip ( 1) after they are compiled. startup code for combined Pascal and FORTRAN programs FORTRAN intrinsics library FORTRAN I/O library FORTRAN <=>Unix interface library math library standard library, see intro ( 3) in the Sun Pascal Manual. 230 Last change: 21 December 1985 Sun Release 3.0 PERFMETER ( 1 ) USER COMMANDS PERFMETER ( 1 ) NAME perfmeter - meter display of system performance values SYNOPSIS perfmeter [ -s sampletime ] [ -h hourhandintv ] [ -m minutehandintv ] [ -M value minmax maxmax ] [ -v value ] [ hostname ] DESCRIPTION perfmeter starts a tool whose iconic form is a meter displaying a system performance value, and whose open form is a strip chart of that value. The default is for the meter to be updated with a sampletime of 2 seconds, for the hour hand to represent an average over an interval of 20 seconds, for the minute hand to represent an average over 2 seconds, and for the value being displayed to be percent of cpu being utilized. These defaults can be modified with command line arguments, or dynamically after the tool has been started. If there is no hostname argument, then the data displayed will be for the local machine, otherwise for the machine named by hostname. In either case, the rstatd(8) daemon must be running on the machine for which statistics are being reported. The maximum scale value for the strip chart will automatically dou- ble or halve to accommodate increasing or decreasing values. The scale limits can be set with a command line option. OPTIONS -s sampletime Sets the sample time to sampletime seconds. -h hourhandintv Sets the hour hand interval to hourhandintv seconds. — m minutehandintv Sets the minute hand interval to minutehandintv seconds. -M value minmax maxmax — v value Sets the performance value to be monitored to one of: cpu percent of cpu being utilized pkts ethemet packets per second page paging activity in pages per second swap jobs swapped per second intr number of device interrupts per second disk disk traffic in transfers per second cntxt number of context switches per second load average number of jobs running on the server over the last minute colls collisions per second detected on the ethemet errs errors per second on receiving packets COMMANDS The value being displayed can be changed by clicking the tool with the rightmost mouse button, and then selecting the appropriate menu item. The other meter parameters can be modified by moving the mouse cursor into the tool (either open or closed), and typing: m decreases minutehandintv by one M increases minutehandintv by one h decreases hourhandintv by one H increases hourhandintv by one Sun Release 3.0 Last change: 23 September 1985 231 PERFMETER ( 1 ) USER COMMANDS PERFMETER ( 1 ) 1-9 Sets sampletime to a range from 1 to 9 seconds. FILES /etc/servers starts statistics server SEE ALSO perfmon(l), netstat(8), vmstat(8), suntools(l), rstatd(8) 232 Last change: 23 September 1985 Sun Release 3.0 PERFMON ( 1 ) USER COMMANDS PERFMON ( 1 ) NAME perfmon - graphical display of general system statistics SYNOPSIS perfmon [ statistic . . . ] DESCRIPTION Perfmon provides a graphical display of the system-wide performance statistics and updates them approxi- mately once a second. It should be executed from a graphics tool inside the SunWindows system. The time interval between updates can be adjusted by typing one of the following characters while the mouse is in the graphics subwindow: s increases the interval by 0.05 seconds (small s means get slower by a little). S increases the interval by one second (capital S means get Slower by a lot), f decreases the interval by 0.05 seconds (small/ means get /aster by a little). F decreases the interval by one second (capital F means get Faster by a lot). R resets the interval to the standard 1.05 seconds. In addition, typing: H, h or ? lists the characters that perfmon is listening for. Q or q causes perfmon to cease executing. If no statistic argument is given, perfmon displays all statistics. A tick is placed on the lines separating the graphs once every fifteen seconds (due to scheduling vagaries, these ticks may not be evenly spaced). Statistics user is the percentage of total CPU time spent in normal and low priority user processes. system is the percentage of total CPU time attributed to system calls and overhead. idle is the percentage of total CPU time spent idle. free is the amount of available real memory (in Kbytes). disk is the total number of disk transfers performed. interrupts is the total number of interrupts serviced, input is the total number of input packets received, output is the total number of output packets transmitted, collision is the total number of collisions between packets observed on the network. SEE ALSO netstat(8), perfmeter(l), suntools(l), vmstat(8) BUGS Perfmon should use rstatd. Sun Release 3.0 Last change: 1 February 1985 233 PI(1) USER COMMANDS PI(1) NAME pi - Pascal interpreter code translator SYNOPSIS pS [ —to ] [ — 1 ] [ — L ] [ — n ] [ — o name ] [ — p ] [ — s ] [ — t ] [ — u ] [ — w ] [ — z ] [ -i name . . . ] name.p DESCRIPTION Pi translates the program in the file name.p leaving interpreter code in the file obj in the current directory. The interpreter code can be executed using px. Pix performs the functions of pi and px for Toad and go’ Pascal. Both pi and pc( 1) support ISO Level 1 Standard Pascal, including conformant array parameters. Deviations from the ISO Standard are noted under BUGS below. OPTIONS The following flags are interpreted by pi; the associated options can also be controlled in comments within the program; see the Pascal User’s Manual in the Sun Fortran and Pascal Manual for details. -b Buffer the file output in units of disk blocks, rather than lines. — i name Enable the listing for any specified procedures, functions, and include files. -1 Make a program listing during translation. -L Map all identifiers and keywords to lower case. -n Begin each listed include file on a new page with a banner line. — o name Name the final output file name instead of a.out. -p Suppress the post-mortem control flow backtrace if an error occurs; suppress statement limit count- ing. -s Accept standard Pascal only; non-standard constructs cause warning diagnostics. -t Suppress runtime tests of subrange variables and treat assert statements as comments. -u Card image mode; only the first 72 characters of input lines are used. -w Suppress warning diagnostics. -z Allow execution profiling with pxp by generating statement counters, and arranging for the creation of the profile data file pmon.out when the resulting object is executed. FILES file.p input file file.i include file(s) /usr/lib/pi3.*strings text of the error messages /usr/lib/how_pi* basic usage explanation obj interpreter code output SEE ALSO Sun Fortran and Pascal Manual pix(l), px(l), pxp(l), pxref(l) DIAGNOSTICS For a basic explanation do tutorials pi In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be able to continue parsing. Some diagnostics indicate only that the input is ‘malformed.’ This occurs if the 234 Last change: 7 November 1984 Sun Release 3.0 PI(1) USER COMMANDS PI(1) recovery can find no simple correction to make the input syntactically valid. Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis The first character of each error message indicates its class: E Fatal error; no code will be generated, e Non-fatal error, w Warning - a potential problem, s Non-standard Pascal construct warning. If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then ‘QUIT’. BUGS The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked structures to be distinguished for portability reasons. Binary set operators are required to have operands with identical types; the ISO standard allows different types, as long as the underlying base types are compatible. For clarity, semantic errors should be flagged at an appropriate place in the source text, and multiple instances of the ‘same’ semantic error should be summarized at the end of a procedure or function rather than evoking many diagnostics. When include files are present, diagnostics relating to the last procedure in one file may appear after the beginning of the listing of the next. Sun Release 3.0 Last change: 7 November 1984 235 PIX(l) USER COMMANDS PK(1) NAME pix - Pascal translator and interpreter SYNOPSIS pix [ options ] [ -i name ... ] name.p [ argument ... ] DESCRIPTION Pix is a ‘load and go’ version of Pascal which combines the functions of the translator pi and the interpreter px. Pix uses pi to translate the program in the file name.p and, if there were no fatal errors during transla- tion, calls px to execute the resulting interpretive code with the specified arguments. A temporary file is used for the object code; the file obj is neither created nor destroyed. Options are as described under pi(l). FILES /usr/ucb/pi Pascal translator /usr/ucb/px Pascal interpreter /tmp/pix* temporary /usr/lib/how_pix basic explanation SEE ALSO The Pascal User's Manual in the Pascal for the Sun Workstation Manual. pi(l)> px(l) DIAGNOSTICS For a basic explanation do tutorial% pix 236 Last change: 7 November 1984 Sun Release 3.0 PLOT ( 1G) USER COMMANDS PLOT(IG) NAME plot - graphics filters SYNOPSIS plot [ -T terminal ] DESCRIPTION These commands read plotting instructions (see plot (5)) from the standard input, and in general produce plotting instructions suitable for a particular terminal on the standard output If no terminal type is specified, the environment parameter TERM (see environ (5)) is used. Known termi- nals are: 4014 Tektronix 4014 storage scope. 450 DASI Hyterm 450 terminal (Diablo mechanism). 300 DASI 300 or GSI terminal (Diablo mechanism). 300S DASI 300s terminal (Diablo mechanism), sun or ver Versatec D1200A printer-plotter. The output is scan-converted and suitable input to Ipr -v. FILES /usr/bin/tek /usr/bin/t450 /usr/bin/t300 /usr/bin/t300s /usr/bin/vplot /usr/tmp/vplot nnnnnn SEE ALSO plot(3X), plot(5), graph(lg), lpr(l), rasterfile(5). Sun Release 3.0 Last change: 23 September 1985 237 PMERGE(l) USER COMMANDS PMERGE ( 1 ) NAME pmerge - pascal file merger SYNOPSIS pmerge name.p . . . DESCRIPTION Pmerge assembles the named Pascal files into a single standard Pascal program. The resulting program is listed on the standard output. It is intended to be used to merge a collection of separately compiled modules so that they can be run through pi, or exported to other sites. FILES /usr/tmp/MG* default temporary files SEE ALSO pc(l), pi(l), Auxiliary documentation Pascal User’ s Manual in the Sun Fortran and Pascal Manual. BUGS Very minimal error checking is done, so incorrect programs will produce unpredictable results. Block comments should be placed after the keyword to which they refer or they are likely to end up in bizarre places. 238 Last change: 1 1 November 1983 Sun Release 3.0 PR ( i ) USER COMMANDS PRO) NAME pr — prepare file(s) for printing, possibly in multiple columns SYNOPSIS Pr [“«][+«][ -h string ] [ -wn ] [ -f ] [ -In ] [ -t ] [ -s/t ] [ -m ] [filename ] . . . DESCRIPTION pr prepares one or more files ’s for printing. The output is separated into pages headed by a date, the name of the file or a specified header, and the page number, pr prints its standard input if there are no file argu- ments. Formfeed characters in the input files cause page breaks in the output, as expected. Inter-terminal messages via write are forbidden during a pr. OPTIONS Options apply to all following file’s but may be reset be tween /i/c’s: — n Produce n -column output. For example: Print of in the one three lines file columns. This option overrides the -t option (see below). +n Begin printing with page n . — h string Use string as a header for the page instead of the default header. -w« For purposes of multi-column output, take the width of the page to be n characters instead of the default 72. -f Use formfeeds instead of newlines to separate pages. A formfeed is assumed to use up two blank lines at the top of a page. Thus this option does not affect the effective page length. -In Take the length of the page to be n lines instead of the default 66. -t Do not print the 5-line header or the 5-line trailer normally supplied for each page. Formfeed characters are not generated when this option is used, even if the -f option .,as used. The -t option is intended for applications where the results should be directed to a file for further process- ing. -sc Separate columns by the single character c instead of by the appropriate amount of white space. A missing c is taken to be a tab. -m Print all file’s simultaneously, each in one column, for example: Print Print Print the the third lines lines file's of of lines file file go one. two. here. EXAMPLES Print a file called dreadnought on the printer — this is the simplest use of pr: tutorial% pr dreadnought | lpr tutorial% Produce three laminations of a file called ridings side by side in the output, with no headers or trailers, the results to appear in the file called Yorkshire : tutorial% pr -m -t ridings ridings ridings > Yorkshire tutorial% Sun Release 3.0 Last change: 23 September 1985 239 PR( i ) USER COMMANDS PR(1) FILES /dev/tty? to suspend messages. SEE ALSO cat(l), lpr(l) DIAGNOSTICS There are no diagnostics when pr is printing on a terminal. BUGS The options described above interact with each other in strange and as yet to be defined ways. 240 Last change: 23 September 1985 Sun Release 3.0 PRINTENV ( 1 ) USER COMMANDS PRINTENV ( 1 ) NAME printenv - print out the environment SYNOPSIS printenv [ name ] DESCRIPTION Printenv prints out the values of the variables in the environment. If a name is specified, only its value is printed. If a name is specified and it is not defined in the environment, printenv returns exit status 1, else it returns status 0. SEE ALSO sh(l), environ(5), csh(l) Sun Release 3.0 Last change: 24 February 1979 241 PRMAIL(l) USER COMMANDS PRMAIL ( 1 ) NAME prmail - display waiting mail SYNOPSIS prmail [ user ... ] DESCRIPTION Prmail displays waiting mail for you, or the specified user s. The mail is not disturbed. FILES /usr/spool/mail/* waiting mail files SEE ALSO biff(l), mail(l), from(l), binmail(l) 242 Last change: 7 March 1984 Sun Release 3.0 PROF ( 1 ) USER COMMANDS PROF ( 1 ) NAME prof - display profile data SYNOPSIS prof [ — a ] [ — 1 ] [ — n ] [ — s ] [ — v [ -low [ —high ] ] ] [ — z ] [ object-file [ profile-file . . . ] ] DESCRIPTION Prof interprets the file produced by the monitor (3) subroutine. In the default case, the symbol table in the named object file ( object-file by default) is read and correlated with the profile file (profile-file by default). For each external symbol, the percentage of time spent executing between that symbol and the next is printed (in decreasing order), together with the number of times that routine was called and the number of milliseconds per call. If more than one profile file is specified, the output represents the sum of the profiles. To tally the number of calls to a routine, the program must be compiled with the -p option of cc,f77 or pc. This option also means that the profile file is produced automatically. Beware of quantization errors. OPTIONS -a Report all symbols rather than just external symbols. -1 Sort the output by symbol value. -n sort the output by number of calls. -s Produce a summary profile file in mon .sum. This is really only useful when more than one profile file is specified. -v [ -low [ -high ]] Suppress all printing and produce a graphic version of the profile on the standard output for display by the plot (IG) filters. When plotting, the numbers low and high, (by default 0 and 100), select a percentage of the profile to be plotted, with accordingly higher resolution. — z Print routines which have zero usage (as indicated by call counts and accumulated time). FILES mon.out for profile a.out for namelist mon.sum for summary profile SEE ALSO monitor(3), cc(l), plot(lG), gprof(l) BUGS Prof is confused by/77 which puts the entry points at the bottom of subroutines and functions. Sun Release 3.0 Last change: 8 October 1984 243 PRS(l) USER COMMANDS PRS(l) NAME prs - print an SCCS file SYNOPSIS /usr/sccs/prs [ -d [ dataspec ] ] [ -r [ SID ] ] [ -e ] [ -I ] [ -a ] filename . . . DESCRIPTION prs prints, on the standard output, parts or all of an SCCS file (see sccsfile (5)) in a user supplied format If a directory is named, prs behaves as though each file in the directory were specified as a named file, except that non-sccs files (last component of the path name does not begin with s.), and unreadable files are silently ignored. If a name of - is given, the standard input is read, in which case each line is taken to be the name of an SCCS file or directory to be processed; non-sccs files and unreadable files are silently ignored. OPTIONS Options apply independently to each named file. -d [ dataspec ] Specifies the output data specification. The dataspec is a string consisting of SCCS file data key- words (see DATA KEYWORDS) interspersed with optional user supplied text. -r[SID] Specifies the SCCS /Dentification (SID) string of a delta for which information is desired. If no SID is specified, the SID of the most recently created delta is assumed. -e Requests information for all deltas created earlier than and including the delta designated via the -r option. -I Requests information for all deltas created later than and including the delta designated via the -r option. -a Requests printing of information for both removed, that is, delta type = R, (see rmdel{ 1)) and existing, that is, delta type = D, deltas. If the -a option is not specified, information for existing deltas only is provided. In the absence of the -d options, prs displays a default set of information consisting of: delta-type, release number and level number, date and time last changed, user-name of the person who changed the file, lines inserted, changed, and unchanged, the MR numbers, and the comments. DATA KEYWORDS Data keywords specify which parts of an SCCS file are to be retrieved and output. All parts of an SCCS file (see sccsfile ( 5)) have an associated data keyword. There is no limit on the number of times a data keyword may appear in a dataspec . The information printed by prs consists of: 1) the user supplied text; and 2) appropriate values (extracted from the SCCS file) substituted for the recognized data keywords in the order of appearance in the dataspec. The format of a data keyword value is either Simple (S), in which keyword substitution is direct, or Multi-line (M), in which keyword substitution is followed by a carriage return. User supplied text is any text other than recognized data keywords. A tab is specified by \t and carriage retum/new-line is specified by \n. 244 Last change: 23 September 1985 Sun Release 3.0 PRS(l) USER COMMANDS PRS(l) Sun Release 3.0 TABLE 1. SCCS Files Data Keywords Keyword Data Item File Section Value Format :Dt: Delta information Delta Table See below* S :DL: Delta line statistics tt :Li:/:Ixl:/:Lu: S :Li: Lines inserted by Delta n nnnnn s :Ld: Lines deleted by Delta it nnnnn s :Lu: Lines unchanged by Delta ii nnnnn s :DT: Delta type 11 D or R s :I: SCCS ED string (SID) it :R:.:L:.:B:.:S: s :R: Release number ii nnnn s :L: Level number it nnnn s :B: Branch number it nnnn s :S: Sequence number ii nnnn s :D: Date Delta created ii :Dy:/:Dm:/:Dd: s :Dy: Year Delta created tt nn s :Dm: Month Delta created it nn s :Dd: Day Delta created it nn s :T: Time Delta created it :Th:::Tm:::Ts: s :Th: Hour Delta created it nn s :Tm: Minutes Delta created it nn s :Ts: Seconds Delta created " nn s :P: Programmer who created Delta it lognameS :DS: Delta sequence number •i nnnn S :DP: Predecessor Delta seq-no. it nnnn S :DI: Seq-no. of deltas incl., excl., ignored it :Dn:/:Dx:/:Dg: S :Dn: Deltas included (seq #) it :DS: :DS: ... S :Dx: Deltas excluded (seq #) it :DS: :DS:... S :Dg: Deltas ignored (seq #) it :DS: :DS: ... s :MR: MR numbers for delta ii text M :C: Comments for delta it text M :UN: User names User Names text M :FL: Flag list Flags text M :Y: Module type flag tt text S :MF: MR validation flag n yes or no S :MP: MR validation pgm name ti text S :KF: Keyword error/waming flag it yes or no S :BF: Branch flag n yes or no S :J: Joint edit flag ti yes or no S :LK: Locked releases it :R:... S :Q: User defined keyword n text s :M: Module name ii text s :FB: Floor boundary it :R: s :CB: Ceiling boundary ti :R: s :Ds: Default SID ii • X* s :ND: Null delta flag it yes or no s :FD: File descriptive text Comments text M :BD: Body Body text M :GB: Gotten body ii text M :W: A form of what string N/A :Z::M:\t:I: s :A: A form of what string N/A :Z::Y: :M: :I::Z: s :Z: what string delimiter N/A @(#) s :F: SCCS file name N/A text s :PN: SCCS file path name N/A * :Dt: = :DT: :I: :D: :T: :P: :DS: :DP: text s Last change: 23 September 1985 245 PRS(l) USER COMMANDS PRS(l) EXAMPLES /usr/sccs/prs -d"Users and/or user IDs for :F: are:\n:UN:" s.file may produce on the standard output: Users and/or user IDs for s.file are: xyz 131 abc /usr/sccs/prs -d"Newest delta for pgm :M:: :I: Created :D: By :P:" -r s.file may produce on the standard output: Newest delta for pgm main.c: 3.7 Created 77/12/1 By cas As a special case: /usr/sccs/prs s.file may produce on the standard output: D 1.1 77/12/1 00:00:00 cas 1 000000/00000/00000 MRs: bl78-12345 W79-54321 COMMENTS: this is the comment line for s.file initial delta for each delta table entry of the “D” type. The only option argument allowed to be used with the special case is the -a option. FILES /tmp/pr????? SEE ALSO sccs(l), admin(l), delta(l), get(l), help(l), sccsfile(5) Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help for explanations. 246 Last change: 23 September 1985 Sun Release 3.0 PS(1) USER COMMANDS PS(1) NAME ps - process status SYNOPSIS ps [ acCegklsStuvwx ] [ num] [ kernel _name ] [ c_dump_file ] [ swapjle ] DESCRIPTION ps displays information about processes. Normally, only processes that you (your user-id) have started are candidates to be displayed by ps, but see the OPTIONS section below for how to get more information. Specifying a makes other users’ processes candidates to be displayed; specifying x includes processes without control terminals in the candidate pool. All output formats include, for each process, the process id — PID, control terminal of the process — TT, cpu time used by the process — TIME (this includes both user and system time), the state — STAT — of the process, and an indication of the COMMAND which is running. The state is given by a sequence of four letters, for example, ‘RWNA’. First letter indicates the runnability of the process: R Runnable processes, T Stopped processes, P Processes in page wait, D Processes in disk (or other short term) waits, S Processes sleeping for less than about 20 seconds, I Processes which are idle (sleeping longer than about 20 seconds). Z A child processes that has terminated and is waiting for its parent process to do a wait. Second letter indicates whether a process is swapped out; blank (that is, a space) in this position indicates that the process is loaded (in memory). W Process is swapped out > Process has specified a soft limit on memory requirements and has exceeded that limit; such a process is (necessarily) not swapped. Third letter indicates whether a process is running with altered CPU scheduling priority (nice): blank (that is, a space) in this position indicates that the process is running without special treatment. N The process priority is reduced, < The process priority has been raised artificially. F ourth letter indicates any special treatment of the process for virtual memory replacement. The letters correspond to options to the vadvise (2) system call. Currently the possibilities are: blank (that is, a space) in this position stands for VA_NORM. A Stands for VA_ANOM. An A typically represents a program which is doing gar- bage collection. S Stands for VA_SEQL. An S is typical of large image processing programs which are using virtual memory to sequentially address voluminous data. Kerneljiame specifies the location of the system namelist. If the k option is given, c_dump Jile tells ps where to look for core. Otherwise, the core dump is located in the file Ivmcore and this argument is ignored. Swap Jile gives the location of a swap file other than the default, Idevldrum . OPTIONS a Display information about all processes with terminals (ordinarily only one’s own processes are displayed). Sun Release 3.0 Last change: 3 December 1985 247 PS(1) USER COMMANDS PS(1) c Display the command name, as stored internally in the system for purposes of accounting, rather than the command arguments, which are kept in the process’ address space. This is more reliable, if less informative, since the process is free to destroy the latter information. C Display raw CPU time in the %CPU field instead of the decaying average. e Display the environment as well as the arguments to the command. g Display all processes. Without this option, ps only prints ‘interesting’ processes. Processes are deemed to be uninteresting if they are process group leaders. This normally eliminates top-level command interpreters and processes waiting for users to login on free terminals. k Normally, kernel name, defaults to /vmunix, c_dump Jile is ignored, and swap Jle defaults to Idevldrum. With the k option in effect, these arguments default to Ivmunix, Ivmcore, and I dev/ drum, respectively. 1 Display a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as described below. s Adds the size SSIZ of the kernel stack of each process (for use by system maintained) to the basic output format. S Display accumulated CPU time used by this process and all of its reaped children. tx Restrict output to processes whose controlling tty is x (which should be specified as printed by ps, for example, t3 for tty3, tco for console, tdO for ttydO, t? for processes with no tty, etc). This option must be the last one given. u Display user-oriented output. This includes fields USER, %CPU, NICE, SIZE, and RSS as described below. v Display a version of the output containing virtual memory. This includes fields RE, SL, PAGEIN, SIZE, RSS, LIM, TSIZ, TRS, %CPU and %MEM, described below. w Use a wide output format (132 columns rather than 80); if repeated, that is, ww, use arbitrarily wide output. This information is used to decide how much of long commands to print. x Display even those processes with no terminal. num A process number may be given, in which case the output is restricted to that process. This option must also be last. DISPLAY FORMATS Fields which are not common to all output formats: USER name of the owner of the process %CPU cpu utilization of the process; this is a decaying average over up to a minute of previous (real) time. Since the time base over which this is computed varies (since processes may be very young) it is possible for the sum of all %CPU fields to exceed 100%. NICE (or NI) process scheduling increment (see setpriority{ 2) and nice{ 3C). SIZE virtual size of the process (in kilobyte units) RSS real memory (resident set) size of the process (in kilobyte units) LIM soft limit on memory used, specified via a call to getrlimit{ 2); if no limit has been specified then shown as xx TSIZ size of text (shared program) image TRS size of resident (real memory) set of text %MEM percentage of real memory used by this process. RE residency time of the process (seconds in core) SL sleep time of the process (seconds blocked) PAGEIN number of disk i/o’s resulting from references by the process to pages not loaded in core. UID numerical user-id of process owner PPID numerical id of parent of process CP short-term cpu utilization factor (used in scheduling) 248 Last change: 3 December 1985 Sun Release 3.0 PS(1) USER COMMANDS PS(1) PRI process priority (non-positive when in non-interruptible wait) ADDR page fram number or swap area position WCHAN event on which process is waiting (an address in the system), with the initial part of the address trimmed off, for example, 80004000 prints as 4000. F flags associated with process as in : SLOAD 0000001 in core SSYS 0000002 swapper or pager process SLOCK 0000004 process being swapped out SSWAP 0000008 save area flag STRC 0000010 process is being traced SWTED 0000020 another tracing flag SULOCK 0000040 user settable lock in core SPAGE 0000080 process in page wait state SKEEP 0000100 another flag to prevent swap out SOMASK 0000200 restore old mask after taking signal SWEXIT 0000400 working on exiting SPHYSIO 0000800 doing physical i/o (bio.c) SVFORK 0001000 process resulted from vfork() SVFDONE 0002000 another vfork flag SNOVM 0004000 no vm, parent in a vfork() SPAGI 0008000 init data space on demand, from inode SSEQL 0010000 user warned of sequential vm behavior SUANOM 0020000 user warned of anomalous vm behavior STIMO 0040000 timing out during sleep SOUSIG 0100000 using old signal mechanism SOWEUPC 0200000 owe process an addupc() call at next ast SSEL 0400000 selecting; wakeup/waiting danger SLOGIN 0800000 a login process (legit child of init) SPTECHG 1000000 pte’s for process have changed A process that has exited and has a parent, but has not yet been waited for by the parent is marked ; a process which is blocked trying to exit is marked ; ps makes an educated guess as to the file name and arguments given when the process was created by examining memory or the swap area. The method is inherently somewhat unreliable and in any event a process is entitled to destroy this infor- mation, so the names cannot be counted on too much. FILES /vmunix system namelist /dev/kmem kernel memory /dev/drum swap device /vmcore core file /dev searched to find swap device and tty names SEE ALSO kill(l), w(l) BUGS Things can change while ps is running; the picture it gives is only a close approximation to reality. Sun Release 3.0 Last change: 3 December 1985 249 PTI(l) USER COMMANDS PTI(l) NAME pti - phototypesetter interpreter SYNOPSIS pti [file ... ] DESCRIPTION Pti shows the commands in a stream from the standard output of troff{\) using trojfs -t option, interpret- ing them as they would act on the typesetter. Horizontal motions shows as counts in internal units and are marked with *<’ and V indicating left and right motion. Vertical space is called leading and is also indi- cated. The output is really cryptic unless you are an experienced C/A/T hardware person. It is better to use troff -a. SEE ALSO troff(l) 250 Last change: 21 August 1985 Sun Release 3.0 PTX(l) USER COMMANDS PTX(l) NAME ptx - permuted index SYNOPSIS ptx [-f] [ — t ] [-w/z] [-gn] [ -o only ] [ -i ignore ] [-b break] [-r ] [ input [ output ] ] DESCRIPTION Pbc generates a permuted index of the contents of file input onto file output (defaults are standard input and output). Ptx has three phases: the first does the permutation, generating one line for each keyword in an input line. The keyword is rotated to the front. The permuted file is then sorted. Finally, the sorted lines are rotated so the keyword comes at the middle of the page. Ptx produces output in the form: .xx "tail" "before keyword" "keyword and after" "head" where .xx may be an nr off (\) or troff{\) macro for user-defined formatting. The before keyword and key- word and after fields incorporate as much of the line as will fit around the keyword when it is printed at the middle of the page. Tail and head, at least one of which is an empty string "", are wrapped-around pieces small enough to fit in the unused space at the opposite end of the line. When original text must be dis- carded, 7’ marks the spot. OPTIONS -f Fold upper and lower case letters for sorting. -t Prepare the output for the phototypesetter; the default line length is 100 characters. — w« Use the next argument, n, as the width of the output line. The default line length is 72 characters. —gn Use the next argument, n, as the number of characters to allow for each gap among the four parts of the line as finally printed. The default gap is 3 characters. _ o only Use as keywords only the words given in the only file. -i ignore Do not use as keywords any words given in the ignore file. If the -i and -o options are missing, use lusr/lib/eign as the ignore file. -b break Use the characters in the break file to separate words. In any case, tab, newline, and space charac- ters are always used as break characters. — r Take any leading nonblank characters of each input line to be a reference identifier (as to a page or chapter) separate from the text of the line. Attach that identifier as a 5th field on each output line. FILES /bin/sort /usr/lib/eign BUGS Line length counts do not account for overstriking or proportional spacing. Sun Release 3.0 Last change: 1 November 1983 251 PWD(l) USER COMMANDS PWD(l) NAME pwd - print working directory name SYNOPSIS pwd DESCRIPTION Pwd prints the pathname of the working (current) directory. If you are using csA(l), you can use the dirs builtin command to do the same job more quickly; BUT dirs can give a different answer in the rare case that the current directory or a containing directory was moved after the shell descended into it. This is because pwd searches back up the directory tree to report the true pathname, whereas dirs remembers the pathname from the last cd command. The example below illus- trates the differences. % cd /usr/wendy/january/reports % pwd /usr/wendy/j anuary/reports % dirs '/january/reports % mv Tjanuary '/february % pwd /usr/wendy/february/reports % dirs '/january/reports % Pwd and dirs also give different answers when you change directory through a symbolic link. For exam- ple: % cd /usr/wendy/january/reports % pwd /usr/wendy/j anuary/reports % dirs "/january/reports % Is -1 /usr/wendy/january lrwxrwxrwx 1 wendy 17 Jan 30 1983 /usr/wendy/january ->/usr/wendy/1984/jan/ % cd /usr/wendy/january % pwd /usr/wendy/1984/jan % dirs /usr/wendy/j anuary They may also report different pathnames if you have changed directories through a symbolic link. SEE ALSO cd(l), csh(l) 252 Last change: 1 February 1985 Sun Release 3.0 PX(1) USER COMMANDS PX(1) NAME px - Pascal interpreter SYNOPSIS px [ obj [ argument ... ] ] description FILES Px interprets the abstract machine code generated by pi. The first argument is the file to be interpreted and defaults to oby remaining arguments are available to the Pascal program using the built-ins argv and argc Px is also invoked by pix when running Toad and go’. 6 If the program terminates abnormally an error message and a control flow backtrace are printed. The number of statements executed and total execution time are printed after normal termination. The p option °f P 1 su PP r esses all of this except the message indicating the cause of abnormal termination. obj default object file pmon.out profile data file SEE ALSO The P ascal User's Manual in the Sun Pascal Manual. pi(l)> pix(l) DIAGNOSTICS Most run-time error messages are self-explanatory. Some of the more unusual ones are: Reference to an inactive file A file other than input or output was used before a call to reset or rewrite. Statement count limit exceeded The limit of 500,000 executed statements (which prevents excessive looping or recursion) has been exceeded. Bad data found on integer read Bad data found on real read Usually, non-numeric input was found for a number. For reals, Pascal requires digits before and after the decimal point so that numbers like ‘.1’ or ‘21.’ evoke the second diagnostic, panic: Some message Indicates a internal inconsistency detected in px probably due to a Pascal system bug. BUGS Post-mortem traceback is not limited; infinite recursion leads to almost infinite traceback. Sun Release 3.0 Last change: 1 November 1984 253 PXP(l) USER COMMANDS PXP(l) NAME pxp - Pascal execution profiler SYNOPSIS pxp [ -acdefjLnstuw_ ] [ -23456789 ] [ -z [ name ... ] ] name.p DESCRIPTION Pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To produce an exe- cution profile all that is necessary is to translate the program specifying the z option to pc, pi, or pix, exe- cute the program, and then type the command tutorial% pxp -z name.p Pxp generates a reformatted listing if none of the c, t, or z options are specified; thus tutorial% pxp old.p > new.p places a pretty-printed version of the program in old.p in the file new.p. OPTIONS The use of the following options of pxp is discussed in the Pascal User’s Manual in the Sun Pascal Manual. -a Print the bodies of all procedures and functions in the profile; even those which were never executed, -c Extract profile data from the file core . -d Include declaration parts in a profile. -e Eliminate include directives when reformatting a file; the include is replaced by the reformatted con- tents of the specified file. -f Fully parenthesize expressions. -j Left justify all procedures and functions. -L Map all identifiers and keywords to lower case. — n Eject a new page as each file is included; in profiles, print a blank line at the top of the page. -s Strip comments from the input text. -t Print a table summarizing procedure and function call counts. -u Card image mode; only the first 72 characters of input lines are used. -w Suppress warning diagnostics. — z Generate an execution profile. If no name s are given the profile is of the entire program. If a list of names is given, then only the specified procedures or functions and the contents of the specified include files will appear in the profile. Underline keywords. — d Use d spaces (where d is a digit, 2 < d < 9) as the basic indenting unit. The default is 4. FILES name.p input file name.i include file(s) name.h include file(s) pmon.out profile data core profile data source for -c option /usr/lib/how_pxp information on basic usage 254 Last change: 7 November 1984 Sun Release 3.0 PXP(l) USER COMMANDS PXP(l) SEE ALSO The Pascal User’s Manual in the Sun Pascal Manual. pc(l), pi(l), px(l) DIAGNOSTICS For a basic explanation do tutorial% pxp Error diagnostics include No profile data in file’ with the c option if the z option was not enabled to pi; ‘Not a Pascal system core file’ if the core is not from a px execution; ‘Program and count data do not correspond’ if the program was changed after compilation, before profiling; or if the wrong program is specified. BUGS Does not place multiple statements per line. Procedures and functions as parameters are printed without nested parameter lists, as in the obsolete Jensen and Wirth syntax. Sun Release 3.0 Last change: 7 November 1984 255 PXREF(l) USER COMMANDS PXREF(l) NAME pxref- Pascal cross-reference program SYNOPSIS pxref [ - ] name DESCRIPTION Pxref makes a line numbered listing and a cross-reference of identifier usage for the program in name. The optional ’ argument suppresses the listing. The keywords goto and label are treated as identifiers for the purpose of the cross-reference. Include directives are not processed, but cause the placement of an entry indexed by ‘#include’ in the cross-reference. SEE ALSO The Pascal User’s Manual in the Sun Fortran and Pascal Manual. BUGS Identifiers are trimmed to 10 characters. 256 Last change: 1 1 November 1983 Sun Release 3.0 QUOTA ( 1 ) USER COMMANDS QUOTA ( 1 ) NAME quota - display disk usage and limits SYNOPSIS quota [ -v ] [ user ] DESCRIPTION Quota displays users disk usage and limits. Only the super-user may use the optional user argument to view the limits of users other than himself. Quota without any flags prints only warnings about mounted file systems where usage is over quota. If a -v flag is supplied, quota will display user’s quotas on all mounted file systems where quotas exist. FILES quotas quota file at the file system root SEE ALSO quotactl(2), quotaon(8), edquota(8), rquotad(8c) Sun Release 3.0 Last change: 15 April 1985 257 RANLIB ( 1 ) USER COMMANDS RANLIB ( 1 ) NAME ranlib - convert archives to random libraries SYNOPSIS ranlib archive . . . DESCRIPTION Ranlib converts each archive argument to a form which the linker W( 1) can load more rapidly. Ranlib does this by adding a table of contents called .SYMDEF to the beginning of the archive. Ranlib uses ar{\) to reconstruct the archive, so that sufficient temporary file space must be available in the file system which contains the current directory. SEE ALSO ld(l), ar(l), lorder(l) BUGS Because generation of a library by or and randomization of the library by ranlib are separate processes, phase errors are possible. The linker warns when the modification date of a library is more recent than the creation date of its dictionary; but this means that you get the warning even if you only copy the library. 258 Last change: 8 February 1983 Sun Release 3.0 RASTPS ( 1 ) USER COMMANDS RASTPS ( 1 ) NAME rastps — convert screen (raster file) image to PostScript SYNOPSIS rastps [ -atf ] [ -htf ] [-p] [-rtf] [-s] [-Wtf ] [-xtf] [ -yN] filename ... DESCRIPTION rastps converts screen images and rasterfiles to PostScript form. The image can then be printed a PostScript printer such as the Sun LaserWriter. A sample use might be % rastps -w3 my_raster | Ipr where my_raster is a raster file (that could have been produced by screendump{ 1)). A common use is % screendump | rastps | Ipr to produce an image the Workstation screen image on a LaserWriter. It takes about 4 minutes to print a non-rotated screendump. If rotation is requested, the time needed increases to about 30 minutes. OPTIONS -aN Adjusts the image to a printer with resolution of N dots per inch. When N is omitted, the resolution is set to 300. -hN Set height of the printed image in inches. -p Portrait mode. —rtf Rotate the figure by tf. -s Select standard pixels. Normally produces (square) rasterfile pixels. -wtf Set width of the printed image in inches. -xtf Specify in inches the location of the lower left-hand comer of the image on the page. -y tf Specify in inches the location of the upper right-hand comer of the image. Sun Release 3.0 Last change: 26 December 1985 259 R ASTREPL ( 1 ) USER COMMANDS R ASTREPL ( 1 ) NAME rastrepl - magnify a raster image by 2 times SYNOPSIS rastrepl [ input-file [ output-file ]] DESCRIPTION Rastrepl reads input-file (or the standard input if input-file is not specified) which should be in rasterfile for- mat (see /usr/include/rasterfile.h), replicates each pixel in both the x and y directions, and writes the result- ing rasterfile to output-file (or the standard output if output-file is not specified). EXAMPLES tutorial^, screendump | rastrepl | lpr -Pversatec -v sends a rasterfile containing the current frame buffer to the Versatec plotter, doubling the size of the image so that it fills a single page. SEE ALSO screendump(l), screenload(l), lpr(l) 260 Last change: 5 November 1984 Sun Release 3.0 RATFOR ( 1 ) USER COMMANDS RATFOR ( 1 ) NAME ratfor - rational FORTRAN dialect SYNOPSIS ratfor [ -6 c ] [ -C ] [ -h ] [ filename . . . ] DESCRIPTION ratfor converts the rational FORTRAN dialect into ordinary FORTRAN 77. It provides control flow con- structs essentially identical to those in C. See the fortran 77 Programmer' s Guide for a description of the Ratfor language. OPTIONS —6c Use the character c as the continuation character in column 6 when translating to FORTRAN. The default is to use the & character as a continuation character. -C Pass Ratfor comments through to the translated code. h Translate Ratfor string constants to Hollerith constants of the form nnnh string. Otherwise just pass the strings through to the translated code. SEE ALSO f77(l) Ratfor in the FORTRAN 77 Programmer’ s Guide Sun Release 3.0 Last change: 21 December 1983 261 RCP(IC) USER COMMANDS RCP(IC) NAME rep - remote file copy SYNOPSIS rep filel file2 rep [ -r ] file ... directory DESCRIPTION rep copies files between machines. Each file or directory argument is either a remote file name of the form “rhost:path”, or a local file name (containing no *:’ characters, or a 7’ before any ‘:’s.) If the -r is specified and any of the source files are directories, rep copies each subtree rooted at that name; in this case the destination must be a directory. If path is not a full path name, it is interpreted relative to your login directory on rhost. A path on a remote host may be quoted (using \, ", or ') so that the metacharacters are interpreted remotely. rep does not prompt for passwords; your current local user name must exist on rhost and allow remote command execution via rs/i(lC). rep handles third party copies, where neither source nor target files are on the current machine. Hostnames may also take the form “rhostmame” to use rname rather than the current user name on the remote host. Please note: rep is meant to copy from one host to another; if by some chance you try to copy a file on top of itself, you will end up with a severely corrupted file (for example, if you executed the following com- mand from host george: ‘george% rep testfile george:/usr/me/testfile’). Remember where you are at all times (putting your hostname in your prompt helps with this)! SEE ALSO ftp(lC), rsh(lC), rlogin(lC) BUGS Doesn’t detect all cases where the target of a copy might be a file in cases where only a directory should be legal. Is confused by any output generated by commands in a .login, .profile, or .eshre file on the remote host. rep doesn’t copy ownership, mode, and timestamps to the new files. rep requires that the source host have permission to execute commands on the remote host when doing third-party copies. If you forget to quote metacharacters intended for the remote host you get an incomprehesible error mes- sage. 262 Last change: 23 September 1985 Sun Release 3.0 REFER ( 1 ) USER COMMANDS REFER ( 1 ) NAME refer - find and insert literature references in documents SYNOPSIS refer [ -ar ] [ -b ] [ -c string ] [ -e ] [ -kx ] [ -1 m,n ] [ -pfile ] [ -n ] [ -s keys ] file . . . DESCRIPTION Refer is a preprocessor for nroff( 1), or trojf(l), that finds and formats references. The input files (standard input by default) are copied to the standard output, except for lines between .[ and .] command lines. Such lines are assumed to contain keywords as for lookbib(l), and are replaced by information from a biblio- graphic data base. The user can avoid the search, override fields from it, or add new fields. The reference data, from whatever source, is assigned to a set of troff strings. Macro packages such as ms(l) print the finished reference text from these strings. A flag is placed in the text at the point of reference. By default, the references are indicated by numbers. When refer is used with eqn{ 1), neqn(Y), or tbl( 1), refer should be used first in the sequence, to minimize the volume of data passed through pipes. OPTIONS -ar Reverse the first r author names (Jones, J. A. instead of J. A. Jones). If r is omitted, all author names are reversed. -b Bare mode — do not put any flags in text (neither numbers or labels). —cstring Capitalize (with Small Caps) the fields whose key-letters are in string. -e Accumulate references instead of leaving the references where encountered, until a sequence of the form: •[ $LIST$ .] is encountered, and then write out all references collected so far. Collapse references to the same source. -kx Instead of numbering references, use labels as specified in a reference data line beginning with the characters %x; By default, x is L. -]m,n Instead of numbering references, use labels from the senior author’s last name and the year of publication. Only the first m letters of the last name and the last n digits of the date are used. If either of m or n is omitted, the entire name or date, respectively, is used. -p Take the next argument as a file of references to be searched. The default file is searched last. -n Do not search the default file. -skeys Sort references by fields whose key-letters are in the keys string, and permute reference numbers in the text accordingly. Using this option implies the -e option. The key-letters in keys may be followed by a number indicating how many such fields are used, with a + sign taken as a very large number. The default is AD, which sorts on the senior author and date. To sort on all authors and then the date, for instance, use the options -sA+T. FILES /usr/dict/papers directory of default publication lists and indexes /usr/lib/refer directory of programs SEE ALSO addbib(l), indxbib(l), lookbib(l), roffbib(l), sortbib(l) Sun Release 3.0 Last change: 29 April 1983 263 REV ( 1 ) USER COMMANDS REV ( 1 ) NAME rev - reverse lines of a file SYNOPSIS rev [ file ] ... DESCRIPTION Rev copies the named files to the standard output, reversing the order of characters in every line. If no file is specified, the standard input is copied. 264 Last change: 16 March 1983 Sun Release 3.0 RLOGIN(IC) USER COMMANDS RLOGIN(IC) NAME rlogin - remote login SYNOPSIS rlogin rhost [ -ec ] [ -1 username ] [ -7 ] [ -8 ] rhost [ -ec ] [ -I username ] [ -7 ] [ -8 ] DESCRIPTION rlogin connects your terminal on the current local host system Ihost to the remote host system rhost. Host names are given in the file /etc/hosts. Each host has one standard name (the first name given in the file), which is unambiguous, and optionally one or more nicknames. The host names for machines to which your machine is networked are also found in the directory /usr/hosts, as symbolic links to rsh. If you put this directory in your search path then the rlogin can be omitted. Additionally, each host has a file letclhosts.equiv which contains a list of rhost ’ s with which it shares account names. When you rlogin on a host specified in your letclhosts.equiv (and if the remote host, in turn, specifies your host in its /etc/ hosts. equiv) you don’t need to give a password. Each user may also have a private equivalence list in a file .rhosts in his login directory. Each line in this file should contain an rhost and a username separated by a space, giving additional cases where logins without passwords are to be permitted. If the originating user and host is not found in these files, the remote machine will prompt for a password. To avoid some security problems, the .rhosts file must be owned by either the remote user or root and may not be a symbolic link. Your remote terminal type is the same as your local terminal type (as given in your environment TERM variable). All echoing takes place at the remote site, so that (except for delays) the rlogin is transparent. Flow control via A S and A Q and flushing of input and output on interrupts are handled properly. ESCAPES Lines that you type which start with the tilde character are ‘escape sequences’ (the escape character can be changed via the -e options): Disconnect from the remote host — this is not the same as a logout, because the local host breaks the connection with no warning to the remote end. "susp Suspend the login session (only if you are using the C-Shell). susp is your ‘suspend’ character — usually A Z — see «y(l). dsusp Suspend the input half of the login, but output will still be seen (only if you are using the C-Shell). dsusp is your ‘deferred suspend’ character — usually A Y — see tty(l). OPTIONS -1 Specifies a different user name ( username , in the synopsis) for the remote login. If you do not use this option, the remote username used is the same as your local username. -e Specifies a different escape character (c , in the synopsis) for the line used to disconnect from the remote host. -8 Pass eight-bit data across the net instead of seven-bit data. SEE ALSO rsh(lC), stty(l) FILES /usr/hosts/* /etc/hosts.equiv "/.rhosts BUGS for rhost version of the command list of rhost s with shared account names private list of rhost s with shared account names Sun Release 3.0 Last change: 23 September 1985 265 RLOGIN(IC) USER COMMANDS RLOGIN(IC) This implementation can only use the TCP network service. More terminal characteristics should be propagated. 266 Last change: 23 September 1985 Sun Release 3.0 RM( 1 ) USER COMMANDS RM(1) NAME rm - remove (unlink) files or directories SYNOPSIS rm ( — f ] [ — r ] [ — i ] [ — ] file . . . DESCRIPTION rm removes (directory entries for) one or more files. If an entry was the last link to the file, the contents of that file are lost. See ln(l) for more information about links. To remove a file, you must have write permission in its directory; but you don’t need read or write permis- sion on the file itself. If you don’t have write permission on the file and the standard input is a terminal, rm displays the file s permissions and waits for you to type in a response. If your response begins with ‘y’ the file is deleted; otherwise the file is left alone. rm -r and rmdir remove entries for directories, rmdir removes the named directory only if it is empty To remove a directory containing files, use rm with the -r option. See rmdir (l) for more information about removing directories. OPTIONS — f Force files to be removed, without displaying permissions, asking questions, or reporting errors. -r Recursively delete the contents of the specified directory (and its subdirectories), and the directory itself. i Ask whether to delete each file, or, under — r, whether to examine each directory. Sometimes called the interactive option. Treat the following arguments as filenames — so that you can specify filenames starting with a minus. WARNING It is forbidden to remove the file *..’ merely to avoid the antisocial consequences of inadvertently doing something like ‘rm — r .*’. SEE ALSO rmdir(l), ln(l) Sun Release 3.0 Last change: 12 July 1985 267 RMDEL(l) USER COMMANDS RMDEL(l) NAME rmdel - remove a delta from an SCCS file SYNOPSIS /usr/sccs/rmdel -rSID file . . . DESCRIPTION Rmdel removes the delta specified by the SID from each named SCCS file. The delta to be removed must be the newest (most recent) delta in its branch in the delta chain of each named SCCS file. In addition, the SID specified must not be that of a version being edited for the purpose of making a delta (that is, if a p-file (see get{ 1)) exists for the named SCCS file, the SID specified must not appear in any entry of the p-file). If a directory is named, rmdel behaves as though each file in the directory were specified as a named file, except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is taken to be the name of an SCCS file to be processed; non-SCCS files and unreadable files are silently ignored. The exact permissions necessary to remove a delta are documented in the Source Code Control System User’s Guide. Simply stated, they are either 1) if you make a delta you can remove it; or 2) if you own the file and directory you can remove a delta. FILES x-file (see delta( 1)) z-file (see delta{ 1)) SEE ALSO sccs(l), delta(l), get(l), help(l), prs(l), sccsfile(5). Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help(l) for explanations. 268 Last change: 6 March 1984 Sun Release 3.0 RMDIR(l) USER COMMANDS RMDIR(l) NAME rmdir, rm -r - remove (unlink) directories or files SYNOPSIS rmdir dir ... rm — r [ — f ] [ — i ] [ — ] filename . . . DESCRIPTION rmdir removes the named directories, which must be empty. rm, with the -r option, recursively removes directories, subdirectories, and any files they contain. See m(l) for more information. If the -i (interactive) option is in effect, rm asks whether to delete each file, and whether to examine each directory. The null option, -, indicates that all following arguments are filenames. This allow you to specify filenames starting with a minus to rm. SEE ALSO rm(l) Sun Release 3.0 Last change: 5 December 1985 269 ROFFBIB ( 1 ) USER COMMANDS ROFFBIB ( 1 ) NAME roffbib - run off bibliographic database SYNOPSIS roffbib [ -e ] [ -h ] [ -m name ] [ -n p ] [ -olist ] [ -Q ] [ -raN ] [ -sN ] [ -Tterm ] [ -V ] [ -x ] [ filename ] ... DESCRIPTION Roffbib prints out all records in a bibliographic database, in bibliography format rather than as footnotes or endnotes. Generally it is used in conjunction with sortbib: sortbib database | roffbib OPTIONS Roffbib accepts all options understood by nr off (l) except -i and -q. -e Produce equally-spaced words in adjusted lines using full terminal resolution. -h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every 8 nominal character widths. — m Prepend the macro file lusr/lib/tmacltmac.name to the input files. There should be a space between the -m and the macro filename. This set of macros will replace the ones defined in /usr/lib/tmac/tmac.bib. -up Number first generated page p . -olist Print only page numbers that appear in the comma-separated list of numbers and ranges. A range N-M means pages N through M; an initial -N means from the beginning to page N; a final N- means from page N to end. -Q Queue output for the phototypesetter. Page offset is set to 1 inch. -raN Set register a (one-character) to N. The command-line argument -rNl will number the refer- ences starting at 1. Four command-line registers control formatting style of the bibliography, much like the number registers of ms( 7). The flag -rV2 will double space the bibliography, while -rVl will double space references but single space annotation paragraphs. The line length can be changed from the default 6.5 inches to 6 inches with the -rL6i argument, and the page offset can be set from the default of 0 to one inch by specifying -rOli (capital O, not zero). — s N Halt prior to every N pages for paper loading or changing (default N =1). To resume, enter a new- line or carriage return. -T Specify term as the terminal type. -V Send output to the Versatec. Page offset is set to 1 inch. —x If abstracts or comments are entered following the %X field key, roffbib will format them into paragraphs for an annotated bibliography. Several %X fields may be given if several annotation paragraphs are desired. FILES /usr/lib/tmac/tmac.bib file of macros used by nroff/troff SEE ALSO "refer" in Formatting Documents on the Sun Workstation refer(l), addbib(l), sortbib(l), indxbib(l), lookbib(l), nroff(l) BUGS Users have to rewrite macros to create customized formats. 270 Last change: 21 August 1985 Sun Release 3.0 RSH(IC) USER COMMANDS RSH(IC) NAME rsh - remote shell SYNOPSIS rsh host [ -1 username ] [ -n ] command host [ -1 username ] [ -n ] command DESCRIPTION rsh connects to the specified host, and executes the specified command, rsh copies its standard input to the remote command, the standard output of the remote command to its standard output, and the standard error of the remote command to its standard error. Interrupt, quit and terminate signals are propagated to the remote command; rsh normally terminates when the remote command does. If you omit command, instead of executing a single command, rsh logs you in on the remote host using rlo- gin. Shell metacharacters which are not quoted are interpreted on the local machine, while quoted metacharac- ters are interpreted on the remote machine. Thus the command: tutorial% rsh lizard cat lizard.file » tutorial. file appends the remote file lizard.file from the machine called lizard to the file called tutorial file on the machine called tutorial, while the command: tutorial rsh lizard cat Iizard.file "»" another .lizard.file appends the file lizard.file on the machine called lizard to the file another. lizard.file. which also resides on the machine called lizard. Host names are given in the file /etc/hosts. Each host has one standard name (the first name given in the file), which is rather long and unambiguous, and optionally one or more nicknames. The host names for machines to which your machine is networked are also found in the directory /usr/hosts, as symbolic links to rsh. If you put this directory in your search path then the rsh can be omitted. OPTIONS -1 username use username as the remote username instead of your local username. In the absence of this option, the remote username is the same as your local username. This remote name must be equivalent to the originating account. No provision is made for specifying a password with a com- mand, and none is necessary — if your username is known at the remote end you will be admitted, otherwise you will be prompted for a password. -n redirect the input of rsh to Idevl null. You sometimes need this option to avoid unfortunate interactions between rsh and the shell which invokes it For example, if you are running csh and invoke a rsh in the background without redirecting its input away from the terminal, it will block even if no reads are posted by the remote command. The -n option will prevent this. The type of remote shell (sh or csh) is determined by the user’s entry in the file /etc/passwd on the remote system. FILES /etc/hosts /usr/hosts/* SEE ALSO rlogin (1C) BUGS You cannot run an interactive command (like vi; use rlogin if you wish to do so.) Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to explain here. Sun Release 3.0 Last change: 23 September 1985 271 RSH(IC) USER COMMANDS RSH(IC) The current local environment is not passed to the remote shell. Sometimes the -n option is needed for reasons that are less than obvious. For example, the command: rsh somehost dd UWdev/nrmtO bs=20b | tar xvpBf - will put your shell into a strange state. Evidently, what happens is that the tar terminates before the rsh. The rsh then tries to write into the "broken pipe" and, instead of terminating neatly, proceeds to compete with your shell for its standard input. Invoking rsh with the -n option avoids such incidents. Note, however, that this bug occurs only when rsh is at the beginning of a pipeline and is not reading stan- dard input. Don’t use the -n if the rsh actually needs to read standard input. For example, tar cf - . | rsh sundial dd of=/dev/rmtO obs=20b doesn’t produce the bug. If you were to use the -n in a case like this, the rsh would incorrectly read from I dev! null instead of from the pipe. 272 Last change: 23 September 1985 Sun Release 3.0 RUP(IC) USER COMMANDS RUP( 1C) NAME rup - show host status of local machines (RPC version) SYNOPSIS rup [ -h ] [ -I ] [ -t ] [ host ... ] DESCRIPTION R up gives a status similar to uptime for remote machines; It broadcasts on the local network, and displays the responses it receives. Normally, the listing is in the order that responses are received, but this order can be changed by specifying one of the options listed below. When host arguments are given, rather than broadcasting rup will only query the list of specified hosts. A remote host will only respond if it is running the rstatd daemon, which is normally started up from inetd(8C). OPTIONS — h sort the display alphabetically by host name. —1 sort the display by load average — t sort the display by up time. FILES /etc/servers SEE ALSO ruptime(lC), inetd(8C), rstatd(8C) BUGS Broadcasting does not work through gateways. Sun Release 3.0 Last change: 5 July 1985 273 RUPTIME ( 1C ) USER COMMANDS RUPTIME (1C) NAME ruptime - show host status of local machines SYNOPSIS ruptime [ —a ] [ — 1 3 [ — t ] [ — u ] DESCRIPTION Ruptime gives a status line like uptime for each machine on the local network; these are formed from pack- ets broadcast by each host on the network once a minute. Machines for which no status report has been received for 5 minutes are shown as being down. Normally, the listing is sorted by host name, but this order can be changed by specifying one of the options listed below. OPTIONS -a count even those users who have been idle for an hour or more. -1 sort the display by load average. -t sort the display by up time. -u sort the display by number of users. FILES /usr/spool/rwho/whod.* data files SEE ALSO rwho(lC) 274 Last change: 7 March 1984 Sun Release 3.0 RUSERS(IC) USER COMMANDS RUSERS(IC) NAME rusers - who’s logged in on local machines (RPC version) SYNOPSIS rusers [ -a ] [ -h ] [ -i ] [ -1 ] [ -u ] [ host . . . ] DESCRIPTION The rusers command produces output similar to users(l) and who(l), but for remote machines. It broad- casts on the local network, and prints the responses it receives. Normally, the listing is in the order that responses are received, but this order can be changed by specifying one of the options listed below. When host arguments are given, rather than broadcasting rusers will only query the list of specified hosts. The default is to print out a listing in the style of users(l) with one line per machine. When the -1 flag is given, a rwho(l) style listing is used. In addition, if a user hasn’t typed to the system for a minute or more, the idle time is reported. A remote host will only respond if it is running the rusersd daemon, which is normally started up from inetd. OPTIONS —a gives a report for a machine even if no users are logged on. — h sort alphabetically by host name. -i sort by idle time. -1 Give a longer listing in the style of who(l ). -u sort by number of users. FILES /etc/servers SEE ALSO rwho(lC), inetd(8C), rusersd(8C) BUGS Broadcasting does not work through gateways. Sun Release 3.0 Last change: 5 July 1985 275 RWALL(l) USER COMMANDS RWALL(l) NAME rwall - write to all users over a network SYNOPSIS rwall hostl host2 ... rwall -n netgroupl netgroup2 ... rwall -h host -n netgroup DESCRIPTION Rwall reads a message from standard input until end-of-file. It then sends this message, preceded by the line “Broadcast Message ...”, to all users logged in on the specified host machines. With the -n option, it sends to the specified network groups, which are defined in netgroupl, 5). A machine can only receive such a message if it is running rwalld( 8), which is normally started up from letc/servers by the daemon inetd{ 8). FILES /etc/servers SEE ALSO wall(l), netgroup(5), rwalld(8), shutdown(8) BUGS The timeout is fairly short in order to be able to send to a large group of machines (some of which may be down) in a reasonable amount of time. Thus the message may not get thru to a heavily loaded machine. 276 Last change: 1 February 1985 Sun Release 3.0 RWHO(IC) USER COMMANDS RWHO(IC) NAME rwho - who’s logged in on local machines SYNOPSIS rwho [ -a ] DESCRIPTION The rwho command produces output similar to who( 1), but for all machines on your network. If no report has been received from a machine for 5 minutes, rwho assumes the machine is down, and does not report users last known to be logged into that machine. If a user hasn’t typed to the system for a minute or more, rwho reports this idle time. If a user hasn’t typed to the system for an hour or more, the user is omitted from the output of rwho unless the -a flag is given. OPTIONS -a report all users whether or not they have typed to the system in the past hour. FILES /usr/spool/rwho/whod.* information about other machines SEE ALSO ruptime(lC), rwhod(8C) BUGS Does not work through gateways. This is unwieldy when the number of machines on the local net is large. Sun Release 3.0 Last change: 8 March 1984 277 SACT(l) USER COMMANDS SACT(l) NAME sact - print current SCCS file editing activity SYNOPSIS /usr/sccs/sact file . . . DESCRIPTION Sact informs the user of any SCCS files which have had one or more get -e commands applied to them, that is, there are files out for editing, and deltas are pending. If a directory is named on the command line, sact behaves as though each file in the directory were specified as a named file, except that non-SCCS files and unreadable files are silently ignored. If a name of - is given, the standard input is read with each line being taken as the name of an SCCS file to be processed. The output for each named file consists of five fields separated by spaces. Field 1 specifies the SID of a delta that currently exists in the SCCS file to which changes will be made to make the new delta. Field 2 specifies the SID for the new delta to be created. Field 3 contains the logname of the user who will make the delta (that is, executed a get for editing). Field 4 contains the date that get -e was executed. Field 5 contains the time that get -e was executed. SEE ALSO sccs(l), delta(l), get(l), unget(l). Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS Use help( 1) for explanations. 278 Last change: 6 March 1984 Sun Release 3.0 sees ( 1 ) USER COMMANDS SCCS(l) NAME sees - front end for the sees subsystem SYNOPSIS sees [ -r ] [ -d prefixpath ] [ -pfinalpath ] command [ SCCS-flags ...][ file ... ] DESCRIPTION system" The sees command is a front end to the utility programs of the Source Code Control System (sees). sees normally prefixes each file, or the last component of each file, with the string SCCS/s., because you normally keep your SCCS database files in a directory called SCCS, and each database file starts with an 5 . prefix. Secs program options must appear before the command argument. Flags to be passed to the actual SCCS command (utility program) must appear after the command argument. These flags are specific to the com- mand being used, and are discussed in Programming Utilities for the Sun Workstation. Secs also includes the capability to run ‘set user id’ to another user to provide additional protection. Cer- tain commands (such as admin) cannot be run ‘set user id’ by all users, since this would allow anyone to change the authorizations. Such commands are always run as the real user. OPTIONS -r Runs secs as the real user rather than as whatever effective user secs is ‘set user id’ to. -d prefixpath Defines the prefix portion of the pathname for the SCCS database files. The default prefix portion of the pathname is the current directory. Prefixpath is prefixed to the entire pathname. For exam- ple: tutorial% sees -d/usr/include get sys/inode.h converts to: get /usr/include/sys/SCCS/s.inode.h The intent here is to create aliases such as: alias syssccs secs -d/usr/src which will be used as: tutorial% syssccs get cmd/who.c —pfinalpath Defines the name of a lower directory in which the SCCS files will be found; SCCS is the default Finalpath is appended before the final component of the pathname. For example: tutorial% secs -pprivate get usr/include/stdio.h converts to: get usr/include/private/s.stdio.h ADDITIONAL SCCS COMMANDS Several ‘pseudo-commands’ are available in addition to the usual SCCS commands. These are: admin The admin command is similar to that of the raw SCCS admin command. When creating new s. files, the create command (described just below) does more of the startup work for you and should be used in preference to admin. create Create is used when creating new 5. files. Given a C source language file called obscure.c, Create does the following actions: (1) creates the s. file called s. obscure. c in the SCCS directory; (2) renames the original source file to , obscure. c; (3) does an sees get on obscure. c. edit Get a file for editing. delget Perform a delta on the named files and then get new versions. The new versions have id key- words expanded, and so cannot be edited. deledit Same as delget, but produces new versions suitable for editing. Deledit is useful for making a ‘checkpoint’ of your current editing phase. Sun Release 3.0 Last change: 8 March 1984 279 SCCS(l) USER COMMANDS SCCS(l) fix Removes the named delta, but leaves you with a copy of the delta with the changes that were in it. Fix must be followed by a -r flag. Fix is useful for fixing small compiler bugs, etc. Since fix doesn’t leave audit trails, use it carefully. clean Removes everything from the current directory that can be recreated from SCCS files. Clean checks for and does not remove any files being edited. If Clean -b is used, branches are not checked to see if they are currently being edited. Note that-b is dangerous if you are keeping the branches in the same directory. unedit ‘Undoes’ the last edit or get -e and returns a file to its previous condition. If you unedit a file being edited, all changes made since the beginning of the editing session are lost info Displays a list of all files being edited. If the -b flag is given, branches (that is, SID’s with two or fewer components) are ignored. If the -u flag is given (with an optional argument), only files being edited by you (or the named user) are listed. check Checks for files currently being edited, like info, but returns an exit code rather than a listing: nothing is printed if nothing is being edited, and a non-zero exit status is returned if anything is being edited. Check may thus be included in an ‘install’ entry in a makefile, to ensure that every- thing is included in an SCCS file before a version is installed. tell Displays a list of files being edited on the standard output Filenames are separated by newlines. Takes the -b and -u flags like info and check. diffs Compares (in cUff-Vkt format) the current version of the program you have out for editing and the versions in SCCS format EXAMPLES To put a file called myprogram.c into SCCS format for the first time, assuming also that there is no SCCS directory already existing: tutorial% mkdir SCCS tutorial% sees create myprogram.c rnyprograntc: 1.1 14 lines after you have verified that everything is all right you remove the version of the file that starts with a comma: tutorial% rm , myprogram.c tutorials To get a copy of myprogram.c for editing, edit that file, then place it back in the SCCS database: tutorial% sees edit myprogram.c 1.1 new delta 1.2 14 lines tutorial% vi myprogram.c your editing session tutorial% sees delget my program. c comments? Added abusive responses for compatibility with rest of system 1.2 7 inserted 7 deleted 7 unchanged 1.2 14 lines tutorial% 280 Last change: 8 March 1984 Sun Release 3.0 SCCS(l) USER COMMANDS SCCS(l) To get a file from another directory: tutorial% sees -p/usr/src/sccs/ get cc.c or: tutorial% secs get /usr/src/sccs/cc.c To make a delta of a large number of files in the current directory: tutorial% secs delta *.c To get a list of files being edited that are not on branches: tutorial% secs info -b To delta everything that you are editing: tutorial% secs delta 'secs tell -u' In a makefile, to get source files from an SCCS file if it does not already exist: SRCS = $(SRCS): sees get $(REL) $@ REGULAR SCCS COMMANDS The ‘regular’ SCCS commands are described very briefly below. It is unlikely that you ever need to use these commands because the user interface is so complicated, and the sees front end command does 99.9% of the interesting tasks for you. admin Creates new SCCS files and changes parameters of exitsing SCCS files. You can use sees create to create new SCCS files, or use secs admin to do other things. ede Changes the commentary material in an SCCS delta. comb Combines SCCS deltas and reconstructs the SCCS files. delta Permanently introduces changes that were made to a file previously retrieved via secs get. You can use secs delget as the more useful version of this command since secs delget does all of the useful work and more to boot. get Extracts a file from the SCCS database, either for compilation, or for editing when the -e option is used. Use secs get if you really need it, but secs delget will normally have done this job for you. Use secs edit instead of get with the -e option. help Supposed to help you interpret SCCS error messages, but usually just parrots the messaage and is generally not considered very helpful. prs Displays information about what is happening in an SCCS file. rmdel Removes a delta from an SCCS file. sact Displays information about editing activity in an SCCS file. The sees info command is a lot more useful for the real life user. sccsdiff Compares two versions of an SCCS file and generates the differences between the two versions. The secs delget command does all this work as part of its normal process. unget Undoes the work of a previous get -e command or a sees edit command. Use the secs unedit command as a useful alternative. val Determines if a given SCCS file meets specified criteria. If you use the secs command, you shouldn’t need to use val, because its user interface is unbelievable. what Displays SCCS identification information. Sun Release 3.0 Last change: 8 March 1984 281 SCCS(l) USER COMMANDS SCCS(l) FILES /usr/sccs/* SEE ALSO admin(l), cdc(l), comb(l), delta(l), get(l), help(l), prs(l), rmdel(l), sact(l), sccsdiff(l) unget(l), val(l), what(l), sccsfile(5) Source Code Control System in Programming Utilities for the Sun Workstation 282 Last change: 8 March 1984 Sun Release 3.0 SCCSDIFF ( 1 ) USER COMMANDS SCCSDIFF ( 1 ) NAME sccsdiff - compare two versions of an SCCS file SYNOPSIS /usr/sccs/sccsdiff -r SIDl -r SID2 [-p ] [ -diffopts ] filenames DESCRIPTION sccsdiff compares two versions of an SCCS file and generates the differences between the two versions. Any number of SCCS files may be specified, but options apply to all files. OPTIONS —rSID? SIDl and SID2 specify the deltas of an SCCS file that are to be compared. Versions are passed to diff in the order given. -p pipe output for each file through pr. —diffopts the -c, — e, — f, — h, — b and — D options of diff cm be specified here. FILES /tmp/get????? Temporary files SEE ALSO sccs(l), diff(l), get(l), help(l), pr(l) Source Code Control System in Programming Tools for the Sun Workstation. DIAGNOSTICS ‘ ‘ file : No differences” If the two versions are the same. Use help for explanations. Sun Release 3.0 Last change: 23 September 1985 283 SCREENDUMP ( 1 ) USER COMMANDS SCREENDUMP ( 1 ) NAME screendump - dump frame buffer image SYNOPSIS screendump [ — f display ] [ — e ] [ — t type ] [ output-file ] DESCRIPTION Screendump reads out the contents of a frame buffer on any model of Sun Workstation and outputs the display image in Sun standard rasterfile format (see lusrlincludelrasterfile.h) on output-file (or on the stan- dard output if output-file is not specified). By default, screendump attempts to output the contents of the console frame buffer (Idevlfb). The -f option explicitly sets the name of the desired frame buffer device. The utility program screenload displays Sun standard rasterfiles on an appropriate Sun Workstation moni- tor. Output filters exist for printing standard monochrome rasterfiles on Versatec V-80 electrostatic plotters. OPTIONS — f display Use display as the device name of the display. -e Shorthand for -t 2. -t type Specify the type of the rasterfile to write: 0 Old format files compatible with Release 1.1 software. 1 Standard format. 2 Run-length encoding of bytes. 65535 To experiment with private encodings. EXAMPLES tutorial% screendump >save.this.image writes the current contents of the console frame buffer into the file save. this. image. tutorial% screendump -f /dev/cgoneO >save.co!or .image writes the current contents of the frame buffer Idev/cgoneO into the file save. color. image. tutorial% screendump | Ipr -Pversatec -v sends a rasterfile containing the current frame buffer to the lineprinter, selecting the printer named “versa- tec” and the “v” output filter (see letclprintcap). , FILES /dev/fb Default name of console display frame buffer. /dev/cgoneO Default name of the Sun-1 color display frame buffer. /dev/cgtwoO Default name of the Sun-2 color display frame buffer. /usr/lib/rasfilters/* Filters for the raster file SEE ALSO lpr(l), rastrepl(l), screenload(l) pr_dump in Programmer’ s Reference Manual for SunWindows 284 Last change: 1 February 1985 Sun Release 3.0 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD ( 1 ) NAME screenload - restore frame buffer image SYNOPSIS screenload [ -d ] [ -f display ] [ -i index ] [ -b ] [ -g ] [ -p ] [ -w ] [ -h# [#### [...]]] [ input-file ] DESCRIPTION Screenload accepts input in Sun standard rasterfile format (see lusr/include/rasterfile.h ) and attempts to display the input on the appropriate monitor (monochrome or color). Screenload normally displays rasterfiles on the console display, but displays them on some heuristically determined color display if it finds no console display. Screenload displays color rasterfiles only on a color monitor. Screenload is able to display monochrome rasters on a color display. If the dimensions of the image contained in the input data are smaller than the actual resolution of the display (for example, loading a 1024-by-800 Sun-1 image on a 1152-by-900 Sun-2 display), screenload centers the image on the actual workstation screen and fills the border area with solid black (by default). Various options may be used to change the fill pattern. If the dimensions of the image contained in the input data are larger than the actual resolution of the display, screenload clips the right and bottom edges of the input image. If there is an optional filename argument, screenload reads its input data from that file. If no filename argument is given, screenload reads its input data from the standard input. The utility program screendump creates Sun standard rasterfiles from the display on a Sun Workstation monitor. OPTIONS -d Verify that display dimensions and input data image dimensions match, and print warning mes- sages if they do not. — f display Use display as the name of the frame buffer device. — i index If the image is smaller than the display, use index (0 <= index < 256) as the index value into the color map for the foreground color of the border fill pattern. The default index value is 255. -b If the input data dimensions are smaller than the display dimensions, fill the border with a pattern of solid ones {default). On a monochrome display this results in a black border; on a color display the color map value selected by the -i option determines the border color. -g If the input data dimensions are smaller than the display dimensions, fill the border with a pattern of “desktop grey”. On a monochrome display this results in a border matching the background pattern used by the SunWindows system; on a color display the color map value selected by the -i option determines the foreground border color, though the pattern is the same as on a mono- chrome display. -p Wait for a newline to be typed on the standard input before exiting. -w If the input data dimensions are smaller than the display dimensions, fill the border with a pattern of solid zeros. On a monochrome display this results in a white border; on a color display the color map value at index 0 determines the border color. -h# If the input data dimensions are smaller than the display dimensions, fill the border with the bit pattern described by the following # 16-bit hexadecimal constants. Note that a “1” bit is black and a “0” bit is white on the monochrome display; on a color diplay the color map value selected by the -i option determines the border foreground color. The number of hex constants in the pat- tern is limited to 16. EXAMPLES tutorial% screenload saved.display.image reloads the raster image contained in the file saved.display.image on the display type indicated by the Sun Release 3.0 Last change: 6 February 1985 285 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD ( 1 ) rasterfile header in that file. tutorial% screenload -f/dev/cgoneO monochrome image reloads the raster image in the file monochrome. image on the frame buffer device Idev/cgoneO. tutorial% screenload -hi ffff sunJLsaved.image is equivalent to the -b option (fill border with black), while tutorial% screenload -h4 8888 8888 2222 2222 sun_l.saved.image is equivalent to the -g option (fill border with desktop grey). FILES /dev/fb Default name of console display frame buffer /dev/cgoneO Default name of Sun-1 color display frame buffer /dev/cgtwoO Default name of the Sun-2 color display frame buffer. /usr/lib/ras filters/* Filters for the raster file SEE ALSO screendump(l) prjoad in Programmer’s Reference Manual for SunWindows 286 Last change: 6 February 1985 Sun Release 3.0 SCRIPT ( 1 ) USER COMMANDS SCRIPT ( 1 ) NAME script - make typescript of terminal session SYNOPSIS script [ -a ] [ file ] DESCRIPTION Script makes a typescript of everything printed on your terminal. The typescript is written to file, or appended to file if the -a option is given. It can be sent to the line printer later with Ipr. If no file name is given, the typescript is saved in the file typescript. The script ends when the forked shell exits. OPTIONS Append the script to the specified file instead of writing over it. BUGS Script places everything in the log file. This is not what the naive user expects. Sun Release 3.0 Last change: 24 March 1983 287 SED(l) USER COMMANDS SED(l) NAME sed - stream editor SYNOPSIS sed [ — n ] [ — e script ] [ — f sfile ] [ file ] . . . DESCRIPTION Sed copies the named files (standard input default) to the standard output, edited according to a script of commands. OPTIONS -e Is a list of edit commands for sed. If there is just one -e option and no -f’s, the -e flag -e may be omitted. -f Take the script from sfile -n suppress the default output. SED SCRIPTS sed scripts consist of editing commands, one per line, of the following form: [address [, address] ] function [arguments] In normal operation sed cyclically copies a line of input into a pattern space (unless there is something left after a ‘D’ command), applies, in sequence, all commands whose addresses select that pattern space, and at the end of the script copies the pattern space to the standard output (except under -n) and deletes the pat- tern space. An address is either a decimal number that counts input lines cumulatively across files, a *$’ that addresses the last line of input, or a context address, ‘/regular expression/’, in the style of ed( 1) modified thus: The escape sequence ‘\n’ matches a newline embedded in the pattern space. A command line with no addresses selects every pattern space. A command line with one address selects each pattern space that matches the address. A command line with two addresses selects the inclusive range from the first pattern space that matches the first address through the next pattern space that matches the second. If the second address is a number less than or equal to the line number first selected, only one line is selected. Thereafter the process is repeated, looking again for the first address. Editing commands can be applied only to non-selected pattern spaces by use of the negation function '!’ (below). Comments. If the first nonwhite character in a line is a pound sign (#), sed treats that line as a comment, and ignores it. If, however, the first such line is of the form #n sed runs as if the -n flag were specified. In the following list of functions the maximum number of permissible addresses for each function is indi- cated in parentheses. An argument denoted text consists of one or more lines, all but the last of which end with ‘V to hide the newline. Backslashes in text are treated like backslashes in the replacement string of an ‘s’ command, and may be used to protect initial blanks and tabs against the stripping that is done on every script line. An argument denoted rfile or wfile must terminate the command line and must be preceded by exactly one blank. Each wfile is created before processing begins. There can be at most 10 distinct wfile arguments. (1) a\ text Append: Place text on the output before reading the next input line. (2) b label 288 Last change: 4 December 1984 Sun Release 3.0 SED(l) USER COMMANDS SED(l) Branch to the command bearing the label. Branch to the end of the script if label is empty. (2)c\ text Change: Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, place text on the output. Start the next cycle. (2) d Delete the pattern space. Start the next cycle. (2) D Delete the initial segment of the pattern space through the first newline. Start the next cycle. (2) g Replace the contents of the pattern space by the contents of the hold space. (2) G Append the contents of the hold space to the pattern space. (2) h Replace the contents of the hold space by the contents of the pattern space. (2) H Append the contents of the pattern space to the hold space. d)i\ text Insert: Place text on the standard output. (2)n Copy the pattern space to the standard output Replace the pattern space with the next line of input. (2)N Append the next line of input to the pattern space with an embedded newline. (The current line number changes.) (2) p Print: Copy the pattern space to the standard output. (2) P Copy the initial segment of the pattern space through the first newline to the standard output. (1) q Quit: Branch to the end of the script. Do not start a new cycle. (2) r rfile Read the contents of rfile. Place them on the output before reading the next input line. (2) s / regular expression/replacement/flags Substitute the replacement string for instances of the regular expression in the pattern space. Any character may be used instead of 7’. For a fuller description see ed{ 1). Flags is zero or more of g Global: Substitute for all nonoverlapping instances of the regular expression rather than just the first one. p Print the pattern space if a replacement was made, w wfile Write: Append the pattern space to wfile if a replacement was made. (2) t label Test: Branch to the command bearing the label if any substitutions have been made since the most recent reading of an input line or execution of a ‘t’. If label is empty, branch to the end of the script. (2) w wfile Write: Append the pattern space to wfile. (2) x Exchange the contents of the pattern and hold spaces. (2) y Istringl/string2/ Transform: Replace all occurrences of characters in stringl with the corresponding character in string2. The lengths of stringl and string2 must be equal. (2)! function Don’t: Apply the function (or group, if function is ‘{’) only to lines not selected by the address(es). (0) : label Sun Release 3.0 Last change: 4 December 1984 289 SED(l) USER COMMANDS SED(l) This command does nothing; it bears a label for ‘b’ and ‘t’ commands to branch to. Note that the maximum length of label is seven characters. (1) = Place the current line number on the standard output as a line. (2) { Execute the following commands through a matching *}’ only when the pattern space is selected. (0) An empty command is ignored. SEE ALSO Using UNIX Text Utilities on the Sun Workstation Editing Text Files on the Sun Workstation ed(l), grep(l), awk(l), lex(l) 290 Last change: 4 December 1984 Sun Release 3.0 SETKEYS ( 1 ) USER COMMANDS SETKEYS ( 1 ) NAME setkeys - modify the interpretation of keyboard keys SYNOPSIS setkeys [ reset | nosunview | [ [lefty ] [ noarrows ] ] ] [ sunl | sun2 1 sun3 ] DESCRIPTION Setkeys changes the kernel’s keyboard translation tables, converting a keyboard to one of a number of com- monly desired configurations. It takes an indication of the modifications to be performed, and optionally, the kind of keyboard attached to the user’s machine. It affects all keyboard input for the machine it is run on (in or out of the window system) until that effect is superseded by rebooting, or by running "setkeys reset". Normally, users should set their /etc/rc.local to run setkeys with appropriate arguments when their machine is booted. OPTIONS modifications Lefty Noarrows Nosunview Reset keyboard type Empty, "reset", "nosunview", or some combination of "lefty" and "noarrows". By default, the keyboard is set to produce the SunView function-key codes (Stop, Props, Front, Close, Find, Again, Undo, Put, Get and Erase; [ standard ] TF1 [ typing ] [ array ] [ .... ] default / lefty: A V < > [ standard ] Again RF1 Stop [ typing ] Undo RF3 [ array ] Put RF5 [ .... ] Get RF7 Delete Find default / lefty, noarrow: TF1 TF2 TF3 TF4 [ standard ] Again RF1 Stop [ typing ] Undo RF3 [ array ] Put RF5 [ .... ] Get RF7 Delete Find RF2 Props RF4 Front RF6 Close RF8 RF2 Props RF4 Front RF6 Close RF8 TF2 TF3 TF4 7 8 9 - 4 5 6, 1 2 3 En- 0 . ter 292 Last change: 31 October 1985 Sun Release 3.0 SETKEYS ( 1 ) USER COMMANDS SETKEYS ( 1 ) Sun2 & Sun3, reset / default: Stop Again TF1 TF2 ... [ standard Props Undo t typing Front Put [ array Close Get [ Find Delete [ noarrows (only): Stop Again TF1 TF2 ... [ standard Props Undo [ typing Front Put [ array Close Get [ Find Delete [ lefty: TF1 TF2 ... Stop RF1 [ standard RF6 RF4 [ typing RF9 RF7 [ array RF12 RF10 t RF15 RF13 [ lefty, noarrows Stop RF1 TF1 TF2 ... [ standard RF6 RF4 [ typing RF9 RF7 [ array RF12 RF10 [ RF15 RF13 [ nosunview: LF11 TF2 ... Stop TF11 [ standard LF12 TF12 [ typing LF13 TF13 [ array LF14 TF14 [ LF15 TF15 [ ] ] RF1 RF2 RF3 ] RF4 RF5 RF6 ] RF7 A RF9 Retn < RF11 > LF RF13 V RF15 ] ] RF1 RF2 RF3 ] RF4 RF5 RF6 ] RF7 RF8 RF9 Retn RF10 RF11 RF12 LF RF13 RF14 RF15 ] ] Again < Stop ] Undo > Props ] Put A Front Retn Get RF11 Close Ctrl Delete V Find ] ] Again RF2 Stop ] Undo RF5 Props ] Put RF8 Front Ret Get RF11 Close Ctrl Delete RF14 Find ] ] RF1 RF2 RF3 ] RF4 RF5 RF6 ] RF7 A RF9 Ret < RF11 > LF RF13 V RF15 Sun Release 3.0 Last change: 31 October 1985 293 SH ( 1 ) USER COMMANDS SH( 1 ) NAME sh - shell, the standard command programming language SYNOPSIS sh [ -acefhiknstuvx ] [ args ] DESCRIPTION Sh is a command programming language that executes commands read from a terminal or a file. See Invo- cation below for the meaning of arguments to the shell. Definitions A blank is a tab or a space. A name is a sequence of letters, digits, or underscores beginning with a letter or underscore. A parameter is a name, a digit, or any of the characters *, @, #, ?, $, and ! . Commands A simple-command is a sequence of non-blank words separated by blanks. The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as argu- ments to the invoked command. The command name is passed as argument 0 (see exec (2)). The value of a simple-command is its exit status if it terminates normally, or (octal) 200 +status if it terminates abnor- mally (see sigvec(2) for a list of status values). A pipeline is a sequence of one or more commands separated by | (or, for historical compatibility, by ‘). The standard output of each command but the last is connected by a pipe {2) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to ter- minate. The exit status of a pipeline is the exit status of the last command. A list is a sequence of one or more pipelines separated by &, &&, or | |, and optionally terminated by ; or &. Of these four symbols, ; and & have equal precedence, which is lower than that of && and | |. The symbols && and | | also have equal precedence. A semicolon (;) causes sequential execution of the preceding pipeline; an ampersand (&) causes asynchronous execution of the preceding pipeline (i.e., the shell does not wait for that pipeline to finish). The symbol && ( | |) causes the list following it to be exe- cuted only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of new-lines may appear in a list, instead of semicolons, to delimit commands. A command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command. for name [ in word ... ] do list done Each time a for command is executed, name is set to the next word taken firom the in word list. If in word ... is omitted, then the for command executes the do list once for each positional param- eter that is set (see Parameter Substitution below). Execution ends when there are no more words in the list. case word in [ pattern [ | pattern ] . . . ) list ;; ] . . . esac A case command executes the list associated with the first pattern that matches word. The form of the patterns is the same as that used for file-name generation (see File Name Generation) except that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly. if list then list [ elif list then list ] . . . [ else list ] fi The list following if is executed and, if it returns a zero exit status, the list following the first then is executed. Otherwise, the list following elif is executed and, if its value is zero, the list follow- ing the next then is executed. Failing that, the else list is executed. If no else list or then list is executed, then the if command returns a zero exit status, while list do list done A while command repeatedly executes the while list and, if the exit status of the last command in the list is zero, executes the do list; otherwise the loop terminates. If no commands in the do list are executed, then the while command returns a zero exit status; until may be used in place of while to negate the loop termination test. (list) 294 Last change: 26 August 1985 Sun Release 3.0 SH( 1 ) USER COMMANDS SH(1) Execute list in a sub-shell. {list;} list is simply executed. name () {list;} Define a function which is referenced by name. The body of the function is the list of commands between { and }. Execution of functions is described below (see Execution). The following words are only recognized as the first word of a command and when not quoted: if then else elif fi case esac for while until do done { } Comments A word beginning with # causes that word and all the following characters up to a new-line to be ignored. Command Substitution The standard output from a command enclosed in a pair of grave accents (" ) may be used as part or all of a word; trailing new-lines are removed. Parameter Substitution The character $ is used to introduce substitutable parameters. There are two types of parameters, posi- tional and keyword. If parameter is a digit, it is a positional parameter. Positional parameters may be assigned values by set. Keyword parameters (also known as variables) may be assigned values by writing: name -value [ name -value ] ... Pattern-matching is not performed on value. There cannot be a function and a variable with the same name. ${ parameter } The value, if any, of the parameter is substituted. The braces are required only when parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If param- eter is * or @, all the positional parameters, starting with $1, are substituted (separated by spaces). Parameter $0 is set from argument zero when the shell is invoked. ${parame ter:— word} If parameter is set and is non-null, substitute its value; otherwise substitute word. ${parame ten-word} If parameter is not set or is null set it to word ; the value of the parameter is substituted. Positional parameters may not be assigned to in this way. %{parameter:1word} If parameter is set and is non-null, substitute its value; otherwise, print word and exit from the shell. If word is omitted, the message “parameter null or not set” is printed. ${parameter:+word} If parameter is set and is non-null, substitute word; otherwise substitute nothing. In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following example, pwd is executed only if d is not set or is null: echo ${d:- N pwd v } If the colon (:) is omitted from the above expressions, the shell only checks whether parameter is set or not. The following parameters are automatically set by the shell: # The number of positional parameters in decimal. - Flags supplied to the shell on invocation or by the set command. ? The decimal value returned by the last synchronously executed command. $ The process number of this shell. ! The process number of the last background command invoked. Sun Release 3.0 Last change: 26 August 1985 295 SH( 1) USER COMMANDS SH( 1 ) The following parameters are used by the shell: HOME The default argument (home directory) for the cd command. PATH The search path for commands (see Execution below). CDPATH The search path for the cd command. MAR, If this parameter is set to the name of a mail file and the mailpath parameter is not set, the shell informs the user of the arrival of mail in the specified file. MAELCHECK This parameter specifies how often (in seconds) the shell will check for the arrival of mail in the files specified by the mailpath or mail parameters. The default value is 600 seconds (10 minutes). If set to 0, the shell will check before each prompt MAILPATH A colon (:) separated list of file names. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each file name can be followed by % and a message that will be printed when the modification time changes. The default mes- sage is you have mail. PSI Primary prompt string, by default “$ ”. PS2 Secondary prompt string, by default “> ” . IFS Internal field separators, normally space, tab, and new-line. SHELL When the shell is invoked, it scans the environment (see Environment below) for this name. If it is found and there is an ’r’ in the file name part of its value, the shell becomes a restricted shell. The shell gives default values to path, PSl, PS2, mailcheck and ifs. HOME and MAIL are set by login( 1). Blank Interpretation After parameter and command substitution, the results of substitution are scanned for internal field separa- tor characters (those found in IFS) and split into distinct arguments where such characters are found. Expli- cit null arguments ("" or - ') are retained. Implicit null arguments (those resulting from parameters that have no values) are removed. File Name Generation Following substitution, each command word is scanned for the characters *, ?, and [ . If one of these char- acters appears the word is regarded as a pattern. The word is replaced with alphabetically sorted file names that match the pattern. If no file name is found that matches the pattern, the word is left unchanged. The character . at the start of a file name or immediately following a /, as well as the character / itself, must be matched explicitly. * Matches any string, including the null string. ? Matches any single character. [ . . . ] Matches any one of the enclosed characters. A pair of characters separated by - matches any character lexically between the pair, inclusive. If the first character following the opening "[ " is a “!” any character not enclosed is matched. Quoting The following characters have a special meaning to the shell and cause termination of a word unless quoted: ; & ( ) | * < > new-line space tab A character may be quoted (i.e., made to stand for itself) by preceding it with a \. The pair \new-Iine is ignored. All characters enclosed between a pair of single quote marks l"), except a single quote, are quoted. Inside double quote marks (""), parameter and command substitution occurs and \ quotes the char- acters \, ' , ", and $. "$*" is equivalent to "$1 $2 . . .", whereas is equivalent to "$1" "$2" — 296 Last change: 26 August 1985 Sun Release 3.0 SH( 1) USER COMMANDS SH( 1 ) Prompting When used interactively, the shell prompts with the value of PS1 before reading a command. If at any time a new-line is typed and further input is needed to complete a command, the secondary prompt (i.e., the value of PS2) is issued. Input/Output Before a command is executed, its input and output may be redirected using a special notation interpreted by the shell. The following may appear anywhere in a simple-command or may precede or follow a com- mand and are not passed on to the invoked command; substitution occurs before word or digit is used: word »word <*c[-]word <&digit <&— Use file word as standard input (file descriptor 0). Use file word as standard output (file descriptor 1). If the file does not exist it is created; otherwise, it is truncated to zero length. Use file word as standard output. If the file exists output is appended to it (by first seek- ing to the end-of-file); otherwise, the file is created. The shell input is read up to a line that is the same as word, or to an end-of-file. The resulting document becomes the standard input. If any character of word is quoted, no interpretation is placed upon the characters of the document; otherwise, parameter and command substitution occurs, (unescaped) \new-line is ignored, and \ must be used to quote the characters \, $, ', and the first character of word. If - is appended to «*:, all leading tabs are stripped from word and from the document Use the file associated with file descriptor digit as standard input. Similarly for the stan- dard output using >&digit. The standard input is closed. Similarly for the standard output using >&-. If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that specified by the digit (instead of the default 0 or 1). For example: ... 2>&1 associates file descriptor 2 with the file currently associated with file descriptor 1. The order in which redirections are specified is significant. The shell evaluates redirections left-to-right For example: ... l>xxt 2>&1 first associates file descriptor 1 with file xxx. It associates file descriptor 2 with the file associated with file descriptor 1 (i.e. xxx). If the order of redirections were reversed, file descriptor 2 would be associated with the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xxx. If a command is followed by & the default standard input for the command is the empty file /dev/null. Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. Redirection of output is not allowed in the restricted shell. Environment The environment (see environ (5)) is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list. The shell interacts with the environment in several ways. On invoca- tion, the shell scans the environment and creates a parameter for each name found, giving it the corresponding value. If the user modifies the value of any of these parameters or creates new parameters, none of these affects the environment unless the export command is used to bind the shell’s parameter to the environment (see also set -a). A parameter may be removed from the environment with the unset com- mand. The environment seen by any executed command is thus composed of any unmodified name-value pairs originally inherited by the shell, minus any pairs removed by unset, plus any modifications or addi- tions, all of which must be noted in export commands. The environment for any simple-command may be augmented by prefixing it with one or more assignments to parameters. Thus: Sun Release 3.0 Last change: 26 August 1985 297 SH( 1) USER COMMANDS SH(1) term= 450 cmd and (export term; term= 450; cmd) are equivalent (as far as the execution of cmd is concerned). If the -k flag is set, all keyword arguments are placed in the environment, even if they occur after the com- mand name. The following first prints a=b c and c: echo a=b c set -k echo a=b c Signals The interrupt and quit signals for an invoked command are ignored if the command is followed by &; otherwise signals have the values inherited by the shell from its parent, with the exception of signal 1 1 (but see also the trap command below). Execution Each time a command is executed, the above substitutions are carried out If the command name matches one of the Special Commands listed below, it is executed in the shell process. If the command name does not match a Special Command, but matches the name of a defined function, the function is executed in the shell process (note how this differs from the execution of shell procedures). The positional parameters $1, $2 are set to the arguments of the function. If the command name matches neither a Special Com- mand nor the name of a defined function, a new process is created and an attempt is made to execute the command via exec (2). The shell parameter PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon (:). The default path is :/bin:/usr/bin (specifying the current directory, /bin, and /usr/bin, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If the command name contains a / the search path is not used; such commands will not be exe- cuted by the restricted shell. Otherwise, each directory in the path is searched for an executable file. If the file has execute permission but is not an a.out file, it is assumed to be a file containing shell commands. A sub-shell is spawned to read it. A parenthesized command is also executed in a sub-shell. The location in the search path where a command was found is remembered by the shell (to help avoid unnecessary execs later). If the command was found in a relative directory, its location must be re- determined whenever the current directory changes. The shell forgets all remembered locations whenever the PATH variable is changed or the hash -r command is executed (see below). Special Commands Input/output redirection is now permitted for these commands. File descriptor 1 is the default output loca- tion. : No effect; the command does nothing. A zero exit code is returned. . file Read and execute commands from file and return. The search path specified by PATH is used to find the directory containing file. break [ n ] Exit from the enclosing for or while loop, if any. If n is specified break n levels, continue [ n ] Resume the next iteration of the enclosing for or while loop. If n is specified resume at the n-th enclosing loop, cd [ arg ] Change the current directory to arg. The shell parameter HOME is the default arg. The shell parameter CDPATH defines the search path for the directory containing arg. Alternative directory names are separated by a colon (:). The default path is (specifying the current directory). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If arg begins with a / the search path is not used. Otherwise, each directory in the path is searched for arg . 298 Last change: 26 August 1985 Sun Release 3.0 SH(1) USER COMMANDS SH( 1 ) echo [ arg . . . ] Echo arguments. See echo(l) for usage and description, eval [ arg ... ] The arguments are read as input to the shell and the resulting command(s) executed, exec [ arg ... ] The command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments may appear and, if no other arguments are given, cause the shell input/output to be modified, exit [ n ] Causes a shell to exit with the exit status specified by n. If n is omitted the exit status is that of the last command executed (an end-of-file will also cause the shell to exit.) export [ name . . . ] The given name s are marked for automatic export to the environment of subsequently-executed commands. If no arguments are given, a list of all names that are exported in this shell is printed. Function names may not be exported, hash [ — r ] [ name . . . ] For each name , the location in the search path of the command specified by name is determined and remembered by the shell. The -r option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is presented. Hits is the number of times a command has been invoked by the shell process. Cost is a measure of the work required to locate a command in the search path. There are certain situations which require that the stored location of a command be recalculated. Commands for which this will be done are indicated by an asterisk (*) adjacent to the hits information. Cost will be incremented when the recalculation is done, login [arg ... ] Equivalent to exec login arg .... See login( 1) for usage and description, pwd Print the current working directory. See pwd(l) for usage and description, read [ name . . . ] One line is read from the standard input and the first word is assigned to the first name, the second word to the second name, etc., with leftover words assigned to the last name. The return code is 0 unless an end-of-file is encountered, readonly [ name . . . ] The given name s are marked readonly and the values of the these name s may not be changed by subsequent assignment. If no arguments are given, a list of all readonly names is printed, return [ n ] Causes a function to exit with the return value specified by n. If n is omitted, the return status is that of the last command executed, set [ — aefhkntuvx [ arg . . . ] ] -a Mark variables which are modified or created for export -e Exit immediately if a command exits with a non-zero exit status. -f Disable file name generation -h Locate and remember function commands as functions are defined (function commands are normally located when the function is executed). -k All keyword arguments are placed in the environment for a command, not just those that precede the command name. -n Read commands but do not execute them. -t Exit after reading and executing one command. -u Treat unset variables as an error when substituting. -v Print shell input lines as they are read. -x Print commands and their arguments as they are executed. — Do not change any of the flags; useful in setting $1 to -. Using + rather than - causes these flags to be turned off. These flags can also be used upon invo- cation of the shell. The current set of flags may be found in $-. The remaining arguments are Sun Release 3.0 Last change: 26 August 1985 299 SH( 1 ) USER COMMANDS SH( 1 ) positional parameters and are assigned, in order, to $1, $2, If no arguments are given the values of all names are printed, shift [ n ] The positional parameters from $n+l ... are renamed $1 If n is not given, it is assumed to be 1. test Evaluate conditional expressions. See test( 1) for usage and description. times Print the accumulated user and system times for processes run from the shell, trap [ arg ] [ n ] . . . The command arg is to be read and executed when the shell receives signal(s) n. (Note that arg is scanned once when the trap is set and once when the trap is taken.) Trap commands are executed in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the current shell is ineffective. An attempt to trap on signal 1 1 (memory fault) produces an error. If arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on exit from the shell. The trap command with no arguments prints a list of commands associated with each signal number, type [ name . . . ] For each name, indicate how it would be interpreted if used as a command name, umask [ ooo ] The user file-creation mode mask is set to ooo. The three octal digits refer to read/write/execute permis- sions for owner, group, and others, respectively. The value of each specified digit is subtracted from the corresponding ‘digit’ specified by the system for the creation of a file. For example, umask 022 removes group and others write permission (files normally created with mode 111 become mode 755; files created with mode 666 become mode 644). The current value of the mask is printed if ooo is omitted, unset [ name . . . ] For each name, remove the corresponding variable or function. The variables path, psi, PS2, MAILCHECK and IFS cannot be unset, wait [ n ] Wait for the specified process and report its termination status. If n is not given all currently active child processes are waited for and the return code is zero. Invocation If the shell is invoked through exec (2) and the first character of argument zero is -, commands are initially read from $HOME/.profile, if such files exist. Thereafter, commands are read as described below, which is also the case when the shell is invoked as /bin/sh. The flags below are interpreted by the shell on invoca- tion only; Note that unless the -c or -s flag is specified, the first argument is assumed to be the name of a file containing commands, and the remaining arguments are passed as positional parameters to that com- mand file: -c string If the -c flag is present commands are read from string . -s If the -s flag is present or if no arguments remain commands are read from the standard input. Any remaining arguments specify the positional parameters. Shell output (except for Special Commands) is written to file descriptor 2. -i If the -i flag is present or if the shell input and output are attached to a terminal, this shell is interactive. In this case terminate is ignored (so that kill 0 does not kill an interactive shell) and INTERRUPT is caught and ignored (so that wait is interruptible). In all cases, QUIT is ignored by the shell. The remaining flags and arguments are described under the set command above. EXIT STATUS Errors detected by the shell, such as syntax errors, cause the shell to return a non-zero exit status. If the shell is being used non-interactively execution of the shell file is abandoned. Otherwise, the shell returns 300 Last change: 26 August 1985 Sun Release 3.0 SH( 1 ) USER COMMANDS SH(1) the exit status of the last command executed (see also the exit command above). FILES $HOME/.profile /tmp/sh* /dev/null SEE ALSO csh(l), cd( 1), echo(l), login(l), pwd(l), test(l), dup(2), exec(2), fork(2), pipe®, signal(2), umask(2), wait(2), a.out(5), profile®, environ®. CAVEATS If a command is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to exec the original command. Use the hash command to correct this situation. If you move the current directory or one above it, pwd may not give the correct response. Use the cd com- mand with a full path name to correct this situation. Sun Release 3.0 Last change: 26 August 1985 301 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) NAME shelltool - Run a shell (or other program) in the SunView environment SYNOPSIS shelltool [ — C ] [ — B boldstyle ] [ program [ args ]] DESCRIPTION shelltool is a standard tool provided with the SunView environment. When invoked, shelltool runs a program, (usually a shell) in an interactive terminal emulator based on a tty subwindow. Keystrokes typed to the shelltool are passed to the program running in the shelltool. If this program is a shell, it accepts commands and runs programs in the usual way. For its scrolling and editting capabilities, you may prefer to use cmdtool instead of shelltool. See cmdtool( 1), suntools( 1), Terminal Emulators, and Windows and Window-Based Tools: Beginner’s Guide for more information. To run graphics programs, use gfxtool — see gfxtool( 1). DEFAULTS OPTIONS /Tty/Bold_style For programs that use emphasized text, shelltool supports bolding as well as inverse video. To set the emphasis style, choose the category Tty in defaultsedit and choose one of the following for the Bold style entry: None disables emphasis Offset_X thicken character horizontally OffsetY thicken character vertically Offset_X_and_Y thicken character both horizontally and vertically Offset_XY thicken character diagonally OffsetXandXY thicken character both horizontally and diagonally Offset_Y_and_XY thicken character both vertically and diagonally Offset_X_and_Y_and_XY thicken character horizontally, vertically and diagonally Invert display emphasis as inverse video, the standard default /Tty/Retained No is the standard default; it specifies that tty subwindows are not retained. If Yes is chosen, tty subwindows are retained; this enhances display speed at the expense of memory consumption. Repaint speed when the window is uncovered is greatly enhanced. COMMANDLINE OPTIONS -C Redirect system console output to this instance of the shelltool. -B boldstyle Sets the boldstyle for this instance of shelltool. Boldstyle may be any of the choices for the defaults database entry for /Tty/Bold_style, or it may be a number from 0 to 8. The numbers mean: 0 None 1 Offset_X 2 Offset_Y 3 Offset_X_and_Y (means Offset_X | Offset Y) 4 Offset_XY 5 Offset_X_and_XY (means Offset_X | Offset_XY) 6 Offset_Y_and_XY (means Offset_Y | Offset XY) 7 Offset_X_and_Y_and_XY (means Offset_X | Offset_Y | Offset_XY) 8 Invert shelltool also takes generic tool arguments; see s untools (1) for a list of these arguments. If a program argument is present, shelltool runs it. If there are no arguments, shelltool runs the program corresponding to your SHELL environment variable. If this environment variable is not available, then shelltool runs /bin/sh. 302 Last change: 30 September 1985 Sun Release 3.0 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) THE TERMINAL EMULATOR The tty subwindow of shelltool is a terminal emulator. Whenever a tty subwindow is created, the startup file '/.ttyswrc is parsed for tty subwindow-specific parameters. A sample .ttyswrc file may be found in /usr/lib/ttyswrc. The command format of this file is: # Comment set variable Turn on the specified variable. mapi key text When key is typed pretend text was input. mapo key text When key is typed pretend text was output. The only currently defined "variable" is "pagemode". "Key" is one of L1-L15, F1-F15, T1-T15, R1-R15, LEFT, or RIGHT (see note below). "Text" may contain escapes such as \E, \n, “X, etc. (escape,’ newline,’ control-X, respectively). See termcap( 5) for the format of the string escapes that are recognized. Note that "mapi" and "mapo" may be replaced by another keymapping mechanism in the future. NOTE: When using the default kernel keyboard tables, the keys LI, LEFT, RIGHT, BREAK, R8, RIO, R12, and R14 cannot be mapped in this way because they send special values to the tty subwindow. Also, when using the default kernel keyboard tables, L1-L10 are now used by SunView. See setkeys{\) and kbd (5) for more information on how to change the behavior of the keyboard. It is possible to have terminal-based programs drive the tool in which its tty subwindow resides by sending it special escape sequences. These escape sequences may also be sent by typing a key appropriately mapped using the "mapo" function described above. The following functions pertain to the tool in which the tty subwindow resides, not the tty subwindow itself. \E [It -open \E[2t - close (become iconic) \E[3t - move, with interactive feedback \E [ 3 ; TOP ; LEFTt - move, to TOP left (pixel coordinates) \E[4t - stretch, with interactive feedback \E[4;WIDTH;HTt - stretch, to WIDTH HT size (in pixels) \E[5t - expose \E[6t -hide \E [ 7 1 - refresh \E [ 8 ; ROWS ; COLSt - stretch, to ROWS COLS size (in characters) \E [lit - report if open or iconic by sending \E[ltor\E[2t \E[13t - report position by sending \E [ 3 ; TOP ; LEFTt \E[14t - report size in pixels by sending \E ( 4 ; WIDTH ; HTt \E[18t - report size in characters by sending \E [ 8 ; ROWS ; COLSt \E [20t - report icon label by sending \E] Llabel\E\ \E[21t - report tool header by sending \E] llabel\E\ \E] l\E\ - set tool header to \E] I\E\ - set icon to the icon contained in ; must be in iconedit output format \E]L