Commands Reference Manual for the Sun Workstation Sun Microsystems, Inc. • 2550 Garcia Avenue • Mountain View, CA 94043 • 415-960-1300 Part No: 800- 11.72-01 Revision E of 15 May, 1985 Trademarks Multibus is a trademark of Intel Corporation. Sun Workstation is a trademark of Sun Microsystems Incorporated. UNIX is a trademark of Bell Laboratories. Copyright ® 1983 by Sun Microsystems. This publication is protected by Federal Copyright Law, with all rights reserved. No part of this publication may be reproduced, stored in a retrieval system, translated, transcribed, or transmit- ted, 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. Revision History Revision Date Comments A 23rd February 1983 First release of this Manual. B 15th April 1983 Second Release of this manual involved many corrections to manual pages. C 1st August 1983 Third Release of this manual involved many corrections to manual pages. D 1st November 1983 Fourth Release of this manual involved many corrections to manual pages. Added OPTIONS to manual pages for clarity. Fixed numerous incorrect cross-references. E 7 January 1984 Fifth Release of this manual involved many corrections to manual pages. The manual was renamed the Commands Reference Manual instead of the User's Manual. F 15 May 1985 Corrected numerous bugs. Brought the Maintenance Com- mands and Procedures (formerly section 8) back into this manual and removed same from the System Manager’s Manual. Page numbering is contiguous throughout the manual and we replaced the permuted index with a human-oriented index. — in — INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) NAME intro — introduction to commands DESCRIPTION This section describes publicly accessible commands in alphabetic order. Certain distinctions of purpose are made in the headings: (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 document preparation. • Section 8 in this manual for system administration procedures, system maintenance and opera- tion commands, plus descriptions of network services daemons and servers. • Getting Started in the Beginner’s Guide to the Sun Workstation. 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( 2). 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 inaccessi- ble 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 2.0 Last change: 6 April 1985 1 ADB(l) USER COMMANDS ADB(l) NAME adb — debugger SYNOPSIS adb | — w ] j — k ] [ — Idir ] [ 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 contain 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 /dev/ mem. —I specifies a directory where files to be read with $< or $« (see below) will be sought; the default is /usr/lib/adb. USING ADB Adb reads commands from the standard input and displays responses on the standard output. Adb ignores QUIT; INTERRUPT causes return to the next adb command. Adb saves and restores terminal characteristics when running a sub— process. This makes it possi- ble to debug programs that manipulate the screen. See tty(i). In general, requests to adb are of the form [ address ] [, count ] [ command ] (;] The symbol dot (.) represents the current location. It is initially zero. If address is present then dot is set to address. For most commands count specifies how many times the command will be executed. The default count is 1. Address and count are expressions. EXPRESSIONS . The value of dot. + The value of dot incremented by the current increment. The value of dot decremented by the current increment. & The last address typed. (Used to be integer A number. The prefixes Oo and OO (“zero oh”) force interpretation in octal radix; the prefixes Ot and OT force interpretation in decimal radix; the prefixes Ox and OX force interpretation in hexadecimal radix. Thus 0o20 = 0tl6 = 0x10 = sixteen. If no prefix appears, then the default radix is used; see the $d command. -The default radix is ini- tially hexadecimal. The hexadecimal digits are 0123456789abcdefABCDEF with the obvious values. Note that if a hexadecimal number starts with a letter, but does not duplicate a defined symbol, it is accepted as a hexadecimal value. To enter a hexade- cimal number that is the same as a defined symbol, preceed it by 0, Ox, or OX. integer. fraction A 32 bit floating point number. 'cccc ' The ASCII value of up to 4 characters. A backslash (‘\’) may be used to escape a '. < name The value of name, which is either a variable name or a register name. Adb maintains a 2 Last change: 1 February 1985 Sun Release 2.0 ADB(l) USER COMMANDS ADB(l) number of variables (see VARIABLES) named by single letters or digits. If name is a register name then the value of the register is obtained from the system header in corfil. The register names are those printed by the $r command. symbol A symbol is a sequence of upper or lower case letters, underscores or digits, not starting with a digit. The backslash character \ may be used to escape other characters. The value of the symbol is taken from the symbol table in objfil. An initial _ will be prepended to symbol if needed. _ symbol In C, the ‘true name’ of an external symbol begins with It may be necessary to use this name to distinguish it from internal or hidden variables of a program. routine. name The address of the variable name in the specified C routine. Both routine and name are symbols. If name is omitted the value is the address of the most recently activated C stack frame corresponding to routine. ( exp ) The value of the expression exp. Unary operators *exp The contents of the location addressed by exp in corfil. %exp The contents of the location addressed by exp in objfil. (Used to be @.) — exp Integer negation. ~ exp Bitwise complement. exp Logical negation. *F exp (Control— f) Translates program addresses into sourcefile addresses, program has been compiled using the —go flag. See cc(l).) 'A exp (Control— a) Translates sourcefile addresses into program addresses, program has been compiled using the —go flag. See cc(l).) 'name (Back— quote) Translates a procedure name into a sourcefile address, program has been compiled using the —go flag. See cc(l).) ” filename” A filename enclosed in quotation marks (for instance, "main.c") produces the sourcefile address for the zero-th line of that file. Thus to reference the third line of the file main.c, we say: "main.c"+3. (Works only if the program has been compiled using the —go flag. See cc(l).) Binary operators are left associative and are less binding than unary operators. el + eS Integer addition. el — eS Integer subtraction. el*e2 Integer multiplication. el%e2 Integer division. el&e2 Bitwise conjunction. el | e2 Bitwise disjunction. el#e2 El rounded up to the next multiple of e2. VARIABLES Adb provides a number of variables. Named variables are set initially by adb but are not used subsequently. Numbered variables are reserved for communication as follows. 0 The last value printed. (Works only if the (Works only if the (Works only if the Sun Release 2.0 Last change: 1 February 1985 3 ADB(l) USER COMMANDS ADB(l) 1 The last offset part of an instruction source. 2 The previous value of variable 1. 9 The count on the last $< or $« command. On entry the following are set from the system header in the corfil. If corfil does not appear to be a core file then these values are set from objfil. b The base address of the data segment, d The data segment size, e The entry point. m The ‘magic’ number (0407, 0410 or 0413). s The stack segment size, t The text segment size. COMMANDS Adb commands consist of a verb followed by a modifier or list of modifiers. The verbs are: ? Print locations starting at address in objfil. / Print locations starting at address in corfil. = Print the value of address itself. @ Interpret address as a sourcefile address, and print locations in objfile or lines of the source text. (Works only if the program has been compiled using the —go flag. See «(!)■) : Manage a subprocess. $ Execute miscellaneous commands. > Assign a value to a variable or register. RETURN Repeat the previous command with a count of 1. Dot is incremented by its current incre- ment. S Call the shell to execute the following command. Each verb has a specific set of modifiers, these are described below. [ r, /, @, = ] Modifiers The first four verbs described above take the same set of modifiers. These modifiers specify the format of command output. Each modifier consists of a letter preceded by an optional repeat count; each verb may take one or more modifiers: [ f, /, @> = ] [ [ rcount ] fletter . . . j Each time one of these commands is given, dot is incremented by a certain amount (sum of the increments specific to each format letter, see below). If a command is given without a modifier, the last specified format is used to display output. The following lists the format letter, the amount dot increments each time the letter is used, and a description of what each letter does, o 2 Print 2 bytes in octal. All octal numbers output by adb are preceded by 0. O 4 Print 4 bytes in octal, q 2 Print in signed octal. Q 4 Print long signed octal, d 2 Print in decimal. D 4 Print long decimal. 4 Last change: 1 February 1985 Sun Release 2.0 ADB(l) USER COMMANDS ADB(l) x 2 Print 2 bytes in hexadecimal. X 4 Print 4 bytes in hexadecimal, u 2 Print as an unsigned decimal number. U 4 Print long unsigned decimal, f 4 Print the 32 bit value as a floating point number. F 8 Print double floating point, b 1 Print the addressed byte in octal, c 1 Print the addressed character. C 1 Print the addressed character using the standard escape convention: print control characters as "X and the delete character as *?. e n Print the addressed characters until a zero character is reached. S n Print a string using the “ X escape convention (see C above), n is the length of the string including its zero terminator. Y 4 Print 4 bytes in date format (see ctime(3)). i n Print as machine instructions, n is the number of bytes occupied by the instruction. In this format, variables 1 and 2 are set to the offset parts of the source and destina- tion respectively. z n Print as machine instructions with 68010 instruction timings, n is the number of bytes occupied by the instruction. In this format, variables 1 and 2 are set to the offset parts of the source and destination respectively. I 0 Print the source text line specified by dot (@ command) or most closely correspond- ing to dot (? command). a 0 Print the value of dot in symbolic form. Symbols are checked to ensure that they have an appropriate type as indicated below. / local or global data symbol ? local or global text symbol = local or global absolute symbol p 4 Print the addressed value in symbolic form using the same rules for symbol lookup as a. A 0 Print the value of dot in sourcefile symbolic form, that is: " filename" +nnn. (Works only if the program has been compiled using the —go flag. See cc(l).) P 4 Print the addressed value in sourcefile symbolic form, that is: " filename" +nnn. (Works only if the program has been compiled using the —go flag. See cc(l).) 4 0 When preceded by an integer, tabs to the next appropriate tab stop. For example, 84 moves to the next 8-space tab stop, r 0 Print a space, n 0 Print a newline. "..."0 Print the enclosed string. Dot is decremented by the current increment. Nothing is printed. + Dot is incremented by 1. Nothing is printed. — Dot is decremented by 1. Nothing is printed. [ r, /] Modifiers \m value mask Words starting at dot are masked with mask and compared with value until a match is found. If L is used then the match is for 4 bytes at a time instead of 2. If no match is found then dot is unchanged; otherwise dot is set to the matched location. If mask is omitted then —1 is used. [r/]w value ... Sun Release 2.0 Last change: 1 February 1985 5 ADB(l) USER COMMANDS ADB(l) Write the 2-byte value into the addressed location. If the command is W, write 4 bytes. Odd addresses are not allowed when writing to the subprocess address space. [T/]m hi el /i[f/| New values for {hi, el, fl) are recorded. If less than three expressions are given then the remaining map parameters are left unchanged. If the T or ‘/’ is followed by V then the second segment ( bS , eS,f2) of the address mapping is changed (see ADDRESS MAPPING, below). If the list is terminated by T or ‘/’ then the file ( objfil or corfil respectively) is used for subsequent requests. (So that, for example, ‘/m?’ will cause '/' to refer to objfil.) : Modifiers be Set breakpoint at address. The breakpoint is executed count— 1 times before causing a stop. Each time the breakpoint is encountered the command c is executed. If this command is omitted or sets dot to zero then the breakpoint causes a stop. Be Like b but takes a sourcefile address. (Works only if the program has been compiled using the —go flag. See cc(l).) d Delete breakpoint at address. B Like d but takes a sourcefile address. (Works only if the program has been compiled using the —go flag. See cc(l).) r Run objfil as a subprocess. If address is given explicitly then the program is entered at this point; otherwise the program is entered at its standard entry point, count specifies how many breakpoints are to be ignored before stopping. Arguments to the subprocess may be supplied on the same line as the command. An argument starting with < or > causes the standard input or output to be established for the command. All signals are enabled on entry to the subprocess. cs The subprocess is continued with signal s, see sigvec{ 2). If address is given then the subprocess is continued at this address. If no signal is specified then the signal that caused the subprocess to stop is sent. Breakpoint skipping is the same as for r. bs As for c except that the subprocess is single stepped count times. If there is no current subprocess then objfil is run as a subprocess as for r. In this case no signal can be sent; the remainder of the line is treated as arguments to the subprocess. S Like s but single steps source lines, rather than machine instructions. This is acheived by repeatedly single— stepping machine instructions until the corresponding sourcefile address changes. (Thus procedure calls cause stepping to stop.) (Works only if the program has been compiled using the —go flag. See cc(l).) 1 Add the signal specified by address to the list of signals which are passed directly to the subprocess with the minimum of interference. Normally, adb intercepts all sig- nals destined for the subprocess, and the user must use the :c command to continue the process with the signal. Signals on this list are handed to the process with an implicit :cs as soon as they are seen. t Remove the signal specified by address from the list of signals that are implicitly passed to the subprocess. k Terminate the current subprocess, if any. $ Modifiers file Append output to file, which is created if it does not exist. If file is omitted, output is returned to the terminal. ? Print process id, the signal which stopped the subprocess, and the registers. Pro- duces the same response as $ used without any modifier, r Print the general registers and the instruction addressed by pc. Dot is set to pc. b Print all breakpoints and their associated counts and commands, c C stack backtrace. If address is given then it is taken as the address of the current frame instead of the contents of the frame— pointer register. If count is given then only the first count frames are printed. C Similar to c, but in addition prints the names and (32 bit) values of all automatic and static variables for each active function. (Works only if the program has been compiled using the —go flag. See cc(l).) d Set the default radix to address and report the new value. Note that address is interpreted in the (old) current radix. Thus “10$d” never changes the default radix. To make decimal the default radix, use “OtlO$d”. e Print the names and values of external variables, w Set the page width for output to address (default 80). 0 Set the limit for symbol matches to address (default 255). 0 All integers input are regarded as octal, q Exit from adb. v Print all non zero variables in octal, m Print the address map. f Print a list of known source file names, p Print a list of known procedure names. p ( Kernel debugging ) Change the current kernel memory mapping to map the desig- nated user structure to the address given by the symbol _u. The address argument is the address of the user’s proc structure. 1 Show which signals are passed to the subprocess with the minimum of adb interfer- ence. Signals may be added to or deleted from this list using the :i and st com- mands. W Re-open objfile and corfile for writing, as though the — w command— line argument had been given. ADDRESS MAPPING The interpretation of an address depends on the context it is used in. If a subprocess is being debugged, addresses are interpreted in the usual way (as described below) in the address space of the subprocess. If the operating system is being debugged, either post-mortem or by using the special file /dev/mem to interactively examine and/or modify memory, the maps are set to map the kernel virtual addresses which start at zero. For some commands, the address is not inter- preted as a memory address at all, but as an ordered pair representing a file number and a line number within that file. The @ command always takes such a sourcefile address, and several operators are available to convert to and from the more customary core locations. The address in a file associated with a written address is determined by a mapping associated with that file. Each mapping is represented by two triples ( bl , el, fl) and (b2, e2, f2) and the file address corresponding to a written address is calculated as follows. bl file address=address+fl—bl, otherwise, Sun Release 2.0 Last change: 1 February 1985 7 ADB(l) USER COMMANDS ADB(l) b2 file addres8’=addres8+f2—b2, otherwise, the requested address is not legal. If a ? or / is followed by an * then only the second triple is used. The initial setting of both mappings is suitable for normal a.out and core files. If either file is not of the kind expected then, for that file, bl is set to 0, el is set to the maximum file size and fl is set to 0; in this way the whole file can be examined with no address translation. 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 variable 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. 8 Last change: 1 February 1985 Sun Release 2.0 ADDBIB ( 1 ) USER COMMANDS ADDBIB ( 1 ) NAME addbib — create or extend bibliographic database SYNOPSIS addbib [ — p promptfile ] [ —a ] database DESCRIPTION When this program starts up, answering “y” to the initial “Instructions?” prompt yields direc- tions; typing “n” or RETURN skips them. Addbib then prompts for various bibliographic fields, reads responses from the terminal, 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). The —a option suppresses prompting for an abstract; asking for an abstract is the default. Abstracts are ended with a CTRL-d. The — p option causes addbib to use a new prompting skele- ton, defined in promptfile. This file should contain prompt strings, a tab, and the key-letters to be written to the database. 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 %0 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 %I Computing Services %C Berkeley %D 1982 Sun Release 2.0 Last change: 27 October 1983 9 ADDBIB ( 1 ) USER COMMANDS ADDBIB ( 1 ) %0 UNX 4.3.5. FILES promptfile optional file to define prompting SEE ALSO refer(l), sortbib(l), roffbib(l), indxbib(l) 10 Last change: 27 October 1983 Sun Release 2.0 AD JACENTSCREENS ( 1 ) USER COMMANDS AD JACENTSCREENS ( 1 ) NAME adjacentscreens — notify the window driver of the physical relationships of screens SYNOPSIS adjacentscreens [ — c | — m ] center screen [ [ — 1 ] — r [ — t [ — 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 fdev/fb. 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 / dev/ cgoneO. The —I 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 —I, but means that side screen is to the right of center screen. — t side screen Like —1, but means that side screen is on ::= RELEASE NUMBER I 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. q text Text is defined by the user. The text is substituted for all occurrences of the %Q% key- word in SCCS file text retrieved by get(l). 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 b. 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{ 1) prompts for Modification Request (MR) numbers as the reason for creating a delta. The optional program specifies the name of an MR number validity checking program (see delta( 1)). 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( 1)). 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( 1)), 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 them- selves be mode 444. The mode of the directories allows only the owner to modify SCCS files con- tained in the directories. 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 —s 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 e .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. 14 Last change: 1 February 1985 Sun Release 2.0 ADMIN ( 1 ) USER COMMANDS ADMIN ( 1 ) DIAGNOSTICS Use help{ 1) for explanations. Sun Release 2.0 Last change: 1 February 1985 15 AR(1) USER COMMANDS AR( 1 ) NAME ar — archive and library maintainer SYNOPSIS ar d[m]p|q]r[t[x [ abcilouv ] [ poaname ] afile name ... DESCRIPTION At 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 pur- pose. 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 with the r and m options. b Place new files before posname ( posname argument must be present). Applies only with the r and m options. c 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. I Local. Ar places its temporary files in the directory /tmp. The I modifier places them in the local directory. 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 informa- tion 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) 16 Last change: 1 November 1983 Sun Release 2.0 AR( 1 ) USER COMMANDS AR( 1 ) BUGS If the same file is mentioned twice in an argument list, it is put in the archive twice. 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 super-user. Sun Release 2.0 Last change: 1 November 1983 17 AS ( 1 ) USER COMMANDS AS ( 1 ) NAME as — mc68000 assembler SYNOPSIS as [ — d2 ] [ -J ] [ -J ] [ -h ] | -L ] [ -R ] [ -o objfile ] file DESCRIPTION As translates assembly code in the named file 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. If the — o flag is omitted, file a. out is used. OPTIONS — d2 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 — J 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 pro- gram size and run time are not important. — h 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 program 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. — L 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. — J Use short (pc-relative) branches to resolve jump’s and jsr’s to externals. This is for com- pact programs which cannot use the -d2 flag because of large program relocation. — R Make initialized data segments read-only by concatenating them to the text segments. This eliminates the need to run editor scripts on assembly code to make initialized data read-only and shared. 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 BUGS Should assemble standard input with no arguments. The Pascal compiler (pc(l)) qualifies a nested procedure name by chaining the names of the enclosing procedures. This sometimes results in names long enough to abort the assembler, which currently limits identifiers to 512 characters. 18 Last change: 7 November 1984 Sun Release 2.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 s/>(l) or csA(l) 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 context.) 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 recognizably truncated. At programs are executed by periodic execution of the command /usr/lib/atrun from cron{ 8). The granularity of at depends upon how often atrun is executed. Standard output or error output is lost unless redirected. EXAMPLES Examples of legitimate commands are: at 8a jan 24 at 1530 fr week FILES /usr/lib/atrun executor (run by cron(8)). 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 /usr/lib/atrun, there may be bugs in scheduling things almost exactly 24 hours into the future. activity for year yy, day dd, hour hhhh. last hhhh activities in progress Sun Release 2.0 Last change: 1 November 1983 19 AWK(l) USER COMMANDS AWK(l) NAME awk — pattern scanning and processing language SYNOPSIS awk [ —f program_Jile ] [ — F c | [ program ] [ file . . . ] DESCRIPTION Awk scans each of its input files for lines that match any of a set of patterns specified in pro- gram. 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-file. 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 associated action is performed for each matched pattern. OPTIONS — f program_file Use the contents of programme 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 available 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 20 Last change: 1 February 1985 Sun Release 2.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 print f statement formats its expression list according to the format template (see printf[ 3S) 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. substrfs, m, n) returns the n-character substring of s that begins at position m. The sprintffformat, expr, expr, ...) function formats the expressions according to the printf( 3S) format given by format and returns the resulting string. Patterns Patterns are arbitrary Boolean combinations (!, II, &&, and parentheses) of regular expressions and relational expressions. Regular expressions must be surrounded by slashes and are as in egrep. Isolated regular 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 per- formed 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 combination 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 — F c 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 format 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 += $1 } END { print "sum is", s, " average is", s/NR } Print fields in reverse order: Sun Release 2.0 Last change: 1 February 1985 21 AWK(l) USER COMMANDS AWK(l) { for (i = NF; i > 0; — i) print $i } 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 lex(l), sed(l) Pattern Scanning and Processing with Awk in the Sun Editing and Text Processing Manual. 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 U!” 22 Last change: 1 February 1985 Sun Release 2.0 BASENAME(l) USER COMMANDS BASENAME(l) NAME basename — strip filename affixes SYNOPSIS basename string [ suffix ] DESCRIPTION Basename deletes any prefix ending in ‘/’ 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 /usr/src/cmd/cat.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 2.0 Last change: 2 June 1983 23 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 arithmetic. 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 + — * / % ‘ {% is remainder; ' is power) +-f — (prefix and postfix; apply to names) == <= >=!=<> = += -= *= /= %= * = 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 24 Last change: 1 April 1981 Sun Release 2.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 assign- ment. 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(l). Assign- ments 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) return(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 rfc(l), 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(l) desk calculator proper SEE ALSO dc(l) L. L. Cherry and R. Morris, BC — An arbitrary precision desk-calculator language BUGS No &&, 1 1, or ! operators. For statement must have all three E’s. Quit is interpreted when read, not when executed. Sun Release 2.0 Last change: 1 April 1981 25 BIFF ( 1 ) 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 session. The command: biff y 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 »A(1) or the mail variable of csA(l). SEE ALSO csh(l), sh(l), mail(l) 26 Last change: 6 March 1984 Sun Release 2.0 BINMAIL ( 1 ) USER COMMANDS BINMAIL ( 1 ) NAME /bin/mail — send or receive mail among users SYNOPSIS /bin/mail [ — I ] [ — p ] [ — q | [ — f filename [ /folm/ small [ — d ] [ — i J [ — r name ] person ... 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 /usr/ucb. /bin/mail with no argument prints a user’s mail, message-by-message in last-in, first-out order. /bin/ mail accepts commands from the standard input to direct disposition messages. When persons 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 lojtn(l). If there is any pending mail, login( 1) tells you there is mail when you log in. It is also possible to have the C-Shell, see csA(l) or the comsat daemon biff(l) tell you about mail that arrives while you are logged in. OPTIONS Printing Mail — i continue after interrupts — an interrupt normally terminates the /bin /mail command and leaves the mail file unchanged. — 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 programs 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. Sun Release 2.0 Last change: 3 January 1984 27 BINMAIL ( 1 ) USER COMMANDS BINMAIL ( 1 ) m [ person j ... mail the message to the named persons (yourself is default), n go on to next message, p print message (again), q same as EOT. b [ file ] ... save the message in the named files (‘mbox’ default), w [ file ] ... save the message, without a header, in the named files (‘mbox’ default). Delete the mes- sage 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 persons /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 SEE ALSO biff(l), write(l), uucp(lC), uux(lC), xsend(l), sendmail(8) BUGS Race conditions sometimes result in a failure to remove a lock file. Any superuser can read your mail, unless it is sent by X8enflle3 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 '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 T. Non- ASCII characters (with the high bit set) are displayed as M- (for meta) followed by tire character of the low 7 bits. — e displays non-printing characters, as — y, 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 ‘'I’. 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 2.0 Last change: 2 June 1983 31 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 indentation that displays the structure of the program. SEE ALSO indent(l) indent(l) is preferred. 32 Last change: 1 February 1985 Sun Release 2.0 CC(1) USER COMMANDS CC(1) NAME cc — C compiler SYNOPSIS cc [ -c 1 [ -g ] [ -O output ] [ -O ] [ -a ] [ -A.asmfl.ags ] [ -B string ] [ -C ] [ -D name ] | -D name=def\ [ — E ] [ -fslngle ] [ -fsky ] [ -go ] | -I dir | [ -p ] | -pg 1 [ -R ] i -S ] [ — t J p|0jl|2 ] ] [ -U name ] [ -v ] [ -w ] filename ... DESCRIPTION Cc is the UNIX C compiler which translates programs written in the C programming language into executable 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 directory, 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 .8 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 compilations 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 name option. If a single C program is compiled and loaded all at once, the intermediate .o file is deleted. OPTIONS The following options are interpreted by cc. See /rf(l) for load-time options. — c Compile only — suppress the loading phase of the compilation, and force an object file to be produced even if only one program is compiled. — g Produce additional symbol table information for rf6x(l) and pass the — lg flag to ld( 1). — o output Name the final output file output. If this option is used, the file a. out is left undis- turbed. — O / Use the object code optimizer to improve the generated code. —a Insert code into the program to count how many times each basic block in the program is executed. After the program is compiled with this option, there will be a .d file for every .c file. The .d file accumulates execution data for the corresponding source file. The /dev/mtO To duplicate the olddir directory hierarchy in the newdir directory: % cd olddir % find . —print { cpio — pdl newdir Some forms of cpio tapes from other sites have the bytes swapped in the file. The a 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: % dd lt=whatever the file is conv=swab j cpio —is Sun Release 2.0 Last change: 1 November 1983 55 CPIO(l) USER COMMANDS CPIO(l) SEE ALSO ar(l), find(l), cpio(5) 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 special files. 56 Last change: 1 November 1983 Sun Release 2.0 CPP(l) USER COMMANDS CPP(l) /4 AM E cpp - the C language preprocessor SYNOPSIS /lib/cpp [ — P -C -Uname -D name —Dname=def —ldir ] [ 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 fT7 (1) or pc (1)). 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 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: operating system: ibm, geos, os, tss, unix hardware: interdata, pdpl 1, u370, u3b, vax, mc68000 UNIX System variant: RES, RT, sun -D name Define name as 1 (one). This is the same as if a -Dname=l option had appeared on the cpp com- mand line, or as if a #define name 1 line had appeared in the source file that cpp is processing. — D name=def Define name as if by a #define directive. This is the same as if a #define name def line had appeared in the source file that cpp is processing. -I dir 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 aigument 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" Sun Release 2.0 Last change: 5 March 1985 1 CPP(l) USER COMMANDS CPP(l) #include 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. #line 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 file name is unchanged. #endif commentary Ends a section of lines begun by a test directive (#if, #ifdef, or #iftadef). Each test directive must have a matching #endif. The commentary 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 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 #define 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 commentary 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 commentary 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) ( lusr/include 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 FTLE_ _ is defined as the current file name (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. Sun Release 2.0 Last change: 5 March 1985 2 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 foo(a) ’\a’ foo(bar) is the seven characters ’\bar’ {space, single-quote, escape character, b, a, r, single-quote). Macro names are not recognized inside character constants or quoted strings during the regular scan. Thus: #define foo bar printf("foo"); does not expand ‘foo’ 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 foo bletch #define bar foo #undef foo bar produces ‘foo’. 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 the input file, with modifications, plus lines of the form: Mlineno "filename " -indicat- ing the original source line number and filename of the following output line. FILES lusrlinclude 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 2.0 Last change: 5 March 1985 3 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 ‘\’. A newline preceded by a ‘\’ is equivalent to a blank. In addition strings enclosed in matched pairs of quotations, l '\ l " or form parts of a word; metacharacters 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 ‘\ 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 ‘\’ and in quotations using ’, 1 ' ’, and Commands A simple command is a sequence of words, the first of which specifies the command to be exe- cuted. A simple command or a sequence of simple commands separated by ‘j’ (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 executed without immediately waiting for it to terminate by follow- ing 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 ‘j j’ or *&&’ indicating, as in the C language, that the second is to be executed only if the first fails or succeeds respectively. (See Expressions). 58 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) 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 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 ‘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 *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 *Y which does not generate a STOP signal until a pro- gram 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 normally 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 out- put 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 ‘%1’ is a synonym for ‘fg %1\ 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’ nor- mally restarts a suspended ex(l) 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 *+’ 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 when- ever 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 immedi- ately 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. Sun Release 2.0 Last change: 26 March 1985 59 CSH(l) USER COMMANDS CSH(l) 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 T may be preceded by an ‘\’ 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. 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 ex write.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 T in the prompt string. With the current event 13 we can refer to previous events by event number ‘111’, relatively as in ‘! — 2’ (referring to the same event), by a prefix of a command word as in ‘!d’ for event 12 or ‘!wri’ for event 9, or by a string contained in a word in the command as in ‘!?mic?’ also referring to event 9. These forms, without further modification, simply reintroduce the words of the specified events, each separated by a single blank. As a special case '!!’ refers to the previous command; thus “!!’ 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) ?s? search x — y range of words — y abbreviates ‘0— y' * abbreviates ,A — $’, 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 argu- ment selector begins with a ,A ’, '$’, V ’ or After the optional word designator can be placed a sequence of modifiers, each preceded by a 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. GO Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) s///r / Substitute r for l 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 sub- stitutions, 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 '/’; a ‘\’ quotes the delim- iter into the l and r strings. The character in the right hand side is replaced by the text from the left. A ‘\’ quotes also. A null / uses the previous string either from a l or from a contex- tual scan string s in ‘!?s?’. The trailing delimiter in the substitution may be omitted if a newline follows immediately as may the trailing ‘V in a contextual scan. A history reference may be given without an event specification, for example, “!$’. In this case the reference 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? A !$’ 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 ‘ A ’. This is equivalent to ‘!:s A ’ providing a convenient shorthand for substitutions on the text of the previous 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 substi- tutions. 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 Command Substitition below) does a quoted string yield parts of more than one word; ,A ’ quoted strings never do. Alias substitution The shell maintains a list of aliases which can be established, displayed and modified by the alias and unaliaa 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 history 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 pro- cess 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 \!* j lpr ' ’ to make a command which pr’s its arguments to the line printer. Sun Release 2.0 Last change: 26 March 1985 61 CSH(l) USER COMMANDS CSH(l) 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 performed and the result assigned to a variable. Variable values are, however, always represented as (zero or more) strings. For the purposes 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 substi- tution is performed keyed by characters. This expansion can be prevented by preceding the '$’ with a ‘\’ except within *"’s where it always occurs, and within "’s where it never occurs. Strings quoted by *' ’ are interpreted later (see Command substitution below) so *$’ substitution does not occur there until later, if at all. 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 command name, and the rest of which become arguments. Unless enclosed in or given the ‘:q’ modifier the results of variable substitution may eventually be command 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 sub- jected 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 ‘1’. If the last member of a range is omitted it defaults to ‘$#name’. The selector V selects all words. It is not an error for a range to be empty if the second argument is omitted or in range. 62 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) $#name ${#name} Gives the number of words in the variable. This is useful for later use in a $0 Substitutes the name of the file from which command input is being read, if the name is not known. Snumber ${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 the braces. The current implementation allows only one V 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 T if the current input filename is known, ‘0’ if it is not. $$ 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 output from such a com- mand 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 V, *?’, ‘[’ 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 specifying 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 meta- characters V, T and ‘[’ imply pattern matching, the characters and ‘{’ being more akin to abbreviations. ‘[selector]’. An error occurs Sun Release 2.0 Last change: 26 March 1985 63 CSH(l) USER COMMANDS CSH(l) In matching filenames, the character ‘.’ at the beginning of a filename or immediately following a ‘/’, as well as the character ‘/’ must be matched explicitly. The character V 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 ‘[...]’ F 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 ‘/usr/ken’ and ‘~ken/chmach’ to ‘/usr/ken/chmach’. If the character is followed by a character other than a letter or '/' 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 con- struct may be nested. Thus ‘~source/sl/{oldls,ls}.c’ expands to ‘/usr/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 spe- cial 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. « word Read the shell input up to a line which is identical to word. Word is not subjected to vari- able, filename or command substitution, and each input line is compared to word before any substitutions are done on this input line. Unless a quoting ‘\’, ‘'’or ’ appears in word variable and command substitution is performed on the intervening lines, allowing *\’ to quote “$’, ‘\’ and ’. Commands which are substituted have all blanks, tabs, and newlines preserved, except for the final newline 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 des- truction of files. In this case the “!’ forms can be used and suppress this check. The forms involving *&’ route the diagnostic output into the specified file as well as the standard output. Name is expanded in the same way as “<’ input filenames are. » name »& name »! name »&! name Uses file name as standard output like *>’ but places output at the end of the file. If the 64 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) variable noclobber is set, it is an error for the file not to exist unless one of the "!’ forms is given. Otherwise similar to 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 com- ponents 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 ‘j’. 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: jj && j *&==!= =~ !" <=>=.<>«» + -*/%! ~ ( ) Here the precedence increases to the right, '==’ *!=’ ‘=~’ and T’, ‘<=’ ‘>=’ “<’ and ‘>’, “«’ and ‘»’, *+’ and ‘ — ’, V ‘/’ and '%’ being, in groups, at the same level. The ‘==’ '!=’ ‘=~’ and 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, Vs, ‘?’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. Strings which begin with ‘0’ are considered octal numbers. Null or missing arguments are con- sidered ‘O’. The result of all 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 ('&’ ’, or ‘J’ then at least this part of the expression 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 assignment operator is optional. Spaces are, however, mandatory in separating com- ponents 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-deflned 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. 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 vari- ables 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. 72 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) &FgV cdpath cwd echo histchars history home ignoreeof mail noclobber noglob nonomatch notify path Set to the arguments to the shell. Positional parameters are substituted from this variable: ‘$1’ is replaced by ‘$argv[l]’, etc. Gives a list of alternate directories searched to find subdirectories in chdir com- mands. The full pathname of the current directory. Set when the — x command line option is given. Echoes each command and its arguments 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. Can be given a string value to change the characters used in history substitu- tion. The first character of its value is used as the history substitution charac- ter, replacing the default character !. The second character of its value replaces the character f in quick substitutions. Can be given a numeric value to control the size of the history list. Any com- mand 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 command 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 com- pletion 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 expansions 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 pat- tern 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. Each word of the path variable specifies a directory in which commands are to be 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 ‘/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 normally hash the contents of the directories in the path variable after reading .cshrc, and each time the path Sun Release 2.0 Last change: 26 March 1985 73 CSH(l) USER COMMANDS CSH(l) prompt savehist shell status time 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. If a '!’ appears in the 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 ‘1’, 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 running 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. To print a percent sign, use two percent signs in a row. 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. 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 888.8 s ee:ee pp% xxx+dddk iii+ooo io mmmpf+www 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), xxx is the average shared memory in Kilobytes (X), ddd is the average unshared data space in Kilobytes (D), Hi and ooo are the number of block input and output operations respectively (I and O), mmm is the number of page faults (F), and ww 74 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) 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 exe- cute 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 com- mand location when a large number of directories are present in the search path. If this mechan- ism 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 '/’, 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 directory; 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 invokers 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 termi- nals. — n Commands are parsed, but not executed. This may aid in syntactic checking of shell scripts. —8 Command input is taken from the standard input. — t A single line of input is read and executed. A ‘\’ 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. — 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. Sun Release 2.0 Last change: 26 March 1985 75 CSH(l) USER COMMANDS CSH(l) After processing of flag arguments if arguments remain but none of the — c, —8, — 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 sys- tems 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 ‘standard’ 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 & commands) are immune to signals generated from the keyboard, including hangups. Other sig- nals 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 ter- minate 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’. 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’. LIMITATIONS Words can be no longer than 1024 characters. The system limits argument lists to 10240 charac- ters. 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 sub- stitute no more characters than are allowed in an argument list. To detect looping, the shell res- tricts the number of alias substititutions on a single 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 Works- tation 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 internally. 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; perhaps this will inspire someone to work on a good virtual terminal interface. In a virtual terminal interface much more interest- ing things could be done with output control. Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be provided rather than aliases. Commands within loops, prompted for by “?’, are not placed in the history list. Control structure should be parsed rather than being recognized as built-in commands. This would allow control commands to be placed anywhere, to be combined with ‘J’, and to be used with and *;’ metasyntax. FILES "/.cshrc "/.login "/.logout "/.history /bin/sh /tmp/sh* /etc/passwd 76 Last change: 26 March 1985 Sun Release 2.0 CSH(l) USER COMMANDS CSH(l) It should be possible to use the modifiers on the output of command substitutions. There are two problems with modifier usage on “$’ substitutions: not all of the *:’ modifiers are available; only one modifier per command substitution is allowed. Quoting conventions are contradictory and confusing. Symbolic links fool the shell. In particular, dirs and ‘cd ..’ don’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 Spath) 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 2.0 Last change: 26 March 1985 77 CTAGS ( 1 ) USER COMMANDS CTAGS ( 1 ) NAME ctags — create a tags file SYNOPSIS ctags [ — BFatuwvx ] file . . . DESCRIPTION Ctags makes a tags file for ez(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(I), vi(l) BUGS Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very simpleminded way. No attempt is made to deal with block structure; if you have two Pas- cal procedures in different 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 usually faster to simply rebuild the tags file. output tags file 78 Last change: 6 March 1984 Sun Release 2.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 2.0 Last change: 16 July 1983 79 DBX(l) USER COMMANDS DBX(l) NAME dbx - debugger SYNOPSIS dbx [ — r ] [ — 1 ] [ — I dir ] [ objfile [ corefile ]j DESCRIPTION Dbx is a tool for source-level debugging and execution of programs. It accepts the same com- mands as dbxtool (1), but provides a user interface which does not use the window system. Objfile is an object file produced by cc(l), /77( 1) and pc(l) (or a combination of them) with the appropriate flag (— g) specified to produce symbol information in the object file. IMPORTANT: every stage of the compilation process, including the Id phase, must include the — g option. If no objfile is specified, one uses 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 Execute objfile immediately. Parameters follow the object file name (redirection is han- dled properly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for user response. Dbx reads from /dev/ tty when — r is specified and standard input is not a terminal. — S Force dbx to act as though standard input is a terminal. —I dir Add dir to the list of directories that are searched when looking for a source file. Nor- mally 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. DBX AND DBXTOOL COMMON USER INTERFACE The following material concerning the user interface applies to both dbx and dbxtool. Note that commands, toolenv, button, and unbutton affect only dbxtool ; they are described in the dbxtool (1) manual entry. The commands described below are divided into the following categories: Execution and Tracing Run the program being debugged, trace its execution, and stop at selected places. Displaying and Naming Data Display data and locate variables in the debugged program. Accessing Source Files Provide operations (such as editing) on the actual source text of the program. Machine Level Commands Provide access to memory locations and machine registers. Miscellaneous Miscellaneous commands such as help, and call a shell. The most useful basic commands to know about are run to run the program being debugged, where to obtain a stack trace with line numbers, print for displaying variables, and stop for setting breakpoints. 80 Last change: 1 February 1985 Sun Release 2.0 DBX(l) USER COMMANDS DBX(l) File Names File names within dbx may include shell metacharacters. The shell used for pattern matching is determined by the SHELL environment variable. Expressions Dbx Expressions are combinations of variables, constants, procedure calls, and operators. Hexa- decimal constants must be preceded by a ‘Ox’ and octal constants by a ‘O’. Character constants must be enclosed in single quotes. Expressions cannot involve strings, structures, or arrays, although elements of structures or arrays may be used. Dbx recognizes these operators: + - * / div % add, subtract, multiply, divide, integer divide and remainder <<>>&!" left shift, right shift, bitwise and, bitwise or, and bitwise complement & * address of operator and contents of operator <><=>= == != ! less than, greater than, less than or equal, greater than or equal, equal to, not equal to, and not && !| logical and, and logical or sizeof (cast) sizeof variable or type, and type cast The field reference operator (‘.’) can be used with pointers to records, as well as records, making the C operator ‘— >’ unnecessary (although it is supported). Precedence and associativity of operators are the same as in C. Parentheses can be used for grouping. Of course, if the program being debugged is not active and there is no core file, one may only use expressions containing constants. Procedure calls require an active child process. Dbx and FORTRAN Note the following when using dbx with FORTRAN programs: 1. Array elements must be referenced with square brackets '[’ and *]’ rather than parentheses, e.g., print whatsit [3] instead of print whatsit(3). 2. The main routine is referenced as MAIN (as distinguished from ‘main’). All other names in the source file which have upper case letters in them will be lower case in dbx, unless the — U option of f77 is used to compile the program. 3. When referring to the value of a logical type in an expression, use the value 0 or 1 rather than false or true, respectively. Dbx Scope Rules Dbx has two external variables which it uses to resolve scope conflicts. These are called ‘file’ and ‘func’ — see Section 3 below, Accessing Source Files. The values of ‘file’ and ‘func’ change automatically as files and routines are entered and exited during execution of the user program. ‘File’ and ‘func’ can also be changed by the user. Changing ‘func’ also changes the value of ‘file’; however, changing ‘file’ does not change ‘func’. Sun Release 2.0 Last change: 1 February 1985 81 DBX(l) USER COMMANDS DBX(l) ‘Func’ is used for name resolution, as in the command: print grab where grab may be defined in two different routines. The search order is: 1. Search for ‘grab’ in the routine named by ‘func’, 2. If ‘grab’ doesn’t exist in the routine named by ‘func’, the file containing the routine named by ‘func’ is searched, 3. finally the next outer level — the whole program in the case of C and FORTRAN — is searched for ‘grab’. Clearly, if ‘grab’ is local to a different routine than the one named by ‘func’, or is a static vari- able in a different file than is the routine named by ‘func’, it won’t be found. Note, however, that print a.grab is allowed, as long as routine ‘a’ has been entered but not exited yet. Note that the file that routine ‘a’ is in might have to be specified when the file name (minus its suffix) is the same as a routine name. For example, if routine ‘a’ is found in module ‘a.c’, then print a.grab would be not enough — one would have to use print a.a.grab. If in doubt as to how to specify a name, use the whereis command, as in wherels grab to display the full qualifications of all instances of the specified name (grab in this case). ‘File’ is used to: 1. resolve conflicts when setting ‘func’ — for example, when a C program has two static rou- tines with the same name, 2. determine which file to use for commands which take only a source line number — for exam- ple, stop at 55, and: 3. determine which file to use for commands such as the ‘edit’ command which has optional arguments or no arguments at all. When dbx begins execution, the value of ‘file’ is the first source file in the compiler/load list and the value of ‘func’ is the module for this same file (that is, without the suffix ‘.c’, ‘.f’ or ‘.p’). This causes name resolution to take place on a global level, that is, names are resolved such that the most global element is found. After execution begins, however, ‘func’ always has a value corresponding to a routine name. Note that changing ‘func’ doesn’t affect the place where dbx continues execution when the pro- gram is restarted. 1. Execution and Tracing Commands When the process being debugged is executing, it may be interrupted by typing the interrupt character. The process is stopped and dbx becomes ready to accept commands. The process can be continued again with the cont command. run [orjs] (< filename] \> filename] Start executing objfile, passing args as command line arguments; < or > can be used to redirect input or output in the usual manner. Otherwise, all characters in args are passed through unchanged. If no arguments are specified, the argument list in the last previous run command (if any) is used. If objfile has been written since the last time the symbolic information was read in, dbx reads in the new information. cont | at source-line-number] [ number ] Continue execution from where it stopped, or, if the clause ‘at source-line-number ’ is given, from that line number. The number causes execution to continue as if that signal had occurred. Source-line-number is evaluated relative to the current ’file’ and must be within the current procedure/function. Execution cannot be continued if the process has ’finished’, i.e., called the standard procedure ’_exit’. Dbx captures control when the process attempts to exit, thereby letting the user examine the program state. trace [in procedure/ function] [if condition ] 82 Last change: 1 February 1985 Sun Release 2.0 DBX(l) USER COMMANDS DBX(l) trace source-line-number (if condition j trace procedure/ function (if condition ] trace expression at source-line-number [if condition] trace variable (in procedure/ function] [if condition] Display tracing information when the program is executed. A number is associated with the command and can be used to turn the tracing off (see the delete command). If no argument is specified, each source line is displayed before it is executed. Execution is substantially slower during this form of tracing. The clause ‘in procedure/ function' restricts tracing information to be displayed only while executing inside the given procedure or function. Note that the 'procedure/ function' traced must be visible in the scope in which the trace command is issued — see the 'func' com- mand. Condition is a Boolean expression and is evaluated prior to displaying the tracing informa- tion; the information is displayed only if condition is true. The first argument describes what is to be traced. The effects of different kinds of argu- ments are described below: Source Line Number Display the line immediately prior to executing it. Source line numbers in a file other than the current one must be preceded by the name of the file in quotes and a colon, for example, "mumble. p":17. Procedure or Function Name Every time the procedure or function is called, display information telling what routine called it, from what source line it was called, and what parameters were passed to it. In addition, its return is noted, and if it is a function, the return value is also displayed. Expression If the argument is an expression with an at clause, the value of the expression is displayed whenever the identified source line is reached. Variable The name and value of the variable are displayed whenever the value changes. Execution is substantially slower during this form of tracing. Tracing is turned off whenever the block in which it was turned on is exited. For instance, if the program is stopped inside some procedure and tracing is invoked, the tracing will end when the procedure is exited. To trace the whole program, tracing must be invoked before a run command is issued. stop at source-line-number (If condition ] atop In procedure/ function (if condition] stop variable [if condition] stop if condition Stop execution when the given line is reached, procedure or function is called, variable is changed, or condition becomes true. Execution slows considerably when conditional stops are used, and is very slow when checking for a change in a variable. when in procedure/ function { command ; ...} when at source-line-number { command ; ...} when condition { command ; ...} Execute the given dbx commands when the procedure or function is called, line number is reached, or condition is true. The braces and the semicolon separating the commands are required. status [> filename] Display the currently active trace and stop commands. Sun Release 2.0 Last change: 1 February 1985 83 DBX(l) USER COMMANDS DBX(l) delete command-number [, ... command-number ) delete all Remove the traces and/or stops corresponding to the given numbers, or all of them. The status command displays the numbers associated with traces and stops. clear source-line-number Clears ALL breakpoints at the given source line number. catch number [, ... number } Ignore number [, ... number ] Start ("catch") or stop ("ignore") trapping the signals with the given numbers before they are sent to the program being debugged. This is useful when a program being debugged handles signals such as interrupts. Initially all signals are trapped except SIGHUP, SIGCONT, SIGCHILD, SIGALRM, SIGKILL, SIGSTP, and SIGW1NCH. step [n] Execute through the next n source lines and stop on the (n+l)st such line. If n is not specified, it is taken to be one. Step into procedures and functions. next [n] Execute through the next n source lines and stop on the (n+l)st such line. If n is not specified, it is taken to be one. Count procedure and function calls as single statements. When using conditions with the trace and stop commands, remember that variable names are resolved with respect to the current scope not the scope of the trace or stop command. For example, if you are currently stopped in function foo and you issue the command stop in bar If x == 5, the variable x refers to x in function foo not in function bar. The func command can be used to changed the scope before issuing a trace or stop command. 2. Naming, Printing and Displaying Data print expression [, expression ...] Print the values of the expressions. Expressions may involve function calls. If execution encounters any breakpoints, execution halts and the dbx command level is re-entered. A stack trace with the where command shows that the call originated from the dbx com- mand level. Variables having the same identifier as one in the current block may be referenced as 'block-name. variable', where block-name is a unique identifier for a block. For example, to access variable ‘c’ inside routine ‘a’ which is declared inside module ‘a.c’, one would have to use print a.a.c to make the name ‘a’ unambiguous. Use whereis to determine the fully qualified name of an identifier. display [ expression |, expression ...]] Display the values of the expressions each time execution of the program being debugged stops. In dbxtool, the expressions and their values appear in the display window. The name qualification rules for print apply to display as well. With no arguments, the display command prints a list of the expressions currently being displayed. undisplay expression [, expression ...] Stop displaying the expressions and their values each time execution of the program being debugged stops. The name qualification rules for print apply to undisplay as well. whatls identifier whatis type Print the declaration of the given identifier or type. The identifier may be qualified with block names as above. Types are useful to print all the members of a structure, union, or enumerated type. which identifier 84 Last change: 1 February 1985 Sun Release 2.0 DBX(l) USER COMMANDS DBX(l) Print the fully qualified form of the given identifier, that is, the outer blocks that the identifier is associated with. wherein identifier Print the fully qualified form of all the symbols whose names match the given identifier. The order in which the symbols are displayed is not meaningful. assign variable = expression set variable = expression Assign the value of the expression to the variable. Currently no type conversion takes place if operands are of different types. call procedure(parameters) Execute the object code associated with the named procedure or function. If execution encounters any breakpoints, execution halts and the dbx command level is re-entered. A stack trace with the where command shows that the call originated from the dbx com- mand level. If the source file that the routine is defined in was compiled with the -g flag, the number and types of parameters must match. However, if C routines are called which are not compiled with the -g flag, dbx will not do parameter checking; the parameters are simply pushed onto the stack as given in the parameter list. Currently, string and structure parameters are not passed properly for C and parameters greater than four bytes in length (for example, complex and double precision variables) and alternate return points are not passed properly for FORTRAN. where [n| Display a list of the top n active procedures and functions on the stack. If n is not specified, it displays all active procedures and functions. dump [func] Display the names and values of all the local variables and parameters in func. If func is not specified the current function is used. up [n] Move up (towards "main") the call stack n levels. If n is not specified, the default is one. This command allows you to examine the local variables in functions other than the current one. In dbxtool, the line containing the call is hilighted for one second. down [ n ] Move down (towards the current stopping point) the call stack n levels. If n is not specified, the default is one. In dbxtool, the line containing the call is hilighted for one second. 3. Accessing Source Files & Directories edit [ filename ] edit procedure/ function-name Invoke an editor on filename or the current source file if none is specified. If a procedure or function name is specified, the editor is invoked on the file that contains it. Which editor is invoked by default depends on the installation. The default can be overridden by setting the environment variable EDITOR to the name of the desired editor. file [ filename \ Change the current source file to filename. Print the name of the current source file if no filename is specified. func [procedure/ function/ program name ] Change the current function. Print the current function if none is specified. Changing the current function implicitly changes the current source file variable file to the one that contains the function; it also changes the current scope used for name resolution. If Sun Release 2.0 Last change: 1 February 1985 85 DBX(l) USER COMMANDS DBX(l) the entire scope of the program is desired, the argument should be the object file name. list [ source-line-number [, source-line-number]] list procedure/ function List the lines in the current source file from the first line number through the second. If no lines are specified, the next 10 lines are listed. If the name of a procedure or function is given lines n — 5 to n+5 are listed where n is the first statement in the procedure or function. If the list command’s argument is a procedure or function, the scope for further listing is changed to that routine — use the file command to change it back. uee [ directory-list ] Set the list of directories to be searched when looking for source files. Print the current list of directories if no directory-list is given. ed [ dirname ] Change dbx's notion of the current directory to dirname. With no argument, use the value of the HOME environment variable. pwd Print dbx’s notion of the current directory. / string | / ] Search down the current file for the regular expression string. The search begins with the line immediately after the current line and, if necessary, continues until the end of the file. The matching line becomes the current line. In dbxtool, the matching line is hilighted for one second. Tsfrin^l?] Search up the current file for the regular expression string. The search begins with the line immediately before the current line and, if necessary, continues until the top of the file. The matching line becomes the current line. In dbxtool, the matching line is hilighted for one second. When dbx is searching for a source file, the value of ‘file’ and the ‘use’ directory search path is used. The value of ‘file’ is appended to each directory in the ‘use’ search path until a file is found. This file becomes the current file. Dbx knows the same file names that are given to the compilers. For instance, if a file is compiled with the command % cc -c -g ../mip/scan.c then dbx knows of the file ../mip/Bcan.c, but it does not know of the file scan.c. 4 , Machine-Level Commands trace! [address] [if cond\ trace! j variable ] [at address] [If cond] stop! [ variable ] [if cond] stop! [at] [address] [if cond] Turn on tracing or set a breakpoint at a machine instruction address. step! next! Single step as in step or next, but do a single machine instruction rather than a source line. address , address/ [mode] [address] / [count] [mode] Display the contents of memory starting at the first address and continuing up to the second address or until count items have been displayed. If no address is specified, the address following the one displayed most recently is used. The mode specifies how memory is to be displayed; if it is omitted the last previously specified mode is used. The initial mode is ‘X’. The following modes are supported: 86 Last change: 1 February 1985 Sun Release 2.0 USER COMMANDS DBX(l) DBX(l) I display the machine instruction d display a word in decimal D display a longword in decimal q display a word in octal O display a longword in octal x display a word in hexadecimal X display a longword in hexadecimal b display a byte in octal c display a byte as a character s display a string of characters terminated by a null byte f display a single precision real number g display a double precision real number Symbolic addresses used in this context are specified by preceding a name with an Registers are denoted by ‘$d0-$d7’ (data registers), ‘$a0-$a7’ (address registers), ‘$fp’ (frame pointer), ‘$sp’ (stack pointer), and ‘$pc’ (program counter). Note that $fp is equivalent to register a6 and $sp is equivalent to register a7. For example, to print the contents of all registers in hex, one would type “&$d0/20X” or “&$dO,&$a7/X”. To print the contents of register dO, one could also type “print $d0” (one cannot currently specify a range with print). Addresses may be expressions made up of other addresses and the operators '+’, ‘ — ’, V, and indirection (unary V). 5. Miscellaneous Commands sh command-line Pass the command line to the shell for execution. The SHELL environment variable determines which shell is used. alias new-command-name character-sequence Respond to new-command-name as though it were character-sequence. Special charac- ters occurring in character-sequence must be enclosed in quotation marks. Alias substi- tution ala the C shell (csh( 1)) also occurs. help [ command } help Print a short message explaining command. If no argument is given, display a synopsis of dbx commands. source Read dbx commands from the given filename. This is especially useful when the filename has been created by redirecting a status command from an earlier debugging session. quit Exit dbx. dbxenv stringlen num dbxenv Set dbx attributes. The only one currently supported is stringlen which controls the maximum number of characters printed for a “char *” variable in a C program. The dbxenv command with no argument prints the attributes and their current values. debug ( objfile [corefile]] Terminate debugging of the current program (if any) and begin debugging the one found in objfile, without incurring the overhead of reinitializing dbx. If no arguments are specified, the name of the program currently being debugged and its arguments is printed. kill Terminate debugging of the current program, but leave dbx ready to debug another. This is particularly useful to eliminate remains of a window program one was debugging without exiting the debugger or to allow the object file to be removed and remade without incurring a "text file busy" error message. Sun Release 2.0 Last change: 1 February 1985 87 DBX(l) USER COMMANDS DBX(l) Debugging Processes that Fork Debugging a process that fork(2)s introduces unique problems. Dbx uses the ptrace( 2) interface to fetch from and store into the debuggee. This interface requires that the debugger be the parent process of the debuggee. If the debuggee forks, the child of the fork is the grandchild of dbx and it cannot be debugged. No breakpoints should be set in the code that is executed by the child of the fork. If the child of the fork trips over a breakpoint, it will die. When the debuggee forks, it can still be debugged with a few caveats. After the fork, there are two processes that are sharing the same text (code) space. The kernel does not allow ptrace to write into a text space that is being used by more than one process. This means the debuggee should not trip over any breakpoints while the child of the fork is still sharing its text space. In most cases, the child of the fork will ezec(2) a new program almost immediately. After the exec, it is safe for the debuggee to trip over breakpoints. Therefore, it is recommended that a sleep ( 2) of two or three seconds be placed in the debuggee immediately after the fork. This gives the child of the fork some time to exec a new program and get out of the way. FILES a.out core “/.dbxinit SEE ALSO cc(l) C compiler 177(1) FORTRAN compiler pc(l) Pascal compiler COMMENTS Dbx suffers from a ‘multiple include’ malady. If a program consists of a number of object files and each is built from source files that include header files, the symbolic information for the header files is replicated in each object file. Since roughly debugger start-up is done for each link, having the linker (Id) reorganize the symbol information won’t save much time, though it does reduce the disk space used. The problem is an artifact of the unrestricted semantics of #include’s in C; for example an include file can contain static declarations that are separate enti- ties for each file in which they are included. BUGS Dbx does not correctly handle C variables that are local to compound statements. When printing these variables it often gives incorrect results. 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 com- mand). The use command and -I option do not override the current directory if there is source by the same name in the current directory. Some operations behave differently in dbx than in C. • Dbx has two division operators — / always yields a floating point result and dlv always yields an integral result. a An array or function name does not imply the address of the array or function in dbx. An array name implies the entire array, and a function name implies a call to the func- tion with no arguments. The address of an array can be obtained by taking the address of the array’s first element, and the address of function can be obtained by taking the address of the function’s name. default object file default core file initial commands 88 Last change: 1 February 1985 Sun Release 2.0 DBX(l) USER COMMANDS DBX(l) Casts do not work with FORTRAN or Pascal. String and structure parameters are not passed properly for C and parameters greater than four bytes in length (for example, complex and double precision variables) and alternate return points are not passed properly for FORTRAN. Sun Release 2.0 Last change: 1 February 1985 89 DBXTOOL(l) USER COMMANDS DBXTOOL ( 1 ) NAME dbxtool — window- and mouse-based debugging tool SYNOPSIS dbxtool [ — i ] [ —I dir ] [ objfile [ corefile ] ] DESCRIPTION Dbxtool is a source-level debugger with a window and mouse-based user interface. It accepts the same commands as dbx (1), but provides a more convenient user interface. Using the mouse, one can 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 several other uses. It functions in the sunx —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 argument 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. 1 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. Sun Release 2.0 Last change: 2 June 1983 95 DC ( 1 ) USER COMMANDS DC ( 1 ) 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 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 imple- ments functions 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. 96 Last change: 2 June 1983 Sun Release 2.0 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 output are used by default. The input and output block size may be specified to take advantage of raw physical I/O. OPTION VALUES \T=name of = name ibs=n obs=n bs=n cbs=n input file is taken from name; standard input is default. output file is taken from name; standard output is default. Note that dd creates and explicit 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 lbs and obs; also, if no conver- sion is specified, it is particularly efficient since no copy need be done conversion buffer size Bkip=n flles=n s®ek=n 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 similar device). seek n records from beginning of output file before copying. This option gen- erally 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 pro- duct. 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. Sun Release 2.0 Last change: 1 February 1985 97 DD( 1 ) USER COMMANDS DD( 1 ) After completion, dd reports the number of whole and partial input and output blocks. EXAMPLE To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file x: tutorial% dd if=/dev/rmtO of=x Ibs=800 cbs=80 eonv=aacll, 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 ASCH/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 conventions. There is no universal solution. The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Inalid cobi- nations silently ignore all but the last mutually-exclusive keyword. 98 Last change: 1 February 1985 Sun Release 2.0 DELTA ( 1 ) USER COMMANDS DELTA ( 1 ) NAME delta — make a delta (change) to an SCCS file SYNOPSIS / usr /sees/ delta [ -r SID ] [ -a ] [ — n | [ -g list ] [ -m[mr/j'sf] ] [ -y[ comment] ] [ -p ] file • • • DESCRIPTION Delta permanently introduces into the named SCCS file changes that were made to the file retrieved by get(l) (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 com- ponent of the path name does not begin with b.) 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 processed. Delta may issue prompts on the standard output depending upon certain options specified and flags (see admin(\)) that may be present in the SCCS file (see — m and — y options below). OPTIONS Options apply independently 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 0 e<(l)). 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(l)), 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 ter- minal, 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 pro- gram (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, della terminates (it is assumed that the MR numbers were not all valid). — y j comment] Arbitrary text to describe the reason for making the delta. A null string is considered a valid comment. 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 Sun Release 2.0 Last change: 6 March 1984 99 DELTA ( 1 ) USER COMMANDS DELTA ( 1 ) comment text. — p Display (on the standard output) the SCCS file differences before and after the delta is applied in a dij f(l) format. FILES All files of the form f-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 gen- erates 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 Ae/p(l) for explanations. 100 Last change: 6 March 1984 Sun Release 2.0 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 con- structions, macro definitions, eqn constructs (between ‘.EQ’ and ‘.EN’ lines or between delim- iters), and table descriptions 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 apos- trophes, 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 .bo to source in the standard macro package files. Sun Release 2.0 Last change: 1 February 1985 101 DES ( 1 ) USER COMMANDS DES ( 1 ) NAME des — encrypt/decrypt with Data Encryption Standard SYNOPSIS des — e j — 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 (one byte 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 execut- ing ps(l) or a derivative. To minimize this possibility, des takes care to destroy the key argu- ment immediately upon entry. The des command attempts to use DES hardware for its job, but will use a software implementa- tion 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 1 /50th as fast. How- ever, 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 out- put 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 multi- ple 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. 102 Last change: 1 February 1985 Sun Release 2.0 DES ( 1 ) USER COMMANDS DES ( 1 ) FILES /dev/des? SEE ALSO des(4) RESTRICTIONS This program is not available on software shipped outside the U.S. Sun Release 2.0 Last change: 1 February 1985 103 DF( 1 ) USER COMMANDS DF(1) NAME df — report free disk space on file systems SYNOPSIS df [ — 1 ] [ filesystem ... ] | file ... ] 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 produces something like: % 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( 8). 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, / dev/ipOa ) or UNIX path names, df produces a report on the file system containing the named file. Thus “df shows the amount of space on the file system containing the current directory. OPTIONS —I Report the number of used and free inodes. FILES /etc/mtab list of currently mounted filesystems SEE ALSO du(l), mtab(5), icheck(8), quot(8), tunefs(8) 104 Last change: 28 February 1985 Sun Release 2.0 DIFF(l) USER COMMANDS DIFF(l) NAME did — differential file and directory comparator SYNOPSIS diff [ —cefh ] [ — b ] filel file2 diff [ — D string ] [ — b ] filel file2 diff j — 1 ) [ — p ] [ — s ] [ ] [ — S name ] [ —cefh ] [ — b ] dirl dir2 DESCRIPTION diff is a differential file comparator. When run on regular files, and when comparing text files which 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 cir- cumstances, diff finds a smallest sufficient set of file differences. If neither filel nor fileS is a directory, either may be given as in which case the standard input is used. If filel is a direc- tory, a file in that directory whose file-name is the same as the file-name of fileS is used (and vice versa). There are several options for output format; the default output format contains lines of these forms: nl a n8,nj nl,nS d nS nl,n2 c nS,nJ These lines resemble ed commands to convert filel into file2. The numbers after the letters per- tain to fileS. In fact, by exchanging ‘a’ for ‘d’ and reading backward one may ascertain equally how to convert fileS into filel. As in ed, identical pairs where nl = nS or nS = n\ are abbrevi- ated 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 ‘>’. If both arguments are directories, diff sorts the contents of the directories by name, and then runs the regular 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 Except for — b, which may be given with any of the others, the following options are mutually exclusive: — e produce a script of a, c and d commands for the editor ed, which will recreate fileS from filel. 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 out- put. (shift; cat $*; echo 'l,$p') | ed — $1 Extra commands are added to the output when comparing directories with — e, so that the result is a sA(l) script for converting text files which are common to the two direc- tories from their state in dirl to their state in dirS. — f produces a script similar to that of — e, not useful with ed, and in the opposite order. — 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: the output beginning with identification of the files involved and their creation dates and then each change is separated by a line with a dozen *’s. The lines removed from filel are marked with those added to fileS are marked ‘+’. Lines which are changed from one file to the other are marked in both files with ‘1’. — h does a fast, half-hearted job. It works only when changed stretches are short and well Sun Release 2.0 Last change: 24 August 1983 105 DIFF(l) USER COMMANDS DIFF(l) separated, but does work on files of unlimited length. Options for the second form of diff are as follows: — D string create a merged version of filel and fileS on the standard output, with C preprocessor controls included so that a compilation of the result without defining string is equivalent to compiling filel, while defining string will yield fileS. — b ignore trailing blanks (spaces and tabs); other strings of blanks compare equal. Options when comparing directories are: —1 long output format; each text file diff is piped through pr(l) to paginate it, other differences are remembered and summarized after all text file differences are reported. — r apply diff recursively to common subdirectories encountered. — b report files which are the same, which are otherwise not mentioned. — Sname starts a directory diff in the middle, beginning with file name. FILES /tmp/d ????? /usr/lib/diffh for — h /usr/bin/pr SEE ALSO cmp(l), cc(l), comm(l), ed(l), diff3(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 decides to run the diff algorithm if they are not equal. This may cause a small amount of spurious output if the files then turn out to be identical, because the only differences are insignificant blank string differences. 106 Last change: 24 August 1983 Sun Release 2.0 DIFF3( 1 ) USER COMMANDS BIFF3 ( 1 ) NAME difI3 — 3-way differential file comparison SYNOPSIS dlff3 [ — ex3 ] filel file2 file3 DESCRIPTION DiffS 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 fileS is different ==3 fileS 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 i nl a Text is to be appended after line number nl in file f, where /= 1, 2, or 3. f : nl , nS c Text is to be changed in the range line nl to line nS. 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, diffS publishes a script for the editor ed that will incorporate into filel all changes between fileS and fileS, 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 will defeat — e. Sun Release 2.0 Last change: 18 January 1983 107 DOMAINNAME ( 1 ) USER COMMANDS DOMAINNAME ( 1 ) NAME domainname - set or display name of current domain system SYNOPSIS domainname [ nameofdomain ] DESCRIPTION With no arguments, domainname displays the name of the current domain. The yellow pages use the domain to refer to a group of hosts. Only the super-user can set the domainname by giving an argument; this is usually done in the startup script / etc/ re. local. SEE ALSO getdomainname(2), setdomainname(2), ypinit(8) 108 Last change: 1 February 1985 Sun Release 2.0 DU( 1 ) USER COMMANDS BU( 1 ) NAME du — summarize disk usage SYNOPSIS du [ — a ] [ —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 direc- tory, 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 ,/tech.papers/lpr.document 217 ./tech. papers/new. manager 401 ./tech. papers 144 ./memos 80 ./letters 388 ./window 93 ./messages 15 ./useful. news 1211 . % SEE ALSO df(l), quot(8) BUGS Non-directories given as arguments (not under —a option) are not listed. If there are too many distinct linked files, du counts the excess files multiply. Sun Release 2.0 Last change: 1 November 1983 109 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 terminated 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 (sA(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. 110 Last change: 26 April 1983 Sun Release 2.0 ED( 1 ) USER COMMANDS ED( 1 ) NAME ed — text editor SYNOPSIS ed [ — ] ( — x ] [ filename ] DESCRIPTION Ed is the basic text editor in the UNIX system. While ed is for all practical purposes superseded by vi, ed is still used by other system utilities such as SCCS. Ed is a line editor — in general, you must specify the line or lines on which to perform the operation you choose (see Line Addressing, below, for a discussion of how to form line-addresses for ed). You can tell ed to perform various operations on the lines. For instance, you can print (display) lines; you can change lines; you can insert new lines into the buffer; you can delete existing lines; you can move or copy lines to a different place in the buffer; you can substitute character strings within lines. See List of Opera- tions, below, for a guide. Also, see Regular Expressions for string-matching metacharacters. Ed does not directly change 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 this buffer. The copy must be ‘saved’ or ‘written’ — using the w (write) operation — 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 consists 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 example, 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) opera- tion. OPTIONS — Suppress the display of character counts normally given by the c, 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 per- formed 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. Sun Release 2.0 Last change: 13 March 1984 111 ED ( 1 ) USER COMMANDS ED(1) 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 sub- sequent 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 for- ward and backward searches (‘/’, “?’). Lines can be accessed (addressed, in ed terminology) in several ways, but the most easily under- stood 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 posi- tioned 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. turn 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 */’ searches forward from the current line and stops at the first line containing a string that matches the regular expression. If neces- sary, the search wraps around to the beginning of the buffer. ? regular 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 “+’ 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. ±addre$s An address beginning with *+’ or ’ is taken relative to the current line; in other words, ‘—5’ is understood to mean ‘.—5’. addres8± An address ending with '+’ or adds or subtracts 1. As a consequence of this rule and 112 Last change: 13 March 1984 Sun Release 2.0 ED ( 1 ) USER COMMANDS ED(1) the previous rule, the line-address ’ refers to the line before the current line. More- over, trailing '+’ and ’ characters have cumulative effect, so ‘ ’ refers to the current line less 2. To maintain compatibility with earlier versions of ed, the character ‘ A ’ 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-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 command 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 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: example% ed winelist [tell ed to edit a file called tvinelist) 42 (ed states there are 43 characters in the file ) Mp (in command mode — tell ed to print all lines) 1978 Chateau Chunder 1979 Redeye Canyon a 1980 Doomsday Special • P 1980 Doomsday Special (in command mode — tell ed to append text) (text input mode — add a new line) (period ends text input mode) (back in command mode — print last line entered) w 65 q example% (command mode — write the file) (ed displays the number of characters written) (command mode — quit the edit session) (back in the Shell) If you interrupt ed, it displays 7interrupted’ 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 iast 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. Sun Release 2.0 Last change: 13 March 1984 113 ED ( 1 ) USER COMMANDS ED( 1 ) 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 rorw 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 opera- tion says you really mean it. E filename Same as c, 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 ‘remem- bered 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 containing 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 expres- sion. 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/jimjams/\ 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 opera- tion 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. ! 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. kz Mark Line. Marks the addressed line with name x (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. 1 may be placed on the same line after any non-I/O operation. 114 Last change: 13 March 1984 Sun Release 2.0 ED ( 1 ) USER COMMANDS ED(1) 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, 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. 8 /regular expression / replacement string/ or, a/regular expression / replacement 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 regular expression are replaced in the line. Keep the g suffix of the s operation distinct from the g operation itself — they are completely different, a accepts two line-addresses to delimit the range of lines within which the substitutions should be done — default line-address is the current line. The current line is left at the last line sub- stituted. Special Characters: Any punctuation character may be used instead of ‘/’ to delimit the regular expres- sion 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 ‘\’. 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. ui 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. Sun Release 2.0 Last change: 13 March 1984 115 ED ( 1 ) USER COMMANDS ED( 1 ) 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. 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(l). 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 *!’ is sent to sft(l) to be interpreted as a shell command. The current line is unchanged. ad(fress 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 expression. 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 character, where a character is anything except a newline character. C any ordinary character except a special character matches itself. Special characters are the delimiters that actually surround the regular expression, plus \ (the escape charac- ter), [ (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 116 Last change: 13 March 1984 Sun Release 2.0 ED ( 1 ) USER COMMANDS £D(1) 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 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. [siring] 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. When two regular expressions are concatenated, they match the leftmost and then the longest possible 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 expression. Such a pattern is called a closure. For example: [a-i][a-e]* 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 sub- stitute 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 ‘\’. This also applies to the character bounding the regular expression (often */’) and to ‘\’ itself. FILES /tmp/e* ed.hup: work is saved here if telephone hangs up SEE ALSO Using the ed Line Editor in Editing and Text Processing on the Sun Workstation. crypt(l) encode and decode ex(l) extended line editor (part of vi) sed(l) stream editor vi(l) visual (display) editor 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 Sun Release 2.0 Last change: 13 March 1984 117 ED( 1 ) USER COMMANDS ED( 1 ) with ed. Use cal(l) to create an empty file. RESTRICTIONS Some size limitations: 512 characters per line, 256 characters per global command list, 64 charac- ters 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. 118 Last change: 13 March 1984 Sun Release 2.0 EQN(l) USER COMMANDS EQN(l) NAME eqn, neqn, checkeq — typeset mathematics SYNOPSIS eqn [ — dxy ] [ — pn ] [ — sn ] [ — f n ] [ 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 troff’s output. Neqn is a preprocessor for nroff{ 1) and is intended for use with terminals. Usage is almost always: tutorial% eqn file ... j troff tutorial% neqn file . . . j nr off 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 — d xy Set equation delimiters may be set to characters x and y with the command-line argu- ment. 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’ appear- ing 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 glo- bally in the body of the document by using the gslze directive. — tn 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 a^id^up. Thus x sub i makes x t , a sub i sup 2 produces a ( , and e sup {x sup 2 + y sup 2} gives e a Fractions are made with over: a over b yields — . sqrt makes square roots: 1 over sqrt {ax sup 2 -kbx+c} results in ^ ax^+bx + c The keywords from and to introduce lower and upper limits on arbitrary things: made with lim from {n— > inf } sum from 0 to n x sub i. n lim XJ*, «— *00 0 is Sun Release 2.0 Last change: 1 February 1985 119 EQN(l) USER COMMANDS EQN(l) Left and right brackets, braces, etc., of the right height are made with left and right: left [ x sup 2 + y sup 2 over alpha right ] '='1 produces 2 -i 2 JL X + a J 1 . The right clause is optional. Legal characters after left and right are braces, brackets, bars, c and f for ceiling and floor, and "" for nothing at all (useful for a right-side-only bracket). Vertical piles of things are made with pile, Iplle, cplle, and rplle: pile {o above b above c} pro- a duces b. There can be an arbitrary number of elements in a pile. Iplle left-justifies, pile and cplle center, with different vertical spacing, and rplle right justifies. Matrices are made with matrix: matrix { Icol { x sub i above y sub 2 } ccol { 1 above 2 } } pro- *, 1 duces . In addition, there is rcol for a right-justified column. »2 2 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 = u, and x vec ~=~ y dyad is t = ff. Sizes and font can be changed with sire n or size ±n, roman, Italic, bold, and font n. Size and fonts can be changed globally in a document by gslze n and gfont n, or by the command- line arguments —an and —in. Successive display arguments can be lined up. Place mark before the desired lineup point in the first equation; 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 (J]), int (f), inf ( oo), and shorthands like >= (>), — > (— ►), and != ( 5 *) are recognized. Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathemat- ical words like sin, cos, log are made Roman automatically. troff( 1) 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 troff when all else fails. SEE ALSO troff(l), tbl(l), ms(7), eqnchar(7) Typesetting Mathematics with ‘eqn’ and Formatting Documents with ‘nroff’ and ‘troff’ in Editing and Text Processing on the Sun Workstation . BUGS To embolden digits, parens, etc., it is necessary to quote them, as in ‘bold "12.3"’. 120 Last change: 1 February 1985 Sun Release 2.0 ERROR ( 1 ) USER COMMANDS ERROR ( 1 ) NAME error — analyze and disperse compiler error messages SYNOPSIS error [ — n ] [ — s ] [ — q ] [ — v | [ — t suffixlist ] [ —I ignore file ] [ name j 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 per- mits 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 standard output. Hence, both error sources should be piped together into error. For example, when using the csh syntax, tutorial% make — s lint J & error — q — v will analyze all the error messages produced by whatever programs make runs when making lint. Error knows about the error messages produced by: make, cc, cpp, ccom, as, Id, lint, pi, pc, and J77. For all languages except Pascal, error messages are restricted to one line. Some error mes- sages 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, /usr/lib/llib-lc and /usr/lib/llib-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 func- tions 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 stan- dard output when that file is touched. Sun Release 2.0 Last change: 13 March 1984 121 ERROR ( 1 ) USER COMMANDS ERROR ( 1 ) true errors 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 message 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 programs in free format languages, such as C or Pascal, it is possible to insert a comment into another comment, 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 standard 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 V wildcards work. Thus the suffix list: ".c.y.f*.h" allows error to touch files ending with ‘.c’, ‘.y’, ‘.f*’ and ‘.y’. —a 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 function names to ignore for lint error messages /dev/tty user’s teletype 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 ‘ J ’ 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 terminals, and has never been used on hardcopy terminals. 122 Last change: 13 March 1984 Sun Release 2.0 EX( 1 ) USER COMMANDS EX( 1 ) NAME ex, edit — text editor SYNOPSIS ex [ - ] [ -R j [ — r ] [ — t tag ] [ Acommand ] [ — v ] [ — x ] [ -w nnn ] [— 1 ] file ... edit [ ex options j DESCRIPTION Ex is the root of a family of editors which includes edit( 1), ex, and t/»(l). Display based editing is the focus of vi. Most users will in fact use vi as the principal interface to the system rather than ex. OPTIONS — supress all interactive feedback to the user — useful for processing ex scripts in shell files. — R edit the file in read-only state. — r recover the indicated files after a crash. — t tag edit the file containing the tag tag. A tags database must have been built previously using the ctags( 1) command. Acommand start the editing session by executing command. —v start up in display editing state using ui(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. — w nnn set the default window (number of lines on your terminal) to nnn — this is useful if you are dialling into the system over a slow ’phone line. —1 set up for editing LISP programs. DOCUMENTATION The document Edit: A tutorial provides a comprehensive introduction to edit assuming no previ- ous knowledge of computers or the UNIX system. The Ex Reference Manual — Version S.5 is a comprehensive and complete manual for the com- mand mode features of ex, but you cannot learn to use the editor by reading it. For an introduc- tion to more advanced forms of editing using the command mode of ex see the editing documents written by Brian Kernighan for the editor erf; the material in the introductory and advanced documents works also with ex. An Introduction to Display Editing with Vi introduces the display editor vi and provides reference material on vi. These documents can be found in the Editing and Text Processing Manual. In addition, the Vi Quick Reference card summarizes the commands of vi in a useful, functional way, and is useful with the Introduction. FILES /usr/lib/ex?.?strings /usr/lib/ex?.?recover /usr /lib/ex?. ?preserve /etc/termcap ~/.exrc /tmp/E xnnnnn /tmp/R xnnnnn /usr/preserve error messages recover command preserve command describes capabilities of terminals editor startup file editor temporary named buffer temporary preservation directory Sun Release 2.0 Last change: 24 October 1984 123 EX( 1 ) USER COMMANDS EX( 1 ) SEE ALSO 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 edi- tor. Null characters are discarded in input files, and cannot appear in resultant files. The editor checks the first five lines of the text file for commands of the form "ex: comm and” 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. 124 Last change: 24 October 1984 Sun Release 2.0 EXPAND ( 1 ) USER COMMANDS EXPAND ( 1 ) NAME expand, unexpand — expand tabs to spaces, and vice versa SYNOPSIS expand [ — tabstop ] [ — tabl,tab2,...,tabn ] [ file ... ] unexpand [ —a ] [ file . . . ] 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 calculations. 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 overridden 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,tab2,. . >,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. This option only applies to unexpand. Sun Release 2.0 Last change: 11 November 1983 125 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 toke'n of the expression is a separate argument. 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 precedence operators grouped. expr j 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 T’ 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 erf(l). 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 char- acters. 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 char- acters 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 string returns the length (that is, the number of characters) of string. ( expr ) parentheses for grouping. EXAMPLES 126 Last change: 26 March 1984 Sun Release 2.0 EXPR(l) USER COMMANDS EXPR(i) To add 1 to the Shell variable a: a=' expr $a + 1' To find the filename part (least significant part) of the pathname stored in variable a, which may or may not contain */’: expr $a : '.*/\(*\K \ $ 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 ‘O’, 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 ordi- nary 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 2.0 Last change: 26 March 1984 127 EYACC(l) USER COMMANDS EYACC(l) NAME eyacc — modified yacc allowing much improved error recovery SYNOPSIS eyacc [ — v ] | grammar ] DESCRIPTION Eyacc is an old version of yacc(l), which produces tables used by the Pascal system and its error recovery routines. 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. 128 Last change: 25 April 1983 Sun Release 2.0 F77 ( 1 ) USER COMMANDS F77 ( 1 ) NAME (77 - FORTRAN 77 compiler SYNOPSIS f7f | — c ] [ — g ] [ — o output ] [ — O ] [ — C ] [ — D name ] [ — Dname[=def\] | — fsky | [ — F ] [ —12 ] [ — Idir ] [ — m ] [ — N[qxsen] nnn ] [ — onetrip ] [ — p j [ — pg ] [ -Sj ] [ — S ] j — u ] [ — U ] [ —v ] [ — ■ w[ 6® ]] filename . . . DESCRIPTION J77 is the UNK FORTRAN 77 compiler, which translates programs written in the FORTRAN 77 programming language into executable load modules or into relocatable binary programs for sub- sequent loading via the ld( 1) linker. 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 .Fare also taken to be FORTRAN 77 source pro- grams, but they are preprocessed by the C preprocessor (equivalent to a cc — E command) before they are compiled by the f77 compiler. Filenames ending in .r are taken to be Ratfor source programs; these are first transformed by the ratfor(l) preprocessor, then compiled by f7 7. In the same way, filenames ending in .c or .s are taken to be C or assembly source programs and are compiled or assembled, producing .o files. OPTIONS The following options have the same meaning as for cc(l). See Irf(l) for load-time options. — c Suppress loading and produce a .o file for each source file. — g Prod uce additional symbol table information for dbx{ 1). Also pass the — lg flag to ld( 1). — o output Name the final output file output instead of a. out. The following options are peculiar to f77: — 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. — Dwame — Dname= definition Define the name to the C preprocessor, as if by ‘#define’. If no definition is given, the name is defined as "1". ( .F suffix files only). -fsky Generate code which assumes the presence of a SKY floating-point processor board. Pro- grams compiled with this option can only be run in systems that have a SKY board installed. Programs compiled without the —fsky option will use the SKY board if it is present, but won’t run as fast as they would if the —fsky option were used. If any part of a program is compiled using the —fsky option, you must also use this option when linking with the f77 command, since a different set of startup routines is required. — F Apply the C preprocessor to .F files and the Ratfor preprocessor to do not compile them. No loading is done. However, any .c or .8 files are compiled or assembled. ./, but do not compile. —12 Make the default size of integer and logical constants and variables two bytes rather than four bytes. — ldir ‘#include’ files whose names do not begin with ‘/’ are always sought by the C Sun Release 2.0 Last change: 1 February 1985 129 F77 ( 1 ) USER COMMANDS F77(l) preprocessor first in the directory of the file argument, then in directories named in —I options, then in the / usr/ include / /77 directory (applies to processing of .F suffix files only). — m Apply the M4 preprocessor to each .r file before transforming it with the Ratfor prepro- cessor. — N[qxscn]nnn Make static tables in the compiler bigger. /77 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 size of multiple tables. — onetrlp 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 frac- tion of time spent in each routine. The results of this profiling appear in a file called mon.out when the program being profiled terminates normally. An execution profile of the program can then be produced 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). — Rz 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[68] Suppress all warning messages, or if the option is — w6B, supress only FORTRAN 66 com- patibility warnings. Other arguments are taken to be either loader option arguments, or /77-compatible object pro- grams, typically produced by an earlier run, or libraries of /77-compatible routines. These pro- grams, together with the results of any compilations specified, are loaded (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. FILES file.[fFrsc] file.o a.out ./fort[pid].? /usr/include/f77 input file object file linked output temporary directory searched by the FORTRAN 77 include statement 130 Last change: 1 February 1985 Sun Release 2.0 F77 ( 1 ) USER COMMANDS F77 ( 1 ) /usr/lib/f77passl /lib/fl /lib/c2 /lib/epp /lib/bin/ratfor /usr/lib/libf77.a /lib/libc.a mon.out gmon.out parser code generator optional optimizer C preprocessor Ratfor preprocessor Fortran library C library, see Section 3 file produced Tor analysis by prof(l) file produced for analysis by gprof(l) SEE ALSO FORTRAN Programmer’s Guide for the Sun Workstation prof(l), gprof(l), cc(l), Id(l), ratfor(l) DIAGNOSTICS The diagnostics produced by f77 itself are intended to be self-explanatory. Occasional messages may be produced by the loader. Sun Release 2.0 Last change: 1 February 1985 131 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. 132 Last change: 11 January 1982 Sun Release 2.0 FILE ( 1 ) USER COMMANDS FILE ( I ) NAME file — determine file type SYNOPSIS me [ -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 containing 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 % Is bensusan fortran. mss messages romero toolkit.tr command. list jokes pascal. mss squash useful. news counts letters play. mss tech. 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 2.0 Last change: 13 November 1984 133 FIND ( I ) USER COMMANDS FIND ( I ) NAME find — find files SYNOPSIS And 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. —name filename True if the filename argument matches the current file name. Normal Shell argu- ment syntax may be used if escaped (watch out for ‘[’, '?’ and V). —perm onum True if the file permission flags exactly match the octal number onum (see chmod( 1)). If onum is prefixed by a minus sign, more flag bits (017777, see s”. 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. — 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 on interactive prompting during mutliple file transfers (unimplemented). — d enable debugging. COMMANDS ! Invoke a shell on the local machine. ascii Set the file transfer 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 file transfer type to support binary image transfer, 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 inter- preter. 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 dip [ remote-directory ] [ local-file ] Print a listing of the directory contents in the directory, remote-directory, and, option- ally, 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, output comes to the terminal. form format Set the file transfer form to format. The default format is “file”, get remote-file \ local-file | 144 Last change: 1 November 1983 Sun Release 2.0 FTP (1C) USER COMMANDS FTP (1C) 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 type, form, mode, and structure are used while transferring the file. 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 j 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, the output is sent to the terminal. mode [ mode-name ] Set the file transfer mode to mode-name. The default mode is “stream” mode. mkdlr directory-name Make a directory on the remote machine. open host [ port ] Establish a connection to the specified host FTP server. An optional port number may be supplied, 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. If prompting is turned off (default), any mget or mput will transfer 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 type, format, mode, and structure. pwd Print the name of the current working directory on the remote machine, quit A synonym for bye. quotearji arg2 ... The arguments specified are sent, verbatim, to the remote FTP server. A single FTP reply code is expected in return. reev 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 the file to. rmdir directory-name Delete a directory on the remote machine. send local-file { remote-file ] A synonym for put. ■tatuB Show the current status of ftp. Sun Release 2.0 Last change: 1 November 1983 145 FTP ( 1C ) USER COMMANDS FTP ( 1C ) struct [ struct-name ] Set the file transfer structure to struct-name. By default “stream” structure is used, tenex Set the file transfer type to that needed to talk to TENEX machines, trace Toggle packet tracing, type [ type-name ] Set the file transfer type to type-name. 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 ftp is invoked with “auto-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 is on, when a file transfer completes, statistics regard- ing the efficiency of the transfer are reported. By default, verbose is on. T [ command ] A synonym for help. Command arguments which have imbedded spaces may be quoted with quote (") marks. FILE NAMING CONVENTIONS Files specified as arguments to ftp commands are processed according to the following rules. 1) If the file name is specifed, the stdln (for reading) or stdout (for writing) is used. 2) If the first character of the file name is “j”, 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 stdout (stdin). If the shell command includes spaces, the argument must be quoted; e.g. “"J Is -It"”. A particularly useful example of this mechan- ism is: “dir [more”. 3) Failing the above checks, local file names are expanded according to the rules used in the csA(l). After the name is expaned, if more than one filename matches, only the first filename is used. FILE TRANSFER PARAMETERS The FTP specification specifies many parameters which may affect a file transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”, and “local byte size” (for PDP-lO’s and PDP-20’s mostly). Ftp supports the ascii and image types of file transfer. Ftp supports only the default values for the remaining file transfer parameters: mode, form, and struct. BUGS Many FTP server implementations do not support experimental operations such as print working directory. Aborting a file transfer does not work right; if one attempts this the local ftp will likely have to be killed by hand. VAX sites running the BBN FTP server appear to ignore the PORT command while indicating complicity; this locks up all file transfers. 146 Last change: 1 November 1983 Sun Release 2.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(l) or dbx{ 1). FILES core. core images BUGS Paging activity that occurs while gcore is running may cause the program to become confused. For best results, the desired processes should be stopped. Sun Release 2.0 Last change: 8 March 1984 147 GET ( 1 ) USER COMMANDS GET ( 1 ) NAME get — get a version of an SCCS file SYNOPSIS /usp/sccs/get [ — r SID ] [ — c eufcolif ] [ —I Hot ] [ — x Hat ] [ —a seq-oo. ] [ — k ] [ — e ] [ — 1 [ P ] ] I -P I I ~m I | -n ] | -s ] [ -b ] | -g ] [ -t ] file ... 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 component of the path name does not begin with a.) 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 unread- able files are silently 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 b.; (see also FILES, below). OPTIONS Options are explained below as though only one SCCS file is to be processed, but the effects of any option argument applies independently to each named file. — r SID The SCCS /Identification 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{ 1) 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 maximum possible values; that is, — c7502 is equivalent to — c750228235950. 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: — c77/2/2 0: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( 1). 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/sccB/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 adm*n(l)) 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(l)) 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: 148 Last change: 6 March 1984 Sun Release 2.0 GET ( 1 ) USER COMMANDS GET ( 1 ) ::= I , ::= SID I SID - SID SID, the SCCS Identification of a delta, may be in any form shown in the ‘SID Specified’ column of Table 1. Partial SIDs are interpreted as shown in the ‘SID Retrieved’ column of Table 1. —x list A list of deltas to be excluded (forced not to be applied) in the creation of the generated file. See the —1 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 — lp 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. — ■ Suppress all output normally written on the standard output. However, fatal error mes- sages (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 verify 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 com6(l) 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 following the notation ‘Excluded’. Sun Release 2.0 Last change: 6 March 1984 149 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 nonej no R defaults to mR mR.mL mR.(mL+l) nonej 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. R.L.B.mS R.L.B.(mS-fl) 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-Hl) 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 max- imum 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( 1)) is present in the file. An entry of — means ‘irrelevant’. t 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 keywords with their value wherever they occur. The following keywords may be used in the text stored in an SCCS file: 150 Last change: 6 March 1984 Sun Release 2.0 GET ( 1 ) USER COMMANDS GET ( 1 ) 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. %I% SCCS identification (SID) (%R%.%L%.%B%.%S%) of the retrieved text. %R% Release. %L% Level. %B% Branch. %S% Sequence. %D% Current date (YY/MM/DD). %H% Current date (MM/DD/YY). %T% Current time (HH:MM:SS). Date newest applied delta was created (YY/MM/DD). %G% Date newest applied delta was created (MM/DD/YY). %\J% Time newest applied delta was created (HH:MM:SS). %Y% Module type: value of the t flag in the SCCS file (see admin{ 1)). %F% SCCS file name. %P% Fully qualified SCCS file name. %Q% The value of the q flag in the file (see admin(l)). %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{ 1). A shorthand notation for constructing what( 1) strings for UNIX program files. %W% = %Z%%M%%I% %A% Another shorthand notation for constructing u;Aa<(l) 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 s .module-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 b. prefix. For example, s.xyz.c, the auxiliary file names would be xyz.c, l.xyz.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; oth- erwise 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 —I 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). Sun Release 2.0 Last change: 6 March 1984 151 GET ( 1 ) USER COMMANDS GET ( 1 ) 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. 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/scca/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 permis- sion 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 z-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 containing 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( 1) for explanations. BUGS If the effective user has write permission (either explicitly or implicitly) in the directory contain- ing the SCCS files, but the real user doesn’t, only one file may be named when the — e option is used. 152 Last change: 6 March 1984 Sun Release 2.0 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 ][—■][—■] [ 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 f77. 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 execu- tion 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 pro- pagated 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 infor- mation about the static function (for instance, time samples, calls to other functions, calls from other functions) 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 excludes the time spent in name (and its descendants) from the total and percentage time computations. More than one — E option may be given. For example, — E mcount — E mcleanup is the default. Sun Release 2.0 Last change: 8 October 1984 153 GPROF(l) USER COMMANDS GPROF(l) — 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. — F name print the graph profile entry only for routine name and its descendants (as — f, above) and also uses only the times of the printed routines in total time and percentage compu- tations. More than one — F option may be given. Only one name may be given with each — F option. The — F option overrides 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 execu- tions of gprof (probably also with a — ■) 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’, Proceed- ings 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 propagated 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. — E FILES a.out 154 Last change: 8 October 1984 Sun Release 2.0 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 sunfoo/s(l) for a list of these arguments. If a program argument is present, gfxtool runs it. If there are no arguments, gfxtool runs the pro- gram corresponding to your SHELL environment variable. If this environment variable is not available, then gfxtool runs /bin/sk. 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{ 1)). Programs invoked in the terminal subwindow can run in the empty subwindow. You can move the boundary between these two subwindows as described in suntools{ 1) 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. /uar/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 com- mand 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 frame. 1 through frame. n on the current working direc- tory, and are displayed in numerical order. A set of sample frames is available to you in the directory /usr/demo/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 characters 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 Sun Release 2.0 Last change: 29 March 1985 155 GFXTOOL ( 1 ) USER COMMANDS GFXTOOL ( 1 ) 1 /20th of a second. Typing “Ff” makes the delay as small as possible. 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 win- dow into a retained window. This allows the image to reappear when uncovered instead of res- tarting 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 "boun- cedemo -d /dev/cgoneO” directs the demo to run on a display other than the console. SEE ALSO suntools( 1) shelltoot( 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?" submenu there has one item, "Flush input", that you can invoke to correct the problem. 156 Last change: 29 March 1985 Sun Release 2.0 GRAPH(IG) USER COMMANDS GRAPH(IG) NAME graph — draw a graph SYNOPSIS graph [ —a spacing [ start ] ] [ — b ] [ — c string ) [ — g gridstyle ] [ —1 label ] [ — m connectmode ] [ — s ] [ — x [ 1 ] lower [ upper [ spacing ) ] ] j — 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 stan- dard 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 distinguishable line styles for other small integers. — b Save screen, don’t erase before plotting. —x [ I ] lower [ upper [ spacing ] ] If 1 is present, x axis is logarithmic, lower&ndupper are lower (and upper) x limits, spac- ing, if present, is grid spacing on x axis. Normally these quantities are determined automatically. — y [ 1 ] lower | upper ( spacing ] ] If 1 is present, y axis is logarithmic, lower&ndupper are lower (and upper) y limits, spac- ing, 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 Sun Release 2.0 Last change: 1 June 1983 157 GRAPH (1G) USER COMMANDS GRAPH (1G) is fraction of space to move up before plotting. — t Transpose horizontal and vertical axes. (Option — x now applies to the vertical axis.) 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. 158 Last change: 1 June 1983 Sun Release 2.0 GREP(l) USER COMMANDS GREP(l) NAME grep, egrep, fgrep — search a file for a pattern SYNOPSIS grep I — ' v ] [ — c ] [ — 1 ] [ — n ] [ — b j [ — 1 ] [ — a ] [ — h ] [ — w ] [ — e expression ] expression [ filename ... ] egrep [ — ' v ] [ — c | [ — I ] [ — n ] [ — b ][—•][ — h ] [ — e expression ] [ —tfile ] [ expression ) j filename | ... ] fgrep [ — v ] | — x ] [ — e ] [ — 1 | [ — n ] [ — b | [ — 1 ] [ — • ] [ — h ] [ — e expression ] [ —tfile ] [ strings ] [ 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 erf(l). 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 $ * [ A J ( ) and \ in the expression as these characters are also meaningful 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 /dev /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 locating disk block numbers by context. — i Ignore the case of letters in making comparisons — that is, upper and lower case are con- sidered identical. This applies to grep and fgrep only. — a 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 Sun Release 2.0 Last change: 12 February 1985 159 GREP ( 1 ) USER COMMANDS GREP ( 1 ) that character. Anchored match: matches the beginning of a line. $ Anchored match: matches the end of a line. * (period) matches any character. c Where c is any single character not otherwise endowed with special meaning matches that character. [slrinj] 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 * (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. \ 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 * + ? (closures), then concatenation, then j (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 ’[l-8]([CJMSNX])’ /usr/man/manl/*.l Look for alternative patterns using egrep : tutorial% egrep ’(SallyjFred) (SmlthJJonesJParker)’ 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 160 Last change: 12 February 1985 Sun Release 2.0 GREP ( 1 ) USER COMMANDS GREP ( 1 ) 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. Ideally there should be only one grep, but for historical reasons there are three different versions each with a slightly different set of options and syntaxes. Sun Release 2.0 Last change: 12 February 1985 161 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 /etc/passwd and possibly to other groups as specified in the file /etc/ 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 162 Last change: 20 June 1983 Sun Release 2.0 HEAD ( 1 ) USER COMMANDS HEAD ( 1 ) 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 -0090 fllel flle2 . . . EXAMPLE gaia% head -4 /usr / man /maul/ {cat, head, tall}. I ==> /usr/man/manl/cat.l <== .TH CAT 1 "2 June 1983" .SH NAME cat — concatenate and display .SH SYNOPSIS ==> /usr/man/manl/head.l <== .TH HEAD 1 "24 August 1983" .SH NAME head — display first few lines of specified files .SH SYNOPSIS ==> /usr/man/manl/tail.l <== .TH TAIL 1 "27 April 1983" .SH NAME tail — display the last part of a file .SH SYNOPSIS SEE ALSO more(l), tail(l), cat(l) Sun Release 2.0 Last change: 24 October 1983 163 HELP ( 1 ) USER COMMANDS HELP ( 1 ) 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 messages) 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, geft, 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/sees/help stuck. FILES /usr/lib/help directory containing files of message text. DIAGNOSTICS Use help{ I) for explanations. 164 Last change: 27 October 1983 Sun Release 2.0 HOSTID(l) 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 hex. This numeric value is unique across all Sun hosts. SEE ALSO gethostid(2) Sun Release 2.0 Last change: 1 February 1985 165 HOSTNAME(l) 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) 166 Last change: 22 March 1983 Sun Release 2.0 ICONTOOL(l) USER COMMANDS ICONTOOL ( 1 ) NAME icontool — create and edit icons and cursors SYNOPSIS Icontool [ filename ] OPTIONS icontool accepts the SunWindows generic tool arguments; see suntools(l) for a list of these argu- ments. DESCRIPTION icontool is a bitmap editor that allows you to create small images such as icons and cursors. icontool 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 sun- tools(l). When invoked, icontool 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 cursor 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 button. 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 alternatives 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 Sun Release 2.0 Last change: 29 March 1985 167 ICONTOOL(l) USER COMMANDS ICONTOOL ( 1 ) 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. Entering an alphabetic string terminated by requests filename completion, icon- tool 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 addi- tion, 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 paint- ing mode. Point at the desired mode and click the left mouse button to move the paint- ing 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 corner of the rectangle and press and hold the left mouse button. While holding the but- ton down, drag the cursor to the diagonally opposite corner of the rectangle. Release the mouse button. In the control panel, the Fill field to the right of the rectangle indicates the current rectangle 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 pat- tern. 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 168 Last change: 29 March 1985 Sun Release 2.0 ICONTOOL(l) USER COMMANDS ICONTOOL ( 1 ) 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 rectangle 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. 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( 1) FILES /usr/bin/icontool Sun Release 2.0 Last change: 29 March 1985 169 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) NAME indent — indent and format C program source SYNOPSIS indent input-file [ output-file ] [ — lnrm ] [ — c nnn ] [ — cdrmn ] | — Innn ] [ — dj | — ndj ] [ —v J — nv j [ —be | — nbe ] [ — drmn ] [ — br J — bl ] DESCRIPTION Indent is intended primarily as a C program formatter. Specifically, indent: • indents code lines • aligns comments • inserts spaces around operators where necessary • breaks up declaration lists as in ‘int a,b,c;’. Indent does not break up long statements to make them fit within the maximum line length, but does flag lines that are too long. Lines are broken so that each statement starts a new line, and braces appear alone on a line — see the — br option to inhibit this. Also, an attempt is made to line up identifiers in declarations. The flags which can be specified follow. They may appear before or after the file names. NOTE: If you specify only an input- file, the formatting is done ‘in-place’, that is, the format- ted file is written back into input-file and a ‘backup’ copy of input-file is written in the current directory. If input-file is named ‘/usr/src/file’, the backup file is named .Bfile. If output-file is specified, indent checks to make sure it is different from input-file. OPTIONS The options listed here control the formatting style imposed by indent. —innn Maximum length of an output line. The default is 75. — c nnn The column in which comments start. The default is 33. — cd nnn The column in which comments on declarations start. The default is for these comments to start in the same column as other comments. —Innn — dj,— ndj — v,— nv — be,— nbc — dnnn The number of spaces for one indentation level. The default is 4. -dj left justifies declarations, —ndj indents declarations the same as code. The default is —ndj. — 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. If -be is specified, then a newline is forced after each comma in a declaration, —nbc turns off this option. The default is —be. This option controls the placement of comments which are not to the right of code. Specifying — d2 means that such comments are placed two indentation levels to the left of code. The default — dO lines up these comments with the code. See the section on comment indentation below. — br,— bl Specifying — bl lines up complex statements like this: if (...) { code } 170 Last change: 28 September 1984 Sun Release 2.0 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) Specifying — br (the default) makes them look like this: if (...) { code } FURTHER DESCRIPTION You may set up your own ‘profile’ of defaults to indent by creating a file called .indent.pro in your login directory and including whatever switches you like. 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 override profile switches. The profile file must be a single line of not more than 127 char- acters. The switches should be separated on the line by spaces or tabs. Multi-line expressions Indent does not break up complicated expressions that extend over multiple lines, but it usually correctly indents such expressions which have already been broken up. Such an expression might end up looking like this: x = ( (Arbitrary parenthesized expression) + ( (Parenthesized expression) * (Parenthesized expression) ) ); Comments Indent recognizes four kinds of comments. They are: straight text, ‘box’ comments, UNIX-style comments, and comments that should be passed through unchanged. The action taken with these various types are as follows: ‘Box’ comments. Indent assumes that any comment with a dash immediately after the start of comment (that is, */*—’) is a comment surrounded by a box of stars. Each line of such a com- ment is left unchanged, except that the first non-blank character of each successive line is lined up with the beginning slash of the first line. Box comments are be indented (see below). ‘Unix-style’ comments. This is the type of section header which is used extensively in the UNIX system source. If the start of comment ('/*’) appears on a line by itself, indent assumes that it is a UNEX-style comment. These are treated similarly to box comments, except the first non-blank character on each line is lined up with the V of the “/*’. Unchanged comments. Any comment which starts in column 1 is left completely unchanged. This is intended primarily for documentation header pages. The check for unchanged comments is made before the check for UNIX-style comments. 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. Straight text comments are indented. Comment indentation Box, UNDC-style, and straight text comments may be indented. If a comment is on a line with code it is started in the ‘comment column’, which is set by the — c nnn command line parameter. Otherwise, the comment is started at nnn indentation levels less than where code is currently being placed, where nnn is specified by the — dnrm command line parameter. Indented comments are never placed in column 1. If the code on a line extends past the comment column, the Sun Release 2.0 Last change: 28 September 1984 171 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) comment is moved to the next line. DIAGNOSTICS Diagnostic error messages, mostly to tell that a text line has been broken or is too long for the output line. FILES .indent. pro profile file BUGS Does not know how to format ‘long’ declarations. 172 Last change: 28 September 1984 Sun Release 2.0 INDXBIB ( 1 ) USER COMMANDS INDXBIB (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{l) 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: /usr/ lib/ refer/ mkey and / usr/ 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 parameters can be changed — see Refer — a Bibliography Sys- tem 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 working directory. FILES i.ia, z.ib, z.ic, where x is the first argument, or if these are not present, then z.ig, x SEE ALSO refer(l), addbib(l), sortbib(l), roflfbib(l), lookbib(l) BUGS Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or earlier. Sun Release 2.0 Last change: 6 April 1985 173 INEWS ( 1 ) USER COMMANDS INEWS ( 1 ) NAME inews — submit news articles SYNOPSIS Inews [ — h ] — t title [ — n newsgroups ] [ — e expiration date ] Inews — p [ filename \ inews — C newsgroup DESCRIPTION Inews submits news articles to the USENET news network. Inews is intended as a raw interface to the news system, not as a human user interface. Casual users should probably use postnews( 1) instead. The first form of inews is for submitting user articles. The body of the article is read from the standard input. A title must be specified as there is no default. Each article belongs to a list of newsgroups. The standard list of newsgroups is used if the list is not specified via the — n option. On the Sun system, the standard subscription list is: general, all. general, general, all. announce, .'junk, .'control, and .'test. If you wish to submit an article in multiple newsgroups, the news- groups must be separated by commas and/or spaces. The expiration date is set to the local default if not otherwise specified. When posting an article, the environment is checked for information about the sender. If NAME is found, its value is used for the full name, rather than the system value obtained from /etc/passwd. This is useful if the system value cannot be set, or when more than one person uses the same login. If ORGANIZATION is found, the value overrides the system default organization. This is useful when a person uses a guest login and is not primarily associated with the organiza- tion owning the machine. The second form of inews is for receiving articles from other machines. If filename is given, the article is read from the specified file; otherwise the article is read from the standard input. An expiration date need not be present and a receival date is ignored if present. After local installation, inews transmits the article to all systems that subscribe to the news- groups that the article belongs to. The third form of inews is for creating new newsgroups. On some systems, this may be limited to specific users such as the super-user or news administrator. This is true on the Sun system. If the file /usr/ lib/ news/ recording is present, it is taken as a list of ‘recordings’ to be shown to users posting news. This is an analogy to the recording you hear when you dial information in some parts of the country, asking you if you really wanted to do this, /usr/ lib/ news/ recording contains lines of the form: newsgroups filename for example: net.all net.recording fa.all fa.recording Any user posting an article to a newsgroup matching the pattern on the left is shown the con- tents of the file on the right. The file is found in the LIB directory (often /usr /lib /news). The user is then told to hit DEL to abort or RETURN to proceed. The intent of this feature is to help companies keep proprietary information from accidently leaking out. OPTIONS — n " newsgroups” specifies a list of newsgroups to which the articles are submitted. Elements in the list must be separated by commas and/or spaces. The expiration date is set to the local default if not otherwise specified. — f [ sender] Specifies the article’s sender. Without this flag, the sender defaults to the user’s name. If — f is specified, the real sender’s name is included as a Sender line. 174 Last change: 13 March 1984 Sun Release 2.0 INEWS ( 1 ) USER COMMANDS INEWS ( 1 ) — h Headers are present at the beginning of the article, and these headers should be included with the article header instead of as text. This mechanism can be used to edit headers and supply additional nondefault headers, but not to specify certain information, such as the sender and article ID that inews itself generates. FILES /usr/spool/news/.sys.nnn temporary articles /usr/spool/news / newsgroups / article_no. Articles /usr/spool/oldnews/ /usr/lib/news/active /usr/lib/news/seq /usr/lib/news/history /usr/lib/news/sys Expired articles List of known newsgroups and highest local article numbers in each. Sequence number of last article List of all articles ever seen System subscription list SEE ALSO mail(l), binmail(l), getdate(3), news(5), newsrc(5), postnews(l), readnews(l), recnews(l), send- news(8), uucp(l), uurec(8), Network News User’s Guide in the Beginner’s Guide to the Sun Workstation. Sun Release 2.0 Last change: 13 March 1984 175 INSTALL ( 1 ) USER COMMANDS INSTALL ( 1 ) NAME install — install files SYNOPSIS Install [ — c ] [ — m mode ] [ — o owner ] [ -g group ] [ -a ] 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. 9 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. In addition, if you want to set any modes (such as set-user- id), you must be super-user. © 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 other- wise 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. ~B 9 rou P . . , . . . . Set the group ownership of the destination file to group, destination is changed to group staff by default. — ■ Strip binary files after it is installed — only applicable to binary files in a.ouf(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 mu(l) or cp(l). 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 mt>(l) or cp(l). 176 Last change: 16 February 1984 Sun Release 2.0 JOIN ( 1 ) USER COMMANDS JOIN(l) NAME join — relational database operator SYNOPSIS join [ —an ] [ — e string ] [ — J [1 { 2| m ] [ — o list ] [ — tc ] filel file2 DESCRIPTION Join forms, on the standard output, a join of the two relations specified by the lines of filel and file2. If filel is the standard input is used. Filel and fileS 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 filel and fileS that have identical join fields. The output line normally consists of the common field, then the rest of the line from filel, then the rest of the line from fileS. 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 unpairable line in filel. 2 produce a line for each unpairable line in fileS. 3 produce a line for each unpairable line in both filel and fileS. The normal output is also produced. — e 8 Replace empty output fields by string. — J [1 j2] m Join on the mth field of file n, where n is 1 or 2. If n is missing, use the mth field in each file. Note that join counts fields from 1 instead of 0 like sorf(l) does. — o list Each output line comprises the fields specifed 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 sor<(l) 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 —6; with — t, the sequence is that of a plain sort. The conventions of j'oi'n(l), sor<(l), comm(l), unt'g(l), look{ 1), and att/I;(l) are wildly incongruous. Sun Release 2.0 Last change: 24 October 1984 177 KILL ( 1 ) USER COMMANDS KILL ( 1 ) NAME kill - send a signal to a process, or terminate a process SYNOPSIS kill [ — sig ] processid . . . kill -1 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 (see sigvec(2)). The signal names are listed by using the -1 option, and are as given in J 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 process 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 caA(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 termi- nals 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 csA(l); it allows job specifiers, such as kill %..., in place of kill arguments. See csh( 1) for details. OPTIONS —I Display a list of signal names. SEE ALSO csh(l), ps(l), kill(2), sigvec(2) BUGS An option to kill process groups ala killpg{ 2) should be provided; a replacement for kill 0 for csA(l) users should be provided. 178 Last change: 24 October 1983 Sun Release 2.0 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 O’ is the same as ‘last ttyO’. If multiple arguments are given, the information which applies to any of the argu- ments 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 control-\) 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 [etc/ wtmp. FILES /usr/adm/wtmp login data base /usr/adm/shutdownlog which records shutdowns and reasons for same SEE ALSO utmp(5), ac(8), lastcomm(l) Sun Release 2.0 Last change: 16 February 1984 179 LASTCOMM(l) USER COMMANDS LASTCOMM(l) NAME lastcomm — show last commands executed in reverse order SYNOPSIS l&stcomm [ 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 life- time. If called with arguments, lastcomm only displays accounting entries with a matching com- mand name, user name, or terminal 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 terminal 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 follow- ing meanings: 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, e 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). o The date and time the process exited. FILES /usr/adm/acct accounting file SEE ALSO last(l), sigvec(2), acct(5), core(5) 180 Last change: 1 February 1985 Sun Release 2.0 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 ] [ —x ] filename . . . DESCRIPTION Ld combines several object programs into one, resolves external references, and searches libraries. In the simplest case several object filenames 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. The argument filenames are concatenated in the order specified. The entry point of the output is the begin- ning 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{ 1), the refer- enced routine must appear after the referencing routine in the library. Titus the order of programs within libraries may be important. The first member of a library should be a file named ‘ .SYMDEF’, which is understood to be a dictionary for the library as produced by ranlib( 1); 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 abbre'^sted library names specified by the -1 option, which can appear anywhere. ^ —A name Incremental loading: linking is to be done in a manne. 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 — e entry Define the entry point: the entry argument is made the name of the entry point of the loaded pro- gram. -Lc 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 placement 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 users executing the file. This involves Sun Release 2.0 Last change: 7 November 1984 1 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, -r flag is present -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 origin at location hex. Specifying a bare -T is the same as using the -Ttext option. -Tdata hex Start the text segment origin 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(l) to discard internally-generated labels while retaining symbols local to routines. -x Do not preserve local (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 ty ^ and whether the file defines or references it. Many such options may be given to trace many mbols. It is usually necessaty to begin sym with an as external C, FORTRAN and Pascal wimbles 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 data segment size roundup. 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(I), ar(l), cc(l), ranlib(l), strip(l) BUGS There is no way to force data to be page-aligned. Sun Release 2.0 Last change: 7 November 1984 2 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 inclu- sion 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 tutorial?? 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. Sun Release 2.0 Last change: 7 March 1984 181 LEX ( 1 ) USER COMMANDS LEX ( 1 ) 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 exe- cuted when expressions are found. A C source program, ’lex.yy.c’ is generated, to be compiled thus: cc lex.yy.c —11 This program, when run, copies unrecognized portions of the input to the output, and executes the associated 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]+ 'a 'A ' ); N+s [ ]+ 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. 182 Last change: 1 November 1983 Sun Release 2.0 LINT ( 1 ) USER COMMANDS LINT ( 1 ) NAME lint — a C program verifier SYNOPSIS lint [ — abchnuvxB ] [ — D name=def\ [ — D name ] [ — U name ] [ —I dir ] file . . . lint [ —Clib ] file . . . 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 preprocessor 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 value is con- stant. 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 compatibility. Function definitions for certain libraries are available to lint ; these libraries are referred to by a conventional name, such as — lm, in the style of W(l). The standard C library (— lc) is lint'e 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.ln in the /usr/lib/lint directory in the correct library format suitable for lint ' ing programs using — lcongress. OPTIONS a Report assignments of long values to lnt variables. b Report break statements that cannot be reached. This is not the default because, unfor- tunately, most lex and many yacc outputs produce dozens of such comments. 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 out 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 without knowing its contents.). — Dn ame—def —Dname Define name to the preprocessor, as if by ‘#define’. If no definition is given, the name is defined as "l". — U name Remove any initial definition of name in the preprocessor. —I dir ‘#include’ files whose names do not begin with '/' are always sought first in the directory of the file argument, then in directories named in —I options, then in the /usr/include directory. Sun Release 2.0 Last change: 1 February 1985 183 LINT ( 1 ) USER COMMANDS LINT ( 1 ) — Clib create a lint library with name lib (see DESCRIPTION section). —Uib use lint library lib from the /usr/lib/lint directory. General Comments The routine exit(2) and other functions which do not return are not understood; this causes vari- ous 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 func- tion 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. /+LINTLIBRARY*/ at the beginning of a file, shuts off complaints about unused functions in this file. EXAMPLE The following lint call: tutorial% lint — b myflle checks the consistency of the file ‘myfile’. The — b option indicates that unreachable break statements are to be checked. FILES / usr/lib/lint/lint[12] /usr/lib/lint/llib-lc.ln /usr/lib/lint/llib-lc /usr/lib/lint/llib-lm.ln /usr/lib/lint/llib-lm /usr/lib/lint/llib-lmp.ln /usr/lib/lint/llib-lmp lib-I*.In SEE ALSO cc(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. programs declarations for standard functions human-readable version of above declarations for math functions human-readable version of above declarations for multiprecision functions human-readable version of above library created by the — C option 184 Last change: 1 February 1985 Sun Release 2.0 LOCKS CREEN ( 1 ) USER COMMANDS LOCKSCREEN ( 1 ) NAME lockscreen — maintain window context until “login” SYNOPSIS lockscreen [ — e ] [ —a ] [ — 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 burn 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 keyboard 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 Sunwin- dows environment is exited and the current 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 2.0 Last change: 25 March 1985 185 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 user i.d. to another. If you use login without an argument, login requests a user name, and a password if appropriate. Echoing is turned off (if possible) during the typing of the password, so it will not appear on the written record of the session. After a successful login, accounting files are updated, the user is informed of the existence of mail, and the message of the day is printed, as is the time he last logged in (unless he has a .hushlogin file in his home directory — this is mainly used to make life easier for non-human users, such as uucp). Login initializes the user and group IDs and the working directory, then executes a command interpreter (usually either sA(l) or csh( 1)) according to specifications found in a password file. 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 environ(5) with information specifying home directory, command interpreter, terminal type (if available) and user name. If the file / etc/ nologin exists, login prints its contents on the user’s terminal and exits. This is used by shutdoum( 8) to stop logins when the system is about to go down. Login is recognized by sA(l) and csA(l) and executed directly (without forking). Login times out and exits if its prompt for input is not answered within some ‘reasonable’ time. When the Bourne Shell (sA(l)) starts up, it reads a file called .profile from the user’s home direc- tory. When the C-Shell (sft(l)) starts up, it reads a file called .login from the user’s home direc- tory, and reads a file called .cshrc from the user’s home directory every time a new C-Shell is started. Note that the Shells only read these files if they are owned by the person who is logging in — these files are not read when login is being used to change user i.d. FILES /etc/utmp /usr/adm/wtmp /usr/spool/mail/* /etc/motd /etc/passwd /etc/nologin .hushlogin accounting accounting mail message-of-the-day password file stops logins makes login quieter SEE ALSO init(8), getty(8), mail(l), passwd(l), passwd(5), environ(5), shutdown(8) DIAGNOSTICS “Login incorrect,” if the name or the password is bad (or mis-typed). “No Shell”, “cannot open password file”, “no directory”: ask your system administrator for assis- tance. 186 Last change: 1 February 1985 Sun Release 2.0 LOOK ( 1 ) USER COMMANDS LOOK ( 1 ) 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 /usr/ diet/ words with collating sequence — df. FILES /usr/dict/words SEE ALSO sort(l), grep(l) Sun Release 2.0 Last change: 13 April 1983 187 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 refer- ence files. FILES z.ia, z.ib, z.ic, where x is the first argument, or if these are not present, then z.ig, x SEE ALSO 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 earlier. 188 Last change: 6 April 1985 Sun Release 2.0 L ORDER ( 1 ) 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 tsorl(l) to find an ordering of a library suitable for one-pass access by / to print the first few lines of all messages. Replying to mail. You can use the reply (r) command to respond to a message, followed by the text, and ending with an EOT (control-D) or a period alone on a line. There are some varia- tions of the reply command: r (the straightforward reply command) replies to the person who sent you the message. This command can also be typed as replysender. R (upper-case R) replies to everyone who got the original message. This command can also be typed as replyall. Also see the replyall variable. Originating mail while browsing. You can use the mail command (m) to originate a message while browsing. While you are composing a message, you can use ‘escapes’ (usually called ‘tilde escapes’) to get mail to treat such lines in special ways. For instance, typing ‘~m’ (alone on a line) places a copy of the current message into the response, but shifted right by one tabstop. Other escapes set up subject fields, add and delete recipients to the message, and allow you to escape to an editor to revise the message or to a shell to run some commands. These options are described in the summary below. 200 Last change: 25 March 1985 Sun Release 2.0 MAIL ( 1 ) USER COMMANDS MABL( 1) Ending a mail processing session. You end a mail session with the quit (q) command. Messages which have been examined but not deleted go to your mbox file. Messages which have been deleted are discarded. Unexamined messages are retained. The — f option specifies that mail read in the contents of your mbox (or the specified file) for browsing; when you quit mail writes undeleted messages back to this file. Personal and systemwide distribution lists. You can create personal distribution lists so that, for instance, you can send mail to ‘cohorts’ and have it go to a group of people. Such lists can be defined by placing a line like: alias cohorts bill ozalp sklower jkf mark cory:kridle in the file .mailrc in your home directory. You can nest distribution lists so that a distribution list can refer to other distribution lists, which finally, refer to individual people. The current list of such aliases can be displayed by the alias (a) command. System Distribution Lists System wide distribution lists can be created by editing /usr/ lib/ aliases, see aliases (5) and sendmail(8); these are kept in a slightly different syntax. In mail you send, personal aliases are expanded in mail sent to others so that they can reply (lower case r) to the recipients. System-wide aliases are not expanded when the mail is sent, but any reply returned to the machine will have the system wide alias expanded as all mail goes through sendmail. If you edit / usr /lib/ aliases, you must run the program newaliases( 8) to rebuild the aliases database. Network mail ( ARPA , UUCP). Mail to sites on the ARPA or UUCP network can be sent using name@site for ARPA-net sites or machineluser for UUCP sites, provided appropriate gateways are known to the system. Be sure to escape the ! in UUCP sites when giving it on a csh command line by preceding it with a \. Mail has a number of options which can be set in the . mailrc file to alter its behavior; thus set askcc enables the ‘askcc’ (ask for carbon copy) feature. These options are summarized below in the sec- tion labelled Mail Options. SUMMARY OF MAIL COMMANDS This summary is adapted from the Mail User's Guide. Each mail command is typed on a line by itself. Arguments may follow the command word. The command word need not be typed in its entirety — the first command which matches the typed prefix is used. Commands which take message lists as arguments use the next message forward which satisfies the command’s requirements if a message-list is not specified. If there are no mes- sages forward of the current message, the search proceeds backwards, and if there are no good messages at all, mail types ‘No applicable messages’ and aborts the command. — [ nnn] Go to the previous message and print it out. If the optional numeric argument nnn is specified, go to the nnn’th previous message and print it. -p[ nnn] Go to the next message and print it out. If the optional numeric argument nnn is specified, go to the nnn’th next message and print it. ? Print a brief summary of commands. I Shell Command Execute the UNIX Shell Command which follows the !. atlas (a) With no arguments, print out all currently-defined aliases. With one argument, print out that alias. With more than one argument, add the users named in the second and later arguments to the alias named in the first argument. dhdh* [ directory] Sun Release 2.0 Last change: 25 March 1985 201 MAIL(l) USER COMMANDS MAIL ( 1 ) (c) Change the user’s working directory to the optional directory argument. Change to the user’s login directory if directory is not specified. delete (d) Takes a list of messages as argument and marks them all as deleted. Deleted mes- sages are not saved in mbox, nor are they available for most other commands. Messages deleted in the current mail session can be undeleted with the undelete command described later. dp (also dt) Delete the current message and print the next message. If there is no next mes- sage, mail says ‘at EOF.’ edit (e) Takes a list of messages and points the text editor at each one in turn. You can edit the message freely, with two exceptions: you must not touch the first line of the message header (The “From” line), and you must leave a blank line at the end of the message. When you exit from the editor (as normal for the editor: ‘write’ and ’quit’), the message is read back in. exit (ex or x) Effects an immediate return to the Shell without modifying the user’s system mailbox, the mbox file, or the edit file when using the — f option. folder (fo) The folder command switches to a new mail file or folder. With no arguments, it tells you which file you are browsing. If you supply a filename as an argument, it will write out changes in the current file, and access the named file. Some special conven- tions are recognized for the argument. # indicates the previous file, % indicates your system mailbox, %user indicates the user’s system mailbox, & means your '/mbox file, and +folder means a file in your folder directory. folders List the names of the folders in your folders directory, from (f) Takes a list of messages and prints their message headers. headers (h) List the current range of headers, 20 at a time (fewer lines are displayed on low-speed terminals). If you want to see another group of headers, you must type a number that lies within that group. For example, headers alone displays the headers of the first 20 messages. To see headers (say) 41 thru 60, you can type headers 45 or in fact any number that lies in the range 41 thru 60. Also see the z command below, which scrolls forwards and backwards through groups of headers. help A synonym for ? hold (ho, also preserve) Takes a message list and marks each message therein to be saved in the user’s system mailbox instead of in mbox. Does not override the delete command. ignore takes a list of character strings as arguments. Lines in the header of mail messages that start with any of the specified character strings are ignored. mail (m) Takes as arguments login names and distribution group names and sends mail to those people. next (n like + or CR) Goes to the next message in sequence and types it. With an argument list, types the next matching message. preserve A synonym for hold. print (p) Takes a message list and types out each message on the user’s terminal. Typing a print command with a capital P prints even ignored headers. 202 Last change: 25 March 1985 Sun Release 2.0 USER COMMANDS MAIL ( 1 ) MAIL ( 1 ) quit (q) Terminate the mail session, saving all undeleted, unsaved messages in your mbox file in your login directory, preserving all messages marked with hold or preserve or never referenced in your system mailbox, and removing all other messages from your system mailbox. If new mail has arrived during the mail session, mail displays a message: You have new mall If you quit while editing a mailbox file with the — f flag, mail rewrites the edit file. Mail then returns to the Shell, unless the rewrite of edit file fails, in which case the user can escape with the exit command. reply (r) Takes a message list and sends mail to each message author just like the mall com- mand. The default message must not be deleted. replyall Replies to all members on a distribution list, regardless of the setting of the replyall variable. replysender Reply to the sender of the message, regardless of the setting of the of the replyall vari- able. Reply (upper-case R) replies to all members on a distribution list. respond A synonym for reply. Respond A synonym for Reply. save (s) Takes a message list and a filename and appends each message in turn to the end of the file. The filename in quotes, followed by the line count and character count is echoed on the user’s terminal. set (se) With no arguments, prints all variable values. Otherwise, sets option. Arguments are of the form: option— value or: option shell (sh) Invokes an interactive version of the shell. size Takes a message list and prints out the size in characters of each message, source (so) Accepts mail commands from a file. subject (su) works like the from command but works with subjects instead of message headers. top Takes a message list and prints the top few lines of each. The number of lines printed is controlled by the variable topllnes and defaults to five. type (t) A synonym for print. unallas Takes a list of names defined by alias commands and discards the remembered groups of users. The group names no longer have any significance. undelete (u) Takes a message list and marks each one as not being deleted. unset Takes a list of option names and discards their remembered values; the inverse of set. visual (v) Takes a message list and invokes the visual editor on each message. Note that the cautions given for the edit option above — about the header and final line of the mes- sage — apply here as well. Sun Release 2.0 Last change: 25 March 1985 MAIL(l) USER COMMANDS MAIL ( 1 ) write (w) is similar to the save command, but write removes the ‘From’ line and the ‘Status’ line from the header of the messages, whereas save leaves those lines in the message. Kit (x) A synonym for exit. s Scrolls forwards and backwards through groups of headers, 20 at a time (fewer lines of headers on low-speed terminals). If a '+’ argument is given, the next 20 headers are displayed, and if a ’ argument is given, the previous 20 headers are displayed. ESCAPE SEQUENCES Here is a summary of the tilde escapes, which are used when composing messages to perform spe- cial functions. Tilde escapes are only recognized at the beginning of lines. The name ‘tilde escape’ is somewhat of a misnomer since the actual escape character can be set by the option escape. '[command Execute the indicated shell command, then return to the message. c name ... Add the given names to the list of carbon copy recipients. “d Read the file dead. letter from your home directory into the message. "e Invoke the text editor on the message collected so far. After the editing session is finished, you may continue appending text to the message. ~f messages Read the named messages into the message being sent. If no messages are specified, read the current message. Also see the command which does the same thing but shifts the message right by one tab stop. "h Edit the message header fields by typing each one in turn and allowing the user to append text to the end or modify the field by using the current terminal erase and kill characters. 'm messages Read the named messages into the message being sent, shifted right one tab. If no mes- sages are specified, read the current message. "p Print out the message collected so far, prefaced by the message header fields. "q Abort the message being sent, copying the message to dead.letter in your home directory if save is set. r filename Read the named file into the message. “a string Make the named string become the current subject field. ~t name ... Add the given names to the direct recipient list. "v Invoke an alternate editor (defined by the VISUAL option) on the message collected so far. Usually, the alternate editor is a screen editor. After you quit the editor, you may resume appending text to the end of your message. "w filename Write the message onto the named file. {command Pipe the message through the command as a filter. If the command gives no output or terminates abnormally, retain the original text of the message. The command fmt(l) is often used as command to rejustify the message. SOS -''ange: 25 March 1985 Sun Release 2.0 MAIL ( 1 ) USER COMMANDS MADL(l) string Insert the string of text in the message prefaced by a single If you have changed the escape character, then you should double that character in order to send it. MAIL OPTIONS Options are controlled via the Bet and unset commands. Options may be either binary, in which case it is only significant to see whether they are set or not, or string, in which case the actual value is of interest. You can set and unset options during a mail session, or you can place the options in your .mailrc file in your home directory. Binary Options. The binary options include the following: append Messages saved in mbox are appended (the default case) to the end rather than prepended. This is set in /usr/ lib/ Mail. rc on version 7 systems. ask Mail prompts you for the subject of each message you send. If you respond with simply a newline, no subject field is sent. askcc Mail prompts for additional carbon copy recipients at the end of each message. Respond- ing with a newline indicates your satisfaction with the current list. autoprint The delete command behaves like dp — thus, after deleting a message, the next one is typed automatically. ignore Mail ignores interrupt signals from your terminal and echoes them as @’s. hold This option is used to hold messages in the system mailbox by default. metoo Usually, when a group is expanded that contains the sender, the sender is removed from the expansion. Setting metoo includes the sender in the group. nosave Prevents mail from saving messages in the dead.letter file in your home directory on receipt of two interrupts (or after a "q). The default action is to save such messages in the dead.letter file. quiet Suppress printing the version of the mail program when first invoked. replyall Alters the action of the reply and Reply commands: reply (lower-case r) normally replies to just the sender of the message. Reply (upper-case R) normally replies to everyone on the distribution list. Setting the replyall variable reverses this behavior so that r (lower-case r) replies to everyone on the distribution list, and R (upper-case R) replies to just the sender. This feature is here to retain compatibility with older versions of the mail system. String Options. The following options have string values: EDITOR Pathname of the text editor to use in the edit command and ~e escape. If not defined, then a default editor is used. The default editor is /usr/ucb/ ex. SHELL Pathname of the shell to use in the ! command and the ~! escape. A default shell is used if this option is not defined. The default shell is /bin/csh. VISUAL Pathname of the text editor to use in the visual command and ~v escape. escape If defined, the first character of this option gives the character to use in the place of ' to denote escapes. record If defined, gives the pathname of the file used to record all outgoing mail. If not defined, Sun Release 2.0 Last change: 25 March 1985 205 MAIL ( 1 ) USER COMMANDS MAIL(l) outgoing mail is not saved. topltaes If defined, gives the number of lines of a message to be printed out with the top com- mand; normally, the first five lines are printed. crt If defined, gives the number of lines of a message to be printed before mail calls up the more(l) utility so that you can peruse the mail messages leisurely. EXAMPLES Send mail to Wendy on her system called ariel: angel% mall wendy@arlel Subject: New DBX Manuals The new DBX manual pages are In angeh/usr/man/manl/dbx.l *D EOT angel% Note that mail asked for a subject; this is controlled by the ask option in the .mailrc file. There is an example of such a file later on in this section. Now when Wendy is working on her system, she will see a mail notification: work, work, work You have new mail. ariel% mall Mail version 2.17 12/26/82. Type ? for help "/usr/spool/mail/wendy": 1 message 1 new >N 1 cuthbert Thu Nov 3 10:03:01 11/265 "New DBX Manual Pages" & Mail signals its readiness for commands Carriage-return means read next message From cuthbert Thu Nov 3 10:03:01 1983 Date: 3 Nov 83 10:02:56 PST (Thu) From: cuthbert (Cuthbert Pouncetrifle) Subject: New DBX Manual Pages To: wendy Status: R The new DBX manual pages are in angeh/usr/man/manl/dbx.l & Mail signals its readiness for commands Carriage-return means read next message At EOF Means there are no more messages & d Delete this message & q Quit from the mail program ariel% Here is a .mailrc file in which you can set options to control mail’s behavior: set crt=30 ask ignore via apparently-to date from status received message-id The first line sets the crt option to 30 lines — if there are messages longer than this, mail calls up more to page through the message in 30-line chunks. The ask option makes mail ask for a subject heading every time you send mail to someone. Finally, the second line says to ignore any line starting with any of the character strings from the list — this shortens the amount of irrelevant junk that appears at the top of mail messages. 206 Last change: 25 March 1985 Sun Release 2.0 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) Here is a line from a .login file (oriented to the C-Shell): set mail=(10 /usr/spool/mail/$USER) This set command instructs the C-Shell to look in / usr/ spool/ mail/%USER for mail every 10 seconds and to notify you if there is mail waiting there. In the absence of the time specification, the Shell looks every five minutes. FILES /usr/spool/mail/* ~/mbox ~/.mailrc /tmp/R# /usr/lib/Mail.help* /usr/lib/Mail.rc /bin/mail /usr/lib/sendmail post office your old mail file giving initial mail commands temporary for editor escape help files system initialization file to do actual mailing postman SEE ALSO binmail(l), fmt(l), newaliases(8), aliases(5), sendmail(8), mailaddr(7), biff(l) Mail User’s Guide in the Beginner’s Guide to the Sun Workstation, which gives an excellent introduction. For sendmail installation instructions, see the Sun System Manager’s Manual. Sun Release 2.0 Last change: 25 March 1985 207 MAKE(l) USER COMMANDS MAKE(l) NAME make — maintain program groups SYNOPSIS make [ — f makefile ][—!][ — k ] I — n | [ ~ * ] [ “ r ] [ — 8 1 I — ' d ] [ — P ] [ — S ] [ — q ] file . » « DESCRIPTION Make executes commands in makefile to update one or more target files. File is typically a pro- gram. If no — f option is present, ‘makefile’ and ‘Makefile’ are tried in order. ‘Makefile’ with a capital M is the preferred choice since it appears towards the front of any list of files and thus tends to stand out. If makefile is make reads the standard input. More than one — f option may appear. Make updates a target if it depends on prerequisite files that have been modified since the target was last modified, or if the target does not exist. Makefile contains a sequence of entries that specify dependencies. The first line of an entry is a blank-separated list of targets, then a colon, then a list of prerequisite files. Text following a semicolon, and all following lines that begin with a tab, are shell commands to be executed to update the target. If a name appears on the left of more than one ‘colon’ line, then it depends on all of the names on the right of the colon on those lines, but only one command sequence may be specified for it. If a name appears on a line with a double colon :: then the command sequence following that line is performed only if the name is out of date with respect to the names to the right of the double colon, and is not affected by other double colon lines on which that name may appear. Two special forms of a name are recognized. A name like library(file) means the file named file stored in the archive named library. A name like library((entry)) means the file stored in archive library containing the entry point entry. Sharp and newline surround comments, except on lines containing shell commands. The following makefile says that program depends on the two files a.o and b.o and that they in turn depend on .c files and a common file called incl: program: a.o b.o cc a.o b.o — lm — o program a. o: incl a.c cc — c a.c b. o: incl b.c cc — c b.c Makefile entries of the form stringl = string2 are macro definitions. Subsequent appearances of ^(stringl) or ^{stringl} are replaced by strings. If stringl is a single character, the parentheses or braces are optional. Make infers prerequisites for files for which makefile gives no construction commands. For example, a .c file may be inferred as prerequisite for a .0 file and be compiled to produce the .0 file. Thus the preceding example can be done more briefly: program: a.o b.o cc a.o b.o — lm — o program a.o b.o: incl Prerequisites are inferred according to selected suffixes listed as the ‘prerequisites’ for the special name .SUFFIXES; multiple lists accumulate; an empty list clears what came before. Order is significant; the first possible name for which both a file and a rule as described in the next para- graph exist is inferred. The default list is 208 Last change: 1 February 1985 Sun Release 2.0 MAKE(l) USER COMMANDS MAKE(l) .SUFFIXES: .out .o .c .e .r .f .y .1 .s .p The rule to create a file with suffix $2 that depends on a similarly named file with suffix si is specified as an entry for the ‘target’ sls2. Before issuing any command, make sets certain special macros: $@ is set to the name of the file to be ‘made’. $? is set to the names of files that are younger than the target. $< is set to the name of the related file that caused the action, only if the command was generated by an implicit rule. $* is set to the prefix shared by the current and dependent filenames, only if the command was generated by an implicit rule. For example, a rule for making optimized .0 files from .c files is .c.o: ; cc — c — O — o $@ $*.c Certain macros are used by the default inference rules to communicate optional arguments to any resulting compilations. In particular, ‘CFLAGS’ is used for cc(l) options, ‘FFLAGS’ for /77(1) options, ‘PFLAGS’ for pc(l) options, and ‘LFLAGS’ and ‘YFLAGS’ for lex and yacc{ 1) options. In addition, the macro ‘MFLAGS’ is filled in with the initial command line options sup- plied to make. This simplifies maintaining a hierarchy of makefiles as one may then invoke make on makefiles in subdirectories and pass along useful options such as — k. Command lines are executed one at a time, each by its own shell. A line is printed when it is executed unless the special target .SILENT is in makefile, or the first character of the command is Commands returning nonzero status (see inlro(l)) cause make to terminate unless the special tar- get .IGNORE is in makefile or the command begins with . Interrupt and quit cause the target to be deleted unless the target is a directory or depends on the special name .PRECIOUS. OPTIONS — f myfile myfile is the name of the file to use for make commands instead of the default ‘makefile’ or ‘Makefile’. —1 Equivalent to the special entry .IGNORE:. — k When a command returns nonzero status, abandon work on the current entry, but con- tinue on branches that do not depend on the current entry. — n Trace and print, but do not execute the commands needed to update the targets. — t Touch, that is, update the modified date of targets, without executing any commands. — r Equivalent to an initial special entry .SUFFIXES: with no list. — s Equivalent to the special entry .SILENT:. — d debug; print internal state after each command — p print internal state after reading Makefile — q determines if the target is up to date — returns a zero exit status if it is, and a non-zero exit status otherwise. — S undoes the effect of the — k option. FILES makefile, Makefile Sun Release 2.0 Last change: 1 February 1985 209 MAKE(l) USER COMMANDS MAKE(l) SEE ALSO sh(l), touch(l), f77(l), pc(l) Make — A Program for Maintaining Computer Programs, in Programming Tools for the Sun Sys- tem. BUGS Some commands return nonzero status inappropriately. Use —1 to overcome the difficulty. Commands that are directly executed by the shell, notably cd(l), are ineffectual across newlines in make. Make should recognize names of libraries in the dependency entries, for example: grab: -lm grab.o cc -o grab grab.o -lm 210 Last change: 1 February 1985 Sun Release 2.0 MAN(l) 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 descriptions of commands specified by name, or for all commands whose description contains any of a set of keywords. 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 /usr/man/catf directories and uses the infor- mation 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 subroutines 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 ca£(l) with the —s option to crush out useless blank lines, uf(l) to create proper underlines for different terminals, and through more(l) 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 path/m&nl instead of in /usr/man/ 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 dev- ice which can actually handle troff’s output. FILES /usr/man/man?/* manual pages in nroff/troff source /usr/man/cat?/* formatted manual pages SEE ALSO more(l), ul(l), whereis(l), catman(8) Sun Release 2.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 u;r*fe(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 2.0 MKDIR(l) USER COMMANDS MKDIR(l) NAME mkdir — make a directory SYNOPSIS mkdir dirname ... DESCRIPTION Mkdir creates directories. Standard entries, for the directory itself, and for its parent, are made automatically. The current umask(2) setting determines the mode in which directories are created. Modes may be modified after creation by using chmod{ 1). Mkdir requires write permission in the parent directory. SEE ALSO chmod(l), rmdir(l), rm(l), umask(2), mkdir(2), rmdir(2) Sun Release 2.0 Last change: 15 March 1983 213 MKSTR(l) USER COMMANDS MKSTR(l) 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 direc- tory 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 ‘errorf" 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 mes- sage 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 efilname]] = ”/usr/lib/pi_strings"; Int efil = -1; error(al, a2, a3, a4) { char buf [256]; if (efil < 0) { efii = open(efilname, 0); If (efil < 0) { oops: perror(efilname); exit(l); } } If (lseek(efil, (long) al, 0) jj 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 lseek(2), xstr(l) 214 Last change: 1 November 1983 Sun Release 2.0 MORE ( 1 ) USER COMMANDS MORE ( 1 ) NAME more, page — browse through a text file SYNOPSIS more [ — cdflsu ] ( —lines ] [ +linenumber ] [ +/ pattern ] [ name ... ] page [ —cdflsu ] [ —lines ] [ +linenumber ] [ +/ pattern ] [ name ... ] DESCRIPTION More is a filter which displays the contents of a text file one screenful at a time on a video termi- nal. It normally 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 Jfc — 1 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 / etc/termcap to determine terminal characteristics, and to determine the default window 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 7 would cause all invocations of more , includ- ing 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) : » display i more lines, (or another screenful if no argument is given) D display 11 more lines (a “scroll”). If i is given, the scroll size is set to i. d same as 'D (control-D) iz same as typing a space except that i, if present, becomes the new window size. is skip i lines and print a screenful of lines if 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/ex pr search for the i-th occurrence of the regular expression expr. If there are less than » 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 command. in search for the i-th occurrence of the last regular expression entered. Sun Release 2.0 Last change: 13 March 1984 215 MORE ( 1 ) USER COMMANDS MORE ( 1 ) ’ (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. 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 "\!" are replaced by "%" and "!" respectively. t:n skip to the i-th next file given in the command line (skips to last file if n doesn’t make sense) t':p skip to the t-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 t 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 can- cel 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 control— \). 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 screen- ful. This is useful if more is being used as a filter in some setting, such as a class, where users are unsophisticated. — f Count logical rather than screen lines. That is, long lines are not folded. This option is recommended 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 actu- ally are, and fold lines erroneously. —1 Do not treat *L (form feed) specially. If -/ is not used, more pauses after any line that contains a *L, 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. 216 Last change: 13 March 1984 Sun Release 2.0 MORE ( 1 ) USER COMMANDS MORE ( 1 ) — 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 informa- tion present on the screen. — u Normally, more handles underlining such as produced by nroff in a manner appropriate to the particular 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 pro- cessing. -f linenumber Start up at linenumber. -8-/ pattern 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.help Help file SEE ALSO csh(l), man(l), script(l), sh(l), environ(5), termcap(5) Sun Release 2.0 Last change: 13 March 1984 217 MT( 1 ) USER COMMANDS MT( 1 ) NAME mt — magnetic tape manipulating program SYNOPSIS mft [ — f tapename ] command [ count ] DESCRIPTION mt sends commands to a magnetic tape drive. If tapename is not specified, the environment vari- able TAPE is used; if TAPE does not exist, mt uses the device /dev/rmtlS. Note that tapename must reference a raw (not block) tape device. By default mt performs the requested operation once. Operations may be performed 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, far Forward space count records, bsf Back space count files, bar 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. retenaion Retension the tape. erase Erase the entire tape. mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecog- nized, 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 SEE ALSO mtio(4), dd(l), ioctl(2), environ(5) BUGS Not all devices support all commands. For example, ar(4s) and a<(4s) currently do not support the far, bsf, or bar commands; but they are the only only ones that currently support the retension and rewind commands. 218 Last change: 04 February 1985 Sun Release 2.0 MV ( 1 ) USER COMMANDS MV ( 1 ) NAME rav — move or rename files SYNOPSIS mv [ — 1 ] [ — f ] [ — ] filel file2 mv [ — I ] [ — f ] [ — ] directoryl directory2 mv [ — 1 ] [ — f ] [ — ] file . . . directory . . . directory DESCRIPTION Mv moves files and directories around in the file system. A side effect of mv is to rename a file or directory. The three major forms of mv are shown in the synopsis above. The first form of mv moves (changes the name of) filel to file2. If file2 already exists, it is removed before filel is moved. If fileS 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 direc- toryS does not already exist — if it does, the third form applies. The third form of mv moves one or more files and directories, with their original names, to the last directory 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 whenever 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 warning 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 filel and file2 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 2.0 Last change: 16 February 1984 219 NICE ( 1 ) USER COMMANDS NICE ( l ) 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 termi- nal. 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 sh( 1). If you use csft(l), then commands executed with are automatically immune to hangup signals while in the background. There is a builtin com- mand nohup which provides immunity from terminate, but it does not redirect output to nohup.out. Nice is built into csh( 1) 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 2.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 symbol table entries (see —a below). If the symbol is local (non-external) the type letter is in lower case. The output is sorted alpha- betically. 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. — f 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 compiler- SEE ALSO ar(l), ar(5), a.out(5) Sun Release 2.0 Last change: 9 June 1983 221 NROFF ( 1 ) USER COMMANDS NROFF ( 1 ) NAME nroff — text formatting and typesetting SYNOPSIS nroff [ — o pagelist ] [ — niVj [ — sTV] [ — m name ] [ — raTV] [ — 1 ] [ — q ] [ — T name ] [ — e j [ — h ][ file ] ... DESCRIPTION Nroff formats text in the named files for typewriter-like devices. See also troff( 1). The full capa- bilities 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 TV to the end. — n TV Number first generated page TV. — sTV Stop every TV pages. Nroff will halt prior to every TV pages (default TV=1) to allow paper loading or changing, and will resume upon receipt of a newline. — m name Prepend the macro file /uBr/lib/tmae/tmac.name to the input files. —raN Set register a (one-character) to TV. —1 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), 300S DASI-300S 300 DASI-300 300X DASI-300X 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). lpr Line printer. xl700 Xerox 1700 daisywheel 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 uaers.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 222 Last change: 1 February 1985 Sun Release 2.0 NROFF(l) USER COMMANDS NROFF(l) /usr/lib/term/* terminal driving tables for nroff SEE ALSO Formatting Documents with Nroff and Troff in Editing and Text Processing on the Sun Worksta- tion. troff(l), eqn(l), tbl(l), ms(7), me(7), man(7), col(l), checknr(l) Sun Release 2.0 Last change: 1 February 1985 223 0D( 1 ) USER COMMANDS OD(l) 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, return=\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. 1 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 out- put, 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 argu- ment must be preceded by The radix of the displayed address will be the same as the radix of the offset, if specified; other- wise it will be octal. Label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in “()” following the file offset. It is intended to be used with core images to indicate the real memory address. The syntax for label is identical to that for offset. SEE ALSO adb(l) 224 Last change: 8 March 1984 Sun Release 2.0 OD ( 1 ) USER COMMANDS OD(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. It is an historical botch to require specification of object, radix, and sign representation in a sin- gle character argument. Sun Release 2.0 Last change: 8 March 1984 225 PAGESIZE(l) USER COMMANDS PAGESIZE(l) NAME pagesize — print system page size SYNOPSIS pagesize DESCRIPTION Pagesize prints the size of a page of memory in bytes, as returned by getpagesize(2). This pro- gram is useful in constructing portable shell scripts. SEE ALSO getpagesize(2) 226 Last change: 3 April 1983 Sun Release 2.0 PASSWD ( 1 ) USER COMMANDS PASSWD ( 1 ) NAME passwd — change login password SYNOPSIS passwd [ — f filename ] [ user-ID ] DESCRIPTION This command changes (or installs) a password associated with the user-ID (your own by default). Passwd prompts for the old password and then for the new one. You must supply both, and the new password must be typed twice to forestall mistakes. New passwords must be at least four characters long, if they use a sufficiently rich alphabet, or at least six characters long if in monocase. Only the owner of the name or the super-user may change a password; the owner must prove he knows the old password. OPTIONS — f Treat file as the password file. FILES /etc/passwd /etc/yp/passwd SEE ALSO login(l), passwd(5), crypt(3), yppasswd(l) Robert Morris and Ken Thompson, UNIX Password Security BUGS Passwd will not change your password if your system uses the yp Yellow Pages name server. Refer to yppasswd(l) for more information. Sun Release 2.0 Last change: 1 February 1985 227 PC ( 1 ) USER COMMANDS PC(1) NAME pc — Pascal compiler SYNOPSIS pc [ — c ] [ — g ] [ — o output ] [ — O ] [ — b ] [ — C ] [ —fsky ] [ — H ] | —l name . . . ] [ —I ] [ — Ipfc ] [ — L ] [ — P ] [ — a ] [ — S ] [ — z j 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 .0 in place of .p). Object files may then be loaded into an execut- able 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 .k files included by all the .p files which call those routines. Pascal’s calling conventions are the same as in C, with var parameters passed by address and other parameters passed by value. Both pc and pt(l) support 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( 1) for load-time options. — c Suppress loading and produce .0 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, verify assert statements, and initialize all variables to zero as in pi. Note that pointers are not checked. This option differs significantly from the -C option of the cc compiler. —fsky Generate code which assumes the presence of a SKY floating-point processor board. Pro- grams compiled with this option can only be run in systems that have a SKY board installed. Programs compiled without the —fsky option will use the SKY board from library routines, but won’t run as fast as they would if the —fsky option were used. If any part of a program is compiled using the —fsky option, you must also use this option when linking with the pc command, since different startup routines are used to initialize the SKY board. — H Compile code to perform range checks on pointers into the heap. —I name 228 Last change: 1 February 1985 Sun Release 2.0 PC(1) USER COMMANDS PC(1) Produce a listing for the specified procedures, functions and Include files. — 1 Make a program listing during translation. — Ipfc Load common startup code for programs containing mixed Pascal and FORTRAN object files. Such programs should also be loaded with the FORTRAN libraries (see flies below). — L Map upper case letters in keywords and identifiers to lower case. — P Use partial evaluation semantics for the boolean operators and and or. For these opera- tors only, left-to-right evaluation is guaranteed, and the second operand is evaluated only if necessary to determine the result. —s Accept standard Pascal only; nonstandard constructs cause warning diagnostics. — S Compile the named program, and leave the assembly language output on the correspond- ing file suffixed ‘.s’. No ‘.o’ is created. —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. Other arguments are taken to be loader option arguments or libraries of pc compatible routines. Certain flags can also be controlled in comments within the program, as described in the Pascal User '8 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 /usr/lib/libpfc.a grams /usr/lib/libF77.a /usr/lib/libI77.a /usr/lib/libU77.a /usr/lib/libm.a /lib/libc.a SEE ALSO Pascal source files macro preprocessor compiler 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 startup code for combined Pascal and FORTRAN pro- FORTRAN intrinsics library FORTRAN I/O library FORTRAN<=>Unix interface library math library standard library, see intro( 3) The Pascal User’s Manual in the Sun Pascal 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 ‘...’. Sun Release 2.0 Last change: 1 February 1985 229 PC(1) USER COMMANDS PC(1) 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 sideeffects. 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 sfn'p(l) after they are compiled. 230 Last change: 1 February 1985 Sun Release 2.0 PERFMETER ( 1 ) USER COMMANDS PERFMETER ( 1 ) NAME perimeter — meter display of system performance values SYNOPSIS perfmeter [ — b sampletime ) [ — h hourhandintv ] [ — m minutehandintv ] [ — 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 host- name. In either case, the rstatd(8) daemon must be running on the machine for which statistics are being reported. OPTIONS — a 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. — v value Set the cpu pkts page swap disk Intr cntxt performance value to be monitored to one of: percent of cpu being utilized ethernet packets per second paging activity in pages per second jobs swapped per second disk traffic in transfers per second number of device interrupts per second number of context switches per second 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 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) Sun Release 2.0 Last change: 1 February 1985 231 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 approximately 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 char- acters while the mouse is in the graphics subwindow: a increases the interval by 0.05 seconds (small 8 means get slower by a little). S increases the interval by one second (capital 5 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 T 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. 232 Last change: 1 February 1985 Sun Release 2.0 PI(1) USER COMMANDS PI(1) NAME pi — Pascal interpreter code translator SYNOPSIS pi [ -b ] [ -1 ] [ -L 1 [ -n 1 [ -o name ][ -p j [-«] | -t ][-«][ -w | [ -s ] [ —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 ‘load 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 com- ments 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. —1 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 counting. — a 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 tutorial% 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 Sun Release 2.0 Last change: 7 November 1984 233 PI(1) USER COMMANDS PI(1) 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 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. 234 Last change: 7 November 1984 Sun Release 2.0 PEX(l) USER COMMANDS PDC(l) NAME pix — Pascal translator and interpreter SYNOPSIS Pi* [ options ] [ —1 name ... j 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 translation, 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 des- troyed. 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 tutoriaI% pix Sun Release 2.0 Last change: 7 November 1984 235 PLOT(IG) USER COMMANDS PLOT ( 1G ) NAME plot — graphics filters SYNOPSIS plot [ — Tterminal [ raster ] ] 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 terminals 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). ver Versatec D1200A printer-plotter. This version of plot places a scan-converted image in /usr/tmp/raster and sends the result directly to the plotter device rather than to the standard output. The optional argument sends a previously scan-converted file called raster to the plotter. FILES /usr/bin/tek /usr/bin/t450 /usr/bin/t300 /usr/bin/t300s /usr/bin/vplot /usr/tmp/raster SEE ALSO plot(3X), plot(5) BUGS There is no lockout protection for /usr/tmp/raster. 236 Last change: 1 November 1983 Sun Release 2.0 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. Sun Release 2.0 Last change: 11 November 1983 237 POSTNEWS ( 1 ) USER COMMANDS POSTNEWS ( 1 ) NAME postnews — submit news articles SYNOPSIS postnews [ article ] DESCRIPTION Postnews calls up the ineu;9(l) utility to submit news articles to USENET. Postnews prompts you for the title of the article, for the newsgroup, and for the distribution. The title of the article should be a phrase suggesting the subject, so that persons reading the news can tell if they are interested in the article. If you omit the name of the newsgroup (by typing a carriage-return when asked for the news- group), postnews posts the article to general. general is read by everyone on the local machine. Other possible newsgroups include, but are not limited to, btl. general, read by all users at all Bell Labs sites on USENET, net. general, read by all users at all sites on USENET, and net. news, read by users interested in the network news on all sites. There is often a local set of newsgroups, such as ucb.all, that circulate within a local set of machines. In this case, ucb newsgroups circulate among machines at the University of Cali- fornia at Berkeley. The distribution can be any valid list of newsgroup names, and defaults to the same as the news- group. If they are the same, the distribution is omitted from the headers put into the editor buffer. A distribution header is included in the headers of the article if given, affecting where the article is distributed to. After entering the title, newsgroup, and distribution, postnews calls up an editor program where you can compose the article. Postnews uses trc'(l) as the editor unless you have specified another editor via the SEDITOR environment variable, in which case postnews uses the editor specified there. An initial set of headers containing the subject and newsgroups will be placed in the editor, fol- lowed by a blank line. The article should be appended to the buffer, after the blank line. These headers can be changed, or additional headers added, while in the editor, if desired. Optionally, the article is read from the file specified by article. For more sophisticated uses, such as posting news from a program, see inews( 1). SEE ALSO mail(l), checknews(l), inews(l), readnews(l). 238 Last change: 6 January 1984 Sun Release 2.0 PR(1) USER COMMANDS PR( 1 ) NAME pr — print file(s), possibly in multiple columns SYNOPSIS pr [ — n ] | +n ] [ — h string j [ -wit ] [ — f ] [ —In ] [ — t ] [ —wn ] [ — m ] [ file ] .. . 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 arguments. Inter-terminal messages via uirile(l) are forbidden during a pr. OPTIONS Options apply to all following file's but may be reset between file’s: — n Produce n-column output. 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. For purposes of multi-column output, take the width of the page to be n characters instead of the default 72. 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. Take the length of the page to be n lines instead of the default 66. 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 was used. The — t option is intended for applications where the results should be directed to a file for further processing. 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. Print all file’s simultaneously, each in one column, file called dreadnought on the printer — this is the simplest use of pr: krypton% pr dreadnaught j lpr krypton% 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: krypton% pr — m — t ridings ridings ridings > Yorkshire krypton% 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. — wn -f -In -t —sc — m EXAMPLES Print a Sun Release 2.0 Last change: 16 February 1984 239 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) 240 Last change: 24 February 1979 Sun Release 2.0 PRMAIL ( 1 ) USER COMMANDS PRMAIL ( 1 ) NAME prmail — print out waiting mail SYNOPSIS prmail [ user ... ] DESCRIPTION Prmail prints the mail which waits for you, or the specified users. The mail is not disturbed. FILES /usr/spool/mail/* waiting mail files SEE ALSO biff(l), mail(l), from(l), binmail(l) Sun Release 2.0 Last change: 7 March 1984 241 PROF ( 1 ) USER COMMANDS PROF ( 1 ) NAME prof — display profile data SYNOPSIS prof [ -a ] | -1 ] [ — n ] [ — s ] [ — v [ -low [ -high ]]][-*][ 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, /77 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. —I Sort the output by symbol value. — n sort the output by number of calls. —a 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 p/of(lG) 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 reso- lution. —i 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), profil(2), cc(l), plot(lG), gprof(l) BUGS Prof is confused by /77 which puts the entry points at the bottom of subroutines and functions. 242 Last change: 8 October 1984 Sun Release 2.0 PRS ( 1 ) USER COMMANDS PRS ( 1 ) NAME prs — print an SCCS file SYNOPSIS /usr/sccs/prs [ — d [ dataspec] ] [ — r[5/D] ] [ — e ] | — 1 ] [ — a ] file ... 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 keywords (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 desig- nated via the — r option. —1 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 infomation 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 \fc and carriage return/new-line is specified by \n. Sun Release 2.0 Last change: 20 March 1984 243 PRS ( 1 ) USER COMMANDS PRS ( 1 ) 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 M :Li:/:Ld:/:Lu: S :Li: Lines inserted by Delta W nnnnn S :Ld: Lines deleted by Delta It nnnnn S :Lu: Lines unchanged by Delta w nnnnn S :DT: Delta type w D or R S :I: SCCS ID string (SID) H :R:.:L:.:B:.:S: S :R: Release number H nnnn S :L: Level number M nnnn S :B: Branch number H nnnn S :S: Sequence number M nnnn S :D: Date Delta created M :Dy:/:Dm:/:Dd: S :Dy: Year Delta created W nn S :Dm: Month Delta created M nn S :Dd: Day Delta created »♦ nn S :T: Time Delta created M :Th:::Tm:::Ts: S :Th: Hour Delta created H nn S :Tm: Minutes Delta created M nn S :Ts: Seconds Delta created N nn S :P: Programmer who created Delta *« logname S :DS: Delta sequence number M nnnn S :DP: Predecessor Delta seq-no. ♦1 nnnn S :DI: Seq-no. of deltas inch, excl., ignored H :Dn:/:Dx:/:Dg: S Dn: Deltas included (seq #) H :DS: :DS: ... S Dx: Deltas excluded (seq #) M :DS: :DS: ... S Dg: Deltas ignored (seq #) M :DS: :DS: ... S MR: MR numbers for delta W text M C: Comments for delta ” text M UN: User names User Names text M FL: Flag list Flags text M Y: Module type flag ♦I text S MF: MR validation flag •I yet or no S MP: MR validation pgm name ff text s KF: Keyword error/warning flag ♦« yet or no s BF: Branch flag It yet or no s J: Joint edit flag It yet or no s LK: Locked releases ♦♦ :R: ... s Q: User defined keyword •l text s M: Module name II text s FB: Floor boundary ♦I :R: s CB: Ceiling boundary w :R: s Ds: Default SID ii :I: s ND: Null delta flag ii yet 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 wAat(l) string N/A :Z::M:\t:I: s -A: A form of what( 1) string N/A :Z::Y: :M: :I::Z: s Z: what( 1 ) string delimiter N/A @(#) s F: SCCS file name N/A text s PN: 244 SCCS file path name N/A Last change: text 20 March 1984 s Sun Release 2.0 PRS ( 1 ) USER COMMANDS PRS(l) * sDts - :DTj sis :D: :T: jPj :DSj sDPs Sun Release 2.0 Last change: 20 March 1984 245 PRS ( 1 ) USER COMMANDS PRS ( 1 ) EXAMPLES /usr /sccs/prs — d’Users and/or user IDs for :F: are:\n:UNs" 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 bl79- 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( 1) for explanations. 246 Last change: 20 March 1984 Sun Release 2.0 PS(1) USER COMMANDS PS(1) NAME ps — process status SYNOPSIS ps [ acCegklsStuvwx# ] [ kernel_name ] [ c^dump^file ] [ swap_file ] DESCRIPTION Ps displays information about processes. Normally, only processes that you have started are can- didates to be displayed by ps, but see the OPTIONS section below for how to get more informa- tion. 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 pro- cess — 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 shows; 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. Fourth 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 garbage 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. Kernel^name 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 /vmcore and this argument is ignored. Swap_fi.le gives the location of a swap file other than the default, /dev/ drum. Sun Release 2.0 Last change: 1 February 1985 247 PS(1) USER COMMANDS PS(1) OPTIONS a Display information about all processes with terminals (ordinarily only one’s own processes are displayed). 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_file is ignored, and 8wap_file defaults to /dev/ drum. With the k option in effect, these arguments default to / vmunix, /vmcore, and / 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 maintainers) 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, tS 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 arbi- trarily wide output. This information is used to decide how much of long commands to print. x Display even those processes with no terminal. # 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 previ- ous (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 1024 byte units) RSS real memory (resident set) size of the process (in 1024 byte 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. 248 Last change: 1 February 1985 Sun Release 2.0 PS(1) USER COMMANDS PS ( 1 ) 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) PRI process priority (non-positive when in non-interruptible wait) ADDR swap address of the process 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 examin- ing memory or the swap area. The method is inherently somewhat unreliable and in any event a process is entitled to destroy this information, 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) Sun Release 2.0 Last change: 1 February 1985 249 PS(1) USER COMMANDS PS(1) BUGS Things can change while ps is running; the picture it gives is only a close approximation to real- ity. 250 Last change: 1 February 1985 Sun Release 2.0 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( 1) using troff’s — t option, interpreting them as they would act on the typesetter. Horizontal motions shows as counts in internal units and are marked with *<’ and *>’ indicating left and right motion. Vertical space is called leading and is also indicated. 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) Sun Release 2.0 Last change: 13 April 1983 251 PTX(l) USER COMMANDS PTX(l) NAME ptx — permuted index SYNOPSIS ptx [ — f ] [ — t | [ — w n ] [ — g n ] [ — o only ] [ —I ignore ] [ — b break ] [ — r ] [ input [ output ] ] DESCRIPTION Ptx generates a permuted index of the contents of file input onto file output (defaults are stan- dard 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 nroff{ 1) or troff( 1) macro for user-defined formatting. The before keyword and keyword 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 discarded, */’ 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 n Use the next argument, n, as the width of the output line. The default line length is 72 characters. — g n 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. —lignore Do not use as keywords any words given in the ignore file. If the —I and — o options are missing, use /usr/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 characters 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. 252 Last change: 1 November 1983 Sun Release 2.0 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 illustrates the differences. % cd /usr/wendy /January /reports % pwd /usr/wendy/january/re ports % dirs /january /reports % mv “/January “/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 example: % cd /usr/wendy /January /reports % pwd /usr/wendy/january/reports % dirs /january/reports % Is —1 /usr/wendy /January lrwxrwxrwx 1 wendy 17 Jan 30 1983 /usr/wendy /january -> /usr/wendy/l984/jan/ % cd /usr/wendy /January % pwd /usr/wendy/1984/jan % dirs /usr/wendy /january They may also report different pathnames if you have changed directories through a symbolic link. SEE ALSO cd(l), csh(l), getwd(3) Sun Release 2.0 Last change: 1 February 1985 253 PX(1) USER COMMANDS PX(1) NAME px — Pascal interpreter SYNOPSIS px [ obj [ argument ... ] ] DESCRIPTION Px interprets the abstract machine code generated by pi. The first argument is the file to be interpreted, and defaults to obj; remaining arguments are available to the Pascal program using the built-ins argv and argc. Px is also invoked by pix when running ‘load and go’. 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 termina- tion. The p option of pi suppresses all of this except the message indicating the cause of abnor- mal termination. FILES obj default object file pmon.out profile data file SEE ALSO The Pascal 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 diag- nostic. 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. 254 Last change: 1 November 1984 Sun Release 2.0 PXP(l) USER COMMANDS PXP(l) NAME pxp — Pascal execution profiler SYNOPSIS pxp ( — acdef]Lnstuw_ ] [ —23450780 ] [ — t [ name ... ) ] name.p DESCRIPTION Pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To pro- duce an execution profile all that is necessary is to translate the program specifying the z option to pc, pi, or pix, execute 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 tutoriaI% 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 Pas- cal 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 refor- matted contents 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. — b 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. — * Generate an execution profile. If no names 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 Sun Release 2.0 Last change: 7 November 1984 255 PXP(l) USER COMMANDS PXP(l) SEE ALSO The Pascal User’s Manual in the Sun Pascal Manual. pc(l)i 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 e 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. 256 Last change: 7 November 1984 Sun Release 2.0 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. Sun Release 2.0 Last change: 11 November 1983 257 RANLIB ( 1 ) USER COMMANDS RANLIB(l) NAME ranlib — convert archives to random libraries SYNOPSIS ranlib archive ... DESCRIPTION Ranlib converts each archive to a form which the loader can load more rapidly. Ranlib does this by adding a table of contents called _.SYMDEF to the beginning of the archive. Ranlib uses ar(l) 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(I), 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 loader, Id, 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 2.0 RASTREPL ( 1 ) USER COMMANDS RASTREPL ( 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 format (see /usr/ include/ rasterfile.h), replicates each pixel in both the x and y direc- tions, and writes the resulting rasterfile to output-file (or the standard output if output-file is not specified). EXAMPLES tutorial% screendump J rastrepl | Ipr — 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) Sun Release 2.0 Last change: 5 November 1984 259 RATFOR(l) USER COMMANDS RATFOR(l) NAME ratfor — rational Fortran dialect SYNOPSIS ratfor [ —8 c ] [ — C j [ — h ] [ filename . . . ] DESCRIPTION Ratfor converts a rational dialect of Fortran into ordinary irrational Fortran. Ratfor provides control flow constructs essentially identical to those in C: statement grouping: { statement; statement; statement } decision- making: if (condition) statement [ else statement ] switch (integer value) { case integer: statement [ default: ] statement } loops: while (condition) statement for (expression; condition; expression) statement do limits statement repeat statement [ until (condition) ] break next and some syntactic sugar to make programs easier to read and write: free form input: multiple statements/line; automatic continuation comments: # this is a comment translation of relatlonals: >, >=, etc., become .GT., .GE., etc. return(expression) returns expression to caller from function define: define name replacement include: include filename Ratfor is best used with /7 7(1). OPTIONS —6c Use the character c as the continuation character in column 6 when translating to For- tran. The default is to use the & character as a continuation character. — C Pass Ratfor comments through to the translated code. —hi Translate Ratfor string constants to Hollerith constants of the form nnnh string. Other- wise just pass the strings through to the translated code. SEE ALSO 177(1) B. W. Kernighan and P. J. Plauger, Software Tools, Addison-Wesley, 1976. 260 Last change: 26 April 1983 Sun Release 2.0 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 “rhostrpath”, or a local file name (containing no characters, or a '/’ 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 rsA(lC). Rep handles third party copies, where neither source nor target files are on the current machine. Hostnames may also take the form “rhost. rname” 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 command 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. Sun Release 2.0 Last change: 25 October 1984 261 READ NEWS ( 1 ) USER COMMANDS READNEWS ( 1 ) NAME readnews — read news articles SYNOPSIS readnews [ —a date ] [ —n newsgroups ] | — t titles ] [ — IprxhftiM ] [ — c [ mailer j ] % readnews — s DESCRIPTION Readnews without argument displays unread articles, readnews — s displays the newsgroup subscription list. Readnews maintains a . newsrc file in your home directory that specifies all news articles already read, .newsrc is updated at the end of each news reading session in which the — x or —I options weren’t specified. If the NEWSRC environment variable is present, it should be the path name of a file to be used in place of .newsrc. An options line may be placed in the .newsrc file. The options line starts with the word options (left justified) followed by the list of standard options just as they would be typed on the read- news command line. The list of options may include: the — n flag along with a newsgroup list; a favorite interface to use for reading the news; and/or the — r or — t flag. Continuation lines are specified by following lines beginning with a space or tab character. Similarly, options can be specified in the NEWSOPTS environment parameter. Options on the command line override options in the .newsrc file and options in the .newsrc file override options in the NEWSOPTS environment parameter. When you use the reply command of the mail(l) or /bin/mail( l) interfaces, readnews uses the MAILER environment parameter to determine which mailer to use. The default is usually mail. You can specify a particular paging program for paging through articles. The PAGER environ- ment parameter should be set to the name of the paging program. The name of the article is referenced with a as in the — c option. If no '%' is present, the article is piped to the pro- gram. Paging may be disabled by setting PAGER to a null value. OPTIONS Some of the option flags determine which of the several interfaces you can use for reading your news. The news system has its own interface which is used if no other choice is made, otherwise one of these options can be used: — M An interface to mail(l). — c A /bin/mail( 1)— like interface. — c ‘mailer’ All selected articles written to a temporary file. Then the mailer is invoked. The name of the temporary file is referenced with a '%'. Thus, ‘mail -f %’ will invoke mail on a temporary file consisting of all selected messages. Other options govern the behavior of readnews itself, as follows: — p Send all selected articles to the standard output with no questions asked. —1 Display only the titles. Do not update the .newsrc file. — r display the articles in reverse order. — f Do not display any followup article —is Display articles in a less verbose format (intended for terminals running at 300 baud). — u Update the .newsrc file every 5 minutes, in case of an unreliable system. Note that if the .newsrc file is updated, the x command will not restore it to its original contents. 262 Last change: 7 March 1984 Sun Release 2.0 READNEWS ( 1 ) USER COMMANDS READNEWS ( 1 ) The following flags determine the selection of articles: — n newsgroups Select all articles that belong to newsgroups. — t titles Select all articles whose titles contain one of the strings specified by titles. — © [ date j Select all articles that were posted past the given date (in mm/dd format). — x Ignore .newsrc file. That is, select articles that have already been read as well as new ones. COMMANDS This section lists the commands you can type to the readnews and /bin/mail interface prompts. The readnews interface suggests some common commands in brackets. Just typing carriage- return is the same as typing the first command. For example, ‘[ynq]’ means that the commands *y’ (yes), ‘n’ (no), and ‘q’ (quit) are common responses, and that ‘y’ is the default. Here are the commands and their meanings: y Yes — displays current article and goes on to next. n No — goes on to next article without displaying current one. In the /bin/ mail interface, this means ‘go on to the next article’, which has the same effect as ‘y’ or just typing carriage-return. q Quit — the .newsrc file is updated if —1 or — x were not on the command line, c Cancel the article — only the author or the super user can do this. r Reply — reply to article’s author via mail. Readnews calls up your EDITOR with a header specifying To, Subject, and References lines taken from the message. You may change or add headers, as appropriate. You add the text of the reply after the blank line, and then exit the editor. The resulting message is mailed to the author of the arti- cle. Reply directly — readnews calls up the mail program (or the program specified in the SMAILER environment variable) so that you can reply to the author. Type the text of the reply and then control-D. Submit a follow up article. Normally you should leave off the title, since the system gen- erates one for you. Readnews calls up your EDITOR so that you can compose the text of the followup. fd Followup directly, without edited headers. This is like /, but the headers of the article are not included in the editor buffer. N [neuwyroup] Go to the next newsgroup or named newsgroup. s [file] Save — the article is appended to the named file. The default filename is Articles. If the first character of the filename is ‘J’, the rest of the filename is taken as the name of a program, which is executed with the text of the article as standard input. If the first character of the filename is it is taken as a full path name of a file. If the SNEWSBOX environment variable is set to a full path name, and the filename contains no ‘/’, the file is saved in SNEWSBOX, otherwise, it is saved relative to $HOME. # Report the name and size of the newsgroup. e Erase — forget that this article was read. h Print a more verbose header. H Print a very verbose header, containing all known information about the article. rd f [title] Sun Release 2.0 Last change: 7 March 1984 263 READ NEWS ( 1 ) USER COMMANDS READ NEWS ( 1 ) U Unsubscribe from this newsgroup. Also goes on to the next newsgroup. d Read a digest. Breaks up a digest into separate articles so you can read and reply to each piece. D Decrypt — invokes a Caesar decoding program on the body of the message. This is used to decrypt rotated jokes posted to net.jokes. Such jokes are usually obscene or otherwise offensive to some groups of people, and so are rotated to avoid accidental decryption by people who would be offended. The title of the joke should indicate the nature of the problem, enabling people to decide whether to decrypt it or not. Normally the Caesar program does a character frequency count on each line of the arti- cle separately, so that lines which are not rotated will be shown in plain text. This works well unless the line is short, in which case it sometimes gets the wrong rotation. An explicit number rotation (usually 13) may be given to force a particular shift. v Print the current version of the news software. ! Shell escape. number Go to number. + [n] Skip n articles. The articles skipped are recorded as ‘unread’ and will be offered to you again the next time you read news. — Go back to last article. This is a toggle, typing it twice returns you to the original arti- cle. x Exit — like quit except that .newsrc is not updated. X system Transmit article to the named system. The c, f, fd, r, rd, e, h, H, and s commands can be followed by -’s to refer to the previous arti- cle. Thus, when replying to an article using the readnews interface, you should normally type ‘r— ’ (or ‘re-’) since by the time you enter a command, you are being offered the next article. EXAMPLES readnews Read all unread articles using the readnews( 1) interface. The .newsrc file is updated at the end of the session. readnews — c ed % —1 Use the ed(l) text editor on a file containing the titles of all unread articles. The .newsrc file is not updated at the end of the session. readnews — n all Ifa.all — M — r Read all unread articles except articles whose newsgroups begin with IB fa . via mail(l) in reverse order. The .newsrc file is updated at the end of the session. readnews — p — n all —a last thursday Print every unread article since last Thursday. The .newsrc file is updated at the end of the session. readnews — p > /dev/null & Discard all unread news. This is useful after returning from a long trip. FILES /usr /spool/news/ newsgroup / number News articles /usr /lib/news/active Active newsgroups and numbers of articles /usr/lib/news/help Help file for readnews(l) interface “/.newsrc Options and list of previously read articles 264 Last change: 7 March 1984 Sun Release 2.0 READ NEWS ( 1 ) USER COMMANDS READ NEWS ( 1 ) SEE ALSO checknews(l), inews(l), sendnews(8), recnews(8), uurec(8), mail(l), news(5), newsrc(5) Sun Release 2.0 Last change: 7 March 1984 265 RECNEWS (8) MAINTENANCE COMMANDS RECNEWS (8) NAME recnews — receive unprocessed articles via mail SYNOPSIS /usr/Hb/newB/recnewB [ newsgroup [ sender ] ] DESCRIPTION Recnews reads a letter from the standard input; determines the article title, sender, and news- group; and gives the body to inews with the right arguments for insertion. If newsgroup is omitted, the to line of the letter is used. If sender is omitted, the sender is deter- mined from the from line of the letter. The title is determined from the subject line. SEE ALSO inews(l), uurec(8), sendnews(8), readnews(l), checknews(l) 266 Last change: 6 January 1984 Sun Release 2.0 REFER ( 1 ) USER COMMANDS REFER ( 1 ) NAME refer — find and insert literature references in documents SYNOPSIS refer [ —a r ] [ — b ] [ — c string ] [ — e ] [ — kz ] [ — 1 m,n ] [ — p file ] [ — n ] [ —akeys ] file ... DESCRIPTION Refer is a preprocessor for nroff{ 1), or troff( 1), 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 bibliographic 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(7) 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( l), or fi/(l), refer should be used first in the sequence, to minimize the volume of data passed through pipes. OPTIONS —a r 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). — c string 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$ •1 is encountered, and then write out all references collected so far. Collapse references to the same source. — kz Instead of numbering references, use labels as specified in a reference data line beginning with the characters %x ; By default, x is L. — lm,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. —akeys 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 — bA+T. FILES /usr/dict/papers directory of default publication lists and indexes /usr /lib/refer directory of programs Sun Release 2.0 Last change: 29 April 1983 267 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. 268 Last change: 16 March 1983 Sun Release 2.0 RLOGIN(IC) USER COMMANDS RLOGIN(IC) NAME rlogin — remote login SYNOPSIS rlogin rhost [ — ec ] [ —I username ] [ —8 ] rhost [ — ec ] [ —1 username J [ —8 ] DESCRIPTION Rlogin connects your terminal on the current local host system Ihost to the remote host system rhost. Each host has a file / etc/hosts. equiv which contains a list of rhost' s with which it shares account names. (The host names must be the standard names as described in rsA(lC).) When you rlogin as the same user on an equivalent host, 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 as in login(l). 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 ‘S and ~Q and flushing of input and output on interrupts are handled properly. ESCAPES Lines starting 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. ~*Z Suspend the login session (only if you are using the C-Shell). Susp is your ‘suspend’ char- acter — usually control-Z — see tty(l). ~*Y 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 control-Y — see Ry(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/* for rhost version of the command /etc/hosts to translate hostname to network address /etc/hosts. equiv list of rhosts with shared account names /•rhosts private list of rhosts with shared account names /etc/services to translate service name tcp/rlogin to network port number BUGS Sun Release 2.0 Last change: 1 February 1985 269 RLOGIN(IC) USER COMMANDS RLOGIN(IC) This implementation can only use the TCP network service. More terminal characteristics should be propagated. 270 Last change: 1 February 1985 Sun Release 2.0 RM( 1 ) USER COMMANDS RM( 1 ) NAME rm, rmdir — remove (unlink) files or directories SYNOPSIS rm [ — f ] ( — r ] [ — 1 ] [ — j file ... rmdir dir ... DESCRIPTION rm.l:.IX "rm command" "" "rm — remove file or directory" rm.l:.IX "remove file or directory" "remove file or directory — rm" rm.l:.DC "delete file or directory" "" "delete file or direc- tory — rm" Rm removes the directory entries for one or more files. If an entry was the last link to the file, the file is destroyed. Rm —r and rmdir remove entries for directories. To remove a file, you must have write permission in its directory; but you don’t need read or write permission 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. To remove a full directory, use rm with the — r option (see below). Rmdir removes the named directory only if it is empty. OPTIONS The following are options for rm: — f Force files to be removed, without displaying permissions, asking questions, or reporting errors. — r Recursively delete the entire contents of the specified directory and the directory itself. —I Ask whether to delete each file, or, under — r, whether to examine each directory. Some- times called the Interactive option. — Treat all the following arguments as filenames — so that you can specify filenames start- ing 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), rmdir(2), unlink(2) Sun Release 2.0 Last change: 2 November 1983 271 RMDEL ( 1 ) USER COMMANDS RMDEL ( 1 ) NAME rmdel — remove a delta from an SCCS file SYNOPSIS /usr /sees /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 pur- pose of making a delta (that is, if a p-file (see ffef(l)) 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( 1) for explanations. 272 Last change: 6 March 1984 Sun Release 2.0 RMDIR(l) USER COMMANDS RMDIR(l) NAME rmdir, rm — remove (unlink) directories or files SYNOPSIS rmdSr dir ... rm | -f ] ( -r ] [ -5 ] [ - 1 file ... DESCRIPTION Rmdir removes entries for the named directories, which must be empty. Rm removes the entries for one or more files from a directory. If an entry was the last link to the file, the file is destroyed. Removal of a file requires write permission in its directory, but nei- ther read nor write permission on the file itself. If a file has no write permission and the standard input is a terminal, its permissions are printed and a line is read from the standard input. If that line begins with ‘y’ the file is deleted, other- wise the file remains. No questions are asked and no errors are reported when the — f (force) option is given. If a designated file is a directory, an error comment is printed unless the optional argument — r has been used. In that case, rm recursively deletes the entire contents of the specified directory, and the directory itself. If the —I (interactive) option is in effect, rm asks whether to delete each file, and, under — r, whether to examine each directory. The null option — indicates that all the arguments following it are to be treated as file names. This allows the specification of file names starting with a minus. SEE ALSO rm(l), unlink(2), rmdir(2) Sun Release 2.0 Last change: 1 April 1981 273 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 out- put, 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 rlogin(lC). Shell metacharacters which are not quoted are interpreted on the local machine, while quoted metacharacters are interpreted on the remote machine. Thus the command: tutorial/? rsh lizard cat lizard.file » tutorlal.flle 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 lizard.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 local machines are also commands in the directory /usr/hosts; 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 (in the sense of rlogin{ 1C)) to the originating account; no provision is made for specifying a password with a command. — n redirect the input of rsh to /dev/ null. You need this option if you are using cs^(l) and put a rsA(lC) in the background without redirecting its input away from the terminal because it will block even if no reads are posted by the remote command. 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(lC) BUGS You cannot run an interactive command (like ui(l)); use rlogin( 1C). Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to explain here. 274 Last change: 1 February 1985 Sun Release 2.0 RSH(IC) USER COMMANDS RSH(IC) The current local environment is not passed to the remote shell. Sun Release 2.0 Last change: 1 February 1985 275 RUPTIME(IC) USER COMMANDS RUPTIME(IC) NAME ruptime — show host status of local machines SYNOPSIS ruptime [ — a ] [ — I | [ — t ] [ — u ] DESCRIPTION Ruptime gives a status line like uptime for each machine on the local network; these are formed from packets 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) 276 Last change: 7 March 1984 Sun Release 2.0 RWALL ( 1 ) USER COMMANDS RWALL ( 1 ) 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 netgroup( 5). A machine can only receive such a message if it is running rwalld(S), which is normally started up from / etc/ servers by the daemon inetd( 8). FILES /etc/servers SEE ALSO wall(l), netgroup(5), rwalld(8), shutdown(8) Sun Release 2.0 Last change: 1 February 1985 277 RWHO(IC) USER COMMANDS RWHO(IC) NAME rwho — who’s logged in on local machines SYNOPSIS rwho [ — s ] DESCRIPTION The rwho command produces output similar to tnAo(l), 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. 278 Last change: 8 March 1984 Sun Release 2.0 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 Toots for the Sun Workstation. DIAGNOSTICS Use help( 1) for explanations. Sun Release 2.0 Last change: 6 March 1984 279 sees ( 1 ) USER COMMANDS SCCS(l) NAME sees — front end for the sees subsystem SYNOPSIS sees | — p ] [ —dprefixpath ] [ — p finalpath ] command [ SCCS-flags ... | [file ... ] DESCRIPTION system" The sees command is a front end to the utility programs of the Source Code Control System (sees), which helps them mesh more cleanly with the rest of UNIX. Sees runs the com- mand with the specified SCCS-flags and files. Note that sees normally prefixes each file, or the last component of each file, with the string SCCS/ 8 ., because you normally keep your SCCS database files in a directory called SCCS, and each database file starts with an 8 . prefix. Sees program options must appear before the command argument. Flags to be passed to the actual SCCS utility program must appear after the command argument. These flags are specific to the command being used, and are discussed in the manual page for that command. Sees also includes the capability to run ‘set user id’ to another user to provide additional protec- tion. Certain 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 sees as the real user rather than as whatever effective user sees is ‘set user id’ to. —dprefixpath 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 example: tutorial% acca — d/uar /include get aya/inode.h converts to: get /usr/include/aya/SCCS/a.inode.h The intent here is to create aliases such as: allaa syssccs acca — d/usr/arc which will be used as: tutorial^ syssccs get cmd/who.e — p finalpath 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 exam- ple: tutorial% acca — pprlvate get usr/include/stdio.h converts to: get uar /include/private /s.stdlo.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 8. 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 s. files. Given a C source language file called ob8cure.c, Create does the following actions: (1) creates the 8. file called 8. obscure. c in the SCCS directory; (2) renames the original source file to , obscure. c; (3) does an acca 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 280 Last change: 8 March 1984 Sun Release 2.0 sees ( 1 ) USER COMMANDS SCCS(X) keywords expanded, and so cannot be edited. deledit Same as delget, but produces new versions suitable for editing. Deledit is useful for mak- ing a ‘checkpoint’ of your current editing phase. 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 everything 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 rfi/f-like format) the current version of the program you have out for edit- ing 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 myprogram.c: 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 tutorial% To get a copy of myprogram.c for editing, edit that file, then place it back in the SCCS database: tutoriaI% sees edit myprogram.c 1.1 new delta 1.2 14 lines tutorial% vl myprogram.c your editing session tutorial% sees delget myprogram.c comments? Added abusive responses for compatibility with rest of system 1.2 7 inserted 7 deleted Sun Release 2.0 Last change: 8 March 1984 281 SCCS(l) USER COMMANDS SCCS(l) 7 unchanged 1.2 14 lines tutorial% To get a file from another directory: tutorial% sees — p/iisr/src/scc*/ get cc.c or: tutorial% sees get /uBr/src/sccs/cc.e To make a delta of a large number of files in the current directory: tutorial% sees delta *.e To get a list of files being edited that are not on branches: tutorial% bccb Info — b To delta everything that you are editing: tutorial% secs delta 'sees 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 com- mand does 99.9% of the interesting tasks for you. admin Creates new SCCS files and changes parameters of exitsing SCCS files. You can use bccb create to create new SCCS files, or use bccb 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 8ccb get. You can use sees delget as the more useful version of this command since sees 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 bccb get if you really need it, but bccb delget will normally have done this job for you. Use bccb edit instead of get with the — e option. help Supposed to help you interpret SCCS error messages, but usually just parrots the mes- saage 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 bccb 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 bccb delget command does all this work as part of its normal process. unget Undoes the work of a previous get — e command or a bccb edit command. Use the bccb unedlt command as a useful alternative. val Determines if a given SCCS file meets specified criteria. If you use the sees command, 282 Last change: 8 March 1984 Sun Release 2.0 SCCS(l) USER COMMANDS SCCS(l) you shouldn’t need to use val, because its user interface is unbelievable. what Displays SCCS identification information. SEE ALSO admin(l), comb(l), cdc(l), delta(l), get(l), help(l), prs(l), rmdel(l), sact(l), sccsdiff(l), sccsfile(5), unget(l), val(l), what(l) Source Code Control System in Programming Tools for the Sun Workstation. Sun Release 2.0 Last change: 8 March 1984 283 SCCSDIFF(l) USER COMMANDS SCCSDIFF(l) NAME sccsdiff — compare two versions of an SCCS file SYNOPSIS j ubf /sees /sccBdil? — r SID1 —T SIDS [ — p ] [ — an ] files DESCRIPTION Sccsdiff compares two versions of an SCCS file and generates the differences between the two ver- sions. Any number of SCCS files may be specified, but options apply to all files. OPTIONS — r SID? SID1 and SIDS specify the deltas of an SCCS file that are to be compared. Versions are passed to diff( 1) in the order given. — p pipe output for each file through pr(l). —Bn n is the file segment size that diff will use. This is useful when the system load is high. 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. 284 Last change: 1 February 1985 Sun Release 2.0 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 out- puts the display image in Sun standard rasterfile format (see /usr /include/ raster file.h) on output-file (or on the standard output if output-file is not specified). By default, screendump attempts to output the contents of the console frame buffer {/dev/fb). 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 Worksta- tion monitor. 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.color .image writes the current contents of the frame buffer /dev/cgoneO into the file save.color.image. tutorial% screendump { lpr — Pversatec —v sends a rasterfile containing the current frame buffer to the lineprinter, selecting the printer named “versatec” and the “v” output filter (see / etc/ printcap). 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 screenload(l), lpr(l) pr_dump in Programmer’s Reference Manual for SunWindows Sun Release 2.0 Last change: 1 February 1985 285 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD ( 1 ) NAME screenload — restore frame buffer image SYNOPSIS screenload [ -d ] [ -f display ] [ -1 index ] [ -b ] [ -g ] [ — p ] [ -w J [ -h# [#### [...]]] [ input-file ] DESCRIPTION Screenload accepts input in Sun standard rasterfile format (see / usr/ 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 deter- mined 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 warn- ing messages 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 —1 option determines the foreground border color, though the pattern is the same as on a monochrome 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 pattern is limited to 16. 286 Last change: 6 February 1985 Sun Release 2.0 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD (1) EXAMPLES tutorial% screenload saved. display. Image reloads the raster image contained in the file saved. display.image on the display type indicated by the 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 / dev/ cgoneO. tutorial/? screenload —hi ffff sun_l. saved. Image is equivalent to the — b option (fill border with black), while tutorial?? screenload — h4 8888 8888 2222 2222 sun_I.saved.lmage is equivalent to the — g option (fill border with desktop grey). FILES /dev/fb /dev/cgoneO /dev/cgtwoO /usr/lib/rasfilters/* Default name of console display frame buffer Default name of Sun-1 color display frame buffer Default name of the Sun-2 color display frame buffer. Filters for the raster file SEE ALSO screendump(l) pr_load in Programmer’s Reference Manual for SunWindows Sun Release 2.0 Last change: 6 February 1985 287 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. 288 Last change: 24 March 1983 Sun Release 2.0 SED ( 1 ) USER COMMANDS SED ( 1 ) 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 — fs, 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 some- thing 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 pattern 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 func- tion *!' (below). In the following list of functions the maximum number of permissible addresses for each function is indicated in parentheses. An argument denoted text consists of one or more lines, all but the last of which end with ‘\’ 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 dis- tinct wfile arguments. (1) a\ text Append: Place text on the output before reading the next input line. (2) b label Branch to the *:’ command bearing the label. Branch to the end of the script if label is empty. Sun Release 2.0 Last change: 4 December 1984 289 SED(l) USER COMMANDS SED(l) (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. (1) 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 ’/’. 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 / string 1/ stringS/ Transform: Replace all occurrences of characters in stringl with the corresponding char- acter in strings. The lengths of stringl and strings must be equal. (2)! function Don’t: Apply the function (or group, if function is ‘{’) only to lines not selected by the address(es). 290 Last change: 4 December 1984 Sun Release 2.0 SED ( 1 ) USER COMMANDS SED(1 ) (0) : label 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 ed(l), grep(l), awk(l), lex(l) Using sed, the Stream Text Editor in Editing and Text Processing on the Sun Workstation. Sun Release 2.0 Last change: 4 December 1984 291 SH(1) USER COMMANDS SH( 1 ) NAME sh, for, case, if, while, s, break, continue, cd, eval, exec, exit, export, login, newgrp, read, readonly, set, shift, times, trap, umask, wait — command language SYNOPSIS nfe [ — eelknrstuvx ] [ arg ] ... DESCRIPTION Sh is a command programming language that executes commands read from a terminal or a file. See Invocation for the meaning of arguments to the shell. Commands. A simple-command is a sequence of non blank words separated by blanks (a blank is a tab or a space). The first word specifies the name of the command to be executed. Except as specified below the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see execve( 2)). The value of a simple-command is its exit status if it terminates normally or 200+slalua if it terminates abnormally (see sigvec(2) for a list of status values). A pipeline is a sequence of one or more commands separated by I. 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 terminate. A list is a sequence of one or more pipelines separated by ;, &, && or !! and optionally ter- minated by ; or &. ; and & have equal precedence which is lower than that of && and II; && and II also have equal precedence. A semicolon causes sequential execution; an ampersand causes the preceding pipeline to be executed without waiting for it to finish. The symbol && causes the list following to be executed only if the preceding pipeline returns a zero value. The symbol II causes the list following to be executed only if the preceding pipeline returns a non zero value. Newlines may appear in a list, instead of semicolons, to delimit commands. A command is either a simple-command or one of the following. The value returned by a com- mand is that of the last simple-command executed in the command. Note that many keywords such as done are only recognized when they are the first keyword on a line, for name [ In word ... ] do list done Each time a for command is executed name is set to the next word in the In word list. If in word... is omitted, In $@ is assumed. Execution ends when there are no more words in the list. case word In [ pattern | I pattern j ... ) list ;; | [ pattern j I pattern j ... ) 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, if list then list [elif list then list ) . . . [ else list j § 292 Last change: 16 October 1984 Sun Release 2.0 SH( 1 ) USER COMMANDS SH( 1 ) The list following If is executed and if it returns zero the list following then is executed. Other- wise, the list following ellf is executed and if its value is zero the list following then is executed. Failing that the else list is executed. while list [ do list j done A while command repeatedly executes the while list and if its value is zero executes the do list; otherwise the loop terminates. The value returned by a while command is that of the last exe- cuted command in the do list, until may be used in place of while to negate the loop termina- tion test. ( list ) Execute list in a subshell. { list } list is simply executed. The following words are only recognized as the first word of a command and when not quoted. If then else ellf 9 case esac for while until do done { } Command substitution. The standard output from a command enclosed in a pair of back quotes (' *) may be used as part or all of a word; trailing newlines are removed. Parameter substitution. The character $ is used to introduce substitutable parameters. Positional parameters may be assigned values by set. Variables may be set by writing name=value [ name=value ] ... $ {parameter} A parameter is a sequence of letters, digits or underscores (a name), a digit, or any of the characters * @ # ? — $ !. 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 parameter is a digit, it is a positional parameter. If parameter is # or @ then all the positional parameters, starting with $ 1 , are substituted separated by spaces. $0 is set from argument zero when the shell is invoked. $ {parameter— word] If parameter is set, substitute its value; otherwise substitute word. $ {parameter = word } If parameter is not set, set it to word; the value of the parameter is then substituted. Positional parameters may not be assigned to in this way. $ {parameter ? word} If parameter is set, substitute its value; otherwise, print word and exit from the shell. If word is omitted, a standard message is printed. $ {parameter -^-word} If parameter is set, substitute word; otherwise substitute nothing. In the above word is not evaluated unless it is to be used as the substituted string. (So that, for example, echo ${d — 'pwd'} will only execute pwd if d is unset.) The following parameters are automatically set by the shell. # The number of positional parameters in decimal. — Options supplied to the shell on invocation or by set. ? The value returned by the last executed command in decimal. $ The process number of this shell. Sun Release 2.0 Last change: 16 October 1984 293 SH(1) USER COMMANDS SH( 1 ) ! The process number of the last background command invoked. The following parameters are used but not set by the shell. HOME The default argument (home directory) for the cd command. PATH The search path for commands (see execution). MAIL If this variable is set to the name of a mail file, the shell informs the user of the arrival of mail in the specified file. PS1 Primary prompt string, by default ’$ ’. PS2 Secondary prompt string, by default ’> ’. IFS Internal field separators, normally apace, tab, and newline. Blank Interpretation. After parameter and command substitution, any results of substitution are scanned for internal field separator characters (those found in tIFS) and split into distinct arguments where such characters are found. Explicit 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 characters appears, the word is regarded as a pattern. The word is replaced with alphabet- ically sorted file names that match the pattern. If no file name is found that matches the pat- tern, the word is left unchanged. The character . at the start of a file name or immediately fol- lowing a /, and the character /, must be matched explicitly. * Matches any string, including the null string. T Matches any single character. [...] Matches any one of the characters enclosed. A pair of characters separated by — matches any character lexically between the pair. Quoting. The following characters have a special meaning to the shell and cause termination of a word unless quoted. ; & ( ) I < > newline space tab A character may be quoted by preceding it with a backslash (\) character, \newline is ignored. All characters enclosed between a pair of quote marks (' '), except a single quote, are quoted. Inside double quotes ("") parameter and command substitution occurs and \ quotes the charac- ters backslash (\), apostrophe (’), double quote ("), and dollar sign ($). "$♦" is equivalent to "Si $2 ..." whereas "$@" is equivalent to "Si" "S2" ... Prompting. When used interactively, the shell prompts with the value of PS1 before reading a command. If at any time a newline is typed and further input is needed to complete a command, the secon- dary prompt ($PS2) is displayed. 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 pre- cede or follow a command and are not passed on to the invoked command. Substitution occurs before word or digit is used. < word Use file word as standard input (file descriptor 0). > word 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. » word Use file word as standard output. If the file exists, output is appended (by seeking to the 294 Last change: 16 October 1984 Sun Release 2.0 SH( 1 ) USER COMMANDS SH( 1 ) end); otherwise the file is created. « word The shell input is read up to a line the same as word, or end of file. The resulting docu- ment 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 sub- stitution occurs, \newllne is ignored, and \ is used to quote the characters backslash (\), dollar sign ($), apostrophe (’), and the first character of word. < & digit The standard input is duplicated from file descriptor digit; see dup( 2). Similarly for the standard output using >. <&— The standard input is closed. Similarly for the standard output using >. If one of the above is preceded by a digit, the file descriptor created is that specified by the digit (instead of the default 0 or 1). For example, ... 2>&1 creates file descriptor 2 to be a duplicate of file descriptor 1. If a command is followed by & then 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. Environment. The environment is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list; see execve(2) and environ(5). The shell interacts with the environment in several ways. On invocation, the shell scans the environment and creates a parameter for each name found, giving it the corresponding value. Executed commands inherit the same environment. If the user modifies the values of these parameters or creates new ones, none of these affects the environment unless the export command is used to bind the shell’s parameter to the environment. The environment seen by any executed command is thus com- posed of any unmodified name-value pairs originally inherited by the shell, plus any modifications or additions, 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 these two lines are equivalent TERM=450 cmd args (export TERM; TERM=450; cmd args) If the — k flag is set, all keyword arguments are placed in the environment, even if they occur after the command name. The following 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 fol- lowed by &; otherwise signals have the values inherited by the shell from its parent. (But see also trap.) Execution. Each time a command is executed the above substitutions are carried out. Except for the ’spe- cial commands’ listed below a new process is created and an attempt is made to execute the com- mand via an execve( 2). The shell parameter $PATH defines the search path for the directory containing the command. Each alternative directory name is separated by a colon (s). The default path is :/bln:/usr/blra. Sun Release 2.0 Last change: 16 October 1984 295 SH(1) USER COMMANDS SH(1) If the command name contains a /, the search path is not used. 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 subshell (that is, a separate process) is spawned to read it. A parenthesized command is also executed in a subshell. Special commands. The following commands are executed in the shell process and except where specified no input output redirection is permitted for such commands. : No effect; the command does nothing. . file Read and execute commands from file and return. The search path SPATH 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 J 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. 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 creat- ing 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 non interactive 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 exit from the shell.) export [ name . . . ] The given names are marked for automatic export to the environment of subsequently- executed commands. If no arguments are given, a list of exportable names is printed, login [ arg . . . \ Equivalent to ’exec login arg ...’. newgrp ( arg ...] Equivalent to ’exec newgrp arg ...’. read name . . . One line is read from the standard input; successive words of the input are assigned to the variables name in order, with leftover words to the last variable. The return code is 0 unless the end-of-file is encountered, readonly [ name ...] The given names are marked readonly and the values of the these names may not be changed by subsequent assignment. If no arguments are given, a list of all readonly names is printed. set [ — eknptuvx \arg . . . ] ] — e If non interactive, exit immediately if a command fails. — k All keyword arguments are placed in the environment for a command, not just those that precede the command name. — o 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. — Turn off the — x and — v options. 296 Last change: 16 October 1984 Sun Release 2.0 SH( 1 ) USER COMMANDS SH( 1 ) These flags can also be used upon invocation of the shell. The current set of flags may be found in . Remaining arguments are positional parameters and are assigned, in order, to tl, $2, etc. If no arguments are given, the values of all names are printed. shift The positional parameters from $2... are renamed Si... times Print the accumulated user and system times for processes run from the shell. trap [ary] [ n\ ... Arg is a command 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. 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 invoked commands. If n is 0, the command arg is executed on exit from the shell, other- wise upon receipt of signal n as numbered in sigvec(2). Trap with no arguments prints a list of commands associated with each signal number. umask [ nnn ] The user file creation mask is set to the octal value nnn (see umas A(2)). If nnn is omit- ted, the current value of the mask is printed. 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. The return code from this command is that of the process waited for. Invocation. If the first character of argument zero is — , commands are read from SHOME/. profile, if such a file exists. Commands are then read as described below. The following flags are interpreted by the shell when it is invoked. — c string If the — c flag is present, commands are read from string. — a If the —a flag is present or if no arguments remain then commands are read from the standard input. Shell output is written to file descriptor 2. —1 If the —I flag is present or if the shell input and output are attached to a terminal (as told by gtty) then this shell is interactive. In this case the terminate signal SIGTERM (see sigvec(2)) is ignored (so that 'kill 0’ does not kill an interactive shell) and the interrupt signal SIGINT is caught and ignored (so that wait is interrupt- able). In all cases SIGQUIT is ignored by the shell. The remaining flags and arguments are described under the Bet command. FILES $HOME/. profile /tmp/sh* /dev/null SEE ALSO Using the Bourne Shell in the Beginner’s Guide to the Sun Workstation csh(l), test(l), execve(2). DIAGNOSTICS 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 then execution of the shell file is abandoned. Otherwise, the shell returns the exit status of the last command executed (see also exit). BUGS If « is used to provide standard input to an asynchronous process invoked by &, the shell gets mixed up about naming the input document. A garbage file /tmp/sh* is created, and the shell complains about not being able to find the file by another name. Sun Release 2.0 Last change: 16 October 1984 297 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) NAME shelltool — Run a shell (or other program) in the SunWindows environment SYNOPSIS shelltool [ — C ] [ program [ args ]] OPTIONS — C Redirect system console output to this instance of the shelltool. shelltool also takes generic tool arguments; see suntools( 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. DESCRIPTION shelltool is a standard tool provided with the SunWindows environment. When invoked, shelltool starts up an interactive character-terminal-based program, usually a shell, inside of a terminal emulator subwindow. If this program is a shell, it accepts commands and runs programs in the usual way. shelltool’ s window may be positioned and manipulated in the same way as any tool window in the SunWindows environment, shelltool supports selections as described in suntools( 1). To invoke Tool Manager Functions, position the cursor on the name stripe or on the outside borders of shelltool’ s window. The Tool Manager is not accessible from shelltool's terminal subwindow because keystrokes are passed to the shell, or to the programs run from it. See sun- tools^), Terminal Emulators for more information. To run graphics programs, use gfxtool — see gfxtool( 1). Unless you instruct the system otherwise, it displays messages for the console by writing over the windows on the display. It bypasses all of the support for multiple windows sharing the bitmap. Solve this problem by starting a copy of shelltool with the -C argument; [that] redirects system console messages into that instance of the shelltool. See suntools( 1) for information on terminal emulators, and for an example showing how shelltool can be started automatically when the windowing environment starts up. SEE ALSO suntools( 1) gfxtool{\) FILES ‘/.ttyswrc /usr/bin/shelltool /usr/bin/suntools /usr/demo/* /usr/src/sun/suntool/shelltool.c BUGS This release has the following notable bugs: (1) Remote login to another machine should be done with a terminal emulator subwindow matching the standard terminal size for the remote machine (for example, 34 by 80 char- acters for a Sun workstation). The remote machine does not understand terminals with 298 Last change: 29 March 1985 Sun Release 2.0 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) non-standard size. (2) 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?" submenu there has one item, "Flush input", that you can invoke to correct the problem. Sun Release 2.0 Last change: 29 March 1985 299 SIZE ( 1 ) USER COMMANDS SIZE ( 1 ) NAME size — size of an object file SYNOPSIS size [ object ... ] DESCRIPTION Size prints the (decimal) number of bytes required by the text, data, and bss portions, and their sum in hex and decimal, of each object-file argument. If no file is specified, a. out is used. SEE ALSO a.out(5) 300 Last change: 2 June 1983 Sun Release 2.0 SLEEP ( 1 ) USER COMMANDS SLEEP ( 1 ) NAME sleep — suspend execution for an interval SYNOPSIS sleep time DESCRIPTION Sleep suspends execution for time seconds. It is used to execute a command after a certain amount of time as in: (sleep 105; command)& or to execute a command every so often, as in: while true do command sleep 37 done SEE ALSO setitimer(2), sleep(3) BUGS Time must be less than 2,147,483,647 seconds. Sun Release 2.0 Last change: 10 June 1983 301 SOELIM(l) USER COMMANDS SOELIM(l) NAME soelim — eliminate .so’s from nroff input SYNOPSIS soelim [file ... ] DESCRIPTION Soelim reads the specified files or the standard input and performs the textual inclusion implied by the nroff directives of the form .so somefile when they appear at the beginning of input lines. This is useful since programs such as tbl do not normally do this; it allows the placement of individual tables in separate files to be run as a part of a large document. An argument consisting of a single minus (— ) is taken to be a file name corresponding to the standard input. Note that inclusion can be suppressed by using ‘ ' ’ instead of that is, 'so /usr/lib/tmac.s EXAMPLE A sample usage of soelim would be soelim exum?.n j tbl j nroff —ms [ col [ lpr SEE ALSO colcrt(l), more(l) BUGS The format of the source commands must involve no strangeness — exactly one space must pre- cede and no spaces follow the file name. 302 Last change: 2 June 1983 Sun Release 2.0 SORT ( 1 ) USER COMMANDS SORT ( 1 ) NAME sort — sort or merge files SYNOPSIS sort | — mubdfinrtz ] [ +posl [ —posS ] ] ... [ — o name ] [ — T directory ][ file ] ... DESCRIPTION Sort sorts lines of all the named files together and writes the result on the standard output. The name ‘— ’ means the standard input. If no input file’s are named, the standard input is sorted. The default sort key is an entire line. Default ordering is lexicographic by bytes in machine col- lating sequence. The notation +posl —posS restricts a sort key to a field beginning at posl and ending just before pos2. Posl and pos2 each have the form m.n, optionally followed by one or more of the flags bdflnr, where m tells a number of fields to skip from the beginning of the line and n tells a number of characters to skip further. If any flags are present they override all the global order- ing options for this key. If the b option is in effect n is counted from the first nonblank in the field; b is attached independently to posS. A missing .n means .0; a missing —pos2 means the end of the line. Under the — tx option, fields are strings separated by x] otherwise fields are nonempty nonblank strings separated by blanks. When there are multiple sort keys, later keys are compared only after all earlier keys compare equal. Lines that otherwise compare equal are ordered with all bytes significant. OPTIONS The ordering is affected globally by the following options, one or more of which may appear, b Ignore leading blanks (spaces and tabs) in field comparisons, d ‘Dictionary’ order: only letters, digits and blanks are significant in comparisons, f Fold upper case letters onto lower case. 1 Ignore characters outside the ASCII range 040-0176 in nonnumeric comparisons. n An initial numeric string, consisting of optional blanks, optional minus sign, and zero or more digits with optional decimal point, is sorted by arithmetic value. Option n implies option b. r Reverse the sense of comparisons. tx ‘Tab character’ separating fields is x. These option arguments are also understood: c Check that the input file is sorted according to the ordering rules; give no output unless the file is out of sort. m Merge only, the input files are already sorted, o name name is the name of an output file to use instead of the standard output. This file may be the same as one of the inputs. T directory directory argument is the name of a directory in which temporary files should be made. u Suppress all but one in each set of equal lines. Ignored bytes and bytes outside keys do not participate in this comparison. EXAMPLES Print in alphabetical order all the unique spellings in a list of words. Capitalized words differ from uncapitalized. Sun Release 2.0 Last change: 8 August 1983 303 SORT ( 1 ) USER COMMANDS SORT ( 1 ) sort — u +0f +0 list Print the password file (passwd( 5)) sorted by user id number (the 3rd colon-separated field), sort — t: +2n /etc/passwd Print the first instance of each month in an already sorted file of (month day) entries. The options — um with just one input file make the choice of a unique representative from a set of equal lines predictable. sort — um +0 —1 dates FILES /usr/tmp/stm*, /tmp/* first and second tries for temporary files SEE ALSO uniq(l), comm(l), rev(l), join(l) DIAGNOSTICS Comments and exits with nonzero status for various trouble conditions and for disorder discovered under option — c. BUGS Very long lines are silently truncated. 304 Last change: 8 August 1983 Sun Release 2.0 SORTBIB(l) USER COMMANDS SORTBIB ( 1 ) NAME sortbib — sort bibliographic database SYNOPSIS sortbib [ — bKEYS ] database ... DESCRIPTION Sortbib sorts files of records containing refer key-letters by user-specified keys. Records may be separated by blank lines, or by .[ and ,| delimiters, but the two styles may not be mixed together. This program reads through each database and pulls out key fields, which are sorted separately. The sorted key fields contain the file pointer, byte offset, and length of corresponding records. These records are delivered using disk seeks and reads, so sortbib may not be used in a pipeline to read standard input. By default, sortbib alphabetizes by the first %A and the %D fields, which contain the senior author and date. The — s option is used to specify new KEYS. For instance, — sATD will sort by author, title, and date, while — sA+D will sort by all authors, and date. Sort keys past the fourth are not meaningful. No more than 16 databases may be sorted together at one time. Records longer than 4096 characters will be truncated. Sortbib sorts on the last word on the %A line, which is assumed to be the author’s last name. A word in the final position, such as “jr.” or “ed.”, will be ignored if the name beforehand ends with a comma. Authors with two-word last names or unusual constructions can be sorted correctly by using the nroff convention “\0” in place of a blank. A %Q field is considered to be the same as %A, except sorting begins with the first, not the last, word. Sortbib sorts on the last word of the %D line, usually the year. It also ignores leading articles (like “A” or “The”) when sorting by titles in the %T or %J fields; it will ignore articles of any modern European language. If a sort-significant field is absent from a record, sortbib places that record before other records containing that field. SEE ALSO refer(I), addbib(l), roffbib(l), indxbib(l), lookbib(l) BUGS Records with missing author fields should probably be sorted by title. Sun Release 2.0 Last change: 8 March 1983 305 SPELL ( 1 ) USER COMMANDS SPELL ( 1 ) NAME spell, spellin, spellout — find spelling errors SYNOPSIS spell [ — v ] [ — b ] [ — d hlist ] [ — s hstop ] [ — h spellhist ] [ file ] ... spellin [ list ] spellout [ — d ] list DESCRIPTION Spell collects words from the named documents, and looks them up in a spelling list. Words that neither occur among nor are derivable (by applying certain inflections, prefixes or suffixes) from words in the spelling list are printed on the standard output. If no files are named, words are collected from the standard input. Spell ignores most troff( 1), tbl( 1), and eqn( 1) constructions. The spelling list is based on many sources, and while more haphazard than an ordinary diction- ary, is also more effective in respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine and chemistry is light. Pertinent auxiliary files may be specified by name arguments, indicated below with their default settings. Copies of all output are accumulated in the history file. The stop list filters out misspellings (for example, thier=thy-y+ier) that would otherwise pass. Two routines help maintain the hash lists used by spell. Both expect a list of words, one per line, from the standard input. Spellin adds the words on the standard input to the preexisting list and places a new list on the standard output. If no list is specified, the new list is created from scratch. Spellout looks up each word in the standard input and prints on the standard output those that are missing from (or present on, with option — d) the hash list. OPTIONS —v Print all words not literally in the spelling list, as well as plausible derivations from spel- ling list words. — b Check British spelling. Besides preferring centre, colour, speciality, travelled, and so on, the — b option insists upon -ise in words like standardise, Fowler and the OED to the contrary notwithstanding. —x print every plausible stem with “=’ for each word. FILES /usr/dict/hlist[ab] /usr/dict/hstop / usr/dict/spellhist /usr/dict/words /usr/lib/spell hashed spelling lists, American & British hashed stop list history file list of words SEE ALSO deroff(l), sort(l), tee(l), sed(l) BUGS The spelling list’s coverage is uneven; new installations will probably wish to monitor the output for several months to gather local additions. British spelling was done by an American. 306 Last change: 1 November 1983 Sun Release 2.0 SPLINE (1G) USER COMMANDS SPLINE ( 1G ) NAME spline — interpolate smooth curve SYNOPSIS spline [ -a ] [ -k ] [ -n ] [ -p J [ -x ] DESCRIPTION Spline takes pairs of numbers from the standard input as abcissas and ordinates of a function. It produces a similar set, which is approximately equally spaced and includes the input set, on the standard output. The cubic spline output (R. W. Hamming, Numerical Methods for Scientists and Engineers, 2nd ed., 349ff) has two continuous derivatives, and sufficiently many points to look smooth when plotted, for example by graph(lG). OPTIONS —a Supply abscissas automatically (they are missing from the input); spacing is given by the next argument, or is assumed to be 1 if next argument is not a number. — k The constant k used in the boundary value computation A = K A = is set by the next argument. By default k = 0. — n Space output points so that approximately n intervals occur between the lower and upper x limits. (Default n = 100.) — p Make output periodic, that is, match derivatives at ends. First and last input values should normally agree. —x Next 1 (or 2) arguments are lower (and upper) x limits. Normally these limits are calcu- lated from the data. Automatic abcissas start at lower limit (default 0). SEE ALSO graph(lG) DIAGNOSTICS When data is not strictly monotonic in x, spline reproduces the input without interpolating extra points. BUGS A limit of 1000 input points is enforced silently. Sun Release 2.0 Last change: 1 June 1983 307 SPLIT ( 1 ) USER COMMANDS SPLIT ( 1 ) NAME split — split a file into pieces SYNOPSIS split | —number ] [ infile [ outfile ] ] DESCRIPTION Split reads file and writes it in n-Iine pieces (default 1000) onto a set of output files (as many files as necessary). The name of the first output file is outfile j with aa appended, the second file is outfileab, and so on lexicographically. If no outfile is given, x is used as default (output files will be called zaa, zab, etc.). If no infile is given, or if — is given in its stead, then the standard input file is used. OPTIONS —number Number of lines in each piece. 308 Last change: 1 February 1985 Sun Release 2.0 STRINGS ( 1 ) USER COMMANDS STRINGS ( 1 ) NAME strings — find printable strings in an object, or other binary, file SYNOPSIS strings [ — ] [ — o ] [ —number ] file ... DESCRIPTION Strings looks for ascii strings in a binary file. A string is any sequence of 4 or more printing char- acters ending with a newline or a null. Strings is useful for identifying random object files and many other things. OPTIONS — Look everywhere in the file for strings. If this flag is omitted, strings only looks in the initialized data space of object files. — o Precede each string by its offset in the file (in octal). — number Use number as the minimum string length rather than 4. SEE ALSO od(l) BUGS The algorithm for identifying strings is extremely primitive. Sun Release 2.0 Last change: 13 March 1984 309 STRIP ( 1 ) USER COMMANDS STRIP ( 1 ) NAME strip — remove symbols and relocation bits SYNOPSIS strip name ... DESCRIPTION Strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler and loader. This is useful to save space after a program has been debugged. The effect of strip is the same as use of the — s option of Id. FILES /tmp/stm? temporary file SEE ALSO ld(l) 310 Last change: 18 January 1983 Sun Release 2.0 STTY(l) USER COMMANDS STTY(l) NAME stty — set terminal options SYNOPSIS stty [ option ... ] DESCRIPTION Stty sets certain I/O options on the current output terminal, and directs its output to the diag- nostic output. With no argument, it reports the speed of the terminal and the settings of options which are different from their defaults. With the argument “all”, all normally-used option set- tings are reported. With the argument “everything”, everything stty knows about is printed. OPTIONS Options to stty are selected from the following set: even allow even parity input —even disallow even parity input odd allow odd parity input —odd disallow odd parity input raw raw mode input (no input processing (erase, kill, interrupt, ...); parity bit passed back) —raw negate raw mode cooked same as ‘—raw’ cbreak make each character available to read( 2) as received; no erase and kill processing, but all other processing (interrupt, suspend, ...) is performed —cbreak make characters available to read only when newline is received — nl allow carriage return for new-line, and output CR-LF for carriage return or new-line nl accept only new-line to end lines echo echo back every character typed —echo do not echo characters lease map upper case to lower case —lease do not map case tandem enable flow control, so that the system sends out the stop character when its internal queue is in danger of overflowing on input, and sends the start character when it is ready to accept further input —tandem disable flow control —tabs replace tabs by spaces when printing tabs preserve tabs ek set erase and kill characters to ‘H (control-H) and ‘U For the following commands which take a character argument c, you may also specify c as the “u” or “undef”, to set the value to be undefined. A value of “ A x”, a 2 character sequence, is also interpreted as a control character, with representing delete. erase c set erase character to c (default '*?’). kill c set kill character to c (default ,A U’). intr c set interrupt character to c (default ‘*C’). quit c set quit character to c (default ‘*\’). start c set start character to c (default ,A Q’). stop c set stop character to c (default ‘“S’), eof c set end of file character to c (default ,A D’). brk c set break character to c (default undefined.) This character is an extra wakeup caus- ing character. crO crl cr2 cr3 select style of delay for carriage return (see ioctl(2)) nlO nil nl2 nl3 select style of delay for linefeed tabO tabl tab2 tab3 Sun Release 2.0 Last change: 19 March 1984 311 STTY(l) USER COMMANDS STTY(l) select style of delay for tab ffO flfl select style of delay for form feed bsO bsl select style of delay for backspace tty33 set all modes suitable for the Teletype Corporation Model 33 terminal. tty37 set all modes suitable for the Teletype Corporation Model 37 terminal. vt05 set all modes suitable for Digital Equipment Corp. VT05 terminal dec set all modes suitable for Digital Equipment Corp. operating systems users; (erase, kill, and interrupt characters to *?, "U, and ‘C, decctlq and “newcrt”.) tn300 set all modes suitable for a General Electric TermiNet 300 tl700 set all modes suitable for Texas Instruments 700 series terminal tele set all modes suitable for Tektronix 4014 terminal 0 hang up phone line immediately 50 75 110 134 150 200 300 000 1200 1800 2400 4800 0600 10200 exta extb Set terminal baud rate to the number given, if possible. (These are the speeds sup- ported by the DH-11 interface). The driver which supports the job control processing of csh( 1) is fully described in tty(4). The options in the list below can only be selected by using the new option to s«j/(l). new Use new driver (switching flushes typeahead). ert Set options for a CRT (ertbs, ctlecho and, if >= 1200 baud, erterase and crtkill.) ertba Echo backspaces on erase characters. prterase For printing terminal echo erased characters backwards within “\” and “/”. erteraae Wipe out erased characters with “backspace-space-backspace.” — erteraae Leave erased characters visible; just backspace, crtkill Wipe out input on like kill ala erteraae. —crtkill Just echo line kill character and a newline on line kill. ctlecho Echo control characters as “ A j” (and delete as “"?”.) Print Iwo backspaces following the EOT character (default ‘*D’). —ctlecho Control characters echo as themselves; in cooked mode EOT (default ‘‘D’) is not echoed. decctlq After output is suspended (normally by *S), only a start character (normally *Q) will restart it. This is compatible with DEC’s vendor supplied systems. —decctlq After output is suspended, any character typed will restart it; the start character will restart output without providing any input. (This is the default.) tostop Background jobs stop if they attempt terminal output. — tostop Output from background jobs to the terminal is allowed, tilde Convert to on output (for Hazeltine terminals). —tilde Leave poor alone. flusho Output is being discarded usually because user hit ‘"O’ (internal state bit). — flusho Output is not being discarded. pendln Input is pending after a switch from ebreak to cooked and will be re-input when a read becomes pending or more input arrives (internal state bit). —pendln Input is not pending. lntrup Send a signal (SIGTINT) to the terminal control process group whenever an input record (line in cooked mode, character in ebreak or raw mode) is available for read- ing. —lntrup Don’t send input available interrupts. mdmbuf Start/stop output on carrier transitions (not implemented). — mdmbuf Return error if write attempted after carrier drops, lltout Send output characters without any processing. 312 Last change: 19 March 1984 Sun Release 2.0 STTY(l) USER COMMANDS STTY(l) — lltout Do normal output processing, inserting delays, etc. nohang Don’t send hangup signal if carrier drops. —nohang Send hangup signal to control process group when carrier drops, etxack Diablo style etx/ack handshaking (not implemented). The following special characters are applicable only to the new teletype driver and are not nor- mally changed. susp c set suspend process character to c (default ‘‘Z’). dsusp c set delayed suspend process character to c (default ‘*Y’). rprnt c set reprint line character to c (default ‘‘R’). flush c set flush output character to c (default ,A 0’). werase c set word erase character to c (default ‘"W’). lnext c set literal next character to c (default ,A V’). SEE ALSO ioctl(2), tset(l), tty(4) Sun Release 2.0 Last change: 19 March 1984 313 SU(1) USER COMMANDS SU(1) NAME su — substitute user id temporarily SYNOPSIS su [ username ] [ — ] [ — c command ] [ — f ] DESCRIPTION Su changes your login to that of the specified username. Su asks for the password, just as if you were logging in as username, and, if the password is given, changes to that username and invokes the shell specified in the password file for that username, without changing the current directory. The user environment is thus unchanged except for HOME and SHELL, which are taken from the password file for the user being substituted (see enntron(5)). The new user ID stays in force until the shell exits. If no username is specified, ‘root’ is assumed. To remind the super-user of his responsibilities, the Shell substitutes *#’ for its usual prompt. OPTIONS - The - flag performs a complete login. That is, it moves to the home directory, reads the .login file, and reads the shell. — c command execute command after logging in as the new user. — f Perform a fast login. That is, do not change directories, do not read the .cshrc file, and do not read the .login file for the new user ID to configure the new shell. If the — and -f flags are omitted, only the shell. SEE ALSO sh(l), csh(l) 314 Last change: 1 February 1985 Sun Release 2.0 SUM ( 1 ) USER COMMANDS SUM ( 1 ) NAME sum — sum and count blocks in a file SYNOPSIS sum file DESCRIPTION Sum calculates and displays a 16-bit checksum for the named file, and also displays the size of the file in kilobytes. It is typically used to look for bad spots, or to validate a file communicated over some transmission line. SEE ALSO wc(l) DIAGNOSTICS ‘Read error’ is indistinguishable from end of file on most devices; check the block count. Sun Release 2.0 Last change: 15 October 1984 315 SUN ( 1 ) USER COMMANDS SUN ( 1 ) NAME sun — is current machine a Sun Workstation SYNOPSIS If sun; then fl (sh) if { sun } then (csh) endif DESCRIPTION The sun command is, on Sun Workstations, the same as \E\ — set tool header to \E] I< file>\E\ — set icon to the icon contained in ; must be in icontool output format \E] L< label >\E\ — set icon label to