Part Number: 800-3827-10 Revision A of 27 March, 1990 The Sun logo, Sun Microsystems, Sun Workstation, NFS, and TOPS are registered trademarks of Sun Microsystems, Inc. Sun, Sun-2, Sun-3, Sun-4, Sun386i, SPARCstation, SPARCserver, NeWS, NSE, OpenWindows, SPARC, Sunlnstall, SunLink, SunNet, SunOS, SunPro, and SunView are trademarks of Sun Microsystems, Inc. UNIX is a registered trademark of AT&T; OPEN LOOK is a trademark of AT&T. All other products or services mentioned in this document are identified by the trademarks or service marks of their respective companies or organizations, and Sun Microsystems, Inc. disclaims any responsibility for specifying which marks are owned by which companies or organizations. x/Open © This logo is a trademark of the X/Open Company Limited in the UK and other countries, and its use is licensed to Sun Microsystems, Inc. The use of this logo certifies SunOS 4.1 conformance with X/Open Portability Guide Issue 2 (XPG 2). Copyright © 1987, 1988, 1989, 1990 Sun Microsystems, Inc. - Printed in U.S.A. All rights reserved. No part of this work covered by copyright hereon may be reproduced in any form or by any means — graphic, electronic, or mechanical - including photocopying, recording, taping, or storage in an information retrieval system, without the prior written permission of the copyright owner. Restricted rights legend: use, duplication, or disclosure by the U.S. government is subject to restrictions set forth in subparagraph (c)(l)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. The Sun Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun ack- nowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user inter- faces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees. This product is protected by one or more of the following U.S. patents: 4,777,485 4,688,190 4,527,232 4,745,407 4,679,014 4,435,792 4,719,569 4,550,368 in addition to foreign patents and applications pending. This software and documentation is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California. We acknowledge the following individuals and institutions for their role in its development: The Regents of the University of California, the Electrical Engineering and Computer Sciences Department at the Berkeley Campus of the University of California, and Other Contributors. Preface OVERVIEW A man page is provided for both the naive user, and sophisticated user who is familiar with the SunOS operating system and is in need of on-line information. A man page is intended to answer concisely the question “What does it do?” The man pages in general comprise a reference manual. They are not intended to be a tutorial. Below is a generic format for man pages. The man pages of each manual section generally follow this order, but include only needed headings. For example, if there are no bugs to report, there is no BUGS section. If a man page documents System V behavior in addition to default SunOS behavior, the System V infor- mation is presented under SYSTEM V headings. See the intro pages for more information about each section, and man(7) for more information about man pages in general. NAME This section gives the names of the commands or functions documented, fol- lowed by a brief description of what they do. CONFIG This section is exclusive to Section 4. It lists the configuration file lines needed to install a driver into the kernel. Where necessary, the configuration lines are presented separately for different hardware platforms. SYNOPSIS This section shows the syntax of commands or functions. When a command or file does not exist in the standard path, its full pathname is shown. Literal char- acters (commands and options) are in bold font and variables (arguments, param- eters and substitution characters) are in italic font. Options and arguments are alphabetized, with single letter arguments first, and options with arguments next, unless a different argument order is required. The following special characters are used in this section: [ ] The option or argument enclosed in these brackets is optional. If the brackets are omitted, the argument must be specified. Preface — Continued PROTOCOL AVAILABILITY DESCRIPTION IOCTLS OPTIONS RETURN VALUES ERRORS Ellipses. Several values may be provided for the previous argument, or the previous argument can be specified multiple times, for example, ‘ filename . I Separator. Only one of the arguments separated by this character can be specified at time. This section occurs only in subsection 3R to indicate the protocol description file. The protocol specification pathname is always listed in bold font. This section briefly states any limitations on the availabilty of the command. These limitations could be hardware or software specific. Software specific ones require certain installation options. This section defines the functionality and behavior of the service. Thus it describes concisely what the command does. It does not discuss OPTIONS or cite EXAMPLES. Interactive commands, subcommands, requests, macros, functions and such, are described under USAGE. This section appears on pages in Section 4 only. Only the device class which supplies appropriate parameters to the ioctls(2) system call is called ioctls and generates its own heading. IOCTLS for a specific device are listed alphabetically (on the man page for that specific device). IOCTLS are used for a particular class of devices all which have an io ending, such as mtio(4). This lists the command options with a concise summary of what each option does. The options are listed literally and in the order they appear in the SYNOPSIS section. Possible arguments to options are discussed under the option, and where appropriate, default values are supplied. If the man page documents functions that return values, this section lists these values and describes the conditions under which they are returned. If a function can return only constant values, such as 0 or-1, these values are listed in tagged paragraphs. Otherwise, a single paragraph describes the return values of each function. Functions declared as void do not return values, so they are not dis- cussed in RETURN VALUES. On failure, most functions place an error code in the global variable errno indi- cating why they failed. This section lists alphabetically all error codes a function can generate and describes the conditions that cause each error. When more than one condition can cause the same error, each condition is described in a separate paragraph under the error code. - IV - Preface — Continued USAGE EXAMPLES ENVIRONMENT FILES SEE ALSO DIAGNOSTICS WARNINGS NOTES This section is provided as a guidance on use. This section lists special rules, features and commands that require in-depth explanations. The subsections listed below are used to explain built-in functionality: Commands Modifiers Variables Expressions Input Grammar This section provides examples of usage or of how to use a command or func- tion. Wherever possible a complete example including command line entry and machine response is shown. Whenever an example is given, the prompt is shown as example % or if the user must be super-user, example# Examples are followed by explanations, variable substitution mles, or returned values. Most examples illustrate concepts from the SYNOPSIS, DESCRIPTION, OPTIONS and USAGE sections. This section lists any environment variables that the command or function affects, followed by a brief description of the effect. This section lists all filenames referred to by the man page, files of interest, and files created or required by commands. Each is followed by a descriptive sum- mary or explanation. This section lists references to other man pages, in-house documentation and out- side publications. This section lists diagnostic messages with a brief explanation of the condition causing the error. Messages appear in bold font with the exception of variables, which are in italic font. This section lists warnings about special conditions which could seriously affect your working conditions — this is not a list of diagnostics. This section lists additional information that does not belong anywhere else on the page. It takes the form of an aside to the user, covering points of special interest. Critical information is never covered here. BUGS This section describes known bugs and wherever possible suggests workarounds. INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) NAME intro - introduction to commands DESCRIPTION This section describes publicly accessible commands in alphabetic order. Commands of general utility, many with enhancements from 4.3 BSD. Pages of special interest have been categorized as follows: 1C Commands for communicating with other systems. 1G Commands used primarily for graphics and computer-aided design. IV System V commands. One or more of the following are true: • The man page documents System V behavior only. • The man page documents default SunOS behavior, and System V behavior as it differs from the default behavior. These System V differences are presented under SYSTEM V section headers. • The man page documents behavior compliant with IEEE Std 1003.1-1988 (POSIX.l). SEE ALSO • Section 8 in this manual for system administration procedures, system maintenance and operation com- mands, local daemons, and network-services servers. • Section 7 in this manual for descriptions of publicly available files and macro packages for document preparation. • Section 6 in this manual for computer games. • SunOS User' s Guide: Getting Started • SunOS User's Guide: Customizing Your Environment ® SunView User’ s Guide • SunOS User’s Guide: Doing More • Programming Utilities and Libraries 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(2V) and exit(2V). The former byte is 0 for normal termination, the latter is customarily 0 for successful execution, nonzero to indicate troubles such as erroneous parameters, bad or inaccessible data, or other inability to cope with the task at hand. It is called variously “exit code,” “exit status” or “return code,” and is described only where special conventions are involved. Sun Release 4.1 Last change: 4 March 1988 3 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) LIST OF COMMANDS Name Appears on Page acctcom acctcom(l) adb adb(l) addbib addbib(l) adjacentscreens adjacentscr eens( 1 ) admin sccs-admin(l) aedplot plot(lG) alias csh(l) alignequals texteditfilters(l) apropos apropos(l) ar ar(lV) arch arch(l) as as(l) at at(l) atq atq(l) atrm atrm(l) awk awk(l) banner banner(lV) bar bar(l) basename basename(lV) batch at(l) be bc(l) bg csh(l) bgplot plot(lG) biff bifid) bin-mail bin-mail(l) break csh(l) breaksw csh(l) cal cal(l) calendar calendar(l) cancel Ipd) capitalize texteditfilters(l) case csh(l) cat cat(lV) cb cb(l) cc cc(lV) cd cd(l) ede sccs-cdc(l) cflow cflow(lV) checkeq eqn(l) checknr checknr(l) chfn passwd(l) chgrp chgrp(l) chkey chkey(l) chmod chmod(lV) chsh passwd(l) clear clear(l) clearcolormap clearcolormap(l) clear_functions clearfunctions(l) click click(l) clock clock(l) Description search and print process accounting files general-purpose debugger create or extend a bibliographic database connect multiple screens to Sun View window driver create and administer SCCS history files graphics filters for various plotters C shell built-in commands, see csh(l) filters provided with textedit(l) locate commands by keyword lookup create library archives, and add or extract files display the architecture of the current host assembler execute a command or script at a specified time display the queue of jobs to be run at specified times remove jobs spooled by at or batch pattern scanning and processing language display a string in large letters create tape archives, and add or extract files display portions of pathnames and filenames execute a command or script at a specified time arbitrary-precision arithmetic language C shell built-in commands, see csh(l) graphics filters for various plotters give notice of incoming mail messages an early program for processing mail messages C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) display a calendar a simple reminder service send/cancel requests to a printer filters provided with textedit(l) C shell built-in commands, see csh(l) concatenate and display a simple C program beautifier C compiler change working directory change the delta commentary of an SCCS delta generate a flow graph for a C program typeset mathematics check nroff and troff input files for errors change local or NIS password information change the group ownership of a file create or change encryption key change the permissions mode of a file change local or NIS password information clear the terminal screen clear the colormap to make console text visible reset the selection service to clear stuck function keys enable or disable the keyboard’s keystroke click display the time in an icon or window 4 Last change: 4 March 1988 Sun Release 4.1 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) cluster cluster/ 1) cmdtool cmdtool(l) cmp cmp(l) col col(lV) colcrt colcrt(l) coloredit coloredit(l) colrm colrm(l) comb sccs-comb(l) comm comm(l) compress compress/ 1) continue csh/l) cp cp(l) cpio cpio/l) cpp cpp/l) crontab crontab/ 1) crtplot plot/lG) crypt crypt/l) csh csh/l) csplit csplit/ IV) ctags ctags/ 1) ctrace ctrace/lV) cu cu/lC) cut cut/lV) cxref cxref/ IV) date date/ IV) dbx dbx/l) dbxtool dbxtool/ 1) dc dc(l) dd dd(l) default csh/l) defaultsedit defaultsedit/1) defaults_from_input defaultsedit/ 1) defaultsfrominput inputfromdefaults/l) defaults_to_indentpro defaultsedit/1) defaultstomailrc defaultsedit/l) delta sccs-delta/l) deroff deroff(l) des des/l) df df(lV) diff diff/l) diff3 diff3(lV) diffmk diffmk/1) dircmp dircmp/lV) dirname basename/lV) dirs csh/l) dis dis/l) disablenumlock enablenumlock/l) domainname domainname/1) dos dos/l) dos2unix dos2unix(l) du du/lV) dumbplot plot/lG) dumpkeys Ioadkeys/1) find optional cluster containing a file run a shell (or program) using the SunView text facility perform a byte-by-byte comparison of two files filter reverse paper motions for terminal diplay filter nroff output for a terminal lacking overstrike capability alter color map segment remove characters from specified columns within each line combine SCCS deltas display lines in common between two sorted lists compress or expand files, display expanded contents C shell built-in commands, see csh(l) copy files copy file archives in and out the C language preprocessor install, edit, remove or list a user’s crontab file graphics filters for various plotters encode or decode a file shell with a C-like syntax and advanced interactive features split a file with respect to a given context create a tags file for use with ex and vi generate a C program execution trace connect to remote system remove selected fields from each line of a file generate a C program cross-reference display or set the date source-level debugger SunView interface for dbx source-level debugger desk calculator convert and copy files with various data formats C shell built-in commands, see csh(l) edit default settings for SunView utilities edit default settings for SunView utilities update current state of the mouse and keyboard edit default settings for SunView utilities edit default settings for SunView utilities make a delta to an SCCS file remove nroff, troff, tbl and eqn constructs encrypt or decrypt data using Data Encryption Standard report free disk space on file systems display line-by-line differences between pairs of text files display line-by-line differences between 3 files mark differences between versions of a troff input file compare directories display portions of pathnames and filenames C shell built-in commands, see csh(l) object code disassembler for COFF enable or disable the numlock key set or display name of the current NIS domain SunView window for IBM PC/AT applications convert text file from DOS format to ISO format display the number of disk blocks used per directory or file graphics filters for various plotters load and dump keyboard translation tables Sun Release 4. 1 Last change: 4 March 1988 5 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) e ex(l) echo echo(lV) ed ed(l) edit ex(l) egrep grep(lV) eject eject(l) else csh(l) enablenumlock enablenumlock( 1) end csh(l) endif csh(l) endsw csh(l) enroll xsend(l) env env(l) eqm eqn(l) error error (1) eval csh(l) ex ex(l) exec csh(l) exit csh(l) expand expand(l) expr expr(lV) false true(l) fdformat fdformat(l) fg csh(l) fgrep grep(lV) file file(l) find find(l) finger finger (1) fmt fmt(l) fmt mail fmt(l) fold fold(l) fontedit fontedit(l) foption foption(l) foreach csh(l) from from(l) ftp ftp(lC) gcore gcore(l) get sccs-get(l) get_alarm set_alarm(l) getoptcvt getopts(l) getopt getopt(lV) getopts getopts(l) getselection get_selection(l) gfxtool gfxtool(l) gigiplot plot(lG) glob csh(l) goto csh(l) gprof gprof(l) graph graph(lG) grep grep(lV) groups groups(l) hashcheck spell(l) hashmake spell(l) line editor echo arguments to the standard output basic line editor line editor search a file for a string or regular expression eject media device from drive C shell built-in commands, see csh(l) enable or disable the numlock key C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) send or receive secret mail obtain or alter environment variables typeset mathematics categorize compiler error messages, insert at source file lines C shell built-in commands, see csh(l) line editor C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) expand TAB characters to SPACE characters, and vice versa evaluate expressions as logical, arithmetic, or string provide truth values format diskettes C shell built-in commands, see csh(l) search a file for a string or regular expression determine the type of a file by examining its contents find files by name, or by other characteristics display information about users simple text and mail-message formatters simple text and mail-message formatters fold long lines for display a vfont screen-font editor determine available floating-point code generation options C shell built-in commands, see csh(l) display the sender and date of newly-arrived mail messages file transfer program get core images of running processes retrieve a version of an SCCS file SunView programmable alarms parse command options in shell scripts parse command options in shell scripts parse command options in shell scripts copy contents of SunView selection to the standard output run graphics programs in a SunView window graphics filters for various plotters C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) display call-graph profile data draw a graph search a file for a string or regular expression display a user’s group memberships report spelling errors report spelling errors 6 Last change: 4 March 1988 Sun Release 4.1 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) hashstat csh(l) head head(l) help sccs-help(l) help_viewer helpviewer(l) history csh(l) hostid hostid(l) hostname hostname(l) hpplot pIot(lG) i386 machid(l) iAPX286 machid(l) iconedit iconedit(l) id id(lV) if csh(l) implot plot(lG) indent indent(l) indentprotodefaults defaultsedit(l) indxbib indxbib(l) inline inline(l) inputfromdefaults defaultsedit(l) input_from_defaults inputfromdefaults(l) insertjbrackets textedit_filters(l) install install(l) ipcrm ipcrm(l) ipcs ipcs(l) jobs csh(l) join join(l) keylogin keylogin(l) keylogout keylogout(l) kill kill(l) label csh(l) last Iast(l) lastcomm lastcomm(l) Id ld(l) ldd ldd(l) ld.so ld(l) leave leave(l) lex lex(l) limit csh(l) line line(l) lint lint(lV) In In(lV) load load(l) loadc load(l) loadkeys loadkeys(l) lockscreendefault defaultsedit(l) lockscreendefault lockscreen(l) lockscreen lockscreen(l) logger logger(l) login login(l) logname logname(l) logout csh(l) look look(l) lookbib lookbib(l) C shell built-in commands, see csh(l) display first few lines of specified files help regarding SCCS error or warning messages provide help with SunView applications and desktop C shell built-in commands, see csh(l) print the numeric identifier of the current host set or print name of current host system graphics filters for various plotters return a true exit status if the processor is of the indicated type return a true exit status if the processor is of the indicated type create and edit images for icons, cursors and panel items print the user name and ID, and group name and ID C shell built-in commands, see csh(l) graphics filters for various plotters indent and format a C program source file edit default settings for SunView utilities create an inverted index to a bibliographic database in-line procedure call expander edit default settings for SunView utilities update the current state of the mouse and keyboard filters provided with textedit(l) install files remove a message queue, semaphore set, or shared memory ID report interprocess communication facilities status C shell built-in commands, see csh(l) relational database operator decrypt and store secret key delete stored secret key send a signal to a process, or terminate a process C shell built-in commands, see csh(l) indicate last logins by user or terminal show the last commands executed, in reverse order link editor, dynamic link editor list dynamic dependencies link editor, dynamic link editor remind you when you have to leave lexical analysis program generator C shell built-in commands, see csh(l) read one line a C program verifier make hard or symbolic links to files load clusters load clusters load and dump keyboard translation tables edit default settings for SunView utilities maintain SunView context and prevent unauthorized access maintain SunView context and prevent unauthorized access add entries to the system log log in to the system get the name by which you logged in C shell built-in commands, see csh(l) find words in the system dictionary or lines in a sorted list find references in a bibliographic database Sun Release 4. 1 Last change: 4 March 1988 7 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) Iorder lorder(l) find an ordering relation for an object library •P lp(D send/cancel requests to a printer lpq ipq(i) display the queue of printer jobs Ipr lpr(l) send a job to the printer lprm Iprm(l) remove jobs from the printer queue lpstat Ipstat(l) display the printer status information lptest Iptest(l) generate lineprinter ripple pattern Is Is(lV) list the contents of a directory lsw lsw(l) list TFS whiteout entries m4 m4(lV) macro language processor m68k machid(l) return a true exit status if the processor is of the indicated type mach mach(l) display the processor type of the current host machid machid(l) return a true exit status if the processor is of the indicated type Mail mail(l) read or send mail messages mailrc_to_defaults defaultsedit(l) edit default settings for SunView utilities mailtool mailtool(l) SunView interface for the mail program make make(l) maintain, update, and regenerate related programs and files man man(l) display reference manual pages mesg mesg(l) permit or deny messages on the terminal mkdir mkdir(l) make a directory mkstr mkstr(l) create an error message file by massaging C source files more more(l) browse or page through a text file mt mt(l) magnetic tape control mv mv(l) move or rename files nawk nawk(l) pattern scanning and processing language neqn eqn(l) typeset mathematics newgrp newgrp(l) log in to a new group nice nice(l) run a command at low priority nl nl(lV) line numbering filter nm nm(l) print symbol name list nohup nohup(lV) run a command immune to hangups and quits notify csh(l) C shell built-in commands, see csh(l) nroff nroff(l) format documents for display or line-printer objdump objdump(l) dump selected parts of a COFF object file od od(lV) octal, decimal, hexadecimal, and ascii dump old-ccat old-compact(l) compress and uncompress files, and cat them old-compact old-compact(l) compress and uncompress files, and cat them old-eyacc old-eyacc(l) modified yacc allowing much improved error recovery old-filemerge old-filemerge(l) window-based file comparison and merging program old-make old-make(l) maintain, update, and regenerate groups of programs old-prmail old-prmail(l) display waiting mail old-pti old-pti(l) phototypesetter interpreter old-setkeys old-setkeys(l) modify interpretation of the keyboard old-sun3cvt old-sun3cvt(l) convert Sun-2 system executables to Sun-3 system executables old-syslog old-syslog(l) make a system log entry old-uncompact old-compact(l) compress and uncompress files, and cat them old-vc old-vc(l) version control on on(lC) execute command on a remote system with local environment onintr csh(l) C shell built-in commands, see csh(l) organizer organizer(l) file and directory manager overview overview(l) run a program from SunView that takes over the screen pack pack(lV) compress and expand files page more(l) browse or page through a text file 8 Last change: 4 March 1988 Sun Release 4.1 INTRO ( 1 ) USER COMMANDS INTRO(l) pagesize pagesize(l) display the size of a page of memory passwd passwd(l) change local or NIS password information paste paste(lV) join corresponding lines of files, subsequent lines of one pax pax(lV) portable archive exchange paxcpio paxcpio(lV) copy file archives in and out peat pack(lV) compress and expand files pdpll machid(i) return a true exit status if the processor is of the indicated type perfmeter perfmeter(l) display system performance values in a meter or strip chart Pg pg(lV) page through a file on a soft-copy terminal plot plot(lG) graphics filters for various plotters popd csh(l) C shell built-in commands, see csh(l) pr pr(lV) prepare file(s) for printing, perhaps in multiple columns printenv printenv(l) display environment variables currently set prof prof(l) display profile data prs sccs-prs(l) display selected portions of an SCCS history prt sccs-prt(l) display delta table information from an SCCS file ps ps(l) display the status of current processes ptx ptx(l) generate a permuted index pushd csh(l) C shell built-in commands, see csh(l) pwd pwd(l) display the pathname of the current working directory quota quota(l) display a user’s disk quota and usage ranlib ranlib(l) convert archives to random libraries rasfilterStol rasfilter8tol(l) convert an 8-bit deep rasterfile to a 1-bit deep rasterfile rastrepl rastrepl(l) magnify a raster image by a factor of two rep rcp(lC) remote file copy rdist rdist(l) remote file distribution program red ed(l) basic line editor refer refer(l) expand and insert references from a bibliographic database rehash csh(l) C shell built-in commands, see csh(l) remove_brackets textedit_filters(l) filters provided with textedit(l) repeat csh(l) C shell built-in commands, see csh(l) reset tset(l) establish or restore terminal characteristics rev rev(l) reverse the order of characters in each line ringalarm setalarm(l) SunView programmable alarms rlogin rlogin(lC) remote login rm rm(l) remove (unlink) files or directories rmdel sccs-rmdel(l) remove a delta from an SCCS file rmdir rm(l) remove (unlink) files or directories roffbib roffbib(l) format and print a bibliographic database rpegen rpcgen(l) RPC protocol compiler rsh rsh(lC) remote shell rup rup(lC) show host status of local machines (RPC version) ruptime ruptime(lC) show host status of local machines rusers rusers(lC) who’s logged in on local machines (RPC version) rwall rwall(lC) write to all users over a network rwho rwho(lC) who’s logged in on local machines sact sccs-sact(l) show editing activity status of an SCCS file secs sccs(l) front end for the Source Code Control System (SCCS) sccs-admin sccs-admin(l) create and administer SCCS history files sccs-cdc sccs-cdc(l) change the delta commentary of an SCCS delta sccs-comb sccs-comb(l) combine SCCS deltas sccs-delta sccs-delta(l) make a delta to an SCCS file sccsdiff sccs-sccsdiff(l) compare two versions of an SCCS file Sun Release 4. 1 Last change: 4 March 1988 9 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) sccs-get sccs-get(l) sccs-help sccs-help(l) sccs-prs sccs-prs(l) sccs-prt sccs-prt(l) sccs-rmdel sccs-rmdel(l) sccs-sact sccs-sact(l) sccs-sccsdiff sccs-sccsdiff(l) sccs-unget sccs-unget(l) sccs-val sccs-val(l) screenblank screenblank(l) screendump screendump(l) screenload screenload(l) script script(l) scrolldefaults defaultsedit(l) sdiff sdiff(lV) sed sed(lV) selection_svc selection_svc(l) set_alarm setalarm(l) setenv csh(l) set csh(l) sh sh(l) shelltool shelltool(l) shift csh(l) shift_lines texteditfilters(l) size size(l) sleep sleep(l) snap snap(l) soelim soelim(l) sort sort(lV) sortbib sortbib(l) source csh(l) spare machid(l) spell spell(l) spellin spell(l) spline spline(lG) split split(l) stop csh(l) strings strings(l) strip strip(l) stty stty (IV) stty_from_defaults defaultsedit(l) stty_from_defaults stty_from_defaults(l) su su(lV) sum sum(lV) sun machid(l) sunview sunview(l) suspend csh(l) sv_acquire sv_acquire(l) sv_release svacquire(l) swin swin(l) switcher switcher(l) switch csh(l) symorder symorder(l) retrieve a version of an SCCS file ask for help regarding SCCS error or warning messages display selected portions of an SCCS history display delta table information from an SCCS file remove a delta from an SCCS file show editing activity status of an SCCS file compare two versions of an SCCS file undo a previous get of an SCCS file validate an SCCS file turn off the screen when the mouse and keyboard are idle dump a frame-buffer image to a file load a frame-buffer image from a file make typescript of a terminal session edit default settings for SunView utilities contrast two text files by displaying them side-by-side stream editor SunView selection service SunView programmable alarms C shell built-in commands, see csh(l) C shell built-in commands, see csh(l) standard UNIX system shell and command-level language run a shell in a SunView terminal window C shell built-in commands, see csh(l) filters provided with textedit(l) display the size of an object file suspend execution for a specified interval SunView application for system and network administration resolve and eliminate .so requests from nroff or troff input sort and collate lines sort a bibliographic database C shell built-in commands, see csh(l) return a true exit status if the processor is of indicated type report spelling errors report spelling errors interpolate smooth curve split a file into pieces C shell built-in commands, see csh(l) find printable strings in an object file or binary remove symbols and relocation bits from an object file set or alter the options for a terminal edit default settings for SunView utilities set terminal editing characters from the defaults database super-user, temporarily switch to a new user ID calculate a checksum for a file return a true exit status if the processor is of indicated type the SunView window environment C shell built-in commands, see csh(l) change owner, group, mode of window devices change owner, group, mode of window devices set or get SunView user input options switch between multiple desktops on the same physical screen C shell built-in commands, see csh(l) rearrange a list of symbols 10 Last change: 4 March 1988 Sun Release 4.1 INTRO ( 1 ) USER COMMANDS INTRO(l) sync sync(l) update the super block; force changed blocks to the disk sysex sysex(l) start the system exerciser syswait syswait(l) execute a command, suspending termination until user input t300 plot(lG) graphics filters for various plotters t300s plot(lG) graphics filters for various plotters t4013 plot(lG) graphics filters for various plotters t450 plot(lG) graphics filters for various plotters tabs tabs(lV) set tab stops on a terminal tail tail(l) display the last part of a file talk talk(l) talk to another user tar tar(l) create tape archives, and add or extract files tbl tbl(l) format tables for nroff or troff tcopy tcopy(l) copy a magnetic tape tcov tcov(l) construct test coverage analysis tee tee(l) replicate the standard output tek plot(lG) graphics filters for various plotters tektool tektool(l) SunView Tektronix 4014 terminal-emulator window telnet telnet(lC) user interface to a remote system using the TELNET protocol test test(lV) return true or false according to a conditional expression textedit textedit(l) SunView window- and mouse-based text editor textedit_filters textedit filters(l) filters provided with textedit(l) tftp tftp(lC) trivial file transfer program then csh(l) C shell built-in commands, see csh(l) time time(lV) time a command tip tip(lC) connect to remote system toolplaces toolplaces(l) display current window locations, sizes, and other attributes touch touch(lV) update the access and modification times of a file tput tput(lV) initialize a terminal or query the terminfo database tr tr(lV) translate characters trace trace(l) trace system calls and signals traffic traffic(lC) SunView program to display Ethernet traffic troff troff(l) typeset or format documents true true(l) provide truth values tset tset(l) establish or restore terminal characteristics tsort tsort(l) topological sort tty tty(l) display the name of the terminal u3b machid(l) return a true exit status if the processor is of the indicated type u3b2 machid(l) return a true exit status if the processor is of the indicated type u3b5 machid(l) return a true exit status if the processor is of the indicated type u3bl5 machid(l) return a true exit status if the processor is of the indicated type ul ul(l) do underlining umask csh(l) C shell built-in commands, see csh(l) unalias csh(l) C shell built-in commands, see csh(l) uname uname(l) display the name of the current system uncompress compress(l) compress or expand files, display expanded contents unexpand expand(l) expand TAB characters to SPACE characters, and vice versa unget sccs-unget(l) undo a previous get of an SCCS file unhash csh(l) C shell built-in commands, see csh(l) unifdef unifdef(l) resolve and remove ifdef’ed lines from cpp input uniq uniq(l) remove or report adjacent duplicate lines units units(l) conversion program unix2dos unix2dos(l) convert text file from ISO format to DOS format unlimit csh(l) C shell built-in commands, see csh(l) Sun Release 4.1 Last change: 4 March 1988 11 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) unload unload(l) unload optional clusters unloadc unload(l) unload optional clusters unpack pack(lV) compress and expand flies unset csh(l) C shell built-in commands, see csh(l) unsetenv csh(l) C shell built-in commands, see csh(l) unwhiteout unwhiteout(l) remove a TFS whiteout entry uptime uptime(l) show how long the system has been up users users(l) display a compact list of users logged in ustar ustar(lV) process tape archives uucp uucp(lC) system to system copy uudecode uuencode(lC) encode a binary file, or decode its ASCII representation uuencode uuencode(lC) encode a binary file, or decode its ASCII representation uulog uucp(lC) system to system copy uuname uucp(lC) system to system copy uupick uuto(lC) public system-to-system file copy uusend uusend(lC) send a file to a remote host uustat uustat(lC) UUCP status inquiry and job control uuto uuto(lC) public system-to-system file copy uux uux(lC) remote system command execution vacation vacation(l) reply to mail automatically val sccs-val(l) validate an SCCS file vax machid(l) return a true exit status if the processor is of the indicated type vedit vi(l) visual display editor based on ex(l) vfontinfo vfontinfo(l) inspect and print out information about fonts vgrind vgrind(l) grind nice program listings vi vi(l) visual display editor based on ex(l) view vi(l) visual display editor based on ex(l) vplot vplot(l) plot graphics for a Versatec printer vswap vswap(l) convert a foreign font file vtroff vtroff(l) troff to a raster plotter vwidth vwidth(l) make a troff width table for a font w w(l) who is logged in, and what are they doing wait wait(l) wait for a process to finish wall wall(l) write to all users logged in wc wc(l) display a count of lines, words and characters what what(l) extract SCCS version information from a file whatis whatis(l) display a one-line summary about a keyword whereis whereis(l) locate the binary, source, and manual page for a command which which(l) locate a command; display its pathname or alias while csh(l) C shell built-in commands, see csh(l) who who(l) who is logged in on the system whoami whoami(l) display the effective current username whois whois(l) TCP/IP Internet user name directory service write write(l) write a message to another user xargs xargs(lV) construct the arguments list(s) and execute a command xget xsend(l) send or receive secret mail xsend xsend(l) send or receive secret mail xstr xstr(l) extract strings from C programs to implement shared strings yacc yacc(l) yet another compiler-compiler: parsing program generator yes yes(l) be repetitively affirmative ypcat ypcat(l) print values in a NIS data base ypmatch ypmatch(l) print the value of one or more keys from a NIS map yppasswd yppasswd(l) change your network password in the NIS database 12 Last change: 4 March 1988 Sun Release 4.1 INTRO ( 1 ) USER COMMANDS INTRO ( 1 ) ypwhich ypwhich(l) return hostname of NIS server or map master zcat compress(l) compress or expand files, display expanded contents Sun Release 4.1 Last change: 4 March 1988 13 ACCTCOM ( 1 ) USER COMMANDS ACCTCOM ( 1 ) NAME acctcom - search and print process accounting files SYNOPSIS acctcom [ -abfhikmqrtv ] [ -C sec ] [ -e time ] [ -E time ] [ -g group ] [ -H factor ] [ -I chars ] [ -1 line ] [ -n pattern ] [ -o output-file ] [ -O sec ] [ -s time ] [ -S time ] [ -u user ] DESCRIPTION acctcom reads filename, the standard input, or /var/adm/pacct, in the form described by acct(5) and writes selected records to the standard output. Each record represents the execution of one process. The output shows the COMMAND NAME, USER, TTYNAME, START TIME, END TIME, REAL (SEC), CPU (SEC), MEAN SIZE(K), and optionally, F ( the fork /exec flag: 1 for fork() without exec()), ST AT (the system exit status), HOG FACTOR, KCORE MIN, CPU FACTOR, CHARS TRNSFD, and BLOCKS READ (total blocks read and written). A “#’ is prepended to the command name if the command was executed with super-user privileges. If a process is not associated with a known terminal, a “?’ is printed in the TTYNAME field. If no filenames are specified, and if the standard input is associated with a terminal or /dev/null (as is the case when using *&’ in the shell), /var/adm/pacct is read; otherwise, the standard input is read. If my filename arguments are given, they are read in their respective order. Each file is normally read for- ward, that is, in chronological order by process completion time. The file /var/adm/pacct is usually the current file to be examined; a busy system may need several such files of which all but the current file are found in /var/adm/pacct?. OPTIONS -a -b -f -h — i -k -m -q -r -t —v -C sec — e time -E time -g group -H factor Show some average statistics about the processes selected. The statistics will be printed after the output records. Read backwards, showing latest commands first. This option has no effect when the stan- dard input is read. Print the fork/exec flag and system exit status columns in the output. The numeric output for this option will be in octal. Instead of mean memory size, show the fraction of total available. CPU time consumed by the process during its execution. This “hog factor” is computed as: (total CPU time)/(elapsed time) Print columns containing the I/O counts in the output. Instead of memory size, show total kcore-minutes. Show mean core size (the default). Do not print any output records, just print the average statistics as with the -a option. Show CPU factor (user time/(system-time + user-time). Show separate system and user CPU times. Exclude column headings from the output. Show only processes with total CPU time, system plus user, exceeding sec seconds. Select processes existing at or before time. Select processes ending at or before time . Using the same time for both — S and — E shows the processes that existed at time. Show only processes belonging to group. The group may be designated by either the group ID or group name. Show only processes that exceed factor, where factor is the “hog factor” as explained in the -h option above. 14 Last change: 12 January 1990 Sun Release 4.1 ACCTCOM ( 1 ) USER COMMANDS ACCTCOM ( 1 ) -I chars Show only processes transferring more characters than the cutoff number given by chars. -1 line Show only processes belonging to terminal /dev/line. -n pattern Show only commands matching pattern that may be a regular expression as in regexp(3). -oofile Copy selected process records in the input data format to ofile; suppress standard output printing. -O sec Show only processes with CPU system time exceeding sec seconds. -s time Select processes existing at or after time , given in the format hr [ : min [ : sec ] ] . -S time Select processes starting at or after time . -u user Show only processes belonging to user that may be specified by: a user ED, a login name that is then converted to a user ID, a '#’, which designates only those processes executed with super-user privileges, or *?’, which designates only those processes associated with unknown user IDs. FILES /etc/passwd /var/adm/pacct /etc/group SEE ALSO ps(l), su(lV) acct(2V), regexp(3), acct(5), utmp(5V), acct(8), acctcms(8), acctcon(8), acctmerg(8), acctprc(8), acctsh(8), fwtmp(8), runacct(8) BUGS acctcom reports only on processes that have terminated; use ps(l) for active processes. If time exceeds the present time, then time is interpreted as occurring on the previous day. Sun Release 4.1 Last change: 12 January 1990 15 ADB(l) USER COMMANDS ADB(l) NAME adb - general-purpose debugger SYNOPSIS adb [ -w ] [ -k ] [ -I dir ] [ objectfile [ corefile ] ] AVAILABILITY adb is available with the Debugging software installation option. Refer to Installing SunOS 4.1 for infor- mation on how to install optional software. DESCRIPTION adb is an interactive, general-purpose debugger. It can be used to examine files and provides a controlled environment for the execution of programs. objectfile 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 objectfile is a.out. corefile is assumed to be a core image file produced after executing objectfile . The default for corefile is core. OPTIONS -k Perform kernel memory mapping; should be used when corefile is a system crash dump or /dev/mem. -w Create both objectfile and corefile, if necessary, and open them for reading and writing so that they can be modified using adb. -I dir specifies a directory where files to be read with $< or $« (see below) will be sought; the default is /usr/lib/adb. USAGE Refer to adb in Debugging Tools for more complete information on how to use adb. Note: Some com- mands require that you compile progams to be debugged with the -go compiler flag; see cc(lV) for details. These commands are not currently available on Sun-4 systems; they are marked ‘-go only’ below. Commands adb reads commands from the standard input and displays responses on the standard output. It does not supply a prompt. It ignores the QUIT signal. INTERRUPT invokes the next adb command, adb generally recognizes command input of the form: [ address ] [, count ] command [ ; ] address and count (if supplied) are expressions that result, respectively, in a new current address, and a repetition count, command is composed of a verb followed by a modifier or list of modifiers. The symbol V represents the current location. It is initially zero. The default count is ‘1’. Verbs ? / @ $r $R $x $X > RETURN Print locations starting at address in objectfile. Print locations starting at address in corefile . Print the value of address itself. Interpret address as a source address. Print locations in objectfile or lines of source, as appropriate, -go only. Manage a subprocess. Print names and contents of CPU registers. Print names and contents of MC6888 1 registers, if any. Print the names and contents of FPA registers 0 through 15, if any. Print the names and contents of FPA registers 16 through 31, if any. Assign a value to a variable or register. Repeat the previous command with a count of 1. Increment V. Shell escape. 16 Last change: 18 February 1988 Sun Release 4.1 ADB ( 1 ) USER COMMANDS ADB ( 1 ) Modifiers Modifiers specify the format of command output. Each modifier consists of a letter, preceded by an integer repeat count. Format Modifiers The following format modifiers apply to the commands ?, /, @, and =. To specify a format, follow the command with an optional repeat count, and the desired format letter or letters: [ v ] [ [ r ]/. . . ] where v is one of these four command verbs, r is a repeat count, and / is one of the format letters listed below: o 0 q Q d D x X h H u U f F e or E b B c C s S Y 1 M z I a P A P t r n (V increment: 2) Print 2 bytes in octal. (4) Print 4 bytes in octal. (2) Print in signed octal. (4) Print long signed octal. (2) Print in decimal. (4) Print long decimal. (2) Print 2 bytes in hexadecimal. (4) Print 4 bytes in hexadecimal. (2) Print 2 bytes in hexadecimal in reverse order. Sun386i systems only. (4) Print 4 bytes in hexadecimal in reverse order. Sun386i systems only. (2) Print as an unsigned decimal number. (4) Print long unsigned decimal. (4) Print a single-precision floating-point number. (8) Print a double-precision floating-point number. (12) Print a 96-bit MC68881 extended-precision floating-point number. Sun-2 or Sun-3 systems only. (1) Print the addressed byte in octal. (1) Print the addressed byte in hexadecimal. Sun386i systems only. (1) Print the addressed character. (1) Print the addressed character using A escape convention. ( n ) Print the addressed string. («) Print a string using the ' escape convention. (4) Print 4 bytes in date format. (n) Print as machine instructions. (n) Print as machine instructions along with machine code. Sun386i systems only. (n) Print with MC68010 machine instruction timings. Sun-2 or Sun-3 system only. (0) Print the source text line specified by V. -go only. (0) Print the value of V in symbolic form. (4) Print the addressed value in symbolic form. (0) Print the value of V in source-symbol form. (4) Print the addressed value in source-symbol form. (0) Tab to the next appropriate TAB stop. (0) Print a SPACE. (0) Print a NEWLINE. (0) Print the enclosed string. (0) Decrement V. (0) Increment V. (0) Decrement V by 1. Modifiers for ? and / Only I value mask Apply mask and compare for value ; move V to matching location. L value mask Apply mask and compare for 4-byte value', move V to matching location, w value Write the 2-byte value to address. W value Write the 4-byte value to address. Sun Release 4. 1 Last change- 18 February 1988 17 ADB(l) USER COMMANDS ADB ( 1 ) m bl el /i[?] : Modifiers b commands B commands w commands D r c s s s Ss t k es u i t k A R $ Modifiers filename 7 r R x X b c C d e w Map new values for bl, el, fl. If the ? or / is followed by * then the second segment {bl , el ,fl) of the address mapping is changed. Set breakpoint, execute commands when reached. Set breakpoint using source address, execute commands when reached, —go only. Set a data write breakpoint at address . Like b except that the breakpoint is hit when the program writes to address . Sun386i systems only. Delete breakpoint at source address, -go only. Run objectfile as a subprocess. The subprocess is continued with signal s. Single-step the subprocess with signal s. Single-step the subprocess with signal s using source lines, -go only. Add the signal specified by address to the list of signals passed directly to the subpro- cess. Remove the signal specified by address from the list implicitly passed to the subprocess. Single-step the subprocess with signal s using source lines, -go only. Like s, but steps over subroutine calls instead of into them. Sun386i systems only. Continue uplevel, stopping after the current routine has returned. Should only be given after the frame pointer has been pushed on the stack. Sun386i systems only. Add the signal specified by address to the list of signals passed directly to the subpro- cess Remove the signal specified by address from the list implicitly passed to the subprocess. Terminate the current subprocess, if any. Attach the process whose process ID is given by address. The PID is generally preceded by Ot so that it will be interpreted in decimal. Sun386i systems only. Release (detach) the current process. Sun386i systems only. Read commands from the file filename. Similar to <, but can be used in a file of commands without closing the file. Append output to filename, which is created if it does not exist. Print process ID, the signal which stopped the subprocess, and the registers. Print the names and contents of the general CPU registers, and the instruction addressed by pc. On Sun-3 systems with an MC6888 1 floating-point coprocessor, print the names and contents of the coprocessor’s registers. On Sun-3 systems with a Floating Point Accelerator (FPA), print the names and contents of FPA floating-point registers 0 through 15. On Sun-4 systems, print the names and contents of the floating-point registers 0 through 15. On Sun-3 systems with an FPA, print the names and contents of FPA registers 16 through 31. On Sun4 systems, print the names and contents of floating-point registers 16 through 31. Print all breakpoints and their associated counts and commands. C stack backtrace. On Sun4 systems, it is impossible for adb to determine how many parameters were passed to a function. The default that adb chooses in a $c command is to show the six parameter registers. This can be overridden by appending a hexadecimal number to the $c command, specifying how many parameters to display. For example, the $cf command will print 15 parameters for each function in the stack trace. C stack backtrace with names and (32 bit) values of all automatic and static variables for each active function, (-go only). Set the default radix to address and report the new value. Note: address is interpreted in the (old) current radix. Thus ‘10$d’ never changes the default radix. Print the names and values of external variables. Set the page width for output to address (default 80). 18 Last change: 18 February 1988 Sun Release 4.1 ADB ( 1 ) USER COMMANDS ADB ( 1 ) s 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 filenames, (-go only), p Print a list of known procedure names, (-go only). p ( Kernel debugging) Change the current kernel memory mapping to map the designated user structure to the address given by _u ( u on Sun386i systems); this is the address of the user’s proc structure. 1 Show which signals are passed to the subprocess with the minimum of adb interference. W Reopen objectfile and corefile for writing, as though the -w command-line argument had been given. 1 Set the length in bytes (1, 2, or 4) of the object referenced by :a and :w to address. Default is 1. Sun386i systems only. Variables Named variables are set initially by adb but are not used subsequently. 0 The last value printed. 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 corefile or objectfile as appropriate, b The base address of the data segment. B The number of an address register that points to the FPA page. Sun-3 systems only, d The data segment size, e The entry point. F On Sun-3 systems, a value of ‘ 1 ’ indicates FPA disassembly, m The ‘magic’ number (0407, 0410 or 0413). s The stack segment size, t The text segment size. Expressions & integer int.fr ac ’ cccc ’ outfile CTRL-D (hold down ‘control’ and depress ‘D’) This sequence, which demonstrates redirecting standard error to a pipe, is useful in a shell procedure (the sequence of output redirection specifications is significant): batch «! nroff filename 2>&1 > outfile | mail loginid t To have a job reschedule itself, invoke at from within the shell procedure, by including code similar to the following within the shell file: at 1900 thursday next week shellfile FILES /var/spool/cron /var/spooI/cron/at.allow /var/spool/cron/at.deny /var/spool/cron/atjobs main cron directory list of allowed users list of denied users spool area SEE ALSO atq(l), atrm(l), csh(l), kill(l), mail(l), nice(l), ps(l), sh(l), umask(2V), cron(8) DIAGNOSTICS Complaints about various syntax errors and times out of range. BUGS If the system crashes, mail stating that the job was not completed is not sent to the user. Shell interpreter specifiers (such as, !/bin/csh) in the beginning of script are ignored. Sun Release 4.1 Last change: 31 October 1988 31 ATQ(l) USER COMMANDS ATQ(l) NAME atq - display the queue of jobs to be run at specified times SYNOPSIS atq [ -c ] [ — n ] username. . . DESCRIPTION atq prints the queue of jobs, created with the at(l) command, that are waiting to be run at later date. With no flags, the queue is sorted in chronological order of execution. If no usernames are specified, the entire queue is displayed; otherwise, only those jobs belonging to the named users are displayed. OPTIONS -c Creation time. Sorted the queue by the time that the at command was given, the most recently created job first. -n Number of jobs. Print the total number of jobs currently in the queue. Do not list them. FILES /var /spool/cron spool area SEE ALSO at(l), atrm(l), cron(8) 32 Last change: 9 September 1987 Sun Release 4.1 ATRM(l) USER COMMANDS ATRM(l) NAME atrm - remove jobs spooled by at or batch SYNOPSIS atrm [ -f i ] [ - ] [job-number ] . . . [ username ] . . . DESCRIPTION atrm removes delayed-execution jobs that were created with the at(l) command. The list of jobs can be displayed by atq(l). atrm removes each job-number you specify, and/or all jobs belonging to username, provided that you own the indicated jobs. Jobs belonging to other users can only be removed by the super-user. OPTIONS -f Force. All information regarding the removal of the specified jobs is suppressed. -i Interactive, atrm asks if a job should be removed; a response of y verifies that the job is to be removed. — Remove jobs that were queued by the current user. If invoked by the super-user, the entire queue will be flushed. FILES /var/spool/cron spool area SEE ALSO at(l), atq(l), cron(8) Sun Release 4.1 Last change: 9 September 1987 33 AWK(l) USER COMMANDS AWK(l) NAME awk - pattern scanning and processing language SYNOPSIS awk [ -f program-file ] [ -Fc ] [ program ] [ variable -value . . . ] [ filename . . . ] DESCRIPTION awk scans each of its input filenames for lines that match any of a set of patterns specified in program. The input filenames are read in order; the standard input is read if there are no filenames. 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 program-file' option, the set of patterns may be in a program-file; a program-file of means the standard input. If the program is specified on the command line, it should be enclosed in single quotes (') to protect it from the shell. awk variables may be set on the command line using arguments of the form variable =value. This sets the awk variable variable to value before the first record of the next filename argument is read. With each pattern in program there can be an associated action that will be performed when a line of a filename matches the pattern. See the discussion below for the format of input lines and the awk language. Each line in each input filename 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 program-file as the source for the program. -Fc Use the character c as the field separator (FS) character. See the discussion of FS below. USAGE Input Lines An input line is made up of fields separated by white space. The field separator can be changed by using FS — see Special Variable Names below. Fields are denoted $1, $2, and so forth. $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. Action Statements 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 ] Sprintf 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, NEWLINE characters or right braces. An empty expression-list stands for the whole line. 34 Last change: 24 September 1987 Sun Release 4.1 AWK(l) USER COMMANDS AWK(l) 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. variable 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 The print statement prints its arguments on the standard output (or on a file if >filename is present), separated by the current output field separator, and terminated by the output record separator. The printf statement formats its expression list according to the format template format (see printf(3V) for a descrip- tion of the formatting control characters). Built In Functions The built-in function length returns the length of its argument taken as a string, or of the whole line if no argument. There are also built-in functions exp, log, sqrt, and int, where int truncates its argument to an integer. ‘substr( s, m, n )’ returns the « -character substring of s that begins at position m. ‘sprintf (for- mat, expression, expression, . . .)’ formats the expressions according to the printf format given by format, and returns the resulting string. Patterns Patterns are arbitrary Boolean combinations (!, 1 1 , &&, and parentheses) of regular expressions and rela- tional expressions. Regular expressions must be surrounded by slashes and are as in egrep (see grep(l V)), 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 performed for all lines between an occurrence of the first pattern and the next occurrence of the second. A relational expression is one of the following: expression matchop regular-expression expression relop expression where a relop is any of the six relational operators in C, and a matchop is either ' (contains) or !' (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 -Fc option. Other variable names with special meanings include NF, the number of fields in the current record; NR, the ordinal number of the current record; FILENAME, the name of the current input file; OFS, the output field separator (default blank); ORS, the output record separator (default NEWLINE); and OFMT, the output for- mat for numbers (default %.6g). EXAMPLES Print lines longer than 72 characters: length > 72 Print first two fields in opposite order: { print $2, $1 } Sun Release 4.1 Last change: 24 September 1987 35 AWK(l) USER COMMANDS AWK(l) Add up first column, print sum and average: { s += $1 } END { print "sum is", s, " average is", s/NR } Print fields in reverse order: { 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 grep(lV), lex(l), sed(lV), printf(3V) Editing Text Files A. V. Aho, B. W. Keminghan, P. J. Weinberger, The AWK Programming Language Addison-Wesley, 1988. NOTES The awk command is not changed to support 8-bit symbol names, as this would produce awk source code that is not portable between systems. BUGS Input white space is not preserved on output if fields are involved. 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 the null string (" ") to it. There is no escape sequence that prints a double-quote. A workaround is to use the sprintf (see printf(3V)) function to store the character into a variable by its ASCII sequence. dq = sprintf(" %c", 34) Syntax errors result in the cryptic message ‘awk: bailing out near line 1’. 36 Last change: 24 September 1987 Sun Release 4.1 BANNER (IV) USER COMMANDS BANNER (IV) NAME banner - display a string in large letters SYNOPSIS /usr/5bin/banner strings AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION banner prints its arguments (each up to 10 characters long) in large letters on the standard output. SEE ALSO echo(lV) BUGS When banner is used with characters from the top half of the Latin- 1 character set (see iso_8859_l(7)), each character is mapped to a best approximation for that character based on the available ASCII character shapes (for example, diacritical marks are removed). Sun Release 4. 1 Last change: 24 September 1987 37 BAR(l) USER COMMANDS BAR(l) NAME bar - create tape archives, and add or extract files SYNOPSIS bar [ - ] crxtu [ 014578feovwbXlFmhpBisHSUZRTIN ] [ bar-file ] [ blocksize ] [ exclude-file ] [ string ] [ target_directory ] [ user_id ] [ include-file ] filenamel . . . [ -C dir filename ... ] . . . DESCRIPTION bar archives and extracts multiple files onto a single bar, file archive, called a bar-file. It is quite similar to tar(5), but it has additional function modifiers, can read and write multiple volumes, and writes and reads a format that is incompatible with tar (see bar(5)). A bar-file is usually a magnetic tape, but it can be any file, bar’s actions are controlled by the first argument, the key, a string of characters containing exactly one function letter from the set rxtuc, and one or more of the optional function modifiers listed below. Other arguments to bar are file or directory names that specify which files to archive or extract. In all cases, the appearance of a directory name refers recursively to the files and subdirectories of that direc- tory. FUNCTION LETTERS c Create a new bar-file and write the named files onto it. r Write the named files on the end of the bar-file. Note: this option does not work with quarter-inch archive tapes. x Extract the named files from the bar-file. If a named file matches a directory with contents written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no filename arguments are given, all files in the archive are extracted. Note: if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions. t List the table of contents of the bar-file. u Add the named files to the bar-file if they are not there or if they have been modified since they were last archived. Note: this option does not work with quarter-inch archive tapes. FUNCTION MODIFIERS 014578 Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid drives. The default is /dev/rmt8. f Use the next argument as the name of the bar-file. If f is omitted, use the device indicated by the TAPE environment variable, if set. Otherwise, use /dev/rmt8 by default. If bar-file is given as bar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, bar can be used as the head or tail of a filter chain, bar can also be used to copy hierarchies with the command: example % cd fromdir; bar cf — . | (cd todir; bar xfBp -) e If any unexpected errors occur bar exits immediately with a positive exit status. o Suppress information specifying owner and modes of directories which bar normally places in the archive. Such information makes former versions of bar generate an error message like: filename; cannot create when they encounter it. v Verbose. Normally bar does its work silently; the v option displays the name of each file bar treats, preceded by the function letter. When used with the t function, v displays the bar-file entries in a form similar to ‘Is -1 38 Last change: 19 February 1988 Sun Release 4.1 USER COMMANDS BAR ( 1 ) BAR(l) w Wait for user confirmation before taking the specified action. If you use w, bar displays the action to be taken followed by the file name, and then waits for a y response to proceed. No action is taken on the named file if you type anything other than a line beginning with y. b Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. The block size is determined automatically when reading tapes (key letters x and t). This determination of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). The maximum blocking factor is determined only by the amount of memory available to bar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utilization. X Use the next argument as a file containing a list of named files (or directories) to be excluded from the bar-file when using the key letters ‘c\ ‘x’, or ‘t’. Multiple X arguments may be used, with one exclude-file per argument. 1 Display error messages if all links to archived files cannot be resolved. If 1 is not used, no error mes- sages are printed. F With one F argument specified, exclude all directories named SCCS from bar-file. With two arguments FF, exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out. m Do not extract modification times of extracted files. The modification time will be the time of extrac- tion. h Follow symbolic links as if they were normal files or directories. Normally, bar does not follow sym- bolic links. p Restore the named files to their original modes, ignoring the present umask(2V). Setuid and sticky information are also extracted if you are the super-user. This option is only useful with the x key letter. B Force bar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that bar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. i Ignore directory checksum errors. s Force the ownership of extracted files to match the bar process’s effective user ID and group ID. H The string of up to 128 characters is to be used as a volume header ID. A volume header is written to each volume of the archive when the c function letter is specified. See bar(5) for the volume header’s format. Use of the H function modifier when creating an archive allows bar to read volumes out of sequence. When extracting a file that spans volumes, bar will identify the tape(s) it needs to extract the entire file. If the wrong volume is inserted, bar issues a warning and prompts again for the correct volume. S Place files specified for extraction in this target directory when used with the x function letter. U Specify the user ID in the volume header when creating archive, when the H function modifier is used. If the c function letter is specified and a volume header exists, bar will verify that the user ids match before overwriting bar-file if the N modifier is specified. Z Specify compression, bar will compress files when used with the c function letter and will decompress files when used with the x function letter, bar will neither compress a compressed file, nor decompress a decompressed file. R Read the volume header and print the information to stdout. N See if the user owns the media (uid matches that in the bar header) before overwriting bar-file with the C key word. Sun Release 4.1 Last change: 19 February 1988 39 BAR(l) USER COMMANDS BAR(l) T When using the x or t function letters, terminate the search of the media after all the files specified are extracted (for x) or listed (for t). I Use the next argument as a file containing a list of named files, one per line, to be included in the bar archive. The include file expects filenames to be followed by a semicolon and newline character. In the case where excluded files (see X flag) also exist, excluded files take precedence over all included files. So, if a file is specified in both the include and exclude files (or on the command line), it will be excluded. OPTIONS -C dir filename In a c (create) or r (replace) operation, bar performs a chdir (see csh(l)) to that directory before inter- preting filename. This allows multiple directories not related by a close common parent to be archived using short relative path names. For example, to archive files from /usr/include and from /etc, one might use: example % bar c -C /usr include -C /etc . If you get a table of contents from the resulting bar-file, you will see something like: include/ include/a.out.h and all the other files in /usr/include . . Ahown and all the other files in /etc Note: the -C option only applies to one following directory name and one following file name. EXAMPLES Here is a simple example using bar to create an archive of your home directory on a tape mounted on drive /dev/rmtO: example% cd example % bar cvf /dev/rmtO . messages The c option means create the archive; the v option makes bar tell you what it’s doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmtO in this example). Here is another example: /dev/rmtO: example% cd example% bar cvfH /dev/rmtO "THIS IS MY HEADER" . messages As in the first example, the c option means create the archive; the v option makes bar tell you what it’s doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmtO in this example). The H option says to use the string "THIS IS MY HEADER" as the ID field in the volume header. Now you can read the table of contents from the archive like this: example% bar tvf /dev/rmtO (access user-id/group-id size mod. date filename) rw .r-r- 1677/40 2123 Nov 7 18:15:1985 Varchive/test.c example% 40 Last change: 19 Februar y 1988 Sun Release 4.1 BAR(l) USER COMMANDS BAR ( 1 ) You can extract files from the archive like this: example% bar xvf /dev/rmtO messages If there are multiple archive files on a tape, each is separated from the following one by an EOF marker, bar does not read the EOF mark on the tape after it finishes reading an archive file because bar looks for a special header to decide when it has reached the end of the archive. Now if you try to use bar to read the next archive file from the tape, bar does not know enough to skip over the EOF mark and tries to read the EOF mark as an archive instead. The result of this is an error message from bar to the effect: bar: blocksize=0 This means that to read another archive from the tape, you must skip over the EOF marker before starting another bar command. You can accomplish this using the mt command, as shown in the example below. Assume that you are reading from /dev/nrmtO. example % bar xvfp /dev/nrmtO read first archive from tape messages i example% mt fsf 1 skip over the end-of-file marker example% bar xvfp /dev/nrmtO read second archive from tape messages example% Finally, here is an example using bar to transfer files across the Ethernet. First, here is how to archive files from the local machine (example) to a tape on a remote system (host): example% bar cvfb - 20 filenames | rsh host dd of=/dev/rmt0 obs=20b messages exam pie % In the example above, we are creating a bar-file with the c key letter, asking for verbose output from bar with the v option, specifying the name of the output bar-file using the f option (the standard output is where the bar-file appears, as indicated by the - sign), and specifying the blocksize (20) with the b option. If you want to change the blocksize, you must change the blocksize arguments both on the bar command and on the dd command. Now, here is how to use bar to get files from a tape on the remote system back to the local system: example% rsh -n host dd if=/dev/rmtO bs=20b | bar xvBfb - 20 filenames messages example% In the example above, we are extracting from the bar-file with the x key letter, asking for verbose output from bar with the v option, telling bar it is reading from a pipe with the B option, specifying the name of the input bar-file using the f option (the standard input is where the bar-file appears, as indicated by the sign), and specifying the blocksize (20) with the b option. FILES /dev/rmt? /dev/rar? /dev/rst? /tmp/bar* ENVIRONMENT TAPE If specified, in the environment, the value of TAPE indicates the default tape device. half-inch magnetic tape interface quarter-inch magnetic tape interface SCSI tape interface Sun Release 4. 1 Last change: 19 February 1988 41 BAR(l) USER COMMANDS BAR ( 1 ) NOTES bar will handle multiple volumes gracefully. If a tape error is encountered, bar issues a message on the standard error requesting a new volume. The presence of a new volume is confirmed when bar reads a line beginning with Y or y on the standard input; a line beginning with N or n aborts the archive; with any other character bar reissues the prompt. SEE ALSO cpio(l), mt(l), umask(2V), bar(5), tar(5), dump(8), restore(8) BUGS Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives cannot backspace. There is no way to ask for the nth occurrence of a file. The u option can be slow. There is no way selectively to follow symbolic links. When extracting tapes created with the r or u options, directory modification times may not be set correctly. Files with names longer than 100 characters cannot be processed. Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form: bar xvf. . . /dev/rstO ‘bar tf. . . /dev/rstO | grep 'pattern If you specify as the target file and the archive spans volumes, the request for a new volume may get lost. 42 Last change: 19 February 1988 Sun Release 4.1 BASENAME ( 1 V ) USER COMMANDS BASENAME ( 1 V ) NAME basename, dimame - display portions of pathnames and filenames SYNOPSIS basename string [ suffix ] dirname string AVAILABILITY The dirname command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION basename deletes any prefix ending in / and the suffix, if present in string. It directs the result to the stan- dard output, and is normally used inside substitution marks 0 ') within shell procedures. dirname delivers all but the last level of the path name in string. EXAMPLES This shell procedure invoked with the argument /usr/src/bin/cat.c compiles the named file and moves the output to cat in the current directory: cc $1 mv a.out 'basename $1 .c' The following example will set the shell variable NAME to /usr/src/cmd: NAME=‘dirname /usr/src/cmd/cat.c‘ SEE ALSO sh(l) Sun Release 4.1 Last change: 17 September 1989 43 BC(1) USER COMMANDS BC(1) NAME be - arbitrary-precision arithmetic language SYNOPSIS be [ -c ] [ -1 ] [filename . . .] DESCRIPTION be is an interactive processor for a language which resembles C but provides unlimited precision arith- metic. be takes input from any files given, then reads the standard input. OPTIONS -c Compile only, be is actually a preprocessor for dc(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. -1 Is the name of an arbitrary precision math library. USAGE Comments Enclosed in / * and * /. Names Simple variables: /, where, l is a lower-case letter. Array elements: [[expression], where, expression is a legal be expression. The words ibase, obase, and scale. Other Operands Arbitrarily long numbers with optional sign and decimal point. ( expression ) sqrt ( expression ) length ( expression ) Number of significant decimal digits scale ( expression ) Number of digits right of decimal point l ( expression , expression ) Operators + -*/%* (% is remainder; A is exponent) ++ — (prefix and postfix; apply to names) == <= >=!=<> Statements expression {statement ; . . . ; statement } where, statement is a legal be statement. if ( expression)statement while ( expression ) statement for ( expression ; expression ; expression ) statement null statement break quit Function Definitions define {(/,...,/){ auto l I statement ; . . . statement return ( expression ) } 44 Last change: 24 September 1987 Sun Release 4.1 BC( 1) USER COMMANDS BC(1) Functions in -1 Math Library s(x) sine c(x) cosine e(x) exponential K*) log a(x) arctangent j (n,x) Bessel function All function arguments are passed by value. The value of a statement that is an expression is printed unless the main operator is an assignment. Either semicolons or newlines may separate statements. Assignment to scale influences the number of digits to be retained on arithmetic operations in the manner of dc(l). Assignments to ibase or obase set the input and output number radix respectively. The same letter may be used as an array, a function, and a simple variable simultaneously. All variables are global to the program. ‘Auto’ variables are pushed down during function calls. When using arrays as function arguments or defining them as automatic variables empty square brackets must follow the array name. EXAMPLES Define a function to compute an approximate value of the exponential function: scale = 20 define e(x){ auto a, b, c, i, s a = 1 b = 1 s = 1 for(i=l; 1==1; i++){ a = a*x b = b*i c = a/b if(c == 0) 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) FILES /usr/lib/Iib.b mathematical library dc(l) desk calculator proper SEE ALSO dc(l) BUGS for statement must have all three expression’ s. quit is interpreted when read, not when executed. Sun Release 4.1 Last change: 24 September 1987 45 BIFF ( 1 ) USER COMMANDS BIFF(l) NAME biff - give notice of incoming mail messages SYNOPSIS biff [yin] DESCRIPTION biff turns mail notification on or off for the terminal session. With no arguments, biff displays the current notification status for the terminal. If notification is allowed, the terminal rings the bell and displays the header and the first few lines of each arriving mail message, biff operates asynchronously. For synchronized notices, use the MAIL variable of sh(l) or the mail variable of csh(l). A ‘biff y’ command can be included in your .login or .profile file for execution when you log in. OPTIONS y Allow mail notification for the terminal, n Disable notification for the terminal. FILES .login .profile SEE ALSO cmdtool(l), csh(l), mail(l), sh(l), shelltool(l), sunview(l), comsat(8C) BUGS You must have ownership the terminal to change its mail-notification status with biff, but windows running under sunview(l) are owned by the super-user. If you enable mail notification for the workstation console (in your .login or .profile file), incoming mail notices also appear on console windows running under sun- view(l). See shelltool(l) or cmdtool(l) for details. 46 Last change: 9 September 1987 Sun Release 4.1 BIN-MAIL ( 1 ) USER COMMANDS BIN-MAIL ( 1 ) NAME bin-mail, binmail - an early program for processing mail messages SYNOPSIS /usr/bin/mail [ -ipq ] [ -f filename ] address /usr/bin/mail recipient . . . DESCRIPTION Note: This is the old version 7 UNIX system mail program. The default mail command, /usr/ucb/mail is described in mail(l). /usr/bin/mail with no address prints a user’s mail, message-by-message in last-in, first-out order, /usr/bin/mail accepts commands from the standard input to direct disposition messages. When addresses are named, /usr/bin/mail takes the standard input up to an EOF (or a line with just ‘.’) and routes it through the mailer daemon to each recipient. See sendmail(8) for details. The message is preceded by the sender’s name and a postmark. Lines that look like postmarks are prepended with *>’. A recipient is a user name recognized by login(l), a network address or local mail alias, or a filename (see aliases(5) for details). If there is any pending mail, login tells you there is mail when you log in. It is also possible to have the C shell, or the daemon biff tell you about mail that arrives while you are logged in. To forward mail automatically, add the addresses of additional recipients to the .forward file in your home directory. Note: forwarding addresses must be valid, or the messages will bounce. You cannot, for instance, reroute your mail to a new host by forwarding it to your new address if it is not yet listed in the Network Information Service (NIS) aliases domain. OPTIONS -i -P -q -f filename USAGE 9 CTRL-D l command + RETURN d dq m [ recipient ] n P q Ignore interrupts. Print messages without prompting for commands. Exit immediately upon receiving an interrupt. Quit immediately upon interrupt. Use filename as if it were the mail file. Print a command summary. Put unexamined mail back in the mail file and quit. Escape to the shell to do command. Go back to previous message. Go on to next message. Go on to next message. Delete message and go on to the next. Delete message and quit. . . . Mail the message to the named recipients (yourself is default). Go on to next message. Print message (again). Same as EOT . Sun Release 4.1 Last change: 28 November 1988 47 BIN-MAIL ( 1 ) USER COMMANDS BIN-MAIL ( 1 ) s [ filename] ... Save the message in the named filenames (‘inbox’ default). If saved successfully, remove it from the list and go on to the next message. w [filename ] . . . Save the message, without a header, in the named filenames (‘mbox’ default). If saved successfully, remove it from the list and go on to the next message. x Exit without changing the mail file. FILES /etc/passwd /var/spool/mail/* /usr/ucb/mail mbox /tmp/ma* /var/spool/mail/* .lock dead .letter $HOME/.forward SEE ALSO biff(l), csh(l), des(l), sendmail(8) BUGS Race conditions sometimes result in a failure to remove a lock file. The super-user can read your mail, unless it is encrypted by des(l), xsend(l), or crypt(3). Even if you encrypt it, the super-user can delete it. NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. to identify sender and locate address incoming mail for user * routes input through daemon to recipients saved mail temp file lock for mail directory unmailable text is saved here list of forwarding recipients login(l), mail(l), uucp(lC), uux(lC), write(l), xsend(l), crypt(3), aliases(5). 48 Last change: 28 November 1988 Sun Release 4.1 CAL(l) USER COMMANDS CAL ( 1 ) NAME cal - display a calendar SYNOPSIS cal [ [ month ] year ] DESCRIPTION cal displays a calendar for the specified year. If a month is also specified, a calendar for that month only is displayed. If neither is specified, a calendar for the present month is printed. year can be between 1 and 9999. Be aware that ‘cal 78’ refers to the early Christian era, not the 20th cen- tury. Also, the year is always considered to start in January, even though this is historically naive. month is a number between 1 and 12. The calendar produced is that for England and her colonies. Try September 1752. Sun Release 4.1 Last change: 9 September 1987 49 CALENDAR ( 1 ) USER COMMANDS CALENDAR ( 1 ) NAME calendar - a simple reminder service SYNOPSIS calendar [ - ] DESCRIPTION calendar consults the file calendar in the current directory and displays lines that contain today’s or tomorrow’s date anywhere in the line. Most reasonable month-day dates — such as ‘Dec. 7,’ ‘december 7,’ and ‘12/7’ — are recognized, but ‘7 December’ or ‘7/12’ are not. If you give the month as with a date — for example, “* 1” — that day in any month will do. On weekends “tomorrow” extends through Monday. When the optional ’ argument is present, calendar does its job for every user who has a file calendar in his login directory and sends him any positive results by mail(l). Normally this is done daily in the wee hours under control of cron(8). The file calendar is first run through the C preprocessor, cpp(l), to include any other calendar files specified with the usual #include syntax. Included calendars are usually shared by all users, and main- tained by the system administrator. FILES '/calendar /usr/lib/calendar to figure out today’s and tomoirow’s dates /etc/passwd /tmp/cal* /lib/cpp SEE ALSO at(l), cpp(l), grep(l V), mail(l), aliases(5), cron(8) NOTES The argument works only on calendar files that are local to the machine; calendar is intended not to work on calendar files that are mounted remotely with NFS. Thus, ‘calendar should be run only on diskful machines where home directories exist; running it on a diskless client has no effect. calendar is no longer in the default root crontab. Because of the network burden ‘calendar -’ can induce, it is inadvisable in an environment running ypbind (see ypserv(8)) with a large passwd.byname map. However, if the usefulness of calendar outweighs the network impact, the super-user may run ‘crontab -e’ to edit the root crontab. Otherwise, individual users may wish to use ‘crontab -e’ to edit their own crontabs to have cron invoke calendar without the *-’ argument, piping output to mail addressed to them- selves. BUGS calendar ’s extended idea of “tomorrow” does not account for holidays. Problems may occur when there is no /etc/passwd file on the local host. The calendar mail will be sent to the user at the machine on which ‘calendar is run. If the system administrator wants the mail to be sent to another machine, mail aliases should be set up accordingly. 50 Last change: 18 August 1989 Sun Release 4.1 CAT (IV) USER COMMANDS CAT (IV) NAME cat - concatenate and display SYNOPSIS cat [ - ] [ -benstuv ] [ filename . . . ] SYSTEM V SYNOPSIS /usr/5bin/cat [ - ] [ -estuv ] [filename. . . ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION cat reads each filename in sequence and displays it on the standard output. Thus: example % cat goodies displays the contents of goodies on the standard output, and example% cat goodiesl goodies2 > goodies3 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. If the standard input is a terminal, input is terminated by an EOF condition. OPTIONS -b Number the lines, as -n, but omit the line numbers from blank lines. -e Display non-printing characters, as -v, and in addition display a $ character at the end of each line. -n Precede each line output with its line number. -s Substitute a single blank line for multiple adjacent blank lines. -t Display non-printing characters, as -v, and in addition display TAB characters as A I (CTRL-I). -u Unbuffered. If -u is not used, output is buffered in blocks, or line-buffered if standard output is a terminal. -v Display non-printing characters (with the exception of TAB and NEWLINE characters) so that they are visible. Control characters print like ' X for CTRDX; the DEL character (octal 0177) print as ,A ?’. Non- ASCII characters (with the high bit set) are displayed as M-x where M- stands for ‘meta’ and x is the character specified by the seven low order bits. SYSTEM V OPTIONS -e If the -v option is specified, display a $ character at the end of each line. -s Suppress messages about files which cannot be opened. -t If the -v option is specified, display TAB characters as A I (CTRL-I) and FORMFEED characters as A L (CTRL-L). -v Display non-printing character (with the exception of TAB, NEWLINE, and FORMFEED charac- ters) so that they are visible. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout cat. On entry to cat, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. Sun Release 4.1 Last change: 19 July 1989 51 CAT(IV) USER COMMANDS CAT (IV) SEE ALSO cp(l)> ex(l), more(l), pg(lV), pr(lV), tail(l) NOTES Beware of ‘cat a b > a’ and ‘cat a b > b\ which destroy the input files before reading them. 52 Last change: 19 July 1989 Sun Release 4.1 CB(1) USER COMMANDS CB ( 1 ) NAME cb - a simple C program beautifier SYNOPSIS cb [ -js ] [ -1 leng ] [filename.. . ] DESCRIPTION cb reads C programs either from its arguments or from the standard input and writes them on the standard output with spacing and indentation that displays the structure of the code. indent(l) is preferred. OPTIONS With no options, cb preserves all user NEWLINE characters. -j Join. Split lines are put back together. -s Standard C style. Formats the code to the style of Kemighan and Ritchie in The C Programming Language. -I leng Split lines longer than leng. SEE ALSO indent(l) B.W. Kemighan and D.M. Ritchie, The C Programming Language, Prentice-Hall, 1978 BUGS Punctuation hidden in preprocessor statements can cause indentation errors. Sun Release 4. 1 Last change: 9 September 1987 53 CC(1V) USER COMMANDS CC(1V) NAME cc - C compiler SYNOPSIS cc [ -a ] [ -align _block ] [ -B binding ] [ -c ] [ -C ] [ -dalign ] [ -dryrun ] [ -D name [=def\ ] [ -E ] [ float option ] [ -fsingle ] [ -g ] [ -go ] [ -help ] [ -I pathname ] [ - J ] [ -L directory ] [ -M ] [ -misalign ] [ -o outputfile ] [ -O [level] ] [ — p ] [ — P ] [ -pg ] [ -pic ] [ -PIC ] [ -pipe ] [ -Qoption prog opt ] [ -Qpath pathname ] [ -Qproduce sourcetype ] [ — R ] [ — S ] [ -sb ] [ -target target arch ] [ —temp =directory ] [ -time ] [ -U name ] [ -w ] sourcefile . . . [ -llibrary ] SYSTEM V SYNOPSIS /usr/5bin/cc arguments /usr/xpg2bin/cc arguments Note: arguments to /usr/5bin/cc and /usr/xpg2bin/cc are identical to those listed above. AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION cc is the C compiler. It translates programs written in the C programming language into executable load modules, or into relocatable binary programs for subsequent loading with the ld(l) link editor. In addition to the many options, cc accepts several types of filename arguments. For instance, files with names ending in .c are taken to be C source programs. They are compiled, and each resulting object pro- gram is placed in the current directory. The object file is named after its source file — the suffix .0 replac- ing .c in the name of the object. In the same way, files whose names end with .s are taken to be assembly source programs. They are assembled, and produce .0 files. Filenames ending in .il are taken to be inline expansion code template files; these are used to expand calls to selected routines in-line when code optimi- zation is enabled. See FILES, below for a complete list of compiler-related filename suffixes. Other arguments refer to assembler or loader options, object programs, or object libraries. Unless -c, -S, -E -P or -Qproduce is specified, these programs and libraries, together with the results of any specified compilations or assemblies, are loaded (in the order given) to produce an output file named a.out. You can specify a name for the executable by using the -o option. If a single file is compiled and loaded all at once, the intermediate file is deleted. /usr/xpg2bin/cc is a shell script that should be used to compile X/Open compliant applications. /usr/5bin/cc and /usr/xpg2bin/cc accept the same arguments and options as cc. /usr/xpg2bin/cc searches /usr/xpg2include for #include files before /usr/include, and specifies /usr/xpg21ib/libxpg.a as an addi- tional static library of object-library routines. OPTIONS When debugging or profiling objects are compiled using the -g or -pg options, respectively, the Id com- mand for linking them should also contain the appropriate option. See ld(l) for link-time options. -a Insert code to count how many times each basic block is executed. Invokes a run-time recording mechanism that creates a .d file for every .c file (at normal termination). The .d file accumulates execution data for the corresponding source file. The tcov(l) utility can then be run on the source file to generate statistics about the program. Since this option entails some optimization, it is incompatible with — g. -align _block Force the global uninitialized data symbol block to be page-aligned by increasing its size to a whole number of pages, and placing its first byte at the beginning of a page. -B binding Specify whether bindings of libraries for linking are static or dynamic, indicating whether libraries are non-shared or shared, respectively. 54 Last change: 6 October 1988 Sun Release 4.1 CC(1V) USER COMMANDS CC(1V) -C -C -dalign -dryrun -Dname[=def] -E float_option -fsingle -g -go -help Suppress linking with ld(l) and produce a .0 file for each source file. A single object file can be named explicitly using the -0 option. Prevent the C preprocessor, cpp(l), from removing comments. (Sun-4 systems only.) Generate double load/store instructions whenever possible for improved performance. Assumes that all double typed data are double aligned, and should not be used when correct alignment is not assured. Show but do not execute the commands constructed by the compilation driver. Define a symbol name to the C preprocessor (cpp(l)). Equivalent to a #define directive in the source. If no def is given, name is defined as ‘1’. Run the source file through cpp(l), the C preprocessor, only. Sends the output to the standard output, or to a file named with the -o option. Includes the cpp line numbering information. (See also, the -P option.) Floating-point code generation option. Can be one of: -f68881 Generate in-line code for Motorola MC68881 floating-point processor (sup- ported only on Sun-3 systems). -ffpa Generate in-line code for Sun Floating Point Accelerator (supported only on Sun-3 systems). -fsky Generate in-line code for Sky floating-point processor (supported only on Sun-2 systems). -fsoft Generate software floating-point calls. Supported only on Sun-2 and Sun-3 systems, for which it is the default. -fstore Insure that expressions allocated to extended precision registers are rounded to storage precision whenever an assignment occurs in the source code. Only has effect when -f68881 is specified (Sun-3 systems only). -fswitch Run-time-switched floating-point calls. The compiled object code is linked at runtime to routines that support one of the above types of floating point code. This was the default in previous releases. Only for use with programs that are floating-point intensive, and must be portable to machines with vari- ous floating-point hardware options (supported only on Sun-2 and Sun-3 sys- tems). (Sun-2, Sun-3 and Sun-4 systems) Use single-precision arithmetic in computations involving only float expressions. Do not convert everything to double, which is the default. Note: floating-point parameters are still converted to double precision, and functions returning values still return double- precision values. Although not standard C, certain programs run much faster using this option. Be aware that some significance can be lost due to lower-precision intermediate values. Produce additional symbol table information for dbx(l) and dbxtool(l) and pass -lg option to ld(l) (so as to include the g library, that is: /usr/lib/libg.a). When this option is given, the -O and -R options are suppressed. Produce additional symbol table information for adb(l). When this option is given, the -O and -R options are suppressed. Display helpful information about cc. Sun Release 4.1 Last change: 6 October 1988 55 CC(1V) USER COMMANDS CC(1V) -I pathname -J -Uibrary -L directory -M -misalign -o outputfile — O [level] -P -P -Pg -pic -PIC -pipe Add pathname to the list of directories in which to search for #include files with relative filenames (not beginning with slash 7’). The preprocessor first searches for #include files in the directory containing sourcefile, then in directories named with -I options (if any), and finally, in /usr/include. Generate 32-bit offsets in switch statement labels (supported only on Sun-2 and Sun-3 systems). Link with object library library (for ld(l)). This option must follow the sourcefile argu- ments. Add directory to the list of directories containing object-library routines (for linking using ld(l). Run only the macro preprocessor on the named C programs, requesting that it generate makefile dependencies and send the result to the standard output (see make(l) for details about makefiles and dependencies). Generate code to allow loading and storage of misaligned data (Sun-4 systems only). Name the output file outputfile. outputfile must have the appropriate suffix for the type of file to be produced by the compilation (see FILES, below), outputfile cannot be the same as sourcefile (the compiler will not overwrite the source file). Optimize the object code. Ignored when either -g, -go, or -a is used. -O with the level omitted is equivalent to -02. On Sun386i systems, any level supplied is treated as level 1. level is one of: 1 Do postpass assembly-level optimization only. 2 Do global optimization prior to code generation, including loop optimi- zations, common subexpression elimination, copy propagation, and automatic register allocation. -02 does not optimize references to or definitions of external or indirect variables. 3 Same as -02, but optimize uses and definitions of external variables. -03 does not trace the effects of pointer assignments. Neither -03 nor -04 should be used when compiling either device drivers, or pro- grams that modify external variables from within signal handlers. 4 Same as -03, but trace the effects of pointer assignments. Prepare the object code to collect data for profiling with prof(l). Invokes a run-time recording mechanism that produces a mon.out file (at normal termination). Run the source file through cpp(l), the C preprocessor, only. Puts the output in a file with a .i suffix. Does not include cpp-type line number information in the output. Prepare the object code to collect data for profiling with gprof(l). Invokes a run-time recording mechanism that produces a gmon.out file (at normal termination). Produce position-independent code. Each reference to a global datum is generated as a dereference of a pointer in the global offset table. Each function call is generated in pc- relative addressing mode through a procedure linkage table. The size of the global offset table is limited to 64K on MC68000-family processors, or to 8K on SPARC processors. Like -pic, but allows the global offset table to span the range of 32-bit addresses in those rare cases where there are too many global data objects for -pic. Use pipes, rather than intermediate files, between cpp(l) and ccom compilation stages. Very cpu-intensive. 56 Last change: 6 October 1988 Sun Release 4.1 CC(1V) USER COMMANDS CC(1V) — Qoption prog opt Pass the option opt to the program prog. The option must be appropriate to that program and may begin with a minus sign, prog can be one of: as, cpp, inline, or id. -Qpath pathname Insert directory pathname into the compilation search path, pathname will be searched for alternate compilation programs, such as cpp(l), and ld(l). This path will also be searched first for certain relocatable object files that are implicidy referenced by the com- piler driver, for example *crt*.o and bb_link.o. -Qproduce sourcetype Produce source code of the type sourcetype. sourcetype can be one of: .c C source (from bb count). .i Preprocessed C source from cpp(l). .0 Object file from as(l). .s Assembler source (from inline, or c2). -R Merge data segment with text segment for as(l). Data initialized in the object file pro- duced by this compilation is read-only, and (unless linked with Id -N) is shared between processes. Ignored when either -g or -go is used. -S Do not assemble the program but produce an assembly source file. -sb Generate extra symbol table information for the Sun Source Code Browser. This is an unbundled product that will be released based on 4.1. -target target _arch Compile object files for the specified processor architecture. Unless used in conjunction with one of the Sun Cross-Compilers, correct programs can be generated only for the architecture of the host on which the compilation is performed. target_arch can be one of: sun2 Produce object files for a Sun-2 system. sun3 Produce object files for a Sun-3 system. sun4 Produce object files for a Sun-4 system. -temp ^directory Set directory for temporary files to be directory. -time Report execution times for the various compilation passes. -Uname Remove any initial definition of the cpp(l) symbol name. Inverse of the -D option. -w Do not print warnings. ENVIRONMENT FILES FLOAT_OPTION (Sun-2, Sun-3, Sun4 systems only.) When no floating-point option is specified, the compiler uses the value of this environment variable (if set). Recognized values are: f68881, ffpa, fsky, fswitch and fsoft. a.out executable output file file. a library of object files file .c C source file file A tcov(l) test coverage input file (Sun-2, Sun-3, Sun4 systems only) fileA C source file after preprocessing with cpp(l) file A inline expansion file file.o object file files assembler source file files assembler source for cpp(l) file. tco\ output from tcov(l) (Sun-2, Sun-3, Sun-4 systems only) /usr/lib/c2 object code optimizer Sun Release 4. 1 Last change: 6 October 1988 57 CC(1V) USER COMMANDS CC(1V) /usr/lib/ccom compiler /usr/lib/compile compiler command-line processing driver /usr/lib/cpp macro preprocessor /usr/lib/crtO.o runtime startup code /usr/lib/Fcrtl.o startup code for -fsoft option (Sun-2, Sun-3, Sun-4 systems only) /usr/lib/gcrtO.o startup for profiling with gprof(l) /usr/lib/Iibc.a standard library, see intro(3) /usr/lib/mcrtO.o startup for profiling with prof(l) intro(3) /usr/lib/Mcrtl.o startup code for -f68881 option (for Sun-3 systems) /lib/optim Sun386i code optimizer /lib/Scrtl.o startup code for -fsky option (for Sun-2 systems) /usr/lib/Wcrtl.o startup code for -ffpa option (for Sun-3 systems) /usr/include standard directory for #include files /usr/lib/bb_link.o basic block counting routine /usr/lib/cg code generator used with /usr/lib/iropt /usr/lib/libc_p.a profiling library, see gprof(l) or prof(l) /usr/lib/inline inline expander of library calls /usr/Iib/iropt intermediate representation optimizer /usr/lib/libm.a math library /usr/51ib/libc.a System V standard compatibility library, see intro(3) /usr/51ib/libcjp.a System V profiling library, see gprof(l) or prof(l) /tmp/* compiler temporary files /usr/xpg2include directory for X/Open #include files /usr/xpg21ib/Iibxpg.a X/Open XPG2 compatibility library /usr/xpg21ib/Iibxpg_p.a Profiled version of X/Open XPG2 compatibility library mon.ouf file produced for analysis by prof(l) gmon.out file produced for analysis by gprof(l) .cb subdirectory that holds the information generated by the -cb option SEE ALSO adb(l), ar(lV), as(l), cflow(lV), cpp(l), ctags(l), cxref(lV), dbx(l), dbxtool(l), gprof(l), inline(l), ld(l), lint(lV), m4(lV), make(l), prof(l), tcov(l), intro(3), monitor(3) Numerical Computation Guide Programming Utilities and Libraries B. W. Kemighan and D. M. Ritchie, The C Programming Language , Prentice-Hall, 1978 DIAGNOSTICS The diagnostics produced by the C compiler are intended to be self-explanatory. Occasional obscure mes- sages may be produced by the preprocessor, assembler, or loader. NOTES While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. The cc com- mand does not generate or support 8-bit symbol names because, until ANSI C, non-ASCn support was not expected. The ANSI C specification now suggests that string literals and comments can contain any charac- ters from any character code set. The following commands are affected by this lack of support for 8-bit characters: cflow(lV), cpp(l), ctags(l), cxref(lV), dbx(l), Iint(l V), m4(lV), and yacc(l). BUGS The program context given in syntax error messages is taken from the input text after the C preprocessor has performed substitutions. Therefore, error messages involving syntax errors in or near macro references or manifest constants may be misleading. 58 Last change: 6 October 1988 Sun Release 4.1 CC(1V) USER COMMANDS CC(1V) Compiling with optimization level 2 or greater may produce incorrect object code if tail-recursion elimina- tion is applied to functions called with fewer actual parameters (arguments) than the number of formal parameters in the function’s definition. Such parameter-count mismatches can be detected using Iint(lV). Sun Release 4. 1 Last change: 6 October 1988 59 CD( 1 ) USER COMMANDS CD ( 1 ) NAME cd - change working directory SYNOPSIS cd [ directory ] DESCRIPTION directory becomes the new working directory. The process must have execute (search) permission in directory. If cd is used without arguments, it returns you to your login directory. In csh(l) you may specify a list of directories in which directory is to be sought as a subdirectory if it is not a subdirectory of the current directory; see the description of the cdpath variable in csh(l). SEE ALSO csh(l), pwd(l), sh(l) 60 Last change: 9 September 1987 Sun Release 4.1 CFLOW(IV) USER COMMANDS CFLOW(IV) NAME cflow - generate a flow graph for a C program SYNOPSIS cflow [-r] [-ix] [ — i_ ] [ -Anum] filenames SYSTEM V SYNOPSIS cflow [ — r] [-ix] [ -i_ ] [ -Anum ] filenames AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION cflow analyzes a collection of C, yacc, lex, assembler, and object files and attempts to build a graph chart- ing the external references. Files suffixed in .y and .1 are run through yacc and lex, respectively; the out- put of yacc and lex for those files, and files suffixed in . c, are first run through the C preprocessor and then run through the first pass of lint(lV). (The -I, -D, and -U options of the C preprocessor are also under- stood.) Files suffixed in . i are passed directly to the first pass of lint. Files suffixed with . s are assembled. Information is extracted from the symbol tables of the output of the assembler and from files suffixed with . o. The output of all this non-trivial processing is collected and turned into a graph of external references which is displayed upon the standard output. Each line of output begins with a reference (that is, line) number, followed by a suitable number of tabs indicating the level. Then the name of the global (normally only a function not defined as an external or beginning with an underscore; see below for the -i inclusion option) a colon and its definition. For infor- mation extracted from C source, the definition consists of an abstract type declaration (for example, char *), and, delimited by angle brackets, the name of the source file and the line number where the definition was found. Definitions extracted from object files indicate the file name and location counter under which the symbol appeared (for example, text). Leading underscores in C-style external names are deleted. Once a definition of a name has been printed, subsequent references to that name contain only the reference number of the line where the definition may be found. For undefined references, only < > is printed. SYSTEM V DESCRIPTION The System V version of cflow in /usr/5bin/cflow makes the C preprocessor, cpp(l) search in /usr/5include for include files before it searches in /usr/include. OPTIONS The following options are interpreted by cflow : -r Reverse the “callerxallee” relationship producing an inverted listing showing the callers of each function. The listing is also sorted in lexicographical order by callee. -ix Include external and static data symbols. The default is to include only functions in the flowgraph. -i_ Include names that begin with an underscore. The default is to exclude these functions (and data if -ix is used). -Anum The num decimal integer indicates the depth at which the flowgraph is cut off. By default this is a very large number. Attempts to set the cutoff depth to a nonpositive integer will be met with con- tempt. Sun Release 4. 1 Last change: 16 September 1989 61 CFLOW(IV) USER COMMANDS CFLOW(IV) EXAMPLES As an example, given the following in file.c: int i; main() { } f() { } f(); gO; f(); i = h(); the command: cflow — ix file.c produces the output 1 main: int(), 2 f: int(), 3 h: <> 4 i: int, 5 g: <> When the nesting level becomes too deep, the -e option of pr(lV) can be used to compress the tab expansion to something less than eight spaces. SEE ALSO as(l), cc(lV), cpp(l), lex(l), lint(lV), nm(l), pr(lV), yacc(l) DIAGNOSTICS Complains about bad options. Complains about multiple definitions and only believes the first. Other mes- sages may come from the various programs used, such as the C preprocessor. NOTES While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. See cc(lV) for an explanation about why cc is not 8-bit clean. BUGS Files produced by lex and yacc cause the reordering of line number declarations which can confuse cflow. To get proper results, feed cflow the yacc or lex input. 62 Last change: 16 September 1989 Sun Release 4.1 CHECKNR ( 1 ) USER COMMANDS CHECKNR ( 1 ) NAME checknr - check nroff and troff input files; report possible errors SYNOPSIS checknr [ -fs ] [ -a . xl .yl .x2 .y2 ... .xn .yn ] [ -c ,xl ,x2 .x3 ... .xn ] [filename . . . ] AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION checknr checks a list of nroff(l) or troff(l) input files for certain kinds of errors involving mismatched opening and closing delimiters and unknown commands. If no files are specified, checknr checks the stan- dard input. Delimiters checked are: • Font changes using \ftt . . . \fP. • Size changes using \sx ... \s0. • Macros that come in open . . . close forms, for example, the .TS and .TE macros which must always come in pairs. checknr knows about the ms(7) and me(7) macro packages. checknr is intended to be used on documents that are prepared with checknr in mind. It expects a certain document writing style for \f and \s commands, in that each \fx must be terminated with \fP and each \sx must be terminated with \s0. While it will work to directly go into the next font or explicitly specify the original font or point size, and many existing documents actually do this, such a practice will produce com- plaints from checknr. Since it is probably better to use the \fP and \s0 forms anyway, you should think of this as a contribution to your document preparation style. OPTIONS -f Ignore \f font changes. -s Ignore \s size changes. -a jcI .yl... Add pairs of macros to the list. The pairs of macros are assumed to be those (such as .DS and .DE) that should be checked for balance. The -a option must be followed by groups of six characters, each group defining a pair of macros. The six characters are a period, the first macro name, another period, and the second macro name. For example, to define a pair .BS and .ES, use ‘-a.BS.ES’ -cjcI... Define commands which checknr would otherwise complain about as undefined. SEE ALSO eqn(l), nroff(l), troff(l), me(7), ms(7) BUGS There is no way to define a one-character macro name using the -a option. Sun Release 4.1 Last change: 22 December 1987 63 CHGRP(l) USER COMMANDS CHGRP(l) NAME chgrp - change the group ownership of a file SYNOPSIS chgrp [ -f ] [ -R ] groupfilename . . . DESCRIPTION chgrp changes the group ID (GID) of the filenames given as arguments to group. The group may be either a decimal GID or a group name found in the GID file, /etc/group. You must belong to the specified group and be the owner of the file, or be the super-user. OPTIONS -f Force. Do not report errors. -R Recursive, chgrp descends through the directory, and any subdirectories, setting the specified GID as it proceeds. When symbolic links are encountered, their group is changed, but they are not traversed. FILES /etc/group SEE ALSO chown(2V), group(5), passwd(5) 64 Last change: 9 September 1987 Sun Release 4.1 CHKEY(l) USER COMMANDS CHKEY(l) NAME chkey - create or change encryption key SYNOPSIS chkey DESCRIPTION chkey prompts the user for their login password, and uses it to encrypt a new encryption key for the user to be stored in the publickey(5) database. If the entry for nobody in the /etc/publickey database has not been commented out, chkey can be used to create new entries. If this entry has been commented out, chkey can only be used to change an existing entry. SEE ALSO keylogin(l), publickey(5), keyserv(8C), newkey(8) Sun Release 4.1 Last change: 18 January 1987 65 CHMOD(IV) USER COMMANDS CHMOD(IV) NAME chmod - change the permissions mode of a file SYNOPSIS chmod [ -fR ] mode filename . . . SYNOPSIS /usr/5bin/chmod [ -fR ] mode filename . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Change the permissions (mode) of a file or files. Only the owner of a file (or the super-user) may change its mode. The mode of each named file is changed according to mode, which may be absolute or symbolic, as fol- lows. Absolute Modes An absolute mode is an octal number constructed from the OR of the following modes: 400 Read by owner. 200 Write by owner. 100 Execute (search in directory) by owner. 040 Read by group. 020 Write by group. 010 Execute (search) by group. 004 Read by others. 002 Write by others. 001 Execute (search) by others. 4000 Set user ID on execution. 2000 Set group ID on execution (this bit is ignored if the file is a directory; it may be set or cleared only using symbolic mode). 1000 Sticky bit, (see chmod(2V) for more information). Symbolic Modes A symbolic mode has the form: [ who ] op permission [ op permission ] . . . who is a combination of: u User’s permissions, g Group permissions, o Others, a All, or ugo. If who is omitted, the default is a, but the setting of the file creation mask (see umask in sh(l) or csh(l) for more information) is taken into account. When who is omitted, chmod will not over- ride the restrictions of your user mask. op is one of: + To add the permission . - To remove the permission . = To assign the permission explicitly (all other bits for that category, owner, group, or oth- ers, will be reset). 66 Last change: 9 September 1987 Sun Release 4.1 CHMOD(IV) USER COMMANDS CHMOD(IV) permission is any combination of: r Read, w Write, x Execute. X Give execute permission if the file is a directory or if there is execute permission for one of the other user classes. s Set owner or group ID. This is only useful with u or g. Also, the set group ID bit of a directory may only be modified with *+’ or \ t Set the sticky bit to save program text between processes. The letters u, g, or o indicate that permission is to be taken from the current mode for the user- class. Omitting permission is only useful with ‘=\ to take away all permissions. Multiple symbolic modes, separated by commas, may be given. Operations are performed in the order specified. SYSTEM V DESCRIPTION If who is omitted in a symbolic mode, it does not take the file creation mask into account, but acts as if who were a. OPTIONS -f Force, chmod will not complain if it fails to change the mode of a file. -R Recursively descend through directory arguments, setting the mode for each file as described above. When symbolic links are encountered, their mode is not changed and they are not traversed. EXAMPLES The first example denies write permission to others, the second makes a file executable by all if it is execut- able by anyone: example% chmod o-w file example % chmod +X file SEE ALSO csh(l), ls(lV), sh(l), chmod(2V), chown(8) Sun Release 4.1 Last change: 9 September 1987 67 CLEAR ( 1 ) USER COMMANDS CLEAR ( 1 ) NAME clear - clear the terminal screen SYNOPSIS clear DESCRIPTION clear clears your screen if this is possible. It looks in the environment for the terminal type and then in /etc/termcap to figure out how to clear the screen. FILES /etc/termcap terminal capability data base 68 Last change: 9 September 1987 Sun Release 4.1 CLE AR_COLORMAP ( 1 ) USER COMMANDS CLE AR_COLORM AP ( 1 ) NAME clear_colormap — clear the colormap to make console text visible SYNOPSIS clear_colormap [ -no ] [ -f framebuffer ] DESCRIPTION clear_colormap ensures that text displayed on the console is visible. If no options are specified it clears the frame buffer and initializes the colormap entries for the first two colors and the last color. If the frame buffer has an overlay plane it is also cleared, its colormap is initialized, and the overlay enable plane is set so that the entire overlay plane is displayed. OPTIONS -n Do not clear the frame buffer or overlay plane. -o Do not clear the overlay plane, initialize its colormap, or modify the overlay enable plane. -f framebuffer Operate on frame buffer device framebuffer instead of the default, /dev/fb. FILES /dev/fb Sun Release 4. 1 Last change: 4 May 1989 69 CLEAR_FUNCTIONS ( 1 ) USER COMMANDS CLEAR_FUNCTIONS ( 1 ) NAME clear_functions - reset the selection service to clear stuck function keys SYNOPSIS clearfunctions DESCRIPTION clear_functions instructs the selection service that no function keys are currently depressed. It is useful in cases where erroneous programs have reported a key press but not the corresponding release. The usual symptom for this situation is that all selections are secondary (underscored rather than inverted), even though no function keys are down. FILES /usr/bin/selection_svc SEE ALSO SunView User’s Guide 70 Last change: 24 September 1987 Sun Release 4.1 CLICK ( 1 ) USER COMMANDS CLICK ( 1 ) NAME click - enable or disable the keyboard’s keystroke click SYNOPSIS click [ — y ] [ — n ] [ — d keyboard-device ] DESCRIPTION Change the setting of the audible keyboard click. The default is no keyboard click. If you want to turn clicking on then a good place to do it is in /etc/rc.local. Only keyboards that support a clicker respond to this command. At the time of this writing, the only key- boards known to have a clicker are the Sun-3 and Sun386i systems keyboards. OPTIONS -y Yes, enable clicking. -n No, disable clicking. -d keyboard-device Specify the keyboard device being set. The default is /dev/kbd. FILES /etc/rc.local /dev/kbd SEE ALSO kbd(4S) DIAGNOSTICS A short help message is printed if an unknown flag is specified or if the -d switch is used and the keyboard device name is not supplied. A diagnostic is printed if the keyboard device name can’t be opened or is not a keyboard type device. BUGS There is no way to determine the state of the keyboard click setting. Sun Release 4.1 Last change: 18 February 1988 71 CLOCK ( 1 ) USER COMMANDS CLOCK ( 1 ) NAME clock - display the time in an icon or window SYNOPSIS clock [ -frst ] [ -d mdyaw ] AVAILABILITY This command is available with the SunView User’ s software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION clock is a SunView utility that displays the current time in a window. When open, clock shows the date and time in text format. When closed, clock displays a clock face. Note: In previous releases clock was known as clocktool. In the current release, /usr/old/clocktool is a symbolic link to clock. OPTIONS -f Display the date and day of week on the clock face. -r Use a square face with roman numerals in the iconic state. This replaces the default round clock face. -s Start clock with the seconds turned on. By default, the clock starts with seconds turned off, and updates every minute. With seconds turned on, it updates every second, and, if iconic, displays a second hand. -t Test mode — ignore the real time, and instead run in a loop continuously incrementing the time by one minute and displaying it. -d Display date information in a small area just below the clock face. The date information to be displayed may include: m the month, d the day of the month (1-31), y the year, a the string AM or PM, as appropriate, w the day of the week (Sun-Sat). There is only room for 3 of these, but any 3 may be displayed in any sequence, clock also accepts all of the generic tool arguments discussed in sunview(l). USAGE clock listens for keyboard input while open. It recognizes the following characters: s or S Enable or disable the display of seconds, t or T Enable or disable “test” mode. FILES / usr/lib/ fonts/fixed widthfonts/sail.r. 6 font for day-of-month clock-face display SEE ALSO date(lV), sunview(l) NOTES When the -r option is specified, clock displays the roman numeral four as nn instead of IV to counterbal- ance the roman numeral eight, VIII. 72 Last change: 21 December 1987 Sun Release 4.1 CLOCK ( 1 ) USER COMMANDS CLOCK ( 1 ) BUGS If you reset the system time, clock will not reflect the new time until you change its state from open to icon, or vice versa. To reset the system time, see date(lV). The date display does not go well with the round clock face. Sun Release 4.1 Last change: 21 December 1987 73 CLUSTER ( 1 ) USER COMMANDS CLUSTER ( 1 ) NAME cluster - find the Application SunOS or Developer’s Toolkit optional cluster containing a file SYNOPSIS cluster [filename ] AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0_x release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION cluster finds the optional software cluster that contains a specified file. If the specified file is contained in one of the clusters in Application SunOS or Developer’s Toolkit, the name of the cluster will be printed on standard output. Without arguments, cluster displays a summary of the clusters in Application SunOS and Developers Toolkit, including the load state and size of each cluster. EXAMPLES To find the name of the cluster that contains the spell command: example % cluster spell spellcheck example% To display a summary of the clusters in Application SunOS and Developer’s Toolkit: % cluster Application SunOS Clusters: available cluster size (bytes) yes accounting 265K no advanced admin 501K Developer’s Toolkit Clusters: availablecluster size (bytes) no base devel 6907K space used by clusters: 6021K bytes total space remaining: 20432K bytes A cluster is available if it has been “loaded” using load(l) or if it has been “mounted” across the network. FILES /usr/lib/Ioad/* data files SEE ALSO load(l), unload(l), toc(5) Sun386i System Setup and Maintenance DIAGNOSTICS The file filenameis not in any of the optional software clusters. The specified file is not part of the Application SunOS or Developer’s Toolkit. 74 Last change: 19 February 1988 Sun Release 4.1 CMDTOOL ( 1 ) USER COMMANDS CMDTOOL ( 1 ) NAME cmdtool - run a shell (or program) using the SunView text facility SYNOPSIS cmdtool [ -C ] [ -M bytes ] [ -P count ] [ generic-tool-arguments ] [ program [ program-arguments ] ] AVAILABILITY This command is available with the SunView User's software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION cmdtool is the standard SunView support facility for shells and other programs. When invoked, cmdtool runs a program (usually a shell) in a text-based command subwindow. Characters typed on the keyboard are inserted at the caret. If the program is a shell, that shell accepts and runs commands in the usual manner, cmdtool also supports programs that perform cursor motions directly, such as vi(l). The text of the current command line can be edited using normal textedit(l) functions. The command subwindow displays a log of the session, which can be scrolled through using the scrollbar (unless the com- mand does cursor motion). This log can be edited, and saved by choosing the ‘Store as New File’ item in the text facility’s pop-up menu. The ‘Split View’ command, also in the pop-up menu, can be used to create two or more independent views of the log. OPTIONS -C Console cmdtool. Display console messages in this cmdtool, which might otherwise appear in unexpected places on the workstation screen. Since a cmdtool window can be scrolled, console error messages can be recorded for later examination. -M bytes Set the log to wrap-around after the indicated number of bytes . -P count Checkpoint the log after every set of count editing operations. generic-tool-arguments cmdtool accepts the generic tool arguments listed in sunview(l). program [ program-arguments ] If a program argument is present, cmdtool runs it and passes any remaining arguments to that program. If no program is given, cmdtool runs the program indicated by the SHELL environment variable, or /usr/bin/sh by default. USAGE Refer to SunView User’s Guide for details on how to use cmdtool. Defaults Options The following options can be configured as default settings using defaultsedit(l). /Tty/Append_only_log When set to TRUE (the standard default) only command lines can be edited. FALSE allows the entire log to be edited. (See also the description of Enable Edit below.) /Tty/lnsert_makes_caret_visible This entry allows you to specify the method for displaying the editing caret. Same_as_for_text Use the setting specified in the defaults for the Text category (the standard default). If_auto_scroIl If the caret is showing, and an inserted NEWLINE would position it below the bottom of the screen (as determined by /Text/Lower_context), the text is scrolled to keep the caret showing. The number of lines scrolled is deter- mined by the /Text/Auto_scrolI_by default. (See textedit(l) for more information.) Sun Release 4.1 Last change: 19 July 1989 75 CMDTOOL ( 1 ) USER COMMANDS CMDTOOL ( 1 ) Always Scroll the caret back into view whenever input would position it off the screen. /Tty/ Checkpoint_frequency If set to 0 (the standard default) no checkpointing is done. For any value greater than zero, a checkpoint is made each time the indicated number editing operations has been performed since the last checkpoint. Each character typed, each Paste, and each Cut counts as an editing opera- tion. At each checkpoint, an updated copy of the log is saved in a file with a name that is con- structed by appending two percent signs (% %) to the name of the log file. By default, the log file has a name of the form /tm p/tty .txt.p/d (pid is the process ID number of cmdtool); the corresponding checkpoint file has a name of the form /tm p/tty .txt.nnnn/m %%. /Tty/Text_wraparound_size If set to 0 (the standard default) no wrap-around takes place; the log file grows without a specified limit. For values greater than zero, wrap-around occurs whenever the indicated number of charac- ters have been written to the log since the last wrap-around. Characters that are pushed over the top are replaced by the message: *** Text is lost because the maximum edit log size has been exceeded. *** /Text/Edit_back_char Set the character for erasing to the left of the caret. Note: in cmdtool, the ‘stty erase’ command has no effect. Text-based tools refer only to the defaults database key settings. The default is DELETE. /Text/Edit_back_word Set the character for erasing the word to the left of the caret. The standard default is CTRL-W. /Text/Edit_back_line Set the character for erasing all characters to the left of the caret. Note: ‘stty kill’ has no effect in cmdtool. The standard default is CTRL-U. The Command Subwindow The command subwindow is based on the text facility, which is described in SunView User’s Guide. It uses the same pop-up menu as the text facility, but with an additional pull-right ‘Cmd Modes’ menu, which contains the ‘Enable Editing’ and ‘Disable Scrolling’ items. Command subwindows support cursor motions, using a new /etc/termcap entry called sun-cmd. Com- mand subwindows automatically set the TERM environment variable to sun-cmd. So, if you rlogin(lC) to a machine that does not have an entry for sun-cmd in its /etc/termcap file, the error message ‘Type sun- cmd unknown’ results. To rectify this, type the command ‘set TERM=sun’. Programs written using the curses(3V) library package will work in a command subwindow, but programs hard-coded for sun-type terminals may not. When supporting a program that performs cursor motions, the command subwindow automatically takes on the characteristics of a tty subwindow (as with shelltool(l)). When that program terminates or sleeps, the full command subwindow functionality is restored. cmdtool supports programs that use CBREAK and NO ECHO terminal modes. This support is normally invisible to the user. However, programs that use RAW mode, such as rlogin(lC) and script(l), inhibit command-line editing with the mouse. In this case, however, tty-style ERASE, word-kill and line-kill char- acters can still be used to edit the current command line. The Command Subwindow Menu Copy, then Paste When there is a current selection, the entire menu item is active. The selection is copied both to the clipboard and to the location pointed to by the caret. When there is no selection, but there is text on the clipboard, only Paste is active. In this case, the contents of the clipboard are copied to the caret. When there is no selection and the clipboard is empty, this item is inactive. ‘Copy then Paste’ is a generic text menu item. Refer to textedit(l) for information about other generic text menu items. 76 Last change: 19 July 1989 Sun Release 4.1 CMDTOOL ( 1 ) USER COMMANDS CMDTOOL ( 1 ) Enable Edit Disable Edit Toggle to allow or disallow editing on the log. Disable Scrolling Enable Scrolling Toggle between a scrollable, editable window, or a display that supports cursor motions. Note: for well-behaved programs (such as vi(l)) this switching is per- formed automatically (so this menu item is seldom needed). Accelerators Text facility accelerators that are especially useful in command subwindows are described here. See textedit(l) for more information. CTRL-RETURN Position the caret at the bottom, and scroll it into view as determined by /Text/Lower_context. META-P Choose the ‘Copy, then Paste’ menu item. CAPS -lock FI Toggle between all-upper-case keyboard input, and mixed-case. ENVIRONMENT The environment variables LC CTYPE, LANG, and LC_default control the character classification throughout cmdtool. On entry to cmdtool, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /tmp/tty.txt./M'd log file "/.textswrc ‘/.ttyswrc usr/lib/.text_extras_menu /etc/termcap SEE ALSO defaultsedit(l), rlogin(lC), script(l), sh(l), shelltool(l), sunview(l), textedit(l), vi(l), curses(3V) Installing SunOS 4.1 SunView User’s Guide BUGS Typing ahead while cmdtool changes between its scrollable and cursor motion modes will sometimes freeze cmdtool . Full terminal emulation is not complete. Some manifestations of this deficiency are: • File completion in the C shell does not work. • Enhanced display of text is not supported. Sun Release 4.1 Last change: 19 July 1989 77 CMP(l) USER COMMANDS CMP(l) NAME cmp - perform a byte-by-byte comparison of two files SYNOPSIS cmp [ -Is ] filename 1 filename2 [ skipl ] [ skip2 ] DESCRIPTION cmp compares filename 1 and filename2 . If filename 1 is the standard input is used. With no options, cmp makes no comment if the files are the same; if they differ, it reports the byte and line number at which the difference occurred, or, that one file is an initial subsequence of the other, skipl and sldp2 are initial byte offsets into filenamel and filename2 respectively, and may be either octal or decimal; a leading 0 denotes octal. OPTIONS -1 Print the byte number (in decimal) and the differing bytes (in octal) for all differences between the two files. -s Silent Print nothing for differing files; set exit codes only. SEE ALSO comm(l), diff(l) DIAGNOSTICS Exit code 0 is returned for identical files, 1 for different files, and 2 for an inaccessible or missing argu- ment, or a system error. 78 Last change: 23 November 1987 Sun Release 4.1 COL(IV) USER COMMANDS COL (IV) NAME col - filter reverse paper motions from nroff output for display on a terminal SYNOPSIS col [ -bfhp ] SYSTEM V SYNOPSIS /usr/5bin/col [ -bfpx ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION col copies the standard input to the standard output and performs line overlays implied by reverse LINEFEED characters (ESC-7 in ASCII) and by forward and reverse half LINEFEED characters (ESC-9 and ESC-8). col is particularly useful for filtering multicolumn output made with the .rt command of nroff(l), and output resulting from use of the tbl(l) preprocessor. The control characters SO (ASCII code 017), and SI (016) are assumed to start and end text in an alternate character set. The character set (primary or alternate) associated with each printing character read is remembered; on output, SO and SI characters are generated where necessary to maintain the correct treat- ment of each character. All control characters are removed from the input except SPACE, BACKSPACE, TAB, RETURN, NEWLINE, ESC (033) followed by one of 7, 8, 9, SI , SO , and VT (013). This last character is an alternate form of full reverse LINEFEED, for compatibility with some other hardware conventions. All other non-printing char- acters are ignored. SYSTEM V DESCRIPTION The System V version of col converts SPACE to TAB characters by default. OPTIONS -b The output device in use is not capable of backspacing. In this case, if several characters are to appear in the same place, only the last one read will be taken. -f Fine. Although col accepts half line motions in its input, it normally does not produce them on output. Instead, text that would appear between lines is moved to the next lower full-line boun- dary. The -f option suppresses this treatment. In this case the output from col may contain for- ward half LINEFEED characters (ESC-9), but will still never contain either kind of reverse line motion. -h Convert strings of blanks to TAB characters to decrease the printing time. — p Pass escape-sequences that col does not know about to the output, rather than stripping them out. This option is highly discouraged unless you are fully aware of the position of the escape sequences within the text. SYSTEM V OPTIONS —x Suppress converting SPACE characters to TAB characters. ENVIRONMENT The environment variables LC CTYPE, LANG, and LC default control the character classification throughout col. On entry to col, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. SEE ALSO nroff(l), tbl(l), troff(l), loca!e(5), iso_8859_l(7) Sun Release 4.1 Last change: 2 October 1989 79 COL (IV) USER COMMANDS COL(IV) BUGS col cannot back up more than 128 lines. At most 1600 characters, including BACKSPACE characters, are allowed on a line. Local vertical motions that would result in backing up over the first line of the document are ignored. As a result, the first line must not have any superscripts. 80 Last change: 2 October 1989 Sun Release 4.1 COLCRT ( 1 ) USER COMMANDS COLCRT ( 1 ) NAME colcrt - filter nroff output for a terminal lacking overstrike capability SYNOPSIS colcrt [ — ] [ — 2 ] [filename . . . ] DESCRIPTION colcrt provides virtual half and reverse LINEFEED sequences for terminals without such capability, and on which overstriking is destructive. Half LINEFEED characters and underlining (changed to dashing are placed on new lines in between the normal output lines. OPTIONS - Suppress all underlining — especially useful for previewing allboxed tables from tbl(l). -2 Print all half LINEFEED characters, effectively double spacing the output. Normally, a minimal space output format is used which suppresses empty lines, colcrt never suppresses two consecu- tive empty lines, however. The -2 option is useful for sending output to the line printer when the output contains superscripts and subscripts which would otherwise be invisible. EXAMPLE A typical use of colcrt would be example % tbl exum2.n | nroff -ms | colcrt — | more SEE ALSO col(lV), more(l), nroff(l), tbl(l), troff(l), ul(l) BUGS Cannot back up more than 102 lines. General overstriking is lost; as a special case ‘ | ’ overstruck with ‘ — ’ or underline becomes ‘ + ’. Lines are trimmed to 132 characters. Some provision should be made for processing superscripts and subscripts in documents which are already double-spaced. Sun Release 4.1 Last change: 9 September 1987 81 COLOREDIT ( 1 ) USER COMMANDS COLOREDIT ( 1 ) NAME coloredit - alter color map segment SYNOPSIS coloredit AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION coloredit is a SunView application for altering the colors of objects (windows) selected with the cursor. These colors may be manipulated in three ways: ® select color name from a list • specify the hue/saturation/value for a color • specify the red/green/blue levels for a color USAGE Window The coloredit window consists of four sections. colorlist An interactive window that lists the available colors for selection. This list can be scrolled up and down with a scrollbar, and comprises the contents of the .rgb file. Select a color and the corresponding RGB and HSV value appears in the colorbar section, coloredit first searches the working directory for .rgb, your home directory, and finally, /usr/lib this file. colorbars An interactive window with two sets of three sliding bars. One set is for defining the hue saturation value of the color desired. The second set is for defining the red-green-blue ratios. The color can be specified using either set of sliding bars. palette A display subwindow divided horizontally into two equal parts. The top part shows the background color; the bottom, the foreground color. If the object has more than 2 colors, all the colors are shown. The background color is color Index #0. The color with the highest Index Number is the foreground color. logo A display subwindow containing the Sun logo in the currently-selected color. Command Buttons The set of command buttons in the colorbars subwindow is as follows. Grab The next object selected will have its color map segment colors displayed in the coloredit win- dow. These colors may then be manipulated. Release Disassociates the colormap segment and the last object with which those colors were associated. The window returns to its default state. Undo Returns the colormap segment to the original colors that the object being colored had when color- ing began. Returns the object to its original colors. FILES •/•rgb "/.rgb /usr/lib/.rgb SEE ALSO sunview(l) 82 Last change: 19 February 1988 Sun Release 4.1 COLRM(l) USER COMMANDS COLRM(l) NAME colrm — remove characters from specified columns within each line SYNOPSIS colrm [ startcol [ endcol ] ] DESCRIPTION colrm removes selected columns from a text file. The text is taken from standard input and copied to the standard output with the specified columns removed. If only startcol is specified, the columns of each line are removed starting with startcol and extending to the end of the line. If both startcol and endcol are specified, all columns between startcol and endcol, inclusive, are removed. Column numbering starts with column 1. SEE ALSO expand(l) Sun Release 4.1 Last change: 9 September 1987 83 COMM ( 1 ) USER COMMANDS COMM ( 1 ) NAME comm - display lines in common, and lines not in common, between two sorted lists SYNOPSIS comm [-11-21-31 -12 1 -13 1 -23 ]filenamel filename 2 DESCRIPTION comm reads filenamel and filename2 , which should be ordered in ASCII collating sequence (see sort(lV)), and produces three-column output when no options are specified: • Column 1 contains lines that occur only in filenamel . • Column 2 contains lines only in filename2 . • Column 3 contains lines common to both files. The filename means the standard input. OPTIONS The following options can be used to suppress the indicated columns from display. You can specify ‘-123’, but doing so suppresses all output. -1 Suppress column 1; omit lines only in filenamel . -2 Suppress column 2; omit lines only in filename2 . -3 Suppress column 3; omit lines common to both files. -12 Suppress columns 1 and 2; only show lines common to both files. -13 Suppress columns 1 and 3; only show lines in filename2 . -23 Suppress columns 2 and 3; only show lines in filenamel . SEE ALSO cmp(l), diff(l), sort(lV), uniq(l) BUGS The options suppress , rather than select the columns you indicate. 84 Last change: 9 September 1987 Sun Release 4.1 COMPRESS ( 1 ) USER COMMANDS COMPRESS(l) NAME compress, uncompress, zcat - compress or expand files, display expanded contents SYNOPSIS compress [ -cfv ] [ -b bits ] [filename. . . ] uncompress [ -cv ] [filename ... ] zcat [filename... ] DESCRIPTION compress reduces the size of the named files using adaptive Lempel-Ziv coding. Whenever possible, each file is replaced by one with the extension .Z, while keeping the same ownership modes, as well as access and modification times. If no files are specified, the standard input is compressed to the standard output. The amount of compression obtained depends on the size of the input, the number of bits per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60%. Compression is generally much better than that achieved by Huffman coding (as used in sys-unconfig(8)), or adaptive Huffman coding (old-compact(l)), and takes less time to compute. The bits parameter specified during compression is encoded within the compressed file, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is subsequently allowed. Compressed files can be restored to their original form using uncompress. zcat produces uncompressed output on the standard output, but leaves the compressed . Z file intact. OPTIONS -c Write to the standard output; no files are changed. The nondestructive behavior of zcat is identi- cal to that of ‘uncompress -c\ -f Force compression, even if the file does not actually shrink, or the corresponding . Z file already exists. Except when running in the background (under sh(l)), if-f is not given, prompt to verify whether an existing . Z file should be overwritten. -v Verbose. Display the percentage reduction for each file compressed. -b bits Set the upper limit (in bits) for common substring codes, bits must be between 9 and 16 (16 is the default). SEE ALSO ln(lV), old-compact(l), sh(l), sys-unconfig(8) A Technique for High Performance Data Compression, Terry A. Welch, computer, vol. 17, no. 6 (June 1984), pp. 8-19. DIAGNOSTICS Exit status is normally 0. If the last file was not compressed because it became larger, the status is 2. If an error occurs, exit status is 1. Usage: compress [-fvc] [-b maxbits] [filename .. .] Invalid options were specified on the command line. Missing maxbits Maxbits must follow -b . filename: not in compressed format The file specified to uncompress has not been compressed. filename: compressed with xxbits, can only handle yy bits filename was compressed by a program that could deal with more bits than the compress code on this machine. Recompress the file with smaller bits. Sun Release 4. 1 Last change: 9 September 1987 85 COMPRESS ( 1 ) USER COMMANDS COMPRESS ( 1 ) filename : already has . Z suffix — no change The file is assumed to be already compressed. Rename the file and try again. filename: already exists; do you wish to overwrite (y or n)? Respond y if you want the output file to be replaced; n if not. uncompress: corrupt input A SIGSEGV violation was detected, which usually means that the input file is corrupted. Compression: xx.xx% Percentage of the input saved by compression. (Relevant only for -v.) — not a regular file: unchanged When the input file is not a regular file, (such as a directory), it is left unaltered. — has xx other links: unchanged The input file has links; it is left unchanged. See ln(l V) for more information. — file unchanged No savings are achieved by compression. The input remains uncompressed. BUGS Although compressed files are compatible between machines with large memory, -bl2 should be used for file transfer to architectures with a small process data space (64KB or less). compress should be more flexible about the existence of the . Z suffix. 86 Last change: 9 September 1987 Sun Release 4.1 CP(1) USER COMMANDS CP(1) NAME cp - copy files SYNOPSIS cp [ -ip ] filename 1 filename 2 cp -rR [ -ip ] directory 1 directory2 cp [ -iprR ] filename . . . directory DESCRIPTION cp copies the contents of filenamel onto filename2 . The mode and owner of filename2 are preserved if it already existed; the mode of the source file is used otherwise. If filenamel is a symbolic link, or a dupli- cate hard link, the contents of the file that the link refers to are copied; links are not preserved. In the second form, cp recursively copies directory 1 , along with its contents and subdirectories, to direc- tory2 . If directory2 does not exist, cp creates it and duplicates the files and subdirectories of directory 1 within it. If directory2 does exist, cp makes a copy of the directory 1 directory within directory2 (as a sub- directory), along with its files and subdirectories. In the third form, each filename is copied to the indicated directory, the basename of the copy corresponds to that of the original. The destination directory must already exist for the copy to succeed. cp refuses to copy a file onto itself. OPTIONS -i Interactive. Prompt for confirmation whenever the copy would overwrite an existing file. A y in answer confirms that the copy should proceed. Any other answer prevents cp from overwriting the file. -p Preserve. Duplicate not only the contents of the original file or directory, but also the modification time and permission modes. -r -R Recursive. If any of the source files are directories, copy the directory along with its files (includ- ing any subdirectories and their files); the destination must be a directory. EXAMPLES To copy a file: example % cp goodies goodies.old example% Is goodies* goodies goodies.old To copy a directory, first to a new, and then to an existing destination directory: example% Is 7bkup /usr/example/fred/bkup not found example% cp -r "/src 7bkup example% Is — R '/bkup x.c y.c z.sh example % cp -r 7src 7bkup example% Is -R 7bkup src x.c y.c z.sh src: x.c y.c z.sh To copy a list of files to a destination directory: example% cp 7src/* /tmp • SEE ALSO cat(lV), ln(lV), mv(l), pr(lV), rcp(lC), tar(l) Sun Release 4.1 Last change: 9 September 1987 87 CP(1) USER COMMANDS CP(1) WARNINGS Beware of a recursive copy like this: example % cp — r 7src 7src/bkup which keeps copying files until it fills the entire file system. BUGS cp copies the contents of files pointed to by symbolic links. It does not copy the symbolic link itself. This can lead to inconsistencies when directory hierarchies are replicated. Filenames that were linked in the ori- ginal hierarchy are no longer linked in the replica. This is also true for files with multiple hard links. See In(lV) for details about symbolic links and hard links. You can preserve links in replicated hierarchies by using tar(l) to copy them. 88 Last change: 9 September 1987 Sun Release 4.1 CPIO(l) USER COMMANDS CPIO(l) NAME cpio - copy file archives in and out SYNOPSIS cpio -o [ aBcv ] cpio -i [ bBcdfmrsStuv6 ] [ patterns ] cpio -p [ adlmuv ] directory DESCRIPTION cpio copies files in to and out from a cpio copy archive. The archive (built by ‘cpio -o’) contains path- name and status information, along with the contents of one or more archived files. OPTIONS -o Copy out an archive. Read the standard input for a list of pathnames, then copy the named files to the standard output in archive form — including pathname and status information. a Reset the access times of input files after they have been copied. B Output is to be blocked at 5120 bytes to the record. This does not apply to the pass option. This option is only meaningful with data directed to raw magnetic devices, such as ‘/dev/rmt?’. c Write header information in ASCII character form for portability. v Verbose. A list of filenames is displayed. When used with the t option, the fable of con- tents looks like the output of an ‘Is -I’ command (see Is(l V)). -i Copy in an archive. Read in an archive from the standard input and extract files with names matching filename substitution patterns , supplied as arguments. patterns are similar to those in sh(l) or csh(l), save that within cpio, the metacharacters “?’, and ‘[ ... ]’ also match the 7’ (slash) character. If no patterns are specified, the default is * (select all files). b Swap both bytes and half-words after reading in data. B Input is to be blocked at 5120 bytes to the record. This does not apply to the pass option. This option is only meaningful with data received from raw magnetic devices, such as ‘/dev/rmt?’. d Create directories as needed, f Copy in all files except those matching patterns. m Retain previous file modification time. This option is ineffective on directories that are being copied. r Interactively rename files. If the user types a null line, the file is skipped. May not be used with the -p option. s Swap bytes after reading in data. 5 Swap halfwords after reading in data. t Print a table of contents of the input archive. No files are created. u Copy unconditionally. Normally, an older file will not replace a newer file with the same name. 6 Process UNIX Version-6 files. -p One pass. Copy in and out in a single operation. Destination pathnames are interpreted relative to the named directory . 1 Whenever possible, link files rather than copying them. Sun Release 4.1 Last change: 6 September 1988 89 CPIO ( 1 ) USER COMMANDS CPIO(l) EXAMPLES To copy the contents of a directory into an archive: example% Is | cpio -o > /dev/mtO To read a cpio archive from a tape drive: example% cpio -icdB < /dev/rmtO To duplicate the olddir directory hierarchy in the newdir directory: example % cd olddir example% find . -depth -print | cpio -pdl newdir The trivial case example% find . -depth -print | cpio -oB >/dev/rmtO can be handled more efficiendy by: example% find . -cpio /dev/rmt/Om cpio archive tapes from other sites may have bytes swapped within the archive. Although the -is option only swaps the data bytes and not those in the header cpio recognizes tapes like this and swaps the bytes in the header automatically. SEE ALSO ar(lV), csh(l), find(l), ls(lV), sh(l), tar(l), cpio(5) BUGS cpio does not support multiple volume tapes. Pathnames are restricted to 128 characters. If there are too many unique linked files, cpio runs out of memory and linking information is lost thereafter. Only the super-user can copy special files. 90 Last change: 6 September 1988 Sun Release 4.1 CPP(l) USER COMMANDS CPP(l) NAME cpp - the C language preprocessor SYNOPSIS /usr/lib/cpp [ -BCHMpPRT ] [ -undef ] [ -Dname ] [ -Dname -def] [ -Idirectory ] [ -U name ] [ -Y directory ] [ input-file [ output-file ] ] DESCRIPTION cpp is the C language preprocessor. It is invoked as the first pass of any C compilation started with the cc(lV) command; however, cpp can also be used as a first-pass preprocessor for other Sun compilers. Although cpp can be used as a macro processor, this is not normally recommended, as its output is geared toward that which would be acceptable as input to a compiler’s second pass. Thus, the preferred way to invoke cpp is through the cc(lV) command, or some other compilation command. For general-purpose macro-processing, see m4(l V), and the chapter on m4 in Programming Utilities and Libraries. cpp optionally accepts two filenames as arguments, input-file and output-file are, respectively, the input and output files for the preprocessor. They default to the standard input and the standard output. OPTIONS -B Support the C++ comment indicator 7 /’. With this indicator everything on the line after the // is treated as a comment. -C Pass all comments (except those that appear on cpp directive lines) through the preprocessor. By default, cpp strips out C-style comments. -H Print the pathnames of included files, one per line on the standard error. -M Generate a list of makefile dependencies and write them to the standard output. This list indicates that the object file which would be generated from the input file depends on the input file as well as the include files referenced. -p Use only the first eight characters to distinguish preprocessor symbols, and issue a warning if extra tokens appear at the end of a line containing a directive. -P Preprocess the input without producing the line control information used by the next pass of the C compiler. -R Allow recursive macros. -T Use only the first eight characters for distinguishing different preprocessor names. This option is included for backward compatibility with systems which always use only the first eight characters. -undef Remove initial definitions for all predefined symbols. -Dname Define name as 1 (one). This is the same as if a -Dname=l option appeared on the cpp command line, or as if a #define name 1 line appeared in the source file that cpp is processing. -Dname =def Define name as if by a #define directive. This is the same as if a #define name def line appeared in the source file that cpp is processing. The -D option has lower precedence than the -U option. That is, if the same name is used in both a -U option and a -D option, the name will be undefined regardless of the order of the options. Sun Release 4.1 Last change: 25 January 1988 91 CPP(l) USER COMMANDS CPP(l) —I directory Insert directory into the search path for #include files with names not beginning with 7’. direc- tory is inserted ahead of the standard list of “include” directories. Thus, #include files with names enclosed in double-quotes (") are searched for first in the directory of the file with the #include line, then in directories named with -I options, and lastly, in directories from the stan- dard list. For #include files with names enclosed in angle-brackets (<>), the directory of the file with the #include line is not searched. See Details below for exact details of this search order. -U name Remove any initial definition of name, where name is a symbol that is predefined by a particular preprocessor. Here is a partial list of symbols that may be predefined, depending upon the archi- tecture of the system: Operating System: ibm, geos, os, tss and unix Hardware: interdata, pdpll, u370, u3b, u3b2, u3b5, u3bl5, u3b20d, vax, ns32000, iAPX286, i386, spare , and sun UNIX system variant: RES, and RT The lint(lV) command: lint The symbols sun and unix are defined for all Sun systems, as is the value returned by the mach command. For Sun-4 systems, this value would be spare. -Y directory Use directory directory in place of the standard list of directories when searching for #include files. USAGE Directives All epp directives start with a hash symbol (#) as the first character on a line. White space (SPACE or TAB characters) can appear after the initial # for proper indentation. #define name token-string Replace subsequent instances of name with token-string. #define name {argument [, argument ] . . . ) token-string There can be no space between name and the *(’• Replace subsequent instances of name, fol- lowed by a parenthesized list of arguments, with token-string , where each occurrence of an argu- ment in the token-string is replaced by the corresponding token in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded token- string unchanged. After the entire token-string has been expanded, epp re-starts its scan for names to expand at the beginning of the newly created token-string. #undef name Remove any definition for the symbol name. No additional tokens are permitted on the directive line after name . #include "filename " #include Read in the contents of filename at this location. This data is processed by epp as if it were part of the current file. When the notation is used, filename is only searched for in the stan- dard “include” directories. See the -I and -Y options above for more detail. No additional tokens are permitted on the directive line after the final or *>’. 92 Last change: 25 January 1988 Sun Release 4.1 CPP(l) USER COMMANDS CPP(l) #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 from where it comes. If " filename " is not given, the current filename is unchanged. No additional tokens are permitted on the directive line after the optional filename. #if constant-expression Subsequent lines up to the matching #else, #elif , or #endif directive, appear in the output only if constant-expression yields a nonzero value. All binary non-assignment C operators, including *&&’, ‘| |’, and V, are legal in constant-expression. The *?:’ operator, and the unary T, and operators, are also legal in constant-expression . The precedence of these operators is the same as that for C. In addition, the unary operator defined, can be used in constant-expression in these two forms: ‘defined ( name )’ or ‘defined name’. This allows the effect of #ifdef and #ifndef directives (described below) in the #if direc- tive. Only these operators, integer constants, and names that are known by cpp should be used within constant-expression . In particular, the size of operator is not available. #ifdef name Subsequent lines up to the matching #else, #elif, or #endif appear in the output only if name has been defined, either with a #define directive or a -D option, and in the absence of an intervening #undef directive. No additional tokens are permitted on the directive line after name. #ifndef name Subsequent lines up to the matching #else, #elif, or #endif appear in the output only if name has not been defined, or if its definition has been removed with an #undef directive. No additional tokens are permitted on the directive line after name . #elif constant-expression Any number of #elif directives may appear between an #if, #ifdef, or #ifndef directive and a matching #else or #endif directive. The lines following the #elif directive appear in the output only if all of the following conditions hold: • The constant-expression in the preceding #if directive evaluated to zero, the name in the preceding #ifdef is not defined, or the name in the preceding #ifndef directive was defined. • The constant-expression in all intervening #elif directives evaluated to zero. • The current constant-expression evaluates to non-zero. If the constant-expression evaluates to non-zero, subsequent #elif and #else directives are ignored up to the matching #endif. Any constant-expression allowed in an #if directive is allowed in an #elif directive. This inverts the sense of the conditional directive otherwise in effect. If the preceding conditional would indicate that lines are to be included, then lines between the #else and the matching #endif are ignored. If the preceding conditional indicates that lines would be ignored, subsequent lines are included in the output. Conditional directives and corresponding #else directives can be nested. End a section of lines begun by one of the conditional directives #if, #ifdef, or #ifndef. Each such directive must have a matching #endif. Macros Formal parameters for macros are recognized in #define directive bodies, even when they occur inside character constants and quoted strings. For instance, the output from: #defineabc(a) |\a| abc(xyz) #else #endif Sun Release 4. 1 Last change: 25 January 1988 93 CPP(l) USER COMMANDS CPP(l) is the seven characters “ | ‘xyz |” (SPACE, vertical-bar, backquote, x, y, z, vertical-bar). Macro names are not recognized within character constants or quoted strings during the regular scan. Thus: #defineabc xyz printf("abc"); does not expand abc in the second line, since it is inside a quoted string that is not part of a #define macro definition. Macros are not expanded while processing a #define or #undef. Thus: #define abc zingo #deiine xyz abc #undef abc xyz produces abc. The token appearing immediately after an #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 “ #define hello goodbye hello”. Output Output consists of a copy of the input file, with modifications, plus lines of the form: #lineno " filename " "level " indicating the original source line number and filename of the following output line and whether this is the first such line after an include file has been entered {level= 1), the first such line after an include file has been exited {level=2), or any other such line {level is empty). Details Directory Search Order #include files is: 1. The directory of the file that 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) (/usr/include on UNIX systems). Special Names Two special names are understood by cpp. The name _ _LINE_ _ is defined as the current line number (a decimal integer) as known by cpp, and FILE is defined as the current filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other defined name. Newline Characters A NEWLINE character 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 con- tinue the definition onto the next line. The escaped NEWLINE is not included in the macro value. Comments Comments are removed (unless the -C option is used on the command line). Comments are also ignored, except that a comment terminates a token. 94 Last change: 25 January 1988 Sun Release 4.1 CPP(l) USER COMMANDS CPP(l) SEE ALSO cc(lV), m4(lV) Programming Utilities and Libraries 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 ver- sions of cpp put out the NEWLINE characters as they were found and expanded. The current version of cpp replaces them with SPACE characters. Because the standard directory for included files may be different in different environments, this form of #include directive: #include should be used, rather than one with an absolute path, like: #include "/usr/include/file.h" cpp warns about the use of the absolute pathname. While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. See cc(lV) for an explanation about why cc is not 8-bit clean. Sun Release 4.1 Last change: 25 January 1988 95 CRONTAB ( 1 ) USER COMMANDS CRONTAB (1) NAME crontab — install, edit, remove or list a user’s crontab file SYNOPSIS crontab [filename ] crontab — e [ username ] crontab -1 [ username ] crontab -r [ username ] DESCRIPTION crontab copies the specified file, or the standard input if no file is specified, into a directory that holds all users’ crontab files. A user’s crontab file lists commands that are to be executed on behalf of that user at specified times on specified dates; the format of these files is described in crontab(5). If the file /var/spool/cron/cron.alIow exists, only users whose username appears in it can use crontab. If that file does not exist, however, crontab checks the /var/spool/cron/cron.deny file to determine if the user should be denied the use of crontab. If neither file exists, only the super-user is allowed to submit a crontab job. If cron.allow does not exist and cron.deny exists and is empty, global usage is permitted. The allow/deny files consist of one user name per line. OPTIONS -e Make a copy of the current user’s crontab file, or create an empty file if it does not exist, and edit that file. The vi(l) editor will be used unless the environment variable VISUAL or EDITOR indi- cates an alternate editor. When editing is complete, install the file as the user’s crontab file if it was modified. If a username is given, the specified user’s crontab file is edited, rather than the current user’s crontab file; this may only be done by the super-user. -1 List the user’s crontab file. -r Remove the current user’s crontab file from the crontab directory. If a username is given, the specified user’s crontab file is removed, rather than the current user’s crontab file; this may only be done by the super-user. FILES /var/spool/cron /var/spool/cron/crontabs /var/spool/cron/cron.allow /var/spool/cron/cron.deny main cron directory spool area list of allowed users list of denied users SEE ALSO sh(l), crontab(5), cron(8) WARNINGS If you inadvertently enter the crontab command with no argument, do not attempt to get out by typing CTRL-D. This removes all entries in your crontab file. Instead, exit by typing your interrupt character (normally CTRL-C). 96 Last change: 9 September 1987 Sun Release 4.1 CRYPT ( 1 ) USER COMMANDS CRYPT ( 1 ) NAME crypt - encode or decode a file SYNOPSIS crypt [ password ] DESCRIPTION crypt encrypts and decrypts the contents of a file, crypt reads from the standard input and writes standard output. The password is a key that selects a particular transformation. If no password is crypt demands a key from the terminal and turns off printing while the key is being typed in. encrypts and decrypts with the same key: example% crypt key < dear, file > encrypted. file example% crypt key < encrypted. file | pr will print the contents of clear. file. Files encrypted by crypt are compatible with those treated by the editors ed(l), ex(l) and vi(l) in encryp- tion mode. The security of encrypted files depends on three factors: the fundamental method must be hard to solve; direct search of the key space must be infeasible; “sneak paths” by which keys or cleartext can become visible must be minimized. crypt implements a one-rotor machine designed along the lines of the German Enigma, but with a 256- element rotor. Methods of attack on such machines are widely known, thus crypt provides minimal secu- rity. The transformation of a key into the internal settings of the machine is deliberately designed to be expen- sive, that is, to take a substantial fraction of a second to compute. However, if keys are restricted to (say) three lower-case letters, then encrypted files can be read by expending only a substantial fraction of five minutes of machine time. Since the key is an argument to the crypt command, it is potentially visible to users executing ps(l) or a derivative command. To minimize this possibility, crypt takes care to destroy any record of the key immediately upon entry. No doubt the choice of keys and key security are the most vulnerable aspect of crypt. FILES /dev/tty for typed key SEE ALSO des(l), ed(l), ex(l), ps(l), vi(l), makekey(8) RESTRICTIONS This program is not available on software shipped outside the U.S. on the given, crypt Sun Release 4.1 Last change: 9 September 1987 97 CSH(l) USER COMMANDS CSH(l) NAME csh - a shell (command interpreter) with a C-like syntax and advanced interactive features SYNOPSIS csh [ -bcefinstvVxX ] [ argument. . . ] DESCRIPTION csh, the C shell, is a command interpreter with a syntax reminiscent of C. It provides a number of con- venient features for interactive use that are not available with the standard (Bourne) shell, including filename completion, command aliasing, history substitution, job control, and a number of built-in com- mands. As with the standard shell, the C shell provides variable, command and filename substitution. Initialization and Termination When first started, the C shell normally performs commands from the .cshrc file in your home directory, provided that it is readable and you either own it or your real group ID matches its group ID. If the shell is invoked with a name that starts with as when started by login(l), the shell runs as a login shell. In this case, after executing commands from the .cshrc file, the shell executes commands from the .login file in your home directory; the same permission checks as those for .cshrc are applied to this file. Typically, the .login file contains commands to specify the terminal type and environment. As a login shell terminates, it performs commands from the .logout file in your home directory; the same permission checks as those for .cshrc are applied to this file. Interactive Operation After startup processing is complete, an interactive C shell begins reading commands from the terminal, prompting with hostname % (or hostname # for the super-user). The shell then repeatedly performs the fol- lowing actions: a line of command input is read and broken into words. This sequence of words is placed on the history list and then parsed, as described under USAGE, below. Finally, the shell executes each command in the current line. Noninteractive Operation When running noninteractively, the shell does not prompt for input from the terminal. A noninteractive C shell can execute a command supplied as an argument on its command line, or interpret commands from a script. OPTIONS -b Force a “break” from option processing. Subsequent command-line arguments are not interpreted as C shell options. This allows the passing of options to a script without confusion. The shell does not run a set-user-ID script unless this option is present. -c Read commands from the first filename argument (which must be present). Remaining arguments are placed in argv, the argument-list variable. -e Exit if a command terminates abnormally or yields a nonzero exit status. -f Fast start. Read neither the .cshrc file, nor the .login file (if a login shell) upon startup. -i Forced interactive. Prompt for command-line input, even if the standard input does not appear to be a terminal (character-special device). -n Parse (interpret), but do not execute commands. This option can be used to check C shell scripts for syntax errors. -s Take commands from the standard input. -t Read and execute a single command line. A ‘V (backslash) can be used to escape each NEWLINE for continuation of the command line onto subsequent input lines. -v Verbose. Set the verbose predefined variable; command input is echoed after history substitution (but before other substitutions) and before execution. -V Set verbose before reading .cshrc. 98 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) -x Echo. Set the echo variable; echo commands after all substitutions and just before execution. -X Set echo before reading .cshrc. Except with the options -c, -i, -s or -t, the first nonoption argument is taken to be the name of a command or script. It is passed as argument zero, and subsequent arguments are added to the argument list for that command or script. USAGE Refer to SunOS User’s Guide: Doing More for tutorial information on how to use the various features of the C shell. Filename Completion When enabled by setting the variable filec, an interactive C shell can complete a partially typed filename or user name. When an unambiguous partial filename is followed by an ESC character on the terminal input line, the shell fills in the remaining characters of a matching filename from the working directory. If a partial filename is followed by the EOF character (usually typed as CTRL-D), the shell lists all filenames that match. It then prompts once again, supplying the incomplete command line typed in so far. When the last (partial) word begins with a tilde (~), the shell attempts completion with a user name, rather than a file in the working directory. The terminal bell signals errors or multiple matches; this can be inhibited by setting the variable nobeep. You can exclude files with certain suffixes by listing those suffixes in the variable fignore. If, however, the only possible completion includes a suffix in the list, it is not ignored, fignore does not affect the listing of filenames by the EOF character. Lexical Structure The shell splits input lines into words at SPACE and TAB characters, except as noted below. The characters &, |, ;, <, >, (, and ) form separate words; if paired, the pairs form single words. These shell metacharac- ters can be made part of other words, and their special meaning can be suppressed by preceding them with a ‘V (backslash). A NEWLINE preceded by a \ is equivalent to a SPACE character. In addition, a string enclosed in matched pairs of single-quotes ( ' ), double-quotes ( " ), or backquotes ( ' ), forms a partial word; metacharacters in such a string, including any SPACE or TAB characters, do not form separate words. Within pairs of backquote (' ) or double-quote ( " ) characters, a NEWLINE preceded by a ‘V (backslash) gives a true NEWLINE character. Additional functions of each type of quote are described, below, under Variable Substitution, Command Substitution, and Filename Substitution. When the shell’s input is not a terminal, the character # introduces a comment that continues to the end of the input line. Its special meaning is suppressed when preceded by a \ or enclosed in matching quotes. Command Line Parsing A simple command is composed of a sequence of words. The first word (that is not part of an I/O redirec- tion) specifies the command to be executed. A simple command, or a set of simple commands separated by | or |& characters, forms a pipeline. With |, the standard output of the preceding command is redirected to the standard input of the command that follows. With | &, both the standard error and the standard output are redirected through the pipeline. Pipelines can be separated by semicolons ( ; ), in which case they are executed sequentially. Pipelines that are separated by && or 1 1 form conditional sequences in which the execution of pipelines on the right depends upon the success or failure, respectively, of the pipeline on the left. A pipeline or sequence can be enclosed within parentheses ‘( )’ to form a simple command that can be a component in a pipeline or sequence. A sequence of pipelines can be executed asynchronously, or “in the background” by appending an rather than waiting for the sequence to finish before issuing a prompt, the shell displays the job number (see Job Control, below) and associated process IDs, and prompts immediately. Sun Release 4. 1 Last change: 2 October 1989 99 CSH(l) USER COMMANDS CSH(l) History Substitution History substitution allows you to use words from previous command lines in the command line you are typing. This simplifies spelling corrections and the repetition of complicated commands or arguments. Command lines are saved in the history list, the size of which is controlled by the history variable. The most recent command is retained in any case. A history substitution begins with a ! (although you can change this with the histchars variable) and may occur anywhere on the command line; history substitu- tions do not nest. The ! can be escaped with \ to suppress its special meaning. Input lines containing history substitutions are echoed on the terminal after being expanded, but before any other substitutions take place or the command gets executed. Event Designators An event designator is a reference to a command-line entry in the history list. ! Start a history substitution, except when followed by a SPACE character, TAB, NEWLINE, = or (. !! Refer to the previous command. By itself, this substitution repeats the previous com- mand. In Refer to command-line n. l-n Refer to the current command-line minus n. Istr Refer to the most recent command starting with str. !?sir[?] Refer to the most recent command containing str. !{...} Insulate a history reference from adjacent characters (if necessary). Word Designators A (colon) separates the event specification from the word designator. It can be omitted if the word designator begins with a or %. If the word is to be selected from the previous command, the second ! character can be omitted from the event specification. For instance, !!:1 and !:1 both refer to the first word of the previous command, while !!$ and !$ both refer to the last word in the previous command. Word designators include: # The entire command line typed so far. 0 The first input word (command). n The n’th argument. - The first argument, that is, 1. $ The last argument. % The word matched by (the most recent) Is search. x-y A range of words; -y abbreviates 0-y. * All the arguments, or a null value if there is just one word in the event. x* Abbreviates x-$. x- Like x* but omitting word $. Modifiers After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a :. h Remove a trailing pathname component, leaving the head, r Remove a trailing suffix of the form ‘ jcxx ’, leaving the basename. e Remove all but the suffix, s lllr[l] Substitute r for /. t Remove all leading pathname components, leaving the tail. & Repeat the previous substitution. g Apply the change to the first occurrence of a match in each word, by prefixing the above (for example, g&). p Print the new command but do not execute it. q Quote the substituted words, escaping further substitutions, x Like q, but break into words at each SPACE character, TAB or NEWLINE. 100 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) Unless preceded by a g, the modification is applied only to the first string that matches /; an error results if no string matches. The left-hand side of substitutions are not regular expressions, but character strings. Any character can be used as the delimiter in place of /. A backslash quotes the delimiter character. The character &, in the right hand side, is replaced by the text from the left-hand-side. The & can be quoted with a backslash. A null l uses the previous string either from a l or from a contextual scan string s from !?s. You can omit the rightmost delimiter if a NEWLINE immediately follows r; the rightmost ? in a context scan can similarly be omitted. Without an event specification, a history reference refers either to the previous command, or to a previous history reference on the command line (if any). Quick Substitution <'/»r[»] This is equivalent to the history substitution: !:s-/-r[>]. Aliases The C shell maintains a list of aliases that you can create, display, and modify using the alias and unalias commands. The shell checks the first word in each command to see if it matches the name of an existing alias. If it does, the command is reprocessed with the alias definition replacing its name; the history substi- tution mechanism is made available as though that command were the previous input line. This allows his- tory substitutions, escaped with a backslash in the definition, to be replaced with actual command-line arguments when the alias is used. If no history substitution is called for, the arguments remain unchanged. Aliases can be nested. That is, an alias definition can contain the name of another alias. Nested aliases are expanded before any history substitutions is applied. This is useful in pipelines such as alias 1m 'Is -I \!+ | more' which when called, pipes the output of ls(lV) through more(l). Except for the first word, the name of the alias may not appear in its definition, nor in any alias referred to by its definition. Such loops are detected, and cause an error message. I/O Redirection The following metacharacters indicate that the subsequent word is the name of a file to which the command’s standard input, standard output, or standard error is redirected; this word is variable, command, and filename expanded separately from the rest of the command. < Redirect the standard input. < < word Read the standard input, up to a line that is identical with word, and place the resulting lines in a temporary file. Unless word is escaped or quoted, variable and command sub- stitutions are performed on these lines. Then, invoke the pipeline with the temporary file as its standard input, word is not subjected to variable, filename or command substitu- tion, and each line is compared to it before any substitutions are performed by the shell. > >! >& >&! Redirect the standard output to a file. If the file does not exist, it is created. If it does exist, it is overwritten; its previous contents are lost. When set, the variable noclobber prevents destruction of existing files. It also prevents redirection to terminals and /dev/null, unless one of the ! forms is used. The & forms redirect both standard output and the standard error (diagnostic output) to the file. >> >>& >>! >>&! Append the standard output. Like >, but places output at the end of the file rather than overwriting it. If noclobber is set, it is an error for the file not to exist, unless one of the ! forms is used. The & forms append both the standard error and standard output to the file. Sun Release 4. 1 Last change: 2 October 1989 101 CSH(l) USER COMMANDS CSH(l) Variable Substitution The C shell maintains a set of variables, each of which is composed of a name and a value. A variable name consists of up to 20 letters and digits, and starts with a letter (the underscore is considered a letter). A variable’s value is a space-separated list of zero or more words. To refer to a variable’s value, precede its name with a *$’. Certain references (described below) can be used to select specific words from the value, or to display other information about the variable. Braces can be used to insulate the reference from other characters in an input-line word. Variable substitution takes place after the input line is analyzed, aliases are resolved, and I/O redirections are applied. Exceptions to this are variable references in I/O redirections (substituted at the time the redirection is made), and backquoted strings (see Command Substitution). Variable substitution can be suppressed by preceding the $ with a \, except within double-quotes where it always occurs. Variable substitution is suppressed inside of single-quotes. A $ is escaped if followed by a SPACE character, TAB or NEWLINE. Variables can be created, displayed, or destroyed using the set and unset commands. Some variables are maintained or used by the shell. For instance, the argv variable contains an image of the shell’s argument list. Of the variables used by the shell, a number are toggles; the shell does not care what their value is, only whether they are set or not. Numerical values can be operated on as numbers (as with the @ built-in). With numeric operations, an empty value is considered to be zero; the second and subsequent words of multiword values are ignored. For instance, when the verbose variable is set to any value (including an empty value), command input is echoed on the terminal. Command and filename substitution is subsequently applied to the words that result from the variable sub- stitution, except when suppressed by double-quotes, when noglob is set (suppressing filename substitu- tion), or when the reference is quoted with the :q modifier. Within double-quotes, a reference is expanded to form (a portion of) a quoted string; multiword values are expanded to a string with embedded SPACE characters. When the :q modifier is applied to the reference, it is expanded to a list of space-separated words, each of which is quoted to prevent subsequent command or filename substitutions. Except as noted below, it is an error to refer to a variable that is not set. $var ${var} $var [index] %{var[index]} $#name ${#name} $0 These are replaced by words from the value of var, each separated by a SPACE charac- ter. If var is an environment variable, its value is returned (but modifiers and the other forms given below are not available). These select only the indicated words from the value of var. Variable substitution is applied to index, which may consist of (or result in) a either single number, two numbers separated by a or an asterisk. Words are indexed starting from 1; a selects all words. If the first number of a range is omitted (as with $argv[-2]), it defaults to 1. If the last number of a range is omitted (as with $argv[l-]), it defaults to $ftvar (the word count). It is not an error for a range to be empty if the second argument is omitted (or within range). These give the number of words in the variable. This substitutes the name of the file from which command input is being read. An error occurs if the name is not known. 102 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) $n ${n} Equivalent to $argv[n], $* Equivalent to $argv[*]. The modifiers :e, :h, :q, :r, :t and :x can be applied (see History Substitution), as can :gh, :gt and :gr. If { } (braces) are used, then the modifiers must appear within the braces. The current implementation allows only one such modifier per expansion. The following references may not be modified with : modifiers. $?var ${?var} Substitutes the string 1 if var is set or 0 if it is not set. $?0 Substitutes 1 if the current input filename is known, or 0 if it is not. $$ Substitute the 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 C shell script. Command and Filename Substitutions Command and filename substitutions are applied selectively to the arguments of built-in commands. Por- tions of expressions that are not evaluated are not expanded. For non-built-in commands, filename expan- sion of the command name is done separately from that of the argument list; expansion occurs in a sub- shell, after I/O redirection is performed. Command Substitution A command enclosed by backquotes ('...') is performed by a subshell. Its standard output is broken into separate words at each SPACE character, TAB and NEWLINE; null words are discarded. This text replaces the backquoted string on the current command line. Within double-quotes, only NEWLINE characters force new words; SPACE and TAB characters are preserved. However, a final NEWLINE is ignored. It is there- fore possible for a command substitution to yield a partial word. Filename Substitution Unquoted words containing any of the characters *, ?, [ or {, or that begin with ~, are expanded (also known as globbing) to an alphabetically sorted list of filenames, as follows: * Match any (zero or more) characters. ? Match any single character. [ . . . ] Match any single character in the enclosed list(s) or range(s). A list is a string of charac- ters. A range is two characters separated by a minus-sign (-), and includes all the char- acters in between in the ASCII collating sequence (see ascii(7)). { str, str , . . . } Expand to each string (or filename-matching pattern) in the comma-separated list. Unlike the pattern-matching expressions above, the expansion of this construct is not sorted. For instance, {b,a} expands to ‘b’ ‘a’, (not ‘a’ ‘b’). As special cases, the char- acters { and }, along with the string {}, are passed undisturbed. ~[ user ] Your home directory, as indicated by the value of the variable home, or that of user, as indicated by the password entry for user. Only the patterns *, ? and [. ..] imply pattern matching; an error results if no filename matches a pattern that contains them. The Y (dot character), when it is the first character in a filename or pathname com- ponent, must be matched explicitly. The / (slash) must also be matched explicitly. Expressions and Operators A number of C shell built-in commands accept expressions, in which the operators are similar to those of C and have the same precedence. These expressions typically appear in the @, exit, if, set and while com- mands, and are often used to regulate the flow of control for executing commands. Components of an expression are separated by white space. Sun Release 4.1 Last change: 2 October 1989 103 CSH(l) USER COMMANDS CSH(l) Null or missing values are considered 0. The result of all expressions are strings, which may represent decimal numbers. The following C shell operators are grouped in order of precedence: (...) grouping ~ one’s complement J logical negation * / % multiplication, division, remainder (These are right associative, which can lead to unexpected results. Group combinations explicidy with parentheses.) + — addition, subtraction (also right associative) « » bitwise shift left, bitwise shift right A V A II V II less than, greater than, less than or equal to, greater than or equal to == != =~ !~ equal to, not equal to, filename-substitution pattern match (described below), filename-substitution pattern mismatch & bitwise AND A bitwise XOR (exclusive or) 1 bitwise inclusive OR && logical AND II logical OR The operators: ==, !=, =~, and !~ compare their arguments as strings; other operators use numbers. The operators =~ and !~ each check whether or not a string to the left matches a filename substitution pattern on the right. This reduces the need for switch statements when pattern-matching between strings is all that is required. Also available are file inquiries: -r filename Return true, or 1 if the user has read access. Otherwise it returns false, or 0. -w filename True if the user has write access. —x filename True if the user has execute permission (or search permission on a directory). -e filename True if file exists. -o filename True if the user owns file. -z filename True if file is of zero length (empty). -f filename True if file is a plain file. -d filename True if file is a directory. If file does not exist or is inaccessible, then all inquiries return false. An inquiry as to the success of a command is also available: { command } If command runs successfully, the expression evaluates to true, 1. Otherwise it evalu- ates to false 0. (Note that, conversely, command itself typically returns 0 when it runs successfully, or some other value if it encounters a problem. If you want to get at the status direcdy, use the value of the status variable rather than this expression). Control Flow The shell contains a number of commands to regulate the flow of control in scripts, and within limits, from the terminal. These commands operate by forcing the shell either to reread input (to loop), or to skip input under certain conditions (to branch). Each occurrence of a foreach, switch, while, if. . .then and else built-in must appear as the first word on its own input line. 104 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) If the shell’s input is not seekable and a loop is being read, that input is buffered. The shell performs seeks within the internal buffer to accomplish the rereading implied by the loop. (To the extent that this allows, backward goto commands will succeed on nonseekable inputs.) Command Execution If the command is a C shell built-in, the shell executes it directly. Otherwise, the shell searches for a file by that name with execute access. If the command-name contains a /, the shell takes it as a pathname, and searches for it. If the command-name does not contain a /, the shell attempts to resolve it to a pathname, searching each directory in the path variable for the command. To speed the search, the shell uses its hash table (see the rehash built-in) to eliminate directories that have no applicable files. This hashing can be disabled with the -c or -t, options, or the unhash built-in. As a special case, if there is no / in the name of the script and there is an alias for the word shell, the expan- sion of the shell alias is prepended (without modification), to the command line. The system attempts to execute the first word of this special (late-occurring) alias, which should be a full pathname. Remaining words of the alias’s definition, along with the text of the input line, are treated as arguments. When a pathname is found that has proper execute permissions, the shell forks a new process and passes it, along with its arguments to the kernel (using the execve(2V) system call). The kernel then attempts to overlay the new process with the desired program. If the file is an executable binary (in a.out(5) format) the kernel succeeds, and begins executing the new process. If the file is a text file, and the first line begins with #!, the next word is taken to be the pathname of a shell (or command) to interpret that script. Subse- quent words on the first line are taken as options for that shell. The kernel invokes (overlays) the indicated shell, using the name of the script as an argument. If neither of the above conditions holds, the kernel cannot overlay the file (the execve(2V) call fails); the C shell then attempts to execute the file by spawning a new shell, as follows: • If the first character of the file is a #, a C shell is invoked. « Otherwise, a standard (Bourne) shell is invoked. Signal Handling The shell normally ignores QUIT signals. Background jobs are immune to signals generated from the key- board, including hangups (HUP). Other signals have the values that the C shell inherited from its environ- ment. The shell’s handling of interrupt and terminate signals within scripts can be controlled by the onintr built-in. Login shells catch the TERM signal; otherwise this signal is passed on to child processes. In no case are interrupts allowed when a login shell is reading the .logout file. Job Control The shell associates a numbered job with each command sequence, to keep track of those commands that are running in the background or have been stopped with TSTP signals (typically CTRL-Z). When a com- mand, or command sequence (semicolon separated list), is started in the background using the & metachar- acter, the shell displays a line with the job number in brackets, and a list of associated process numbers: [1] 1234 To see the current list of jobs, use the jobs built-in command. The job most recently stopped (or put into the background if none are stopped) is referred to as the current job, and is indicated with a *+’. The previ- ous job is indicated with a when the current job is terminated or moved to the foreground, this job takes its place (becomes the new current job). To manipulate jobs, refer to the bg, fg, kill, stop and % built-ins. A reference to a job begins with a By itself, the percent-sign refers to the current job. % %+ %% The current job. %- The previous job. %j Refer to job j as in: ‘kill -9 %j\ j can be a job number, or a string that uniquely specifies the command-line by which it was started; ‘fg %vi’ might bring a stopped vi job to the foreground, for instance. Sun Release 4.1 Last change: 2 October 1989 105 CSH(l) USER COMMANDS CSH(l) %? string Specify the job for which the command-line uniquely contains string. A job running in the background stops when it attempts to read from the terminal. Background jobs can normally produce output, but this can be suppressed using the ‘stty tostop’ command. Status Reporting While running interactively, the shell tracks the status of each job and reports whenever a finishes or becomes blocked. It normally displays a message to this effect as it issues a prompt, so as to avoid disturb- ing the appearance of your input. When set, the notify variable indicates that the shell is to report status changes immediately. By default, the notify command marks the current process; after starting a back- ground job, type notify to mark it. Built-In Commands Built-in commands are executed within the C shell. If a built-in command occurs as any component of a pipeline except the last, it is executed in a subshell. : Null command. This command is interpreted, but performs no action, alias [ name [ def] ] Assign def to the alias name, def is a list of words that may contain escaped history- substitution metasyntax, name is not allowed to be alias or unalias. If def is omitted, the alias name is displayed along with its current definition. If both name and def are omitted, all aliases are displayed. bg [%job] . . . Run the current or specified jobs in the background. break Resume execution after the end of the nearest enclosing foreach or while loop. The remain- ing commands on the current line are executed. This allows multilevel breaks to be written as a list of break commands, all on one line. breaksw Break from a switch, resuming after the endsw. case label: A label in a switch statement. cd [ dir ] chdir [ dir ] Change the shell’s working directory to directory dir. If no argument is given, change to the home directory of the user. If dir is a relative pathname not found in the current directory, check for it in those directories listed in the cdpath variable. If dir is the name of a shell vari- able whose value starts with a /, change to the directory named by that value. continue Continue execution of the nearest enclosing while or foreach. default: Labels the default case in a switch statement. The default should come after all case labels. Any remaining commands on the command line are first executed. dirs [ -1 ] Print the directory stack, most recent to the left; the first directory shown is the current direc- tory. With the -1 argument, produce an unabbreviated printout; use of the ~ notation is suppressed. echo [ -n ] list The words in list are written to the shell’s standard output, separated by SPACE characters. The output is terminated with a NEWLINE unless the -n option is used. eval argument . . . Reads the arguments as input to the shell, and executes the resulting command(s). This is usu- ally used to execute commands generated as the result of command or variable substitution, since parsing occurs before these substitutions. See tset(l) for an example of how to use eval. exec command Execute command in place of the current shell, which terminates. 106 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH ( 1 ) exit [ (expr) ] The shell exits, either with the value of the status variable, or with the value of the specified by the expression expr. fg % [job] Bring the current or specified job into the foreground, foreach var ( wordlist ) end The variable var is successively set to each member of wordlist. The sequence of commands between this command and the matching end is executed for each new value of var. (Both foreach and end must appear alone on separate lines.) The built-in command continue may be used to continue the loop prematurely and the built-in command break to terminate it prematurely. When this command is read from the terminal, the loop is read up once prompting with ? before any statements in the loop are executed. glob wordlist Perform filename expansion on wordlist. Like echo, but no \ escapes are recognized. Words are delimited by null characters in the output. goto label The specified label is filename and command expanded to yield a label. The shell rewinds its input as much as possible and searches for a line of the form label : possibly preceded by SPACE or TAB characters. Execution continues after the indicated line. It is an error to jump to a label that occurs between a while or for built-in, and its corresponding end. hashstat Print a statistics line indicating how effective the internal hash table has been at locating com- mands (and avoiding execs). An exec is attempted for each component of the path where the hash function indicates a possible hit, and in each component that does not begin with a 7’. history [ -hr ] [ n ] Display the history list; if n is given, display only the n most recent events. -r Reverse the order of printout to be most recent first rather than oldest first. -h Display the history list without leading numbers. This is used to produce files suitable for sourcing using the -h option to source. if (expr) command If the specified expression evaluates to true, the single command with arguments is executed. Variable substitution on command happens early, at the same time it does for the rest of the if command, command must be a simple command, not a pipeline, a command list, or a parenthesized command list. Note: I/O redirection occurs even if expr is false, when command is not executed (this is a bug). if (expr) then else if (expr2 ) then else endif jobs[ -1 Sun Release 4.1 If expr is true, commands up to the first else are executed. Otherwise, if expr2 is true, the commands between the else if and the second else are executed. Otherwise, commands between the else and the endif are executed. Any number of else if pairs are allowed, but only one else. Only one endif is needed, but it is required. The words else and endif must be the first nonwhite characters on a line. The if must appear alone on its input line or after an else.) List the active jobs under job control. -1 List process IDs, in addition to the normal information. Last change: 2 October 1989 107 CSH(l) USER COMMANDS CSH(l) kill [ -sig ] [ pid ][%job] ... kill -1 Send the TERM (terminate) signal, by default, or the signal specified, to the specified process ID, the job indicated, or the current job. Signals are either given by number or by name. There is no default. Typing kill does not send a signal to the current job. If the signal being sent is TERM (terminate) or HUP (hangup), then the job or process is sent a CONT (continue) signal as well. -1 List the signal names that can be sent, limit [ -h ] [ resource [ max-use ] ] Limit the consumption by the current process or any process it spawns, each not to exceed max-use on the specified resource . If max-use is omitted, print the current limit; if resource is omitted, display all limits. -h Use hard limits instead of the current limits. Hard limits impose a ceiling on the values of the current limits. Only the super-user may raise the hard limits. resource is one of: cputime Maximum CPU seconds per process, filesize Largest single file allowed. datasize Maximum data size (including stack) for the process, stacksize Maximum stack size for the process, coredumpsize Maximum size of a core dump (file), descriptors Maximum value for a file descriptor. max-use is a number, with an optional scaling factor, as follows: nh Hours (for cputime). nk n kilobytes. This is the default for all but cputime. nm n megabytes or minutes (for cputime). mm :ss Minutes and seconds (for cputime). login [ username l-p ] Terminate a login shell and invoke login(l). The .logout file is not processed. If username is omitted, login prompts for the name of a user. -p Preserve the current environment (variables). logout Terminate a login shell. nice [ +n I -n ] [ command ] Increment the process priority value for the shell or for command by n. The higher the priority value, the lower the priority of a process, and the slower it runs. When given, command is always run in a subshell, and the restrictions placed on commands in simple if commands apply. If command is omitted, nice increments the value for the current shell. If no increment is specified, nice sets the nice value to 4. The range of nice values is from -20 through 19. Values of n outside this range set the value to the lower, or to the higher boundary, respec- tively. +n Increment the process priority value by n. -n Decrement by n. This argument can be used only by the super-user, nohup [ command ] Run command with HUPs ignored. With no arguments, ignore HUPs throughout the remainder of a script. When given, command is always run in a subshell, and the restrictions placed on commands in simple if commands apply. All processes detached with & are effectively nohup’d. notify [ %job] ... Notify the user asynchronously when the status of the current, or of specified jobs, changes. 108 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) onintr [ - I label ] Control the action of the shell on interrupts. With no arguments, onintr restores the default action of the shell on interrupts. (The shell terminates shell scripts and returns to the terminal command input level). With the - argument, the shell ignores all interrupts. With a label argument, the shell executes a goto label when an interrupt is received or a child process ter- minates because it was interrupted. popd [+n] Pop the directory stack, and cds to the new top directory. The elements of the directory stack are numbered from 0 starting at the top. +n Discard the n ’th entry in the stack. pushd [+n I dir ] Push a directory onto the directory stack. With no arguments, exchange the top two elements. +n Rotate the n ’th entry to the top of the stack and cd to it. dir Push the current working directory onto the stack and change to dir. rehash Recompute the internal hash table of the contents of directories listed in the path variable to account for new commands added. repeat count command Repeat command count times command is subject to the same restrictions as with the one-line if statement. set \yar [ = value ] ] set var[n\ = word With no arguments, set displays the values of all shell variables. Multiword values are displayed as a parenthesized list. With the var argument alone, set assigns an empty (null) value to the variable var. With arguments of the form var = value set assigns value to var, where value is one of: word A single word (or quoted string). (wordlist) A space-separated list of words enclosed in parentheses. Values are command and filename expanded before being assigned. The form set var[n ] = word replaces the n’th word in a multiword value with word. setenv [ VAR [ word ] ] With no arguments, setenv displays all environment variables. With the VAR argument sets the environment variable VAR to have an empty (null) value. (By convention, environment vari- ables are normally given upper-case names.) With both VAR and word arguments setenv sets the environment variable NAME to the value word, which must be either a single word or a quoted string. The most commonly used environment variables, USER, TERM, and PATH, are automatically imported to and exported from the csh variables user, term, and path; there is no need to use setenv for these. In addidon, the shell sets the PWD environment variable from the csh variable cwd whenever the latter changes. shift ( variable ] The components of argv, or variable, if supplied, are shifted to the left, discarding the first component. It is an error for the variable not to be set, or to have a null value. source [ -h ] name Reads commands from name, source commands may be nested, but if they are nested too deeply the shell may run out of file descriptors. An error in a sourced file at any level ter- minates all nested source commands. -h Place commands from the file name on the history list without executing them. Sun Release 4.1 Last change: 2 October 1989 109 CSH(l) USER COMMANDS CSH(l) stop [%job] . . . Stop the current or specified background job. suspend Stop the shell in its tracks, much as if it had been sent a stop signal with A Z. This is most often used to stop shells started by su. switch ( string ) case label: breaksw default: breaksw endsw Each label is successively matched, against the specified string, which is first command and filename expanded. The file metacharacters *, ? and [...] may be used in the case labels, which are variable expanded. If none of the labels match before a “default” label is found, execution begins after the default label. Each case statement and the default statement must appear at the beginning of a line. The command breaksw continues execution after the endsw. Otherwise control falls through subsequent case and default statements as with C. If no label matches and there is no default, execution continues after the endsw. time [ command ] With no argument, print a summary of time used by this C shell and its children. With an optional command, execute command and print a summary of the time it uses. umask [ value ] Display the file creation mask. With value set the file creation mask, value is given in octal, and is XORed with the permissions of 666 for files and 111 for directories to arrive at the per- missions for new files. Common values include 002, giving complete access to the group, and read (and directory search) access to others, or 022, giving read (and directory search) but not write permission to the group and others. unalias pattern Discard aliases that match (filename substitution) pattern. All aliases are removed by unalias *. unhash Disable the internal hash table, unlimit [ -h ] [ resource ] Remove a limitation on resource . If no resource is specified, then all resource limitations are removed. See the description of the limit command for the list of resource names. -h Remove corresponding hard limits. Only the super-user may do this, unset pattern Remove variables whose names match (filename substitution) pattern. All variables are removed by ‘unset this has noticeably distasteful side-effects. unsetenv variable Remove variable from the environment. Pattern matching, as with unset is not performed, wait Wait for background jobs to finish (or for an interrupt) before prompting, while ( expr ) end While expr is true (evaluates to non-zero), repeat commands between the while and the match- ing end statement, break and continue may be used to terminate or continue the loop prema- turely. The while and end must appear alone on their input lines. If the shell’s input is a ter- minal, it prompts for commands with a question-mark until the end command is entered and then performs the commands in the loop. 110 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) %[job][&] Bring the current or indicated job to the foreground. With the ampersand, continue running job in the background. @ [ var =expr ] @ [ var[n ] =expr ] With no arguments, display the values for all shell variables. With arguments, the variable var, or the n ’th word in the value of var, to the value that expr evaluates to. (If [n] is supplied, both var and its n’th component must already exist.) If the expression contains the characters >, <, & or |, then at least this part of expr must be placed within parentheses. 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 components of expr that would otherwise be single words. Special postfix operators, + + and — increment or decrement name , respectively. Environment Variables and Predefined Shell Variables Unlike the standard shell, the C shell maintains a distinction between environment variables, which are automatically exported to processes it invokes, and shell variables, which are not. Both types of variables are treated similarly under variable substitution. The shell sets the variables argv, cwd, home, path, prompt, shell, and status upon initialization. The shell copies the environment variable USER into the shell variable user, TERM into term, and HOME into home, and copies each back into the respective environment variable whenever the shell variables are reset. PATH and path are similarly handled. You need only set path once in the .cshrc or .login file. The environment variable PWD is set from cwd when- ever the latter changes. The following shell variables have predefined meanings: argv Argument list. Contains the list of command line arguments supplied to the current invocation of the shell. This variable determines the value of the positional parame- ters $1, $2, and so on. cdpath Contains a list of directories to be searched by the cd, chdir, and popd commands, if the directory argument each accepts is not a subdirectory of the current directory. cwd The full pathname of the current directory. echo Echo commands (after substitutions), just before execution. fignore A list of filename suffixes to ignore when attempting filename completion. Typically the single word ‘.o’. filec Enable filename completion, in which case the CTRL-D character CTRL-D) and the ESC character have special significance when typed in at the end of a terminal input line: EOT Print a list of all filenames that start with the preceding string. ESC Replace the preceding string with the longest unambiguous extension. hardpaths If set, pathnames in the directory stack are resolved to contain no symbolic-link components. histchars A two-character string. The first character replaces ! as the history-substitution char- acter. The second replaces the carat (-) for quick substitutions. history The number of lines saved in the history list. A very large number may use up all of the C shell’s memory. If not set, the C shell saves only the most recent command. home The user’s home directory. The filename expansion of ~ refers to the value of this variable. ignoreeof If set, the shell ignores EOF from terminals. This protects against accidentally killing a C shell by typing a CTRL-D. Sun Release 4.1 Last change: 2 October 1989 111 CSH(l) USER COMMANDS CSH(l) mail nobeep noclobber noglob nonomatch notify path prompt savehist shell status time A list of files where the C shell checks for mail. If the first word of the value is a number, it specifies a mail checking interval in seconds (default 5 minutes). Suppress the bell during command completion when asking the C shell to extend an ambiguous filename. Restrict output redirection so that existing files are not destroyed by accident. > redirections can only be made to new files. » redirections can only be made to existing files. Inhibit filename substitution. This is most useful in shell scripts once filenames (if any) are obtained and no further expansion is desired. Returns the filename substitution pattern, rather than an error, if the pattern is not matched. Malformed patterns still result in errors. If set, the shell notifies you immediately as jobs are completed, rather than waiting until just before issuing a prompt. The list of directories in which to search for commands, path is initialized from the environment variable PATH, which the C shell updates whenever path changes. A null word specifies the current directory. The default is typically: (. /usr/ucb /usr/bin). If path becomes unset only full pathnames will execute. An interactive C shell will normally hash the contents of the directories listed after reading .cshrc, and whenever path is reset. If new commands are added, use the rehash command to update the table. The string an interactive C shell prompts with. Noninteractive shells leave the prompt variable unset. Aliases and other commands in the .cshrc file that are only useful interactively, can be placed after the following test: ‘if ($?prompt == 0) exit’, to reduce startup time for noninteractive shells. A ! in the prompt string is replaced by the current event number. The default prompt is hostname % for mere mortals, or hostname # for the super-user. The number of lines from the history list that are saved in ~/.history when the user logs out. Large values for savehist slow down the C shell during startup. The file in which the C shell resides. This is used in forking shells to interpret files that have execute bits set, but that are not executable by the system. The status returned by the most recent command. If that command terminated abnormally, 0200 is added to the status. Built-in commands that fail return exit status 1, all other built-in commands set status to 0. Control automatic timing of commands. Can be supplied with one or two values. The first is the reporting threshold in CPU seconds. The second is a string of tags and text indicating which resources to report on. A tag is a percent sign (%) followed by a single upper-case letter (unrecognized tags print as text): %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. 112 Last change: 2 October 1989 Sun Release 4.1 CSH(l) USER COMMANDS CSH(l) %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 summary display outputs from the %U, %S, %E, %P, %X, %D, %I, %0, %F and %W tags, in that order. verbose Display each command after history substitution takes place. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout all command line parsing. These variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid charac- ter classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES ~/.cshrc ~/.login "/.logout "/.history /tmp/sh* /etc/passwd SEE ALSO login(l), printenv(l), sh(l), tset(l), access(2V), execve(2V), fork(2V), pipe(2V), termio(4), a.out(5), environ(5V), locale(5), ascii(7), iso_8859_l(7) SunOS User’ s Guide: Doing More SunOS User’ s Guide: Getting Started DIAGNOSTICS You have stopped jobs. You attempted to exit the C shell with stopped jobs under job control. An immediate second attempt to exit will succeed, terminating the stopped jobs. LIMITATIONS Words can be no longer than 1024 characters. The system limits argument lists to 1,048,576 characters. However, the maximum number of arguments to a command for which filename expansion applies is 1706. Command substitutions may expand to no more characters than are allowed in the argument list. To detect looping, the shell restricts the number of alias substitutions on a single line to 20. BUGS When a command is restarted from a stop, the shell prints the directory it started in if this is different from the current directory; this can be misleading (that is, wrong) as the job may have changed directories inter- nally. Shell built-in 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 never executes c. This is espe- cially noticeable if the expansion results from an alias. It can be avoided by placing the sequence in parentheses to force it into a subshell. Control over terminal output after processes are started is primitive; use the Sun Window system if you need better output control. Multiline shell procedures should be provided, as they are with the standard (Bourne) shell. Read at beginning of execution by each shell. Read by login shells after .cshrc at login. Read by login shells at logout. Saved history for use at next login. Temporary file for ‘«’. Source of home directories for '~name . Sun Release 4.1 Last change: 2 October 1989 113 CSH(l) USER COMMANDS CSH(l) Commands within loops, prompted for by ?, are not placed in the history list. Control structures should be parsed rather than being recognized as built-in commands. This would allow control commands to be placed anywhere, to be combined with |, and to be used with & and ; metasyntax. It should be possible to use the : modifiers on the output of command substitutions. There are two prob- lems with : modifier usage on variable substitutions: not all of the modifiers are available, and only one modifier per substitution is allowed. The g (global) flag in history substitutions applies only to the first match in each word, rather than all matches in all words. The standard text editors consistently do the latter when given the g flag in a substitu- tion command. Quoting conventions are confusing. Overriding the escape character to force variable substitutions within double quotes is counterintuitive and inconsistent with the Bourne shell. Symbolic links can fool the shell. Setting the hardpaths variable alleviates this. ‘set path’ should remove duplicate pathnames from the pathname list. These often occur because a shell script or a .cshrc file does something like ‘set path=(/usr/local /usr/hosts $path)’ to ensure that the named directories are in the pathname list. The only way to direct the standard output and standard error separately is by invoking a subshell, as fol- lows: example % ( command > outfile ) >& errorfile Although robust enough for general use, adventures into the esoteric periphery of the C shell may reveal unexpected quirks. 114 Last change: 2 October 1989 Sun Release 4.1 CSPLIT ( 1 V ) USER COMMANDS CSPLIT (IV) NAME csplit - split a file with respect to a given context SYNOPSIS csplit [ -f prefix ] [ — k ] [ — s ] filename argument 1 [ . . .argumentn ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION csplit reads the file whose name is filename and separates it into n+\ sections, defined by the arguments argumentl through argumentn. If the filename argument is a the standard input is used. By default the sections are placed in files named xxOO through xxn. n may not be greater than 99. These sections receive the following portions of the file: xxOO From the start of filename up to (but not including) the line indicated by argumentl (see OPTIONS below for an explanation of these arguments.) xxOl: From the line indicated by argumentl up to the line indicated by argument2 . xxn: From the line referenced by argumentn to the end of filename. csplit prints the character counts for each file created, and removes any files it creates if an error occurs. OPTIONS -f prefix name the created files prefix 00 through prefan . -k Suppress removal of created files when an error occurs. -s Suppress printing of character counts. The arguments argumentl through argumentn can be a combination of the following selection operators: Irexpl A file is to be created for the section from the current line up to (but not including) the line containing the regular expression rexp. The current line then becomes the line containing rexp. This argument may be followed by an optional V or some number of lines (for example, /Page/-5). %rexp % This argument is the same as Irexpl, except that no file is created for the selected section. lineno A file is to be created from the current line up to (but not including) lineno. The current line becomes lineno . {num} Repeat argument. This argument may follow any of the above arguments. If it follows a rexp type argument, that argument is applied num more times. If it follows lineno, the file will be split every lineno lines ( num times) from that point. Enclose all rexp type arguments that contain blanks or other characters meaningful to the shell in the appropriate quotes. Regular expressions may not contain embedded new-lines. EXAMPLES This example splits the file at every 100 lines, up to 10,000 lines, csplit -k file 100 {99} Assuming that prog.c follows the normal C coding convention of ending routines with a } at the beginning of the line, this example will create a file containing each separate C routine (up to 21) in prog.c. csplit -k prog. c '%main(%' T}/+1' {20} SEE ALSO ed(l), sh(l), regexp(3) Sun Release 4.1 Last change: 16 September 1989 115 CSPLIT ( 1 V ) USER COMMANDS CSPLIT (IV) DIAGNOSTICS Self-explanatory except for: arg - out of range which means that the given argument did not refer to a line between the current position and the EOF. 116 Last change: 16 September 1989 Sun Release 4.1 CTAGS(l) USER COMMANDS CTAGS(l) NAME ctags - create a tags file for use with ex and vi SYNOPSIS ctags [ -aBFtuvwx ] [ -f tagsfile ] filename. . . DESCRIPTION ctags makes a tags file for ex(l) from the specified C, Pascal, FORTRAN, yacc(l), and lex(l) sources. A tags file gives the locations of specified objects (in this case functions and type definitions) in a group of files. Each entry in the tags is composed of three fields separated by white space, the object name, the file in which it is defined, and an address specification. Function definitions are located using regular expres- sion patterns, type definitions, using a line number. ex and vi(l) use entries in the tags file to locate and display a definition. Normally ctags places the tag descriptions in a file called tags; this may be overridden with the -f option. By default, the tags file is sorted in lexicographic (ASCII) order, and ex expects its entries to be so sorted. Files with names ending in .c or .h are assumed to be C source files and are searched for C routine and macro definitions. Files with names ending in .y are assumed to be yacc source files. Files with names ending in .1 are assumed to be lex files. Others are first examined to see if they contain any Pascal or FOR- TRAN routine definitions; if not, they are processed again looking for C definitions. The tag for the main( ) function is treated specially in C programs. The tag formed is created by prepend- ing M to filename , 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 -a Append output to an existing tags file. The resulting file is not sorted. To preserve the order, use -u instead. -B Use backward searching patterns (?. . . ?). -F Use forward searching patterns (/. . . /) (default). -t Create tags for typedefs. -u Update the specified files in the tags file. Entries that refer to them are deleted and then replaced in lexicographic order. Beware: this option is implemented in a way which is rather slow; it may be faster simply to rebuild the tags file. -v Produce an index of the form expected by vgrind(l) on the standard output. This listing contains the function name, file name, and page number (assuming 64 line pages). Since the output will be sorted into lexicographic order, it may be desired to run the output through ‘sort -f\ See EXAM- PLES. -w Suppress warning diagnostics. -x 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. EXAMPLES Using ctags with the -v option produces entries in an order which may not always be appropriate for vgrind. To produce results in alphabetical order, you may want to run the output through ‘sort -f\ example % ctags -v filename. c filename.h | sort -f > index example% vgrind -x index Sun Release 4. 1 Last change: 26 October 1988 117 CTAGS(l) USER COMMANDS CTAGS(l) To build a tags file for C sources in a directory hierarchy, first create an empty tags file, and then run the following find(l) command: example% cd 7src ; rm -f tags ; touch tags example% find "/src \( -name ’*.c’ -o -name ’*.h’ \) -exec ctags -u -f /usr/src/tags {} \; FILES tags output tags file SEE ALSO cc(lV), ex(l), find(l), vgrind(l), vi(l) NOTES While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. See cc(lV) for an explanation about why cc is not 8-bit clean. BUGS Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very sim- pleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures in dif- ferent blocks with the same name, ctags will only make an entry for one. ctags does not know about #ifdefs. ctags should know about Pascal types. Relies on the input being well formed to detect typedefs. Use of -tx shows only the last line of typedefs. 118 Last change: 26 October 1988 Sun Release 4.1 CTR ACE ( 1 V ) USER COMMANDS CTRACE (IV) NAME ctrace — generate a C program execution trace SYNOPSIS ctrace [ -f functions ] [ -v functions ] [ -o x u e ] [ -s P b ] [-In] [ -t n ] [ ] [ -b ] [ -p ’ s ’ ] [-*■/] [ filename ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ctrace allows you to follow the execution of a C program, statement by statement. The effect is similar to executing a shell procedure with the -x option, ctrace reads the C program in filename (or from standard input if you do not specify filename ), inserts statements to print the text of each executable statement and the values of all variables referenced or modified, and writes the modified program to the standard output. You must put the output of ctrace into a temporary file because the cc(lV) command does not allow the use of a pipe. You then compile and execute this file. As each statement in the program executes it will be listed at the terminal, followed by the name and value of any variables referenced or modified in the statement, followed by any output from the statement. Loops in the trace output are detected and tracing is stopped until the loop is exited or a different sequence of statements within the loop is executed. A warning message is printed every 1000 times through the loop to help you detect infinite loops. The trace output goes to the standard output so you can put it into a file for examination with an editor or the tail(l) command. OPTIONS -f functions Trace only these functions. -v functions Trace all but these functions. You may want to add to the default formats for printing variables, long and pointer variables are always printed as signed integers. Pointers to character arrays are printed as strings if appropriate, char, short, and int variables are printed as signed integers and, if appropriate, as characters, double variables are printed as floating-point numbers in scientific notation. You can request that variables be printed in addi- tional formats, if appropriate, with these options: -o Octal. -x Hexadecimal. -u Unsigned. -e Floating point. These options are used only in special circumstances: -1 n Check n consecutively executed statements for looping trace output, instead of the default of 20. Use 0 to get all the trace output from loops. -s Suppress redundant trace output from simple assignment statements and string copy func- tion calls. This option can hide a bug caused by use of the = operator in place of the = = operator. -t n Trace n variables per statement instead of the default of 10 (the maximum number is 20). The DIAGNOSTICS section explains when to use this option. -P Run the C preprocessor on the input before tracing it. You can also use the -D, -I, and -U cc(lV) options. Sun Release 4.1 Last change: 16 September 1989 119 CTRACE(IV) USER COMMANDS CTRACE(IV) These options are used to tailor the run-time trace package when the traced program will run in a non-UNIX system environment: — b Use only basic functions in the trace code, that is, those in ctype(3V), printf(3V), and string(3). These are often available even in cross-compilers for microprocessors. In partic- ular, this option is needed when the traced program runs under an operating system that does not have signaI(3V), fflush, longjmp or setjmp(3V) (see fc!ose(3V) and setjmp(3V)). -p ’ s’ Change the trace print function from the default of ’printf(’. For example, ’fprintf(stderr’ would send the trace to the standard error output. -r / Use file / in place of the runtime, c trace function package. This lets you change the entire print function, instead of just the name and leading arguments (see the -p option). USAGE Execution-Time Trace Control The default operation for ctrace is to trace the entire program file, unless you use the -f or -v options to trace specific functions. This does not give you statement by statement control of the tracing, nor does it let you turn the tracing off and on when executing the tracedprogram. You can do both of these by adding ctroff( ) and ctronQ function calls to your program to turn the tracing off and on, respectively, at execution time. Thus, you can code arbitrarily complex criteria for trace con- trol with if statements, and you can even conditionally include this code because ctrace defines the CTRACE preprocessor variable. For example: #ifdef CTRACE if (c == ’!’ &&i> 1000) ctronQ; #endif You can also call these functions from dbx(l) if you compile with the -g option. For example, to trace all but lines 7 to 10 in the primary source file, enter: dbx a. out when at 7 { call ctroff( ); cont; } when at 11 { call ctron( ); cont; } run You can also turn the trace off and on by setting the static variable tr_ct_ to 0 and 1, respectively. This is useful if you are using a debugger that cannot call these functions directly, such as adb(l). EXAMPLES If the file lc. c contains this C program: #in elude mainQ I* count lines in input */ { int c, nl; nl = 0; while ((c = getchar( )) != EOF) if (c = ’\n’) ++nl; printf("%d\n", nl); } and you enter these commands and test data: cc Ic. c a. out 1 CTRL-D, the program will be compiled and executed. The output of the program will be the number 2, which is not correct because there is only one line in the test data. The error in this program is common, but subtle. 120 Last change: 16 September 1989 Sun Release 4.1 CTRACE ( 1 V ) USER COMMANDS CTRACE (IV) If you invoke ctrace with these commands: ctrace lc. c >temp.c cc temp, c a. out the output will be: main() nl = 0; /* nl == 0 *1 while ((c = getcharQ) != EOF) The program is now waiting for input. If you enter the same test data as before, the output will be: I* c == 49 or ’1’ *1 if (c = ’\n’) /* c == 10 or ’\n’ */ ++nl; /* nl == 1 */ while ((c = getchar( )) != EOF) I* c == 10 or ’\n’ *1 if (c = ’\n’) /* c == 10 or ’\n’ *1 ++nl; /* nl == 2 *1 I* repeating *1 If you now enter an end of file character (CTRL-D) the final output will be: I* repeated <1 time *1 while ((c = getchar()) != EOF) I* c == -1 */ printf(" %d\n", nl); I* nl == 2 *12 I* return *1 Program output is printed at the end of the trace line for the nl variable. Also note the return comment added by ctrace at the end of the trace output. This shows the implicit return at the terminating brace in the function. The trace output shows that variable c is assigned the value ’1’ in line 7, but in line 8 it has the value ’\n\ Once your attention is drawn to this if statement, you will probably realize that you used the assignment operator = in place of the equal operator = =. You can easily miss this error during code reading. FILES /usr/lib/ctrace/runtime.c run-time trace package SEE ALSO adb(l), cc(lV), dbx(l), tail(l), ctype(3V), fclose(3V), printf(3V), setjmp(3V), signal(3V), string(3) DIAGNOSTICS This section contains diagnostic messages from both ctrace and cc(lV), since the traced code often gets some cc warning messages. You can get cc error messages in some rare cases, all of which can be avoided. From ctrace warning: some variables are not traced in this statement Only 10 variables are traced in a statement to prevent the C compiler ‘out of tree space; simplify expression’ error. Use the -t option to increase this number. warning: statement too long to trace This statement is over 400 characters long. Make sure that you are using tabs to indent your code, not spaces. Sun Release 4.1 Last change: 16 September 1989 121 CTRACE ( 1 V ) USER COMMANDS CTRACE (IV) cannot handle preprocessor code, use -P option This is usually caused by #ifdef/#endif preprocessor statements in the middle of a C statement, or by a semicolon at the end of a #define preprocessor statement. ’ if . . . else if ’ sequence too long Split the sequence by removing an else from the middle. possible syntax error, try -P option Use the -P option to preprocess the ctrace input, along with any appropriate -D, -I, and -U preprocessor options. If you still get the error message, check the WARNINGS section below. From cc warning: floating-point not implemented warning: illegal combination of pointer and integer warning: statement not reached warning: sizeof returns 0 Ignore these messages. compiler takes size of function See the ctrace ‘possible syntax error’ message above. yacc stack overflow See the ctrace ‘’if . . . else if sequence too long’ message above, out of tree space; simplify expression Use the -t option to reduce the number of traced variables per statement from the default of 10. Ignore the ‘ctrace: too many variables to trace’ warnings you will now get. redeclaration of signal Either correct this declaration of signal(3V), or remove it and #include . Warnings You will get a ctrace syntax error if you omit the semicolon at the end of the last element declaration in a structure or union, just before the right brace ( }). This is optional in some C compilers. Defining a function with the same name as a system function may cause a syntax error if the number of arguments is changed. Just use a different name. ctrace assumes that BADMAG is a preprocessor macro, and that EOF and NULL are #defined constants. Declaring any of these to be variables, for example, ‘int EOF;’, will cause a syntax error. BUGS ctrace does not know about the components of aggregates like structures, unions, and arrays. It cannot choose a format to print all the components of an aggregate when an assignment is made to the entire aggregate, ctrace may choose to print the address of an aggregate or use the wrong format (for example, %e for a structure with two integer members) when printing the value of an aggregate. Pointer values are always treated as pointers to character strings. The loop trace output elimination is done separately for each file of a multi-file program. This can result in functions called from a loop still being traced, or the elimination of trace output from one function in a file until another in the same file is called. 122 Last change: 16 September 1989 Sun Release 4.1 CU(1C) USER COMMANDS CU(1C) NAME cu - connect to remote system SYNOPSIS cu [ — dhnt ] [ -e i -o ] [ -I line ] [ -s speed ] phone-number cu [ -dh ] [ -e I -o ] [ -s speed ] -1 line cu [ -dh ] [ -e I -o ] systemname DESCRIPTION cu calls up another system, or possibly a terminal. It manages an interactive conversation with possible transfers of ASCII files. If phone-number is specified, it is the telephone number of the system to be dialed. Equal signs specify a pause for a secondary dial tone, and minus signs specify dialing delays of 4 seconds. If systemname is specified, it is the UUCP name of a the system to be dialed; in this case, cu will obtain an appropriate direct line or telephone number from /etc/uucp/Systems. Note: the systemname option should not be used in conjunction with the -1 and -s options as cu will connect to the first available line for the system name specified, ignoring the requested line and speed. If neither phone-number nor systemname are specified, the —1 line option must be provided; line specifies the device name to use. OPTIONS -d Print diagnostic traces. -h Emulate local echo, supporting calls to other computer systems which expect terminals to be set to half-duplex mode. -n For added security, prompt the user to provide the telephone number to be dialed rather than taking it from the command line. -t Perform appropriate mapping of RETURN to RETURN-LINE-FEED pairs. This is used to dial an ASCH terminal which has been set to auto answer. Generate even parity for data sent to the remote system. Generate odd parity for data sent to the remote system. Specify a device name to use as the communication line. This can be used to override the search that would otherwise take place for the first available line having the right speed. When the -1 option is used without the -s option, the speed of a line is taken from the /etc/uucp/Devices file. When the -1 and -s options are both used together, cu will search the Devices file to check if the requested speed for the requested line is available. If so, the connection will be made at the requested speed; otherwise an error message will be printed and the call will not be made. The specified device is generally a directly connected asyn- chronous line (for example, /dev/ttyab) in which case a telephone number {phone-number ) is not required. The specified device need not be in the /dev directory. If the specified dev- ice is associated with an auto dialer, a telephone number must be provided. Use of this option with systemname rather than phone-number will not give the desired result (see sys- temname below). Specify the transmission speed (300, 1200, 2400, 4800, 9600); The default value is “Any” speed which will depend on the order of the lines in the Devices file. Most modems are either 300 or 1200 baud. Directly connected lines may be set to a speed higher than 1200 baud. USAGE After making the connection, cu runs as two processes: the transmit process reads data from the standard input and, except for lines beginning with ", passes it to the remote system; the receive process accepts data from the remote system and, except for lines beginning with ", passes it to the standard output. Normally, an automatic XON/XOFF protocol is used to control input from the remote so the buffer is not overrun. Sun Release 4.1 Last change: 26 July 1988 123 CU(1C) USER COMMANDS CU(1C) Commands A tilde ( ~ ) appearing as the first character of a line is an escape signal which directs cu to perform some special action. The transmit recognizes the following escape sequences: Drop the connection and exit (you may still be logged in on the remote machine). Escape to an interactive shell on the local machine (exiting the shell returns you to cu). Run the command cmd on the local system (using sh -c). Run the command cmd locally and send its output to the remote system. Change the directory on the local system. Note: "led will cause the command to be run by a sub-shell, probably not what was intended. %take from [to] Copy file from (on the remote system) to file to on the local system. If to is omitted, the from argument is used in both places. %put from [to] Copy file from (on local system) to file to on remote system. If to is omitted, the from argu- ment is used in both places. For both '%take and "%put commands, as each block of the file is transferred, consecutive single digits are printed to the terminal. Send the line 'line to the remote system. Send a BREAK to the remote system (which can also be specified as "%b). Toggle the -d debugging option on or off (which can also be specified as _ %d). Prints the values of the termio(4) structure variables for the user’s terminal (useful for debugging). Prints the values of the termio structure variables for the remote communication line (useful for debugging). Toggle between XON/XOFF input control protocol and no input control. This is useful in case the remote system is one which does not respond properly to the XON or XOFF charac- ters. The receive process normally copies data from the remote system to its standard output. Internally the pro- gram accomplishes this by initiating an output diversion to a file when a line from the remote begins with ~. Data from the remote is diverted (or appended, if » is used) to file on the local system. The trailing "> marks the end of the diversion. The use of ‘%put requires stty(lV) and cat(lV) on the remote side. It also requires that the current erase and kill characters on the remote system be identical to these current control characters on the local system. Backslashes are inserted at appropriate places. The use of “%take requires the existence of echo(lV) and cat(lV) on the remote system. Also, tabs mode (see stty(lV)) should be set on the remote system if TAB characters are to be copied without expansion to SPACE characters. When cu is used on system X to connect to system Y and subsequently used on system Y to connect to sys- tem Z, commands on system Y can be executed by using In general, “ executes the command on the ori- ginal machine, “ executes the command on the next machine in the chain. EXAMPLES To dial a system whose telephone number is 9 201 555 1212 using 1200 baud (where dialtone is expected after the 9): cu — s!200 9=12015551212 “ line '% break ~% debug "t 1 “% nostop ~lcmd ~%cmd -%cd 124 Last change: 26 July 1988 Sun Release 4.1 CU(1C) USER COMMANDS CU(1C) If the speed is not specified, “Any” is the default value. To login to a system connected by a direct line: cu -1 /dev/ttyXX or cu — 1 ttyXX To dial a system with the specific line and a specific speed: cu -sl200 -1 ttyXX To dial a system using a specific line associated with an auto dialer: cu -1 culXX 9=12015551212 To use a system name: cu systemname FILES /etc/uucp/Systems file listing remote systems /etc/uucp/Devices file listing devices to use /var/spool/Iocks/LCK . .* lock file to avoid conflicts with UUCP SEE ALSO cat(lV), echo(lV), stty(lV), tip(lC), uucp(lC), termio(4) DIAGNOSTICS Exit code is zero for normal exit, otherwise, 1. WARNINGS The cu command does not do any integrity checking on data it transfers. Data fields with special cu char- acters may not be transmitted properly. Depending on the interconnection hardware, it may be necessary to use a ‘V to terminate the conversion even if stty 0 has been used. Non-printing characters are not dependably transmitted using either the "%put or “%take commands. BUGS There is an artificial slowing of transmission by cu during the "%put operation so that loss of data is unlikely. Sun Release 4.1 Last change: 26 July 1988 125 CUT (IV) USER COMMANDS CUT (IV) NAME cut - remove selected fields from each line of a file SYNOPSIS cut -c list [filename . . . ] cut -f list [ -dc ] [ -s ] [filename . . . ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Use cut to cut out columns from a table or fields from each line of a file; in data base parlance, it imple- ments the projection of a relation. The fields as specified by list can be of fixed length, (such as on a punched card), or of variable length between lines. They can be marked with a field delimiter character, such as TAB (as specified with the -d option), cut can be used as a filter; if no files are given, the standard input is used. In addition, a file name of ’ explicitly refers to the standard input. OPTIONS -c list By character position, list is a comma-separated list of integer field numbers (in increasing order), with an optional to indicate ranges: 1 , 4,7 characters 1, 4 and 7 1 - 3,8 characters 1 through 3, and 8 - 5,10 characters (1) through 5, and 10 3 - characters 3 through (last) -f list By field position. Instead of character positions, list specifies fields that are separated a delimiter (normally a TAB): 1 , 4,7 fields 1,4 and 7 Lines with no field delimiters are normally passed through intact (to allow for subheadings). -dc Set the field delimiter to c. The default is a TAB. Characters with special meaning to the shell such as a TAB or SPACE characters, must be quoted. -s Suppress lines with no delimiter characters. EXAMPLES cut -d: -fl,5 /etc/passwd Mapping of user IDs to names. name=who am i | cut -fl -d" " Set name to the current login name. SEE ALSO grep(lV), paste(lV) DIAGNOSTICS ERROR: line too long A line can have no more than 1023 characters or fields. ERROR: bad list for c / f option Missing -c or -f option or incorrectly specified list. No error occurs if a line has fewer fields than the list calls for. ERROR: no fields The list is empty. ERROR: no delimiter Missing char on -d option. ERROR: cannot handle multiple adjacent backspaces Adjacent backspaces cannot be processed correctly. 126 Last change: 16 September 1989 Sun Release 4.1 CUT (IV) USER COMMANDS CUT(IV) WARNING: cannot open filename : reason Either filename cannot be read or does not exist. If multiple filenames are present, process- ing continues. WARNING: I/O error riding filename', reason An I/O error occurred when reading filename. If multiple filenames are present, processing continues. Sun Release 4. 1 Last change: 16 September 1989 127 CXREF(IV) USER COMMANDS CXREF(IV) NAME cxref- generate a C program cross-reference SYNOPSIS cxref [ -c ] [ — w [ num ] ] [ — o filename ] [ — t ] filenames SYSTEM V SYNOPSIS /usr/5bin/cxref [ -c ] [ -w [ num ] ] [ -o filename ] [ -t] filenames AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION cxref analyzes a collection of C files and attempts to build a cross-reference table, cxref utilizes a special option of cpp(l) to include tdefine’d information in its symbol table. It produces a listing on standard out- put of all symbols (auto, static, and global) in each file separately, or with the -c option, in combination. Each symbol contains an asterisk (*) before the declaring reference. SYSTEM V DESCRIPTION The System V version of cxref, run as /usr/5bin/cxref, makes the C preprocessor search for include files in /usr/5include before searching for them in /usr/include. OPTIONS In addition to the -D, -I and -U options (which are identical to their interpretation by cc(lV)), the follow- ing options are interpreted by cxref: -c Print a combined cross-reference of all input files. -w[ num ] Width option which formats output no wider than num (decimal) columns. This option will default to 80 if num is not specified or is less than 51. -o filename Direct output to named file . -s Operate silently; does not print input file names. -t Format listing for 80-column width. FILES /usr/tmp/xr* temporary files SEE ALSO cc(lV), cpp(l) DIAGNOSTICS Error messages are unusually cryptic, but usually mean that you cannot compile these files, anyway. NOTES While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. See cc(lV) for an explanation about why cc is not 8-bit clean. BUGS cxref considers a formal argument in a #define macro definition to be a declaration of that symbol. For example, a program that includes ctype. h, will contain many declarations of the variable c. 128 Last change: 16 September 1989 Sun Release 4.1 DATE (IV) USER COMMANDS DATE (IV) NAME date - display or set the date SYNOPSIS date [ -u ] [ -a [ - ] sss.fff] [ yy mm dd hh mm [.«]][ +format ] SYSTEM V SYNOPSIS /usr/5bin/date [ -u ] [ -a [ - ] sss.fff ] [ mm dd hh mm [ yy ] ] [ + format ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION If no argument is given, or if the argument begins with +, date displays the current date and time. Other- wise, the current date is set. 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. If the argument begins with +, the output of date is under the control of the user. The format for the output is similar to that of the first argument to printf(3V). All output fields are of fixed size (zero padded if necessary). Each field descriptor is preceded by % and will be replaced in the output by its corresponding value. A single % is encoded by %%. All other characters are copied to the output without change. The string is always terminated with a new-line character. Field Descriptors: n insert a new-line character t insert a tab character m month of year - 01 to 12 d day of month - 01 to 31 y last 2 digits of year - 00 to 99 D date as mm/dd/yy H hour - 00 to 23 M minute - 00 to 59 S second - 00 to 59 T time as HH:MM:SS j day of year - 001 to 366 w day of week - Sunday = 0 a abbreviated weekday - Sun to Sat h abbreviated month - Jan to Dec r time in AM/PM notation SYSTEM V SYNOPSIS When setting the date, 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; yy is the last 2 digits of the year number and is optional. The current year is the default if no year is mentioned. 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. -a [~]sss.fff Using the adjtime(2) system call, tell the system to slowly adjust the time by sss.fff seconds (fff represents fractions of a second). This adjustment can be positive or nega- tive. The system’s clock will be sped up or slowed down until it has drifted by the number of seconds specified. Sun Release 4.1 Last change; 23 November 1987 129 DATE (IV) USER COMMANDS DATE (IV) EXAMPLES date 10080045 Would set the date to Oct 8, 12:45 AM. If the year were 1986, and the date were so set, date '+DATE: %m/%d/%y%nTIME: %H:%M:%S' would generate as output: DATE: 08/01/86 TIME: 14:45:05 FILES /var/adm/wtmp to record time-setting /usr/share/lib/zoneinfo timezone definitions SEE ALSO adjtime(2), printf(3V), utmp(5V) DIAGNOSTICS date: Failed to set date: Not owner If you try to change the date but are not the super-user. date: bad format character If the field descriptor is not recognizable. 130 Last change: 23 November 1987 Sun Release 4.1 DBX(l) USER COMMANDS DBX(l) NAME dbx - source-level debugger SYNOPSIS dbx [ -f /count ] [ -i ] [ -I dir ] [ -k ] [ -kbd ] [ -Pfd ] [ -r ] [ -s startup ] [ -sr ts tar tup ] [ objfile [ corefile I process-id ] ] AVAILABILITY This command is available with the Debugging software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION dbx is a utility for source-level debugging and execution of programs written in C, or other supported languages such as Pascal and FORTRAN 77. dbx accepts the same commands as dbxtool(l), but uses a standard terminal (tty) interface. objfile is an object file, produced by cc(lV) or another compiler, with the -g option to include a symbol table. This symbol table contains the names of all the source files used to create it, and these files are avail- able for perusal while using the debugger. If no objfile is specified, you can use dbx’s debug command to specify the program to debug. If there is a file named core in the current directory, or a corefile argument is specified, you can use dbx to examine the state of the program when the core file was produced. dbx commands in the file . dbxinit are executed immediately before the symbol table is read, if that file exists in the current directory, or in the user’s home directory if . dbxinit does not exist in the current direc- tory. OPTIONS -f f count Alter the initial estimate of the number functions in the program being debugged. The ini- tial setting is 500. -i Force dbx to act as though the standard input were a terminal or terminal emulator. -I dir Add dir to the list of directories in which to search for a source file, dbx normally searches the current directory, and the directory where objfile is located. The directory search path can be reset with the use command. -k -kbd -Pfd -s startup -sr tstartup Kernel debugging. Debug a program that sets the keyboard into up-down translation mode. This flag is neces- sary if a program uses up-down decoding. Create a pipeline to a dbxtool(l) process, fd is the file descriptor through which to pipe out- put to the front-end process. This option is passed automatically to dbx by dbxtool. Execute objfile immediately. Parameters follow the object file name (redirection is handled properly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for a response, dbx reads from the terminal (/dev/tty) when -r is specified and standard input is a file or pipe. Read initialization commands from the file named startup. Read initialization commands from the temporary file named startup , and then remove that file. USAGE Refer to dbx in the Debugging Tools manual. 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, to display variables, and stop, to set breakpoints. Sun Release 4.1 Last change: 6 December 1989 131 DBX(l) USER COMMANDS DBX ( 1 ) Filenames Filenames in 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. Variables are either variables in the program being debugged or special dbx variables whose names begin with $. 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. Operators + - * / div % Add, subtract, multiply, divide, integer division, and remainder, respectively. dbx has two division operators. 7’ always yields a floating-point result and div always yields an integral result. << >> & | 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 to, greater than or equal to, equal, not equal, and negation. & & || Logical AND, and logical OR sizeof (cast) Size of variable or type and type cast. • -> Field reference, and pointed-to-field reference (however, dot works for both in dbx). Precedence and associativity of operators are the same as for C; parentheses can be used for grouping. If there is no corefile, only expressions containing constants are available. Procedure calls require an active child process. Scope Rules dbx uses the current file and function to resolve scope conflicts. Their values are updated as files and func- tions are entered and exited during execution. You can also change them explicitly by using the file and func commands. When the current function is changed, the current file is updated along with it, but not vice versa. Execution and Tracing Commands 'C Interrupt. Stop the program being debugged and enter dbx. run [ args ] [ < infile ] [ > I » outfile ] Start executing objfile, reading in any new information from it. With no args, use the argument list from the previous run command. args Pass args as command-line arguments to the program. < I > I » Redirect input or output, or append output to a file. rerun [ args ] [ < infile ] [ > I » outfile ] Like the run command, except that when args are omitted, none are passed to the program. cont [ at sourceline ] [ sig signal ] Continue execution from where it stopped. at sourceline Start from sourceline sig signal Continue as if signal had occurred, signal may be a number or a name as with catch. 132 Last change: 6 December 1989 Sun Release 4.1 DBX ( 1 ) USER COMMANDS DBX ( 1 ) trace [ in function ] [ if condition ] trace sourceline [ if condition ] trace function [ if condition ] trace expression at sourceline [ if condition ] trace variable [ in function ] [ if condition ] Display tracing information. If no argument is specified, each source line is displayed before exe- cution. Tracing is turned off when the function or procedure is exited. in function Display tracing information only while executing the function or pro- cedure function. if condition Display tracing information only if condition is true. sourceline Display the line immediately prior to executing it. Source line-numbers from another file are written as filename: n. function Display the routine and source line called from, parameters passed in, and return value. expression at sourceline Display the value of expression whenever sourceline is reached. variable Display the name and value whenever variable changes. stop at sourceline [ if condition ] stop in function [ if condition ] stop variable [ if condition ] stop if condition Stop execution when the sourceline is reached, function is called, variable is changed, or condi- tion becomes true. when in function { command ; [ command ; ] . . . } when at sourceline { command ; [ command ;]...} when condition { command ; [ command ; ] . . . } Execute the dbx command^ s) when function is called, sourceline is reached, or condition is true. status [ > filename ] Display active trace, stop and when commands, and associated command numbers. delete all delete cmd-no [ , cmd-no ] . . . Remove all traces, stops and whens, or those corresponding to each dbx cmd-no (as displayed by status). clear [ sourceline ] Clear all breakpoints at the current stopping point, or at sourceline. catch [ signal [ , signal ] . . . ] Display all signals currently being caught, or catch signal before it is sent to the program being debugged. A signal can be specified either by name (with the SIG prefix omitted, as with kill(l)) or number. Initially all signals are caught except SIGHUP, SIGEMT, SIGFPE, SIGKILL, SIGALRM, SIGTSTP, SIGCONT, SIGCHLD, and SIGWINCH. ignore [ signal [ , signal ] . . . ] Display all signals currently being ignored, or stop catching signal, which may be specified by name or number as with catch. step [n ] Execute the next n source lines. If omitted, n is taken to be 1. Steps into functions. next [n ] Execute the next n source lines. If omitted, n is taken to be 1. next steps past functions. Sun Release 4. 1 Last change: 6 December 1989 133 DBX(l) USER COMMANDS DBX ( 1 ) Naming, Printing and Displaying Data Variables from another function or procedure with the same name as one in the current block must be qualified as follows: [ 'sourcefile function 'variable For Pascal variables there may be more than one function or procedure name, each separated by a backquote. print expression [ , expression \ ... Print the value of each expression, which may involve function calls. Program execution halts when a breakpoint is reached, and dbx resumes. display [ expression [ , expression ] . . . ] Print a list of the expressions currently being displayed, or display the value of each expression whenever execution stops. undisplay [ expression [ , expression ] . . . ] Stop displaying the value of each expression whenever execution stops. If expression is a con- stant, it refers to a display-number as shown by the display command with no arguments. whatis identifier whatis type Print the declaration of the given identifier or type, types are useful to print all the members of a structure, union, or enumerated type. which identifier Print the fully-qualified name of the given identifier, whereis identifier Print the fully qualified name of all symbols matching identifier. assign variable = expression set variable = expression Assign the value of expression to variable. There is no type conversion for operands of differing type. set81 fpreg=wordl word2 word3 Treat the concatenation of wordl word2 word3 as a 96-bit, IEEE floating-point value and assign it to the MC68881 floating-point register fpreg. (Supported only on Sun-3). call function ( parameters ) Execute the named function. Arguments are passed according to the rules for the source-language of function. where [ n] List all, or the top n, active functions on the stack, dump [function ] Display the names and values of local variables and parameters in the current or specified func- tion. up [«] down [n] Move up (towards “main”) or down the call stack, one or n levels. File Access Commands edit [filename I function ] Edit the current source file, or the given filename or the file that contains function. file [filename ] Print the name of the current source file, or change the current source file to filename. 134 Last change: 6 December 1989 Sun Release 4.1 DBX(l) USER COMMANDS DBX(l) func [function\ program I objfile ] Print the name of the current function, or change to the given function, program, or objfile. Also changes the current scope. list [ startline [ , endline ] ] list function List the next ten lines from current source file, list from startline through endline, or and list from five lines above, to five lines below the first line of function. use [ directory-list ] Print or set the list of directories in which to search for source files, cd [ directory ] Change the current working directory for dbx to directory (or to the value of the HOME environ- ment variable). pwd Print the current working directory for dbx. /reg-exp[l] treg-exp [ ? ] Search the current file for the regular expression reg-exp, from the next (previous) line to the end (top). The matching line becomes the new current line. 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 characters occur- ring in character-sequence must be enclosed in quotation marks. Alias substitution as with the C shell (csh(l)) also occurs. help t command ] Display a synopsis of dbx commands, or print a short message explaining command. make Invoke make(l) with the name of the program as its argument. Any arguments set using dbxenv makeargs are also passed as arguments. setenv name string Set environment variable name to string. source filename Read and execute dbx commands from filename. Useful when the filename has been created by redirecting an earlier status command. quit Exit dbx. dbxenv dbxenv case sensitive I insensitive dbxenv fpaasm on I off dbxenv fpabase a[0-7] I off dbxenv makeargs string dbxenv stringlen num dbxenv speed seconds Display dbx attributes or set the named attribute: case Controls whether upper- and lower-case characters are treated as different values. The default is sensitive. fpaasm Controls FPA instruction disassembly. The default is on. (Supported only on Sun-3). Sun Release 4.1 Last change: 6 December 1989 135 DBX(l) USER COMMANDS DBX(l) fpabase Sets the base register for FPA instruction disassembly. The default is off. (Supported only on Sun-3 systems). makeargs Sets arguments to pass to make. The default is CC=cc -g. speed Set the interval between execution during tracing. The default is 0.5 seconds. str inglen Controls the maximum number of characters printed for a “char *” variable in a C program. The default is 512. debug [ -k ] [ objfile [ corefile I pid ] ] With no arguments, print the name of the current program. With arguments, stop debugging the current program and begin debugging objfile having either corefile or the current process ID pid. The -k option indicates kernel debugging. kill Stop debugging of the current program, but be ready to debug another. detach Detach the current program (process) from dbx. dbx will be unable to access or modify its state. modules modules select [ all I objfile . . . ] modules append objfile [ objfile . . . ] The modules command displays or sets the current modules selection list. If the modules selec- tion list is set, the debugger reads debugging information only for object files in this list. Debug- ging information for object files not in the modules selection list is ignored. modules with no arguments displays the set of object files for which source level debugging infor- mation is currently available, including the path names of any associated source files. If the debugger cannot access a source file for which it has debugging information, it displays the source file name with a trailing *?’ (question mark) character. Source file path names reflect the current search path as set by the use command or the —I option. modules select displays the current modules selection list if no objfile is given. Otherwise, modules select sets the modules selection list to the specified object files. To get complete debug- ging information, the debugger may need to read object files not in the modules selection list, ‘modules select’ displays these “implied” file names with trailing (asterisk) characters (see NOTES), ‘modules select all’ discards the modules selection list. modules append appends the specified object files to the modules selection list. If the modules selection list includes an object file not in the executable being debugged, the debugger issues a warning. proc [ pid ] For kernel debugging. Display which process is mapped into the user area, or map pid to the user area. Machine-Level Commands tracei [ address ] [ if condition ] tracei [ variable ] [at address ] [ if condition ] Trace execution of a specific machine-instruction address. stopi [ variable ] [ if condition ] stopi [at address ] [ if condition ] Set a breakpoint at a machine instruction address. stepi nexti Single step as in step or next, but do a single machine instruction rather than a source line. 136 Last change: 6 December 1989 Sun Release 4.1 DBX(l) USER COMMANDS DBX ( 1 ) address, address / [ mode ] address / [count ] [ mode ] Display the contents of memory starting at the first (or current) address up to the second address, or until count items have been displayed. The initial display mode is X. The following modes are supported: i the machine instruction d word in decimal D longword in decimal o word in octal O longword in octal x word in hexadecimal X longword in hexadecimal b byte in octal c byte as a character s strings as characters terminated by a null f single precision real number F double-precision real number E extended-precision real number (not supported on Sun-4) An address can be specified as an item from the following list, as an expression made up of other addresses and the operators *+’, and indirection (unary “*’), or as an arbitrary expression enclosed in parentheses. &name symbolic address integer numeric address address = [ mode ] Display the value of the address. Machine Registers The machine registers for the current machine type are represented as special dbx variables. They can be used in expressions as any other dbx variable can. The registers and their variable names are: Sun-2 and Sun-3 Registers $d[0-7] $a[0-7] $fp $sp $pc $ps Sun-3-Only Registers $fp[0-7] $fpc $fps $fpi $fpf $fpa[0-31] $sfpa[0-31] Sun-4 Registers $g[0-7] $o[0-7] $i[0-7] $l[0-7] $fp $sp data registers address registers frame pointer, equivalent to register a 6 stack pointer, equivalent to register a7 program counter program status MC6888 1 data registers MC6888 1 control register MC6888 1 status register MC68881 instruction address register MC68881 flags register (unused, idle, busy) double-precision interpretation of FPA registers. single-precision interpretation of FPA registers. global registers “out” registers “in” registers “local” registers frame pointer, equivalent to register i 6 stack pointer, equivalent to register 06 Sun Release 4.1 Last change: 6 December 1989 137 DBX(l) USER COMMANDS DBX(l) $y Y register $psr processor state register $wim window invalid mask register $tbr trap base register $pc program counter $npc next program counter $f[0-31] FPU “f” registers $fsr FPU status register $fq FPU queue Sun386i Registers $SS stack segment register $eflags flags $cs code segment register $eip instruction pointer $eax general register $ecx general register $edx general register $ebx general register $esp stack pointer $ebp frame pointer $esi source index register $edi destination index register $ds data segment register $es alternate data segment register $fs alternate data segment register $gs alternate data segment register Registers for the 80386 lower halves (16 bits) are: Sax general register $cx general register $dx general register $bx general register $sp stack pointer $bp frame pointer $si source index register $di destination index register Sip instruction pointer, lower 16 bits Sflags flags, lower 16 bits The first four Sun386i 16-bit registers can be split into 8-bit parts: $al lower (right) half of register $ax $ah higher (left) half of register $ax $cl lower (right) half of register $cx $ch higher (left) half of register $cx $dl lower (right) half of register $dx $dh higher (left) half of register $dx $bl lower (right) half of register $bx $bh higher (left) half of register $bx Registers for the 80387 are: $fctrl control register $fstat status register $ftag tag register $fip instruction pointer offset $fcs code segment selector 138 Last change: 6 December 1989 Sun Release 4.1 DBX(l) USER COMMANDS DBX(l) $fopoff operand pointer offset $fopsel operand pointer selector $stO - $st7 data registers ENVIRONMENT dbx checks the environment variable EDITOR for the name of the text editor to use with the edit command. FILES core . dbxinit 7. dbxinit SEE ALSO cc(lV), csh(l), dbxtool(l), kill(l), lex(l), make(l), yacc(l) Debugging Tools NOTES Because the cc command does not generate or support 8-bit symbol names, it is inappropriate to make dbx 8-bit clean. See cc(l V) for an explanation about why cc is not 8-bit clean. To save space, the linker eliminates debugging information redundantly defined in multiple include files. If the linker excluded some of the symbols for an object file in the modules selection list, the debugger must read debugging information from the object files where these symbols were first defined. If these “implied” modules are not in the modules selection list, ‘modules select’ displays their names with tr ailin g *■*’ (asterisk) characters. 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 command). Unlike C, dbx does not recognize an array or function name as the address of the array or function. In dbx, an array name signifies the entire array, and a function name signifies a call to the function with no arguments. To get the address of an array, take the address of its first element. To get the address of a function, take the address of its name. Casts do not work with FORTRAN 77 or Pascal. Executable code incorporated into a source file using an #include preprocessor directive confuses dbx. dbx is confused by the output of program generators such as yacc(l) and lex(l). A step command issued at a procedure call will not work properly when debugging information is available for the function being called and that function is in a shared library. default core file local dbx initialization file user’s dbx initialization file Sun Release 4.1 Last change: 6 December 1989 139 DBXTOOL ( 1 ) USER COMMANDS DBXTOOL ( 1 ) NAME dbxtool — SunView interface for the dbx source-level debugger SYNOPSIS dbxtool [ -d ] [ -i ] [ -k ] [ -kbd ] [ -I directory ] [ objectfile [ corefile ] ] AVAILABILITY This command is available with the Debugging software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION dbxtool, a source-level debugger for C, Pascal and FORTRAN 77 programs, is a standard tool that runs within the SunView environment. It accepts the same commands as dbx, but provides a more convenient user interface. You can use the mouse to set breakpoints, examine the values of variables, control execution, peruse source files, and so on. dbxtool has separate subwindows for viewing source code, entering commands and other uses. objectfile is an object file produced by cc(lV), any other Sun compiler, (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 linking phase, must include the — g option. If no objectfile is specified, you can use the debug command to specify the program to be debugged. The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it. These files are available for perusal while using the debugger. If a file named core exists in the current directory or a corefile is specified, dbxtool can be used to examine the state of the program when it faulted. Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit does not exist in the current directory. OPTIONS — d Produce debugging information for the pipeline from which it reads dbx(l) output. -i Force dbxtool to act as though standard input were a terminal. -k Kernel debugging. -kbd Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if you are debugging a program that uses up/down encoding. -I directory Add directory to the list of directories that are searched when looking for a source file. Normally dbxtool looks for source files in the current directory and then in the directory where objectfile is located. The directory search path can also be set with the use command. Multiple -I options may be given. USAGE Refer to dbx(l) for a summary of dbx commands, or Debugging Tools for more complete information on using dbxtool. FILES core default core file . dbxinit local dbx initialization file 7. dbxinit user’s dbx initialization file SEE ALSO cc(lV), dbx(l) Debugging Tools SunView Programmer’ s Guide 140 Last change: 11 January 1988 Sun Release 4.1 DBXTOOL ( 1 ) USER COMMANDS DBXTOOL ( 1 ) BUGS The bugs for dbx(l) apply to dbxtool as well. The interaction between scrolling in the source subwindow and dbx’s regular expression search commands is wrong. Scrolling should affect where the next search begins, but it does not. Sun Release 4.1 Last change: 11 January 1988 141 DC ( 1 ) USER COMMANDS DC ( 1 ) NAME dc — desk calculator SYNOPSIS dc [ filename ] DESCRIPTION dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but an input base, output base, and a number of fractional digits to be maintained may be specified. The overall struc- ture of dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its end, and then from the standard input. Note: bc(l) is a preprocessor for dc that provides infix (normal arithmetic) notation, a C-like syntax for functions, and reasonable control structures for programs. The following input constructs are recognized: Commands number Push a number onto the stack. A number is an unbroken string of the digits 0-9. It may be preceded by an underscore to input a negative number, and may contain decimal points. + - / * % “ The top two values on the stack are: added (+), subtracted (-), multiplied (*), divided (/), remaindered (%), or exponentiated (*). The two entries are popped off the stack and the result is pushed in their place. Any fractional part of an exponent is ignored. s x Pop the top of the stack and store into a register named x, where x is any character. S x Treat x as a stack and push the value onto it. lx Push the value in register x onto the stack. The register x is not altered. All registers start with zero value. Lx Treat register x as a stack, and pop its top value onto the main stack, d Duplicate the top value on the stack. p Print the top value on the stack. The top value remains unchanged. P Interpret the top of the stack as an ASCII string, remove and print it. f Print all values on the stack and in registers. q Exit the program. If executing a string, pop the recursion level by two. Q Pop the top value on the stack, and pop the string execution level by that value. x Treat the top element of the stack as a character string and execute it as a string of dc com- mands. X Replace the number on the top of the stack with its scale factor. [ . . . ] Put the bracketed ASCII string onto the top of the stack. x =x Pop and compare top two elements of the stack. Execute register x if they obey the stated rela- tion. v Replace 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. ! Interpret the rest of the line as a command. c Clear all values on the stack. i Pop the top value on the stack and use that value as the input radix. I Push the input base on the top of the stack, o Pop the top value on the stack and use as the output radix. 142 Last change: 23 September 1987 Sun Release 4.1 DC(1) USER COMMANDS DC(1) 0 Push the output base on the top of the stack. k The top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate number of places are printed on output, and maintained during multiplication, divi- sion, and exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all are changed together. z Push the stack level onto the stack. Z Replace the number on the top of the stack with its length. ? Take a line of input from the input source (usually the terminal) and execute it. ; : 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) DIAGNOSTICS x is unimplemented stack empty Out of space Out of headers Out of pushdown Nesting Depth BUGS Base conversions on fractions are truncated to the number of fractional digits of the input value. The values are not rounded. Where x is an octal number. For not enough elements on the stack to do what was asked. When the free list is exhausted (too many digits). For too many numbers being kept around. For too many items on the stack. For too many levels of nested execution. Sun Release 4.1 Last change: 23 September 1987 143 DD(1) USER COMMANDS DD(1) NAME dd — convert and copy files with various data formats SYNOPSIS dd [ option=value ] . . . DESCRIPTION dd copies a specified input file to a specified output with possible conversions. The standard input and out- put are used by default. The input and output block size may be specified to take advantage of raw physi- cal I/O. OPTIONS if=name Input file is taken from name ; standard input is default. of =name Output file is taken from name; standard output is default. Note: dd creates an explicit output file; therefore the seek option is usually useless with explicit output except in spe- cial cases such as using magnetic tape or raw disk files. ibs=n Input block size n bytes (default 512). obs=n Output block size n bytes (default 512). bs=n Set both input and output block size, superseding ibs and obs; also, if no conversion is specified, it is particularly efficient since no copy need be done. Block sizes for the Sun386i are 9k for 3.5-inch floppy disks, and 126b (blocks) for quarter-inch tapes. cbs=n Conversion buffer size. skip=n Skip n input records before starting copy files=n Copy n input files before terminating (makes sense only when input is a magtape or similar device). seek=n Seek n records from beginning of output file before copying. This option generally only works with magnetic tapes and raw disk files and is otherwise usually useless if the explicit output file was named with the of option. count=n Copy only n input records. conv=ascii Convert EBCDIC to ASCII, ebcdic Convert ASCII to EBCDIC, ibm Slightly different map of ASCII to EBCDIC, block Convert variable length records to fixed length, unblock Convert fixed length records to variable length, lease Map alphabetics to lower case, ucase Map alphabetics to upper case, swab Swap every pair of bytes, noerror Do not stop processing on an error, sync Pad every input record to ibs. arg,arg [,...] Several comma-separated conversions, for a combination of effects. For instance, conv=sync, block is useful for reading variable-length output from a pipe. Where sizes are specified, a number of bytes is expected. A number may end with k (kilobytes) to specify multiplication by 1024, b (blocks of 512 bytes) to specify multiplication by 512, or w (words) to specify multiplication by 4; a pair of numbers may be separated by x to indicate a product. 144 Last change: 28 January 1988 Sun Release 4.1 DD(1) USER COMMANDS DD(1) cbs is used only if ascii, unblock, ebcdic, ibm, or block conversion is specified. In the first two cases, cbs characters are placed into the conversion buffer, any specified character mapping is done, trailing blanks trimmed and NEWLINE added before sending the line to the output. In the latter three cases, characters are read into the conversion buffer, and blanks added to make up an output record of size cbs. After completion, dd reports the number of whole and partial input and output blocks. EXAMPLES To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file x: example % dd if = /dev/rmtO of = x ibs = 800 cbs = 80 conv = ascii, lease Note: the use of raw magtape: dd is especially suited to I/O on the raw physical devices because it allows reading and writing in arbitrary record sizes. Sun386i EXAMPLES The following write the file filename to a 3.5-inch floppy and read from the floppy into a file filename, respectively: example% dd \f=filename of=/dev/rfdOc bs=9k example % dd if=/dev/rfdOc of =filename bs=9k Sun386i files names are shown in fdformat(l). SEE ALSO cp(l), fdformat(l), tr(lV) DIAGNOSTICS f+p records in(out): Numbers of full and partial records read(written). BUGS The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 1968. The ibm conversion, while less blessed as a standard, corresponds better to certain IBM print train conven- tions. There is no universal solution. The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Invalid combinations silently ignore all but the last mutually-exclusive keyword. Sun Release 4.1 Last change: 28 January 1988 145 DEFAULTSEDIT ( 1 ) USER COMMANDS DEFAULTSEDIT ( 1 ) NAME defaultsedit, defaults_from_input, defaults_to_indentpro, defaults_to_mailrc, indentpro_to_defaults, input_from_defaults, lockscreen_default, mailrc_to_defaults, scrolldefaults, stty_from_defaults - create or edit default settings for SunView utilities SYNOPSIS defaultsedit [ generic-tool-arguments ] defaults_from_input defaults_to_indentpro defaults_to_mailrc indentpro_to_defaults input_from_defaults lockscreen_default mailrc_to_defaults scrolldefaults stty_from_defaults AVAILABILITY These commands are available with the SunView User’s Guide software installation option. Refer to Ins- talling SunOS 4.1 for information on how to install optional software. DESCRIPTION defaultsedit is a SunView application that provides a convenient means for inspecting and setting default parameters. It can be viewed as an alternative to the traditional UNIX operating system . *rc files that con- tain initialization options for various commands. Currently, you can use defaultsedit to manipulate options to the programs indent(l), mail(l) and mailtool(l), stty(lV), and defaultsedit, as well as the menu , scrollbar, text subwindow and tty subwindow packages, and the SunView environment itself. The remaining commands are used by defaultsedit to perform conversions and other functions; they can also be invoked directly from the shell: defaults_from_input defaults_to_indentpro defaults_to_mailrc indentpro_to_defaults input_from_defaults lockscreen_default mailrc_to_defaults scrolldefaults stty_from_defaults update window-system I/O defaults from current system values update indent(l) defaults in the database from the .indentpro file update the .mailrc file from the defaults database update indent defaults from the .indent.pro file update current system values for window-system I/O from defaults data- base apply current default for lockscreen(l) display program update mail(l) and/or mailtool(l) defaults from the .mailrc file a SunView application that lets you try out different settings from the Scrollbar category interactively set terminal (TTY) options from defaults database Any program or package that a user can customize by setting or changing a parameter could be written so as to get its initialization options from the defaults database. For further information, see SunView System Programmer’ s Guide. 146 Last change: 15 February 1988 Sun Release 4.1 DEFAULTSEDIT ( 1 ) USER COMMANDS DEFAULTSEDIT ( 1 ) OPTIONS defaultsedit accepts all of the generic tool arguments discussed in sunview(l). USAGE This only applies to defaultsedit. Subwindows defaultsedit consists of four subwindows. From top to bottom they are: control Contains the name of the category currently displayed, and buttons labeled SAVE, QUIT, RESET, and EDIT ITEM. To change the category, click the LEFT mouse button on the word CATEGORY, or use the menu that pops up when you click the RIGHT mouse but- ton. message A small text subwindow where messages from defaultsedit are displayed. parameters Shows all current default parameter names with corresponding values. Clicking the LEFT mouse button over a parameter displays a help string in the message subwindow. edit A small text subwindow which enables text editing of parameter values. This is useful for very long text values, such as a long mailing list. Control Panel SAVE Save the current values that differ from the standard defaults in your private database — that is, the . defaults file in your home directory. QUIT Exit without saving any changes. RESET Reset the default parameters of the current category to the values in your private data- base. This is useful if you change some values, then change your mind and want to restore the original values. EDIT ITEM Clicking the RIGHT mouse button over the EDIT ITEM button brings up a menu with three choices: COPY ITEM, DELETE ITEM and EDIT LABEL. Only text or numeric items can be edited. Note: edits made using this menu will appear only in your private defaults database, not in the master database. The three editing operations are described below. COPY ITEM Choosing COPY ITEM will duplicate the current item. You can then edit both the label and the value of the newly created item. Only items with text or numeric values can be copied in this way. COPY ITEM is useful when you want to change the number of instances of a certain type of item — for example, to insert a new mail alias into your defaults database. DELETE ITEM Choosing DELETE ITEM will delete the current item from your private database. It can- not be permanendy deleted if the corresponding node is present in the master database. However, you can make it behave like an undefined node by giving it the special value 255Und.efined.255 . EDIT LABEL Choosing EDIT LABEL allows you to edit the label of the current item. When you choose EDIT LABEL, the label of the current item changes from bold to normal face. Then you can select the label and edit it as a normal panel text item. Note: SunView starts up faster when you set the Private_onIy parameter in the Defaults category to TRUE, in which case only your private .defaults file is read. ENVIRONMENT DEFAULTS_FILE The value of this environment variable indicates the file from which private Sun- View defaults are read. When it is undefined, defaults are read from the . defaults file in your home directory. Sun Release 4.1 Last change: 15 February 1988 147 DEFAULTSEDIT ( 1 ) USER COMMANDS DEFAULTSEDIT ( 1 ) FILES /usi7lib/defaults/*.d System-wide parameters and their standard settings. Each file is a category in defaultsedit. "/.defaults SEE ALSO indent(l), lockscreen(l), mail(l), mailtool(l), stty(lV), sunview(l) SunView User’s Guide SuriView System Programmer s Guide BUGS Editing of choice items or categories is not supported by defaultsedit. Neither is editing of the master defaults database — to add a new program to the master defaults database, you have to edit a master defaults textfile. defaultsedit reorders mail aliases that appear in the .mailrc file. This can adversely affect recursive mail aliases. To avoid this, use the source command for mail(l) to include a file containing such aliases. 148 Last change: 15 February 1988 Sun Release 4.1 DEROFF ( 1 ) USER COMMANDS DEROFF ( 1 ) NAME deroff - remove nroff, troff, tbl and eqn constructs SYNOPSIS deroff [ -w ] filename . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION deroff reads each file in sequence and removes all nroff and troff command lines, backslash constructions, macro definitions, eqn constructs (between .EQ and .EN lines or between delimiters), and table descriptions and writes the remainder on the standard output, deroff follows chains of included files (.so and .nx com- mands); if a file has already been included, a .so is ignored and a .nx terminates execution. If no input file is given, deroff reads from the standard input file. OPTIONS -w Generate a word list, one word per line. A ‘word’ is a string of letters, digits, and apostrophes, beginning with a letter; apostrophes are removed. All other characters are ignored. SEE ALSO eqn(l), nroff(l), tbl(l), troff(l) BUGS deroff is not a complete troff interpreter, so it can be confused by subtle constructs. Most errors result in too much rather than too little output. deroff does not work well with files that use .so to source in the standard macro package files. Sun Release 4.1 Last change: 21 December 1987 149 DES ( 1 ) USER COMMANDS DES ( 1 ) NAME des - encrypt or decrypt data using Data Encryption Standard SYNOPSIS des -e I -d [ -bfs ] [ -k key ] [ input-file [ output-file ] ] 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. 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, that is, if insertions or deletions are made to the encrypted file then decryption will not succeed. CBC mode also ensures that regularities in clear data do not appear in the encrypted data. ECB mode treats each 8 bytes as units of encryptions, so if parts of the encrypted file are modified then other parts may still be decrypted. Identical values of clear text encrypt to identical values of cipher text. The key used for the DES algorithm is obtained by prompting the user unless the ‘-k key ’ option is given. If the key is an argument to the des command, it is potentially visible to users executing ps(l) or a deriva- tive. To minimize this possibility, des takes care to destroy the key argument immediately upon entry. The des command attempts to use DES hardware for its job, but will use a software implementation of the DES algorithm if the hardware is unavailable. Normally, a warning message is printed if the DES hardware is unavailable since the software is only about l/50th as fast. However, the -f option will suppress the warning. The -s option may be used to force use of software instead of hardware DES. The des command reads from standard input unless input-file is specified and writes to standard output unless output-file is given. The following sections give information required to implement compatible facilities in other environments. Since the CBC and ECB modes of DES require units of 8 bytes to be encrypted, files being encrypted by the des command have 1 to 8 bytes appended to them to cause them to be a multiple of 8 bytes. The last byte, when decrypted, gives the number of bytes (0 to 7) which are to be saved of the last 8 bytes. The other bytes of those appended to the input are randomized before encryption. If, when decrypting, the last byte is not in the range of 0 to 7 then either the encrypted file has been corrupted or an incorrect key was provided for decryption and an error message is printed. The DES algorithm requires an 8 byte key whose low order bits are assumed to be odd-parity bits. The ASCH 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. OPTIONS -b Select ECB (eight bytes at a time) encryption mode. -d Decrypt data. -e Encrypt data. -f Suppress warning message when software implementation is used. -s Select software implementation for the encryption algorithm. -k key Use the encryption key specified. FILES /dev/ des? 150 Last change: 9 September 1987 Sun Release 4.1 DES(l) USER COMMANDS DES ( 1 ) SEE ALSO ps(l) BUGS It would be better to use a real 56-bit key rather than an ASCII-based 56-bit pattern. Knowing that the key was derived from ASCII radically reduces the time necessary for a brute-force cryptographic attack. RESTRICTIONS Software encryption is disabled for programs shipped outside of the U.S. The program will still be able to encrypt files if one can obtain an encryption chip, legally or otherwise. Sun Release 4.1 Last change: 9 September 1987 151 DF(1V) USER COMMANDS DF(1V) NAME df- report free disk space on file systems SYNOPSIS df [ -a ] [ -i ] [ -t type ] [filesystem ... ] [filename ... ] SYSTEM V SYNOPSIS /usr/5bin/df [ -t ] [ filesystem . . . ] [ filename . . . ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION df displays the amount of disk space occupied by currently mounted file systems, the amount of used and available space, and how much of the file system’s total capacity has been used. Used without arguments, df reports on all mounted file systems, producing something like: example % df Filesystem kbytes used avail capacity Mounted on /dev/ipOa 7445 4714 1986 70% / /dev/ipOg 42277 35291 2758 93% /usr Note: 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/ipOas or 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. SYSTEM V DESCRIPTION The System V version of df works in the same manner as above but prints only the amount of available space (in 512 byte units) and the number of free inodes. OPTIONS -a Report on all filesystems including the uninteresting ones which have zero total blocks, (that is, automounter ) -i Report the number of used and free inodes. Print if no information is available. -t type Report on filesystems of a given type (for example, nfs or 4.2). SYSTEM V OPTIONS -t Report the total allocated space figures. FILES /etc/mtab List of filesystems currently mounted. SEE ALSO du(lV), mtab(5), quot(8), tunefs(8) 152 Last change: 16 September 1989 Sun Release 4.1 DEFF(l) USER COMMANDS DIFF(l) NAME diff - display line-by-line differences between pairs of text files SYNOPSIS diff [ -bitw ] [ -c [ # ] I -e I -f I -n I -h ] filenamel filename2 diff [ -bitw ] [ -Dstring ] filenamel filename2 diff [ -bitw ] [ — c [ # ] 1 — e I — f I — n I — h ] [ — 1 ] [ — r ] [ — s ] [ -S name ] directoryl directory2 DESCRIPTION diff is a differential file comparator. When run on regular files, and when comparing text files that differ during directory comparison (see the notes below on comparing directories), diff tells what lines must be changed in the files to bring them into agreement. Except in rare circumstances, diff finds a smallest sufficient set of differences. If neither filenamel nor filename2 is a directory, either may be given as in which case the standard input is used. If filenamel is a directory, a file in that directory whose filename is the same as the filename of filename2 is used (and vice versa). There are several options for output format; the default output format contains lines of these forms: nl a n3,n4 nl ,n2 d n3 nl,n2 c n3,n4 These lines resemble ed(l) commands to convert filenamel into filename2. The numbers after the letters pertain \ofilename2. In fact, by exchanging a for d and reading backward one may ascertain equally how to convert filename2 into filenamel . As in ed(l), identical pairs, where nl = n2 or n3 = n4, 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 regu- lar file diff program as described above on text files which are different. Binary files which differ, com- mon subdirectories, and files which appear in only one directory are listed. OPTIONS -b Ignore trailing blanks (SPACE and TAB characters) and treat all other strings of blanks as equivalent. -i Ignore the case of letters; for example, ‘A’ will compare equal to ‘a’. -t Expand TAB characters in output lines. Normal or -c output adds character(s) to the front of each line which may alter the indentation of the original source lines and make the output listing difficult to interpret. This option will preserve the original source’s indentation. -w Ignore all blanks (SPACE and TAB characters); for example, ‘if ( a = = b )’ will compare equal to ‘if(a= =b)\ The following four options are mutually exclusive: -c[#] Produce a listing of differences with lines of context. The default is to present 3 lines of context and may be changed, (to 10, for example), by -clO. With -c the output format is modified slightly: output begins with identification of the files involved and their creation dates, then each change is separated by a line with a dozen * s. The lines removed from filenamel are marked with ‘- ’; those added to filename2 are marked ‘+ ’. Lines which are changed from one file to the other are marked in both files with ‘! ’. Changes which lie within lines of each other are grouped together on output. This is a change from the previous ‘diff -c’ but the resulting output is usually much easier to interpret. -e Produce a script of a, c, and d commands for the editor ed, which will recreate filename2 from filenamel . Sun Release 4.1 Last change: 2 October 1989 153 DIFF(l) USER COMMANDS DIFF(l) In connection with -e, the following shell program may help maintain multiple versions of a file. Only an ancestral file ($1) and a chain of version-to- version ed scripts ($2, $3,...) made by diff need be on hand. A ‘latest version’ appears on the standard output. (shift; cat $*; echo %$p')| ed-$l Extra commands are added to the output when comparing directories with -e, so that the result is a sh script for converting text files which are common to the two directories from their state in directory 1 to their state in directory2 . -f Produce a script similar to that of -e, not useful with ed, which is in the opposite order. -n Produce a script similar to that of -e, but in the opposite order and with a count of changed lines on each insert or delete command. -h Do a fast, half-hearted job. It works only when changed stretches are short and well 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 filenamel and filename2 on the standard output, with C preprocessor controls included so that a compilation of the result without defining string is equivalent to com- piling filenamel , while defining string will yield filename2 . Options when comparing directories are: -1 Long output format; each text file diff is piped through pr(lV) to paginate it, other differences are remembered and summarized after all text file differences are reported. -r Apply diff recursively to common subdirectories encountered. -s Report files which are the same, which are otherwise not mentioned. -S name Start a directory diff in the middle, beginning with file name. ENVIRONMENT The environment variables LC CTYPE, LANG, and LC_default control the character classification throughout diff. On entry to diff, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /tmp/d????? /usr/lib/diffh for -h SEE ALSO cc(lV), cmp(l), comm(l), cpp(l), diff3(lV), ed(l), pr(lV), locale(5), iso_8859_l(7) DIAGNOSTICS Exit status is 0 for no differences, 1 for some differences, 2 for trouble. Missing newline at end of fileY Indicates that the last line of file X did not have a NEWLINE. If the lines are different, they will be flagged and output, although the output will seem to indicate they are the same. 154 Last change: 2 October 1989 Sun Release 4.1 DIFF(l) USER COMMANDS DIFF(l) BUGS Editing scripts produced under the -e or -f option are naive about creating lines consisting of a single V. When comparing directories with the -b, -w, or -i options specified, diff first compares the files (as in cmp(l), and then runs the regular 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 or case differences. The -D option ignores existing preprocessor controls in the source files, and can generate #ifdefs’s with overlapping scope. The output should be checked by hand, or run through ‘cc -E’ (see cc(lV)) and then diffed with the original source files. Discrepancies revealed should be corrected before compilation. Sun Release 4. 1 Last change: 2 October 1989 155 DIFF3 ( IV ) USER COMMANDS DIFF3 ( IV ) NAME diffi - display line-by-line differences between 3 files SYNOPSIS diff3 [-exEX3 ]filenamel filename2 filename3 SYSTEM V SYNOPSIS /usr/5bin/diff3 [ — ex3 ] filenamel filename2 filename3 AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION diff3 compares three versions of a file, and publishes disagreeing ranges of text flagged with these codes: ==== All three files differ ====1 filenamel is different ====2 filename2 is different ====3 filename3 is different The types of differences between a given range within the given files are indicated in one of these ways: /: nl a Text is to be appended after line number nl in file/, where /= 1, 2, or 3. f:nl,n2c Text is to be changed in the range line nl to line n2. If nl = n2, the range may be abbreviated to nl . The original contents of the range follows immediately after a c indication. When the contents of two files are identical, the contents of the lower-numbered file is suppressed. OPTIONS The options to diff3 instruct it to produce a script for the editor ed, rather than a list of differences. This script will incorporate some or all of the differences between filename2 and filename3 into filenamel . This script will not include a w or q command at the end, so that it will not write out the changed file. -e Produce a script that will incorporate all changes between filename2 and filename3, that is, the changes that normally would be flagged *====’ and ‘====3’. -x Produce a script that will incorporate only changes flagged 1 ====’. -3 Produce a script that will incorporate only changes flagged ‘====3’. -E Produce a script that will incorporate all changes between filename2 and filename3 , but treat over- lapping changes (that is, changes that would be flagged with ==== in the normal listing) dif- ferently. The overlapping lines from both files will be inserted by the edit script, bracketed by ««« and »»» lines. -X Produce a script that will incorporate only changes flagged ====, but treat these changes in the manner of the -E option. 156 Last change: 9 September 1987 Sun Release 4.1 DIFF3 ( 1 V ) USER COMMANDS DIFF3( IV) For example, suppose lines 7-8 are changed in both filenamel and filename2. Applying the edit script generated by the command diff3 -E filenamel filename2 filename3 to filenamel results in the following file. lines 1-6 of filenamel <««« filenamel lines 7-8 of filenamel lines 7-8 of filename3 »»»> filename3 rest of filenamel SYSTEM V OPTIONS The System V version of diff3 does not support the -E and -X options. The script produced by the -e, -x, and -3 options does include a w and q command at the end, so that it will write out the changed file. EXAMPLES The following command will incorporate all the changes between filename2 and fi.lena.me3 into filenamel , and print the resulting file to the standard output. If the System V version of diff3, is used , filenamel will be replaced with the resulting file. (diff3 -e filenamel filename2 filename3 ; echo 'l,$p')| ed - filenamel FILES /tmp/d3????? /usr/lib/diff3 /usr/5Iib/diff3prog SEE ALSO diff(l), ed(l) BUGS Text lines that consist of a single V will defeat a -e option. Sun Release 4.1 Last change: 9 September 1987 157 DIFFMK ( 1 ) USER COMMANDS DIFFMK ( 1 ) NAME diffmk - mark differences between versions of a troff input file SYNOPSIS diffmk oldfile newfile markedfile AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION diffmk compares two versions of a file and creates a third version that includes “change mark” (.me) com- mands for nroff(l) and troff(l). oldfile and newfile are the old and new versions of the file, diffmk gen- erates markedfile , which, contains the text from newfile with troff(l) “change mark” requests (.me) inserted where newfile differs from oldfile. When markedfile is formatted, changed or inserted text is shown by | at the right margin of each line. The position of deleted text is shown by a single *. diffmk can also be used in conjunction with the proper troff requests to produce program listings with marked changes. In the following command line: diffmk old.c new.c marked.c ; nroff reqs marked.c | pr the file reqs contains the following troff requests: .pi 1 .11 77 jnf .eo .nh which eliminate page breaks, adjust the line length, set no-fill mode, ignore escape characters, and turn off hyphenation, respectively. If the characters | and * are inappropriate, you might run markedfile through sed(lV) to globally change them. SEE ALSO diff(l), nroff(l), sed(lV), troff(l) BUGS Aesthetic considerations may dictate manual adjustment of some output. File differences involving only formatting requests may produce undesirable output, that is, replacing .sp by .sp 2 will produce a “change mark” on the preceding or following line of output. 158 Last change: 18 January 1988 Sun Release 4.1 DIRCMP(IV) USER COMMANDS DIRCMP(IV) NAME dircmp - compare directories SYNOPSIS /usr/5bin/dircmp [ — d ] [ — s ] [ -w n ] dirl dirt AVAILABILITY This command is available with the System V software installation option. See Installing SunOS 4.1 for information on how to install this command. DESCRIPTION dircmp examines dirl and dirt and generates various tabulated information about the contents of the directories. Listings of files that are unique to each directory are generated for all the options. If no option is entered, a list is output indicating whether the filenames common to both directories have the same con- tents. OPTIONS -d Compare the contents of files with the same name in both directories and output a list telling what must be changed in the two files to bring them into agreement. The list format is described in diff(l). -s Suppress messages about identical files. -w/i Change the width of the output line to n characters. The default width is 72. SEE ALSO cmp(l), diff(l) Installing SunOS 4.1 Sun Release 4.1 Last change: 24 September 1987 159 DIS(l) USER COMMANDS DIS(l) NAME dis - object code disassembler for COFF SYNOPSIS dis [ -o ] [ -V ] [ -L ] [ -d sec ] [ -da sec ] [ -F function ] [ -t sec ] [ -1 string ] coff-file . . . AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION The dis command produces an assembly-language listing of cojf-file, which may be any object file in COFF format, or an archive of COFF object files. The listing includes assembly statements and an octal or hexadecimal representation of the binary that pro- duced those statements. OPTIONS -o Print numbers in octal. The default is hexadecimal. -V Print, on standard error, the version number of the disassembler being executed. -L Lookup source labels in the symbol table for subsequent printing. This option works only if the file was compiled with additional debugging information (e.g., the -g option of cc(lV)). -d sec Disassemble the named section as data, printing the offset of the data from the beginning of the section. -da sec Disassemble the named section as data, printing the actual address of the data. -F function Disassemble only the named function in each object file specified on the command line. The -F option may be specified multiple times on the command line. -t sec Disassemble the named section as text. -1 string Disassemble the library file specified by string. For example, dis -1 x -1 z disassembles libx.a and libz.a. All libraries are assumed to be in /usr/lib. If the -d, -da or -t options are specified, only those named sections from each user-supplied file name will be disassembled. Otherwise, all sections containing text will be disassembled. On output, a number enclosed in brackets at the beginning of a line, such as [5], represents that the break- pointable line number starts with the following instruction. These line numbers will be printed only if the file was compiled with additional debugging information (e.g., the -g option of cc(lV)). An expression such as <40> in the operand field or in the symbolic disassembly, following a relative displacement for control transfer instructions, is the computed address within the section to which control will be transferred. A function name will appear in the first column, followed by ( ). FILES /usr/lib SEE ALSO cc(lV) coff(5) NOTES Because the assembler does not generate or support 8-bit symbol names, it is inappropriate to make dis 8- bit clean. Seeas(l). 160 Last change: 19 February 1988 Sun Release 4.1 DOMAINNAME ( 1 ) USER COMMANDS DOMAINNAME ( 1 ) NAME domainname - set or display name of the current NIS domain SYNOPSIS domainname [ name-of-domain ] DESCRIPTION Without an argument, domainname displays the name of the current domain, which typically encompasses a group of hosts under the same administration. As such, the name of a Network Information Service (NIS) domain is normally also a valid Internet domain name, and can be used in conjunction with the send- mail(8) and the name server named(8C). Only the super-user can set the name of the domain, by giving domainname an argument; this can be done only in the startup script /etc/rc.local. SEE ALSO named(8C), sendmail(8), ypinit(8) NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. Sun Release 4.1 Last change: 16 November 1987 161 DOS ( 1 ) USER COMMANDS DOS ( 1 ) NAME dos - SunView window for IBM PC/AT applications SYNOPSIS dos [ -b ] [ -p config ] [ — q ] [ — s ] [ -update time ] [ — w ] [ — c command ] AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION A window created by dos looks and acts like the screen of an IBM PC/AT or compatible computer running MS-DOS 3.3, except that it has expanded features. It allows sharing of files with the SunOS operating sys- tem, copying and pasting data between windows, and piping and redirection. You may run any reasonable number of DOS windows simultaneously. Shrinking or expanding the window will not change the contents to accommodate the new size. USAGE Menu The menu available in the window by pressing the right mouse button allows various controls over the work in the window. Edit allows you to copy and paste between windows. The Show Screen menu item selects the type of screen display — either Hercules, CGA, or Monochrome. Use the DOS MODE command to set the corresponding DOS display mode. See the Sun386i User’ s Guide or on-line help for more infor- mation. The Mouse menu item allows you to control whether the mouse operates like a Microsoft or com- patible mouse or in normal SunView fashion (see Sun386i Advanced Skills for instructions on enabling Microsoft mouse driver software). The Send to printer menu item allows you to send queued jobs to the print spooler. Sound controls the volume of sounds from the DOS window. Device allows you to select which disks and other devices will be used and which are to be considered write only. The Reboot DOS Window item is equivalent to restarting the window. This can also be accomplished by pressing the CON- TROL, ALT, and DELETE keys simultaneously. Printer Assignments DOS uses three printer designations: LPT1, LPT2, and LPT3. The default settings are: files sent to LPT1 go to the default system printer. Files sent to LPT2 are appended to the file lpt-2 in your home directory. Epson-compatible print jobs can be sent to LPT3 to yield Epson FX-80 quality output on a Postscript printer. Drives The DOS command FORMAT A: IS works only if the current working directory contains DOS files. This is usually Drive C and sometimes Drive A. Drive A The Sun386i 3.5-inch diskette drive, used for reading PC format diskettes onto the hard disk and writing data to be stored on floppy. Drive A is not accessible across a network. Drive B An optional 5.25-inch diskette drive. Same restrictions as Drive A. Drive C A virtual disk stored in the 7pc/C: file. Files written to Drive C cannot be accessed from the SunOS operating system. Drive C is generally intended for storage of applications and copy protected software but not data. To DOS, drive C is a 20- megabyte drive. You can install copy-protected software on drive C, but not on other drives. Drives D through S Equivalents of the SunOS operating system directories. They can be accessed from either the DOS or SunOS operating systems, and can contain any number of files and other directories. The SunOS directories referenced by DOS drives other than D, H, and R (described below) are user-defined (using the DOS EXTEND command). 162 Last change: 19 February 1988 Sun Release 4.1 DOS ( 1 ) USER COMMANDS DOS ( 1 ) Drive D The current SunOS directory when the DOS window was opened. May sub- sequently be changed to any other directory. Drive H The home directory of the user who opened the window. May subsequently be changed to any directory in the user’s home directory tree. Drive R Initially equivalent to the root directory of the SunOS operating system. File Sharing between SunOS and DOS File names under DOS consist of 8 characters, a period, and a 3 character extension. When a SunOS filename does not comply with these rules, its name is modified by placing a tilde (”) in an appropriate loca- tion so that the file name conforms to DOS specifications while remaining unique. It is recommended that filenames conform to DOS requirements for files to be used in both the SunOS and DOS operating systems. Because the SunOS and DOS operating systems use different conventions for RETURN characters, dos2unix and unix2dos are provided to convert text files between the two formats. Command Sharing between SunOS and DOS The /etc/dos/unix directory contains a list of SunOS commands accessible from DOS. Other SunOS com- mands not in this list can be executed from DOS with the command ‘unix command ’. SunOS commands always use SunOS filename conventions and DOS commands always use DOS filename conventions, regardless of whether either type of command is executed from the SunOS or DOS operating system. Only DOS commands can use drives A and C. OPTIONS -b Boots (loads) DOS and opens a window using the AUTOEXEC.BAT and CONFIG.SYS files instead of 7pc/.quickpc. A DOS sign-on message is displayed in the window. -s Boot DOS and save a new .quickpc unless C:AUTOEXEC.BAT, C:CONFIG.SYS, or /etc/dos/defaults/rom has a date newer than the .quickpc file (see the -s option). -p config Loads an alternate file instead of setup.pc. -q Forces dos to read settings from the .quickpc file (as specified in setup.pc) even if C: AUTOEXEC.BAT, C:CONFIG.SYS, or /etc/dos/defaults/rom have been updated since you last typed dos -s. -s Boot DOS and save a new .quickpc file under the name specified on the SAVE line in 7pc/setup.pc. Use this option after making changes to drive C’s AUTOEXEC.BAT or CONFIG.SYS. Exits DOS after saving the .quickpc file. -update Gives you a new drive C and a new setup.pc using the settings from /etc/dos/defaults/C: and /etc/dos/defaults/setup.pc, respectively. -w Runs DOS text-only commands and applications in the current SunView Commands window. -c command Executes the given DOS command in the newly created window. If you use the -c option, -c and the command that follows it must be the last items on the command line. ENVIRONMENT DOS_LOCKING This environment variable determines which locking service is used to lock drive C for write access. If it is set to on, DOS uses the locking service on the server where the home directory is located. This locks drive C for access from any DOS window on the net- work. If it is set to off, DOS uses the local system’s locking service. This locks drive C only for access from DOS windows running on the local system. The default is on. Some servers (for example, some VAX/Ultrix systems) do not provide an NFS locking service. For home directories stored on these servers, set the variable to off to avoid an error message when a DOS window starts up. Sun Release 4. 1 Last change: 19 February 1988 163 DOS ( 1 ) USER COMMANDS DOS ( 1 ) DOS.PRINTER The value of this environment variable indicates the timeout (in seconds) for printing. A value of 20 (the default) indicates that jobs will be sent to the UNIX print spooler after 20 seconds of no printing activity from DOS to that printer. A value of 0 indicates that the spooler must be flushed manually from the menu in the window. DOSLOOKUP If on, this environment variable indicates that a command should be tried as a DOS com- mand if not recognized by the SunOS system. If DOS supports the command, a DOS window is created and the command executed in that window. If the command does not exist, the normal SunOS error message results. FILES /etc/dos/unix /etc/dos/defaults/ .quickpc /etc/dos/defaults/setup.pc /etc/dos/defaults/boards.pc /etc/dos/defaults/C: 7pc/autoexec.bat C: AUTOEXEC.BAT D: AUTOEXEC.BAT C:CONFIG.SYS '/pc/setup.pc 7pc/.quickpc 7pc/C: DIAGNOSTICS Cannot save filename quick-start file. The dos command was unable to save the specified quick-start file. Check the SAVE setting in your PC setup file (normally 7pc/setup.pc). Also check file access permissions on the specified quick-start file. Cannot load filename quick-start file. dos was unable to read the specified quick-start file. Check the SAVE setting in your setup.pc file. Also check file access permissions on the specified quick-start file. Possible software incompatibility. Unsupported 286 instruction instruction at address . Possible software incompatibility. Unsupported 386 instruction. Possible software incompatibility. Segment wrap. Possible software incompatibility. Two-byte opcode . The application you are running was written specifically for 80286 or 80386 machines. Software run from a DOS window must be compatible with 8086 systems. Files in this directory indicate which SunOS commands are accessible from DOS. Default .quickpc file copied into a user’s home PC directory (7pc) the first time a DOS window is started. Not used by DOS in this location. Default setup.pc file copied into a user’s home DOS directory (7pc) the first time a DOS window is started. Not used by DOS in this location. Stores information about IBM PC/XT/AT-compatible boards installed in your system. Default drive C file copied into a user’s home PC directory the first time a DOS window is started. Contains drive assignments, search paths, and other startup commands. Searched after C:AUTOEXEC.BAT and D: AUTOEXEC.BAT. Contains commands to access system printers and special drives. You should not need to change the AUTOEXEC.BAT on drive C. Put your changes in the AUTOEXEC.BAT on drive H (in your home directory). C:AUTOEXEC.BAT is not accessible from the SunOS system. If an AUTOEXEC.BAT file exists in the current directory, DOS tries execute faster running C:AUTOEXEC.BAT. Specifies device drivers and other system parameters. C:CONFIG.SYS is not accessible from the SunOS system. Defines printers, standard PC devices, and drive C. One or more of these files may exist, under various names which you assign. An image of DOS as last saved with dos -s, including all DOS environment variables and drivers that were in effect at that time. DOS normally reads this file at startup. A user’s personal copy of drive C. 164 Last change: 19 February 1988 Sun Release 4.1 DOS(l) USER COMMANDS DOS ( 1 ) Copying default configuration files into your home directory . This is the first time you have run the dos command. A '/pc directory is being set up, and DOS-related files are being copied into it. Another DOS window already has access to device IRQ level number is still in use by another DOS window . Your PC configuration file (normally "/pc/setup.pc) is requesting access to a physical device that another DOS window is using. Port number number out of range for board board. The port number specified in the /etc/dos/defaults/boards.pc is invalid. IRQ value number out of range for board board. The interrupt level specified in the /etc/dos/defaults/boards.pc is invalid. IRQ level number is in use by a Unix driver . There is a Unix driver servicing the board you are trying to attach to DOS. You are using the wrong IRQ level or you should use the driver instead. Interrupt level number is used by DOS to support device The interrupt level specified in the /etc/dos/defaults/boards.pc conflicts with an interrupt value currently being used by either a physical or emulated DOS device. I/O address range address-address requested for name board already in use by device . The address range specified in the /etc/dos/defaults/boards.pc conflicts with range currently being used by either a physical or emulated DOS device. Cannot share device with a hardware interrupt or DMA channel . A shared device specified in the /etc/dos/defaults/boards.pc was also assigned an interrupt level in this file. Shared devices cannot be assigned interrupt levels. Couldn’t find name board in boards.pc . A file specified in the PC setup file (normally 7pc/setup.pc) is not listed in the /etc/dos/defaults/boards.pc file. Check the setup.pc file, or add an entry for the board in boards.pc. ROM is newer than .quickpc. Rebooting programjiame . Save a new .quickpc file by issuing the command dos -s. Warning: Your personal drive C (pathname) is not protected against simultaneous access by more than one workstation. Ask your system administrator to upgrade server to use the lock manager. Until your home directory server is updated with this program, do not use programjiame when you are logged into more than one workstation. The system on the network where your drive C is stored has not protected the drive against access by DOS windows in other workstations on the network. This usually means that the server where your home directory is stored does not provide an NFS locking service. To avoid this error mes- sage, set the environment variable DOS_LOCKING to off. SEE ALSO dos2unix(l), unix2dos(l) Sun386i User’s Guide Sun386i Advanced Skills Sun MS-DOS Reference Manual Sun Release 4.1 Last change: 19 February 1988 165 D0S2UMX ( 1 ) USER COMMANDS DOS2UNIX ( 1 ) NAME dos2unix - convert text file from DOS format to ISO format SYNOPSIS dos2unix [ -ascii ] [ -iso ] [ -7 ] originalfile convertedfile AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION dos2unix converts characters in the DOS extended character set to the corresponding ISO standard charac- ters. This command can be invoked from either DOS or SunOS. However, the filenames must conform to the conventions of the environment in which the command is invoked. If the original file and the converted file are the same, dos2unix will rewrite the original file after convert- ing it. OPTIONS -ascii Removes extra carriage returns and converts end of file characters in DOS format text files to con- form to SunOS requirements. -iso This is the default. It converts characters in the DOS extended character set to the corresponding ISO standard characters. -7 Convert 8 bit DOS graphics characters to 7 bit space characters so that SunOS can read the file. DIAGNOSTICS File filename not found, or no read permission The input file you specified does not exist, or you do not have read permission (check with the SunOS Is -1 command). Bad output filename filename, or no write permission The output file you specified is either invalid, or you do not have write permission for that file or the directory that contains it. Check also that the drive or diskette is not write-protected. Error while writing to temporary file An error occurred while converting your file, possibly because there is not enough space on the current drive. Check the amount of space on the current drive using the DIR command. Also be certain that the default diskette or drive is write-enabled (not write-protected). Note that when this error occurs, the original file remains intact. Could not rename temporary file to Translated temporary file name = filename. The program could not perform the final step in converting your file. Your converted file is stored under the name indicated on the second line of this message. SEE ALSO dos(l), unix2dos(l) Sun386i Advanced Skills Sun MS-DOS Reference Manual 166 Last change: 19 February 1988 Sun Release 4.1 DU(1V) USER COMMANDS DU(1V) NAME du — display the number of disk blocks used per directory or file SYNOPSIS du [ -s ] [ -a ] [filename . . . ] SYSTEM V SYNOPSIS /usr/5bin/du [ -s ] [ -a ] [ -r ] [filename ... ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION du gives the number of kilobytes contained in all files and, recursively, directories within each specified directory or file filename. If filename is missing, V (the current directory) is used. A file which has multiple links to it is only counted once. SYSTEM V DESCRIPTION The System V version of du gives the number of 512-byte blocks rather than the number of kilobytes. OPTIONS -s Only display the grand total for each of the specified filename s. -a Generate an entry for each file. Entries are generated only for each directory in the absence of options. SYSTEM V OPTIONS -r The System V version of du is normally silent about directories that cannot be read, files that can- not be opened, etc. The -r option will cause du to generate messages in such instances. EXAMPLE Here is an example of using du in a directory. We used the pwd(l) command to identify the directory, then used du to show the usage of all the subdirectories in that directory. The grand total for the directory is the last entry in the display: % pwd /usr/ralph/misc % du 5 ./jokes 33 ./squash 44 ./tech.papers/Ipr .document 217 ./tech.papers/new.manager 401 ./tech.papers 144 ./memos 80 ./letters 388 ./window 93 ./messages 15 ./usefuLnews 1211 . % SEE ALSO df(lV), pwd(l), quot(8) BUGS Filename arguments that are not directory names are ignored, unless you use -a . If there are too many distinct linked files, du will count the excess files more than once. Sun Release 4.1 Last change: 9 September 1987 167 ECHO (IV) USER COMMANDS ECHO (IV) NAME echo - echo arguments to the standard output SYNOPSIS echo [ -n ] [ argument . . . ] SYSTEM V SYNOPSIS /usr/5bin/echo argument . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION echo writes its arguments on the standard output. Arguments must be separated by SPACE characters or TAB characters, 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 (sh(l)), you can send diagnostics to the standard error file by typing: echo . . . >&2 SYSTEM V DESCRIPTION Note: If /usr/5bin is ahead of /usr/bin in the Bourne shell’s search path, its built-in echo command mimics the System V version of echo as described here. echo also understands C -like escape conventions; beware of conflicts with the shell’s use of ‘V: \b BACKSPACE \c Print line without NEWLINE \f FORMFEED \n NEWLINE \r RETURN \t TAB \v vertical TAB \\ backslash \n the 8-bit character whose ASCII code is the 1-, 2-, 3- or 4-digit octal number n. The first digit must be zero. OPTIONS -n Do not add the NEWLINE to the output. SEE ALSO sh(l) 168 Last change: 9 September 1987 Sun Release 4.1 ED(1) USER COMMANDS ED ( 1 ) NAME ed, red - basic line editor SYNOPSIS ed [ - ] [ -sx ] [ -p string ] [filename ] red [ - ] [ -sx ] [ -p string ] [filename ] DESCRIPTION ed is the most basic line editor of the UNIX system. Although superseded by ex(l) and vi(l) for most pur- poses, ed is still used by various system utilities. ed operates on a copy of filename, called a buffer, and overwrites a file only when you issue the w (write) command, ed provides line oriented editing commands to display or change lines, to insert and delete lines from the buffer, to move or copy lines within the buffer, or to substitute character strings within lines. red is a restricted version of ed. It will only allow editing of files in the current directory, and prohibits executing commands using ! command . Attempts to bypass these restrictions result in an error message. OPTIONS -s Suppress printing of character counts (by e, r, and w commands), diagnostics (by e and q com- mands), and the ! prompt (after a ! command). Also, suppress printing the ? diagnostic before overwriting unsaved changes in the buffer. -x Edit an encrypted file (see crypt(l) for details). -p string Use string as the editing prompt in command mode. USAGE Command Structure ed commands have a simple and regular structure. They consist of an optional address, or two optional addresses separated by a comma or semicolon, then a single-character command, which may be followed by a parameter for that command: [address [ , address ]] command [parameter ] If only one address is specified, operations are performed on that line. If two addresses are specified, ed performs the operation on the inclusive range of lines. Commands that requires an address use certain addresses by default, typically the address of the current line. For example, l,10p means “print (display) lines 1 through 10” (two addresses), 5a means “append text after line 5” (one address), and d means “delete the current line” (no address with the current line used as default). The meaning of parameter varies for each operation — for the move (m) and transfer (t) opera- tions, for instance, it is the line that the addressed lines are to be moved to or transferred after. For reading (r) and writing (w) a file, parameter specifies the name of the file that is to be read or written. ed is extremely terse in its interaction with the user. Its normal response to most problems is simply a question mark (?). This may happen when ed cannot find a specified line in the buffer, or if a search for a regular expression fails in a substitute (s) command. The h command prints a somewhat more complete diagnostic for the most recent error encountered; the H command requests that the diagnostic be printed for all errors. Addresses Lines can be addressed in several ways: nnn By line number. Lines in the buffer are numbered relative to the start of the buffer. When displayed, line numbers are not physically present with the text of the file or buffer. $ The last line of the buffer. . The current line, ed keeps track of the line on which you last performed an operation. This line is called the current line . You can address this line by typing a “dot” character. Sun Release 4. 1 Last change: 2 October 1989 169 ED(1) USER COMMANDS ED ( 1 ) ±n By relative line number. Address the line number that is n lines higher, or n lines lower than the current line. 'c Address the line marked with the mark character c, which must be a lower-case letter. Lines are marked with the k command, described below. IREI An RE is a Regular Expression, described under Regular Expressions below. When enclosed by slashes, RE addresses the first line found by searching for a matching string. The search proceeds forward from the line following the current line, and wraps through the beginning of the buffer to include all preceding lines, as well as the current line. ?R£? An RE enclosed in question marks addresses the first line containing a match found by searching backward from the line preceding the current line. The search wraps through the end of the buffer to include all lines following the current line (in reverse order), as well as the current line. address±n An address followed by a plus sign (+) or a minus sign (-), followed by a decimal number, specifies that address plus or minus the indicated number of lines. (The plus sign may be omit- ted.) If the address is omitted, the current line is used as the base. For example, ‘31-3’ addresses line 28 in the buffer. address± If an address ends with *+’ or then 1 is added to or subtracted from the address, respectively. As a consequence of this rule and the previous rule, the address ’ refers to the line preceding the current line. (To maintain compatibility with earlier versions of ed, the character ‘ A ’ is equivalent to ‘-’.) Trailing V and characters have a cumulative effect, so refers to the current line, less 2. , By itself, a comma stands for the address pair ‘1,$’. ; A semicolon by itself stands for the pair By default for a given command. If you do not specify an address for a command to operate on, a command that requires an address supplies one by default. This is typically the current line. A pair of addresses separated by a comma signifies an inclusive range of lines, and the current line is not changed unless the command changes it. When addresses are separated by a semicolon, however, the current line is set to the address preceding the semicolon before any subsequent addresses are interpreted. This feature can be used to determine the starting line for forward and backward searches using 7’, and *?’. The second address of any two-address sequence must correspond to a line that occurs later in the buffer than that of the first address. Regular Expressions ed supports a limited form of regular-expression notation, which can be used in a line address to specify lines by content. A regular expression (RE) specifies a set of character strings to match against — 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 Addresses , above), and also for selecting strings to be replaced using the s (substitute) command. Where multiple matches are present in a line, a regular expression matches the longest of the leftmost matching strings. Regular expressions can be built up from the following “single-character” RE’s: c Any ordinary character not listed below. An ordinary character matches itself. \ Backslash. When followed by a special character, the RE matches the “quoted” character. A backslash followed by one of <, >, (, ), {, or }, represents an operator in a regular expression, as described below. . Dot. Matches any single character except NEWLINE. 170 Last change: 2 October 1989 Sun Release 4.1 ED(1) USER COMMANDS ED(1) As the leftmost character, a caret (or circumflex) constrains the RE to match the leftmost portion of a line. A match of this type is called an “anchored match” because it is “anchored” to a specific place in the fine. The " character loses its special meaning if it appears in any position other than the start of the RE. $ As the rightmost character, a dollar sign constrains the RE to match the rightmost portion of a line. The $ character loses its special meaning if it appears in any position other than at the end of the RE. a R£$ The construction ''RE $ constrains the RE to match the entire line. \< The sequence \< in an RE constrains the one-character RE immediately following it only to match something at the beginning of a “word”; that is, either at the beginning of a line, or just before a letter, digit, or underline and after a character not one of these. \> The sequence \> in an RE constrains the one-character RE immediately following it only to match something at the end of a “word.” [ c . . . ] A nonempty string of characters, enclosed in square brackets matches any single character in the string. For example, [abcxyz] matches any single character from the set ‘abcxyz’. When the first character of the string is a caret O, then the RE matches any character except NEWLINE and those in the remainder of the string. For example, ‘["45678]’ matches any character except ‘45678’. A caret in any other position is interpreted as an ordinary character. [ ] c . . . ] The right square bracket does not terminate the enclosed string if it is the first character (after an initial if any), in the bracketed string. In this position it is treated as an ordinary character. [ l-r ] The minus sign, between two characters, indicates a range of consecutive ASCII characters to match. For example, the range ‘[0-9]’ is equivalent to the string ‘[0123456789]’. Such a brack- eted string of characters is known as a character class. The ‘— ’ is treated as an ordinary character if it occurs first (or first after an initial ") or last in the string. d Delimiter character. The character used to delimit an RE within a command is special for that command (for example, see how / is used in the g command, below). The following rules and special characters allow for constructing RE’s from single-character RE’s: A concatenation of RE’s matches a concatenation of text strings, each of which is a match for a successive RE in the search pattern. * A single-character RE, followed by an asterisk (*) matches zero or more occurrences of the single-character RE. Such a pattern is called a closure. For example, [a-z][a-z]* matches any string of one or more lower case letters. \{m\} \{m,\} \{m,n\} A one-character RE followed by \{m\], or \{m,n\ } is an RE that matches a range of occurrences of the one-character RE. The values of m and n must be nonnegative integers less than 256; \{m\} matches exactly m occurrences; \{m,\} matches at least m occurrences; \{m,n\} matches any number of occurrences between m and «, inclusively. Whenever a choice exists, the RE matches as many occurrences as possible. \(. . A) An RE enclosed between the character sequences \( and \) matches whatever the unadorned RE matches, but saves the string matched by the enclosed RE in a numbered substring register. There can be up to nine such substrings in an RE, and parenthesis operators can be nested. Vi Match the contents of the nth substring register from the current RE. This provides a mechanism for extracting matched substrings. For example, the expression "\(..*\)\1$ matches a line consist- ing entirely of two adjacent non-null appearances of the same string. When nested parenthesized substrings are present, n is determined by counting occurrences of \( starting from the left. / / The null RE (/ /) is equivalent to the last RE encountered. Sun Release 4.1 Last change: 2 October 1989 171 ED(1) USER COMMANDS ED(1) Commands The commands a for append, c for change, and i for insert, allow you to add new text to the buffer. While accepting new text, ed is said to be in input mode. While in input mode, no commands are recognized; all character input is inserted into the buffer. To exit from input mode, enter a dot ( . ) on a line by itself; ed then reverts to command mode. Or, you can interrupt ed (typically with CTRL-C), in which case it displays a ? and returns to command mode. Commands may accept zero, one, or two addresses. Commands that accept no addresses regard the pres- ence of an address as an error. Commands that accept one or two addresses assume default addresses when too few addresses are given; if more addresses are given than such a command requires, only the last ones are used. In the following list of ed commands, the default addresses are shown in parentheses; the parenthesized addresses are not part of the command. It is generally illegal for more than one command to appear on a line. However, any command (except e, f, r, or w) may be followed by 1, n, or p in which case the current line is either listed, numbered or printed, respectively. ( ‘>a text . Append text. Add lines of text into the buffer after the addressed line. The resulting current line is the last line of input, or the addressed line if no text is entered. Address 0 is legal for this com- mand, in which case the text is placed at the beginning of the buffer. The maximum number of characters per input line (from a terminal) is 256, including the final NEWLINE. text . Change lines. Delete the addressed lines, and then accept lines of text to replace them, c accepts one or two addresses; the default is the current line. The resulting current line is the last line of input, or the line preceding the deleted lines if no text is entered. ^"'^d Delete the addressed lines from the buffer, d accepts one or two addresses; the default is the current line. The resulting current line is the line following the last one deleted; if the deleted lines were at the end of the buffer, the new last line is the resulting current line. e filename Edit a file. Delete the entire contents of the buffer, and then read in the named file. The resulting current line is the last line of the buffer, e reports the number of characters read into the buffer, and sets filename to be the current file (for use as a default filename in subsequent commands). If no filename is given, the current filename, if any, is used (see the f command, below). If filename is replaced by a shell (sh(l)) command prefaced with a T, the shell command is executed and its output is read into the buffer after the current line. Such a shell command is not used as the current filename, e displays a ? if the buffer has not been written out since the last change made — another e command in response to the ? forces the command to take effect. E filename The E command is like e, except that the editor does not check for changes to the buffer since the last w command was performed. f filename Display or set the current filename. If filename is given as an argument, the file (f) command changes the current filename to filename ; otherwise, it prints the current filename. ^ gl RE I command-list The global (g) command performs command-list on all lines in the range of addresses that match RE. ed executes command-list for each matching line in succession, setting the current line to each in turn, command-list can contain a single command, or it can be continued across input lines, with one ed command per line, by escaping all but the last NEWLINE with a \ character. Operations that place ed into input mode (a, i, and c), are permitted in command-lisf, the final V 172 Last change: 2 October 1989 Sun Release 4.1 ED ( 1 ) USER COMMANDS ED ( 1 ) terminating text input may be omitted if it is the last line of the command-list, g, G, v, and V commands, however, are not permitted. An empty command-list is equivalent to the p command. (1,$) G IRE/ The interactive G (Global) command, selects all lines that match the given RE. Then, each selected line is made current, and any one command (other than one of the a, c, i, g, G, v, and V commands) can be performed upon that line. A NEWLINE acts as a null command; an & reexe- cutes the most recent command. Commands entered during execution of the G command can address and affect lines other than the current line. The G command can be terminated by an interrupt (typically CTRL-D). h Help. Display a short error message that explains the reason for the most recent ? diagnostic. H Automatic printing of help diagnostics. Toggle between printing the ? diagnostic, or automati- cally printing diagnostic messages as well. (0 i text . Insert Text. Insert the given text into the buffer, above the addressed line, i accepts one address', the default is the current line. The resulting current line is the last line of input; if no text is input, it is the line just before the addressed line. This command differs from the a command only in the placement of the input text; Address 0 is not allowed for this command. The maximum number of characters that may be entered from a terminal is 256 per line (including the NEWLINE character). Join Lines. Remove the NEWLINE character from between the two addressed lines. The defaults are the current line and the line following. If exactly one address is given, this command does nothing. The joined line is the resulting current line. ^kc Mark the addressed line with the name c, a lower-case letter. The address-form, 'c, addresses the line marked by c. k accepts one address', the default is the current line. The current line is left unchanged. List nonprinting characters. Print the addressed lines in an unambiguous way: a few nonprinting characters, such as TAB and BACKSPACE are represented by visually mnemonic overstrikes. All other nonprinting characters are shown in octal, with long lines folded. 1 accepts one or two addresses; the default is the current line. The resulting current line is the last line printed. An 1 command may be appended to any command other than e, f, r, or w. m address Move addressed lines to just after address. Address 0 is legal, and moves the addressed line(s) to the beginning of the file. An error results if address falls within the range of lines to move, m accepts two addresses to specify a range of lines to move; the default is the current line. The resulting current line is the last of the moved lines. Number the displayed lines. Print the addressed lines, preceding each with its line number and a TAB character, n accepts one or two addresses; the default is the current line. The resulting current line is the last line printed. The n command can be appended to any command other than e, f, r, orw. Print the addressed lines, p accepts one or two addresses; the default is the current line. The resulting current line is the last line printed. The p command may be appended to any command other than e, f, r, or w. For example, dp deletes the current line and prints the new current line. Toggle prompting on or off. When prompting is in effect, the editor prompts with a * for com- mands. A subsequent P command turns prompting off. Quit. Exit from ed. Note, however, that the buffer is not automatically written out; you must write any changes to be saved with the w command; ed warns you once if you have not saved your changes (unless the option is in effect). A second q forces ed to exit regardless, destroy- ing the buffer’s contents. Last change: 2 October 1989 (”•). (•’•)] P q Sun Release 4.1 173 ED(1) USER COMMANDS ED(1) Q Force quit. This is the same as q, but you do not get any warning if you have not previously writ- ten out the buffer, ed simply exits. ^ r filename Read in the contents of filename, after the addressed line. If filename is not given, the current filename, if any, is used (see the e and f commands). The current filename is not altered; if there is no current filename, filename becomes the current filename, r accepts one address ; the default is $. Address 0 is legal for r, in which case the file is read in at the beginning of the buffer. If the read is successful, the number of characters read is typed. The resulting current line is the last line read in from the file. If filename is replaced by a shell (sh(l)) command prefaced with a !, the shell command is executed and its output is read in. Such a shell command is not remembered as the current filename. s /RElrsI slRElrs/g s iRElrs/n Substitute. Search each addressed line for the first occurrence of a string matching the specified RE, and replace it with rs, the replacement string. If g (global suffix) is appended to the com- mand, replace all (non-overlapped) matching strings in each addressed line with the replacement string rs. Note: the g suffix is distinct from the g command. If a number n is appended, replace only the n’th occurrence of the matched string on each addressed line, s accepts one or two addresses; the default is the current line. The resulting current line is the last line on which a sub- stitution is made. An error results if RE matches no strings in the addressed line or range. Any character (other than SPACE or NEWLINE can be used instead of / to delimit RE and rs. As with RE’s in addresses, you can refer to the entire string matched by RE with an ‘&’; you can refer to parenthesized substrings within RE using \1 . . . \n. When % is the only character in rs, the rs from in the most recent substitute command is used as the current rs. The % loses its special meaning when it is in a replacement string of more than one character, or if it is preceded by a backslash. A line may be split by substituting a NEWLINE character into it. The NEWLINE in the replace- ment must be escaped by preceding with an ‘V. Such substitutions cannot be done as part of a g or v command list t address Transfer. Transpose a copy of the addressed range of lines to just after the given address, t (transfer) is like m (move), except that it copies of the lines, rather than moving them, t accepts two addresses preceding the operation letter, the current address is the default. The resulting current line is the last line copied. Address 0 is allowed. u Undo. Reverse the effect of the most recent command that modified the buffer. A second u undoes the undo operation. v/REl command-list This command is the same as the global command g except that the command-list is executed with V initially set to every line that does not match the RE. (1,$) V/RE Similar to the G command, except that the lines selected are those that do not match the RE. w filename Write the addressed lines to filename. If the file does not exist, ed creates it. The current filename is not altered; if there is no current filename, then filename becomes current. If no filename is given, the current filename, if any, is used, w accepts one or two addresses; the default is all lines in the file. The current line is unchanged. If the command is successful, the number of characters written is displayed. If filename is replaced by a shell (sh(l)) command prefaced with a T, the shell command is executed with standard input taken from the addressed lines. Such a shell com- mand is not remembered as the current filename. 174 Last change: 2 October 1989 Sun Release 4.1 ED(1) USER COMMANDS ED(1) (!•$) w filename Like w, but append the addressed lines onto the named file. x Encrypt the file, ed prompts for an encryption key from the standard input. Subsequent e, r, and w commands encrypt and decrypt the text with this key (see crypt(l)). An empty key turns off encryption. Encryption can also be specified on the command line with the -x option. ^ = Display the line number of the addressed line; the current line remains unchanged. ! shell-command Run a shell command, shell-command is a (Bourne shell) command line, ed replaces the unes- caped character % with the current filename; if a ! appears as the first character of the shell com- mand, it is replaced with the text of the previous shell command. (!! repeats the last shell com- mand.) If any such expansion is performed, the expanded line is echoed. The current line is unchanged. address NEWLINE An address, alone on a line, prints the addressed line. A NEWLINE alone is equivalent to ‘.+lp’, which is useful for stepping forward through the buffer. If an interrupt signal (ASCII DEL or BREAK) is sent, ed prints a ? and returns to its command level. File Format Specification Support ed supports the fspec(5) formatting capability for displaying lines. When the first line of a file is a format specification of the form; s max:> where ts is the column number of a TAB stop and max is the maximum line length for display purposes, and with the terminal in ‘stty -tabs’ or ‘stty tab3’ mode (see stty(lV) for details), the indicated TAB stops are used in displayed lines. While inserting text, however, TAB stops are set to every eighth column. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout ed. On entry to ed, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /usr/tmp/e# temporary; # is the process number ed.hup file for saved work if the terminal is hung up SEE ALSO crypt(l), ex(l), grep(lV), sed(lV), sh(l), stty(lV), vi(l), regexp(3), fspec(5), loca!e(5), iso_8859_l(7) Editing Text Files LIMITATIONS The following limitations apply; 512 characters per line. 256 characters per global command-list. 1024 characters per filename. The limit on the number of lines depends on the amount of user memory: each line takes 1 word. When reading a file, ed discards ASCII NUL characters and all characters after the last NEWLINE. Files (such as executable images) that contain characters not in the ASCII set (bit 8 on) cannot be edited using ed. Sun Release 4.1 Last change: 2 October 1989 175 ED(1) USER COMMANDS ED ( 1 ) If a file is not terminated by a NEWLINE character, ed adds one and prints a message saying that it has done SO. If the closing delimiter of an RE or of a replacement string (such as /) would be the last character before a NEWLINE, that delimiter can be omitted, in which case the addressed line is printed. The following pairs of commands are equivalent: s/sl/s2 s/sl/s2/p g/sl g/sl/p ?sl ?sl? DIAGNOSTICS ? For command errors. 1 file '.error For an inaccessible file (use the h (help) and H (Help) commands for detailed explanations). If changes have been made in the buffer since the last w command, ed issues a warning ? when a command is given that would destroy the buffers contents. A second e or q command at this point will take effect. The ’ and -s command-line options inhibit this feature. WARNINGS A ! command cannot be subject to a g or a v command. The sequence \n in an RE does not match a NEWLINE character. Files encrypted directly with the crypt(l) command with the null key cannot be edited. The encryption facilities of ed are not available on software shipped outside the U.S. If the editor input is coming from a command file, the editor exits at the first failure of a command in that file. 176 Last change: 2 October 1989 Sun Release 4.1 EJECT ( 1 ) USER COMMANDS EJECT ( 1 ) NAME eject - eject media device from drive SYNOPSIS eject [ -dfnq ] [ device I nickname ] AVAILABILITY This command is not available on Sun 386/ systems. DESCRIPTION eject is used for those removable media devices that do not have a manual eject button. The device may be specified by its name or by a nickname; if no device is specified the default device is used. Only devices that support eject under program control respond to this command. It is not recommended to physically eject media from a device which contains mounted filesystems, eject automatically searches for any mounted filesystems which reside on the device and attempts to umount them prior to ejecting the media (see mount(8)). If the unmount operation fails, eject prints a warning message and exits. The -f flag may be used to specify an eject even if the device contains mounted parti- tions. eject can also display its default device and a list of nicknames. OPTIONS -d -f -n -q device nickname FILES /dev/rfdOc /dev/rsrO /dev/srO SEE ALSO fd(4S), sr(4S), mount(8) EXIT STATUS eject returns the following exit codes: 0 If the operation was successful or, with the -q option, the media is in the drive. 1 If the operation was unsuccessful or, with the -q option, the media is not in the drive. 2 If invalid flags were specified. 3 If an ioctl( ) request failed. DIAGNOSTICS A short help message is printed if an unknown flag is specified. A diagnostic is printed if the device name cannot be opened or does not support eject. Device Busy An attempt was made to eject a device that has a mounted filesystem. A warning message is printed when doing a forced eject of a mounted device. BUGS There should be a way to change the default on a per-user basis. Display the name of the default device to be ejected. Force the device to eject even if it is busy. Display the nickname to device name translation table. Query to see if the media is present. Specify which device to eject, by the name it appears in the directory /dev. Specify which device to eject, by its nickname as known to this command. raw files block files Sun Release 4.1 Last change: 4 December 1989 177 ENABLENUMLOCK ( 1 ) USER COMMANDS ENABLENUMLOCK ( 1 ) NAME enablenumlock, disablenumlock - enable or disable the numlock key SYNOPSIS enablenumlock disablenumlock AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION When you press the “Num Lock” key and then press one of the keys numbered R1 through R15 on the right keypad, the character on the upper part of the key is generated rather than the key’s function. In previous releases, “Num Lock” was enabled only in DOS windows and in some third-party UNIX appli- cations. Currently, “Num Lock” is enabled by default for the right keypad in all SunView windows. enablenumlock re-enables “Num Lock” for applications that expect it to be enabled. SEE ALSO Sun386i User' s Guide BUGS The default enabling of the “Num Lock” key is incompatible with some applications with special work around code to enable the “Num Lock” key. These applications require the use of disablenumlock. DOS applications are not affected. 178 Last change: 6 October 1989 Sun Release 4.1 ENV ( 1 ) USER COMMANDS ENV ( 1 ) NAME env — obtain or alter environment variables for command execution SYNOPSIS env [ — ] [ name=value . . . ] [ command ] DESCRIPTION env obtains the current environment, modifies it according to its arguments, and executes the command with the modified environment that results. If no command is specified, the resulting environment is displayed. OPTIONS - Ignore the environment that would otherwise be inherited from the current shell. Restricts the environment for command to that specified by the arguments. name=value Set the environment variable filename to value and add it to the environment. SEE ALSO sh(l), execve(2V), profil(2), environ(5V) Sun Release 4.1 Last change: 9 September 1987 179 EQN(l) USER COMMANDS EQN(l) NAME eqn, neqn, checkeq - typeset mathematics SYNOPSIS eqn [ -d xy ] [ -fn ] [ -p n ] [ -s n ] [filename ] . . . neqn [filename ] . . . checkeq [filename ] ... AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION eqn (and neqn) are language processors to assist in describing equations, eqn is a preprocessor for troff(l) and is intended for devices that can print troff’s output, neqn is a preprocessor for nroff(l) and is intended for use with terminals. Usage is almost always: example % eqn filename ... | troff example % neqn filename ... | nroff If no filenames 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 possi- ble 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 -dry Set equation delimiters set to characters r and y with the command-line argument. The more com- mon way to do this is with delimry between .EQ and .EN. The left and right delimiters may be identical. Delimiters are turned off by delim off appearing in the text. All text that is neither between delimiters nor between .EQ and .EN is passed through untouched. -fn Change font to n globally in the document. The font can also be changed globally in the body of the document by using the gfont directive. — pn Reduce subscripts and superscripts by n point sizes from the previous size. In the absence of the -p option, subscripts and superscripts are reduced by 3 point sizes from the previous size. -sn Change point size to n globally in the document. The point size can also be changed globally in the body of the document by using the gsize directive. EQN LANGUAGE Tokens within eqn are separated by braces, double quotes, tildes, circumflexes, SPACE, TAB, or NEWLINE characters. 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 O half as much. Subscripts and superscripts are produced with the keywords sub and sup. Thus ‘x sub i’ makes x i , ‘a sub i sup 2’ produces a, 2 , and ‘e sup {x sup 2 + y sup 2}’ gives e x +y . Fractions are made with over: ‘a over b’ yields a_ b' sqrt makes square roots: ‘1 over sqrt {ax sup 2 The keywords from and to introduce lower and from {n-> inf } sum from 0 to n x sub i’. +bx+c}’ results in , — sax 2 +bx+c upper limits on arbitrary things: n lim is made with iim o 180 Last change: 31 January 1990 Sun Release 4.1 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 .*1 = 1. The right clause is optional. Legal characters after 2 over alpha right ] "=T produces a 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). a Vertical piles of things are made with pile, lpile, cpile, and rpile: ‘pile {a above b above c}’ produces b. c There can be an arbitrary number of elements in a pile, lpile left-justifies, pile and cpile center, with dif- ferent vertical spacing, and rpile right justifies. Matrices are made with matrix: ‘matrix { lcol { x sub i above y sub 2 } ccol { 1 above 2 } }’ produces Xi 1 >2 2 ‘ In addition, there is rcol for a right-justified column. Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and under: ‘x dot = f(t) bar’ is x =f (0. ‘y dotdot bar '=' n under’ is y =n, and ‘x vec '=" y dyad’ is it = y. Sizes and font can be changed with size n or size ±n, roman, italic, bold, and font n. Size and fonts can be changed globally in a document by gsize n and gfont n, or by the command-line arguments -s n and -f n. Successive display arguments can be lined up. Place mark before the desired lineup point in the first equa- tion; place lineup at the place that is to line up vertically in subsequent equations. Shorthands may be defined or existing keywords redefined with define; define thing % replacement % defines a new token called thing which will be replaced by replacement whenever it appears thereafter. The % may be any character that does not occur in replacement. Keywords like sum (£), int (J), inf (=»), and shorthands like >= (>), -> ( — >), and != (*) are recognized. Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathematical words like sin, cos, and log are made Roman automatically, troff(l) four-character escapes like \(bu (#) can be used any- where. 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 tbl(l), troff(l), eqnchar(7), ms(7) Formatting Documents BUGS To embolden digits, parens, etc., it is necessary to quote them, as in ‘bold "12.3"’. Sun Release 4.1 Last change: 31 January 1990 181 ERROR ( 1 ) USER COMMANDS ERROR ( 1 ) NAME error - categorize compiler error messages, insert at responsible source file lines SYNOPSIS error [ — n ] [ — s ] [ — q ] [ — v ] [ — t suffixlist ] [ -I ignorefile ] [filename ] DESCRIPTION error analyzes error messages produced by a number of compilers and language processors. It replaces the painful, traditional methods of scribbling abbreviations of errors on paper, and permits error messages and source code to be viewed simultaneously. error looks at error messages, either from the specified file filename 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. • Inserts the error message into the source file immediately preceding the erroneous line. Error messages that 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. error is intended to be run with its standard input connected with a pipe to the error message source. Some language processors put error messages on their standard error file; others put their messages on the stan- dard output. Hence, both error sources should be piped together into error. For example, when using the csh syntax, tutorial % make -s lint | & error will analyze all the error messages produced by whatever programs make(l) runs when making lint. error knows about the error messages produced by: make(l), cc(lV), cpp(l), as(l), ld(l), lint(lV), and other compilers. For all languages except Pascal, error messages are restricted to one line. Some error messages refer to more than one line in more than one file, in which case error duplicates the error mes- sage and inserts it in all the appropriate places. 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 referring 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(l) can’t be found, try ex(l) or ed(l) from standard places. -t suffixlist 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 separated, and wildcards work. Thus the suffix list: .c.y.f*.h allows error to touch files ending with \c’, ‘.y’, \f*’ and ‘.h’. -s Print out statistics regarding the error categorization. error catches interrupt and terminate signals, and terminates in an orderly fashion. USAGE Action Statements 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. 182 Last change: 9 September 1987 Sun Release 4.1 ERROR ( 1 ) USER COMMANDS ERROR ( 1 ) Error messages from lint that refer to one of the two lint libraries, /usr/lib/lint/llib-lc and /usr/lib/lint/llib-port are discarded, to prevent accidentaly touching these libraries. Again, these error messages are consumed entirely by error. 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. 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. 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. 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 preceding 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. FILES "/.errorrc function names to ignore for lint error messages /dev/tty user’s teletype SEE ALSO as(l), cc(lV), cpp(l), csh(l), ed(l), ex(l), ld(l), lint(lV), make(l), vi(l) BUGS Opens the tty-device directly for user input. Source files with links make a new copy of the file with only one link to it. Changing a language processor’s error message format may cause error to not understand the error mes- sage. 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 | mark- ing the point of error is also disturbed by error. error was designed for work on CRT ’s at reasonably high speed. It is less pleasant on slow speed termi- nals, and has never been used on hardcopy terminals. discard nullify not file specific file specific true errors Sun Release 4.1 Last change: 9 September 1987 183 EX(1) USER COMMANDS EX ( 1 ) NAME ex, edit, e - line editor SYNOPSIS ex [ - ] [ — lLrRsvVxC ] [ -t tag ] [ +c command I -c command ] filename. . . edit [ options ] DESCRIPTION ex, a line editor, is the root of a family of editors that includes edit, ex(l), and vi(l) (the display editor). In most cases vi is preferred for interactive use. OPTIONS - I -s Suppress all interactive feedback to the user (useful for processing ex scripts in shell files). -1 Set up for editing LISP programs. -L List the names of all files saved as the result of an editor or system crash. — r Recover the indicated filenames after a system crash. -R Read only. Do not overwrite the original file. -v Start up in display editing state using vi. You can achieve the same effect by simply typing the vi command itself. -Y Verbose. Any non-tty input will be echoed on standard error. This may be useful when pro- cessing editor commands within shell scripts. -x Prompt for a key to be used in encrypting the file being edited. When used in conjunction with a pre-existing file, ex will make an educated guess to determine whether or not the input text file is already encrypted. -C Encryption option; the same as the -x option, except that all input text is assumed to have already been encrypted. This guarantees decryption in the cases where the -x option incorrectly determines that the input file is not already encrypted (this is extremely rare, and will only occur in conjunction with the use of files containing non-ASCII text). -t tag Edit the file containing the tag tag. A tags database must first be created using the ctags(l) command. +c command — c command Start the editing session by executing command. ENVIRONMENT The editor recognizes the environment variable EXINIT as a command (or list of commands separated by | characters) to run when it starts up. If this variable is undefined, the editor checks for startup commands in the file $HOME/.exrc file, which you must own. However, if there is a .exrc owned by you in the current directory, the editor takes its startup commands from this file — overriding both the file in your home directory and the environment variable. The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout ex. On entry to ex, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /usr/lib/ex?.?strings error messages /usr/lib/ex?.?recover recover command /usr/lib/ex?.?preserve preserve command 184 Last change: 18 December 1989 Sun Release 4.1 EX(1) USER COMMANDS EX ( 1 ) /etc/termcap .exrc $HOME/.exrc /tmp/Exnn/in« /tmp/Rxnnnnn /var/preserve describes capabilities of terminals editor startup file for current directory user’s editor startup file if ./.exrc is not found editor temporary file file named buffer temporary preservation directory SEE ALSO awk(l), ctags(l), ed(l), grep(lV), sed(lV), vi(l), locale(5), termcap(5), environ(5V), iso_8859_l(7) Editing Text Files BUGS 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 do not print a name if the command line option is used. There is no easy way to do a single scan ignoring case. The editor does not warn if text is placed in named buffers and not used before exiting the editor. Null characters are discarded in input files, and cannot appear in resultant files. With the modeline option in effect, the editor checks the first five lines of the text file for commands of the form ex: command : or vi: command : if any are found, the editor executes them. This can result in unexpected behavior, and is not recom- mended in any case. In earlier releases, modeline was in effect by default. Now it is not, but setting it in the .exrc file or the EXINIT environment variable can still produce untoward effects. RESTRICTIONS The encryption facilities of ex are not available on software shipped outside the U.S. Sun Release 4.1 Last change: 18 December 1989 185 EXPAND ( 1 ) USER COMMANDS EXPAND ( 1 ) NAME expand, unexpand - expand TAB characters to SPACE characters, and vice versa SYNOPSIS expand [ -tab stop ] [ -tabl , tab2 tabn ] [ filename . . . ] unexpand [ -a ] [ filename ... ] DESCRIPTION expand copies filenames (or the standard input) to the standard output, with TAB characters expanded to SPACE characters. 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 TAB characters. unexpand copies filenames (or the standard input) to the standard output, putting TAB characters back into the data. By default, only leading SPACE and TAB characters are converted to strings of tabs, but this can be overridden by the -a option (see the OPTIONS section below). OPTIONS expand —tabstop Specify as a single argument, sets TAB characters tabstop SPACE characters apart instead of the default 8. -tabl,tab2 tabn Set TAB characters at the columns specified by tabl. . . unexpand -a Insert TAB characters when replacing a run of two or more SPACE characters would produce a smaller output file. 186 Last change: 9 September 1987 Sun Release 4.1 EXPR(IV) USER COMMANDS EXPR(IV) NAME expr - evaluate arguments as a logical, arithmetic, or string expression SYNOPSIS /bin/expr argument. . . SYSTEM V SYNOPSIS /usr/5bin/expr argument. . . AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION expr evaluates expressions as specified by its arguments. After evaluation, the result is written on the stan- dard output. Each token of the expression is a separate argument, so terms of the expression must be separated by blanks. Characters special to the shell must be escaped. Note: 0 is returned to indicate a zero value, rather than the null string. Strings containing blanks or other special characters should be quoted. Integer-valued arguments may be preceded by a unary minus sign. Internally, integers are treated as 32- bit, two’s-complement numbers. The operators and keywords are listed below. Characters that need to be escaped are preceded by ‘V. The list is in order of increasing precedence, with equal precedence operators grouped within { } symbols. expr \| expr Return the first expr if it is neither NULL nor 0, otherwise returns the second expr. expr \& expr Return the first expr if neither expr is NULL or 0, otherwise returns 0. expr { =,\>, \>= , \<, \<=, != } expr Return the result of an integer comparison if both arguments are integers, otherwise returns the result of a lexical comparison. expr { +, - } expr Addition or subtraction of integer-valued arguments. expr [\*,l,% } expr Multiplication, division, or remainder of the integer-valued arguments. string : regular-expression match string regular-expression The two forms of the matching operator above are synonymous. The matching operators : and match compare the first argument with the second argument which must be a regular expression. Regular expression syntax is the same as that of ed(l), except that all patterns are “anchored” (treated as if they begin with A ) and, therefore, ' is not a special character, in that context. Nor- mally, the matching operator returns the number of characters matched (0 on failure). Alterna- tively, the \( . . .\) pattern symbols can be used to return a portion of the first argument. substr string integer-1 integer-2 Extract the substring of string starting at position integer-1 and of length integer -2 characters. If integer-1 has a value greater than the length of string , expr returns a null string. If you try to extract more characters than there are in string, expr returns all the remaining characters from string. Beware of using negative values for either integer-1 or integer-2 as expr tends to run for- ever in these cases. index string character-list Report the first position in string at which any one of the characters in character-list matches a character in string. Sun Release 4.1 Last change: 5 January 1988 187 EXPR(IV) USER COMMANDS EXPR(IV) length string Return the length (that is, the number of characters) of string. ( expr ) Parentheses may be used for grouping. SYSTEM V DESCRIPTION The operators substr, index, and length are not supported. EXAMPLES 1. a=‘expr $a + 1‘ Adds 1 to the shell variable a. 2. # ’For $a equal to either "/usr/abc/file" or just "file" ’ expr $a : \*A(.*\)’ \| $a Returns the last segment of a path name (that is, the filename part). Watch out for / alone as an argument: expr will take it as the division operator (see BUGS below). 3. # A better representation of example 2. expr //$a : ’.*A(.*\)’ The addition of the // characters eliminates any ambiguity about the division operator and simplifies the whole expression. 4. expr $VAR : Returns the number of characters in $VAR. SEE ALSO ed(l), sh(l), test(lV) EXIT CODE expr returns the following exit codes: 0 if the expression is neither null nor 0 1 if the expression is null or 0 2 for invalid expressions. DIAGNOSTICS syntax error for operator/operand errors non-numeric argument if arithmetic is attempted on such a string division by zero if an attempt to divide by zero is made BUGS After argument processing by the shell, expr cannot tell the difference between an operator and an operand except by the value. If $a is an =, the command: expr $a = ’=’ looks like: expr = = = as the arguments are passed to expr (and they will all be taken as the = operator). The following works: expr X$a = X= Note: the match, substr, length, and index operators cannot themselves be used as ordinary strings. That is, the expression: example% expr index expurgatorious length syntax error example % generates the ‘syntax error’ message as shown instead of the value 1 as you might expect. 188 Last change: 5 January 1988 Sun Release 4.1 FDFORMAT ( 1 ) USER COMMANDS FDFORMAT ( 1 ) NAME fdformat - format diskettes for use with SunOS SYNOPSIS Sun386i Systems fdformat [ -L ] [ -2 ] SPARCstation 1 and Sun-3/80 Systems fdformat [ -eflv ] [ device ] AVAILABLITY This command is available on Sun386i, SPARCstation 1 and Sun-3/80 systems only. DESCRIPTION fdformat is a utility for formatting floppy diskettes. All new blank diskettes must be formatted before they can be used, fdformat formats and verifies each track on the diskette, and terminates if it finds any bad sectors. All existing data on the diskette, if any, is destroyed by formatting. By default, fdformat formats a high density diskette with a capacity of 1.44 megabytes. Use the -L or -1 option to format low density diskettes (720K capacity). Note: it is not possible to put a low density format onto a high density floppy diskette. High density diskettes can be recognized by the high density detect hole in the lower right comer of the diskette, opposite the write protect hole in the lower left comer. The SPARCstation 1 and Sun-3/80 version of fdformat writes a SunOS label on the diskette in logical block 0 after it has been formatted. The label is required on SPARCstation 1 and Sun-3/80 systems if you intend to put a UNIX file system on the floppy diskette. On Sun386i systems, use the -2 option to format diskettes in the optional external 5 1/4" floppy drive. To format a diskette for use under MS-DOS, use the MS-DOS FORMAT command in a DOS window on the Sun386i system. OPTIONS Sun386i Systems -L Format a low density diskette. -2 Format a diskette in the optional external 5.25-inch floppy drive. SPARCstation 1 and Sun-3/80 Systems -e Eject the diskette when done. -f Force. Do not ask for confirmation before starting format. -1 Format a low density (720K) diskette. -v Verify the floppy diskette after formatting. FILES Sun386i Systems /dev/rfdOc 1.44 megabyte 3.5-inch high density diskette drive /dev/rfdlOc 720 kilobyte 3.5-inch low density diskette drive /dev/rfd2c High density 5.25-inch floppy drive /dev/rfd!2c Low density 5.25-inch floppy drive SPARCstation 1 and Sun-3/80 Systems /dev/rfdOc SEE ALSO dos(l), fd(4S) Sun Release 4.1 Last change: 4 December 1989 189 FDFORMAT ( 1 ) USER COMMANDS FDFORMAT ( 1 ) BUGS Currently bad sector mapping is not supported on floppy diskettes. Therefore, a diskette is unusable if fdformat finds an error (bad sector). 190 Last change: 4 December 1989 Sun Release 4.1 FILE ( 1 ) USER COMMANDS FILE(l) NAME file - determine the type of a file by examining its contents SYNOPSIS file [ -f ffile ] [ -cL ] [ -m mfile ] filename.. . DESCRIPTION file performs a series of tests on each filename in an attempt to determine what it contains. If the contents of a file appear to be ASCII text, file examines the first 512 bytes and tries to guess its language. file uses the file /etc/magic to identify files that have some sort of magic number, that is, any file containing a numeric or string constant that indicates its type. OPTIONS -c Check for format errors in the magic number file. For reasons of efficiency, this validation is not normally carried out. No file type-checking is done under -c. -f ffile Get a list of filenames to identify from ffile. -L If a file is a symbolic link, test the file the link references rather than the link itself. -m mfile Use mfile as the name of an alternate magic number file. EXAMPLE This example illustrates the use of file on all the files in a specific user’s directory: example % pwd /usr/blort/misc example % file * code: mc68020 demand paged executable code.c: c program text counts: ascii text doc: roff, nroff , or eqn input text empty .file: empty libz: archive random library memos: directory project: symbolic link to /usr/project script: executable shell script titles: ascii text s5.stuff: cpio archive example % ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout file. On entry to file, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification mles of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /etc/magic Sun Release 4.1 Last change: 2 October 1989 191 FILE ( 1 ) USER COMMANDS FILE ( 1 ) SEE ALSO locale(5), magic(5) BUGS file often makes mistakes. In particular, it often suggests that command files are C programs. Does not recognize Pascal or LISP. 192 Last change: 2 October 1989 Sun Release 4.1 FTND( 1 ) USER COMMANDS FIND(l) NAME find - find files by name, or by other characteristics SYNOPSIS find pathname-list expression find component DESCRIPTION find recursively descends the directory hierarchy for each pathname in the pathname-list, seeking files that match a logical expression written using the operators listed below. find does not follow symbolic links to other files or directories; it applies the selection criteria to the sym- bolic links themselves, as if they were ordinary files (see ln(l V) for a description of symbolic links). If the, fast-find, feature is enabled, find displays pathnames in which a filename component occurs. USAGE Operators In the descriptions, the argument n is used as a decimal integer where +n means more than n, -n means less than n, and n means exactly n. -fstype type True if the filesystem to which the file belongs is of type type , where type is typically 4.2 or nfs. -name filename -perm onum -prune -type c True if the filename argument matches the current file name. Shell argument syntax can be used if escaped (watch out for [, ?.and *). True if the file permission flags exactly match the octal number onum (see chmod(l V)). If onum is prefixed by a minus sign, more flag bits (017777, see chmod(lV)) become significant and the flags are compared: (flags &onum)==onum . Always yields true. Has the side effect of pruning the search tree at the file. That is, if the current path name is a directory, find will not descend into that directory. True if the type of the file is c, where c is one of: b for block special file c c for character special file d for directory f for plain file p for named pipe (FIFO) I for symbolic link s for socket -links n -user uname -nouser -group gname -nogroup -size n -inum n -atime n -mtime n True if the file has n links. True if the file belongs to the user uname. If uname is numeric and does not appear as a login name in the /etc/passwd database, it is taken as a user ID. True if the file belongs to a user not in the /etc/passwd database. True if the file belongs to group gname . If gname is numeric and does not appear as a login name in the /etc/group database, it is taken as a group ID. True if the file belongs to a group not in the /etc/group database. True if the file is n blocks long (512 bytes per block). If n is followed by a c, the size is in characters. True if the file has inode number n. True if the file has been accessed in n days. Note: the access time of directories in path-name-list is changed by find itself. True if the file has been modified in n days. Sun Release 4.1 Last change: 6 January 1989 193 FIND( 1 ) USER COMMANDS FIND ( 1 ) — ctime n True if the file has been changed in n days. “Changed” means either that the file has been modified or some attribute of the file (its owner, its group, the number of links to it, etc.) has been changed. -exec command True if the executed command returns a zero value as exit status. The end of command must be punctuated by an escaped semicolon. A command argument { } is replaced by the current pathname. -ok command Like -exec except that the generated command is written on the standard output, then the standard input is read and the command executed only upon response y. -print Always true; the current pathname is printed. -Is Always true; prints current pathname together with its associated statistics. These include (respectively) inode number, size in kilobytes (1024 bytes), protection mode, number of hard links, user, group, size in bytes, and modification time. If the file is a special file the size field will instead contain the major and minor device numbers. If the file is a symbolic link the pathname of the linked-to file is printed preceded by *->’. The format is identical to that of Is -gilds (see ls(l V)). Note: formatting is done internally, without executing the Is program. -cpio device Always true; write the current file on device in cpio(5) format (5120-byte records). -ncpio device Always true; write the current file on device in cpio -c format (5 120-byte records). -newer file True if the current file has been modified more recently than the argument filename. -xdev Always true; find does not traverse down into a file system different from the one on which current argument pathname resides. -depth Always true; find descends the directory hierarchy, acting on the entries in a directory before acting on the directory itself. This can be useful when find is used with cpio(l) to transfer files that are contained in directories without write permission. ( expression ) True if the parenthesized expression is true. Note: Parentheses are special to the shell and must be escaped. ! primary True if the primary is false (! is the unary not operator). primary 1 [ -a ] primary2 True if both primary 1 and primary2 are true. The -a is not required. It is implied by the juxtaposition of two primaries. primary 1 -oprimary2 True if either primary 1 or primary2 is true (-o is the or operator). Fast-Find The fast-find feature is enabled by the presence of the find.codes database in /usr/Iib/find. You must be root to build or update this database by running the updatedb script in that same directory. You may wish to modify the updatedb script to suit your needs. An alternate database can be specified by setting the FCODES environment variable. EXAMPLE In our local development system, we keep a file called TIMESTAMP in all the manual page directories. Here is how to find all entries that have been updated since TIMESTAMP was created: example% find /usr/share/man/man2 -newer /usr/share/man/man2/TIMESTAMP -print /usr/share/man/man2 /usr/share/man/man2/socket.2 /usr/share/man/man2/mmap.2 example% 194 Last change: 6 January 1989 Sun Release 4.1 FIND(l) USER COMMANDS FIND ( 1 ) To find all the files called intro.ms starting from the current directory: example% find . -name intro.ms -print . /manuals/assembler/intro.ms . /manuals/sun.core/intro.ms . /manuals/ driver. tut/in tro.ms ./manuals/sys.manager/uucp.impl/intro.ms ./supplements/general.works/unix.introduction/intro.ms . /supplements/programming, tools/sccs/intro. ms example % To recursively print all files names in the current directory and below, but skipping SCCS directories: example% find . -name SCCS -prune -o -print example % To recursively print all files names in the current directory and below, skipping the contents of SCCS direc- tories, but printing out the SCCS directory name: example% find . -print -name SCCS -prune example % To remove files beneath your home directory named a.out or *.o that have not been accessed for a week and that are not mounted using NFS: example % cd example % find . \( -name a.out -o -name ’*.o’ \) -atime +7 -exec rm { } \; -o -fstype nfs -prune FILES /usr/lib/find/find.codes /usr/lib/find/updatedb /usr/lib/find/code /usr/lib/find/bigram ENVIRONMENT FCODES database for fast find script to update fast-find database fast-find database utilities alternate database for fast find SEE ALSO chmod(lV), cpio(l), ln(lV), ls(lV), sh(l), test(lV), cpio(5), fs(5) Sun Release 4.1 Last change: 6 January 1989 195 FINGER ( 1 ) USER COMMANDS FINGER ( 1 ) NAME finger — display information about users SYNOPSIS finger [ options ] name . . . DESCRIPTION By default, finger displays information about each logged-in user, including his or her: login name, full name, terminal name (prepended with a if write-permission is denied), idle time, login time, and loca- tion (comment field in /etc/ttytab for users logged in locally, hostname for users logged in remotely) if known. Idle time is minutes if it is a single integer, hours and minutes if a ’ is present, or days and hours if a d is present. When one or more name arguments are given, more detailed information is given for each name specified, whether they are logged in or not. A name may be a first or last name, or an account name. Information is presented in a multi-line format, and includes, in addition to the information mentioned above: the user’s home directory and login shell the time they logged in if they are currently logged in, or the time they last logged in if they are not, as well as the terminal or host from which they logged in and, if a terminal, the comment field in /etc/ttytab for that terminal the last time they received mail, and the last time they read their mail any plan contained in the file .plan in the user’s home directory and any project on which they are working described in the file .project (also in that directory) If a name argument contains an at-sign, then a connection is attempted to the machine named after the at-sign, and the remote finger daemon is queried. The data returned by that daemon is printed. If a long format printout is to be produced, finger passes the -1 option to the remote finger daemon over the network using the /W feature of the protocol (see NAME/FINGER Protocol ). OPTIONS -m Match arguments only on user name (not first or last name). -1 Force long output format. -s Force short output format. -q Force quick output format, which is similar to short format except that only the login name, termi- nal, and login time are printed. -i Force “idle” output format, which is similar to short format except that only the login name, ter- minal, login time, and idle time are printed. -b Suppress printing the user’s home directory and shell in a long format printout. -f Suppress printing the header that is normally printed in a non-long format printout. -w Suppress printing the full name in a short format printout. -h Suppress printing of the .project file in a long format printout. -p Suppress printing of the .plan file in a long format printout. FILES /etc/utmp /etc/passwd /var/adm/lastlog /etc/ttytab "/.plan "/.project who is logged in for users’ names last login times terminal locations plans projects 196 Last change: 10 January 1988 Sun Release 4.1 FINGER ( 1 ) USER COMMANDS FINGER ( 1 ) SEE ALSO passwd(l), w(l), who(l), whois(l) Harrenstien, K„ NAMEIFINGER Protocol, 1977 December 30, RFC 742. BUGS Only the first line of the .project file is printed. Sun Release 4.1 Last change: 10 January 1988 197 FMT(l) USER COMMANDS FMT(l) NAME fmt, fmt_mail - simple text and mail-message formatters SYNOPSIS fmt [ -cs ] [ —width ] [ inputfile. . . ] fmt_mail [ -cs ] [ -width ] [ inputfile . . . ] DESCRIPTION fmt is a simple text formatter that fills and joins lines to produce output lines of (up to) the number of char- acters specified in the -width option. The default width is 72. fmt concatenates the inputfile s listed as arguments. If none are given, fmt formats text from the standard input. Blank lines are preserved in the output, as is the spacing between words, fmt does not fill lines beginning with V, for compatibility with nroff(l). Nor does it fill lines starting with ‘From:’ (but for full compatibil- ity with mail(l), use fmt_mail). Indentation is preserved in the output, and input lines with differing indentation are not joined (unless -c is used). fmt can also be used as an in-line text filter for vi(l); the vi command: !}fmt reformats the text between the cursor location and the end of the paragraph. fmt_mail is a script that formats and sends mail messages. It leaves mail header lines untouched, and runs the remainder of the message through fmt -s. The resulting message is passed along to sendmail(8), which routes it to the recipient. OPTIONS -c Crown margin mode. Preserve the indentation of the first two lines within a paragraph, and align the left margin of each subsequent line with that of the second line. This is useful for tagged para- graphs. -s Split lines only. Do not join short lines to form longer ones. This prevents sample lines of code, and other such “formatted” text, from being unduly combined. -width Fill output lines to up to width columns. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout fmt. On entry to fmt, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. SEE ALSO mail(l), nroff(l), vi(l) 198 Last change: 28 December 1987 Sun Release 4.1 FOLD ( 1 ) USER COMMANDS FOLD ( 1 ) NAME fold - fold long lines for display on an output device of a given width SYNOPSIS fold [ -width ] [ file ] DESCRIPTION Fold the contents of the specified files, or the standard input if no files are specified, breaking the lines to have maximum width width. The default for width is 80. Width should be a multiple of 8 if tabs are present, or the tabs should be expanded using expand(l) before using fold. SEE ALSO expand(l) BUGS Folding may not work correctly if underlining is present. Sun Release 4.1 Last change: 9 September 1987 199 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) NAME fontedit — a vfont screen-font editor SYNOPSIS fontedit [ generic-tool-argument ] ... [ fontjiame ] AVAILABILITY This command is available with the SunView User’s software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION fontedit is an editor for fixed-width fonts in vfont format whose characters are no taller than 24 pixels (larger characters will not fit completely onto the screen). For a description of vfont format, see vfont(5). OPTIONS generic-tool-argument fontedit accepts any generic tool argument as described in sunview(l). Otherwise, you can mani- pulate the tool using the Frame Menu. COMMANDS To edit a font, type ‘fontedit’. A fontjiame may be supplied on the command line or may be typed into the Control panel once the program has started. If it exists, the fontjiame file must be in vfont format. When the program starts, it displays a single large window containing four subwindows. From top to bot- tom, the four sub windows are: 1) The top subwindow, a message subwindow, displays messages, prompts, and warnings. 2) The second subwindow from the top, an Control panel, allows you to set global parameters for the entire font and specify operations for editing any single character. The options are: (Load) Load in the font specified in the file name field. The program will warn you if you try to read over a modified font. (Store) Store the current font onto disk with the name in file name field. (Quit) Quit the program; warns you if you have modified the font. Font name: The name of the font. Max Width and Max Height: The size, in pixels, of the largest character in the font. If you edit an existing font, these parameters are set automatically; you must set them if you are creating a new font. Changing either of these values for an existing font may alter the glyph of some charac- ters of the font. If the glyph size of a character is larger than the new max size, then that character is clipped to the new size (its bottom and right edges are moved in). However, if a glyph’s size is smaller than the new size, the glyph is left alone. Caps Height and X-Height: The distance, in pixels, between the top of a capital and lowercase letter and the baseline. When an existing font is edited, the values of Caps Height and X-Height are estimated by fontedit , and may require some adjustment. The number of pixels from the top (that is, the upper left comer) of the character to the baseline. For an existing font, the value of the largest baseline distance is used. For a new font, each character will have the same baseline distance. If this value is changed, then the baseline distance for all characters in the font will be the new value. Apply the current values of Max Width, Max Height, Caps Height, X-Height, and Baseline to the font. That is, changes made to these values do not take effect until Apply is selected. Baseline: (Apply) 200 Last change: 2 October 1989 Sun Release 4.1 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) Operation: This is a list of drawing and editing operations that you can perform on a character. For drawing, the left mouse button draws in black, and the middle draws in white. Operations are: Single Pt Press a mouse button down and a grey cell will appear; move the mouse and the cell will follow it. Releasing the button will draw. Pt Wipe Pressing a button down will draw and moving with the button down will con- tinue drawing until the button is released. Line Button down marks the end point of a line; moving with the button down rubber bands a line; releasing button draws the line. Rect Like Line except draws a rectangle. Cut Button down marks one end of rectangle, and moving rubber bands the out- line of the rectangle. Button up places the contents of the rectangle into a buffer and then “cuts” (draws in white) the rectangular region from the character. The Paste operation (below) gets the data from the buffer. Copy Like Cut except that the region is just copied; no change is made to the char- acter. Paste Button down displays a rectangle the size of the region in the buffer. Moving with the button down moves the rectangle. Button up pastes the contents of the buffer into the character. The contents of the paste buffer cannot be transferred between tools. In Copy or Cut mode, holding down the shift key while pressing the left or middle mouse button will perform a Paste action. For best results, after plac- ing a region in the buffer, press down the shift key and hold it down, then press down the mouse button. Release the mouse key to paste the region and then release the shift key. 3) The third subwindow echoes the characters in the current font as they are typed. Note that the cursor must be in this window in order to see the characters. Your character delete key will delete the echoed characters. 4) The bottom subwindow, the editing subwindow, displays eight smaller squares at its top; these are called edit buttons. The top section of each of these buttons contains a line of text in the form nnn: c, where nnn is the hexadecimal number of the character and c is the standard ASCII character corresponding to that number. In the lower section of the button the character of the current font, if it exists, is displayed. Clicking once over an editing button selects its character for editing. Just below this row of buttons is a box with the characters “0 9 A Z a z” in it. This box is called a slider. The slider allows you to scroll around in the font and select which section of the font you want displayed in the edit buttons. The black rectangle near “a” is an indicator which shows the section of the font that is displayed in the buttons above. To move the indicator, select it by pressing the left or middle mouse button down over the indicator and then move the mouse to the left or right with the button down; the indicator will slide along with the cursor. Releasing the button selects the new sec- tion of the font. A faster method of moving about in the font is to just press down and release the mouse button above the area you want without bothering to drag the indicator. Another method of scrolling through the characters of the font is to press a key on the keyboard when the cursor is in the bottom window; that character is the first one displayed in the edit buttons. EDITING CHARACTERS: To edit a character, click once over the edit button where the character is displayed. When you do this, an edit pad will appear in the bottom subwindow. Sun Release 4.1 Last change: 2 October 1989 201 FONTEDIT ( 1 ) USER COMMANDS FONTEDIT ( 1 ) The edit pad consists of an editing area bordered by scales, a proof area, and 3 command buttons. The edit- ing area is Max Width by Max Height when the pad opens, and displays a magnified view of the selected character. Black squares indicate foreground pixels. The editing area is surrounded by scales which show the current Caps Height, X-Height and Baseline in reverse video. Just outside the scales, on the top, right side, and bottom of the pad, are three small boxes with the capital letters "R", "B", and "A" in them. These boxes are movable sliders that change the right edge, bottom edge, and x-axis advance of the character respectively. In a fixed-width font, these values are usually the same for all characters; however, in a variable-width font these controls can be used to set these properties for each character. To the right of the pad is the proof area where the character is displayed at normal (that is, screen) resolu- tion and three buttons. The three buttons are: Undo Clicking the left or middle mouse button undoes the last operation. Store Stores the current representation of the character in the font. Quit Closes the edit pad. In the bottom subwindow, the right mouse button displays a menu of operations. These operations are the same as those in the control panel discussed above; you can select the current operation by either picking the operation in the control panel or by selecting the appropriate menu with the right button of the mouse. When the cursor is in the other subwindows, the right button displays the standard tool menu. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout fontedit. On entry to fontedit, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES / usr/lib/ fonts/fixedwidthfonts Sun-supplied screen fonts SEE ALSO sunview(l), vswap(l), locale(5), vfont(5), iso_8859_l(7) BUGS Results are unpredictable with variable-width fonts. The baseline should be greater than 0 or else the font cannot be read in by fontedit or by sunview(l). 202 Last change: 2 October 1989 Sun Release 4.1 FOPTION ( 1 ) USER COMMANDS FOPTION ( 1 ) NAME foption - determine available floating-point code generation options SYNOPSIS foption [ -ftype ] AVAILABILITY This command is not available for the Sun386i. DESCRIPTION foption has two uses. Called without an argument, it sends a string to standard output which is the com- piler floating-point option corresponding to the type of floating-point hardware that would be used by a program compiled with -fswitch. Exit status is undefined. This usage is intended for interactively deter- mining available floating-point hardware. On systems without floating-point hardware, the result would be example % foption soft corresponding to the compiler option -fsoft. Called with an argument which is one of the compiler floating-point options -ffpa, -f68881, -fsoft, or -fswitch, it produces no output but returns exit status 0 (true) if a program compiled with that option could execute on this machine, and status 1 (false) otherwise. Thus foption -fsoft and foption -fswitch always produce exit status 0. This usage is intended for shell scripts and Makefiles that, for instance, select dif- ferent executable files or link with different libraries according to the floating-point hardware present. foption is undefined on Sun-4 systems since there are no floating-point code generation options. OPTIONS -ftype Return exit status 0 if a program compiled -f type could execute on this machine. SEE ALSO cc(lV), fpaversion(8), mc68881version(8) Sun Release 4.1 Last change: 8 December 1987 203 FROM ( 1 ) USER COMMANDS FROM ( 1 ) NAME from - display the sender and date of newly-arrived mail messages SYNOPSIS from [ — s sender ] [ username ] DESCRIPTION from prints out the mail header lines in your mailbox file to show you who your mail is from. If username is specified, then username’s mailbox is examined instead of your own. OPTIONS -s sender Only display headers for mail sent by sender. FILES /var/spool/mail/* SEE ALSO biff(l), mail(l), old-prmail(l) 204 Last change: 9 September 1987 Sun Release 4.1 FTP(IC) USER COMMANDS FTP(IC) NAME ftp - file transfer program SYNOPSIS ftp [ -dgintv ] [ hostname ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ftp is the user interface to the ARPANET standard File Transfer Protocol (FTP), ftp transfers files to and from a remote network site. The client host with which ftp is to communicate may be specified on the command line. If this is done, ftp immediately attempts to establish a connection to an FTP server on that host; otherwise, ftp enters its command interpreter and awaits instructions from the user. When ftp is awaiting commands from the user, it displays the prompt ‘ftp>’. OPTIONS Options may be specified at the command line, or to the command interpreter. -d Enable debugging. -g Disable filename “globbing.” -i Turn off interactive prompting during multiple file transfers. -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 will prompt for the login name of the account on the remote machine (the default is the login name on the local machine), and, if necessary, prompts for a password and an account with which to login. -t Enable packet tracing (unimplemented). -v Show all responses from the remote server, as well as report on data transfer statistics. This is turned on by default if ftp is running interactively with its input coming from the user’s terminal. COMMANDS ! [ command ] Run command as a shell command on the local machine. If no command is given, invoke an interactive shell. $ macro-name [ args ] Execute the macro macro-name that was defined with the macdef command. Arguments are passed to the macro unglobbed. account [ passwd ] Supply a supplemental password required by a remote system for access to resources once a login has been successfully completed. If no argument is included, the user will be prompted for an account password in a non-echoing input mode. append local-file [ remote-file ] Append a local file to a file on the remote machine. If remote-file is left unspecified, the local file name is used in naming the remote file after being altered by any ntrans or nmap setting. File transfer uses the current settings for “representation type”, “file structure”, and “transfer mode”. Set the “representation type” to “network ASCII”. This is the default type. Sound a bell after each file transfer command is completed. Set the “representation type” to “image”. Last change: 15 January 1988 205 ascii bell binary Sun Release 4.1 FTP (1C) USER COMMANDS FTP (1C) bye Terminate the FTP session with the remote server and exit ftp. An EOF will also terminate the ses- sion and exit. case Toggle remote computer file name case mapping during mget commands. When case is on (default is off), remote computer file names with all letters in upper case are written in the local directory with the letters mapped to lower case. cd remote -dire dory Change the working directory on the remote machine to remote-directory . cdup Change the remote machine working directory to the parent of the current remote machine work- ing directory. close Terminate the FTP session with the remote server, and return to the command interpreter. Any defined macros are erased. cr Toggle RETURN stripping during “network ASCII” type file retrieval. Records are denoted by a RETURN/LINEFEED sequence during “network ASCII” type file transfer. When cr is on (the default), RETURN characters are stripped from this sequence to conform with the UNIX system single LINEFEED record delimiter. Records on non-UNIX-system remote hosts may contain single LINEFEED characters; when an “network ASCII” type transfer is made, these LINEFEED charac- ters may be distinguished from a record delimiter only when cr is off. delete remote-file Delete the file remote-file on the remote machine, debug [ debug-value ] Toggle debugging mode. If an optional debug-value is specified it is used to set the debugging level. When debugging is on, ftp prints each command sent to the remote machine, preceded by the string dir [ remote-directory ] [ local-file ] Print a listing of the directory contents in the directory, remote-directory , and, optionally, placing the output in local-file. If no directory is specified, the current working directory on the remote machine is used. If no local file is specified, or local-file is output is sent to the terminal. disconnect A synonym for close. form [ format-name ] Set the carriage control format subtype of the “representation type” to format-name . The only valid format-name is non-print, which corresponds to the default “non-print” subtype. get remote-file [ local-file ] Retrieve the remote-file and store it on the local machine. If the local file name is not specified, it is given the same name it has on the remote machine, subject to alteration by the current case, ntrans, and nmap settings. The current settings for “representation type”, “file structure”, and “transfer mode” are used while transferring the file. glob Toggle filename expansion, or “globbing”, for mdelete, mget and mput. If globbing is turned off, filenames are taken literally. Globbing for mput is done as in csh(l). For mdelete and mget, each remote file name is expanded separately on the remote machine, and the lists are not merged. Expansion of a directory name is likely to be radically different from expansion of the name of an ordinary file: the exact result depends on the remote operating system and FTP server, and can be previewed by doing ‘mis remote-files mget and mput are not meant to transfer entire directory subtrees of files. You can do this by transferring a tar(l) archive of the subtree (using a “representation type” of “image” as set by the binary command). 206 Last change: 15 January 1988 Sun Release 4.1 FTP ( 1C ) USER COMMANDS FTP ( 1C ) hash Toggle hash-sign (#) printing for each data block transferred, help [ command ] Print an informative message about the meaning of command. If no argument is given, ftp prints a list of the known commands. led [ directory \ Change the working directory on the local machine. If no directory is specified, the user’s home directory is used. Is [ remote-directory ] [ local-file ] Print an abbreviated listing of the contents of a directory on the remote machine. If remote- directory is left unspecified, the current working directory is used. If no local file is specified, or if local-file is the output is sent to the terminal. maedef macro-name Define a macro. Subsequent lines are stored as the macro macro-name ; a null line (consecutive NEWLINE characters in a file or RETURN characters from the terminal) terminates macro input mode. There is a limit of 16 macros and 4096 total characters in all defined macros. Macros remain defined until a close command is executed. The macro processor interprets *$’ and ‘V as special characters. A ‘$’ followed by a number (or numbers) is replaced by the corresponding argument on the macro invocation command line. A *$’ followed by an ‘i’ signals that macro processor that the executing macro is to be looped. On the first pass ‘$i’ is replaced by the first argument on the macro invocation command line, on the second pass it is replaced by the second argument, and so on. A ‘V followed by any character is replaced by that character. Use the ‘V to prevent special treatment of the *$’. mdelete [ remote-files ] Delete the remote-files on the remote machine. mdir remote-files local-file Like dir, except multiple remote files may be specified. If interactive prompting is on, ftp will prompt the user to verify that the last argument is indeed the target local file for receiving mdir output. mget remote-files Expand the remote-files on the remote machine and do a get for each file name thus produced. See glob for details on the filename expansion. Resulting file names will then be processed according to case, ntrans, and nmap settings. Files are transferred into the local working direc- tory, which can be changed with ‘led directory new local directories can be created with ‘! mkdir directory'. mkdir directory-name Make a directory on the remote machine. mis remote-files local-file Like ls(lV), except multiple remote files may be specified. If interactive prompting is on, ftp will prompt the user to verify that the last argument is indeed the target local file for receiving mis out- put. mode [ mode-name ] Set the “transfer mode” to mode-name. The only valid mode-name is stream, which corresponds to the default “stream” mode. mput local-files Expand wild cards in the list of local files given as arguments and do a put for each file in the resulting list. See glob for details of filename expansion. Resulting file names will then be pro- cessed according to ntrans and nmap settings. Sun Release 4.1 Last change: 15 January 1988 207 FTP(IC) USER COMMANDS FTP (1C) nmap [ inpattern outpattern ] Set or unset the filename mapping mechanism. If no arguments are specified, the filename map- ping mechanism is unset. If arguments are specified, remote filenames are mapped during mput commands and put commands issued without a specified remote target filename. If arguments are specified, local filenames are mapped during mget commands and get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX-system remote host with different file naming conventions or practices. The mapping follows the pattern set by inpattern and outpat- tern. inpattern is a template for incoming filenames (which may have already been processed according to the ntrans and case settings). Variable templating is accomplished by including the sequences $1, $2, .... $9 in inpattern. Use \ to prevent this special treatment of the $ character. All other characters are treated literally, and are used to determine the nmap inpattern variable values. For example, given inpattern $1.$2 and the remote file name mydata.data, $1 would have the value “mydata”, and $2 would have the value “data”. The outpattern determines the resulting mapped filename. The sequences $1, $2, . . . , $9 are replaced by any value resulting from the inpattern template. The sequence $0 is replaced by the original filename. Additionally, the sequence '[seql ,seq2 ]’ is replaced by seql if seql is not a null string; otherwise it is replaced by seq2 . For example, the command ‘nmap $1.$2.$3 [$l,$2].[$2,file]’ would yield the output filename myfile.data for input filenames myfile.data and myfiIe.data.oId, myfile.file for the input filename myfile, and myfile.myfile for the input filename .myfile. SPACE characters may be included in outpattern, as in the example ‘nmap $1 1 sed "s / *$//" > $1’. Use the \ character to prevent spe- cial treatment of the ‘$’, ‘[’, T and characters. ntrans [ inchars [ outchars ] ] Set or unset the filename character translation mechanism. If no arguments are specified, the filename character translation mechanism is unset. If arguments are specified, characters in remote filenames are translated during mput commands and put commands issued without a specified remote target filename, and characters in local filenames are translated during mget commands and get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX-system remote host with different file naming conventions or practices. Characters in a filename matching a character in inchars are replaced with the corresponding character in outchars. If the character’s position in inchars is longer than the length of outchars, the character is deleted from the file name. 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. By default, prompting is turned on. If prompting is turned off, any mget or mput will transfer all files, and any mdelete will delete all files. proxy ftp-command Execute an FTP command on a secondary control connection. This command allows simultaneous connection to two remote FTP servers for transferring files between the two servers. The first proxy command should be an open, to establish the secondary control connection. Enter the com- mand ‘proxy ?’ to see other FTP commands executable on the secondary connection. 208 Last change: 15 January 1988 Sun Release 4.1 FTP(IC) USER COMMANDS FTP(IC) The following commands behave differently when prefaced by proxy: open will not define new macros during the auto-login process, close will not erase existing macro definitions, get and mget transfer files from the host on the primary control connection to the host on the secondary control connection, and put, mput, and append transfer files from the host on the secondary control con- nection to the host on the primary control connection. Third party file transfers depend upon support of the PASV command by the server on the secon- dary control connection. 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 after processing according to any ntrans or nmap settings in naming the remote file. File transfer uses the current settings for “representation type”, “file structure”, and “transfer mode”. pwd Print the name of the current working directory on the remote machine. quit A synonym for bye. quote argl arg2 . . . Send the arguments specified, verbatim, to the remote FTP server. A single FTP reply code is expected in return. recv remote-file [ local-file ] A synonym for get. remotehelp [ command-name ] Request help from the remote FTP server. If a command-name is specified it is supplied to the server as well. rename from to Rename the Ole from on the remote machine to have the name to. reset Clear reply queue. This command re-synchronizes command/reply sequencing with the remote FTP server. Resynchronization may be necessary following a violation of the FTP protocol by the remote server. rmdir directory-name Delete a directory on the remote machine. runique Toggle storing of files on the local system with unique filenames. If a file already exists with a name equal to the target local filename for a get or mget command, a ‘.1’ is appended to the name. If the resulting name matches another existing file, a ‘.2’ is appended to the original name. If this process continues up to ‘.99’, an error message is printed, and the transfer does not take place. The generated unique filename will be reported. Note: runique will not affect local files generated from a shell command (see below). The default value is off. send local-file [ remote-file ] A synonym for put. sendport Toggle the use of PORT commands. By default, ftp will attempt to use a PORT command when establishing a connection for each data transfer. The use of PORT commands can prevent delays when performing multiple file transfers. If the PORT command fails, ftp will use the default data port. When the use of PORT commands is disabled, no attempt will be made to use PORT com- mands for each data transfer. This is useful when connected to certain FTP implementations that ignore PORT commands but incorrectly indicate they have been accepted. status Show the current status of ftp. Sun Release 4.1 Last change: 15 January 1988 209 FTP(IC) USER COMMANDS FTP (1C) struct [ struct-name ] Set the “file structure” to struct-name. The only valid struct-name is file, which corresponds to the default “file” structure. sunique Toggle storing of files on remote machine under unique file names. The remote FTP server must support the STOU command for successful completion. The remote server will report the unique name. Default value is off. tenex Set the “representation type” to that needed to talk to TENEX machines, trace Toggle packet tracing (unimplemented), type [ type-name ] Set the “representation type” to type-name. The valid type-names are ascii for “network ASCII”, binary or image for “image”, and tenex for “local byte size” with a byte size of 8 (used to talk to TENEX machines). If no type is specified, the current type is printed. The default type is “net- work ASCH”. 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. If an account field is specified, an account command will be relayed to the remote server after the login sequence is completed if the remote server did not require it for logging in. 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 mode is on, when a file transfer completes, statistics regarding the efficiency of the transfer are reported. By default, verbose mode is on if ftp’s commands are com- ing from a terminal, and off otherwise. ? [ command ] A synonym for help. Command arguments which have embedded spaces may be quoted with quote (") marks. If any command argument which is not indicated as being optional is not specified, ftp will prompt for that argument. ABORTING A FILE TRANSFER To abort a file transfer, use the terminal interrupt key (usually CTRL-C). Sending transfers will be immedi- ately halted. Receiving transfers will be halted by sending a ftp protocol ABOR command to the remote server, and discarding any further data received. The speed at which this is accomplished depends upon the remote server’s support for ABOR processing. If the remote server does not support the ABOR com- mand, an “ftp>” prompt will not appear until the remote server has completed sending the requested file. The terminal interrupt key sequence will be ignored when ftp has completed any local processing and is awaiting a reply from the remote server. A long delay in this mode may result from the ABOR processing described above, or from unexpected behavior by the remote server, including violations of the ftp proto- col. If the delay results from unexpected remote server behavior, the local ftp program must be killed by hand. FILE NAMING CONVENTIONS Local files specified as arguments to ftp commands are processed according to the following rules. 1) If the file name -’ is specified, the standard input (for reading) or standard output (for writing) is used. 210 Last change: 15 January 1988 Sun Release 4.1 FTP(IC) USER COMMANDS FTP (1C) 2) If the first character of the file name is *|\ the remainder of the argument is interpreted as a shell command, ftp then forks a shell, using popen(3S) with the argument supplied, and reads (writes) from the standard output (standard input) of that shell. If the shell command includes SPACE characters, the argument must be quoted; for example ‘"| Is -It"’. A particularly useful example of this mechanism is: ‘dir | more’. 3) Failing the above checks, if “globbing” is enabled, local file names are expanded according to the rules used in the csh(l); see the glob command. If the ftp command expects a single local file (for example, put), only the first filename generated by the “globbing” operation is used. 4) For mget commands and get commands with unspecified local file names, the local filename is the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting filename may then be altered if runique is on. 5) For mput commands and put commands with unspecified remote file names, the remote filename is the local filename, which may be altered by a ntrans or nmap setting. The resulting filename may then be altered by the remote server if sunique is on. FILE TRANSFER PARAMETERS The FTP specification specifies many parameters which may affect a file transfer. The “representation type” may be one of “network ASCII”, “EBCDIC”, “image”, or “local byte size” with a specified byte size (for PDP-lO’s and PDP-20’s mostly). The “network ASCII” and “EBCDIC” types have a further subtype which specifies whether vertical format control (NEWLINE characters, form feeds, etc.) are to be passed through (“non-print”), provided in TELNET format (“TELNET format controls”), or provided in ASA (FORTRAN) (“carriage control (ASA)”) format, ftp supports the “network ASCII” (subtype “non- print” only) and “image” types, plus “local byte size” with a byte size of 8 for communicating with TENEX machines. The “file structure” may be one of “file” (no record structure), “record”, or “page”, ftp supports only the default value, which is “file”. The “transfer mode” may be one of “stream”, “block”, or “compressed”, ftp supports only the default value, which is “stream”. SEE ALSO csh(l), Is(lV), rcp(lC), tar(l), popen(3S), netrc(5), ftpd(8C) BUGS Correct execution of many commands depends upon proper behavior by the remote server. An error in the treatment of carriage returns in the 4.2 BSD code handling transfers with a “representation type” of “network ASCII” has been corrected. This correction may result in incorrect transfers of binary files to and from 4.2 BSD servers using a “representation type” of “network ASCII”. Avoid this problem by using the “image” type. Sun Release 4.1 Last change; 15 January 1988 211 GCORE ( 1 ) USER COMMANDS GCORE ( 1 ) NAME gcore - get core images of running processes SYNOPSIS gcore [ — o filename ] process-id. . . . DESCRIPTION gcore creates a core image of each specified process. Such an image can be used with adb(l) or dbx(l). The name of the core image file for the process whose process ID is process-id will be cor e.process-id. OPTIONS -o filename Substitute filename in place of core as the first part of the name of the core image files. FILES cor e.process-id core images SEE ALSO adb(l), csh(l), dbx(l), kill(l), ptrace(2) 212 Last change: 26 February 1988 Sun Release 4.1 GETOPT (IV) USER COMMANDS GETOPT (IV) NAME getopt — parse command options in shell scripts SYNOPSIS set — ‘getopt opstring $*‘ set argv = (‘getopt opstring $*‘) AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION getopt breaks up options in command lines for easy parsing by shell scripts, and checks for legal options. optstring is a string of option letters to recognize, (see getopt(3)). If a letter is followed by a colon, the option is expected to have an argument — which may or may not be separated by white space. (The ‘ — ’ following set indicates that the Bourne shell is to pass arguments beginning with a dash as parameters to the script.) If ’ appears on the command line that invokes the script, getopt uses it to delimit the end of options it is to parse (see example below). If used explicitly, getopt will recognize it; otherwise, getopt will generate it at the first argument it encounters that has no In either case, getopt places it at the end of the options. The positional parameters ($1 $2. . . ) of the shell are reset so that each option in optstring is broken out and preceded by a along with the argument (if any) for each. EXAMPLE The following code fragment shows how one might process the arguments for a command that can take the options a or b, as well as the option o, which requires an argument: #! /usr/bin/sh set --getopt abo: $*‘ if [ $? != 0 ] then echo $USAGE exit 2 fi for i in $* do case $i in -a | -b) FLAG =$i; shift;; -o) OARG =$2; shift 2;; — ) shift; break;; esac done This code will accept any of the following command lines as equivalent: cmd -a -o arg fl f2 cmd -aoarg fl f2 cmd -oarg -a fl f2 cmd -a -oarg — fl f2 SEE ALSO csh(l), getopts(l), sh(l), getopt(3) DIAGNOSTICS getopt prints an error message on the standard error when it encounters an option letter not included in opt- string. Sun Release 4.1 Last change: 17 September 1989 213 GETOPT ( 1 V ) USER COMMANDS GETOPT(IV) NOTES getopts(l) is preferred. 214 Last change: 17 September 1989 Sun Release 4.1 GETOPTS ( 1 ) USER COMMANDS GETOPTS ( 1 ) NAME getopts, getoptcvt — parse command options in shell scripts SYNOPSIS getopts optstring name [ argument. . . ] getoptcvt [ -b ] filename DESCRIPTION getopts is used by shell procedures to parse positional parameters and to check for legal options. It should be used in place of the getopt(lV) command. It supports the following command syntax rules: © Option names must be one character long. ® All options must be preceded by © Options with no arguments may be grouped after a single • Option-arguments cannot be optional. ® All options must precede operands on the command line. • ‘ — ’ may be used to indicate the end of the options. optstring must contain the option letters the command using getopts will recognize; if a letter is followed by a colon, the option is expected to have an argument, or group of arguments, which must be separated from it by white space. Each time it is invoked, getopts will place the next option in the shell variable name and the index of the next argument to be processed in the shell variable OPTIND. Whenever the shell or a shell procedure is invoked, OPTIND is initialized to 1. When an option requires an option-argument, getopts places it in the shell variable OPTARG. If an illegal option is encountered, ? will be placed in name . When the end of options is encountered, getopts exits with a non-zero exit status. The special option ‘ — ’ may be used to delimit the end of the options. By default, getopts parses the positional parameters. If extra arguments ( argument . . .) are given on the getopts command line, getopts will parse them instead. getoptcvt reads the shell script in filename, converts it to use getopts instead of getopt, and writes the results on the standard output. OPTIONS getoptcvt -b Generate a script that will be portable to earlier releases of the UNIX system. The script will determine at run time whether to invoke getopts or getopt. Sun Release 4.1 Last change: 7 September 1989 215 GETOPTS ( 1 ) USER COMMANDS GETOPTS ( 1 ) EXAMPLE The following fragment of a shell program shows how one might process the arguments for a command that can take the options a or b, as well as the option o, which requires an option-argument: while getopts abo: c do case $c in a| b) FLAG=$c;; o) OARG=$OPTARG;; \?) echo $USAGE esac exit 2;; done shift ‘expr $OPTIND - 1 ( This code will accept any of the following as equivalent: cmd -a -b -o "xxx z yy" filename cmd —a — b -o "xxx z yy" — filename cmd -ab -o xxx,z,yy filename cmd -ab -o "xxx z yy" filename cmd -o xxx,z,yy -b -a filename SEE ALSO getopt(lV), sh(l), getopt(3) WARNING Changing the value of the shell variable OPTIND or parsing different sets of arguments may lead to unex- pected results. DIAGNOSTICS getopts prints an error message on the standard error when it encounters an option letter not included in opt string. 216 Last change: 7 September 1989 Sun Release 4.1 GET_SELECTI0N(1) USER COMMANDS GET_SELECTION ( 1 ) NAME get_selection - copy the contents of a SunView selection to the standard output SYNOPSIS get_selection [ rank ] [ t seconds ] [ D ] AVAILABILITY This command is available with the SunView User's software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION get_selection prints the contents of the indicated selection on standard out. A selection is a collection of objects (for instance, characters) picked with the mouse in the SunView window system. OPTIONS rank Indicate which selection is to be printed: 1: primary; 2: secondary; 3: clipboard. The default is primary. t seconds Indicate how many seconds to wait for the holder of a selection to respond to a request before giving up. The default is 6 seconds. D Debugging. Inquire through a special debugging service for the selection, rather than accessing the standard service. Useful only for debugging window applications which are clients of the selection library. EXAMPLE The following line in a SunView root menu file provides a menu command to print the primary selection on the user’s default printer: “Print It” sh -c get_selection | ipr SEE ALSO SunView User's Guide Sun Release 4.1 Last change: 21 December 1987 217 GFXTOOL ( 1 ) USER COMMANDS GFXTOOL ( 1 ) NAME gfxtool - run graphics programs in a Sun View window SYNOPSIS gfxtool [ -C ] [ program [ arguments ] ] AVAILABILITY This command is available with the SunView User's software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION gfxtool is a standard tool provided with the SunView environment. It runs graphics programs that do not overwrite the terminal emulator from which they run. gfxtool has two subwindows: a terminal subwindow and an empty subwindow. The terminal subwindow contains a running shell, just like the shelltool (see shelltool(l)). Programs invoked in the terminal subwin- dow can run in the empty subwindow. You can move the boundary between these two subwindows as described in sunview(l). If you wish, you can make gfxtool your console by entering -C as the first argu- ment. Normally you can use the mouse and keyboard anywhere in the empty subwindow to access frame func- tions. 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 Frame Menu from the tool boundaries or frame header. gfxtool also accepts all of the generic tool arguments; see sunview(l) for a list of these arguments. If a program argument is present, gfxtool runs it. If there are no arguments, gfxtool runs the program corresponding to your SHELL environment variable. If this environment variable is not available, then gfxtool runs sh(l). OPTIONS -C Redirect system console output to this instance of gfxtool. FILES "/.ttyswrc /usr/demo/* SEE ALSO sh(l), shelltool(l), sunview(l), graphics_demos(6) 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 Frame Menu; the ‘TTY Hung?’ submenu there has one item, ‘Flush input’, that you can invoke to correct the problem. 218 Last change: 21 December 1987 Sun Release 4.1 GPROF(l) USER COMMANDS GPROF(l) NAME gprof - display call-graph profile data SYNOPSIS gprof [ -abcsz ] [ -e function-name ] [ -E function-name ] [ -f function-name ] [ -F function-name ] [ image-file [ profile-file . . . ] ] DESCRIPTION gprof produces an execution profile of a program. The effect of called routines is incorporated in the profile of each caller. The profile data is taken from the call graph profile file which is created by programs compiled with the -pg option of cc(lV) and other compilers. That option also links in versions of the library routines which are compiled for profiling. The symbol table in the executable image file image-file (a.out by default) is read and correlated with the call graph profile file profile-file (gmon.out by default). If more than one profile file is specified, the gprof output shows the sum of the profile information in the given profile files. First, execution times for each routines 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. The first listing shows the func- tions sorted according to the time they represent, including the time of their call graph descendants. Below each function entry is shown its (direct) call-graph children, and how their times are propagated to this function. A similar display above the function shows how this function’s time and the time of its descen- dants 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. Next, a flat profile is given, similar to that provided by prof(l). This listing gives the total execution times and call counts for each of the functions in the program, sorted by decreasing time. Finally, an index show- ing the correspondence between function names and call-graph profile index numbers. A single function may be split into subfunctions for profiling by means of the MARK macro (see prof(3)). 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(2V) or return normally for the profiling information to be saved in the gmon.out file. OPTIONS -a Suppress printing statically declared functions. If this option is given, all relevant information about the static function (for instance, time samples, calls to other functions, calls from other func- tions) belongs to the function loaded just before the static function in the a.out file. -b Brief. Suppress descriptions 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. -s Produce a profile file gmon.sum which represents the sum of the profile information in all the specified profile files. This summary profile file may be given to subsequent executions of gprof (probably also with a -s) option to accumulate profile data across several runs of an a.out file. -z 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. -e function-name Suppress printing the graph profile entry for routine function-name and all its descendants (unless they have other ancestors that are not suppressed). More than one -e option may be given. Only on & function-name may be given with each -e option. Sun Release 4.1 Last change: 22 December 1987 219 GPROF(l) USER COMMANDS GPROF(l) -E function-name Suppress printing the graph profile entry for routine function-name (and its descendants) as — e, above, and also exclude the time spent in function-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. -f function-name Print the graph profile entry only for routine function-name and its descendants. More than one -f option may be given. Only one function-name may be given with each -f option. -F function-name Print the graph profile entry only for routine function-name and its descendants (as -f, above) and also use only the times of the printed routines in total time and percentage computations. More than one -F option may be given. Only one function-name may be given with each -F option. The -F option overrides the -E option. ENVIRONMENT PROFDIR If this environment variable contains a value, place profiling output within that directory, in a file named pid.programname. pid is the process ID, and programname is the name of the program being profiled, as determined by removing any path prefix from the argv[0] with which the pro- gram was called. If the variable contains a NULL value, no profiling output is produced. Other- wise, profiling output is placed in the file gmon.out. FILES a.out executable file containing namelist gmon.out dynamic call-graph and profile gmon.sum summarized dynamic call-graph and profile $PROFDIR /pid.programname SEE ALSO cc(lV), prof(l), tcov(l), exit(2V), profil(2), monitor(3), prof(3) Graham, S.L., Kessler, P.B., McKusick, M.K., ‘ gprof A Call Graph Execution Profiler ’, Proceedings of the SIGPLAN ’82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No. 6, pp. 120-126, June 1982. BUGS Parents which are not themselves profiled will have the time of their profiled children propagated to them, but they will appear to be spontaneously invoked in the call-graph listing, and will not have their time pro- pagated further. Similarly, signal catchers, even though profiled, will appear to be spontaneous (although for more obscure reasons). Any profiled children of signal catchers should have their times propagated properly, unless the signal catcher was invoked during the execution of the profiling routine, in which case all is lost. 220 Last change: 22 December 1987 Sun Release 4.1 GRAPH (1G) USER COMMANDS GRAPH (1G) 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 ] ] ] [ -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 abscissaes and ordinates of a graph. Successive points are connected by straight lines. The standard output from graph contains plotting instructions (see plot(5)) suitable for input to plot(lG) or to the command Ipr -g (see lpr(l)). 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 NEWLINE characters. 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. If a specified lower limit exceeds the upper limit, the axis is reversed. -a spacing [ start ] Supply abscissaes automatically (they are missing from the input); spacing is the spacing (default 1). start is the starting point for automatic abscissaes (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 Mode (style) of connecting lines: 0 disconnected, 1 connected (default). Some dev- ices give distinguishable line styles for other small integers. -s Save screen, do not erase before plotting. -x [ 1 ] lower [ upper [ spacing ] ] If 1 is present, x axis is logarithmic, lower and upper are lower (and upper) x limits. spacing, if present, is grid spacing on x axis. Normally these quantities are deter- mined automatically. -y [ 1 ] lower [ upper [ spacing ] ] If 1 is present, y axis is logarithmic, lower and upper are lower (and upper) y limits. spacing, if present, is grid spacing on y axis. Normally these quantities are deter- mined automatically. -h fraction fraction of space for height. -w fraction fraction of space for width. -r fraction fraction of space to move right before plotting. -u fraction fraction of space to move up before plotting. -t Transpose horizontal and vertical axes. Option -x now applies to the vertical axis. SEE ALSO lpr(l), plot(lG), spline(lG) Sun Release 4.1 Last change: 9 September 1987 221 GRAPH (1G) USER COMMANDS GRAPH (1G) BUGS graph stores all points internally and drops those for which there is no room. Segments that run out of bounds are dropped, not windowed. Logarithmic axes may not be reversed. 222 Last change: 9 September 1987 Sun Release 4.1 GREP(IV) USER COMMANDS GREP(IV) NAME grep, egrep, fgrep - search a file for a string or regular expression SYNOPSIS grep [ -bchilnsvw ] [ -e expression ] [filename.. . ] egrep [ -bchilnsv ] [ -e expression ] [ -f filename ] [ expression ] [filename.. . ] fgrep [ -bchilnsvx ] [ -e string ] [ -f filename ] [ string ] [filename.. . ] SYSTEM V SYNOPSIS /usr/5bin/grep [ -bchilnsvw ] [ -e expression ] [filename. . . ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Commands of the grep family search the input filenames (the standard input default) for lines matching a pattern. Normally, each line found is copied to the standard output, grep patterns are limited regular expressions in the style of ed(l). egrep patterns are full regular expressions including alternation, 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 ‘$\ [, T. *(’> T, and ‘V in the expression, as these characters are also meaningful to the shell. It is safest to enclose the entire expression argument in single quotes 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 -b Precede each line by the block number on which it was found. This is sometimes useful in locat- ing disk block numbers by context. -c Display a count of matching lines rather than displaying the lines which match. -h Do not display filenames. -i Ignore the case of letters in making comparisons — that is, upper and lower case are considered identical. -1 List only the names of files with matching lines (once) separated by NEWLINE characters. — n Precede each line by its relative line number in the file. -s Work silently, that is, display nothing except error messages. This is useful for checking the error status. -v Invert the search to only display lines that do not match. -w Search for the expression as a word as if surrounded by \< and \>. This applies to grep only. -x Display only those lines which match exactly — that is, only lines which match in their entirety. This applies to fgrep only. -e expression Same as a simple expression argument, but useful when the expression begins with a -e string For fgrep the argument is a literal character string. -f filename Take the regular expression (egrep) or a list of strings separated by NEWLINE (fgrep) from filename . Sun Release 4.1 Last change: 30 November 1988 223 GREP(IV) USER COMMANDS GREP(IV) SYSTEM V OPTIONS The -s option to grep indicates that error messages for nonexistent or unreadable files should be suppressed, not that all messages except for error messages should be suppressed. REGULAR EXPRESSIONS The following one-character regular expressions match a single character: c An ordinary character ( not one of the special characters discussed below) is a one-character regu- lar expression that matches that character. \c A backslash (\) followed by any special character is a one-character regular expression that matches the special character itself. The special characters are: • V, ‘[\ and ‘V (period, asterisk, left square bracket, and backslash, respec- tively), which are always special, except when they appear within square brack- ets ([ ]). • ,A ’ (caret or circumflex), which is special at the beginning of an entire regular expression, or when it immediately follows the left of a pair of square brackets (□)• • $ (currency symbol), which is special at the end of an entire regular expression. A backslash followed by one of “<’, V, ‘(\ ‘)\ T, or ‘}\ represents a special operator in the regular expression; see below. . A V (period) is a one-character regular expression that matches any character except NEWLINE. [ string ] A non-empty string of characters enclosed in square brackets is a one-character regular expression that matches any one character in that string. If, however, the first character of the string is a ,A ’ (a circumflex or caret), the one-character regular expression matches any character except NEW- LINE and the remaining characters in the string. The ,A ’ has this special meaning only if it occurs first in the string. The (minus) may be used to indicate a range of consecutive ASCII charac- ters; for example, [0-9] is equivalent to [0123456789]. The loses this special meaning if it occurs first (after an initial ,A ’, if any) or last in the string. The *]’ (right square bracket) does not terminate such a string when it is the first character within it (after an initial ‘ A ’, if any); that is, [ ]a-f] matches either *]’ (a right square bracket ) or one of the letters a through f inclusive. The four characters V, ‘[ ’, and ‘V stand for themselves within such a string of characters. The following rules may be used to construct regular expressions: * A one-character regular expression followed by (an asterisk) is a regular expression that matches zero or more occurrences of the one-character regular expression. If there is any choice, the longest leftmost string that permits a match is chosen. \(and\) A regular expression enclosed between the character sequences \( and \) matches whatever the unadorned regular expression matches. This applies only to grep. \n The expression \n matches the same string of characters as was matched by an expression enclosed between \( and \) earlier in the same regular expression. Here n is a digit; the sub- expression specified is that beginning with the nth occurrence of \( counting from the left. For example, the expression %*\)\1$ matches a line consisting of two repeated appearances of the same string. Concatenation The concatenation of regular expressions is a regular expression that matches the concatenation of the strings matched by each component of the regular expression. \< The sequence \< in a regular expression constrains the one-character regular expression immedi- ately following it only to match something at the beginning of a “word”; that is, either at the beginning of a line, or just before a letter, digit, or underline and after a character not one of these. 224 Last change: 30 November 1988 Sun Release 4.1 GREP(IV) USER COMMANDS GREP(IV) \> The sequence \> in a regular expression constrains the one-character regular expression immedi- ately following it only to match something at the end of a “word”; that is, either at the end of a line, or just before a character which is neither a letter, digit, nor underline. \0n\} \{m,n\} A regular expression followed by \{m\}, or \{m,n\) matches a range of occurrences of the regular expression. The values of m and n must be non-negative integers less than 256; \{m\} matches exactly m occurrences; \{m,\) matches at least m occurrences; \{m,n\} matches any number of occurrences between m and n inclusive. Whenever a choice exists, the regular expres- sion matches as many occurrences as possible. A circumflex or caret (*) at the beginning of an entire regular expression constrains that regular expression to match an initial segment of a line. $ A currency symbol ($) at the end of an entire regular expression constrains that regular expression to match a final segment of a line. The construction example % * entire regular expression $ constrains the entire regular expression to match the entire line. egrep accepts regular expressions of the same sort grep does, except for \(, \), W, \<, \>, \{, and \}, with the addition of: * A regular expression (not just a one-character regular expression) followed by (an asterisk) is a regular expression that matches zero or more occurrences of the one-character regular expression. If there is any choice, the longest left- most string that permits a match is chosen. + A regular expression followed by *+’ (a plus sign) is a regular expression that matches one or more occurrences of the one-character regular expression. If there is any choice, the longest leftmost string that permits a match is chosen. ? A regular expression followed by *?’ (a question mark) is a regular expression that matches zero or one occurrences of the one-character regular expression. If there is any choice, the longest leftmost string that permits a match is chosen. | Alternation: two regular expressions separated by T or NEWLINE match either a match for the first or a match for the second. () 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 V *?’ (closures), then concatenation, then *|’ (alternation)and NEWLINE. EXAMPLES Search a file for a fixed string using fgrep: example% fgrep intro /usr/share/man/man3/*.3* Look for character classes using grep: example% grep ’[1-8]([CJMSNX])’ /usr/share/man/manl/*.l Look for alternative patterns using egrep: example% egrep ’(SalIy|Fred) (Smith|Jones|Parker)’ telephone.list Sun Release 4.1 Last change: 30 November 1988 225 GREP(IV) USER COMMANDS GREP(IV) To get the filename displayed when only processing a single file, use /dev/null as the second file in the list: example% grep ’Sally Parker’ telephone.list /dev/null FILES /dev/null SEE ALSO awk(l), ed(l), ex(l), sh(l), vi(l), sed(lV) BUGS Lines are limited to 1024 characters by grep; longer lines are truncated. The combination of -1 and -v options does not produce a list of files in which a regular expression is not found. To get such a list, use the Bourne shell construct: for filename in * do if [ ‘grep "re" $filename | wc -1‘ -eq 0 ] then echo %filename fi done or the C shell construct: foreach filename (*) if (‘grep "re" $filename | wc -1‘ == 0) echo $ filename end Ideally there should be only one grep. DIAGNOSTICS Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files. 226 Last change: 30 November 1988 Sun Release 4.1 GROUPS ( 1 ) USER COMMANDS GROUPS (1 ) NAME groups - display a user’s group memberships SYNOPSIS groups [ username . . . ] DESCRIPTION With no arguments, groups displays the groups to which you belong; else it displays the groups to which the username belongs. Each user belongs to a group specified in the password file /etc/passwd and possi- bly 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. FILES /etc/passwd /etc/group SEE ALSO getgroups(2V) Sun Release 4.1 Last change: 9 September 1987 227 HEAD ( 1 ) USER COMMANDS HEAD ( 1 ) NAME head - display first few lines of specified files SYNOPSIS head [ —n ] [filename . . .] DESCRIPTION head copies the first n lines of each filename to the standard output. If no filename is given, head copies lines from the standard input. The default value of n is 10 lines. When more than one file is specified, the start of each file which looks like: ==>filename <== Thus, a common way to display a set of short files, identifying each one, is: example % head -9999 filenamel filename2 ... EXAMPLE The following example: example% head -4 /usr/share/man/manl/{cat,head,tail}.l* produces: ==> /usr/share/man/manl/cat.lv <== ,TH CAT IV "2 June 1983" .SH NAME cat - concatenate and display .SH SYNOPSIS ==> /usr/share/man/manl/head.l <== .TH HEAD I "24 August 1983" .SH NAME head - display first few lines of specified files .SH SYNOPSIS ==> /usr/share/man/manl/tail.l <== .TH TAIL 1 "27 April 1983" .SH NAME tail - display the last part of a file .SH SYNOPSIS SEE ALSO cat(lV), more(l), tail(l) 228 Last change: 9 September 1987 Sun Release 4.1 HELP_OPEN ( 1 ) USER COMMANDS HELP_OPEN ( 1 ) NAME help_open - use help_viewer to open a file SYNOPSIS help_open [ -a ] [filename [ pagejiumber ] ] AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION help_open is used to cause a running help_viewer(l) to open a file, filename is typically the name of a help_viewer file. A call is made to help_viewer using the same RPC mechanism as is used by Spot Help. If filename is relative, help_viewer looks for it relative to the default help directory (as defined in the user’s .defaults database). Otherwise, help_viewer treats filename as an absolute pathname. If the RPC call to help_viewer fails, he!p_open attempts to spawn help_viewer, with filename as a com- mand line argument. If the -a command line option was given, then filename is first converted to an abso- lute pathname, as described in OPTIONS, below. OPTIONS -a Convert filename to an absolute pathname. This option causes help_open to get the current work- ing directory and append it to the front of filename (thus creating an absolute pathname) before passing filename on to help_viewer. This allows help_open to be used with other processes, such as Sun Organizer (see organizer(l)), which deal in relative pathnames. The -a option has no effect if filename begins with the character ’/’. EXAMPLES In the first example, help_viewer opens the file help/He!p_Basics. This file is located relative to the default help directory (as defined in the user’s .defaults database). If the default help directory is set to /vol/help/language/USA-English, this is /vol/help/language/USA-English/help/Help_Basics. example% helpopen help/Help_Basics example % The second example is the same as the first, but it opens Help_Basics to page 3. example % help open “help/HelpBasics 3” example% In the next example, helpviewer opens somefile using the absolute pathname, /home/mtravis/somefile. example% help open /home/mtravis/somefile example % In the last example, help_viewer opens /home/ahinkle/anotherfile. example % cd /home/ahinkle example% help open -a anotherfile example % FILES /usr/Iib/help/* SEE ALSO help_viewer(l), organizer(l), help(5), help_viewer(5) Sun386i User’s Guide Sun386i Developer' s Guide Sun Release 4.1 Last change: 21 January 1990 229 HELP_VIEWER ( 1 ) USER COMMANDS HELP_VDEWER ( 1 ) NAME help_viewer - SunView application providing help with applications and desktop SYNOPSIS /usr/lib/help_viewer [ —A time ] [ —dir dirname ] [filename [ # ] ] AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION helpviewer accesses help documentation about SunView applications and the SunView Desktop. This help consists of intermixed text and graphics This help consists of intermixed text and graphics displayed in a window called the Help Viewer. You start and control help_viewer by one of these methods: • Typing help_viewer at a shell prompt. • Clicking on the More Help button in a Spot Help window. • Sending instructions to the Help Viewer using the help_open command. filename is the name of startup file relative to help directory (or /vol/help by default, as set in the Help category of defaultsedit). # is a page number separated from the filename by a SPACE. If # is omitted, the first page is shown. The documentation within help_viewer is extensible, but as shipped it includes handbooks for the Desktop, mailtool(l), shelltool(l), textedit(l), sunview(l), organizer(l), dos(l), coloredit(l), snap(l), and itself (help_viewer). Developers and users can include additional handbooks by modifying /vol/help/format/Top_Level. See help_viewer(5). The user moves between the various pages of help with the assistance of hypertext links. Links are con- nections between pages of text. The convention is to use underlined text to indicate the presence of a link. When the user double-clicks on a link, the text associated with the topic indicated by the link is shown in the Help Viewer. There are links in many places to make it quick and easy to go from place to place within the help_viewer database. Many help topics contain more than one page of text. In these cases, links to the next page and to the pre- vious page are available at the upper-right comer of the Help Viewer, allowing the user to page through the document. The user’s current position within the hierarchy of text is indicated by the links at the upper-left comer of the Help Viewer. The last link in the list is the level just above the user’s current position. OPTIONS The standard SunView options for window size, position, fonts, and other options are accepted. But note that the font setting only affects the font in the Help Viewer namestripe. Also, Help Viewer text does not wrap as a window is resized. See sunview(l) for details. -A time Sets autoclose for time minutes. If the help window is not used for time minutes, it closes automatically. -dir dirname Name of the help directory FILES /vol/help automount point of miscellaneous help files The files in /usr/lib/help are used by the help and the help_viewer facilities, and the SCCS sccs-help(l) facility. 230 Last change: 19 February 1988 Sun Release 4.1 HELP_VIEWER ( 1 ) USER COMMANDS HELP_VIEWER ( 1 ) Directories within /usr/lib/help named after SunView applications and the Desktop contain specific infor- mation used by help_viewer. See help_viewer(5) for information about the files in these directories. SEE ALSO sccs-help(l), mailtool(l), shelltool(l), textedit(l), help_open(l), help_viewer(5) Sun386i User’s Guide Sun386i Developer' s Guide DIAGNOSTICS helpviewer(l) displays a pop-up error window if it cannot find the file required to show the requested help. Sun Release 4.1 Last change: 19 February 1988 231 HOSTID ( 1 ) USER COMMANDS HOSTID ( 1 ) NAME hostid - print the numeric identifier of the current host SYNOPSIS hostid DESCRIPTION The hostid command prints the identifier of the current host in hexadecimal. This numeric value is unique across all Sun hosts. SEE ALSO gethostid(2) 232 Last change: 9 September 1987 Sun Release 4.1 HOSTNAME ( 1 ) USER COMMANDS HOSTNAME ( 1 ) NAME hostname — set or print name of current host system SYNOPSIS hostname [ name-of-host ] 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. FILES /etc/rc.local SEE ALSO gethostname(2) Sun Release 4.1 Last change: 9 September 1987 233 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) NAME iconedit - create and edit images for SunView icons, cursors and panel items SYNOPSIS iconedit [filename ] OPTIONS iconedit accepts the standard SunView command-line arguments; see sunview(l) for a list. AVAILABILITY This command is available with the SunView User’s software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION iconedit is a standard tool provided with the SunView environment. With it you can create and edit small images for use in icons, cursors, panel items, etc. iconedit has 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 (at the center right). • An area for status messages (at the upper right). • An area containing instructions for the use of the mouse (above the drawing canvas). Inside the canvas, use the left button to draw and the middle button to erase. As you draw, an enlarged ver- sion of the image appears in the canvas, while a life-sized version of the image appears in the proof area. Use the right button to undo the previous operation. While editing a cursor image, you can try the cursor out against different backgrounds and with different raster operations by moving the cursor into the proof area. CONTROL PANEL The large control panel to the right of the canvas contains many items through which you can control iconedit. Some items are buttons which allow you to initiate commands, some are text fields which you type into, and some are choice items allowing you select from a range of options. Use the left button to select items. Most items also have a menu which you can invoke with the right button. There are three text fields: the two at the top labeled Dir: and File:, and one to the right of the abc labeled Fill:. A triangular caret points to the current type-in position. Typing RETURN advances the caret to the next text field; you can also move the caret to a text field by selecting the field with the left button. Each item in the control panel is described below: Dir The current directory. File The current filename. The default is the filename given on the command line. You can request filename completion by pressing ESC. iconedit searches the current directory for files whose names begin with the string you entered. If the filename search locates only one file, that file will be loaded in. In addition, typing CTRL-L, CTRL-S, CTRL-B or CTRL-Q are equivalent to pressing the Load, Store, Browse, 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. Browse (Button) Display all the images in the current directory in a popup panel. When you select an image with the left button, it will be loaded into the canvas for editing and the browsing panel will be hidden. Pressing browse again will cause the panel to popup again (it will come up immedi- ately if the directory and file fields have not been modified). Quit (Button) Terminate processing. Quitting requires confirmation. 234 Last change: 2 October 1989 Sun Release 4.1 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) Size Alter the canvas size. Choices are icon size (64 x 64 pixels) or cursor size (16 x 16 pixels). Grid Display a grid over the drawing canvas, or turn the 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 painting modes. Instructions for each painting mode appear above the canvas. The painting modes are: dot Paint a single dot at a time. line Draw a line. To draw a line on the canvas, point to the first endpoint of the line, and press and hold the left mouse button. While holding the button down, drag the cursor to the second endpoint of the line. Release the mouse button. rectangle Draw a rectangle. To draw a rectangle on the canvas, point to the first comer of the rec- tangle and press and hold the left mouse button. While holding the button down, drag the cursor to the diagonally opposite comer of the rectangle. Release the mouse button. In the control panel, the Fill field to the right of the rectangle indicates the current rectan- gle fill pattern. Any rectangles you paint on the canvas will be filled with this pattern. circle Draw a circle. To draw a circle on the canvas, point to the center of the circle, and press and hold the left mouse button. While holding the button down, drag the cursor to the desired edge of the circle. Release the mouse button. In the control panel, the Fill field to the right of the circle indicates the current circle fill pattern. Any circles you paint on the canvas will be filled with this pattern. abc Insert text. To insert text, move the painting hand to abc and type the desired text. Then move the cursor to the canvas and press and hold the left mouse button. A box will appear where the text is to go. Position the box as desired and release the mouse button. In addition, you can choose the font in which to draw the text. Point at the Fill field to the right of the abc and either click the left mouse button to cycle through the available fonts or press and hold the right mouse button to bring up a menu of fonts. Load This is the rasterop to be used when loading a file in from disk. (See the Pixrect Reference Manual for details on rasterops). Fill This is the rasterop to be used when filling the canvas. The source for this operation is the rectan- gle fill pattern, and the destination is the canvas. Proof This is the rasterop to be used when rendering the proof image. The source for this operation is the proof image, and the destination is the proof background. 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. Sun Release 4.1 Last change: 2 October 1989 235 ICONEDIT ( 1 ) USER COMMANDS ICONEDIT ( 1 ) ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout iconedit. On entry to iconedit, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. SEE ALSO sunview(l) Pixrect Reference Manual 236 Last change: 2 October 1989 Sun Release 4.1 ID ( IV ) USER COMMANDS ID(1V) NAME id - print the user name and ID, and group name and ID SYNOPSIS id AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION id displays your user and group ID, and your username. If your real and effective IDs do not match, both are printed. SEE ALSO getuid(2V) Sun Release 4.1 Last change: 17 September 1989 237 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) NAME indent - indent and format a C program source file SYNOPSIS indent input-file [ output-file ] [ [ -bap I -nbap ] [ -bacc I -nbacc ] [ -bad I -nbad ] [ -bbb I -nbbb ] [ -be I -nbc ] [ -bl ] [ -br ] [ -bs I -nbs ] [ -cn ] [ -edn ] [ -cdb I -nedb ] [ -ce I -nee ] [ -ci n ] [ —clin ] [ — dn ] [ —din ] [ — eei I — neei ] [ — fcl I — nfcl ] [ —in ] [ —ip I —nip ] [ —In ] [ — len ] [ -Ip I -nip ] [ -pcs I -npcs ] [ -npro ] [ -psl I -npsl ] [ -sc I -nsc ] [ -sob I -nsob ] [ -st ] [ -troff ] [ -v I -nv ] DESCRIPTION indent is a C program formatter. It reformats the C program in the input-file according to the switches. The switches which can be specified are described below. They may appear before or after the file names. Note: if you only specify an input-file, the formatting is done “in-place”, that is, the formatted file is written back into input-file and a backup copy of input-file is written in the current directory. If input-file is named /blah/blah/file, the backup file is named file.BAK. If output-file is specified, indent checks to make sure it is different from input-file. OPTIONS The options listed below control the formatting style imposed by indent. -bap, -nbap If -bap is specified, a blank line is forced after every procedure body. Default: -nbap. -bacc, -nbacc If -bacc is specified, a blank line is forced around every conditional compilation block. That is. in front of every #ifdef and after every #endif. Other blanklines surrounding these will be swallowed. Default: -nbacc. -bad, -nbad If -bad is specified, a blank line is forced after every block of declarations. Default: -nbad. -bbb, -nbbb If -bbb is specified, a blank line is forced before every block comment. Default: -nbbb. -bc,-nbc -br,-bl If -be is specified, then a NEWLINE is forced after each comma in a declaration, -nbc turns off this option. The default is -be. Specifying -bl lines up compound statements like this: if ( • • •) { Specifying -br (the default) makes them look like this: -bs,-nbs Enable (disable) the forcing of a blank after sizeof. Some people believe that sizeof should appear as though it were a procedure call (-nbs, the default) and some people believe that since sizeof is an operator, it should always be treated that way and should always have a blank after it. -cn The column in which comments on code start. The default is 33. -edn The column in which comments on declarations start. The default is for these comments to start in the same column as those on code. 238 Last change: 9 September 1987 Sun Release 4.1 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) -cdb,-ncdb Enable (disable) the placement of comment delimiters on blank lines. With this option enabled, comments look like this: /* * this is a comment */ Rather than like this: I* this is a comment *1 This only affects block comments, not comments to the right of code. The default is -cdb . -ce,-nce Enables (disables) forcing else’s to cuddle up to the immediately preceding The default is -ce. -cin Sets the continuation indent to be n. Continuation lines will be indented that far from the begin- ning of the first line of the statement. Parenthesized expressions have extra indentation added to indicate the nesting, unless -lp is in effect, -ci defaults to the same value as -i. -cli/t Cause case labels to be indented n tab stops to the right of the containing switch statement. -cli0.5 causes case labels to be indented half a tab stop. The default is -cliO . — dn Control the placement of comments which are not to the right of code. The default -dl means that such comments are placed one indentation level to the left of code. Specifying -dO lines up these comments with the code. See the section on comment indentation below. -din Specify the indentation, in character positions, from a declaration keyword to the following identifier. The default is -dil6 . -eei,-neei If -eei is specified, and extra expression indent is applied on continuation lines of the expression part of if() and while(). These continuation lines will be indented one extra level — twice instead of just once. This is to avoid the confusion between the continued expression and the statement that follows the if( ) or while( ). Default: -neei. -fcl,-nfcl Enables (disables) the formatting of comments that start in column 1. Often, comments whose leading 7’ is in column 1 have been carefully hand formatted by the programmer. In such cases, -nfcl should be used. The default is -fcl. -i/i The number of spaces for one indentation level. The default is 4. -ip, -nip Enables (disables) the indentation of parameter declarations from the left margin. The default is -ip. -Irt Maximum length of an output line with a trailing comment. The default is 78. — Ic/i Sets the line length for block comments to n. It defaults to being the same as the usual line length as specified with -1. -lp,-nlp Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren which is not.closed on that line, then continuation lines will be lined up to start at the character position just after the left parenthesis. For example, here is how a piece of continued code looks with -nip in effect: pi = first_procedure(second_procedure(p2, p3), third_procedure(p4, p5)); Sun Release 4.1 Last change: 9 September 1987 239 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) With -lp in effect (the default) the code looks somewhat clearer: pi = first_procedure(second_procedure(p2, p3), third_procedure(p4, p5)); Inserting a couple more NEWLINE characters we get: Pi = first_procedure(second_procedure(p2, p3), ' third_procedure(p4, p5)); -npro Ignore the profile files, ./.indent.pro and V.indent.pro. -pcs , -npcs If true (-pcs) all procedure calls will have a space inserted between the name and the ’(’• The default is -npcs. — psl , -npsl If true (-psl) the names of procedures being defined are placed in column 1 — their types, if any, will be left on the previous lines. The default is -psl. -sc,-nsc Enables (disables) the placement of asterisks (‘*’s) at the left edge of all comments. -sob,-nsob If -sob is specified, indent will swallow optional blank lines. You can use this to get rid of blank lines after declarations. The default is -nsob. -st indent takes its input from the standard input, and put its output to the standard output. -T typename Add typename to the list of type keywords. Names accumulate: -T can be specified more than once. You need to specify all the typenames that appear in your program that are defined by typedefs — nothing will be harmed if you miss a few, but the program won’t be formatted as nicely as it should. This sounds like a painful thing to have to do, but it is really a symptom of a problem in C: typedef causes a syntactic change in the language and indent cannot find all typedefs. -troff Causes indent to format the program for processing by troff. It will produce a fancy listing in much the same spirit as vgrind. If the output file is not specified, the default is the standard out- put, rather than formatting in place. The usual way to get a troffed listing is with the command indent -troff program. c | troff -mindent -v,-nv -v turns on “verbose” mode, -nv turns it off. When in verbose mode, indent reports when it splits one line of input into two or more lines of output, and gives some size statistics at comple- tion. The default is -nv. FURTHER DESCRIPTION You may set up your own “profile” of defaults to indent by creating a file called .indent.pro in either your login directory or the current directory and including whatever switches you like. An .indent.pro in the current directory takes precedence over the one in your login directory. If indent is run and a profile file exists, then it is read to set up the program’s defaults. Switches on the command line, though, always over- ride profile switches. The switches should be separated by SPACE, TAB, or NEWLINE characters. Comments Boxed indent assumes that any comment with a dash or star immediately after the start of com- ment (that is, 7*-’or7**’) is a comment surrounded by a box of stars. Each line of such a comment is left unchanged, except that its indentation may be adjusted to account for the change in indentation of the first line of the comment. 240 Last change: 9 September 1987 Sun Release 4.1 INDENT ( 1 ) USER COMMANDS INDENT ( 1 ) Straight text All other comments are treated as straight text, indent fits as many words (separated by SPACE, TAB, or NEWLINE characters) on a line as possible. Blank lines break para- graphs. Comment indentation If a comment is on a line with code it is started in the “comment column”, which is set by the -c n com- mand line parameter. Otherwise, the comment is started at n indentation levels less than where code is currently being placed, where n is specified by the -dn command line parameter. If the code on a line extends past the comment column, the comment starts further to the right, and the right margin may be automatically extended in extreme cases. Preprocessor lines In general, indent leaves preprocessor lines alone. The only reformatting that it will do is to straighten up trailing comments. It leaves imbedded comments alone. Conditional compilation (#ifdef...#endif) is recognized and indent attempts to correctly compensate for the syntactic peculiarities introduced. C syntax indent understands a substantial amount about the syntax of C, but it has a “forgiving” parser. It attempts to cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros like: #define forever for(;;) is handled properly. FILES ./.indent.pro profile file "/.indent.pro profile file /usr/share/Iib/tmac/tmac.indent troff macro package for ‘indent -tr off’ output. SEE ALSO ls(lV), troff(l) BUGS indent has even more switches than Is(lV). A common mistake that often causes grief is typing: indent *.c to the shell in an attempt to indent all the C programs in a directory. This is probably a bug, not a feature. The -bs option splits an excessively fine hair. Sun Release 4.1 Last change: 9 September 1987 241 INDXBIB ( 1 ) USER COMMANDS INDXBIB ( 1 ) NAME indxbib — create an inverted index to a bibliographic database SYNOPSIS indxbib database-file. . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION indxbib makes an inverted index to the named database-file (which must reside within the current direc- tory), typically for use by lookbib(l) and refer(l). A database contains 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 trun- cates words to 6 characters, and maps upper case to lower case. It also discards words shorter than 3 char- acters, words among the 100 most common English words, and numbers (dates) < 1900 or > 2000. These parameters can be changed. See refer in Formatting Documents for details. indxbib creates an entry file (with a .ia suffix), a posting file (.ib), and a tag file (.ic), in the working direc- tory. FILES /usr/lib/refer/mkey /usr/lib/refer/inv x.ia x.ib x.ic xAg SEE ALSO addbib(l), lookbib(l), refer(l), roffbib(l), sortbib(l) Formatting Documents BUGS All dates should probably be indexed, since many disciplines refer to literature written in the 1800s or ear- lier. indxbib does not recognize pathnames. entry file posting file tag file reference file 242 Last change: 21 December 1987 Sun Release 4.1 INLINE ( 1 ) USER COMMANDS INLINE ( 1 ) NAME inline - in-line procedure call expander SYNOPSIS /usr/lib/inline [ -w ] [ -v ] [ -o outputfile ] [ -i inlinefile ] . . . [ cpu-option ] [fpu-option ] filename. . . DESCRIPTION inline expands assembly language calls in the indicated source files into copies of the corresponding pro- cedure bodies obtained from an inlinefile specified with the -i option. If no inlinefile is specified, the source files are simply concatenated and written to the standard output. If no source files are specified, the input is read from the standard input. Inline itself is little more than a sed script. Almost all of the benefit produced is derived from subsequent peephole optimization. OPTIONS -w Display warnings for duplicate definitions on the standard error. -v Verbose. Display the names of routines that were actually in-line expanded in the sourcefile on the standard error. -o outputfile write output to the indicated file; standard output by default. -i inlinefile Read in-line code templates from inlinefile. cpu-option Specify templates for the machine architecture of a Sun-2 or Sun-3 system. If this option is omit- ted, the proper template for the host architecture is used. Can be one of: -mc 68010 expand .mc 68010 code templates -mc 68020 expand .mc 68020 code templates fpu-option Specify a floating-point processor option for a Sun-2 or Sun-3 system. Can be one of: -fsoft expand .fsoft code templates (the default) -fswitch expand .fswitch code templates -fsky expand .fsky code templates (-mc 68010 only) — f 68881 expand ,f 68881 code templates (-mc 68020 only) -ffpa expand .ffpa code templates (-mc 68020 only) USAGE Each inlinefile contains one or more labeled assembly language templates of the form: inline-directive instructions .end where the instructions constitute an in-line expansion of the named routine. An inline-directive is a com- mand of the form: .inline identifier, argsize This declares a block of code for the routine named by identifier, with argsize bytes of arguments. ( argsize is optional on Sun-4 systems). Calls to the named routine are replaced by the code in the in-line template. Sun Release 4.1 Last change: 23 September 1987 243 INLINE ( 1 ) USER COMMANDS INLINE(l) For Sun-2 and Sun-3 systems, the following additional forms are recognized: .mc68010 identifier, argsize .mc68020 identifier, argsize •fsoft identifier, argsize .fswitch identifier, argsize •fsky identifier, argsize .f68881 identifier, argsize .ffpa identifier, argsize These forms are similar to .inline, with the addition of a CPU or FPU specification. The template is only expanded if the specified target system matches the value of the target CPU or FPU type, as determined by the command-line options, or if none were given, by the type of the host system. Multiple templates are permitted; matching templates after the first are ignored. Duplicate templates may be placed in order of decreasing performance of the corresponding hardware; thus the most efficient usable version will be selected. Coding Conventions for all Sun Systems In-line templates should be coded as expansions of C-compatible procedure calls, with the difference that the return address cannot be depended upon to be in the expected place, since no call instruction will have been executed. See FILES, below, for examples. In-line templates must conform to standard Sun parameter passing and register usage conventions, as detailed below. They must not call routines that violate these conventions; for example, assembly language routines such as setjmp(3V) may cause problems. Registers other than the ones mentioned below must not be used or set. Branch instructions in an in-line template may only transfer to numeric labels (If, 2b, and so on) defined within the in-line template. No other control transfers are allowed. Only opcodes and addressing modes generated by Sun compilers are guaranteed to work. Binary encod- ings of instructions are not supported. Coding Conventions for Sun-2 and Sun-3 Arguments are passed in 32-bit aligned memory locations starting at sp@. Note that there is no return address on the stack, since no jbsr instruction will have been executed. Results are returned in dO or dO/dl. The following registers may be used as temporaries: registers aO, al, dO, and dl on the MC68010 and MC68020; registers fpO and fpl on the MC68881; registers fpaO through fpa3 on the Sun Floating-Point Accelerator. No other registers may be used. The template must delete exactly argsize bytes from the stack. This is to enable inline to deal with autoin- crement and autodecrement addressing modes, which in turn are used by c2 to delimit the lifetimes of stack temporaries. The stack must not underflow the level of the last argument. Use jcc branch mnemonics instead of bcc. The bcc ops are span limited and will fail if retargeted to a label whose span overflows the branch displacement field. Coding Conventions for Sun-4 Systems Arguments are passed in registers %o0-%o5, followed by memory locations starting at [%sp+0x5c]. %sp is guaranteed to be 64-bit aligned. The contents of %o7 are undefined, since no call instruction will have been executed. Results are returned in %o0 or %fO/%fl. Registers %o0-%o5 and %f0-%f31 may be used as temporaries. 244 Last change: 23 September 1987 Sun Release 4.1 INLINE ( 1 ) USER COMMANDS INLINE(l) Integral and single-precision floating-point arguments are 32-bit aligned. Double-precision floating-point arguments are guaranteed to be 64-bit aligned if their offsets are multiples of 8. Each control-transfer instruction (branches and calls) must be immediately followed by a nop. Call instructions must include an extra (final) argument which indicates the number of registers used to pass parameters to the called routine. Note that for Sun-4 systems, the instruction following an expanded ’call’ is inserted by inline before the expanded code to preserve the semantics of the call’s delay slot. FILES /usr/lib/inline in-line procedure call expander /usr/lib/fsoft/libm.il in-line templates for software floating point (Sun-2 and Sun-3 only) /usr/lib/fswitch/libm.il in-line templates for switched floating point (Sun-2 and Sun-3 only) /usr/lib/fsky/Iibm.il in-line templates for Sky FFP (Sun-2 only) /usr/Iib/f68881/libm.il in-line templates for Motorola 68881 (Sun-3 only) /usr/lib/ffpa/libm.il in-line templates for Sun FPA (Sun-3 only) WARNING inline does not check for violations of the coding conventions described above. Sun Release 4.1 Last change: 23 September 1987 245 INPUT_FROM_DEF AULTS ( 1 ) USER COMMANDS INPUT_FROM_DEF AULTS ( 1 ) NAME input_ffom_defaults, defaults_from_input - update the current state of the mouse and keyboard from the defaults database, and vice versa SYNOPSIS input_from_defaults defaults_from_input AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION input_from_defaults updates various parameters controlling mouse- and keyboard-processing on the machine on which it is run. It should be used on systems which are running the SunView window system. The parameters control the distribution of function keys on the keyboard, the assignment of buttons on the mouse, the scaling of mouse-to-cursor motion, and the effect of two filters on mouse-motion originally pro- vided to compensate for defective mice. The new values are taken from the defaults database, starting with the file .defaults in the user’s home directory. When Private only is False in the $HOME/.defaults file, the /usr/lib/defaults/*.d file is consulted. See defaultsedit(l) for more information about the defaults database. defaults_from_input is the inverse operation to input_from_defaults. It updates the user’s private defaults database (used by defaultsedit(l)) to reflect the current state of kernel input parameters listed above. FILES $HOME/.defaults /usr/lib/ defaults/* ,d $HOME/.login SEE ALSO csh(l), defaultsedit(l) SunView User's Guide NOTES The parameter settings set by input_from_defau!ts are lost when the system goes down. To set them automatically on login, csh(l) users can include the following in their .login files: if (‘tty‘==/dev/console) then echo ’Setting input defaults’ input_from_defaults endif BUGS input_from_defaults should be targetable to any user’s .defaults file. 246 Last change: 8 September 1989 Sun Release 4.1 INSTALL ( 1 ) USER COMMANDS INSTALL ( 1 ) NAME install - install files SYNOPSIS install [ — cs ] [ — g group ] [ -m mode ] [ -o owner ] filel file2 install [ -cs ] [ -g group ] [ -m mode ] [ -o owner ] file . . . directory install -d [ -g group ] [ -m mode ] [ -o owner ] directory AVAILABILITY This command is available with the Install software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Install is used within makefiles to copy new versions of files into a destination directory and to create the destination directory itself. The first two forms are similar to the cp(l) command with the addition that executable files can be stripped during the copy and the owner, group, and mode of the installed file(s) can be given. The third form can be used to create a destination directory with the required owner, group and permis- sions. Note: install uses no special privileges to copy files from one place to another. The implications of this are: • You must have permission to read the files to be installed. • You must have permission to copy into the destination file or directory. • You must have permission to change the modes on the final copy of the file if you want to use the -m option to change modes. • You must be superuser if you want to specify the ownership of the installed file with -o. If you are not the super-user, or if -o is not in effect, the installed file will be owned by you, regardless of who owns the original. OPTIONS -g group Set the group ownership of the installed file or directory, (staff by default) -m mode Set the mode for the installed file or directory. (0755 by default) -o owner If run as root, set the ownership of the installed file to the user-ID of owner. -c Copy files. In fact install always copies files, but the -c option is retained for back- wards compatibility with old shell scripts that might otherwise break. -s Strip executable files after they are copied. -d Create a directory. Missing parent directories are created as required as in mkdir -p. If the directory already exists, the owner, group and mode will be set to the values given on the command line. SEE ALSO chgrp(l), chmod(lV), cp(l), mkdir(l), strip(l), chown(8) Sun Release 4.1 Last change: 7 September 1988 247 IPCRM(l) USER COMMANDS IPCRM ( 1 ) NAME ipcrm — remove a message queue, semaphore set, or shared memory ED SYNOPSIS ipcrm [ primitives ] DESCRIPTION ipcrm removes one or several messages, semaphores, or shared memory identifiers, as specified by the fol- lowing primitives : — q msqid removes the message queue identifier msqid from the system and destroys the message queue and data structures associated with it. - in shmid removes the shared memory identifier shmid from the system. The shared memory segment and data structures associated with it are destroyed after the last detach. -s semid removes the semaphore identifier semid from the system and destroys the set of semaphores and data structures associated with it. -Q msgkey removes the message queue identifier, created with key msgkey, from the system and destroys the message queue and data structures associated with it. -M shmkey removes the shared memory identifier, created with key shmkey, from the system. The shared memory segment and data structures associated with it are destroyed after the last detach. -S semkey removes the semaphore identifier, created with key semkey , from the system and destroys the set of semaphores and data structures associated with it. The identifiers and keys may be found by using ipcs(l). The details of removing identifiers are described in msgctl(2), shmctl(2), and semctl(2) in the sections detailing the IPC RMID command. SEE ALSO ipcs(l), msgctl(2), msgget(2), semctl(2), semget(2), semop(2), shmctl(2), shmget(2), shmop(2) 248 Last change: 9 September 1987 Sun Release 4.1 IPCS(l) USER COMMANDS IPCS(l) NAME ipcs - report interprocess communication facilities status SYNOPSIS ipcs [ primitives ] DESCRIPTION ipcs prints information about active interprocess communication facilities as specified by the primitives shown below. If no primitives are given, information is printed in short format for message queues, shared memory, and semaphores that are currently active in the system. Command - Line Primitives If any of the primitives -m, -q, or -s are specified, information about only indicated facilities is printed. If none of these are specified, information about all three is printed. -q -m -s -b -c -o -P -t -a -C corefile Print information about active message queues. Print information about active shared memory segments. Print information about active semaphores. Print the currently allowed size information. (Maximum number of bytes in messages on queue for message queues, size of segments for shared memory, and number of semaphores in each set for semaphores.) See below for the meaning of columns in a listing. Print creator’s login name and group name. See below. Print information on outstanding usage. (Number of messages on queue and total number of bytes in messages on queue for message queues and number of processes attached to shared memory segments.) Print process number information. (Process ID of last process to send a message and process ID of last process to receive a message on message queues and process ID of creating process and process ID of last process to attach or detach on shared memory segments)See below. Print time information. (Time of the last control operation that changed the access per- missions for all facilities. Time of last msgsnd and last msgrcv (see msgop(2)) on mes- sage queues, last shmat and last shmdt (see shmop(2)) on shared memory, last semop(2) on semaphores.) See below. Use all display primitives. (This is a shorthand notation for -b, -c, -o, -p, and -t.) Use the file corefile in place of /dev/mem. -N namelist The argument will be taken as the name of an alternate filenamelist (/vmunix is the default). The column headings and the meaning of the columns in an ipcs listing are given below; the letters in parentheses indicate the primitives that cause the corresponding heading to appear; all means that the head- ing always appears. Note: these primitives only determine what information is provided for each facility; they do not determine which facilities will be listed. T (all) Type of the facility: q message queue m shared memory segment s semaphore ID (all) The identifier for the facility entry. Sun Release 4.1 Last change: 9 September 1987 249 IPCS(l) USER COMMANDS EPCS(l) KEY MODE OWNER GROUP CREATOR CGROUP CBYTES QNUM QBYTES LSPID LRPID STIME RTIME CTIME NATTCH SEGSZ CPID LPID ATIME (all) The key used as an argument to msgget(2), semget(2), or shmget(2) to create the facil- ity entry. (Note: The key of a shared memory segment is changed to IPC_PRIVATE when the segment has been removed until all processes attached to the segment detach it.) (all) The facility access modes and flags: The mode consists of 1 1 characters that are inter- preted as follows: The first two characters are: R If a process is waiting on a msgrcv. S If a process is waiting on a msgsnd. D If the associated shared memory segment has been removed. It will disappear when the last process attached to the segment detaches it. C If the associated shared memory segment is to be cleared when the first attach is executed. - If the corresponding special flag is not set. The next 9 characters are interpreted as three sets of three bits each. The first set refers to the owner’s permissions; the next to permissions of others in the user-group of the facility entry; and the last to all others. Within each set, the first character indicates permission to read, the second character indicates per- mission to write or alter the facility entry, and the last character is currently unused. The permissions are indicated as follows: r If read permission is granted, w If write permission is granted, a If alter permission is granted. — If the indicated permission is not granted. (all) The login name of the owner of the facility entry. (all) The group name of the group of the owner of the facility entry. (a,c) The login name of the creator of the facility entry. (a,c) The group name of the group of the creator of the facility entry. (a,o) The number of bytes in messages currently outstanding on the associated message queue. (a,o) The number of messages currently outstanding on the associated message queue. (a,b) The maximum number of bytes allowed in messages outstanding on the associated message queue. (a,p) The process ID of the last process to send a message to the associated queue. (a,p) The process ID of the last process to receive a message from the associated queue. (a,t) The time the last message was sent to the associated queue. (a,t) The time the last message was received from the associated queue. (a,t) The time when the associated entry was created or changed. (a,o) The number of processes attached to the associated shared memory segment. (a,b) The size of the associated shared memory segment. (a,p) The process ID of the creator of the shared memory entry. (a,p) The process ID of the last process to attach or detach the shared memory segment. (a,t) The time the last attach was completed to the associated shared memory segment. 250 Last change: 9 September 1987 Sun Release 4.1 IPCS(l) USER COMMANDS IPCS ( 1 ) DTIME NSEMS OTIME (a,t) The time the last detach was completed on the associated shared memory segment. (a,b) The number of semaphores in the set associated with the semaphore entry. (a,t) The time the last semaphore operation was completed on the set associated with the semaphore entry. FILES /vmunix system namelist /dev/mem memory /etc/passwd user names /etc/group group names SEE ALSO ipcrm(l), msgop(2), semctl(2), semget(2), semop(2), shmctl(2), shmget(2), shmop(2) BUGS Things can change while ipcs is running; the picture it gives is only a close approximation to reality. Sun Release 4. 1 Last change: 9 September 1987 251 JOIN ( 1 ) USER COMMANDS JOIN ( 1 ) NAME join — relational database operator SYNOPSIS join [ -an ] [ -e string ] [ -j [112] m ] [ -o list ] [ -tc ] filenamel filename2 DESCRIPTION join forms, on the standard output, a join of the two relations specified by the lines of filenamel and filename2 . If filenamel is the standard input is used. filenamel and filename2 must be sorted in increasing ASCII collating sequence on the fields on which they are to be joined — normally the first in each line. There is one line in the output for each pair of lines in filenamel and filename2 that have identical join fields. The output line normally consists of the common field, then the rest of the line from filenamel , then the rest of the line from filename2 . The default input field separators are SPACE, TAB, and NEWLINE characters. If the default input field separators are used, multiple separators count as one field separator, and leading separators are ignored. The default output field separator is a blank. OPTIONS -an The parameter n can be one of the values: 1 Produce a line for each unpairable line in filenamel . 2 Produce a line for each unpairable line in filename2 . 3 Produce a line for each unpairable line in both filenamel and filename2 . The normal output is also produced. -e string Replace empty output fields by string. -j[H2 \m The j may be immediately followed by n, which is either a 1 or a 2. If n is missing, the join is on the m’th field of both files. If n is present, the join is on the m’th field of file n, and the first field of the other. Note: join counts fields from 1 instead of 0 as sort(l V) does. -o list Each output line comprises the fields specified in list, each element of which has the form n.m, where n is a file number and m is a field number. The common field is not printed unless specifically requested. Note: join counts fields from 1 instead of 0 like sort does. -tc Use character c as a separator (tab character). Every appearance of c in a line is significant. The character c is used as the field separator for both input and output. EXAMPLE The following command line will join the password file and the group file, matching on the numeric group ID, and outputting the login name, the group name and the login directory. It is assumed that the files have been sorted in ASCII collating sequence on the group ID fields. join -jl 4 — j2 3 -o 1.1 2.1 1.6 -t: /etc/passwd /etc/group SEE ALSO awk(l), comm(l), look(l), sort(lV), uniq(l) BUGS With default field separation, the collating sequence is that of sort -b; with -t, the sequence is that of a plain sort. The conventions of join, sort, comm, uniq, look, and awk are wildly incongruous. Filenames that are numeric may cause conflict when the — o option is used right before listing filenames. 252 Last change: 16 February 1988 Sun Release 4.1 KEYLOGIN ( 1 ) USER COMMANDS KEYLOGIN ( 1 ) NAME keylogin - decrypt and store secret key SYNOPSIS keylogin DESCRIPTION keylogin prompts the user for their login password, and uses it to decrypt the user’s secret key stored in the publickey(5) database. Once decrypted, the user’s key is stored by the local key server process keyserv(8C) to be used by any secure network services, such as NFS. Normally, login(l) does this work when the user logs onto the system, but running keylogin may be neces- sary if the user did not type a password to login(l). SEE ALSO chkey(l), login(l), publickey(5), keyserv(8C), newkey(8) Sun Release 4.1 Last change: 9 September 1987 253 KEYLOGOUT ( 1 ) USER COMMANDS KEYLOGOUT (1) NAME keylogout - delete stored secret key SYNOPSIS keylogout [ -f ] DESCRIPTION keylogout deletes the key stored by the key server process keyserv(8C) to be used by any secure network services, such as NFS. Further access to the key is revoked, however current session keys may remain valid till they expire, or are refreshed. This option will cause any background jobs that need secure RPC services to fail, and any scheduled at jobs that need the key to fail. Also since only one copy is kept on a machine of the key, it is a bad idea to place this in your .logout file since it will affect other sessions on the same machine. OPTIONS -f Forget the rootkey. This will break secure NFS if it is done on a server. SEE ALSO chkey(l), login(l), keylogin(l), publickey(5), keyserv(8C), newkey(8) 254 Last change: 15 April 1989 Sun Release 4.1 KILL ( 1 ) USER COMMANDS KILL ( 1 ) NAME kill - send a signal to a process, or terminate a process SYNOPSIS kill [ -signal ] pid . . . kill-1 DESCRIPTION kill sends the TERM (terminate, 15) signal to the processes with the specified pids. If a signal name or number preceded by is given as first argument, that signal is sent instead of terminate. The signal names are listed by using the -1 option, and are as given in , stripped of the common SIG prefix. The terminate signal will kill processes that do not catch the signal, so ‘kill -9 . . .’ is a sure kill, as the KILL (9) signal cannot be caught. By convention, if process number 0 is specified, all members in the pro- cess group (that is, processes resulting from the current login) are signaled (but beware: this works only if you use sh(l); not if you use csh(l).) Negative process numbers also have special meanings; see kill(2V) for details. The killed processes must belong to the current user unless he is the super-user. To shut the system down and bring it up single user the super-user may send the initialization process a TERM (terminate) signal by ‘kill 1’; see init(8). To force init to close and open terminals according to what is currently in /etc/ttytab use ‘kill -HUP 1’ (sending a hangup signal to process 1). The shell reports the process number of an asynchronous process started with *&’ (run in the background). Process numbers can also be found by using ps(l). kill is built in to csh(l); it allows job specifiers, such as ‘kill % ...’, in place of kill arguments. See csh(l) for details. OPTIONS -1 Display a list of signal names. FILES /etc/ttytab SEE ALSO csh(l), ps(l), kill(2V), sigvec(2), init(8) BUGS A replacement for ‘kill 0’ for csh(l) users should be provided. Sun Release 4. 1 Last change: 16 November 1987 255 LAST ( 1 ) USER COMMANDS LAST ( 1 ) NAME last - indicate last logins by user or terminal 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 tele- type or any group of users and teletypes. Arguments specify names of users or teletypes of interest. Names of teletypes may be given fully or abbreviated. For example last 0 is the same as lasttfyO. If multi- ple arguments are given, the information which applies to any of the arguments is printed. For example last root console would list all of “root’s” sessions as well as all sessions on the console terminal, last displays the sessions of the specified users and teletypes, most recent first, indicating the times at which the session began, the duration of the session, and the teletype which the session took place on. If the session is still continuing or was cut short by a reboot, last so indicates. The pseudo-user reboot logs in at reboots of the system, thus last reboot will give an indication of mean time between reboot. last with no arguments displays a record of all logins and logouts, in reverse order. If last is interrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit sig- nal (generated by a CTRLA) last indicates how far the search has progressed so far, and the search contin- ues. 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 /var/adm/wtmp. FILES /var/adm/wtmp login data base SEE ALSO lastcomm(l), utmp(5V), ac(8) 256 Last change: 9 September 1987 Sun Release 4.1 LASTCOMM ( 1 ) USER COMMANDS LASTCOMM ( 1 ) NAME lastcomm - show the last commands executed, in reverse order SYNOPSIS lastcomm [ command-name ] . . . [ user-name ] . . . [ terminal-name ] . . . DESCRIPTION lastcomm gives information on previously executed commands, lastcomm with no arguments displays information about all the commands recorded during the current accounting file’s lifetime. If called with arguments, lastcomm displays only accounting entries with a matching command-name, user-name, or terminal-name. EXAMPLES The command example% lastcomm a.out root ttydO would produce a listing of all the executions of commands named a.out, by user root while using the ter- minal ttydO. example % lastcomm root would produce a listing of all the commands executed by user root. For each process entry, lastcomm displays the following 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. • The name of the user who ran the process. • The terminal from which the user was logged in at the time (if applicable). • The amount of CPU time used by the process (in seconds). • The date and time the process starts. FILES /var/adm/pacct accounting file SEE ALSO last(l), sigvec(2), acct(5), core(5) Sun Release 4. 1 Last change: 7 September 1989 257 LD ( 1 ) USER COMMANDS LD(1) NAME Id, ld.so - link editor, dynamic link editor SYNOPSIS Id [ -align datum ] [ -assert assertion-keyword ] [ -A name ] [ -B binding-keyword ] [ -d ] [ -dc ] [ -dp ] [ -D hex ] [ -e entry ] [ -lx ] [ -L dir ] [ -M ] [ -n ] [ -N ] [ -o name ] [ -p ] [-r ] [ — s ] [-S] [ — t ] [-T[text] hex ] [-Tdata/iex] [-u name] [ — x ] [-X] [ -ysym ] [-z ] filename ... DESCRIPTION Id combines object programs to create an executable file or another object program suitable for further Id processing (with the -r option). The object modules on which Id operates are specified on the command line, and can be: • simple object files, which typically end in the .0 suffix, and are referred to as “dot-oh” files e ar(lV) library archives (.a), or “libraries” • dynamically-bound, sharable object files (.so), are also referred to as “shared libraries,” which are created from previous Id executions. Unless an output file is specified, Id produces a file named a.out. This file contains the object files given as input, appropriately combined to form an executable file. OPTIONS When linking debugging or profiling objects, include the -g or -pg option (see cc(l V)), as appropriate, in the Id command. Options should appear before filenames, except for abbreviated library names specified with -1 options, and some binding control options specified by -B (which can appear anywhere in the line). -align datum Force the global uninitialized data symbol datum (usually a FORTRAN common block) to be page-aligned. Increase its size to a whole number of pages, and place its first byte at the start of a page. -assert assertion-keyword Check an assertion about the link editing being performed. The assertion desired is specified by the assertion-keyword string. Id is silent if the assertion holds, else it yields a diagnostic and aborts. Valid assertion-keyword' s and their interpretations are: definitions If the resulting program were run now, there would be no run-time undefined symbol diagnostics. This assertion is set by default. nodefinitions Permit the successful linking of a program with unresolved references, nosymbolic There are no symbolic relocation items remaining to be resolved, pure-text The resulting load has no relocation items remaining in its text. -A name Incremental loading: linking is to be done in a manner so that the resulting object may be read into an already executing program, name is the name of a file whose symbol table is taken as a basis on which to define additional symbols. Only newly linked material is entered into the text and data portions of a.out, but the new symbol table will reflect all symbols defined before and after the incremental load. This argument must appear before any other object file in the argument list. One or both of the -T options 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. 258 Last change: 21 January 1990 Sun Release 4.1 LD( 1 ) USER COMMANDS LD(1) -B binding-keyword Specify allowed binding times for the items which follow. Allowed values of binding-keyword are: -d -dc -dp dynamic nosymbolic static symbolic Allow dynamic binding: do not resolve symbolic references, allow creation of run-time symbol and relocation environment. -Bdynamic is the default. When -Bdynamic is in effect, all sharable objects encountered until a succeeding -Bstatic may be added dynamically to the object being linked. Non-sharable objects are bound statically. Do not perform symbolic relocation, even if other options imply it. Bind statically. Opposite of -Bdynamic. Implied when either -n or -N is specified. Influences handling of all objects following its specification on a command line until the next -Bdynamic. Force symbolic relocation. Normally implied if an entry point has been specified with -e, or if dynamic loading is in effect. Force common storage for uninitialized variables and other common symbols to be allocated in the current Id run, even when the -r flag is present (which would otherwise postpone this binding until the final linking phase). Do -d, but also copy initialized data referenced by this program from shared objects. Force an alias definition of undefined procedure entry points. Used with dynamic binding to improve sharing and the locality of run-time relocations. -D hex Pad the data segment with zero-valued bytes to make it hex bytes long. -e entry Define the entry point: the entry argument is made the name of the entry point of the loaded pro- gram. Implies -Bsymbolic. -Lc[.v] This option is an abbreviation for the library name libx.a, where x is a string. Id searches for libraries first in any directories specified with -L options, then in the standard directories /lib, /usr/lib, and /usr/Iocal/lib. A library is searched when its name is encountered, so the placement of a -1 is significant. If a dynamically loadable object is found, and -Bdynamic is in effect at that point on the command line, then Id prepares to access the object for relocation at run-time. In such a case, the optional .v suffix can be used to indicate a specific library version. -L dir Add dir to the list of directories in which to search for libraries. Directories specified with -L are searched before the standard directories, /lib, /usr/lib, and /usr /local/lib. When building a pro- gram in which one or more objects are loaded when -Bdynamic is in effect, those directories specified by -L options will be “remembered” for use at execution time. This permits the con- struction of software that uses shared objects as libraries not residing in the standard locations and avoids requiring the specification of the LD_LIBRARY_PATH environment variable in order to execute such software. Note that such directories are retained in exactly the form specified in the option, which means that relative directory specifications (i.e., not beginning with “/”) will be evaluated relative to the current directory when the program is run, not just during the operation of Id. -M Produce a primitive load map, listing the names of the files which will be loaded. -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 with the data areas placed at the beginning of the next address boundary following the end of the text. Implies -Bstatic. -N Do not make the text portion read-only. (Use “magic number” 0407.) Implies -Bstatic. -o name name is made the name of the Id output file, instead of a.out. Sun Release 4.1 Last change: 21 January 1990 259 LD ( 1 ) USER COMMANDS LD ( 1 ) -p Arrange for the data segment to begin on a page boundary, even if the text is not shared (with the -N option). -r Generate relocation bits in the output file so that it can be the subject of another Id run. This flag also prevents final definitions from being given to common symbols, and suppresses the “undefined symbol” diagnostics. -s Strip the output, 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(l). -S Strip the output by removing all symbols except locals and globals. -t Trace: display the name of each file as it is processed. -T [ text ] hex Start the text segment at location hex. Specifying -T is the same as using the -Ttext option. -Tdata hex Start the data segment at location hex. This option is only of use to programmers wishing to write code for PROMs, since the resulting code cannot be executed by the system. -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 Preserve only global (non-.globl) symbols in the output symbol table; only enter external symbols. This option saves some space in the output file. -X Record local symbols, except for those whose names begin with L. This option is used by cc to discard internally generated labels while retaining symbols local to routines. -ysym Display each file in which sym appears, its type and whether the file defines or references it. Many such options may be given to trace many symbols. It is usually necessary to begin sym with an as external C, FORTRAN and Pascal variables begin with underscores. -z Arrange for the process demand paged from the resulting executable file (0413 “magic number”). This is the default. Results in a (32-byte) header on the output file followed by text and data seg- ments, each of which has a multiple of page-size bytes (being padded out with null characters 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 rounding the data segment size. Implies -Bdynamic. USAGE Command Line Processing In general, options should appear ahead of the list of files to process. Unless otherwise specified, the effect of an option covers all of Id operations, independent of that option’s placement on the command line. Exceptions to this rule include some of the binding control options specified by ‘-B’ and the abbreviated library-names specified by ‘-1’. These may appear anywhere, and their influence is dependent upon their location. Some options may be obtained from environment variables, such options are interpreted before any on the command line (see ENVIRONMENT, below). Object File Processing The files specified on the command line are processed in the order listed. Information is extracted from each file, and concatenated to form the output. The specific processing performed on a given file depends upon whether it is a simple object file, a library archive, or a shared library. Simple object (.o) files are concatenated to the output as they are encountered. Library archive (.a) files are searched exactly once each, as each is encountered; only those archive entries matching an unresolved external reference are extracted and concatenated to the output. If a member of an archive references a symbol defined by another member of that same archive, the member making the reference must appear before the member containing the definition. 260 Last change: 21 January 1990 Sun Release 4.1 LD(1) USER COMMANDS LD ( 1 ) On Sun386i, a library contains a dictionary of symbols, On other Sun systems, processing library archives through ranlib(l) provides this dictionary. In addition, you can use lorder(l), in combination with tsort(l) to place library members in calling order (see lorder(l) for details), or both (for fastest symbol lookup). The first member of an archived processed by ranlib has the reserved name of .SYMDEF, which Id takes to be the dictionary of all symbols defined by members of the archive. Sharable objects (.so) are scanned for symbol definitions and references, but are not normally included in the output from Id, except in cases where a shared library exports initialized data structures and the -dc option is in effect. However, the occurrence of each sharable object file in the Id command line is noted in the resulting executable file; this notation is utilized by an execution-time variant of Id, ld.so, for deferred and dynamic loading and binding during execution. See Execution-Time Loading, below, for details. The -1 option specifies a short name for an object file or archive used as a library. The full name of the object file is derived by adding the prefix lib and a suffix of either .a or .so[.v] to indicate an ar(lV) archive or a shared library, respectively. The specific suffix used is determined through rules discussed in Binding and Relocation Semantics, below. Id searches for the desired object file through a list of directories specified by -L options, the environment variable LD_LIBRARY_PATH, and finally, the built-in list of standard library directories: /lib, /usr/lib, and /usr/local/lib. Binding and Relocation Semantics The manner in which Id processes a given object file is dependent in part upon the “binding mode” in which it is operating at the time the file is encountered. This binding mode is specified by the -B flag, which takes the keyword arguments: dynamic Allow dynamic binding, do not resolve symbolic references, and allow creation of execution-time symbol and relocation information. This is the default setting. static Force static binding, implied by options that generate non-sharable executable for- mats. -Bdynamic and -Bstatic may be specified several times, and may be used to toggle each other on and off. Like -1, the influence of each depends upon its location within the command line. When -Bdynamic is in effect, -1 searches may be satisfied by the first occurrence of either form of library (.so or .a), but if both are encountered, the .so form is preferred. When -Bstatic is in effect, Id refuses to use any .so libraries it encounters; it continue searching for the .a form. Furthermore, an explicit request to load a .so file is treated as an error. After Id has processed all input files and command line options, the form of the output it produces is based on the information provided in both. Id first tries to reduce all symbolic references to relative numerical offsets within the executable it is building. To perform this “symbolic reduction,” Id must be able to deter- mine that: • all information relating to the program has been provided, in particular, no .so is to be added at execution time; and/or • the program has an entry point, and symbolic reduction can be performed for all symbols hav- ing definitions existing in the material provided. It should be noted that uninitialized “common” areas (for example, uninitialized C globals) are allocated by the link editor after it has collected all references. In particular, this allocation can not occur in a program that still requires the addition of information contained in a .so file, as the missing information may affect the allocation process. Initialized “commons” however, are allocated within the executable in which their definition appears. After Id has performed all the symbolic reductions it can, it attempts to transform all relative references to absolute addresses. Id is able to perform this “relative reduction” only if it has been provided some abso- lute address, either implicitly through the specification of an entry point, or explicitly through Id command-line options. If, after performing all the reductions it can, there are no further relocations or definitions to perform, then Id has produced a completely linked executable. Sun Release 4.1 Last change: 21 January 1990 261 LD(1) USER COMMANDS LD(1) Execution-Time Loading In the event that one or more reductions can not be completed, the executable will require further link edit- ing at execution time in order to be usable. Such executables contain an data structure identified with the symbol DYNAMIC. An incompletely linked “main” program should be linked with a “bootstrap” rou- tine that invokes ld.so, which uses the information contained in the main program’s DYNAMIC to assemble the rest of the executables constituting the entire program. A standard Sun compilation driver (such as cc(lV)) automatically includes such a module in each “main” executable. When ld.so is given control on program startup, it finds all .so files specified when the program was con- structed (and all .so’s on which they depend), and loads them into the address space. The algorithm by which such files are found mimics that used when Id is run, and like Id, can be influenced by the setting of LD_LIBRARY_PATH and any -L options specified to Id when the program was built. ld.so then com- pletes all remaining relocations, with the exception of procedure call relocations; failure to resolve a given non-procedural relocation results in termination of the program with an appropriate diagnostic. Procedure relocations are resolved when the referencing instruction is first executed. It should be noted that it is possible for “undefined symbol” diagnostics to be produced during program execution if a given target is not defined when referenced. Although it is possible for binding errors to occur at execution-time, such an occurrence generally indicates something wrong in the maintenance of shared objects. Id’s —assert nodefinitions function (on by default) checks at ld-time whether or not an execution-time binding error would occur. Version Handling for Shared Libraries To allow the independent evolution of .so’s used as libraries and the programs which use them, Id’s han- dling of .so files found through -1 options involves the retention and management of version control infor- mation. The .so files used as such “shared libraries” are post-fixed with a Dewey-decimal format string describing the version of the “library” contained in the file. The first decimal component is called the library’s “major version” number, and the second component its “minor version” number. When Id records a .so used as a library, it also records these two numbers in the database used by ld.so at execution time. In turn, ld.so uses these numbers to decide which of multiple ver- sions of a given library is “best” or whether any of the available versions are acceptable. The rules are: • Major Versions Identical: the major version used at execution time must exactly match the version found at ld-time. Failure to find an instance of the library with a matching major ver- sion causes a diagnostic to be issued and the program’s execution to be terminated. • Highest Minor Version: in the presence of multiple instances of libraries that match the desired major version, ld.so uses the highest minor version it finds. However, if the highest minor version found at execution time is less than the version found at ld-time, a warning diagnostic is issued; program execution continues. The semantics of version numbers are such that major version numbers should be changed whenever inter- faces are changed. Minor versions should be changed to reflect compatible updates to libraries, and pro- grams will silently favor the highest compatible version they can obtain. Special Symbols A number of symbols have special meanings to Id and programs should not define these symbols. The symbols described below are those actually seen by Id. Note: C and several other languages prepend sym- bols they use with etext The first location after the text of the program. _edata The first location after initialized data, end The first location after all data. 262 Last change: 21 January 1990 Sun Release 4.1 LD(1) USER COMMANDS LD ( 1 ) DYNAMIC Identifies an ld-produced data structure. It is defined with a non-zero value in executables which require execution-time link editing. By convention, if defined, it is the first symbol in the symbol table associated with an a.out file. GLOBAL_OFFSET_TABLE_ A position-independent reference to an ld-constructed table of addresses. This table is constructed from “position-independent” data references occurring in objects that have been assembled with the assembler’s -k flag (invoked on behalf of C compilations performed with the -pic flag). A related table (for which no symbol is currently defined) contains a series of transfer instructions and is created from “position-independent” procedure calls or, if -dp is specified to Id, a list of undefined symbols. Symbols in object files beginning with the letter L are taken to be local symbols and unless otherwise specified are purged from Id output files. ENVIRONMENT LDLIBRARYPATH A colon-separated list of directories in which to search for libraries specified with the -1 option. Similar to the PATH environment variable. LD_LIBRARY_PATH also affects library searching during execution-time loading, causing the search to use first those directories found in the environment variable, then any directories specified by -L options, and finally the standard direc- tories /usr/lib and /usr/local/lib. NOTE: when running a set-user- or set-group-ID program, ld.so will only search for libraries in directories it “trusts”, which are /usr/lib, /usr/51ib, /usr/local/lib, and any directories specified within the executable as a result of -L options given when the exe- cutable was constructed. LDOPTIONS A default set of options to Id. LD_OPTIONS is interpreted by Id just as though its value had been placed on the command line, immediately following the name used to invoke Id, as in: example % Id $LD_OPTIONS . . . other-arguments . . . Note: Environment variable-names beginning with the characters ‘LD_’ are reserved for possible future enhancements to Id. FILES /usr/lib/lib*.a lib*.so.v lib*.sa.v /usr/lib/ld.so /usr/lib/*crt*.o a.out /usr/local/lib SEE ALSO ar(lV), as(l), cc(lV), lorder(l), ranlib(l), strip(l), tsort(l), ldconfig(8) BUGS Options are being overloaded and are an inappropriate vehicle for describing to Id the wide variety of things it can do. There needs to be a link-editing language which can be used in the more complex situa- tions. The -r option does not properly handle programs assembled with the -k (position-independent) flag, invoked from cc with -pic or —PIC. libraries shared libraries exported, initialized shared library data execution-time Id default program bootstraps output file Sun Release 4. 1 Last change: 21 January 1990 263 LDD(l) USER COMMANDS LDD ( 1 ) NAME ldd - list dynamic dependencies SYNOPSIS ldd filename . . . DESCRIPTION For each filename , ldd lists the dynamically loaded objects on which that filename depends, if any. If the dynamic dependency is a “library” (a so-called “shared library”), then both the canonical form of the library name and version and the actual pathname used to access the library are listed. For example, if a given filename uses a shared C library version 4, which has the name /usr/lib/libc.so.4.9 (where 9 is the most recent revision to interface version number 4) then ldd filename will report: filename: -lc.4 => /usr/lib/libc.so.4.9 For each filename which is not an executable program, or else does not require any dynamic objects for its execution, ldd will issue an appropriate diagnostic. It should be noted that although all dynamically linked programs depend on the file /usr/lib/ld.so , ldd will never report this dependency. SEE ALSO ld(l) 264 Last change: 12 November 1987 Sun Release 4.1 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, and at the time. After the specified time, it reminds you every minute thereafter 10 more times, leave disappears after you log off. You can specify the time in on of two ways, namely as an absolute time of day in the form hhmm where hh is a time in hours (on a 12 or 24 hour clock), or you can place a + sign in front of the time, in which case the time is relative to the current time, that is, the specified number of hours and minutes from now. All times are converted to a 12 hour clock, and assumed to be in the next 12 hours. If no argument is given, leave prompts with ‘When do you have to leave?’, leave exits if you just type a NEWLINE, otherwise the reply is assumed to be a time. This form is suitable for inclusion in a .login or .profile. leave ignores interrupts, quits, and terminates. To get rid of it you should either log off or use kill -9 and its process ID. EXAMPLES The first example sets the alarm to an absolute time of day: example% leave 1535 Alarm set for Wed Mar 7 15:35:07 1984 work work work work example% Time to leave! The second example sets the alarm for 10 minutes in the future: example % leave +10 Alarm set for Wed Mar 7 work work work work example % Time to leave! work work work work example % You’re going to be late! FILES .login .profile SEE ALSO calendar(l) Sun Release 4.1 Last change: 9 September 1987 265 LEX ( 1 ) USER COMMANDS LEX ( 1 ) NAME lex - lexical analysis program generator SYNOPSIS lex [ -fntv ] [filename ] ... DESCRIPTION lex generates programs to be used in simple lexical analysis of text. Each filename (the standard input by default) contains regular expressions to search for, and actions written in C to be executed when expres- sions are found. A C source program, lex.yy.c is generated, to be compiled as follows: cc lex.yy.c -11 This program, when run, copies unrecognized portions of the input to the output, and executes the associ- ated C action for each regular expression that is recognized. The actual string matched is left in yytext, an external character array. Matching is done in order of the strings in the file. The strings may contain square braces to indicate char- acter classes, as in [abx-z] to indicate a, b, x, y, and z; and the operators *, + and ?, which mean, respec- tively, any nonnegative number, any positive number, or either zero or one occurrences of the previous character or character-class. The “dot” character (‘ . ’) is the class of all ASCII characters except NEWLINE. Parentheses for grouping and vertical bar for alternation are also supported. The notation r{d,e} in a rule indicates instances of regular expression r between d and e. It has a higher precedence than |, but lower than that of *, ?, +, or concatenation. The A (carat character) at the beginning of an expression permits a successful match only immediately after a NEWLINE, and the $ character at the end of an expression requires a trailing NEWLINE. The / character in an expression indicates trailing context; only the part of the expression up to the slash is returned in yytext, although the remainder of the expression must follow in the input stream. An operator character may be used as an ordinary symbol if it is within symbols or preceded by ‘V. Three subroutines defined as macros are expected: input() to read a character; unput(c) to replace a char- acter read; and output(c) to place an output character. They are defined in terms of the standard streams, but you can override them. The program generated is named yylex( ), and the library contains a main( ) which calls it. The action REJECT on the right side of the rule rejects this match and executes the next suit- able match; the function yymore( ) accumulates additional characters into the same yytext; and the func- tion yyless(n) where n is the number of characters to retain in yytext. The macros input and output use files yyin and yyout to read from and write to, defaulted to stdin and stdout, respectively. In a lex program, any line beginning with a blank is assumed to contain only C text and is copied; if it pre- cedes % % it is copied into the external definition area of the lex.yy.c file. All rules should follow a % %, as in YACC. Lines preceding % % which begin with a nonblank character define the string on the left to be the remainder of the line; it can be used later by surrounding it with { }. Note: curly brackets do not imply parentheses; only string substitution is done. The external names generated by lex all begin with the prefix yy or YY. Certain table sizes for the resulting finite-state machine can be set in the definitions section: %p n number of positions is n (default 2000) %nn number of states is n (500) %t n number of parse tree nodes is n (1000) %a n number of transitions is n (3000) The use of one or more of the above automatically implies the -v option, unless the -n option is used. 266 Last change: 1 December 1988 Sun Release 4.1 LEX ( 1 ) USER COMMANDS LEX ( 1 ) OPTIONS -f Faster compilation. Do not bother to pack the resulting tables; limited to small programs. -n Opposite of -v; -n is default. -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. EXAMPLES The following command line: lex lexcommands would draw lex instructions from the file lexcommands, and place the output in lex.yy.c. The following: %% [A-Z] putchar (yytext[0]+'a'-'A'); [ ]+$ ; [ ]+ putchar(' '); is an example of a lex program. It converts upper case to lower, removes blanks at the end of lines, and replaces multiple blanks by single blanks. D [0-9] %% if printf("IF statementV); [a-z]+ printf("tag, value %s\n",yytext); 0{D}+ printf("octal number %s\n",yytext); {D}+ printf(" decimal number %s\n",yytext); "++" printf(" unary op\n"); tl + t» printf(" binary op\n"); { loop: while (input() != '*0; switch (input( )) { case T: break; case unput('*')> default: go to loop; } } FILES lex.yy.c SEE ALSO sed(lV), yacc(l) Programming Utilities and Libraries NOTES The lex command is not changed to support 8-bit symbol names, as this would produce lex source code that is not portable between systems. Sun Release 4.1 Last change: 1 December 1988 267 LINE ( 1 ) USER COMMANDS LINE(l) NAME line - read one line SYNOPSIS line DESCRIPTION line copies one line (up to a NEWLINE) from the standard input and writes it on the standard output. It returns an exit code of 1 on EOF and always prints a NEWLINE at least. It is often used within shell scripts to read a line from the terminal. SEE ALSO sh(l), read(2V) 268 Last change: 9 September 1987 Sun Release 4.1 LINT (IV) USER COMMANDS LINT (IV) NAME lint - a C program verifier SYNOPSIS lint [ -abchinquvxz ] [ -D name [= def ] ] [ -bast-arch ] [ -I directory ] [ -1 library ] [ -o outputfile ] t -target -arch ] [ -U name ] filename . . . lint [ -Clibrary ] [ -D name [=def] ] [ -host =arch ] [ -I directory ] [ -1 library ] [ -target=arc/z ] [ -U name ] filename . . . SYSTEM V SYNOPSIS /usr/5bin/lint [ -abcghnpquvxzO ] [ -Dname [=def] ] [ -I directory ] [ -Mibrary ] [ -o outputfile ] [ -U name ] filename . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION lint attempts to detect features of the named C program files that are likely to be bugs, to be non-portable, or to be wasteful. It also performs stricter type checking than does the C compiler, lint runs the C prepro- cessor as its first phase, with the preprocessor symbol lint defined to allow certain questionable code to be altered or skipped by lint. Therefore, this symbol should be thought of as a reserved word for all code that is to be checked by lint. Among the possible problems that are currently noted are unreachable statements, loops not entered at the top, automatic variables declared and not used, and logical expressions with constant values. Function calls are checked for inconsistencies, such as calls to functions that return values in some places and not in others, functions called with varying numbers of arguments, function calls that pass arguments of a type other than the type the function expects to receive, functions whose values are not used, and calls to func- tions not returning values that use the non-existent return value of the function. Filename arguments ending with .c are taken to be C source files. Filename arguments with names ending with .In are taken to be the result of an earlier invocation of lint, with either the -i or the -C option in effect. The .In files are analogous to the .o (object) files produced by the cc(lV) from .c files, lint also accepts special libraries specified with the -1 option, which contain simplified definitions of standard library routines (preprocessed by ‘lint -C’) for faster checking of function calls. lint processes the various .c, .In, and \Yib-\library An (lint library) files and process them in command-line order. By default, lint appends the standard C lint library (llib-lc.ln) to the end of the list of files. When the -C and -i options are omitted the second pass of lint checks this list of files for mutual compatibility. When the -C or the -i options are used, the .In and the \\\b-\library An files are ignored. SYSTEM V DESCRIPTION Filename arguments with names ending with .In are taken to be the result of an earlier invocation of lint, with either the -c or the -o option in effect. lint processes the various .c, .In, and \\\b-\library An (lint library) files and process them in command-line order. By default, lint appends the standard C lint library (llib-lc.ln) to the end of the list of files. How- ever, if the -p option is used, the portable C lint library (Uib-port.ln) is appended instead. When the -c option is omitted the second pass of lint checks this list of files for mutual compatibility. When the -c option is used, the .In and the llib-l/z'brary.ln files are ignored. lint produces its first-pass output on a per-source-file basis. Complaints regarding included files are col- lected and printed after all source files have been processed. If the -c option is not used, information gath- ered from all input files is then collected and checked for consistency. At this point, if it is not clear whether a complaint stems from a given source file or from one of its included files, the source file name is printed, followed by a question mark. Sun Release 4.1 Last change: 23 February 1988 269 LINT (IV) USER COMMANDS LINT(IV) OPTIONS -a Report assignments of long values to variables that are not long. -b Report break statements that cannot be reached. This is not the default because, unfortunately, most lex(l) and many yacc(l) outputs produce many such complaints. -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. -i Produce a .In file for every .c file on the command line. These .In files are the product of lint’s first pass only, and are not checked for compatibility between functions. -n Do not check compatibility against the standard library. -q Do not complain about constructs that do not cause portability problems between current Sun implementations of the C language but that will cause portability problems between other imple- mentations. If the -q flag is specified, lint treats type enum as an int, treats type long as type int and type unsigned long as unsigned int, and treats a 0 argument as being conformable with any pointer. -u Do not complain about functions and external variables used and not defined, or defined and not used (this is suitable for running lint on a subset of files comprising part of a larger program). -v Suppress complaints about unused arguments in functions. -x Report variables referred to by extern declarations, but never used. -z Do not complain about structures that are never defined (for example, using a structure pointer without knowing its contents). -Clibrary Create a lint library with the name llib-1/zbrary.ln. -D name[=def\ Define name for cpp(l), as if by a #define directive. If no definition is given, name is defined as 1 . -host=arch (Sun-2, Sun-3, and Sun-4 systems only) Define the host architecture to be arch. The default is the architecture returned by the arch(l) command, arch can be one of sun2, sun3, or sun4. -I directory Add directory to the list of list of directories in which to search for include files. Include files with names that do not begin with / are always sought first in the directory of the filename argument, then in directories named in -I options, then in the /usr/include directory. -1 library Use the lint library library from the /usr/lib/lint directory. -o outputfile Name the output file outputfile. outputfile cannot be the same as sourcefile (lint will not overwrite the source file). -target=arc/z (Sun-2, Sun-3, and Sun-4 systems only) Define the target architecture to be arch, for additional portability checks specific to that architec- ture. The default is the value returned by the arch(l) command, arch can be one of: sun2, sun3, or sun4. -U name Remove any initial definition of name for the preprocessor. 270 Last change: 23 February 1988 Sun Release 4.1 LINT ( 1 V ) USER COMMANDS LINT (IV) SYSTEM V OPTIONS The sense of the -a, -b, -h, and -x options is reversed in the System V version of lint; the tests they con- trol are performed unless the flag is specified. The -C option is not available; instead, the -c or -o options can be used. The -i option is not used; instead, the -c option can be used. The -q, -host, and -target options are not available. — c Produce a .In file for every .c file on the command line. These .In files are the product of lint’s first pass only, and are not checked for compatibility between functions. -g . . , -O These options are accepted but ignored. By recognizing these options, lint’s behavior is closer to that of the cc(l V) command. -n Do not check compatibility against either the standard or the portable lint library. -p Attempt to check portability of code to other dialects of C, such as IBM 370 and Honeywell GCOS. Along with performing stricter checking, this option truncates all non-external names to eight characters, and all external names to six characters and one case. -o library Create a lint library with the name Ilib-l/z'b.ln. The -c option nullifies any use of the -o option. The lint library produced is the input that is given to lint’s second pass. The -o option simply saves this file in the named lint library. To produce a Hib-1/zb.ln without extraneous messages, use of the -x option is suggested. The -v option is useful if the source file(s) for the lint library are just external interfaces (for example, the way the file llib-lc is written). These option settings are also available through the use of “lint comments” (see Input Grammar below). USAGE For more information about lint refer to lint in Programming Utilities and Libraries To create lint libraries, use the -C option. For example example% lint -Ccongress filenames . . . where filenames are the C sources of library congress, produces a file llib-lcongress.ln in the current direc- tory in the correct library format suitable for “linting” programs using -lcongress. Input Grammar lint’s first pass reads standard C source files, lint recognizes the following C comments as commands. /♦NOTREACHED*/ At appropriate points, inhibit comments about unreachable code. (This comment is typically placed just after calls to functions like exit(2V)). /♦VARARGSn*/ Suppress the usual checking for variable numbers of arguments in the following function declara- tion. The data types of the first n arguments are checked; a missing n is taken to be 0. In this ver- sion of lint, /*' VARARGSO*/ is allowed. It no longer indicates the absence of variable arguments. /♦ARGSUSED*/ Enable the -v option for the next function. /+LINTLIBRARY*/ At the beginning of a file, shut off complaints about unused functions and function arguments in this file. This is equivalent to using the -v and -x options. Sun Release 4. 1 Last change: 23 February 1988 271 LINT (IV) USER COMMANDS LINT (IV) SYSTEM V USAGE The behavior of the -c and the -o options allows for incremental use of lint on a set of C source files. Invoking ‘lint -c’ for each source file produces a corresponding .In file, and prints all messages pertaining to that source file. After all of the source files have been run through lint separately, it is invoked once more (without the -c option), and with all of the .In files and —be options. This produces messages about any inconsistencies between files. This scheme works well with make(l), since it allows make to “lint” only those source files that have been modified since the last time lint was run. To create lint libraries, use the -o option. For example example% lint — x — o congress filenames . . . where filenames are the C sources of library congress, produces a file llib-lcongress.ln in the current direc- tory in the correct library format suitable for “linting” programs using -lcongress. EXAMPLE The following lint call: example % lint -b myfile.c checks the consistency of the code in the C source file file myfile.c. The -b option indicates that unreach- able break statements are to be checked for. FILES /usr/lib/lint/lint[12] programs /usr/lib/lint/llib-1* .In various prebuilt lint libraries /usr/lib/lint/llib-1* sources of the prebuilt lint libraries The following lint libraries are supplied with SunOS: -1c, -lcore, -leurses, -lkvm, -llwp, -1m, -Imp, -lpixrect, -Iplot, -Isuntool, -lsunwindow, -ltermcap, and -ltermlib. Additional lint libraries may be installed separately. SYSTEM V FILES /usr/51ib/Iint/lint[12] programs /usr/ 51 ib/lint/llib-1 * .In various prebuilt lint libraries /usr/51ib/lint/llib-l* sources of the prebuilt lint libraries The following System V lint libraries are supplied with SunOS: -1c, -lcore, -leurses, -lkvm, -llwp, -lm, -Imp, -lpixrect, -Iplot, -lport. -Isuntool, and -lsunwindow. Additional lint libraries may be installed separately. SEE ALSO cc(lV), cpp(l), lex(l), make(l), yacc(l), exit(2V), setjmp(3V), ansic(7V), bsd(7V), posix(7V), sunos(7), svidii(7V), svidiii(7V), xopen(7V) Programming Utilities and Libraries NOTES Because cc does not generate or support 8-bit symbol names, it is inappropriate to make lint 8-bit clean. See cc(lV) for an explanation about why cc is not 8-bit clean. BUGS There are some things you just cannot get lint to shut up about. The routines exit(2V), longjmp (see setjmp(3V)) and other functions that do not return are not under- stood; this causes various incorrect diagnostics. Libraries created by the -C or -o options will, when used in later lint runs, cause certain errors that were reported when the libraries were created to be reported again, and cause line numbers and file names from the original source used to create those libraries to be reported in error messages. For these reasons, it is still useful to produce stripped down lint library source files and to use them to generate lint libraries. 272 Last change: 23 February 1988 Sun Release 4.1 LN(1Y) USER COMMANDS LN(1V) NAME In - make hard or symbolic links to files SYNOPSIS In [ -fs ] filename [ linkname ] In [ -fs ] pathname . . . directory SYSTEM V SYNOPSIS /usr/5bin/ln [ -fFs ] filename [ linkname ] In [ -fFs ] pathname. . . directory AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION In creates an additional directory entry, called a link, to a file or directory. Any number of links can be assigned to a file. The number of links does not affect other file attributes such as size, protections, data, etc. filename is the name of the original file or directory, linkname is the new name to associate with the file or filename. If linkname is omitted, the last component of filename is used as the name of the link. If the last argument is the name of a directory, symbolic links are made in that directory for each pathname argument; In uses the last component of each pathname as the name of each link in the named directory. A hard link (the default) is a standard directory entry just like the one made when the file was created. Hard links can only be made to existing files. Hard links cannot be made across file systems (disk parti- tions, mounted file systems). To remove a file, all hard links to it must be removed, including the name by which it was first created; removing the last hard link releases the inode associated with the file. A symbolic link, made with the -s option, is a special directory entry that points to another named file. Symbolic links can span file systems and point to directories. In fact, you can create a symbolic link that points to a file that is currently absent from the file system; removing the file that it points to does not affect or alter the symbolic link itself. A symbolic link to a directory behaves differently than you might expect in certain cases. While an Is(lV) on such a link displays the files in the pointed-to directory, an ‘Is -F displays information about the link itself: example % In -s dir link example% Is link filel file2 file3 file4 example % Is -1 link lrwxrwxrwx 1 user 7 Jan 11 23:27 link -> dir When you cd(l) to a directory through a symbolic link, you wind up in the pointed-to location within the file system. This means that the parent of the new working directory is not the parent of the symbolic link, but rather, the parent of the pointed-to directory. For instance, in the following case the final working directory is /usr and not /home/user/Iinktest. example% pwd /home/user/linktest example % In -s /usr/tmp symlink example % cd symlink example% cd .. example% pwd /usr C shell user’s can avoid any resulting navigation problems by using the pushd and popd built-in com- mands instead of cd. Sun Release 4.1 Last change: 16 September 1989 273 LN (IV) USER COMMANDS LN (IV) SYSTEM V DESCRIPTION The System V version of In behaves as described above except for the following. If the linkname is an existing file and its mode does not forbid writing, then its contents are destroyed. If however its mode does not allow writing, the mode is printed, and the user asked for a response. OPTIONS -f Force a hard link to a directory — this option is only available to the super-user. -s Create a symbolic link or links. SYSTEM V OPTIONS -f Force files to be linked without displaying permissions, asking questions or reporting errors. -F Force a hard link to a directory — this option is only available to the super-user. -s Create a symbolic link or links. EXAMPLE The commands below illustrate the effects of the different forms of the In command: example% In file link example% Is -F file link file link example% In -s file symlink example % Is -F file symlink file symlink@ example % Is -li file link symlink 10606 -rw-r-r— 2 user 0 Jan 12 00:06 file 10606 -rw-r-r- 2 user 0 Jan 12 00:06 link 10607 lrwxrwxrwx 1 user 4 Jan 12 00:06 symlink -> file example % In -s nonesuch devoid exam pie % Is -F devoid devoid@ example % cat devoid devoid: No such file or directory example% In -s /proto/bin/* /tmp/bin example% Is -F /proto/bin /tmp/bin /proto/bin: x* y* z* /tmp/bin: x@ y@ z@ SEE ALSO cp(l), ls(lV), mv(l), rm(l), link(2V), readlink(2), stat(2V), symlink(2) BUGS When the last argument is a directory, simple basenames should not be used for pathname arguments. If a basename is used, the resulting symbolic link points to itself: example% In -s file /tmp example% Is -1 /tmp/file lrwxrwxrwx 1 user 4 Jan 12 00:16 /tmp/file -> file example% cat /tmp/file /tmp/file: Too many levels of symbolic links 274 Last change: 16 September 1989 Sun Release 4.1 LN(1V) USER COMMANDS LN(1V) To avoid this problem, use full pathnames, or prepend a reference to the PWD variable to files in the work- ing directory: example% rm /tmp/file example% In -s $PWD/fiIe /tmp Irwxrwxrwx 1 user 4 Jan 12 00:16 /tmp/file -> /home/user/subdir/file Sun Release 4. 1 Last change: 16 September 1989 275 LOAD ( 1 ) USER COMMANDS LOAD ( 1 ) NAME load, loadc - load Application SunOS or Developer’s Toolkit clusters SYNOPSIS load [filename . . .] loadc [ cluster . . . ] loadc appl loadc devel AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION load loads the optional clusters in the Application SunOS or the Developer’s Toolkit that contain the files specified in the filename arguments, loadc loads the optional clusters in the Application SunOS or the Developers Toolkit specified in the cluster arguments. Specify the special cluster name appl with loadc to load all the Application SunOS clusters. Likewise, specify devel to loadc to load all the Developer’s Toolkit clusters. load and loadc require the user to specify the distribution medium, either 3.5-inch diskette or quarter- inch tape, and insert the diskette or tape. The user will be asked to confirm that the specified medium has been inserted. If the user confirmation is negative, no software will be loaded. Without arguments, load and loadc display a summary of the clusters in the Application SunOS and Developer’s Toolkit, including the load state and size of each cluster. EXAMPLES To load the cluster that contains the spell(l) command: example% load spell Enter your distribution media type (1=1/4" tape, 2=3.5" diskette): 2 Insert diskette n to load the spellcheck cluster, confirm (y/n): y Loading the spellcheck cluster ... The spellcheck cluster has been loaded, space used by clusters: 6021K bytes total space remaining: 20432K bytes example% To load the spellcheck cluster: example % loadc spellcheck Enter your distribution media type (1=1/4" tape, 2=3.5" diskette): 2 Insert diskette n to load the spellcheck, confirm (y/n): y Loading the spellcheck cluster . . . The spellcheck cluster has been loaded, space used by clusters: 6021K bytes total space remaining: 20432K bytes example % To display a summary of the clusters in the Application SunOS and Developer’s Toolkit: example % load Application SunOS Optional Clusters: available cluster size (bytes) yes accounting 265K no advanced admin 501K 276 Last change: 19 February 1988 Sun Release 4.1 LOAD ( 1 ) USER COMMANDS LOAD(l) Developer’s Toolkit Optional Clusters: available cluster size (bytes) no base devel 6907K space used by clusters: 6021K bytes total space remaining: 20432K bytes example % A cluster is available if it has been “loaded” using load or loadc or if it has been “mounted” across the net- work. ENVIRONMENT LOADMEDIA Used to specify the distribution media type for the system. It can be set to diskette to specify 3.5-inch diskette or tape to specify 1/4" tape. If it is set, load and loadc will not ask the user to enter the distribution media type. FILES /usr/cluster/appl where Application SunOS clusters are loaded (or mounted) /usr/cluster/devel where Developer’s Toolkit clusters are loaded (or mounted) /usr/Iib/load/* data files SEE ALSO cluster(l), unload(l), toc(5) Sun386i System Setup and Maintenance DIAGNOSTICS Wrong diskette! tape An incorrect diskette or tape was inserted. The user will again be asked to insert the specified media. The file filename is not in any of the optional software clusters. The specified file is not part of the Application SunOS or Developer’s Toolkit. There is no cluster cluster. The specified cluster is not part of the Application SunOS or Developers Toolkit. The cluster cluster is already loaded, overwrite? (y/n): The specified cluster appears to have been loaded already. Type y followed by RETURN to have the cluster loaded or n followed by RETURN to cancel the loading of the cluster. Cluster cluster requires nK; there is not enough disk space. There is not enough disk space to hold the specified cluster. The cluster cluster has not been loaded. The loading of the specified cluster has been canceled or interrupted by the user. The Application SunOS (and/or) Developers Toolkit are mounted. The Application SunOS or Developers Toolkit or both are mounted across the network and can not be loaded or unloaded. The tape /diskette drive is currently in use. You are trying to load a cluster from tape (or diskette) and another process currently has control of the tape (or diskette) drive. Sun Release 4.1 Last change: 19 February 1988 277 LOADKEYS ( 1 ) USER COMMANDS LOADKEYS (1) NAME loadkeys, dumpkeys - load and dump keyboard translation tables SYNOPSIS loadkeys [ -e ] [filename ] dumpkeys DESCRIPTION loadkeys loadkeys reads the file specified by filename, and modifies the keyboard streams module’s translation tables. If no file is specified, and the keyboard is a Type-4 keyboard, a default file for the layout indicated by the DIP switches on the keyboard. The file is in the format specified by keytables(5). If the layout code in the DIP switches on the keyboard has the hexadecimal value 0 xdd, the file loaded by loadkeys by default is /usr/share/lib/keytables/layoutjW. These files specify only the entries that change between the different Type-4 keyboard layouts. dumpkeys dumpkeys writes, to the standard output, the current contents of the keyboard streams module’s translation tables, in the format specified by keytables(5). OPTIONS -e loadkeys loads the requested keytable layout information into the EEPROM keytables. This allows the console monitor to select the correct key-values when a non-US keyboard is connected to the workstation. FILES /usr/share/lib/keytables/layoutcW default keytable files SEE ALSO kb(4M), keytables(5) BUGS The -e option requires EEPROM rev 2.6 or later. 278 Last change: 1 September 1988 Sun Release 4.1 LOCKSCREEN ( 1 ) USER COMMANDS LOCKSCREEN ( 1 ) NAME lockscreen, lockscreen_default - maintain SunView context and prevent unauthorized access SYNOPSIS lockscreen [ -enr ] [ -b program ] [ -t seconds ] [ gfx-program [ gfx-program-arguments ] ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information about installing optional software. DESCRIPTION lockscreen is a SunView utility that locks the screen against unauthorized access while preserving the state of the SunView display. It clears the workstation screen to black, and then runs gfx-program, which typi- cally provides a moving graphics display to reduce phosphor bum. When no gfx-program is provided, a suitable default program is run. lockscreen requires the user’s password before restoring the window context. When any keyboard or mouse button is pressed, the graphics screen is replaced by a password screen that displays the user name, a small box with a bouncing logo, and a prompt for the user’s password. If the user has no password, or if the -n option is used, the window context is simply restored. When the password screen appears: • Restore the window context by entering the user’s password followed by a RETURN (this password is not echoed on the screen) or, • Point to the black box and click the left button to return to the graphics display. If neither of the above actions is taken, gfx _program will resume execution after the interval specified with the -t option. OPTIONS -e Add the Exit Desktop choice to the password screen. If pointed to and clicked, the SunView environment is exited and the current user is logged out. -n Require no password to reenter the window environment. -r Allow the use of the user name root in the ‘Name: ’ field of the password screen. Normally, root is not accepted as a valid user name. -b program Allow an additional program to be run as a child process of lockscreen. This background process could be a compile server or some other useful program that the user wants run while lockscreen is running. No arguments are passed to this program. -t seconds After seconds seconds, clear the password screen and restart gfx-program. The default is 5 minutes (300 seconds). [ gfx-program ] [ gfx-program-arguments ] Run this program after clearing the screen to black. When no program argument is present, lock- screen tries to run lockscreen_defauIt if it is in the standard search path; otherwise, a bouncing Sun logo appears. When gfx-program-arguments are specified and the gfx-program is not, the arguments are passed to lockscreen_default. lockscreen_default is typically a non-interactive graphics program (see graphics_demos(6)). lockscreen does not search for lockscreen_default when the gfx-program is specified explicitly as an empty argument (an adjacent pair of quote- marks). FILES /usr/bin/lockscreen_defauIt Default gfx-program. This displays a series of life(6) patterns. If a file named lockscreen_default appears earlier in the search path, that file is used instead. Sun Release 4.1 Last change: 5 December 1989 279 LOCKS CREEN ( 1 ) USER COMMANDS LOCKS CREEN ( 1 ) SEE ALSO login(l), sunview(l) BUGS lockscreen is more secure when gfx-program are not specified and when lockscreen_default is not in the search path. To improve security, enter the following command as root, or start lockscreen with an empty argument (see OPTIONS, above). # mv /usr/bin/lockscreen_default /usr/bin/lockscreen_default- 280 Last change: 5 December 1989 Sun Release 4.1 LOGGER ( 1 ) USER COMMANDS LOGGER ( 1 ) NAME logger - add entries to the system log SYNOPSIS logger [ -t tag ] [ -p priority ] [ — i ] [ — f filename ] [ message ] . . . DESCRIPTION logger provides a method for adding one-line entries to the system log file from the command line. One or more message arguments can be given on the command line, in which case each is logged immediately. Otherwise, a filename can be specified, in which case each line in the file is logged. If neither is specified, logger reads and logs messages on a line-by-line basis from the standard input. OPTIONS -t tag Mark each line added to the log with the specified tag . -p priority Enter the message with the specified priority. The message priority can be specified numer- ically, or as a facility .level pair. For example, ‘-p local3.info’ assigns the message priority to the info level in the Iocal3 facility. The default priority is user .notice. -i Log the process ID of the logger process with each line. -f filename Use the contents of filename as the message to log. message If this is unspecified, either the file indicated with -f or the standard input is added to the log. EXAMPLES logger System rebooted will log the message ‘System rebooted’ to the facility at priority notice to be treated by syslogd as other messages to the facility notice are. logger -p localO.notice -t HOSTIDM -f /dev/idmc will read from the file /dev/idmc and will log each line in that file as a message with the tag ‘HOSTIDM’ at priority notice to be treated by syslogd as other messages to the facility localO are. SEE ALSO syslog(3), sys!ogd(8) Sun Release 4. 1 Last change: 9 September 1987 281 LOGIN ( 1 ) USER COMMANDS LOGIN ( 1 ) NAME login - log in to the system SYNOPSIS login [ -p ] [ username ] DESCRIPTION login signs username on to the system initially; login may also be used at any time to change from one user ID to another. When used with no argument, login requests a user name and password (if appropriate). Echoing is turned off (if possible) while typing the password. Note: the number of significant characters in a password is 8. See passwd(l). If password aging is enabled and the password corresponding to the user name has expired, the user will be prompted for a new password. The user has to successfully modify his password for login to proceed. See passwd(l). When successful, login updates accounting files, prints disk usage and limits (by running quota(l),) prints the message of the day, informs you of the existence of any mail, and displays the time you last logged in. None of these messages is printed if there is a .hushlogin file in your home directory. This is mostly used to make life easier for nonhuman users, such as uucp(lC). login initializes the user and group IDs and the working directory, then starts a command interpreter shell (usually either sh(l) or csh(l)) according to specifications found in the file /etc/passwd. Argument 0 of the command interpreter is the name of the command interpreter with a leading dash (*-’) prepended. login also modifies the environment (environ(5V)) with information specifying home directory, command interpreter, terminal-type (if available) and username. The -p argument preserves the remainder of the environment, otherwise any previous environment is discarded. The super-user root may only log in on those terminals marked as “secure” in the /etc/ttytab file. Other- wise, the super-user must log in as an ordinary user and become super-user using su(lv). For example, if the file contained: console "/etc/getty Console-9600" sun on secure ttyOO "/etc/getty Console-9600" sun on the super-user could only log in directly on the console. See ttytab(5) for a discussion of “secure” and other getty(8) options used in /etc/ttytab. If the file /etc/nologin exists, login prints its contents on the user’s terminal and exits. This is used by shut- down^) to stop logins when the system is about to go down. The login command, recognized by sh(l) and csh(l), is executed directly (without forking), and terminates that shell. To resume working, you must log in again. login times out and exits if its prompt for input is not answered within a reasonable time. When the Bourne shell (sh) starts up, it reads a file called .profile from your home directory (that of the username you use to log in). When the C shell (csh) starts up, it reads a file called .cshrc from your home directory, and then reads a file called .login. The shells read these files only if they are owned by the person logging in. OPTIONS -p Preserve any existing environment variables and their values; otherwise the previous environment is discarded. FILES /etc/utmp accounting /var/adm/wtmp accounting /var/adm/lastlog time of last login 282 Last change: 12 June 1988 Sun Release 4.1 LOGIN ( 1 ) USER COMMANDS LOGIN ( 1 ) /etc/ttytab /usr/ucb/quota /var/spool/mail/* /etc/motd /etc/passwd /etc/nologin "/.hushlogin .login .profile terminal types quota check mail message-of-the-day password file stop login, print message makes login quieter SEE ALSO csh(l), mail(l), passwd(l), quota(l), rlogin(lC), sh(l), uucp(lC), environ(5V), fbtab(5), passwd(5), svdtab(5), utmp(5V), getty(8), init(8), shutdown(8) DIAGNOSTICS Login incorrect If the name or the password is bad (or mistyped). No Shell cannot open password file no directory Ask your system administrator for assistance. NOTES The following options are undocumented, and not intended for the user. The -r option is used by the remote login server, rlogind(8C) to force login to enter into an initial connection protocol, -h is used by telnetd(8C) and other servers to list the host from which the connection was received. The following warnings apply when login account names contain characters outside the range of 7-bit ASCII: • A user cannot rlogin to account-name containing 8-bit characters from a system that does not handle 8-bit characters. • A user cannot log in to account-name containing 8-bit characters from a 7-bit ASCII terminal (through a modem, for example). • Several parts of the C library are not tested for 8-bit user names. • Codeset mapping can vary between systems, so an 8-bit pattern can represent different characters on different sytems. • Password algorithms do not work with 8-bit characters in the password. Sun Release 4.1 Last change: 12 June 1988 283 LOGNAME ( 1 ) USER COMMANDS LOGNAME ( 1 ) NAME logname - get the name by which you logged in SYNOPSIS logname DESCRIPTION logname returns the contents of the environment variable LOGNAME, which is set when a user logs into the system. FILES /etc/profile SEE ALSO env(l), login(l), environ(5V) NOTES The following warnings apply when login accounts contain characters outside the range of 7-bit ASCII: • A user cannot rlogin to account-name containing 8-bit characters from a system that does not handle 8-bit characters. • A user cannot log in to account-name containing 8-bit characters from a 7-bit ASCII terminal (through a modem, for example). • Several parts of the C library are not tested for 8-bit user names. • Codeset mapping can vary between systems, so an 8-bit pattern can represent different characters on different sytems. • Password algorithms do not work with 8-bit characters. 284 Last change: 9 September 1987 Sun Release 4.1 LOOK ( 1 ) USER COMMANDS LOOK ( 1 ) NAME look - find words in the system dictionary or lines in a sorted list SYNOPSIS look [ -df ] [ -tc ] string [filename ] DESCRIPTION look consults a sorted filename and prints all lines that begin with string. If no filename is specified, look uses /usr/dict/words with collating sequence -df. OPTIONS -d Dictionary order. Only letters, digits, TAB and SPACE characters are used in comparisons, -f Fold case. Upper case letters aren’t distinguished from lower case in comparisons. -tc Set termination character. All characters to the right of c in string are ignored. PILES /usr/dict/words SEE ALSO grep(lV), sort(lV) Sun Release 4.1 Last change: 17 August 1987 285 LOOKBIB ( 1 ) USER COMMANDS LOOKBIB ( 1 ) NAME lookbib - find references in a bibliographic database SYNOPSIS lookbib database AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. 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 V prompt on the terminal, and retrieves records containing all these keywords. If nothing matches, nothing is returned except another V prompt. It is possible to search multiple databases, as long as they have a common index made by indxbib(l). 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 (see grep(lV)). lookbib then uses this fgrep file to find references. This method is simpler to use, but the .ig file is slower to use than the .i[abc] files, and does not allow the use of multiple reference files. FILES x.ia x.ib x.ic x.xg SEE ALSO addbib(l), grep(lV), indxbib(l), refer(l), roffbib(l), sortbib(l) Formatting Documents BUGS Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or ear- lier. index files reference file 286 Last change: 21 December 1987 Sun Release 4.1 LORDER ( 1 ) USER COMMANDS LORDER ( 1 ) NAME lorder - find an ordering relation for an object library SYNOPSIS lorder filename . . . DESCRIPTION Give lorder one or more object or library archive (see ar(lV)) filenames, and it lists pairs of object file names — meaning that the first file of the pair refers to external identifiers defined in the second — to the standard output, lorder’s output may be processed by tsort(l) to find an ordering of a library suitable for one-pass access by ld(l). EXAMPLE This brash one-liner intends to build a new library from existing .o files, ar cr library ' lorder *.o | tsort' The ranlib(l), command converts an ordered archive into a randomly accessed library and makes lorder unnecessary. SEE ALSO ar(lV), ld(l), ranlib(l), tsort(l) BUGS The names of object files, in and out of libraries, must end with ‘.o’; otherwise, nonsense results. Sun Release 4.1 Last change: 9 September 1987 287 LP(1) USER COMMANDS LP( 1 ) NAME lp, cancel - send/cancel requests to a printer SYNOPSIS lp [ -cmsw ] [ -d dest ] [ -nnumber ] [ -o option ] [ -t title ] filename . . . cancel [ ids ] [ printers ] DESCRIPTION lp arranges for the named files and associated information (collectively called a request ) to be printed by a line printer. If no file names are mentioned, the standard input is assumed. The file name stands for the standard input and may be supplied on the command line in conjunction with named filenames. The order in which filenames appear is the same order in which they will be printed. lp associates a unique id with each request and prints it on the standard output. This id can be used later to cancel (see cancel) or find the status (see Ipstat(l)) of the request. cancel cancels line printer requests. The command line arguments may be either request ids (as returned by lp(l)) or printer names. When ids are specified, cancel removes the jobs corresponding to the ids on the destination printer. See the -d option for details on how the default destination printer is obtained. For a complete list of printers, use lpstat(l). Specifying a request id cancels the associated request even if it is currently printing. Specifying a printer cancels the request which is currently printing on that printer. In either case, the cancellation of a request that is currently printing frees the printer to print its next available request. OPTIONS The following options to Ip may appear in any order and may be intermixed with file names: -c Make copies of the filenames to be printed immediately when lp is invoked. Otherwise, filenames will not be copied, but will be linked whenever possible. If the -c option is not given, then the user should be careful not to remove any of the filenames before the request has been printed in its entirety. It should also be noted that in the absence of the — c option, any changes made to the named filenames after the request is made but before it is printed will be reflected in the printed output. -m Send mail (see mail(l)) after the files have been printed. By default, no mail is sent upon nor- mal completion of the print request. -s Suppress messages from lp{ 1) such as ‘request id is . . -w Write a message on the user’s terminal after the filenames have been printed. If the user is not logged in locally, then mail will be sent instead. -d dest Choose dest as the printer that is to do the printing. By default, dest is taken from the environ- ment variable LPDEST (if it is set). Otherwise, dest will be taken from the environment vari- able PRINTER. If PRINTER is not defined either, then the default destination for the computer system is used. Destination names vary between systems (see lpstat(l)). — n number Print number copies (default of 1) of the output. — o option Specify printer-dependent options. Several such options may be collected by specifying the -o option more than once. -t title Print title on the banner page of the output. FILES /etc/termcap SEE ALSO lpstat(l), lpr(l), Iprm(l), mail(l), lpc(8), lpd(8) 288 Last change: 21 June 1988 Sun Release 4.1 LPQ(l) USER COMMANDS LPQ(l) NAME lpq - display the queue of printer jobs SYNOPSIS lpq [ -P printer ] [ -1 ] [ + [ interval ] ] [ job# . . . ] [ username ... ] DESCRIPTION lpq displays the contents of a printer queue. It reports the status of jobs specified by job#, or all jobs owned by the user specified by username. lpq reports on all jobs in the default printer queue when invoked with no arguments. For each print job in the queue, lpq reports the user’s name, current position, the names of input files comprising the job, the job number (by which it is referred to when using lprm(l)) and the total size in bytes. Normally, only as much information as will fit on one line is displayed. Jobs are normally queued on a first-in-first-out basis. Filenames comprising a job may be unavailable, such as when Ipr is used at the end of a pipeline; in such cases the filename field indicates “(standard input)”. If lpq warns that there is no daemon present (that is, due to some malfunction), the lpc(8) command can be used to restart a printer daemon. OPTIONS -P printer Display information about the queue for the specified printer. In the absence of the -P option, the queue to the printer specified by the PRINTER variable in the environment is used. If the PRINTER variable isn’t set, the queue for the default printer is used. -1 Display queue information in long format; includes the name of the host from which the job originated. +[ interval ] Display the spool queue periodically until it empties. This option clears the terminal screen before reporting on the queue. If an interval is supplied, lpq sleeps that number of seconds in between reports. FILES /etc/termcap /etc/printcap /var/spool/l* /var/spool/l*/cf* /var/spool/l*/lock for manipulating the screen for repeated display to determine printer characteristics spooling directory, as determined from printcap control files specifying jobs lock file to obtain the currently active job SEE ALSO lpr(l), lprm(l), lpc(8), lpd(8) DIAGNOSTICS printer is ready and printing The lpq program checks to see if there is a printer daemon. If the daemon is hung, the super-user can abort the current daemon and start a new one using Ipc(8). Waiting for printer to become ready (offline ?) The daemon could not open the printer device. The printer may be turned off-line. This message can also occur if a printer is out of paper, the paper is jammed, and so on. Another possible cause is that a process, such as an output filter, has exclusive use of the device. The only recourse in this case is to kill the offending process and restart the printer with lpc. waiting for host to come up A daemon is trying to connect to the remote machine named host, in order to send the files in the local queue. If the remote machine is up, lpd on the remote machine is probably dead or hung and should be restarted using lpc . Sun Release 4.1 Last change: 9 September 1987 289 LPQ(l) USER COMMANDS LPQ(l) sending to host The files are being transferred to the remote host, or else the local daemon has hung while trying to transfer the files. Warning: printer is down The printer has been marked as being unavailable with Ipc. Warning: no daemon present The Ipd process overseeing the spooling queue, as indicated in the “lock” file in that directory, does not exist. This normally occurs only when the daemon has unexpectedly died. Check the printer’s error log for a diagnostic from the deceased process; you can restart the printer daemon with lpc. BUGS Ipq may report unreliably. The status as reported may not always reflect the actual state of the printer. Under some circumstances, Ipq reports that a printer is ready and printing when the daemon is, in fact, hung. Output formatting is sensitive to the line length of the terminal; this can result in widely-spaced columns. Ipq is sometimes unable to open various files when the lock file is malformed. 290 Last change: 9 September 1987 Sun Release 4.1 LPR(l) USER COMMANDS LPR(l) NAME lpr - send a job to the printer SYNOPSIS lpr [ -P printer ] [ -# copies ] [ -C class ] [ -Jjob ] [ -T title ] [ -i [ indent ] ] [ -1234 font ] [ -wcols ] [ -r ] [ -m ] [ — h ] [ — s ] [ -filter-option ] [filename . . . ] DESCRIPTION lpr creates a printer job in a spooling area for subsequent printing as facilities become available. Each printer job consists of a control file and one or more data files. The data files are copies of (or, with — s , symbolic links to) each filename you specify. The spool area is managed by the line printer daemon, lpd(8). Jobs that specify a printer on a remote machine are forwarded by Ipd. lpr reads from the standard input if no files are specified. OPTIONS -P printer Send output to the named printer. Otherwise send output to the printer named in the PRINTER environment variable, or to the default printer, lp. -ttcopies Produce the number of copies indicated for each named file. For example: example % lpr — #3 index.c lookup.c produces three copies of index.c, followed by three copies of lookup.c. On the other hand, example% cat index.c lookup.c | lpr-#3 generates three copies of the concatenation of the files. -C class Print class as the job classification on the burst page. For example, examp le% lpr — C Operations new.index.c replaces the system name (the name returned by hostname) with “Operations” on the burst page, and prints the file new.index.c . -3job Print job as the job name on the burst page. Normally, lpr uses the first file’s name. -T title Use title instead of the file name for the title used by pr(lV). -i[ indent ] Indent output indent SPACE characters. Eight SPACE characters is the default. The indent is passed to the input filter. If no input filter is present, this option is ignored. -1 font -2 font -3 font -4 font Mount the specified font on font position 1, 2, 3 or 4. The daemon will construct a .rail- mag file in the spool directory that indicates the mount by referencing /usr/lib/vfont/font. -w cols Use cols as the page width for pr. -r Remove the file upon completion of spooling, or upon completion of printing with the -s option. -m Send mail upon completion. -h Suppress printing the burst page. -s Create a symbolic link from the spool area to the data files rather than trying to copy them (so large files can be printed). This means the data files should not be modified or removed until they have been printed. This option can be used to avoid truncating files larger than the maximum given in the mx capability of the printcap(5) entry, -s only prevents copies of local files from being made. Jobs from remote hosts are copied any- way. -s only works with named data files; if the lpr command is at the end of a pipe- line, the data is copied to the spool. Sun Release 4.1 Last change: 28 August 1989 291 LPR(l) USER COMMANDS LPR(l) filter-option The following single letter options notify the line printer spooler that the files are not standard text files. The spooling daemon will use the appropriate filters to print the data accordingly. -p Use pr to format the files (Ipr -p is very much like ‘pr | lpr’). -1 Print control characters and suppress page breaks. -t The files contain troff(l) (cat phototypesetter) binary data. -n The files contain data from ditroff (device independent troff). -d The files contain data from tex (DVI format from Stanford). -g The files contain standard plot data as produced by the plot(3X) routines (see also plot(lG) for the filters used by the printer spooler). -v The files contain a raster image, see rasterfile(5). The printer must support an appropriate imaging model such as PostScript in order to print the image. -c The files contain data produced by cifplot. -f Interpret the first character of each line as a standard FORTRAN carriage control character. If no filter-option is given (and the printer can interpret PostScript), the string '%!’ as the first two characters of a file indicates that it contains PostScript commands. These filter options offer a standard user interface, and all options may not be available for, nor applicable to, all printers. FILES /etc/passwd /etc/printcap /usr/lib/lpd /var/spool/l* /var/spool/I*/cf* /var/spool/l*/df* /var/spool/l*/tf* /usr/lib/vfont/font personal identification printer capabilities data base line printer daemon directories used for spooling daemon control files data files specified in ‘cf’ files temporary copies of ‘cf’ files SEE ALSO lpq(l), lprm(l), plot(lG), pr(lV), screendump(l), troff(l), plot(3X), printcap(5), rasterfile(5), lpc(8), lpd(8) DIAGNOSTICS lpr: copy file is too large A file is determined to be too “large” to print by copying into the spool area, lpr truncates the file, and prints as much of it as it can. The maximum file length is specified by the mx capability of the printcap(5) entry for the printer. If no mx capability is specified, the default limit is 1000 Kbytes. Use the -s option as defined above to make a symbolic link to the file instead of copying it. lpr: printer : unknown printer The printer was not found in the printcap database. Usually this is a typing mistake; however, it may indicate a missing or incorrect entry in the /etc/printcap file. lpr: printer : jobs queued, but cannot start daemon. The connection to lpd on the local machine failed. This usually means the printer server started at boot time has died or is hung. Check the local socket /dev/printer to be sure it still exists (if it does not exist, there is no lpd process running). 292 Last change: 28 August 1989 Sun Release 4.1 LPR(l) USER COMMANDS LPR ( 1 ) lpr: printer : printer queue is disabled This means the queue was turned off with example % /usr/etc/lpc disable printer to prevent lpr from putting files in the queue. This is normally done by the system manager when a printer is going to be down for a long time. The printer can be turned back on by a super-user with Ipc. If a connection to lpd on the local machine cannot be made lpr will say that the daemon cannot be started. Diagnostics may be printed in the daemon log file regarding missing spool files by lpd. BUGS Command-line options cannot be combined into a single argument as with some other commands. The command: lpr -fs is not equivalent to lpr -f-s Placing the -s flag first, or writing each option as a separate argument, makes a link as expected. lpr -p is not precisely equivalent to pr | lpr. lpr -p puts the current date at the top of each page, rather than the date last modified. Fonts for troff(l) and T £ X® reside on the printer host. It is currently not possible to use local font libraries. lpr refuses to print a.out files and library archives. The -s option only avoids copying the data file to the spool directory of the local machine. If the printer for a job resides on a remote machine, the data file will be copied to the remote spool directory in all cases. Sun Release 4.1 Last change: 28 August 1989 293 LPRM(l) USER COMMANDS LPRM(l) NAME lprm - remove jobs from the printer queue SYNOPSIS lprm [ -P printer ] [ - ] [job # ... ] [ username . . . ] DESCRIPTION lprm removes a job or jobs from a printer’s spooling queue. Since the spool directory is protected from users, using lprm is normally the only method by which a user can remove a job. Without any arguments, lprm deletes the job that is currently active, provided that the user who invoked lprm owns that job. When the super-user specifies a username, lprm removes all jobs belonging to that user. You can remove a specific job by supplying its job number as an argument, which you can obtain using lpq(l). For example: example % Ipq-Phost host is ready and printing Rank Owner Job Files Total Size active wendy 385 standard input 35501 bytes example % lprm -Phost 385 lprm reports the names of any files it removes, and is silent if there are no applicable jobs to remove. lprm kills the active printer daemon, if necessary, before removing spooled jobs; it restarts the daemon when through. OPTIONS -P printer Specify the queue associated with a specific printer. Otherwise the value of the PRINTER variable in the environment is used. If this variable is unset, the queue for the default printer is used. — Remove all jobs owned by you. If invoked by the super-user, all jobs in the spool are removed. (Job ownership is determined by the user’s login name and host name on the machine where the lpr command was invoked). FILES /etc/printcap /var/spool/* /var/spool/l*/lock printer characteristics file spooling directories lock file used to obtain the pid of the current daemon and the job number of the currently active job SEE ALSO lpr(l), lpq(l)> lpd(8) DIAGNOSTICS lprm: printer: cannot restart printer daemon The connection to lpd on the local machine failed. This usually means the printer server started at boot time has died or is hung. If it is hung, the master lpd(8) daemon may have to be killed and a new one started. BUGS Since race conditions are possible when updating the lock file, an active job may be incorrectly identified for removal by an lprm command issued with no arguments. During the interval between an lpq(l) com- mand and the execution of lprm, the next job in line may have become active; that job may be removed unintentionally if it is owned by you. To avoid this, supply lprm with the job number to remove when a critical job that you own is next in line. Only the super-user can remove print jobs submitted from another host. 294 Last change: 7 September 1988 Sun Release 4.1 LPSTAT ( 1 ) USER COMMANDS LPSTAT ( 1 ) NAME lpstat - display the printer status information SYNOPSIS lpstat [ -d ] [ -r ] [ -s ] [ -t ] [ -a [ list ] ] [ -c [ list ] ] [ -o [ list ] ] [ -p [ list ] ] [ -u [ list ] ] [ -v [ list ] ] DESCRIPTION lpstat prints information about the current status of the printer spooling system. If no options are given, then lpstat prints the status of all requests made to Ip(l) by the user. When the destination printer is not explicitly specified, the value of the LPDEST environment variable is used by default. If LPDEST is not defined, then the value of the PRINTER environment variable is used. If PRINTER is not defined either, then the system default printer is used. Any arguments that are not options are assumed to be request ids (as returned by Ip), lpstat prints the status of such requests. OPTIONS The options below may appear in any order and may be repeated and intermixed with other arguments. Some of the options below may be followed by an optional list that can be in one of two forms: a list of items separated from one another by a comma, or a list of items enclosed in double quotes and separated from one another by a comma and/or one or more SPACE characters. For example: -u"userl, user2, user3" The omission of a list following such options prints all information relevant to the option, for example: lpstat -o prints the status of all output requests. -d Print the system default destination for output requests. -r Print the status of the printer request scheduler -s Print a status summary, including the status of the line printer scheduler, the system default destination, a list of class names and their members, and a list of printers and their associated devices. -t Print all status information. -a[ to] Print acceptance status of destinations for output requests, list is a list of intermixed printer names. -c[to] Print class names and their members, to is a list of class names. — o[ list] Print the status of output requests, list is a list of intermixed printer names, class names, and request ids. -p[ list ] Print the status of printers, list is a list of printer names. — u[ list ] Print status of output requests for users on the default printer, list is a list of login names. — v[ to] Print the names of printers and the path names of the devices associated with them, list is a list of printer names. FILES /usr/spool/lp SEE ALSO lp(l), lpr(l), lprm(l), Ipc(8), lpd(8) Sun Release 4.1 Last change: 21 June 1988 295 LPTEST ( 1 ) USER COMMANDS LPTEST ( 1 ) NAME lptest - generate lineprinter ripple pattern SYNOPSIS lptest [ length [ count ] ] DESCRIPTION lptest writes the traditional "ripple test" pattern on standard output. In 96 lines, this pattern will print all 96 printable ASCII characters in each position. While originally created to test printers, it is quite useful for testing terminals, driving terminal ports for debugging purposes, or any other task where a quick supply of random data is needed. The length argument specifies the output line length if the default length of 79 is inappropriate. The count argument specifies the number of output lines to be generated if the default count of 200 is inap- propriate. Note that if count is to be specified, length must be also be specified. 296 Last change: 16 February 1988 Sun Release 4.1 LS(1V) USER COMMANDS LS(1V) NAME Is - list the contents of a directory SYNOPSIS Is [ — aAcCdfFgilLqrRstul ] filename . . . SYSTEM V SYNOPSIS /usr/5bin/ls [ -abcCdfFgilLmnopqrRstux ] filename . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION For each filename which is a directory, Is lists the contents of the directory; for each filename which is a file, Is repeats its name and any other information requested. By default, the output is sorted alphabetically. When no argument is given, the current directory is listed. When several arguments are given, the argu- ments are first sorted appropriately, but file arguments are processed before directories and their contents. In order to determine output formats for the -C, -x, and -m options, /usr/5bin/ls uses an environment variable, COLUMNS, to determine the number of character positions available on one output line. If this variable is not set, the terminfo database is used to determine the number of columns, based on the environment variable TERM. If this information cannot be obtained, 80 columns are assumed. Permissions Field The mode printed under the -1 option contains 10 characters interpreted as follows. If the first character is: d entry is a directory; b entry is a block-type special file; c entry is a character-type special file; I entry is a symbolic link; p entry is a FIFO (also known as “named pipe”) special file; s entry is an AF_UNIX address family socket, or - entry is a plain file. The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner permis- sions; the next refers to permissions to others in the same user- group; and the last refers to all others. Within each set the three characters indicate permission respectively to read, to write, or to execute the file as a program. For a directory, “execute” permission is interpreted to mean permission to search the direc- tory. The permissions are indicated as follows: r the file is readable; w the file is writable; x the file is executable; - the indicated permission is not granted. The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the owner-execute permission character is given as s if the file has the set-user-id bit set. The last character of the mode (normally x or is t if the 1000 bit of the mode is on. See chmod(lV) for the meaning of this mode. The indications of set-ID and 1000 bits of the mode are capitalized (S and T respectively) if the corresponding execute permission is not set. When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is printed. OPTIONS -a List all entries; in the absence of this option, entries whose names begin with a V are not listed (except for the super-user, for whom Is, but not /usr/5bin/ls, normally prints even files that begin with a *.’)• -A (Is only) Same as -a, except that V and 1 ..’ are not listed. Sun Release 4.1 Last change: 2 October 1989 297 LS(1V) USER COMMANDS LS(1V) -c Use time of last edit (or last mode change) for sorting or printing. -C Force multi-column output, with entries sorted down the columns; for Is, this is the default when output is to a terminal. -d If argument is a directory, list only its name (not its contents); often used with -1 to get the status of a directory. -f Force each argument to be interpreted as a directory and list the name found in each slot. This option turns off -1, -t, -s, and -r, and turns on -a; the order is the order in which entries appear in the directory. -F Mark directories with a trailing slash (*/’), executable files with a trailing asterisk ('*’), symbolic links with a trailing at-sign (‘@’). and AF_UNIX address family sockets with a trailing equals sign ('=’)• -g For Is, show the group ownership of the file in a long output. For /usr/5bin/ls, print a long listing, the same as — 1, except that the owner is not printed. -i For each file, print the i-number in the first column of the report. -1 List in long format, giving mode, number of links, owner, size in bytes, and time of last modification for each file. If the file is a special file the size field will instead contain the major and minor device numbers. If the time of last modification is greater than six months ago, it is shown in the format ‘month date year'-, files modified within six months show ‘ month date time'. If the file is a symbolic link the pathname of the linked-to file is printed preceded by ‘ — >’. /usr/5bin/ls will print the group in addition to the owner. -L If argument is a symbolic link, list the file or directory the link references rather than the link itself. -q Display non-graphic characters in filenames as the character ?; for Is, this is the default when out- put is to a terminal. -r Reverse the order of sort to get reverse alphabetic or oldest first as appropriate. -R Recursively list subdirectories encountered. -s Give size of each file, including any indirect blocks used to map the file, in kilobytes (Is) or 512- byte blocks (/usr/5bin/ls). -t Sort by time modified (latest first) instead of by name. -u Use time of last access instead of last modification for sorting (with the -t option) and/or printing (with the -1 option). -1 (Is only) Force one entry per line output format; this is the default when output is not to a terminal. SYSTEM V OPTIONS -b Force printing of non-graphic characters to be in the octal \ddd notation. -m Stream output format; the file names are printed as a list separated by commas, with as many entries as possible printed on a line. -n The same as -I, except that the owner’s UID and group’s GID numbers are printed, rather than the associated character strings. -o The same as -1, except that the group is not printed. -p Put a slash (7’) after each filename if that file is a directory. -x Multi-column output with entries sorted across rather than down the page. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_defauIt control the character classification throughout Is. On entry to Is, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character 298 Last change: 2 October 1989 Sun Release 4.1 LS(1V) USER COMMANDS LS(1V) classification are ignored. For example, a new setting for LANG does not override the current valid charac- ter classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /etc/passwd to get user ID’s for ‘Is -I’ and is -o’. /etc/group to get group ID for is -g’ and ‘/usr/5bin/ls -1’. /usr/share/lib/terminfo/* to get terminal information for /usr/5bin/Is. SEE ALSO chmod(lV) BUGS NEWLINE and TAB are considered printing characters in filenames. The output device is assumed to be 80 columns wide. The option setting based on whether the output is a teletype is undesirable as ‘Is -s’ is much different than is -s I lpr’. On the other hand, not doing this setting would make old shell scripts which used Is almost certain losers. None of the above apply to /usr/5bin/ls. Unprintable characters in file names may confuse the columnar output options. Sun Release 4.1 Last change: 2 October 1989 299 LSW(l) USER COMMANDS LSW(l) NAME lsw - list TFS whiteout entries SYNOPSIS lsw filename . . . DESCRIPTION For each filename that is a directory, lsw lists the whiteout entries in that directory. These whiteout entries are created by the translucent file service See tfs(4S). SEE ALSO unwhiteout(l), tfs(4S), mount_tfs(8), tfsd(8) 300 Last change: 23 November 1988 Sun Release 4.1 M4 ( IV ) USER COMMANDS M4 ( 1 V ) NAME m4 - macro language processor SYNOPSIS m4 [ filename ] ... SYSTEM V SYNOPSIS /usr/5bin/m4 [ -es ] [ -Bint ] [ -Hint ] [ -Sint ] [ -Tint ] [ -D name=val ] [ -U name ] [ filename ]... AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION m4 is a macro processor intended as a front end for Ratfor, C, and other languages. Each of the argument files is processed in order; if there are no files, or if a file name is the standard input is read. The pro- cessed text is written on the standard output. Macro calls have the form: name{argumentl[, argument2 , . . .,] argumentn ) The ‘(’ must immediately follow the name of the macro. If the name of a defined macro is not followed by a it is interpreted as a call of the macro with no arguments. Potential macro names consist of letters, digits, and (underscores) where the first character is not a digit. Leading unquoted SPACE, TAB, and NEWLINE characters are ignored while collecting arguments. Left and right single quotes (‘ ’) are used to quote strings. The value of a quoted string is the string stripped of the quotes. When a macro name is recognized, the arguments are collected by searching for a matching right parenthesis. If fewer arguments are supplied than are in the macro definition, the trailing arguments are taken to be NULL. Macro evaluation proceeds normally during the collection of the arguments, and any commas or right parentheses which happen to turn up within the value of a nested call are as effective as those in the original input text. After argument collection, the value of the macro is pushed back onto the input stream and rescanned. SYSTEM V OPTIONS The options and their effects are as follows: -e Operate interactively. Interrupts are ignored and the output is unbuffered. -s Enable line sync output for the C preprocessor (#line . . . ) -Bint Change the size of the push-back and argument collection buffers from the default of 4,096. -Hint Change the size of the symbol table hash array from the default of 199. The size should be prime. -Sint Change the size of the call stack from the default of 100 slots. Macros take three slots, and non- macro arguments take one. -Tint Change the size of the token buffer from the default of 512 bytes. To be effective, these flags must appear before any file names and before any -D or -U flags: -D name[=val] Define filename to be val or to be NULL in val’s absence. -U name Undefine name. USAGE Built-In Macros m4 makes available the following built-in macros. They may be redefined, but once this is done the origi- nal meaning is lost. Their values are NULL unless otherwise stated. Sun Release 4.1 Last change: 23 September 1987 301 M4(1V) USER COMMANDS M4( IV) define The second argument is installed as the value of the macro whose name is the first argu- ment. Each occurrence of $n in the replacement text, where n is a digit, is replaced by the n’th argument. Argument 0 is the name of the macro; missing arguments are replaced by the NULL string. undefine Remove the definition of the macro named in the argument. ifdef If the first argument is defined, the value is the second argument, otherwise the third. If there is no third argument, the value is NULL. The word unix is predefined. changequote Change quote characters to the first and second arguments, changequote without arguments restores the original values (that is, ‘ ’)• divert m4 maintains 10 output streams, numbered 0-9. The final output is the concatenation of the streams in numerical order; initially stream 0 is the current stream. The divert macro changes the current output stream to the (digit-string) argument. Output diverted to a stream other than 0 through 9 is discarded. undivert Display immediate output of text from diversions named as arguments, or all diversions if no argument. Text may be undiverted into another diversion. Undiverting discards the diverted text. divnum Return the value of the current output stream. dnl Read and discard characters up to and including the next NEWLINE. ifelse Has three or more arguments. If the first argument is the same string as the second, then the value is the third argument. If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6, 7 and so on. Otherwise, the value is either the last string not used by the above process, or, if it is not present, NULL. incr Return the value of the argument incremented by 1. The value of the argument is calculated by interpreting an initial digit-string as a decimal number. eval Evaluate the argument as an arithmetic expression, using 32-bit arithmetic. Operators include + (exponentiation); relational; parentheses. len Return the number of characters in the argument. index Return the position in the first argument where the second argument begins (zero origin), or -1 if the second argument does not occur. substr Return a substring of the first argument. The second argument is a zero origin number selecting the first character; the third argument indicates the length of the substring. A miss- ing third argument is taken to be large enough to extend to the end of the first string. translit Transliterate the characters in the first argument from the set given by the second argument to the set given by the third. No abbreviations are permitted. include Return the contents of the file named in the argument. sinclude Is similar to include, except that it says nothing if the file is inaccessible. syscmd Execute the system command given in the first argument. No value is returned. maketemp Fill in a string of XXXXX in the argument with the current process ID. errprint Print the argument on the diagnostic output file. dumpdef Print current names and definitions, for the named items, or for all if no arguments are given. SYSTEM V USAGE In the System V version of m4, the following built-in macros have added capabilities. 302 Last change: 23 September 1987 Sun Release 4.1 M4(1V) USER COMMANDS M4( IV) Built-In Macros define '$#’ is replaced by the number of arguments; $* is replaced by a list of all the arguments separated by commas; $@ is like but each argument is quoted (with the current quotes). changequote Change quote symbols to the first and second arguments. The symbols may be up to five characters long. eval Additional operators include bitwise *&’, ‘| and Octal, decimal and hex numbers may be specified as in C. The second argument specifies the radix for the result; the default is 10. The third argument may be used to specify the minimum number of digits in the result. The System V version of m4 makes available the following additional built-in macros. defn Return the quoted definition of the argument(s). It is useful for renaming macros, especially built-ins. pushdef popdef shift changecom deer sysval m4exit m4wrap traceon traceoff SEE ALSO cc(lV) Like define, but saves any previous definition. Remove current definition of the argument(s), exposing the previous one, if any. Return all but the first argument. The other arguments are quoted and pushed back with commas in between. The quoting nullifies the effect of the extra scan that will subsequently be performed. Change left and right comment markers from the default # and NEWLINE. With no argu- ments, the comment mechanism is effectively disabled. With one argument, the left marker becomes the argument and the right marker becomes NEWLINE. With two arguments, both markers are affected. Comment markers may be up to five characters long. Return the value of the argument decremented by 1. Return code from the last call to sysemd. Exit immediately from m4. Argument 1, if given, is the exit code; the default is 0. Argument 1 will be pushed back at final EOF. For example, ‘m4wrap(“cleanup( )”)’. With no arguments, turn on tracing for all macros (including built-ins). Otherwise, turn on tracing for named macros. Turn off trace globally and for any macros specified. Macros specifically traced by traceon can be untraced only by specific calls to traceoff. m.4 — A Macro Processor, in Programming Utilities and Libraries NOTES While the compiler allows 8-bit strings and comments, 8-bits are not allowed anywhere else. The cc(lV) command does not generate or support 8-bit symbol names because, until ANSI C, non-ASCII support was not expected. The ANSI C specification now suggests that string literals and comments can contain any characters from any character code set. Sun Release 4.1 Last change: 23 September 1987 303 MACH ( 1 ) USER COMMANDS MACH ( 1 ) NAME mach - display the processor type of the current host SYNOPSIS mach DESCRIPTION The mach command displays the processor-type of the current Sun host. SEE ALSO arch(l), machid(l) 304 Last change: 9 September 1987 Sun Release 4.1 MACHID ( 1 ) USER COMMANDS MACHID (1) NAME machid, sun, iAPX286, m68k, pdpll, spare, u3b, u3b2, u3b5, u3bl5, vax, i386 - return a true exit status if the processor is of the indicated type SYNOPSIS sun iAPX286 m68k pdpll spare u3b u3b2 u3b5 u3bl5 vax i386 DESCRIPTION The following commands will return a true value (exit code of 0) if you are on a processor that the com- mand name indicates. sun True if you are on a Sun system. iAPX286 True if you are on a computer using an iAPX286 processor. i386 True if you are on a computer using an iAPX386 processor. m68k True if you are on a computer, such as a Sun-3 or a Sun-3x, using an M68000-family processor. pdpll True if you are on a PDP-11. spare True if you are on a computer, such as a Sun-4, using a SPARC-family processor. u3b True if you are on a 3B20S computer. u3b2 True if you are on a 3B2 computer. u3b5 True if you are on a 3B5 computer. u3bl5 True if you are on a 3B 15 computer. vax True if you are on a VAX. The commands that do not apply will return a false (non-zero) value. These commands are often used within make(l) makefiles and shell procedures to increase portability. SEE ALSO arch(l), mach(l), make(l), sh(l), test(lV), true(l) Sun Release 4.1 Last change: 18 February 1988 305 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) NAME mail. Mail - read or send mail messages SYNOPSIS Mail [ -deHinNUv ] [ -f [ filename I +folder ] ] [ -T file ] [ -u user ] Mail [ -dFinUv ] [ -h number ] [ -r address ] [ -s subject ] recipient . . . /usr/ucb/mail . . . DESCRIPTION mail is a comfortable, flexible, interactive program for composing, sending and receiving electronic mes- sages. While reading messages, mail provides you with commands to browse, display, save, delete, and respond to messages. While sending mail, mail allows editing and reviewing of messages being com- posed, and the inclusion of text from files or other messages. Incoming mail is stored in the system mailbox for each user. This is a file named after the user in /var/spool/mail. mail normally looks in this file for incoming messages, but you can use the MAIL environment variable to have it look in a different file. When you read a message, it is marked to be moved to a secondary file for storage. This secondary file, called the mbox, is normally the file mbox in your home directory. This file can also be changed by setting the MBOX environment variable. Messages remain in the mbox file until deliberately removed. OPTIONS If no recipient is specified, mail attempts to read messages from the system mailbox. -d Turn on debugging output. (Neither particularly interesting nor recommended.) -e Test for presence of mail. If there is no mail, mail prints nothing and exits (with a suc- cessful return code). -F Record the message in a file named after the first recipient. Override the record variable, if set. -H Print header summary only. -i Ignore interrupts (as with the ignore variable). -n Do not initialize from the system default Mail.rc file. -N Do not print initial header summary. -U Convert uucp style addresses to Internet standards. Overrides the conv environment vari- able. -v Pass the -v flag to sendmail(8). -f [filename] Read messages from filename instead of system mailbox. If no filename is specified, the mbox is used. -f +folder Use the file folder in the folder directory (same as the folder command). The name of this directory is listed in the folder variable. -h number The number of network “hops” made so far. This is provided for network software to avoid infinite delivery loops. -r address Pass address to network delivery software. All tilde (-) commands are disabled. -s subject Set the Subject header field to subject. —T file Print the contents of the article-id fields of all messages that were read or deleted on file (for the use of network news programs if available). -u user Read user's system mailbox. This is only effective if user's system mailbox is not read protected. 306 Last change: 19 December 1988 Sun Release 4.1 MAIL(l) USER COMMANDS MAIL ( 1 ) USAGE Refer to SunOS User’s Guide: Getting Started for tutorial information about mail. Starting Mail As it starts, mail reads commands from a system-wide file (/usr/lib/Mail.rc) to initialize certain variables, then it reads from a private start-up file called the .mailrc file (it is normally the file .mailrc in your home directory, but can be changed by setting the MAILRC environment variable) for your personal commands and variable settings. Most mail commands are legal inside start-up files. The most common uses for this file are to set up initial display options and alias lists. The following commands are not legal in the start-up file: !, Copy, edit, followup, Followup, hold, mail, preserve, reply. Reply, replyall, replysender, shell, and visual. Any errors in the start-up file cause the remaining lines in that file to be ignored. You can use the mail command to send a message directly by including names of recipients as arguments on the command line. When no recipients appear on the mail command line, it enters command mode, from which you can read messages sent to you. If you list no recipients and have no messages, mail prints the message: ‘No mail for username' and exits. When in command mode (while reading messages), you can send messages using the mail command. Sending Mail While you are composing a message to send, mail is in input mode. If no subject is specified as an argu- ment to the command a prompt for the subject is printed. After entering the subject line, mail enters input mode to accept the text of your message to send. As you type in the message, mail stores it in a temporary file. To review or modify the message, enter the appropriate tilde escapes, listed below, at the beginning of an input line. To indicate that the message is ready to send, type a dot (or EOF character, normally CTRL-D ) on a line by itself, mail submits the message to sendmail(8) for routing to each recipient. Recipients can be; © local usernames ® Internet addresses of the form: name@domain s uucp(lC) addresses of the form: [hostl. . .host\]host\username ® filenames for which you have write permission • alias groups If the name of the recipient begins with a pipe symbol ( | ), the remainder of the name is taken as a shell command to pipe the message through. This provides an automatic interface with any program that reads the standard input, such as lpr(l) to record outgoing mail on paper. An alias group is the name of a list of recipients that is set by the alias command, taken from the host’s /etc/aliases file, or taken from the Net- work Information Service (NIS) aliases domain. See aliases(5) for more information about mail addresses and aliases. Tilde Escapes The following tilde escape commands can be used when composing messages to send. Each must appear at the beginning of an input line. The escape character ( —), can be changed by setting a new value for the escape variable. The escape character can be entered as text by typing it twice. -! [ shell-command ] Escape to the shell. If present, run shell-command. Simulate EOF (terminate message input). Sun Release 4.1 Last change: 19 December 1988 307 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) mail-command. — _ mail-command Perform the indicated mail command. Valid only when sending a message while reading mail. -? Print a summary of tilde escapes. ~A Insert the autograph string Sign into the message. -a Insert the autograph string sign into the message. ~b name . . . Add the name s to the blind carbon copy (Bcc) list. This is like the carbon copy (Cc) list, except that the names in the Bcc list are not shown in the header of the mail message. ~c name . . . Add the names to the carbon copy (Cc) list. ~d Read in the dead.letler file. The name of this file is listed in the variable DEAD. ~e Invoke the editor to edit the message. The name of the editor is listed in the EDITOR variable. The default editor is ex(l). ~f [message-list] Forward the listed messages, or the current message being read. Valid only when sending a mes- sage while reading mail; the messages are inserted without alteration (as opposed to the ~m escape). -h Prompt for the message header lines: Subject, To, Cc, and Bcc. If the header line contains text, you can edit the text by backspacing over it and retyping. -i variable Insert the value of the named variable into the message. ~m [message-list] Insert text from the specified messages, or the current message, into the letter. Valid only when sending a message while reading mail; the text the message is shifted to the right, and the string contained in the indentprefix variable is inserted as the leftmost characters of each line. If indentprefix is not set, a TAB character is inserted into each line. ~p Print the message being entered. ~q Quit from input mode by simulating an interrupt. If the body of the message is not empty, the par- tial message is saved in the dead.letter file. ~r filename ~< filename - in the header summary. For commands that take an optional list of messages, if you omit a message number as an argument, the command applies to the current message. A message-list is a list of message specifications, separated by SPACE characters, which may include: . The current message. n Message number n. The first undeleted message. $ The last message. + The next undeleted message. - The previous undeleted message. * All messages. n-m An inclusive range of message numbers. user All messages from user. /string All messages with string in the subject line (case ignored). :c All messages of type c, where c is one of: d deleted messages n new messages o old messages r read messages u unread messages Note: the context of the command determines whether this type of message specification makes sense. Additional arguments are treated as strings whose usage depends on the command involved. Filenames, where expected, are expanded using the normal shell filename-substitution mechanism. Special characters, recognized by certain commands, are documented with those commands. Commands While in command mode, if you type in an empty command line (a RETURN or NEWLINE only), the print command is assumed. The following is a complete list of mail commands: ! shell-command Escape to the shell. The name of the shell to use is listed in the SHELL variable. # arguments Null command. This may be used as if it were a comment in .mailrc files, but note that it must be separated from its arguments (commentary) by white space. = Print the current message number. ? Print a summary of commands. alias [alias recipient ...] group [alias recipient ...] Declare an alias for the given list of recipients. The list will be substituted when the alias is used as a recipient while sending mail. When put in the .mailrc file, this command provides you with a record of the alias. With no arguments, the command displays the list of defined aliases. alternates name . . . Declare a list of alternate names for your login. When responding to a message, these names are removed from the list of recipients for the response. With no argu- ments, alternates prints the current list of alternate names. Sun Release 4.1 Last change: 19 December 1988 309 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) cd[ directory] chdir [directory] Change directory. If directory is not specified, SHOME is used, copy [message-list] [filename ] Copy messages to the file without marking the messages as saved. Otherwise equivalent to the save command. Copy [message-list] Save the specified messages in a file whose name is derived from the author of the message to be saved, without marking the messages as saved. Otherwise equivalent to the Save command. delete [message-list] Delete messages from the system mailbox. If the variable autoprint is set, print the message following the last message deleted. discard [header-field . . .] ignore [header-field. . .] Suppress printing of the specified header fields when displaying messages on the screen, such as “Status” and “Received”. The fields are included when the message is saved unless the variable alwaysignore is set. The Print and Type commands display all header fields, ignored or not. dp [message-list] dt [message-list] Delete the specified messages from the system mailbox, and print the message after the last one deleted. Equivalent to a delete command followed by a print command. echo [string . . . ] Echo the given strings (like echo(lV)). edit [message-list] Edit the given messages. The messages are placed in a temporary file and the EDI- TOR variable is used to get the name of the editor. The default editor is ex(l). exit xit Exit from mail without changing the system mailbox. No messages are saved in the mbox (see also quit). file [filename ] folder [filename ] Quit from the current mailbox file and read in the named mailbox file. Several spe- cial characters are recognized when used as file names: % Your system mailbox. %user The system mailbox for user. # The previous mail file. & Your mbox file (of messages previously read). +filename The named file in the folder directory (listed in the folder vari- able). With no arguments, file prints the name of the current mail file, and the number of messages and characters it contains. folders Print the name of each mail file in the folder directory (listed in the folder variable). followup [message] Respond to a message, recording the response in a file, name of which is derived from the author of the message (overrides the record variable, if set). See also the Followup, Save, and Copy commands and the outfolder variable. Followup [message-list] Respond to the first message in the message list, sending the message to the author of each message in the list. The subject line is taken from the first message, and the response is recorded in a file, the name of which is derived from the author of the first message (overrides the record variable, if set). See also the followup. Save, and Copy commands and the outfolder variable. from [message-list] Print the header summary for the indicated messages or the current message. 310 Last change: 19 December 1988 Sun Release 4.1 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) group alias name . . . Same as the alias command. headers [ message ] Print the page of headers that includes the message specified, or the current message. The screen variable sets the number of headers per page. See also the z command. help Print a summary of commands. hold [message-list] preserve [message-list] Hold the specified messages in the system mailbox. ifslrlr mail-command else mail-command endif Conditional execution, where s will execute following mail-command up to an else or endif, if the program is in send mode, r executes the mail-command only in receive mode, and t executes the mail-command only if mail is being run from a ter- minal. Useful primarily in the .mailrc file. ignore [ header-field . . . ] Same as the discard command. inc Incorporate messages that arrive while you are reading the system mailbox. The new messages are added to the message list in the current mail session. This com- mand does not commit changes made during the session, and prior messages are not renumbered. list Prints all commands available. No explanation is given, load [message] filename Load the specified message from the name file, filename should contain a single mail message including mail headers (as saved by the save command). Mail a message to the specified recipients. Arrange for the given messages to end up in the standard mbox file when mail ter- minates normally. See also the exit and quit commands. New [message-list] unread [message-list] Unread [message-list] Take a message list and mark each message as not having been read. next message Go to next message matching message. A message-list can be given instead of mes- sage, but only first valid message in the list is used. (This can be used, for instance, to jump to the next message from a specific user.) pipe [message-list] [shell-command] | [message-list] [shell-command] Pipe the message through shell-command. The message is treated marked as read (and normally saved to the mbox file when mail exits). If no arguments are given, the current message is piped through the command specified by the value of the cmd variable. If the page variable is set, a form feed character is inserted after each mes- sage. preserve [message-list] Same as the hold command. mail recipient . . . mbox [message-list] new [message-list] Sun Release 4. 1 Last change: 19 December 1988 311 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) print [message-list] type [ message-list ] Print the specified messages. If the crt variable is set, messages longer than the number of lines it indicates paged through the command specified by the PAGER variable. The default paging command is more(l). Print [ message-list ] Type [message-list] Print the specified messages on the screen, including all header fields. Overrides suppression of fields by the ignore and retain commands. quit Exit from mail storing messages that were read in the mbox file and unread messages in the system mailbox. Messages that have been explicitly saved in a file are deleted unless the variable keepsave is set. reply [message-list] respond [message-list] replysender [message-list] Send a response to the author of each message in the message-list. The subject line is taken from the first message. If record is set to a filename, a copy of the reply is added to that file. If the replyall variable is set, the actions of Reply/Respond and reply/respond are reversed. The replysender command is not affected by the replyall variable, but sends each reply only to the sender of each message. Reply [message] Respond [message] replyall [message] Reply to the specified message, including all other recipients of that message. If the variable record is set to a filename, a copy of the reply added to that file. If the replyall variable is set, the actions of Reply/Respond and reply/respond are reversed. The replyall command is not affected by the replyall variable, but always sends the reply to all recipients of the message. retain Add the list of header fields named to the retained list. Only the header fields in the retain list are shown on your terminal when you print a message. All other header fields are suppressed. The set of retained fields specified by the retain command overrides any list of ignored fields specified by the ignore command. The Type and Print commands can be used to print a message in its entirety. If retain is executed with no arguments, it lists the current set of retained fields. save [message-list] [filename] Save the specified messages in the named file. The file is created if it does not exist. If no filename is specified, the file named in the MBOX variable is used, mbox in your home directory by default. Each saved message is deleted from the system mailbox when mail terminates unless the keepsave variable is set. See also the exit and quit commands. Save [message-list] Save the specified messages in a file whose name is derived from the author of the first message. The name of the file is taken from the author’s name, with all network addressing stripped off. See also the Copy, followup, and Followup commands and the outfolder variables. value] ] Define a variable. To assign a value to variable, separate the variable name from the value by an '=’ (there must be no space before or after the *=’). A variable may be given a null, string, or numeric value. To embed SPACE characters within a value enclose it in quotes. With no arguments, set displays all defined variables and any values they might have. See Variables for a description of all predefined mail variables. Invoke the interactive shell listed in the SHELL variable. set [variable [= shell 312 Last change: 19 December 1988 Sun Release 4.1 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) size [ message-list ] Print the size in characters of the specified messages. source filename Read commands from the given file and return to command mode. top [ message-list ] Print the top few lines of the specified messages. If the toplines variable is set, it is taken as the number of lines to print. The default number is 5. touch [message-list] Touch the specified messages. If any message in message-list is not specifically saved in a file, it will be placed in the mbox upon normal termination. See also the exit and quit commands. type [ message-list ] Same as the print command. Type [ message-list ] Same as the Print command, undelete [message-list] Restore deleted messages. This command only restores messages deleted in the current mail session. If the autoprint variable is set, the last message restored is printed. unread [message-list] Unread [message-list] Same as the new command. unset variable . . . Erase the specified variables. If the variable was imported from the environment (that is, an environment variable or exported shell variable), it cannot be unset from within mail. version Print the current version and release date of the mail utility. visual [message-list] Edit the given messages with the screen editor listed in the VISUAL variable. The default screen editor is vi(l). Each message is placed in a temporary file for editing. write [message-list] [filename] Write the given messages onto the specified file, but without the header and trailing blank line. Otherwise, this is equivalent to the save command. xit Same as the exit command. z[ + 1 — ] Scroll the header display forward (+) or backward (-) one screenfull. The number of headers displayed is set by the screen variable. Forwarding Messages To forward a specific message, include it in a message to the desired recipients with the -f or ~m tilde escapes. To forward mail automatically, add a comma-separated list of addresses for additional recipients to the .forward file in your home directory. This is different from the format of the alias command, which takes a space-separated list instead. Note: forwarding addresses must be valid (as described in aliases(5)), or the messages will “bounce.” You cannot, for instance, reroute your mail to a new host by forwarding it to your new address if it is not yet listed in the NIS aliases domain. Variables The behavior of mail is governed by a set of predefined variables that are set and cleared using the set and unset commands. Environment Variables Values for the following variables are read in automatically from the environment; they cannot be altered from within mail: HOME=directory The user’s home directory. MATL=filename The name of the initial mailbox file to read (in lieu of the standard system mailbox). The default is /var/spool/maiI/«rernamc . Sun Release 4.1 Last change: 19 December 1988 313 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) MAlLRC-filename The name of the personal start-up file. The default is $HOME/.mailrc. Mail Variables The following variables can be initialized within the .mailrc file, or set and altered interactively using the set command. They can also be imported from the environment (in which case their values cannot be changed within mail). The unset command clears variables. The set command can also be used to clear a variable by prefixing the word no to the name of the variable to clear. Variables for which values are normally supplied are indicated with an equal-sign (=). The equal-sign is required by the set command, and there can be no spaces between the variable-name, equal-sign, and value, using set to assign a value. allnet All network names whose last component (login name) match are treated as identical. This causes the message fist specifications to behave similarly. Default is noallnet. See also the alternates command and the metoo variable. alwaysignore append askcc asksub autoprint bang Ignore header fields with ignore everywhere, not just during print or type. Affects the save, Save, copy. Copy, top, pipe, and write commands, and the ~m and -f tilde escapes. Upon termination, append messages to the end of the mbox file instead of prepending them. Default is noappend but append is set in the global start-up file (which can be suppressed with the -n command line option). Prompt for the Cc list after message is entered. Default is noaskcc. Prompt for subject if it is not specified on the command line with the -s option. Enabled by default. Enable automatic printing of messages after delete and undelete commands. Default is noautoprint. Enable the special-casing of exclamation points (!) in shell escape command lines as in vi(l). Default is nobang. cmd =shell-command Set the default command for the pipe command. No default value. con \=conversion Convert uucp addresses to the address style specified by conversion , which can be either: internet This requires a mail delivery program conforming to the RFC822 standard for electronic mail addressing. optimize Remove loops in uucp(lC) address paths (typically generated by the reply com- mand). No rerouting is performed; mail has no knowledge of UUCP routes or connections. Conversion is disabled by default. See also sendmail(8) and the -U command line option. crt ^number Pipe messages having more than number lines through the command specified by the value of the PAGER variable ( more by default). Disabled by default. DEAD = filename The name of the file in which to save partial letters in case of untimely interrupt or delivery errors. Default is the file dead.letter in your home directory. debug Enable verbose diagnostics for debugging. Messages are not delivered. Default is node- bug. 314 Last change: 19 December 1988 Sun Release 4.1 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) dot Take a period on a line by itself during input from a terminal as EOF. Default is nodot but dot is set in the global start-up file (which can be suppressed with the -n command line option). editheaders Include message headers in the text to be edited by the "e and "v commands. EDIT OR=shell-command The command to run when the editor ~e command is used. Default is ex(l). escape=c Substitute c for the - escape character. fo\der=directory The directory for saving standard mail files. User specified file names beginning with a plus (+) are expanded by preceding the filename with this directory name to obtain the real filename. If directory does not start with a slash (/), the value of HOME is prepended to it. There is no default for the folder variable. See also outfolder below. header Enable printing of the header summary when entering mail. Enabled by default. hold Preserve all messages that are read in the system mailbox instead of putting them in the standard mbox save file. Default is nohold for mail and hold for mailtool(l). ignore Ignore interrupts while entering messages. Handy for noisy dial-up lines. Default is noignore. ignoreeof Ignore EOF during message input. Input must be terminated by a period (V) on a line by itself or by the command. Default is noignoreeof. See also dot above. indentprefix=sfring When indentprefix is set, string is used to mark indented lines from messages included with -m. The default is a TAB character. keep When the system mailbox is empty, truncate it to zero length instead of removing it. Dis- abled by default. keepsave Keep messages that have been saved in other files in the system mailbox instead of delet- ing them. Default is nokeepsave. \ASTER=shell-command The command (and options) to use when listing the files in the folder directory. The default is ls(lV). MBOX=fdename The name of the file to save messages which have been read. The xit command overrides this variable, as does saving the message explicitly to another file. Default is the file mbox in your home directory. metoo If your login appears as a recipient, do not delete it from the list. Default is nometoo. no When used as a prefix to a variable name, has the effect of unsetting the variable. onehop When responding to a message that was originally sent to several recipients, the other recipient addresses are normally forced to be relative to the originating author’s machine for the response. This flag disables alteration of the recipients’ addresses, improving efficiency in a network where all machines can send directly to all other machines (that is, one “hop” away). outfolder Locate the files used to record outgoing messages in the directory specified by the folder variable unless the pathname is absolute. Default is nooutfolder. See folder above and the Save, Copy, followup, and Followup commands. page Used with the pipe command to insert a form feed after each message sent through the pipe. Default is nopage. Sun Release 4.1 Last change: 19 December 1988 315 MAIL ( 1 ) USER COMMANDS MAIL ( 1 ) P A G ER= sh ell comma ml The command to use as a filter for paginating output, along with any options to be used. Default is more(l). prompt=sm‘ng Set the command mode prompt to string . Default is ‘&\ quiet Refrain from printing the opening message and version when entering mail. Default is noquiet. record=filename Record all outgoing mail in filename. Disabled by default. See also the variable out- folder. replyall Reverse the effect of the reply and Reply commands. save Enable saving of messages in the dead. letter file on interrupt or delivery error. See DEAD for a description of this file. Enabled by default. screen= number Set the number of lines in a screen-full of headers for the headers command. sendmail =s hell-command Alternate command for delivering messages. Note: in addition to the expected list of recipients, mail also passes the — i and -m, flags to the command. Since these flags are not appropriate to other commands, you may have to use a shell script that strips them from the arguments list before invoking the desired command. sendwait Wait for background mailer to finish before returning. Default is nosendwait. SHELL=shell-command The name of a preferred command interpreter. Typically inherited from the environment, the shell is normally the one you always use. Otherwise defaults to sh(l). showto When displaying the header summary and the message is from you, print the recipient’s name instead of the author’s name. s\gn=autograph The autograph text inserted into the message when the ~a (autograph) command is given. No default (see also the ~i tilde escape). Sign=auto graph The autograph text inserted into the message when the ~A command is given. No default (see also the -i tilde escape). to\>\mes=number The number of lines of header to print with the top command. Default is 5. verbose Invoke sendmail with the -v flag. VISU AL=shell-command The name of a preferred screen editor. Default is vi. FILES $HOMEl .mailrc $HOME/ forward $HOMElmbox $HOME Idead.letter /var/spool/mail /usr/lib/Mail.he!p* /usr/lib/Mail.rc /tmp/R[emqsx]* personal start-up file list of recipients for automatic forwarding of messages secondary storage file undeliverable messages file directory for system mailboxes help message files global start-up file temporary files 316 Last change: 19 December 1988 Sun Release 4.1 MAIL(l) USER COMMANDS MAIL ( 1 ) SEE ALSO biff(l), bin-mail(l), echo(lV), ex(l), fmt(l), ls(lV), mailtool(l), more(l), sh(l), uucp(lC), vacation(l), vi(l), aliases(5), newaliases(8), sendmail(8) SunOS User’s Guide: Getting Started mail is found in /usr/ucb/Mail, as a link to /usr/ucb/mail. If you wish to use the original (version 7) UNIX mail program, you can find it in /usr/bin/mail. Its man page is named bin-mail(l). BUGS Where shell-command is shown as valid, arguments are not always allowed. Experimentation is recom- mended. Internal variables imported from the execution environment cannot be unset. Replies do not always generate correct return addresses. Try resending the errant reply with onehop set. mail does not lock your record file. So, if you use a record file and send two or more messages simultane- ously, lines from the messages may be interleaved in the record file. The format for the alias command is a space-separated list of recipients, while the format for an alias in either the .forward or /etc/aliases is a comma-separated list. NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. Sun Release 4. 1 Last change: 19 December 1988 317 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) NAME mailtool - SunView interface for the mail program SYNOPSIS mailtool [ -Mx ] [ -Mi interval ] [ generic-tool-arguments ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION mailtool is the standard SunView interface to mail(l). It provides a window and mouse-based interface for reading, storing, composing, and sending mail messages. Scrollable windows allow easy access to your mailbox and mail folders. Software “panel buttons” make frequently-used commands readily available. Less-used commands are accessible from menus, and keyboard accelerators are provided for the more experienced user. The full editing capabilities of textedit(l) and the SunView selection service are available for modifying and composing mail. In addition, you can customize mailtool by setting various parameters with defaultsedit(l). OPTIONS -Mx Expert mode. Do not ask for confirmation after potentially damaging mail commands. This has the same effect as setting the expert variable. -Mi interval Check for new mail every interval seconds. This has the same effect as specifying a value for the interval variable. generic-tool-arguments mailtool accepts the generic tool arguments described in sunview(l). USAGE Users who are not familiar with the mail command should read SunOS User’s Guide: Getting Started . For more information on text editing and the selection service, see the SunView User’ s Guide. mailtool comes up closed. You can open the tool by clicking on the icon with the LEFT mouse button, mailtool starts reading your system mailbox as it opens. Alternatively, the frame menu on the icon con- tains the Open pull-right item, which allows you to open mailtool to a selected folder, or open and Com- pose, or just open without performing any other operation. Subwindows mailtool is composed of six parts. From top to bottom, they are: frame header This is the broad stripe at the top of the tool, and it displays status information. The right side displays information about the most-recently executed command. The left side displays other information such as the name of the current folder. When involved in a lengthy opera- tion, mailtool displays a message to that effect on the left side. While an operation is pend- ing, the cursor takes on the shape of an hourglass; you must wait until it finishes. header-list window This read-only text window contains a list of message headers from the current folder or mailbox. Initially, it shows the contents of your system mailbox (by default). Each header typically contains fields indicating who the message is from, its subject, and so forth. There is a scrollbar to the left that you can use to scroll through the headers. 318 Last change: 2 October 1989 Sun Release 4.1 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) control panel This panel contains a collection of software buttons corresponding to the most frequently used mail(l) commands. Clicking on one of these buttons starts the indicated operation for either the selected or the current message. Commands that require the name of a folder, such as Save, use the contents of the ‘File:’ text item. You must enter the name of a file or folder in this space before clicking on the button. In addition to the panel buttons, other commands and variations are accessible through menus “behind” each panel button. To display a button menu, hold down the RIGHT mouse button over the panel button. See Command Menus, below, for details. The message window This text window displays the current message (marked with *>’ in the header window). You can edit this message, in which case the result replaces the original message in the mailbox or folder. composition panel This panel contains software buttons for composing or replying to messages, and is visible only when you are composing a message or reply. composition window This text window, in which you compose messages to send, appears in conjunction with the composition panel. It is normally displayed only when composing a message or reply. It is initially loaded with mail header lines such as ‘To:’ and ‘Subject:’, and perhaps, ‘Cc:’. After these labels come various text fields, such as |>recipients<|. You can move from field to field using CTRL-TAB. This advances to the next text field. If you supply input to the field, your input replaces its contents. Empty fields are deleted when the message is sent. You can continue to edit the message as you see fit until you click on Deliver, at which point the message is sent as is. (You normally cannot retrieve a message once it has been sent). pop-up composition window While composing a message or reply, clicking again on Compose or Reply, opens another frame that contains a composition panel and window. The only limit on the number of such pop-up composition frames is the number of windows that a tool can support. These addi- tional frames operate independently. Basic Mailtool Concepts Choosing a message To choose a message, place the cursor anywhere in its header in the header window and click the LEFT mouse button. If there is no message chosen, mailtool applies operations to the current message. Current message The message that is displayed in the message window, and flagged with a V in the header window. Confirmation Some operations require confirmation, in which case an alert is displayed. You can then confirm or cancel the operation. Folders When mailtool starts up, it normally reads your system mailbox. However, you can select another “folder” (file containing mail messages) from which to read. Committing Changes Some operations change the state of your system mailbox or the current folder. These changes are not finalized until you commit them. For instance, you can “undelete” mes- sages that were deleted, provided that you have not yet done an operation that commits your changes. If the mailtool session is interrupted, pending changes to the mailbox or folder do Sun Release 4.1 Last change: 2 October 1989 319 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) not take effect. The Done button commits changes, as does the Quit button, which also exits from mailtool. To deliberately exit without committing, use the pop-up menu behind the Quit button. Control Panel Except for the Next and Undelete buttons, mailtool commands operate on the selected message or the current message only. You cannot specify a list or range of messages as with mail(l). The control panel buttons and items are (in alphabetical order): Compose Open a composition panel and window to compose a message. Delete Delete the selected or current message. Done Commit changes, close mailtool, and read new mail on next Open. File: This is a text item in which to enter the name of a folder for the Save, Copy, and Folder commands. This name can be a full pathname, a pathname relative to the current directory (the directory mailtool was started from), or a filename prefixed with a '+’ to refer to a file in the “folder” directory. Folder Commit changes and switch to the file or folder specified in the ‘File: ’ text item. Misc Display a pop-up panel to change the current directory of mailtool. Other miscellaneous operations are available on the menu behind this button. New Mail If you are examining your system mailbox, retrieve new mail without committing changes. If your are examining a folder, commit any changes to the folder, switch back to system mailbox, and retrieve any new mail in the process. Next Display the message following the current message in the message window. Print Print the corresponding message on a hardcopy printer. Reply Open a composition window to reply to the selected or current message. Save Save the current or selected message in the folder specified in the ‘File:’ text field, and delete it from your system mailbox or current folder. Show Display the chosen or current message in the message window. The Composition Panel This panel contains four buttons and a cycle-item. The cycle-item controls the behavior of the composition window when it becomes inactive — when the user delivers or cancels a message. Items in the cycle are: Disappear Remove the composition window and panel from display. This is the default. Stay Up Clear the window, but leave it displayed. Close Close a pop-up composition frame. The panel buttons are: Cancel Abort the message being composed. Deliver Send the message being composed to the indicated recipients. Include Insert the corresponding message into the composition window at the caret. This operation can be performed repeatedly, to include various messages. Re-address Insert the appropriate ‘To:’, ‘Subject:’ and ‘Cc:’ fields at the top of the composition win- dow. Command Menus All panel buttons have menus behind them. The first item on the menu is the default command; choosing this item is the same as clicking on the panel button. 320 Last change: 2 October 1989 Sun Release 4.1 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) Some menu items are pull-right to menus of related commands. You can browse the button menus to dis- cover what additional commands are available, and what their accelerators are, if any. The following com- mands are particularly useful. Change Directory Display a pop-up panel to change the current directory. Commit Changes Commit changes. This item is behind the New Mail button when viewing a folder. Commit Changes and Quit Behind the Done button. Commit changes and exit mailtool(l). This is the same as choosing Quit from the frame menu. Commit Changes and Retrieve New Mail Behind the New Mail button. Commit changes and retrieve new mail, switching to the system mail box if in a folder. This is the default when viewing a folder. Copy Behind the Save button. Copy the selected message to the file or folder specified in the ‘File:’ text item, without deleting it from the mailbox or folder. Deliver, Leave Window Intact Behind the Deliver button. Deliver the message, but do not undisplay, close, or clear the message composition window. Include, Indented Behind the Include button. Include the indicated message, setting it off by indentation rather than bracketing it with ‘ — Begin Included Message — ’ and * — End Included Message — ’ lines. Previous Behind the Next button. Display the previous message in the message window. Quit without Committing Changes Behind the Done button. Exit mailtool without committing changes. Show Full Header Behind the Show button. Display the complete message in the message window, includ- ing header lines that are normally ignored. Source .mailrc Behind the Misc button. Read in your .mailrc file to acquire new variables and settings. Note: this operation does not “forget” the previous option settings: only changes to boolean variables take effect. Undelete Behind the Delete button. Undelete the most recently deleted message(s) — this may be used repeatedly. It is inactive when there are no deleted messages. There are two special menus for use with the ‘File:’ text item. Choosing a name from either of these menus replaces the contents of this item. The menu behind the ‘File:’ item holds the most recently used folder names of the current session. It is be initialized by the filemenu variable. The menu behind the Folder button displays all folders in the “folder” directory, which is specified by the folder variable (described in mail(l)). Folders can be organized into subdirectories within the folder directory. Files in these subdirectories appear in a hierarchy of pull-right menus. To switch to a folder, choose it from one of the file menus, or type it in directly, and click on the Folder button. To return to your system mailbox, use the New Mail button. Mailtool Variables In addition to the variables recognized by mail(l), mailtool recognizes those listed below. They can be set by using defaultsedit(l), or by editing your .mailrc file directly. Unless otherwise noted, the default for the following variables is off. Sun Release 4.1 Last change: 2 October 1989 321 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) allowreversescan When set, allows you to step through messages in latest-first oldest-first order if you choose. The next message depends on the order of travel. alwaysusepopup Never split the message window to compose or reply; always use pop-up composition windows. askbcc autoprint bell disablefields Prompt for the ‘Bcc:’ field when composing or replying. Display the next message when the current message is deleted or saved. The number of times to ring the bell when new mail arrives. The default is 0. Do not use text fields in the composition window. The default is to use text fields. editmessagewindow Request confirmation before the first editing operation to a message in the message win- dow (as opposed to composing a reply). The default is not to request confirmation of the first edit. expert filemenu filemenusize Set expert mode in which no confirmations are requested. A list of files from which to initialize the ‘File:’ menu. These can be absolute path- names, pathnames relative to the working directory for mailtool (typically your home directory), or filenames prefixed with a V, which are taken as relative to the directory specified in the folder variable (see mail(l)). Specifies the maximum size of the ‘File:’ menu. The default is 10. flash The number of times to flash the window or icon when new mail arrives. The default is 0 . headerlines interval maillines moveinputfocus pop-uplines msgpercent The number of lines in header window. The default is 10. The interval in seconds to check for new mail. The default is 300. The number of lines in mail message window. The default is 30. Move the input focus into the composition window for Compose and Reply. This only works for click-to-type. The number of lines in pop-up message composition window. The default is 30. The percent of the message window to remain visible during Compose or Reply. The default is 50. printmail The command to use to print a message. The default is ipr -p’. trash The name of trash bin, which may be accessed just like any other folder. If set, all deleted messages are moved to the trash bin. The trash bin is emptied when you commit changes. Conditional Settings You can make your .mailrc set variables conditionally, depending on whether it is running in the tty environment or the window environment. See SunOS User’ s Guide: Getting Started for details. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout mailtool. On entry to mailtool, these environment variables are checked in the following order: LC CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment vari- ables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell char- acter classification defaults to the POSIX.l “C” locale. 322 Last change: 2 October 1989 Sun Release 4.1 MAILTOOL ( 1 ) USER COMMANDS MAILTOOL ( 1 ) F IL ES /var/spool/mail/* system mailboxes "/.mailrc startup file for mail and mailtool SEE ALSO bin-mail(l), defaultsedit(l), mail(l), sunview(l), textedit(l) aliases(5), locale(5), newaliases(8), send- mail(8) SunOS User’s Guide: Getting Started SunView User's Guide BUGS If mail(l) receives an error, then mailtool may hang, in which case you must kill it. New mail status is only approximate, therefore the presence of new mail is not always accurately reflected in the icon image or tool frame header. Mouse input may be lost while mailtool switches to iconic state. When notifying you of new mail, mailtool will not flash the window or icon without beeping (ringing the audible bell). Thus, the number of flashes is limited by the number of beeps you set. Unlike mail(l), mailtool retains unsaved messages in the system mailbox by default; that is, the hold vari- able is initially set. Sun Release 4.1 Last change: 2 October 1989 323 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) NAME make - maintain, update, and regenerate related programs and files SYNOPSIS make [ -f makefile ] . . . [ -d ] [ -dd ] [ -D ] [ -DD ] [ -e ] [ -i ] [ -k ] [ -n ] [ -p ] [ -P ] [ -q ] [ -r ] [ -s ] [ -S ] [ -t ] [ target . . . ] [ macro=value ... ] DESCRIPTION make executes a list of shell commands associated with each target, typically to create or update a file of the same name, makefile contains entries that describe how to bring a target up to date with respect to those on which it depends, which are called dependencies. Since each dependency is a target, it may have dependencies of its own. Targets, dependencies, and sub-dependencies comprise a tree structure that make traces when deciding whether or not to rebuild a target. make recursively checks each target against its dependencies, beginning with the first target entry in makefile if no target argument is supplied on the command line. If, after processing all of its dependencies, a target file is found either to be missing, or to be older than any of its dependencies, make rebuilds it. Optionally with this version of make, a target can be treated as out-of-date when the commands used to generate it have changed since the last time the target was built. To build a given target, make executes the list of commands, called a rule. This rule may be listed expli- citly in the target’s makefile entry, or it may be supplied implicitly by make. When no makefile is specified with a -f option: • If there is a file named makefile in the working directory, make uses that file. If, however, there is an SCCS history file (SCCS/s.makefiIe) which is newer, make attempts to retrieve and use the most recent version. • In the absence of the above file(s), if a file named Makefile is present in the working directory, make attempts to use it. If there is an SCCS history file (SCCS/s.Makefile) that is newer, make attempts to retrieve and use the most recent version. If no target is specified on the command line, make uses the first target defined in makefile. If a target has no makefile entry, or if its entry has no rule, make attempts to derive a rule by each of the following methods, in turn, until a suitable rule is found. (Each method is described under USAGE below.) • Pattern matching rules. • Implicit rules, read in from a user-supplied makefile. • Standard implicit rules (also known as suffix rules), typically read in from the file . • SCCS retrieval, make retrieves the most recent version from the SCCS history file (if any). See the description of the .SCCS_GET: special-function target for details. « The rule from the .DEFAULT: target entry, if there is such an entry in the makefile. If there is no makefile entry for a target, if no rule can be derived for building it, and if no file by that name is present, make issues an error message and halts. OPTIONS -f makefile Use the description file makefile. A as the makefile argument denotes the standard input. The contents of makefile , when present, override the standard set of implicit rules and predefined mac- ros. When more than one *— f makefile ’ argument pair appears, make uses the concatenation of those files, in order of appearance. N -d Display the reasons why make chooses to rebuild a target; make displays any and all dependen- cies that are newer. In addition, make displays options read in from the MAKEFLAGS environ- ment variable. 324 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) -dd Display the dependency check and processing in vast detail. -D Display the text of the makefiles read in. -DD Display the text of the makefiles, default.mk file, the state file, and all hidden-dependency reports, -e Environment variables override assignments within makefiles. -i Ignore error codes returned by commands. Equivalent to the special-function target ‘.IGNORE:’. -k When a nonzero error status is returned by a rule, or when make cannot find a rule, abandon work on the current target, but continue with other dependency branches that do not depend on it. -n No execution mode. Print commands, but do not execute them. Even lines beginning with an @ are printed. However, if a command line contains a reference to the $(MAKE) macro, that line is always executed (see the discussion of MAKEFLAGS in Reading Makefiles and the Environ- ment). -p Print out the complete set of macro definitions and target descriptions. -P Merely report dependencies, rather than building them. -q Question mode, make returns a zero or nonzero status code depending on whether or not the tar- get file is up to date. -r Do not read in the default makefile . -s Silent mode. Do not print command lines before executing them. Equivalent to the special- function target ‘.SILENT:’. -S Undo the effect of the -k option. Stop processing when a non-zero exit status is returned by a command. -t Touch the target files (bringing them up to date) rather than performing their rules. This can be dangerous when files are maintained by more than one person. When the .KEEP_STATE: target appears in the makefile, this option updates the state file just as if the rules had been performed. macro =value Macro definition. This definition overrides any regular definition for the specified macro within the makefile itself, or in the environment. However, this definition can still be overridden by con- ditional macro assignments. USAGE Refer to SunOS User s Guide: Doing More and make in Programming Utilities and Libraries for tutorial information about make. Reading Makefiles and the Environment When make first starts, it reads the MAKEFLAGS environment variable to obtain any the following options specified present in its value: -d, -D, -e, -i, -k, -I, -n, -p, -q, -r, -s, -S, or -t. (Within the MAKEFLAGS value, the leading ‘ — ’ character for the option string is omitted.) make then reads the com- mand line for additional options, which also take effect. Next, make reads in a default makefile that typically contains predefined macro definitions, target entries for implicit rules, and additional rules, such as the rule for retrieving SCCS files. If present, make uses the file default.mk in the current directory; otherwise it reads the file , which contains the standard definitions and rules. Use the directive: include in your local default.mk file to include them. Sun Release 4.1 Last change: 15 September 1989 325 MAKE(l) USER COMMANDS MAKE ( 1 ) Next, make imports variables from the environment (unless the -e option is in effect), and treats them as defined macros. Because make uses the most recent definition it encounters, a macro definition in the makefile normally overrides an environment variable of the same name. When -e is in effect, however, environment variables are read in after all makefiles have been read. In that case, the environment vari- ables take precedence over definitions in the makefile. Next, make reads the state file, ,make.state in the local directory if it exists, and then any makefiles you specify with — f, or one of makefile or Makefile as described above. Next, (after reading the environment if -e is in effect), make reads in any macro definitions supplied as command line arguments. These override macro definitions in the makefile and the environment both, but only for the make command itself. make exports environment variables, using the most recently defined value. Macro definitions supplied on the command line are not normally exported, unless the macro is also an environment variable. make does not export macros defined in the makefile. If an environment variable is set, and a macro with the same name is defined on the command line, make exports its value as defined on the command line. Unless -e is in effect, macro definitions within the makefile take precedence over those imported from the environment. The macros MAKEFLAGS, MAKE, KEEPSTATE, SHELL, HOSTARCH, TARGET ARCH, HOST MACH, and TARGET MACH are special cases. See Special-Purpose Macros below, for details. Makefile Target Entries A target entry has the following format: target . . . [: I ::] [ dependency ] . . . [; command ] . . . [command] The first line contains the name of a target, or a space-separated list of target names, terminated with a colon or double colon. If a list of targets is given, this is equivalent to having a separate entry of the same form for each target. The colon(s) may be followed by a dependency , or a dependency list, make checks this list before building the target. The dependency list may be terminated with a semicolon (;), which in turn can be followed by a single Bourne shell command. Subsequent lines in the target entry begin with a TAB, and contain Bourne shell commands. These commands comprise the rule for building the target. Shell commands may be continued across input lines by escaping the NEWLINE with a backslash (\). The continuing line must also start with a TAB. To rebuild a target, make expands macros, strips off initial TAB characters and either executes the com- mand directly (if it contains no shell metacharacters), or passes each command line to a Bourne shell for execution. The first line that does not begin with a TAB or # begins another target or macro definition. Makefile Special Characters Global # Start a comment. The comment ends at the next NEWLINE. If the # follows the TAB in a com- mand line, that line is passed to the shell (which also treats # as the start of a comment). include filename If the word include appears as the first seven letters of a line and is followed by a SPACE or TAB, the string that follows is taken as a filename to interpolate at that line, include files can be nested to a depth of no more than about 16. If filename is a macro reference, it is expanded. 326 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) Targets and Dependencies : Target list terminator. Words following the colon are added to the dependency list for the target or targets. If a target is named in more than one colon-terminated target entry, the dependencies for all its entries are added to form that target’s complete dependency list. :: Target terminator for alternate dependencies. When used in place of a the double-colon allows a target to be checked and updated with respect to alternate dependency lists. When the target is out-of-date with respect to dependencies listed in the first alternate, it is built according to the rule for that entry. When out-of-date with respect to dependencies in another alternate, it is built according the rule in that other entry. Implicit rules do not apply to double-colon targets; you must supply a rule for each entry. If no dependencies are specified, the rule is always performed. target [+ target . . . ] : Target group. The rule in the target entry builds all the indicated targets as a group. It is normally performed only once per make run, but is checked for command dependencies every time a target in the group is encountered in the dependency scan. % Pattern matching wild card metacharacter. Like the shell wild card, *%’ matches any string of zero or more characters in a target name or dependency, in the target portion of a conditional macro definition, or within a pattern replacement macro reference. Note: only one *%’ can appear in a target, dependency-name, or pattern-replacement macro reference. Jpathname make ignores the leading ‘J’ characters from targets with names given as pathnames relative to “dot,” the working directory. Macros = Macro definition. The word to the left of this character is the macro name; words to the right comprise its value. Leading and trailing white space characters are stripped from the value. A word break following the = is implied. $ Macro reference. The following character, or the parenthesized or bracketed string, is interpreted as a macro reference: make expands the reference (including the $) by replacing it with the macro’s value. 0 { } Macro-reference name delimiters. A parenthesized or bracketed word appended to a $ is taken as the name of the macro being referred to. Without the delimiters, make recognizes only the first character as the macro name. $$ A reference to the dollar-sign macro, the value of which is the character *$’. Used to pass variable expressions beginning with $ to the shell, to refer to environment variables which are expanded by the shell, or to delay processing of dynamic macros within the dependency list of a target, until that target is actually processed. \$ Escaped dollar-sign character. Interpreted as a literal dollar sign within a rule. += When used in place of *=’, appends a string to a macro definition (must be surrounded by white space, unlike *=’). := Conditional macro assignment. When preceded by a list of targets with explicit target entries, the macro definition that follows takes effect when processing only those targets, and their dependen- cies. :sh = Define the value of a macro to be the output of a command (see Command Substitutions, below). :sh In a macro reference, execute the command stored in the macro, and replace the reference with the output of that command (see Command Substitutions). Sun Release 4. 1 Last change: 15 September 1989 327 MAKE(l) USER COMMANDS MAKE(l) Rules - make ignores any nonzero error code returned by a command line for which the first non-TAB character is a This character is not passed to the shell as part of the command line, make normally terminates when a command returns nonzero status, unless the -i or -k options, or the JGNORE: special-function target is in effect. @ If the first non-TAB character is a @, make does not print the command line before executing it. This character is not passed to the shell. ? Escape command-dependency checking. Command lines starting with this character are not sub- ject to command dependency checking. ! Force command-dependency checking. Command-dependency checking is applied to command lines for which it would otherwise be suppressed. This checking is normally suppressed for lines that contain references to the ‘V dynamic macro (for example, ‘$?’)- When any combination of *?’, or T appear as the first characters after the TAB, all that are present apply. None are passed to the shell. Special-Function Targets When incorporated in a makefile, the following target names perform special-functions: .DEFAULT: If it has an entry in the makefile, the rule for this target is used to process a target when there is no other entry for it, no rule for building it, and no SCCS history file from which to retrieve a current version, make ignores any dependencies for this target. .DONE: If defined in the makefile, make processes this target and its dependencies after all other targets are built. This target is also performed when make halts with an error, unless the .FAILED target is defined. .FAILED: This target, along with its dependencies, is performed instead of .DONE when defined in the makefile and make halts with an error. .IGNORE: Ignore errors. When this target appears in the makefile, make ignores non-zero error codes returned from commands. .INIT: If defined in the makefile, this target and its dependencies are built before any other targets are processed. .KEEPSTATE: If this target appears in the makefile, make updates the state file, .make.state, in the current direc- tory. This target also activates command dependencies, and hidden dependency checks. .M AKEVERSION : A target-entry of the form: .MAKEVERSION: VERSION-nwmber enables version checking. If the version of make differs from the version indicated, make issues a warning message. .NO_PARALLEL: Currently, this target has no effect, it is, however, reserved for future use. .PARALLEL: Currently of no effect, but reserved for future use. .PRECIOUS: List of files not to delete, make does not remove any of the files listed as dependencies for this target when interrupted, make normally removes the current target when it receives an interrupt. 328 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) .SCCS_GET: This target contains the rule for retrieving the current version of an SCCS file from its history file. To suppress automatic retrieval, add an entry for this target with an empty rule to your makefile. .SILENT: Run silently. When this target appears in the makefile, make does not echo commands before exe- cuting them. .SUFFIXES: The suffixes list for selecting implicit rules (see The Suffixes List). .WAIT: Currently of no effect, but reserved for future use. Clearing Special Targets In this version of make, you can clear the definition of the following special targets by supplying entries for them with no dependencies and no rule: .DEFAULT, .SCCS GET, and .SUFFIXES Command Dependencies When the ,KEEP_STATE: target appears in the makefile, make checks the command for building a target against the state file, .make.state. If the command has changed since the last make run, make rebuilds the target. Hidden Dependencies When the .KEEP_STATE: target appears in the makefile, make reads reports from cpp(l) and other compi- lation processors for any “hidden” files, such as #include files. If the target is out of date with respect to any of these files, make rebuilds it. Macros Entries of the form macro =value define macros, macro is the name of the macro, and value , which consists of all characters up to a com- ment character or unescaped NEWLINE, is the value, make strips both leading and trailing white space in accepting the value. Subsequent references to the macro, of the forms: %{name) or ${name} are replaced by value. The parentheses or brackets can be omitted in a reference to a macro with a single-character name. Macro references can contain references to other macros, in which case nested references are expanded first. Suffix Replacement Macro References Substitutions within macros can be made as follows: %{name '.string 1 =string2 ) where stringl is either a suffix, or a word to be replaced in the macro definition, and string 2 is the replace- ment suffix or word. Words in a macro value are separated by SPACE, TAB, and escaped NEWLINE char- acters. Sun Release 4.1 Last change: 15 September 1989 329 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) Pattern Replacement Macro References Pattern matching replacements can also be applied to macros, with a reference of the form: %(name: op%os= np%ns ) where op is the existing (old) prefix and os is the existing (old) suffix, np and ns are the new prefix and new suffix, respectively, and the pattern matched by % (a string of zero or more characters), is carried forward from the value being replaced. For example: PROGRAM=fabricate DEBUG= $(PROGRAM: %=tmp/%-g) sets the value of DEBUG to tmp/fabricate-g. Note: pattern replacement macro references cannot be used in the dependency list of a pattern matching rule; the % characters are not evaluated independently. Also, any number of % metacharacters can appear after the equal-sign. Appending to a Macro Words can be appended to macro values as follows: macro += word . . . Special-Purpose Macros When the MAKEFLAGS variable is present in the environment, make takes options from it, in combination with options entered on the command line, make retains this combined value as the MAKEFLAGS macro, and exports it automatically to each command or shell it invokes. Note: flags passed by way of MAKEFLAGS are only displayed when the — d, or — dd options are in effect. The MAKE macro is another special case. It has the value make by default, and temporarily overrides the -n option for any line in which it is referred to. This allows nested invocations of make written as: $(MAKE) . . . to run recursively, with the -n flag in effect for all commands but make. This lets you use ‘make -n’ to test an entire hierarchy of makefiles. For compatibility with the 4.2 BSD make, the MFLAGS macro is set from the MAKEFLAGS variable by prepending a MFLAGS is not exported automatically. The SHELL macro, when set to a single-word value such as /usr/bin/csh, indicates the name of an alternate shell to use. The default is /bin/sh. Note: make executes commands that contain no shell metacharacters itself. Built-in commands, such as dirs in the C shell, are not recognized unless the command line includes a metacharacter (for instance, a semicolon). This macro is neither imported from, nor exported to the environment, regardless of -e. To be sure it is set properly, you must define this macro within every makefile that requires it. The KEEP_STATE environment variable has the same effect as the .KEEP_STATE: special-function target. It enables command dependencies, hidden dependencies and writing of the state file. The following macros are provided for use with cross-compilation: HOSTARCH The machine architecture of the host system. By default, this is the output of the arch(l) com- mand prepended with ‘ — ’. Under normal circumstances, this value should never be altered by the user. TARGETARCH The machine architecture of the target system. By default, the output of arch, prepended with « > HOSTMACH The machine architecture of the host system. By default, this is the output of the mach(l), prepended with ‘ — ’. Under normal circumstances, this value should never be altered by the user. 330 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) TARGET_MACH The machine architecture of the target system. By default, the output of mach, prepended with Dynamic Macros There are several dynamically maintained macros that are useful as abbreviations within rules. They are shown here as references; if you were to define them, make would simply override the definition. $* The basename of the current target, derived as if selected for use with an implicit rule. $< The name of a dependency file, derived as if selected for use with an implicit rule. $@ The name of the current target. This is the only dynamic macro whose value is strictly determined when used in a dependency list. (In which case it takes the form $? The list of dependencies that are newer than the target. Command-dependency checking is automatically suppressed for lines that contain this macro, just as if the command had been prefixed with a *?’. See the description of *?’, under Makefile Special Tokens, above. You can force this check with the ! command-line prefix. $% The name of the library member being processed. (See Library Maintenance, below.) To refer to the $@ dynamic macro within a dependency list, precede the reference with an additional ‘$’ character (as in, ‘$$@’). Because make assigns $< and $* as it would for implicit rules (according to the suffixes list and the directory contents), they may be unreliable when used within explicit target entries. These macros can be modified to apply either to the filename part, or the directory part of the strings they stand for, by adding an upper case F or D, respectively (and enclosing the resulting name in parentheses or braces). Thus, ‘$(@D)’ refers to the directory part of the string if there is no directory part, V is assigned. $(@F) refers to the filename part. Conditional Macro Definitions A macro definition of the form: target-list := macro = value indicates that when processing any of the targets listed and their dependencies , macro is to be set to the value supplied. Note that if a conditional macro is referred to in a dependency list, the $ must be delayed (use $$ instead). Also, target-list may contain a % pattern, in which case the macro will be conditionally defined for all targets encountered that match the pattern. A pattern replacement reference can be used within the value. You can temporarily append to a macro’s value with a conditional definition of the form: target-list := macro += value Predefined Macros make supplies the macros shown in the table that follows for compilers and their options, host architec- tures, and other commands. Unless these macros are read in as environment variables, their values are not exported by make. If you run make with any of these set in the environment, it is a good idea to add com- mentary to the makefile to indicate what value each is expected to take. If -r is in effect, make does not read the default makefile (,/default.mk or ) in which these macro definitions are sup- plied. Sun Release 4. 1 Last change: 15 September 1989 331 MAKE(l) USER COMMANDS MAKE ( 1 ) Table of Predefined Macros Use Macro Default Value Library AR ar Archives ARFLAGS rv Assembler AS as Commands ASFLAGS COMPILED $(AS) $(ASFLAGS) $(TARGET_MACH) COMPILE.S $(CC) $(ASFLAGS) $(CPPFLAGS) $(TARGET_MACH) — c C Compiler CC CC Commands CFLAGS CPPFLAGS COMPILE.c $(CC) $(CFLAGS) $(CPPFLAGS) -target $(TARGET_ARCH:-%=%) -c LINK.C $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) -target $(TARGET_ARCH:-% = %) FORTRAN 77 FC f77 Compiler FFLAGS Commands COMPILE.f $(FC) $(FFLAGS) $(TARGET_ARCH) — c LINK.f $(FC) $(FFLAGS) $(TARGET_ARCH) $(LDFLAGS) COMPILE.F $(FC) $(FFLAGS) $(CPPFLAGS) $(TARGET_ARCH) — c LINK.F $(FC) $(FFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH) Link Editor LD Id Command LDFLAGS lex LEX lex Command LFLAGS LEX.l $(LEX) $(LFLAGS) -t lint LINT lint Command LINTFLAGS LINT.c $(LINT) $(LINTFLAGS) $(CPPFLAGS) $(TARGET_ARCH) Modula 2 M2C m2c Commands M2FLAGS MODFLAGS DEFFLAGS COMPILE.def $(M2C) $(M2FLAGS) $(DEFFLAGS) $(TARGET_ARCH) COMPILE.mod $(M2C) $(M2FLAGS) $(MODFLAGS) $(TARGET_ARCH) Pascal PC pc Compiler PFLAGS Commands COMPILE.p $(PC) $(PFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c LINK.p $(PC) $(PFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH) Ratfor RFLAGS Compilation COMPILE.r $(FC) $(FFLAGS) $(RFLAGS) $(TARGET_ARCH) -c Commands LINK.r $(FC) $(FFLAGS) $(RFLAGS) $(TARGET_ARCH) $(LDFLAGS) rm Command RM rm -f sees SCCSFLAGS Command SCCSGETFLAGS -s yacc YACC yacc Command YFLAGS YACC.y $(YACC) $(YFLAGS) Suffixes .o .c .c" .s .s" .S .S' .In .f .r .F .F' .1 List SUFFIXES .1" .mod .mod" .sym .def .deF .p .p" .r .r' .y .y" .h .h' .sh .sh' .cps .cps" 332 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) Implicit Rules When a target has no entry in the makefile, make attempts to determine its class (if any) and apply the rule for that class. An implicit rule describes how to build any target of a given class, from an associated dependency file. The class of a target can be determined either by a pattern, or by a suffix; the correspond- ing dependency file (with the same basename) from which such a target might be built. In addition to a predefined set of implicit rules, make allows you to define your own, either by pattern, or by suffix. Pattern Matching Rules A target entry of the form: tp%ts: dp%ds rule is a pattern matching rule, in which tp is a target prefix, ts is a target suffix, dp is a dependency prefix, and ds is a dependency suffix (any of which may be null). The % stands for a basename of zero or more char- acters that is matched in the target, and is used to construct the name of a dependency. When make encounters a match in its search for an implicit rule, it uses the rule in that target entry to build the target from the dependency file. Pattern-matching implicit rules typically make use of the $@ and $< dynamic macros as placeholders for the target and dependency names. Other, regular dependencies may occur in the dependency list. An entry of the form: tp%ts : [dependency . . . ] dp %ds [dependency . . . ] rule is a valid pattern matching rule. Suffix Rules When no pattern matching rule applies, make checks the target name to see if it ends with a suffix in the known suffixes list. If so, make checks for any suffix rules, as well as a dependency file with same root and another recognized suffix, from which to build it. The target entry for a suffix rule takes the form: DsTs: rule where Ts is the suffix of the target, Ds is the suffix of the dependency file, and rule is the rule for building a target in the class. Both Ds and Ts must appear in the suffixes list. (A suffix need not begin with a V to be recognized.) A suffix rule with only one suffix describes how to build a target having a null (or no) suffix from a depen- dency file with the indicated suffix. For instance, the ,c rule could be used to build an executable program named file from a C source file named ‘file.c\ If a target with a null suffix has an explicit dependency, make omits the search for a suffix rule. Sun Release 4.1 Last change: 15 September 1989 333 MAKE(l) USER COMMANDS MAKE(l) Table of Standard Implicit (Suffix) Rules Use Implicit Rule Name Command Line Assembly .s.o $(COMPILE.s) — o $@$< Files .s.a $(COMPILE.s) -o $% $< $(AR) $(ARFLAGS) $@ $% $(RM) $% .S.o $(COMPILE.S) -o $@ $< .S.a $(COMPILE.S) -o $% $< $(AR) $(ARFLAGS) $@ $% $(RM) $% C .c $(LINK.c) -o $@ $< $(LDLIBS) Files .c.In $(LINT.c) $(OUTPl7T_OPTION) -1 $< x.o $(COMPILE.c) $(OUTPUT_OPTION) $< x.a $(COMPILE.c) -o $% $< $(AR) $(ARFLAGS) $@ $% $(RM) $% FORTRAN 77 .f $(LINK.f) -o $@ $< $(LDLIBS) Files .f.o $(COMPILE.f) $(OUTPUT OPTION) $< .f.a $(COMPILE.f) -o $% $< $(AR) $(ARFLAGS) $@ $% $(RM) $% .F $(LINK.F) -0 $@ $< $(LDLIBS) .F.o $(COMPILE.F) $(OUTPUT_OPTION) $< .F.a $(COMPILE.F) -o $% $< $(AR) $(ARFLAGS) $@ $% $(RM) $% lex .1 $(RM) $*.c Files $(LEX.l) $<>$*.c $(LINK.c) -o $@ $*.c $(LDLIBS) $(RM) $*.c .lx $(RM) $@ $(LEX.l) $<>$@ .I.In $(RM) $*.C $(LEX.l) $<>$*.C $(LINT.c) -o $@ -i $*.c $(RM) $*.c .1.0 $(RM) $*.c $(LEX.I) $< > $*.c $(COMPILE.c) -o $@ $*.c $(RM) $*.c Modula 2 .mod $(COMPILE.mod) -o $@ -e $@ $< Files .mod.o $(COMPILE.mod) -o $@$< .def.sym $(COMPILE.def) -o $@ $< NeWS .cps.h cps $*.cps Pascal •P $(LINK.p) -o $@ $< $(LDLIBS) Files .p.o $(COMPILE.p) $(OUTPUT_OPTION) $< Ratfor .r $(LINK.r) -o $@ $< $(LDLIBS) Files .r.o $(COMPILE.r) $(OUTPUT_OPTION) $< .r.a $(COMPILE.r) -o $% $< $(AR) $(ARFLAGS) $@$% $(RM) $% 334 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE(l) Table of Standard Implicit (Suffix) Rules (continued) Use Implicit Ride Name Command Line SCCS Files .SCCSGET sees $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ -G$@ Shell Scripts .sh cat $< >$@ chmod +x $@ yacc Files •y $(YACC.y) $< $(LINK.c) -o $@ y.tab.c $(LDLIBS) $(RM) y.tab.c •y-c $(YACC.y) $< mv y.tab.c $@ ,y.ln $(YACC.y) $< $(LINT.c) -o $@ -i y.tab.c $(RM) y.tab.c ■y-o $(YACC.y) $< $(COMPILE.c) -o $@ y.tab.c $(RM) y.tab.c make reads in the standard set of implicit rules from the file , unless — r is in effect, or there is a defaultmk file in the local directory that does not include that file. The Suffixes List The suffixes list is given as the list of dependencies for the ‘.SUFFIXES:’ special-function target. The default list is contained in the SUFFIXES macro (See Table of Predefined Macros for the standard list of suffixes). You can define additional .SUFFIXES: targets; a .SUFFIXES target with no dependencies clears the list of suffixes. Order is significant within the list; make selects a rule that corresponds to the target’s suffix and the first dependency-file suffix found in the list. To place suffixes at the head of the list, clear the list and replace it with the new suffixes, followed by the default list; .SUFFIXES: .SUFFIXES: suffixes $(SUFFIXES) A tilde (') indicates that if a dependency file with the indicated suffix (minus the ') is under SCCS its most recent version should be retrieved, if necessary, before the target is processed. Library Maintenance A target name of the form: lib (member ...) refers to a member, or a space-separated list of members, in an ar(l V) library. The dependency of the library member on the corresponding file must be given as an explicit entry in the makefile. This can be handled by a pattern matching rule of the form: lib(%.s ): %.s where .s is the suffix of the member; this suffix is typically .o for object libraries. A target name of the form lib ((symbol)) refers to the member of a randomized object library (see ranlib(l)) that defines the entry point named sym- bol. Sun Release 4. 1 Last change: 15 September 1989 335 MAKE(l) USER COMMANDS MAKE(l) Command Execution Command lines are executed one at a time, each by its own process or shell. Shell commands, notably cd, are ineffectual across an unescaped NEWLINE in the makefile. A line is printed (after macro expansion) just before being executed. This is suppressed if it starts with a ‘@\ if there is a ‘.SILENT:’ entry in the makefile, or if make is run with the -s option. Although the -n option specifies printing without execu- tion, lines containing the macro $(MAKE) are executed regardless, and lines containing the @ special char- acter are printed. The -t (touch) option updates the modification date of a file without executing any rules. This can be dangerous when sources are maintained by more than one person. Bourne Shell Constructs To use the Bourne shell if control structure for branching, use a command line of the form: if expression ; \ then command ; \ ... ;\ else ; \ ... ;\ fi Although composed of several input lines, the escaped NEWLINE characters insure that make treats them all as one (shell) command line. To use the Bourne shell for control structure for loops, use a command line of the form: for var in list ; \ do command ; \ done To refer to a shell variable, use an escaped dollar-sign (\$). This prevents expansion of the dollar-sign by make. Command Substitutions To incorporate the standard output of a shell command in a macro, use a definition of the form: MACRO :sh =command The command is executed only once, standard error output is discarded, and NEWLINE characters are replaced with SPACES. If the command has a non-zero exit status, make halts with an error. To capture the output of a shell command in a macro reference, use a reference of the form: $(MACRO :sh) where MACRO is the name of a macro containing a valid Bourne shell command line. In this case, the com- mand is executed whenever the reference is evaluated. As with shell command substitutions, the reference is replaced with the standard output of the command. If the command has a non-zero exit status, make halts with an error. Signals INT and QUIT signals received from the keyboard halt make and remove the target file being processed unless that target is in the dependency list for ‘.PRECIOUS:’. 336 Last change: 15 September 1989 Sun Release 4.1 MAKE ( 1 ) USER COMMANDS MAKE ( 1 ) EXAMPLES This makefile says that pgm depends on two files a.o and b.o, and that they in turn depend on their corresponding source files (a.c and b.c) along with a common file incl.h: pgm: a.o b.o $(LINK.c) -o $@ a.o b.o a. o: incl.h a.c cc -c a.c b. o: incl.h b.c cc -c b.c The following makefile uses implicit rules to express the same dependencies: pgm: a.o b.o cc a.o b.o -o pgm a.o b.o: incl.h FILES makefile Makefile SCCS/s.makefile SCCS/s.Makefile default.mk .make.state current version(s) of make description file SCCS history files for the above makefile(s) default file for user-defined targets, macros, and implicit rules makefile for standard implicit rules and macros (not read if default.mk is) state file in the local directory SEE ALSO ar(lV), cc(lV), cd(l), sccs-get(l), lex(l), ranlib(l), passwd(5) SunOS User's Guide: Doing More Programming Utilities and Libraries DIAGNOSTICS make returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0. Do not know how to make target. Stop. There is no makefile entry for target, and none of make’s implicit rules apply (there is no depen- dency file with a suffix in the suffixes list, or the target’s suffix is not in the list). *** target removed. make was interrupted while building target. Rather than leaving a partially-completed version that is newer than its dependencies, make removes the file named target. *** target not removed. make was interrupted while building target and target was not present in the directory. *** target could not be removed, reason make was interrupted while building target, which was not removed for the indicated reason. Read of include file ‘file’ failed The makefile indicated in an include directive was not found, or was inaccessible. Loop detected when expanding macro value '■macro ’ A reference to the macro being defined was found in the definition. Could not write state file '■file' You used the .KEEPSTATE: target, but do not have write permission on the state file. *** Error code n The previous shell command returned a nonzero error code. Sun Release 4.1 Last change: 15 September 1989 337 MAKE(l) USER COMMANDS MAKE(l) *** signal message The previous shell command was aborted due to a signal. If core dumped’ appears after the message, a core file was created. Conditional macro conflict encountered Displayed only when -d is in effect, this message indicates that two or more parallel targets currently being processed depend on a target which is built differently for each by virtue of condi- tional macros. Since the target cannot simultaneously satisfy both dependency relationships, it is conflicted. BUGS Some commands return nonzero status inappropriately; to overcome this difficulty, prefix the offending command line in the rule with a Filenames with the characters *=’, or do not work. You cannot build file.o from Iib(file.o). Options supplied by MAKEFLAGS should be reported for nested make commands. Use the -d option to find out what options the nested command picks up from MAKEFLAGS. This version of make is incompatible in certain respects with previous versions: e The -d option output is much briefer in this version, -dd now produces the equivalent voluminous output. ® make attempts to derive values for the dynamic macros ‘$*\ ‘$<’, and *$?’, while processing explicit targets. It uses the same method as for implicit rules; in some cases this can lead either to unexpected values, or to an empty value being assigned. (Actually, this was true for earlier versions as well, even though the documentation stated otherwise.) • make no longer searches the current directory for SCCS history files. • Suffix replacement in macro references are now applied after the macro is expanded. There is no guarantee that makefiles created for this version of make will work with earlier versions. If there is no default.mk file in the current directory, and the file is missing, make stops before processing any targets. To force make to run anyway, create an empty default.mk file in the current directory. Once a dependency is made, make assumes the dependency file is present for the remainder of the run. If a rule subsequently removes that file and future targets depend on its existence, unexpected errors may result. When hidden dependency checking is in effect, the $? macro’s value includes the names of hidden depen- dencies. This can lead to improper filename arguments to commands when $? is used in a rule. Pattern replacement macro references cannot be used in the dependency list of a pattern matching rule. Unlike previous versions, this version of make strips a leading ‘./’ from the value of the ‘$@’ dynamic macro. With automatic SCCS retrieval, this version of make does not support tilde suffix rules. The only dynamic macro whose value is strictly determined when used in a dependency list is $@ (takes the form ‘$$@’). make invokes the shell with the -e (exit-on-errors) argument. Thus, with semicolon-separated command sequences, execution of the later commands depends on the success of the former. This is consistent with make’s behavior of halting immediately when a problem occurs, but cannot be inferred from the syntax of the rule alone. 338 Last change: 15 September 1989 Sun Release 4.1 MAN(l) USER COMMANDS MAN(l) NAME man — display reference manual pages; find reference pages by keyword SYNOPSIS man [ - ] [ -t ] [ -M path ] [ -T macro-package ] [ [ section ] title ...] ... man [ -M path ] -k keyword . . . man [ -M path ] -f filename . . . DESCRIPTION man displays information from the reference manuals. It can display complete manual pages that you select by title, or one-line summaries selected either by keyword (-k), or by the name of an associated file (- 0 - A section, when given, applies to the titles that follow it on the command line (up to the next section, if any), man looks in the indicated section of the manual for those titles, section is either a digit (perhaps followed by a single letter indicating the type of manual page), or one of the words new, local, old, or pub- lic. The abbreviations n, 1, o and p are also allowed. If section is omitted, man searches all reference sec- tions (giving preference to commands over functions) and prints the first manual page it finds. If no manual page is located, man prints an error message. The reference page sources are typically located in the /usr/man/man? directories. Since these directories are optionally installed, they may not reside on your host; you may have to mount /usr/man from a host on which they do reside. If there are preformatted, up-to-date versions in corresponding cat? or fmt? direc- tories, man simply displays or prints those versions. If the preformatted version of interest is out of date or missing, man reformats it prior to display. If directories for the preformatted versions are not provided, man reformats a page whenever it is requested; it uses a temporary file to store the formatted text during display. If the standard output is not a terminal, or if the flag is given, man pipes its output through cat(lV). Otherwise, man pipes its output through more(l) to handle paging and underlining on the screen. OPTIONS -t man arranges for the specified manual pages to be troffed to a suitable raster output device (see troff(l) or vtroff(l)). If both the - and -t flags are given, man updates the troffed versions of each named title (if necessary), but does not display them. -M path Change the search path for manual pages, path is a colon-separated list of directories that contain manual page directory subtrees. For example, /usr/man/u_man:/usr/man/a_man makes man search in the standard System V locations. When used with the -k or -f options, the -M option must appear first. Each directory in the path is assumed to contain subdirectories of the form man[l-8I-p]. -T macro-package man uses macro-package rather than the standard -man macros defined in /usr/lib/tmac/tmac.an for formatting manual pages. — k keyword . . . man prints out one-line summaries from the whatis database (table of contents) that contain any of the given keywords. The whatis database is created using the catman(8) command with the -w option. -f filename . . . man attempts to locate manual pages related to any of the given filenames. It strips the leading pathname components from each filename, and then prints one-line summaries containing the resulting basename or names. This option also uses the whatis database. Sun Release 4.1 Last change: 12 January 1988 339 MAN ( 1 ) USER COMMANDS MAN(l) MANUAL PAGES Manual pages are troff(l)/nrofT(l) source files prepared with the -man macro package. Refer to man(7), or Formatting Documents for more information. When formatting a manual page, man examines the first line to determine whether it requires special pro- cessing. Referring to Other Manual Pages If the first line of the manual page is a reference to another manual page entry fitting the pattern: .so man?*/ sourcefile man processes the indicated file in place of the current one. The reference must be expressed as a path- name relative to the root of the manual page directory subtree. When the second or any subsequent line starts with .so, man ignores it; troff(l) or nroff(l) processes the request in the usual manner. Preprocessing Manual Pages If the first line is a string of the form: 'V X where X is separated from the by a single SPACE and consists of any combination of characters in the following list, man pipes its input to troff(l) or nroff(l) through the corresponding preprocessors. e eqn(l), or neqn for nroff r refer(l) t tbl(l) v vgrind(l) If eqn or neqn is invoked, it will automatically read the file /usr/pub/eqnchar (see eqnchar(7)). If nroff(l) is invoked, col(lV) is automatically used. ENVIRONMENT MANPATH If set, its value overrides /usr/man as the default search path. (The -M flag, in turn, overrides this value.) PAGER A program to use for interactively delivering man’s output to the screen. If not set, ‘more -s’ (see more(l)) is used. TCAT The name of the program to use to display troffed manual pages. If not set, ‘lpr -t’ (see lpr(l)) is used. TROFF The name of the formatter to use when the — t flag is given. If not set, troff is used. FILES /usr/[share]/man /usr/[share]/man/man?/* /usr/[share]/man/cat?/* /usr/[share]/man/fmt?/* /usr/[share]/man/whatis /usr/[share]/lib/tmac/tmac.an /usr/pub/eqnchar root of the standard manual page directory subtree unformatted manual entries nroffed manual entries troffed manual entries table of contents and keyword database standard -man macro package SEE ALSO apropos(l), cat(lV), col(lV), eqn(l), Ipr(l), more(l), nroff(l), refer(l), tbl(l), troff(l), vgrind(l), vtroff(l), whatis(l), eqnchar(7), man(7), catman(8) 340 Last change: 12 January 1988 Sun Release 4.1 MAN ( 1 ) USER COMMANDS MAN ( 1 ) NOTES BUGS Because troff is not 8-bit clean, man has not been made 8-bit clean. The — f and -k options use the /usr/man/whatis database, which is created by catman(8). The manual is supposed to be reproducible either on a phototypesetter or on an ASCII terminal. However, on a terminal some information (indicated by font changes, for instance) is necessarily lost. Some dumb terminals cannot process the vertical motions produced by the e (eqn(l)) preprocessing flag. To prevent garbled output on these terminals, when you use e also use t, to invoke col(lV) implicitly. This workaround has the disadvantage of eliminating superscripts and subscripts — even on those terminals that can display them. CTRL-Q will clear a terminal that gets confused by eqn(l) output. Sun Release 4.1 Last change: 12 January 1988 341 MESG(l) USER COMMANDS MESG(l) NAME mesg - permit or deny messages on the terminal SYNOPSIS mesg [ n ] [ y ] DESCRIPTION mesg with argument n forbids messages with write(l) by revoking non-user write permission on the user’s terminal, mesg with argument y reinstates permission. All by itself, mesg reports the current state without changing it. FILES /dev/tty* SEE ALSO write(l), talk(l) DIAGNOSTICS Exit status is 0 if messages are receivable, 1 if not, 2 on error. 342 Last change: 9 September 1987 Sun Release 4.1 MKDIR ( 1 ) USER COMMANDS MKDIR ( 1 ) NAME mkdir - make a directory SYNOPSIS mkdir [ -p ] dirname. . . DESCRIPTION mkdir creates directories. Standard entries, V, for the directory itself, and for its parent, are made automatically. The -p flag allows missing parent directories to be created as needed. With the exception of the set-gid bit, the current umask(2V) setting determines the mode in which direc- tories are created. The new directory inherits the set-gid bit of the parent directory. Modes may be modified after creation by using chmod(l V). mkdir requires write permission in the parent directory. SEE ALSO chmod(lV), rm(l), mkdir(2V), umask(2V) Sun Release 4.1 Last change: 22 August 1989 343 MKSTR(l) USER COMMANDS MKSTR(l) NAME mkstr - create an error message file by massaging C source files SYNOPSIS mkstr [ - ] messagefile prefix filename. . . 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 filename s, placing a massaged version of the input file in a file with a name consisting of the specified prefix and the original source file name. A typical example of using mkstr would be: mkstr pistrings processed *.c This command would cause all the error messages from the C source files in the current directory to be placed in the file pistrings and processed copies of the source for these files to be placed in files whose names are prefixed with processed. To process the error messages in the source to the message file, mkstr keys on the string ‘error(" ’ in the input stream. Each time it occurs, the C string starting at the ‘"’is placed in the message file followed by a null character and a NEWLINE character; the null character terminates the message so it can be easily used when retrieved, the NEWLINE 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; errorfal, a2, a3, a4) { char buf[256]; if (efil < 0) { efil = open(efilname, 0); if (efil < 0) { oops: perror (efilname); exit (1); } } if (Iseek(efil, (long) al, 0) 1 1 read(efil, buf, 256) <= 0) goto oops; printf(buf, a2, a3, a4); } OPTIONS - Place error messages at the end of the specified message file for recompiling part of a large mkstred program. SEE ALSO xstr(l) 344 Last change: 9 September 1987 Sun Release 4.1 MORE ( 1 ) USER COMMANDS MORE(l) NAME more, page — browse or page through a text file SYNOPSIS more [ — cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ filename ...] page [ -cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ filename ...] DESCRIPTION more is a filter that displays the contents of a text file on the terminal, one screenful at a time. It normally pauses after each screenful, and prints -More- at the bottom of the screen, more provides a two-line overlap between screens for continuity. If more is reading from a file rather than a pipe, the percentage of characters displayed so far is also shown. more scrolls up to display one more line in response to a RETURN character; it displays another screenful in response to a SPACE character. Other commands are listed below. page clears the screen before displaying the next screenful of text; it only provides a one-line overlap between screens. more sets the terminal to noecho mode, so that the output can be continuous. Commands that you type do not normally show up on your terminal, except for the / and ! commands. If the standard output is not a terminal, more acts just like cat(l V), except that a header is printed before each file in a series. OPTIONS -c Clear before displaying. Redrawing the screen instead of scrolling for faster displays. This option is ignored if the terminal does not have the ability to clear to the end of a line. -d Display error messages rather than ringing the terminal bell if an unrecognized command is used. This is helpful for inexperienced users. -f Do not fold long lines. This is useful when lines contain nonprinting characters or escape sequences, such as those generated when nroff(l) output is piped through ul(l). -1 Do not treat FORMFEED characters (CTRL-D) as “page breaks.” If -1 is not used, more pauses to accept commands after any line containing a X character (CTRL-D). Also, if a file begins with a FORMFEED, the screen is cleared before the file is printed. -s Squeeze. Replace multiple blank lines with a single blank line. This is helpful when viewing nrofT(l) output, on the screen. -u Suppress generation of underlining escape sequences. Normally, more handles underlining, such as that produced by nroff(l), in a manner appropriate to the terminal. If the terminal can perform underlining or has a stand-out mode, more supplies appropriate escape sequences as called for in the text file. -lines Display the indicated number of lines in each screenful, rather than the default (the number of lines in the terminal screen less two). +linenumber Start up at linenumber. +1 pattern Start up two lines above the line containing the regular expression pattern. Note: unlike editors, this construct should not end with a 7\ If it does, then the trailing slash is taken as a character in the search pattern. Sun Release 4.1 Last change: 9 September 1987 345 MORE ( 1 ) USER COMMANDS MORE ( 1 ) USAGE Environment more uses the terminal’s termcap(5) entry to determine its display characteristics, and looks in the environment variable MORE for any preset options. For instance, to page through files using the -c mode by default, set the value of this variable to -c. (Normally, the command sequence to set up this environ- ment variable is placed in the .login or .profile file). Commands The commands take effect immediately; it is not necessary to type a carriage return. Up to the time when the command character itself is given, the user may type the line kill character to cancel the numerical argument being formed. In addition, the user may type the erase character to redisplay the ‘-More- ( xx%)' message. In the following commands, / is a numerical argument (1 by default). /SPACE Display another screenful, or / more lines if / is specified. /RETURN Display another line, or / more lines, if specified. i“D (CTRL-D) Display (scroll down) 1 1 more lines. / is given, the scroll size is set to / . id Same as A D. /z Same as SPACE, except that / , if present, becomes the new default number of lines per screen- ful. is Skip i lines and then print a screenful, if Skip i screenfuls and then print a screenful. /“B (CTRL-B) Skip back / screenfuls and then print a screenful. b Same as "B (CTRL-D). q Q Exit from more. = Display the current line number. v Drop into the vi(l) editor at the current line of the current file, h Help. Give a description of all the more commands. il pattern Search for the / th occurrence of the regular expression pattern. Display the screenful starting two lines prior to the line that contains the / th match for the regular expression pattern , or the end of a pipe, whichever comes first. If more is displaying a file and there is no such match, its position in the file remains unchanged. Regular expressions can be edited using erase and kill characters. Erasing back past the first column cancels the search command. in Search for the / th occurrence of the last pattern entered. Single quote. Go to the point from which the last search started. If no search has been per- formed in the current file, go to the beginning of the file. ! command Invoke a shell to execute command . The characters % and !, when used within command are replaced with the current filename and the previous shell command, respectively. If there is no current filename, % is not expanded. Prepend a backslash to these characters to escape expan- sion. /:n Skip to the / th next filename given in the command line, or to the last filename in the list if / is out of range. /:p Skip to the / th previous filename given in the command line, or to the first filename if / is out of range. If given while more is positioned within a file, go to the beginning of the file. If more is reading from a pipe, more simply rings the terminal bell. 346 Last change: 9 September 1987 Sun Release 4.1 MORE ( 1 ) USER COMMANDS MORE ( 1 ) :f Display the current filename and line number. :q :Q Exit from more (same as q or Q ). . Dot. Repeat the previous command. A \ Halt a partial display of text, more stops sending output, and displays the usual --More- prompt. Unfortunately, some output is lost as a result. FILES /etc/termcap terminal data base /usr/lib/more.help help file SEE ALSO cat(lV), csh(l), man(l), script(l), sh(l), environ(5V), termcap(5) BUGS Skipping backwards is too slow on large files. Sun Release 4. 1 Last change: 9 September 1987 347 MT ( 1 ) USER COMMANDS MT ( 1 ) NAME mt - magnetic tape control SYNOPSIS mt [ -f tapename ] command [ count ] DESCRIPTION mt sends commands to a magnetic tape drive. If tapename is not specified, the environment variable TAPE is used. If TAPE does not exist, mt uses the device /dev/rmtl2. tapename refers to a raw tape device. By default, mt performs the requested operation once; multiple operations may be performed by specifying count. The available commands are listed below. Only as many characters as are required to uniquely identify a command need be specified. mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized or if mt was unable to open the specified tape drive, and 2 if an operation failed. OPTIONS eof, weof Write count EOF marks at the current position on the tape. fsf Forward space over count EOF marks. The tape is positioned on the first block of the file, fsr Forward space count records. bsf Back space over count EOF marks. The tape is positioned on the beginning-of-tape side of the EOF mark. bsr Back space count records. nbsf Back space count files. The tape is positioned on the first block of the file. This is equivalent to count+1 bsf’s followed by one fsf. asf Absolute space to count file number. This is equivalent to a rewind followed by a fsf count. For the following commands, count is ignored: eom Space to the end of recorded media on the tape. This is useful for appending files onto pre- viously written tapes. rewind Rewind the tape. offline, rewoffl Rewind the tape and, if appropriate, take the drive unit off-line by unloading the tape. status retension erase FILES /dev/rmt* /dev/rar* /dev/rst* Print status information about the tape unit. Rewind the cartridge tape completely, then wind it forward to the end of the reel and back to beginning-of-tape to smooth out tape tension. Erase the entire tape. magnetic tape interface Archive cartridge tape interface SCSI tape interface SEE ALSO ar(4S), mtio(4), st(4S), tm(4S), xt(4S) environ(5V) BUGS Not all devices support all options. Some options are hardware-dependent. Refer to the corresponding device manual page. 348 Last change: 19 December 1989 Sun Release 4.1 MT ( 1 ) USER COMMANDS MT(1) WARNINGS The bsf option for SCSI tape in SunOS 4.0.3 is incompatible with this release and releases prior to 4.0.3. Sun Release 4.1 Last change: 19 December 1989 349 MV(1) USER COMMANDS MV ( 1 ) NAME mv - move or rename files SYNOPSIS mv [ - ] [ -fi] filenamel filename2 mv [ - ] [ -f i ] directory 1 directory 2 mv [ - ] [ -f i ] filename . . . directory DESCRIPTION mv moves files and directories around in the file system. A side effect of mv is to rename a file or direc- tory. The three major forms of mv are shown in the synopsis above. The first form of mv moves (changes the name of) filenamel to filename2 . If filename2 already exists, it is removed before filenamel is moved. If filename2 has a mode which forbids writing, mv prints the mode (see chmod(2V)) 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) directory 1 to directory2 , only if directory2 does not already exist — if it does, the third form applies. The third form of mv moves one or more filenames (may also be directories) with their original names, into the last directory in the list. mv refuses to move a file or directory onto itself. OPTIONS - Interpret all the following arguments to mv as file names. This allows file names starting with minus. -f Force. Override any mode restrictions and the -i option. The -f option also suppresses any warn- ing messages about modes which would potentially restrict overwriting. -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. SEE ALSO cp(l), ln(lV), chmod(2V), rename(2V) DIAGNOSTICS mv: pathname: rename: Permission denied Attempted to move pathname into a directory that did not have write permission. BUGS If filenamel and filename2 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. Modification times may be different than expected when mv must copy the file’s data, rather than simply updating a directory entry. mv will not move a directory from one file system to another. Use cp(l) instead. 350 Last change: 23 September 1985 Sun Release 4.1 NAWK(l) USER COMMANDS NAWK(l) NAME nawk — pattern scanning and processing language SYNOPSIS awk [ -f program-file ] [ -F c ] [ program ] [ variable =value . . . ] [filename . . . ] DESCRIPTION nawk is a new version of awk(l) that provides additional features including, dynamic regular expressions, additional built-ins and operators, and user defined functions. Other implementations refer to this com- mand by its original name, awk, choosing to replace the original program with the enhanced one. Since there is a slight incompatibility between the two versions (see BUGS below) both versions are available in the SunOS environment, the original, awk, and the enhanced, nawk. nawk scans each input filename for lines that match any of a set of patterns specified in program, program string must be enclosed in single quotes ( ’ ) to protect it from the shell. For each pattern in program there may be an associated action performed when a line of a filename matches the pattern. The set of pattern- action statements may appear literally as program or in a file specified with the -f program-file option. OPTIONS -f filename Specify the contents of filename as the source for the program. -F c Set the input field separator to c. If the field separator is longer than one character, it is taken to be a regular expression, and should be enclosed in single quotes to protect special characters from the shell. variable =value Set a built-in variable to value before the first record of the next filename is read. See Built-in Variables below for a complete list of available variables. USAGE Input Lines Input files are read in order; if there are no files, the standard input is read. The file name means the standard input. Each input line is matched against the pattern portion of every pattern-action statement; the associated action is performed for each matched pattern. An input line is normally made up of fields separated by white space. This default can be changed by using the FS built-in variable or the -F c option.) The fields are denoted $1, $2, . . . ; $0 refers to the entire line. Pattern-action Statements nawk programs contain pattern-action statements of the form: pattern { action } Either pattern or action may be omitted. If there is no action with a pattern, the matching line is printed. If there is no pattern with an action, the action is performed on every input line. Patterns are arbitrary Boolean combinations (!,| | , &&, and parentheses) of relational expressions and reg- ular expressions. A relational expression is one of the following: expression relop expression expression matchop regular expression expression in array-name ( expression , expression, . . . ) in array-name where relop is any of the six relational operators in C, and matchop is either “ (contains) or !" (does not contain). An expression is an arithmetic expression, a relational expression, the special expression var in array, or a Boolean combination of these. Sun Release 4.1 Last change: 9 October 1989 351 NAWK ( 1 ) USER COMMANDS NAWK ( 1 ) The special patterns BEGIN and END may be used to capture control before the first input line has been read and after the last input line has been read respectively. They are the only patterns that require an action statement. These keywords do not combine with any other patterns. Regular expressions are as in egrep (see grep(lV). In patterns they must be surrounded by slashes. Iso- lated regular expressions in a pattern apply to the entire line. Regular expressions may also occur in rela- tional expressions. A pattern may consist of two patterns separated by a comma; in this case, the action is performed for all lines between an occurrence of the first pattern and the next occurrence of the second pat- tern. An action is a sequence of statements. A statement may be one of the following: if ( expression ) statement [ else statement ] while ( expression ) statement do statement while ( expression ) for ( expression ; expression ; expression ) statement for ( var in array ) statement delete may[subscript] break continue { [ statement ] . . . } expression # commonly variable = expression print [ expression-list ] [ expression ] printf format [ , expression-list ] [ expression ] next # skip remaining patterns on this input line exit [expr] # skip the rest of the input; exit status is expr return [expr] Statements are terminated by semicolons, right braces, or NEWLINE characters. An empty expression-list stands for the whole input 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 [*']), or fields. Variables are initialized to the null string or zero. Array subscripts may be any string, not necessarily numeric; this allows for a form of associative memory. String constants are quoted ("). The print statement prints its arguments on the standard output, or on a file if expression is present, or on a pipe if ‘| cmd' is present. The arguments are separated by the current output field separator and ter- minated by the output record separator. The printf statement formats its expression list according to the format (see printf(3V)). Built-in Variables A regular expression may be used to separate fields by using the -F c option or by assigning the expres- sion to the built-in variable FS. The default is to ignore leading blanks and to separate fields by blanks and/or tab characters. However, if FS is assigned a value, leading blanks are no longer ignored. Built-in variables include: ARGC Command line argument count. ARGV Command line argument array. FILENAME Name of the current input file. FNR Ordinal number of the current record in the current file. FS Input field separator regular expression (default blank). NF Number of fields in the current record. NR Ordinal number of the current record. OFMT Output format for numbers (default % .6g). 352 Last change: 9 October 1989 Sun Release 4.1 NAWK(l) USER COMMANDS NAWK(l) OFS Output field separator (default blank). ORS Output record separator (default NEWLINE). RS Input record separator (default NEWLINE). SUBSEP Separates multiple subscripts (default is 034). nawk has a variety of built-in functions: arithmetic, string, input/output, and general. The arithmetic functions are: atan.2, cos , exp, int, log, rand, sin, sqrt, and srand. int truncates its argument to an integer, rand returns a random number between 0 and 1 . srand ( expr ) sets the seed value for rand to expr or uses the time of day if expr is omitted. The string functions are: gsub (for,‘repl,‘in) behaves like sub (see below), except that it replaces successive occurrences of the regu- lar expression (like the ed global substitute command). index(s,t) returns the position in string s where string t first occurs, or 0 if it does not occur at all. int truncates to an integer value. length(s) returns the length of its argument taken as a string, or of the whole line if there is no argument. match(s,‘re) returns the position in string s where the regular expression re occurs, or 0 if it does not occur at all. RSTART is set to the starting position (which is the same as the returned value), and RLENGTH is set to the length of the matched string. rand random number on (0, 1). splits, ‘a, 'fs) splits the string s into array elements a [7], a [2], a[n], and returns n. The separation is done with the regular expression fs or with the field separator FS if fs is not given. srand sets the seed for rand sprintf (fmt,' expr,' expr,'. . .) formats the expressions according to the printf(3V) format given by fmt and returns the resulting string. sub(for,‘repl,‘in ) substitutes the string repl in place of the first instance of the regular expression for in string in and returns the number of substitutions. If in is omitted, nawk substitutes in the current record ($0). substr(j,‘ffz,‘fl) returns the « -character substring of s that begins at position m. The input/output and general functions are: close(filename) closes the file or pipe named filename . cmd I getline pipes the output of cmd into getline; each successive call to getline returns the next line of output from cmd. getline sets $0 to the next input record from the current input file. getline 72 Print first two fields in opposite order: { print $2, $1 } Same, with input fields separated by comma and/or blanks and tabs: BEGIN { FS = ",[ \t]*|[ \t]+" } { 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: { 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 } Simulate echo(l V): BEGIN { for (i = 1; i < ARGC; i++) printf " %s", ARGV[i] printf "\n" exit } Print file, filling in page numbers starting at 5: /Page/ { $2 = n++; } { print } example% nawk -f program n=5 input SEE ALSO grep(lV), lex(l), sed(lV), printf(3V) Editing Text Files A. V. Aho, B. W. Keminghan, P. J. Weinberger, The AWK Programming Language Addison-Wesley, 1988. 354 Last change: 9 October 1989 Sun Release 4.1 NAWK(l) USER COMMANDS NAWK ( 1 ) BUGS Input white space is not preserved on output if fields are involved. 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 the null string (" ") to it. Pattern-action statements must be separated by either a semi-colon or a NEWLINE. This is an incompatibil- ity with the old version of awk. Sun Release 4. 1 Last change: 9 October 1989 355 NEWGRP ( 1 ) USER COMMANDS NEWGRP ( 1 ) NAME newgrp - log in to a new group SYNOPSIS newgrp [ - ] [ group ] DESCRIPTION newgrp changes a user’s group identification. Only the group-ID is changed; the user remains a member of all groups previously established by setgroups (see getgroups(2V)). The user remains logged in and the current directory is unchanged, but the group-ID of newly-created files will be set to the new effective group-ID (see open(2V)). The user is always given a new shell, replacing the current shell, regardless of whether newgrp terminated successfully or due to an error condition (such as an unknown group). Exported variables retain their values after invoking newgrp; however, all unexported variables are either reset to their default value or set to null. System variables (such as HOME, LOGNAME, PATH, SHELL, TERM, and USER), unless exported by the system or explicitly exported by the user, are reset to default values. Note: the shell command export (see sh(l)) is the method to export variables, while the C shell command setenv (see csh(l)) implicitly exports its argument. With no arguments, newgrp changes the group identification back to the group specified in the user’s pass- word file entry. If the first argument to newgrp is a the environment is changed to what would be expected if the user actually logged in again. A password is demanded if the group has a password and the user does not, or if the group has a password and the user is not listed in /etc/group as being a member of that group. FILES /etc/group system group file /etc/passwd system password file SEE ALSO csh(l), login(l), sh(l), su(lV), open(2V), getgroups(2V), initgroups(3), environ(SV), group(5), passwd(5) NOTES For consistency with login naming rules (which do not allow 8-bit file names), group identifications cannot contain 8-bit characters. See login(l) for explanations about why login is not 8-bit clean. BUGS There is no convenient way to enter a password into /etc/group. Use of group passwords is not encouraged, because, by their very nature, they encourage poor security practices. Group passwords may disappear in the future. 356 Last change: 16 November 1987 Sun Release 4.1 NICE ( 1 ) USER COMMANDS NICE ( 1 ) NAME nice — run a command at low priority SYNOPSIS nice [ -number ] command [ arguments ] DESCRIPTION There are two distinct versions of nice: it is built in to the C shell, and is an executable program available in /usr/bin/nice for use with the Bourne shell. nice executes command with the “nice” value number. The nice value is one of the factors used by the kernel to determine a process’s scheduling priority. Scheduling priorities range from 0 to 127. The higher the value, the lower the command’s scheduling priority, and the lower the value, the higher the command’s scheduling priority. In addition to the nice value, the kernel also recent CPU usage by the process, the time the process has been waiting to run, and other factors to arrive at scheduling priority. If the number argument is present, the nice value is incremented or decremented by that amount, between the limits -20 and 19. If there is no number argument, the default nice value is 10 for the Bourne shell, and 4 for the C-shell. The super-user may run commands with priority higher than normal by using negative nice values, such as - 10 . EXAMPLES The following examples illustrate the use of nice values for users (not the super-user) using /usr/bin/nice. The examples use the -1 option to ps(l) because it shows both the nice value and the kernel scheduling priority. Notice the NI and PRI columns. In the first example, the user doesn’t use nice, so the niceness is zero, the default value, which is reflected by 0 in the NI column. The corresponding process scheduling priority is shown in the PRI column as 28 (this may vary because of the other factors the kernel’s scheduler uses). In the second example, the user uses a nice value of 10, and the corresponding priority is 53, a higher numerical value but a lower priority. Notice that this is the same as: example% nice ps -1 because the default nice value is 10. In the third example, the user asks that the nice value be incremented by 20, but it’s shown as 19 under NI, because that’s the upper limit of niceness. A fourth example shows the error message when an ordinary user tries to decrement the nice value. example% ps-I F UID PID PPID CP PRI NI SZ RSS WCHAN ST AT TT TIME COMMAND 1944216623 972512 28 0120 336 R p2 0:00 ps-1 example % nice -10 ps -1 F UID PID PPID CP PRI NI SZ RSS WCHAN ST AT TT TIME COMMAND 19442 16608 16606 32 53 10 120 328 R N p2 0:00 ps -1 example% nice -20 ps -1 F UID PID PPID CP PRI NI SZ RSS WCHAN ST AT TT TIME COMMAND 19442 16609 16606 37 72 19 120 328 R N p2 0:00 ps -1 Sun Release 4. 1 Last change: 9 September 1987 357 NICE ( 1 ) USER COMMANDS NICE ( 1 ) example% nice — 20 ps -1 nice: setpriority: Permission denied example % SEE ALSO csh(l), getpriority(2), nice(3V), pstat(8), renice(8) DIAGNOSTICS nice returns the exit status of the subject command. BUGS The nice command has a different syntax than the /usr/bin/nice command described here. It uses the plus sign, +, to increment nice values, for example: example% nice + number increments the nice value by number. It uses a single a minus sign, — , to decrement nice values for super- user. 358 Last change: 9 September 1987 Sun Release 4.1 NL(1V) USER COMMANDS NL(1V) NAME nl - line numbering filter SYNOPSIS nl [ -p ] [ -h type ] [ -b type ] [ -ftype ] [ -v start ] [ -iincr ] [ -1 num ] [ -s sep ] [ -w width ] [ -nfmt ] [ -Adelim ] filename AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION nl reads lines from filename (or the standard input), numbers them according to the options in effect, and sends its output to the standard output. nl views the text it reads in terms of logical pages. Line numbering is normally reset at the start of each page. A logical page is composed of header, body and footer sections. The start of each page section is signaled by input lines containing section delimiters only: Start of file header \:\: body \: footer Empty sections are valid. Different line-numbering options are available within each section. The default scheme is no numbering for headers and footers. OPTIONS -p Do not restart numbering at logical page delimiters. -b type Specify which logical page body lines are to be numbered, type is one of: a number all lines t number lines with printable text only (the default) n no line numbering p rexp number only lines that contain the regular expression rexp — h type Same as — b type except for the header. The default type for the logical page header is n (no lines numbered). -ftype Same as -b type except for the footer. The default for logical page footer is n (no lines num- bered). -\start start is the initial value used to number logical page lines. The default is 1. -iincr incr is the increment by which to number logical page lines. The default is 1. -s sep sep is the character(s) used to separate the line number from the corresponding text line. The default is a TAB. -wwidth width is the number of characters to be used for the line-number field. The default is 6. -nfmt fmt is the line numbering format. Recognized values are: rn right justified, leading zeroes suppressed (the default) In left justified, leading zeroes suppressed rz right justified, leading zeroes kept Sun Release 4.1 Last change: 17 September 1989 359 NL(1V) USER COMMANDS NL(1V) —\num num is the number of blank lines to be considered as one. For example, —12 results in only the second adjacent blank being numbered (if the appropriate -ha, -ba, and/or -fa option is set). The default is 1. -dbcc The delimiter characters specifying the start of a logical page section may be changed from the default characters (k) to two user-specified characters. If only one character is entered, the second character remains the default character (:). No space should appear between the -d and the delimiter characters. To enter a backslash, use two backslashes. EXAMPLE The command: nl -vlO -ilO -d!+ filenamel will number filenamel starting at line number 10 with an increment of ten. The logical page delimiters are !+. SEE ALSO pr(lV) 360 Last change: 17 September 1989 Sun Release 4.1 NM(1) USER COMMANDS NM(1) NAME nm - print symbol name list SYNOPSIS nm [ -gnoprsua ] [ [filename ]... DESCRIPTION nm prints the name list (symbol table) of each object filename in the argument list. If an argument is an archive, a listing for each object file in the archive will be produced. If no filename is given, the symbols in a.out are listed. Output Format Each symbol name is preceded by its value (blanks if undefined) and one of the letters: A absolute B bss segment symbol C common symbol D data segment symbol f filename t a static function symbol T text segment symbol U undefined - debug, giving symbol table entries (see -a below) The type letter is upper case if the symbol is external, and lower case if it is local. The output is sorted alphabetically. OPTIONS -a Print all symbols. -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 Do not sort; print in symbol-table order. -r Sort in reverse order. -s Sort according to the size of the external symbol (computed from the difference between the value of the symbol and the value of the symbol with the next higher value). This difference is the value printed. -u Print only undefined symbols. EXAMPLE example % nm prints the symbol list of the file named a.out, the default output file for the C, compiler. SEE ALSO ar(lV), as(l), cc(lV), ld(l), tmpnam(3S), a.out(5), ar(5), coff(5) BUGS To see what is in a shared library, run nm on the static (.a) version. Sun386i BUGS When all the symbols are printed, they must be printed in the order they appear in the symbol table in order to preserve scoping information. Therefore, the -v and -n options should be used only in conjunction with the -e option. Sun Release 4.1 Last change: 7 September 1989 361 NOHUP(IV) USER COMMANDS NOHUP(IV) NAME nohup - run a command immune to hangups and quits SYNOPSIS /usr/bin/nohup command [ arguments ] SYSTEM V SYNOPSIS /usr/5bin/nohup command [ arguments ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION There are three distinct versions of nohup: it is built in to the C shell, and is an executable program avail- able in /usr/bin/nohup and /usr/5bin/nohup when using the Bourne shell. The Bourne shell version of nohup executes command such that it is immune to HUP (hangup) and TERM (terminate) signals. If the standard output is a terminal, it is redirected to the file nohup.out. The standard error is redirected to follow the standard output. The priority is incremented by 5. nohup should be invoked from the shell with ‘&’ in order to prevent it from responding to interrupts or input from the next user. SYSTEM V DESCRIPTON Processes run by nohup are immune to HUP (hangup) and QUIT (quit) signals; nohup does not arrange to make them immune to a TERM (terminate) signal, so unless they arrange to be immune to a TERM signal, or the shell makes them immune to a TERM signal, they will receive that signal. If nohup.out is not writ- able in the current directory, output is redirected to $HOME/nohup.out. If the standard error is a terminal, it is redirected to the standard output, otherwise it is not redirected. The priority of the process run by nohup is not altered. EXAMPLE It is frequently desirable to apply nohup to pipelines or lists of commands. This can be done only by plac- ing pipelines and command lists in a single file, called a shell script. The command example % nohup sh script applies to everything in script. (If the script is to be executed often, then the need to type sh can be elim- inated by giving script execute permission). Add an ampersand and the contents of script are run in the background with interrupts also ignored (see sh(l)): example % nohup script & FILES nohup.out $HOME/nohup.out SEE ALSO chmod(lV), csh(l), nice(l), sh(l), signaI(3V) BUGS If you use csh(l), then commands executed with *&’ are automatically immune to HUP signals while in the background. There is a C shell built-in command nohup that provides immunity from terminate, but does not redirect output to nohup.out. 362 Last change: 10 January 1988 Sun Release 4.1 NOHUP(IV) USER COMMANDS NOHUP(IV) nohup does not recognize command sequences. For instance, nohup commandl ; command.2 applies only to commandl and the command: nohup ( commandl ; command2 ) is syntactically incorrect. Be careful of where the standard error is redirected. The following command may put error messages on tape, making it unreadable: nohup cpio -o < list > /dev/rmt/lm& while nohup cpio -o < list > /dev/rmt/lm 2>errors& puts the error messages into the file errors. Sun Release 4.1 Last change: 10 January 1988 363 NROFF(l) USER COMMANDS NROFF(l) NAME nroff - format documents for display or line-printer SYNOPSIS nroff [ -ehig ] [ -m name ] [ -mV ] [ -o pagelist ] [ -raN ] [ -sN ] [ -T name ] AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION nroff formats text in the named files for typewriter-like devices. See also troff(l). The full capabilities of nroff and troff are described in Formatting Documents. If no file argument is present, nroff reads the standard input. An argument consisting of a ’ 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. -e Produce equally-spaced words in adjusted lines, using full terminal resolution. -h Use output TAB characters during horizontal spacing to speed output and reduce output character count. TAB settings are assumed to be every 8 nominal character widths. -i Read the standard input after the input files are exhausted. -q Invoke the simultaneous input-output mode of the rd request. -m name Prepend the macro file /usr/share/lib/tmac/tmac.name to the input files. -aN Number first generated page N . -opagelist Print only pages whose page numbers appear in the comma-separated list of numbers and ranges. A range N-M means pages N through M\ an initial -N means from the beginning to page N; and a final N- means from N to the end. -raN Set register a (one-character) to N. -sN Stop every N pages, nroff will halt prior to every N pages (default N= 1) to allow paper loading or changing, and will resume upon receipt of a NEWLINE. -T name Prepare output for a device of the specified name. Known names are: 37 Teletype Corporation Model 37 terminal — this is the default, crt I Ipr I tn300 GE TermiNet 300, or any line printer or terminal without half-line capa- bility. 300 DASI-300. 300-12 DASI-300 — 12-pitch. 300S I 302 1 dtc DASI-300S. 300S-12 I 302-12 I dtcl2 DASI-300S. 382 DASI-382 (fancy DTC 382). 382-12 DASI-82 (fancy DTC 382 — 12-pitch). 450 I ipsi DASI-450 (Diablo Hyterm). 450-12 ! ipsil2 DASI-450 (Diablo Hyterm) — 12-pitch. 450-12-8 DASI-450 (Diablo Hyterm) — 12-pitch and lines-per-inch. 450X DASI-450X (Diablo Hyterm). 832 AJ 832. 364 Last change: 22 December 1987 Sun Release 4.1 NROFF ( 1 ) USER COMMANDS NROFF ( 1 ) 833 AJ 833. 832-12 AJ 832 — 12-pitch. 833-12 AJ 833 — 12-pitch. epson Epson FX80. itoh C:ITOH Prowriter. itoh-12 C:ITOH Prowriter — 12-pitch. nec NEC 5570 or NEC 7770 Spinwriter. necl2 NEC 5570 or NEC 7770 Spinwriter — 12-pitch. nec-t NEC 5570/7770 Spinwriter — Tech-Math/Times-Romanthimble. qume Qume Sprint — 5 or9. qumel2 Qume Sprint — 5 or 9,12-pitch. xerox Xerox 1770 or Diablo 1670. xeroxl2 Xerox 1770 or Diablo 1670 — 12-pitch. x-ecs Xerox/Diablo 1730/630 — Extended Character Set. x-ecsl2 Xerox/Diablo 1730/630 — Extended Character Set, 12-pitch. man Dumb terminal, used for online man pages. EXAMPLE The following command: example% nroff -s4 -me users.guide formats users.guide using the - -me macro package, and stopping every 4 pages. FILES /tmp/ta* temporary file /usr/share/lib/tmac/tmac.* standard macro files /usr/share/lib/term/* terminal driving tables for nroff /usr/share/lib/term/README index to terminal description files SEE ALSO checknr(l), col(lV), eqn(l), tbl(l), troff(l), term(5), man(7), me(7), ms(7) Formatting Documents NOTES nroff is not 8-bit clean because making nroff 8-bit clean would require rewriting the nroff internals and filters. Also, some nroff syntax is based on ASCII only and does not lend itself to 8-bit character sequences. Sun Release 4.1 Last change: 22 December 1987 365 OBJDUMP ( 1 ) USER COMMANDS OBJDUMP ( 1 ) NAME objdump - dump selected parts of a COFF object file SYNOPSIS objdump [ option [ modifier . . . ] ] filename . . . AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION The objdump command dumps selected parts of each of its object filename arguments. This command is compatible with System V in all its options. It will accept both object files and archives of object files. objdump command attempts to format the information it dumps in a meaningful way, printing certain information in character, hex, octal or decimal representation as appropriate. OPTIONS -a Dump the archive header of each member of each archive file argument. -g Dump the global symbols in the symbol table of an archive. -f Dump each file header. -o Dump each optional header. -h Dump section headers. -s Dump section contents. -r Dump relocation information. -1 Dump line number information. -t Dump symbol table entries. -z name Dump line number entries for the named function. -c Dump the string table. -L Interpret and print the contents of the .lib sections. Modifiers The following modifiers are used in conjunction with the options listed above. -d number Dump the section number, number, or the range of sections starting at number and ending at the number specified by +d. +d number Dump sections in the range either beginning with first section or beginning with section specified by -d. -n name Dump information pertaining only to the named entity. This modifier applies to -h, -s, -r, -I, and -t. — p Suppress printing of the headers. -t index Dump only the indexed symbol table entry. The -t used in conjunction with +t, specifies a range of symbol table entries. +t index Dump the symbol table entries in the range ending with the indexed entry. The range begins at the first symbol table entry or at the entry specified by the -t option. -u Underline the name of the file for emphasis. -v Dump information in symbolic representation rather than numeric (e.g., C STATIC instead of 0X02). This modifier can be used with all the above options except -s and -o. 366 Last change: 19 February 1988 Sun Release 4.1 OBJDUMP ( 1 ) USER COMMANDS OBJDUMP ( 1 ) — z name , number -x name number Dump line number entry or range of line numbers starting at number for the named function. +z number Dump line numbers starting at either function name or number specified by -x, up to number specified by +z. White space separating an option and its modifier is optional. SEE ALSO ar(5), coff(5) Sun Release 4. 1 Last change: 19 February 1988 367 0D(1V) USER COMMANDS OD(IV) NAME od - octal, decimal, hexadecimal, and ascii dump SYNOPSIS od [ -format ] [filename ] [ [+]offset[.] [b] [label] ] SYSTEM V SYNOPSIS /usr/5bin/od [ arguments ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION od displays filename, or its 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 an EOF. Format Arguments 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: NUL=\0, BACKSPACES, FORMFEEDS, NEWLINES, RETURNS, TABS; others appear as 3-digit octal numbers. Bytes with the parity bit set are displayed in octal. d Interpret (short) words as unsigned decimal. f Interpret long words as floating point. h Interpret (short) words as unsigned hexadecimal. i Interpret (short) words as signed decimal. 1 Interpret long words as signed decimal. o Interpret (short) words as unsigned octal. s[n] Look for strings of ASCII graphic characters, terminated with a null byte, n specifies the minimum length string to be recognized. By default, the minimum length is 3 characters. v Show all data. By default, display lines that are identical to the last line shown are not output, but are indicated with an in column 1. w[n] Specifies the number of input bytes to be interpreted and displayed on each output line. If w is not specified, 16 bytes are read for each display line. If n is not specified, it defaults to 32. x Interpret (short) words as hexadecimal. An upper case format character implies the long or double precision form of the object. The offset argument specifies the byte offset into the file where dumping is to commence. By default this argument is interpreted in octal. A different radix can be specified; if V 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 filename argument is omitted, the offset argument must be preceded by *+’. The radix of the displayed address will be the same as the radix of the offset, if specified; otherwise it will be octal. label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in ( ) 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. 368 Last change: 2 October 1989 Sun Release 4.1 OD(IV) USER COMMANDS OD(IV) SYSTEM V DESCRIPTION The s format interprets (short) words as signed decimal, rather than searching for strings; the S format searches for strings. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout od. On entry to od, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. SEE ALSO adb(l), dbx(l), dbxtool(l), locale(5), iso_8859_l(7) BUGS A file name argument cannot start with *+’. A hexadecimal offset cannot 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 single character argument. Sun Release 4.1 Last change: 2 October 1989 369 OLD-COMPACT ( 1 ) USER COMMANDS OLD-COMP ACT(l) NAME old-compact, old-uncompact, old-ccat - compress and uncompress files, and cat them SYNOPSIS /usr/old/compact [ filename . . . ] uncompact [filename... ] ccat [filename... ] DESCRIPTION Note: This program is considered to be obsolete, and will not be distributed or supported in future Sun releases. compact compresses the named files using an adaptive Huffman code. If no file names are given, the stan- dard input is compacted to the standard output, compact operates as an on-line algorithm. Each time a byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huff- man code for the set of frequencies seen so far. It is unnecessary to prepend a decoding tree to the compressed file since the encoder and the decoder start in the same state and stay synchronized. Further- more, compact and uncompact can operate as filters. In particular: ... | compact | uncompact | . . . operates as a (very slow) no-op. When an argument file is given, it is compacted and the resulting file is placed in file.C; file is removed. The first two bytes of the compacted file code the fact that the file is compacted. This code is used to prohibit recompaction. The amount of compression to be expected depends on the type of file being compressed. Typical values of compression are: Text (38%), Pascal Source (43%), C Source (36%) and Binary (19%). These values are the percentages of file bytes reduced. uncompact restores the original file from a file called file. C which was compressed by compact. If no file names are given, the standard input is uncompacted to the standard output. ccat cats the original file from a file compressed by compact, without uncompressing the file. FILES *.C compacted file created by compact, removed by uncompact SEE ALSO Gallager, Robert G., Variations on a Theme of Huffman, I. E.E.E. Transactions on Information Theory, vol. IT-24, no. 6, November 1978, pp. 668 - 674. 370 Last change: 24 September 1987 Sun Release 4.1 OLD-EYACC ( 1 ) USER COMMANDS OLD-EYACC ( 1 ) NAME old-eyacc - modified yacc allowing much improved error recovery SYNOPSIS /usr/old/eyacc [ -v ] [ grammar ] DESCRIPTION eyacc is a version of yacc(l), that produces tables used by the Pascal system and its error recovery rou- tines. eyacc fully enumerates test actions in its parser when an error token is in the look-ahead set. This prevents the parser from making undesirable reductions when an error occurs before the error is detected. The table format is different in eyacc than it was in the old yacc, as minor changes had been made for efficiency reasons. SEE ALSO yacc(l) Practical LR Error Recovery by Susan L. Graham, Charles B. Haley and W. N. Joy; SIGPLAN Conference on Compiler Construction, August 1979. BUGS pc and its error recovery routines should be made into a library of routines for the new yacc. Sun Release 4. 1 Last change: 24 September 1987 371 OLD-FILEMERGE ( 1 ) USER COMMANDS OLD-FILEMERGE ( 1 ) NAME old-filemerge - window-based file comparison and merging program SYNOPSIS /usr/old/filemerge [ -br ] [ -a ancestor ] [ -1 listfile ] [ leftfile [ rightfile [ outfile ] ] ] DESCRIPTION Note: This program is considered to be obsolete, and will not be distributed or supported in future Sun releases. filemerge is a window-based version of diff(l), for comparing and merging text files. It displays two files for side-by-side comparison, each in a read-only text-subwindow. Beneath them, an editing subwindow can be used to construct a merged version — one which contains selected lines from either or both input files, along with any additional edits you may make. leftfile and rightfile are the files to be compared, and outfile is name of the file containing the merged ver- sion. If outfile is a directory, then the output is placed in the file outfile! leftfile. If outfile is omitted, the output file is named filemerge. out by default. If no filename arguments are given, you can enter them from within the tool itself. OPTIONS -b Ignore leading blanks in comparisons. -r Read-only mode. Do not display the editing subwindow. -a ancestor Compare both files with respect to ancestor. A minus-sign indicates lines that have been deleted relative to the ancestor. A plus-sign indicates lines added relative to the ancestor. -1 listfile Process a list of filename pairs. With this option, leftfile and rightfile are the names of directories, and listfile contains a list of filenames that appear in both, filemerge compares the versions of each file between the two directories, and allows you to create a merged version (typically in the directory outfile). The SHIFT-Load command button, which is selected by holding the SHIFT key while clicking on the Load button, reads in the next pair named in the list. If listfile is then the list of files is read from the standard input. USAGE The text in the editing subwindow ( outfile ) is initially the same as that in leftfile. To construct a merged version, you can directly edit the text of outfile with textedit commands, or you can change a selected difference to match rightfile (the one on the right) by clicking the Right button in the top panel. Differences At any given time, one of the displayed “differences” is current. The current difference is indicated by emboldening the symbol adjacent to each line, and also by the notation “i of n” displayed in the control panel. Once a difference is current, you can use the Left and Right buttons to apply either the left-hand or the right-hand version of the text to outfile. The Next and Prev buttons select the next or previous differ- ence, respectively. Property Sheet You can customize filemerge using the property sheet to set or alter various display and control options. To bring up the property sheet, press the Props function key (typically L3) while the mouse is over any part of the filemerge window. Menus There are pop-up menus associated with several of the control panel items, and a menu associated with the editing subwindow. The former provide to select any command function obtained with a modified mouse- button (such as SHIFT-Next ); the editing subwindow’s menu has items that control the filename and direc- tory location of the merged output. To bring up a menu, move the mouse-cursor to the command button, or to the editing subwindow, and hold down the RIGHT mouse-button. Select a desired menu item by releas- ing the mouse-button after moving the cursor on top of it. 372 Last change: 9 September 1987 Sun Release 4.1 OLD-FILEMERGE ( 1 ) USER COMMANDS OLD-FILEMERGE ( 1 ) Command Buttons Next Make the next difference current. The subwindow scrolls, if necessary, to display it. SHIFT-Next 12 Make the first difference current. (Also a menu item from the Next menu.) Prev Make the previous difference current. SHIFT-Prev 12 Make the last difference current. (Also a menu item from the Prev menu.) Right Apply right-hand version of the current difference to outfile. If autoadvance is in effect, advance to the next difference. SHIFT-Right 12 Apply the right-hand version and advance to the next difference, unless autoadvance is in effect. (Also a menu item from the Right menu.) CTRL-Right Apply the right-hand version for the current difference, and for all subsequent differences up to the end of the file. Left Apply the left-hand version of the current difference. Undo Undo the last Right or Left operation. You can Undo up to 100 stacked operations. You cannot undo an Undo. SHIFT-Undo 12 Undo all the operations since the last Load, or the last 100 operations. Scroll-Lock When in effect, the three text-subwindows scroll in unison. Otherwise each subwindow scrolls independently. i of n The number of the current difference, i, out of n detected differences. Popping up a menu on this item allows you to jump to a selected difference. Load Load the files whose names appear by the prompts Filel: and File2:. SHIFT-Load 12 When the -I option is used, load the files from the directories shown in Filel and File2 corresponding to the next name in the list (taken from the listfile argument). Done Save outfile and close the tool. The name used to save the file appears in the namestripe, in the same fashion as textedit(l). SHIFT-Done 12 Save without closing. You can also save the merged version using the Save item in the editing subwindow’s menu. Quit Exit the tool. You must explicitly save your merged outfile, either with the Done button or the Save item in the editing subwindow’s menu. Properties Hitting the L3 function key brings up a property sheet that controls several filemerge parameters. The information in the property sheet is stored in the file 7. filemergerc. The property panel items have the fol- lowing meanings: Apply Any changes you have made to the property sheet will now take effect. Reset Reset the property sheet to the state it had at the time of the last Apply. Done Close the property sheet. autoadvance Advance to the next difference after each Left or Rightoperation. Toplines Number of lines in the top two subwindows. Bottomlines Number of lines in the bottom subwindow. Columns Number of columns in the left (and also right) subwindow. FILES 7. filemergerc file storing property sheet information filemerge.out default output file Sun Release 4.1 Last change: 9 September 1987 373 OLD-FILEMERGE ( 1 ) USER COMMANDS OLD-FILEMERGE ( 1 ) SEE ALSO diff(l), sdiff(lV), textedit(l) BUGS Using the Find function key gets the subwindows out of sync for scrolling. To resync them, turn Scroll Lock first off, and then on. 374 Last change: 9 September 1987 Sun Release 4.1 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) NAME old-make - maintain, update, and regenerate groups of programs SYNOPSIS /usr/old/make [ -f makefile ] . . . [ -bdeikmnpqrsSt ] [ target . . . ] [ macro-name =value . . . ] DESCRIPTION make executes a list of shell commands associated with each target, typically to create or update a file of the same name, makefile contains entries for targets that describe how to bring them up to date with respect to the files and/or other targets on which each depends, called dependencies . A target is out of date when the file it describes is missing, or when one (or more) of its dependency files has a more recent modification time than that of the target file, make recursively scans the list of depen- dencies for each target argument (or the first target entry in the makefile if no target argument is supplied) to generate a list of targets to check. It then checks, from the bottom up, each target against any files it depends on to see if it is out of date. If so, make rebuilds that target. To rebuild a target, make executes the set of shell commands, called a rule, associated with it. This rule may be listed explicitly in a makefile entry for that target, or it may be supplied implicitly by make. If no makefile is specified on the command line, make uses the first file it finds with a name from the fol- lowing list: makefile, Makefile, s.makefile, s.Makefile, SCCS/s.makefile, SCCS/s.Makefile. If no target is specified on the command line, make uses the first target defined in makefile. If a target has no makefile entry, or if its entry has no rule, make attempts to update that target using an implicit rule. OPTIONS -f makefile Use the description file makefile. A as the makefile argument denotes the standard input. The contents of makefile, when present, override the builtin rules. When more than one ‘-f makefile' argument pairs appear, make takes input from each makefile in the order listed (just as if they were run through cat(lV)). -b This option has no effect, but is present for compatibility reasons. -d Debug mode. Print out detailed information on files and times examined. -e Environment variables override assignments within makefiles. -i Ignore error codes returned by invoked commands. -k When a nonzero error status is returned by an invoked command, abandon work on the current target but continue with other branches that do not depend on that target. -n No execution mode. Print commands, but do not execute them. Even lines beginning with an @ are printed. However, if a command line contains the $(MAKE) macro, that line is always exe- cuted (see the discussion of MAKEFLAGS in Environment Variables and Macros). -p Print out the complete set of macro definitions and target descriptions. -q Question mode, make returns a zero or nonzero status code depending on whether or not the tar- get file is up to date. -r Do not use the implicit rules make supplies by default. Implicit rules defined in the makefile remain in effect. -s Silent mode. Do not print command lines before executing them. -S Undo the effect of the -k option. -t Touch the target files (bringing them up to date) rather than performing commands listed in their rules. Sun Release 4.1 Last change: 16 November 1987 375 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) macro-name =value Macro definition. This definition overrides any definition for the specified macro that occurs in the makefile itself, or in the environment. See Macros and Environment Variables and Macros , for details. USAGE Refer to SunOS User’s Guide: Doing More and Programming Utilities and Libraries for tutorial informa- tion about make. Targets and Rules There need not be an actual file named by a target, but every dependency in the dependency list must be either the name of a file, or the name of another target. If the target has no dependency list and no rule, or if the target has no entry in the makefile, make attempts to produce an entry by selecting a rule from its set of implicit rules. If none of the implicit rules apply, make uses the rule specified in the .DEFAULT target (if it appears in the makefile). Otherwise make stops and produces an error message. Makefile Target Entries A target entry has the following format: target . . . : [dependency ] . . . [; command ] . . . [command] The first line contains the name of a target (or a space-separated list of target names), terminated with a colon (:). This may be followed by a dependency , or a dependency list that make checks in the order listed. The dependency list may be terminated with a semicolon (;), which in turn can be followed by a Bourne shell command. Subsequent lines in the target entry begin with a TAB, and contain Bourne shell commands. These commands comprise a rule for building the target, and are performed when the target is updated by make. Shell commands may be continued across input lines by escaping the NEWLINE with a backslash (\). The continuing line must also start with a TAB. To rebuild a target, make expands any macros, strips off initial TAB characters and passes each resulting command line to a Bourne shell for execution. The first nonblank line that does not begin with a TAB or # begins another target or macro definition. Makefile Special Characters :: Conditional dependency branch. When used in place of a colon (:) the double-colons allow a tar- get to be checked and updated with respect to more than one dependency list. The double-colons allow the target to have more than one branch entry in the makefile, each with a different depen- dency list and a different rule, make checks each branch, in order of appearance, to see if the tar- get is outdated with respect to its dependency list. If so, make updates the target according to dependencies and rule for that branch. # Start a comment. The comment ends at the next NEWLINE. $ Macro expansion. See Macros, below, for details. Following the TAB, if the first character of a command line is a ‘-\ make ignores any nonzero error code it may return, make normally terminates when a command returns nonzero status, unless the -i or -k options are in effect. @ Following the TAB, if the first character is a make does not print the command line before executing it. If ’ and appear as the first two characters after the TAB, both apply. $$ The dollar-sign, escaped from macro expansion. Can be used to pass variable expressions begin- ning with $ to the shell. 376 Last change: 16 November 1987 Sun Release 4.1 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) Command Execution Command lines are executed one at a time, each by its own shell. Shell commands, notably cd, are ineffec- tual across an unescaped NEWLINE in the makefile. A line is printed (after macro expansion) as it is exe- cuted, unless it starts with a there is a .SILENT entry in the dependency hierarchy of the current target, or make is run with the -s option. Although the -n option specifies printing without execution, lines con- taining the macro $(MAKE) are executed regardless, and lines containing the @ special character are printed. The -t (touch) option updates the modification date of a file without executing any rules. This can be dangerous when sources are maintained by more than one person. To take advantage of the Bourne shell if control structure for branching, use a command line of the form: if expression ; \ then command ; \ command ; \ elif expression ; \ else command ; \ fi Although composed of several input lines, the escaped NEWLINE characters insure that make treats them all as one command line. To take advantage of the Bourne shell for control statement, use a command line of the form: for var in list ; do \ command ; \ done To write shell variables, use double dollar-signs ($$). This escapes expansion of the dollar-sign by make. Signals INT and QUIT signals received from the keyboard halt make and remove the target file being processed (unless it is in the dependency list for .PRECIOUS). Special-Function Targets When incorporated in a makefile, the following target names perform special functions. .DEFAULT If this target is defined in the makefile, its rule is used when there is no entry in the makefile for a given target and none of the implicit rules applies, make ignores the dependency list for this target. .PRECIOUS List of files not to delete. Files listed as dependencies for this target are not removed if make is interrupted while rebuilding them. .SILENT Run silently. When this target appears in the makefile, make does not echo commands before executing them. .IGNORE Ignore errors. When this target appears in the makefile, make ignores nonzero error codes returned from commands. .SUFFIXES The suffixes list for selecting implicit rules (see Implicit Rules). Include Files make has an include file capability. If the word include appears as the first seven letters of a line, and is followed by a SPACE or a TAB, the string that follows is taken as a filename. The text of the named file is read in at the current location in the makefile, include files can be nested to a depth of no more than about 16. Sun Release 4.1 Last change: 16 November 1987 377 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) Macros Entries of the form macro-name =value define macros, name is the name of the macro, and value , which consists of all characters up to a comment character or unescaped NEWLINE, is the value. Words in a macro value are delimited by SPACE, TAB, and escaped NEWLINE characters, and the terminating NEWLINE. Subsequent references to the macro, of the forms: $(name) or ${name) are replaced by value. The parentheses or brackets can be omitted in a reference to a macro with a single-character name. Macros definitions can contain references to other macros, but the nested references aren’t expanded immediately. Instead, they are expanded along with references to the macro itself. Substitutions within macros can be made as follows: $(name :strl =str2) where strl is either a suffix, or a word to be replaced in the macro definition, and str2 is the replacement suffix or word. Dynamically Maintained Macros There are several dynamically maintained macros that are useful as abbreviations within rules. $* The basename of the current target. It is assigned only for implicit rules. $< The name of the file on which the target is assumed to depend. This macro is only assigned for implicit rules, or within the .DEFAULT target’s rule. $@ The name of the current target. It is assigned only for rules in targets that are explicitly defined in the makefile. $? The list of dependencies with respect to which the target is out of date. This macro is assigned only for explicit rules. $% The library member. The $% macro is only evaluated when the target is an archive library member of the form: liblfile.o ). In this case, $@ evaluates to lib and $% evaluates to the library member, file.o. All of these macros but $? can be modified to apply either to the filename part, or the directory part of the strings they stand for, by adding an upper case F or D, respectively (and enclosing the resulting name in parentheses or braces). Thus, *$(@D)’ refers to the directory part of the string ‘$@’. If there is no direc- tory part, Y is generated. Environment Variables and Macros After reading in its implicit rules, make reads in variables from the environment, treating them as if they were macro definitions. Only then does make read in a makefile. Thus, macro assignments within a makefile override environment variables, provided that the — e option is not in effect. In turn, make exports environment variables to each shell it invokes. Macros not read in from the environment are not exported. The MAKEFLAGS macro is a special case. When present as an environment variable, make takes its options (except for -f, -p, and -d) from MAKEFLAGS in combination with any flags entered on the com- mand line, make retains this combined value, exports it automatically to each shell it forks, and reads its value to obtain options for any make commands it invokes. Note, however that flags passed with MAKEFLAGS even though they are in effect, are not shown in the output produced by make. The MAKE macro is another special case. It has the value make by default, and temporarily overrides the — n option for any line that contains a reference to it. This allows nested invocations of make written as: $(MAKE) . . . to run recursively, so that the command make -n can be used to test an entire hierarchy of makefiles. 378 Last change: 16 November 1987 Sun Release 4.1 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) For compatibility with the 4.2 BSD make, the MFLAGS macro is set from the MAKEFLAGS variable by prepending a \ MFLAGS is not exported automatically, make supplies the following macros for compilers and their options: cc C compiler, cc(lV) CFLAGS C compiler options FC FORTRAN 77 compiler, f77(l) FFLAGS RFLAGS FORTRAN 77 compiler options FORTRAN 77 compiler options with Ratfor (.r) source files PC Pascal compiler, pc(l) PFLAGS Pascal compiler options M2C Modula-2 compiler M2FLAGS Modula-2 compiler options GET sees (1) get command GFLAGS secs get options AS the assembler, as(l) ASFLAGS assembler options LD the linker, Id (1) LDFLAGS linker options LEX lex(l) LFLAGS lex options YACC yacc (1) YFLAGS yacc options Unless these macros are read in as environment variables, their values are not exported by make. If you run make with any these set in the environment, it is a good idea to add commentary to the makefile to indicate what value each takes. If-r is in effect, make ignores these macro definitions. When set to a single-word value such as /usr/bin/csh, the SHELL macro indicates the name of an alternate shell to use for invoking commands. Note: to improve normal performance make executes command lines that contain no shell metacharacters directly. Such builtin commands as dirs, or set in the C shell are not recognized unless the command line includes a metacharacter (for instance, a semicolon). Implicit Rules make supplies implicit rules for certain types of targets that have no explicit rule defined in the makefile. For these types of targets, make attempts to select an implicit rule by looking for an association between the target and a file in the directory that shares its basename. That file, if found, is presumed to be a depen- dency file. The implicit rule is selected according to the target’s suffix (which may be null), and that of the dependency file. If there is no such dependency file, if the suffix of either dependency or target is not the suffixes list, or if there is no implicit rule defined for that pair of suffixes, no rule is selected, make either uses the default rule that you have supplied (if any), or stops. The suffixes list is a target with each known suffix listed as a dependency, by default: .SUFFIXES: .o .c .c~ .mod .mod~ .sym .def .def~ .p .p~ .f .f~ .r ,r~ .y .y~ .1 .1~ .s .s~ .sh .sh~ .h .h Multiple suffix-list targets accumulate; a .SUFFIXES target with no dependencies clears the list of suffixes. Order is significant; make selects a rule that corresponds to the target’s suffix and the first dependency-file suffix found in the list. A tilde (~) refers to the s .prefix, of an SCCS history file (see sccs(l)). If make cannot locate a history file (with a name of the form s.basename. suffix) in the current working directory, it checks for one in the SCCS subdirectory (if that directory exists) for one from which to sccs-get(l) the dependency file. An implicit rule is a target of the form: dt : rule where t is the suffix of the target, d is the suffix of the dependency, and rule is the implicit rule for building such a target from such a dependency. Both d and t must appear in the suffixes list for make to recognize the target as one that defines an implicit rule. An implicit rule with only one suffix describes how to build a target having a null (or no) suffix, from a dependency having the indicated suffix. For instance, the .c rule describes how to build the executable file from a C source file, file .c. Sun Release 4.1 Last change: 16 November 1987 379 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) Implicit rules are supplied for the following suffixes and suffix pairs: .c .c~ .p .p .mod .mod .f .f .F .F .r .r .sh .sh .c.o .c .o .c .c .p.o .p .0 .p .p .mod.o .mod~.o .mod~.mod .def.sym .def~.sym .def~.def .f.o .f~.f .F.o .F~.o .F~.F .r.o .r~.o .r~.r .s.o .s~.o .s~.s .sh~.sh .y.o .y~.o .l.o .I~.o .y.c .y .c .y .y .I.c .1 .c .1 .1 .c.a .c~.a .s~.a .fo~.li These rules can be changed within a makefile, and additional implicit rules can be added. To print out make’s internal rules, use the following command. Note: this command only works with the Bourne Shell: $ make -fp - 2>/dev/null /dev/tty) >&/dev/null Library Maintenance If a target name contains parentheses, as with: lib.a(member) it is assumed to be the name of an archive (ar(lV)) library. The string within the parentheses refers to a member of the library. (If the string contains more than one word, the only first word is used.) A member of an archive can be explicitly made to depend on a file with a matching filename. For instance, given a directory that contains the files meml.c and mem2.c, along with a makefile with the entries: lib.a: lib.a(meml.o) lib.a(mem2.0) lib.a(meml.o): meml.o ar rv lib.a meml.o lib.a(mem2.o): mem2.o ar rv lib.a mem2.o make, when run, compiles the .c files into relocatable object (. 0 ) files using the .c.o implicit rule. It then loads the freshly compiled version of each file into the library according to the explicit rules in the lib.a()targets. Implicit rules pertaining to archive libraries have the form .XX .a where the XX is the suffix from which the archive member is to be made. An unfortunate byproduct of the current implementation requires that XX to be different from the suffix of the archive member itself. For instance, the target lib(/z/e.o) cannot depend upon the file.o explicitly, but instead, must be made to depend on a source file, such as file.c. For this rea- son it is recommended that you define an explicit target in the makefile for each library member to main- tain, as shown above. A target name of the form library ((entry-point)) refers to the member of a randomized object library (see ranlib(l)) that defines the symbol entry-point. EXAMPLES This makefile says that pgm depends on two files a.o and b.o, and that they in turn depend on their corresponding source files (a.c and b.c) along with a common file inckh: pgm: a.o b.o cc a.o b.o -o $@ a. o: incl.h a.c cc -c a.c b. o: incl.h b.c cc -c b.c 380 Last change: 16 November 1987 Sun Release 4.1 OLD-MAKE ( 1 ) USER COMMANDS OLD-MAKE ( 1 ) The following makefile uses the builtin inference rules to express the same dependencies: pgm: a.o b.o cc a.o b.o -o pgm a.o b.o: incl.h FILES [Mm]akefile s.[Mm]akefile SCCS/s.[mM]akefile DIAGNOSTICS Don’t know how to make target . Stop. There is no makefile entry for target , and none of make’s implicit rules apply (there is no depen- dency file with a suffix in the suffixes list, or the target’s suffix is not in the list). *** target removed. make was interrupted in the middle of trying to build target. Rather than leaving a partially- completed version that is newer than its dependencies, make removes the file associated with tar- get. *** Error code n. The previous shell command returned a nonzero error code. In this case make stops, unless either the -k or the -i option is set, the target .IGNORE appears, or the command is prefixed with a in the makefile. *** signal message The previous shell command was aborted due to a signal. If core dumped’ appears after the message, a core file was created. SEE ALSO ar(lV), cat(lV), cc(lV), cd(l), csh(l), Iex(l), ranlib(l), sccs(l), sccs-get(l), sh(l) SunOS User’s Guide: Doing More Programming Utilities and Libraries BUGS Some commands return nonzero status inappropriately; use -i to overcome the difficulty. Filenames with the characters =, :, and @ will not work. You cannot build lib(/z/e.o) from file.o. The macro substitution $(a:.o=.c") does not work. Options supplied by MAKEFLAGS should appear in output from make. Sun Release 4. 1 Last change: 16 November 1987 381 OLD-PRMAIL ( 1 ) USER COMMANDS OLD-PRMAIL ( 1 ) NAME old-prmail - display waiting mail SYNOPSIS /usr/old/prmail [ user ] ... DESCRIPTION Note: This program is considered to be obsolete, and will not be distributed or supported in future Sun releases. prmail displays waiting mail for you, or the specified users. The mail is not disturbed. FILES /var/spool/mail/* waiting mail files SEE ALSO biff(l), bin-mail(l), from(l), mail(l) 382 Last change: 31 March 1987 Sun Release 4.1 OLD-PTI ( 1 ) USER COMMANDS OLD-PTI ( 1 ) NAME old-pti - phototypesetter interpreter SYNOPSIS /usr/old/pti [ filename . . . ] DESCRIPTION Note: This program is considered to be obsolete, and will not be distributed or supported in future Sun releases. pti shows the commands in a stream from the standard output of troff(l) using troff’s -t option, interpret- ing the commands as they would act on the typesetter. Horizontal motions show 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 4.1 Last change: 16 November 1987 383 OLD-SETKEYS ( 1 ) USER COMMANDS OLD-SETKEYS ( 1 ) NAME old-setkeys — modify interpretation of the keyboard SYNOPSIS /usr/old/setkeys [ reset I nosunview I [ [ lefty ] [ noarrows ] ] ] [ sunl I sun2 I sun3 ] Sun386i SYNOPSIS setkeys [ reset I nosunview I [ [ lefty ] [ noarrows ] ] ] [ sunl I sun2 I sun3l sun4 ] DESCRIPTION setkeys has been superseded by the Input category in defaultsedit(l), and by the program input_from_defaults (1). It is retained for backwards compatibility on Sun-2, Sun-3 and Sun-4 systems. Sun386i DESCRIPTION setkeys changes the kernel’s keyboard translation tables, converting a keyboard to one of a number of commonly desired configurations. It takes an indication of the modifications to be performed, and option- ally, the kind of keyboard attached to the user’s machine. It affects all keyboard input for the machine it is run on (in or out of the window system) until that effect is superseded by rebooting, or by running ‘setkeys reset’. OPTIONS modifications Empty, or one of reset, nosunview, or some combination of lefty and noarrows. By default, the keyboard is set to produce the SunView function-key codes (Stop, Props, Front, Close, Find, Again, Undo, Copy, Paste and Cut; SunView User's Guide. On Sun-2 and Sun-3 keyboards, this is meaningless; on the Sun-1, those functions are assigned to two columns of the right numeric- function pad. lefty Indicate the SunView functions are to be produced from keys on the right side of the keyboard, convenient for using the mouse in the left hand. On the Sun-2 and Sun-3 systems, the SunView functions are reflected to the outside columns of the right function pad; those right-side functions are distributed in a more complicated fashion dic- tated by keeping the arrow keys together; see below. Also, the Line Feed key, immediately below Return, is converted to a second Control. On the Sun-1, lefty is the same as the default, since there is no left function pad. noarrows Reassign the keys with cursor arrows on their caps to produce simple function codes (so they may be used with filters in the textsw, or mapped input in the ttysw). nosunview Only valid on Sun-2 and Sun-3 keyboards, or on a Sun-4 keyboard used with 386i architecture, nosunview is incompatible with lefty, noarrows, or reset. This option assigns new codes to keys FI and L2 - L10, codes that are not normally produced anywhere on the keyboard. These codes may be selected by a mapi or mapo operation defined in a user’s .ttyswrc file. This option supports a measure of backwards compatibility to programs that apply some other interpretation to the affected function keys. It allows them to access the new codes when the stan- dard codes would be preempted by SunView functions (for instance, in a tty(l) subwindow). reset Incompatible with lefty, noarrows, or nosunview; it causes the keyboard to be reset to its original interpretation. keyboard-type One of sunl, sun2, or sun3. sun4 is available with 386i architecture only. Normally, this option is omitted; the type of keyboard attached to the system is obtained from the kernel. If included, the option is believed in preference to the kernel’s information, setkeys treats Sun-2 and Sun-3 keyboards identically except when the modification is reset. 384 Last change: 1 October 1987 Sun Release 4.1 OLD-SETKEYS ( 1 ) USER COMMANDS OLD-SETKEYS ( 1 ) Note: The keyboard type is not necessarily the same as the machine type. A Sun-1 keyboard is the VTlOO-style keyboard shipped with Model lOOUs, while Sun-2 and Sun-3 keyboards may be attached interchangeably to Sun-2 and Sun-3 machines. A Sun-3 keyboard is distinguished by its aerodynamic housing, and the presence of Caps and Alternate keys. Options may appear in any order, and case is not significant. The accompanying diagrams show the exact distribution of codes for each combination of keyboard and arguments to setkeys. EXAMPLES The command setkeys lefty noarrows puts the SunView functions on the right pad of the keyboard, replacing arrow keys by the corresponding right-function codes, and displacing right-function codes to the left pad. The command: setkeys sunl reset restores a Sun-1 keyboard to its original arrangement. SEE ALSO defaultsedit(l), input_from_defaults(l), kb(4M) SunView User' s Guide BUGS setkeys affects the kernel’s key tables, which in turn affects all users logged in to the system. DIAGRAMS Sun-1, reset: * V < > [ standard ] TF1 TF2 TF3 TF4 [ typing 1 7 8 9 - [ array 1 4 5 6 > [ ] 1 2 3 En- 0 • ter default / lefty: > < A V [ standard 1 Again RF1 Stop RF2 [ typing ] Undo RF3 Props RF4 [ array ] Put RF5 Front RF6 [ ] Get RF7 Close RF8 Delete Find default / lefty, noarrow: TF1 TF2 TF3 TF4 [ standard ] Again RF1 Stop RF2 [ typing 1 Undo RF3 Props RF4 [ array ] Put RF5 Front RF6 [ ] Get RF7 Close RF8 Delete Find Sun Release 4.1 Last change: 1 October 1987 385 OLD-SETKEYS ( 1 ) USER COMMANDS Sun-2 & Sun-3, reset / default: TF1 TF2 ... ] Stop Again [ standard ] RF1 RF2 RF3 Props Undo [ typing ] RF4 RF5 RF6 Front Put [ array ] RF7 A RF9 Close Get [ Retn < RF11 > Find Delete [ LF RF13 V RF15 noarrows (only) TF1 TF2 ... ] Stop Again [ standard 1 RF1 RF2 RF3 Props Undo [ typing ] RF4 RF5 RF6 Front Put [ array ] RF7 RF8 RF9 Close Get [ Retn RF10 RF11 RF12 Find Delete [ LF RF13 RF14 RF15 lefty: TF1 TF2 ... ] Stop RF1 [ standard ] Again < Stop RF6 RF4 [ typing 1 Undo > Props RF9 RF7 [ array ] Put A Front RF12 RF10 [ Retn Get RF11 Close RF15 RF13 [ Ctrl Delete V Find lefty, noarrows TF1 TF2 ... 1 Stop RF1 [ standard 1 Again RF2 Stop RF6 RF4 [ typing 1 Undo RF5 Props RF9 RF7 [ array 1 Put RF8 Front RF12 RF10 [ Ret Get RF11 Close RF15 RF13 [ Ctrl Delete RF14 Find nosunview: LF11 TF2 ... ] Stop TF11 [ standard ] RF1 RF2 RF3 LF12 TF12 [ typing ] RF4 RF5 RF6 LF13 TF13 [ array ] RF7 A RF9 LF14 TF14 [ Ret < RF11 > LF15 TF15 [ LF RF13 Y RF15 Last change: 1 October 1987 OLD-SETKEYS ( 1 ) Sun Release 4.1 386 0LD-SUN3CVT ( 1 ) USER COMMANDS OLD-SUN3CVT ( 1 ) NAME old-sun3cvt - convert large Sun-2 system executables to Sun-3 system executables SYNOPSIS /usr/old/sun3cvt [ oldfile [ newfile ] ] DESCRIPTION Note: This program is considered to be obsolete, and will not be distributed or supported in future Sun releases. sun3cvt converts an old Sun-2 system program file (predating Sun release 3.0) into a Sun-3 system execut- able file. The default oldfile is a.out. The default newfile is sun3.out. sun3cvt attempts to create a file of the same type (magic number). However, for sharable-text files with less than 128kb of text, the new file will not be sharable (since Sun-3 data segments must begin on 128kb boundaries). Also, most programs have some text in the data segment as a consequence of the new larger Sun-3 system page and segment sizes. execve(2V) executes an old Sun-2 system program file, but the program’s text is not sharable. Old pure- text programs with text segments larger than 128kb can be made sharable on machines running release 3.0 or subsequent releases by using sun3cvt. FILES a.out default oldfile sun3.out default newfile SEE ALSO execve(2V) Sun Release 4.1 Last change: 16 November 1987 387 OLD-SYSLOG ( 1 ) USER COMMANDS OLD-SYSLOG ( 1 ) NAME old-syslog - make a system log entry SYNOPSIS /usr/old/syslog [ — ] [ — p ] [ — i name ] [ -level ] [ message . . . ] DESCRIPTION Note: this program is considered to be obsolete, and will not be distributed or supported in future Sun releases. See logger(l) to add system log entries. syslog sends the specified message (or the standard input if is specified) as a system log entry to the syslog daemon. The log entry is sent to the daemon on the machine specified by the loghost entry in the /etc/hosts file. OPTIONS - Each line of the standard input is sent as a log entry. -p syslog logs its process ID in addition to the other information. -i name Specify the name to be used as the “ident” for the log entry. -level The message will be logged at the specified level. The level can be specified numerically, in the range 1 through 9, or symbolically using the names specified in the include file (with the leading LOG_ stripped off). syslog-HELP lists the valid symbolic level names. Only the super-user can make log entries at levels less than or equal to SALERT. FILES /usr/etc/syslogd syslog daemon SEE ALSO logger(l), syslog(3), syslogd(8) 388 Last change: 31 March 1987 Sun Release 4.1 OLD-VC(l) USER COMMANDS OLD- VC ( 1 ) NAME old- vc - version control SYNOPSIS /usr/old/vc [ -a ] [ -s ] [ -t ] [ -cc ] [ keyword=value ]. . . DESCRIPTION The vc command copies lines from the standard input to the standard output under control of its arguments and the control statements encountered in the standard input. In the process of performing the copy opera- tion, a reference to a user-declared keyword is replaced by its character-string value , when appearing in a plain text line or control statement. Copying lines from the standard input to the standard output is conditional, based on tests (in control state- ments) of keyword values specified either in control statements, or as vc command-line arguments. OPTIONS -a Force replacement of keyword references in all text lines, and not just in vc statements. -s Silent. Suppress warning messages (but not error messages) that are normally printed on the diag- nostic output. -t If a TAB character appears on a line, all characters from the beginning of a line, up to and includ- ing the first TAB, are ignored for the purpose of detecting a control statement. If the TAB precedes a control statement, the leading text is discarded. -cc Specify an alternate control character to use instead of USAGE vc distinguishes between text input lines and version control statement lines. A version control statement (control statement) is a single line beginning with a control character. The default control character is colon (:), except as modified by the -cc option. Input lines beginning with a backslash (\), and followed by a control character, are not control lines and are copied to the standard output as text with the backslash removed. Lines beginning with a backslash, but not followed by a control character, are copied in their entirety. Keyword Replacement A keyword is composed of 9 or less alphanumeric characters; the first must be alphabetic. A value is any printable ASCII character or character string. An unsigned string of digits is treated as a numeric value in control operations. Keyword values may not contain any SPACE or TAB characters. Keyword replacement is performed whenever a keyword, surrounded by control characters, is encountered on a version control statement. The -a option forces replacement of keywords in all lines of text. An uninterpreted control character may be included in a value by preceding it with ‘\\ If a literal ‘\’ is desired, then it too must be preceded by a ‘ \ ’. Version Control Statements : del keyword[Jceyword] Declare a keyword. All keywords must be declared. : asg keyword=value Assign a value to a keyword. An asg statement overrides any previous assignment for the corresponding keyword, including those on the vc command line. Keywords declared, but not assigned values, have null values. Sun Release 4.1 Last change: 16 November 1987 389 OLD-VC ( 1 ) USER COMMANDS OLD-VC ( 1 ) :if [not] condition :end Skip lines of the standard input. When condition is TRUE , all lines between the if statement and the matching end statement are copied to the standard output. Otherwise, the intervening lines are discarded and ignored, including intervening control statements. Intervening if and end control statements are recognized solely for the purpose of maintaining the proper if-end matching. The not argument inverts the sense of the condition. When it is used, intervening lines are included in the output only when the conditions is false. condition is a logical expression composed of comparisons and logical operators. A comparison consists of two text values (may be keyword references) separated by a comparison operator. Each value must be separated from all operators by at least one SPACE . Numeric strings are treated as unsigned integers for certain comparisons. The comparison operators are: = equal (string) != not equal (string) > greater than (numeric) < less than (numeric) For instance, the line: :ifxxc l=yyy tests to see whether the string ‘xxx’ is not equal to ‘yyy ’ , which is true; subsequent intervening lines are therefore included. The logical sense of comparisons can be combined using the logical operators (in order of pre- cedence): 0 & I For instance, the :if xxx = yyy \ xxx != yyy is true because either comparison will make it true, while : if xxx = yyy & xxx != yyy is false, because in this case, both comparisons must be true. '•'•text Force keyword replacement on lines that are copied to the standard output, independent from the -a option. The two leading control characters are removed, and keywords surrounded by control characters in text are replaced by their value before the line is copied to the output file. :on :off Turn on or off keyword replacement on all lines. :ctl c Change the control character to c. :msg message Print message on the diagnostic output. :err message Print the given message, followed by: ERROR: err statement on line , , . (915) on the diagnostic output; vc halts execution, and returns an exit code of 1. SEE ALSO sccs-help(l) logical grouping and or line 390 Last change: 16 November 1987 Sun Release 4.1 OLD-VC(l) USER COMMANDS OLD-VC(l) DIAGNOSTICS Use sccs-help(l) for explanations. Sun Release 4.1 Last change: 16 November 1987 391 0N(1C) USER COMMANDS ON(IC) NAME on - execute a command on a remote system, but with the local environment SYNOPSIS on [ — i ] [ — d ] [ — n ] host command [ argument ] . . . DESCRIPTION The on program is used to execute commands on another system, in an environment similar to that invok- ing the program. All environment variables are passed, and the current working directory is preserved. To preserve the working directory, the working file system must be either already mounted on the host or be exported to it. Relative path names will only work if they are within the current file system; absolute path names may cause problems. The standard input is connected to the standard input of the remote command, and the standard output and the standard error from the remote command are sent to the corresponding files for the on command. OPTIONS — i -d -n SEE ALSO chkey(l), publickey(5), exports(5), rexd(8C) DIAGNOSTICS unknown host Host name not found. cannot connect to server Host down or not running the server. can’t find Problem finding the working directory. can’t locate mount point Problem finding current file system. RPC: Authentication error The server requires des authentication and you do not have a secret key registered with keyserv. Perhaps you logged in without a password. Try to keylogin. If that fails try to set your publickey with chkey. Other error messages may be passed back from the server. BUGS The SunView window system can get confused by the environment variables. When the working directory is remote mounted over NFS, a "Z hangs the window. Root cannot use on. Interactive mode. Use remote echoing and special character processing. This option is needed for programs that expect to be talking to a terminal. All terminal modes and window size changes are propagated. Debug mode. Print out some messages as work is being done. No Input. This option causes the remote program to get EOF when it reads from the standard input, instead of passing the standard input from the standard input of the on program. For example, -n is necessary when running commands in the background with job control. 392 Last change: 8 September 1988 Sun Release 4.1 ORGANIZER ( 1 ) USER COMMANDS ORGANIZER ( 1 ) NAME organizer - file and directory manager SYNOPSIS organizer [ —A time ] AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION organizer is a SunView application for viewing and manipulating files and directories. It performs many of the functions of the ls(lV), cd(l), chmod(lV), cp(l), mv(l), mkdir(l), rmdir(see rm(l)), and dump(8) commands, and with a visual interface. At any given time, the organizer window normally shows the files and directories in a single directory, representing each file or directory with an appropriate illustrated icon. The illustration indicates whether a file is a directory, contains text, is an executable program, or optionally a user-defined file type. When organizer is switched into Map mode, the icons are arranged to indicate the hierarchy of files and directories. Double clicking on a directory icon shows the contents of that directory in a new column. Several display modes are available, and can be set for an individual organizer window or for all organ- izer windows. You can select whether hidden files are shown, whether just the name, the name and infor- mation, or name and icon are shown for each file and directory, and how the contents are sorted. Text files can be “edited” by double clicking on the file’s icon. The contents of the file are then shown and can be edited in a separate text editor window. In the .orgrc file you can specify the EXECUTE, EDIT, and PRINT applications for your own user-defined file types. You can move down through the directory hierarchy by double clicking on a directory icon, and up by dou- ble clicking on the parent directory name on the ancestor list in the upper left comer of the organizer panel. Copying, moving, and deleting require you to select one or more files. To select a file, click the left button on it (do not double click — this will open the file). To select additional files to be operated on, click the middle button on each additional file. Copying and moving operations require a destination directory. After the files are selected, change direc- tories to the desired destination as described above, and then “drop” the files with the Drop button on the command panel. If the copy involves overwriting an identically named file, an alert will allow you to confirm that you want to overwrite the file. If you copy a file and then “drop” it in the same directory, organizer will prepend copy_of_ to the file name of the new file. OPTIONS -A time Sets autoclose for time minutes. If organizer is not used for time minutes, it closes automatically. FILES /usr/include/images/* file and directory icons "/.orgrc ../.Deleted OrgFiles organizer creates this directory to store files so you can undo the last thing you did, for example, deleting files. SEE ALSO mkdir(l), mv(l), rm(l), orgrc(5), restore(8) Sun386i User s Guide Sun386i Advanced Skills Sun Release 4.1 Last change: 19 February 1988 393 OVERVIEW ( 1 ) USER COMMANDS OVERVIEW ( 1 ) NAME overview - run a program from SunView that takes over the screen SYNOPSIS overview [ -w ] [ generic _tool_options ] programjiame [ arguments ] . . . AVAILABILITY This command is available with the SunView User's Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Bitmap graphics based programs that are not SunView based can be run from SunView using overview, overview shows an icon in SunView when overview is brought up iconic (-Wi generic tool option; see sunview(l)) or when the program being run by overview is suspended (for example, using CTRL-Z). Opening the overview icon, or starting overview non-iconic, starts the program named on the command line, overview suppresses SunView so that SunView window applications will not interfere with the program’s display output or input devices. overview runs programs that fit the following profile: own display The program needs to own the bits on the screen. It does not use the sun- view library to arbitrate the use of the display and input devices between processes. keyboard input from stdin The program takes keyboard input from stdin directly. mouse input from /dev/mouse The program takes locator input from the mouse directly. OPTIONS -w This option is used to specify that the program being run creates its own SunWindows window in order to receive the serialized input stream from the keyboard and mouse that is provided by the SunWindows kernel driver, -w tells overview to not convert SunWindows input into ASCII which is then sent to the program being run under overview via a pty. X and NeWS are programs that fall in this category (as of Dec 86. This is subject to change in the future.) SEE ALSO sunview(l) BUGS Users of overview on a Sun-3/110 should be aware of the impact of plane groups on pre-3.2 applications. You cannot successfully run pre-3.2 applications under overview if overview itself is running in the color buffer. If you start overview so that it is not running in the overlay plane, then the enable plane is not be properly set up for viewing the application. This means that you cannot run overview with the -Wf or -Wb generic tool arguments. Also, you cannot run overview on a desktop created by sunview using the - 8bit_color_only option. 394 Last change: 21 December 1987 Sun Release 4.1 PACK (IV) USER COMMANDS PACK(IV) NAME pack, peat, unpack — compress and expand files SYNOPSIS pack [ - ] [ -f ] filename . . . peat filename. . . unpack filename .. . AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION pack attempts to store the specified files in a packed form using Huffman (minimum redundancy) codes on a byte-by-byte basis. Wherever possible (and useful), each input file filename is replaced by a packed file filename. z with the same access modes, access and modified dates, and owner as those of filename. If pack is successful, filename will be removed. Packed files can be restored to their original form using unpack or peat. The amount of compression obtained depends on the size of the input file and the frequency distribution of its characters. Because a decoding tree forms the first part of each .z file, it is usually not worthwhile to pack files smaller than three blocks unless the distribution of characters is very skewed. This may occur with printer plots or pictures. Typically, large text-files are reduced to 60-75% of their original size. Load modules, which use a larger character set and have a more uniform distribution of characters, show little compression. Their packed versions come in at about 90% of the original size. No packing will occur if: the file appears to be already packed the file name has more than 12 characters the file has links the file is a directory the file cannot be opened no disk storage blocks will be saved by packing a file called name. z already exists the .z file cannot be created an I/O error occurred during processing The last segment of the filename must contain no more than 12 characters to allow space for the appended .z extension. Directories cannot be packed. peat does for packed files what cat(lV) does for ordinary files, except that peat cannot be used as a filter. The specified files are unpacked and written to the standard output. To view a packed file named name. z use: peat file name. z or just: peat filename To make an unpacked copy without destroying the packed version, use peat filename > newname Sun Release 4. 1 Last change: 17 September 1989 395 PACK (IV) USER COMMANDS PACK(IV) Failure may occur if: the filename (exclusive of the .z) has more than 12 characters: the file cannot be opened; the file does not appear to be the output of pack. unpack expands files created by pack. For each file filename specified in the command, a search is made for a file called filename, z (or just filename, if filename ends in .z). If this file appears to be a packed, it is replaced by its expanded version. The new file has the .z suffix stripped from its name, and has the same access modes, access and modification dates, and owner as those of the packed file. Failure may occur for the same reasons that it may in peat, as well as for the following: « a file with the “unpacked” name already exists • the unpacked file cannot be created. OPTIONS - Print compression statistics for the following filename or names on the standard output. Subse- quent *-'s between filenames toggle statistics off and on. -f Force packing of filename. This is useful for causing an entire directory to be packed, even if some of the files will not benefit. DIAGNOSTICS pack returns the number of files that it failed to compress. peat returns the number of files it was unable to unpack. unpack returns the number of files it was unable to unpack. SEE ALSO cat(lV) 396 Last change: 17 September 1989 Sun Release 4.1 PAGESIZE ( 1 ) USER COMMANDS PAGESIZE ( 1 ) NAME pagesize - display the size of a page of memory SYNOPSIS pagesize DESCRIPTION pagesize prints the size of a page of memory in bytes, as returned by getpagesize(2). This program is use- ful in constructing portable shell scripts. SEE ALSO getpagesize(2) Sun Release 4. 1 Last change: 9 September 1987 397 PASSWD ( 1 ) USER COMMANDS PASSWD ( 1 ) NAME passwd, chfn, chsh - change local or NIS password information SYNOPSIS passwd [ -1 | -y ] [ -afs ] [ -d [ username ] ] [ -e username ] [ -F filename ] [ -n numdays username ] [ -x numdays username ] [ username ] chfn [ -1 | -y ] [ -f ] [ -F filename ] [ username ] chsh [ —1 | — y ] [ — s ] [ — F filename ] [ username ] DESCRIPTION passwd changes (or installs) a password, login shell (-s option), or full name (-f option) associated with the user username (your own by default), chsh is equivalent to passwd with the — s option, and chfn is equivalent to passwd with the -f option. Use ‘passwd — y’ or yppasswd(l) to change your password in the Network Information Service (NIS). This will not affect your local password, or your password on any remote machines on which you have accounts, passwd calls yppasswd automatically if you do not have an entry in the local passwd file, and the -1 option is not specified. When changing a password, 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. If password aging is enabled, the first time an ordinary user enters the new password passwd checks to see if the old password has “aged” sufficiently. Password “aging” is the amount of time (usually a certain number of days) that must elapse between password changes. If “aging” is insufficient the new password is rejected and passwd terminates. New passwords should be at least five characters long, if they combine upper-case and lower-case letters, or at least six characters long if in monocase. Users that persist in entering shorter passwords are compromising their own security. The number of significant characters in a password is eight, although longer passwords will be accepted. Only the owner of the name or the super-user may change a password; the owner must prove he knows the old password. The super-user can change any password and is not forced to comply with password aging requirements. When changing a login shell, passwd displays the current login shell and then prompts for the new one. The new login shell must be one of the approved shells listed in /etc/shells unless you are the super-user. If /etc/shells does not exist, the only shells that may be specified are /bin/sh and /bin/csh. The super-user may change anyone’s login shell; normal users may only change their own login shell. When changing a full name, passwd displays the current full name, enclosed between brackets, and prompts for a new full name. If you type a RETURN, the full name is not changed. If the full name is to be made blank, you must type the word “none”. The super-user may change anyone’s full name; normal users may only change their own. OPTIONS -a Display the name and aging information for all users. Can only be invoked by the super-user. -f Change the full name. -1 Change the local password, login shell, or full name. If username exists in the local passwd file, this is the default. -s Change the login shell. -y Change passwd, login shell, or full name in the NIS database. -d [ username ] Display the name and aging information for the caller or the user specified if the invoker has the right privileges. 398 Last change: 12 June 1988 Sun Release 4.1 PASSWD ( 1 ) USER COMMANDS PASSWD ( 1 ) — e username Expire the password for the user name specified. Can only be invoked by the super-user. -F filename Treat filename as the password file. -n numdays username Set the maturity time of the password for username. Passwords that have not “aged” enough can- not be changed. Can only be set by the super-user. -x numdays username Set the expiration time of the password for username. Can only be set by the super-user. FILES /etc/passwd file containing all of this information /etc/shells list of approved shells SEE ALSO finger(l), login(l), yppasswd(l), crypt(3), passwd(5) NOTES Password algorithms do not work with 8-bit characters. This maintains consistency with login file naming rules, which do not allow 8-bit characters in login names. See Iogin(l) for explanations about why login is not 8-bit clean. The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. Sun Release 4. 1 Last change: 12 June 1988 399 PASTE (IV) USER COMMANDS PASTE (IV) NAME paste — join corresponding lines of several files, or subsequent lines of one file SYNOPSIS paste filenamel filename2 . . . paste -d list filenamel filename2 . . . paste -s [ -d list ] filename AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION In the first two forms, paste concatenates corresponding lines of the given input files filenamel ,filename2 , etc. It treats each file as a column or columns of a table and pastes them together horizontally (parallel merging). It is the counterpart of cat(lV) which concatenates vertically, that is, one file after the other. In the last form above, paste replaces the function of an older command with the same name by combining subsequent lines of the input file (serial merging). In all cases, lines are glued together with the TAB char- acter, or with characters from an optionally specified list, paste can be used as a filter, if - is used in place of a filename. OPTIONS -d Without this option, the NEWLINE characters of each but the last file (or last line in case of the -s option) are replaced by a TAB character. This option allows replacing the TAB character by one or more alternate characters in list. The list is used circularly; when exhausted, it is reused. In parallel merging (no -s option), the lines from the last file are always terminated with a NEWLINE character, not from the list, list may contain the special escape sequences: \n (NEWLINE), \t (tab), \\ (backslash), and \0 (empty string, not a null character). Quoting may be necessary, if characters have special meaning to the shell. -s Merge subsequent lines rather than one from each input file. Use TAB for concatenation, unless list is specified with -d. Regardless of the list, the very last character of the file is forced to be a NEWLINE. EXAMPLES List directory in four columns: Is | paste Combine pairs of lines into lines: paste -s -d"\t\n" filename SEE ALSO cat(lV), cut(lV), grep(lV), pr(lV) DIAGNOSTICS line too long Output lines are restricted to 51 1 characters, too many files Except for -s option, no more than 12 input files may be specified. 400 Last change: 17 September 1989 Sun Release 4.1 PAX(IV) USER COMMANDS PAX ( IV ) NAME pax - portable archive exchange SYNOPSIS /usr/5bin/pax [ -cimopuvy ] [ -f archive [ -s replstr ] [ -t device ] [ pattern ... ] /usr/5bin/pax -r [ -cimnopuvy ] [ -f archive ] [ -s replstr ] [ -t device ] [ pattern . . . ] /usr/5bin/pax -w [ -adimuvy ] [ -b blocking ] [ -f archive ] [ -s replstr ] [ -t device ] [ -x format ] [ pathname . . . ] /usr/5bin/pax — rw [ — ilmopuvy ] [ -s replstr ] [ pathname ... ] directory AVAILABILITY pax is available with the System V software installation option. Refer to Installing SunOS 4.1 for informa- tion on how to install optional software. DESCRIPTION pax reads and writes archive files which conform to the Archive/Interchange File Format specified in IEEE Std. 1003.1-1988 (POSIX.l). pax can also read, but not write, a number of other file formats in addi- tion to those specified in the Archive/Interchange File Format description. Support for these traditional file formats, such as V7 tar(l) and System V binary cpio(l) format archives, is provided for backward compatibility and to maximize portability. pax will also support traditional cpio and System V tar interfaces if invoked with the name cpio or tar respectively. See the paxcpio(l V) or ustar(lV) manual pages for more details. directory specifies the destination directory pathname for copies when both the -r and -w options are specified. The directory must exist and be writable before the copy or and error results. pathname is a file whose contents are used instead of the files named on the standard input. When a direc- tory is named, all of its files and (recursively) subdirectories are copied as well. A pattern is given in the standard shell pattern matching notation. The default if no pattern is specified is which selects all files. Combinations of the -r and -w command line arguments specify whether pax will read, write or list the contents of the specified archive, or move the specified files to another directory. If neither the -r or -w options are given, pax will list the contents of the specified archive. In this mode, pax lists normal files one per line, hard link pathnames as pathname == linkname and symbolic link pathnames (if supported by the implementation) as pathname — > linkname where pathname is the name of the file being extracted, and linkname is the name of a file which appeared earlier in the archive. If the -v option is specified, then pax list normal pathnames in the same format used by Is(lV) with the -1 option. Hard links are shown as == linkname and symbolic links (if supported) are shown as -> linkname pax is capable of reading and writing archives which span multiple physical volumes. Upon detecting an end of medium on an archive which is not yet completed, pax will prompt the user for the next volume of the archive and will allow the user to specify the location of the next volume. When writing to an archive, the standard input is used as a list of pathnames if no pathname operands are specified. The format is one pathname per fine. Otherwise, the standard input is the archive file, which is formatted according to one of the specifications in Archive/Interchange File format in POSIX.l, or some other implementation-defined format. Sun Release 4.1 Last change: 6 September 1989 401 PAX (IV) USER COMMANDS PAX ( 1 V ) The user ID and group ID of the process, together with the appropriate privileges, affect the ability of pax to restore ownership and permissions attributes of the archived files. See format-reading utility in Archive/Interchange File Format in POSIX.l. OPTIONS — w Write the files and directories specified by pathname to the standard output together with the path- name and status information prescribed by the archive format used, pathname refers to the files and (recursively) subdirectories of that directory. If pathname is not specified, then the standard input is read to get a list of pathnames to copy, one pathname per line. In this case, only those pathnames appearing on the standard input are copied. -r Read an archive file from the standard input. Only files with names that match pattern are selected for extraction. The selected files are conditionally created and copied relative to the current directory tree, subject to the options described below. By default, the owner and group of selected files will be that of the invoking process, and the permissions and modification times will be the sames as those in the archive. The supported archive formats are automatically detected on input. The default output format is ustar, but may be overridden by the -x format option described below. — rw Read the files and directories named in pathname and copy them to the destination directory . A directory pathname refers to the files and (recursively) subdirectories of that directory. If path- name is not specified, the standard input is read to get a list of pathnames to copy, one pathname per line. In this case, only those pathnames appearing on the standard input are copied. The directory named by directory must exist and have the proper permissions before the copy can occur. —a Append the files specified by pathname to the specified archive. -c Complement the match sense of pattern . -d Intermediate directories not explicitly listed in the archive are not created. This option is ignored unless the -r option is specified. -i Interactively rename files. Substitutions specified by the -s option (described below) are per- formed before requesting the new file name from the user. A file is skipped if an empty line is entered and pax exits with an exit status of 0 if an EOF is encountered. -1 Link files rather than copy when possible. -m File modification times are not retained. -n When -r is specified, but -w is not, the pattern arguments are treated as ordinary file names. Only the first occurrence of each of these files in the input archive is read. The pax utility exits with a zero exit status after all files in the list have been read. If one or more files in the list is not found, pax writes a diagnostic to standard error for each of the files and exits with a non-zero exit status. The file names are compared before any of the -i, -s, or -y options are applied. -o Restore file ownership as specified in the archive. The invoking process must have appropriate privileges to accomplish this. -p Preserve the access time of the input files after they have been copied. -u Copy each file only if it is newer than a pre-existing file with the same name. This implies the -a option. —v List file names as they are encountered. Produces a verbose table of contents listing on the stan- dard output when both the -r and -w options are omitted, otherwise the file names are printed to standard error as they are encountered in the archive. 402 Last change: 6 September 1989 Sun Release 4.1 PAX (IV) USER COMMANDS PAX (IV) -y Interactively prompt for the disposition of each file. Substitutions specified by -s options (described above) are performed before prompting the user for disposition, pax exits after receiv- ing an EOF or an input line starting with the character q. Files are ignored if an input line starting with anything other than y is specified. This option cannot be used in conjunction with the -i option. -b blocking Block the output at blocking bytes per write to the archive file. A k suffix multiplies blocking by 1024, a b suffix multiplies blocking by 512 and a m suffix multiplies blocking by 1048576 (1 megabyte). If not specified, blocking is automatically determined on input and is ignored if the -rw option is specified. -f archive Specify the pathname of the input or output archive, overriding the default of the standard input for the -r option or the standard output for the -w option. -s replstr File names are modified according to the substitution expression using the syntax of ed(l) as shown: -s loldlnewl[gp] Any non-null character may be used as a delimiter (a T is used here as an example). Multiple -s expressions may be specified; the expressions are applied in the order specified, terminating with the first successful substitution. The optional trailing g replaces the old expression each time it occurs in the source string. The optional trailing p lists successful mappings on the standard error. Files that substitute to an empty string are ignored both on input and output. -t device The device option argument is an implementation-defined identifier that names the input or output archive device, overriding the default of the standard input for -r and the standard output for -w. -x format Specifies the output archive format. The input format, which must be one of the following, is automatically determined when the -r option is used. The supported formats are: cpio The extended CPIO interchange format specified in Extended CPIO Format in POSIX.l. tar The extended TAR interchange format specified in Extended TAR Format in POSIX.l. This is the default archive format. Only the last of multiple -f or -t options take effect. The options -a, -c, -d, -i, -1, -p, -t, -u, and -y are provided for functional compatibility with the histori- cal cpio and tar utilities. The option defaults were chosen based on the most common usage of these options, therefore, some of the options have meanings different than those of the historical commands. EXAMPLES The following command: pax -w -f /dev/rmtO . copies the contents of the current directory to tape drive 0. The commands: mkdir newdir cd olddir pax -rw . newdir copies the contents of olddir to newdir. Sun Release 4.1 Last change: 6 September 1989 403 PAX ( IV) USER COMMANDS PAX (IV) The command: pax -r -s ’,//*usr//*, >’ -f pax.out reads the archive pax.out with all files rooted in /usr in the archive extracted relative to the current direc- tory. FILES /dev/tty used to prompt the user for information when the -i or -y options are specified SEE ALSO cpio(l), ed(l), find(l), Is(lV), paxcpio(lV), tar(l), ustar(lV), cpio(5), tar(5) IEEE Std. 1003.1-1988 DIAGNOSTICS pax will terminate immediately, without processing any additional files on the command line or in the archive. EXIT CODES pax exits with one of the following values: 0 All files in the archive were processed successfully. >0 pax aborted due to errors encountered during operation. BUGS Special permissions may be required to copy or extract special files. For device, user ID, and group ID numbers larger than 65535 additional header records are output. These records are ignored by some historical version of cpio(l) and tar(l). The archive formats described in Archive/Interchange File Format have certain restrictions that have been carried over from historical usage. For example, there are restrictions on the length of pathnames stored in the archive. When getting an ‘Is -F style listing on tar format archives, link counts are listed as zero since the ustar archive format does not keep link count information. AUTHOR Mark H. Colburn NAPS International 117 Mackubin Street, Suite 1 St. Paul, MN 55102 Sponsored by The USENIX Association for public distribution. 404 Last change: 6 September 1989 Sun Release 4.1 PAXCPIO(IV) USER COMMANDS PAXCPIO(IV) NAME paxcpio - copy file archives in and out SYNOPSIS /usr/5bin/paxcpio-o [ aBcv ] /usr/5bin/paxcpio -i [ Bcdfmrtuv ] [ pattern ... ] /usr/5bin/paxcpio-p [ adlmruv ] directory AVAILABILITY paxcpio is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION paxcpio produces and reads files in the format specified by the cpio Archive/Interchange File Format specified in IEEE Std. 1003.1-1988. When specified with the -i argument, paxcpio extracts files from the standard input, which is assumed to be the product of a previous ‘paxcpio -o’. Only files with names that match pattern are selected, pattern is a simple regular expression given in the name-generating notation of the shell. Multiple patterns may be specified, and if no pattern is specified, the default is **’, selecting all files. The extracted files are condi- tionally created and copied into the current directory, and possibly any levels below, based upon the options specified. The permissions of the files will be those of the previous ‘paxcpio -o’. The owner and group of the files will be that of the current user unless the user has appropriate privileges, in which case paxcpio retains the owner and group of the files of the previous ‘paxcpio -o’. When specified with the -p argument, paxcpio reads the standard input to obtain a list of files that are con- ditionally created and copied into the destination directory based upon the options described below. If an error is detected, the cause is reported and paxcpio continues to copy other files, paxcpio will skip over any unrecognized files that it encounters in the archive. The following restrictions apply to paxcpio: o Pathnames are restricted to 256 characters. • Appropriate privileges are required to copy special files. • Blocks are reported in 5 12-byte quantities. OPTIONS -a Reset access times of input files after they have been copied. When the -1 option is also specified, the linked files do not have their access times reset. Can only be used with the -i or -o argu- ments. -B Input/output is to be blocked 5120 bytes to the record. Can only be used with the -i or -o argu- ments for data that is directed to or from character special files. -c Write header information in ASCII character for for portability. Can only be used with the -i or -o arguments. Note: this option should always be used to write portable files. -d Create directories as needed. Can only be used with the -i or -p arguments. -f Copy in all files except those in patterns. Can only be used with the -i argument. -1 Whenever possible, link files rather than copying them. Can only be used with the -p argument. -m Retain previous modification times. This option is ineffective on directories that are being copied. Can only be used with the -i or -p arguments. -r Interactively rename files. The user is asked whether to rename pattern each invocation. Read and write permissions for /dev/tty are required for this option. If the user types a null line, the file is skipped. Should only be used with the -i or -o arguments. -t Print a table of contents of the input. No files are created. Can only be used with the -i argument. Sun Release 4.1 Last change: 19 September 1989 405 PAXCPIO(IV) USER COMMANDS PAXCPIO(IV) -u Copy files unconditionally; usually an older file will not replace a new file with the same name. Can only be used with the -i or -p arguments. -v Verbose. Print the names of the affected files. Can only be used with the -i argument. Provides a detailed listing when used with the -t option. EXAMPLES The following command: Is | paxcpio -o > . ./newfile copies out the files listed by ls(lV) and redirects them to the file newfile. The following command: cat newfile | paxcpio -id "memo/al" "memo/b*" uses the output file newfile from paxcpio -o, takes those files that match the patterns "memo/al" and "memo/b*", creates the directories below the current directory, and places the files in the appropriate directories. The command: find . -depth -print | paxcpio -pdlmv newdir takes the file names piped to it from find(l) and copies or links those files to another directory named newdir, while retaining the modification time. EXIT CODES paxcpio exits with one of the following values: 0 All input files were copied. 2 paxcpio encountered errors in copying or accessing files or directories. An error will be reported for nonexistent files or directories, or permissions that do not allow the user to access the source or target files. FILES /dev/tty used to prompt the user for information when the -i or -r options are specified SEE ALSO cpio(l), find(l), pax(lV), tar(l), ustar(lV), cpio(5), tar(5) IEEE Std. 1003.1-1988 NOTES It is important to use the -depth option of find(l) to generate pathnames for paxcpio. This eliminates problems paxcpio could have trying to create files under read-only directories. AUTHOR Mark H. Colburn NAPS International 117 Mackubin Street, Suite 1 St. Paul, MN 55102 Sponsored by The USENIX Association for public distribution. 406 Last change: 19 September 1989 Sun Release 4.1 PERFMETER ( 1 ) USER COMMANDS PERFMETER ( 1 ) NAME perfmeter - display system performance values in a meter or strip chart SYNOPSIS perfmeter [ -s sample-time ] [ -h h-hand-int ] [ -m m-hand-int ] [ -M smax minmax maxmax ] [ -v value ] [ hostname ] AVAILABILITY This command is available with the SunView User’s software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION perfmeter is a SunView utility that displays performance values (statistics) for a given hostname. If no host is specified, statistics on the current host are metered. The rstatd(8C) daemon must be running on the machine being metered. When open, perfmeter displays a performance value in the form of a strip chart. When closed, it displays a meter dial. By default, the display is updated with a sample-time of 2 seconds. The hour hand of the meter represents the average over a 20-second interval; the minute hand, the average over 2 seconds. The default value displayed is the percent of CPU being utilized. The maximum scale value for the strip chart will automatically double or halve to accommodate increasing or decreasing values for the host machine. This scale can be restricted to a certain range with the -M option. OPTIONS -s sample-time Set the sample time to sample-time seconds. -h h-hand-int Set the hour-hand interval to h-hand-int seconds, m m-hand-int Set the minute hand interval to m-hand-int seconds. -M smax minmax maxmax Set a range of maximum values for the strip chart. Values for each of the arguments should be powers of 2. smax sets the starting maximum-value, minmax sets the lowest allowed maximum- value for the scale, maxmax sets the highest allowed maximum-value. -v value Set the performance value to be monitored to one of: cpu Percent of CPU being utilized. pkts Ethernet packets per second. page Paging activity in pages per second. swap Jobs swapped per second. intr Number of device interrupts per second. disk Disk traffic in transfers per second. cntxt Number of context switches per second. load Average number of runnable processes over the last minute. colls Collisions per second detected on the ethemet. errs Errors per second on receiving packets. Sun Release 4.1 Last change: 21 January 1988 407 PERFMETER ( 1 ) USER COMMANDS PERFMETER ( 1 ) USAGE Commands You can change the statistic being displayed by clicking the RIGHT mouse button, and then choosing the desired menu item. The other meter parameters can be modified by moving the pointer onto the tool (either open or closed), and typing: m Decrease minutehandintv by one M Increase minutehandintv by one h Decrease hourhandintv by one H Increase hourhandintv by one 1-9 Set sampletime to a range from 1 to 9 seconds. FILES /etc/inetd.conf starts statistics server SEE ALSO sunview(l), netstat(8C), rstatd(8C), vmstat(8) 408 Last change: 21 January 1988 Sun Release 4.1 PG(1V) USER COMMANDS PG(1V) NAME pg - page through a file on a soft-copy terminal SYNOPSIS /usr/5bin/pg [ -cefns ] [ -number ] [ -p string ] [ +linenumber ] [ +/patternl ] [ filename . . . ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION pg is a filter that allows you to page through filename, one screenful at a time, on a soft-copy terminal. With a filename of or no filename specified, pg reads from the standard input. Each screenful is fol- lowed by a prompt. If the user types a RETURN, another page is displayed; other possibilities are enumerated below. This command is different from previous paginators in that it allows you to back up and review something that has already passed. The method for doing this is explained below. In order to determine terminal attributes, pg scans the terminfo(5V) data base for the terminal type specified by the environment variable TERM. If TERM is not defined, the terminal type dumb is assumed. The responses that may be typed when pg pauses can be divided into three categories: those causing further perusal, those that search, and those that modify the perusal environment. Commands which cause further perusal normally take a preceding address, an optionally signed number indicating the point from which further text should be displayed. This address is interpreted in either pages or lines depending on the command. A signed address specifies a point relative to the current page or line, and an unsigned address specifies an address relative to the beginning of the file. Each command has a default address that is used if none is provided. The perusal commands and their defaults are as follows: (+1) NEWLINE or SPACE Display one page. The address is specified in pages. (+1) I With a relative address pg will simulate scrolling the screen, forward or backward, the number of lines specified. With an absolute address this command prints a screenful beginning at the specified line. (+1) d or "D Simulate scrolling half a screen forward or backward. The following perusal commands take no address. . or 'L Redisplay the current page of text. $ Display the last full window in the file. Use with caution when the input is a pipe. The following commands are available for searching for text patterns in the text. The regular expressions described in ed(l) are available. They must always be terminated by a NEWLINE, even if the — n option is specified. ilpatternl Search forward for the zth (default 1=1) occurrence of pattern. Searching begins immediately after the current page and continues to the end of the current file, without wrap-around. r pattern’' ilpatternl Search backwards for the ith (default i=l) occurrence of pattern. Searching begins immediately before the current page and continues to the beginning of the current file, without wrap-around. The " notation is useful for Adds 100 terminals which will not properly handle the ?. Sun Release 4.1 Last change: 16 November 1987 409 PG(1V) USER COMMANDS PG(1V) After searching, pg will normally display the line found at the top of the screen. This can be modified by appending m or b to the search command to leave the line found in the middle or at the bottom of the win- dow from now on. The suffix t can be used to restore the original situation. The user of pg can modify the environment of perusal with the following commands: in Begin perusing the ith next file in the command line. The i is an unsigned number, default value is 1. ip Begin perusing the ith previous file in the command line, i is an unsigned number, default is 1. iw Display another window of text. If i is present, set the window size to i. s filename Save the input in the named file. Only the current file being perused is saved. The white space between the s and filename is optional. This command must always be terminated by a NEWLINE, even if the -n option is specified. h Help by displaying an abbreviated summary of available commands. Q or Q Quit pg. ! command command is passed to the shell, whose name is taken from the SHELL environment vari- able. If this is not available, the default shell is used. This command must always be terminated by a NEWLINE, even if the -n option is specified. At any time when output is being sent to the terminal, the user can hit the quit key, normally CTRLA or the BREAK (interrupt) key. This causes pg to stop sending output, and display the 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. If the standard output is not a terminal, then pg acts just like cat(l V), except that a header is printed before each file (if there is more than one). OPTIONS The command line options are: -number An integer specifying the size (in lines) of the window that pg is to use instead of the default. (On a terminal containing 24 lines, the default window size is 23). -p string Use string as the prompt. If the prompt string contains a ‘%d’, the first occurrence of ‘%d’ in the prompt will be replaced by the current page number when the prompt is issued. The default prompt string is -c Home the cursor and clear the screen before displaying each page. This option is ignored if clear_screen is not defined for this terminal type in the terminfo(5V) data base. -e Do not pause at the end of each file. -f Inhibit pg from splitting lines. Normally, pg splits lines longer than the screen width, but some sequences of characters in the text being displayed (for instance, escape sequences for underlining) generate undesirable results. -n Automatic end of command as soon as a command letter is entered. Normally, com- mands must be terminated by a NEWLINE character. -s Print all messages and prompts in standout mode (usually inverse video). +linenumber Start up at linenumber. 410 Last change: 16 November 1987 Sun Release 4.1 PG(1V) USER COMMANDS PG(1V) +lpatternl Start up at the first line containing the regular expression pattern. EXAMPLES A sample usage of pg in reading system news would be news | pg-p ’(Page %d):’ FILES /usr/share/lib/terminfo/* terminal information data base /tmp/pg* temporary file when input is from a pipe SEE ALSO cat(lV), crypt(l), ed(l), grep(lV), more(l), terminfo(SV) BUGS If terminal TAB characters are not set every eight positions, undesirable results may occur. When using pg as a filter with another command that changes the terminal I/O options (for instance, crypt(l)), terminal settings may not be restored correctly. NOTES While waiting for terminal input, pg responds to BREAK , DEL , and * by terminating execution. Between prompts, however, these signals interrupt pg’s current task and place the user in prompt mode. These should be used with caution when input is being read from a pipe, since an interrupt is likely to terminate the other commands in the pipeline. Users of more(l) will find that the z and f commands are available, and that the terminal 7’, iA \ or *?’ may be omitted from the searching commands. Sun Release 4.1 Last change: 16 November 1987 411 PLOT ( 1G ) USER COMMANDS PLOT(IG) NAME plot, aedplot, bgplot, crtplot, dumbplot, gigiplot, hpplot, implot, t300, t300s, t4013, t450, tek - graphics filters for various plotters SYNOPSIS plot [ -T terminal ] AVAILABILITY This command is available with the Graphics software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION plot reads plotting instructions (see plot(5)) from the standard input and produces plotting instructions suit- able for a particular terminal on the standard output. If no terminal is specified, the environment variable TERM is used. The default terminal is tek. ENVIRONMENT Except for ver, the following terminal-types can be used with ‘lpr -g’ see lpr(l)) to produce plotted out- put: 2648 I 2648a I h8 I hp2648 I hp2648a Hewlett Packard 2648 graphics terminal. 300 DASI 300 or GSI terminal (Diablo mechanism). 300s I 300S DASI 300s terminal (Diablo mechanism). 450 DASI Hyterm 450 terminal (Diablo mechanism). 4013 Tektronix 4013 storage scope. 4014 I tek Tektronix 4014 and 4015 storage scope with Enhanced Graphics Module. (Use 4013 for Tektronix 4014 or 4015 without the Enhanced Graphics Module). aed AED 512 color graphics terminal . bgplot I bitgraph BBN bitgraph graphics terminal. crt Any crt terminal capable of running vi(l). dumb I un I unknown Dumb terminals without cursor addressing or line printers, gigi I vtl25 DEC vtl25 terminal. h7 I hp7 I hp7221 Hewlett Packard 7221 graphics terminal, implot Imagen plotter, var Benson Varian printer-plotter ver Versatec D1200A printer-plotter. The output is scan-converted and suitable input to ‘lpr-v’. FILES /usr/bin/t300 /usr/bin/t300s /usr/bin/t4013 /usr/bin/t450 /usr/bin/aedplot /usr/bin/crtplot /usr/bin/gigiplot /usr/bin/implot 412 Last change: 22 December 1987 Sun Release 4.1 PLOT(IG) USER COMMANDS PLOT ( 1G) /usr/bin/plot /usr/bin/bgplot /usr/bin/dumbplot /usr/bin/hpplot /usr/bin/vplot /usr/bin/tek /usr/bin/t450 /usr/bin/t300 /usr/bin/t300s /usr/bin/vplot / var/tm p/vp lotnnnnnn SEE ALSO graph(lG), lpr(l), vi(l), plot(3X), plot(5), rasterfile(5) Sun Release 4.1 Last change: 22 December 1987 413 PR(1V) USER COMMANDS PR(1V) NAME pr - prepare file(s) for printing, perhaps in multiple columns SYNOPSIS pr [ - 1 + n ] [ -fmt ] [ -h string ] [ -In ] [ -sc ] [ -w n ] [ filename ] . . . SYSTEM V SYNOPSIS /usr/Sbin/pr [ - 1 + n ] [ -adfmprt ] [ -eck ] [ -h string ] [ -ick ] [ -In ] [ -nek ] [ -on ] [ -sc ] [ -wn ] [filename ] . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION pr prepares one or more filenames for printing. By default, the output is separated into pages headed by a date, the name of the file, and the page number, pr prints its standard input if there are no filename argu- ments. FORMFEED characters in the input files cause page breaks in the output, as expected. By default, columns are of equal width, separated by at least one SPACE; lines that do not fit are truncated. If the -s option is used, lines are not truncated and columns are separated by the separation character. Inter-terminal messages using write(l) are forbidden during a pr. OPTIONS Options apply to all following filenames but may be reset between filenames: -f Use FORMFEED characters instead of NEWLINE characters 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 effec- tive page length. -m Print all filenames simultaneously, each in one column, for example: Print Print The the the third lines lines file’s of of lines file file go one. two. here. -t Do not print the 5-line header or the 5-line trailer normally supplied for each page. Pages are not separated 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. -h string Use string, instead of the file name, in the page header. -In Take the length of the page to be n lines instead of the default 66. -sc Separate columns by the single character c instead of by the appropriate amount of white space. A missing c is taken to be a TAB. -wn For multicolumn output, take the width of the page to be n characters instead of the default 72. -n Producen -column output. For example: Print of in the one three lines file columns. Columns are not balanced; if, for example, there are as many lines in the file as there are lines on the page, only one column will be printed. Even if the -t option (see below) is specified, blank lines will be printed at the end of the output to pad it to a full page. +n Begin printing with page n. 414 Last change: 9 September 1987 Sun Release 4.1 PR(1V) USER COMMANDS PR(1V) SYSTEM V OPTIONS When the -n option is specified for multicolumn output, columns are balanced. For example, if there are as many lines in the file as there are lines to be printed, and two columns are to be printed, each column will contain half the lines of the file. If the -t option is specified, no blank lines will be printed to pad the last page. The options -e and -i are assumed for multicolumn output. The -m option overrides the -k and -a options. The -f option does not assume that FORMFEED uses up two blank lines; blank lines will be printed after the FORMFEED if necessary. If the standard output is a terminal, -f will cause pr to wait for a RETURN before printing the first page. -a When combined with the -n option, print multicolumn output across the page. For example: Print the lines of one file in three columns. -d Double-space the output. -p Pause before beginning each page if the output is directed to a terminal (pr will ring the bell at the terminal and wait for a RETURN). — r Do Not print diagnostic reports if a file cannot be opened, or if it is empty. -eck Expand input TAB characters to character positions k+ 1, 2*k+l, 3*k+l, etc. If £ is 0 or is omitted, default TAB settings at every eighth position are assumed. TAB characters in the input are expanded into the appropriate number of SPACE characters. If c (any non- digit character) is given, it is treated as the input TAB character (default for c is the TAB character). -ick In output, replace white space wherever possible by inserting TAB characters to character positions jfc+1, 2*k+l, 3*k+l, etc. If k is 0 or is omitted, default TAB settings at every eighth position are assumed. If c (any non-digit character) is given, it is treated as the output TAB (default for c is the TAB character). -ncjfc Provide k -digit line numbering (default for k is 5). The number occupies the first k + 1 character positions of each column of normal output or each line of -m output. If c (any non-digit character) is given, it is appended to the line number to separate it from what- ever follows (default for c is a TAB). -ok Offset each line by k character positions. The number of character positions per line is the sum of the width and offset. EXAMPLES Print a file called dreadnought on the printer — this is the simplest use of pr: example% pr dreadnought | Ipr example% 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: example% pr -m -t ridings ridings ridings > Yorkshire example % FILES /dev/tty* to suspend messages. SEE ALSO cat(lV), Ipr(l), write(l) Sun Release 4.1 Last change: 9 September 1987 415 PR(1V) USER COMMANDS PR(1V) DIAGNOSTICS can’t print 0 cols, using 1 -0 was specified as a -n option. pr: bad key key An illegal option was given. pr: No room for columns. The number of columns requested will not fit on the page, pr: Too many args More than 10 files were specified with the — m option. filename : error filename could not be opened. This diagnostic is not printed if pr is printing on a terminal. SYSTEM V DIAGNOSTICS pr: bad option An illegal option was given. pr: width too small The number of columns requested will not fit on the page, pr: too many files More than 10 files were specified with the -m option, pr: page-buffer overflow The formatting required is more complicated than pr can handle, pr: out of space pr could not allocate a buffer it required, pr: filename -- empty file filename was empty. This diagnostic is printed after all the files are printed if pr is printing on a terminal. pr: can’t open filename filename could not be opened. This diagnostic is printed after all the files are printed if pr is print- ing on a terminal. BUGS The options described above interact with each other in strange and as yet to be defined ways. 416 Last change: 9 September 1987 Sun Release 4.1 PRINTENV ( 1 ) USER COMMANDS PRINTENV (1) NAME printenv - display environment variables currently set SYNOPSIS printenv [ variable ] DESCRIPTION printenv prints out the values of the variables in the environment. If a variable is specified, only its value is printed. SEE ALSO csh(l), sh(l), stty(lV), tset(l), environ(5V) DIAGNOSTICS If a variable is specified and it is not defined in the environment, printenv returns an exit status of 1. Sun Release 4.1 Last change: 9 September 1987 417 PROF ( 1 ) USER COMMANDS PROF ( 1 ) NAME prof - display profile data SYNOPSIS prof [ -alnsz ] [ -v -low [ -high ] ] [ image-file [ profile-file . . . ] ] DESCRIPTION prof produces an execution profile of a program. The profile data is taken from the profile file which is created by programs compiled with the -p option of cc(lV) and other compilers. That option also links in versions of the library routines (see monitor(3)) which are compiled for profiling. The symbol table in the executable image file image-file (a.out by default) is read and correlated with the profile file profile-file (mon.out by default). For each external symbol, the percentage of time spent executing between that sym- bol 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 prof output shows the sum of the profile information in the given profile files. To tally the number of calls to a routine, the modules that make up the program must be compiled with the ’cc -p’ option (see cc(l V)). This option also means that the profile file is produced automatically. A single function may be split into subfunctions for profiling by means of the MARK macro (see prof(3)). Beware of quantization errors. The profiled program must call exit(2V) or return normally for the profiling information to be saved in the mon.out file. OPTIONS -a Report all symbols rather than just external symbols. -1 Sort the output by symbol value. -n Sort the output by number of calls. -s Produce a summary profile file in mon.sum. This is really only useful when more than one profile file is specified. -z Display routines which have zero usage (as indicated by call counts and accumulated time). -v [ -low [ -high ]] Suppress all printing and produce a graphic version of the profile on the standard output for display by the plot(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 resolution. ENVIRONMENT PROFDIR If this environment variable contains a value, place profiling output within that directory, in a file named pid.programname. pid is the process ID, and programname is the name of the program being profiled, as determined by removing any path prefix from the argv[0] with which the pro- gram was called. If the variable contains a NULL value, no profiling output is produced. Other- wise, profiling output is placed in the file mon.out. FILES a.out executable file containing namelist $PROFDTRl pid.programname mon.out profiling output mon.sum summary profile SEE ALSO cc(lV), gprof(l), plot(lG), tcov(l), exit(2V), profil(2), monitor(3) 418 Last change: 22 December 1987 Sun Release 4.1 PROF ( 1 ) USER COMMANDS PROF ( 1 ) BUGS prof is confused by the FORTRAN compiler which puts the entry points at the bottom of subroutines and functions. Sun Release 4.1 Last change: 22 December 1987 419 PS(1) USER COMMANDS PS(1) NAME ps - display the status of current processes SYNOPSIS ps [ HacCegjklnrSuUvwx ] [ -fcc ] I [ num ] [ kernel-name ] [ c-dump-file ] [ swap-file ] DESCRIPTION ps displays information about processes. Normally, only those processes that are running with your effec- tive user ID and are attached to a controlling terminal (see termio(4)) are shown. Additional categories of processes can be added to the display using various options. In particular, the -a option allows you to include processes that are not owned by you (that do not have your user ID), and the -x option allows you to include processes without control terminals. When you specify both -a and -x, you get processes owned by anyone, with or without a control terminal. The -r option restricts the list of processes printed to “running” processes: runnable processes, those in page wait, or those in short-term non-interruptible waits. ps displays the process ID, under PID; the control terminal (if any), under TT; the cpu time used by the pro- cess so far, including both user and system time), under TIME; the state of the process, under ST AT; and finally, an indication of the COMMAND that 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 non-interruptible waits; typically short-term waits for disk or NFS I/O. S Processes sleeping for less than about 20 seconds. I Processes that are idle (sleeping longer than about 20 seconds). Z Processes that have terminated and that are waiting for their parent process to io a wait(2V) (“zombie” processes). Second letter indicates whether a process is swapped out; blank Represented as a SPACE character, in this position indicates that the process is loaded (in memory). W Process is swapped out. > Process has specified a soft limit on memory requirements and has exceeded that limit; such a process is (necessarily) not swapped. Third letter indicates whether a process is running with altered CPU scheduling priority (nice(l)): blank Represented as a SPACE character, 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 Represented as a SPACE character, 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 that 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-file tells ps where to look for the core dump. Otherwise, the core dump is located in the file /vmcore and this argu- ment is ignored, swap-file gives the location of a swap file other than the default, /dev/drum. 420 Last change: 2 October 1989 Sun Release 4.1 PS(1) USER COMMANDS PS(1) OPTIONS Options must all be combined to form the first argument. -a Include information about processes owned by others. -c Display the command name, as stored internally in the system for accounting purposes, rather than the command arguments, which are kept in the process address space. This is more reliable, if less informative, as the process is free to destroy the latter information. -C Display raw CPU time instead of the decaying average in the %CPU field. -e Display the environment as well as the arguments to the command. -g Display all processes. Without this option, ps prints only “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. -j Display a listing useful for job control information, with fields PPID, PID, PGID, SID, TT, TPGID, STAT, UID, TIME, and COMMAND as described below. With this option, the STAT field has three additional letters: C indicates the process does not want SIGCHLD when a child changes state done to job con- trol. E The process has completed an exec, and the parent can no longer change the process group of this process. O The process is an orphan, with no parent process to handle job control signals. -k Normally, kernel-name defaults to /vmunix, c-dump-file is ignored, and swap-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 F, PPID, CP, PRI, NI, SZ, RSS, and WCHAN, as described below. -n Produce numeric output for some fields. In a long listing, the WCHAN field is printed numerically rather than symbolically, or, in a user listing, the USER field is replaced by a UID field. -r Restrict output to “running” processes. -S Display accumulated CPU time used by this process and all of its reaped children. -u Display user-oriented output. This includes fields USER, %CPU, %MEM, SZ, RSS and START as described below. -U Update a private database where ps keeps system information. Include ‘ps -IT in the /etc/rc file. -v Display a version of the output describing virtual memory information. This includes fields RE, SL, PAGEIN, SIZE, RSS, LIM, %CPU and %MEM, described below. -w Use a wide output format (132 columns rather than 80); if repeated, that is, -ww, use arbitrarily wide output. This information is used to decide how much of long commands to print. -x Include processes with no controlling terminal. The following two options are mutually exclusive. When specified, these options must appear immediately following the last option. — fit Restrict output to processes whose controlling terminal is x (which should be specified as printed by ps; for example, t3 for /dev/tty3, tco for /dev/console, tdO for /dev/ttydO, t? for processes with no terminal, etc). This option must be the last one given. num A process number may be given, in which case the output is restricted to that process. This option must also be last, and must appear with no white space between it and the previous option. Sun Release 4.1 Last change: 2 October 1989 421 PS(1) USER COMMANDS PS(1) DISPLAY FORMATS Fields that are not common to all output formats: USER Name of the owner of the process. %CPU CPU use of the process; this is a decaying average over up to a minute of previous (real) time. Because 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%. NI Process scheduling increment (see getpriority(2) and nice(3V)). SIZE SZ The combined size of the data and stack segments (in kilobytes) RSS Real memory (resident set) size of the process (in kilobytes). LIM Soft limit on memory used, specified using a call to getrlimit(2); if no limit has been specified, this is shown as xx. %MEM Percentage of real memory used by this process. RE Residency time of the process (seconds in core). SL Sleep time of the process (seconds blocked). PAGEIN Number of disk I/Os resulting from references by the process to pages not loaded in core. UID Numeric user-ID of process owner. PPID Numeric ID of parent of process. SID Numeric ID of the session to which the process belongs. SID = PGID = PID indicates a ses- sion leader. PGID Numeric ID of the process group of the process. TPGID Numeric ID of the process group associated with the terminal specified under TT (dis- tinguished process group, see termio(4)). CP Short-term CPU utilization factor (used in scheduling). PRI Process priority (non-positive when in non-interruptible wait). START Time the process was created if today, or the date it was created if before today. WCHAN Event on which process is waiting (an address in the system). A symbol is chosen that classifies the address, unless numeric output is requested (see the n flag). In this case, the address is printed in hexadecimal. F Flags (in hex) associated with process as in : SLOAD 00000001 in core SSYS 00000002 swapper or pager process SLOCK 00000004 process being swapped out SSWAP 00000008 save area flag STRC 00000010 process is being traced SWTED 00000020 parent has been told that this process stopped SULOCK 00000040 user can set lock in core SPAGE 00000080 process in page wait state SKEEP 00000100 another flag to prevent swap out SOMASK 00000200 restore old mask after taking signal SWEXIT 00000400 working on exiting SPHYSIO 00000800 doing physical I/O SVFORK 00001000 process resulted from vfork() SVFDONE 00002000 another vfork flag SNOVM 00004000 no vm, parent in a vfork() SPAGI 00008000 init data space on demand, from vnode 422 Last change: 2 October 1989 Sun Release 4.1 PS(1) USER COMMANDS PS(1) SSEQL 00010000 user warned of sequential vm behavior SUANOM 00020000 user warned of anomalous vm behavior STIMO 00040000 timing out during sleep SORPHAN 00080000 process is orphaned STRACNG 00100000 process is tracing another process SOWEUPC 00200000 process is being profiled and has a pending count increment SSEL 00400000 selecting; wakeup/waiting danger SFAVORD 02000000 favored treatment in swapout and pageout SLKDONE 04000000 record-locking has been done STRCSYS 08000000 tracing system calls SNOCLDSTOP 10000000 SIGCHLD not sent when child stops SEXECED 20000000 process has completed an exec SRPC 40000000 sunview window locking A process that has exited and has a parent, but has not yet been waited for by the parent, is marked ; a process that is blocked trying to exit is marked ; otherwise, ps makes an educated guess as to the file name and arguments given when the process was created by examining memory or the swap area. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout ps. On entry to ps, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /vmunix /dev/kmem /dev/drum /vmcore /dev /etc/psdatabase system namelist kernel memory swap device core file searched to find swap device and terminal names system namelist, device, and wait channel information SEE ALSO kill(l), w(l), getpriority(2), getrlimit(2), wait(2V), vadvise(2), nice(3V), termio(4), locale(5), pstat(8) BUGS Things can change while ps is running; the picture it gives is only a close approximation to the current state. Sun Release 4.1 Last change: 2 October 1989 423 PTX(l) USER COMMANDS PTX(l) NAME ptx - generate a permuted index SYNOPSIS ptx [ -f ] [ -t ] [ -w n ] [ -g n ] [ -o only ] [ -i ignore ] [ -b break] [ -r ] [ input [ output ] ] AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ptx generates a permuted index of the contents of file input onto file output (defaults are standard input and output), ptx has three phases: the first does the permutation, generating one line for each keyword in an input line. The keyword is rotated to the front. The permuted file is then sorted. Finally, the sorted lines are rotated so the keyword comes at the middle of the page, ptx produces output in the form: jcx "tail” " before keyword" " keyword and after" " head " where xx may be an nroff(l) or troff(l) macro for user-defined formatting. The before keyword and key- word and after fields incorporate as much of the line as will fit around the keyword when it is printed at the middle of the page, tail and head, at least one of which is an empty string are wrapped-around pieces small enough to fit in the unused space at the opposite end of the line. When original text must be dis- carded, 7’ marks the spot. OPTIONS -f Fold upper and lower case letters for sorting. -t Prepare the output for the phototypesetter; the default line length is 100 characters. -w 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. -i ignore 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 /usr/lib/eign SEE ALSO nroff(l), sort(lV), troff(l) BUGS Line length counts do not account for overstriking or proportional spacing. 424 Last change: 21 December 1987 Sun Release 4.1 PWD(l) USER COMMANDS PWD(l) NAME pwd - display the pathname of the current working directory SYNOPSIS pwd DESCRIPTION pwd prints the pathname of the working (current) directory. If you are using csh(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(l) command. The example below illus- trates the differences. example % cd /usr/wendy/january/reports example% pwd /usr/wendy/january/reports exam pie % dirs "/january/reports exam pie % mv /january /february example % pwd /usr/wendy/february/reports example % dirs “/january/reports example % pwd and dirs also give different answers when you change directory through a symbolic link. For exam- ple: example % cd /usr/wendy/january/reports exam pie % pwd /usr/wendy/january/reports example % dirs "/january/reports example% Is -1 /usr/wendy/january Irwxrwxrwx 1 wendy 17 Jan 30 1983 /usr/wendy/january -> /usr/wendy/1984/jan/ example % cd /usr/wendy/january example % pwd /usr/wendy/1984/jan example % dirs /usr/wendy/january The pathnames of files mounted with the Automounter can also change if the file is not used for a certain time interval (the default is five minutes). To prevent this, set the environment variable AUTOMOUNT_FIXNAMES. See automount(8) for more information. SEE ALSO cd(l), csh(l), automount(8) Sun Release 4.1 Last change: 9 September 1987 425 QUOTA ( 1 ) USER COMMANDS QUOTA ( 1 ) NAME quota - display a user’s disk quota and usage SYNOPSIS quota [ -v ] [ username ] DESCRIPTION quota displays users’ disk usage and limits. Only the super-user may use the optional username argument to view the limits of users other than himself. quota without options displays only warnings about mounted file systems where usage is over quota. Remotely mounted file systems which are mounted with the “noquota” option (see fstab(5)) are ignored. OPTIONS -v Display user’s quotas on all mounted file systems where quotas exist. FILES quotas quota file at the file system root /etc/mtab list of currently mounted filesystems SEE ALSO quotactl(2), fstab(5), edquota(8), quotaon(8), rquotad(8C) 426 Last change: 9 September 1987 Sun Release 4.1 RANLIB ( 1 ) USER COMMANDS RANLIB (1) NAME ranlib - convert archives to random libraries SYNOPSIS ranlib [ -t ] archive. . . DESCRIPTION ranlib converts each archive to a form that can be linked more rapidly, ranlib does this by adding a table of contents called .SYMDEF to the beginning of the archive, ranlib uses ar(lV) to reconstruct the archive. Sufficient temporary file space must be available in the file system that contains the current direc- tory. OPTIONS -t ranlib only “touches” the archives and does not modify them. This is useful after copying an archive or using the -t option of make(l) to avoid having ld(l) complain about an “out of date” symbol table. SEE ALSO ar(lV), ld(l), lorder(l), make(l) BUGS Because generation of a library by ar and randomization of the library by ranlib are separate processes, phase errors are possible. The linker. 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. Sun Release 4.1 Last change: 9 September 1987 427 R ASFILTER8TO 1 ( 1 ) USER COMMANDS R ASFILTER8TO 1 ( 1 ) NAME rasfilter8tol - convert an 8-bit deep rasterfile to a 1-bit deep rasterfile SYNOPSIS rasfilter8tol [ -d ] [ -rgba threshold ] [ infile [ outfile ]] DESCRIPTION rasfilter8tol reads the 8-bit deep rasterfile infile (the standard input default) and converts it to the 1-bit deep rasterfile outfile (standard output default) by thresholding or ordered dither. The output format is Sun standard rasterfile format (see ). This command is useful for viewing 8-bit rasterfiles on dev- ices that can only display monochrome images. OPTIONS -d Use ordered dither to convert the input file instead of thresholding. -rgba threshold Set the threshold for the red, green, blue, and average pixel color values. Pixels whose color values are greater than or equal to all of the thresholds are given a value of 0 (white) in the output rasterfile; other pixels are set to 1 (black). The average threshold defaults to 128, the individual thresholds to zero. EXAMPLE The command example% screendump -f /dev/cgtwo | rasfilter8tol | Ipr -Pversatec -v prints a monochromatic representation of the /dev/cgtwo frame buffer on the printer named versatec using the v output filter (see /etc/printcap). The printer must support an appropriate imaging model such as PostScript in order to print the image. FILES /usr/lib/rasfilters/* filters for non-standard rasterfile formats SEE ALSO lpr(l), rastrepl(l), screendump(l), screenload(l) Pixrect Reference Manual 428 Last change: 8 September 1988 Sun Release 4.1 RASTREPL ( 1 ) USER COMMANDS RASTREPL ( 1 ) NAME rastrepl - magnify a raster image by a factor of two SYNOPSIS rastrepl [ input-file [ output-file ]] DESCRIPTION rastrepl reads the rasterfile input-file (the standard input default) and converts it to the rasterfile output-file (the standard output default) which is twice as large in width and height. Pixel replication is used to mag- nify the image. The output file has the same type as the input file. EXAMPLES The following command: example % screendump | rastrepl | lpr — Pversatec — v sends a rasterfile containing the current frame buffer contents to the Versatec plotter, doubling the size of the image so that it fills a single page. FILES /usr/lib/rasfilters/* filters for non-standard rasterfile formats SEE ALSO lpr(l), screendump(l), screenload(l) Pixrect Reference Manual Sun Release 4.1 Last change: 24 September 1987 429 RCP(IC) USER COMMANDS RCP(IC) NAME rep - remote file copy SYNOPSIS rep [ -p ] filenamel filename2 rep [ -pr ] filename. . .directory AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION rep copies files between machines. Each filename or directory argument is either a remote file name of the form: hostname '.path or a local file name (containing no V characters, or a T before any Vs). If & filename is not a full path name, it is interpreted relative to your home directory on hostname. 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 hostname and allow remote command execution by rsh(lC). rep handles third party copies, where neither source nor target files are on the current machine. Hostnames may also take the form username @ hostname filename to use username rather than your current local user name as the user name on the remote host, rep also supports Internet domain addressing of the remote host, so that: username @host .domain filename specifies the username to be used, the hostname, and the domain in which that host resides. Filenames that are not full path names will be interpreted relative to the home directory of the user named username, on the remote host. The destination hostname may also take the form hostname .username filename to support destination machines that are running older versions of rep. OPTIONS -p Attempt to give each copy the same modification times, access times, and modes as the original file. -r Copy each subtree rooted at filename ; in this case the destination must be a directory. FILES •eshre .login .profile SEE ALSO ftp(lC), rlogin(lC), rsh(lC) BUGS rep does not detect all cases where the target of a copy might be a file in cases where only a directory should be legal. rep can become confused by output generated by commands in a .profile, .eshre, or .login file on the remote host. 430 Last change: 17 May 1989 Sun Release 4.1 RCP(IC) USER COMMANDS RCP(IC) rep requires that the source host have permission to execute commands on the remote host when doing third-party copies. If you forget to quote metacharacters intended for the remote host you get an incomprehensible error mes- sage. Sun Release 4.1 Last change; 17 May 1989 431 RDIST ( 1 ) USER COMMANDS RDIST ( 1 ) NAME rdist - remote file distribution program SYNOPSIS rdist [ -b ] [ -h ] [ -i ] [ -n ] [ -q ] [ -R ] [ -v ] [ -w ] [ -y ] [ -d macro = value ] [ -f distfile ] [ -m host ] . . . [ package ... ] rdist [ -b ] [ -h ] [ -i ] [ -n ] [ -q ] [ -R ] [ -v ] [ -w ] [ -y ] -c pathname ... [login @]hostname[:destpath] AVAILABILITY This command is available with the Networking software installation option. See Installing SunOS 4.1 for information about installing optional software. DESCRIPTION rdist maintains copies of files on multiple hosts. It preserves the owner, group, mode, and modification time of the master copies, and can update programs that are executing. Normally, a copy on a remote host is updated if its size or modification time differs from the original on the local host, rdist reads the indi- cated distfile for instructions on updating files and/or directories. If distfile is the standard input is used. If no -f option is present, rdist first looks in its working directory for distfile, and then for Distfile, for instructions. rdist updates each package specified on the command line; if none are given, all packages are updated according to their entries in the distfile. OPTIONS — b Binary comparison. Perform a binary comparison and update files if they differ, rather than merely comparing dates and sizes. -h Follow symbolic links. Copy the file that the link points to rather than the link itself. -i Ignore unresolved links, rdist will normally try to maintain the link structure of files being transffered and warn the user if all the links cannot be found. -n Print the commands without executing them. This option is useful for debugging a distfile. -q Quiet mode. Do not display the files being updated on the standard output. -R Remove extraneous files. If a directory is being updated, remove files on the remote host that do not correspond to those in the master (local) directory. This is useful for maintaining truly identi- cal copies of directories. -v Verify that the files are up to date on all the hosts. Any files that are out of date are displayed, but no files are updated, nor is any mail sent. -w Whole mode. The whole file name is appended to the destination directory name. Normally, only the last component of a name is used when renaming files. This preserves the directory structure of the files being copied, instead of flattening the directory structure. For instance, renaming a list of files such as ( dirl/fl dir2/f2 ) to dir3 would create files dir3/dirl/fl and dir3/dir2/f2 instead of dir3/fl and dir3/f2. When the -w option is used with a filename that begins with ", everything except the home directory is appended to the destination name. -y Younger mode. Do not update remote copies that are younger than the master copy, but issue a warning message instead. -d macro =value Define macro to have value. This option is used to define or override macro definitions in the distfile. value can be the empty string, one name, or a list of names surrounded by parentheses and separated by white space. 432 Last change: 18 December 1989 Sun Release 4.1 RDIST(l) USER COMMANDS RDIST(l) — c pathname . . . [login @~\hostname[:destpath ] Update each pathname on the named host. (Relative filenames are taken as relative to your home directory.) If the ‘ login @’ prefix is given, the update is performed with the user ID of login. If the ‘ idestpath ’ is given, the remote file is installed as that pathname. -f distjile Use the description file distjile. A ’ as the distfile argument denotes the standard input. -m host Limit which machines are to be updated. Multiple -m arguments can be given to limit updates to a subset of the hosts listed in the distfile. USAGE Packages A typical package begins with a label composed of the package name followed by a colon: package : This label allows you to group any number of file-to-host and file-to-timestamp mappings into a single dis- tribution package. If no package label appears in the distfile, the default package includes all mappings in the file. A file-to-host mapping specifies a list of files or directories to distribute, their destination host(s), and any rdist primitives to use in performing the update. A mapping of this sort takes the form: ( pathname ...)->( hostname . . . ) primitive ; [primitive ;] . . . In this case, each pathname is the full pathname of a local file or directory to distribute; each hostname is the name of a remote host on which those files are to be copied, and primitive is one of the rdist primitive listed under Primitives , below. If there is only one pathname or hostname, the surrounding parentheses can be omitted. A hostname can also take the form: login@hostname in which case the update is performed as the user named login. A file-to-timestamp mapping is used to monitor which local files are updated with respect to a local “times- tamp” file. This mapping takes the form: {filename ... ) :: timestamp-file primitive ; [primitive ;] . . . In this case, timestamp-file is the name of a file, the modification time of which is compared with each named file on the local host. If a file is newer than time-stamp-file , rdist displays a message to that effect. If there is only one filename , the parentheses can be omitted. White Space Characters NEWLINE, TAB, and SPACE characters are all treated as white space; a mapping continues across input lines until the start of the next mapping: either a single filename followed by a *->’ or the opening parenthesis of a filename list. Comments Comments begin with # and end with a NEWLINE. Macros rdist has a limited macro facility. Macros are only expanded in filename or hostname lists, and in the argu- ment lists of certain primitives. Macros cannot be used to stand for primitives or their options, or the or symbols. A macro definition is a line of the form: macro = value Sun Release 4.1 Last change: 18 December 1989 433 RDIST(l) USER COMMANDS RDIST(l) A macro reference is a string of the form: ${macro } although (as with make(l)) the braces can be omitted if the macro name consists of just one character. Metacharacters The shell meta-characters: [, ], {, }, * and ? are recognized and expanded (on the local host only) just as they are with csh(l). Metacharacters can be escaped by prepending a backslash. The " character is also expanded in the same way as with csh, however, it is expanded separately on the local and destination hosts. Filenames File names that do not begin with / or “ are taken to be relative to user’s home directory on each destination host. Note that they are not relative to the current working directory. Primitives The following primitives can be used to specify actions rdist is to take when updating remote copies of each file. install [ -b ] [ -h ] [ -i ] [ -R ] [ -v ] [ -w ] [ — y ] [newname] Copy out-of-date files and directories (recursively). If no install primitive appears in the package entry, or if no newname option is given, the name of the local file is given to the remote host’s copy. If absent from the remote host, parent directories in a filename’s path are created. To help prevent disasters, a non-empty directory on a target host is not replaced with a regular file or a symbolic link by rdist. However, when using the -R option, a non-empty directory is removed if the corresponding filename is completely absent on the master host. The options for install have the same semantics as their command line counterparts, but are limited in scope to a particular map. The login name used on the destination host is the same as the local host unless the destina- tion name is of the format login@host. In that case, the update is performed under the username login. notify address . . . Send mail to the indicated TCP/IP address of the form: user@host that lists the files updated and any errors that may have occurred. If an address does not contain a ‘@host ’ suffix, rdist uses the name of the destination host to complete the address. except filename . . . Omit from updates the files named as arguments. except_patpa«ern . . . Omit from updates the filenames that match each regular-expression pattern (see ed(l) for more information on regular expressions. Note that \ and $ characters must be escaped in the distfile. Shell variables can also be used within a pattern, however shell filename expansion is not sup- ported. special [filename ] . . . ” command-line " Specify a Bourne shell, sh(l) command line to execute on the remote host after each named file is updated. If no filename argument is present, the command-line is performed for every updated file, with the shell variable FILE set to the file’s name on the local host. The quotation marks allow command-line to span input lines in the distfile; multiple shell commands must be separated by semicolons (;). The default working directory for the shell executing each command-line is the user’s home direc- tory on the remote host. 434 Last change: 18 December 1989 Sun Release 4.1 RDIST(l) USER COMMANDS RDIST(l) EXAMPLES The following sample distfile instructs rdist to maintain identical copies of a shared library, a shared- library initialized data file, several include files, and a directory, on hosts named hermes and magus. On magus, commands are executed as root, rdist notifies merlin@druid whenever it discovers that a local file has changed relative to a timestamp file. HOSTS = ( hermes root@magus ) FILES = ( /usr/local/lib/libcant.so.1.1 /usrlocal/lib/libcant.sa.1.1 /usr/local/include/{*.h} /usr/local/bin ) ${FILES} -> ${HOSTS} install -R ; ${FILES} :: /usr /local/lib/timestamp notify merlin@druid ; FILES /tmp/rdist* temporary file for update lists SEE ALSO csh(l), ed(l), sh(l), stat(2V) DIAGNOSTICS A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shell, for example, you are in too many groups. BUGS Source files must reside or be mounted on the local host. There is no easy way to have a special command executed only once after all files in a directory have been updated. Variable expansion only works for name lists; there should be a general macro facility, rdist aborts on files that have a negative modification time (before Jan 1, 1970). There should be a “force” option to allow replacement of non-empty directories by regular files or sym- links. A means of updating file modes and owners of otherwise identical files is also needed. WARNINGS root does not have its accustomed access privileges on NFS mounted file systems. Using rdist to copy to such a file system may fail, or the copies may be owned by user “nobody.” Sun Release 4.1 Last change: 18 December 1989 435 REFER ( 1 ) USER COMMANDS REFER ( 1 ) NAME refer - expand and insert references from a bibliographic database SYNOPSIS refer [ -ben ] [ -ar ] [ -c string ] [ -let ] [ -1 m,n ] [ -p filename ] [ -s keys ] filename . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION refer is a preprocessor for nroff(l), or troff(l), that finds and formats references. The input files (standard input by default) are copied to the standard output, except for lines between and command lines. Such lines are assumed to contain keywords as for Iookbib(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(l), neqn, or tbl(l), refer should be used first in the sequence, to minimize the volume of data passed through pipes. OPTIONS -b Bare mode — do not put any flags in text (neither numbers or labels). -e Accumulate references instead of leaving the references where encountered, until a sequence of the form: •1 $LIST$ .] is encountered, and then write out all references collected so far. Collapse references to the same source. -n Do not search the default file. -ar Reverse the first r author names (Jones, J. A. instead of J. A. Jones). If r is omitted, all author names are reversed. -c string Capitalize (with SMALL CAPS) the fields whose key-letters are in string. -kx Instead of numbering references, use labels as specified in a reference data line beginning with the characters %x; By default, x is L. -1 m,n Instead of numbering references, use labels from the senior author’s last name and the year of publication. Only the first m letters of the last name and the last n digits of the date are used. If either of m or n is omitted, the entire name or date, respectively, is used. -p filename Take the next argument as a file of references to be searched. The default file is searched last. -s keys Sort references by fields whose key-letters are in the keys string, and permute reference numbers in the text accordingly. Using this option implies the -e option. The key-letters in keys may be followed by a number indicating how many such fields are used, with a + sign taken as a very large number. The default is AD, which sorts on the senior author and date. To sort on all authors and then the date, for instance, use the options ‘-sA+T’. 436 Last change: 21 December 1987 Sun Release 4.1 REFER ( 1 ) USER COMMANDS REFER ( 1 ) FILES /usr/dict/papers directory of default publication lists and indexes /usr/lib/refer directory of programs SEE ALSO addbib(l), eqn(l), indxbib(l), lookbib(l), nroff(l), roffbib(l), sortbib(l), tbl(l), troff(l) Sun Release 4.1 Last change: 21 December 1987 437 REV ( 1 ) USER COMMANDS REV ( 1 ) NAME rev - reverse the order of characters in each line SYNOPSIS rev [filename ] . . . 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. 438 Last change: 9 September 1987 Sun Release 4.1 RLOGIN(IC) USER COMMANDS RLOGIN(IC) NAME rlogin - remote login SYNOPSIS rlogin [ -L ] [ -8 ] [ -ec ] [ -1 username ] hostname AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION rlogin establishes a remote login session from your terminal to the remote machine named hostname. Hostnames are listed in the hosts database, which may be contained in the /etc/hosts file, the Network Information Service (NIS) hosts database, the Internet domain name server, or a combination of these. Each host has one official name (the first name in the database entry), and optionally one or more nick- names. Either official hostnames or nicknames may be specified in hostname. Each remote machine may have a file named /etc/hosts.equiv containing a list of trusted hostnames with which it shares usernames. Users with the same username on both the local and remote machine may rlogin from the machines listed in the remote machine’s /etc/hosts.equiv file without supplying a pass- word. Individual users may set up a similar private equivalence list with the file .rhosts in their home directories. Each line in this file contains two names: a hostname and a username separated by a SPACE. An entry in a remote user’s .rhosts file permits the user named username who is logged into hostname to rlogin to the remote machine as the remote user without supplying a password. If the name of the local host is not found in the /etc/hosts.equiv file on the remote machine, and the local username and hostname are not found in the remote user’s .rhosts file, then the remote machine will prompt for a password. Host- names listed in /etc/hosts.equiv and .rhosts files must be the official hostnames listed in the hosts database; nicknames may not be used in either of these files. To counter security problems, the .rhosts file must be owned by either the remote user or by root. The remote terminal type is the same as your local terminal type (as given in your environment TERM variable). The terminal or window size is also copied to the remote system if the server supports the op- tion, and changes in size are reflected as well. All echoing takes place at the remote site, so that (except for delays) the remote login is transparent. How control using “S (CTRL-S) and A Q (CTRL-Q) and flushing of input and output on interrupts are handled properly. ESCAPES Lines that you type which start with the tilde character are “escape sequences” (the escape character can be changed using the -e options): Disconnect from the remote host — this is not the same as a logout, because the local host breaks the connection with no warning to the remote end. "susp Suspend the login session (only if you are using the C shell), susp is your “suspend” character, usually A Z, (CTRL-Z), see tty(l). "dsusp Suspend the input half of the login, but output will still be seen (only if you are using the C shell), dsusp is your “deferred suspend” character, usually "Y, (CTRL-Y), see tty(l). OPTIONS -L Allow the rlogin session to be run in “litout” mode. -8 Pass eight-bit data across the net instead of seven-bit data. -ec Specify a different escape character, c, for the line used to disconnect from the remote host. -1 username Specify a different username for the remote login. If you do not use this option, the remote user- name used is the same as your local username. Sun Release 4.1 Last change: 17 December 1987 439 RLOGIN(IC) USER COMMANDS RLOGIN(IC) FILES /usr/hosts/* for the hostname version of the command /etc/hosts.equiv list of trusted hostnames with shared usernames /.rhosts private list of trusted hostname/usemame combinations SEE ALSO rsh(lC), stty(lV), tty(l), ypcat(l), hosts(5), named(8C) BUGS This implementation can only use the TCP network service. More of the environment should be propagated. NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. 440 Last change: 17 December 1987 Sun Release 4.1 RM( 1) USER COMMANDS RM( 1 ) NAME rm, rmdir - remove (unlink) files or directories SYNOPSIS rm [ - ] [ -fir ] filename. . . rmdir directory. . . DESCRIPTION rm removes (directory entries for) one or more files. If an entry was the last link to the file, the contents of that file are lost. See ln(lV) for more information about multiple links to files. To remove a file, you must have write permission in its directory; but you do not need read or write permis- sion on the file itself. If you do not 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. rmdir removes each named directory, rmdir only removes empty directories. OPTIONS - Treat the following arguments as filenames so that you can specify filenames starting with a minus. -f Force files to be removed without displaying permissions, asking questions or reporting errors. -i Ask whether to delete each file, and, under -r, whether to examine each directory. Sometimes called the interactive option. -r Recursively delete the contents of a directory, its subdirectories, and the directory itself. SEE ALSO ln(lV), su(lV) BUGS ‘rm — r’ removes a directory and its files only if your real user ID has write permission on that directory. DIAGNOSTICS rm: filename : No such file or directory filename does not exist, rm will also return false (1) if filename was not found. WARNING It is forbidden to remove the file to avoid the antisocial consequences of inadvertently doing something like ‘rm -r Sun Release 4. 1 Last change: 12 January 1988 441 ROFFBIB ( 1 ) USER COMMANDS ROFFBIB ( 1 ) NAME roffbib - format and print a bibliographic database SYNOPSIS roffbib t -e ] [ -h ] [ -m filename ] [ -n p ] [ -o list ] [ -Q ] [ -r aN ] [ -s N ] [ -T term ] [ -V ] [ -x ] [ filename ] . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. DESCRIPTION roffbib prints out all records in a bibliographic database, in bibliography format rather than as footnotes or endnotes. Generally it is used in conjunction with sortbib(l): example% sortbib database | roffbib OPTIONS roffbib accepts all options understood by nroff(l) except -i and -q. -e Produce equally-spaced words in adjusted lines using full terminal resolution. -h Use output tabs during horizontal spacing to speed output and reduce output character count. TAB settings are assumed to be every 8 nominal character widths. -m filename Prepend the macro file /usr/share/lib/tmac/tmac.name to the input files. There should be a space between the -m and the macro filename. This set of macros will replace the ones defined in /usr/share/lib/tmac/tmac.bib. -n p Number first generated page p . -olist Print only page numbers that appear in the comma-separated list of numbers and ranges. A range N-M means pages N through M ; an initial —N means from the beginning to page N; a final N— means from page N to end. -Q Queue output for the phototypesetter. Page offset is set to 1 inch. -r aN Set register a (one-character) to N. The command-line argument -rNl will number the references starting at 1. Four command-line registers control formatting style of the bibliography, much like the number registers of ms(7). The flag -rV2 will double space the bibliography, while -rVl will double space references but single space annotation paragraphs. The line length can be changed from the default 6.5 inches to 6 inches with the -rL6i argument, and the page offset can be set from the de- fault of 0 to one inch by specifying -rOli (capital O, not zero). -sN Halt prior to every N pages for paper loading or changing (default N =1). To resume, enter NEW- LINE or RETURN. -T term Specify term as the terminal type. -V Send output to the Versatec. Page offset is set to 1 inch. This option not available on Sun386i systems. -x If abstracts or comments are entered following the %X field key, roffbib will format them into paragraphs for an annotated bibliography. Several %X fields may be given if several annotation paragraphs are desired. FILES /usr/share/lib/tmac/tmac.bib file of macros used by nroff/troff 442 Last change: 18 February 1988 Sun Release 4.1 ROFFBIB ( 1 ) USER COMMANDS ROFFBIB ( 1 ) SEE ALSO addbib(l), indxbib(l), lookbib(l), nroff(l) refer(l), sortbib(l), troff(l) Formatting Documents BUGS Users have to rewrite macros to create customized formats. Sun Release 4.1 Last change: 18 February 1988 443 RPCGEN ( 1 ) USER COMMANDS RPCGEN ( 1 ) NAME rpcgen - RPC protocol compiler SYNOPSIS rpcgen infile rpcgen [ -D name [= value] ] [ -I [ -K seconds ] ] [ -L ] [ -T ] infile rpcgen — c | — h | —1 | -m | — t [ — o outfile ] [ infile ] rpcgen -s transport [ -o outfile ] [ infile ] DESCRIPTION rpcgen generates C code to implement an RPC protocol. The input to rpcgen is a language similar to C known as the RPC Language (Remote Procedure Call Language). Information about the syntax of RPC Language is available in the ‘ rpcgen ’ Programming Guide in the Network Programming manual. rpcgen is normally used as in the first synopsis where it takes an input file and generates four output files. If the infile is named proto.x, then rpcgen generates a header file in proto.h, XDR routines in proto_xdr.c, server side stubs in proto_svc.c, and client side stubs in proto_clnt.c. With the -T option, it also gen- erates the RPC dispatch table in proto tbl.i. The second synposis provides special features which allow for the creation of more sophisticated RPC servers. These features include support for RPC dispatch tables, and user provided #defines. The entries in the RPC dispatch table contain: • pointers to the service routine corresponding to that procedure a a pointer to the input and output arguments • the size of these routines A server can use the dispatch table to check authorization and then to execute the service routine; a client library may use it to deal with the details of storage management and XDR data conversion. The other two synopses shown above are used when one does not want to generate all the output files, but only a particular one. Their usage is described in the EXAMPLES section below. The C-preprocessor, cpp(l), is run on the input file before it is actually interpreted by rpcgen, so all the cpp directives are legal within an rpcgen input file. For each type of output file, rpcgen defines a special cpp symbol for use by the rpcgen programmer: RPCHDR RPC_XDR RPCSVC RPCCLNT RPC TBL defined when compiling into header files defined when compiling into XDR routines defined when compiling into server side stubs defined when compiling into client side stubs defined when compiling into RPC dispatch tables In addition, rpcgen does a little preprocessing of its own. Any line beginning with ‘ % ’ is passed directly into the output file, uninterpreted by rpcgen. For every data type referred to in infile, rpcgen assumes that there exists a routine with the string ‘xdr_’ prepended to the data type. If this routine does not exist in the RPC/XDR library, it must be provided. Providing an undefined data type allows customization of XDR rou- tines. OPTIONS -c Compile into XDR routines. -D name[=value] Define a symbol name. Equivalent to the #define directive in the source. If no value is given, name is defined as 1. This option may be called more than once. -h Compile into C data-definitions (a header file). The -T option can be used in conjunction to produce a header file which supports RPC dispatch tables. -I Compile support for inetd(8C) in the server side stubs. Such servers can be self started or can be started by inetd. When the server is self-started, it backgrounds itself by default. A special define symbol RPC_SVC_FG can be used to run the server process in foreground, or 444 Last change: 20 January 1990 Sun Release 4.1 RPCGEN ( 1 ) USER COMMANDS RPCGEN ( 1 ) alternately the user may just compile it without the —I option. If there are no pending client requests, the inetd servers exit after 120 seconds (default). The default can be changed with the — K option. All the error messages for inetd servers are always logged in with syslog(3). -K seconds If the server was started by inetd, specify the time in seconds after which the server should exit if there is no further activity. This option is useful for customization. If seconds is 0, the server exits after serving that given request. If seconds is — 1, the server hangs around for ever after being started by inetd. This option is valid only with the -I option. -1 Compile into client side stubs. -L When the servers are started in foreground, use syslog( ) to log the server errors instead of printing them on the standard error. -m Compile into server side stubs, but do not generate a “main” routine. This option is useful for doing callback-routines and for people who need to write their own “main” routine to do initialization. For inetd support, they should be compiled with the -I option. In such cases, it defines 2 global variables: _rpcpmstart and rpcfdtype. The value of _rpcpmstart should be 1 or 0 depending upon whether it was started by inetd or not. The value of jrpcfdtype should be SOCK_STREAM or SOCK_DGRAM depending upon the type of the connection. Specify the name of the output file. If none is specified, the standard output is used (-c, -h, -I, -m, -s and -t modes only). Compile into server side stubs for the given transport. The supported transports are udp and tcp. This option may be called more than once so as to compile a server that serves multiple transports. For inetd support, they should be compiled with the —I option. Compile into RPC dispatch table. Generate the code to support RPC dispatch tables. -c, -h, -1, -m, -s and -t are used exclusively to generate a particular type of file, while the I, -L and -T are global and can be used with the other options. -o outfile -s transport -t -T The options - options -D, - EXAMPLES The following example generates all the five files: prot.h, prot_clnt.c, prot_svc.c, prot_xdr.c and prot_tbl.i. The server error messages are logged, instead of being sent to the standard error. example % rpcgen -LT prot.x The following example generates prot.h, protclntc, prot xdr.c and prot_svc.c. protsvc.c supports server invocation by inetd. If the server is started by inetd, the server exits after 20 seconds of inactivity. example% rpcgen -I -K 20 prot.x The following example sends the header file (with support for dispatch tables) on the standard output. example'% rpcgen -hT prot.x The following example sends the server side stubs file for the transport tcp on the standard output. example% rpcgen -s tcp prot.x SEE ALSO cpp(l), rpc(3N), inetd(8C) ‘ rpcgen ’ Programming Guide in N etwork Programming Sun Release 4.1 Last change: 20 January 1990 445 RPCGEN(l) USER COMMANDS RPCGEN ( 1 ) BUGS The RPC Language does not support nesting of structures. As a work-around, structures can be declared at the top-level, and their name used inside other structures in order to achieve the same effect. Name clashes can occur when using program definitions, since the apparent scoping does not really apply. Most of these can be avoided by giving unique names for programs, versions, procedures and types. 446 Last change: 20 January 1990 Sun Release 4.1 RSH(IC) USER COMMANDS RSH(IC) NAME rsh - remote shell SYNOPSIS rsh [ -1 username ] [ -n ] hostname [ command ] rsh hostname [ -1 username ] [ -n ] [ command ] hostname [ -1 username ] [ -n ] [ command ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION rsh connects to the specified hostname and executes the specified command, rsh copies its standard input to the remote command, the standard output of the remote command to its standard output, and the standard error of the remote command to its standard error. Interrupt, quit and terminate signals are propagated to the remote command; rsh normally terminates when the remote command does. If you omit command, instead of executing a single command, rsh logs you in on the remote host using rlogin(lC). Shell metacharacters which are not quoted are interpreted on the local machine, while quoted metacharac- ters are interpreted on the remote machine. See EXAMPLES. Hostnames are given in the hosts database, which may be contained in the /etc/hosts file, the Network In- formation Service (NIS) hosts database, the Internet domain name database, or some combination of the three. Each host has one official name (the first name in the database entry) and optionally one or more nicknames. Official hostnames or nicknames may be given as hostname. If the name of the file from which rsh is executed is anything other than “rsh,” rsh takes this name as its hostname argument. This allows you to create a symbolic link to rsh in the name of a host which, when executed, will invoke a remote shell on that host. The /usr/hosts directory is provided to be populated with symbolic links in the names of commonly used hosts. By including /usr/hosts in your shell’s search path, you can run rsh by typing hostname to your shell. Each remote machine may have a file named /etc/hosts.equiv containing a list of trusted hostnames with which it shares usernames. Users with the same username on both the local and remote machine may rsh from the machines listed in the remote machine’s /etc/hosts file. Individual users may set up a similar private equivalence list with the file .rhosts in their home directories. Each line in this file contains two names: a hostname and a username separated by a SPACE. The entry permits the user named username who is logged into hostname to use rsh to access the remote machine as the remote user. If the name of the local host is not found in the /etc/hosts.equiv file on the remote machine, and the local username and host- name are not found in the remote user’s .rhosts file, then the access is denied. The hostnames listed in the /etc/hosts.equiv and .rhosts files must be the official hostnames listed in the hosts database; nicknames may not be used in either of these files. rsh will not prompt for a password if access is denied on the remote machine unless the command argu- ment is omited. OPTIONS -1 username Use username as the remote username instead of your local username. In the absence of this op- tion, the remote username is the same as your local username. -n Redirect the input of rsh to /dev/null. You sometimes need this option to avoid unfortunate in- teractions between rsh and the shell which invokes it. For example, if you are running rsh and start a rsh in the background without redirecting its input away from the terminal, it will block even if no reads are posted by the remote command. The -n option will prevent this. Sun Release 4.1 Last change: 17 December 1987 447 RSH(IC) USER COMMANDS RSH(IC) The type of remote shell (sh, rsh, or other) is determined by the user’s entry in the file /etc/passwd on the remote system. EXAMPLES The following command appends the remote file lizard.file from the machine called lizard to the file called example.file on the machine called example. example% rsh lizard cat lizard.file » example.file This example appends the file lizard.file on the machine called lizard to the file another.lizard.file which also resides on the machine called lizard. example% rsh lizard cat lizard.file "»" another. lizard. file FILES /etc/hosts /usr/hosts/* /etc/passwd SEE ALSO rlogin(lC), vi(l), ypcat(l), hosts(5), named(8C), rshd(8C) BUGS You cannot run an interactive command (such as vi(l)); use rlogin if you wish to do so. Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to explain here. The current local environment is not passed to the remote shell. Sometimes the -n option is needed for reasons that are less than obvious. For example, the command below puts your shell into a strange state. example % rsh somehost dd if=/dev/nrmtO bs=20b | tar xvpBf- Evidently, what happens is that the tar terminates before the rsh. The rsh then tries to write into the “bro- ken pipe” and, instead of terminating neatly, proceeds to compete with your shell for its standard input. In- voking rsh with the -n option avoids such incidents. Note: this bug occurs only when rsh is at the beginning of a pipeline and is not reading standard input. Do not use the -n if rsh actually needs to read standard input. For example, the following command does not produce the bug. example% tar cf - . | rsh sundial dd of=/dev/rmtO obs=20b If you were to use the -n in a case like this, rsh would incorrectly read from /dev/null instead of from the pipe. NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. 448 Last change: 17 December 1987 Sun Release 4.1 RUP(IC) USER COMMANDS RUP(IC) NAME rup - show host status of local machines (RPC version) SYNOPSIS rup [ -hit ] rup [ host. . . ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION rup gives a status similar to uptime for remote machines. It broadcasts on the local network, and displays the responses it receives. Normally, the listing is in the order that responses are received, but this order can be changed by specifying one of the options listed below. When host arguments are given, rather than broadcasting rup will only query the list of specified hosts. A remote host will only respond if it is running the rstatd daemon, which is normally started up from inetd(8C). OPTIONS -h Sort the display alphabetically by host name. -1 Sort the display by load average. -t Sort the display by up time. FILES /etc/servers SEE ALSO ruptime(lC), inetd(8C), rstatd(8C) BUGS Broadcasting does not work through gateways. Sun Release 4. 1 Last change: 17 December 1987 449 RUPTTME(IC) USER COMMANDS RUPTIME(IC) NAME ruptime - show host status of local machines SYNOPSIS ruptime [ -alrtu ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. 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. -r Reverse the sorting order. -t Sort the display by up time. -u Sort the display by number of users. FILES / var/spool/ rwho/whod.* data files SEE ALSO rup(lC), rwho(lC) 450 Last change: 17 December 1987 Sun Release 4.1 RUSERS(IC) USER COMMANDS RUSERS(IC) NAME rusers - who’s logged in on local machines (RPC version) SYNOPSIS rusers [ -ahilu ] [ host. . . ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION The rusers command produces output similar to users(l) and who(l), but for remote machines. It broad- casts on the local network, and prints the responses it receives. Normally, the listing is in the order that responses are received, but this order can be changed by specifying one of the options listed below. When host arguments are given, rather than broadcasting rusers will only query the list of specified hosts. The default is to print out a listing in the style of users(l) with one line per machine. When the -1 flag is given, a rwho(lC) style listing is used. In addition, if a user has not typed to the system for a minute or more, the idle time is reported. A remote host will only respond if it is running the rusersd daemon, which is normally started up from inetd(8C). OPTIONS -a Give a report for a machine even if no users are logged on. -h Sort alphabetically by host name. -i Sort by idle time. -1 Give a longer listing in the style of who(l). -u Sort by number of users. FILES /etc/inetd.conf SEE ALSO rwho(lC), users(l), who(l), inetd(8C), rusersd(8C) BUGS Broadcasting does not work through gateways. Sun Release 4. 1 Last change: 17 December 1987 451 RWALL(IC) USER COMMANDS RWALL(IC) NAME rwall - write to all users over a network SYNOPSIS /usr/etc/rwall hostname . . . /usr/etc/rwall -n net group. . . /usr/etc/rwall -h hostname -n netgroup AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION rwall reads a message from standard input until EOF. 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(8C), which is normally started up from /etc/inetd.conf by the daemon inetd(8C). FILES /etc/inetd.conf SEE ALSO wall(l), netgroup(5), inetd(8C), rwalld(8C), shutdown(8) BUGS The timeout is fairly short in order to be able to send to a large group of machines (some of which may be down) in a reasonable amount of time. Thus the message may not get through to a heavily loaded machine. 452 Last change: 17 December 1987 Sun Release 4.1 RWHO(IC) USER COMMANDS RWHO(IC) NAME rwho - who’s logged in on local machines SYNOPSIS rwho [ -a ] AVAILABILITY The rwho service daemon, rwhod(8C) must be enabled for this command to return useful results. Refer to finger(l), rup(lC) and rusers(lC) for alternatives. AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION The rwho command produces output similar to who(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 has not typed to the system for a minute or more, rwho reports this idle time. If a user has not 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 /var/spool/rwho/whod.* information about other machines SEE ALSO finger(l), rup(lC), ruptime(lC), rusers(lC), who(l), rwhod(8C) BUGS Does not work through gateways. This is unwieldy when the number of machines on the local net is large. Sun Release 4.1 Last change: 17 December 1987 453 sees ( 1 ) USER COMMANDS SCCS(l) NAME sees - front end for the Source Code Control System (SCCS) SYNOPSIS sees [ -r ] [ -drootprejix ] [ -p subdir ] subcommand [ option . . . ] [ filename . . . ] DESCRIPTION The sees command is a comprehensive, straightforward front end to the various utility programs of the Source Code Control System (SCCS). secs applies the indicated subcommand to the history file associated with each of the indicated files. The name of an SCCS history file is derived by prepending the ‘s.’ prefix to the filename of a working copy. The sees command normally expects these ‘s.files’ to reside in an SCCS subdirectory. Thus, when you supply secs with a filename argument, it normally applies the subcommand to a file named s. filename in the SCCS subdirectory. If filename is a pathname, secs looks for the history file in the SCCS subdirecto- ry of that file’s parent directory. If filename is a directory, however, sees applies the subcommand to every s.file file it contains. Thus, the command: secs get program.c would apply the get subcommand to a history file named: SCCS/s.program.c while the command: secs get SCCS would apply it to every s.file in the SCCS subdirectory. Options for the secs command itself must appear before the subcommand argument. Options for a given subcommand must appear after the subcommand argument. These options are specific to each subcom- mand, and are described along with the subcommands themselves (see Subcommands, below). Running Setuid The sees command also includes the capability to run “setuid” to provide additional protection. However this does not apply to subcommands such as sccs-admin(l), since this would allow anyone to change the authorizations of the history file. Commands that would do so always run as the real user. OPTIONS -r Run secs with the real user ID, rather than set to the effective user ID. -drootprejix Define the root portion of the pathname for SCCS history files. The default root portion is the current directory. Note: rootprefix is prepended to the entire filename argument, even if filename is an absolute pathname, -d overrides any directory specified by the PROJECTDIR environment variable (see ENVIRONMENT, below). -p subdir Define the (subdirectory within which a history file is expected to reside. SCCS is the default. (See EXAMPLES, below). USAGE Subcommands Many of the following secs subcommands invoke programs that reside in /usr/sccs. Many of these sub- commands accept additional arguments that are documented in the reference page for the utility program the subcommand invokes. admin Modify the flags or checksum of an SCCS history file. Refer to sccs-admin(l) for more informa- tion about the admin utility. While admin can be used to initialize a history file, you may find that the create subcommand is simpler to use for this purpose. 454 Last change: 2 August 1988 Sun Release 4.1 SCCS(l) USER COMMANDS SCCS ( 1 ) ede — r sid [ —y [comment] ] Annotate (change) the delta commentary. Refer to sccs-cdc(l). Note: the fix subcommand can be used to replace the delta, rather than merely annotating the existing commentary. -r sid Specify the SCCS delta ID (SID) to which the change notation is to be added. The SID for a given delta is a number, in Dewey decimal format, composed of two or four fields: the release and level fields, and for branch deltas, the branch and sequence fields. For instance, the SID for the initial delta is normally 1.1. -y [comment] Specify the comment with which to annotate the delta commentary. If -y is om- itted, sees prompts for a comment. A null comment results in an empty annota- tion. check [-b] ]-u[username]] Check for files currently being edited. Like info and tell, but returns an exit code, rather than pro- ducing a listing of files, check returns a non-zero exit status if anything is being edited. -b Ignore branches. — u [username] Only check files being edited by you. When username is specified, only check files being edited by that user. clean [-b] Remove everything in the current directory that can be retrieved from an SCCS history. Does not remove files that are being edited. -b Do not check branches to see if they are being edited, ‘clean -b’ is dangerous when branch versions are kept in the same directory. comb Generate scripts to combine deltas. Refer to sccs-comb(l). create Create (initialize) history files, create performs the following steps: • Renames the original source file to ,program.c in the current directory. • Create the history file called s.program.c in the SCCS subdirectory. • Performs an ‘sees get’ on program.c to retrieve a read-only copy of the initial version. deledit [-s] [-y [comment] ] Equivalent to an ‘sees delta’ and then an ‘sees edit’, deledit checks in a delta, and checks the file back out again, but leaves the current working copy of the file intact. -s Silent. Do not report delta numbers or statistics. -y [comment] Supply a comment for the delta commentary. If -y is omitted, delta prompts for a comment. A NULL comment results in an empty comment field for the delta. delget [-s] [-y [comment] ] Perform an ‘sees delta’ and then an ‘sees get’ to check in a delta and retrieve read-only copies of the resulting new version. See the deledit subcommand for a description of -s and -y. sees per- forms a delta on all the files specified in the argument list, and then a get on all the files. If an er- ror occurs during the delta, the get is not performed. delta [-s] [-y [comment] ] Check in pending changes. Records the line-by-line changes introduced while the file was checked out. The effective user ID must be the same as the ID of the person who has the file checked out. Refer to sccs-delta(l). See the deledit subcommand for a description of-s and -y. Sun Release 4.1 Last change: 2 August 1988 455 sees ( 1 ) USER COMMANDS sees ( 1 ) diffs [-C] [-c date-time] [-rsz'd] diff-options Compare (in diff(l) format) the working copy of a file that is checked out for editing, with a ver- sion from the SCCS history. Use the most recent checked-in version by default. The diffs sub- command accepts the same options as diff, with the exception that the -c option to diff must be specified as -C. -C Pass the -c option to diff. -c date-time Use the most recent version checked in before the indicated date and time for comparison, date-time takes the form: yy [mm [ dd[hh [mm [ 55 ] ] ] ] ]. Omitted un- its default to their maximum possible values; that is -c7502 is equivalent to -C750228235959. -r sid Use the version corresponding to the indicated delta for comparison. edit Retrieve a version of the file for editing, ‘sees edit’ extracts a version of the file that is writable by you, and creates a p.file in the SCCS subdirectory as lock on the history, so that no one else can check that version in or out. ID keywords are retrieved in unexpanded form, edit accepts the same options as get, below. enter Similar to create, but omits the final ‘sees get’. This may be used if an ‘secs edit’ is to be per- formed immediately after the history file is initialized. fix -rsid Revise a (leaf) delta. Remove the indicated delta from the SCCS history, but leave a working copy of the current version in the directory. This is useful for incorporating trivial updates for which no audit record is needed, or for revising the delta commentary, fix must be followed by a -r option, to specify the SID of the delta to remove. The indicated delta must be the most recent (leaf) delta in its branch. Use fix with caution since it does not leave an audit trail of differences (although the previous commentary is retained within the history file). get [-ekmps] [-c date-time] [-rsz'd] Retrieve a version from the SCCS history. By default, this is a read-only working copy of the most recent version; ID keywords are in expanded form. Refer to sccs-get(l). -e Retrieve a version for editing. Same as secs edit. -k Retrieve a writable copy but do not check out the file. ID keywords are unex- panded. -m Precede each line with the SID of the delta in which it was added. -p Produce the retrieved version on the standard output. Reports that would nor- mally go to the standard output (delta ID’s and statistics) are directed to the stan- dard error. -s Silent. Do not report version numbers or statistics. -c date-time Retrieve the latest version checked in prior to the date and time indicated by the date-time argument, date-time takes the form: yy[mm[dd[hh[mm[ss] ] ] ] ]. -r sid Retrieve the version corresponding to the indicated SID. help message-code\sccs-command help stuck Supply more information about SCCS diagnostics, help displays a brief explanation of the error when you supply the code displayed by an SCCS diagnostic message. If you supply the name of an SCCS command, it prints a usage line, help also recognizes the keyword stuck. Refer to sccs- help(l). 456 Last change: 2 August 1988 Sun Release 4.1 sees ( 1 ) USER COMMANDS SCCS(l) info [-b] [-u [username]] Display a list of files being edited, including the version number checked out, the version to be checked in, the name of the user who holds the lock, and the date and time the file was checked out. -b Ignore branches. -u [username] Only list files checked out by you. When username is specified, only list files checked out by that user. print Print the entire history of each named file. Equivalent to an ‘sees prs -e’ followed by an ‘secs get -p -m’. prs [-el] [-c date- time] [-rsid] Peruse (display) the delta table, or other portion of an s.file. Refer to sccs-prs(l). -e Display delta table information for all deltas earlier than the one specified with -r (or all deltas if none is specified). -1 Display information for all deltas later than, and including, that specified by -c or-r. -c date-time Specify the latest delta checked in before the indicated date and time. The date-time argument takes the form: yy [mm [dd[hh [mm [ 55 ] ] ] ] ]. -rsid Specify a given delta by SID. prt [-y] Display the delta table, but omit the MR field (see sccsfile(5) for more information on this field). Refer to sccs-prt(l). -y Display the most recent delta table entry. The format is a single output line for each filename argument, which is convenient for use in a pipeline with awk(l) orsed(lV). rmdel -rsid Remove the indicated delta from the history file. That delta must be the most recent (leaf) delta in its branch. Refer to sccs-rmdel(l). sccsdiff -r old-sid -rnew-sid diff-options Compare two versions corresponding to the indicated SIDs (deltas) using diff. Refer to sccs- sccsdiff(l). tell [-b] [-u [username] ] Display the list of files that are currendy checked out, one filename per line. -b Ignore branches. -u [username] Only list files checked out to you. When username is specified, only list files check out to that user. unedit “Undo” the last edit or ‘get -e\ and return the working copy to its previous condition, unedit backs out all pending changes made since the file was checked out. unget Same as unedit. Refer to sccs-unget(l). val Validate the history file. Refer to sccs-val(l). what Display any expanded ID keyword strings contained in a binary (object) or text file. Refer to what(l) for more information. Sun Release 4.1 Last change: 2 August 1988 457 SCCS(l) USER COMMANDS SCCS ( 1 ) ENVIRONMENT If the environment variable PROJECTDIR is set to contain an absolute pathname (beginning with a slash), sccs searches for SCCS history files in the directory given by that variable. If PROJECTDIR does not begin with a slash, it is taken as the name of a user, and sccs searches the sre or source subdirectory of that user’s home directory for history files. EXAMPLES sccs converts the command: sccs -d/usr/src/include get stdio.h to: /usr/sccs/get /usr/src/include/SCCS/s.stdio.h The command: sccs -pprivate get include/stdio.h becomes: /usr/sccs/get include/private/s.stdio.h To initialize the history file for a source file named program.c: make the SCCS subdirectory, and then use ‘sees create’: example% mkdir SCCS example % sccs create program.c program.c: 1.1 14 lines After verifying the working copy, you can remove the backup file that starts with a comma: example% diff program.c , program.c example% rm , program.c To check out a copy of program.c for editing, edit it, and then check it back in: example% sccs edit program.c 1.1 new delta 1.2 14 lines example% vi program.c your editing session example% sccs delget program.c comments? clarified cryptic diagnostic 1.2 3 inserted 2 deleted 12 unchanged 1.2 15 lines To retrieve a file from another directory into the current directory: example% sccs get /usr/src/sccs/cc.c or: example % sccs -p/usr/src/sccs/ get cc.c 458 Last change: 2 August 1988 Sun Release 4.1 SCCS(l) USER COMMANDS SCCS ( 1 ) To check out all files under SCCS in the current directory: example% sees edit SCCS To check in all files currently checked out to you: example % secs delta 'secs tell -u' FILES SCCS SCCS subdirectory SCCSldfile temporary file of differences SCCSlpfile lock (permissions) file for checked-out versions SCCS/ q file temporary file SCCS/ s file SCCS history file SCCS/xfile temporary copy of the s.file SCCS/zfile temporary lock file /usr/sccs/* SCCS utility programs SEE ALSO awk(l), diff(l), sccs-admin(l), sccs-cdc(l), sccs-comb(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs- prs(l), sccs-rmdel(l), sccs-sact(l), sccs-sccsdiff(l), sccs-unget(l), sccs-val(l), sed(lV), what(l), sccsfile(5) Programming Utilities and Libraries BUGS There is no sact subcommand to invoke /usr/sccs/sact (see sccs-sact(l)). However, the info subcommand performs an equivalent function. Sun Release 4. 1 Last change: 2 August 1988 459 SCCS-ADMIN ( 1 ) USER COMMANDS SCCS-ADMIN ( 1 ) NAME sccs-admin, admin - create and administer SCCS history files SYNOPSIS /usr/sccs/admin [ -bhnz ] [ -ausername\groupid ] . . . [ -d flag ] . . . [ -zusernamelgroupid ] . . . [ — f flag [ value ] ] . . . [ -i [filename ] ] [ -1 al release [, release. . . ] ] [ -m mr-list ] [ -r release ] t -t [ description-file ] ] [ -y [comment] ] s.filename . . . DESCRIPTION admin creates or modifies the flags and other parameters of SCCS history files. Filenames of SCCS history files begin with the ‘s.’ prefix, and are referred to as s.files, or “history” files. The named s.file is created if it does not exist already. Its parameters are initialized or modified according to the options you specify. Parameters not specified are given default values when the file is initialized, otherwise they remain unchanged. If a directory name is used in place of the s.filename argument, the admin command applies to all s.files in that directory. Unreadable s.files produce an error. The use of as the s.filename argument indicates that the names of files are to be read from the standard input, one s.file per line. OPTIONS -b Force encoding of binary data. Files that contain ASCII NUL or other control characters, or that do not end with a NEWLINE, are recognized as binary data files. The contents of such files are stored in the history file in encoded form. See uuencode(lC) for details about the encoding. This option is normally used in conjunction with -i to force admin to encode initial versions not recognized as containing binary data. -h Check the structure of an existing s.file (see sccsfile(5», and compare a newly computed check- sum with one stored in the first line of that file, -h inhibits writing on the file; and so nullifies the effect of any other options. -n Create a new SCCS history file. -z Recompute the file check-sum and store it in the first line of the s.file. Caution: it is important to verify the contents of the history file (see sccs-val(l), and the print subcommand in sccs(l)), since using -z on a truly corrupted file may prevent detection of the error. -ausername\groupid Add a user name, or a numerical group ID, to the list of users who may check deltas in or out. If the list is empty, any user is allowed to do so. -dflag Delete the indicated flag from the SCCS file. The -d option may be specified only for existing s.files. See -f for the list of recognized flags. -eusername \groupid Erase a user name or group ID from the list of users allowed to make deltas. -fflag [value] Set the indicated flag to the (optional) value specified. The following flags are recognized: b Enable branch deltas. When b is set, branches can be created using the -b op- tion of the SCCS get command (see sccs-get(l)). cceil Set a ceiling on the releases that can be checked out. ceil is a number less than or equal to 9999. If c is not set, the ceiling is 9999. ffloor Set a floor on the releases that can be checked out. The floor is a number greater than 0 but less than 9999. If f is not set, the floor is 1. d sid The default delta number, or SID, to be used by an SCCS get command. 460 Last change: 19 December 1989 Sun Release 4.1 SCCS-ADMIN ( 1 ) USER COMMANDS SCCS-ADMIN ( 1 ) i Treat the ‘No id keywords (ge6)’ message issued by an SCCS get or delta com- mand as an error rather than a warning. j Allow concurrent updates. la lrelease[, release . . . ] Lock the indicated list of releases against deltas. If a is used, lock out deltas to all releases. An SCCS ‘get -e’ command fails when applied against a locked release. n Create empty releases when releases are skipped. These null (empty) deltas serve as anchor points for branch deltas. q value Supply a value to which the %Q% keyword is to expand when a read-only ver- sion is retrieved with the SCCS get command. m module Supply a value for the module name to which the %M% keyword is to expand. If the m flag is not specified, the value assigned is the name of the SCCS file with the leading s. removed. t type Supply a value for the module type to which the % Y % keyword is to expand, v [ program ] Specify a validation program for the MR numbers associated with a new delta. The optional program specifies the name of an MR number validity checking program. If this flag is set when creating an SCCS file, the -m option must also be used, in which case the list of MRs may be empty. -i [filename] Initialize the history file with text from the indicated file. This text constitutes the initial delta, or set of checked-in changes. If filename is omitted, the initial text is obtained from the standard in- put. Omitting the -i option altogether creates an empty s.file. You can only initialize one s.file with text using -i. This option implies the -n option. -la -1 release [, release. . . ] Unlock the specified releases so that deltas can be checked in. If a is specified, allow deltas to be checked in for all releases. -m [ mr-list ] Insert the indicated Modification Request (MR) numbers into the commentary for the initial ver- sion. When specifying more than one MR number on the command line, mr-list takes the form of a quoted, space-separated list. A warning results if the v flag is not set or the MR validation fails. -r release Specify the release for the initial delta, -r may be used only in conjunction with -i. The initial delta is inserted into release 1 if this option is omitted. The level of the initial delta is always 1; initial deltas are named 1.1 by default. -t [ description-file ] Insert descriptive text from the file description-file. When — t is used in conjunction with — n, or — i to initialize a new s.file, the description-file must be supplied. When modifying the description for an existing file: a — t option without a description-file removes the descriptive text, if any; a — t op- tion with a description-file replaces the existing text. -y [ comment ] Insert the indicated comment in the “Comments:” field for the initial delta. Valid only in con- junction with -i or -n. If -y option is omitted, a default comment line is inserted that notes the date and time the history file was created. Sun Release 4.1 Last change: 19 December 1989 461 SCCS-ADMIN ( 1 ) USER COMMANDS SCCS-ADMIN ( 1 ) FILES s.* history file SCCS/s.* history file in SCCS subdirectory z.* temporary lock file WARNINGS The last component of all SCCS filenames must have the ‘s.’ prefix. New SCCS files are given mode 444 (see chmod(lV)). All writing done by admin is to a temporary file with an x. prefix, created with mode 444 for a new SCCS file, or with the same mode as an existing SCCS file. After successful execution of ad- min, the existing s. file is removed and replaced with the x.file. This ensures that changes are made to the SCCS file only when no errors have occurred. It is recommended that directories containing SCCS files have permission mode 755, and that the s.files themselves have mode 444. The mode for directories allows only the owner to modify the SCCS files con- tained in the directories, while the mode of the s.files prevents all modifications except those performed us- ing SCCS commands. If it should be necessary to patch an SCCS file for any reason, the mode may be changed to 644 by the own- er to allow use of a text editor. However, extreme care must be taken when doing this. The edited file should always be processed by an ‘admin -h’ to check for corruption, followed by an ‘admin -z’ to gen- erate a proper check-sum. Another ‘admin -h’ is recommended to ensure that the resulting s.file is valid. admin also uses a temporary lock s.file, starting with the ‘z.’ prefix, to prevent simultaneous updates to the s.file. See sccs-get(l) for further information about the ‘z.file’. SEE ALSO sccs(l), sccs-cdc(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-rmdel(l), sccs-val(l), sccsfile(5) Programming Utilities and Libraries. DIAGNOSTICS Use the SCCS help command for explanations (see sccs-help(l)). 462 Last change: 19 December 1989 Sun Release 4.1 SCCS-CDC(l) USER COMMANDS SCCS-CDC(l) NAME sccs-cdc, cdc — change the delta commentary of an SCCS delta SYNOPSIS /usr/sccs/cdc -r sid [ -m mr-list ] [ -y [ comment ] ] s.filename . . . DESCRIPTION cdc annotates the delta commentary for the SCCS delta ID (SID) specified by the -r option in each named s.file. If the v flag is set in the s.file, you can also use cdc to update the Modification Request (MR) list. If you checked in the delta, or, if you own the file and directory and have write permission, you can use cdc to annotate the commentary. Rather than replacing the existing commentary, cdc inserts the new comment you supply, followed by a line of the form: *** CHANGED *** yylmmldd hh/mmlss username above the existing commentary. If a directory is named as the s.filename argument, the cdc command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). If is given as the s.filename argument, each line of the standard input is taken as the name of an SCCS history file to be pro- cessed, and the -m and -y options must be used. OPTIONS -rsid Specify the SID of the delta to change. -mmr-list Specify one or more MR numbers to add or delete. When specifying more than one MR on the command line, mr-list takes the form of a quoted, space-separated list. To delete an MR number, precede it with a ! character (an empty MR list has no effect). A list of deleted MRs is placed in the comment section of the delta commentary. If -m is not used and the standard input is a terminal, cdc prompts with MRs? for the list (before issuing the comments? prompt), -m is only useful when the v flag is set in the s.file. If that flag has a value, it is taken to be the name of a program to validate the MR numbers. If that validation program returns a non-zero exit status, cdc terminates and the delta commen- tary remains unchanged. — y [comment] Use comment as the annotation in the delta commentary. The previous comments are retained; the comment is added along with a notation that the commentary was changed. A null comment leaves the commentary unaffected. If -y is not specified and the stan- dard input is a terminal, cdc prompts with comments? for the text of the notation to be added. An unescaped NEWLINE character terminates the annotation text. EXAMPLES The following command: example% cdc -rl.6 -y" corrected commentary" s.program.c produces the following annotated commentary for delta 1.6 in s.program.c: D 1.6 88/07/05 23:21:07 username 9 0 00001/00000/00000 MRs: COMMENTS: corrected commentary *** CHANGED *** 88/07/07 14:09:41 username performance enhancements in main() Sun Release 4.1 Last change: 27 June 1988 463 SCCS-CDC(l) USER COMMANDS SCCS-CDC ( 1 ) FILES z.file temporary lock file SEE ALSO sccs(l), sccs-admin(l), sccs-comb(l), sccs-delta(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). 464 Last change: 27 June 1988 Sun Release 4.1 SCCS-COMB ( 1 ) USER COMMANDS SCCS-COMB ( 1 ) NAME sccs-comb, comb - combine SCCS deltas SYNOPSIS /usr/sccs/comb [ -os ] [ -c sid-list ] [ -p sid ] s.filename . . . DESCRIPTION comb generates a shell script (see sh(l)) that you can use to reconstruct the indicated s.files. This script is written to the standard output. If a directory name is used in place of the s.filename argument, the comb command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard in- put, one s.file per line. If no options are specified, comb preserves only the most recent (leaf) delta in a branch, and the minimal number of ancestors needed to preserve the history. OPTIONS -o For each ‘get -e’ generated, access the reconstructed file at the release of the delta to be created. Otherwise, the reconstructed file is accessed at the most recent ancestor. The use of -o may de- crease the size of the reconstructed s.file. It may also alter the shape of the delta tree of the origi- nal file. -s Generate scripts to gather statistics, rather than combining deltas. When run, the shell scripts re- port: the file name, size (in blocks) after combining, original size (also in blocks), and the percen- tage size change, computed by the formula: 100 * ( original - combined ) / original This option can be used to calculate the space that will be saved, before actually doing the com- bining. -c sid-list Include the indicated list of deltas. All other deltas are omitted, sid-list is a comma-separated list of SCCS delta IDs (SIDs). To specify a range of deltas, use a separator instead of a comma, between two SIDs in the list. -p SID The SID of the oldest delta to be preserved. FILES s. COMB reconstructed SCCS file comb????? temporary file SEE ALSO sccs(l), sccs-admin(l), sccs-cdc(l), sccs-delta(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), sccs-sccsdiff(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). BUGS comb may rearrange the shape of the tree of deltas. It may not save any space; in fact, it is possible for the reconstructed file to actually be larger than the original. Sun Release 4.1 Last change: 27 June 1988 465 SCCS-DELTA ( 1 ) USER COMMANDS SCCS-DELTA ( 1 ) NAME sccs-delta, delta - make a delta to an SCCS file SYNOPSIS /usr/sccs/delta [ — nps ] [ — g sid-list ] [ -m mr-list ] [ — r sid ] [ — y [comment] ] s.filename . . . DESCRIPTION delta checks in a record of the line-by-line differences made to a checked-out version of a file under SCCS control. These changes are taken from the writable working copy that was retrieved using the SCCS get command (see sccs-get(l)). This working copy does not have the ‘s.’ prefix, and is also referred to as a g-file. If a directory name is used in place of the s.filename , argument, the delta command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard in- put, one s.file per line (requires -y, and in some cases, -m). delta may issue prompts on the standard output depending upon the options specified and the flags that are set in the s.file (see sccs-admin(l), and the -m and -y options below, for details). OPTIONS -n Retain the edited g-file, which is normally removed at the completion of processing. -p Display line-by-line differences (in diff(l) format) on the standard output. -s Silent. Do not display warning or confirmation messages. Do not suppress error messages (which are written to standard error). -g sid-list Specify a list of deltas to omit when the file is accessed at the SCCS version ID (SID) created by this delta, sid-list is a comma-separated list of SIDs. To specify a range of deltas, use a separa- tor instead of a comma, between two SIDs in the list. -m f mr-list ] If the SCCS file has the v flag set (see sccs-admin(l)), you must supply one or more Modification Request (MR) numbers for the new delta. When specifying more than one MR number on the command line, mr-list takes the form of a quoted, space-separated list. If -m is not used and the standard input is a terminal, delta prompts with MRs? for the list (before issuing the comments? prompt). If the v flag in the s.file has a value, it is taken to be the name of a program to validate the MR numbers. If that validation program returns a non-zero exit status, delta terminates without checking in the changes. -r sid When two or more versions are checked out, specify the version to check in. This SID value can be either the SID specified on the get command line, or the SID of the new version to be checked in as reported by get. A diagnostic results if the specified SID is ambiguous, or if one is required but not supplied. -y [comment] Supply a comment for the delta table (version log). A null comment is accepted, and produces an empty commentary in the log. If -y is not specified and the standard input is a terminal, delta prompts with ‘comments?’. An unescaped NEWLINE terminates the comment. FILES dfile temporary file of differences pfile lock file for a checked-out version qfile temporary file s.file SCCS history file x.file temporary copy of the s.file zfile temporary file 466 Last change: 19 December 1989 Sun Release 4.1 SCCS-DELTA ( 1 ) USER COMMANDS SCCS-DELTA (1 ) WARNINGS Lines beginning with an ASCII SOH 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 produces an error. SEE ALSO sccs(l), sccs-admin(l), sccs-cdc(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), sccs-sccsdiff(l), sccs-unget(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). Sun Release 4.1 Last change: 19 December 1989 467 SCCS-GET ( 1 ) USER COMMANDS SCCS-GET ( 1 ) NAME sccs-get, get - retrieve a version of an SCCS file SYNOPSIS /usr/sccs/get [ -begkmnpst ] [ -1 [ p ] ] [ -a sequence ] [ -cdate-time ] [ -G g-file ] [ -isid-list ] [ -r sid ] [ -xsid-list ] s. filename . . . DESCRIPTION get retrieves a working copy from the SCCS history file, according to the specified options. For each s. filename argument, get displays the SCCS delta ID (SID) and number of lines retrieved. If a directory name is used in place of the sfilename argument, the get command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the sfilename argument indicates that the names of files are to be read from the standard input, one s.file per line. The retrieved file normally has the same filename base as the s.file, less the prefix, and is referred to as the g-file. For each file processed, get responds (on the standard output) with the SID being accessed, and with the number of lines retrieved from the s.file. OPTIONS -b Create a new branch. Used with the -e option to indicate that the new delta should have an SID in a new branch. Instead of incrementing the level for version to be checked in, get indicates in the p.file that the delta to be checked in should either initialize a new branch and sequence (if there is no existing branch at the current level), or increment the branch component of the SID. If the b flag is not set in the s.file, this option is ignored. -e Retrieve a version for editing. With this option, get places a lock on the s.file, so that no one else can check in changes to the version you have checked out. If the j flag is set in the s.file, the lock is advisory: get issues a warning message. Concurrent use of ‘get — e’ for different SIDs is al- lowed, however, get will not check out a version of the file if a writable version is present in the directory. All SCCS file protections stored in the s.file, including the release ceiling, floor, and au- thorized user list, are honored by ‘get -e\ -g Get the SCCS version ID, without retrieving the version itself. Used to verify the existence of a particular SID. -k Suppress expansion of ID keywords, -k is implied by the -e. -m Precede each retrieved line with the SID of the delta in which it was added to the file. The SID is separated from the line with a TAB. -n Precede each line with the %M% ID keyword and a TAB. When both the -m and -n options are used, the ID keyword precedes the SID, and the line of text. -p Write the text of the retrieved version to the standard output. All messages that normally go to the standard output are written to the standard error instead. -s Suppress all output normally written on the standard output. However, fatal error messages (which always go to the standard error) remain unaffected. -t Retrieve the most recently created (top) delta in a given release (for example: -rl). -1 [ p ] Retrieve a summary of the delta table (version log) and write it to a listing file, with the i.’ prefix (called ‘I.file’). When -lp is used, write the summary onto the standard output. -a sequence Retrieve the version corresponding to the indicated delta sequence number. This option is used primarily by the SCCS comb command (see sccs-comb(l)); for users, -r is an easier way to speci- fy a version, -a supercedes -r when both are used. 468 Last change: 28 June 1988 Sun Release 4.1 SCCS -GET ( 1 ) USER COMMANDS SCCS-GET ( 1 ) -c date-time Retrieve the latest version checked in prior to the date and time indicated by the date-time argu- ment date-time takes the form: yy[mm[dd[hh[mm[ss] ] ] ] ]. Units omitted from the indicated date and time default to their maximum possible values; that is -c7502 is equivalent to -c750228235959. Any number of non-numeric characters may separate the various 2 digit com- ponents. If white-space characters occur, the date-time specification must be quoted. -G newname Use newname as the name of the retrieved version. -isid-list Specify a list of deltas to include in the retrieved version. The included deltas are noted in the standard output message, sid-list is a comma-separated list of SIDs. To specify a range of deltas, use a separator instead of a comma, between two SIDs in the list. -rsid Retrieve the version corresponding to the indicated SID (delta). The SID for a given delta is a number, in Dewey decimal format, composed of two or four fields: the release and level fields, and for branch deltas, the branch and sequence fields. For instance, if 1.2 is the SID, 1 is the release, and 2 is the level number. If 1.2.3.4 is the SID, 3 is the branch and 4 is the sequence number. You need not specify the entire SID to retrieve a version with get. When you omit -r altogether, or when you omit both release and level, get normally retrieves the highest release and level. If the d flag is set to an SID in the s.file and you omit the SID, get retrieves the default version indi- cated by that flag. When you specify a release but omit the level, get retrieves the highest level in that release. If that release does not exist, get retrieves highest level from the next-highest existing release. Similarly with branches, if you specify a release, level and branch, get retrieves the highest se- quence in that branch. -\sid-list Exclude the indicated deltas from the retrieved version. The excluded deltas are noted in the stan- dard output message, sid-list is a comma-separated list of SIDs. To specify a range of deltas, use a separator instead of a comma, between two SIDs in the list. USAGE ID Keywords In the absence of -e or -k, get expands the following ID keywords by replacing them with the indicated values in the text of the retrieved source. Keyword Value %A% Shorthand notation for an ID line with data for what(l): %Z%%Y% %M% %I%%Z% %B% SID branch component %C% Current line number. 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. %D% Current date: yylmmldd %E% Date newest applied delta was created: yylmmldd %F% SCCS s.file name % G % Date newest applied delta was created: mmldd/yy %H% Current date: mmldd/yy %\% SID of the retrieved version: %R%.%L%.%B%.%S% %L% SID level component %M% Module name: either the value of the m flag in the s.file (see sccs-admin(l)), or the name of the s.file less the prefix %P% Fully qualified s.file name Sun Release 4.1 Last change: 28 June 1988 469 SCCS-GET ( 1 ) SCCS-GET ( 1 ) USER COMMANDS %Q% Value of the q flag in the s.file % R % SID Release component % S % SID Sequence component %' T % Current time: hh : mm : ss % U % Time the newest applied delta was created: hh :mm :ss %W% Shorthand notation for an ID line with data for what: %Z% %M% %\% %\% Module type: value of the t flag in the s.file %Z% 4-character string: ‘@(#)\ recognized by what. FILES “g-file” P -file z.file SEE ALSO sccs(l), sccs-admin(l), sccs-delta(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-sact(l), sccs-unget(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). BUGS If the effective user has write permission (either explicitly or implicitly) in the directory containing the SCCS files, but the real user does not, only one file may be named when using -e. version retrieved by get file containing extracted delta table info permissions (lock) file temporary copy of s.file 470 Last change: 28 June 1988 Sun Release 4.1 SCCS-HELP(l) USER COMMANDS SCCS-HELP(l) NAME sccs-help, help - ask for help regarding SCCS error or warning messages SYNOPSIS /usr/sccs/help [ argument ] . . . DESCRIPTION help retrieves information to further explain errors messages and warnings from SCCS commands. It also provides some information about SCCS command usage. If no arguments are given, help prompts for one. An argument may be a message number (which normally appears in parentheses following each SCCS er- ror or warning message), or an SCCS command name, help responds with an explanation of the message or a usage line for the command. When all else fails, try ‘/usr/sccs/help stuck’. FILES /usr/lib/help directory containing files of message text. /usr/sccs/help SEE ALSO sccs(l), sccs-admin(l), sccs-cdc(l), sccs-comb(l), sccs-delta(l), sccs-get(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), sccs-sact(l), sccs-sccsdiff(l), sccs-unget(l), sccs-val(l), what(l), sccsfile(5) Sun Release 4.1 Last change: 28 June 1988 471 SCCS-PRS ( 1 ) USER COMMANDS SCCS-PRS ( 1 ) NAME sccs-prs, prs — display selected portions of an SCCS history SYNOPSIS /usr/sccs/prs [ -ael ] [ — c date-time ] [ -d dataspec ] [ — r sid ] s.filename . . . DESCRIPTION prs displays part or all of the SCCS file (see sccsfile(5)) in a user supplied format. If a directory name is used in place of the s.filename argument, the prs command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard input, one s.file per line. OPTIONS In the absence of options, prs displays the delta table (version log). In the absence of — d, or —1, prs displays the entry for each delta indicated by the other options. -a Include all deltas, including those marked as removed (see sccs-rmdel(l)). -e Request information for all deltas created earlier than, and including, the delta indicated with -r or-c. -1 Request information for all deltas created later than, and including, the delta indicated with -r or -c. — c date-time Display information on the latest delta checked in prior to the date and time indicated by the date- time argument, date-time takes the form: yy[mm[dd[hh[mm[ss ] ] ] ] ] Units omitted from the indicated date and time default to their maximum possible values; that is -c7502 is equivalent to -c750228235959. Any number of non-numeric characters may separate the various 2 digit components. If white-space characters occur, the date-time specification must be quoted. -ddataspec Produce a report according to the indicated data specification, dataspec consists of a (quoted) text string that includes embedded data keywords of the form: ‘:key:’ (see Data Keywords, below), prs expands these keywords in the output it produces. To specify a TAB character in the output, use \t; to specify a NEWLINE in the output, use \n. -r sid Specify the SCCS delta ID (SID) of the delta for which information is desired. If no SID is specified, the most recently created delta is used. USAGE Data Keywords Data keywords specify which parts of an SCCS file are to be retrieved. All parts of an SCCS file (see sccsfile(5)) have an associated data keyword. A data keyword may appear any number of times in a data specification argument to -d. These data keywords are listed in the table below: Keyword Data Item File Section Value Format :A: a format for the what string: N/A :Z::Y: :M: :I::Z: S :B: branch number D nnnn S :BD: body B text M :BF: branch flag F yes or no S :CB: ceiling boundary F :R: S :C: comments for delta D text M :D: date delta created D :Dy:/:Dm:/:Dd: S :Dd: day delta created D nn S 472 Last change: 29 June 1988 Sun Release 4.1 SCCS-PRS ( 1 ) USER COMMANDS SCCS-PRS ( 1 ) :Dg: deltas ignored (seq #) D :DS: :DS: ... s :DI: seq-no. of deltas included, excluded, ignored D :Dn:/:Dx:/:Dg: S DL: delta line statistics D :Li:/:Ld:/:Lu: S Dm: month delta created D nn s Dn: deltas included (seq #) D :DS: :DS: ... s DP: predecessor delta seq-no. D nnnn s Ds: default SID F :I: s DS: delta sequence number D nnnn s Dt: delta information D :DT: :I: :D: :T: :P: :DS: :DP: s DT: delta type D D or R s Dx: deltas excluded (seq #) D :DS: ... s Dy: year delta created D nn s F: s.file name N/A text s FB: floor boundary F :R: s FD: file descriptive text C text M FL: flag list F text M GB: gotten body B text M I: SCCS delta ID (SID) D S J: joint edit flag F yes or no S KF: keyword error/waming flag F yes or no s L: level number D nnnn s Ld: lines deleted by delta D nnnnn s Li: lines inserted by delta D nnnnn s LK: locked releases F :R: ... s Lu: lines unchanged by delta D nnnnn s M: module name F text s MF: MR validation flag F yes or no s MP: MR validation program F text s MR: MR numbers for delta D text M ND: null delta flag F yes or no S Q: user defined keyword F text s P: user who created delta D username s PN: s.file’s pathname N/A text s R: release number D nnnn s S: sequence number D nnnn s T: time delta created D :Th:::Tm:::Ts: s Th: hour delta created D nn s Tm: minutes delta created D nn s Ts: seconds delta created D nn s UN: user names U text M W: a form of what string N/A :Z::M:\t:I: S Y: module type flag F text s Z: what string delimiter N/A @m s *B = body, D = delta table, F = flags, U = user names **S = simple format, M = multi-line format Sun Release 4. 1 Last change: 29 June 1988 473 SCCS-PRS ( 1 ) USER COMMANDS SCCS-PRS ( 1 ) EXAMPLES The command: /usr/sccs/prs — e — d" :I:\t:P:" program.c produces: 1.6 username 1.5 username FILES /tmp/pr????? temporary file SEE ALSO sccs(l), sccs-cdc(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prt(l), sccs-sact(l), sccs-sccsdiff(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). 474 Last change: 29 June 1988 Sun Release 4.1 SCCS-PRT ( 1 ) USER COMMANDS SCCS-PRT ( 1 ) NAME sccs-prt, prt - display delta table information from an SCCS file SYNOPSIS /usr/sccs/prt [-abdefistu] [ -c date-time ] [ -r date-time ] [ -y sid] s. filename . . . DESCRIPTION prt prints selected portions of an SCCS file. By default, it prints the delta table (version log). If a directory name is used in place of the s.filename argument, the prt command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard input, one s.file per line. OPTIONS If any option other than -y, -c, or -r is supplied, the name of each file being processed (preceded by one NEWLINE and followed by two NEWLINE characters) appears above its contents. If none of the -u, -f, -t, or -b options are used, -d is assumed, -s, -i are mutually exclusive, as are -c and -r. -a Display log entries for all deltas, including those marked as removed. -b Print the body of the s.file. -d Print delta table entries. This is the default. -e Everything. This option implies -d, -i, -u, -f, and -t. -f Print the flags of each named s.file. -i Print the serial numbers of included, excluded, and ignored deltas. -s Print only the first line of the delta table entries; that is, only up to the statistics. -t Print the descriptive text contained in the s.file. -u Print the user-names and/or numerical group IDs of users allowed to make deltas. -c date-time Exclude delta table entries that are specified cutoff date and time. Each entry is printed as a single line, preceded by the name of the SCCS file. This format (also produced by -r , and -y) makes it easy to sort multiple delta tables in chronological order. When both -y and -c, or -y and -r are supplied, prt stops printing when the first of the two conditions is met. -rdate-time Exclude delta table entries that are newer than the specified cutoff date and time. -y sid Exclude delta table entries made prior to the SID specified. If no delta in the table has the specified SID, the entire table is printed. If no SID is specified, the most recent delta is printed. USAGE Output Format The following format is used to print those portions of the s.file that are specified by the various options. • NEWLINE ® Type of delta (D or R) • SPACE • SCCS delta ID (SID) • TAB • Date and time of creation in the form: yylmmldd hhlmmlss Sun Release 4.1 Last change: 30 June 1988 475 SCCS-PRT ( 1 ) USER COMMANDS SCCS-PRT ( 1 ) • SPACE © Username the delta’s creator ® TAB © Serial number of the delta © SPACE e Predecessor delta’s serial number e TAB • Line-by-line change statistics in the form: inserted! deletedlunchanged o NEWLINE • List of included deltas, followed by a NEWLINE (only if there were any such deltas and the -i options was used) • List of excluded deltas, followed by a NEWLINE (only if there were any such deltas and the -i options was used) ® List of ignored deltas, followed by a NEWLINE (only if there were any such deltas and the -i options was used) • List of modification requests (MR s), followed by a NEWLINE (only if any MR numbers were supplied). ® Lines of the delta commentary (if any), followed by a NEWLINE. EXAMPLES The command: /usr/sccs/prt -y program.c produces a one-line display of the delta table entry for the most recent version: s.program.c: D 1.6 88/07/06 21:39:39 username 5 4 00159/00080/00636 . . . SEE ALSO sccs(l), sccs-cdc(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-sact(l), sccs-sccsdiff(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). 476 Last change: 30 June 1988 Sun Release 4.1 SCCS-RMDEL ( 1 ) USER COMMANDS SCCS-RMDEL ( 1 ) NAME sccs-rmdel, rmdel - remove a delta from an SCCS file SYNOPSIS /usr/sccs/rmdel -r sid s.filename . . . DESCRIPTION rmdel removes the delta specified by the SCCS delta ID (SID) supplied with -r. The delta to be removed must be the most recent (leaf) delta in its branch. In addition, the SID must not be that of a version checked out for editing: it must not appear in any entry of the version lock file (p.file). If you created the delta, or, if you own the file and directory and have write permission, you can remove it with rmdel. If a directory name is used in place of the s.filename argument, the rmdel command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard in- put, one s.file per line. FILES s file history file zfile temporary copy of the s.file P file permissions file SEE ALSO sccs(l), sccs-admin(l), sccs-cdc(l), sccs-comb(l), sccs-delta(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-sccsdiff(l), sccs-unget(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (sccs-help(l)). Sun Release 4.1 Last change: 30 June 1988 477 SCCS-S ACT ( 1 ) USER COMMANDS SCCS-SACT ( 1 ) NAME sccs-sact, sact - show editing activity status of an SCCS file SYNOPSIS /usr/sccs/sact s.filename . . . DESCRIPTION sact informs the user of any SCCS files that are checked out for editing. The output for each named file consists of five fields separated by SPACE characters. • SID of a delta that currently exists in the SCCS file, to which changes will be made to make the new delta • SID for the new delta to be created • Username of the person who has the file checked out for editing. • Date that the version was checked out. • Time that the version was checked out. If a directory name is used in place of the s.filename argument, the sact command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of as the s.filename argument indicates that the names of files are to be read from the standard in- put, one s.file per line. SEE ALSO sccs(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-prt(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (see sccs-help(l)). BUGS sact is not recognized as a subcommand of sccs(l). 478 Last change: 30 June 1988 Sun Release 4.1 SCCS-SCCSDIFF ( 1 ) USER COMMANDS SCCS-SCCSDIFF ( 1 ) NAME sccs-sccsdiff, sccsdiff - compare two versions of an SCCS file SYNOPSIS /usr/sccs/sccsdiff [ -p ] -r sid -r sid [ diff-options ] s.filename DESCRIPTION sccsdiff compares two versions of an SCCS file and displays the differences between the two versions. Any number of SCCS files may be specified; the options specified apply to all named s.files. OPTIONS -p Pipe output for each file through pr(l V). -r sid Specify a version corresponding to the indicated SCCS delta ID (SID) for comparison. Versions are passed to diff(l) in the order given. diff-options Pass options to diff(l), including: -c, -e, -f, -h, -b and -D. FILES /tmp/get????? temporary files SEE ALSO diff(l), sccs(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-prt(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS filename : No differences If the two versions are the same. Use the SCCS help command for explanations of other messages (see sccs-help(l)). Sun Release 4.1 Last change: 30 June 1988 479 SCCS-UNGET ( 1 ) USER COMMANDS SCCS-UNGET ( 1 ) NAME sccs-unget, unget - undo a previous get of an SCCS file SYNOPSIS /usr/sccs/unget [ -ns ] [ -r sid ] s.filename . . . DESCRIPTION unget undoes the effect of a ‘get -e’ done prior to the creation of the pending delta. If a directory name is used in place of the s.filename argument, the unget command applies to all s.files in that directory. Unreadable s.files produce an error; processing continues with the next file (if any). The use of ’ as the s.filename argument indicates that the names of files are to be read from the standard in- put, one s.file per line. OPTIONS -n Retain the retrieved version, which is otherwise removed. -s Suppress display of the SCCS delta ID (SID). -rsid When multiple versions are checked out, specify which pending delta to abort. A diagnostic results if the specified SID is ambiguous, or if it is necessary but omitted from the command line. SEE ALSO sccs(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), sccs-sact(l), sccs-sccsdiff(l), what(l), sccsfile(5) DIAGNOSTICS Use the SCCS help command for explanations (see sccs-help(l)). 480 Last change: 30 June 1988 Sun Release 4.1 SCCS-VAL(l) USER COMMANDS SCCS-VAL(l) NAME sccs-val, val - validate an SCCS file SYNOPSIS /usr/sccs/val - /usr/sccs/val [ -s ] [ -m name ] [ -r sid ] [ -y type ] s.filename . . . DESCRIPTION val determines if the specified s.files files meet the characteristics specified by the indicated arguments, val can process up to 50 files on a single command line. val has a special argument, which reads the standard input until the end-of-file condition is detected. Each line read is independently processed as if it were a command line argument list. val generates diagnostic messages on the standard output for each command line and file processed and also returns a single 8-bit code upon exit as described below. The 8-bit code returned by val is a disjunction of the possible errors, that is, it can be interpreted as a bit string where (moving from left to right) the bits set are interpreted as follows: bit 0 = missing file argument bit 1 = unknown or duplicate option bit 2 = corrupted s.file bit 3 - can not open file or file not in s.file format bit 4 = the SCCS delta ID (SID) is invalid or ambiguous bit 5 = the SID does not exist bit 6 = mismatch between % Y % and -y argument bit 7 = mismatch between %M% -m argument val can process two or more files on a given command line, and in turn can process multiple command lines (when reading the standard input). In these cases, an aggregate code is returned which is the logical OR of the codes generated for each command line and file processed. OPTIONS -s Silent. Suppress the normal error or warning messages. -mname Compare name with the %M% ID keyword in the s.file. -r sid Check to see if the indicated SID is ambiguous, invalid, or absent from the s.file. -y type Compare type with the % Y% ID keyword. SEE ALSO sccs(l), sccs-admin(l), sccs-delta(l), sccs-get(l), sccs-help(l), what(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (see sccs-help(l)). Sun Release 4.1 Last change: 30 June 1988 481 SCREENBLANK ( 1 ) USER COMMANDS SCREENBLANK ( 1 ) NAME screenblank - turn off the screen when the mouse and keyboard are idle SYNOPSIS screenblank [ -m ] [ — k ] [ — d interval ] [ -e interval ] [ -f frame-buffer ] DESCRIPTION screenblank turns off the display when the mouse and keyboard are idle for an extended period (the de- fault is 10 minutes), screenblank will continue to run until killed by hand, using ‘kill processid’ . Place the screenblank command in your /etc/rc.local file. OPTIONS -m Do not check whether the mouse has been idle. -k Do not check whether the keyboard has been idle. -d interval Disable after interval seconds, interval is a number of the form xxxjcxx where each x is a decimal digit. The default is 600 seconds (10 minutes). -e interval Enable within interval seconds, interval is the time between successive polls for keyboard or mouse activity. If a poll detects keyboard or mouse activity, the display is resumed, interval is a number of seconds, of the form xxxjcxx where each x is a decimal digit. The default is 0.25 seconds. -f frame-buffer frame-bujfer is the path name of the frame-buffer on which video disabling/enabling applies. The defaults is /dev/fb. FILES /dev/fb SEE ALSO lockscreen(l), sunview(l) BUGS screenblank only checks /dev/console for activity; it does not check non-window programs from /dev/tty which bypass /dev/console . Consequently, screenblank will turn off the display if /dev/tty programs (for example, pixrect-based programs) are the only ones running. When not running sunview(l), only the RETURN key resumes video display. 482 Last change: 9 September 1987 Sun Release 4.1 SCREENDUMP ( 1 ) USER COMMANDS SCREENDUMP ( 1 ) NAME screendump - dump a frame-buffer image to a file SYNOPSIS screendump [ -cCeo ] [ -f frame-buffer ] [ -t type ] [ -xyXY value ] [filename ] DESCRIPTION screendump reads the contents of a frame buffer and writes the display image to filename (the default is the standard output ) in Sun standard rasterfile format. If the frame buffer has both an overlay plane and color planes, screendump examines the overlay enable plane and tries to make the output file represent what is visible on the screen. It maps the overlay plane foreground and background colors into the closest values present in the color map for the color planes. OPTIONS -c -C -e -o -f frame-buffer -t type -x value -y value -X value -Y value EXAMPLES The command: example % screendump save.this.image writes the current contents of the console frame buffer into the file save.this.image, while the command: example % screendump -f /dev/cgtwo save.color .image writes the current contents of the color frame buffer /dev/cgtwo into the file save.color .image. The command: example% screendump | lpr -Pversatec -v sends a rasterfile containing the current frame-buffer to the lineprinter, selecting the printer versatec and the v output filter (see /etc/printcap). The printer must support an appropriate imaging model such as PostScript in order to print the image. FILES /usr/Iib/rasfilters/* filters for non-standard rasterfile formats /dev/fb default frame buffer device /etc/printcap Dump the frame-buffer contents directly without making a temporary copy in a memory pixrect. Saves time and memory but lengthens the time the frame-buffer must be inac- tive to guarantee a consistent screen dump. Dump the frame-buffer color planes only (ignored if the display does not have color planes). Set the output rasterfile type to 2, RT_BYTE_ENCODED. For most images this saves a significant amount of space compared to the standard format. Dump the frame-buffer overlay plane only (ignored if the display does not have an over- lay plane). Dump the specified frame-buffer device (default is /dev/fb). Set the output rasterfile type (default 1 , RT_STANDARD). Set the x or y coordinate of the upper left comer of the area to be dumped to the given value. Set the width or height of the area to be dumped to the given value. Sun Release 4.1 Last change: 8 September 1988 483 SCREENDUMP ( 1 ) USER COMMANDS SCREENDUMP ( 1 ) SEE ALSO lpr(l), rasfilter8tol(l), rastrepl(l), screenload(l) Pixrect Reference Manual BUGS The output file or the screen may be corrupted if the frame-buffer contents are modified while the dump is in progress. 484 Last change: 8 September 1988 Sun Release 4.1 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD ( 1 ) NAME screenload - load a frame-buffer image from a file SYNOPSIS screenload [ -bgnw ] [ -dopr ] [ -f frame-buffer ] [ -h count data . . . ] [ -i color ] [ -xyXY value ] [filename ] DESCRIPTION screenload reads a Sun standard rasterfile (see rasterfile(5)) and displays it on a frame-buffer, screenload is able to display monochrome images on a color display, but cannot display color images on a mono- chrome display. If the input file contains a color image, a frame-buffer has not been explicitly specified, and /dev/fb is a monochrome frame-buffer, screenload looks for a color frame-buffer with one of the stan- dard device names. If the image contained in the input file is larger than the actual resolution of the display, screenload clips the right and bottom edges of the image. If the input image is smaller than the display (for example, load- ing an 1152-by-900 image on a 1600-by-1280 high resolution display), screenload centers the image on the display surface and fills the border area with solid black (by default). Various options may be used to change the image location, or to change or disable the fill pattern. OPTIONS -b Fill the border area 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 Fill the border area with a pattern of “desktop grey”. On a monochrome display this results in a border matching the default background pattern used by SunView; on a color display the color map value selected by the -i option determines the foreground border color, though the pattern is the same as on a monochrome display. -n Do not fill the border area. -w Fill the border area 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 bord- er color. -d Print a warning message if the display size does not match the rasterfile image size. -o Load the image on the overlay plane of the display (ignored if the display does not have an overlay plane). -p Wait for a NEWLINE to be typed on the standard input before exiting. -r Reverse the foreground and background of the output image. Useful when loading a screendump made from a reverse video screen. -f frame-buffer Display the image on the specified frame-buffer device (default /dev/fb). -h count data . . . Fill the border area with the bit pattern described by the following count 16-bit hexade- cimal constants. Note: a “1” bit is black and a “0” bit is white on the monochrome display; on a color display 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. -i color Fill the border area with the given color value (default 255). -x value -y value Set the x or y coordinate of the upper left comer of the image on the display to the given value. Sun Release 4.1 Last change: 23 November 1987 485 SCREENLOAD ( 1 ) USER COMMANDS SCREENLOAD ( 1 ) -X value -Y value Set the maximum width or height of the displayed image to the given value. EXAMPLES The command: example% screenload saved.display.image loads the raster image contained in the file saved.display.image on the display type indicated by the rasterfile header in that file. The command: example % screenload -f /dev/cgtwo monochrome. image reloads the raster image in the file monochrome.image on the color frame-buffer device /dev/cgtwo. The command: example% screenload -hi ffff small. saved. image is equivalent to the -b option (fill border with black), while example % screenload -h4 8888 8888 2222 2222 small.saved.image is equivalent to the -g option (fill border with desktop grey). FILES /usr/lib/rasfilters/* filters for non-standard rasterfile formats /dev/fb default frame buffer device SEE ALSO rasfiIter8tol(l), rastrepl(l), screendump(l), screenload(l) Pixrect Reference Manual 486 Last change: 23 November 1987 Sun Release 4.1 SCRIPT ( 1 ) USER COMMANDS SCRIPT(l) NAME script - make typescript of a terminal session SYNOPSIS script [ -a ] [ filename ] DESCRIPTION script makes a typescript of everything printed on your terminal. The typescript is written to filename, or appended to filename if the -a option is given. It can be sent to the line printer later with Ipr(l). If no file name is given, the typescript is saved in the file typescript. The script ends when the forked shell exits. OPTIONS -a Append the script to the specified file instead of writing over it. SEE ALSO lpr(l) BUGS script places everything in the log file. This is not what the naive user expects. Sun Release 4.1 Last change: 9 September 1987 487 SDIFF(IV) USER COMMANDS SDIFF(IV) NAME sdiff - contrast two text files by displaying them side-by-side SYNOPSIS sdiff [ -1 ] [ -o outfile ] [ -s ] [ -w n ] filenamel filename2 AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION sdiff uses the output of diff-b to produce a side-by-side listing of two files indicating those lines that are different. Each line of the two files is printed with a blank gutter between them if the lines are identical, a < in the gutter if the line only exists in filenamel , a > in the gutter if the line only exists in filename2 , and a | for lines that are different. See EXAMPLES. OPTIONS -w n Use n as the width of the output line. The default line length is 130 characters. -1 Only print the left side of any identical lines. -s Silent. Do not print identical lines. -o outfile Use the next argument, output, as the name of an output file created as an interactively controlled merging of filenamel and filename2. Identical lines of filenamel and filename2 are copied to out- put. Sets of differences, as produced by diff, are printed; where a set of differences share a com- mon gutter character. After printing each set of differences, sdiff prompts with a % and waits for you to type one of the following commands: 1 Append the left column to the output file. r Append the right column to the output file. s Turn on silent mode; do not print identical lines. v Turn off silent mode. e 1 Call the ed(l) with the left column. e r Call ed(l) with the right column. e b Call ed(l) with the concatenation of left and right columns, e Call ed(l) with a zero length file. On exit from ed(l), the resulting file is concatenated to the named output file, q Exit from the program. EXAMPLES A sample output of sdiff would look like this: * I y a a b < c < d d > c 488 Last change: 17 September 1989 Sun Release 4.1 SDIFF(IV) USER COMMANDS SDIFF(IV) SEE ALSO diff(l), ed(l) Sun Release 4. 1 Last change: 17 September 1989 489 SED(IV) USER COMMANDS SED(IV) NAME sed- stream editor SYNOPSIS sed [ -n ] [ -e script ] [ -f sfilename ] [ filename ]. . . SYSTEM V SYNOPSIS /usr/5bin/sed [ -n ] [ -e script ] [ -f sfilename ] [filename ]. . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION sed copies the filenames (standard input default) to the standard output, edited according to a script of com- mands. OPTIONS -n Suppress the default output. -e script script is an edit command for sed. If there is just one -e option and no -f options, the -e flag may be omitted. -f sfilename Take the script from sfilename. USAGE sed Scripts sed scripts consist of editing commands, one per line, of the following form: [ address [, address ] ] function [ arguments ] In normal operation sed cyclically copies a line of input into a pattern space (unless there is something left after a D command), sequentially applies all commands with addresses matching that pattern space until reaching the end of the script, copies the pattern space to the standard output (except under -n), and finally, deletes the pattern space. Some commands use a hold space to save all or part of the pattern space for subsequent retrieval. An address is either: a decimal number linecount, which is cumulative across input files; a $, which addresses the last input line; or a context address, which is a / regular expression! in the style of ed(l); with the following exceptions: \?RE? In a context address, the construction \ ?regular expression?, where ? is any character, is identical to / regular expression!. Note: in the context address \xabc\xdefx, the second x stands for itself, so that the regular expression is abcxdef. \n Matches a NEWLINE embedded in the pattern space. . Matches any character except the NEWLINE ending the pattern space. null A command line with no address selects every pattern space. address Selects each pattern space that matches. 490 Last change: 3 February 1989 Sun Release 4.1 SED(IV) USER COMMANDS SED(IV) addressl ,address2 Selects the inclusive range from the first pattern space matching addrressl to the first pat- tern space matching address2 . Selects only one line if addressl is greater than or equal to address2 . Comments If the first nonwhite character in a line is a '#’ (pound sign), sed treats that line as a comment, and ignores it. If, however, the first such line is of the form: #n sed runs as if the -n flag were specified. Functions The maximum number of permissible addresses for each function is indicated in parentheses in the list below. 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 SPACE and TAB characters against the stripping that is done on every script line. An argument denoted rfilename or wfilename must terminate the command line and must be preceded by exactly one SPACE. Each wfilename is created before processing begins. There can be at most 10 distinct wfilename 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 emp- ty. (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 cy- cle. (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) I List the pattern space on the standard output in an unambiguous form. Non-printing charac- ters are spelled in two digit ASCII and long lines are folded. (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. Sun Release 4.1 Last change: 3 February 1989 491 SED(IV) USER COMMANDS SED(IV) (2) P Copy the initial segment of the pattern space through the first NEWLINE to the standard out- put. (1) q Quit: branch to the end of the script. Do not start a new cycle. (2) r rfilename Read the contents of rfilename . Place them on the output before reading the next input line. (2) s/regular expression/replacement/flags Substitute the replacement string for instances of the regular expression in the pattern space. Any character may be used instead of 7\ For a fuller description see ed(l). flags is zero or more of: n n= 1-512. Substitute for just the nth occurrence of the regu/ar expression . 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 wfilename Write: append the pattern space to wfilename 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 wfilename Write: append the pattern space to wfilename. (2) x Exchange the contents of the pattern and hold spaces. (2) ylstringllstring2l Transform: replace all occurrences of characters in stringl with the corresponding character in string2 . The lengths of stringl and string2 must be equal. (2)! function Do not: apply the function (or group, if function is *{’ ) only to lines not selected by the address(es). (0) : label This command does nothing; it bears a label for b and t commands to branch to. Note: 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. Commands are separated by (0) An empty command is ignored. System V sed Scripts Initial SPACE and TAB characters are not stripped from text lines. DIAGNOSTICS Too many commands The command list contained more than 200 commands. Too much command text The command list was too big for sed to handle. Text in the a, c, and i commands, text read in by r commands, addresses, regular expressions and replacement strings in s commands, and transla- tion tables in y commands all require sed to store data internally. Command line too long A command line was longer than 4000 characters. 492 Last change: 3 February 1989 Sun Release 4.1 SED(IV) USER COMMANDS SED(IV) Too many line numbers More than 256 decimal number linecounts were specified as addresses in the command list. Too many files in w commands More than 10 different files were specified in w commands or w options for s commands in the command list. Too many labels More than 50 labels were specified in the command list. Unrecognized command A command was not one of the ones recognized by sed. Extra text at end of command A command had extra text after the end. Illegal line number An address was neither a decimal number linecount, a $, nor a context address. Space missing before filename There was no space between a r or w command, or the w option for a s command, and the filename specified for that command. Too many {’s There were more { than } in the list of commands to be executed. Too many }’s There were more } than { in the list of commands to be executed. No addresses allowed A command that takes no addresses had an address specified. Only one address allowed A command that takes one address had two addresses specified. “\digit” out of range The number in a \n item in a regular expression or a replacement string in a s command was greater than 9. Bad number One of the endpoints in a range item in a regular expression (that is, an item of the form {«} or {n,m}) was not a number. Range endpoint too large One of the endpoints in a range item in a regular expression was greater than 255. More than 2 numbers given in \{ \} More than two endpoints were given in a range expression. } expected after \ A \ appeared in a range expression and was not followed by a }. First number exceeds second in \{ \} The first endpoint in a range expression was greater than the second. Illegal or missing delimiter The delimiter at the end of a regular expression was absent. \( \) imbalance There were more \( than \), or more \) than \(, in a regular expression. Sun Release 4.1 Last change: 3 February 1989 493 SED(IV) USER COMMANDS SED(IV) [ ] imbalance There were more [ than ], or more ] than [, in a regular expression. First RE may not be null The first regular expression in an address or in a s command was null (empty). Ending delimiter missing on substitution The ending delimiter in a s command was absent. Ending delimiter missing on string The ending delimiter in a y command was absent. Transform strings not the same size The two strings in a y command were not the same size. Suffix too large - 512 max The suffix in a s command, specifying which occurrence of the regular expression should be re- placed, was greater than 512. Label too long A label in a command was longer than 8 characters. Duplicate labels The same label was specified by more than one : command. File name too long The filename specified in a r or w command, or in the w option for a s command, was longer than 1024 characters. Output line too long. An output line was longer than 4000 characters long. Too many appends or reads after line n More than 20 a or r commands were to be executed for line n. Hold space overflowed. More than 4000 characters were to be stored in the hold space. SEE ALSO awk(l), ed(l), grep(lV), lex(l) Editing Text Files BUGS There is a combined limit of 200 -e and -f arguments. In addition, there are various internal size limits which, in rare cases, may overflow. To overcome these limitations, either combine or break out scripts, or use a pipeline of sed commands. 494 Last change: 3 February 1989 Sun Release 4.1 SELECTION_SVC ( 1 ) USER COMMANDS SELECTION_SVC ( 1 ) NAME selection_svc — SunView selection service SYNOPSIS selection_svc [ -d ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION The SunView selection service handles the state and rank of various selections for its client programs. A selection service is started automatically by sunview(l). However, you can also start one explicitly using the selection_svc command. OPTIONS -d Debug a client program. Use the alternate socket provided for testing and debugging a client pro- gram. The second selection service invoked with the -d handles a different set of selections, and can co-exist with one started in the normal fashion. Each service responds only to requests direct- ed to its own socket. The client to be debugged can be directed to use the “debugging” service by using the seln_use_test_service() procedure, as described in the SunView System Programmer' s Guide. SEE ALSO sunview(l) SunView User’s Guide SunView System Programmer’ s Guide Sun Release 4. 1 Last change: 21 December 1987 495 SET_ALARM ( 1 ) USER COMMANDS SET_ ALARM ( 1 ) NAME set_alarm, get_alarm, ring_alarm - SunView programmable alarms SYNOPSIS set_a!arm [ — b number ] [ -f number ] [ -d duration ] get_alarm ring_alarm AVAILABILITY This command is available with the SunView User’s software installation option. Refer to Installing SunOS 4.1 for more information on how to install optional software. DESCRIPTION set_alarm sets the WINDOW_ALARM environment variable according to the options specified. get_alarm returns the setting of WINDOW_ALARM in the form: WINDOW_ALARM=sedmg ring_alarm performs the actual beeping and flashing of the alarm. Note: the occurrence of the alarm is controlled by the SunView/Visible_Bell and Sun View/ Audible_Bell settings in defaultsedit(l). If either of these is disabled, the respective feature of the alarm will not occur, regardless of how it is specified by WINDOWALARM. In the C shell, set_alarm echoes the following command to set the WINDOW_ALARM environment vari- able: set noglob ;setenv WINDOW ALARM setting', unset noglob; In the Bourne shell, set_alarm echos the following: export WINDOW_ALARM;WINDOW_ALARM=,reth/ig ; Consequently, set_alarm is should be used as follows: eval ‘set_alarm [optionsY OPTIONS -b number Specify the number of beeps. The default is 1. -f number Specify the number of flashes. The default is 1. -d duration Specify the duration of the beep in milliseconds. The default is 1000. ENVIRONMENT The SunView programmable alarms use the WIND O W_A L ARM environment variable to define the charac- teristics of the alarm. The variable is set with a string argument of the following form: :beeps=/?:flashes=/:dur=f: SEE ALSO csh(l), defaultsedit(l), sh(l) SunView User' s Guide DIAGNOSTICS get_alarm: the WINDOW ALARM environment variable is NULL. This message is self-explanatory. ringalarm: WINDOW ALARM is NULL; using default values. set_alarm was not used to set values for the WINDOW_ALARM environment variable. See OPTIONS for default values. ring alarm: WINDOW ME not found Attempted to ring the alarm when SunView is not running. 496 Last change: 30 September 1989 Sun Release 4.1 SET_ALARM ( 1 ) USER COMMANDS SET_ALARM ( 1 ) BUGS and LIMITATIONS The user must be running SunView in order to ring the alarm; consequently, the alarms cannot be used with Open Windows. Sun Release 4. 1 Last change: 30 September 1989 497 SH( 1) USER COMMANDS SH( 1 ) NAME sh - shell, the standard UNIX system command interpreter and command-level language SYNOPSIS sh [ -acefhiknstuvx ] [ arguments ] DESCRIPTION sh, the Bourne shell, is the standard UNIX-system command interpreter. It executes commands read from a terminal or a file. Definitions A blank is a TAB or a SPACE character. A name is a sequence of letters, digits, or underscores beginning with a letter or underscore. A parameter is a name, a digit, or any of the characters *, @, $, and ! . Invocation If the shell is invoked through execve(2V), exec(), see execl(3V), and the first character of argument zero is commands are initially read from /etc/profile and from $HOME/.profile, if such files exist. Thereafter, commands are read as described below, which is also the case when the shell is invoked as sh. OPTIONS The options below are interpreted by the shell on invocation only; unless the -c or -s option is specified, the first argument is assumed to be the name of a file containing commands, and the remaining arguments are passed as positional parameters for use with the commands that file contains. -i If the -i option is present or if the shell input and output are attached to a terminal, this shell is interactive. In this case TERMINATE is ignored (so that ‘kill O’ does not kill an interactive shell) and INTERRUPT is caught and ignored (so that wait is interruptible). In all cases, QUIT is ignored by the shell. -s If the -s option is present or if no arguments remain commands are read from the stan- dard input. Any remaining arguments specify the positional parameters. Shell output (except for Special Commands) is written to file descriptor 2. -c string If the -c option is present commands are read from string. The remaining options and arguments are described under the set command, under Special Commands, below. USAGE Refer to SunOS User’s Guide: Doing More for more information about using the shell as a programming language. Commands A simple command is a sequence of nonblank words separated by blanks. The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as argu- ments to the invoked command. The command name is passed as argument 0 (see execve(2V)). The value of a simple command is its exit status if it terminates normally, or (octal) 200 +status if it terminates abnor- mally (see sigvec(2) for a list of status values). A pipeline is a sequence of one or more commands separated by T (or, for historical compatibility, by ‘ ’). The standard output of each command but the last is connected by a pipe (see pipe(2V)) to the standard input of the next command. Each command is run as a separate process; the shell normally waits for the last command to terminate before prompting for or accepting the next input line. The exit status of a pipe- line is the exit status of its last command. 498 Last change: 2 October 1989 Sun Release 4.1 SH(1) USER COMMANDS SH ( 1 ) A list is a sequence of one or more simple commands or pipelines, separated by V, or ‘| |\ and optionally terminated by or “&’. Of these four symbols, and have equal precedence, which is lower than that of *&&’ and ‘| |\ The symbols ‘&&’ and ‘| |’ also have equal precedence. A semicolon (;) sequentially executes the preceding pipeline; an ampersand (&) asynchronously executes the preceding pipeline (the shell does not wait for that pipeline to finish). The symbols && and 1 1 are used to indicate conditional execution of the list that follows. With && , list is executed only if the preceding pipeline (or command) returns a zero exit status. With 1 1, list is executed only if the preceding pipeline (or command) returns a nonzero exit status. An arbitrary number of NEWLINE characters may appear in a list, instead of semicolons, to delimit commands. A command is either a simple command or one of the following constructions. Unless otherwise stated, the value returned by a command is that of the last simple command executed in the construction. for name [ in word ... ] do list done Each time a for command is executed, name is set to the next word taken from the in word list. If in word ... is omitted, then the for command executes the do list once for each positional param- eter that is set (see Parameter Substitution below). Execution ends when there are no more words in the list. case word in [pattern [ | pattern ]...) list ;; ] ... esac A case command executes the list associated with the first pattern that matches word. The form of the patterns is the same as that used for filename generation (see Filename Generation) except that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly. if list then list [ elif list then list ] . . . [ else list ] fi The list following if is executed and, if it returns a zero exit status, the list following the first then is executed. Otherwise, the list following elif is executed and, if its value is zero, the list follow- ing the next then is executed. Failing that, the else list is executed. If no else list or then list is executed, then the if command returns a zero exit status. while list do list done A while command repeatedly executes the while list and, if the exit status of the last command in the list is zero, executes the do list', otherwise the loop terminates. If no commands in the do list are executed, then the while command returns a zero exit status; until may be used in place of while to negate the loop termination test. ( list ) Execute list in a subshell. { list;} list is simply executed. name () {list;} Define a function which is referenced by name. The body of the function is the list of commands between { and }. Execution of functions is described below (see Execution). The following words are only recognized as the first word of a command and when not quoted: if then else elif fi case esac for while until do done { } Comments A word beginning with # and all the following characters up to a NEWLINE are ignored. Command Substitution The shell reads commands from the string between two grave accents (“) and the standard output from these commands may be used as all or part of a word. Trailing NEWLINE characters from the standard out- put are removed. No interpretation is done on the string before the string is read, except to remove backslashes (\) used to escape other characters. Backslashes may be used to escape a grave accent (‘) or another backslash (\) and are removed before the command string is read. Escaping grave accents allows nested command sub- stitution. If the command substitution lies within a pair of double quotes (" ...‘ ... "), a backslash used to escape a double quote (\") will be removed; otherwise, it will be left intact. Sun Release 4.1 Last change: 2 October 1989 499 SH( 1) USER COMMANDS SH(1) If a backslash is used to escape a NEWLINE character (\NEWLINE), both the backslash and the NEWLINE are removed (see Quoting, later). In addition, backslashes used to escape dollar signs (\$) are removed. Since no interpretation is done on the command string before it is read, inserting a backslash to escape a dollar sign has no effect. Backslashes that precede characters other than \, ‘, ", NEWLINE, and $ are left intact when the command string is read. Parameter Substitution The character $ is used to introduce substitutable parameters. There are two types of parameters, posi- tional and keyword. If parameter is a digit, it is a positional parameter. Positional parameters may be assigned values by set. Keyword parameters (also known as variables) may be assigned values by writing: name=value [ name=value ] ... Pattern-matching is not performed on value. There cannot be a function and a variable with the same name. %{parameter } The value, if any, of the parameter is substituted. The braces are required only when parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If param- eter is or all the positional parameters, starting with $1, are substituted (separated by SPACE characters). Parameter $0 is set from argument zero when the shell is invoked. If the colon (:) is omitted from the following expressions, the shell only checks whether parameter is set or not. %{parameter :-word } If parameter is set and is nonnull, substitute its value; otherwise substitute word. ${parameter:=word} If parameter is not set or is null set it to word ; the value of the parameter is substituted. Positional parameters may not be assigned to in this way. %{parameter ilword} If parameter is set and is nonnull, substitute its value; otherwise, print word and exit from the shell. If word is omitted, the message ‘parameter null or not set’ is printed. ^{parameter :+word} If parameter is set and is nonnull, substitute word ; otherwise substitute nothing. In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following example, pwd is executed only if d is not set or is null: echo ${d:-‘pwd‘} The following parameters are automatically set by the shell: # The number of positional parameters in decimal. - Hags supplied to the shell on invocation or by the set command. ? The decimal value returned by the last synchronously executed command. $ The process number of this shell. ! The process number of the last background command invoked. The following parameters are used by the shell: HOME The default argument (home directory) for the cd command. PATH The search path for commands (see Execution below). CDPATH The search path for the cd command. MAIL If this parameter is set to the name of a mail file and the MAILPATH parameter is not set, the shell informs the user of the arrival of mail in the specified file. 500 Last change: 2 October 1989 Sun Release 4.1 SH( 1) USER COMMANDS SH ( 1 ) MAILCHECK MAILPATH PS1 PS2 IFS SHELL This parameter specifies how often (in seconds) the shell will check for the arrival of mail in the files specified by the MAILPATH or MAIL parameters. The default value is 600 seconds (10 minutes). If set to 0, the shell will check before each primary prompt. A colon (:) separated list of filenames. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each filename can be followed by % and a message that will be printed when the modification time changes. The default message is ‘you have mail’. Primary prompt string, by default ‘$ ’. Secondary prompt string, by default ‘> Internal field separators, normally SPACE, TAB, and NEWLINE. When the shell is invoked, it scans the environment (see Environment below) for this name. The shell gives default values to PATH, PSl, PS2, MAILCHECK and IFS. HOME and MAIL are set by login(l). Blank Interpretation After parameter and command substitution, the results of substitution are scanned for internal field separa- tor characters (those found in IFS) and split into distinct arguments where such characters are found. Explicit null arguments ("" or ”) are retained. Implicit null arguments (those resulting from parameters that have no values) are removed. Input/Output A command’s input and output may be redirected using a special notation interpreted by the shell. The fol- lowing may appear anywhere in a simple command or may precede or follow a command and are not passed on to the invoked command. Note: parameter and command substitution occurs before word or digit is used. 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 to it (by first seek- ing to the EOF); otherwise, the file is created. < <[-}word After parameter and command substitution is done on word, the shell input is read up to the first line that literally matches the resulting word, or to an EOF. If, however, is appended to: • leading TAB characters are stripped from word before the shell input is read (but after parameter and command substitution is done on word), • leading TAB characters are stripped from the shell input as it is read and before each line is compared with word, and • shell input is read up to the first line that literally matches the resulting word, or to an EOF. If any character of word is quoted, (see Quoting, later), no additional processing is done to the shell input. If no characters of word are quoted: • parameter and command substitution occurs, • (escaped) \NEWLINE is ignored, and • ‘V must be used to quote the characters ‘V, “$’, and “’. Sun Release 4.1 Last change: 2 October 1989 501 SH( 1) USER COMMANDS SH( 1 ) The resulting document becomes the standard input. <&digit Use the file associated with file descriptor digit as standard input. Similarly for the standard out- put using >&digit. <&- The standard input is closed. Similarly for the standard output using If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that specified by the digit (instead of the default 0 or 1). For example: ... 2>&1 associates file descriptor 2 with the file currently associated with file descriptor 1. The order in which redirections are specified is significant. The shell evaluates redirections left-to-right. For example: ... 1>xxc2>&1 first associates file descriptor 1 with file xxx. It associates file descriptor 2 with the file associated with file descriptor 1 (namely, file xxx). If the order of redirections were reversed, file descriptor 2 would be associ- ated with the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xxx. Using the terminology introduced on the first page, under Commands, if a command is composed of several simple commands , redirection will be evaluated for the entire command before it is evaluated for each simple command. That is, the shell evaluates redirection for the entire list, then each pipeline within the list, then each command within each pipeline, then each list within each command. If a command is followed by & the default standard input for the command is the empty file /dev/null. Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. Filename Generation Before a command is executed, 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 alphabetically sorted filenames that match the pattern. If no filename is found that matches the pattern, the word is left unchanged. The character V at the start of a filename or immediately following a 7’, as well as the char- acter T itself, must be matched explicitly. * Matches any string, including the null string. ? Matches any single character. [ . . . ] Matches any one of the enclosed characters. A pair of characters separated by matches any character lexically between the pair, inclusive. If the first character follow- ing the opening [ is a ! any character not enclosed is matched. Quoting The following characters have a special meaning to the shell and cause termination of a word unless quoted: ;&()|*<> NEWLINE SPACE TAB A character may be quoted (made to stand for itself) by preceding it with a backslash (\) or inserting it between a pair of quote marks (” or ""). During processing, the shell may quote certain characters to prevent them from taking on a special meaning. Backslashes used to quote a single character are removed from the word before the command is executed. The pair \NEWLINE is removed from a word before com- mand and parameter substitution. 502 Last change: 2 October 1989 Sun Release 4.1 SH(1) USER COMMANDS SH( 1 ) All characters enclosed between a pair of single quote marks (”), except a single quote, are quoted by the shell. Backslash has no special meaning inside a pair of single quotes. A single quote may be quoted inside a pair of double quote marks (for example, Inside a pair of double quote marks parameter and command substitution occurs and the shell quotes the results to avoid blank interpretation and file name generation. If $* is within a pair of double quotes, the positional parameters are substituted and quoted, separated by quoted spaces ("$1 $2 . . ."); however, if $@ is within a pair of double quotes, the positional parameters are substituted and quoted, separated by unquoted spaces ("$1" "$2" . . . ). \ quotes the characters \, ‘, ", and $. The pair \NEWLINE is removed before parameter and command substitution. If a backslash precedes characters other than \, *, ", $, and NEWLINE, then the backslash itself is quoted by the shell. Prompting When used interactively, the shell prompts with the value of PSl before reading a command. If at any time a RETURN is typed and further input is needed to complete a command, the secondary prompt (the value of PS2) is issued. Environment The environment (see environ(5V)) is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list. The shell interacts with the environment in several ways. On invocation, the shell scans the environment and creates a parameter for each name found, giving it the corresponding value. If the user modifies the value of any of these parameters or creates new parameters, none of these affects the environment unless the export command is used to bind the shell’s parameter to the environment (see also ‘set -a’). A parameter may be removed from the environment with the unset command. The environment seen by any executed command is thus composed of any unmodified name- value pairs originally inherited by the shell, minus any pairs removed by unset, plus any modifications or 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: TERM=450 cmd and (export TERM; TERM=450; cmd) are equivalent (as far as the execution of cmd is concerned). If the -k option is set, all keyword arguments are placed in the environment, even if they occur after the command name. The following first prints a=b c and c: echo a=b c set -k echo a=b c Signals The INTERRUPT and QUIT signals for an invoked command are ignored if the command is followed by &; otherwise signals have the values inherited by the shell from its parent (but see also the trap command below). INTERRUPT is handled asynchronously. Sun Release 4.1 Last change: 2 October 1989 503 SH ( 1 ) USER COMMANDS SH ( 1 ) Execution Each time a command is executed, the above substitutions are carried out. If the command name matches one of the Special Commands listed below, it is executed in the shell process. If the command name does not match a Special Command, but matches the name of a defined function, the function is executed in the shell process (note how this differs from the execution of shell procedures). The positional parameters $1, $2 are set to the arguments of the function. If the command name matches neither a Special Com- mand nor the name of a defined function, a new process is created and an attempt is made to execute the command using execve(2V). The shell parameter PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon (:). The default path is :/usr/ucb:/bin:/usr/bin (specifying /usr/ucb, /bin, and /usr/bin, in addition to the current directory). Directories are searched in order. The current directory is specified by a null path name, which can appear immediately after the equal sign (PATH=: . . . ), between the colon delimiters (...:: . . . ) anywhere else in the path list, or at the end of the path list ( ... :). 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 binary executable (see a.out(5) for details) or an executable script (with a first line beginning with #!) it is assumed to be a file containing shell commands, and a subshell is spawned to read it. A parenthesized command is also executed in a subshell. The location in the search path where a command was found is remembered by the shell (to help avoid unnecessary execs later). If the command was found in a relative directory, its location must be re- determined whenever the current directory changes. The shell forgets all remembered locations whenever the PATH variable is changed or the ‘hash -r’ command is executed (see below). Special Commands Input/output redirection is now permitted for these commands. File descriptor 1 is the default output loca- tion. : No effect; the command does nothing. A zero exit code is returned. . filename Read and execute commands from filename and return. The search path specified by PATH is used to find the directory containing filename . break [ n ] Exit from the enclosing for or while loop, if any. If n is specified break n levels. continue [ n ] Resume the next iteration of the enclosing for or while loop. If n is specified resume at the n ’th enclosing loop. cd[ arg ] Change the current directory to argument. The shell parameter HOME is the default argument. The shell parameter CD PATH defines the search path for the directory con- taining argument. Alternative directory names are separated by a colon (:). The default path is NULL (specifying the current directory). Note: the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If argument begins with a / the search path is not used. Otherwise, each directory in the path is searched for argument. echo [ argument ... ] Echo arguments. See echo(lV) for usage and description, eval [ argument ... ] The arguments are read as input to the shell and the resulting command(s) executed, exec [ argument . . . ] 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, modify the shell’s input/output. 504 Last change: 2 October 1989 Sun Release 4.1 SH ( 1 ) USER COMMANDS SH ( 1 ) exit [ n ] Exit a shell with the exit status specified by n. If n is omitted the exit status is that of the last command executed (an EOF will also cause the shell to exit.) export [ name . . . ] The given name s are marked for automatic export to the environment of subsequently- executed commands. If no arguments are given, variable names that have been marked for export during the current shell’s execution are listed. (Variable names exported from a parent shell are listed only if they have been exported again during the current shell’s execution.) Function names are not exported. getopts Use in shell scripts to parse positional parameters and check for legal options. See getopts(l) for usage and description. hash [ -r ] [ name . . . ] For each name, the location in the search path of the command specified by name is determined and remembered by the shell. The -r option causes the shell to forget all remembered locations. If no arguments are given, information about remembered com- mands is presented, hits is the number of times a command has been invoked by the shell process, cost is a measure of the work required to locate a command in the search path. If a command is found in a “relative” directory in the search path, after changing to that directory, the stored location of that command is recalculated. Commands for which this will be done are indicated by an asterisk (*) adjacent to the hits information. cost will be incremented when the recalculation is done. login [ argument ... ] Equivalent to ‘exec login argument ’ See login(l) for usage and description. newgrp [ argument ... ] Equivalent to ‘exec newgrp argument ’ See newgrp(l) for usage and description. pwd Print the current working directory. See pwd(l) for usage and description, read [ name ... ] One line is read from the standard input and, using the internal field separator, IFS (nor- mally a SPACE or TAB character), to delimit word boundaries, the first word is assigned to the first name, the second word to the second name, etc., with leftover words assigned to the last name . Lines can be continued using \NEWLINE. Characters other than NEW- LINE can be quoted by preceding them with a backslash. These backslashes are removed before words are assigned to names, and no interpretation is done on the char- acter that follows the backslash. The return code is 0 unless an EOF is encountered. readonly [ name ... ] The given names are marked readonly and the values of the these name s may not be changed by subsequent assignment. If no arguments are given, a list of all readonly names is printed. return [ n ] Exit a function with the return value specified by n. If n is omitted, the return status is that of the last command executed. Sun Release 4. 1 Last change: 2 October 1989 505 SH( 1) USER COMMANDS SH(1) set [ -aefhkntuvx- [ argument . . . ] ] —a Mark variables which are modified or created for export. -e Exit immediately if a command exits with a nonzero exit status. -f Disable filename generation. -h Locate and remember function commands as functions are defined (function commands are normally located when the function is executed). -k All keyword arguments are placed in the environment for a command, not just those that precede the command name. -n Read commands but do not execute them. — t Exit after reading and executing one command. -u Treat unset variables as an error when substituting. -v Print shell input lines as they are read. -x Print commands and their arguments as they are executed. — Do not change any of the options; useful in setting $1 to Using V rather than turns off these options. These options can also be used upon invocation of the shell. The current set of options may be found in ‘$-\ The remaining arguments are positional parameters and are assigned, in order, to $1, $2, and so on. If no arguments are given, the values of all names are printed. shift [ n ] The positional parameters are shifted to the left, from position n+1 to position 1, and so on. Previous values for $1 through $n are discarded. If n is not given, it is assumed to be 1. test Evaluate conditional expressions. See test(lV) for usage and description, times Print the accumulated user and system times for processes run from the shell, trap [arg][n]... The command arg is to be read and executed when the shell receives signal(s) n. (Note: arg is scanned once when the trap is set and once when the trap is taken.) Trap com- mands are executed in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the current shell is ineffective. If arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on exit from the shell. The trap command with no arguments prints a list of commands associated with each signal number. type [ name . . . ] For each name, indicate how it would be interpreted if used as a command name, umask [ ooo ] The user file-creation mode mask is set to ooo (see csh(l)). The three octal digits refer to read/write/execute permissions for owner, group, and others, respectively. The value of each specified digit is subtracted from the corresponding “digit” specified by the sys- tem for the creation of a file. For example, umask 022 removes group and others write permission (files normally created with mode 111 become mode 755; files created with mode 666 become mode 644). The current value of the mask is printed if ooo is omit- ted. 506 Last change: 2 October 1989 Sun Release 4.1 SH( 1) USER COMMANDS SH(1) unset [ name ... ] For each name, remove the corresponding variable or function. The variables PATH, PSl, PS2, MAILCHECK and IFS cannot be unset. wait [ n ] Wait for the background process whose process ID is n and report its termination status. If n is omitted, all the shell’s currently active background processes are waited for and the return code will be zero. EXIT STATUS Errors detected by the shell, such as syntax errors, return a nonzero exit status. If the shell is being used noninteractively execution of the shell file is abandoned. Otherwise, the shell returns the exit status of the last command executed (see also the exit command above). ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout all command line parsing. These variables are checked in the following order: LC CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid charac- ter classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /etc/profile $HOME/.profile /tmp/sh* /dev/null /usr/lib/rsh SEE ALSO cd(l), csh(l), echo(lV), env(l), getopts(l), login(l), newgrp(l), pwd(l), test(lV), wait(l), dup(2V), execve(2V), fork(2V), pipe(2V), sigvec(2), wait(2V), execI(3V), a.out(5), environ(5V), locale(5) SunOS User's Guide: Doing More WARNINGS Words used for filenames in input/output redirection are not interpreted for filename generation (see File Name Generation, above). For example, ‘cat filel > a*’ will create a file named ‘a*’. Because commands in pipelines are run as separate processes, variables set in a pipeline have no effect on the parent shell. If you get the error message ‘cannot fork, too many processes’, try using the wait(l) command to clean up your background processes. If this does not help, the system process table is probably full or you have too many active foreground processes. There is a limit to the number of process IDs associated with your login, and to the number the system can keep track of. Sun Release 4.1 Last change: 2 October 1989 507 SH( 1) USER COMMANDS SH(1) BUGS If a command is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to exec the original command. Use the hash command to correct this situation. If you move the current directory or one above it, pwd may not give the correct response. Use the cd com- mand with a full path name to correct this situation. Not all the processes of a 3- or more-stage pipeline are children of the shell, and thus cannot be waited for. For wait n, if n is not an active process ID, all the shell’s currently active background processes are waited for and the return code will be zero. 508 Last change: 2 October 1989 Sun Release 4.1 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) NAME shelltool - run a shell (or other program) in a SunView terminal window SYNOPSIS shelltool [ -C ] [ -B boldstyle ] [ -I command ] [ generic-tool-arguments ] [ program [ arguments ] ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION shelltool is a standard SunView facility for shells or other programs that may use a standard tty-based in- terface. When invoked, shelltool runs a program, (usually a shell) in an interactive terminal emulator based on a tty subwindow. Keyboard input is passed to that program. If the program is a shell, it accepts commands and runs programs in the usual way. cmdtool(l), which provides moused-based editing, logging, and scrolling capabilities, also supports shell- level programs. See SunView User's Guide for more information. To run graphics programs, use gfxtool(l). OPTIONS -C Redirect system console output to this shelltool. -B boldstyle Set the style for displaying bold text to boldstyle. boldstyle can be a string specifying one of the choices for the /Tty/Bo!d_style default, see Defaults Options, below, or it may be a numerical value for one of those choices, from 0 to 8, corresponding to the placement of the choice in the list. -I command Pass command to the shell. SPACE characters within the command must be escaped. generic-tool-arguments shelltool accepts the generic tool arguments listed in sunview(l). If a program argument is present, shelltool runs it. If no program is given, shelltool runs the program indi- cated by the SHELL environment variable, or /usr/bin/sh by default. USAGE Defaults Options These options are available through defaultsedit(l). /Tty/Bold_style Select a style for emphasized text: None OffsetX Offset_Y OffsetXandY Offset_XY Offset_X_and_XY OffsetYandXY Offset_X_and_Y_and Disable emphasis. Thicken characters horizontally. Thicken characters vertically. Thicken characters both horizontally and vertically. Thicken characters diagonally. Thicken character both horizontally and diagonally. Thicken characters both vertically and diagonally. XY Thicken characters horizontally, vertically and diagonally. Invert Display emphasis as inverse video (the standard default). /Tty/Inverse_mode Select a style for inverse video display: Sun Release 4.1 Last change: 26 May 1988 509 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) Enable Enable inverse mode for inverted text. Disable Disable inverse mode for inverted text. Same_as_bold Display inverted text as bold text. /Tty/Underline_mode Select a style for underlined text: Enable Enable underline mode for underlined text. Disable Disable underline mode for underlined text. Same_as_bold Display underlined text as bold text. /Tty/Retained When set to “Yes”, hidden tty subwindow areas are retained in memory. This enhances the speed of repainting the screen at the expense of memory area. “No” is the standard default; it specifies that tty subwindows are not retained. The Terminal Emulator The tty subwindow is a terminal emulator. Whenever a tty subwindow is created, the startup file "/.ttyswrc is read for initialization parameters that are specific to the tty subwindow. The .ttyswrc File A sample .ttyswrc file can be found in /usr/lib/ttyswrc. The command format for this file is: # Comment. set variable Turn on the specified variable. mapi key text When key is typed pretend text was input. mapo key text When key is typed pretend text was output. The only currently defined variable is pagemode, key is one of L1-L15, F1-F15, T1-T15, R1-R15, LEFT, or RIGHT (see note below), text may contain escapes such as \E, Vi, 'X, etc. (ESC, RETURN, and CTRL-X, respectively). See termcap(5) for the format of the string escapes that are recognized. Note: mapi and mapo may be replaced by another keymapping mechanism in the future. When using the default kernel keyboard tables, the keys LI, LEFT, RIGHT, BREAK, R8, RIO, R12, and R14 cannot be mapped in this way; they send special values to the tty subwindow. Also, when using the default kernel keyboard tables, L1-L10 are now used by SunView. See input_from_defaults(l) and kbd(4S) for more information on how to change the behavior of the keyboard. It is possible to have terminal-based programs drive the tool in which its tty subwindow resides by sending special escape sequences. These escape sequences may also be sent by typing a key appropriately mapped using the mapo function described above. The following functions pertain to the tool in which the tty subwindow resides, not the tty subwindow itself. \E[lt - open \E[2t - close (become iconic) \E[3t - move, with interactive feedback \E[3;TOP;LEFTt - move, to TOP LEFT (pixel coordinates) \E[4t - stretch, with interactive feedback \E[4;HT;WIDTHt - stretch, to HT WIDTH size (in pixels) \E[5t - front \E[6t -back \E[7t - refresh \E[8;ROWS;COLSt - stretch, to ROWS COLS size (in characters) \E[llt - report if open or iconic by sending \E[lt or \E[2t \E[13t - report position by sending \E[3;TOP;LEFTt 510 Last change: 26 May 1988 Sun Release 4.1 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) \E[14t - report size in pixels by sending \E[4;HT;WIDTHt \E[18t - report size in characters by sending \E[8;ROWS;COLSt \E[20t - report icon label by sending \E]Llabel\E\ \E[21t - report tool header by sending \E]llabel\E\ \E]ltext\E\ - set tool header to text \E]Ifile\E\ - set icon to the icon contained in file; file must be in iconedit output for- mat \E]Llabel\E\ - set icon label to label \E[>OPT; . . .h - turn SB OPT on (OPT = 1 => pagemode), for example, \E[>l;3;4h \E[>OPT; . . .k - report OPT; sends \E[>OPTl or \E[>OPTh for each OPT \E[>OPT; . . .1 - turn OPT off (OPT = 1 => pagemode), for example, \E[>1;3;41 See EXAMPLES for an example of using this facility. Selections Terminal subwindows support a selection facility that allows you to capture a block of text, move it between windows, and replicate it. You can make a selection by clicking the left button on the mouse at the top-left character of the block to capture, and then clicking the middle button on the bottom-right character. The selected text is highlighted. Multiple clicks of the LEFT mouse button capture: 1 click a character 2 clicks a word 3 clicks a line 4 clicks a screenful You can also make a selection by moving the mouse while holding the select button, and then releasing it. The selection is deselected if you type any key or new output is written to the window that holds the selec- tion. Menu To manipulate your selection, press the menu button over the terminal subwindow. A ttysw menu appears with the menu items discussed below: Copy, then Paste When there is a selection in any window, the entire item is active. Selecting it copies the selection both to the clipboard and to the insertion point (cursor). It copies selections in tty, text, command, and panel subwindows, and It is intended to bridge the gap between Stuff and the selection facility (see SunView User's Guide. When there is no selection but there is text on the clipboard, only Paste is active. In this case, the contents of the clipboard are copied to the insertion point (cursor). When there is no selection and nothing on the clipboard, this item is inactive. Enable Page Mode Disable Page Mode Toggle page mode on and off. Page mode prevents output from scrolling off the screen. It is an alternative to more(l). When page mode is on, the cursor changes to resemble a tiny stop-sign when ever a screenful of output is displayed. To res- tart output, type any key, or select the Continue menu item that temporarily re- places Enable Page Mode. Stuff is provided for backward compatibility. It copies the selection jto the insertion point (cursor) as though they had been typed from the keyboard. Stuff can only handle selections made in a tty subwindow. Sun Release 4.1 Last change: 26 May 1988 511 SHELLTOOL ( 1 ) USER COMMANDS SHELLTOOL ( 1 ) Flush Input Occasionally the input buffer fills up and the terminal emulator appears to freeze. If this happens, the ‘Flush Input’ appears in the menu; choosing it clears the buffer and allows you to continue. EXAMPLES The following aliases can be put into your “/.cshrc file: # dynamically set the name stripe of the tool: alias header ’echo -n "VE]1\!*\E\"’ # dynamically set the label on the icon: alias iheader ’echo -n "\E]L\!*\E\"’ # dynamically set the image on the icon: alias icon ’echo-n "\E]I\!*\EV” FILES "/•ttyswrc /usr/Iib/ttyswrc /usr/demo/* SEE ALSO cmdtool(l), defaultsedit(l), gfxtool(l), input_from_defaults(l), more(l), rlogin(lC), sunview(l), kbd(4S), termcap(5) SunView User’s Guide 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, an alert will come up with a message saying ‘Too many keystrokes in input buffer’. Choosing the Flush Input Buffer menu item may correct the problem. This is a bug for a terminal emulator subwindow running on top of or rlogin(lC) to a machine with pre-4.0 release kernel. 512 Last change: 26 May 1988 Sun Release 4.1 SIZE ( 1 ) USER COMMANDS SIZE ( 1 ) NAME size - display the size of an object file SYNOPSIS size [ object-file . . . ] Sun386i SYNOPSIS /usr/bin/size [— n] [— f] [- 0 ] [— x] [-\] filename . . . 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. Sun386i DESCRIPTION The Sun386i version of the System V compatibility package includes /usr/bin/size, which allows the Sys- tem V options to be used, and creates the same output as the System V size(l) command; it produces sec- tion size information in bytes for each loaded section in COFF files. The size of the text, data, and bss (uninitialized data) sections is printed, as well as the sum of the sizes of these sections. If an archive file is given, it displays the information for all archive members. Sun386i OPTIONS -n Includes NOLOAD sections in the size. -f Produces full output, that is, it prints the size of every loaded section, followed by the section name in parentheses. -o Print numbers in octal, instead of the default which is decimal. -x Print numbers in hexadecimal. -V Supply version information. Sun386i DIAGNOSTICS size: name: cannot open name cannot be read. size: name : bad magic name is not an appropriate common object file. Sun386i WARNINGS Since the size of bss sections is not known until link-edit time, this command does not give the true total size of pre-linked objects. SEE ALSO cc(lV), size(l), a.out(5), ar(5), coff(5) Sun Release 4.1 Last change: 18 February 1988 513 SLEEP ( 1 ) USER COMMANDS SLEEP ( 1 ) NAME sleep - suspend execution for a specified 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 sleep(3V) BUGS time must be less than 2,147,483,647 seconds. 514 Last change: 9 September 1987 Sun Release 4.1 SNAP ( 1 ) USER COMMANDS SNAP(l) NAME snap — SunView application for system and network administration SYNOPSIS snap AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION snap simplifies the execution of a variety of system administration tasks in the user-friendly environment of a SunView window, snap eases the following tasks: personal or centralized backup and restoration of files, management of users accounts and user groups, software installation, network administration, and management of devices such as printers, terminals, modems, and the peripheral box containing disk and tape drives. Anyone can use snap, but the operations allowed depend on the secondary group membership of the user at the time that snap is invoked. There are four secondary user groups specifically recognized by snap, membership in which bestows various powers over the corresponding area of system administration. These are: accounts users and user groups. devices printers, terminals, modems, and peripheral box. operator centralized backup and restoration of files, and installation of software. networks domains and systems, including the New User Accounts feature and Automatic System Instal- lation features. A user’s snap privileges depend upon which of these four groups he or she belongs to. If they get an ac- count through New User Accounts, or if an administrator adds them using the defaults, new users become members of the primary group users, and are given all snap privileges. This can be changed by changing the secondary group membership of the primary group users with snap. Note: this does not change the group membership of existing users, but only of new users. The secondary group membership of existing users must be changed individually. Accounts An administrator using snap can create new user accounts and remove existing ones, change a user’s snap privileges, and control users’ access to their accounts. New users can create their own accounts as they first login if the New User Accounts feature is activated as described under Networks below. Devices Epson and Epson-like printers (most printers using the Centronics parallel interface), text serial printers, and HP Laserjet and compatible printers can be administered with snap . The supported terminal types are vt-100 and wyse. The supported modem types are Hayes Smartmodem or a modem that is compatible with Hayes Smartmodem. For all other types of terminals, modems, or printers, the software must be configured manually. See System and Network Administration for details. snap can add or remove, display and change information about, or disable or enable either a printer, a ter- minal, a modem, or the peripheral box containing disk and tape drives. Devices not added using snap can not be manipulated with snap. Sun Release 4. 1 Last change: 19 February 1988 515 SNAP(l) USER COMMANDS SNAP ( 1 ) Operator Regardless of the primary or secondary group membership of users, they can backup and restore their own files with snap. Backup and removal of all files can be done by members of the operator group. Networks Much of the network setup must be done when the first machine in the network, the master server, is start- ed up, and when each client is connected and booted for the first time. Some of this information can never be changed. Once the master and slave servers are installed, snap can be used to add and assign diskless clients to servers, remove them, modify their network roles, and perform all the functions listed above under Ac- counts, Devices, and Operator on any system in the network. If desired, you can also enable or disable the feature that allows a user to create his own account while log- ging in (New User Accounts), and the automatic system installation feature, two possible security loo- pholes. SEE ALSO Sun386i System and Network Administration System and Network Administration 516 Last change: 19 February 1988 Sun Release 4.1 SOELIM ( 1 ) USER COMMANDS SOELIM ( 1 ) NAME soelim - resolve and eliminate .so requests from nroff or troff input SYNOPSIS soelim [filename . . . ] AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. DESCRIPTION soelim reads the specified files or the standard input and performs the textual inclusion implied by the nroff(l) directives of the form .so somefile when they appear at the beginning of input lines. This is useful since programs such as tbl(l) do not nor- mally do this; it allows the placement of individual tables in separate files to be run as a part of a large do- cument. An argument consisting of is taken to be a file name corresponding to the standard input. Note: inclusion can be suppressed by using ‘ ' ’ instead of ‘ that is, ' so /usr/share/lib/tmac/tmac.s EXAMPLE A sample usage of soelim would be soelim exum?.n | tbl | nroff SEE ALSO colcrt(l), more(l), nroff(l), tbl(l) Sun Release 4.1 Last change: 9 September 1987 517 SORT(IV) USER COMMANDS SORT(IV) NAME sort - sort and collate lines SYNOPSIS sort [ -bdf iMnr ] [ -tc ] [ sort-field . . . ] [ -emu ] [ -o[ ] output-file ] [ -T directory ] [ -y kmem ] [ -z recsz ] filename. . . SYSTEM V SYNOPSIS /usr/5bin/sort [ —bdf iMnr ] [ — tc ] [ sort-field . . . ] [ -emu ] [ -o[ ]output-file ] [ — T directory ] [ -y kmem ] [ -z recsz ] filename . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION The sort program sorts and collates lines contained in the named files, and writes the result onto the stan- dard output. If no filename argument is given, or if appears as an argument, sort accepts input from the standard input. Output lines are normally sorted on a character-by-character basis, from left to right within a line. The default collating sequence is the ASCII character set. Lines can also be sorted according to the contents of one or more fields specified by a sort-field, specification, using the +sw (starting-word), -ew (end-at-word), and the -tc (set-TAB-character/word delimiter) options, as described under OPTIONS below. When no word delimiter is specified, one or more adjacent white-space characters (SPACE and TAB) signify the end of the previous word; the lines: xyz xyz are collated as: xyz *“ xyz Each sort-field is evaluated in command-line order; later fields are applied to the sorting sequence only when all earlier fields compare equally. When all specified fields compare equally between two or more lines, that subset of lines is sorted on a character-by-character basis, from left to right. SYSTEM V DESCRIPTION When no fields are specified in the command line, the System V version of sort treats leading blanks as significant, even with the -n (numeric collating sequence) option; the lines: 123 23 are collated as: 23 123 OPTIONS Collating Flags -b Ignore leading SPACE characters when determining the starting and ending positions of a field. -d Dictionary order. Only letters, digits and the white-space characters SPACE and TAB are significant in comparisons. -f Fold in lower case. Treat upper- and lower-case letters equally in collating comparisons. -i Ignore characters outside the ASCII range 040-0176 in non-numeric comparisons. 518 Last change: 19 September 1989 Sun Release 4.1 SORT (IV) USER COMMANDS SORT (IV) -M Month order. The first three non-blank characters of the field are folded to upper case and col- lated according to the sequence: JAN FEB . . . DEC. Field values outside this range appear earlier than JAN. The -M option implies the -b option. -n Numeric collating sequence. An initial numeric string, consisting of optional blanks, optional minus signs, and zero or more digits with an optional decimal point, is sorted by arithmetic value. The -n option implies the -b option, but only when at least one sort-field is specified on the com- mand line. -r Reverse the current collating sequence. Field Specification Options -tc Use c as the word delimiter character; unlike white-space characters, adjacent delimiters indicate word breaks; if : is the delimiter character, :: delimits an empty word. sort-field This is a combination of options that specifies a field, within each line, to sort on. A sort-field specification can take either of the following forms: +sw[cf] +sw -ew[cf\ where sw is the number of the starting word (beginning with ‘0’) to include in the field, ew is the number of the word before which to end the field, and cf is a string containing collating flags (without a leading When included in a sort-field specification, these flags apply only to the field being specified, and when given, override other collating flags given in separate arguments (which otherwise apply to an entire line). If the -ew option is omitted, the field continues to the end of a line. You can apply a character offset to sw and ew to indicate that a field is to start or end a given number of characters within a word, using the notation: ‘w.c\ A starting position specified in the form: ‘+w.c’ indicates the character in position c (beginning with 0 for the first character), within word w (1 and 1.0 are equivalent). An ending position specified in the form: ‘-w.c’ indicates that the field ends at the character just prior to position c (beginning with 0 for the delimiter just prior to the first character), within word w. If the -b flag is in effect, c is counted from the first non-white-space or non-delimiter character in the field, otherwise, delimiter characters are counted. Other Options -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. -u Unique. Emit only the first line in each set of lines for which all sorting fields compare equally. -ooutput-file -o output-file Direct output to the file specified as output-file, instead of the standard output. This file may be the same as one of the input files. -y kmem The amount of main memory used by the sort has a large impact on its performance. Sorting a small file in a large amount of memory is a waste. If this option is omitted, sort begins using a system default memory size, and continues to add space as needed. If this option is given sort starts with kmem , kilobytes of memory, if allowed, or as close to that amount as possible. Supply- ing -yO guarantees that sort starts with a minimum of memory. By convention, -y (with no argu- ment) starts with maximum memory. Sun Release 4.1 Last change: 19 September 1989 519 SORT (IV) USER COMMANDS SORT (IV) — z recsz The size of the longest line read is recorded in the sort phase so that buffers can be allocated dur- ing the merge phase. If the sort phase is omitted because either of the -c or -m options is in effect, a default size of 1024 bytes is used. Lines longer than the buffer size terminate sort abnor- mally. Supplying the actual number of bytes in the longest line to be merged (or some larger value) avoids this. -T directory The directory argument is the name of a directory in which to place temporary files. EXAMPLES Sort the contents of input-file with word number 1 (the second word) as the sort key: sort +1-2 input-file Sort, in reverse order, the contents of input-filel and input-file2, placing the output in output-file and using the first character of the second field as the sort key: sort -r -o output-file +1.0 —1.1 input-filel input-file2 Sort, in reverse order, the contents of input-filel and input-file2 using the first non-blank character of the second field as the sort key: sort-r +1.0b -1.1b input-filel input-file2 Print the password file (passwd(5)) sorted by the numeric user ID (the third colon-separated field): sort -t: +2n -3 /etc/passwd Print the lines of the already sorted file input-file, suppressing all but the first occurrence of lines having the same third field (the options -mu with just one input file make the choice of a unique representative from a set of equal lines predictable): sort -mu +2 -3 input-file FILES /usr/tmp/stm??? SEE ALSO comm(l), join(l), rev(l), uniq(l) DIAGNOSTICS Comments and exits with non-zero status for various trouble conditions (such as when input lines are too long), and for disorders discovered under the -c option. When the last line of an input file is missing a NEWLINE, sort appends one, prints a warning message, and continues. 520 Last change: 19 September 1989 Sun Release 4.1 SORTBIB ( 1 ) USER COMMANDS SORTBIB ( 1 ) NAME sortbib - sort a bibliographic database SYNOPSIS sortbib [ -s KEYS ] database . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. 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 truncat- ed. 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. Au- thors with two-word last names or unusual constructions can be sorted correctly by using the nroff conven- tion ‘\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 modem European language. If a sort-significant field is absent from a record, sortbib places that record before other records containing that field. SEE ALSO addbib(l), indxbib(l), lookbib(l), refer(l), roffbib(l) refer in Formatting Documents BUGS Records with missing author fields should probably be sorted by title. Sun Release 4.1 Last change: 21 December 1987 521 SPELL ( 1 ) USER COMMANDS SPELL ( 1 ) NAME spell, hashmake, spellin, hashcheck - report spelling errors SYNOPSIS spell [ -blvx ] [ -d hlist ] [ -h spellhist ] [ -s hstop ] [ +local Jile \ [filename ] ... /usr/lib/spell/hashmake /usr/lib/spell/spellin n /usr/lib/spell/hashcheck spellingjist DESCRIPTION spell collects words from the named files, and looks them up in a hashed spelling list. Words that do not appear in the list, or cannot be derived from those that do appear by applying certain inflections, prefixes or suffixes, are displayed on the standard output. If there are no filename arguments, words to check are collected from the standard input, spell ignores most troff(l), tbl(l), and eqn(l) constructs. Copies of all output words are accumulated in the history file, and a stop list filters out misspellings (for example, their=thy-y+ier) that would otherwise pass. By default, spell (like deroff(l)) follows chains of included files (.so and .nx troff(l) requests), unless the names of such included files begin with /usr/lib. If a +local Jile argument is specified, words found in local Jile are removed from spell’s output, local Jle is the name of a user-provided file that contains a sorted list of words, one per line. With this option, the user can specify a set of words that are correct spellings (in addition to spell’s own spelling list) for each job. The standard spelling list is based on many sources, and while more haphazard than an ordinary dictionary, 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. Three programs help maintain and check the hash lists used by spell: hashmake Reads a list of words from the standard input and writes the corresponding nine-digit hash code on the standard output. spellin Reads n hash codes from the standard input and writes a compressed spelling list on the standard output. hashcheck Reads a compressed spellingjist and recreates the nine-digit hash codes for all the words in it; it writes these codes on the standard output. OPTIONS -b -1 Check British spelling. Besides preferring “centre”, “colour”, “programme”, “speciality”, “travelled”, and so on, this option insists upon -ise in words like standardize, despite what Fowler and the OED say. Follow the chains of all included files. -v — X -d hlist -h spellhist -s hstop Print all words not literally in the spelling list, as well as plausible derivations from spelling list words. Print every plausible stem with *=’ for each word. Use the file hlist as the hashed spelling list. Place misspelled words with a user/date stamp in file spellhist. Use hstop as the hashed stop list. 522 Last change: 8 June 1988 Sun Release 4.1 SPELL ( 1 ) USER COMMANDS SPELL ( 1 ) FILES /usr/lib/spell/hlist[ab] /usr/lib/spell/hstop /usr/Iib/spell/spellhist /usr/Iib/spell/spellprog hashed spelling lists, American & British hashed stop list history file program called by the /usr/bin/spell shell script SEE ALSO deroff(l), sed(lV), sort(lV), tee(l) BUGS The spelling list’s coverage is uneven; new installations may wish to monitor the output for several months to gather local additions. British spelling was done by an American. NOTES Misspelled words can be monitored by default by setting the H_SPELL variable in /usr/bin/spell to the name of a file that has permission mode 666. spell works only on English words defined in the US ASCII codeset. Sun Release 4.1 Last change: 8 June 1988 523 SPLINE (1G) USER COMMANDS SPLINE (1G) NAME spline - interpolate smooth curve SYNOPSIS spline [ -aknpx ] . . . 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 argu- ment, or is assumed to be 1 if next argument is not a number. -k The constant k used in the boundary value computation y'o = ky", y’n = ky'^iox 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 calculated from the data. Automatic abcissas start at lower limit (default 0). SEE ALSO graph(lG) R. W. Hamming, Numerical Methods for Scientists and Engineers, 2nd ed. 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. 524 Last change: 9 September 1987 Sun Release 4.1 SPLIT ( 1 ) USER COMMANDS SPLIT ( 1 ) NAME split — split a file into pieces SYNOPSIS split [ -number ] [ infile [ outfile ] ] DESCRIPTION split reads infile and writes it in number - line pieces (default 1000) onto a set of output files (as many files as necessary). The name of the first output file is outfile with aa appended, the second file is outfile ab, and so on lexicographically. If no outfile is given, x is used as default (output files will be called xaa, xab, 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. Sun Release 4.1 Last change: 9 September 1987 525 STRINGS ( 1 ) USER COMMANDS STRINGS ( 1 ) NAME strings — find printable strings in an object file or binary SYNOPSIS strings [ - ] [ -o ] [ -number ] filename . . . DESCRIPTION strings looks for ASCII strings in a binary file. A string is any sequence of 4 or more printing characters ending with a NEWLINE or a null character. 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. -number Use number as the minimum string length rather than 4. SEE ALSO od(lV) NOTES strings is not 8-bit clean because it makes too many mistakes when it is expected to look for strings con- taining non-ASCn characters. BUGS The algorithm for identifying strings is extremely primitive. 526 Last change: 9 September 1987 Sun Release 4.1 STRIP ( 1) USER COMMANDS STRIP ( 1 ) NAME strip - remove symbols and relocation bits from an object file SYNOPSIS strip filename... DESCRIPTION strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler and linker. 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 ld(l). SEE ALSO ld(l), a.out(5) BUGS Unstripped 2.0 binary files will not run if stripped by the 3.0 version. A message of the form: pid xxx : killed due to swap problems in I/O error mapping page, when attempting to run a program indicates that this is the problem. Sun Release 4.1 Last change: 7 September 1988 527 STTY(IV) USER COMMANDS STTY(IV) NAME stty - set or alter the options for a terminal SYNOPSIS stty [ -ag ] [ option ] . . . SYSTEM V SYNOPSIS /usr/5bin/stty [ -ag ] [ option ] . . . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION stty sets certain terminal I/O options for the device that is the current standard output. Without arguments, it reports the settings of certain terminal options for the device that is the standard output; the settings are reported on the standard error. Detailed information about the modes listed in the first live groups below may be found in termio(4). Op- tions in the last group are implemented using options in the previous groups. Note: many combinations of options make no sense, but no sanity checking is performed. SYSTEM V DESCRIPTION stty sets or reports terminal options for the device that is the current standard input; the settings are report- ed on the standard output. OPTIONS -a Report all of the option settings. -g Report current settings in a form that can be used as an argument to another stty command. Special Requests speed The terminal speed alone is printed on the standard output. size The terminal (window) sizes are printed on the standard output, first rows and then columns. size and speed always report on the settings of /dev/tty, and always report the settings to the standard output. Control Modes Hparenb Enable parity generation and detection. With a \ disable parity checking. Hparodd Select odd parity. With a select even parity. cs5 cs6 cs7 cs8 Select character size. 0 Hang up phone line immediately. 50 75 110 134 150 200 300 600 1200 1800 2400 4800 9600 19200 exta 38400 extb Set terminal baud rate to the number given, if possible. (Not all speeds are supported by all hardware interfaces.) [-]hupcl Hang up connection on last close. With a do not hang up connection. [-]hup Same as hupcl. [-]cstopb Use two stop bits per character. With a use one stop bit per character. [-]cread Enable the receiver. With a disable the receiver. Mclocal Assume a line without modem control. With a assume a line with modem control. 528 Last change: 2 October 1989 Sun Release 4.1 STTY(IV) USER COMMANDS STTY(IV) Input Modes Hignbrk [-Jbrkint Hignpar Hparmrk Hinpck [— ]istrip [ — ]inlcr Higncr [-]icrnl [-]iuclc [-]ixon [-]ixany [-Jdecctlq [-]ixoff [-Jtandem Himaxbel [-Jiexten Ignore break on input. With a do not ignore a break on input. Signal SIGINT on break. With a do not signal. Ignore parity errors. With a do not ignore parity errors. Mark parity errors With a do not mark parity errors. Enable input parity checking. With a disable input parity checking. Strip input characters to seven bits. With a do not strip input characters. Map NEWLINE to RETURN on input. With a do not map on input. Ignore RETURN on input. With a do not ignore RETURN on input. Map RETURN to NEWLINE on input. With a do not map. Map upper-case alphabetics to lower case on input. With a do not map. Enable START/STOP output control. With a disable output control. When enabled, output is stopped by sending a STOP character and started by sending a START character. Allow any character to restart output. With a ‘-\ only restart with a START character. Same as -ixany. Request that the system send START/STOP characters when the input queue is nearly empty/full. With a request that the system not send START/STOP characters. Same as ixoff. Request that the system send a BEL character to your terminal, and not to flush the input queue, if a character received when the input queue is full. With a request that it flush the input queue and not send a BEL character. Enable all SunOS special characters, such as word erase. With a enable only the POSIX subset of special characters (INTR, QUIT, ERASE, KILL, EOF, NL, EOL, SUSP, STOP, START, and CR). Output Modes [-]opost Post-process output. With a do not post-process output; ignore all other output modes. [-]olcuc Map lower-case alphabetics to upper case on output. With a do not map. Honlcr Map NEWLINE to RETURN-NEWLINE on output. With a do not map. Hocrnl Map RETURN to NEWLINE on output. With a do not map. Honocr Do not place RETURN characters at column zero. With a do place RETURN characters at column zero. [-Jonlret On the terminal NEWLINE performs the RETURN function. With a NEWLINE does not perform the RETURN function. Hofill Use fill characters for delays. With a use timing for delays. [— Jofdel Fill characters are DEL characters. With a *-*, fill characters are NUL characters. crO crl cr2 cr3 Select style of delay for RETURN characters. nlO nil Select style of delay for LINEFEED characters. Sun Release 4. 1 Last change: 2 October 1989 529 STTY(IV) USER COMMANDS STTY(IV) tabO tabl tab2 tab3 bsO bsl ffOffl vtO vtl Local Modes [— ]isig [-]icanon [-jcbreak Hxcase [-]echo [-]echoe Hcrterase t-]echok Ifkc [-]echonl [-jnoflsh [-jtostop [-]echoctl [-]ctIecho Hechoprt [-jprterase [-jechoke [— ]crtkiU Select style of delay for horizontal TAB characters. Select style of delay for BACKSPACE characters. Select style of delay for form FORMFEED characters. Select style of delay for vertical TAB characters. Enable the checking of characters against the special characters INTR and QUIT. With a disable this checking. Enable canonical input (ERASE, KILL, WERASE, and RPRNT processing). With a disable canonical input. Same as -icanon. Perform canonical upper/lower-case presentation. With a do not perform canonical upper/lower-case presentation. Echo back every character typed. With a do not echo back. Echo the ERASE character as a sequence of BACKSPACE-SPACE-BACKSPACE. With a echo the ERASE character as itself. Same as echoe. Echo NEWLINE after echoing a KILL character. With a do not echo NEWLINE after echoing a KILL character. Same as echok; obsolete. Echo NEWLINE, even if echo is not set. With a do not echo NEWLINE if echo is not set. Disable flush after INTR or QUIT. With a enable flush. Stop background jobs that attempt to write to the terminal. With a allow background jobs to write to the terminal. Echo control characters as x (and delete as *?’.) Print two BACKSPACE characters follow- ing the EOF character (default CTRL-D). With a echo control characters as themselves. Same as echoctl. Echo erased characters backwards within ‘V and 7’; used on printing terminals. With a echo erased characters as indicated by echoe. Same as echoprt. Echo the KILL character by erasing each character on the line as indicated by echoprt and echoe. With a echo the KILL character as indicated by echoctl and echok. Same as echoke. control-character c Set control-character to c, where control-character is one of erase, kill, intr, quit, eof, eol, eol2, start, stop, susp, rprnt, flush, werase, or Inext. If c is preceded by a caret Q, (es- caped from the shell) then the value used is the corresponding CTRL character (for instance, ‘*D’ is a CTRL-D); “?’ is interpreted as DEL and ’ is interpreted as undefined. min i Set the MIN value to i. 530 Last change: 2 October 1989 Sun Release 4.1 STTY(IV) USER COMMANDS STTY(IV) time/ Set the TIME value to/. rows n Set the recorded number of rows on the terminal to Z. columns / Set the recorded number of columns on the terminal to /. cols/ An alias for columns/. Combination Modes cooked Process the ERASE, WERASE, KILL, INTR, QUIT, EOF, EOL, EOL2, STOP, START, SUSP, RPRNT, FLUSH, and LNEXT characters specially, and perform output post- processing. evenp or parity Enable parenb, disable parodd, and set cs7. oddp Enable parenb and parodd, and set cs7. -evenp or -parity Disable parenb, and set cs8. -oddp Disable parenb and parodd, and set cs8. pass8 Disable parenb and istrip, and set cs8. -pass8 Enable parenb and istrip, and set cs7. litout Disable parenb, istrip, and opost, and set cs8. -Iitout Enable parenb, istrip, and opost, and set cs7. [-]raw Enable raw input and output. With a disable raw I/O. In raw mode, there is no special processing of the ERASE, WERASE, KILL, INTR, QUIT, EOF, EOL, EOL2, STOP, START, SUSP, RPRNT, FLUSH, nor LNEXT characters, nor is there any other input pre-processing nor output post-processing, brkint, istrip, imaxbel, and parenb are disabled, and cs8 is set. [— ]nl Unset icrnl, onlcr. With a set them. In addition -nl unsets inlcr, igncr, ocrnl, and onlret. [-]lcase Set xcase, iuclc, and olcuc. With a unset them. [-JLCASE Same as lease (-lease). [-]tabs tab3 Preserve TAB characters when printing. With a or with tab3, expand TAB characters to SPACE characters. ek Reset the ERASE and KILL characters back to normal: DEL and CTRL-U). sane Reset all modes to some reasonable values. ert Set options for a CRT (echoe, echoctl, and, if >= 1200 baud, echoke.) dec Set all modes suitable for Digital Equipment Corp. operating systems users (ERASE, KILL, and INTR characters to *?, “U, and "C, decctlq, and crt.) term Set all modes suitable for the terminal type term, where term is one of tty33, tty37, vt05, tn300, ti700, or tek. -ertsets Raise the RTS (Request to Send) modem control line. Suspends output until the CTS (Clear to Send) line is raised. Sun Release 4. 1 Last change: 2 October 1989 531 STTY(IV) USER COMMANDS STTY(IV) ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout stty. On entry to stty, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. SEE ALSO ioctI(2), termio(4), locale(5) 532 Last change: 2 October 1989 Sun Release 4.1 STTY_FROM_DEF AULTS ( 1 ) USER COMMANDS STTY_FROM_DEF AULTS ( 1 ) NAME stty_from_defaults - set terminal editing characters from the defaults database SYNOPSIS stty_from_defaults AVAILABILITY This command is available with the SunView User' s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION stty_from_defaults is a utility provided with the SunView environment. stty_from_defaults sets the three editing characters (to erase a character, erase a word, and kill a line) ac- cording to the choices in your defaults database. It does not set any other tty options. If you run stty(lV) in your .login or rc.local files, you may want to run stty_from_defaults immediately after it. This will override any settings of ■stry erase, sf/ywerase, or 57 ry kill, so that you will have the same character-editing behavior with SunView application programs. To specify the editing characters stty_from_defaults will set, run defaultsedit(l) and select the "Text" category. The editing characters are called Edit_back_char, Edit_back_word, and Edit_back_line. Type the value you want to the right of each item. To specify CTRL-X, type ‘X’ — that is, the three characters ‘V, ‘ A ’, and ‘X’. To specify DEL, type *?’. If you do not specify your own values, the default values are DEL, CTRL-W, and CTRL-U, respectively. SEE ALSO defaultsedit(l), stty(lV), sunview(l) SunView User’s Guide Sun Release 4.1 Last change: 21 December 1987 533 SU(1V) USER COMMANDS SU(1V) NAME su - super-user, temporarily switch to a new user ID SYNOPSIS su [ - ] [ -f ] [ username [ arg . . . ] ] SYSTEM V SYNOPSIS su [ - ] [ username [ arg . . . ] ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION su creates a new shell process that has the user ID for the specified username as its real and effective user ID. su asks for the password, just as if you were logging in as username, and, if the password is given, changes the real and effective user IDs and group IDs and group set to those of username and invokes the shell specified in the password file for that username , without changing the current directory. The user en- vironment is thus unchanged except for HOME and SHELL, which are taken from the password file for the user being substituted (see environ(5V)). If username is not root, USER is changed to username. The new user ID stays in force until the shell exits. The new shell will not be a login shell, so it will not read username' s .login or .profile files, but it will read any other configuration files for that user (for instance, the .cshrc file for the C shell) just as if that user had invoked a new shell. If no username is specified, root is assumed. If the wheel group (group 0) does not contain a null user list and has members, only they can su to root, even with the root password. To remind the super-user of his responsibilities, the shell substitutes *#’ for ’$’ or ’%’ in its usual prompt (except if you will be running sh(l) and PS1 is set - in this case, the prompt will not be modified). If args are given, they are passed to username ’s shell. Any additional arguments given on the command line are passed to the program invoked as the shell. When using programs like sh(l) and csh(l), an arg of the form -c string executes string via the shell. OPTIONS -f FILES .cshrc .login .profile SEE ALSO csh(l), login(l), sh(l), environ(5V) NOTES su does not accept 8-bit user IDs. See login(l) for explanations about why 8-bit login names are not accept- able. Perform a complete login. Remove all variables from the environment except for TERM, set USER to username, set HOME and SHELL as specified above, set PATH to :/usr/ucb:/bin:/usr/bin, change directories to username's home directory, and tell the shell to read username’s .login or .profile file. Perform a fast su by passing the -f flag to the shell. This flag is only meant for use with the C shell; it will prevent the C shell from reading username ’s .cshrc file. If it is used with the Bourne shell, it will disable filename generation. 534 Last change: 21 September 1989 Sun Release 4.1 SU(1V) USER COMMANDS SU(1V) BUGS su fails when run from within a subdirectory of a directory that username either cannot search, or cannot read (that is, username does not have both read and execute permission). su fails to reset the user ID to root when the current working directory is in an NFS-mounted file system, and does not have its search permission set for “other” users. Sun Release 4.1 Last change: 21 September 1989 535 SUM (IV) USER COMMANDS SUM(IV) NAME sum - calculate a checksum for a file SYNOPSIS sum filename SYSTEM V SYNOPSIS /usr/5bin/sum [-r ] filename AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. 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 transmis- sion line. The checksum is calculated by an algorithm which may yield different results on machines with 16-bit ints and machines with 32-bit ints, so it cannot always be used to validate that a file has been transferred between machines with different-sized ints. SYSTEM V DESCRIPTION sum calculates and prints a 16-bit checksum for the named file, and also prints the number of 512-byte blocks in the file. It is typically used to look for bad spots, or to validate a file communicated over some transmission line. This algorithm is independent of the size of ints on the machine. SYSTEM V OPTIONS The option -r causes the (machine-dependent) algorithm used by the non-System V sum to be used in computing the checksum. SEE ALSO wc(l) DIAGNOSTICS Read error is indistinguishable from EOF on most devices; check the block count. 536 Last change: 9 September 1987 Sun Release 4.1 SUNVffiW(l) USER COMMANDS SUNVffiW(l) NAME sunview - the SunView window environment SYNOPSIS sunview [ -i ] [ -p ] [ -B I -F I -P ] [ -S ] [ -8bit_color_onIy ] [ -over!ay_only ] [ -toggle_enab!e ] [ -b red green blue ] [ -d display-device ] [ -f red green blue ] [ -k keyboard-device ] [ -m mouse-device ] [ -n I -s startup-filename ] [ -background raster-filename ] [ -pattern on I off I gray I iconedit file name ] DESCRIPTION sunview starts up the SunView environment and (unless you have specified otherwise) a default layout of a few useful “tools,” or window-based applications. See Start-up Processing below to learn how to specify your own initial layout of tools. Some of the behavior of sunview is controlled by settings in your defaults database; see SunView Defaults below, and defaultsedit(l) for more information. To exit sunview use the Exit SunView menu item. In an emergency, type CTRL-D then CTRL-Q (there is no confirmation in this case). OPTIONS -i Invert the background and foreground colors used on the screen. On a monochrome monitor, this option provides a video reversed image. On a color monitor, colors that are not used as the background and foreground are not affected. -p Print to the standard output the name of the window device used for the sunview back- ground. -B Use the “background color” ( -b ) for the background. -F Use the “foreground color” ( -f ) for the background. -P Use a stipple pattern for the background. This option is assumed unless -F or -B is specified. -S Set Click-to-type mode, allowing you to select a window by clicking in it. Having done so, input is directed to that window regardless of the position of the pointer, until you click to select some other window. -8bit_color_onIy For multiple plane group frame buffers, only let windows be created in the 8 bit color plane group. This frees up the black and white overlay plane to have a separate desktop running on it. This option is usually used with the -toggle_enable option. See Multiple Desktops on the Same Screen, below. -overIay_only For multiple plane group frame buffers, only let windows be created in the black and white overlay plane group. This frees up the 8 bit color plane group to have a separate desktop running in it. This option is usually used with the -toggle_enable option. See Multiple Desktops on the Same Screen, below. -toggle_enable For multiple plane group frame buffers, when sliding the pointer between different desk- tops running within different plane groups on the same screen, change the enable plane to allow viewing of the destination desktop. See Multiple Desktops on the Same Screen, below. Sun Release 4.1 Last change: 1 June 1988 537 SUNVffiW(l) USER COMMANDS SUNVIEW ( 1 ) -b red green blue Specify values for the red , green and blue components of the background color. If this option is not specified, each component of the background color is 255 (white). Sun 3/110 system users that use this option should use the -8bit_color_only option as well. -d display -device Use display-device as the output device, rather than /dev/fb the default frame buffer device. -f red green blue Specify values for the red, green and blue components of the foreground color. If this option is not specified, each component of the foreground color is 0 (black). Sun 3/110 system users that use this option should use the -8bit_color_only option as well. — k keyboard-device Accept keyboard input from keyboard-device, rather than /dev/kbd, the default key- board device. -m mouse-device Use mouse-device as the system pointing device (locator), rather than /dev/mouse, the default mouse device. -n Bypass startup processing by ignoring the /usr/lib/.sunview and "/.sunview (and ‘/.sun- tools) files. -s startup-filename Read startup commands from startup-filename instead of /usr/lib/.sunview or "/.sun- view). -background raster-filename Use the indicated raster file as the image in your background. The raster file can be created with screendump(l). Screen dumps produced on color monitors currently do not work as input to this option. Small images are centered on the screen. -pattern on I off I gray I iconeditfilename Use the indicated “pattern” to cover the background, on means to use the default desk- top gray pattern, off means to not use the default desktop gray pattern, gray means to use a 50% gray color on color monitors, iconeditfilename is the name of a file produced with iconedit(l) which contains an image that is to be replicated over the background. USAGE Windows The SunView environment always has one window open, referred to as the background, which covers the whole screen. A solid color or pattern is its only content. Each application is given its own window which lies on top of some of the background (and possibly on top of other applications). A window obscures any part of another window which lies below it. Input to Windows Mouse input is always directed to the window that the pointer is in at the time. Keyboard input can follow mouse input or, it can remain within a designated window using the Click-to-Type default setting. If you are not using Click-to-Type, and the pointer is on the background, keyboard input is discarded. Input ac- tions (mouse motions, button clicks, and keystrokes) are synchronized, which means that you can “type- ahead” and “mouse-ahead,” even across windows. Mouse Buttons LEFT mouse button Click to select or choose objects. MIDDLE mouse button In text, click once to shorten or lengthen your selection. In graphic applications or on the desktop, press and hold to move objects. 538 Last change: 1 June 1988 Sun Release 4.1 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) RIGHT mouse button Press and hold down to invoke menus. Menus sunview provides pop-up menus. There are two styles of pop-up menus: an early style, called “stacking menus,” and a newer style, called “walking menus” (also known as “pull-right menus”). In the current release, walking menus are the default; stacking menus are still available as a defaults option. Usually, a menu is invoked by pressing and holding the RIGHT mouse button. The menu remains on the screen as long as you hold the RIGHT mouse button down. To choose a menu item, move the pointer onto it (it is then highlighted), then release the RIGHT mouse button. Another available option is “stay-up menus.” A stay-up menu is invoked by pressing and releasing the RIGHT mouse button. The menu appears on the screen after you release the RIGHT mouse button. To choose a menu item, move the pointer onto it (it is then highlighted), then press and release the RIGHT mouse button a second time. Stay-up menus are an option in your defaults database; see SunView De- faults below. With walking menus, any menu item can have an arrow pointing (=>) to the right. Moving the pointer onto this arrow pops up a “sub-menu,” with additional items. Choosing the item with an arrow (the “pull-right item”) invokes the first item on the sub-menu. The SunView Menu You can use the default SunView menu to start SunView applications and perform some useful functions. To invoke it, hold down the RIGHT mouse button when the pointer is anywhere in the background. The default SunView menu is defined in the file /usr/lib/.rootmenu. It consists of four sub-menus, labeled Shells, Editors, Tools, and Services, along with an Exit SunView item. These sub-menus contain the fol- lowing items: Shells Command Tool Bring up a cmdtool(l), a scrollable window-based terminal emulator that supports a shell. Shell Tool Bring up a shelltool(l), an tty-based terminal emulator that supports a shell. Graphics Tool Bring up a gfxtool(l), for running graphics programs. Console Bring up a Console window, a cmdtool with the -C flag, to act as the system console. Since many system messages can be directed to the console, there should always be a console window on the screen. Editors Text Editor Defaults Editor Icon Editor Font Editor Bring up a textedit(l), for reading and editing text files. Bring up a defaultsedit(l), for browsing or changing your defaults settings. Bring up a new iconedit(l). Bring up a fontedit(l). Tools Mail Tool Bring up a mailtool(l), for reading and sending mail. Dbx (Debug) Tool Bring up a dbxtool(l), a window-based source debugger. Sun Release 4. 1 Last change: 1 June 1988 539 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) Performance Meter Bring up a perfmeter(l) to monitor system performance. Bring up a new clock(l). Redraw the entire screen. Use this to repair damage done by processes that wrote to the screen without consulting the SunView sys- tem. There are two items on this submenu. Check Printer Queue and Print Selected Text. Check Printer Queue displays the printer queue in your console; Print Selected Text sends selected text to the standard printer. There are two items on this submenu, ‘Command Tool’ and ‘Shell Tool’. Each creates a terminal emulator that prompts for a machine name and then starts a shell on that machine. Writes out a "/.sunview file that sunview can then use when starting up again. An existing "/.sunview file is saved as "/.sunview-. Completely covers the screen with a graphics display, and “locks” the workstation until you type your password. When you “unlock” the workstation, the screen is restored as it was when you locked it. See lockscreen(l) for details. Exit from sunview, including all windows, and kill processes associat- ed with them. You return to the shell from which you started sunview. You can specify your own SunView menu; see SunView Defaults below for details. The Frame Menu A small set of universal functions are available through the Frame menu. There are also accelerators for some of these functions, described under Frame Menu Accelerators, below. You can invoke the Frame menu when the cursor is over a part of the application that does not provide an application-specific menu, such as the frame header (broad stripe holding the application’s name), the border stripes of the window, and the icon. Close Open Move Resize Choosing Resize invokes an Unconstrained resize. Toggle the application between closed (iconic) and open state. Icons are placed on the screen according to the icon policy in your defaults database; see SunView Defaults below. When a window is closed, its underlying processes continue to run. Moves the application window to another spot on the screen. Move has a sub-menu with two items: Unconstrained and Constrained. Unconstrained Move the window both horizontally and vertically. Constrained Moves are either vertical or horizontal, but not both. Choosing Move invokes an Unconstrained move. Shrink or stretch the size of a window on the screen. Resize has a sub-menu containing: Unconstrained Resize the window both horizontally and vertically. Constrained Resize vertically or horizontally, but not both. Clock Services Redisplay All Printing Remote Login Save Layout Lock Screen Exit SunView 540 Last change: 1 June 1988 Sun Release 4.1 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) UnZoom Zoom Zoom expands a window vertically to the full height of the screen. UnZoom undoes this. FullScreen Make a window the full height and width of the screen. Front Bring the window to “the top of the pile.” The whole window becomes visible, and hides any window it happens to overlap on the screen. Back Put the window on the “bottom of the pile”. The window is hidden by any window which overlaps it. Props Display the property sheet. (Only active for applications that provide a property sheet.) Redisplay Redraw the contents of the window. Quit Notify the application to terminate gracefully. Requires confirmation. Frame Menu Accelerators Accelerators are provided for some Frame menu functions. You can invoke these functions by pushing a single button in the window’s frame header or outer border. See the SunView Beginner’s Guide for more details. Open Click the LEFT mouse button when the pointer is over the icon. Move Press and hold the MIDDLE mouse button while the pointer is in the frame header or outer border. A bounding box that tracks the mouse is displayed while you hold the button down. When you release the button, the window is redisplayed within the bounding box. If the pointer is near a comer, the move is Unconstrained. If it is in the center third of an edge, the move is Constrained. Resize Hold the CTRL key and press and hold the MIDDLE mouse button while the pointer is in the frame header or outer border. A bounding box is displayed, and one side or corner tracks the mouse. If the pointer is near a comer when you press the mouse button, the resize is Unconstrained; if in the middle third of an edge, the resize is Constrained. Zoom UnZoom Hold the CTRL key and click the LEFT mouse button while the pointer is in the frame header or outer border. Front Click the LEFT mouse button while the pointer is on the frame header or outer bord- er. Back Hold the SHIFT key and click the LEFT mouse button while the pointer is on the frame header or outer border. In addition, you can use two function keys as even faster accelerators. To expose a window that is partially hidden, press the Front function key (normally L5) while the pointer is anywhere in that window. Or, if the window is completely exposed, use the Front key to hide it. Similarly, to close an open window, press the Open key (normally L7) while the pointer is anywhere in that window. If the window is iconic, use the Open key to open it. In applications with multiple windows, you can often adjust the border between two windows up or down, without changing the overall size of the application: hold the CTRL key, press the MIDDLE mouse button over the boundary between the two windows, and adjust the size of the (bounded) subwindow as with Resize. Sun Release 4.1 Last change: 1 June 1988 541 SUNVffiW(l) USER COMMANDS SUNVEEW ( 1 ) Startup Processing: The .sunview File Unless you override it, sunview starts up with a predefined layout of windows. The default layout is specified in the file /usr/lib/.sunview. If there is a file called .sunview in your home directory, it is used in- stead. For compatibility with earlier releases, if there is no .sunview file in your home directory, but a .suntools file instead, the latter file is used. SunView Defaults SunView allows you to customize the behavior of applications and packages by setting options in a de- faults database (one for each user). Use defaultsedit(l) to browse and edit your defaults database. Select the “SunView” category to see the following items (and some others): Walking_menus If enabled, the SunView menu, the Frame menu, and many applications will use walking menus. Applications that have not been converted will still use stacking menus. If disabled, applications will use stacking menus. The default value is “En- abled.” Click_to_Type If enabled, keyboard input will stay in a window until you click the LEFT or MIDDLE mouse button in another window. If disabled, keyboard input will follow the mouse. The default value is “Disabled.” Font You can change the SunView default font by giving the full pathname of the font you want to use. Some alternate fonts are in the directory /usr/lib/fonts/fixedwidthfonts. The default font from the SunOS 2.0 release was /usr/lib/fonts/fixedwidthfonts/screen.r.13. The default value is null, which has the same effect as specifying /usr/lib/fonts/fixedwidthfonts/screen.r.ll. Rootmenu_filename You can change the SunView menu by giving the full pathname of a file that specifies your own menu. See The SunView Menu File below for details. The de- fault value is null, which gives you the menu found in /usi71ib/.rootmenu. Icon_gravity Determine which edge of the screen (“North”, “South”, “East”, or “West”) icons will place themselves against. The default value is “North.” Audible_bell If enabled, the “bell” command will produce a beep. The default value is “Enabled.” Visible_bell If enabled, the “bell” command will cause the screen to flash. The default value is “Enabled.” Root_Pattern Used to specify the “pattern” that covers the background, “on” means to use the de- fault desktop gray pattern, “off’ means to not use the default desktop gray pattern, “gray” means to use a 50% gray color on color monitors. Anything else is the name of a file produced with iconedit(l) which contains an image that is replicated all over the background. The default value is “on.” After you have set the options you want in the “SunView” category, click on the Save button in de- faultsedit; then exit sunview and restart it. Select the “Menu” category to see the following items (and some others): Stay_up If enabled, menus are invoked by pressing and releasing the RIGHT mouse button; the menu appears after you release the RIGHT mouse button. To choose a menu item, point at it, then press and release the RIGHT mouse button a second time. The de- fault value is “False”. 542 Last change: 1 June 1988 Sun Release 4.1 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) Itemsincolumnmajor If enabled, menus that have more than one column are presented in “column major” order (the way ls(lV) presents file names). This may make a large menu easier to read. The default value is “False.” After you have set the options you want in the “Menu” category, click on the Save button in defaultsedit. Any applications you start after saving your changes will be affected by your new choices. For all defaults categories except for “SunView”, you do not need to exit sunview and restart it. The SunView Menu File The file called /usr/lib/.rootmenu contains the specification of the default SunView menu. You can change the SunView menu by creating your own file and giving its name in the Rootmenu_filename item in the SunView Defaults. Lines in the file have the following format: The left side is a menu item to be displayed, and the right side is a command to be executed when that menu item is chosen. You can also include comment lines (begin- ning with a “#’) and blank lines. The menu item can be a string, or the full pathname of an icon file delimited by angle brackets (unless Walking_menus is disabled in the SunView defaults). Strings with embedded blanks must be delimited by double quotes. There are four reserved-word commands that can appear on the right side. EXIT Exit sunview (requires confirmation). REFRESH Redraw the entire screen. MENU This menu item is a pull-right item with a submenu. If a full pathname follows the MENU command, the submenu contents are taken from that file. Other- wise, all the lines between a MENU command and a matching END command are added to the submenu. END Mark the end of a nested submenu. The left side of this line should match the left side of a line with a MENU command. If the command is not one of these four reserved-word commands, it is treated as a command line and exe- cuted. No shell interpretation is done, although you can run a shell as a command. Here is a menu file that demonstrates some of these features: Quit "Mail reader" "My tools" "Click to type" "Follow mouse" "Print selection" "Nested menu" EXIT mailtool MENU /home/me/mytooIs.menu swin — c swin -m sh -c get selection | Ipr MENU "Command Tool" cmdtool "Shell Tool" shelltool "Nested menu" END "Icon menu" MENU Sun Release 4.1 Last change: 1 June 1988 543 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) textedit dbxtool "Icon menu" END Multiple Screens The sunview program runs on either a monochrome or color screen. Each screen on a machine with multi- ple screens may have a separate sunview running. The keyboard and mouse input devices can be shared between screens. Using adjacentscreens(l) you can set up the pointer to slide from one screen to another when you move it off the edge of a screen. To set up an instance of sunview on two screens: • Invoke sunview on the first display as you normally would. This starts an instance of sunview on the default frame buffer (/dev/fb). e In a shelltool, run: sunview -d device & This starts another device. A typical choice might be /dev/cgone. • In that same shelltool, run: adjacentscreens /dev/fb -r device This sets up the cursor to switch between screens as it crosses the right or left edge of the respective screens. Multiple Desktops on the Same Screen Machines that support multiple plane groups, such as the Sun-3/110 system, can support independent sun- view processes on each plane group. They can share keyboard and mouse input in a manner similar to that for multiple screens. To set up two plane groups: • Start sunview in the color plane group by running: sunview -8bit_color_only -toggleenable This starts sunview on the default frame buffer named /dev/fb, but limits access to the color plane group. © In a shelltool, run: sunview -d /dev/bwtwoO -toggle enable -n & This starts sunview in the overlay plane accessed by /dev/bwtwoO. ® Run: adjacentscreens -c /dev/fb -1 /dev/bwtwoO This sets up the pointer to switch between desktops as it crosses the right or left edge of the respective desktops. Pre-3.2 applications cannot be run on the -8bit_color_only desktop, because they do not write to the over- lay plane. switcher(l), another application for switching between desktops, uses some amusing video wipe anima- tion. It can also be used to toggle the enable plane. Sec switcher(l) for details. 544 Last change: 1 June 1988 Sun Release 4.1 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) Generic Tool Arguments Most window-based tools take the following arguments in their command lines: FLAG (LONG FLAG) ARGUMENTS NOTES -Ww (-width) columns -Wh (-height) lines -Ws (-size) xy x and y are in pixels -Wp (-position) xy x and y are in pixels -WP (-iconposition) xy x and y are in pixels -W1 (-label) string -Wi (-iconic) makes the application start iconic (closed) -Wt (-font) filename -Wn (-no_name_stripe) -Wf (-foreground_color) red green blue 0-255 (no color-full color) -Wb (-background_color) red green blue 0-255 (no color-full color) -w g (-setdefaultcolor) (apply color to subwindows too) -WI (-icon_image) filename (for applications with non-default icons) -WL (-iconjabel) string (for applications with non-default icons) -WT (-iconfont) filename (for applications with non-default icons) -WH (-help) print this table Each flag option may be specified in either its short form or its long form; the two are completely synonymous. SunView Applications Some of the applications that run in the SunView environment: clock(l), cmdtool(l), dbxtool(l), defaultsedit(l), fontedit(l), gfxtool(l), iconedit(l), lockscreen(l), mailtool(l), overview(l), perfmeter(l), shelltool(l), tektool(l), textedit(l), traffic(lC) Some of the utility programs that run in or with the SunView environment: adjacentscreens(l), clearfunctions(l), getselection(l), sttyfromdefaults(l), swin(l), switcher(l), toolplaces(l) ENVIRONMENT DEF AULTS_FILE The value of this environment variable indicates the file from which SunView de- faults are read. When it is undefined, defaults are read from the .defaults file in your home directory. FILES "/.sunview /usr/lib/.sunview /usr/lib/.rootmenu /usr/lib/fonts/fixedvvidthfonts/* /dev/winx /dev/ptypx /dev/ttypx /dev/fb /dev/kbd /dev/mouse /etc/utmp Sun Release 4.1 Last change: 1 June 1988 545 SUNVIEW ( 1 ) USER COMMANDS SUNVIEW ( 1 ) SEE ALSO adjacentscreens(l), clear_functions(l), clock(l), cmdtool(l), dbxtool(l), defaultsedit(l), fontedit(l), get_selection(l), gfxtool(l), iconedit(l), lockscreen(l), mailtool(l), overview(l), perfmeter(l), screen- dump(l), shelltool(l), stty_from_defaults(l), swin(l), switcher(l), tektool(l), textedit(l), tool- places(l), traffic(lC), fbtab(5), svdtab(5) BUGS Console messages ignore window boundaries unless redirected to a console window. This can disrupt the sunview desktop display. The display can be restored using the Redisplay All item on the SunView menu. To prevent this, use the Console item to start a console window. With an optical mouse, sometimes the arrow-shaped cursor does not move at start-up; moving the mouse in large circles on its pad normally brings it to life. sunview requires that the /etc/utmp file be given read and write permission for all users. On a color display, colors may “go strange” when the cursor is in certain windows that request a large number of colors. When running multiple desktops, only one console window can be used. In Click-to-type mode, it is impossible to exit from sunview by typing CTRL-D CTRL-Q. 546 Last change; 1 June 1988 Sun Release 4.1 S V_ACQUIRE ( 1 ) USER COMMANDS S V_ACQUIRE ( 1 ) NAME sv_acquire, sv_release - change owner, group, permissions of window devices SYNOPSIS sv_acquire [ star twin [ nwins [ nbackground ]]] sv_release DESCRIPTION sv_acquire changes the owner, group and permissions of window system devices to the user ID, group ID, and the permissions specified in /etc/svdtab (see svdtab(5)), if there is an entry in that file. If no entry ex- ists in /etc/svdtab, no changes will be made. sv_release returns the owner, and group to root and wheel. The permissions are set as specified in /etc/svdtab. startwin indicates the first win to change, nwins indicates the number of windows to change, nbackgound indicates the number of win devices to change in the backgound. This is a setuid root program spawned by the window system (for example, sunview(l)). sv_acquire exits if the user does not own console devices listed in /etc/fbtab (see fbtab(5)). sv_acquire exits with 0 on success and -1 on failure. EXAMPLES In the following example, sv_acquire sets the user ID and the group ID of /dev/winO through /dev/winl5 in the foreground and spawns a background process to set /dev/winl6 through /dev/win256 and exit with er- ror status. sv acquire 0 256 240 The purpose of spawning a background process is to allow the caller to avoid waiting for all win devices to be changed. Note: a diskless 3/50 sets approximately 16 wins per second. SEE ALSO sunview(l), fbtab(5), svdtab(5) Sun Release 4.1 Last change: 25 January 1990 547 SWIN ( 1 ) USER COMMANDS SWIN ( 1 ) NAME swin - set or get SunView user input options SYNOPSIS swin [ -cghm ] [ -r event value shift_state ] [ -s event value shift _state ] [ -t seconds ] AVAILABILITY This command is available with the SunView User's Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION The swin (set window; analogous to stty(lV)) command lets you change some of the input behavior of your SunView environment. By default, your keyboard input follows your pointer. This means that in ord- er to type to a window you position the pointer over the window. This is called keyboard-follow s-mouse mode. You can specify that the keyboard input continues to go to the same window, regardless of the pointer posi- tion, until you take some specific action, like clicking the mouse. When this is done, you can roam around the screen with the pointer and not change the window to which keyboard input is directed. Running Sun- View like this is said to be operating in click-to-type mode. When running in click-to-type mode, one user action sets the type-in point in the window that you want to receive keyboard input. The default user action to do this is the clicking of the LEFT mouse button while positioning the pointer over the new type-in point. This user action can be changed. Another user action restores the previous type-in point in the window that you want to receive keyboard in- put. The default user action to do this is the clicking of the MIDDLE mouse button while positioning the pointer over the window. This user action can be changed. OPTIONS -c Turn on click-to-type mode using the default user actions: the LEFT mouse button sets the type-in point and the MIDDLE mouse button restores the type-in point. You can use the defaultsedit(l) program to set click-to-type on permanently; see the Click_to_Type option of sunview(l). -g Get the state of the user input options controlled by swin. If no arguments are supplied to swin then -g is implied. -h Print out a help message that briefly describes the options to swin. -m Run in keyboard-follows-mouse mode. -s event value shift_state Set the user action that sets the type-in point and sets the keyboard input window. The event identifies the particular user action and is one of: LOC_WINENTER pointer entering a window MS_LEFT LEFT mouse button MS_MIDDLE MIDDLE mouse button MS_RIGHT RIGHT mouse button 548 Last change: 21 December 1987 Sun Release 4.1 SWIN(l) USER COMMANDS SWIN(l) decimal jiumber place the decimal number of a firm event here; see list of events in (avoid function keys, normally unused control-ASCII characters are OK, normally unused SHIFT keys are OK). value identifies the transition of the event and is one of: ENTER the pointer entering a window (use with LOC_WINENTER) DOWN the button associated with event went down UP the button associated with event went up (avoid this) The shift state identifies the state of the SHIFT keys at the time of the event /value pair in order for that pair to be used to control the keyboard input window. The shift state is one of: SHIFT_DONT_CARE Ignore the state of the SHIFT keys SHIFT_ALL_UP All the SHIFT keys must be up SHIFT_LEFT The left SHIFT key must be down (not the key labeled LEFT) SHIFTJRIGHT the right SHIFT key must be down (not the key labeled RIGHT) SHIFT_LEFTCTRL the left CTRL key must be down SHIFTJRIGHTCTRL the right CTRL key must be down -r event value shift _state Set the user action that restores the type-in point and sets the keyboard input window. This user action is swallowed so that the application that owns the window does not see it. However, if the window already has keyboard input or if the window refuses keyboard input then this user action is passed on through to the application. The parameters to this command are like those for -s. The following example shows modifying the default click-to-type user actions so that a SHIFT left is required for the restore user event: example % swin -c -r MS MIDDLE DOWN SHIFTLEFT -t seconds SunView synchronizes input so that it does not hand out the next user action until the application fielding the current user action finishes its processing. This allows type-ahead and mouse-ahead. If an application does not finish processing within a given length of time (process virtual time; not wall clock time), the next user action is handed out anyway. This avoids any one application from hanging the workstation. The -t command sets this time limit. A seconds value of 0 tells Sun- View to run unsynchronized; beware of race conditions in this mode. The default seconds value is 2 and the -c command makes it 10 seconds. SEE ALSO defaultsedit(l), stty(lV), sunview(l) SunView User’s Guide Sun Release 4. 1 Last change: 21 December 1987 549 SWIN(l) USER COMMANDS SWIN(l) DIAGNOSTICS swin not passed parent window in environment swin does not work unless SunView is started already. BUGS swin gets you no help in preventing you from specifying -r or -s parameters that are not sensible. 550 Last change: 21 December 1987 Sun Release 4.1 SWITCHER ( 1 ) USER COMMANDS SWITCHER ( 1 ) NAME switcher - switch attention between multiple SunView desktops on the same physical screen SYNOPSIS switcher [ -d frame-buffer ] [ — s nlllrlilolf] t -m x y ] [ -n ] [ -e 0 1 1 ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION switcher is used as an alternative to adjacentscreens(l) for getting between desktops on the Sun-3/I10. Clicking the switcher icon gets you to another desktop using some amusing video-wipe animation. When using walking menus, a menu is available to invoke the switch as well, switcher can also be used to sim- ply set the enable plane to 0 or 1 should it get out of wack. OPTIONS -d frame-buffer The frame buffer is a frame buffer device name, such as /dev/fb, /dev/cgfour or /dev/bwtwoO, on which the desktop that you want to get to resides. This name is the same one supplied to sunview. The -d flag is optional; if not specified, the default device is /dev/fb -snlllrlilolf The -s flag specifies the type of animation used when switching: n (now), 1 (left wipe), r (right wipe), i (tunnel in), o (tunnel out), or f (fade). The -s flag is optional because if not specified, the default animation is to switch immediately, n (now) mode. -mi y The -m indicates what the mouse position should be on the destination desktop after the switch. An ( x y ) value-pair of (-1 -1) says to use the position of the mouse on the desktop at the time of the switch as the mouse position on the destination desktop. The -m flag is optional; if not specified, the default is (-1 -1). -n The -n flag means no switcher icon is wanted so do the switch right now and exit switcher after the switch. This is handy if you want to switch from a root menu command. -e 0 1 1 The -e flag causes the overlay enable plane of the device specified with the -d flag to be set to ei- ther 0 (show color) or 1 (show black and white), switcher run with this option has nothing to do with SunView, only the enable plane is set. EXAMPLE A common multiple desktop configuration for the Sun-3/110 is one monochrome and one color desktop. You could set up an instance of sunview(l) on each plane group in the following ways: 1. Invoke sunview in the color plane group by running: example% sunview -8bit_color_only -toggle_enable This starts sunview on the default frame buffer named /dev/fb but limits access to the color plane group. 2. Inashelltool(l), run: example% sunview -d /dev/bwtwoO — toggle_enable & This starts sunview in the overlay plane that is accessed by /dev/bwtwoO. Sun Release 4.1 Last change: 18 February 1988 551 SWITCHER ( 1 ) USER COMMANDS SWITCHER ( 1 ) 3. In a shelltool on the original desktop run: example% switcher -d /dev/bwtwoO -s i & Clicking on the switcher icon when it is visible moves you to the /dev/bwtwoO desktop. 4. In a shelltool on the /dev/bwtwoO desktop run: example % switcher -s o & Clicking on the switcher icon when it is visible moves you back to the /dev/fb desktop. FILES /usr/bin/switcher /dev/bwtwoO /dev/fb /dev/cgfour SEE ALSO adjacentscreens(l), shelltool(l), sunview(l) 552 Last change: 18 February 1988 Sun Release 4.1 SYMORDER(l) USER COMMANDS S YMORDER ( 1 ) NAME symorder - rearrange a list of symbols SYNOPSIS symorder [ -s ] orderlist symbolfile DESCRIPTION sysmfile is a file containing symbols to be found in objectfile, 1 symbol per line. objectfile is updated in place to put the requested symbols first in the symbol table, in the order specified. This is done by swapping the old symbols in the required spots with the new ones. If all of the order sym- bols are not found, an error is generated. This program was specifically designed to cut down on the overhead of getting symbols from /vmunix. Sun386i DESCRIPTION Symbols specified on the command line are moved to the beginning of the output symbol table, not swapped. Therefore, the symbols specified on the command line will appear in order at the beginning of the output symbol table, followed by the original symbol table with the gaps created by the moved symbols closed. OPTIONS -s Work silently, that is, display nothing except error messages. This is useful for checking the error status. FILES /vmunix SEE ALSO nlist(3V) Sun Release 4.1 Last change: 18 February 1988 553 SYNC ( 1 ) USER COMMANDS SYNC ( 1 ) NAME sync - update the super block; force changed blocks to the disk SYNOPSIS sync DESCRIPTION sync forces any information on its way to the disk to be written out immediately, sync can be called to en- sure that all disk writes are completed before the processor is halted abnormally. SEE ALSO cron(8), fsck(8), halt(8), reboot(8) 554 Last change: 9 September 1987 Sun Release 4.1 SYSEX(l) USER COMMANDS SYSEX(l) NAME sysex - start the system exerciser SYNOPSIS sysex AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0.x release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION sysex is the system exerciser for Sun386i systems. This program is designed to run under the SunView environment, but a dumb terminal interface is provid- ed. The program tests subsystems of a Sun386i system, printing information to the console and log files. Most commands are accessible by way of buttons, toggle switches, or menus. A startup file ‘/.sysexrc, can be created by experienced users to set runtime parameters. USAGE Subwindows Control Panel Tells which version of the exerciser is running. User controls sysex executions through the toggles, buttons, and sliders in this panel. Perfmon window Graphically displays system statics. The standard SunView perfmeter(l). Console window Displays the system messages and sysex error messages. Status Window Displays pass counts and error counts for all tests that are currently selected. Also displays system pass count, and total system errors. Elapsed time signifies time since start button is pressed. Load Sliders These slide bars allow the user to modulate the load on the system. I/O-CPU Load Moving this slider changes the balance between I/O-intensive and compute-intensive tests that are running. SYSTEM LOAD Moving this slider increases and decreases the system activity generated by sysex. Test Toggles Each test selection on the control panel is selectable by moving the cursor over to the toggle and pressing the left mouse button. The tests are displayed by device groups in the control panel. A test is enabled when a check mark is seen in the box. Clicking left on the group label acts as a group enable/disable for all tests in that device group. Currendy there are tests for physical memory and virtual memory, fixed disk, diskette, Ethernet, and color frame buffer. Command Buttons Command buttons exist for the following commands: Quit Sysex Stop all current tests and exit the exerciser. All logs will be saved. Log Files Display menu for choosing a log to view, reset, or print. Options Display window through which ‘/.sysexrc parameters can be modified. Print Screen Take screendump of the current screen. Sun Release 4.1 Last change: 1 1 February 1988 555 SYSEX ( 1 ) USER COMMANDS SYSEX ( 1 ) Start Tests Stop Tests Pause Continue Start all test from passO that have been selected. Resets pass count. Toggles to Stop Tests. Begin elapsed time count. Stop all tests that are running. Toggles to Start Tests. Pause tests by issuing SIGSTP. Continue testing from the stopped state without resetting pass count. Toggles to Pause, leaves pass counts intact. Continue elapsed time count if Continued from a Pause. Logs When the user selects the DISPLAY LOGS button and chooses from the log menu, a scrollable pop-up win- dow displays the log, which is one of /var/sysex/sysex.info, /var/sysex/sysex.error, or /etc/adm/messages. Logs contain messages classified as INFO, WARNING, ERROR, or FATAL. The INFO file contains all messages; the ERROR file contains only error and fatal messages. Variables sysex has several variables than can be set in the "/.sysexrc file. Some of the variables pertain to only one test and others are global to all tests. Clicking Done saves changes to the "/.sysexrc file. Clicking Cancel leaves options unchanged. verbose Display messages about what is currently taking place, verify Run through a cursory pass of tests to see all subsystems present. runonerr Halt subsystem testing when an error occurs, sysexhaltonerr Stop sysex if an error occurs in any subsystem, core Create core dump in Ivor I sysex. single_pass Run one pass of each selected device test. For the expert user, more commands are available by clicking the manufacturing cycle to Enabled. This displays the following options: fdc_wait Variable wait time between executions of the diskette test, vmemwait Variable delay between successive executions of the virtual memory test, debug Display all messages to aid analysis of problem systems. checkeeprom Read NVRAM configuration information and display values, intervention Turn on or off the confirmer for all destructive tests, or for tests requiring media. FILES /usr/sysex/sysex /var/sysex/core / var/sysex/sysex.info /var/sysex/sysex.error 556 Last change: 11 February 1988 Sun Release 4.1 SYSWAIT(l) USER COMMANDS SYSWAIT(l) NAME syswait - execute a command, suspending termination until user input SYNOPSIS syswait message command AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0 jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION syswait executes a specified command, suspending termination until the user types any character, message is the message prompting the user to type a character to terminate the command, command is the command to be executed. EXAMPLE The following example invokes a cmdtool and executes ‘Is *.c’, but waits for the user to type a character before terminating the Is and closing the cmdtool window. cmdtool syswait "Press any key to quit..." "Is *.c" & Sun Release 4.1 Last change: 19 February 1988 557 TABS (IV) USER COMMANDS TABS (IV) NAME tabs - set tab stops on a terminal SYNOPSIS /usr/5bin/tabs ( tabspec ] [ —Ttype ] [ +mn ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION tabs can be used to specify TAB stops on terminals that support remotely-settable hardware TAB charac- ters. TAB stops are set according to the tabspec option, as described below, and previous settings are erased. Four types of tab specification are accepted for tabspec. They are: -code Set the TAB stops according to the canned TAB setting specified by code, as given by fspec(5). -n Set the TAB stops at intervals of n columns, that is, at 1+n, l+2*n, and so on, as per the -n specification as given by fspec(5). nl ,n2,... Set the TAB stops at positions nl , n2, and so on, as per the nl ,n2,... specification as given by fspec(5). --file Read the first line of the file specified by file, searching for a format specification as given by fspec(5). If this line contains a format specification, set the TAB stops accordingly, otherwise set them to every 8 columns. This type of specification may be used to make sure that a file contain- ing a TAB specification is displayed with correct TAB settings. For example, it can be used with the pr(lV) command: tabs — file; pr file If no tabspec is given, the default value is -8, the standard default TAB setting. The lowest column number is 1. Note: for tabs, column 1 always refers to the leftmost column on a terminal, even one whose column markers begin at 0, (such as the DASI 300, DASI 300s, and DASI 450). TAB and margin setting is per- formed by echoing to the proper sequences to the standard output. OPTIONS -T type tabs usually needs to know the type of terminal in order to set TAB characters, and always needs to know to set margins, type is a name listed in term(5). If no -T flag is supplied, tabs uses the value of the environment variable TERM. If TERM is not defined in the environment (see environ(5V)), tabs tries a default sequence that will work for many terminals. +mn The margin argument may be used for some terminals. It moves all TAB stops over n columns by making column n+1 the left margin. If +m is given without a value of n, the value assumed is 10. For a TermiNet, the first value in the tab list should be 1, or the margin will move even further to the right. The normal (leftmost) margin on most terminals is obtained by +m0. The margin for most terminals is reset only when the +m flag is given explicitly. SEE ALSO pr(lV), tput(lV), environ(5V), fspec(5), term(5), terminfo(5V) 558 Last change: 7 January 1988 Sun Release 4.1 TABS (IV) USER COMMANDS TABS (IV) BUGS There is no consistency between different terminals regarding ways of clearing tabs and setting the left margin. tabs clears only 20 tabs (on terminals requiring a long sequence), but is willing to set 64. Sun Release 4.1 Last change: 7 January 1988 559 TAIL ( 1 ) USER COMMANDS TAIL ( 1 ) NAME tail - display the last part of a file SYNOPSIS tail + 1 -number [ lbc ] [ f ] [filename ] tail + 1 -number [ 1 ] [ rf ] [filename ] DESCRIPTION tail copies filename to the standard output beginning at a designated place. If no file is named, the standard input is used. OPTIONS Options are all jammed together, not specified separately with their own signs. + number Begin copying at distance number from the beginning of the file, number is counted in units of lines, blocks or characters, according to the appended option 1, b, or c. When no units are specified, counting is by lines. If number is not specified, the value 10 is used. -number Begin copying at distance number from the end of the file, number is counted in units of lines, blocks or characters, according to the appended option 1, b, or c. When no units are specified, counting is by lines. If number is not specified, the value 10 is used. 1 number is counted in units of lines. b number is counted in units of blocks. c number is counted in units of characters. r Copy lines from the end of the file in reverse order. The default for option r is to print the entire file in reverse order, number is the count of lines from the end of the file regardless of sign. Op- tion r may not be used with b or c. f If the input file is not a pipe, do not terminate after the line of the input file has been copied, but enter an endless loop, sleeping for a second and then attempting to read and copy further records from the input file. This option may be used to monitor the growth of a file that is being written by some other process. For example, the command: tail -f fred will print the last ten lines of the file fred, followed by any lines that are appended to fred between the time tail is initiated and killed. As another example, the command: tail -15cf fred will print the last 15 characters of the file fred, followed by any lines that are appended to fred between the time tail is initiated and killed. SEE ALSO dd(l) BUGS Data for a tail relative to the end of the file is stored in a buffer, and thus is limited in size. Various kinds of anomalous behavior may happen with character special files. 560 Last change: 14 August 1989 Sun Release 4.1 TALK ( 1 ) USER COMMANDS TALK ( 1 ) NAME talk - talk to another user SYNOPSIS talk username [ ttyname ] DESCRIPTION talk is a visual communication program which copies lines from your terminal to that of another user. If you wish to talk to someone on your own machine, then username is just the person’s login name. If you wish to talk to a user on another host, then username is one of the following forms : hostluser ho st. user hostluser user @ host though user@host is perhaps preferred. If you want to talk to a user who is logged in more than once, the ttyname argument may be used to indi- cate the appropriate terminal name. When first called, talk sends the message: Message from TaWHaemonC&his machine&tiime. . . talk: connection requested by your _name @y our jnachine. talk: respond with: talk your _name@your jnachine to the user you wish to talk to. At this point, the recipient of the message should reply by typing: example % talk your _name@your jnachine It does not matter from which machine the recipient replies, as long as their login name is the same. Once communication is established, the two parties may type simultaneously, with their output appearing in separate windows. Typing CTRL-L redraws the screen, while your erase, kill, and word kill characters will work in talk as normal. To exit, just type your interrupt character; talk then moves the cursor to the bottom of the screen and restores the terminal. Permission to talk may be denied or granted by use of the mesg command. At the outset talking is allowed. Certain commands, in particular nroff(l) and pr(l V) disallow messages in order to prevent messy output. FILES /etc/hosts to find the recipient’s machine /etc/utmp to find the recipient’s tty SEE ALSO mail(l), mesg(l), nroff(l), pr(lV), who(l), write(l), talkd(8C) Sun Release 4.1 Last change: 9 September 1987 561 TAR(l) USER COMMANDS TAR(l) NAME tar - create tape archives, and add or extract files SYNOPSIS tar [ — ]c|r|t|u|x[ bBefFhilmopvwX014578 ] [ tarfile ] [ blocksize ] [ exclude-file ] [ -I include-file ] filename 1 filename2 ... -C directory filenameN . . . DESCRIPTION tar archives and extracts multiple files onto a single tar, file archive, called a tarfile. A tarfile is usually a magnetic tape, but it can be any file, tar’s actions are controlled by the first argument, the key , a string of characters containing exactly one function letter from the set crtux, and one or more of the optional func- tion modifiers listed below. Other arguments to tar are file or directory names that specify which files to archive or extract. In all cases, the appearance of a directory name refers recursively to the files and sub- directories of that directory. FUNCTION LETTERS c Create a new tarfile and write the named files onto it. r Write the named files on the end of the tarfile. Note: this option does not work with quarter-inch archive tapes. t List the table of contents of the tarfile . u Add the named files to the tarfile if they are not there or if they have been modified since they were last archived. Note: this option does not work with quarter-inch archive tapes. x Extract the named files from the tarfile. If a named file matches a directory with contents written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored (if possible). If no filename arguments are given, all files in the archive are extracted. Note: if multiple entries specifying the same file are on the tape, the last one overwrites all earlier versions. FUNCTION MODIFIERS b Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. The block size is determined automatically when reading tapes (key letters x and t). This determination of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). The maximum blocking factor is determined only by the amount of memory available to tar when it is run. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better media utilization. B Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks even when more data is coming. e If any unexpected errors occur tar will exit immediately with a positive exit status. f Use the next argument as the name of the tarfile. If f is omitted, use the device indicated by the TAPE environment variable, if set. Otherwise, use /dev/rmt8 by default. If tarfile is given as tar writes to the standard output or reads from the standard input, whichever is appropriate. Thus, tar can be used as the head or tail of a filter chain, tar can also be used to copy hierarchies with the command: example% cd fromdir; tar cf — - 1 (cd todir; tar xfBp -) F With one F argument specified, exclude all directories named SCCS from tarfile. With two argu- ments FF, exclude all directories named SCCS, all files with .o as their suffix, and all files named errs, core, and a.out. h Follow symbolic links as if they were normal files or directories. Normally, tar does not follow symbolic links. i Ignore directory checksum errors. 562 Last change: 16 February 1988 Sun Release 4.1 USER COMMANDS TAR(l) TAR(l) 1 Display error messages if all links to archived files cannot be resolved. If 1 is not used, no error messages are printed. m Do not extract modification times of extracted files. The modification time will be the time of extraction. o Suppress information specifying owner and modes of directories which tar normally places in the archive. Such information makes former versions of tar generate an error message like: filename/.' cannot create when they encounter it. p Restore the named files to their original modes, ignoring the present umask(2V). SetUID and sticky information are also extracted if you are the super-user. This option is only useful with the x key letter. v Verbose. Normally tar does its work silently; this option displays the name of each file tar treats, preceded by the function letter. When used with the t function, v displays the tarfile entries in a form similar to ‘Is -I’. w Wait for user confirmation before taking the specified action. If you use w, tar displays the action to be taken followed by the file name, and then waits for a y response to proceed. No action is taken on the named file if you type anything other than a line beginning with y. X Use the next argument as a file containing a list of named files (or directories) to be excluded from the tarfile when using the key letters c, x, or t. Multiple X arguments may be used, with one exclude file per argument. 014578 Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid drives. The default is /dev/rmt8. If a file name is preceded by -I then the filename is opened. A list filenames, one per line, is treated as if each appeared separately on the command line. Be careful of trailing white space in both include and exclude file lists. In the case where excluded files (see X option) also exist, excluded files take precedence over all included files. So, if a file is specified in both the include and exclude files (or on the command line), it will be excluded. If a file name is preceded by -C in a c (create) or r (replace) operation, tar will perform a chdir (see csh(l)) to that file name. This allows multiple directories not related by a close common parent to be archived using short relative path names. See EXAMPLES below. Note: the -C option only applies to one following directory name and one following file name. EXAMPLES To archive files from /usr/include and from /etc, one might use: example% tar c -C /usr include -C /etc . If you get a table of contents from the resulting tarfile, you will see something like: include/ include/a.out.h and all the other files in /usr/include . . . /chown and all the other files in /etc Sun Release 4. 1 Last change: 16 February 1988 563 TAR ( 1 ) USER COMMANDS TAR ( 1 ) Here is a simple example using tar to create an archive of your home directory on a tape mounted on drive /dev/rmtO: example% cd example% tar cvf /dev/rmtO . messages from tar The c option means create the archive; the v option makes tar tell you what it is doing as it works; the f option means that you are specifically naming the file onto which the archive should be placed (/dev/rmtO in this example). Now you can read the table of contents from the archive like this: example% tar tvf /dev/rmtO display table of contents of the archive ( access user-id/ group-id size mod. date filename) rw-r--r— 1677/40 2123 Nov 7 18:15:1985 Varchive/test.c example% You can extract files from the archive like this; example% tar xvf /dev/rmtO extract files from the archive messages from tar example % If there are multiple archive files on a tape, each is separated from the following one by an EOF marker, tar does not read the EOF mark on the tape after it finishes reading an archive file because tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use tar to read the next archive file from the tape, tar does not know enough to skip over the EOF mark and tries to read the EOF mark as an archive instead. The result of this is an error message from tar to the effect: tar: blocksize=0 This means that to read another archive from the tape, you must skip over the EOF marker before starting another tar command. You can accomplish this using the mt(l) command, as shown in the example below. Assume that you are reading from /dev/nrmtO. example% tar xvfp /dev/nrmtO read first archive from tape messages from tar example% mt fsf 1 skip over the end-of-file marker example% tar xvfp /dev/nrmtO read second archive from tape messages from tar example% Finally, here is an example using tar to transfer files across the Ethernet. First, here is how to archive files from the local machine (example) to a tape on a remote system (host): example% tar cvfb - 20 filenames \ rsh host dd of=/dev/rmt0 obs=20b messages from tar exam pie % In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with the v option, specifying the name of the output tarfile using the f option (the standard output is where the tarfile appears, as indicated by the sign), and specifying the blocksize (20) with the b option. If you want to change the blocksize, you must change the blocksize arguments both on the tar command and on the dd command. Now, here is how to use tar to get files from a tape on the remote system back to the local system: example% rsh -n host dd if=/dev/rmtO bs=20b | tar xvBfb - 20 filenames messages from tar example% 564 Last change: 16 February 1988 Sun Release 4.1 TAR ( 1 ) USER COMMANDS TAR(l) In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the input tarfile using the f option (the standard input is where the tarfile appears, as indicated by the sign), and specifying the blocksize (20) with the b option. FILES /dev/rmt? half-inch magnetic tape interface /dev/rst? SCSI tape interface /tmp/tar* ENVIRONMENT TAPE If specified, in the environment, the value of TAPE indicates the default tape device. SEE ALSO cpio(l), csh(l), mt(l), umask(2V), tar(5), dump(8), restore(8) BUGS Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives cannot backspace. There is no way to ask for the nth occurrence of a file. Tape errors are handled ungracefully. The u option can be slow. There is no way selectively to follow symbolic links. When extracting tapes created with the r or u options, directory modification times may not be set correctly. Files with names longer than 100 characters cannot be processed. Filename substitution wildcards do not work for extracting files from the archive. To get around this, use a command of the form: tar xvf. . . /dev/rstO ‘tar tf. . . /dev/rstO | grep ’ pattern ,l Sun Release 4.1 Last change: 16 February 1988 565 TBL(l) USER COMMANDS TBL(l) NAME tbl - format tables for nroff or troff SYNOPSIS tbl [ -ms ] [filename ] . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. DESCRIPTION tbl is a preprocessor for formatting tables for nroff(l) or troff(l). The input filenames are copied to the standard output, except that lines between .TS and .TE command lines are assumed to describe tables and are reformatted. Details are given in Formatting Documents. If no arguments are given, tbl reads the standard input, so tbl may be used as a filter. When tbl is used with eqn(l) or neqn the tbl command should be first, to minimize the volume of data passed through pipes. OPTIONS -ms Copy the -ms macro package to the front of the output file. EXAMPLE As an example, letting \t represent a TAB (which should be typed as a genuine TAB) the input •TS css CCS c c c 1 n n. HousehoId\tPopulation Town\tHouseholds \tNumber\tSize Bedminster\t789\t3.26 Bernards Twp.\t3087\t3.74 Bernards ville\t2018\t3.30 Bound Brook\t3425\t3.04 Branchburg\tl644\t3.49 Bridgewater\t7897\t3.81 Far HiIIs\t240\t3.19 .TE yields Household Population Town Households Number Size Bedminster 789 3.26 Bernards Twp. 3087 3.74 Bernardsville 2018 3.30 Bound Brook 3425 3.04 Branchburg 1644 3.49 Bridgewater 7897 3.81 Far Hills 240 3.19 566 Last change: 21 December 1987 Sun Release 4.1 TBL(l) USER COMMANDS TBL(l) SEE ALSO eqn(l), nroff(l), troff(l) Formatting Documents Sun Release 4.1 Last change: 21 December 1987 567 TCOPY(l) USER COMMANDS TCOPY(l) NAME tcopy - copy a magnetic tape SYNOPSIS tcopy source [ destination ] DESCRIPTION tcopy copies the magnetic tape mounted on the tape drive specified by the source argument. The only as- sumption made about the contents of a tape is that there are two tape marks at the end. When only a source drive is specified, tcopy scans the tape, and displays information about the sizes of records and tape files. If a destination is specified, tcopy makes a copies the source tape onto the destina- tion tape, with blocking preserved. As it copies, tcopy produces the same output as it does when only scanning a tape. SEE ALSO mt(l) 568 Last change: 9 September 1987 Sun Release 4.1 TCOV(l) USER COMMANDS TCOV(l) NAME tcov - construct test coverage analysis and statement-by-statement profile SYNOPSIS tcov [ -a ] [ -n ] srcfile. . . AVAILABILITY This command is available on Sun-3 and Sun-4 systems only. DESCRIPTION tcov produces a test coverage analysis and statement-by-statement profile of a C or FORTRAN program. When a program in a file named file, c or file A is compiled with the -a option, a corresponding file .d file is created. Each time the program is executed, test coverage information is accumulated \nfileA. tcov takes source files as arguments. It reads the corresponding file A file and produces an annotated listing of the program with coverage data in file. tcov. Each straight-line segment of code (or each line if the -a option to tcov is specified) is prefixed with the number of times it has been executed; lines which have not been executed are prefixed with #####. Note: the profile produced includes only the number of times each statement was executed, not execution times; to obtain times for routines use gprof(l) or prof(l). OPTIONS -a -n EXAMPLES The command: example % cc -a -o prog prog.c compiles with the -a option — produces prog.d The command: example% prog executes the program accumulates data in prog.d The command: example % tcov prog.c produces an annotated listing in file prog.tcov FILES file.c input C program file file.f input FORTRAN program file file.d input test coverage data file file.tcov output test coverage analysis listing file /usr/lib/bb_Iink.o entry and exit routines for test coverage analysis SEE ALSO cc(lV), gprof(l), prof(l), exit(2V) DIAGNOSTICS premature end of file Issued for routines containing no statements. BUGS The analyzed program must call exit(2V) or return normally for the coverage information to be saved in the .d file. Display an execution count for each statement; if -a is not specified, an execution count is displayed only for the first statement of each straight-line segment of code. Display table of the line numbers of the n most frequently executed statements and their execution counts. Sun Release 4.1 Last change: 18 February 1988 569 TEE(l) USER COMMANDS TEE ( 1 ) NAME tee - replicate the standard output SYNOPSIS tee [ -ai ] [filename ] . . . DESCRIPTION tee transcribes the standard input to the standard output and makes copies in filenames. OPTIONS -a Append the output to the filenames rather than overwriting them. -i Ignore interrupts. 570 Last change: 9 September 1987 Sun Release 4.1 TEKTOOL ( 1 ) USER COMMANDS TEKTOOL ( 1 ) NAME tektool - SunView Tektronix 4014 terminal-emulator window SYNOPSIS tektool [ -s[ Icdeg[ ce ]m[ 12 ] ] [ -[ cr ] command-line ] [ -f fontdir ] AVAILABILITY This command is available with the SunView User’s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION tektool emulates a Tektronix 4014 terminal with the enhanced graphics module. It does this in much the same way as shelltool (see shelltool(l)) emulates a regular glass tty. When tektool is invoked, a command (usually a shell) is started up, its output and input are connected to the emulator, and a new window is formed. The default window is the entire screen. When the emulator is running, keys TF(1) through TF(3), (usually function keys F1-F3 (see kbd(4S)) have special meaning. TF (1) Unshifted, this is the 4014 PAGE button. Shifted, this is the 4014 RESET button. TF (2) Copy screen. The raster image () of the 4014 screen is piped to a com- mand found in the TEKCOPY environment variable. If TEKCOPY is not found in the environment, ‘Ipr -v’ is used. The copy button is unaffected by window manipulations, and will transmit the contents of the 4014 screen only. TF (3) Release page full condition. These functions are also available through the tool menu. When in graphics input (GIN) mode and the 4014 crosshairs are visible, the left hand mouse button may be used as the space bar to terminate GIN mode. OPTIONS -s Specifies the Tektronix 4014 strap options with the following modifiers: 1 Received LINEFEED characters also generate RETURN characters, c Received RETURN characters also generate LINEFEED characters, d Received DELETE characters are used as low order Y axis ( LOY ) addresses, e Echo keyboard input. g Graphic input mode (GIN) terminator specification. If this strap is followed by a c, GIN mode data is terminated by a RETURN character. If it is followed by a e, GIN mode data is terminated by a RETURN character followed by an EOT character. If this strap is not present, no characters are sent after GIN mode data, m Page full control specification. If this strap is followed by a 1, tektool will stop accepting tty input when a LINEFEED character is done past the last line in margin 1. This is the 4014 page full condition. The page full condition it released by a PAGE or a RELEASE or any ASCII keyboard input. If this strap is followed by a 2, the page full condition happens at the end of margin 2. If this strap is not present, the page full condition never occurs. If the -s option is not given, the environment is searched for the TEKSTRAPS vari- able which provides the modifiers. The straps may also be set by the property sheet available by selecting the PROPS menu item. If no straps are specified the d strap is assumed. -c command-line Take terminal emulator input from a shell which in turn runs the command-line follow- ing the -c option. Sun Release 4.1 Last change: 15 June 1988 571 TEKTOOL ( 1 ) USER COMMANDS TEKTOOL ( 1 ) -f fontdir Look for fonts in the directory specified by fontdir. The fonts must be called tekfontO through tekfont3. Fonts must be in vfont(5) format. If this option is not given, the font directory is obtained from the TEKFONTS environment variable (if it exists). If no font directory is specified, /usr/Iib/fonts/tekfonts is used. — r command-line Run command-line to provide input to the terminal emulator. This must be the last option, since the remainder of the arguments are used by the command. FILES /usr/lib/fonts/tekfonts/tekfont[0-3] SEE ALSO shelltool(l), sunview(l), kbd(4S), vfont(5) Installing SunOS 4.1 BUGS Special point plot mode is not supported. Z-axis stuff, except for defocusing, is not supported. Defocused alpha characters are not supported. DIAGNOSTICS copy command failed The copy command in the TEKCOPY environment variable or in the property sheet could not be executed. WARNINGS Like all 4014 emulators, this does not duplicate every nuance of the 4014. For instance, certain programs redraw stuff already on the screen in order to highlight things with the storage flash. This will not work here. Also, even though the emulator supports the full 4096 point addressing of the 4014, it cannot display this on the screen. All points will be rounded to the nearest available pixel. This may cause some funny effects. The tektool window may be treated just like other windows; it can be overlaid, moved, reshaped etc. However, when the window is reshaped, the contents will not scale. 572 Last change: 15 June 1988 Sun Release 4.1 TELNET (1C) USER COMMANDS TELNET (1C) NAME telnet - user interface to a remote system using the TELNET protocol SYNOPSIS telnet [ host [ port ] ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION telnet communicates with another host using the TELNET protocol. If telnet is invoked without arguments, it enters command mode, indicated by its prompt (telnet>). In this mode, it accepts and executes the com- mands listed below. If it is invoked with arguments, it performs an open command (see below) with those arguments. Once a connection has been opened, telnet enters input mode. In this mode, text typed is sent to the remote host. The input mode entered will be either “character at a time” or “line by line” depending on what the remote system supports. In “character at a time” mode, most text typed is immediately sent to the remote host for processing. In “line by line” mode, all text is echoed locally, and (normally) only completed lines are sent to the remote host. The “local echo character” (initially ‘*E’) may be used to turn off and on the local echo (this would mostly be used to enter passwords without the password being echoed). In either mode, if the localchars toggle is TRUE (the default in line mode; see below), the user’s quit, intr, and flush characters are trapped locally, and sent as TELNET protocol sequences to the remote side. There are options (see toggle autoflush and toggle autosynch below) which cause this action to flush subsequent output to the terminal (until the remote host acknowledges the TELNET sequence) and flush previous termi- nal input (in the case of quit and intr). While connected to a remote host, telnet command mode may be entered by typing the telnet “escape character” (initially ‘T, (control-right-bracket)). When in command mode, the normal terminal editing conventions are available. USAGE Telnet Commands The following commands are available. Only enough of each command to uniquely identify it need be typed (this is also true for arguments to the mode, set, toggle, and display commands). open host [ port ] Open a connection to the named host. If no port number is specified, telnet will attempt to contact a TELNET server at the default port. The host specification may be either a host name (see hosts(5)) or an Internet address specified in the “dot notation” (see inet(3N)). close Close a TELNET session and return to command mode. quit Close any open TELNET session and exit telnet. An EOF (in command mode) will also close a session and exit. z Suspend telnet. This command only works when the user is using a shell that supports job con- trol, such as csh(l). mode type type is either line (for “line by line” mode) or character (for “character at a time” mode). The remote host is asked for permission to go into the requested mode. If the remote host is capable of entering that mode, the requested mode will be entered. status Show the current status of telnet. This includes the peer one is connected to, as well as the current mode. Sun Release 4.1 Last change: 17 December 1987 573 TELNET (1C) USER COMMANDS TELNET (1C) display [ argument... ] Display all, or some, of the set and toggle values (see below). ? [ command. ] Get help. With no arguments, telnet prints a help summary. If a command is specified, telnet will print the help information for just that command. send arguments Send one or more special character sequences to the remote host. The following are the argu- ments which may be specified (more than one argument may be specified at a time): escape Send the current telnet escape character (initially ‘T). synch Send the TELNET SYNCH sequence. This sequence causes the remote system to discard all previously typed (but not yet read) input. This sequence is sent as TCP urgent data (and may not work if the remote system is a 4.2 BSD system - if it does not work, a lower case “r” may be echoed on the terminal). brk Send the TELNET BRK (Break) sequence, which may have significance to the remote system. ip Send the TELNET IP (Interrupt Process) sequence, which should cause the remote system to abort the currently running process. ao Sends the TELNET AO (Abort Output) sequence, which should cause the remote system to flush all output from the remote system to the user’s terminal. ayt Sends the TELNET AYT (Are You There) sequence, to which the remote system may or may not choose to respond. ec Sends the TELNET EC (Erase Character) sequence, which should cause the remote sys- tem to erase the last character entered. el Sends the TELNET EL (Erase Line) sequence, which should cause the remote system to erase the line currently being entered. ga Sends the TELNET GA (Go Ahead) sequence, which likely has no significance to the remote system. nop Sends the TELNET NOP (No Operation) sequence. ? Prints out help information for the send command, set argument value Set any one of a number of telnet variables to a specific value. The special value “off’ turns off the function associated with the variable. The values of variables may be interrogated with the display command. The variables which may be specified are: echo This is the value (initially “E’) which, when in “line by line” mode, toggles between doing local echoing of entered characters (for normal processing), and suppressing echo- ing of entered characters (for entering, say, a password). escape This is the telnet escape character (initially “[’) which causes entry into telnet command mode (when connected to a remote system). interrupt If telnet is in localchars mode (see toggle localchars below) and the interrupt character is typed, a TELNET IP sequence (see send ip above) is sent to the remote host. The ini- tial value for the interrupt character is taken to be the terminal’s intr character. 574 Last change: 17 December 1987 Sun Release 4.1 TELNET (1C) USER COMMANDS TELNET (1C) quit If telnet is in localchars mode (see toggle localchars below) and the quit character is typed, a TELNET BRK sequence (see send brk above) is sent to the remote host. The ini- tial value for the quit character is taken to be the terminal’s quit character. flushoutput If telnet is in localchars mode (see toggle localchars below) and the, flushoutput charac- ter is typed, a TELNET AO sequence (see send ao above) is sent to the remote host. The initial value for the flush character is taken to be the terminal’s flush character. erase If telnet is in localchars mode (see toggle localchars below), and if telnet is operating in “character at a time” mode, then when this character is typed, a TELNET EC sequence (see send ec above) is sent to the remote system. The initial value for the erase character is taken to be the terminal’s erase character. kill If telnet is in localchars mode (see toggle localchars below), and if telnet is operating in “character at a time” mode, then when this character is typed, a TELNET EL sequence (see send el above) is sent to the remote system. The initial value for the kill character is taken to be the terminal’s kill character. eof If telnet is operating in “line by line” mode, entering this character as the first character on a line will cause this character to be sent to the remote system. The initial value of the eof character is taken to be the terminal’s eof character. toggle arguments... Toggle (between TRUE and FALSE) various flags that control how telnet responds to events. More than one argument may be specified. The state of these flags may be interrogated with the display command. Valid arguments are: localchars If this is TRUE, then the flush, interrupt, quit, erase, and kill characters (see set above) are recognized locally, and transformed into (hopefully) appropriate TELNET control sequences (respectively ao, ip, brk, ec, and el; see send above). The initial value for this toggle is TRUE in “line by line” mode, and FALSE in “character at a time” mode. autoflush If autoflush and localchars are both TRUE, then when the ao, intr, or quit characters are recognized (and transformed into TELNET sequences; see set above for details), telnet refuses to display any data on the user’s terminal until the remote system acknowledges (via a TELNET Timing Mark option) that it has processed those TELNET sequences. The initial value for this toggle is TRUE if the terminal user had not done an "stty noflsh", oth- erwise FALSE (see stty(lV)). autosynch If autosynch and localchars are both TRUE, then when either the intr or quit characters is typed (see set above for descriptions of the intr and quit characters), the resulting TEL- NET sequence sent is followed by the TELNET SYNCH sequence. This procedure should cause the remote system to begin throwing away all previously typed input until both of the TELNET sequences have been read and acted upon. The initial value of this toggle is FALSE. crmod Toggle RETURN mode. When this mode is enabled, most RETURN characters received from the remote host will be mapped into a RETURN followed by a LINEFEED. This mode does not affect those characters typed by the user, only those received from the remote host. This mode is not very useful unless the remote host only sends RETURN, but never LINEFEED. The initial value for this toggle is FALSE. debug Toggle socket level debugging (useful only to the super-user). The initial value for this toggle is FALSE. Sun Release 4.1 Last change: 17 December 1987 575 TELNET (1C) USER COMMANDS TELNET (1C) options Toggle the display of some internal telnet protocol processing (having to do with TEL- NET options). The initial value for this toggle is FALSE. netdata Toggle the display of all network data (in hexadecimal format). The initial value for this toggle is FALSE. ? Display the legal toggle commands. SEE ALSO csh(l), rlogin(lC), stty(lV) inet(3N), hosts(5) BUGS There is no adequate way for dealing with flow control. On some remote systems, echo has to be turned off manually when in “line by line” mode. There is enough settable state to justify a .telnetrc file. No capability for a .telnetrc file is provided. In “line by line” mode, the terminal’s EOF character is only recognized (and sent to the remote system) when it is the first character on a line. 576 Last change: 17 December 1987 Sun Release 4.1 TEST (IV) USER COMMANDS TEST(IV) NAME test - return true or false according to a conditional expression SYNOPSIS test expression [ expression ] DESCRIPTION test evaluates the expression expression and, if its value is true, returns a zero (true) exit status; otherwise, a non-zero (false) exit status is returned, test returns a non-zero exit if there are no arguments. USAGE Primitives The following primitives are used to construct expression. -b filename True if filename exists and is a block special device. — c filename True if filename exists and is a character special device. -d filename True if filename exists and is a directory. -f filename True if filename exists and is not a directory. -g filename True if filename exists and its set-group-ID bit is set. -h filename True if filename exists and is a symbolic link. -k filename True if filename exists and its sticky bit is set. -1 string the length of the string. -n si True if the length of the string si is non-zero. — p filename True if filename exists and is a named pipe (FIFO). -r filename True if filename exists and is readable. -s filename True if filename exists and has a size greater than zero. -t [fildes ] True if the open file whose file descriptor number is fildes (1 by default) is associated with a ter- minal device. -u filename True if filename exists and its set-user-ID bit is set. -w filename True if filename exists and is writable. -x filename True if filename exists and is executable. Sun Release 4.1 Last change: 15 December 1988 577 TEST (IV) USER COMMANDS TEST (IV) -z si True if the length of string si is zero. si = s2 True if the strings si and s2 are equal. si != s2 True if the strings si and s2 are not equal. si True if si is not the null string. nl -eq n2 True if the integers nl and n2 are numerically equal. nl -ne m2 True if the integer nl is not numerically equal to the integer m2 . nl -gt m2 True if the integer nl is numerically greater than the integer m2 . nl -ge m2 True if the integer nl is numerically greater than or equal to the integer m2. nl -It m2 True if the integer nl is numerically less than the integer m2 . nl -Ie m2 True if the integer nl is numerically less than or equal to the integer m2 . Operators The above primaries may be combined with the following operators: ! Unary negation operator. -a Binary and operator. -o Binary or operator. ( expression ) Parentheses for grouping. -a has higher precedence than -o. Notice that all the operators and flags are separate arguments to test. Notice also that parentheses are meaningful to the Shell and must be escaped. SYSTEM V USAGE The actions of the System V version of test are the same, except for the following primitives: -f filename True if filename exists and is a regular file. -1 string Not supported. SEE ALSO find(l), sh(l) WARNING In the second form of the command (that is, the one that uses [], rather than the word test), the square brackets must be delimited by blanks. Some UNIX systems do not recognize the second form of the command. NOTES The test command is built into the Bourne shell, which chooses the 4.2 BSD or the System V version of test, depending on whether /usr/5bin appears before /usr/bin in the shell’s PATH variable. This is con- sistent with the behavior of other commands present in both /usr/bin and /usr/5bin. The fact that test is built into the shell also means that a program named test cannot be run without specify- ing a pathname; if the program is in the current directory, ./test will suffice. 578 Last change: 15 December 1988 Sun Release 4.1 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) NAME textedit - SunView window- and mouse-based text editor SYNOPSIS textedit [ generic-tool-arguments ] [ -Ea on | off ] [ -adjust_is_pending_delete ] [ -Ei on | off ] t -auto_indent ] [ -Eo on | off ] [ -okay_to_overwrite ] [ -Er on | off ] [ -read only ] t -Ec N ] [ -checkpoint count ] [ -EL lines ] [ -lower_context lines ] [ -Em pixels ] [ -margin pixels ] [ -En N ] [ -number_of Jines lines ] [ -Es N ] [ -scratchwindow lines ] [ -ES N ] [ -multi_click_space radius ] [ -Et N ] [ -tab_width tabstop ] [ -ET N ] [ -multi_click_timeout intrvl ] [ -Eu N ] [ -history_limit max ] [ -EU N ] [ -upper_context lines ] filename AVAILABILITY This command is available with the SunView User's Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION textedit is a mouse-oriented text editor that runs within the SunView environment. It creates a window containing two text subwindows. The top subwindow (referred to as the “scratch” window) can be used to store small pieces of text. The bottom subwindow (referred to as the “edit” window) displays the contents of filename, if given. The name of the file currently being edited is displayed in the left-hand portion of the frame header. The name of the current working directory is displayed in the right-hand portion. OPTIONS generic-tool-arguments textedit accepts the SunView generic tool arguments listed in sunview(l). -Ea on I off -adjust_is_pending_delete Choose whether or not an adjustment to a selection makes the selection “pending-delete.” The default is off. This option corresponds to, and overrides, the adjustispendingdelete Text defaults entry. -Ei on I off -auto_indent Choose whether or not to automatically indent newly-opened lines. The default is off. Corresponds to the auto_indent Text default. -Eo on I off -okay_to_overwrite Set behavior to the Store as New File menu item. If on a Store as New File to the current file is treated as a Save Current File. If off (the standard default). Store as New File operations using the current filename result in an error message. Corresponds to Store_self_is_sa ve . -Er on I off -read_only Turn read-only mode on or off. When on, text cannot be modified. -Ec N -checkpoint count Checkpoint after every count editing operations. If count is 0 (the standard default), no checkpointing takes place. Each character typed, each Paste, and each Cut counts as an editing operation. Corresponds to checkpoint_frequency. Sun Release 4.1 Last change: 2 October 1989 579 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) -EL lines -lower_context lines Specify the minimum number of lines to keep between the caret and the bottom of the text subwindow. The default is 2. Corresponds to lower_context. -Em pixels -margin pixels Set the scrollbar margin width in pixels. The default is 4. Corresponds to left_margin. -En N -number_of_lines lines Set the number of lines in the bottom subwindow. The default is 45. -Es N -scratch_window lines Set the number of lines in the scratch window. A zero value means that there is no scratch window. The standard default is 1. Corresponds to scratch_window. -ESN -multi_click_space radius Set the radius, in pixels, within which clicks must occur to be treated as a multi-click selec- tion. The default is 3 pixels. Corresponds to multi_click_space. -Et N -tabwidth tabstop Set the number of SPACE characters displayed per TAB stop. The default is 8. This option has no effect on the characters in the file. Corresponds to tab_width. -ET N -multi_click_timeout intrvl Set the interval, in milliseconds, within which any two clicks must occur to be treated as a multi-click selection. The default is 390 milliseconds. Corresponds to multi_click_timeout. -Eu N -history_limit max Set the maximum number of editing operations that can be undone or replayed. The default is 50. Corresponds to history_limit. -EU N -uppercontext lines Set the minimum number of lines to keep between the caret and the top of the text subwin- dow. The default is 2. Corresponds to upper_context. USAGE For a description of how to use the facilities of the text subwindows, see the SunView User’ s Guide. Signal Processing If textedit hangs, for whatever reason, you can send a SIGHUP signal to its process ID, which forces it to write any changes (if possible): kill -HUP pid The edits are written to the file texted it. pid in its working directory. If that fails, textedit successively tries to write to a file by that name in /var/tmp, and then /tmp. In addition, whenever textedit catches a fatal signal, such as SIGILL, it tries to write out the edits before aborting. 580 Last change: 2 October 1989 Sun Release 4.1 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) Defaults Options There are several dozen user-specified defaults that affect the behavior of the text-based facilities. See defaultsedit(l) for a complete description. Important defaults entries in the Text category are: Edit_back_char Set the character for erasing to the left of the caret The standard default is DELETE. Note: the tty erase character-setting has no effect on textedit. Text-based tools refer only to the defaults database key settings. Edit_back_word Set the character for erasing the word to the left of the caret. The standard default is CTRL-W. Edit_back_line Set the character for erasing all characters to the left of the caret. The standard default is CTRL-U. Checkpoint_frequency If set to 0 (the standard default) no checkpointing is done. For any value greater than zero, a checkpoint is made each time the indicated number of editing operations has been performed since the last checkpoint. Each character typed, each Paste, and each Cut counts as an editing operation. The checkpoint file has a name of the form: filename %%, where filename is the name of the file being edited. Making a selection In textedit, the mouse is used to specify a selection, which is a character span to operate on. The mouse is also used to position the insertion point and to invoke a menu of commands. The assignment of commands to the mouse buttons is: Mouse button Description LEFT Starts a new selection and moves the insertion point to the end of the selection nearest the mouse cursor. MIDDLE Extends a selection, and moves the insertion point. RIGHT Displays a menu of operations, explained below. There are two types of selections: a primary selection is indicated by video-inversion of the span of charac- ters, and tends to persist. A secondary selection is indicated by underlining the span of characters and only exists while one of the four function keys corresponding to the commands Cut, Find, Paste, or Copy, is depressed. In addition, a selection can be “pending-delete,” as indicated by overlaying the span of characters with a light gray pattern. A selection is made pending-delete by holding the CTRL key while clicking the LEFT or MIDDLE mouse buttons. If a primary selection is pending-delete, it is only deleted when characters are inserted, either by type-in or by Paste or Copy. If a secondary selection is pending-delete, it is deleted when the function key is released, except in the case of the Find, which deselects the secondary selection. You can make adjusted selections switch to pending-delete using the adjustisjpendingdelete defaults entry, or the -Ea option. In this case, CTRL-Middle makes the selection not pending-delete. Commands that operate on the primary selection do so even if the primary selection is not in the window that issued the command. Sun Release 4.1 Last change: 2 October 1989 581 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) Inserting Text and Command Characters For the most part, typing any of the standard keys either inserts the corresponding character at the insertion point, or erases characters. However, certain key combinations are treated as commands. Some of the most useful are: Command Character Description Cut-Primary META-X Erases, and moves to the Clipboard, the primary selection. Find-Primary META-F Searches the text for the pattern specified by the primary selection or by the Clipboard, if there is no primary selection. Copy-to-Clipboard META-C Copies the primary selection to the Clipboard. Paste-Clipboard META-V Inserts the Clipboard contents at the insertion point. Copy-then-Paste META-P Copies the primary selection to the insertion point (through the Clipboard). Go-to-EOF CTRL-RETURN Moves the insertion point to the end of the text, positioning the text so that the insertion point is visible. Function Keys The commands indicated by use of the function keys are: Command Sun-2 1 3 Key Description Stop LI Aborts the current command. Again L2 Repeats the previous editing sequence since a primary selection was made. Undo L4 Undoes a prior editing sequence. Front L5 Makes the window completely visible (or hides it, if it is already exposed). Copy L6 Copies the primary selection, either to the Clipboard or at the closest end of the secondary selection. Open L7 Makes the window iconic (or normal, if it is already iconic). Paste L8 Copies either the secondary selection or the Clipboard at the insertion point. Find L9 Searches for the pattern specified by, in order, the secondary selection, the primary selection, or the Clipboard. Cut L10 Erases, and moves to the Clipboard, either the primary or the secondary selection. CAPSLOCK FI Forces all subsequently typed alphabetic characters to be upper-case. This key is a toggle; striking it a second time undoes the effect of the first strike. Find usually searches the text forwards, towards the end. Holding down the SHIFT key while invoking Find searches backward through the text, towards the beginning. If the pattern is not found before the search encounters either extreme, it “wraps around” and continues from the other extreme. Find starts the search at the appropriate end of the primary selection, if the primary selection is in the subwindow that the search is made in; otherwise it starts at the insertion point, unless the subwindow cannot be edited, in which case it starts at the beginning of the text. CTRL-Find invokes the Find and Replace pop-up frame. The default assignment of function keys can be modified using defaultsedit(l). 582 Last change: 2 October 1989 Sun Release 4.1 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) Menu Items File A pull-right menu item for file operations. Edit A pull-right menu item equivalent of the editing function keys. The Edit submenu provides Again, Undo, Copy, Paste, and Cut (same as function keys L2, L4, L6, L8, and L10). Display A pull-right menu item for controlling the way text is displayed and line display format. Find A pull-right menu item for find and delimiter matching operations. Extras A user definable pull-right menu item. The Extras standard submenu is controlled by /usr/lib/text_extras_menu. This file has the same syntax as .rootmenu file. See sun- view(l). Only those items that are active appear as normal text in the menu; inactive items (which are inappropriate at the time) are “grayed out”. User Defined Commands The file /usr/lib/text_extras_menu specifies filter programs that are included in the text subwindow Extras pull-right menu item. The file "/.textswrc specifies filter programs that are assigned to (available) function keys. These filters are applied to the contents of the primary selection. Their output is entered at the caret. The file /usr/lib/textswrc is a sample containing a set of useful filters. It is not read automatically. ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout textedit. On entry to textedit, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES '/.textswrc / usr/lib/text_extras_menu /usr/bin filename % textedit .pid /tmp/Text* SEE ALSO defaultsedit(l), kill(l), sunview(l) SunView User' s Guide DIAGNOSTICS Cannot open file 'filename', aborting! filename does not exist or cannot be read, textedit produces the following exit status codes: 0 normal termination 1 standard SunView help message was printed 2 help message was requested and printed 3 abnormal termination in response to a signal, usually due to an internal error 4 abnormal termination during initialization, usually due to a missing file or running out of swap space specifies bindings of filters to function keys specifies bindings of filters for the extras menu pull-right items contains useful filters, including shift_lines and capitalize. prior version of filename is available here after a Save Current File menu operation edited version of filename-, generated in response to fatal internal errors editing session logs Sun Release 4.1 Last change: 2 October 1989 583 TEXTEDIT ( 1 ) USER COMMANDS TEXTEDIT ( 1 ) BUGS Multi-click to change the current selection does not work for Adjust Selection. Handling of long lines is incorrect in certain scrolling situations. There is no way to replay any editing sequence except the most recent, ‘textedit newfile’ fails if newfile does not exist. 584 Last change: 2 October 1989 Sun Release 4.1 TEXTEDIT_FILTERS ( 1 ) USER COMMANDS TEXTEDIT JTLTERS ( 1 ) NAME textedit_filters, align_equals, capitalize, insert_brackets, removejjrackets, shift_lines - filters provided with textedit(l) SYNOPSIS align_equals capitalize [ -u I -1 1 -c ] insertjbrackets l r remove brackets l r shiftjines [ -t ] n DESCRIPTION Each of these filters is designed to operate on pending-delete selections in text subwindows. You can use them from within text subwindows either by mapping them to function keys in your .textswrc file or adding them to the text ‘Extras’ menu in your .text_extras_menu file. See the SunView User’s Guide for details. When a filter is used as a command (perhaps in a pipeline), it is applied to the standard input and the filtered text appears on standard output. align_equals lines up the “=’ (equal signs) in C assignment statements. Some programmers feel that this makes for improved readability. It aligns all equal signs with the rightmost equal sign in the selection (or the standard input), by padding with spaces between the sign and the previous nonwhite character; it replaces the selection with the aligned text (or writes this text to the standard output). For instance: big_long_express ion = x; short erexpr = y; z += 1; becomes: big longexpress ion = x; shorter_expr = y; z += 1 ; capitalize changes the capitalization of the selection (or the standard input) and replaces it (or writes to the standard output). The -1 option converts all characters to lower case; -c converts the first letter of each word to upper case; and -u converts all characters to upper case. If no option is specified, then capitalize consults its input to determine what to do. If the text is all capitals, it is converted to all lower case. If the text is all lower case or of mixed cases and contains no white space (such as a NEWLINE, SPACE, or TAB), it is converted to all capitals. If there is white space, then the case of the first character in each word is inverted. insert_brackets surrounds the selection (or the standard input) with the specified character sequences. I and r are the left- and right-bracketing characters, respectively. removebrackets removes the left- and right-bracketing characters, specified by l and r, respectively from the selection (or the standard input). shiftjines adjusts indentation of the selection (or the standard input) by n spaces, and replaces the selec- tion with the adjusted text (or writes to the standard output), shiftjines adjusts to the left when n is nega- tive. If -t is specified, the lines are shifted left or right by n tab stops. The default is 8 spaces per tab stop, but if the first line of the selection (or the standard input) begins with white space, then the tab stops are set to four spaces. Sun Release 4.1 Last change: 19 February 1988 585 TEXTEDIT_FILTERS ( 1 ) USER COMMANDS TEXTEDIT_FILTERS ( 1 ) FILES /tmp/Cap.pzd temporary file used by capitalize /tmp/Ins pid temporary file used by insert_brackets /usr/lib/.text_extras_menu default ‘Extras’ menu /usr/Iib/.textswrc sample function-key mappings SEE ALSO textedit(l) SunView User's Guide 586 Last change: 19 February 1988 Sun Release 4.1 TFTP(IC) USER COMMANDS TFTP(IC) NAME tftp - trivial file transfer program SYNOPSIS tftp [ host ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION tftp is the user interface to the Internet TFTP (Trivial File Transfer Protocol), which allows users to transfer files to and from a remote machine. The remote host may be specified on the command line, in which case tftp uses host as the default host for future transfers (see the connect command below). USAGE Commands Once tftp is running, it issues the prompt: tftp> and recognizes the following commands: connect host-name [ port ] Set the host (and optionally port) for transfers. Note: the TFTP protocol, unlike the FTP protocol, does not maintain connections between transfers; thus, the connect command does not actually create a connection, but merely remembers what host is to be used for transfers. You do not have to use the connect command; the remote host can be specified as part of the get or put commands. mode transfer-mode Set the mode for transfers; transfer-mode may be one of ascii or binary. The default is ascii. put filename put localfile remotefile put filenamel filename2 . . .filenameN remote-directory Transfer a file, or a set of files, to the specified remote file or directory. The destination can be in one of two forms: a filename on the remote host if the host has already been specified, or a string of the form host’.filename to specify both a host and filename at the same time. If the latter form is used, the specified host becomes the default for future transfers. If the remote-directory form is used, the remote host is assumed to be running the UNIX system, get filename get remotename localname get filenamel filename2 . . . filenameN Get a file or set of files from the specified remote sources, source can be in one of two forms: a filename on the remote host if the host has already been specified, or a string of the form host’.filename to specify both a host and filename at the same time. If the latter form is used, the last host specified becomes the default for future transfers. quit Exit tftp. An EOF also exits. verbose Toggle verbose mode. trace Toggle packet tracing. status Show current status. Sun Release 4.1 Last change: 26 February 1988 587 TFTP(IC) USER COMMANDS TFTP(IC) rexmt retransmission-timeout Set the per-packet retransmission timeout, in seconds. timeout total-transmission-timeout Set the total transmission timeout, in seconds. ascii Shorthand for mode ascii. binary Shorthand for mode binary. ? [ command-name . . . ] Print help information. WARNING The default transfer-mode is ascii. This differs from pre-4.0 Sun (and pre-4.3 BSD) releases, so explicit ac- tion must now be taken when transferring non-AScn files such as executable commands. BUGS Because there is no user-login or validation within the TFTP protocol, many remote sites restrict file access in various ways. Approved methods for file access are specific to each site, and therefore cannot be docu- mented here. 588 Last change: 26 February 1988 Sun Release 4.1 TIME (IV) USER COMMANDS TIME (IV) NAME time - time a command SYNOPSIS time [ command ] SYSTEM V SYNOPSIS /usr/5bin/time [ command ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION There are three distinct versions of time: it is built in to the C shell, and is an executable program available in /usr/bin/time and /usr/5bin/time when using the Bourne shell. In each case, times are displayed on the diagnostic output stream. In the case of the C shell, a time command with no command argument simply displays a summary of time used by this shell and its children. When arguments are given the specified simple command is timed and the C shell displays a time summary as described in csh(l). The time commands in /usr/bin/time and /usr/5bin/time time the given command, which must be specified, that is, command is not optional as it is in the C shell’s timing facility. When the command is complete, time displays the elapsed time during the command, the time spent in the system, and the time spent in execution of the command. Times are reported in seconds. The only difference between the ver- sions in /usr/bin/time and /usr/5bin/time is between their output formats; /usr/bin/time prints all three times on the same line, while /usr/5bin/time prints them on separate lines. EXAMPLES The three examples here show the differences between the csh version of time and the versions in /usr/bin/time and /usr/bin/time. The example assumes that csh is the shell in use. example% time wc /usr/share/man/manl/csh.l 1876 11223 65895 /usr/share/man/manl/csh.l 2.7u 0.9s 0:03 91% 3+5k 19+2io lpf+Ow example%/usr/bin/time wc /usr/share/man/manl/csh.l 1876 11223 65895 /usr/share/man/manl/csh.l 4.3 real 2.7 user 1.0 sys example% /usr/5bin/time wc /usr/share/man/manl/csh.l 1876 11223 65895 /usr/share/man/manl/csh.l real 4.3 user 2.7 sys 1.0 example% SEE ALSO csh(l) Sun Release 4. 1 Last change: 19 September 1989 589 TIME (IV) USER COMMANDS TIME (IV) BUGS Elapsed time is accurate to the second, while the CPU times are measured to the 50th second. Thus the sum of the CPU times can be up to a second larger than the elapsed time. When the command being timed is interrupted, the timing values displayed may not always be accurate. 590 Last change: 19 September 1989 Sun Release 4.1 TIP(IC) USER COMMANDS TIP(IC) NAME tip — connect to remote system SYNOPSIS tip [ -v ] [ -speed-entry ] hostname I phone-number DESCRIPTION tip establishes a full-duplex terminal connection to a remote host. Once the connection is established, a remote session using tip behaves like an interactive session on a local terminal. The remote file (described in the remote(5) manual page) contains entries describing remote systems and line speeds used by tip. Each host has a default baud rate for the connection, or you can specify a speed with the -speed-entry command line argument. When phone-number is specified, tip looks for an entry in the remote file of the form: tip -speed-entry When it finds such an entry, it sets the connection speed accordingly. If it finds no such entry, tip interprets -speed-entry as if it were a system name, resulting in an error message. If you omit -speed-entry, tip uses the tipO entry to set a speed for the connection. When establishing the connection tip sends a connection message to the remote system. The default value for this message can be found in the remote file. When tip attempts to connect to a remote system, it opens the associated device with an exclusive-open ioctl(2) call. Thus only one user at a time may access a device. This is to prevent multiple processes from sampling the terminal line. In addition, tip honors the locking protocol used by uucp(lC). When tip starts up it reads commands from the file .tiprc in your home directory. OPTIONS -v Display commands from the .tiprc file as they are executed. USAGE Typed characters are normally transmitted directly to the remote machine (which does the echoing as well). At any time that tip prompts for an argument (for example, during setup of a file transfer) the line typed may be edited with the standard erase and kill characters. A null line in response to a prompt, or an inter- rupt, aborts the dialogue and returns you to the remote machine. Commands A tilde ( ~ ) appearing as the first character of a line is an escape signal which directs tip to perform some special action, tip recognizes the following escape sequences: - D Drop the connection and exit (you may still be logged in on the remote machine). 'c [name] Change directory to name (no argument implies change to your home directory). "! Escape to an interactive shell on the local machine (exiting the shell returns you to tip). '> Copy file from local to remote. “< Copy file from remote to local. Sun Release 4.1 Last change: 16 August 1988 591 TIP (1C) USER COMMANDS TIP (1C) 'p from [ to ] Send a file to a remote host running the UNIX system. When you use the put command, the remote system runs the command string cat > to while tip sends it the from file. If the to file is not specified, the from file name is used. This com- mand is actually a UNIX-system-specific version of the *">’ command. "t from [ to ] Take a file from a remote host running the UNIX system. As in the put command the to file defaults to the from file name if it is not specified. The remote host executes the command string cat from ; echo *A to send the file to tip. 'I Pipe the output from a remote command to a local process. The command string sent to the local system is processed by the shell. "C Connect a program to the remote machine. The command string sent to the program is processed by the shell. The program inherits file descriptors 0 as remote line input, 1 as remote line output, and 2 as tty standard error. "$ Pipe the output from a local process to the remote host. The command string sent to the local sys- tem is processed by the shell. "# Send a BREAK to the remote system. 's Set a variable (see the discussion below). “Z Stop tip (only available when run under a shell that supports job control, such as the C shell). “Y Stop only the “local side” of tip (only available when run under a shell that supports job control, such as the C shell); the “remote side” of tip, the side that displays output from the remote host, is left running. "? Get a summary of the tilde escapes. Copying files requires some cooperation on the part of the remote host. When a ’> or "< escape is used to send a file, tip prompts for a file name (to be transmitted or received) and a command to be sent to the remote system, in case the file is being transferred from the remote system. The default end of transmis- sion string for transferring a file from the local system to the remote is specified as the oe capability in the remote(5) file, but may be changed by the set command. While tip is transferring a file the number of lines transferred will be continuously displayed on the screen. A file transfer may be aborted with an inter- rupt. AUTO CALL UNITS tip may be used to dial up remote systems using a number of auto-call unit’s (ACU’s). When the remote system description contains the du capability, tip uses the call-unit (cu), ACU type (at), and phone numbers (pn) supplied. Normally tip displays verbose messages as it dials. See remote(5) for details of the remote host specification. Depending on the type of auto-dialer being used to establish a connection the remote host may have gar- bage characters sent to it upon connection. The user should never assume that the first characters typed to the foreign host are the first ones presented to it. The recommended practice is to immediately type a kill character upon establishing a connection (most UNIX systems either support @ or CTRL-U as the initial kill character). tip currently supports the Ventel MD-212+ modem and DC Hayes-compatible modems. 592 Last change: 16 August 1988 Sun Release 4.1 ■np(ic) USER COMMANDS TIP ( 1C ) REMOTE HOST DESCRIPTIONS Descriptions of remote hosts are normally located in the system-wide file /etc/remote. However, a user may maintain personal description files (and phone numbers) by defining and exporting the REMOTE shell variable. The remote file must be readable by tip, but a secondary file describing phone numbers may be maintained readable only by the user. This secondary phone number file is /etc/phones, unless the shell variable PHONES is defined and exported. As described in remote(5), the phones file is read when the host description’s phone number(s) capability is an ‘@\ The phone number file contains lines of the form: system-name phone-number Each phone number found for a system is tried until either a connection is established, or an end of file is reached. Phone numbers are constructed from ‘0123456789-=*’, where the *=’ and ‘*’ are used to indi- cate a second dial tone should be waited for (ACU dependent). TIP INTERNAL VARIABLES tip maintains a set of variables which are used in normal operation. Some of these variables are read-only to normal users (root is allowed to change anything of interest). Variables may be displayed and set through the "s escape. The syntax for variables is patterned after vi(l) and mail(l). Supplying all as an argument to the "s escape displays all variables that the user can read. Alternatively, the user may request display of a particular variable by attaching a ? to the end. For example ‘"s escape?’ displays the current escape character. Variables are numeric, string, character, or Boolean values. Boolean variables are set merely by specifying their name. They may be reset by prepending a ! to the name. Other variable types are set by appending an = and the value. The entire assignment must not have any blanks in it. A single set command may be used to interrogate as well as set a number of variables. Variables may be initialized at run time by placing set commands (without the "s prefix) in a .tiprc file in one’s home directory. The -v option makes tip display the sets as they are made. Comments preceded by a # sign can appear in the .tiprc file. Finally, the variable names must either be completely specified or an abbreviation may be given. The fol- lowing list details those variables known to tip. beautify (bool) Discard unprintable characters when a session is being scripted; abbreviated be. If the nb capability is present, beautify is initially set to off-, otherwise, beautify is initially set to on. baudrate (num) The baud rate at which the connection was established; abbreviated ba. If a baud rate was specified on the command line, baudrate is initially set to the specified value; otherwise, if the br capability is present, baudrate is initially set to the value of that capability; otherwise, baudrate is set to 300 baud. Once tip has been started, baudrate can only changed by the super-user. dialtimeout (num) When dialing a phone number, the time (in seconds) to wait for a connection to be esta- blished; abbreviated dial, dialtimeout is initially set to 60 seconds, and can only changed by the super-user. disconnect (str) The string to send to the remote host to disconnect from it; abbreviated di. If the di capability is present, disconnect is initially set to the value of that capability; otherwise, disconnect is set to a null string (" "). echocheck (bool) Synchronize with the remote host during file transfer by waiting for the echo of the last character transmitted; abbreviated ec. If the ec capability is present, echocheck is initially set to on\ otherwise, echocheck is initially set to off. Sun Release 4. 1 Last change: 16 August 1988 593 TIP(IC) USER COMMANDS TIP(IC) eofread (str) The set of characters which signify an end-of-transmission during a '< file transfer command; abbreviated eofr. If the ie capability is present, eofread is initially set to the value of that capabil- ity; otherwise, eofread is set to a null string eofwrite (str) The string sent to indicate end-of-transmission during a *> file transfer command; abbreviated eofw. If the oe capability is present, eofread is initially set to the value of that capability; other- wise, eofread is set to a null string eol (str) The set of characters which indicate an end-of-line. tip will recognize escape characters only after an end-of-line. If the el capability is present, eol is initially set to the value of that capability; otherwise, eol is set to a null string (""). escape (char) The command prefix (escape) character; abbreviated es. If the es capability is present, escape is initially set to the value of that capability; otherwise, escape is set to ‘ ‘ etimeout (num) The amount of time, in seconds, that tip should wait for the echo-check response when echocheck is set; abbreviated et. If the et capability is present, etimeout is initially set to the value of that capability; otherwise, etimeout is set to 10 seconds. exceptions (str) The set of characters which should not be discarded due to the beautification switch; abbrevi- ated ex. If the ex capability is present, exceptions is initially set to the value of that capability; otherwise, exceptions is set to ‘\t\n\f\b’. force (char) The character used to force literal data transmission; abbreviated fo. If the fo capability is present, force is initially set to the value of that capability; otherwise, force is set to \377 (which disables it). framesize (num) The amount of data (in bytes) to buffer between file system writes when receiving files; abbreviated fr. If the fs capability is present, framesize is initially set to the value of that capabil- ity; otherwise, framesize is set to 1024. halfduplex (bool) Do local echoing because the host is half-duplex; abbreviated hdx. If the hd capability is present, halfduplex is initially set to on; otherwise, halfduplex is initially set to off . hardwareflow (bool) Do hardware flow control; abbreviated hf. If the hf capability is present, hardwareflow is initially set to on; otherwise, hardwareflowcontrol is initially set to off. host (str) The name of the host to which you are connected; abbreviated ho. host is permanendy set to the name given on the command line or in the HOST environment variable. localecho (bool) A synonym for halfduplex; abbreviated le. log (str) The name of the file to which to log information about outgoing phone calls, log is initially set to /var/adm/aculog, and can only be inspected or changed by the super-user. parity (str) The parity to be generated and checked when talking to the remote host; abbreviated par. The possible values are: none zero Parity is not checked on input, and the parity bit is set to zero on output, one Parity is not checked on input, and the parity bit is set to one on output. 594 Last change: 16 August 1988 Sun Release 4.1 TIP(IC) USER COMMANDS TIP ( 1C) even Even parity is checked for on input and generated on output. odd Odd parity is checked for on input and generated on output. If the pa capability is present, parity is initially set to the value of that capability; otherwise, par- ity is set to none. phones The file in which to find hidden phone numbers. If the environment variable PHONES is set, phones is set to the value of PHONES; otherwise, phones is set to /etc/phones. The value of phones cannot be changed from within tip. prompt (char) The character which indicates an end-of-line on the remote host; abbreviated pr. This value is used to synchronize during data transfers. The count of lines transferred during a file transfer command is based on receipt of this character. If the pr capability is present, prompt is initially set to the value of that capability; otherwise, prompt is set to \n. raise (bool) Upper case mapping mode; abbreviated ra. When this mode is enabled, all lower case letters will be mapped to upper case by tip for transmission to the remote machine. If the ra capa- bility is present, raise is initially set to on; otherwise, raise is initially set to off. raisechar (char) The input character used to toggle upper case mapping mode; abbreviated rc. If the rc capability is present, raisechar is initially set to the value of that capability; otherwise, raisechar is set to \377 (which disables it). rawftp (bool) Send all characters during file transfers; do not filter non-printable characters, and do not do translations like \n to \r. Abbreviated raw. If the rw capability is present, rawftp is initially set to on; otherwise, rawftp is initially set to off. record (str) The name of the file in which a session script is recorded; abbreviated rec. If the re capabil- ity is present, record is initially set to the value of that capability; otherwise, record is set to tip .record. remote The file in which to find descriptions of remote systems. If the environment variable REMOTE is set, remote is set to the value of REMOTE; otherwise, remote is set to /etc/remote. The value of remote cannot be changed from within tip. script (bool) Session scripting mode; abbreviated sc. When script is on, tip will record everything transmitted by the remote machine in the script record file specified in record. If the beautify switch is on, only printable ASCII characters will be included in the script file (those characters between 040 and 0177). The variable exceptions is used to indicate characters which are an exception to the normal beautification rules. If the sc capability is present, script is initially set to on; otherwise, script is initially set to off. tabexpand (bool) Expand TAB characters to SPACE characters during file transfers; abbreviated tab. When tabexpand is on, each tab is expanded to 8 SPACE characters. If the tb capability is present, tabexpand is initially set to on; otherwise, tabexpand is initially set to off. tandem (bool) Use XON/XOFF flow control to limit the rate that data is sent by the remote host; abbrevi- ated ta. If the nt capability is present, tandem is initially set to off-, otherwise, tandem is initially set to on. verbose (bool) Verbose mode; abbreviated verb; When verbose mode is enabled, tip prints messages while dialing, shows the current number of lines transferred during a file transfer operations, and more. If the nv capability is present, verbose is initially set to off-, otherwise, verbose is initially set to on. SHELL (str) The name of the shell to use for the '! command; default value is /bin/sh, or taken from the environment. HOME (str) The home directory to use for the "c command; default value is taken from the environment. Sun Release 4.1 Last change: 16 August 1988 595 TIP(IC) USER COMMANDS TIP (1C) EXAMPLES An example of the dialogue used to transfer files is given below. arpa% tip monet [connected] . . .(assume we are talking to a UNIX system). . . ucbmonet login: sam Password: monet % cat > sylvester.c "> Filename: Sylvester .c 32 lines transferred in 1 minute 3 seconds monet % monet % "< Filename: reply .c List command for remote host: cat reply .c 65 lines transferred in 2 minutes monet % . . .(or, equivalently). . . monet % "p sylvester.c . . .(actually echoes as "[put] sylvester.c). . . 32 lines transferred in 1 minute 3 seconds monet % monet % “t reply .c . . .(actually echoes as '[take] reply. c). . . 65 lines transferred in 2 minutes monet % ...(to print a file locally). . . monet% "|Local command: pr -h Sylvester .c | Ipr List command for remote host: cat sylvester.c monet% " A D [EOT] . . .(back on the local system). . . ENVIRONMENT The following environment variables are read by tip. REMOTE The location of the remote file. PHONES The location of the file containing private phone numbers. HOST A default host to connect to. HOME One’s log-in directory (for chdirs). SHELL The shell to fork on a *'!’ escape. FILES "/.tiprc /var/spool/locks/LCK /var/adm/aculog /etc/phones /etc/remote initialization file lock file to avoid conflicts with UUCP file in which outgoing calls are logged 596 Last change: 16 August 1988 Sun Release 4.1 TTP( 1C) USER COMMANDS TIP(IC) SEE ALSO cu(lC), mail(l), uucp(lC), vi(l), ioctl(2), phones(5), remote(5) BUGS There are two additional variables chardelay and linedelay that are currently not implemented. Sun Release 4. 1 Last change: 16 August 1988 597 TOOLPLACES ( 1 ) USER COMMANDS TOOLPLACES ( 1 ) NAME toolplaces - display current SunView window locations, sizes, and other attributes SYNOPSIS toolplaces [ -o|0|u ] [ -help ] AVAILABILITY This command is available with the SunView User’ s Guide software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION toolplaces generates position, size, label, and program attributes for the windows running on a SunView screen at the time of execution, (toolplaces does not work when SunView is not running.) Many people redirect standard output from toolplaces to the .sunview file, so as to reuse the current win- dow system attributes each time they execute sunview(l). For each window on the screen at execution time, toolplaces shows: the tool name the “open” window position the size of the window in pixels the “closed,” or icon, window position an indicator of whether the window is open or closed the label at the top of the window the name of the program running in the window, if a program is running there any flags or options to a program running in the window toolplaces describes each window on one output line, as long as necessary, using the current sunview for- mat. Current sunview format consists of window tool descriptions, one per line, as in this example (the \ indi- cates that the current line continues on the next line): shelltool -Wp 491 795 -Ws 580 87 -WP 0 836 -C clock -Wp 120 120 -Ws 122 55 -WP 1086 826 -Wi \ -W1 " open clock" -S -r -d wdm shelltool -Wp 491 166 -Ws 650 567 -WP 702 836 \ -Wl due rlogin due shelltool -Wp 0 0 -Ws 650 525 -WP 64 836 \ -Wl "Small Window: /usr/bin/csh" shelltool -Wp 501 0 -Ws 650 812 -WP 128 836 \ -Wl "Big Window: /usr/bin/csh" OPTIONS -o Show window tool information in the old suntools format for window attributes, but specifies the appropriate tool names for each tool. -O Show window tool information in the old suntools format for window attributes, specifying tool- name as the name for each tool. -u Show the updated window tool information in the order that you originally specified it. -help Show help information preceding tool attributes. 598 Last change: 12 January 1988 Sun Release 4.1 TOOLPLACES ( 1 ) USER COMMANDS TOOLPLACES ( 1 ) FILES ‘/.sunview format file for sunview(l) SEE ALSO sunview(l) SunView User’ s Guide Sun Release 4. 1 Last change: 12 January 1988 599 TOUCH (IV) USER COMMANDS TOUCH (IV) NAME touch - update the access and modification times of a file SYNOPSIS touch [ -c ] [ -f ] filename . . . SYSTEM V SYNOPSIS /usr/5bin/touch [ -acm ] [ date-time ] filename.. . AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION touch sets the access and modification times of each argument to the current time. A file is created if it does not already exist. touch is valuable when used in conjunction with make(l), where, for instance, you might want to force a complete rebuild of a program composed of many pieces. In such a case, you might type: example% touch *.c exam pie % make make(l) would then see that all the ,c files were more recent than the corresponding .o files, and would start the compilation from scratch. OPTIONS -c Do not create filename if it does not exist. -f Attempt to force the touch in spite of read and write permissions on filename . SYSTEM V OPTIONS Options must be grouped to form the first argument. The date-time argument takes the form: mmddhhmm\yy] and updates the modification time to that specified, rather than the current time. The first mm is the month, dd is the day of the month, hh is the hour, and the second mm is the minute. If yy is specified, it is the last two digits of the year. If omitted, the current year is assumed. -a Update only the access time. -c Do not create filename if it does not exist. -m Update only the modification time. SEE ALSO make(l), utimes(2) BUGS It is difficult to touch a file whose name consists entirely of digits in the System V touch, as it will interpret the first such non-flag argument as a time. You must ensure that there is a character in the name which is not a digit, by specifying it as ./name rather than name. 600 Last change: 19 September 1989 Sun Release 4.1 TPUT(IV) USER COMMANDS TPUT(IV) NAME tput - initialize a terminal or query the terminfo database SYNOPSIS /usr/5bin/tput [ -T type ] capability [ parameter ...] /usr/5bin/tput [ -T type ] init /usr/5bin/tput [ -T type ] longname /usr/5bin/tput [ -Ttype ] reset AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION tput uses the terminfo(5V) database to make the values of terminal-dependent capabilities and information available to the shell, to initialize or reset the terminal, or return the long name of the requested terminal type. Normally, the terminal type is taken from the environment variable TERM; if the -T type option is specified, the terminal type is taken from that option. tput displays a string if the given capability is a string capability, or an integer if it is an integer capability; it displays no output if the capability is a boolean. If capability is a boolean, tput returns true (0) if that capability is set, or false (1) otherwise. If capability is a string, tput returns true (0) if that capability is set, or false (1) otherwise. If capability is an integer, a value of true (0) is returned whether or not the capability is set for the terminal. To determine if an integer capability is set, you must examine the standard output. For a complete list of capabilities and the capability associated with each, see terminfo(5V). If capability is a string capability that takes parameters, the parameter arguments are instantiated into the string. An all-numeric parameter argument is passed to the attribute as a number. OPTIONS -Ttype Indicate the type of terminal. If this option is supplied, the environment variables LINES and COLUMNS are not used. init If the terminfo database is present and an entry for the user’s terminal exists, emit the terminal’s initialization strings, set up any delays specified, and turn the expansion of TAB characters on or off, as specified by the terminal’s entry in the terminfo database. If the terminal has a TAB char- acter, and either has a capability for setting TAB characters or initially has its TAB characters set every 8 SPACE characters, expansion of TAB characters is turned off, otherwise expansion of TAB characters is turned on. If expansion of TAB characters is turned on, and the terminal has a capa- bility for setting TAB characters, TAB stops are set to every eight columns. If an entry does not contain the information needed for any of these actions, that action is silently skipped. reset Emit the terminal’s reset strings, and set up delays and TAB characters as specified. If the reset strings are not present, but initialization strings are, the initialization strings are used. longname If the terminfo database is present and an entry for the user’s terminal exists, emit the long name of the terminal. The long name is the last name in the first line of the terminal’s description in the terminfo database. Sun Release 4.1 Last change: 20 January 1988 601 TPUT(IV) USER COMMANDS TPUT(IV) EXIT CODES 0 The boolean or string capability is set, or the capability is an integer type and is present. 1 The capability is not set. 2 Usage error. 3 The terminal is of an unknown type, or the terminfo database is not present. 4 Unknown terminfo capability. -1 The integer capability is not defined for this terminal type. EXAMPLES tput init tput -Tsun reset tput cup 0 0 tput clear tput cols tput -Tsun cols bold=‘tput smso‘ offbold=‘tput rmso‘ tput he tput cup 23 4 tput Iongname Initialize the terminal according to the type of terminal in the environmental vari- able TERM. This command can be included in a .profile or .login file. Reset a Sun workstation console, shelltool(l) window, or cmdtool(l) window, overriding the type of terminal in the environmental variable TERM. Send the sequence to move the cursor to row 0, column 0 (the upper left comer of the screen, usually known as the “home” cursor position). Echo the clear-screen sequence for the current terminal. Print the number of columns for the current terminal. Print the number of columns for the Sun workstation console or subwindow. Set the shell variables bold, to begin stand-out mode sequence, and offbold, to end standout mode sequence, for the current terminal. This might be followed by a prompt: echo "${bold} Please type in your name: ${offbold}\c" Set exit code to indicate if the current terminal is a hardcopy terminal. Send the sequence to move the cursor to row 23, column 4. Print the long name from the terminfo database for the type of terminal specified in the environmental variable TERM. FILES /usr/shar e/lib/ terminfo/?/* compiled terminal description database /usr/5include/curses.h curses(3V) header file /usr/5include/term.h terminfo(5V) header file /usr/shar e/lib/tabset/* TAB settings for some terminals, in a format appropriate to be output to the termi- nal (escape sequences that set margins and TAB characters); for more information, see the Tabs and Initialization section of terminfo(5V). .login .profile SEE ALSO cmdtool(l), shelltool(l), stty(lV), curses(3V), terminfo(5V) 602 Last change: 20 January 1988 Sun Release 4.1 TR(1V) USER COMMANDS TR(1V) NAME tr - translate characters SYNOPSIS tr [ — cds ] [ stringl [ string2 ] ] SYSTEM V SYNOPSIS /usr/5bin/tr [ -cds ] [ stringl [ string2 ] ] AVAILABILITY The System V version of this command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION tr copies the standard input to the standard output with substitution or deletion of selected characters. The arguments stringl and string2 are considered sets of characters. Any input character found in stringl is mapped into the character in the corresponding position within string2 . When string2 is short, it is padded to the length of stringl by duplicating its last character. In either string the notation: a-b denotes a range of characters from a to b in increasing ASCII order. The character \ , followed by 1, 2 or 3 octal digits stands for the character whose ASCII code is given by those digits. As with the shell, the escape character \ , followed by any other character, escapes any special meaning for that character. SYSTEM V DESCRIPTION When string2 is short, characters in stringl with no corresponding character in string2 are not translated. In either string the following abbreviation conventions introduce ranges of characters or repeated charac- ters into the strings. Note: in the System V version, square brackets are required to specify a range. [a-z] Stands for the string of characters whose ASCII codes run from character a to character z, in- clusive. [a*n] Stands for n repetitions of a. If the first digit of n is 0, n is considered octal; otherwise, n is taken to be decimal. A zero or missing n is taken to be huge; this facility is useful for padding string2 . OPTIONS Any combination of the options -c, -d, or -s may be used: -c Complement the set of characters in stringl with respect to the universe of characters whose ASCfi codes are 01 through 0377 octal; -d Delete all input characters in stringl . -s Squeeze all strings of repeated output characters that are in string2 to single characters. EXAMPLE The following example creates a list of all the words in filenamel one per line in filename2 , where a word is taken to be a maximal string of alphabetics. The second string is quoted to protect * \ ’ from the shell. 012 is the ASCII code for NEWLINE. tr -cs A-Za-z '\012' < filenamel >filename2 In the System V version, this would be specified as: tr-cs '[A-Z] [a-z]' '[\012*]' < file name l>filename2 Sun Release 4.1 Last change: 9 September 1987 603 TR(1V) USER COMMANDS TR(1V) SEE ALSO ed(l), expand(l), ascii(7) BUGS Will not handle ASCII NUL in stringl or string2. tr always deletes NUL from input. 604 Last change: 9 September 1987 Sun Release 4.1 TRACE ( 1 ) USER COMMANDS TRACE ( 1 ) NAME trace - trace system calls and signals SYNOPSIS trace [ -ct ] [ -o filename ] command trace [ -ct ] [ -o filename ] -p pid DESCRIPTION trace runs the specified command until it exits. It intercepts the system calls and signals of a process. The name of the system call, its arguments and result are listed on the standard output. Each line in the trace contains the system call name, followed by its arguments in parentheses and its result. Error returns (result = -1) have the error name and error message appended. Signals are printed as a signal name followed by the signal number. Arguments are printed according to their type. Structure pointers are always printed as hex addresses. Character pointers are dereferenced and printed as a quoted string. Non- printing characters in strings are represented by escape codes. Only the first 32 bytes of strings are printed; longer strings have two dots appended following the closing quote. The quick brown fox jumps over t . . Strings with more than 50% non-printing characters are assumed to contain binary data and are represented by a null string followed by two dots. »t ft OPTIONS -c Print a quick summary of system call and signal counts, instead of printing a full trace. -t Prefix each line of the trace with the time of day. -o filename Write the trace output to the file filename rather than to the standard output. -p pid Attach to the process with the process ID pid and begin tracing. The trace may be ter- minated at any time by a keyboard interrupt signal (CTRL-C); trace will respond by detach- ing itself from the traced process leaving it to continue running. EXAMPLES example% trace date gettimeofday (0x21474, 0x2147c) = 0 gettimeofday (0x21474, 0) = 0 gettimeofday (0xefffc78, 0x214ac) = 0 ioctl (1, 0x40067408, OxefffalO) = -1 ENOTTY (Inappropriate ioctl for device) fstat (1, 0xefffa30) = 0 getpagesize 0 = 8192 brk (0x27640) = 0 close (0) = 0 Thu Dec 4 14:16:36 PST 1986 write (1, "Thu Dec 4 14:16:36 PST 1986\n", 29) = 29 close (1) = 0 close (2) = 0 exit (0) = ? example% SEE ALSO ptrace(2) Sun Release 4.1 Last change: 8 August 1989 605 TRACE ( 1 ) USER COMMANDS TRACE ( 1 ) NOTES A process that has a system call trace applied to it with the -p option will receive a SIGSTOP. This signal may interrupt a system call that is not restartable. This may have an unpredictable effect on the process if the process takes no action to restart the system call. BUGS Programs that use the setuid bit do not have effective user ID privileges while being traced. Child processes of a traced process are not traced. A traced process ignores SIGSTOP. A traced process runs slowly. 606 Last change: 8 August 1989 Sun Release 4.1 TRAFFIC (1C) USER COMMANDS TRAFFIC (1C) NAME traffic — SunView program to display Ethernet traffic SYNOPSIS traffic [ -h host ] [ -s subwindows ] AVAILABILITY This command is available when both the Networking and the SunView User s software options are in- stalled. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION traffic graphically displays ethemet traffic. It gets statistics from etherd(8C), running on machine host. The tool is divided into subwindows, each giving a different view of network traffic. OPTIONS -h host Specify a host from which to get statistics. The default value of host is the machine that traffic is running on. -s subwindows Specify the number of subwindows to display initially. The default value of subwindows is 1. SUB WINDOWS To the right of each subwindow is a panel that selects what the subwindow is viewing. When Size is checked, than the size distribution of packets is displayed. Proto is for protocol, Src is for source of pack- et, and Dst is for destination of packet. Since it is not possible to show all possible sources, when Src is selected, only the 8 highest sources are displayed (and similarly for Dst ). For each of these choices, the distribution is displayed by a histogram. The panel above each subwindow controls characteristics of the histograms. At the left of the panel is a shaded square, corresponding to one of the two shades of bars in the histogram. You can switch the shade by either clicking on the square with the left button, or bringing up a menu over the square with the right mouse button. When the light colored square is visible, then the slider in the center of the panel controls how often the light colored bars are up- dated. When the dark square is visible, then the slider refers to the dark bars of the histogram. To the right of the slider is a choice of Abs versus Rel. This selects whether the height of the histogram is Absolute in packets per second, or Relative in percent of total packets on the ethemet. Next in the panel are three small horizontal bars. When selected (that is, when a check mark appears to the left of the three bars), a horizon- tal grid appears on the histogram. Finally the button marked Delete Me will delete the subwindow. The right hand panel also has a choice for Load Load is represented as a strip chart, rather than a histo- gram. The maximum value of the graph represents a load of 100%, that is 10 megabits per second on the ethemet. When Load is selected, there is only one slider, and no Rel versus Abs choice. At the very top of the tool is a panel that contains filters, as well as a Split button that splits the tool and creates a new subwindow, and a Quit button that exits the tool. The filters apply to all the subwindows. When a filter is selected, a check mark appears to the left of the word Filter. There can be more than one filter active at the same time. The meaning of each filter is as follows. Src is a host or net, which can be specified either by name or address (similarly for Dst). Proto is an ip protocol, and can either be a name (such as udp, icmp ) or a number. Lnth is either a packet length, or a range of lengths separated by a dash. SEE ALSO etherd(8C) BUGS If multiple copies of traffic are using the same copy of etherd, and one of them invokes a filter, then all the copies of traffic will be filtered. Sun Release 4.1 Last change: 21 December 1987 607 TROFF(l) USER COMMANDS TROFF(l) NAME troff - typeset or format documents SYNOPSIS troff [ -abfiqtwz ] [ -m package ] [ -nN ] [ -opagelist ] [ -p N ] [ -raN ] [ -sN ] [filenames ] . . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION troff formats text in the filenames. For historical reasons, output goes to a CAT/4 phototypesetter attached to /dev/cat, but nobody uses a CAT/4 anymore. Ordinarily, postprocessing software converts output to a form that can be printed on newer typesetters or laser printers. Default font width tables correspond to Times Roman on PostScript™ printers. See also the nroff(l) manual page, which describes a formatter for typewriter-like devices. Input to treff is expected to consist of text interspersed with formatting requests and macros. If no filename argument is present, troff reads standard input. A as a filename argument indicates that stan- dard input is to be read at that point in the list of input files; troff reads the files named ahead of the in the arguments list, then text from the standard input, and then text from the files named after the If the file /etc/adm/tracct is writable, troff keeps printer accounting records there. The integrity of that file may be secured by making troff a “set-user-ID” program (see chmod(lV) for details on the setuid per- mission bit.) OPTIONS Options may appear in any order, but they all must appear before the first filename . -a Send a printable ASCII approximation of the results to the standard output. -i Read the standard input after the input files are exhausted. -q Disable echoing during a .rd request. -t Direct output to the standard output instead of the printer. Since this output is it is generally redirected to lpr -t. non-ASCH -m package Prepend the macro file /usr/lib/tmac/tmac.pac£age to the input filenames. most references to macro packages include the leading “m” as part of the man(7) macro package resides in /usr/lib/tmac/tmac.an). (Note that name; the -nN Number first generated page N. -olist 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 begin- ning to page N; and a final N- means from N to the end. -raN Set register a (one-character) to N. Some options of troff only apply if you have a CAT/4 typesetter attached to your system. These options remain present for backward compatibility. However, this version of troff does not support this typesetter by default. -b Report whether the typesetter is busy or available. No text processing is done. -f Refrain from feeding paper out and stopping at the end of the print job on the typesetter, -w Wait until typesetter is available, if currently busy. -z Suppress all formatted output. Display only terminal messages produced by .tm requests and diagnostics. 608 Last change: 21 December 1987 Sun Release 4.1 TROFF(l) USER COMMANDS TROFF(l) -pN Print all characters in point size N while retaining all prescribed spacings and motions, to reduce elapsed time on the typesetter. -s N Stop the phototypesetter every N pages, troff produces a trailer so you can change cassettes; resume by pressing the typesetter’s start button. FILES /tmp/ta* /usr/Iib/tmac/tmac.* /usr/lib/term/* /usr/lib/font/* /dev/cat /etc/adm/tracct SEE ALSO checknr(l), chmod(lV), col(lV), eqn(l), lpr(l), nroff(l), tbl(l), printcap(5), man(7), me(7), ms(7), Ipd(8) Formatting Documents Using nrof f and troff DIAGNOSTICS No / dev/cat: try -t or -a The CAT/4 typesetter is not accessible from your machine. Combine the -t option of troff with the -t option of lpr(l) to get output on a laser printer or typesetter. For information on how to inform lpd(8) of a PostScript printer attached to a remote host, see printcap(5). NOTES troff is not 8-bit clean because it is by design based on 7-bit ASCII. temporary file standard macro files terminal driving tables for nroff font width tables for alternate mounted troff fonts phototypesetter accounting statistics for /dev/cat Sun Release 4. 1 Last change: 21 December 1987 609 TRUE ( 1 ) USER COMMANDS TRUE ( 1 ) NAME true, false - 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 The following Bourne shell script will be executed while the case status is “true”. while true do command list done SEE ALSO csh(l), sh(l) EXIT STATUS true has exit status 0. false has exit status 1. 610 Last change: 9 September 1987 Sun Release 4.1 TSET(l) USER COMMANDS TSET(l) NAME tset, reset - establish or restore terminal characteristics SYNOPSIS tset [ -InQrsS ] [ -ec ] [ -kc ] [ -m [port-lD [ baudrate] : type ] . . . ] [type] reset [ — ] [ — ec ] [ — I ] [ — kc ] [ — n ] [ -Q ] [ — r ] [ -s ] [ — S ] -m [ indent ] [ test baudrate ]: type ] . . . [ type ] DESCRIPTION tset sets up your terminal, typically when you first log in. It does terminal dependent processing such as setting erase and kill characters, setting or resetting delays, sending any sequences needed to properly ini- tialized the terminal, and the like, tset first determines the type of terminal involved, and then does neces- sary initializations and mode settings. The type of terminal attached to each port is specified in the /etc/ttytab database. Type names for terminals may be found in the termcap(5) database. If a port is not wired permanently to a specific terminal (not hardwired) it is given an appropriate generic identifier such as dialup. reset clears the terminal settings by turning off CBREAK and RAW modes, output delays and parity check- ing, turns on NEWLINE translation, echo and TAB expansion, and restores undefined special characters to their default state. It then sets the modes as usual, based on the terminal type (which will probably over- ride some of the above). (See stty(lV) for more information.) All arguments to tset may be used with reset, reset also uses the rs= and rf= (reset string and file) instead of the initialization string and file from /etc/termcap. This is useful after a program dies and leaves the terminal in a funny state. Often in this situation, characters will not echo as you type them. You may have to type ‘LINEFEED reset LINEFEED’ since ‘RETURN’ may not work. When no arguments are specified, tset reads the terminal type from the TERM environment variable and re-initializes the terminal, and performs initialization of mode, environment and other options at login time to determine the terminal type and set up terminal modes. When used in a startup script (.profile for sh(l) users or .login for csh(l) users) it is desirable to give infor- mation about the type of terminal you will usually use on ports that are not hardwired. These ports are identified in /etc/ttyab as dialup or plugboard, etc. Any of the alternate generic names given in /etc/termcap may be used for the identifier. Refer to the -m option under OPTIONS for more information. If no mapping applies and a final type option, not preceded by a -m, is given on the command line then that type is used; otherwise the type found in the /etc/ttytab database is used as the terminal type. This should always be the case for hardwired ports. It is usually desirable to return the terminal type, as finally determined by tset, and information about the terminal’s capabilities, to a shell’s environment. This can be done using the -, -s, or -S options. (Refer to OPTIONS for more information.) For the Bourne shell, put this command in your .profile file: eval 'tset -s options... ' or using the C shell, put this command in your .login file: eval 'tset — s options... ' With the C shell, it is also convenient to make an alias in your .cshrc file: alias tset 'eval 'tset -s \!* w This also allows the command: tset 2621 to be invoked at any time to set the terminal and environment. Note to Bourne Shell users: It is not possi- ble to get this aliasing effect with a shell script, because shell scripts cannot set the environment of their parent. If a process could set its parent’s environment, none of this nonsense would be necessary in the first place. Sun Release 4. 1 Last change: 18 December 1989 611 TSET(l) USER COMMANDS TSET(l) Once the terminal type is known, tset sets the terminal driver mode. This normally involves sending an initialization sequence to the terminal, setting the single character erase (and optionally the line-kill (full line erase)) characters, and setting special character delays. TAB and NEWLINE expansion are turned off during transmission of the terminal initialization sequence. On terminals that can backspace but not overstrike (such as a CRT), and when the erase character is *#’, the erase character is changed as if -e had been used. OPTIONS - The name of the terminal finally decided upon is output on the standard output. This is intended to be captured by the shell and placed in the TERM environment variable. -ec Set the erase character to be the named character c on all terminals. Default is the backspace key on the keyboard, usually “H (CTRL-H). The character c can either be typed directly, or entered using the circumflex-character notation used here. -ic Set the interrupt character to be the named character c on all terminals. Default is C (CTRL-C). The character c can either be typed directly, or entered using the circumflex-character notation used here. -I Suppress transmitting terminal-initialization strings. -kc Set the line kill character to be the named character c on all terminals. Default is 'U (CTRL-U). The kill character is left alone if -k is not specified. Control characters can be specified by prefixing the alphabetical character with a circumflex (as in CTRL-U) instead of entering the actual control key itself. This allows you to specify control keys that are currently assigned. -n Specify that the new tty driver modes should be initialized for this terminal. Probably useless since stty new is the default. -Q Suppress printing the ‘Erase set to’ and ‘Kill set to’ messages. -r In addition to other actions, reports the terminal type. -s Output commands to set and export TERM and TERMCAP. This can be used with set noglob eval 'tset -s unset noglob to bring the terminal information into the environment. Doing so makes programs such as vi(l) start up faster. If the SHELL environment variable ends with csh, C shell commands are output, otherwise Bourne shell commands are output. -S Similar to the -s option, but produces two strings containing suitable values for the (environment) variables TERM and TERMCAP, respectively, and can be used as follows: set noglob set t=('tset -S...') setenv TERM $t[l] setenv TERMCAP ”$t[2]" unset t unset noglob Since -s loads these values, its use is preferred. If the SHELL environment variable does not end with csh, -S produces the same Bourne shell commands that -s does. 612 Last change: 18 December 1989 Sun Release 4.1 TSET(l) USER COMMANDS TSET(l) — m \port-lD[baudrate\ : type] ... Specify (map) a terminal type when connected to a generic port (such as dialup or plugboard ) identified by port-ID. The baudrate argument can be used to check the baudrate of the port and set the terminal type accordingly. The target rate is prefixed by any combination of the following operators to specify the conditions under which the mapping is made: > Greater than @ Equals or “at” < Less than ! It is not the case that (negates the above operators) ? Prompt for the terminal type. If no response is given, then type is selected by default. In the following example, the terminal type is set to adm3a if the port is a dialup with a speed of greater than 300 or to dw2 if the port is a dialup at 300 baud or less. In the third case, the question mark preceding the terminal type indicates that the user is to verify the type desired. A null response indicates that the named type is correct. Otherwise, the user’s response is taken to be the type desired. tset — m ’dialup>300:adm3a’ — m ’dialup:dw2’ — m ’plugboard:?adm3a’ To prevent interpretation as metacharacters, the entire argument to -m should be enclosed in sin- gle quotes. When using the C shell, exclamation points should be preceded by a backslash (\). EXAMPLES These examples all use the option. A typical use of tset in a .profile or .login will also use the -e and -k options, and often the -n or -Q options as well. These options have been omitted here to keep the examples short. To select a 2621, you might put the following sequence of commands in your .login file (or .profile for Bourne shell users). set noglob eval 'tset -s 2621' unset noglob If you have an h 19 at home which you dial up on, but your office terminal is hardwired and known in /etc/ttytab, you might use: set noglob eval 'tset -s -m dialup:hl9' unset noglob If you have a switch which connects to various ports (making it impractical to identify which port you may be connected to), and use various terminals from time to time, you can select from among those terminals according to the speed or baud rate. In the example below, tset will prompt you for a terminal type if the baud rate is greater than 1200 (say, 9600 for a terminal connected by an RS-232 line), and use a Wyse 50 by default. If the baud rate is less than or equal to 1200, it will select a 2621. Note the placement of the question mark, and the quotes to protect the > and ? from interpretation by the shell, set noglob eval 'tset -s -m ’switch>1200:?wy’ -m ’switch<=1200:2621’' unset noglob All of the above entries will fall back on the terminal type specified in /etc/ttytab if none of the conditions hold. The following entry is appropriate if you always dial up, always at the same baud rate, on many dif- ferent kinds of terminals, and the terminal you use most often is an adm3a. set noglob eval 'tset -s ?adm3a' unset noglob Sun Release 4.1 Last change: 18 December 1989 613 TSET(l) USER COMMANDS TSET(l) If the file /etc/ttytab is not properly set up and you want to make the selection based only on the baud rate, you might use the following: set noglob eval 'tset -s -m ’>1200:wy’ 2621' unset noglob The following example quietly sets the erase character to BACKSPACE, and kill to CTRL-U. If the port is switched, it selects a Concept 100 for speeds less than or equal to 1200, and asks for the terminal type oth- erwise (the default in this case is a Wyse 50). If the port is a direct dialup, it selects Concept 100 as the ter- minal type. If logging in over the TCP/IP, the terminal type selected is a Datamedia 2500 terminal or emu- lator. (Note the backslash escaping the NEWLINE at the end of the first line in the example.) set noglob eval 'tset -e -k'U -Q -s -m ’switch<=1200:conceptl00’ -m \ ’switch:?wy’ -m dialup:conceptl00 -m arpanet:dm2500' unset noglob FILES /etc/ttytab /etc/termcap /usr/share/lib/tabset/* .login .profile SEE ALSO csh(l), sh(l), stty(lV), vi(l), environ(5V), termcap(5), ttytab(5) NOTES Once the terminal’s size has been initialized, further invocations of tset will not affect it. To correct this, do the following: example% stty rows 0 colums 0 and then run tset normally. BUGS The tset command is one of the first commands a user must master when getting started on a UNIX system. Unfortunately, it is one of the most complex, largely because of the extra effort the user must go through to get the environment of the login shell set. Something needs to be done to make all this simpler, either the login program should do this stuff, or a default shell alias should be made, or a way to set the environment of the parent should exist. This program cannot intuit personal choices for erase, interrupt and line kill characters, so it leaves these set to the local system standards. It could well be argued that the shell should be responsible for ensuring that the terminal remains in a sane state; this would eliminate the need for the reset program. port name to terminal type mapping database terminal capability database TAB setting sequences for various terminals. Pointed to by termcap entries. 614 Last change: 18 December 1989 Sun Release 4.1 TSORT(l) USER COMMANDS TSORT(l) NAME tsort - topological sort SYNOPSIS tsort [filename ] DESCRIPTION tsort produces on the standard output a totally ordered list of items consistent with a partial ordering of items mentioned in the input filename. If no filename is specified, the standard input is understood. The input consists of pairs of items (nonempty strings) separated by SPACE characters. Pairs of different items indicate ordering. Pairs of identical items indicate presence, but not ordering. SEE ALSO lorder(l) BUGS Uses a quadratic algorithm; not worth fixing for the typical use of ordering a library archive file. Sun Release 4.1 Last change: 9 September 1987 615 TTY ( 1) USER COMMANDS TTY (1) NAME tty - display the name of the terminal SYNOPSIS tty [ -s ] DESCRIPTION tty prints the pathname of the user’s terminal unless the -s (silent) option is given. In either case, the exit value is zero if the standard input is a terminal, and one if it is not. OPTIONS -s Silent. Does not print the pathname of the user’s terminal. 616 Last change: 9 September 1987 Sun Release 4.1 UL(1) USER COMMANDS UL(1) NAME ul - do underlining SYNOPSIS ul [ — i ] [ — t terminal ] [filename . . . ] DESCRIPTION ul reads the named filenames (or the standard input if none are given) and translates occurrences of under- scores to the sequence which indicates underlining for the terminal in use, as specified by the environment variable TERM, ul uses the /etc/termcap file to determine the appropriate sequences for underlining. If the terminal is incapable of underlining, but is capable of a standout mode then that is used instead. If the ter- minal can overstrike, or handles underlining automatically, ul degenerates to cat(l V). If the terminal can- not underline, underlining is ignored. OPTIONS -t terminal Override the terminal kind specified in the environment. If the terminal cannot underline, under- lining is ignored. -i Indicate underlining by a separate line containing appropriate dashes * — *; this is useful when you want to look at the underlining which is present in an nroff(l) output stream on a CRT-terminal. FILES /etc/termcap SEE ALSO cat(lV), colcrt(l), man(l), nroff(l) BUGS nroff usually generates a series of backspaces and underlines intermixed with the text to indicate underlin- ing. ul makes attempt to optimize the backward motion. Sun Release 4.1 Last change: 9 September 1987 617 UNAME ( 1 ) USER COMMANDS UNAME ( 1 ) NAME uname - display the name of the current system SYNOPSIS uname [ -mnrsva ] DESCRIPTION uname prints information about the current system on the standard output. If no options are specified, uname prints the current system’s name. OPTIONS -m Print the machine hardware name. -n Print the nodename. The nodename may be a name that the system is known by to a communica- tions network. -r Print the operating system release. -s Print the system name (default). -v Print the operating system version. -a Print all the above information. SEE ALSO uname(2V) 618 Last change: 26 September 1988 Sun Release 4.1 UNIFDEF ( 1 ) USER COMMANDS UNIFDEF ( 1 ) NAME unifdef - resolve and remove ifdef’ed lines from cpp input SYNOPSIS unifdef [ -c 1 1 ] [ -Dname ] [ -U name ] [ -iD name ] [ -iU name ] . . . [ filename ] DESCRIPTION unifdef removes ifdefed lines from a file while otherwise leaving the file alone. It is smart enough to deal with the nested ifdefs, comments, single and double quotes of C syntax, but it does not do any including or interpretation of macros. Neither does it strip out comments, though it recognizes and ignores them. You specify which symbols you want defined with — D options, and which you want undefined with -U options. Lines within those ifdefs will be copied to the output, or removed, as appropriate. Any ifdef, ifndef, else, and endif lines associated with filename will also be removed. ifdefs involving symbols you do not specify are untouched and copied out along with their associated ifdef, else, and endif lines. If an ifdefY occurs nested inside another ifdefY, then the inside ifdef is treated as if it were an unrecog- nized symbol. If the same symbol appears in more than one argument, only the first occurrence is significant. unifdef copies its output to the standard output and will take its input from the standard input if no filename argument is given. OPTIONS -c Complement the normal operation. Lines that would have been removed or blanked are retained, and vice versa. -1 Replace “lines removed” lines with blank lines. -t Plain text option, unifdef refrains from attempting to recognize comments and single and double quotes. -iD name Ignore, but print out, lines associated with the defined symbol filename. If you use ifdefs to delimit non-C lines, such as comments or code which is under construction, then you must tell unifdef which symbols are used for that purpose so that it won’t try to parse for quotes and comments within them. -iU name Ignore, but print out, lines associated with the undefined symbol filename. SEE ALSO cpp(l), diff(l) DIAGNOSTICS Premature EOF Inappropriate else or endif. Exit status is 0 if output is exact copy of input, 1 if not, 2 if trouble. BUGS Does not know how to deal with cpp(l) constructs such as #if defined(X) || defined(Y) Sun Release 4. 1 Last change: 9 September 1987 619 UNIQ(l) USER COMMANDS UNIQ(l) NAME uniq - remove or report adjacent duplicate lines SYNOPSIS uniq [ -cdu [ + 1 —n ] [ inputfile [ outputfile ] ] DESCRIPTION uniq reads the input file comparing adjacent lines. In the normal case, the second and succeeding copies of repeated lines are removed; the remainder is written on the output file. Note: repeated lines must be adja- cent in order to be found; see sort(lV). OPTIONS -c Supersede -u and -d and generate an output report in default style but with each line preceded by a count of the number of times it occurred. The normal output of uniq is the union of the -u and -d options. -d Write one copy of just the repeated lines. -u Copy only those lines which are not repeated in the original file. The n arguments specify skipping an initial portion of each line in the comparison: +n The first n characters are ignored. Fields are skipped before characters. -n The first n fields together with any blanks before each are ignored. A field is defined as a string of non-SPACE, non-TAB characters separated by SPACE and TAB characters from its neighbors. SEE ALSO comm(l), sort(lV) 620 Last change: 9 September 1987 Sun Release 4.1 UMTS ( 1 ) USER COMMAMDS UMTS ( 1 ) NAME units - conversion program SYNOPSIS units DESCRIPTION units converts quantities expressed in various standard scales to their equivalents in other scales. It works interactively in this fashion: You have: inch You want: cm * 2.540000e+00 / 3.937008e-01 A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multiplier. Powers are indicated by suffixed positive integers, division by the usual sign: You have: 15 lbs force/in2 You want: atm * 1.020689e+00 / 9.797299e-01 units only does multiplicative scale changes. Thus it can convert Kelvin to Rankine, but not Celsius to Fahrenheit. Most familiar units, abbreviations, and metric prefixes are recognized, together with a gen- erous leavening of exotica and a few constants of nature including: pi Ratio of circumference to diameter, c Speed of light, e Charge on an electron, g Acceleration of gravity, force Same as g, mole Avogadro’s number, water Pressure head per unit height of water, au Astronomical unit. pound is not recognized as a unit of mass; lb is. pound refers to a British pound. Compound names are run together (for instance, lightyear). British units that differ from their U.S. counterparts are prefixed thus: brgallon. Currency is denoted belgiumfranc, britainpound, . . . For a complete list of units, type: cat /usr/iib/units FILES /usr/iib/units BUGS Do not base your financial plans on the currency conversions. Sun Release 4.1 Last change: 9 September 1987 621 UNIX2DOS ( 1 ) USER COMMANDS UNIX2DOS ( 1 ) NAME unix2dos - convert text file from ISO format to DOS format SYNOPSIS unix2dos [ -ascii ] [ -iso ] [ -7 ] originalfile convertedfile AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0jc release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION unix2dos converts ISO standard characters to the corresponding characters in the DOS extended character set. This command may be invoked from either DOS or SunOS. However, the filenames must conform to the conventions of the environment in which the command is invoked. If the original file and the converted file are the same, unix2dos will rewrite the original file after convert- ing it. OPTIONS —ascii Adds carriage returns and converts end of file characters in SunOS format text files to conform to DOS requirements. -iso This is the default. Converts ISO standard characters to the corresponding character in the DOS extended character set -7 Convert 8 bit SunOS characters to 7 bit DOS characters. DIAGNOSTICS File filename not found, or no read permission The input file you specified does not exist, or you do not have read permission (check with the SunOS command Is -1). Bad output filename filename, or no write permission The output file you specified is either invalid, or you do not have write permission for that file or the directory that contains it Check also that the drive or diskette is not write-protected. Error while writing to temporary file An error occurred while converting your file, possibly because there is not enough space on the current drive. Check the amount of space on the current drive using the DIR command. Also be certain that the default diskette or drive is write-enabled (not write-protected). Note that when this error occurs, the original file remains intact. Could not rename tmpfile to filename. Translated tmpfile name = filename. The program could not perform the final step in converting your file. Your converted file is stored under the name indicated on the second line of this message. SEE ALSO dos(l), dos2unix(l) Sun386i Advanced Skills Sun MS-DOS Reference Manual 622 Last change: 19 February 1988 Sun Release 4.1 UNLOAD ( 1 ) USER COMMANDS UNLOAD ( 1 ) NAME unload, unloadc - unload Application SunOS or Developer’s Toolkit optional clusters SYNOPSIS wAoaA filename... unloadc cluster. . . AVAILABILITY Available only on Sun 386i systems running a SunOS 4.0a release or earlier. Not a SunOS 4.1 release feature. DESCRIPTION unload unloads the Application SunOS or Developer’s Toolkit clusters that contain the specified file argu- ments. unloadc unloads the specified Application SunOS or Developer’s Toolkit clusters. Without arguments, unload and unloadc display a summary of the clusters in the Application SunOS and Developer’s Toolkit, including the load state and size of each cluster. EXAMPLES To unload the cluster that contains the spell command: exam pie % unload spell About to unload the spellcheck cluster, confirm (y/n): y Unloading the spellcheck cluster ... The spellcheck cluster has been unloaded, space used by clusters: 5358K bytes total space remaining: 20962K bytes example % To display a summary of the clusters in the Application SunOS and Developer’s Toolkit: example % unload Application SunOS Optional Clusters: availablecluster size (bytes) yes accounting 265K no advanced admin 501K Developer’s Toolkit Optional Clusters: availablecluster size (bytes) no base devel 6907K space used by clusters: 6021K bytes total space remaining: 20432K bytes FILES /export/cIuster/sun386.sunosre/ease/appl where Application SunOS clusters are loaded (or mounted), release is the current release of the operating system, for example, 4.0.2. Sun Release 4.1 Last change: 19 February 1988 623 UNLOAD ( 1 ) USER COMMANDS UNLOAD ( 1 ) /export/cluster/sun386.sunosre/ea^e/deveI where Developer’s Toolkit clusters are loaded (or mounted), release is the current release of the operating system, for example, 4.0.2. /usr/lib/Ioad/* data files SEE ALSO cluster(l), load(l), toc(5) Sun386i Setup and Maintenance DIAGNOSTICS The file filename is not in any of the optional software clusters. The specified file is not part of the Application SunOS or Developer’s Toolkit. The cluster cluster is not loaded. The specified cluster is not loaded on disk. There is no cluster cluster. The specified cluster is not part of the Application SunOS or Developer’s Toolkit. The Application SunOS (and/or) Developer’s Toolkit are mounted. The Application SunOS or Developer’s Toolkit or both are mounted across the network and can not be loaded or unloaded. 624 Last change: 19 February 1988 Sun Release 4.1 UNWHITEOUT ( 1 ) USER COMMANDS UNWHITEOUT ( 1 ) NAME unwhiteout - remove a TFS whiteout entry SYNOPSIS unwhiteout filename . . . DESCRIPTION For each filename that is a whiteout entry, unwhiteout removes that entry from the containing directory. These whiteout entries are created by the translucent file service. See tfs(4S). SEE ALSO Isw(l), tfs(4S), mount_tfs(8), tfsd(8) Sun Release 4.1 Last change: 23 November 1988 625 UPTIME ( 1 ) USER COMMANDS UPTIME ( 1 ) NAME uptime - show how long the system has been up SYNOPSIS uptime DESCRIPTION uptime prints the current time, the length of time the system has been up, and the average number of jobs in the run queue over the last 1, 5 and 15 minutes. It is, essentially, the first line of a w(l) command. EXAMPLE example% uptime 6:47am up 6 days, 16:38, 1 users, load average: 0.69, 0.28, 0.17 example % FILES /vmunix system namelist SEE ALSO w(l) 626 Last change: 9 September 1987 Sun Release 4.1 USERS (1) USER COMMANDS USERS ( 1 ) NAME users - display a compact list of users logged in SYNOPSIS users DESCRIPTION users lists the login names of the users currently on the system in a compact, one-line format: example% users paul george ringo example % FILES /etc/utmp SEE ALSO who(l) Sun Release 4.1 Last change: 9 September 1987 627 USTAR(IV) USER COMMANDS USTAR(IV) NAME ustar - process tape archives SYNOPSIS /usr/5bin/ustar -c [ bfvw ] device block filename . . . /usr/5bin/ustar -r [ bvw ] device block [filename . . . ] /usr/5bin/ustar -t [ fv ] device /usr/5bin/ustar -u [ bvw ] device block /usr/5bin/ustar -x [ flmovw ] device [filename . . . ] AVAILABILITY ustar is available with the System V software installation option. Refer to Installing SunOS 4.1 for infor- mation on how to install optional software. DESCRIPTION ustar reads and writes archive files which conform to the Archive/Interchange File Format specified in IEEE Std. 1003.1-1988. If the files exist, their modes are not changed except as described above. The owner, group and modification time are restored if possible. If no filename argument is given, the entire contents of the ar- chive is extracted. Note: if several files with the same name are in the archive, the last one will overwrite all earlier ones. OPTIONS -c Create a new archive; writing begins at the beginning of the archive, instead of after the last file. -r Write names files to the end of the archive. -t List the names of all of the files in the archive. — u Add named files to the archive if they are not already there, or if they have been modified since last written into the archive. This implies the -r option. -x Extracts named files from the archive. If a named file matches a directory whose contents had been written onto the archive, that directory is recursively extracted. If a named file in the archive does not exist on the system, the file is create with the same mode as the one in the archive, except that the set-user-id and get-group-id modes are not set unless the user has appropriate privileges. -b Use the next argument on the command line as the blocking factor for tape records. The default is 1; the maximum is 20. This option should only be used with raw magnetic tape archives. Nor- mally, the block size is determined automatically when reading tapes. -f Use the next argument on the command line as the name of the archive instead of the default, which is usually a tape drive. If is specified as a filename ustar writes to the standard output or reads from the standard input, whichever is appropriate for the options given. Thus, ustar can be used as the head or tail of a pipeline. -8 Report if ustar cannot resolve all of the links to the files being archived. If -! is not specified, no error messages are written to the standard output. This modifier is only valid with the -c, -r and -u options. -m Do not restore the modification times. The modification time of the file will be the time of extrac- tion. This modifier is invalid with the -t option. -© Extracted files take on the user and group identifier of the user running the program rather than those on the archive. This modifier is only valid with the -x option. -v Verbose. Print the name of each file it processes, preceded by the option letter. With the -t op- tion, -v gives more information about the archive entries than just the name. 628 Last change: 6 September 1989 Sun Release 4.1 USTAR(IV) USER COMMANDS USTAR(IV) -w Print the action to be taken, followed by the name of the file, and then wait for the user’s confirmation. If a word beginning with y is given, the action is performed. Any other input im- plies no and the action is not performed. This modifier is invalid with the — t option. FILES /dev/tty used to prompt the user for information when the -i or -y options are specified SEE ALSO cpio(l), dd(l), find(l), pax(lV), paxcpio(lV), cpio(5), tar(5) AUTHOR Mark H. Colburn NAPS International 117 Mackubin Street, Suite 1 St. Paul, MN 55102 Sponsored by The USENIX Association for public distribution. Sun Release 4.1 Last change: 6 September 1989 629 UUCP (1C) USER COMMANDS UUCP (1C) NAME uucp, uulog, uuname - system to system copy SYNOPSIS uucp [ -cCdfjmr ] [ -g grade ] [ -miser name ] [ -x debugjevel ] source-file . . . destination-file uulog [ -x ] [ -f system ] [ -s system ] [ -number ] uuname [ -cl 3 AVAILABILITY These commands are available with the uucp software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION uucp uucp copies each source-file to the named destination-file. A filename may be a path name on your machine, or may have the form system-name ! pathname where system-name is taken from a list of system names that uucp knows about. The system-name may also be a list of names such as system-namelsystem-namel. . \system-name\pathname in which case an attempt is made to send the file by way of the specified route, to the destination. See WARNINGS and BUGS below for restrictions. Care should be taken to ensure that intermediate nodes in the route are willing to foward information (see WARNINGS below for restrictions). The shell metacharacters ?, *, and [ ] appearing in the pathname part will be expanded on the appropriate system. Path names may be one of: • a full pathname; • a pathname preceded by 'user name /; username is interpreted as a username on the specified system and is replaced by that user’s login directory on that system; • a pathname preceded by 'I destination! ; the 7 is replaced by the “public UUCP” directory on the remote machine Note: this destination will be treated as a file name unless more than one file is being transferred by this request or the destination is already a directory. To ensure that it is a directory, follow the destination with a 7’. For example 7dan/ as the destination will make the directory /usr/spool/uucppublic/dan if it does not exist and put the requested file(s) in that directory; ® a partial pathname, which is prefixed by the pathname of current directory. If the result is an erroneous pathname for the remote system, the copy will fail. If the destination-file is a directory, the last component of the source-file name is used. uucp preserves execute permissions across the transmission and gives 0666 read and write permissions (see chmod(2V)). uulog uulog queries the log file /var/spool/uucp/.Log/uucico/system of uucp transactions for system system , or the log file /var/spool/uucp/.Log/uuxqt/ system of uux(lC) transactions for system system. uuname uuname lists the UUCP names of systems that can be accessed using uucp. 630 Last change: 8 June 1988 Sun Release 4.1 UUCP (1C) USER COMMANDS UUCP (1C) OPTIONS uucp -c Use the source file when copying out rather than copying the file to the spool directory. This is the default. — C Make a copy of outgoing files in the UUCP spool directory, rather than copying the source file directly to the target system. This lets you remove the source file after issuing the uucp com- mand. -d Make all necessary directories for the file copy. This is the default. -f Do not make intermediate directories for the file copy. -j Output the job identification ASCII string on the standard output. This job identification can be used by uustat(lC) to obtain the status or terminate a job. -m Send mail to the requester when the copy is complete. -r Do not start uucico(8C), just queue the job. -g grade grade is a single letter or number, from 0 to 9, A to Z, or a to z; 0 is the highest grade, and z is the lowest grade. Lower grades will cause the job to be transmitted earlier during a particular conver- sation. The default grade is n. By way of comparison, uux(lC) defaults to A; mail is usually sent at grade C. -nusername Notify username on the remote system (that is, send username mail) that a file was sent. -x debug Jevel Produce debugging output on the standard output, debugjevel is a number between 0 and 9; higher numbers give more detailed information. 5, 7, and 9 are good numbers to try; they give increasing amounts of detail. uulog -x Look in the uuxqt(8C) log file for the given system. -f system Does a ‘tail -F of the file transfer log for system. You must hit BREAK to exit this function. -ssystem Print information about work involving system system. -number Indicate that a tail command of number lines should be executed. uuname -c Display the names of systems known to cu(lC). The two lists are the same, unless your machine is using different Systems files for cu and uucp. See the Sysfiles file. -1 Display the local system name. FILES /var/spool/uucp spool directories /var/spool/uucppublic public directory for receiving and sending /etc/uucp/* other data files /usr/lib/uucp/* other program files SEE ALSO mail(l), uustat(lC), uux(lC), chmod(2V), uucico(8C), uuxqt(8C) System and Network Administration Sun Release 4.1 Last change: 8 June 1988 631 UUCP (1C) USER COMMANDS UUCP (1C) WARNINGS The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely restricted. You will very likely not be able to fetch files by path name; ask a responsible person on the remote system to send them to you. For the same reasons you will probably not be able to send files to arbitrary path names. As distributed, the remotely accessible files are those whose names begin /usr/spool/uucppublic (equivalent to 7). All files received by uucp will be owned by the user ID uucp. The -m option will only work sending files or receiving a single file. Receiving multiple files specified by special shell characters ?, *, and [ ] will not activate the -m option. The forwarding of files through other systems may not be compatible with other versions of UUCP. If for- warding is used, all systems in the route must have the same version of UUCP. When invoking uucp from csh(l), the ! character must be prefixed by the \ escape to inhibit csh’s history mechanism. Quotes are not sufficient BUGS Protected files and files that are in protected directories that are owned by the requestor can be sent by uucp. However, if the requestor is root, and the directory is not searchable by “other” or the file is not readable by “other”, the request will fail. 632 Last change: 8 June 1988 Sun Release 4.1 UUENCODE (1C) USER COMMANDS UUENCODE (1C) NAME uuencode, uudecode - encode a binary file, or decode its ASCII representation SYNOPSIS uuencode [ source-file ] file-label uudecode [ encoded-file ] DESCRIPTION uuencode converts a binary file into an ASCII-encoded representation that can be sent using mail(l). It en- codes the contents of source-file, or the standard input if no source-file argument is given. The file-label argument is required. It is included in the encoded file’s header as the name of the file into which uudecode is to place the binary (decoded) data, uuencode also includes the ownership and permission modes of source-file, so that file-label is recreated with those same ownership and permission modes. If the remote host is a UNIX system with the sendmail(8) mail-message delivery daemon, you can pipe the output of uuencode through mail(l) to the recipient named decode on the remote host. This recipient is typically an alias for the uudecode program (see aliases(5) for details), which allows a binary file to be decoded (extracted) from a mail message automatically. If this alias is absent on a particular host, the en- coded file can be mailed to a user, who can run it through uudecode manually. uudecode reads an encoded-file , strips off any leading and trailing lines added by mailer programs, and re- creates the original binary data with the filename and the mode and owner specified in the header. The encoded file is an ordinary ASCII text file; it can be edited by any text editor. But it is best only to change the mode or file-label in the header to avoid corrupting the decoded binary. SEE ALSO mail(l), uucp(lC), uusend(lC), uux(lC), aliases(5), uuencode(5), sendmail(8) BUGS The encoded file’s size is expanded by 35% (3 bytes become 4, plus control information), causing it to take longer to transmit than the equivalent binary. The user on the remote system who is invoking uudecode (typically uucp) must have write permission on the file specified in the file-label. Since both uuencode and uudecode run with user ID set to uucp, uudecode can fail with “permission denied” when attempted in a directory that does not have write permission allowed for “other.” Sun Release 4.1 Last change: 23 November 1987 633 UUSEND(IC) USER COMMANDS UUSEND(IC) NAME uusend - send a file to a remote host SYNOPSIS uusend [ -fr ] [ -m mode ] source-file system-namel \syslem-name2\. . .Idestination-file AVAILABILITY This command is available with the uucp software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. DESCRIPTION uusend sends the file, source-file, to a given location, destination-file, on a remote system. The system need not be directly connected to the local system, but a chain of uucp(lC) links must connect the two sys- tems. If destination-file is a directory, the last component of the source-file name is used. The source file can be meaning to use the standard input. These options are primarily intended for internal use of uusend. The destination file can include the " username or 7 syntax. OPTIONS -f Do not make intermediate directories for sending the file. -r Do not start uucico, just queue the job. -m mode Take the mode of the file on the remote end from the octal number specified as mode. The mode of the input file is used if the -m option is not specified. SEE ALSO uucp(lC), uuencode(lC), uux(lC) BUGS This command should not exist, since uucp should handle it. All systems along the line must have the uusend command available and allow remote execution of it. Some UUCP systems have a bug where binary files cannot be the input to a uux command. If this bug ex- ists in any system along the line, the file will show up severely corrupted. 634 Last change: 5 July 1988 Sun Release 4.1 UUSTAT(IC) USER COMMANDS UUSTAT(IC) NAME uustat - UUCP status inquiry and job control SYNOPSIS uustat -a l-m l-p l-q l-k jobid \-rjobid uustat [ -s system ] [ -u user ] AVAILABILITY This command is available with the uucp software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION uustat displays the status of, or cancels, previously specified uucp(lC) commands. It also reports the status of uucp connections to other systems. When no options are given, uustat displays the status of all uucp requests issued by the current user. OPTIONS Only one of the following options can be specified at a time: -a Output all jobs in queue. -m Report the status of accessibility of all machines. -p Execute a ps for all the PIDs listed in the lock files. -q List the jobs queued for each machine. If a status file exists for the machine, its date, time and status information are reported. In addition, if a number appears in parentheses next to the number of C. or X. files, it is the age in days of the oldest C./X. file for that system. The Retry field represents the number of hours until the next possible call. The Count is the number of failure attempts. For systems with a moderate number of outstanding jobs, this could take 30 seconds or more to execute. An example of the output from — q is: eagle 3C 04/07-11:07 NO DEVICES AVAILABLE mh3bs3 2C 07/07-10:42 SUCCESSFUL This indicates the number of command files that are waiting for each system. Each command file may have zero or more files to be sent (zero means to call the system and see if work is to be done). The date and time refer to the previous interaction with the system followed by the status of the interaction. -k jobid Kill the UUCP request with job identification of jobid. You must either own the job to be killed, or be the super-user. -r jobid Rejuvenate jobid. The files associated with jobid are touched so that their modification time is set to the current time. This prevents the cleanup daemon from deleting the job until the jobs modification time reaches the next limit imposed by the daemon. The following options can be specified separately or together: -ssystem Report the status of all UUCP requests for remote system system. -u user Report the status of all UUCP requests issued by user. Sun Release 4. 1 Last change: 8 June 1988 635 UUSTAT(IC) USER COMMANDS UUSTAT(IC) Output for both the -s and -u options has the following format: eaglenOOOO 4/07-11:01:03 (POLL) eagleNlbd7 4/07-11:07 S eagle dan 522 /usr/dan/A eagleClbdS 4/07-11:07 S eagle dan 59 D.3b2al2ce4924 4/07-11:07 S eagle dan rmail mike The first field is the job ID of the job. This is followed by the date and time. The next field is ei- ther an S or R depending on whether the job is to send or request a file. This is followed by the user ID of the user who queued the job. The next field contains the size of the file, or in the case of a remote execution request, the name of the command. When the size appears in this field, the file name is also given. This can either be the name given by the user, or an internal name created for data files associated with remote executions (rmail in this example). FILES /var/spool/uucp/* UUCP spool directories SEE ALSO uucp(lC) 636 Last change: 8 June 1988 Sun Release 4.1 UUTO(IC) USER COMMANDS UUTO(IC) NAME uuto, uupick - public system-to-system file copy SYNOPSIS uuto [ -mp ] source-file . . . destination uupick [ -s system ] AVAILABILITY This command is available with the uucp software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION uuto uuto sends source-files to destination, uuto uses the uucp(lC) facility to send files, while it allows the lo- cal system to control the file access. A source-file name is a path name on your machine. Destination has the form: system-name ! username where system-name is taken from a list of system names that uucp knows about (see uucp(lC)). username is the username of someone on the specified system. The files (or sub-trees if directories are specified) are sent to the “public UUCP” directory on the remote machine system-name. Normally, this directory is /usr/spool/uucppublic. Specifically the files are sent to PVBDIR/receiy el username I my system I file where PUBDIR is the “public UUCP” directory on system-name , my system is the system from which the files are sent, and file is the file being sent. The destined recipient is notified by mail(l) of the arrival of files. uupick uupick accepts or rejects the files transmitted to the user. Specifically, uupick searches the “public UUCP” directory on the local machine for files destined for the user. For each entry (file or directory) found, the following message is printed on the standard output: from system : [file file-name] [ dir dirname ] ? uupick then reads a line from the standard input to determine the disposition of the file: d m [ dir ] a [ dir ] P q EOT (CTRL-D) l command Go on to next entry. Delete the entry. Move the entry to named directory dir. If dir is not specified as a complete path name (in which $HOME is legitimate), a destination relative to the current directory is as- sumed. If no destination is given, the default is the current directory. Same as m except moving all the files sent from system. Print the content of the file. Stop. Same as q. Escape to the shell to do command. Print a command summary. Sun Release 4. 1 Last change: 26 May 1988 637 UUTO(IC) USER COMMANDS UUTO(IC) OPTIONS uuto -m Send mail to the sender when the copy is complete. -p Copy the source file into the spool directory before transmission. uupick -s system Search only the “public UUCP” directory on the local machine for files sent from system. FILES /usr/spool/uucppublic public UUCP directory SEE ALSO mail(l), uucp(lC), uustat(lC), uux(lC), uucleanup(8C) WARNINGS In order to send files that begin with a dot (such as, .profile) the files must by qualified with a dot. For ex- ample: .profile, .prof*, and .profil? are correct, whereas *prof* and ?profile are incorrect. 638 Last change: 26 May 1988 Sun Release 4.1 UUX(IC) USER COMMANDS UUX(IC) NAME uux - remote system command execution SYNOPSIS uux [ - ] [ -bcCjnprz ] [ -a name ] [ -g grade ] [ -x debug Jevel ] command-string AVAILABILITY This command is available with the uucp software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION uux will gather 0 or more files from various systems, execute a command on a specified system and send the standard output to a file on a specified system. For security reasons, most installations limit the list of commands executable on behalf of an incoming request from uux, permitting only the receipt of mail (see mail(l)). Remote execution permissions are defined in /etc/uucp/Permissions. The command-string is made up of one or more arguments that look like a shell command line, except that the command and file names may be prefixed by ‘system-namel ’. A null system-name is interpreted as the local system. Path names may be one of: « a full pathname; • a pathname preceded by "username /; username is interpreted as a username on the specified system and is replaced by that user’s login directory on that system; • a pathname preceded by 7 destination! ; the 7 is replaced by the “public UUCP” directory on the remote machine Note: this destination will be treated as a file name unless more than one file is being transferred by this request or the destination is already a directory. To ensure that it is a directory, follow the destination with a T. For example 7dan/ as the destination will make the directory /usr/spool/uucppublic/dan if it does not exist and put the requested file(s) in that directory; • a partial pathname, which is prefixed by the pathname of current directory. The option sends the standard input to the uux command as the standard input to the command-string. Any special shell characters such as < >, ;, and | should be quoted either by quoting the entire command- string, or by quoting the special characters as individual arguments. uux will attempt to get all files to the execution system. For files that are output files, the file name must be escaped using parentheses. For example, the command uux a!cut -fl b!/usr/file \(c!/usr/file\) gets /usr/file from system b and sends it to system a, performs a cut command on that file and sends the result of the cut command to system c. uux will notify you if the requested command on the remote system was disallowed, or if the command fails (that is, returns a non-zero exit status). This notification can be turned off by the -n option. The response comes by remote mail from the remote machine. OPTIONS -b Return whatever standard input was provided to the uux command if the job fails (that is, returns a non-zero exit status). -c Do not copy local file to the spool directory for transfer to the remote machine. This is the default. -C Force the copy of local files to the spool directory for transfer. -j Output the jobid ASCII string on the standard output which is the job identification. This job identification can be used by uustat(lC) to obtain the status or terminate a job. Sun Release 4. 1 Last change: 8 June 1988 639 UUX(IC) USER COMMANDS UUX(IC) — n Do not return any indication by mail(l) of success or failure of the job. -p Same as the standard input to uux is made the standard input to the command-string . -r Do not start uucico(8C), just queue the job. — z Return an indication by mail even if the job succeeds (that is, returns a zero exit status). -a name Use name as the user identification replacing the initiator user ID. Notification will be returned to the user. -g grade grade is a single letter or number, from 0 to 9, A to Z, or a to z; 0 is the highest grade, and z is the lowest grade. Lower grades will transmit the job earlier during a particular conversation. The default grade is A. -x debugjevel Produce debugging output on the standard output, debugjevel is a number between 0 and 9; higher numbers give more detailed information. 5, 7, and 9 are good numbers to try; they give increasing amounts of detail. EXAMPLE The command uux "!diff usg!/usr/dan/filel pwba!/a4/dan/file2 > !7dan/file.diff" will get the filel and file2 files from the usg and pwba machines, execute a diff(l) command and put the results in file.diff in the local PUBDIR/dan directory. FILES /var/spool/uucp spool directories /etc/uucp/Permissions remote execution permissions /etc/uucp/* other data /usr/lib/uucp/* other programs SEE ALSO mail(l), uucp(lC), uustat(lC), uucico(8C) System and Network Administration WARNINGS Only the first command of a shell pipeline may have a ‘ system-namel ’. All other commands are executed on the system of the first command. The use of the shell metacharacter * will probably not do what you want it to do. The shell tokens « and » are not implemented. The execution of commands on remote systems takes place in an execution directory known to the UUCP system. All files required for the execution will be put into this directory unless they already reside on that machine. Therefore, the simple file name (without path or machine reference) must be unique within the uux request. The following command will NOT work: uux "aldiff b!/usr/dan/xyz c!/usr/dan/xyz > !xyz.diff" but the command uux "aldiff a!/usr/dan/xyz c!/usr/dan/xyz > Ixyz.diff" will work (if diff is a permitted command). When invoking uux from csh(l), the 1 character must be prefixed by the \ escape to inhibit csh’s history mechanism. Quotes are not sufficient 640 Last change: 8 June 1988 Sun Release 4.1 UUX(IC) USER COMMANDS UUX(IC) BUGS Protected files and files that are in protected directories that are owned by the requestor can be sent in com- mands using uux. However, if the requestor is root, and the directory is not searchable by “other”, the request will fail. Sun Release 4.1 Last change: 8 June 1988 641 VACATION ( 1 ) USER COMMANDS VACATION ( 1 ) NAME vacation — reply to mail automatically SYNOPSIS vacation [ -I ] vacation [ -j ] [ -a alias ] [ -tN ] username DESCRIPTION vacation automatically replies to incoming mail. The reply is contained in the file .vacation.msg in your home directory. The vacation program run interactively will create a .vacation.msg file for you (which you may edit). Type vacation with no arguments. (See USAGE below.) For example, the message created by vacation is: Subject: away from my mail From: smith (via the vacation program) I will not be reading my mail for a while. Your mail regarding "$SUBJECT" will be read when I return The .vacation.msg file should include a header with at least a ‘Subject:’ line (it should not contain a ‘To:’ line and need not contain a ‘From:’ line, since these are generated automatically). If the string $SUBJECT appears in the .vacation.msg file, it is replaced with the subject of the original mes- sage when the reply is sent. No message is sent if the ‘To:’ or the ‘Cc:’ line does not list the user to whom the original message was sent or one of a number of aliases for them, if the initial From line includes the string — REQUEST@, or if a ‘Precedence: bulk’ or ‘Precedence: junk’ line is included in the header. OPTIONS -I Initialize the .vacation.pag and .vacation.dir files and start vacation. If the -I flag is not specified, and a user argument is given, vacation reads the first line from the standard input (for a ‘From:’ line, no colon). If absent, it produces an error message. The following options may be specified: -a alias Indicate that alias is one of the valid aliases for the user running vacation, so that mail addressed to that alias generates a reply. -j Do not check whether the recipient appears in the ‘To:’ or the ‘Cc:’ line. -tAI Change the interval between repeat replies to the same sender. The default is 1 week. A trailing s, m, h, d, or w scales N to seconds, minutes, hours, days, or weeks respectively. USAGE To start vacation, create a .forward file in your home directory containing a line of the form: \username, "|/usr/ucb/vacation username " where username is your login name. Then type in the command: vacation -I To stop vacation, remove the .forward file, or move it to a new name. 642 Last change: 25 November 1987 Sun Release 4.1 VACATION ( 1 ) USER COMMANDS VACATION(l) If vacation is run with no arguments, it will permit you to interactively turn vacation on or off. It will create a .vacation.msg file for you, or edit an existing one, using the editor specified by the VISUAL or ED- ITOR environment variable, or vi(l) if neither of those environment variables are set. If a .forward file is present in your home directory, it will ask whether you want to remove it and turn off vacation. If it is not present in your home directory, it creates it for you, and automatically performs a ‘vacation -I’ function, turning on vacation. FILES .forward $HOME/.vacation.msg A list of senders is kept in the files .vacation.pag and .vacation.dir in your home directory. SEE ALSO vi(l), sendmail(8) Sun Release 4.1 Last change: 25 November 1987 643 VFONTINFO ( 1 ) USER COMMANDS VFONTINFO ( 1 ) NAME vfontinfo - inspect and print out information about fonts SYNOPSIS /usr/lib/vfontinfo [ -mvz ]fontname [ characters ] AVAILABILITY This command is available with the Versatec software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION vfontinfo allows you to examine a font in the UNIX system format. It prints out all the information in the font header and information about every non-null (width > 0) glyph. This can be used to make sure the font is consistent with the format. Th efontname argument is the name of the font you wish to inspect. It writes to the standard output. If it cannot find the file in your working directory, it looks in /usr/lib/vfont (the place most of the fonts are kept). The characters, if given, specify certain characters to show. If omitted, the entire font is shown. OPTIONS -m Display header. -v Verbose. Display bits of the glyph using commas, periods, and pipe (T) symbols. -z Zoom. Display bits of the glyph as an array of M and SPACE characters. FILES /usr/lib/vfont /usr/Iib/vpd Versatec daemon SEE ALSO vswap(l), vwidth(l), vfont(5) 644 Last change: 19 October 1988 Sun Release 4.1 VGRIND ( 1 ) USER COMMANDS VGRIND ( 1 ) NAME vgrind - grind nice program listings SYNOPSIS vgrind [ -fntwWx ] [ -d defs-file ] [ -h header ] [ -Uanguage ] [ -s n ] [ -opagelist ] [ -P printer ] [ — T output-device ] filename. . . AVAILABILITY This command is available with the Text software installation option. Refer to Installing SunOS 4.1 for in- formation on how to install optional software. DESCRIPTION vgrind formats the program sources named by the filename arguments in a nice style using troff(l). Com- ments are placed in italics, keywords in bold face, and as each function is encountered its name is listed on the page margin. vgrind runs in two basic modes, filter mode or regular mode. In filter mode vgrind acts as a filter in a manner similar to tbl(l). The standard input is passed directly to the standard output except for lines bracketed by the troff-like macros: .vS starts processing •vE ends processing These lines are formatted as described above. The output from this filter can be passed to troff for output. There need be no particular ordering with eqn(l) or tbl. In regular mode vgrind accepts input filenames, processes them, and passes them to troff for output. If no filename is given, or if the argument is given, vgrind reads from the standard input (default if -f is specified). In both modes vgrind passes any lines beginning with a decimal point without conversion. OPTIONS Note: the syntax of options with arguments is important. Some require a SPACE between the option name and the argument, while those that do not have a SPACE below will not tolerate one. -f Force filter mode. -n Do not make keywords boldface. -x Output the index file in a “pretty” format. The index file itself is produced whenever vgrind is run with a file called index present in the current directory. The index of function definitions can then be run off by giving vgrind the -x option and the file index as argument. -w Consider TAB characters to be spaced four columns apart instead of the usual eight. -d defs-file Specify an alternate language definitions file (default is /usr/Iib/vgrindefs). -h header Specify a header to appear in the center of every output page. -Uanguage Specify the language to use. Among the languages currently known are: Bourne shell (-lsh), C (-lc, the default), C shell (— Icsh), emacs MLisp, (-1ml), FORTRAN (-If), Icon (-II), ISP (-i), LDL (-1LDL), Model (-Im), Pascal (-lp), and RATFOR (-lr). -s n Specify a point size to use on output (exactly the same as the argument of a troff .ps point size re- quest). Sun Release 4.1 Last change: 8 June 1988 645 VGRIND ( 1 ) USER COMMANDS VGRIND ( 1 ) vgrind passes the following options to the formatter specified by the TROFF environment variable, see EN- VIRONMENT below. -t Similar to the same option in troff; that is, formatted text goes to the standard output. -o pagelist Print only those pages whose page numbers appear in the comma-separated pagelist of numbers and ranges. A range N-M means pages N through M\ an initial -N means from the beginning to page N\ and a final N— means from N to the end. — P printer Send output to the named printer. — T output-device Format output for the specified output-device . -W Force output to the (wide) Versatec printer rather than the (narrow) Varian. vtroff(l) only. ENVIRONMENT In regular mode vgrind feeds its intermediate output to the text formatter given by the value of the TROFF environment variable, or to troff if this variable is not defined in the environment. This mechanism allows for local variations in troff ’s name. FILES index /usr/lib/vgrindefs /usr/lib/vfontedpr /usr/share/lib/tmac/tmac.vgrind file where source for index is created language descriptions preprocessor macro package SEE ALSO troff(l), vtroff(l), vgrindefs(5) BUGS vgrind assumes that a certain programming style is followed: C Function names can be preceded on a line only by SPACE, TAB, or an asterisk. The parenthesized arguments must also be on the same line. FORTRAN Function names need to appear on the same line as the keywords function or subroutine . MLisp Function names should not appear on the same line as the preceding defun . Model Function names need to appear on the same line as the keywords is beginproc. Pascal Function names need to appear on the same line as the keywords function or procedure . If these conventions are not followed, the indexing and marginal function name comment mechanisms will fail. More generally, arbitrary formatting styles for programs mostly look bad. The use of SPACE characters to align source code fails miserably; if you plan to vgrind your program you should use TAB characters. This is somewhat inevitable since the fonts vgrind uses are variable width. The mechanism of ctags(l) in recognizing functions should be used here. The -w option is a crock, but there is no other way to achieve the desired effect. 646 Last change: 8 June 1988 Sun Release 4.1 VGRIND ( 1 ) USER COMMANDS VGRIND ( 1 ) The macros defined in tmac.vgrind do not coexist gracefully with those of other macro packages, making filter mode difficult to use effectively. vgrind does not process certain special characters in csh(l) scripts correctly. Sun Release 4. 1 Last change: 8 June 1988 647 VI(1) USER COMMANDS VI(1) NAME vi, view, vedit - visual display editor based on ex(l) SYNOPSIS vi [ -CILRVx ] [ -c command ] [ -r filename ] [ -t tag ] [ -w nnn ] [ +command ] filename. . . view. . . vedit. . . DESCRIPTION vi (visual) is a display oriented text editor based on ex(l). ex and vi are, in fact, the same text editor; it is possible to get to the command mode of ex from within vi and vice-versa. view runs vi with the readonly flag set. With view, you can browse through files interactively without making any changes. vedit runs vi with the report flag set to 1, the showmode and novice flags set, and the magic flag turned off. These default settings are intended to make easier for beginners to learn vi. OPTIONS -C -I -L -R -V -x -c command -r filename -t tag +command ENVIRONMENT The editor recognizes the environment variable EXINIT as a command (or list of commands separated by | characters) to run when it starts up. If this variable is undefined, the editor checks for startup commands in the file 7.exrc file, which you must own. However, if there is a .exrc owned by you in the current directo- ry, the editor takes its startup commands from this file — overriding both the file in your home directory and the environment variable. Encryption option; the same as the -x option, except that all input text is assumed to have already been encrypted. This guarantees decryption in the cases where the -x option in- correctly determines that the input file is not already encrypted (this is extremely rare, and will only occur in conjunction with the use of files containing non-ASCII text). Set up for editing LISP programs. List the names of all files saved as the result of an editor or system crash. Edit files in read only state. This has the same effect as the view command. Verbose. Any non-tty input will be echoed on standard error. Prompt for a key to be used in encrypting the file being edited. When used in conjunction with a pre-existing file, ex will make an educated guess to determine whether or not the in- put text file is already encrypted. Start the editing session by executing the editor command command. If command contains spaces, it must be surrounded by double quotess, see EXAMPLES below. Recover the named files after a crash. Edit the file containing tag. There must be a tags database in the directory, built by ctags(l), that contains a reference to tag. Start the editing session by executing command. This is identical to the -c option. 648 Last change: 2 October 1989 Sun Release 4.1 VI(1) USER COMMANDS vi(i) The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout vi. On entry to vi, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid charac- ter classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. In the “C” locale, all 8-bit characters are escaped into an octal represen- tation. EXAMPLES The following command: example % vi-c ":r test" tested will read in the file test at the end of the tested file. SEE ALSO ctags(l), ex(l) Editing Text Files SunOS User’ s Guide: Getting Started BUGS Software TAB characters using CTRL-T work only immediately after the autoindent. SHIFT-left and SHIFT-right on intelligent terminals do not make use of insert and delete character opera- tions in the terminal. The wrapmargin option can be fooled since it looks at output columns when blanks are typed. When in- sert mode pushes an existing word through the margin and onto the next line without a break, the line will not be broken. Insert/delete within a line can be slow if TAB characters are present on intelligent terminals, since the ter- minals need help in doing this correctly. Saving text on deletes in the named buffers is somewhat inefficient. The source command does not work when executed as ‘:source’; there is no way to use the ‘:append\ ‘:change’, and insert’ commands, since it is not possible to give more than one line of input to a es- cape. To use these on a ‘rglobal’ you must Q to ex command mode, execute them, and then reenter the screen editor with vi or open. When using the -r option to recover a file, you must write the recovered text before quitting or you will lose it. vi does not prevent you from exiting without writing unless you make changes. vi does not adjust when the SunView window in which it runs is resized. RESTRICTIONS The encryption facilities of vi are not available on software shipped outside the U.S. Sun Release 4.1 Last change: 2 October 1989 649 VPLOT(l) USER COMMANDS VPLOT(l) NAME vplot - plot graphics for a Versatec printer SYNOPSIS vplot [ — VW ] [ — b Ipr-argument ] filename AVAILABILITY This command is available with the Versatec software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION vplot reads plot(5) format graphics input from the file specified by filename (the standard input if no filename is specified) and produces a plot on the Varian or Versatec printer. OPTIONS -V Force output to the standard Versatec printer. -W Force output to the (wide) Versatec printer rather than the standard Versatec printer. -b Ipr-argument argument (the next argument on the command line) specifies extra arguments to lpr(l). SEE ALSO lpr(l), plot(lG), plot(5) 650 Last change: 21 December 1987 Sun Release 4.1 VSWAP(l) USER COMMANDS VSWAP(l) NAME vswap - convert a foreign font file SYNOPSIS /usr/lib/ vswap [ -r ] AVAILABILITY This command is available with the Versatec software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION Without the -r option, vswap translates its standard input (which must be a vfont(5) file in the reversed- byte order) into a locally correct vfont file on its standard output. With the -r option, vswap translates its standard input (which must be a vfont file in the local-byte order) into a byte-reversed vfont file on its stan- dard output. The UNIX system vfont representation for fonts is a binary file containing machine-dependent elements — short (16-bit) integers, in particular. There are (at least) two common ways of representing a 16-bit integer. A program compiled on a VAX will expect the VAX format, while the same program compiled on a machine using a Motorola 68000-family processor or a SPARC processor will expect the reverse format, vswap can be used to convert font files created on a VAX to the format required to use them on Suns. (All Suns use the same vfont format, regardless of the native byte order of the processor, including Suns that use the Intel 80386 processor. Programs that will be run on Suns that use the Intel 80386 processor must be aware of this, and convert the machine-dependent elements when they read or write vfont files.) It can also convert Sun-format font files to VAX format (with the -r option). SEE ALSO troff(l), vfont(5) BUGS A machine-independent font format should be defined. Sun Release 4.1 Last change: 10 January 1988 651 VTROFF(l) USER COMMANDS VTROFF ( 1 ) NAME vtroff- troff to a raster plotter SYNOPSIS vtroff [ -wx ] [ -F majorfont ] [ -1 length ] [ -123 minorfont ] troff-arguments AVAILABILITY This command is available with the Versatec software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION vtroff runs troff(l) sending its output through various programs to produce typeset output on a raster plotter such as a Benson-Varian or a Versatec. OPTIONS -w Specify that a wide output device be used; the default is to use a narrow device. -x Simulate photo-typesetter output exactly. As with, using the width tables for the C.A.T. photo- typesetter. — F fontname Specify fontname as the desired font. This will place normal, italic and bold versions of the font on positions 1, 2, and 3. The default font is a Hershey font, argument and then the font name. -1 length Split the output onto successive pages every length inches rather than the default 1 1 inches. -123 minorfont Place a font only on a single position specified by -n (where n is 1, 2, or 3) and the minor font name. A .r will be added to the minor font name if needed. Thus vtroff -ms paper will set a paper in the Hershey font, while vtroff -F nonie -ms paper will set the paper in the (sans serif) nonie font. FILES /usr/share/lib/tmac/tmac.vcat default font mounts and bug fixes /usr/lib/fontinfo/* fixes for other fonts /usr/lib/vfont directory containing fonts SEE ALSO troff(l), vfont(5) BUGS Since some macro packages work correctly only if the fonts named R, I, B, and S are mounted, and since the Versatec fonts have different widths for individual characters than the fonts found on the typesetter, the following dodge was necessary: If you do not use the .fp troff directive then you get the widths of the stan- dard typesetter fonts suitable for shipping the output of troff over the network to the computer center A machine for phototypesetting. If, however, you remount the R, I, B and S fonts, then you get the width tables for the Versatec. 652 Last change: 21 December 1987 Sun Release 4.1 V WIDTH ( 1 ) USER COMMANDS VWIDTH ( 1 ) NAME vwidth - make a troff width table for a font SYNOPSIS /usr/lib/vwidth fontfile pointsize > ftxc.c cc -c ftxc.c mv ftxxo /usr/lib/font/ftxc AVAILABILITY This command is available with the Versatec software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION vwidth translates from the width information stored in the vfont style format to the format expected by troff(l) — an object file in a.out(5) format, troff should look directly in the font file but it doesn’t. vwidth should be used after editing a font with fontedit(l). It is not necessary to use vwidth unless you have made a change that would affect the width tables. Such changes include numerically editing the width field, adding a new character, and moving or copying a character to a new position. It is not always necessary to use vwidth if the physical width of the glyph (for instance the number of columns in the bit matrix) has changed, but if it has changed much the logical width should probably be changed and vwidth run. vwidth produces a C program on its standard output. This program should be run through the C compiler and the object (that is, the .o file) saved. The resulting file should be placed in /usr/lib/font in the file ftxc where xx is a one or two letter code that is the logical (internal to troff) font name. This name can be found by looking in the file /usr/lib/fontinfo//nawe * where fname is the external name of the font. FILES /usr/lib/font a.out SEE ALSO troff(l), vtroff(l), fontedit(l), a.out(5), vfont(5) Sun Release 4.1 Last change: 21 December 1987 653 W(1) USER COMMANDS W(l) NAME w - who is logged in, and what are they doing SYNOPSIS w [ -his ] [ user ] DESCRIPTION w displays a summary of the current activity on the system, including what each user is doing. The head- ing line shows the current time of day, how long the system has been up, the number of users logged into the system, and the load averages. The load average numbers give the number of jobs in the run queue averaged over 1, 5 and 15 minutes. The fields displayed are: the users login name, the name of the tty the user is on, the time of day the user logged on (in hours:minutes), the idle time — that is, the number of minutes since the user last typed any- thing (in hours:minutes), the CPU time used by all processes and their children on that terminal (in minutes:seconds), the CPU time used by the currently active processes (in minutes:seconds), the name and arguments of the current process. If a user name is included, output is restricted to that user. OPTIONS -h Suppress the heading. -1 Produce a long form of output, which is the default. -s Produce a short form of output. In the short form, the tty is abbreviated, the login time and CPU times are left off, as are the arguments to commands. EXAMPLE example % w 7:36am up 6 days, 16:45, 1 users, load average: 0.20, 0.23, 0.18 User tty login@ idle JCPU PCPU what ralph console 7:10am 1 10:05 4:31 w example % ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout w. On entry to w, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_defauIt. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid charac- ter classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /etc/utmp /dev/kmem /dev/drum SEE ALSO ps(l), who(l), utmp(5V) BUGS The notion of the “current process” is muddy. The current algorithm is ‘the highest numbered process on the terminal that is not ignoring interrupts, or, if there is none, the highest numbered process on the termi- nal’. This fails, for example, in critical sections of programs like the shell and editor, or when faulty pro- grams running in the background fork and fail to ignore interrupts. In cases where no process can be found, w prints 654 Last change: 9 September 1987 Sun Release 4.1 W(l) USER COMMANDS W(l) The CPU time is only an estimate, in particular, if someone leaves a background process running after log- ging out, the person currently on that terminal is “charged” with the time. Background processes are not shown, even though they account for much of the load on the system. Sometimes processes, typically those in the background, are printed with null or garbaged arguments. In these cases, the name of the command is printed in parentheses. w does not know about the new conventions for detecting background jobs. It will sometimes find a back- ground job instead of the right one. Sun Release 4. 1 Last change: 9 September 1987 655 WAIT ( 1 ) USER COMMANDS WAIT ( 1 ) NAME wait - wait for a process to finish SYNOPSIS wait DESCRIPTION Wait until all processes started with & or bg have completed, and report on abnormal terminations. Because the wait(2V) system call must be executed in the parent process, the shell itself executes wait, without creating a new process. SEE ALSO csh(l), sh(l), wait(2V) BUGS Not all the processes of a 3- or more-stage pipeline are children of the shell, and thus cannot be waited for. This bug does not apply to csh(l). 656 Last change: 9 September 1987 Sun Release 4.1 WALL ( 1 ) USER COMMANDS WALL ( 1 ) NAME wall - write to all users logged in SYNOPSIS wall [ -a ] [ filename ] DESCRIPTION wall reads the standard input until an EOF. It then sends this message, preceded by ‘Broadcast Message to all logged in users. If filename is given, then the message is read in from that file. Normally, pseudo-terminals that do not correspond to rlogin sessions are ignored. Thus when in sunview(l), the mes- sage appears only on the console window. However, -a will send the message even to such pseudo- terminals. The sender should be super-user to override any protections the users may have invoked. FILES /dev/tty? /etc/utmp SEE ALSO mesg(l), sunview(l), write(l) Sun Release 4.1 Last change: 9 September 1987 657 WC(1) USER COMMANDS WC(1) NAME wc - display a count of lines, words and characters SYNOPSIS wc [ — lwc ] [filename ... ] DESCRIPTION wc counts lines, words, and characters in filenames, or in the standard input if no filename appears. It also keeps a total count for all named files. A word is a string of characters delimited by SPACE, TAB, or NEW- LINE characters. OPTIONS When filenames are specified on the command line, their names will be printed along with the counts. The default is -lwc (count lines, words, and characters). 1 Count lines, w Count words, c Count characters. EXAMPLE example% wc/usr/share/man/manl/{csh.l,sh.l,telnet.l} 1876 11223 65895 /usr/share/man/manl/csh.l 674 3310 20338 /usr/share/man/manl/sh.l 260 1110 6834 /usr/share/man/manl/telnet.l 2810 15643 93067 total example % ENVIRONMENT The environment variables LC_CTYPE, LANG, and LC_default control the character classification throughout wc. On entry to wc, these environment variables are checked in the following order: LC_CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. 658 Last change: 2 October 1989 Sun Release 4.1 WHAT ( 1 ) USER COMMANDS WHAT ( 1 ) NAME what - extract SCCS version information from a file SYNOPSIS what [ -s ] filename . . . DESCRIPTION what searches each filename for occurrences of the pattern @(#) that the SCCS get command (see sccs- get(l)) substitutes for the %Z% ID keyword, and prints what follows up to a ", >, NEWLINE, \, or null character. For instance, if the C program in file program.c contains char sccsid[ ] = " @(#)identification information " ; and program.c is compiled to yield program.o and a.out, the command: what programs program.o a.out produces: program.c: identification information program.o: identification information a.out: identification information OPTIONS -s Stop after the first occurrence of the pattern. SEE ALSO sccs(l), sccs-admin(l), sccs-cdc(l), sccs-comb(l), sccs-delta(l), sccs-get(l), sccs-help(l), sccs-prs(l), sccs-prt(l), sccs-rmdel(l), sccs-sact(l), sccs-sccsdiff(l), sccs-unget(l), sccs-val(l), sccsfile(5) Programming Utilities and Libraries DIAGNOSTICS Use the SCCS help command for explanations (see sccs-help(l)). BUGS There is a remote possibility that a spurious occurrence of the ‘@(#)’ pattern could be found by what. Sun Release 4.1 Last change: 30 June 1988 659 WHATIS ( 1 ) USER COMMANDS WHATIS ( 1 ) NAME whatis - display a one-line summary about a keyword SYNOPSIS whatis command . . . DESCRIPTION whatis looks up a given command and displays the header line from the manual section. You can then run the man(l) command to get more information. If the line starts ‘name(sect/o/i) . . .’ you can do ‘man section name’ to get the documentation for it. Try ‘whatis ed’ and then you should do ‘man 1 ed’ to get the manual page for ed(l). whatis is actually just the -f option to the man(l) command. whatis uses the whatis database. This database can be created using the -w option of catman(8). FILES / usr/[share]/man/whatis data base SEE ALSO apropos(l), man(l), catman(8) NOTES whatis uses the /usr/man/whatis database, which is created by catman(8). 660 Last change: 9 September 1987 Sun Release 4.1 WHEREIS ( 1 ) USER COMMANDS WHEREIS ( 1 ) NAME whereis - locate the binary, source, and manual page files for a command SYNOPSIS whereis [ -bmsu ] [ -BMS directory. . . -f] filename . . . DESCRIPTION whereis locates source/binary and manuals sections for specified files. The supplied names are first stripped of leading pathname components and any (single) trailing extension of the form .ext, for example, .c. Prefixes of s. resulting from use of source code control are also dealt with, whereis then attempts to locate the desired program in a list of standard places: /usr/bin /usr/bin /usr/5bin /usr/games /usr/hosts /usr/include /usr/local / usr/etc /usr/lib /usr/share/man /usr/src /usr/ucb OPTIONS -b Search only for binaries. — m Search only for manual sections. -s Search only for sources. -u Search for unusual entries. A file is said to be unusual if it does not have one entry of each requested type. Thus ‘whereis -m -u *’ asks for those files in the current directory which have no documentation. -B Change or otherwise limit the places where whereis searches for binaries. -M Change or otherwise limit the places where whereis searches for manual sections. -S Change or otherwise limit the places where whereis searches for sources. -f Terminate the last directory list and signals the start of file names, and must be used when any of the -B, -M, or -S options are used. EXAMPLE Find all files in /usr/bin which are not documented in /usr/share/man/manl with source in /usr/src/cmd: example% cd /usr/ucb example% whereis -u -M /usr/share/man/manl -S /usr/src/cmd -f * FILES /usr/src/* /usr/{doc,man}/* /etc, /usr/{lib, bin, ucb, old, new, local} SEE ALSO chdir(2V) Sun Release 4.1 Last change: 9 September 1987 661 WHEREIS ( 1 ) USER COMMANDS WHEREIS ( 1 ) BUGS Since whereis uses chdir(2V) to run faster, pathnames given with the -M, -S, or -B must be full; that is, they must begin with a 7’. 662 Last change: 9 September 1987 Sun Release 4.1 WHICH ( 1 ) USER COMMANDS WHICH ( 1 ) NAME which - locate a command; display its pathname or alias SYNOPSIS which [ filename ] ... DESCRIPTION which takes a list of names and looks for the files which would be executed had these names been given as commands. Each argument is expanded if it is aliased, and searched for along the user’s path. Both aliases and path are taken from the user’s .cshrc file. FILES "/.cshrc source of aliases and path values SEE ALSO csh(l) DIAGNOSTICS A diagnostic is given for names which are aliased to more than a single word, or if an executable file with the argument name was not found in the path. BUGS Only aliases and paths from "/.cshrc are used; importing from the current environment is not attempted. Must be executed by csh(l), since only csh knows about aliases. To compensate for '/.cshrc files in which aliases depend upon the prompt variable being set, which sets this variable. If the '/.cshrc produces output or prompts for input when prompt is set, which may produce some strange results. Sun Release 4.1 Last change: 9 September 1987 663 WHO ( 1 ) USER COMMANDS WHO ( 1 ) NAME who - who is logged in on the system SYNOPSIS who [ who-file ] [ am i ] DESCRIPTION Used without arguments, who lists the login name, terminal name, and login time for each current user, who gets this information from the /etc/utmp file. If a filename argument is given, the named file is examined instead of /etc/utmp. Typically the named file is /var/adm/wtmp, which contains a record of all logins since it was created. In this case, who lists logins, logouts, and crashes. Each login is listed with user name, terminal name (with /dev/ suppressed), and date and time. Logouts produce a similar line without a user name. Reboots produce a line with ‘ ’ in place of the device name, and a fossil time indicating when the system went down. Finally, the adjacent pair of en- tries ‘I* and *}’ indicate the system-maintained time just before and after a date command changed the system’s idea of the time. With two arguments, as in ‘who am i’ (and also ‘who is who’), who tells who you are logged in as: it displays your hostname, login name, terminal name, and login time. EXAMPLES example% who am i examplelralph ttypO Apr 27 11:24 example % example% who mktg ttymO gwen ttypO ralph ttypl example% Apr 27 11:11 Apr 27 11:25 Apr 27 11:30 FILES /etc/utmp /var/adm/wtmp SEE ALSO login(l), w(l), whoami(l), utmp(5V), Iocale(5) 664 Last change: 23 September 1987 Sun Release 4.1 WHO AMI ( 1 ) USER COMMANDS WHOAMI ( 1 ) NAME whoami - display the effective current username SYNOPSIS whoami DESCRIPTION whoami displays the login name corresponding to the current effective uer ID. If you have used su(lV) to temporarily adopt another user, whoami will report the login name associated with that user ID. whoami gets its information from the geteuid() and getpwuid() library routines (see getuid(2V) and getpwent(3V), respectively). FILES /etc/passwd username data base /etc/utmp database of users currently logged in SEE ALSO su(lV), who(l), getuid(2V), getpwent(3V), utmp(5V) Sun Release 4.1 Last change: 9 September 1987 665 WHOIS(l) USER COMMANDS WHOIS(l) NAME whois - TCP/IP Internet user name directory service SYNOPSIS whois [ -h host ] identifier DESCRIPTION whois searches for an TCP/IP directory entry for an identifier which is either a name (such as “Smith”) or a handle (such as “SRI-NIC”). You can force a name-only search by preceding the name with a period; you can force a handle-only search by preceding the handle with an exclamation point. See EXAMPLES. If you are searching for a group or organization entry, you can have the entire membership list of the group displayed with the record by preceding the argument with (an asterisk). You may of course use an exclamation point and asterisk, or a period and asterisk together. EXAMPLES example % whois Smith looks for name or handle SMITH. exam pie % whois \! SRI-NIC looks for handle SRI-NIC only. example% whois ’.Smith, John’ looks for name “John Smith” only. Adding to the name or handle argument will match anything from that point; that is, ‘ZU...’ will match ZUL, ZUM, etc. 666 Last change; 9 September 1987 Sun Release 4.1 WRITE ( 1 ) USER COMMANDS WRITE ( 1 ) NAME write - write a message to another user SYNOPSIS write username [ ttyname ] DESCRIPTION write copies lines from your standard input to username ’s screen. When you type a write command, the person you are writing to sees a message like this: Message from hostnamelyourname on your tty name After typing the write command, enter the text of your message. What you type appears line-by-line on the other user’s screen. Conclude by typing an EOF indication (CTRL-D) or an interrupt. At this point write displays EOF on your recipient’s screen and exits. To write to a user who is logged in more than once, use the ttyname argument to indicate the appropriate terminal name. You can grant or deny other users permission to write to you by using the mesg command (default allows writing). Certain commands, nroff(l) and pr(lV) in particular, do not allow anyone to write to you while you are using them in order to prevent messy output. If write finds the character T at the beginning of a line, it calls the shell to execute the rest of the line as a command. Two people can carry on a conversation by “writing” to each other. When the other person receives the message indicating you are writing to him, he can then write back to you if he wishes. However, since you are now simultaneously typing and receiving messages, you end up with garbage on your screen unless you work out some sort of scheduling scheme with your partner. You might try the following conventional protocol: when you first write to another user, wait for him to write back before starting to send. Each per- son should end each message with a distinctive signal — -o- (for “over”) is standard — so that the other knows when to begin a reply. To end your conversation, type -oo- (for “over and out”) before finishing the conversation. EXAMPLE Here is an example of a short dialog between two people on different terminals. Two users called “Horace” and “Eudora” are logged in on a system called “jones”. To illustrate the process, both users’ screens are shown side-by-side: Eudora’s Terminal Horace’s Terminal Horace is staring at his screen jones % write horace how about a squash game tonight? -o- Message from jonesieudora on tty09 at 17:05 . . . how about a squash game tonight? -o- jones% write eudora I’m playing tiddlywinks with Carmeline -o- Message from joneslhorace on tty03 at 17:06 ... I’m playing tiddlywinks with Carmeline -o- How about the beach on Sunday? -o- How about the beach on Sunday? -o- Sorry, I’m washing my tent that day -o- Sorry, I’m washing my tent that day -o- See you when I get back from Peru -oo- Sun Release 4.1 Last change: 2 October 1989 667 WRITE ( 1 ) USER COMMANDS WRITE ( 1 ) See you when I get back from Peru -oo- 'D jones% I hear rack of llama is very tasty -oo EOF ENVIRONMENT The environment variables LCCTYPE, LANG, and LC_default control the character classification throughout write. On entry to write, these environment variables are checked in the following order: LC CTYPE, LANG, and LC_default. When a valid value is found, remaining environment variables for character classification are ignored. For example, a new setting for LANG does not override the current valid character classification rules of LC_CTYPE. When none of the values is valid, the shell character classification defaults to the POSIX.l “C” locale. FILES /etc/utmp to find user /usr/bin/sh to execute ! SEE ALSO mail(l), mesg(l), pr(lV), talk(l), troff(l), who(l), locale(5) EOF I hear rack of Hama is very tasty -OO' D jones% 668 Last change: 2 October 1989 Sun Release 4.1 XARGS(IV) USER COMMANDS XARGS(IV) NAME xargs - construct the arguments list(s) and execute a command SYNOPSIS xargs [ — ptx ] [ —eeofstr ] [ — i replstr ] [ —Inumber ] [ — n number ] [ — s size ] [ command [ initial-arguments ] ] AVAILABILITY This command is available with the System V software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION xargs combines the fixed initial-arguments with arguments read from the standard input, to execute the specified command one or more times. The number of arguments read for each command invocation, and the manner in which they are combined are determined by the options specified. command, which may be a shell file, is searched for using one’s $PATH. If command is omitted, /usr/bin/echo is used. Arguments read in from the standard input are defined to be contiguous strings of characters delimited by white space. Empty lines are always discarded. Blanks and tabs may be embedded as part of an argument if they are escaped or quoted. Characters enclosed in quotes (single or double) are taken literally, and the delimiting quotes are removed. Outside of quoted strings, a ‘V (backslash) will escape the character it pre- cedes. Each arguments-list is constructed starting with the initial-arguments, followed by some number of argu- ments read from the standard input (Exception: see the -i option). Options -i, -1, and -n determine how arguments are selected for each command invocation. When none of these options are coded, the initial- arguments are followed by arguments read continuously from the standard input until an internal buffer is full, and then command is executed with the accumulated arguments. This process is repeated until there are none left. When there are option conflicts (for instance, -1 versus -n), the last option takes precedence. xargs will terminate if it receives a return code of-1, or if it cannot execute command. When command is a shell script, it should explicitly exit (see sh(l)) with an appropriate value to avoid accidentally returning with -1. OPTIONS ~P -t — x -eeofstr -ireplstr Sun Release 4. 1 Prompt mode. The user is asked whether to execute command each invocation. Trace mode (-t) is turned on to print the command instance to be executed, followed by a ? . . . prompt. A reply of y (optionally followed by anything) will execute the command; any- thing else, including just a return, skips that particular invocation of command. Trace mode. The command and each constructed argument list are echoed to file descriptor 2 just prior to their execution. Terminate xargs if any argument list would be greater than size characters; -x is forced by the options -i and -1. When neither of the options -i, -1, or -n are coded, the total length of all arguments must be within the size limit. eofstr is taken as the logical EOF string. (underbar) is assumed for the logical EOF string if -e is not coded. The value -e with no eofstr coded turns off the logical EOF string capability (underbar is taken literally), xargs reads the standard input until either EOF or the logical EOF string is encountered. Insert mode: command is executed for each line from the standard input, taking the en- tire line as a single argument, inserting it in initial-arguments for each occurrence of replstr. A maximum of 5 arguments in initial-arguments may each contain one or more Last change: 17 September 1989 669 XARGS(IV) USER COMMANDS XARGS (IV) instances of replstr. SPACE and TAB characters at the beginning of each line are thrown away. Constructed arguments may not grow larger than 255 characters, and option -x is also forced. { } is assumed for replstr if not specified. -\number command is executed for each nonempty number lines of arguments from the standard input. The last invocation of command will be with fewer lines of arguments if fewer than number remain. A line is considered to end with the first NEWLINE unless the last character of the line is a SPACE or a TAB; a trailing SPACE or TAB signals continuation through the next non-empty line. If number is omitted, 1 is assumed. The -x option is forced. Execute command using as many standard input arguments as possible, up to number ar- guments maximum. Fewer arguments will be used if their total size is greater than size characters, and for the last invocation if there are fewer than number arguments remain- ing. If option -x is also coded, each number arguments must fit in the size limitation, else xargs terminates execution. The maximum total size of each argument list is set to size characters; size must be a po- sitive integer less than or equal to 470. If — s is not coded, 470 is taken as the default. Note: the character count for size includes one extra character for each argument and the count of characters in the command name. EXAMPLES The following will move all files from directory $1 to directory $2, and echo each move command just be- fore doing it: Is $1 | xargs -i -t mv $l/{ } $2/{ } The following will combine the output of the parenthesized commands onto one line, which is then echoed to the end of file log: (logname; date; echo $0 $*) | xargs »log The user is asked which files in the current directory are to be archived and archives them into arch(l) one at a time, or many at a time. Is | xargs -p -I ar r arch Is | xargs -p -1 | xargs ar r arch The following will execute diff(l) with successive pairs of arguments originally typed as shell arguments: echo $* | xargs -n2 diff SEE ALSO arch(l), diff(l), sh(l) -n number -s size 670 Last change: 17 September 1989 Sun Release 4.1 XSEND(l) USER COMMANDS XSEND(l) NAME xsend, xget, enroll - send or receive secret mail SYNOPSIS xsend username xget enroll DESCRIPTION These commands implement a secure communication channel, which is like mail(l), but no one can read the messages except the intended recipient. The method embodies a public-key cryptosystem using knap- sacks. To receive messages, use enroll; it asks you for a password that you must subsequently quote in order to receive secret mail. To receive secret mail, use xget. It asks for your password, then gives you the messages. To send secret mail, use xsend in the same manner as the ordinary mail command. Unlike mail, xsend ac- cepts only one target. A message announcing the receipt of secret mail is also sent by ordinary mail. FILES /var/spool/secretmail/*.key keys / var/spool/secretmail/ * . [0-9] messages SEE ALSO mail(l) BUGS The knapsack public-key cryptosystem is known to be breakable. Secret mail should be integrated with ordinary mail. The announcement of secret mail makes “traffic analysis” possible. Sun Release 4.1 Last change: 9 September 1987 671 XSTR(l) USER COMMANDS XSTR(l) NAME xstr — extract strings from C programs to implement shared strings SYNOPSIS xstr — c filename [ -v ] [ -1 array ] xstr [ -1 array ] xstr filename [ — v ] [ — 1 array ] DESCRIPTION xstr maintains a file called strings into which strings in component parts of a large program are hashed. These strings are replaced with references to this common area. This serves to implement shared constant strings, which are most useful if they are also read-only. The command xstr -c filename extracts the strings from the C source in name, replacing string references by expressions of the form &xstr\number] for some number. An appropriate declaration of xstr is prepended to the file. The result- ing C text is placed in the file x.c, to then be compiled. The strings from this file are placed in the strings data base if they are not there already. Repeated strings and strings which are suffixes of existing strings do not cause changes to the data base. After all components of a large program have been compiled, a file declaring the common xstr space called xs.c can be created by a command of the form xstr This xs.c file should then be compiled and loaded with the rest of the program. If possible, the array can be made read-only (shared) saving space and swap overhead. xstr can also be used on a single file. A command xstr filename creates files x.c and xs.c as before, without using or affecting any strings file in the same directory. It may be useful to run xstr after the C preprocessor if any macro definitions yield strings or if there is con- ditional code which contains strings which may not, in fact, be needed, xstr reads from the standard input when the argument is given. An appropriate command sequence for running xstr after the C prepro- cessor is: cc -E name.c | xstr -c - cc -c x.c mv x.o name.o xstr does not touch the file strings unless new items are added; thus make(l) can avoid remaking xs.o un- less truly necessary. OPTIONS -c filename Take C source text from filename . -v Verbose: display a progress report indicating where new or duplicate strings were found. -1 array Specify the named array in program references to abstracted strings. The default array name is xstr. 672 Last change: 19 April 1989 Sun Release 4.1 XSTR(l) USER COMMANDS XSTR(l) FILES strings data base of strings x.c massaged C source xs.c C source for definition of array “xstr” /tmp/xs* temp file when xstr filename doesn’t touch strings SEE ALSO make(l), mkstr(l) BUGS If a string is a suffix of another string in the data base, but the shorter string is seen first by xstr both strings will be placed in the data base, when just placing the longer one there would do. Sun Release 4.1 Last change: 19 April 1989 673 YACC(l) USER COMMANDS YACC(l) NAME yacc - yet another compiler-compiler: parsing program generator SYNOPSIS yacc [ -dvlt ] grammar DESCRIPTION yacc converts a context-free grammar into a set of tables for a simple automaton which executes an LR(1) parsing algorithm. The grammar may be ambiguous, in which case specified precedence rules may be used to break those ambiguities. The output file, y.tab.c, must be compiled by the C compiler to produce a function named yyparse( ). The yyparse( ) function must be loaded with the lexical analyzer yylex( ), as well as main( ) and the error han- dling routine yyerror(). These routines must be supplied by the user; lex(l) is useful for creating lexical analyzers usable by yacc-produced parsers. OPTIONS -d Generate the file y.tab.h with the define statements that associate the yacc-assigned “token codes” with the user-declared “token names” so that source files other than y.tab.c can access the token codes. -v Prepare the file y.output containing a description of the parsing tables and a report on conflicts generated by ambiguities in the grammar. -1 Generate y.tab.c containing no numbered line directives. -t Set the preprocessor symbol yydebug, so y.tab.c will be compiled with runtime debugging code. FILES y.output y.tab.c y.tab.h yacc.tmp, yacc.acts /usr/lib/yaccpar /usr/51ib/liby.a SEE ALSO cc(lV), lex(l) Programming Utilities and Libraries LR Parsing by A. V. Aho and S. C. Johnson, Computing Surveys, June, 1974 DIAGNOSTICS The number of reduce-reduce and shift-reduce conflicts is reported on the standard output; a more detailed report is found in the y.output file. Similarly, it is also reported if some rules are not reachable from the start symbol. NOTES Because the cc(lV) command does not generate or support 8-bit symbol names, it is inappropriate to make yacc 8-bit clean. See cc(lV) for an explanation about why cc is not 8-bit clean. BUGS Because file names are fixed, no more than one yacc process should be active in a given directory at a time. description of parsing tables and conflict report output parser defines for token names temporary files parser prototype for C programs library provides primitive routines main( ) and yyerrorf ) to facilitate the initial use of yacc. 674 Last change: 1 February 1989 Sun Release 4.1 YES ( 1 ) USER COMMANDS YES ( 1 ) NAME yes - be repetitively affirmative SYNOPSIS yes [ expletive ] DESCRIPTION yes repeatedly outputs y, or if expletive is given, that is output repeatedly. Termination is by typing an in- terrupt character. Sun Release 4.1 Last change: 9 September 1987 675 YPCAT(l) USER COMMANDS YPCAT(l) NAME ypcat - print values in a NIS data base SYNOPSIS ypcat [ -kt ] [ -d domainname ] mname ypcat -x AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ypcat prints out values in a Network Information Service (NIS) map specified by mname, which may be ei- ther a map name or a map nickname . Since ypcat uses the NIS service, no NIS server is specified. To look at the network-wide password database, passwd.byname, (with the nickname passwd). type in: ypcat passwd Refer to ypfiles(5) and ypserv(8) for an overview of the NIS service. OPTIONS -k Display the keys for those maps in which the values are null or the key is not part of the value. -t Inhibit translation of mname to map name. For example, ‘ypcat -t passwd’ will fail because there is no map named passwd, whereas ‘ ypcat passwd ’ will be translated to ‘ypcat passwd.byname’. -d domainname Specify a domain other than the default domain. The default domain is returned by domainname. -x Display the map nickname table. This lists the nicknames {mname s) the command knows of, and indicates the mapname associated with each nickname. SEE ALSO domainname(l), ypmatch(l), ypfiles(5), ypserv(8) NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trade- mark in the United Kingdom of British Telecommunications pic, and may not be used without permission. 676 Last change: 17 December 1987 Sun Release 4.1 YPMATCH ( 1 ) USER COMMANDS YPMATCH ( 1 ) NAME ypmatch - print the value of one or more keys from a NIS map SYNOPSIS ypmatch [ -d domain ] [ — k ] [ — t ] key . . . mname ypmatch -x AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ypmatch prints the values associated with one or more keys from the Network Information Service (NIS) map specified by mname , which may be either a mapname or an map nickname. Multiple keys can be specified; the same map will be searched for all . The keys must be exact values insofar as capitalization and length are concerned. No pattern matching is available. If a key is not matched, a diagnostic message is produced. OPTIONS -d Specify a domain other than the default domain. -k Before printing the value of a key, print the key itself, followed by a colon . This is useful only if the keys are not duplicated in the values, or you’ve specified so many keys that the output could be confusing. -t Inhibit translation of nickname to mapname. For example, ‘ypmatch -t zippy passwd ’ will fail because there is no map named passwd, while ‘ypmatch zippy passwd ’ will be translated to ‘ypmatch zippy passwd.byname ’. -x Display the map nickname table. This lists the nicknames ( mnames ) the command knows of, and indicates the mapname associated with each nickname. SEE ALSO ypcat(l), ypfiles(5) NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trade- mark in the United Kingdom of Bridsh Telecommunications pic, and may not be used without permission. Sun Release 4.1 Last change: 17 December 1987 677 YPPASSWD ( 1 ) USER COMMANDS YPPASSWD ( 1 ) NAME yppasswd - change your network password in the NIS database SYNOPSIS yppasswd [ username ] ypchfn [ username ] ypchsh [ username ] AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION yppasswd changes (or installs) the network password associated with the user username (your own name by default) in the Network Information Service (NIS) database. The NIS password may be different from the local one on your own machine. See passwd(l). ypchfn changes the full name associated with username in the NIS database. ypchsh changes the login shell associated with username in the NIS database. yppasswd prompts for the old NIS password, and then for the new one. You must type in the old password correctly for the change to take effect. 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, and at least six characters long if monocase. These rules are relaxed if you are insistent enough. Only the owner of the name or the super-user may change a password; in either case you must prove you know the old password. The NIS password daemon, yppasswdd(8C) must be running on your NIS server in order for the new pass- word to take effect. SEE ALSO passwd(l), ypfiles(5), yppasswdd(8C) BUGS The update protocol passes all the information to the server in one RPC call, without ever looking at it. Thus if you type in your old password incorrectly, you will not be notified until after you have entered your new password. NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trade- mark in the United Kingdom of British Telecommunications pic, and may not be used without permission. 678 Last change; 20 January 1990 Sun Release 4.1 YPWHICH ( 1 ) USER COMMANDS YPWHICH ( 1 ) NAME ypwhich - return hostname of NIS server or map master SYNOPSIS ypwhich [ -d [ domain ] ] [ -VI I -V2 ] [ hostname ] ypwhich [ -t mapname ] [ d domain ] — m [ mname ] ypwhich -x AVAILABILITY This command is available with the Networking software installation option. Refer to Installing SunOS 4.1 for information on how to install optional software. DESCRIPTION ypwhich tells which Network Information Service (NIS) server supplies NIS services to an NIS client, or which is the master for a map. If invoked without arguments, it gives the NIS server for the local machine. If hostname is specified, that machine is queried to find out which NIS server it is using. Refer to ypfiles(5) and ypserv(8) for an overview of the NIS services. OPTIONS -d Use domain instead of the default domain. -VI Which server is serving v.l NIS protocol-speaking client processes. -V2 Which server is serving v.2 NIS protocol client processes. If neither version is specified, ypwhich attempts to locate the server that supplies the (current) v.2 services. If there is no v.2 server currently bound, ypwhich then attempts to locate the server sup- plying the v.l services. Since NIS servers and NIS clients are both backward compatible, the user need seldom be concerned about which version is currently in use. -t mapname Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is not true of any Sun-supplied map. -m Find the master NIS server for a map. No hostname can be specified with the -m option, mname can be a mapname, or a nickname for a map. When mname is omitted, produce a list available maps. -x Display the map nickname table. This lists the nicknames ( mnames ) the command knows of, and indicates the mapname associated with each nickname. SEE ALSO ypfiles(5), rpcinfo(8C), ypserv(8), ypset(8) NOTES The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trade- mark in the United Kingdom of British Telecommunications pic, and may not be used without permission. Sun Release 4. 1 Last change: 17 December 1987 679 Notes