GAWK(1) Utility Commands GAWK(1) NAME gawk - pattern scanning and processing language SYNOPSIS gawk [ POSIX or GNU style options ] -f _p_r_o_g_r_a_m-_f_i_l_e [ - - ] file ... gawk [ POSIX or GNU style options ] [ -- ] _p_r_o_g_r_a_m-_t_e_x_t file ... DESCRIPTION _G_a_w_k is the GNU Project's implementation of the AWK program- ming language. It conforms to the definition of the language in the POSIX 1003.2 Command Language And Utilities Standard. This version in turn is based on the description in _T_h_e _A_W_K _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e, by Aho, Kernighan, and Weinberger, with the additional features defined in the Sys- tem V Release 4 version of UNIX _a_w_k. _G_a_w_k also provides some GNU-specific extensions. The command line consists of options to _g_a_w_k itself, the AWK program text (if not supplied via the -f or --file options), and values to be made available in the ARGC and ARGV pre- defined AWK variables. OPTIONS _G_a_w_k options may be either the traditional POSIX one letter options, or the GNU style long options. POSIX style options start with a single ``-'', while GNU long options start with `` - -''. GNU style long options are provided for both GNU- specific features and for POSIX mandated features. Other implementations of the AWK language are likely to only accept the traditional one letter options. Following the POSIX standard, _g_a_w_k-specific options are sup- plied via arguments to the -W option. Multiple -W options may be supplied, or multiple arguments may be supplied together if they are separated by commas, or enclosed in quotes and separated by white space. Case is ignored in arguments to the - W option. Each - W option has a corresponding GNU style long option, as detailed below. Arguments to GNU style long options are either joined with the option by an = sign, with no intervening spaces, or they may be provided in the next command line argument. _G_a_w_k accepts the following options. -F _f_s --field-separator=_f_s Use _f_s for the input field separator (the value of the FS predefined variable). -v _v_a_r=_v_a_l Free Software FoundatiLoanst change: Apr 18 1994 1 GAWK(1) Utility Commands GAWK(1) --assign=_v_a_r=_v_a_l Assign the value _v_a_l, to the variable _v_a_r, before exe- cution of the program begins. Such variable values are available to the BEGIN block of an AWK program. -f _p_r_o_g_r_a_m-_f_i_l_e --file=_p_r_o_g_r_a_m-_f_i_l_e Read the AWK program source from the file _p_r_o_g_r_a_m-_f_i_l_e, instead of from the first command line argument. Mul- tiple -f (or --file) options may be used. -mf=_N_N_N -mr=_N_N_N Set various memory limits to the value _N_N_N. The f flag sets the maximum number of fields, and the r flag sets the maximum record size. These two flags and the - m option are from the AT&T Bell Labs research version of UNIX _a_w_k. They are ignored by _g_a_w_k, since _g_a_w_k has no pre-defined limits. -W compat --compat Run in _c_o_m_p_a_t_i_b_i_l_i_t_y mode. In compatibility mode, _g_a_w_k behaves identically to UNIX _a_w_k; none of the GNU-specific extensions are recognized. See GNU EXTENSIONS, below, for more information. -W copyleft -W copyright --copyleft --copyright Print the short version of the GNU copyright information message on the error output. -W help -W usage --help --usage Print a relatively short summary of the avail- able options on the error output. Per the GNU Coding Standards, these options cause an immedi- ate, successful exit. -W lint --lint Provide warnings about constructs that are dubious or non-portable to other AWK implementa- tions. -W posix --posix This turns on _c_o_m_p_a_t_i_b_i_l_i_t_y mode, with the following additional restrictions: +o \x escape sequences are not recognized. +o The synonym func for the keyword function is not recognized. Free Software FoundatiLoanst change: Apr 18 1994 2 GAWK(1) Utility Commands GAWK(1) +o The operators ** and **= cannot be used in place of ^ and ^=. -W source=_p_r_o_g_r_a_m-_t_e_x_t --source=_p_r_o_g_r_a_m-_t_e_x_t Use _p_r_o_g_r_a_m-_t_e_x_t as AWK program source code. This option allows the easy intermixing of library functions (used via the -f and - - file options) with source code entered on the command line. It is intended primarily for medium to large size AWK programs used in shell scripts. The -W source= form of this option uses the rest of the command line argument for _p_r_o_g_r_a_m-_t_e_x_t; no other options to -W will be recognized in the same argument. -W version --version Print version information for this particular copy of _g_a_w_k on the error output. This is use- ful mainly for knowing if the current copy of _g_a_w_k on your system is up to date with respect to whatever the Free Software Foundation is dis- tributing. Per the GNU Coding Standards, these options cause an immediate, successful exit. -- Signal the end of options. This is useful to allow further arguments to the AWK program itself to start with a ``-''. This is mainly for consistency with the argument parsing con- vention used by most other POSIX programs. In compatibility mode, any other options are flagged as illegal, but are otherwise ignored. In normal operation, as long as program text has been supplied, unknown options are passed on to the AWK program in the ARGV array for process- ing. This is particularly useful for running AWK programs via the ``#!'' executable interpreter mechanism. AWK PROGRAM EXECUTION An AWK program consists of a sequence of pattern-action statements and optional function definitions. _p_a_t_t_e_r_n { _a_c_t_i_o_n _s_t_a_t_e_m_e_n_t_s } function _n_a_m_e(_p_a_r_a_m_e_t_e_r _l_i_s_t) { _s_t_a_t_e_m_e_n_t_s } _G_a_w_k first reads the program source from the _p_r_o_g_r_a_m-_f_i_l_e(s) if specified, from arguments to -W source=, or from the first non-option argument on the command line. The -f and - W source= options may be used multiple times on the command line. _G_a_w_k will read the program text as if all the _p_r_o_g_r_a_m-_f_i_l_es and command line source texts had been con- catenated together. This is useful for building libraries Free Software FoundatiLoanst change: Apr 18 1994 3 GAWK(1) Utility Commands GAWK(1) of AWK functions, without having to include them in each new AWK program that uses them. It also provides the ability to mix library functions with command line programs. The environment variable AWKPATH specifies a search path to use when finding source files named with the -f option. If this variable does not exist, the default path is ".:/usr/lib/awk:/usr/local/lib/awk". If a file name given to the -f option contains a ``/'' character, no path search is performed. _G_a_w_k executes AWK programs in the following order. First, all variable assignments specified via the -v option are performed. Next, _g_a_w_k compiles the program into an internal form. Then, _g_a_w_k executes the code in the BEGIN block(s) (if any), and then proceeds to read each file named in the ARGV array. If there are no files named on the command line, _g_a_w_k reads the standard input. If a filename on the command line has the form _v_a_r=_v_a_l it is treated as a variable assignment. The variable _v_a_r will be assigned the value _v_a_l. (This happens after any BEGIN block(s) have been run.) Command line variable assignment is most useful for dynamically assigning values to the vari- ables AWK uses to control how input is broken into fields and records. It is also useful for controlling state if mul- tiple passes are needed over a single data file. If the value of a particular element of ARGV is empty (""), _g_a_w_k skips over it. For each line in the input, _g_a_w_k tests to see if it matches any _p_a_t_t_e_r_n in the AWK program. For each pattern that the line matches, the associated _a_c_t_i_o_n is executed. The pat- terns are tested in the order they occur in the program. Finally, after all the input is exhausted, _g_a_w_k executes the code in the END block(s) (if any). VARIABLES AND FIELDS AWK variables are dynamic; they come into existence when they are first used. Their values are either floating-point numbers or strings, or both, depending upon how they are used. AWK also has one dimensional arrays; arrays with mul- tiple dimensions may be simulated. Several pre-defined variables are set as a program runs; these will be described as needed and summarized below. Fields As each input line is read, _g_a_w_k splits the line into _f_i_e_l_d_s, using the value of the FS variable as the field separator. If FS is a single character, fields are Free Software FoundatiLoanst change: Apr 18 1994 4 GAWK(1) Utility Commands GAWK(1) separated by that character. Otherwise, FS is expected to be a full regular expression. In the special case that FS is a single blank, fields are separated by runs of blanks and/or tabs. Note that the value of IGNORECASE (see below) will also affect how fields are split when FS is a regular expression. If the FIELDWIDTHS variable is set to a space separated list of numbers, each field is expected to have fixed width, and _g_a_w_k will split up the record using the specified widths. The value of FS is ignored. Assigning a new value to FS overrides the use of FIELDWIDTHS, and restores the default behavior. Each field in the input line may be referenced by its posi- tion, $1, $2, and so on. $0 is the whole line. The value of a field may be assigned to as well. Fields need not be referenced by constants: n = 5 print $n prints the fifth field in the input line. The variable NF is set to the total number of fields in the input line. References to non-existent fields (i.e. fields after $NF) produce the null-string. However, assigning to a non- existent field (e.g., $(NF+2) = 5) will increase the value of NF, create any intervening fields with the null string as their value, and cause the value of $0 to be recomputed, with the fields being separated by the value of OFS. Refer- ences to negative numbered fields cause a fatal error. Built-in Variables AWK's built-in variables are: ARGC The number of command line arguments (does not include options to _g_a_w_k, or the program source). ARGIND The index in ARGV of the current file being pro- cessed. ARGV Array of command line arguments. The array is indexed from 0 to ARGC - 1. Dynamically chang- ing the contents of ARGV can control the files used for data. CONVFMT The conversion format for numbers, "%.6g", by default. ENVIRON An array containing the values of the current environment. The array is indexed by the Free Software FoundatiLoanst change: Apr 18 1994 5 GAWK(1) Utility Commands GAWK(1) environment variables, each element being the value of that variable (e.g., ENVIRON["HOME"] might be /u/arnold). Changing this array does not affect the environment seen by programs which _g_a_w_k spawns via redirection or the sys- tem() function. (This may change in a future version of _g_a_w_k.) ERRNO If a system error occurs either doing a redirec- tion for getline, during a read for getline, or during a close(), then ERRNO will contain a string describing the error. FIELDWIDTHS A white-space separated list of fieldwidths. When set, _g_a_w_k parses the input into fields of fixed width, instead of using the value of the FS variable as the field separator. The fixed field width facility is still experimental; expect the semantics to change as _g_a_w_k evolves over time. FILENAME The name of the current input file. If no files are specified on the command line, the value of FILENAME is ``-''. However, FILENAME is unde- fined inside the BEGIN block. FNR The input record number in the current input file. FS The input field separator, a blank by default. IGNORECASE Controls the case-sensitivity of all regular expression operations. If IGNORECASE has a non- zero value, then pattern matching in rules, field splitting with FS, regular expression matching with ~ and !~, and the gsub(), index(), match(), split(), and sub() pre-defined func- tions will all ignore case when doing regular expression operations. Thus, if IGNORECASE is not equal to zero, /aB/ matches all of the strings "ab", "aB", "Ab", and "AB". As with all AWK variables, the initial value of IGNORECASE is zero, so all regular expression operations are normally case-sensitive. NF The number of fields in the current input record. NR The total number of input records seen so far. OFMT The output format for numbers, "%.6g", by default. Free Software FoundatiLoanst change: Apr 18 1994 6 GAWK(1) Utility Commands GAWK(1) OFS The output field separator, a blank by default. ORS The output record separator, by default a new- line. RS The input record separator, by default a new- line. RS is exceptional in that only the first character of its string value is used for separating records. (This will probably change in a future release of _g_a_w_k.) If RS is set to the null string, then records are separated by blank lines. When RS is set to the null string, then the newline character always acts as a field separator, in addition to whatever value FS may have. RSTART The index of the first character matched by match(); 0 if no match. RLENGTH The length of the string matched by match(); - 1 if no match. SUBSEP The character used to separate multiple sub- scripts in array elements, by default "\034". Arrays Arrays are subscripted with an expression between square brackets ([ and ]). If the expression is an expression list (_e_x_p_r, _e_x_p_r ...) then the array subscript is a string con- sisting of the concatenation of the (string) value of each expression, separated by the value of the SUBSEP variable. This facility is used to simulate multiply dimensioned arrays. For example: i = "A" ; j = "B" ; k = "C" x[i, j, k] = "hello, world\n" assigns the string "hello, world\n" to the element of the array x which is indexed by the string "A\034B\034C". All arrays in AWK are associative, i.e. indexed by string values. The special operator in may be used in an if or while state- ment to see if an array has an index consisting of a partic- ular value. if (val in array) print array[val] If the array has multiple subscripts, use (i, j) in array. Free Software FoundatiLoanst change: Apr 18 1994 7 GAWK(1) Utility Commands GAWK(1) The in construct may also be used in a for loop to iterate over all the elements of an array. An element may be deleted from an array using the delete statement. The delete statement may also be used to delete the entire contents of an array. Variable Typing And Conversion Variables and fields may be (floating point) numbers, or strings, or both. How the value of a variable is interpreted depends upon its context. If used in a numeric expression, it will be treated as a number, if used as a string it will be treated as a string. To force a variable to be treated as a number, add 0 to it; to force it to be treated as a string, concatenate it with the null string. When a string must be converted to a number, the conversion is accomplished using _a_t_o_f(3). A number is converted to a string by using the value of CONVFMT as a format string for _s_p_r_i_n_t_f(3), with the numeric value of the variable as the argument. However, even though all numbers in AWK are floating-point, integral values are _a_l_w_a_y_s converted as integers. Thus, given CONVFMT = "%2.2f" a = 12 b = a "" the variable b has a string value of "12" and not "12.00". _G_a_w_k performs comparisons as follows: If two variables are numeric, they are compared numerically. If one value is numeric and the other has a string value that is a ``numeric string,'' then comparisons are also done numerically. Oth- erwise, the numeric value is converted to a string and a string comparison is performed. Two strings are compared, of course, as strings. According to the POSIX standard, even if two strings are numeric strings, a numeric com- parison is performed. However, this is clearly incorrect, and _g_a_w_k does not do this. Uninitialized variables have the numeric value 0 and the string value "" (the null, or empty, string). PATTERNS AND ACTIONS AWK is a line oriented language. The pattern comes first, and then the action. Action statements are enclosed in { and }. Either the pattern may be missing, or the action may be missing, but, of course, not both. If the pattern is miss- ing, the action will be executed for every single line of Free Software FoundatiLoanst change: Apr 18 1994 8 GAWK(1) Utility Commands GAWK(1) input. A missing action is equivalent to { print } which prints the entire line. Comments begin with the ``#'' character, and continue until the end of the line. Blank lines may be used to separate statements. Normally, a statement ends with a newline, how- ever, this is not the case for lines ending in a ``,'', ``{'', ``?'', ``:'', ``&&'', or ``||''. Lines ending in do or else also have their statements automatically continued on the following line. In other cases, a line can be con- tinued by ending it with a ``\'', in which case the newline will be ignored. Multiple statements may be put on one line by separating them with a ``;''. This applies to both the statements within the action part of a pattern-action pair (the usual case), and to the pattern-action statements themselves. Patterns AWK patterns may be one of the following: BEGIN END /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n/ _r_e_l_a_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n _p_a_t_t_e_r_n && _p_a_t_t_e_r_n _p_a_t_t_e_r_n || _p_a_t_t_e_r_n _p_a_t_t_e_r_n ? _p_a_t_t_e_r_n : _p_a_t_t_e_r_n (_p_a_t_t_e_r_n) ! _p_a_t_t_e_r_n _p_a_t_t_e_r_n_1, _p_a_t_t_e_r_n_2 BEGIN and END are two special kinds of patterns which are not tested against the input. The action parts of all BEGIN patterns are merged as if all the statements had been writ- ten in a single BEGIN block. They are executed before any of the input is read. Similarly, all the END blocks are merged, and executed when all the input is exhausted (or when an exit statement is executed). BEGIN and END patterns cannot be combined with other patterns in pattern expressions. BEGIN and END patterns cannot have missing action parts. For /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n/ patterns, the associated statement is executed for each input line that matches the regular expression. Regular expressions are the same as those in _e_g_r_e_p(1), and are summarized below. A _r_e_l_a_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n may use any of the operators defined below in the section on actions. These generally test Free Software FoundatiLoanst change: Apr 18 1994 9 GAWK(1) Utility Commands GAWK(1) whether certain fields match certain regular expressions. The &&, ||, and ! operators are logical AND, logical OR, and logical NOT, respectively, as in C. They do short-circuit evaluation, also as in C, and are used for combining more primitive pattern expressions. As in most languages, parentheses may be used to change the order of evaluation. The ?: operator is like the same operator in C. If the first pattern is true then the pattern used for testing is the second pattern, otherwise it is the third. Only one of the second and third patterns is evaluated. The _p_a_t_t_e_r_n_1, _p_a_t_t_e_r_n_2 form of an expression is called a _r_a_n_g_e _p_a_t_t_e_r_n. It matches all input records starting with a line that matches _p_a_t_t_e_r_n_1, and continuing until a record that matches _p_a_t_t_e_r_n_2, inclusive. It does not combine with any other sort of pattern expression. Regular Expressions Regular expressions are the extended kind found in _e_g_r_e_p. They are composed of characters as follows: _c matches the non-metacharacter _c. \_c matches the literal character _c. . matches any character except newline. ^ matches the beginning of a line or a string. $ matches the end of a line or a string. [_a_b_c...] character class, matches any of the characters _a_b_c.... [^_a_b_c...] negated character class, matches any character except _a_b_c... and newline. _r_1|_r_2 alternation: matches either _r_1 or _r_2. _r_1_r_2 concatenation: matches _r_1, and then _r_2. _r+ matches one or more _r's. _r* matches zero or more _r's. _r? matches zero or one _r's. (_r) grouping: matches _r. Free Software FoundatiLoanst change: Apr 18 1994 10 GAWK(1) Utility Commands GAWK(1) The escape sequences that are valid in string constants (see below) are also legal in regular expressions. Actions Action statements are enclosed in braces, { and }. Action statements consist of the usual assignment, conditional, and looping statements found in most languages. The operators, control statements, and input/output statements available are patterned after those in C. Operators The operators in AWK, in order of increasing precedence, are = += -= *= /= %= ^= Assignment. Both absolute assignment (_v_a_r = _v_a_l_u_e) and operator-assignment (the other forms) are supported. ?: The C conditional expression. This has the form _e_x_p_r_1 ? _e_x_p_r_2 : _e_x_p_r_3. If _e_x_p_r_1 is true, the value of the expression is _e_x_p_r_2, otherwise it is _e_x_p_r_3. Only one of _e_x_p_r_2 and _e_x_p_r_3 is evaluated. || Logical OR. && Logical AND. ~ !~ Regular expression match, negated match. NOTE: Do not use a constant regular expression (/foo/) on the left-hand side of a ~ or !~. Only use one on the right-hand side. The expression /foo/ ~ _e_x_p has the same meaning as (($0 ~ /foo/) ~ _e_x_p). This is usually _n_o_t what was intended. < > <= >= != == The regular relational operators. _b_l_a_n_k String concatenation. + - Addition and subtraction. * / % Multiplication, division, and modulus. + - ! Unary plus, unary minus, and logical negation. ^ Exponentiation (** may also be used, and **= for the assignment operator). ++ - - Increment and decrement, both prefix and Free Software FoundatiLoanst change: Apr 18 1994 11 GAWK(1) Utility Commands GAWK(1) postfix. $ Field reference. Control Statements The control statements are as follows: if (_c_o_n_d_i_t_i_o_n) _s_t_a_t_e_m_e_n_t [ else _s_t_a_t_e_m_e_n_t ] while (_c_o_n_d_i_t_i_o_n) _s_t_a_t_e_m_e_n_t do _s_t_a_t_e_m_e_n_t while (_c_o_n_d_i_t_i_o_n) for (_e_x_p_r_1; _e_x_p_r_2; _e_x_p_r_3) _s_t_a_t_e_m_e_n_t for (_v_a_r in _a_r_r_a_y) _s_t_a_t_e_m_e_n_t break continue delete _a_r_r_a_y[_i_n_d_e_x] delete _a_r_r_a_y exit [ _e_x_p_r_e_s_s_i_o_n ] { _s_t_a_t_e_m_e_n_t_s } I/O Statements The input/output statements are as follows: close(_f_i_l_e_n_a_m_e) Close file (or pipe, see below). getline Set $0 from next input record; set NF, NR, FNR. getline <_f_i_l_e Set $0 from next record of _f_i_l_e; set NF. getline _v_a_r Set _v_a_r from next input record; set NF, FNR. getline _v_a_r <_f_i_l_e Set _v_a_r from next record of _f_i_l_e. next Stop processing the current input record. The next input record is read and processing starts over with the first pattern in the AWK program. If the end of the input data is reached, the END block(s), if any, are exe- cuted. next file Stop processing the current input file. The next input record read comes from the next input file. FILENAME is updated, FNR is reset to 1, and processing starts over with the first pattern in the AWK program. If the end of the input data is reached, the END block(s), if any, are exe- cuted. Free Software FoundatiLoanst change: Apr 18 1994 12 GAWK(1) Utility Commands GAWK(1) print Prints the current record. print _e_x_p_r-_l_i_s_t Prints expressions. Each expression is separated by the value of the OFS variable. The output record is ter- minated with the value of the ORS variable. print _e_x_p_r-_l_i_s_t >_f_i_l_e Prints expressions on _f_i_l_e. Each expression is separated by the value of the OFS variable. The output record is terminated with the value of the ORS variable. printf _f_m_t, _e_x_p_r-_l_i_s_t Format and print. printf _f_m_t, _e_x_p_r-_l_i_s_t >_f_i_l_e Format and print on _f_i_l_e. system(_c_m_d-_l_i_n_e) Execute the command _c_m_d-_l_i_n_e, and return the exit status. (This may not be available on non-POSIX systems.) Other input/output redirections are also allowed. For print and printf, >>_f_i_l_e appends output to the _f_i_l_e, while | _c_o_m_- _m_a_n_d writes on a pipe. In a similar fashion, _c_o_m_m_a_n_d | get- line pipes into getline. The getline command will return 0 on end of file, and -1 on an error. The _p_r_i_n_t_f Statement The AWK versions of the printf statement and sprintf() func- tion (see below) accept the following conversion specifica- tion formats: %c An ASCII character. If the argument used for %c is numeric, it is treated as a character and printed. Otherwise, the argument is assumed to be a string, and the only first character of that string is printed. %d A decimal number (the integer part). %i Just like %d. %e A floating point number of the form [-]d.ddddddE[+-]dd. %f A floating point number of the form [-]ddd.dddddd. %g Use e or f conversion, whichever is shorter, with non- significant zeros suppressed. %o An unsigned octal number (again, an integer). Free Software FoundatiLoanst change: Apr 18 1994 13 GAWK(1) Utility Commands GAWK(1) %s A character string. %x An unsigned hexadecimal number (an integer). %X Like %x, but using ABCDEF instead of abcdef. %% A single % character; no argument is converted. There are optional, additional parameters that may lie between the % and the control letter: - The expression should be left-justified within its field. _w_i_d_t_h The field should be padded to this width. If the number has a leading zero, then the field will be padded with zeros. Otherwise it is padded with blanks. This applies even to the non-numeric output formats. ._p_r_e_c A number indicating the maximum width of strings or digits to the right of the decimal point. The dynamic _w_i_d_t_h and _p_r_e_c capabilities of the ANSI C printf() routines are supported. A * in place of either the width or prec specifications will cause their values to be taken from the argument list to printf or sprintf(). Special File Names When doing I/O redirection from either print or printf into a file, or via getline from a file, _g_a_w_k recognizes certain special filenames internally. These filenames allow access to open file descriptors inherited from _g_a_w_k's parent pro- cess (usually the shell). Other special filenames provide access information about the running gawk process. The filenames are: /dev/pid Reading this file returns the process ID of the current process, in decimal, terminated with a newline. /dev/ppid Reading this file returns the parent process ID of the current process, in decimal, terminated with a newline. /dev/pgrpid Reading this file returns the process group ID of the current process, in decimal, terminated with a newline. /dev/user Reading this file returns a single record ter- minated with a newline. The fields are Free Software FoundatiLoanst change: Apr 18 1994 14 GAWK(1) Utility Commands GAWK(1) separated with blanks. $1 is the value of the _g_e_t_u_i_d(2) system call, $2 is the value of the _g_e_t_e_u_i_d(2) system call, $3 is the value of the _g_e_t_g_i_d(2) system call, and $4 is the value of the _g_e_t_e_g_i_d(2) system call. If there are any additional fields, they are the group IDs returned by _g_e_t_g_r_o_u_p_s(2). Multiple groups may not be supported on all systems. /dev/stdin The standard input. /dev/stdout The standard output. /dev/stderr The standard error output. /dev/fd/_n The file associated with the open file descrip- tor _n. These are particularly useful for error messages. For exam- ple: print "You blew it!" > "/dev/stderr" whereas you would otherwise have to use print "You blew it!" | "cat 1>&2" These file names may also be used on the command line to name data files. Numeric Functions AWK has the following pre-defined arithmetic functions: atan2(_y, _x) returns the arctangent of _y/_x in radians. cos(_e_x_p_r) returns the cosine in radians. exp(_e_x_p_r) the exponential function. int(_e_x_p_r) truncates to integer. log(_e_x_p_r) the natural logarithm function. rand() returns a random number between 0 and 1. sin(_e_x_p_r) returns the sine in radians. sqrt(_e_x_p_r) the square root function. srand(_e_x_p_r) use _e_x_p_r as a new seed for the random number generator. If no _e_x_p_r is provided, the time of day will be used. The return value is the Free Software FoundatiLoanst change: Apr 18 1994 15 GAWK(1) Utility Commands GAWK(1) previous seed for the random number generator. String Functions AWK has the following pre-defined string functions: gsub(_r, _s, _t) for each substring matching the reg- ular expression _r in the string _t, substitute the string _s, and return the number of substitutions. If _t is not supplied, use $0. index(_s, _t) returns the index of the string _t in the string _s, or 0 if _t is not present. length(_s) returns the length of the string _s, or the length of $0 if _s is not sup- plied. match(_s, _r) returns the position in _s where the regular expression _r occurs, or 0 if _r is not present, and sets the values of RSTART and RLENGTH. split(_s, _a, _r) splits the string _s into the array _a on the regular expression _r, and returns the number of fields. If _r is omitted, FS is used instead. The array _a is cleared first. sprintf(_f_m_t, _e_x_p_r-_l_i_s_t) prints _e_x_p_r-_l_i_s_t according to _f_m_t, and returns the resulting string. sub(_r, _s, _t) just like gsub(), but only the first matching substring is replaced. substr(_s, _i, _n) returns the _n-character substring of _s starting at _i. If _n is omitted, the rest of _s is used. tolower(_s_t_r) returns a copy of the string _s_t_r, with all the upper-case characters in _s_t_r translated to their corresponding lower-case counter- parts. Non-alphabetic characters are left unchanged. toupper(_s_t_r) returns a copy of the string _s_t_r, with all the lower-case characters in _s_t_r translated to their corresponding upper-case counter- parts. Non-alphabetic characters Free Software FoundatiLoanst change: Apr 18 1994 16 GAWK(1) Utility Commands GAWK(1) are left unchanged. Time Functions Since one of the primary uses of AWK programs is processing log files that contain time stamp information, _g_a_w_k provides the following two functions for obtaining time stamps and formatting them. systime() returns the current time of day as the number of seconds since the Epoch (Midnight UTC, January 1, 1970 on POSIX systems). strftime(_f_o_r_m_a_t, _t_i_m_e_s_t_a_m_p) formats _t_i_m_e_s_t_a_m_p according to the specification in _f_o_r_m_a_t. The _t_i_m_e_s_t_a_m_p should be of the same form as returned by systime(). If _t_i_m_e_s_t_a_m_p is missing, the current time of day is used. See the specification for the strftime() function in ANSI C for the format conversions that are guaranteed to be available. A public-domain version of _s_t_r_f_t_i_m_e(3) and a man page for it are shipped with _g_a_w_k; if that version was used to build _g_a_w_k, then all of the conversions described in that man page are available to _g_a_w_k. String Constants String constants in AWK are sequences of characters enclosed between double quotes ("). Within strings, certain _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s are recognized, as in C. These are: \\ A literal backslash. \a The ``alert'' character; usually the ASCII BEL charac- ter. \b backspace. \f form-feed. \n new line. \r carriage return. \t horizontal tab. \v vertical tab. \x_h_e_x _d_i_g_i_t_s The character represented by the string of hexadecimal digits following the \x. As in ANSI C, all following hexadecimal digits are considered part of the escape sequence. (This feature should tell us something about Free Software FoundatiLoanst change: Apr 18 1994 17 GAWK(1) Utility Commands GAWK(1) language design by committee.) E.g., "\x1B" is the ASCII ESC (escape) character. \_d_d_d The character represented by the 1-, 2-, or 3-digit sequence of octal digits. E.g. "\033" is the ASCII ESC (escape) character. \_c The literal character _c. The escape sequences may also be used inside constant regu- lar expressions (e.g., /[ \t\f\n\r\v]/ matches whitespace characters). FUNCTIONS Functions in AWK are defined as follows: function _n_a_m_e(_p_a_r_a_m_e_t_e_r _l_i_s_t) { _s_t_a_t_e_m_e_n_t_s } Functions are executed when called from within the action parts of regular pattern-action statements. Actual parame- ters supplied in the function call are used to instantiate the formal parameters declared in the function. Arrays are passed by reference, other variables are passed by value. Since functions were not originally part of the AWK language, the provision for local variables is rather clumsy: They are declared as extra parameters in the parame- ter list. The convention is to separate local variables from real parameters by extra spaces in the parameter list. For example: function f(p, q, a, b) { # a & b are local ..... } /abc/ { ... ; f(1, 2) ; ... } The left parenthesis in a function call is required to immediately follow the function name, without any interven- ing white space. This is to avoid a syntactic ambiguity with the concatenation operator. This restriction does not apply to the built-in functions listed above. Functions may call each other and may be recursive. Func- tion parameters used as local variables are initialized to the null string and the number zero upon function invoca- tion. The word func may be used in place of function. EXAMPLES Print and sort the login names of all users: Free Software FoundatiLoanst change: Apr 18 1994 18 GAWK(1) Utility Commands GAWK(1) BEGIN { FS = ":" } { print $1 | "sort" } Count lines in a file: { nlines++ } END { print nlines } Precede each line by its number in the file: { print FNR, $0 } Concatenate and line number (a variation on a theme): { print NR, $0 } SEE ALSO _e_g_r_e_p(1), _g_e_t_p_i_d(2), _g_e_t_p_p_i_d(2), _g_e_t_p_g_r_p(2), _g_e_t_u_i_d(2), _g_e_t_e_u_i_d(2), _g_e_t_g_i_d(2), _g_e_t_e_g_i_d(2), _g_e_t_g_r_o_u_p_s(2) _T_h_e _A_W_K _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e, Alfred V. Aho, Brian W. Ker- nighan, Peter J. Weinberger, Addison-Wesley, 1988. ISBN 0- 201-07981-X. _T_h_e _G_A_W_K _M_a_n_u_a_l, Edition 0.15, published by the Free Software Foundation, 1993. POSIX COMPATIBILITY A primary goal for _g_a_w_k is compatibility with the POSIX standard, as well as with the latest version of UNIX _a_w_k. To this end, _g_a_w_k incorporates the following user visible features which are not described in the AWK book, but are part of _a_w_k in System V Release 4, and are in the POSIX standard. The -v option for assigning variables before program execu- tion starts is new. The book indicates that command line variable assignment happens when _a_w_k would otherwise open the argument as a file, which is after the BEGIN block is executed. However, in earlier implementations, when such an assignment appeared before any file names, the assignment would happen _b_e_f_o_r_e the BEGIN block was run. Applications came to depend on this ``feature.'' When _a_w_k was changed to match its documentation, this option was added to accommo- date applications that depended upon the old behavior. (This feature was agreed upon by both the AT&T and GNU developers.) The -W option for implementation specific features is from the POSIX standard. Free Software FoundatiLoanst change: Apr 18 1994 19 GAWK(1) Utility Commands GAWK(1) When processing arguments, _g_a_w_k uses the special option ``-- '' to signal the end of arguments. In compatibility mode, it will warn about, but otherwise ignore, undefined options. In normal operation, such arguments are passed on to the AWK program for it to process. The AWK book does not define the return value of srand(). The System V Release 4 version of UNIX _a_w_k (and the POSIX standard) has it return the seed it was using, to allow keeping track of random number sequences. Therefore srand() in _g_a_w_k also returns its current seed. Other new features are: The use of multiple - f options (from MKS _a_w_k); the ENVIRON array; the \a, and \v escape sequences (done originally in _g_a_w_k and fed back into AT&T's); the tolower() and toupper() built-in functions (from AT&T); and the ANSI C conversion specifications in printf (done first in AT&T's version). GNU EXTENSIONS _G_a_w_k has some extensions to POSIX _a_w_k. They are described in this section. All the extensions described here can be disabled by invoking _g_a_w_k with the -W compat option. The following features of _g_a_w_k are not available in POSIX _a_w_k. +o The \x escape sequence. +o The systime() and strftime() functions. +o The special file names available for I/O redirection are not recognized. +o The ARGIND and ERRNO variables are not special. +o The IGNORECASE variable and its side-effects are not available. +o The FIELDWIDTHS variable and fixed width field splitting. +o No path search is performed for files named via the - f option. Therefore the AWKPATH environment vari- able is not special. +o The use of next file to abandon processing of the current input file. +o The use of delete _a_r_r_a_y to delete the entire con- tents of an array. Free Software FoundatiLoanst change: Apr 18 1994 20 GAWK(1) Utility Commands GAWK(1) The AWK book does not define the return value of the close() function. _G_a_w_k's close() returns the value from _f_c_l_o_s_e(3), or _p_c_l_o_s_e(3), when closing a file or pipe, respectively. When _g_a_w_k is invoked with the -W compat option, if the _f_s argument to the -F option is ``t'', then FS will be set to the tab character. Since this is a rather ugly special case, it is not the default behavior. This behavior also does not occur if -W posix has been specified. HISTORICAL FEATURES There are two features of historical AWK implementations that _g_a_w_k supports. First, it is possible to call the length() built-in function not only with no argument, but even without parentheses! Thus, a = length is the same as either of a = length() a = length($0) This feature is marked as ``deprecated'' in the POSIX stan- dard, and _g_a_w_k will issue a warning about its use if -W lint is specified on the command line. The other feature is the use of the continue statement out- side the body of a while, for, or do loop. Traditional AWK implementations have treated such usage as equivalent to the next statement. _G_a_w_k will support this usage if -W posix has not been specified. ENVIRONMENT VARIABLES If POSIXLY_CORRECT exists in the environment, then _g_a_w_k behaves exactly as if --posix had been specified on the com- mand line. If --lint has been specified, _g_a_w_k will issue a warning message to this effect. BUGS The -F option is not necessary given the command line vari- able assignment feature; it remains only for backwards com- patibility. If your system actually has support for /dev/fd and the associated /dev/stdin, /dev/stdout, and /dev/stderr files, you may get different output from _g_a_w_k than you would get on a system without those files. When _g_a_w_k interprets these files internally, it synchronizes output to the standard output with output to /dev/stdout, while on a system with those files, the output is actually to different open files. Caveat Emptor. Free Software FoundatiLoanst change: Apr 18 1994 21 GAWK(1) Utility Commands GAWK(1) VERSION INFORMATION This man page documents _g_a_w_k, version 2.15. Starting with the 2.15 version of _g_a_w_k, the -c, -V, -C, - a, and -e options of the 2.11 version are no longer recognized. This fact will not even be documented in the manual page for version 2.16. AUTHORS The original version of UNIX _a_w_k was designed and imple- mented by Alfred Aho, Peter Weinberger, and Brian Kernighan of AT&T Bell Labs. Brian Kernighan continues to maintain and enhance it. Paul Rubin and Jay Fenlason, of the Free Software Founda- tion, wrote _g_a_w_k, to be compatible with the original version of _a_w_k distributed in Seventh Edition UNIX. John Woods con- tributed a number of bug fixes. David Trueman, with contri- butions from Arnold Robbins, made _g_a_w_k compatible with the new version of UNIX _a_w_k. The initial DOS port was done by Conrad Kwok and Scott Gar- finkle. Scott Deifik is the current DOS maintainer. Pat Rankin did the port to VMS, and Michal Jaegermann did the port to the Atari ST. The port to OS/2 was done by Kai Uwe Rommel, with contributions and help from Darrel Hankerson. ACKNOWLEDGEMENTS Brian Kernighan of Bell Labs provided valuable assistance during testing and debugging. We thank him. Free Software FoundatiLoanst change: Apr 18 1994 22 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) NNNNAAAAMMMMEEEE perlop - Perl operators and precedence SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS Perl operators have the following associativity and precedence, listed from highest precedence to lowest. Note that all operators borrowed from C keep the same precedence relationship with each other, even where C's precedence is slightly screwy. (This makes learning Perl easier for C folks.) With very few exceptions, these all operate on scalar values only, not array values. left terms and list operators (leftward) left -> nonassoc ++ -- right ** right ! ~ \ and unary + and - left =~ !~ left * / % x left + - . left << >> nonassoc named unary operators nonassoc < > <= >= lt gt le ge nonassoc == != <=> eq ne cmp left & left | ^ left && left || nonassoc .. right ?: right = += -= *= etc. left , => nonassoc list operators (rightward) right not left and left or xor In the following sections, these operators are covered in precedence order. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN TTTTeeeerrrrmmmmssss aaaannnndddd LLLLiiiisssstttt OOOOppppeeeerrrraaaattttoooorrrrssss ((((LLLLeeeeffffttttwwwwaaaarrrrdddd)))) Any TERM is of highest precedence of Perl. These includes variables, quote and quotelike operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary operators behaving as functions because you put parentheses around the arguments. These are all documented in the _p_e_r_l_f_u_n_c manpage. 25/Mar/96 Last change: perl 5.003 with 1 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) If any list operator (_p_r_i_n_t(), etc.) or any unary operator (_c_h_d_i_r(), etc.) is followed by a left parenthesis as the next token, the operator and arguments within parentheses are taken to be of highest precedence, just like a normal function call. In the absence of parentheses, the precedence of list operators such as print, sort, or chmod is either very high or very low depending on whether you look at the left side of operator or the right side of it. For example, in @ary = (1, 3, sort 4, 2); print @ary; # prints 1324 the commas on the right of the sort are evaluated before the sort, but the commas on the left are evaluated after. In other words, list operators tend to gobble up all the arguments that follow them, and then act like a simple TERM with regard to the preceding expression. Note that you have to be careful with parens: # These evaluate exit before doing the print: print($foo, exit); # Obviously not what you want. print $foo, exit; # Nor is this. # These do the print before evaluating exit: (print $foo), exit; # This is what you want. print($foo), exit; # Or this. print ($foo), exit; # Or even this. Also note that print ($foo & 255) + 1, "\n"; probably doesn't do what you expect at first glance. See the section on _N_a_m_e_d _U_n_a_r_y _O_p_e_r_a_t_o_r_s for more discussion of this. Also parsed as terms are the do {} and eval {} constructs, as well as subroutine and method calls, and the anonymous constructors [] and {}. See also the section on _Q_u_o_t_e _a_n_d _Q_u_o_t_e_l_i_k_e _O_p_e_r_a_t_o_r_s toward the end of this section, as well as the section on _I/_O _O_p_e_r_a_t_o_r_s. TTTThhhheeee AAAArrrrrrrroooowwww OOOOppppeeeerrrraaaattttoooorrrr Just as in C and C++, "->" is an infix dereference operator. If the right side is either a [...] or {...} subscript, then the left side must be either a hard or symbolic reference to an array or hash (or a location capable of holding a hard 25/Mar/96 Last change: perl 5.003 with 2 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) reference, if it's an lvalue (assignable)). See the _p_e_r_l_r_e_f manpage. Otherwise, the right side is a method name or a simple scalar variable containing the method name, and the left side must either be an object (a blessed reference) or a class name (that is, a package name). See the _p_e_r_l_o_b_j manpage. AAAAuuuuttttooooiiiinnnnccccrrrreeeemmmmeeeennnntttt aaaannnndddd AAAAuuuuttttooooddddeeeeccccrrrreeeemmmmeeeennnntttt "++" and "--" work as in C. That is, if placed before a variable, they increment or decrement the variable before returning the value, and if placed after, increment or decrement the variable after returning the value. The autoincrement operator has a little extra built-in magic to it. If you increment a variable that is numeric, or that has ever been used in a numeric context, you get a normal increment. If, however, the variable has only been used in string contexts since it was set, and has a value that is not null and matches the pattern /^[a-zA-Z]*[0-9]*$/, the increment is done as a string, preserving each character within its range, with carry: print ++($foo = '99'); # prints '100' print ++($foo = 'a0'); # prints 'a1' print ++($foo = 'Az'); # prints 'Ba' print ++($foo = 'zz'); # prints 'aaa' The autodecrement operator is not magical. EEEExxxxppppoooonnnneeeennnnttttiiiiaaaattttiiiioooonnnn Binary "**" is the exponentiation operator. Note that it binds even more tightly than unary minus, so -2**4 is - (2**4), not (-2)**4. (This is implemented using C's _p_o_w(3) function, which actually works on doubles internally.) SSSSyyyymmmmbbbboooolllliiiicccc UUUUnnnnaaaarrrryyyy OOOOppppeeeerrrraaaattttoooorrrrssss Unary "!" performs logical negation, i.e. "not". See also not for a lower precedence version of this. Unary "-" performs arithmetic negation if the operand is numeric. If the operand is an identifier, a string consisting of a minus sign concatenated with the identifier is returned. Otherwise, if the string starts with a plus or minus, a string starting with the opposite sign is returned. One effect of these rules is that -bareword is equivalent to "-bareword". 25/Mar/96 Last change: perl 5.003 with 3 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) Unary "~" performs bitwise negation, i.e. 1's complement. Unary "+" has no effect whatsoever, even on strings. It is useful syntactically for separating a function name from a parenthesized expression that would otherwise be interpreted as the complete list of function arguments. (See examples above under the section on _L_i_s_t _O_p_e_r_a_t_o_r_s.) Unary "\" creates a reference to whatever follows it. See the _p_e_r_l_r_e_f manpage. Do not confuse this behavior with the behavior of backslash within a string, although both forms do convey the notion of protecting the next thing from interpretation. BBBBiiiinnnnddddiiiinnnngggg OOOOppppeeeerrrraaaattttoooorrrrssss Binary "=~" binds a scalar expression to a pattern match. Certain operations search or modify the string $_ by default. This operator makes that kind of operation work on some other string. The right argument is a search pattern, substitution, or translation. The left argument is what is supposed to be searched, substituted, or translated instead of the default $_. The return value indicates the success of the operation. (If the right argument is an expression rather than a search pattern, substitution, or translation, it is interpreted as a search pattern at run time. This is less efficient than an explicit search, since the pattern must be compiled every time the expression is evaluated- -unless you've used /o.) Binary "!~" is just like "=~" except the return value is negated in the logical sense. MMMMuuuullllttttiiiipppplllliiiiccccaaaattttiiiivvvveeee OOOOppppeeeerrrraaaattttoooorrrrssss Binary "*" multiplies two numbers. Binary "/" divides two numbers. Binary "%" computes the modulus of the two numbers. Binary "x" is the repetition operator. In a scalar context, it returns a string consisting of the left operand repeated the number of times specified by the right operand. In a list context, if the left operand is a list in parens, it repeats the list. print '-' x 80; # print row of dashes print "\t" x ($tab/8), ' ' x ($tab%8); # tab over 25/Mar/96 Last change: perl 5.003 with 4 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) @ones = (1) x 80; # a list of 80 1's @ones = (5) x @ones; # set all elements to 5 AAAAddddddddiiiittttiiiivvvveeee OOOOppppeeeerrrraaaattttoooorrrrssss Binary "+" returns the sum of two numbers. Binary "-" returns the difference of two numbers. Binary "." concatenates two strings. SSSShhhhiiiifffftttt OOOOppppeeeerrrraaaattttoooorrrrssss Binary "<<" returns the value of its left argument shifted left by the number of bits specified by the right argument. Arguments should be integers. Binary ">>" returns the value of its left argument shifted right by the number of bits specified by the right argument. Arguments should be integers. NNNNaaaammmmeeeedddd UUUUnnnnaaaarrrryyyy OOOOppppeeeerrrraaaattttoooorrrrssss The various named unary operators are treated as functions with one argument, with optional parentheses. These include the filetest operators, like -f, -M, etc. See the _p_e_r_l_f_u_n_c manpage. If any list operator (_p_r_i_n_t(), etc.) or any unary operator (_c_h_d_i_r(), etc.) is followed by a left parenthesis as the next token, the operator and arguments within parentheses are taken to be of highest precedence, just like a normal function call. Examples: chdir $foo || die; # (chdir $foo) || die chdir($foo) || die; # (chdir $foo) || die chdir ($foo) || die; # (chdir $foo) || die chdir +($foo) || die; # (chdir $foo) || die but, because * is higher precedence than ||: chdir $foo * 20; # chdir ($foo * 20) chdir($foo) * 20; # (chdir $foo) * 20 chdir ($foo) * 20; # (chdir $foo) * 20 chdir +($foo) * 20; # chdir ($foo * 20) rand 10 * 20; # rand (10 * 20) rand(10) * 20; # (rand 10) * 20 rand (10) * 20; # (rand 10) * 20 rand +(10) * 20; # rand (10 * 20) 25/Mar/96 Last change: perl 5.003 with 5 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) See also the section on _L_i_s_t _O_p_e_r_a_t_o_r_s. RRRReeeellllaaaattttiiiioooonnnnaaaallll OOOOppppeeeerrrraaaattttoooorrrrssss Binary "<" returns true if the left argument is numerically less than the right argument. Binary ">" returns true if the left argument is numerically greater than the right argument. Binary "<=" returns true if the left argument is numerically less than or equal to the right argument. Binary ">=" returns true if the left argument is numerically greater than or equal to the right argument. Binary "lt" returns true if the left argument is stringwise less than the right argument. Binary "gt" returns true if the left argument is stringwise greater than the right argument. Binary "le" returns true if the left argument is stringwise less than or equal to the right argument. Binary "ge" returns true if the left argument is stringwise greater than or equal to the right argument. EEEEqqqquuuuaaaalllliiiittttyyyy OOOOppppeeeerrrraaaattttoooorrrrssss Binary "==" returns true if the left argument is numerically equal to the right argument. Binary "!=" returns true if the left argument is numerically not equal to the right argument. Binary "<=>" returns -1, 0, or 1 depending on whether the left argument is numerically less than, equal to, or greater than the right argument. Binary "eq" returns true if the left argument is stringwise equal to the right argument. Binary "ne" returns true if the left argument is stringwise not equal to the right argument. Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise less than, equal to, or greater than the right argument. 25/Mar/96 Last change: perl 5.003 with 6 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) BBBBiiiittttwwwwiiiisssseeee AAAAnnnndddd Binary "&" returns its operators ANDed together bit by bit. BBBBiiiittttwwwwiiiisssseeee OOOOrrrr aaaannnndddd EEEExxxxcccclllluuuussssiiiivvvveeee OOOOrrrr Binary "|" returns its operators ORed together bit by bit. Binary "^" returns its operators XORed together bit by bit. CCCC----ssssttttyyyylllleeee LLLLooooggggiiiiccccaaaallll AAAAnnnndddd Binary "&&" performs a short-circuit logical AND operation. That is, if the left operand is false, the right operand is not even evaluated. Scalar or list context propagates down to the right operand if it is evaluated. CCCC----ssssttttyyyylllleeee LLLLooooggggiiiiccccaaaallll OOOOrrrr Binary "||" performs a short-circuit logical OR operation. That is, if the left operand is true, the right operand is not even evaluated. Scalar or list context propagates down to the right operand if it is evaluated. The || and && operators differ from C's in that, rather than returning 0 or 1, they return the last value evaluated. Thus, a reasonably portable way to find out the home directory (assuming it's not "0") might be: $home = $ENV{'HOME'} || $ENV{'LOGDIR'} || (getpwuid($<))[7] || die "You're homeless!\n"; As more readable alternatives to && and ||, Perl provides "and" and "or" operators (see below). The short-circuit behavior is identical. The precedence of "and" and "or" is much lower, however, so that you can safely use them after a list operator without the need for parentheses: unlink "alpha", "beta", "gamma" or gripe(), next LINE; With the C-style operators that would have been written like this: unlink("alpha", "beta", "gamma") || (gripe(), next LINE); RRRRaaaannnnggggeeee OOOOppppeeeerrrraaaattttoooorrrr Binary ".." is the range operator, which is really two different operators depending on the context. In a list 25/Mar/96 Last change: perl 5.003 with 7 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) context, it returns an array of values counting (by ones) from the left value to the right value. This is useful for writing for (1..10) loops and for doing slice operations on arrays. Be aware that under the current implementation, a temporary array is created, so you'll burn a lot of memory if you write something like this: for (1 .. 1_000_000) { # code } In a scalar context, ".." returns a boolean value. The operator is bistable, like a flip-flop, and emulates the line-range (comma) operator of sssseeeedddd, aaaawwwwkkkk, and various editors. Each ".." operator maintains its own boolean state. It is false as long as its left operand is false. Once the left operand is true, the range operator stays true until the right operand is true, _A_F_T_E_R which the range operator becomes false again. (It doesn't become false till the next time the range operator is evaluated. It can test the right operand and become false on the same evaluation it became true (as in aaaawwwwkkkk), but it still returns true once. If you don't want it to test the right operand till the next evaluation (as in sssseeeedddd), use three dots ("...") instead of two.) The right operand is not evaluated while the operator is in the "false" state, and the left operand is not evaluated while the operator is in the "true" state. The precedence is a little lower than || and &&. The value returned is either the null string for false, or a sequence number (beginning with 1) for true. The sequence number is reset for each range encountered. The final sequence number in a range has the string "E0" appended to it, which doesn't affect its numeric value, but gives you something to search for if you want to exclude the endpoint. You can exclude the beginning point by waiting for the sequence number to be greater than 1. If either operand of scalar ".." is a numeric literal, that operand is implicitly compared to the $. variable, the current line number. Examples: As a scalar operator: if (101 .. 200) { print; } # print 2nd hundred lines next line if (1 .. /^$/); # skip header lines s/^/> / if (/^$/ .. eof()); # quote body As a list operator: for (101 .. 200) { print; } # print $_ 100 times @foo = @foo[$[ .. $#foo]; # an expensive no-op @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items The range operator (in a list context) makes use of the 25/Mar/96 Last change: perl 5.003 with 8 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) magical autoincrement algorithm if the operands are strings. You can say @alphabet = ('A' .. 'Z'); to get all the letters of the alphabet, or $hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15]; to get a hexadecimal digit, or @z2 = ('01' .. '31'); print $z2[$mday]; to get dates with leading zeros. If the final value specified is not in the sequence that the magical increment would produce, the sequence goes until the next value would be longer than the final value specified. CCCCoooonnnnddddiiiittttiiiioooonnnnaaaallll OOOOppppeeeerrrraaaattttoooorrrr Ternary "?:" is the conditional operator, just as in C. It works much like an if-then-else. If the argument before the ? is true, the argument before the : is returned, otherwise the argument after the : is returned. For example: printf "I have %d dog%s.\n", $n, ($n == 1) ? '' : "s"; Scalar or list context propagates downward into the 2nd or 3rd argument, whichever is selected. $a = $ok ? $b : $c; # get a scalar @a = $ok ? @b : @c; # get an array $a = $ok ? @b : @c; # oops, that's just a count! The operator may be assigned to if both the 2nd and 3rd arguments are legal lvalues (meaning that you can assign to them): ($a_or_b ? $a : $b) = $c; This is not necessarily guaranteed to contribute to the readability of your program. AAAAssssssssiiiiggggnnnnmmmmeeeennnntttt OOOOppppeeeerrrraaaattttoooorrrrssss "=" is the ordinary assignment operator. Assignment operators work as in C. That is, $a += 2; 25/Mar/96 Last change: perl 5.003 with 9 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) is equivalent to $a = $a + 2; although without duplicating any side effects that dereferencing the lvalue might trigger, such as from _t_i_e(). Other assignment operators work similarly. The following are recognized: **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x= Note that while these are grouped by family, they all have the precedence of assignment. Unlike in C, the assignment operator produces a valid lvalue. Modifying an assignment is equivalent to doing the assignment and then modifying the variable that was assigned to. This is useful for modifying a copy of something, like this: ($tmp = $global) =~ tr [A-Z] [a-z]; Likewise, ($a += 2) *= 3; is equivalent to $a += 2; $a *= 3; CCCCoooommmmmmmmaaaa OOOOppppeeeerrrraaaattttoooorrrr Binary "," is the comma operator. In a scalar context it evaluates its left argument, throws that value away, then evaluates its right argument and returns that value. This is just like C's comma operator. In a list context, it's just the list argument separator, and inserts both its arguments into the list. The => digraph is mostly just a synonym for the comma operator. It's useful for documenting arguments that come in pairs. As of release 5.001, it also forces any word to the left of it to be interpreted as a string. 25/Mar/96 Last change: perl 5.003 with 10 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) LLLLiiiisssstttt OOOOppppeeeerrrraaaattttoooorrrrssss ((((RRRRiiiigggghhhhttttwwwwaaaarrrrdddd)))) On the right side of a list operator, it has very low precedence, such that it controls all comma-separated expressions found there. The only operators with lower precedence are the logical operators "and", "or", and "not", which may be used to evaluate calls to list operators without the need for extra parentheses: open HANDLE, "filename" or die "Can't open: $!\n"; See also discussion of list operators in the section on _L_i_s_t _O_p_e_r_a_t_o_r_s (_L_e_f_t_w_a_r_d). LLLLooooggggiiiiccccaaaallll NNNNooootttt Unary "not" returns the logical negation of the expression to its right. It's the equivalent of "!" except for the very low precedence. LLLLooooggggiiiiccccaaaallll AAAAnnnndddd Binary "and" returns the logical conjunction of the two surrounding expressions. It's equivalent to && except for the very low precedence. This means that it short-circuits: i.e. the right expression is evaluated only if the left expression is true. LLLLooooggggiiiiccccaaaallll oooorrrr aaaannnndddd EEEExxxxcccclllluuuussssiiiivvvveeee OOOOrrrr Binary "or" returns the logical disjunction of the two surrounding expressions. It's equivalent to || except for the very low precedence. This means that it short-circuits: i.e. the right expression is evaluated only if the left expression is false. Binary "xor" returns the exclusive-OR of the two surrounding expressions. It cannot short circuit, of course. CCCC OOOOppppeeeerrrraaaattttoooorrrrssss MMMMiiiissssssssiiiinnnngggg FFFFrrrroooommmm PPPPeeeerrrrllll Here is what C has that Perl doesn't: unary & Address-of operator. (But see the "\" operator for taking a reference.) unary * Dereference-address operator. (Perl's prefix dereferencing operators are typed: $, @, %, and &.) (TYPE) Type casting operator. 25/Mar/96 Last change: perl 5.003 with 11 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) QQQQuuuuooootttteeee aaaannnndddd QQQQuuuuooootttteeeelllliiiikkkkeeee OOOOppppeeeerrrraaaattttoooorrrrssss While we usually think of quotes as literal values, in Perl they function as operators, providing various kinds of interpolating and pattern matching capabilities. Perl provides customary quote characters for these behaviors, but also provides a way for you to choose your quote character for any of them. In the following table, a {} represents any pair of delimiters you choose. Non-bracketing delimiters use the same character fore and aft, but the 4 sorts of brackets (round, angle, square, curly) will all nest. Customary Generic Meaning Interpolates '' q{} Literal no "" qq{} Literal yes `` qx{} Command yes qw{} Word list no // m{} Pattern match yes s{}{} Substitution yes tr{}{} Translation no For constructs that do interpolation, variables beginning with "$" or "@" are interpolated, as are the following sequences: \t tab \n newline \r return \f form feed \b backspace \a alarm (bell) \e escape \033 octal char \x1b hex char \c[ control char \l lowercase next char \u uppercase next char \L lowercase till \E \U uppercase till \E \E end case modification \Q quote regexp metacharacters till \E Patterns are subject to an additional level of interpretation as a regular expression. This is done as a second pass, after variables are interpolated, so that regular expressions may be incorporated into the pattern from the variables. If this is not what you want, use \Q to interpolate a variable literally. Apart from the above, there are no multiple levels of interpolation. In particular, contrary to the expectations 25/Mar/96 Last change: perl 5.003 with 12 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) of shell programmers, backquotes do _N_O_T interpolate within double quotes, nor do single quotes impede evaluation of variables when used within double quotes. RRRReeeeggggeeeexxxxpppp QQQQuuuuooootttteeeelllliiiikkkkeeee OOOOppppeeeerrrraaaattttoooorrrrssss Here are the quotelike operators that apply to pattern matching and related activities. ?PATTERN? This is just like the /pattern/ search, except that it matches only once between calls to the _r_e_s_e_t() operator. This is a useful optimization when you only want to see the first occurrence of something in each file of a set of files, for instance. Only ?? patterns local to the current package are reset. This usage is vaguely deprecated, and may be removed in some future version of Perl. m/PATTERN/gimosx /PATTERN/gimosx Searches a string for a pattern match, and in a scalar context returns true (1) or false (''). If no string is specified via the =~ or !~ operator, the $_ string is searched. (The string specified with =~ need not be an lvalue--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.) See also the _p_e_r_l_r_e manpage. Options are: g Match globally, i.e. find all occurrences. i Do case-insensitive pattern matching. m Treat string as multiple lines. o Only compile pattern once. s Treat string as single line. x Use extended regular expressions. If "/" is the delimiter then the initial m is optional. With the m you can use any pair of non- alphanumeric, non-whitespace characters as delimiters. This is particularly useful for matching Unix path names that contain "/", to avoid LTS (leaning toothpick syndrome). PATTERN may contain variables, which will be interpolated (and the pattern recompiled) every time the pattern search is evaluated. (Note that $) and $| might not be interpolated because they look like end-of-string tests.) If you want such a pattern to 25/Mar/96 Last change: perl 5.003 with 13 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) be compiled only once, add a /o after the trailing delimiter. This avoids expensive run-time recompilations, and is useful when the value you are interpolating won't change over the life of the script. However, mentioning /o constitutes a promise that you won't change the variables in the pattern. If you change them, Perl won't even notice. If the PATTERN evaluates to a null string, the last successfully executed regular expression is used instead. If used in a context that requires a list value, a pattern match returns a list consisting of the subexpressions matched by the parentheses in the pattern, i.e. ($1, $2, $3...). (Note that here $1 etc. are also set, and that this differs from Perl 4's behavior.) If the match fails, a null array is returned. If the match succeeds, but there were no parentheses, a list value of (1) is returned. Examples: open(TTY, '/dev/tty'); =~ /^y/i && foo(); # do foo if desired if (/Version: *([0-9.]*)/) { $version = $1; } next if m#^/usr/spool/uucp#; # poor man's grep $arg = shift; while (<>) { print if /$arg/o; # compile only once } if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/)) This last example splits $foo into the first two words and the remainder of the line, and assigns those three fields to $F1, $F2 and $Etc. The conditional is true if any variables were assigned, i.e. if the pattern matched. The /g modifier specifies global pattern matching- -that is, matching as many times as possible within the string. How it behaves depends on the context. In a list context, it returns a list of all the substrings matched by all the parentheses in the regular expression. If there are no parentheses, it returns a list of all the matched strings, as if 25/Mar/96 Last change: perl 5.003 with 14 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) there were parentheses around the whole pattern. In a scalar context, m//g iterates through the string, returning TRUE each time it matches, and FALSE when it eventually runs out of matches. (In other words, it remembers where it left off last time and restarts the search at that point. You can actually find the current match position of a string using the _p_o_s() function--see the _p_e_r_l_f_u_n_c manpage.) If you modify the string in any way, the match position is reset to the beginning. Examples: # list context ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g); # scalar context $/ = ""; $* = 1; # $* deprecated in Perl 5 while ($paragraph = <>) { while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { $sentences++; } } print "$sentences\n"; q/STRING/ 'STRING' A single-quoted, literal string. Backslashes are ignored, unless followed by the delimiter or another backslash, in which case the delimiter or backslash is interpolated. $foo = q!I said, "You said, 'She said it.'"!; $bar = q('This is it.'); qq/STRING/ "" .nr )I STRING""n A double-quoted, interpolated string. $_ .= qq (*** The previous line contains the naughty word "$1".\n) if /(tcl|rexx|python)/; # :-) qx/STRING/ `STRING` A string which is interpolated and then executed as a system command. The collected standard output of 25/Mar/96 Last change: perl 5.003 with 15 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) the command is returned. In scalar context, it comes back as a single (potentially multi-line) string. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR). $today = qx{ date }; See the section on _I/_O _O_p_e_r_a_t_o_r_s for more discussion. qw/STRING/ Returns a list of the words extracted out of STRING, using embedded whitespace as the word delimiters. It is exactly equivalent to split(' ', q/STRING/); Some frequently seen examples: use POSIX qw( setlocale localeconv ) @EXPORT = qw( foo bar baz ); s/PATTERN/REPLACEMENT/egimosx Searches a string for a pattern, and if found, replaces that pattern with the replacement text and returns the number of substitutions made. Otherwise it returns false (0). If no string is specified via the =~ or !~ operator, the $_ variable is searched and modified. (The string specified with =~ must be a scalar variable, an array element, a hash element, or an assignment to one of those, i.e. an lvalue.) If the delimiter chosen is single quote, no variable interpolation is done on either the PATTERN or the REPLACEMENT. Otherwise, if the PATTERN contains a $ that looks like a variable rather than an end-of- string test, the variable will be interpolated into the pattern at run-time. If you only want the pattern compiled once the first time the variable is interpolated, use the /o option. If the pattern evaluates to a null string, the last successfully executed regular expression is used instead. See the _p_e_r_l_r_e manpage for further explanation on these. Options are: 25/Mar/96 Last change: perl 5.003 with 16 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) e Evaluate the right side as an expression. g Replace globally, i.e. all occurrences. i Do case-insensitive pattern matching. m Treat string as multiple lines. o Only compile pattern once. s Treat string as single line. x Use extended regular expressions. Any non-alphanumeric, non-whitespace delimiter may replace the slashes. If single quotes are used, no interpretation is done on the replacement string (the /e modifier overrides this, however). If backquotes are used, the replacement string is a command to execute whose output will be used as the actual replacement text. If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own pair of quotes, which may or may not be bracketing quotes, e.g. s(foo)(bar) or s/bar/. A /e will cause the replacement portion to be interpreter as a full-fledged Perl expression and _e_v_a_l()ed right then and there. It is, however, syntax checked at compile-time. Examples: s/\bgreen\b/mauve/g; # don't change wintergreen $path =~ s|/usr/bin|/usr/local/bin|; s/Login: $foo/Login: $bar/; # run-time pattern ($foo = $bar) =~ s/this/that/; $count = ($paragraph =~ s/Mister\b/Mr./g); $_ = 'abc123xyz'; s/\d+/$&*2/e; # yields 'abc246xyz' s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz' s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz' s/%(.)/$percent{$1}/g; # change percent escapes; no /e s/%(.)/$percent{$1} || $&/ge; # expr now, so /e s/^=(\w+)/&pod($1)/ge; # use function call # /e's can even nest; this will expand # simple embedded variables in $_ s/(\$\w+)/$1/eeg; 25/Mar/96 Last change: perl 5.003 with 17 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) # Delete C comments. $program =~ s { /\* # Match the opening delimiter. .*? # Match a minimal number of characters. \*/ # Match the closing delimiter. } []gsx; s/^\s*(.*?)\s*$/$1/; # trim white space s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields Note the use of $ instead of \ in the last example. Unlike sssseeeedddd, we only use the \<_d_i_g_i_t> form in the left hand side. Anywhere else it's $<_d_i_g_i_t>. Occasionally, you can't just use a /g to get all the changes to occur. Here are two common cases: # put commas in the right places in an integer 1 while s/(.*\d)(\d\d\d)/$1,$2/g; # perl4 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g; # perl5 # expand tabs to 8-column spacing 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e; tr/SEARCHLIST/REPLACEMENTLIST/cds y/SEARCHLIST/REPLACEMENTLIST/cds Translates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is translated. (The string specified with =~ must be a scalar variable, an array element, or an assignment to one of those, i.e. an lvalue.) For sssseeeedddd devotees, y is provided as a synonym for tr. If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes, e.g. tr[A-Z][a-z] or tr(+-*/)/ABCD/. Options: c Complement the SEARCHLIST. d Delete found but unreplaced characters. s Squash duplicate replaced characters. If the /c modifier is specified, the SEARCHLIST character set is complemented. If the /d modifier is specified, any characters specified by SEARCHLIST 25/Mar/96 Last change: perl 5.003 with 18 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) not found in REPLACEMENTLIST are deleted. (Note that this is slightly more flexible than the behavior of some ttttrrrr programs, which delete anything they find in the SEARCHLIST, period.) If the /s modifier is specified, sequences of characters that were translated to the same character are squashed down to a single instance of the character. If the /d modifier is used, the REPLACEMENTLIST is always interpreted exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST, the final character is replicated till it is long enough. If the REPLACEMENTLIST is null, the SEARCHLIST is replicated. This latter is useful for counting characters in a class or for squashing character sequences in a class. Examples: $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case $cnt = tr/*/*/; # count the stars in $_ $cnt = $sky =~ tr/*/*/; # count the stars in $sky $cnt = tr/0-9//; # count the digits in $_ tr/a-zA-Z//s; # bookkeeper -> bokeper ($HOST = $host) =~ tr/a-z/A-Z/; tr/a-zA-Z/ /cs; # change non-alphas to single space tr [\200-\377] [\000-\177]; # delete 8th bit If multiple translations are given for a character, only the first one is used: tr/AAA/XYZ/ will translate any A to X. Note that because the translation table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use an _e_v_a_l(): eval "tr/$oldlist/$newlist/"; die $@ if $@; 25/Mar/96 Last change: perl 5.003 with 19 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) eval "tr/$oldlist/$newlist/, 1" or die $@; IIII////OOOO OOOOppppeeeerrrraaaattttoooorrrrssss There are several I/O operators you should know about. A string is enclosed by backticks (grave accents) first undergoes variable substitution just like a double quoted string. It is then interpreted as a command, and the output of that command is the value of the pseudo-literal, like in a shell. In a scalar context, a single string consisting of all the output is returned. In a list context, a list of values is returned, one for each line of output. (You can set $/ to use a different line terminator.) The command is executed each time the pseudo-literal is evaluated. The status value of the command is returned in $? (see the _p_e_r_l_v_a_r manpage for the interpretation of $?). Unlike in ccccsssshhhh, no translation is done on the return data--newlines remain newlines. Unlike in any of the shells, single quotes do not hide variable names in the command from interpretation. To pass a $ through to the shell you need to hide it with a backslash. The generalized form of backticks is qx//. (Because backticks always undergo shell expansion as well, see the _p_e_r_l_s_e_c manpage for security concerns.) Evaluating a filehandle in angle brackets yields the next line from that file (newline included, so it's never false until end of file, at which time an undefined value is returned). Ordinarily you must assign that value to a variable, but there is one situation where an automatic assignment happens. _I_f _a_n_d _O_N_L_Y _i_f the input symbol is the only thing inside the conditional of a while loop, the value is automatically assigned to the variable $_. The assigned value is then tested to see if it is defined. (This may seem like an odd thing to you, but you'll use the construct in almost every Perl script you write.) Anyway, the following lines are equivalent to each other: while (defined($_ = )) { print; } while () { print; } for (;;) { print; } print while defined($_ = ); print while ; The filehandles STDIN, STDOUT and STDERR are predefined. (The filehandles stdin, stdout and stderr will also work except in packages, where they would be interpreted as local identifiers rather than global.) Additional filehandles may be created with the _o_p_e_n() function. See the open() entry in the _p_e_r_l_f_u_n_c manpage for details on this. 25/Mar/96 Last change: perl 5.003 with 20 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) If a is used in a context that is looking for a list, a list consisting of all the input lines is returned, one line per list element. It's easy to make a _L_A_R_G_E data space this way, so use with care. The null filehandle <> is special and can be used to emulate the behavior of sssseeeedddd and aaaawwwwkkkk. Input from <> comes either from standard input, or from each file listed on the command line. Here's how it works: the first time <> is evaluated, the @ARGV array is checked, and if it is null, $ARGV[0] is set to "-", which when opened gives you standard input. The @ARGV array is then processed as a list of filenames. The loop while (<>) { ... # code for each line } is equivalent to the following Perl-like pseudo code: unshift(@ARGV, '-') if $#ARGV < $[; while ($ARGV = shift) { open(ARGV, $ARGV); while () { ... # code for each line } } except that it isn't so cumbersome to say, and will actually work. It really does shift array @ARGV and put the current filename into variable $ARGV. It also uses filehandle _A_R_G_V internally--<> is just a synonym for , which is magical. (The pseudo code above doesn't work because it treats as non-magical.) You can modify @ARGV before the first <> as long as the array ends up containing the list of filenames you really want. Line numbers ($.) continue as if the input were one big happy file. (But see example under _e_o_f() for how to reset line numbers on each file.) If you want to set @ARGV to your own list of files, go right ahead. If you want to pass switches into your script, you can use one of the Getopts modules or put a loop on the front like this: 25/Mar/96 Last change: perl 5.003 with 21 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) while ($_ = $ARGV[0], /^-/) { shift; last if /^--$/; if (/^-D(.*)/) { $debug = $1 } if (/^-v/) { $verbose++ } ... # other switches } while (<>) { ... # code for each line } The <> symbol will return FALSE only once. If you call it again after this it will assume you are processing another @ARGV list, and if you haven't set @ARGV, will input from STDIN. If the string inside the angle brackets is a reference to a scalar variable (e.g. <$foo>), then that variable contains the name of the filehandle to input from, or a reference to the same. For example: $fh = \*STDIN; $line = <$fh>; If the string inside angle brackets is not a filehandle or a scalar variable containing a filehandle name or reference, then it is interpreted as a filename pattern to be globbed, and either a list of filenames or the next filename in the list is returned, depending on context. One level of $ interpretation is done first, but you can't say <$foo> because that's an indirect filehandle as explained in the previous paragraph. In older version of Perl, programmers would insert curly brackets to force interpretation as a filename glob: <${foo}>. These days, it's considered cleaner to call the internal function directly as glob($foo), which is probably the right way to have done it in the first place.) Example: while (<*.c>) { chmod 0644, $_; } is equivalent to open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|"); while () { chop; chmod 0644, $_; } In fact, it's currently implemented that way. (Which means it will not work on filenames with spaces in them unless you 25/Mar/96 Last change: perl 5.003 with 22 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) have _c_s_h(1) on your machine.) Of course, the shortest way to do the above is: chmod 0644, <*.c>; Because globbing invokes a shell, it's often faster to call _r_e_a_d_d_i_r() yourself and just do your own _g_r_e_p() on the filenames. Furthermore, due to its current implementation of using a shell, the _g_l_o_b() routine may get "Arg list too long" errors (unless you've installed _t_c_s_h(1L) as /_b_i_n/_c_s_h). A glob only evaluates its (embedded) argument when it is starting a new list. All values must be read before it will start over. In a list context this isn't important, because you automatically get them all anyway. In a scalar context, however, the operator returns the next value each time it is called, or a FALSE value if you've just run out. Again, FALSE is returned only once. So if you're expecting a single value from a glob, it is much better to say ($file) = ; than $file = ; because the latter will alternate between returning a filename and returning FALSE. It you're trying to do variable interpolation, it's definitely better to use the _g_l_o_b() function, because the older notation can cause people to become confused with the indirect filehandle notatin. @files = glob("$dir/*.[ch]"); @files = glob($files[$i]); CCCCoooonnnnssssttttaaaannnntttt FFFFoooollllddddiiiinnnngggg Like C, Perl does a certain amount of expression evaluation at compile time, whenever it determines that all of the arguments to an operator are static and have no side effects. In particular, string concatenation happens at compile time between literals that don't do variable substitution. Backslash interpretation also happens at compile time. You can say 'Now is the time for all' . "\n" . 'good men to come to.' and this all reduces to one string internally. Likewise, if 25/Mar/96 Last change: perl 5.003 with 23 PERLOP(1) Perl Programmers Reference Guide PERLOP(1) you say foreach $file (@filenames) { if (-s $file > 5 + 100 * 2**16) { ... } } the compiler will pre-compute the number that expression represents so that the interpreter won't have to. IIIInnnntttteeeeggggeeeerrrr aaaarrrriiiitttthhhhmmmmeeeettttiiiicccc By default Perl assumes that it must do most of its arithmetic in floating point. But by saying use integer; you may tell the compiler that it's okay to use integer operations from here to the end of the enclosing BLOCK. An inner BLOCK may countermand this by saying no integer; which lasts until the end of that BLOCK. 25/Mar/96 Last change: perl 5.003 with 24 TCSH(1) User Commands TCSH(1) NNAAMMEE tcsh - C shell with file name completion and command line editing SSYYNNOOPPSSIISS ttccsshh [ --bbccddeeffiimmnnqqssttvvVVxxXX ] [ _a_r_g_u_m_e_n_t ... ] or ttccsshh --ll OS/Dependent Options ttccsshh [ --FF ] [ --DDnnaammee[[==vvaalluuee]] ] DDEESSCCRRIIPPTTIIOONN _T_c_s_h is an enhanced version of the Berkeley UNIX C shell _c_s_h(1). It behaves exactly like the C shell, except for the added utilities of: 1) Command line editing using Emacs-style commands. 2) Visual step up/down through the history list. 3) Terminal mode sanity checking and resetting. 4) Interactive command, file name and user name comple- tion. 5) File/directory/user list in the middle of a typed com- mand. 6) Spelling correction of command, file, and user names. 7) Lookup of command documentation in the middle of a typed command. 8) Enhanced history mechanism. 9) Automatic locking/logout after long periods of idle time. 10) Automatic execution of a single command prior to printing each prompt. 11) Automatic periodic command execution. 12) A new syntax for the prompt, and the ability to set the prompt for "while" and "for" loops. 13) Time stamps in the history list. 14) An addition to the syntax of filenames to access entries in the directory stack, and the ability treat Cornell 6.04.00 Last change: 3 July 1993 1 TCSH(1) User Commands TCSH(1) symbolic links in a sane way when changing direc- tories. 15) The ability to watch for logins and logouts by user or terminal on the machine. 16) A scheduled event list, which specifies commands which are to be executed at given times. 17) A new builtin that does a subset of _l_s(1). 18) An addition to the file expression syntax for a char- acter not in a set of characters and the ability to negate a globbing pattern. 19) New automatically initialized environment variables _H_O_S_T and _H_O_S_T_T_Y_P_E. 20) Commands for debugging terminal capabilities. 21) Searching for the visual history mechanism. 22) New builtins for the _w_h_i_c_h(1) and _w_h_e_r_e commands. 23) Restarting a stopped editor with two keystrokes. 24) Status line support 25) Automatic execution of a command when the current working directory is changed. 26) Native Language System support. 27) Automatic process time reporting. 28) OS Dependent Builtin Support 29) Automatic window size adjustment 30) Input files 31) Additional/Undocumented Options 32) Enhanced history/variable modifier expansion 33) Programmable completion. 34) Enhanced file inquiry operator. 35) Readonly variables. For a description of standard C-shell features, see the _c_s_h Cornell 6.04.00 Last change: 3 July 1993 2 TCSH(1) User Commands TCSH(1) manual page. 11.. CCOOMMMMAANNDD LLIINNEE EEDDIITTIINNGG Commands that the user types in may be edited using the same control characters that Gnu Emacs or vi uses. Arrow and function key sequences are also allowed. _T_c_s_h allows this by setting the terminal to `CBREAK' mode and reading the input one character at a time. There is a new shell command, _b_i_n_d_k_e_y, that allows the user to redefine what any key does, or find out what any or all of the keys do. Syntax: bindkey [ -a ] [ -c ] [ -s ] [ -v ] [ -e ] [ -d ] [ -k ] [ -l ] [ -r ] [ -- ] [ [ in-string | key-name ] [ out- string | command ]] If no values are given all bindings are listed. If only in- string is given, bindings for the in-string is listed. Otherwise it binds the in-string to the given out-string or command. If out-string, this is treated as input to _t_c_s_h when in-string is typed. This may be used recursively to currently a level of 10 deep. There are two basic key maps: the normal and alternative one. The alternative is used by VI command mode. For multi- character input the basic key maps contains a sequence- lead-in for the first character in the input. Options: -a bind in-string in alternative key map -s bind an out-string instead of a command -c bind a unix command instead of a command -v bind for default VI-mode -e bind for default emacs-mode -k interpret in-string as a symbolic arrow key name -d bind to compiled in default -l list functions available with short description -r remove the binding of in-string In strings control characters may be written as caret- and backslash ("\") is used to escape a character as follows: \\aa bell character \\nn line feed (new line) \\bb back space \\tt horizontal tab \\vv vertical tab \\ff form feed \\rr carriage return \\ee escape Cornell 6.04.00 Last change: 3 July 1993 3 TCSH(1) User Commands TCSH(1) \\nnnnnn character code in octal In all other cases \ escapes the following character. Needed for escaping the special meaning of \ and ^. Delete is written as "^?" (caret-question mark). _T_c_s_h always binds the arrow keys as defined by the termcap entry to: up arrow up-history down arrow down-history right arrow forward-char left arrow backward-char except where these bindings would alter other single charac- ter bindings. If this is not desired one can avoid the automatic arrow key binding using _s_e_t_t_c to change the arrow key escape sequences to the empty string. The ansi/vt100 sequences for arrow keys are always bound. The following is a list of the default emacs and vi bind- ings. Characters with the 8th bit set are written as M- . Note however, that unlike with the old _b_i_n_d command (see below), the syntax M- has no special meaning to the _b_i_n_d_k_e_y command, and the bindings for the sequence escape+ and M- as given below are handled separately (although the the default bindings are the same). The printable ascii characters not mentioned in the list are bound to the _s_e_l_f-_i_n_s_e_r_t-_c_o_m_m_a_n_d function, which just inserts the given character literally into the input line. The remaining characters are bound to the _u_n_d_e_f_i_n_e_d-_k_e_y function, which only causes a beep (unless _n_o_b_e_e_p is set, of course). EMACS bindings "^@" -> set-mark-command "^A" -> beginning-of-line "^B" -> backward-char "^C" -> tty-sigintr "^D" -> delete-char-or-list "^E" -> end-of-line "^F" -> forward-char "^G" -> is undefined "^H" -> backward-delete-char "^I" -> complete-word "^J" -> newline "^K" -> kill-line "^L" -> clear-screen "^M" -> newline "^N" -> down-history "^O" -> tty-flush-output "^P" -> up-history Cornell 6.04.00 Last change: 3 July 1993 4 TCSH(1) User Commands TCSH(1) "^Q" -> tty-start-output "^R" -> redisplay "^S" -> tty-stop-output "^T" -> transpose-chars "^U" -> kill-whole-line "^V" -> quoted-insert "^W" -> kill-region "^X" -> sequence-lead-in "^Y" -> yank "^Z" -> tty-sigtsusp "^[" -> sequence-lead-in "^\" -> tty-sigquit "^]" -> tty-dsusp " " to "/" -> self-insert-command "0" to "9" -> digit ":" to "~" -> self-insert-command "^?" -> backward-delete-char EMACS Multi-character and 8 bit bindings "^[^D" or "M-^D" -> list-choices "^[^H" or "M-^H" -> backward-delete-word "^[^I" or "M-^I" -> complete-word "^[^L" or "M-^L" -> clear-screen "^[^Z" or "M-^Z" -> run-fg-editor "^[^[" or "M-^[" -> complete-word "^[^_" or "M-^_" -> copy-prev-word "^[ " or "M- " -> expand-history "^[!" or "M-!" -> expand-history "^[$" or "M-$" -> spell-line "^[0" or "M-0" -> digit-argument "^[1" or "M-1" -> digit-argument "^[2" or "M-2" -> digit-argument "^[3" or "M-3" -> digit-argument "^[4" or "M-4" -> digit-argument "^[5" or "M-5" -> digit-argument "^[6" or "M-6" -> digit-argument "^[7" or "M-7" -> digit-argument "^[8" or "M-8" -> digit-argument "^[9" or "M-9" -> digit-argument "^[?" or "M-?" -> which-command "^[B" or "M-B" -> backward-word "^[C" or "M-C" -> capitalize-word "^[D" or "M-D" -> delete-word "^[F" or "M-F" -> forward-word "^[H" or "M-H" -> run-help "^[L" or "M-L" -> downcase-word "^[N" or "M-N" -> history-search-forward "^[P" or "M-P" -> history-search-backward "^[R" or "M-R" -> toggle-literal-history "^[S" or "M-S" -> spell-word "^[U" or "M-U" -> upcase-word Cornell 6.04.00 Last change: 3 July 1993 5 TCSH(1) User Commands TCSH(1) "^[W" or "M-W" -> copy-region-as-kill "^[_" or "M-_" -> insert-last-word "^[b" or "M-b" -> backward-word "^[c" or "M-c" -> capitalize-word "^[d" or "M-d" -> delete-word "^[f" or "M-f" -> forward-word "^[h" or "M-h" -> run-help "^[l" or "M-l" -> downcase-word "^[n" or "M-n" -> history-search-forward "^[p" or "M-p" -> history-search-backward "^[r" or "M-r" -> toggle-literal-history "^[s" or "M-s" -> spell-word "^[u" or "M-u" -> upcase-word "^[w" or "M-w" -> copy-region-as-kill "^[^?" or "M-^?" -> backward-delete-word "^X^X" -> exchange-point-and-mark "^X*" -> expand-glob "^X$" -> expand-variables "^XG" -> list-glob "^Xg" -> list-glob "^Xn -> normalize-path "^XN -> normalize-path VI Insert Mode functions "^@" -> is undefined "^A" -> beginning-of-line "^B" -> backward-char "^C" -> tty-sigintr "^D" -> list-or-eof "^E" -> end-of-line "^F" -> forward-char "^G" -> list-glob "^H" -> backward-delete-char "^I" -> complete-word "^J" -> newline "^K" -> kill-line "^L" -> clear-screen "^M" -> newline "^N" -> down-history "^O" -> tty-flush-output "^P" -> up-history "^Q" -> tty-start-output "^R" -> redisplay "^S" -> tty-stop-output "^T" -> transpose-chars "^U" -> backward-kill-line "^V" -> quoted-insert "^W" -> backward-delete-word "^X" -> expand-line "^Y" -> tty-dsusp Cornell 6.04.00 Last change: 3 July 1993 6 TCSH(1) User Commands TCSH(1) "^Z" -> tty-sigtsusp "^[" -> vi-cmd-mode "^\" -> tty-sigquit " " to "~" -> self-insert-command "^?" -> backward-delete-char VI Command Mode functions "^@" -> is undefined "^A" -> beginning-of-line "^B" -> is undefined "^C" -> tty-sigintr "^D" -> list-choices "^E" -> end-of-line "^F" -> is undefined "^G" -> list-glob "^H" -> backward-char "^I" -> vi-cmd-mode-complete "^J" -> newline "^K" -> kill-line "^L" -> clear-screen "^M" -> newline "^N" -> down-history "^O" -> tty-flush-output "^P" -> up-history "^Q" -> tty-start-output "^R" -> redisplay "^S" -> tty-stop-output "^T" -> is undefined "^U" -> backward-kill-line "^V" -> is undefined "^W" -> backward-delete-word "^X" -> expand-line "^[" -> sequence-lead-in "^\" -> tty-sigquit " " -> forward-char "!" -> expand-history "$" -> end-of-line "*" -> expand-glob "+" -> down-history ";" -> vi-repeat-char-fwd "," -> vi-repeat-char-back "-" -> up-history "." -> is undefined "/" -> vi-search-back "0" -> vi-zero "1" to "9" -> digit-argument "?" -> vi-search-fwd "@" -> is undefined "A" -> vi-add-at-eol "B" -> vi-word-back "C" -> change-till-end-of-line Cornell 6.04.00 Last change: 3 July 1993 7 TCSH(1) User Commands TCSH(1) "D" -> kill-line "E" -> vi-endword "F" -> vi-char-back "I" -> vi-insert-at-bol "J" -> history-search-forward "K" -> history-search-backward "N" -> vi-search-back "O" -> sequence-lead-in "R" -> vi-replace-mode "S" -> vi-substitute-line "T" -> vi-charto-back "U" -> is undefined "V" -> expand-variables "W" -> vi-word-fwd "X" -> backward-delete-char "[" -> sequence-lead-in "\^" -> beginning-of-line "a" -> vi-add "b" -> backward-word "c" -> is undefined "d" -> vi-delmeta "e" -> vi-eword "f" -> vi-char-fwd "h" -> backward-char "i" -> vi-insert "j" -> down-history "k" -> up-history "l" -> forward-char "m" -> is undefined "n" -> vi-search-fwd "r" -> vi-replace-char "s" -> vi-substitute-char "t" -> vi-charto-fwd "u" -> vi-undo "v" -> expand-variables "w" -> vi-beginning-of-next-word "x" -> delete-char "~" -> change-case "^?" -> backward-delete-char "M-?" -> run-help "M-[" -> sequence-lead-in "M-O" -> sequence-lead-in VI Multi-character bindings "^[?" -> run-help In _t_c_s_h there are two input modes: _i_n_s_e_r_t and _o_v_e_r_w_r_i_t_e. All characters that are bound to the _s_e_l_f-_i_n_s_e_r_t-_c_o_m_m_a_n_d either get inserted or overwrite what was under the cursor depend- ing on the input mode. In emacs one can toggle between modes Cornell 6.04.00 Last change: 3 July 1993 8 TCSH(1) User Commands TCSH(1) using the _o_v_e_r_w_r_i_t_e-_m_o_d_e function, and in VI one can use any of the replace mode commands. By default the mode is preserved between input lines. To specify a default mode that can be enforced at the beginning of each command line, the variable _i_n_p_u_t_m_o_d_e can be set to either _i_n_s_e_r_t or _o_v_e_r_w_r_i_t_e. There is also an older version of bindkey called _b_i_n_d, that allows the user to redefine what any key does, or find out what any or all of the keys do. This is retained for compa- tibility reasons. If given two arguments _b_i_n_d binds the function (first argu- ment) to the given key (second argument). The key may be: the direct character or a caret- combination, which is converted to control-; M- for an escaped character; or F- for a function key. For the last of these, the function key prefix must be bound to the func- tion "sequence-lead-in" and the string specified to the _b_i_n_d command must not include this prefix. If given one argument _b_i_n_d takes the argument as the name for a key and tells what that key does. As a special case, the user can say bind emacs or bind vi to bind all the keys for Emacs or vi mode respectively. If given no arguments _b_i_n_d tells what all of the keys do. If you give bind the single argument of 'defaults', it resets each key to its default value (see the above list). 22.. VVIISSUUAALL HHIISSTTOORRYY The keys ^P and ^N are used to step up and down the history list. If the user has typed in the following: > ls foo bar > echo mumble mumble > then enters ^_P, the shell will place "echo mumble" into the editing buffer, and will put the cursor at the end of the line. If another ^_P is entered, then the editing line will change to "ls". More ^_Ps will make the bell ring, since there are no more lines in the history. ^_N works the same way, except it steps down (forward in time). Cornell 6.04.00 Last change: 3 July 1993 9 TCSH(1) User Commands TCSH(1) An easy way to re-do a command is to type ^_P followed by _R_e_t_u_r_n. Also, pieces of previous commands can be assembled to make a new command. The commands that work on regions are especially useful for this. ^_P and ^_N actually only copy commands from out of the his- tory into the edit buffer; thus the user may step back into the history and then edit things, but those changes do not affect what is actually in _t_c_s_h '_s history. Another way to recall (parts of) history commands is via the 'expand-history' function. A variation of the 'expand- history' function is called 'magic-space'. This function expands _c_s_h history, and always appends a space. Magic-space thus can be bound to , to automatically expand _c_s_h history. Expand-history is normally bound to _M-<_s_p_a_c_e> and magic-space is not bound. 33.. TTTTYY MMOODDEE SSAANNIITTYY As part of the editor, _t_c_s_h does a check and reset of the terminal mode bits. If the speed has been changed, then _t_c_s_h will change to using that speed. _T_c_s_h will also obey changes in the padding needed by the tty. Also, the shell will automatically turn off RAW and CBREAK (on systems that use _t_e_r_m_i_o(_7) it will turn on ICANON) modes, and will turn on the tty driver's output processing (OPOST). The list of the tty modes that are always set or cleared by _t_c_s_h can be examined and modified using the _s_e_t_t_y builtin. The _s_e_t_t_y display is similar to _s_t_t_y(_1), and varies depend- ing on the system's tty driver. Modes that _t_c_s_h will always try to set are shown as +_m_o_d_e . Modes that _t_c_s_h will always try to clear are shown as -_m_o_d_e and modes that tcsh will track and allow to be modified are not shown by default, or if the -_a flag is given, are shown without a leading sign. For tty characters, -_c_h_a_r disables the tty character, while +_c_h_a_r protects the tty character from being changed. Setty can be used to control the three different modes _t_c_s_h uses for the tty. The default mode displayed is the "exe- cute" mode which is used when tcsh executes commands. The two other modes are the "edit" mode and the "quote" mode. The "edit" mode is used for command line editing, and the "quote" mode is used when entering literal characters. The "execute" mode can be specified with -_x , the "edit" mode with -_d , and the "quote" mode with -_q For example if one wants to set the _e_c_h_o_k flag and let the _e_c_h_o_e pass unchanged: > setty iflag:-inlcr -igncr +icrnl oflag:+opost +onlcr -onlret Cornell 6.04.00 Last change: 3 July 1993 10 TCSH(1) User Commands TCSH(1) cflag: lflag:+isig +icanon +echo +echoe -echok -echonl -noflsh +echoctl -flusho +iexten chars: > setty +echok echoe > setty iflag:-inlcr -igncr +icrnl oflag:+opost +onlcr -onlret cflag: lflag:+isig +icanon +echo +echok -echonl -noflsh +echoctl -flusho +iexten chars: 44.. WWOORRDD CCOOMMPPLLEETTIIOONN In typing commands, it is no longer necessary to type a com- plete name, only a unique abbreviation is necessary. When you type a TAB to _t_c_s_h it will complete the name for you, echoing the full name on the terminal (and entering it into the edit buffer). If the prefix you typed matches no name, the terminal bell is rung, unless the variable _n_o_b_e_e_p is set. The name may be partially completed if the prefix matches several longer names. If this is the case, the name is extended up to the point of ambiguity, and the bell is rung. This works for file names, command names, shell vari- ables and the ~ user name convention. The variable _f_i_g_n_o_r_e may be set to a list of suffixes to be disregarded during completion. _E_x_a_m_p_l_e Assume the current directory contained the files: DSC.TXT bin cmd lib memos DSC.NEW chaos cmtest mail netnews bench class dev mbox new The command: > gnumacs ch[TAB] would cause _t_c_s_h to complete the command with the file name chaos. If instead, the user had typed: > gnumacs D[TAB] _t_c_s_h would have extended the name to DSC and rung the termi- nal bell, indicating partial completion. However, if _f_i_g_n_o_r_e had previously been set to a list containing .NEW as one element, e.g. ( .o .NEW ), _t_c_s_h would have completed the `D' to DSC.TXT. Cornell 6.04.00 Last change: 3 July 1993 11 TCSH(1) User Commands TCSH(1) File name completion works equally well when other direc- tories are addressed. Additionally, _t_c_s_h understands the C shell tilde (~) convention for home directories. In addi- tion it caches tilde name references for fast access. This cache can be flushed by using the builtin _r_e_h_a_s_h. Thus, > cd ~speech/data/fr[TAB] does what one might expect. This may also be used to expand login names only. Thus, > cd ~sy[TAB] expands to > cd ~synthesis Command names may also be completed, for example, > gnum[TAB] will expand to "gnumacs" (assuming that there are no other commands that begin with "gnum"). Shell and environment variables are recognized also and in addition they can be expanded: > set local=/usr/local > echo $lo[TAB] will expand to "$local/". Note that a slash is appended because the expanded variable points to a directory. Also: > set local=/usr/local > echo $local/[^D] bin/ etc/ lib/ man/ src/ will correctly list the contents of /usr/local. Shell and environment variables can also be expanded via the expand- variables function: > echo $local/[^X$] > echo /usr/local/ Completion also works when the cursor is in the middle of the line, rather than just the end. All of the text after the cursor will be saved, the completion will work (possibly adding to the current name), and then the saved text will be restored in place, after the cursor. Cornell 6.04.00 Last change: 3 July 1993 12 TCSH(1) User Commands TCSH(1) The behavior of the completion can be changed by the setting of several shell variables: Setting the _r_e_c_e_x_a_c_t variable makes an exact command be expanded rather than just ringing the bell. For example, assume the current directory has two sub-directories called foo and food, then with _r_e_c_e_x_a_c_t set the following could be done: > cd fo[TAB] to ... > cd foo[TAB] to ... > cd foo/ rather than beeping on the second TAB. If the _a_u_t_o_l_i_s_t variable is set, invoking completion when several choices are possible will automatically list the choices, effectively merging the functionality described in the next section into the completion mechanism. If _a_u_t_o_l_i_s_t is set to "ambiguous", then _t_c_s_h will only list the choices if there were no new characters added in the completion operation. The "noise level" can be controlled by the value that _m_a_t_c_h_- _b_e_e_p is set to: With matchbeep=nomatch, completion will only beep if there are no matching names; with matchbeep=ambiguous, completion will _a_l_s_o beep if there are many possible matches; with matchbeep=notunique, completion will _a_l_s_o beep when there is an exact match but there are other, longer, matches (see recexact). With matchbeep=never or set to any other value completion will never beep. If matchbeep is not set it defaults to ambiguous. If the _a_u_t_o_e_x_p_a_n_d variable is set, the expand-history func- tion will be invoked automatically before the completion attempt, expanding normal _c_s_h history substitutions. For covert operation, the variable _n_o_b_e_e_p can be set; it will prevent the completion mechanism, as well as _t_c_s_h in general, from actually beeping. Finally, if the _a_u_t_o_c_o_r_r_e_c_t variable is set, the spelling correction is attempted for any path components up to the completion point. 55.. LLIISSTTIINNGG OOFF PPOOSSSSIIBBLLEE NNAAMMEESS At any point in typing a command, you may request "what names are available". Thus, when you have typed, perhaps: > cd ~speech/data/fritz/ Cornell 6.04.00 Last change: 3 July 1993 13 TCSH(1) User Commands TCSH(1) you may wish to know what files or sub-directories exist (in ~speech/data/fritz), without, of course, aborting the com- mand you are typing. Typing the character Control-D (^D), will list the names (files, in this case) available. The files are listed in multicolumn format, sorted column-wise. Directories are indicated with a trailing `/', executable files with a `*', symbolic links with a '@', sockets with a '=', FIFOs (named pipes) with a '|', character devices with a '%', and block devices with a '#'. Once printed, the com- mand is re-echoed for you to complete. Additionally, one may want to know which files match a pre- fix. If the user had typed: > cd ~speech/data/fr[^D] all files and sub-directories whose prefix was ``fr'' would be printed. Notice that the example before was simply a degenerate case of this with a null trailing file name. (The null string is a prefix of all strings.) Notice also, that a trailing slash is required to pass to a new directory for both file name completion and listing. The degenerate > ~[^D] will print a full list of login names on the current system. Note, however, that the degenerate > [^D] does not list all of the commands, but only the files in the current working directory. Listing/expanding of words that match a name containing wildcard characters can be done via the list-glob/expand- glob function: > ls foo.c bar.c a.out > vi *.c[^Xg] foo.c bar.c > vi *.c[^X*] > vi foo.c bar.c CCoommmmaanndd NNaammee RReeccooggnniittiioonn Command name recognition and completion works in the same manner as file name recognition and completion above. The current value of the environment variable _P_A_T_H is used in searching for the command. For example > newa[TAB] Cornell 6.04.00 Last change: 3 July 1993 14 TCSH(1) User Commands TCSH(1) might expand to > newaliases Also, > new[^D] would list all commands (along PATH) that begin with "new". Note that Control-D has three different effects on _t_c_s_h. On an empty line (one that contains nothing, not even spaces), ^_D sends an EOF to _t_c_s_h just as it does for normal programs. When the cursor is in the middle of a line of text, ^_D deletes the character that the cursor is under. Finally, a ^_D at the end of a line of text lists the available names at that point. To get a list of available names when the cur- sor is in the middle of a line (or on an empty line), a Meta-Control-D should be typed (Escape followed by Control- D). 66.. SSPPEELLLLIINNGG CCOORRRREECCTTIIOONN If while typing a command, the user mistypes or misspells a file name, user name, or command name, _t_c_s_h can correct the spelling. When correcting a file name, each part of the path is individually checked and corrected. Spelling correction can be invoked in several different ways: The _s_p_e_l_l-_w_o_r_d function, normally bound to M-s (and M-S), will attempt to correct the word immediately before the cur- sor. For example, suppose that the user has typed: > cd /uxr/spol/news[ESC s] _T_c_s_h will check the path for spelling, correct the mistakes, and redraw the line as > cd /usr/spool/news leaving the cursor at the end of the line. Spelling correction of the entire command line (independent of where the cursor is) can be done with the _s_p_e_l_l-_l_i_n_e function, normally bound to M-$ (Escape Dollar-sign). It will check each word independently, but in order to avoid e.g. command options, no correction is attempted on words whose first character is found in the string "!.\^-*%". Finally, automatic spelling correction will be done each time the Return key is hit, if the _c_o_r_r_e_c_t variable is set to an appropriate value: correct=cmd will cause the spel- ling of the command name only to be checked, while Cornell 6.04.00 Last change: 3 July 1993 15 TCSH(1) User Commands TCSH(1) correct=all causes checking of all words on the line, like the spell-line function. If any part of the command line is corrected, the user will be given a special prompt as defined by the _p_r_o_m_p_t_3 variable, followed by the corrected line, e.g. > lz /usr/bin CORRECT>ls /usr/bin (y|n|e)? Answering 'y' or at the prompt will cause the corrected line to be executed, 'e' will leave the uncorrected command in the input buffer and anything else will execute the original line unchanged. Automatic correction is not guaranteed to work the way the user intended. Command line parsing is done in a rudimen- tary fashion. It is mostly provided as an experimental feature. Suggestions and improvements are welcome. 77.. DDOOCCUUMMEENNTTAATTIIOONN LLOOOOKKUUPP The editor function _r_u_n-_h_e_l_p (M-h) prints a help file on the current command (using the same definition of current as the completion routines use). This help file is found by searching the path list HPATH for files of the form foo.help, foo.1, foo.8, or foo.6 in that order (assuming that the current command is foo). The file is just printed, not paged in any way. This is because _r_u_n-_h_e_l_p is meant to be used to look up short help files, not manual pages (although it can do manual pages also). 88.. EENNHHAANNCCEEDD HHIISSTTOORRYY MMEECCHHAANNIISSMM _T_c_s_h will save the history list between login sessions. It does this by writing the current list to the file "~/.his- tory" on logout, and reading it in on login. For example, placing the line > set history=25 savehist=20 tells _t_c_s_h to save the last 25 commands on the history list, and to save the last 20 of them between logins. The "savehist" variable may be set up to the size of history, although it is an error to have _s_a_v_e_h_i_s_t larger than _h_i_s_- _t_o_r_y. In addition to the above _t_c_s_h, keeps unparsed (literal) versions of the history if the variable _h_i_s_t_l_i_t is set. Also the toggle-history function toggles between the parsed and literal version of the recalled history in the editor buffer. For example: > set histlit > echo !:s/foo/bar; ls Modifier failed. > ^P Cornell 6.04.00 Last change: 3 July 1993 16 TCSH(1) User Commands TCSH(1) > echo !:s/foo/bar; ls > unset histlit > echo !:s/foo/bar; ls Modifier failed. > ^P > echo unset histlit[M-r] > echo !:s/foo/bar; ls _T_c_s_h also supports the history escape !#. This undocumented _c_s_h escape holds the words of the current line. This is use- ful in renaming commands: > mv foo bar!#:1 mv foo barfoo Care should be taken when using this history expansion in _c_s_h since there is no check for recursion. In _t_c_s_h up to 10 levels of recursion are allowed. Another difference between _t_c_s_h and _c_s_h history expansion, is the treatment of history arguments. In _c_s_h !_3_d expands to event 3 with the letter "d" appended to it. There is no way to repeat a command that begins with a number using the name of the command in the history escape. In _t_c_s_h only numeric arguments are treated as event numbers; therefore !_3_d is interpreted as: repeat the last command that started with the string "3d". To mimic the _c_s_h behavior !_3\_d can be used. 99.. AAUUTTOOMMAATTIICC LLOOGGOOUUTT//LLOOCCKKIINNGG The automatic locking and logout time are controlled by the variable _a_u_t_o_l_o_g_o_u_t. The value of the first word is the number of minutes of inactivity will be allowed before automatically logging the user out. When that many minutes have been reached, the shell prints "auto-logout" and dies (without executing ~/.logout). The default for _t_c_s_h is to set _a_u_t_o_l_o_g_o_u_t for 60 minutes on login shells, and when the user is root. To disable autologout (for instance in a win- dow system), unset the shell variable _a_u_t_o_l_o_g_o_u_t. The value of the optional second word indicates the number of minutes of inactivity after which the user will be prompted for his login password to continue working. Failure to enter the correct password 5 times, results in auto- logout. 1100.. EEXXEECCUUTTIIOONN OOFF AA CCOOMMMMAANNDD PPRRIIOORR TTOO EEAACCHH PPRROOMMPPTT _T_c_s_h supports a special alias, _p_r_e_c_m_d, which if set holds a command that will be executed before printing each prompt. For example, if the user has done > alias precmd date Cornell 6.04.00 Last change: 3 July 1993 17 TCSH(1) User Commands TCSH(1) then the program _d_a_t_e will be run just before the shell prompts for each command. There are no limitations on what precmd can be set to do, although discretion should be used. 1111.. PPEERRIIOODDIICC CCOOMMMMAANNDD EEXXEECCUUTTIIOONN _T_c_s_h is now capable of providing periodic command execution through the use of the shell variable _t_p_e_r_i_o_d and the alias _p_e_r_i_o_d_i_c. When these items are set, the alias _p_e_r_i_o_d_i_c will be executed every _t_p_e_r_i_o_d minutes. This provides a con- venient means for checking on common but infrequent changes, such as new messages. Example: > set tperiod = 30 > alias periodic checknews This will cause the _c_h_e_c_k_n_e_w_s(1) program to be run every 30 minutes. Having the alias _p_e_r_i_o_d_i_c set but with an unset _t_p_e_r_i_o_d (or a value of 0 for _t_p_e_r_i_o_d) will cause _p_e_r_i_o_d_i_c to degenerate to another form of _p_r_e_c_m_d. 1122.. NNEEWW PPRROOMMPPTT FFOORRMMAATT The format for the _p_r_o_m_p_t shell variable has been changed to include many new things, such as the current time of day, current working directory, etc.. The new format uses "%" to signal an expansion, much like _p_r_i_n_t_f(_3_S). The available sequences are: %/ Current working directory. %~ cwd. If it starts with $HOME, that part is replaced by a ~. In addition if a directory name prefix matches a user's home directory, that part of the directory will be substituted with ~user. NOTE: The ~user substitution will only happen if the shell has performed a ~ expansion for that user name in this session. %c or %. Trailing component of cwd, may be followed by by a digit to get more than one component, if it starts with $HOME, that part is replaced with a ~. %C Trailing component of cwd, may be followed by a digit to get more than one component, no ~ substitution. %h, %!, ! Current history event number. %M The full machine hostname. %m The hostname up to the first ".". %S (%s) Start (stop) standout mode. %B (%b) Start (stop) boldfacing mode. (Only if tcsh was compiled to be eight bit clean.) %U (%u) Start (stop) underline mode. (Only if tcsh was compiled to be eight bit clean.) %t or %@ Current time of day, in 12-hour, am/pm format. %T Current time of day, in 24-hour format. Cornell 6.04.00 Last change: 3 July 1993 18 TCSH(1) User Commands TCSH(1) (But see the _a_m_p_m shell variable below.) %p Current time in 12-hour format, am/pm format with seconds. %P Current time in 24-hour format, with seconds. \c `c' is parsed the same way as in bindkey. ^c `c' is parsed the same way as in bindkey. %% A single %. %n The user name, contents of $user. %d The weekday in format. %D The day in dd format. %w The month in format. %W The month in mm format. %y The year in yy format. %Y The year in yyyy format. %l The line (tty) the user is logged on. %L clear from prompt to end of display or end of line. %# A `#' if tcsh is run as a root shell, a `>' if not. %{..%} Include string as a literal escape sequence. Note that the enclosed escape sequence, should only be used to change terminal attributes and should not move the cursor location. Also, this cannot be the last character in the prompt string. (Available only if tcsh was compiled to be eight bit clean.) %? return code of the last command executed just before the prompt. %R In prompt3 this is the corrected string; in prompt2 it is the status of the parser. On %C, %c and %., if the optional digit is 0, then then next digit is interpreted as the number of directory components to be skipped, and the number of components skipped are reported as: /path/path. The sequences for standout are often used to indicate that this is an enabled (running as root) shell. An example: > set prompt="%m [%h] %U[%@]%u [%/] you rang? " tut [37] [_2:_5_4_p_m] [/usr/accts/sys] you rang? _ In addition, there is a new variable, _p_r_o_m_p_t_2, which is used to prompt for the body of while and for loops (wherever nor- mal _c_s_h prompts with a question mark). The default for _p_r_o_m_p_t_2 is "%R? ": the status of the parser followed by a question mark. This alternate prompt is also used when the parser is waiting for more input; i.e. when the previous line ended in a \. The _p_r_o_m_p_t_3 variable is used when displaying the corrected command line when automatic spel- ling correction is in effect; it defaults to "CORRECT>%R (y|n|e)? ". Cornell 6.04.00 Last change: 3 July 1993 19 TCSH(1) User Commands TCSH(1) 1133.. TTIIMMEE--SSTTAAMMPPEEDD HHIISSTTOORRYY LLIISSTT The history list in _t_c_s_h now has a time-of-day stamp attached to each history list event. This time stamp is printed whenever the history command is executed. This allows the user to keep track of when the various events occurred. The time stamps are not maintained on the saved history list (also available in _c_s_h); thus, on logging back in, all the saved history events will be recorded with the login time as their time stamp. The time stamp printouts can be omitted from the history list by adding the -t switch to the _h_i_s_t_o_r_y command. _T_c_s_h provides a way to save, restore and clear the history list in a file. _h_i_s_t_o_r_y -_S [<_f_i_l_e_n_a_m_e>] _h_i_s_t_o_r_y -_L [<_f_i_l_e_n_a_m_e>] _h_i_s_t_o_r_y -_c The 'S' flag saves the current history, the 'L' flags loads the history, and the 'c' flag clears the history. If a filename is not specified, then $HOME/.history is used. 1144.. DDIIRREECCTTOORRYY AACCCCEESSSS _T_c_s_h supports three new flags to control directory style printing for cd, pushd, popd, and dirs: -_n Print entries in new lines so that the screen width is not exceeded -_l Don't print ~ but print the whole path -_v Print the stack entries one in each line, preceded by the stack number. Note that popd +n can be used to pop out stack entries of directories that do not exist any more. _T_c_s_h always saves the last directory visited. Changing to the previous directory can be done by using '_c_d -' or '_p_u_s_h_d -'. _T_c_s_h will now allow the user to access all elements in the directory stack directly. The syntax "=" is recog- nized by _t_c_s_h as indicating a particular directory in the stack. (This works for the file/command name recognition as well.) This syntax is analogous to the ~ syntax for access to users' home directories. The stack is viewed as zero- based, i.e., =0 is the same as $cwd, which is the same as ".". As a special case, the string "=-" is recognized as indicating the last directory in the stack. Thus, > dirs -v 0 /usr/net/bin Cornell 6.04.00 Last change: 3 July 1993 20 TCSH(1) User Commands TCSH(1) 1 /usr/spool/uucp 2 /usr/accts/sys > echo =2 /usr/accts/sys > ls -l =1/LOGFILE -rw-r--r-- 1 uucp 2594 Jan 19 09:09 /usr/spool/uucp/LOGFILE > echo =-/.cs* /usr/accts/sys/.cshrc > echo =4 Not that many dir stack entries. > _T_c_s_h will complain if you ask for a directory stack item which does not exist. In the normal _c_s_h, saying "pushd +2" would rotate the entire stack around through 2 stack elements, placing the entry found there at the top of the stack. If, however, the new shell variable _d_e_x_t_r_a_c_t is set, then issuing "pushd +n" will cause the nth directory stack element to be extracted from its current position, which will then be pushed onto the top of the stack. Example: > dirs ~ /usr/spool/uucp /usr/net/bin /sys/src > set dextract > pushd +2 /usr/net/bin ~ /usr/spool/uucp /sys/src > unset dextract > pushd +2 /usr/spool/uucp /sys/src /usr/net/bin ~ _T_c_s_h provides a way to save, restore and clear the directory stack in a file. _d_i_r_s -_S [<_f_i_l_e_n_a_m_e>] _d_i_r_s -_L [<_f_i_l_e_n_a_m_e>] _d_i_r_s -_c The 'S' flag saves the current directory stack, the 'L' flags loads the directory stack, and the 'c' flag clears the directory stack. If a filename is not specified, then $HOME/.cshdirs is used. In addition, if the shell variable _d_u_n_i_q_u_e is set, only directories that are not already in the directory stack will be added when _p_u_s_h is invoked. The way symbolic links that point to directories are crossed is determined by the _s_y_m_l_i_n_k_s variable. By default, it is not set to anything and symbolic links are not treated spe- cially. However, it can be set to either: _c_h_a_s_e, _i_g_n_o_r_e, or Cornell 6.04.00 Last change: 3 July 1993 21 TCSH(1) User Commands TCSH(1) _e_x_p_a_n_d. If _s_y_m_l_i_n_k_s is set to _c_h_a_s_e, then every time the directory changes, $_c_w_d reflects the real directory name, and not the name through the link. A notable exception is the user's home directory, but that should be fixed. If _s_y_m_- _l_i_n_k_s is set to either _i_g_n_o_r_e or _e_x_p_a_n_d, then tcsh tries to determine the current directory name relative to the name of the current directory before the link was crossed. In simple terms, if you chdir through a symbolic link and then cd .., you will end .. relatively to where you were before you crossed the link and not .. relatively to where the symbolic link points. While _i_g_n_o_r_e affects only builtin commands and completion, _e_x_p_a_n_d affects command execution too, by `fix- ing' arguments that it considers to be path names. Unfor- tunately this does not work in every case, specially when file arguments are embedded in command line options. _E_x_p_a_n_d also allows to specify the `real' (as opposed to the one determined relatively to $_c_w_d), _b_y _q_u_o_t_i_n_g _t_h_e _f_i_l_e _a_r_g_u_- _m_e_n_t. For example: > cd /tmp > mkdir from from/src to > ln -s ../from/src to/dst > unset symlinks > cd /tmp/to/dst; echo $cwd /tmp/to/dst > cd ..; echo $cwd /tmp/from > set symlinks=chase > cd /tmp/to/dst; echo $cwd /tmp/from/src > cd ..; echo $cwd /tmp/from > set symlinks=ignore > cd /tmp/to/dst; echo $cwd /tmp/to/dst > cd ..; echo $cwd /tmp/to > set symlinks=expand > cd /tmp/to/dst; echo $cwd /tmp/to/dst > cd ..; echo $cwd # builtin /tmp/to > cd /tmp/to/dst; echo $cwd /tmp/to/dst > cd ".."; echo $cwd # quoted /tmp/from Cornell 6.04.00 Last change: 3 July 1993 22 TCSH(1) User Commands TCSH(1) > /bin/echo .. # rewrites non builtin commands. /tmp/to > /bin/echo ".." While the _e_x_p_a_n_d setting is the most convenient, and makes symbolic links invisible, it can sometimes be misleading and confusing in cases where it fails to recognize arguments. A compromise is to use the _i_g_n_o_r_e setting and use the editor functions "normalize-path", bound by default to ^_X_n. 1155.. WWAATTCCHHIINNGG FFOORR LLOOGGIINNSS AANNDD LLOOGGOOUUTTSS _T_c_s_h has a mechanism so that the user can watch for login and logout activity of any user or terminal in the system. This is accomplished using the new special shell variable _w_a_t_c_h, which contains login/terminal pattern pairs to be checked for activity. For example: > set watch=(sys ttyjd root console) This setting will allow the user to check on when the user "sys" logs in on /dev/ttyjd. Similarly, it will inform the user of root's activity on the console. In order to be more general, the word "any" may be substituted for either a user's or a terminal's name, thus allowing > set watch=('b*' any any ttyh0) which will check for users that match the pattern 'b*' log- ging in or out of the system on any terminal, as well as anyone logging in to /dev/ttyh0. Naturally, the completely general case > set watch=(any any) allows the user to check on any and all login/logout activity in the the system. By default, the interval between checks of users on the sys- tem is 10 minutes; this can be changed by making the first element of _w_a_t_c_h a number of minutes which should be used instead, as in > set watch=(40 any any) which will check for any users logging in or out every 40 minutes. There is also a new command, _l_o_g, which is used to cause _t_c_s_h to inform the user of all users/terminals affected by _w_a_t_c_h whether they have been announced before or not. This is useful if a user has been on for some time and cannot remember if a particular person/terminal is online right now Cornell 6.04.00 Last change: 3 July 1993 23 TCSH(1) User Commands TCSH(1) or not. _L_o_g will reset all indication of previous announce- ment and give the user the login list all over again, as well as printing the current value of _w_a_t_c_h. The first time that _w_a_t_c_h is set at _t_c_s_h startup, all affected users and terminals will be printed as though those users/terminals had just logged on. This may appear to be a bug, but is generally considered a feature, since it allows the user to see who is on when he first logs in. The format of the printouts can be tailored via setting of the variable _w_h_o. In addition to the standard prompt % escapes, the following sequences are available for the for- mat specification: %n The name of the user that logged in/out. %a The observed action, i.e. "logged on", "logged off", or "replaced on". %l The line (tty) the user is logged on. %M The full hostname of the remote host ("local" if non-remote). %m The hostname up to the first ".". If only the ip address is available or the utmp field contains the name of an x-windows display, the whole name is printed. The %M and %m sequences are only available on systems that store the remote hostname in /etc/utmp. If _w_h_o is not set, the format defaults to "%n has %a %l from %m.", or "%n has %a %l." on systems that don't store the hostname. 1166.. TTIIMMEEDD EEVVEENNTT LLIISSTT _T_c_s_h now supports a scheduled-event list through the use of the command _s_c_h_e_d. This command gives the user a mechanism by which to arrange for other commands to be executed at given times. An event is added to the scheduled-event list by saying > sched [+]hh:mm as in > sched 11:00 echo It\'s eleven o\'clock. This will make an entry in the list at 11am for the echo command to be run with the given arguments. The time may be specified in either absolute or relative time, and absolute times may have a morning/afternoon specification as well, using "am" or "pm." For example, > sched +2:15 /usr/lib/uucp/uucico -r1 -sother > sched 5pm set prompt='[%h] It\'s after 5; go home: >' Cornell 6.04.00 Last change: 3 July 1993 24 TCSH(1) User Commands TCSH(1) > sched +3am echo This syntax doesn\'t work. Relative time inconsistent with am/pm. > Note that _t_c_s_h will complain if you try to make faulty time specifications. Printing the current time-event list is accomplished by giv- ing the _s_c_h_e_d command with no arguments: > sched 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico -r1 -sother 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: > > There is also a mechanism by which the user can remove an item from the list: > sched --3 Usage for delete: sched -. > sched -3 Not that many scheduled events. > sched -2 > sched 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico -r1 -sother > All commands specified on the scheduled-event list will be executed just prior to printing the first prompt immediately following the time when the command is to be run. Hence, it is possible to miss the exact time when the command is to be run, but _t_c_s_h will definitely get around to all commands which are overdue at its next prompt. Scheduled-event list items which come due while _t_c_s_h is waiting for user input will be executed immediately. In no case, however, will normal operation of already-running commands be interrupted so that a scheduled-event list element may be run. This mechanism is similar to, but not the same as, the _a_t(1) command on some Unix systems. Its major disadvantage is that it does not necessarily run a command at exactly the specified time (but only if another command is already being run). Its major advantage is that commands which run directly from _t_c_s_h, as sched commands are, have access to shell variables and other structures. This provides a mechanism for changing one's working environment based on the time of day. 1177.. BBUUIILLTTIINN FFOORR llss --FF There is a new builtin command called _l_s-_F which does the same thing as the command "ls -F". If the shell variable _s_h_o_w_d_o_t_s has been set, it acts like "ls -aF". If _s_h_o_w_d_o_t_s is Cornell 6.04.00 Last change: 3 July 1993 25 TCSH(1) User Commands TCSH(1) equal to "-A", then _l_s-_F acts like "ls -AF". Ls-F works like ls, only it is generally faster, since it does not need to fork and exec, and safer against Trojan horses if the user has `.' in the execution path. If other switches are passed to _l_s-_F, then the normal ls is executed. Aliasing ls to ls-F provides a fast alternative way of listing files. Note that on non BSD machines, where ls -C is not the default, _l_s-_F, behaves like ls -CF. _l_s-_F appends the following characters depending on the file type: = File is an AF_UNIX domain socket. [if system supports sockets] | File is a named pipe (fifo) [if system supports named pipes] % File is a character device # File is a block device / File is a directory * File is executable + File is a hidden directory [aix] or context dependent [hpux] : File is network special [hpux] On systems that support symbolic links the variable _l_i_s_t_- _l_i_n_k_s controls the way symbolic links are identified. If _l_i_s_t_l_i_n_k_s is not set then the character '@' is appended to the file. If _l_i_s_t_l_i_n_k_s is set then the following characters are appended to the filename depending on the type of file the symbolic links points to: @ File is a symbolic link pointing to a non-directory > File is a symbolic link pointing to a directory & File is a symbolic link pointing to nowhere While setting _l_i_s_t_l_i_n_k_s can be helpful while navigating around the file system, it slows down _l_s-_F and it causes mounting of file systems if the symbolic links point to an NFS auto-mounted partition. 1188.. GGLLOOBBBBIINNGG SSYYNNTTAAXX AADDDDIITTIIOONNSS The syntax for any character in a range (for example ".[a- z]*") has been extended so as to conform with standard Unix regular expression syntax (see _e_d(1)). Specifically, after an open bracket ("["), if the first character is a caret ("^") then the character matched will be any not in the range specified. For example: > cd ~ Cornell 6.04.00 Last change: 3 July 1993 26 TCSH(1) User Commands TCSH(1) > echo .[a-z]* .cshrc .emacs .login .logout .menuwmrc > echo .[^.]* .Xdefaults .Xinit .cshrc .emacs .login .logout .menuwmrc > Note that the second form includes .Xdefaults and .Xinit because 'X' (and all the lower case letters) are outside of the range of a single '.'. Also the ability to negate a globbing pattern has been added: > echo * foo foobar bar barfoo > echo ^foo* bar barfoo Note that this does not work correctly if the expression does not have any wildcard characters (?*[]) or if the expression has braces {}. 1199.. NNEEWW EENNVVIIRROONNMMEENNTT AANNDD SSHHEELLLL VVAARRIIAABBLLEESS On startup, _t_c_s_h now automatically initializes the environ- ment variable _H_O_S_T to the name of the machine that it is running on. It does this by doing a _g_e_t_h_o_s_t_n_a_m_e(2) system call, and setting _H_O_S_T to the result. _T_c_s_h also initializes the environment variable _H_O_S_T_T_Y_P_E to a symbolic name for the type of computer that it is running on. This is useful when sharing a single physical directory between several types of machines (running NFS, for instance). For example, if the following is in ._l_o_g_i_n: set path = (~/bin.$HOSTTYPE /usr/ucb /bin /usr/bin /usr/games .) and the user has directories named "bin._m_a_c_h_i_n_e" (where _m_a_c_h_i_n_e is a name from the list below), then the user can have the same programs compiled for different machines in the appropriate "bin._m_a_c_h_i_n_e" directories and _t_c_s_h will run the binary for the correct machine. The current possible values are: _3_8_6_B_S_D an Intel 386, running 386BSD _a_i_x_3_7_0 an IBM 370, running aix _a_i_x_E_S_A an IBM ESA, running aix _a_l_l_i_a_n_t an Alliant FX series _a_l_l_i_a_n_t-_f_x_8_0 an Alliant FX80 (mc68000 based) _a_l_l_i_a_n_t-_f_x_2_8_0_0 an Alliant FX2800 (i860 based) _a_l_p_h_a an DEC Alpha running OSF/1 Cornell 6.04.00 Last change: 3 July 1993 27 TCSH(1) User Commands TCSH(1) _a_m_d_a_h_l an Amdahl running uts 2.1 _a_m_i_g_a an amiga running amix 2.02 _a_p_o_l_l_o an Apollo running DomainOS _a_t_t_3_b_1_5 an AT&T 3b15 _a_t_t_3_b_2 an AT&T 3b2 _a_t_t_3_b_2_0 an AT&T 3b20 _a_t_t_3_b_5 an AT&T 3b5 _b_a_l_a_n_c_e a Sequent Balance (32000 based) _b_s_d_3_8_6 an Intel 386, running BSDI's bsd386 _b_u_t_t_e_r_f_l_y a BBN Computer Butterfly 1000 _c_o_h_3_8_6 a 386 running Coherent 4.0 _c_o_h_e_r_e_n_t an unknown machine running Coherent _c_o_n_v_e_x a Convex _c_r_a_y a Cray running Unicos _d_e_c_s_t_a_t_i_o_n a DecStation XXXX _e_t_a_1_0 an ETA 10 running SVR3 _g_o_u_l_d-_n_p_1 a Gould NP1 _h_k_6_8 a Heurikon HK68 running Uniplus+ 5.0 _h_p_3_0_0 an HP 9000, series 300, running mtXinu _h_p_8_0_0 an HP 9000, series 800, running mtXinu _h_p_9_0_0_0_s_3_0_0 an HP 9000, series 300, running hpux _h_p_9_0_0_0_s_5_0_0 an HP 9000, series 500, running hpux _h_p_9_0_0_0_s_7_0_0 an HP 9000, series 700, running hpux _h_p_9_0_0_0_s_8_0_0 an HP 9000, series 800, running hpux _h_p an HP, running hpux _i_3_8_6 an Intel 386, generic _i_3_8_6-_m_a_c_h an Intel 386, running mach _i_3_8_6-_l_i_n_u_x an Intel 386, running Linux _i_3_8_6-_e_m_x an Intel 386, running emx [unix emulation under OS/2] _i_n_t_e_l_3_8_6 an Intel 386, running INTEL's SVR3 _i_r_i_s_3_d a Silicon Graphics Iris 3000 _i_r_i_s_4_d a Silicon Graphics Iris 4D _i_s_c_3_8_6 an Intel 386, running ISC _l_y_n_x_o_s-_i_3_8_6 _A_n _I_n_t_e_l _3_8_6 _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_i_8_6_0 _A_n _I_n_t_e_l _8_6_0 _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_m_6_8_k _A _M_o_t_o_r_o_l_a _6_8_K _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_m_8_8_k _A _M_o_t_o_r_o_l_a _8_8_K _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_s_p_a_r_c _A _s_p_a_r_c _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_m_i_p_s _A _m_i_p_s _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _l_y_n_x_o_s-_u_n_k_n_o_w_n _S_o_m_e_t_h_i_n_g _r_u_n_n_i_n_g _L_y_n_x/_O_S-_2._1 _m_8_8_k an mc88000 CPU machine _m_a_c_2 an Apple Computer Macintosh II, running AUX _m_a_s_s_c_o_m_p a Concurrent (Masscomp), running RTU _m_i_n_i_x_3_8_6 an i386 running minix _m_i_n_i_x a mac or an amiga running minix _m_i_p_s another mips CPU _m_u_l_t_i_m_a_x an Encore Computer Corp. Multimax (32000 based) _n_e_w_s a Sony NEWS 800 or 1700 workstation _n_e_w_s__m_i_p_s a NeWS machine with mips CPU _n_d_5_0_0 a Norsk Data ND 500/5000 running Ndix _n_s_3_2_0_0_0 an NS32000 CPU machine _n_e_x_t a NeXT computer Cornell 6.04.00 Last change: 3 July 1993 28 TCSH(1) User Commands TCSH(1) _p_a_r_a_g_o_n an intel paragon running osf1 _p_f_a_5_0 a PFU/Fujitsu A-xx computer _p_s_2 an IBM PS/2, running aix _p_t_x a Sequent Symmetry running DYNIX/ptx (386/486 based) _p_y_r_a_m_i_d a Pyramid Technology computer (of any flavor) _r_s_6_0_0_0 an IBM RS6000, running aix _r_t an IBM PC/RT, running BSD (AOS 4.3) or mach _r_t_p_c an IBM PC/RT, running aix _s_c_o_3_8_6 an Intel 386, running SCO _s_t_e_l_l_a_r a stellar running stellix _s_u_n a Sun workstation of none of the above types _s_u_n_2 a Sun Microsystems series 2 workstation (68010 based) _s_u_n_3 a Sun Microsystems series 3 workstation (68020 based) _s_u_n_3_8_6_i a Sun Microsystems 386i workstation (386 based) _s_u_n_4 a Sun Microsystems series 4 workstation (SPARC based) _s_y_m_m_e_t_r_y a Sequent Symmetry running DYNIX 3 (386/486 based) _s_y_s_V_8_8 a Motorola MPC running System V/88 R32V2 (SVR3/88100 based) _t_a_h_o_e a tahoe running 4BSD _t_e_k_4_3_0_0 a Tektronix 4300 running UTek (BSD 4.2 / 68020 based) _t_e_k_X_D_8_8 a Tektronix XD88/10 running UTekV 3.2e (SVR3/88100 based) _t_i_t_a_n an Stardent Titan _u_n_i_x_p_c an UNIX/PC running SVR1 att7300 aka att3b1 _v_a_x a Digital Equipment Corp. Vax (of any flavor) _v_i_s_t_r_a_8_0_0 a Stardent Vistra 800 running SVR4 _V_M_S-_P_O_S_I_X a vax? running VMS/POSIX (The names of the machines are usually trade marks of the corresponding companies.) _T_c_s_h also initializes the shell variables _u_i_d and _g_i_d to the value of the current real user ID/GID. This is useful for telling what user/group the shell is running as. Under Domain/OS _t_c_s_h will also set _o_i_d indicating the current real organization id. 2200.. CCOOMMMMAANNDDSS FFOORR DDEEBBUUGGGGIINNGG Only two such commands are available at this point, both concerned with testing termcap entries. _t_e_l_l_t_c tells you, politely, what _t_c_s_h thinks of your termi- nal, and _s_e_t_t_c `cap' `value' tells _t_c_s_h to believe that the termcap capability `cap' ( as defined in _t_e_r_m_c_a_p(5) ) has the value `value'. No checking for sanity is performed, so beware of improper use. Note that Concept terminal users may have to "settc xn no" to get proper wrapping at the rightmost column. 2211.. SSEEAARRCCHHIINNGG FFOORR TTHHEE VVIISSUUAALL HHIISSTTOORRYY Four new editor functions have been added in emacs mode: Two of them, history-search-backward, bound to M-p (and M-P), and history-search-forward, bound to M-n (and M-N), imple- ment a conventional search mechanism, while the other two, Cornell 6.04.00 Last change: 3 July 1993 29 TCSH(1) User Commands TCSH(1) i-search-back and i-search-fwd, both unbound by default, implement the emacs-style incremental search. History-search-backward (history-search-forward) searches backward (forward) through the history list for previous (next) occurrence of the beginning of the input buffer as a command. That is, if the user types: > echo foo foo > ls filea fileb > echo bar bar > and then types "echop", the shell will place "echo bar" in the editing buffer. If another _M-_p was entered, the editing buffer would change to "echo foo". This capability is compatible with the plain visual history; if the user were to then enter ^_P the editing buffer would be changed to "ls". The pattern used to search through the history is defined by the characters from the beginning of the line up to the current cursor position and may contain a shell glob- bing pattern. Successive history searches use the same pat- tern. When the incremental search functions are used, a prompt - "bck:" or "fwd:", depending on the chosen direction - appears, and characters typed are appended to the search pattern. The matching command line is placed in the editing buffer, with the cursor positioned at the point where the pattern was found (the incremental search will also do searching within a command line). If the search fails, the terminal bell is rung, and the ':' in the prompt is changed to '?'. If these functions are bound to single characters, and one of those is typed again during the incremental search, the search continues in the corresponding direction, with the pattern unchanged; if the previous search failed, this will also cause it to "wrap around" the history list. Finally, the following characters also have a special meaning during the search: Delete (or any character bound to _b_a_c_k_w_a_r_d-_d_e_l_e_t_e-_c_h_a_r) Undo the effect of the last character typed, deleting a character from the pattern if appropriate. ^G Abort the search, back to the last successful one if previous search failed, otherwise entire search. ^W Append the rest of the current word to the pattern. ESC Terminate the search, leaving current line in buffer. Cornell 6.04.00 Last change: 3 July 1993 30 TCSH(1) User Commands TCSH(1) Any other character, that isn't bound to _s_e_l_f-_i_n_s_e_r_t- _c_o_m_m_a_n_d, terminates the search, leaving the current command line in the editing buffer, after which _t_c_s_h interprets the character as if it was normal input - notably _R_e_t_u_r_n will cause the current command line to be executed. In vi mode "vi-search-fwd" (bound to '/') and "vi-search- back" (bound to '?') can be used to search the visual his- tory. In command mode '/' or '?' followed by a shell pat- tern, searches the visual history for the pattern. The pat- tern can be terminated either with a _R_e_t_u_r_n, in which case the matched history event is placed in the command buffer or an _E_s_c_a_p_e, in which case the matched history event is exe- cuted. If no history event matches the shell pattern then the bell is rung. 2222.. BBUUIILLTTIINN WWHHIICCHH((11))//WWHHEERREE CCOOMMMMAANNDDSS There is now a builtin version of the _w_h_i_c_h(1) command. The builtin version is just like the original, except that it correctly reports aliases peculiar to this _t_c_s_h, and builtin commands. The only other difference is that the builtin runs somewhere between 10 and 100 times faster. There is also a key-function interface to this command: the _w_h_i_c_h- _c_o_m_m_a_n_d function (normally bound to M-?), can be used any- where on the command line, and will in effect do a 'which' on the command name. Similarly where will report all known instances of the com- mand: aliases, builtins, as well as all references in the path. 2233.. RREESSTTAARRTTIINNGG AA SSTTOOPPPPEEDD EEDDIITTOORR There is another new editor function: run-fg-editor, which is bound to _M-^_Z. When typed, it saves away the current input buffer, and looks for a stopped job with a name equal to the file name part (last element) of either the EDITOR or VISUAL environment variables (if not defined, the default names are "ed" and "vi" respectively). If such a job is found, then it is restarted as if "fg %_n_a_m_e" had been typed. This is used to toggle back and forth between an editor and the shell easily. Some people bind this function to ^_Z so they can do this even more easily. 2244.. SSTTAATTUUSS LLIINNEE SSUUPPPPOORRTT _T_c_s_h has a new builtin called _e_c_h_o_t_c that allows the user to access the terminal capabilities from the command line, similar to the system V _t_p_u_t(1). > echotc home Places the cursor at the home position and Cornell 6.04.00 Last change: 3 July 1993 31 TCSH(1) User Commands TCSH(1) > echotc cm 3 10 places the cursor at column 3 row 10. This command replaces the _e_l and _s_l variables that used contain the escape sequences to begin and end status line changes. The command: > echo $sl this is a test $el is replaced by: > echotc ts 0; echo "this is a test"; echotc fs In addition _e_c_h_o_t_c understands the arguments _b_a_u_d, _l_i_n_e_s, _c_o_l_s, _m_e_t_a, and _t_a_b_s And prints the baud rate, the number of lines and columns, and "yes" or "no" depending if the termi- nal has tabs or a meta key. This can be useful in determin- ing how terse the output of commands will be depending on the baud rate, or setting limits to commands like history to the highest number so that the terminal does not scroll: > set history=`echotc lines` > @ history-- Note: Termcap strings may contain wildcard characters, and echoing them will not work correctly. The suggested method of setting shell variables to terminal capability strings is using double quotes, as in the following example that places the date in the status line: > set tosl="`echotc ts 0`" > set frsl="`echotc fs`" > echo -n "$tosl";date; echo -n "$frsl" _E_c_h_o_t_c accepts two flags. The flag -_v enables verbose mes- sages and the flag -_s ignores any errors and returns the empty string if the capability is not found. 2255.. EEXXEECCUUTTIIOONN OOFF AA CCOOMMMMAANNDD AAFFTTEERR CCHHAANNGGIINNGG TTHHEE CCUURRRREENNTT WWOORRKKIINNGG DDIIRREECCTTOORRYY _T_c_s_h now supports a special alias, _c_w_d_c_m_d, which if set holds a command that will be executed after changing the value of $cwd. For example, if the user is running on an X window system _x_t_e_r_m(_1), and a re-parenting window manager that supports title bars such as _t_w_m(_1) _a_n_d _h_a_s _d_o_n_e: > alias cwdcmd 'echo -n "^[]2;${HOST}:$cwd ^G"' then the shell will change the title of the running _x_t_e_r_m(_1) to be the name of the host, a colon, and the full current working directory. A more fancy way to do that is: Cornell 6.04.00 Last change: 3 July 1993 32 TCSH(1) User Commands TCSH(1) > alias cwdcmd 'echo -n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"' This will put the hostname and working directory on the title bar but only the hostname in the icon manager menu. Note that if a user defines _c_w_d_c_m_d to contain a _c_d, _p_u_s_h_d, or _p_o_p_d, command, an infinite loop may result. In this case, it is the author's opinion that said user will get what he deserves. 2266.. NNAATTIIVVEE LLAANNGGUUAAGGEE SSYYSSTTEEMM _T_c_s_h is eight bit clean (if so compiled, see the description of the _v_e_r_s_i_o_n shell variable below), and will thus support character sets needing this capability. The _t_c_s_h support for NLS differs depending on whether it was compiled to use the system's NLS (again, see the _v_e_r_s_i_o_n variable) or not. In either case, the default for character classification (i.e. which characters are printable etc) and sorting is 7- bit ascii, and any setting or unsetting of the LANG or LC_CTYPE environment variables will cause a check for possi- ble changes in these respects. When using the system's NLS, the _s_e_t_l_o_c_a_l_e C library func- tion will be called to determine appropriate character clas- sification and sorting - this function will typically exam- ine the LANG and LC_CTYPE variables for this purpose (refer to the system documentation for further details). Other- wise, NLS will be simulated, by assuming that the ISO 8859-1 character set is used whenever either of the LANG and LC_CTYPE variables are set, regardless of their values. Sorting is not affected for the simulated NLS. In addition, with both real and simulated NLS, all printable characters in the range \200-\377, i.e. those that have M- bindings, are automatically rebound to _s_e_l_f-_i_n_s_e_r_t- _c_o_m_m_a_n_d (the corresponding binding for the escape+ sequence, if any, is left alone). This automatic rebinding is inhibited if the NOREBIND environment variable is set - this may be useful for the simulated NLS, or a primitive real NLS which assumes full ISO 8859-1 (otherwise all M- bindings in the range \240-\377 will effectively be undone in these cases). Explicitly rebinding the relevant keys, using _b_i_n_d_k_e_y, is of course still possible. Unknown characters (i.e. those that are neither printable nor control characters) will be printed using the \nnn for- mat. If the tty is not in 8 bit mode, other 8 bit charac- ters will be printed by converting them to ascii and using standout mode. _T_c_s_h will never change the 7/8 bit mode of the tty, and will track user-initiated settings for this - i.e. it may be necessary for NLS users (or, for that matter, those that want to use a Meta key) to explicitly set the tty Cornell 6.04.00 Last change: 3 July 1993 33 TCSH(1) User Commands TCSH(1) in 8 bit mode through the appropriate _s_t_t_y(1) command in e.g. the .login file. 2277.. AAUUTTOOMMAATTIICC PPRROOCCEESSSS TTIIMMEE RREEPPOORRTTIINNGG Automatic process time reporting is a feature that exists in _c_s_h, but it is usually not documented. In addition _t_c_s_h pro- vides a slightly enriched syntax. Process time reports are controlled via the _t_i_m_e shell variable. The first word of the _t_i_m_e variable indicates the minimum number of CPU seconds the process has to consume before a time report is produced. The optional second word controls the format of the report. The following sequences are available for the format specification: %U The time the process spent in user mode in cpu seconds. %S The time the process spent in kernel mode in cpu seconds. %E The elapsed time in seconds. %P The CPU percentage computed as (%U + %S) / %E. The following sequences are supported only in systems that have the BSD resource limit functions. %W Number of times the process was swapped. %X The average amount in (shared) text space used in Kbytes. %D The average amount in (unshared) data/stack space used in Kbytes. %K The total space used (%X + %D) in Kbytes. %M The maximum memory the process had in use at any time in Kbytes. %F The number of major page faults (page needed to be brought from disk). %R The number of minor page faults. %I The number of input operations. %O The number of output operations. %r The number of socket messages received. %s The number of socket messages sent. %k The number of signals received. %w Number of voluntary context switches (waits). %c Number of involuntary context switches. The default time format is "%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww" for systems that support resource usage reporting and "%Uu %Ss %E %P" for systems that do not. For Sequent's DYNIX/ptx %X, %D, %K, %r and %s are not sup- ported. However, the following additional sequences are available. %Y The number of system calls performed. Cornell 6.04.00 Last change: 3 July 1993 34 TCSH(1) User Commands TCSH(1) %Z The number of pages which are zero-filled on demand. %i The number of times a process' resident set size was increased by the kernel. %d The number of times a process' resident set size was decreased by the kernel. %l The number of read system calls performed. %m The number of write system calls performed. %p the number of reads from raw disk devices. %q the number of writes to raw disk devices. The default time format for Sequent's DYNIX/ptx is "%Uu %Ss $E %P %I+%Oio %Fpf+%Ww". Also note that the CPU percentage can be higher than 100% on multi-processors. 2288.. OOSS//DDEEPPEENNDDEENNTT BBUUIILLTTIINN SSUUPPPPOORRTT _T_R_A_N_S_P_A_R_E_N_T _C_O_M_P_U_T_I_N_G _F_A_C_I_L_I_T_Y On systems that support TCF (aix-ibm370, aix-ps2) the fol- lowing builtins have been added: ggeettssppaatthh Print the current system execution path. sseettssppaatthh LLOOCCAALL||<>||<> ...... Set the current execution path. ggeettxxvveerrss Print the current experimental version prefix. sseettxxvveerrss [[<>]] If the optional string is ommited, any experimen- tal version prefix is removed. Otherwise the experimental version prefix is set to string. mmiiggrraattee [[--<>]] <>||%%<> ...... mmiiggrraattee --<> The first form migrates the process or job to the site specified or the default site determined by the system path. The second form, is equivalent to 'migrate - $$', i.e. migrates the current process to the site specified. Note: migrating _t_c_s_h itself can cause unexpected behavior, since the shell does not like to lose its tty. In addition, jobs will print the site the job is executing. _D_o_m_a_i_n/_O_S _S_u_p_p_o_r_t Cornell 6.04.00 Last change: 3 July 1993 35 TCSH(1) User Commands TCSH(1) iinnlliibb <> ...... Inlib adds shared libraries to the current environment. There is no way to remove them... rroooottnnooddee ////<> Change the name of the current rootnode. From now on, / will resolve to //<_r_o_o_t_n_o_d_e> vveerr [[<>]] [[<>]] Without arguments, print $_S_Y_S_T_Y_P_E; with the <_s_y_s_t_y_p_e> provided, set _S_Y_S_T_Y_P_E to the one provided. Valid sys- types are bsd4.3 and sys5.3. If a <_c_o_m_m_a_n_d> is argument is given, then <_c_o_m_m_a_n_d> is executed under the <_s_y_s_- _t_y_p_e> specified. _M_a_c_h sseettppaatthh <> ...... XXX: What does it do? _M_a_s_s_c_o_m_p/_R_T_U uunniivveerrssee <> ...... Sets the current universe to the specified parameter. _C_o_n_v_e_x/_O_S wwaarrpp [[<>]] ...... Without arguments prints the current value of the universe. With a universe argument it sets the current universe to the value of the argument. 2299.. WWIINNDDOOWW SSIIZZEE TTRRAACCKKIINNGG On systems that support SIGWINCH or SIGWINDOW, _t_c_s_h adapts to window resizing automatically and adjusts the environment variables LINES and COLUMNS if set. Also if the environment variable TERMCAP contains li#, and co# fields, these will be adjusted also to reflect the new window size. 3300.. IINNPPUUTT FFIILLEESS On startup _t_c_s_h will try to source /_e_t_c/_c_s_h._c_s_h_r_c and then /_e_t_c/_c_s_h._l_o_g_i_n if the shell is a login shell. Then it will try to source $_H_O_M_E/._t_c_s_h_r_c and then $_H_O_M_E/._c_s_h_r_c if $_H_O_M_E/._t_c_s_h_r_c is not found. Then it will source $_H_O_M_E/._l_o_g_i_n if the shell is a login shell. On exit _t_c_s_h will source first /_e_t_c/_c_s_h._l_o_g_o_u_t and then $_H_O_M_E/._l_o_g_o_u_t if the shell was a login shell. Note: On _c_o_n_v_e_x_o_s, _s_t_e_l_l_i_x and _I_N_T_E_L the names of the system default files are /_e_t_c/_c_s_h_r_c , /_e_t_c/_l_o_g_i_n and /_e_t_c/_l_o_g_o_u_t Cornell 6.04.00 Last change: 3 July 1993 36 TCSH(1) User Commands TCSH(1) respectively. On the NeXT the names are also different: /_e_t_c/_c_s_h_r_c._s_t_d , /_e_t_c/_l_o_g_i_n._s_t_d and /_e_t_c/_l_o_g_o_u_t._s_t_d Finally on _i_r_i_x, _A/_U_X, _A_M_I_X, and the _c_r_a_y only the file /_e_t_c/_c_s_h_r_c is executed if the shell is a login shell. 3311.. CCOOMMMMAANNDD LLIINNEE OOPPTTIIOONNSS This section describes options that are either undocumented in _c_s_h (*) or present only in _t_c_s_h. (+) -_d Force load of directory stack. (+) -_D_n_a_m_e[=_v_a_l_u_e] Set environment variable name to value. (Domain/OS only) (+) -_F Use fork() instead of vfork() to spawn processes. (Convex/OS only) (+) -_l Make _t_c_s_h behave like a login shell. (+) -_m Allow reading of a .cshrc that does not belong to the effective user. Newer versions of _s_u(_1) can pass that to the shell. (some versions of csh have it) (+*) -_q Make the shell accept SIGQUIT, and behave when it is used under a debugger. Job control is disabled. (*) 3322.. HHIISSTTOORRYY AANNDD VVAARRIIAABBLLEE MMOODDIIFFIIEERR EENNHHAANNCCEEMMEENNTTSS _T_c_s_h accepts more than one variable modifier per variable or history expansion. For example, in _c_s_h(_1) the following com- mand expands to: % set a=/usr/local/foo.bar.baz % echo $a:t:r:e foo.bar.baz:r:e but in _t_c_s_h: > set a=/usr/local/foo.bar.baz > echo $a:t:r:e bar This bug fix changes slightly the input syntax of _c_s_h, caus- ing expressions of the form to have invalid syntax: > set a=/usr/local/foo.bar.baz > echo $a:t:$cwd Unknown variable modifier. Cornell 6.04.00 Last change: 3 July 1993 37 TCSH(1) User Commands TCSH(1) Which is the correct behavior, since after the second colon a variable modifier is expected and `$' is found. Expres- sions like this should be re-written as: > echo ${a:t}:$cwd _T_c_s_h can also use the _l and _u modifiers to change the case of a word. Also _t_c_s_h has an additional : character _a which applies the current modifier multiple times in the same word, in the same way _g applies the modifier once in each word: > set foo=(a:b:c d:e:f) > echo $foo:s/:/ / a b:c d:e:f > echo $foo:gs/:/ / a b:c d e:f > echo $foo:as/:/ / a b c d:e:f > echo $foo:ags/:/ / a b c d e f The _c_s_h expert will notice in the above example another _t_c_s_h enhancement. In _c_s_h the _s modifier does not work for vari- ables. The _a character works correctly with other modifiers, for example: > echo $host tesla.ee.cornell.edu > echo $host:r tesla.ee.cornell > echo $host:ar tesla _N_o_t_e: The _a character causes a modifier to be applied to a word repeatedly until the modifier fails. This can lead to an infinite loop in the current implementation when used with the _s modifier. For example :as/f/ff/ will never ter- minate. This behavior might change in the future. 3333.. PPRROOGGRRAAMMMMAABBLLEE CCOOMMPPLLEETTIIOONN The new _c_o_m_p_l_e_t_e and _u_n_c_o_m_p_l_e_t_e builtins can change the behavior of the listing and file-completion in tcsh. For example some commands like _c_d, _p_u_s_h_d, _p_o_p_d , _m_k_d_i_r(_1), _r_m_d_i_r(_1) accept only directories as arguments. Normally _t_c_s_h when asked to list or complete an argument for those commands takes into account all the files and not only directories. This behavior can be changed by telling _t_c_s_h Cornell 6.04.00 Last change: 3 July 1993 38 TCSH(1) User Commands TCSH(1) that these commands only expect directory arguments: > complete cd 'n/*/d/' The above command tells _t_c_s_h to complete any following word with a directory. The syntax for the _c_o_m_p_l_e_t_e and _u_n_c_o_m_p_l_e_t_e builtins is: _c_o_m_p_l_e_t_e [<_c_o_m_m_a_n_d-_p_a_t_t_e_r_n> [<_c_o_m_p_l_e_t_i_o_n-_a_r_g_u_m_e_n_t>]] _u_n_c_o_m_p_l_e_t_e <_c_o_m_m_a_n_d-_p_a_t_t_e_r_n> Completion arguments are matched in turn from left to right and the first successful match is returned. There are three different completion arguments, modeled after the _s_e_d(_1) substitute command and they are of the form: <>//<>//<>//[[<>||//]] The five commands available are: pp This specifies position-dependent completion. The matching pattern is a numeric range similar to the one used to index shell variables. If the current word is within that range, then the completion action is taken. For example: > complete cd 'p/1/d/' completes only the first argument of 'cd' with a direc- tory. A special useful case of position-dependent com- pletion can be used to disambiguate command completion: > set autolist > co[TAB] complete compress > complete -co* 'p/0/(complete)/' > co[TAB] > complete _ The above command tells the completion mechanism to match any word on position 0, that matches the pattern _c_o* . If a match is found, the word is replaced with the literal pattern "complete". The leading '-' in the pattern signifies that this completion is to be used only with ambiguous commands. nn,,NN This command specifies next-word completions. The matching pattern in this case is a shell pattern that must match the previous word on the command line (_n), or the word before that (_N). For example: Cornell 6.04.00 Last change: 3 July 1993 39 TCSH(1) User Commands TCSH(1) > complete find 'n/-user/u/' Here the argument of the find command which follows the -user argument is completed from the list of users. cc,,CC The last two completion commands complete the current word. The matching pattern in this case must match the prefix of the current word. For example: > complete cc 'c/-I/d/' completes the the word containing -I from the list of directories. While ``cc'' discards the matched prefix, ``CC'' keeps it and applies the completion using it. So far the _d, _u, (_w_o_r_d) completion actions have been men- tioned. The complete list of completion actions are: C Complete completions S Complete signals a Complete aliases b Complete binding c Complete command d Complete directory e Complete environment variable f Complete file or path component j Complete jobs l Complete limits n Complete nothing p Complete files using the supplied pathname prefix s Complete shell variable t Complete non directory `text' filename v Complete any variable u Complete username x Explain what argument when listing is requested. $var Complete using words from variable (...) Complete using words from list `...` Complete evaluating word list from the output of command. All the above completion actions, except _x, $_v_a_r, (...), and `...` can have an additional shell pattern which must match the files to be completed, separated from the action with a ':'. The '_x' completion action instead expects the explana- tion string specified this way. For example, in the C com- piler, it makes sense to complete only files that the com- piler understands: > complete cc 'n/*/f:*.[cao]/' It is also useful to exclude files from the completion list. Normally _t_c_s_h will expand the following command: Cornell 6.04.00 Last change: 3 July 1993 40 TCSH(1) User Commands TCSH(1) > set fignore=(.o) > ls foo.c foo.o > vi f[TAB] > vi foo.c > rm f[TAB] > rm foo.c A better way to do this is to use the _c_o_m_p_l_e_t_e builtin to protect precious files: > complete rm 'n/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/' > ls foo.c foo.o > vi f[TAB] > vi foo.c > rm f[TAB] > rm foo.o Note that _f_i_g_n_o_r_e is not used when a shell pattern is speci- fied in a completion action. Other commands don't expect files as arguments, so the com- pletion builtin can be used to change the list of items to be completed: > complete man 'n/*/c/' # complete commands > complete which 'n/*/c/' > complete dbx 'p/2/(core)/' 'n/*/c/' > complete alias 'p/1/a/' # complete aliases > complete set 'p/1/s/' # complete variables > complete finger 'p/1/u/' # complete user-names Note that in the _d_b_x example, the positional completion is specified before the next word completion. Since completions are evaluated from left to right, if the next word comple- tion was specified first it would always match and the posi- tional completion would never be executed. This is a common mistake when defining a completion. In some cases the list needs to be customized or dynamically generated. > set hostnames=(prep.ai.mit.edu tesla.ee.cornell.edu) > complete rlogin 'p/1/$hostnames/' Consider a complex example using matching patterns to direct argument dependent completions: > complete find 'n/-fstype/(nfs 4.2)/' 'n/-name/f/' \ 'n/-type/(c b d f p l s)/' 'n/-user/u/' 'n/-exec/c/' \ 'n/-ok/c/' 'n/-cpio/f/' 'n/-ncpio/f/' 'n/-newer/f/' \ 'c/-/(fstype name perm prune type user nouser \ Cornell 6.04.00 Last change: 3 July 1993 41 TCSH(1) User Commands TCSH(1) group nogroup size inum atime mtime ctime exec \ ok print ls cpio ncpio newer xdev depth)/' \ 'n/*/d/' The words following the -_f_s_t_y_p_e and -_t_y_p_e arguments is to be completed from the lists specified. The word following the -_n_a_m_e, -_c_p_i_o, -_n_c_p_i_o, and -_n_e_w_e_r arguments are to be com- pleted using files or directory components. The word fol- lowing the -_u_s_e_r argument will be completed from the list of user names of the system, and the word following the -_e_x_e_c and -_o_k arguments will be completed from the list of com- mands. The fourth line specifies how the current word will be completed if it starts with a -. Note that the pattern of this completion argument refers to the _c_u_r_r_e_n_t word and not to the _p_r_e_v_i_o_u_s word, like before. Finally the last line in the find completion matches all the remaining cases and requires a directory component. > cd /usr > set autolist > find [TAB] bin/ include/ lib/ local/ man/ src/ > find -[TAB] atime depth group mtime newer ok prune user cpio exec inum name nogroup perm size xdev ctime fstype ls ncpio nouser print type > find -u[TAB] > find -user [TAB] christos root > find -user c[TAB] > find -user christos Another useful feature is to override the default suffix rules. For example: > complete rcp 'c/*:/f/' 'p/1/$hosts/:' > complete finger 'c/*@/$hosts/' 'p/1/u/@' completes from $hosts appending a `:' and then begins expanding files, where finger expands user-names appending an `@' and then begins expanding hosts. Another exotic example that makes use of dynamic command execution is: > complete talk p/1/'`users | tr " " "\012" | uniq`'/ \ n/\*/\`who\ \|\ grep\ \$:1\ \|\ awk\ \'\{\ print\ \$2\ \}\'\`/ Here we want to get a list of the active users, as an argu- ment to talk, then we want to pick the user, and find his tty... Note that there is no quoting performed inside the Cornell 6.04.00 Last change: 3 July 1993 42 TCSH(1) User Commands TCSH(1) completion patterns. If the character '/' is used in the matched pattern, then another punctuation character can be used as a separator. The only pattern recognized is $$::<> which is substituted by the n'th word of the current line. Notes: 1. The completion command-patterns are overridden when the internal parsing mechanism determines that the comple- tion is a login name, or a variable. 2. This is an experimental feature and the syntax/behavior may change in future versions. FFYYII This shell uses CBREAK mode but takes typed-ahead characters anyway. You can still use _s_t_t_y(1) to set some of the modes of your terminal (but not bindings). This shell will restore your tty to a sane mode if it appears to return from some command in raw, CBREAK, or noe- cho mode. This behavior can be changed using _s_e_t_t_y. EENNHHAANNCCEEDD FFIILLEE IINNQQUUIIRRIIEESS _C_s_h allows the following file inquiries that can appear as primitive operands in expressions. They are for the form -_l <_f_i_l_e_n_a_m_e>. r read access w write access x execute access e existence o ownership z zero size f plain file d directory l symbolic link * _T_c_s_h defines also the following: c character special file b block special file p named pipe (fifo) * u set-user-ID bit is set g set-group-ID bit is set k sticky bit is set s the file is non-zero size. t open file descriptor for terminal device [a number] S socket special file * Cornell 6.04.00 Last change: 3 July 1993 43 TCSH(1) User Commands TCSH(1) X executable in the path or shell builtin Notes: On systems without the file types indicated by * the file inquiry operands return false. If tcsh is compiled for POSIX [i.e. POSIX is defined in config.h], then the result of test is based on the permis- sion bits of the file and not on the result of the _a_c_c_e_s_s(_2) system call. I.e. if you mount a file system read-only, and test -w a file, then the test will succeed in POSIX mode, if the permissions of the file allow writing. RREEAADDOONNLLYY VVAARRIIAABBLLEESS _T_c_s_h allows defining variables as readonly. Such variables cannot be cleared or modified. E.g. > set -r x=(1 2 3) > unset x unset: $x is read-only. > set x=5 set: $x is read-only. > set -r x=5 set: $x is read-only. > echo $x 1 2 3 In addition 'set -r' will list only the readonly variables. EENNVVIIRROONNMMEENNTT HPATH -- path to look for command documentation LANG -- used to give preferred character environment (see NLS) LC_CTYPE -- used to change only ctype character handling (see NLS) NOREBIND -- inhibits rebinding of printable characters to self-insert-command PATH -- path to look for command execution SHLVL -- current shell level nesting TERM -- used to tell how to handle the terminal LINES -- Number of lines in terminal (see WINDOW SIZE) COLUMNS -- Number of columns in terminal (see WINDOW SIZE) TERMCAP -- Terminal capability string (see WINDOW SIZE) SYSTYPE -- The current system type (Domain OS only) NNEEWW SSHHEELLLL VVAARRIIAABBLLEESS aaddddssuuffffiixx add a / for directories, and a space for normal files when complete matches a name exactly. If unset don't add anything extra. aammppmm show all times in 12 hour, AM/PM format. Cornell 6.04.00 Last change: 3 July 1993 44 TCSH(1) User Commands TCSH(1) aauuttooccoorrrreecctt Correct mis-spelled path components automatically before attempting completion. aauuttooeexxppaanndd invoke the expand-history function automatically on completion. aauuttoolliisstt list possibilities on an ambiguous completion. aauuttoollooggoouutt The first word indicates number of minutes of inactivity before automatic logout. The optional second word indicates the number of minutes of inactivity after which the user will be prompted for his login password to enter a command. bbaacckkssllaasshh__qquuoottee makes the backslash quote \, ', and ". This option changes the parsing mechanism for tcsh, and it can cause syntax errors in _c_s_h scripts. ccoorrrreecctt automatically try to correct the spelling of com- mands. Must be set to either correct=cmd, only command name will be corrected, or correct=all, the whole line will be corrected. ddeexxttrraacctt extract a directory on pushd rather than rotating. ddiirrssffiillee If set, it contains the full path-name where a directory stack file is read/written. It defaults to $home/.cshdirs. This file is executed last after .cshrc and .login to restore the directory stack. ddiirrssttaacckk If set, it contains an array of all the direc- tories on the directory stack. $dirstack[1] is the current working directory, $dirstack[2] the first directory on the stack etc. Setting $dirstack resets all the stack entries, but the current working directory which is preserved. dduunniiqquuee Push only directories that are not already in the directory stack. eecchhoo__ssttyyllee Set the style of the builtin echo. Valid values are: _b_s_d : if the first argument is -n, don't echo a newline. Cornell 6.04.00 Last change: 3 July 1993 45 TCSH(1) User Commands TCSH(1) _s_y_s_v : recognize \ escape sequences in echo strings. _b_o_t_h : recognize both -n and \ escape sequences. _n_o_n_e : the purist's echo. eeddiitt use the input editor, set by default. ffiiggnnoorree list of file name suffixes (e.g. .o, ~) to ignore during complete. ggiidd the current real group id. hhiissttlliitt If set, history lines in the editor will be shown with its literal value (that is the line as it was input) instead of the shells lexical version. The current history line can be toggled between literal and lexical with the toggle-literal- history function. History lines saved at shell exit are also saved as this variable indicates. hhiissttffiillee If set, it contains the full path-name where a history file is read/written. It defaults to $home/.history. This is useful when sharing the same home directory in different machines, or if one wants to save all the histories in the tty sessions. It is usually set in .cshrc for interac- tive shells, because history is sourced between .cshrc and .login so that it is available from .login. hhiissttoorryy The first word of the history variable indicates the number of history events to be saved. The optional second word indicates the format history is printed (Defaults to "%h\t%T\t%R\n"). iinnppuuttmmooddee Can be set to either _i_n_s_e_r_t or _o_v_e_r_w_r_i_t_e to con- trol the line editing behavior, as described in section 1. lliissttjjoobbss list all jobs when suspending. set listjobs=long, produces long format. lliissttlliinnkkss Resolve symbolic links when listing files so that the correct filetype is shown. lliissttmmaaxx maximum number of items to list without asking first. lliissttmmaaxxrroowwss maximum number of rows of items to list without asking first. (local AFEB hack at University of Cornell 6.04.00 Last change: 3 July 1993 46 TCSH(1) User Commands TCSH(1) Twente) mmaattcchhbbeeeepp control beeping on completion. With matchbeep=nomatch, completion only beeps when there is no match, with matchbeep=ambiguous, beeps also when there are multiple matches, with matchbeep=notunique, beeps when there is one exact and other longer matches, with matchbeep=never, it never beeps. nnoobbeeeepp Disables beeping completely. nnookkaannjjii If kanji support is enable, setting this variable disables it, so that the meta key can be used. nnoossttaatt An list of directories that should not be stat'ed during a completion operation. Some directories e.g. "/afs", can take too much time to complete a _s_t_a_t(_2) operation, making them prime candidates for membership in this list. ooiidd The organization id number (Domain OS only). pprriinntteexxiittvvaalluuee if an interactive program exits non-zero, print the exit value. pprroommpptt the string to prompt with. pprroommpptt22 the string to prompt for while and for loops with. pprroommpptt33 the string to prompt with when automatic spelling correction has corrected a command line. ppuusshhddttoohhoommee make pushd with no args do a "pushd ~" (like cd does). ppuusshhddssiilleenntt do not print the dir stack on every pushd and popd. rreecceexxaacctt recognize exact matches even if they are ambigu- ous. rreeccooggnniizzee__oonnllyy__eexxeeccuuttaabblleess list choices of commands only displays files in the path that are executable (slow). rrmmssttaarr Prompt the user before execution of `rm *'. ssaavveeddiirrss Before exiting, create a file called Cornell 6.04.00 Last change: 3 July 1993 47 TCSH(1) User Commands TCSH(1) $HOME/.cshdirs that contains the necessary com- mands to restore the current directory stack. _T_c_s_h will read this file during startup and restore the directory stack. ssaavveehhiisstt number of history items to save between login ses- sions. If it is just set, the number of items is taken from $history. sshhllvvll Integer value indicating the number of nested shells. On login shells the level is reset to 1. sshhoowwddoottss show hidden files in list and complete operations. If it is set to -A, then "." and ".." are not displayed, similarly to the BSD ls -A. ssyymmlliinnkkss can be set to: _c_h_a_s_e , in order to resolve the full path names, _i_g_n_o_r_e , in order to use $cwd to resolve relative directory references for buil- tins. _e_x_p_a_n_d , in order to use $cwd and rewrite the arguments for commands. ttccsshh Contains the current version of the shell as R.VV.PP. The _R indicates the major release number, the _V_V the current version and the _P_P the patchlevel. tteerrmm the terminal type; see above. ttppeerriioodd periodic command wait period (in minutes). ttttyy The name of the tty, or empty if not attached to one. uuiidd the current real user ID. vveerrssiioonn the version ID stamp for this _t_c_s_h. It contains, the origin of this version of _t_c_s_h, the date this version was released and a string containing a comma separated list of the compile time options enabled: 8b 7b If tcsh was compiled to be eight bit clean or not. The default is 8b. nls Set if tcsh uses the system's NLS, should be the default for systems that have NLS. lf Set if tcsh should execute .login before .cshrc on login shells. Default is not set. dl Set if tcsh should put . last on the path for security. Default is set. vi Set if tcsh's default editor is vi. Default is unset (emacs) dtr Set if tcsh should drop dtr on login shells Cornell 6.04.00 Last change: 3 July 1993 48 TCSH(1) User Commands TCSH(1) when exiting. Default is unset. bye Set if tcsh should accept bye in addition to logout, and rename log to watchlog. Default is unset. al Set if tcsh should determine if autologout should be enabled. The default is set. kan Set if tcsh is compiled for Kanji. (ignore the iso character set.) Default is unset. sm Set if tcsh was compiled to use the system's malloc. hb Set if tcsh is emulating #! in shell script execution In addition to the above strings, administrators can enter local strings to indicate differences in the local version. vviissiibblleebbeellll use the visible bell (screen flash) rather than audible bell. wwaattcchh list of events to watch. wwhhoo format string for the printouts generated when _w_a_t_c_h is set. wwoorrddcchhaarrss list of non-alphanumeric characters considered part of a word for the purpose of the forward- word, backward-word etc functions -- defaults to "*?_-.[]~=". NNEEWW SSPPEECCIIAALL AALLIIAASSEESS _c_w_d_c_m_d the command is run after every change of working directory. _p_e_r_i_o_d_i_c the command to be run every _t_p_e_r_i_o_d minutes. _p_r_e_c_m_d the command to be run prior to printing each prompt. _b_e_e_p_c_m_d the command to be run every time _t_c_s_h wants to echo the terminal bell. SSEEEE AALLSSOO xterm(1), twm(1), csh(1), chsh(1), termcap(5), termio(7) BBUUGGSS The screen update for lines longer than the screen width is very poor if the terminal cannot move the cursor up (i.e. terminal type "dumb"). I am certain that there are bugs. Bugs (preferably with fixes) should be sent to Christos Zoulas Cornell 6.04.00 Last change: 3 July 1993 49 TCSH(1) User Commands TCSH(1) (christos@ee.cornell.edu). VVEERRSSIIOONN This man page documents tcsh 6.04.00 (Cornell) 93/07/03. AAUUTTHHOORRSS Ken Greer, HP Labs, 1981 Wrote the command completion. Mike Ellis, Fairchild, 1983 Added command name recognition/completion. Paul Placeway, Ohio State CIS dept., 1983 Added the command line editor. Rayan Zachariassen, University of Toronto, 1984 Added the builtin _w_h_i_c_h feature to the editor, and the code for _l_s-_F . Also numerous bug fixes, modifications, and per- formance enhancements. Chris Kingsley, Caltech Wrote the fast storage allocator routines (nmalloc.c). Karl Kleinpaste, CCI 1983-4 Added special aliases, directory stack extraction stuff, login/logout watch, and scheduled events. Also came up with the idea of the new prompt format. Paul Placeway, Ohio State CIS dept., 1987 Re-wrote the editor, cleaned up other code, and added the prompt routines, added to the syntax for file name expres- sions, and sped up the shell some. Chris Grevstad, TRW, 1987 Ported the 4.3 csh sources to tcsh. Christos S. Zoulas, Cornell U. EE dept., 1987-92 ported tcsh to HPUX, and System V rel. 2 and 3 and wrote a SysV version of getwd.c. Added SHORT_STRINGS support. New version of sh.glob.c. James J Dempsey, BBN, 1988, and Paul Placeway, OSU, 1988 Re-ported tcsh to A/UX. BBUUGGFFIIXXEESS AANNDD EENNHHAANNCCEEMMEENNTTSS Tim P. Starrin, National Aeronautics and Space Administra- tion, Langley Research Center Operations, 1993 Readonly variable additions. Jeff Fink, 1992 Added complete-word-fwd, and complete-word-back editor Cornell 6.04.00 Last change: 3 July 1993 50 TCSH(1) User Commands TCSH(1) functions Harry C. Pulley, 1992 Coherent port Andy Phillips, Mullard Space Science Lab U.K., 1992 VMS-POSIX port. Beto Appleton, IBM Corp., 1992 Walking process group fixes, lots of misc csh bug fixes, POSIX file tests, POSIX SIGHUP. Scott Bolte, Cray Computer Corp., 1992 CSOS port. Kaveh R. Ghazi, Rutgers University, 1992 Fixes and Ports for Tek, m88k, Titan, Masscomp. Mark Linderman, Cornell University, 1992 OS/2 Port, (he does not run OS/2 anymore so he cannot help you porting tcsh on it) Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992 Linux port. Scott Krotz, Motorola, 1991 Minix port. David Dawes, Sydney U. Australia, Physics dept., 1991 SVR4 job control fixes. (reverse pipeline startup code, and signal fixes). Jose Sousa, Interactive Systems Corp., 1991 Extended vi fixes. Added delete command in vi. Marc Horowitz, MIT, 1991 Ansification fixes, new exec hashing code, imake fixes, where builtin. Eric Schnoebelen, Convex, 1990 Convex support, lots of csh bug fixes, save and restore of directory stack. Jaap Vermeulen, Sequent, 1990-91 Vi mode fixes, expand-line, window change fixes, ported to symmetry machines. Ron Flax, Apple, 1990 Ported again to A/UX 2.0 Dan Oscarsson, LTH Sweden, 1990 NLS support and simulated for non NLS sites. Correction of Cornell 6.04.00 Last change: 3 July 1993 51 TCSH(1) User Commands TCSH(1) file names also handles the case when the / is replaced by another character. The editor does not switch into cbreak mode unless needed. The shell will not use character attri- butes when output is not to a tty. Johan Widen, SICS Sweden, 1990 Shell level variable, mach support, correct-line, 8-bit printing. Matt Day, Sanyo Icon, 1990 Added POSIX termio support; Fixed limit stuff for SysV. Hans J. Albertsson (Sun Sweden) Added the ampm variable handling, DING!, and the settc and telltc builtins. Michael Bloom Fixed some of the interrupt handling. Michael Fine, Digital Equipment Corp added the extended key support. Daniel Long, NNSC, 1988 Added the wordchars variable. George Hartzell, MCD Biology, University of Colorado- Boulder, 1988 Fixed the always resetting to DEL bug. Patrick Wolfe, Kuck and Associates, Inc., 1988 Cleaned up VI mode and wrote the new editor description (in section 1). Jak Kirman, 1988 Fixed the SunOS 4 giant stack allocation bug. Bruce Robertson, Tektronix, 1989 Fixed setting erase and kill (again). David C Lawrence, Rensselaer Polytechnic Institute, 1989 Added "autolist" variable and code to list possibilities on ambiguous completion. Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991. Modified "autolist" variable and code to give options on beeping behavior. Modified the history search to search for the whole string from the beginning of the line to the cur- sor. Alec Wolman, DEC, 1989 Added code to allow newlines in the prompt. Cornell 6.04.00 Last change: 3 July 1993 52 TCSH(1) User Commands TCSH(1) Matt Landau, BBN, 1989 Fixed YP bugs on Suns, added .tcshrc stuff. Ray Moody, Purdue Physics, 1989 Added the code to do magic spacebar history expansion. Mordechai ????, Intel, 1989 Re-arranged the printprompt() routine to use a switch(*cp) (rather than a bunch of ifs), and added a few things to it. Josh Siegel, dspo.gov, 1989 Fixed "fg-editor" and added the status line shell variables "sl" and "el". Karl Berry, UMB, 1989 Fixed a bug involving environ (in sh.func.c) on NeXT comput- ers. Michael Greim, Universitaet des Saarlandes, Saarbruecken, W-Germany, Fixed the nested backquote bug (yes, you can do it; think about aliases) in 4.2 csh. This fix was posted to comp.bugs.4bsd. Kazuhiro Honda, Department of Computer Science, Keio Univer- sity, 1989 Added the code for automatic spelling correction, the prompt3 stuff (the autocorrect prompt), and HOSTTYPE symbols for the Sony NEWS. Paul Placeway, BBN, 1990 Fixed character redrawing code insert bugs, and made redraw- ing code handle multiple character movement, insert, and delete (if it exists). Fixed setting of SHELL. Per Hedeland, Ellemtel, Sweden, 1990 Various bugfixes and improvements, e.g. in history expan- sion, autolist, added autoexpand, updated the manual. TTHHAANNKKSS TTOO A special thanks to: Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig, Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky, and all the other people at Ohio State for suggestions and encourage- ment. Also, thanks to all the people on the net for putting up with, reporting bugs in, and suggesting new additions to the old tcsh editor. Cornell 6.04.00 Last change: 3 July 1993 53 No manual entry for wget. Misc. Reference Manual Pages LYNX(l) NAME lynx - a general purpose distributed information browser for the World Wide Web SYNOPSIS Lynx [options] [path or URL] use "lynx -help" to display a complete list of current options. DESCRIPTION _L_y_n_x is a fully-featured World Wide Web (WWW) client for users running cursor-addressable, character-cell display devices (e.g., vt100 terminals, vt100 emulators running on PCs or Macs, or any other "curses-oriented" display). It will display hypertext markup language (HTML) documents con- taining links to files residing on the local system, as well as files residing on remote systems running Gopher, HTTP, FTP, WAIS, and NNTP servers. Current versions of _L_y_n_x run on Unix and VMS. _L_y_n_x can be used to access information on the World Wide Web, or to build information systems intended primarily for local access. For example, _L_y_n_x has been used to build several Campus Wide Information Systems (CWIS). In addi- tion, _L_y_n_x can be used to build systems isolated within a single LAN. OPTIONS At start up, _L_y_n_x will load any local file or remote URL specified at the command line. For help with URLs, press "?" or "h" while running _L_y_n_x. Then follow the link titled, "Help on URLs." - If the only argument is '-', then Lynx expects to receive the arguments from stdin. This is to allow for the potentially very long command line that can be associated with the -get_data or -post_data arguments (see below). -anonymous used to specify the anonymous account. -auth=_I_D:_P_A_S_S_W_D set authorization ID and password for protected docu- ments at startup. -base prepend a request URL comment and BASE tag to text/html outputs for -source or -mime_header dumps. -book SunOS 5.8 Last change: Local 1 Misc. Reference Manual Pages LYNX(l) use the bookmark page as the startfile. The default or command line startfile is still set for the Main screen command, and will be used if the bookmark page is una- vailable or blank. -buried_news toggles scanning of news articles for buried refer- ences, and converts them to news links. Not recom- mended because email addresses enclosed in angle brack- ets will be converted to false news links, and uuen- coded messages can be trashed. -cache=_N_U_M_B_E_R set the NUMBER of documents cached in memory. The default is 10. -case enable case-sensitive string searching. -cfg=_F_I_L_E_N_A_M_E specifies a Lynx configuration file other than the default lynx.cfg. -child exit on left-arrow in startfile, and disable save to disk. -cookies toggles handling of Set-Cookie headers. -crawl with -traversal, output each page to a file. with -dump, format output as with -traversal, but to stdout. -display=_D_I_S_P_L_A_Y set the display variable for X rexec-ed programs. -dump dumps the formatted output of the default document or one specified on the command line to standard out. This can be used in the following way: lynx -dump http://www.crl.com/~subir/lynx.html. -editor=_E_D_I_T_O_R enable edit mode using the specified EDITOR. (vi, ed, emacs, etc.) -emacskeys enable emacs-like key movement. -enable_scrollback toggles compatibility with comm programs' scrollback 2 Last change: Local SunOS 5.8 Misc. Reference Manual Pages LYNX(l) keys (may be incompatible with some curses packages). -error_file=_F_I_L_E define a file where Lynx will report HTTP access codes. -fileversions include all versions of files in local VMS directory listings. -force_html forces the first document to be interpreted as HTML. -ftp disable ftp access. -get_data send form data from stdin using GET method and dump results. -head send a HEAD request for the mime headers. -help print this Lynx command syntax usage message. -historical toggles use of '>' or '-->' as a terminator for com- ments. -homepage=_U_R_L set homepage separate from start page. -image_links toggles inclusion of links for all images. -index=_U_R_L set the default index file to the specified URL. -link=UMBER starting count for lnk#.dat files produced by -crawl. -localhost disable URLs that point to remote hosts. -locexec enable local program execution from local files only (if Lynx was compiled with local execution enabled). -mime_header prints the MIME header of a fetched document along with its source. -minimal SunOS 5.8 Last change: Local 3 Misc. Reference Manual Pages LYNX(l) toggles minimal versus valid comment parsing. -newschunksize=UMBER number of articles in chunked news listings. -newsmaxchunk=UMBER maximum news articles in listings before chunking. -nobrowse disable directory browsing. -noexec disable local program execution. (DEFAULT) -nofilereferer disable transmissions of Referer headers for file URLs. -nofrom disable transmissions of From headers. -nolist disable the link list feature in dumps. -nolog disable mailing of error messages to document owners. -nopause disable forced pauses for statusline messages. -noprint disable print functions. -noredir prevents automatic redirection and prints a message with a link to the new URL. -noreferer disable transmissions of Referer headers. -nosocks disable SOCKS proxy usage by a SOCKSified Lynx. -nostatus disable the retrieval status messages. -number_links force numbering of links. -popup toggles handling of single-choice SELECT options via popup windows or as lists of radio buttons. 4 Last change: Local SunOS 5.8 Misc. Reference Manual Pages LYNX(l) -post_data send form data from stdin using POST method and dump results. -print enable print functions. (default) -pseudo_inlines toggles pseudo-ALTs for inlines with no ALT string. -raw toggles default setting of 8-bit character translations or CJK mode for the startup character set. -realm restricts access to URLs in the starting realm. -reload flushes the cache on a proxy server (only the first document affected). -restrictions=[_o_p_t_i_o_n][,_o_p_t_i_o_n][,_o_p_t_i_o_n]... allows a list of services to be disabled selectively. The following list is printed if no options are speci- fied. _a_l_l - restricts all options. _b_o_o_k_m_a_r_k - disallow changing the location of the book- mark file. _b_o_o_k_m_a_r_k__e_x_e_c - disallow execution links via the book- mark file. _c_h_a_n_g_e__e_x_e_c__p_e_r_m_s - disallow changing the eXecute per- mission on files (but still allow it for directories) when local file management is enabled. _d_e_f_a_u_l_t - same as command line option -anonymous. Dis- ables default services for anonymous users. Currently set to all restricted except for: inside_telnet, outside_telnet, inside_news, inside_ftp, outside_ftp, inside_rlogin, outside_rlogin, jump, mail and goto. Defaults are setable within userdefs.h. _d_i_r_e_d__s_u_p_p_o_r_t - disallow local file management. _d_i_s_k__s_a_v_e - disallow saving binary files to disk in the download menu. _d_o_w_n_l_o_a_d - disallow downloaders in the download menu. _e_d_i_t_o_r - disallow editing. SunOS 5.8 Last change: Local 5 Misc. Reference Manual Pages LYNX(l) _e_x_e_c - disable execution scripts. _e_x_e_c__f_r_o_z_e_n - disallow the user from changing the local execution option. _f_i_l_e__u_r_l - disallow using G)oto, served links or book- marks for file: URLs. _g_o_t_o - disable the 'g' (goto) command. _i_n_s_i_d_e__f_t_p - disallow ftps for people coming from inside your domain (utmp required for selectivity). _i_n_s_i_d_e__n_e_w_s - disallow USENET news posting for people coming from inside your domain (utmp required for selectivity). _i_n_s_i_d_e__r_l_o_g_i_n - disallow rlogins for people coming from inside your domain (utmp required for selectivity). _i_n_s_i_d_e__t_e_l_n_e_t - disallow telnets for people coming from inside your domain (utmp required for selectivity). _j_u_m_p - disable the 'j' (jump) command. _m_u_l_t_i_b_o_o_k - disallow multiple bookmarks. _m_a_i_l - disallow mail. _n_e_w_s__p_o_s_t - disallow USENET News posting. _o_p_t_i_o_n_s__s_a_v_e - disallow saving options in .lynxrc. _o_u_t_s_i_d_e__f_t_p - disallow ftps for people coming from out- side your domain (utmp required for selectivity). _o_u_t_s_i_d_e__n_e_w_s - disallow USENET news posting for people coming from outside your domain (utmp required for selectivity). _o_u_t_s_i_d_e__r_l_o_g_i_n - disallow rlogins for people coming from outside your domain (utmp required for selec- tivity). _o_u_t_s_i_d_e__t_e_l_n_e_t - disallow telnets for people coming from outside your domain (utmp required for selec- tivity). _p_r_i_n_t - disallow most print options. _s_h_e_l_l - disallow shell escapes and lynxexec or lynxprog G)oto's. 6 Last change: Local SunOS 5.8 Misc. Reference Manual Pages LYNX(l) _s_u_s_p_e_n_d - disallow Unix Control-Z suspends with escape to shell. _t_e_l_n_e_t__p_o_r_t - disallow specifying a port in telnet G)oto's. _u_s_e_r_a_g_e_n_t - disallow modifications of the User-Agent header. -resubmit_posts toggles forced resubmissions (no-cache) of forms with method POST when the documents they returned are sought with the PREV_DOC command or from the History List. -rlogin disable recognition of rlogin commands. -selective require .www_browsable files to browse directories. -show_cursor If enabled the cursor will not be hidden in the right hand corner but will instead be positioned at the start of the currently selected link. Show cursor is the default for systems without FANCY_CURSES capabilities. The default configuration can be changed in userdefs.h or lynx.cfg. The command line switch toggles the default. -source works the same as dump but outputs HTML source instead of formatted text. -startfile_ok allow non-http startfile and homepage with -validate. -telnet disable recognition of telnet commands. -term=_T_E_R_M tell Lynx what terminal type to assume its talking to. (This may be useful for remote execution, when, for example, Lynx connects to a remote TCP/IP port that starts a script that, in turn, starts another Lynx pro- cess.) -trace turns on WWW trace mode. -traversal traverse all http links derived from startfile. When SunOS 5.8 Last change: Local 7 Misc. Reference Manual Pages LYNX(l) used with -crawl, each link that begins with the same string as startfile is output to a file, intended for indexing. See CRAWL.announce for more information. -underscore toggles use of _underline_ format in dumps. -validate accept only http URLs (for validation). Complete secu- rity restrictions also are implemented. -version print version information. -vikeys enable vi-like key movement. COMMANDS o Use Up arrow and Down arrow to scroll through hypertext links. o Right arrow or Return will follow a highlighted hypertext link. o Left Arrow will retreat from a link. o Type "h" or "?" for online help and descriptions of key- stroke commands. o Type "k" for a complete list of the current key-stroke command mappings. NOTES This is the Lynx v2.7 Release for Unix/VMS If you wish to contribute to the further development of _L_y_n_x, subscribe to our mailing list. Send email to with "subscribe lynx-dev" as the only line in the body of your message. Send bug reports, comments, suggestions to after subscribing. Unsubscribe by sending email to with "unsubscribe lynx-dev" as the only line in the body of your message. Do not send the unsubscribe message to the lynx- dev list, itself. ACKNOWLEDGMENTS Lynx has incorporated code from a variety of sources along the way. The earliest versions of Lynx included code from Earl Fogel of Computing Services at the University of Saskatchewan, who implemented HYPERREZ in the Unix environ- ment. HYPERREZ was developed by Niel Larson of Think.com and served as the model for the early versions of Lynx. Those versions also incorporated libraries from the Unix 8 Last change: Local SunOS 5.8 Misc. Reference Manual Pages LYNX(l) Gopher clients developed at the University of Minnesota, and the later versions of Lynx rely on the WWW client library code developed by Tim Berners-Lee and the WWW community. Also a special thanks to Foteos Macrides who ported much of Lynx to VMS and did or organized most of its development since the departures of Lou Montulli and Garrett Blythe from the University of Kansas in the summer of 1994 through the current release of v2.7, and to everyone on the net who has contributed to Lynx's development either directly (through patches, comments or bug reports) or indirectly (through inspiration and development of other systems). AUTHORS Lou Montulli, Garrett Blythe, Craig Lavender, Michael Grobe, Charles Rezac Academic Computing Services University of Kansas Lawrence, Kansas 66047 Foteos Macrides Worcester Foundation for Biomedical Research Shrewsbury, Massachusetts 01545 SunOS 5.8 Last change: Local 9 User Commands csh(1) NAME csh - shell command interpreter with a C-like syntax SYNOPSIS csh [ -bcefinstvVxX ] [ _a_r_g_u_m_e_n_t ... ] DESCRIPTION csh, the C shell, is a command interpreter with a syntax reminiscent of the C language. It provides a number of con- venient features for interactive use that are not available with the Bourne shell, including filename completion, com- mand aliasing, history substitution, job control, and a number of built-in commands. As with the Bourne 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(1), the shell runs as a login shell. If the shell is a login shell, this is the sequence of invo- cations: First, commands in /etc/.login are executed. Next, commands from the .cshrc file your home directory are exe- cuted. Then 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. (For an explanation of file interpreters, see below "Command Execution" and exec(2).) 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 privileged user). The shell then repeatedly performs the following actions: a line of command input is read and broken into _w_o_r_d_s. 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 exe- cute a command supplied as an _a_r_g_u_m_e_n_t on its command line, or interpret commands from a file, also known as a script. SunOS 5.8 Last change: 23 May 1997 1 User Commands csh(1) OPTIONS The following options are supported: -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 set- user-ID or set-group-ID scripts unless this option is present. -c Execute the first _a_r_g_u_m_e_n_t (which must be present). Remaining arguments are placed in argv, the argument- list variable, and passed directly to csh. -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 `\' (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. -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 nonop- tion _a_r_g_u_m_e_n_t is taken to be the name of a command or script. It is passed as argument zero, and subsequent argu- ments are added to the argument list for that command or script. SunOS 5.8 Last change: 23 May 1997 2 User Commands csh(1) USAGE 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 (usu- ally 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 suf- fixes in the variable fignore. If, however, the only possi- ble 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 metacharacters can be made part of other words, and their special meaning can be suppressed by preceding them with a `\' (backslash). A new- line 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 `\' (backslash) gives a true newline character. Additional functions of each type of quote are described, below, under Variable Substitution, Command Sub- stitution, 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 SunOS 5.8 Last change: 23 May 1997 3 User Commands csh(1) A _s_i_m_p_l_e _c_o_m_m_a_n_d is composed of a sequence of words. The first word (that is not part of an I/O redirection) speci- fies the command to be executed. A simple command, or a set of simple commands separated by | or |& characters, forms a _p_i_p_e_l_i_n_e. With |, the standard output of the preceding com- mand 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 || form conditional sequences in which the execu- tion 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. History Substitution History substitution allows you to use words from previous command lines in the command line you are typing. This sim- plifies spelling corrections and the repetition of compli- cated 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 any- where on the command line; history substitutions 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 sub- stitutions 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 substi- tution repeats the previous command. SunOS 5.8 Last change: 23 May 1997 4 User Commands csh(1) !_n Refer to command line _n. !-n Refer to the current command line minus _n. !_s_t_r Refer to the most recent command starting with _s_t_r. !?_s_t_r? Refer to the most recent command containing _s_t_r. !?_s_t_r? _a_d_d_i_t_i_o_n_a_l Refer to the most recent command containing _s_t_r and append _a_d_d_i_t_i_o_n_a_l to that referenced command. !{_c_o_m_m_a_n_d} _a_d_d_i_t_i_o_n_a_l Refer to the most recent command beginning with _c_o_m_- _m_a_n_d and append _a_d_d_i_t_i_o_n_a_l to that referenced command. ^_p_r_e_v_i_o_u_s__w_o_r_d^_r_e_p_l_a_c_e_m_e_n_t^ Repeat the previous command line replacing the string _p_r_e_v_i_o_u_s__w_o_r_d with the string _r_e_p_l_a_c_e_m_e_n_t. This is equivalent to the history substitution: !:s/_p_r_e_v_i_o_u_s__w_o_r_d/_r_e_p_l_a_c_e_m_e_n_t/. To re-execute a specific previous command AND make such a substitution, say, re-executing command #6, !:6s/_p_r_e_v_i_o_u_s__w_o_r_d/_r_e_p_l_a_c_e_m_e_n_t/. 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 com- mand, 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) ?_s search. SunOS 5.8 Last change: 23 May 1997 5 User Commands csh(1) _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 one of the following modifiers, preceded by a :. h Remove a trailing pathname component, leaving the head. r Remove a trailing suffix of the form `._x_x_x', leaving the basename. e Remove all but the suffix, leaving the Extension. s/_l/_r/ Substitute _r for _l. 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 substi- tutions. x Like q, but break into words at each space character, tab or newline. Unless preceded by a g, the modification is applied only to the first string that matches _l; an error results if no string matches. The left-hand side of substitutions are not regular expres- sions, but character strings. Any character can be used as the delimiter in place of /. A backslash quotes the delim- iter 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 SunOS 5.8 Last change: 23 May 1997 6 User Commands csh(1) 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 ^_l^_r^ This is equivalent to the history substitution: !:s/_l/_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 com- mand is reprocessed with the alias definition replacing its name; the history substitution mechanism is made available as though that command were the previous input line. This allows history 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 con- tain the name of another alias. Nested aliases are expanded before any history substitutions is applied. This is useful in pipelines such as alias lm 'ls -l \!* | more' which when called, pipes the output of ls(1) through more(1). 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. <<_w_o_r_d Read the standard input, up to a line that is identi- cal with _w_o_r_d, and place the resulting lines in a tem- porary file. Unless _w_o_r_d is escaped or quoted, SunOS 5.8 Last change: 23 May 1997 7 User Commands csh(1) variable and command substitutions are performed on these lines. Then, the pipeline is invoked with the temporary file as its standard input. _w_o_r_d is not sub- jected to variable, filename, or command substitution, and each line is compared to it before any substitu- tions 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. Variable Substitution The C shell maintains a set of _v_a_r_i_a_b_l_e_s, each of which is composed of a _n_a_m_e and a _v_a_l_u_e. 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 informa- tion 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 charac- ter, tab or newline. SunOS 5.8 Last change: 23 May 1997 8 User Commands csh(1) 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 command). 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 substitution, except when suppressed by double-quotes, when noglob is set (suppressing filename substitution), 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 subse- quent command or filename substitutions. Except as noted below, it is an error to refer to a variable that is not set. $_v_a_r ${_v_a_r} These are replaced by words from the value of _v_a_r, each separated by a space character. If _v_a_r is an environment variable, its value is returned (but `:' modifiers and the other forms given below are not available). $_v_a_r[_i_n_d_e_x] ${_v_a_r[_i_n_d_e_x]} These select only the indicated words from the value of _v_a_r. Variable substitution is applied to _i_n_d_e_x, which may consist of (or result in) a either single number, two numbers separated by a `-', or an aster- isk. 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[1-]), it defaults to $#_v_a_r (the word count). It is not an error for a range to be empty if the second argument is omitted (or within range). SunOS 5.8 Last change: 23 May 1997 9 User Commands csh(1) $#_n_a_m_e ${#_n_a_m_e} These give the number of words in the variable. $0 This substitutes the name of the file from which com- mand input is being read except for setuid shell scripts. An error occurs if the name is not known. $_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 : modif- iers. $?_v_a_r ${?_v_a_r} Substitutes the string 1 if _v_a_r 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. $$ Substitutes 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. Portions of expres- sions that are not evaluated are not expanded. For non- built-in commands, filename expansion of the command name is done separately from that of the argument list; expansion occurs in a subshell, 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 SunOS 5.8 Last change: 23 May 1997 10 User Commands csh(1) 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 _g_l_o_b_- _b_i_n_g) to an alphabetically sorted list of filenames, as fol- lows: * 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 characters. A range is two characters separated by a dash (-), and includes all the characters in between in the ASCII collating sequence (see ascii(5)). { _s_t_r, _s_t_r, ... } Expand to each string (or filename-matching pattern) in the comma-separated list. Unlike the pattern- matching expressions above, the expansion of this con- struct is not sorted. For instance, {b,a} expands to `b' `a', (not `a' `b'). As special cases, the charac- ters { and }, along with the string {}, are passed undisturbed. ~[_u_s_e_r] Your home directory, as indicated by the value of the variable home, or that of _u_s_e_r, as indicated by the password entry for _u_s_e_r. Only the patterns *, ? and [...] imply pattern matching; an error results if no filename matches a pattern that contains them. The `.' (dot character), when it is the first charac- ter in a filename or pathname component, 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 commands, and are often used to regulate the flow of control for executing commands. Com- ponents of an expression are separated by white space. Null or missing values are considered 0. The result of all expressions is a string, which may represent decimal SunOS 5.8 Last change: 23 May 1997 11 User Commands csh(1) numbers. The following C shell operators are grouped in order of pre- cedence: (...) grouping >~ one's complement ! logical negation * / % multiplication, division, remainder (these are right associative, which can lead to unexpected results; group combinations explicitly with parentheses.) + - addition, subtraction (also right associative) << >> bitwise shift left, bitwise shift right < > <= >= 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 ^ bitwise XOR (exclusive or) | bitwise inclusive OR && logical AND || 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 _f_i_l_e_n_a_m_e Return true, or 1 if the user has read access. Other- wise it returns false, or 0. SunOS 5.8 Last change: 23 May 1997 12 User Commands csh(1) -w _f_i_l_e_n_a_m_e True if the user has write access. -x _f_i_l_e_n_a_m_e True if the user has execute permission (or search permission on a directory). -e _f_i_l_e_n_a_m_e True if _f_i_l_e_n_a_m_e exists. -o _f_i_l_e_n_a_m_e True if the user owns _f_i_l_e_n_a_m_e. -z _f_i_l_e_n_a_m_e True if _f_i_l_e_n_a_m_e is of zero length (empty). -f _f_i_l_e_n_a_m_e True if _f_i_l_e_n_a_m_e is a plain file. -d _f_i_l_e_n_a_m_e True if _f_i_l_e_n_a_m_e is a directory. If _f_i_l_e_n_a_m_e does not exist or is inaccessible, then all inquiries return false. An inquiry as to the success of a command is also available: { _c_o_m_m_a_n_d } If _c_o_m_m_a_n_d runs successfully, the expression evaluates to true, 1. Otherwise, it evaluates to false, 0. (Note: Conversely, _c_o_m_m_a_n_d 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 directly, 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 _l_o_o_p), or to skip input under certain conditions (to _b_r_a_n_c_h). Each occurrence of a foreach, switch, while, if...then and else built-in command must appear as the first word on its own input line. 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, back- ward goto commands will succeed on nonseekable inputs.) SunOS 5.8 Last change: 23 May 1997 13 User Commands csh(1) Command Execution If the command is a C shell built-in command, the shell exe- cutes it directly. Otherwise, the shell searches for a file by that name with execute access. If the command name con- tains 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 direc- tory in the path variable for the command. To speed the search, the shell uses its hash table (see the rehash built-in command) to eliminate directories that have no applicable files. This hashing can be disabled with the -c or -t, options, or the unhash built-in command. 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 permis- sions, the shell forks a new process and passes it, along with its arguments, to the kernel using the execve() system call (see exec(2)). The kernel then attempts to overlay the new process with the desired program. If the file is an exe- cutable binary (in a.out(4) 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. Subsequent 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 argu- ment. If neither of the above conditions holds, the kernel cannot overlay the file and the execve() call fails (see exec(2)); the C shell then attempts to execute the file by spawning a new shell, as follows: +o If the first character of the file is a #, a C shell is invoked. +o Otherwise, a Bourne shell is invoked. Signal Handling The shell normally ignores QUIT signals. Background jobs are immune to signals generated from the keyboard, including hangups (HUP). Other signals have the values that the C shell inherited from its environment. The shell's handling of interrupt and terminate signals within scripts can be SunOS 5.8 Last change: 23 May 1997 14 User Commands csh(1) controlled by the onintr built-in command. 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 _j_o_b with each command sequence to keep track of those commands that are running in the background or have been stopped with TSTP signals (typi- cally CTRL-z). When a command or command sequence (semicolon separated list) is started in the background using the & metacharacter, 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 com- mand. The job most recently stopped (or put into the back- ground if none are stopped) is referred to as the _c_u_r_r_e_n_t job and is indicated with a `+'. The previous job is indi- cated 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-in commands. 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 com- mand line by which it was started; `fg %vi' might bring a stopped vi job to the foreground, for instance. %?_s_t_r_i_n_g Specify the job for which the command line uniquely contains _s_t_r_i_n_g. 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. SunOS 5.8 Last change: 23 May 1997 15 User Commands csh(1) Status Reporting While running interactively, the shell tracks the status of each job and reports whenever the job finishes or becomes blocked. It normally displays a message to this effect as it issues a prompt, in order to avoid disturbing 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 background 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 per- forms no action. alias [ _n_a_m_e [ _d_e_f ] ] Assign _d_e_f to the alias _n_a_m_e. _d_e_f is a list of words that may contain escaped history-substitution metasyn- tax. _n_a_m_e is not allowed to be alias or unalias. If _d_e_f is omitted, the current definition for the alias _n_a_m_e is displayed. If both _n_a_m_e and _d_e_f are omitted, all aliases are displayed with their definitions. bg [ %_j_o_b ... ] Run the current or specified jobs in the background. break Resume execution after the end of the nearest enclos- ing foreach or while loop. The remaining 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 _l_a_b_e_l: A label in a switch statement. cd [_d_i_r ] chdir [_d_i_r ] Change the shell's working directory to directory _d_i_r. If no argument is given, change to the home directory of the user. If _d_i_r is a relative pathname not found in the current directory, check for it in those direc- tories listed in the cdpath variable. If _d_i_r is the name of a shell variable whose value starts with a /, change to the directory named by that value. SunOS 5.8 Last change: 23 May 1997 16 User Commands csh(1) continue Continue execution of the next iteration of the nearest enclosing while or foreach loop. 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 exe- cuted. dirs [-l] Print the directory stack, most recent to the left; the first directory shown is the current directory. With the -l argument, produce an unabbreviated prin- tout; use of the ~ notation is suppressed. echo [-n] _l_i_s_t The words in _l_i_s_t 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. csh will, by default, invoke its built-in echo, if echo is called without the full pathname of a Unix command, regardless of the configuration of your PATH (see echo(1)). eval _a_r_g_u_m_e_n_t... Reads the arguments as input to the shell and executes the resulting command(s). This is usually used to exe- cute commands generated as the result of command or variable substitution. See tset(1B) for an example of how to use eval. exec _c_o_m_m_a_n_d Execute _c_o_m_m_a_n_d in place of the current shell, which terminates. exit [(_e_x_p_r)] The calling shell or shell script exits, either with the value of the status variable or with the value specified by the expression _e_x_p_r. fg [%_j_o_b ] Bring the current or specified _j_o_b into the fore- ground. foreach _v_a_r (_w_o_r_d_l_i_s_t) ... end The variable _v_a_r is successively set to each member of _w_o_r_d_l_i_s_t. The sequence of commands between this com- mand and the matching end is executed for each new SunOS 5.8 Last change: 23 May 1997 17 User Commands csh(1) value of _v_a_r. Both foreach and end must appear alone on separate lines. The built-in command continue may be used to terminate the execution of the current iteration of the loop and the built-in command break may be used to terminate execution of the foreach command. When this command is read from the terminal, the loop is read once prompt- ing with ? before any statements in the loop are exe- cuted. glob _w_o_r_d_l_i_s_t Perform filename expansion on _w_o_r_d_l_i_s_t. Like echo, but no \ escapes are recognized. Words are delimited by _N_U_L_L characters in the output. goto _l_a_b_e_l The specified _l_a_b_e_l is a filename and a command expanded to yield a label. The shell rewinds its input as much as possible and searches for a line of the form _l_a_b_e_l: 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 command and its corresponding end. hashstat Print a statistics line indicating how effective the internal hash table for the _p_a_t_h variable has been at locating commands (and avoiding execs). An exec is attempted for each component of the _p_a_t_h where the hash function indicates a possible hit and in each component that does not begin with a `/'. These statistics only reflect the effectiveness of the _p_a_t_h variable, not the _c_d_p_a_t_h variable. 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 _s_o_u_r_c_e. if (_e_x_p_r )_c_o_m_m_a_n_d If the specified expression evaluates to true, the single _c_o_m_m_a_n_d with arguments is executed. Variable substitution on _c_o_m_m_a_n_d happens early, at the same SunOS 5.8 Last change: 23 May 1997 18 User Commands csh(1) time it does for the rest of the if command. _c_o_m_m_a_n_d must be a simple command, not a pipeline, a command list, or a parenthesized command list. Note: I/O redirection occurs even if _e_x_p_r is false, when _c_o_m_m_a_n_d is _n_o_t executed (this is a bug). if (expr) then ... else if (_e_x_p_r_2) then ... else ... endif If _e_x_p_r is true, commands up to the first else are executed. Otherwise, if _e_x_p_r_2 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. jobs [-l] List the active jobs under job control. -l List process IDs, in addition to the normal information. kill [ -_s_i_g ] [ _p_i_d ] [ %_j_o_b ] ... kill -l Send the TERM (terminate) signal, by default, or the signal specified, to the specified process ID, the _j_o_b indicated, or the current _j_o_b. Signals are either given by number or by name. There is no default. Typ- ing 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 (con- tinue) signal as well. -l List the signal names that can be sent. limit [-h] [_r_e_s_o_u_r_c_e [_m_a_x-_u_s_e ] ] Limit the consumption by the current process or any SunOS 5.8 Last change: 23 May 1997 19 User Commands csh(1) process it spawns, each not to exceed _m_a_x-_u_s_e on the specified _r_e_s_o_u_r_c_e. If _m_a_x-_u_s_e is omitted, print the current limit; if _r_e_s_o_u_r_c_e is omitted, display all limits. (Run the sysdef(1M) command to obtain the max- imum possible limits for your system. The values reported are in hexadecimal, but can be translated into decimal numbers using the bc(1) command). -h Use hard limits instead of the current limits. Hard limits impose a ceiling on the values of the current limits. Only the privileged user may raise the hard limits. _r_e_s_o_u_r_c_e is one of: cputime Maximum CPU seconds per process. filesize Largest single file allowed; limited to the size of the filesystem. (see df(1M)). datasize (heapsize) Maximum data size (including stack) for the process. This is the size of your virtual memory See swap(1M). stacksize Maximum stack size for the process. See swap(1M). coredumpsize Maximum size of a core dump (file). This limited to the size of the filesystem. descriptors Maximum number of file descriptors. Run sysdef(). memorysize Maximum size of virtual memory. _m_a_x-_u_s_e 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). _m_m:_s_s Minutes and seconds (for cputime). SunOS 5.8 Last change: 23 May 1997 20 User Commands csh(1) Example of limit: to limit the size of a core file dump to 0 Megabytes, type the following: limit coredumpsize 0M login [_u_s_e_r_n_a_m_e| -p ] Terminate a login shell and invoke login(1). The .logout file is not processed. If _u_s_e_r_n_a_m_e is omitted, login prompts for the name of a user. -p Preserve the current environment (variables). logout Terminate a login shell. nice [+_n |-_n ] [_c_o_m_m_a_n_d ] Increment the process priority value for the shell or for _c_o_m_m_a_n_d by _n. The higher the priority value, the lower the priority of a process, and the slower it runs. When given, _c_o_m_m_a_n_d is always run in a subshell, and the restrictions placed on commands in simple if commands apply. If _c_o_m_m_a_n_d is omitted, nice increments the value for the current shell. If no increment is specified, nice sets the process priority value to 4. The range of process priority values is from -20 to 20. Values of _n outside this range set the value to the lower, or to the higher boundary, respectively. +_n Increment the process priority value by _n. -_n Decrement by _n. This argument can be used only by the privileged user. nohup [_c_o_m_m_a_n_d ] Run _c_o_m_m_a_n_d with HUPs ignored. With no arguments, ignore HUPs throughout the remainder of a script. When given, _c_o_m_m_a_n_d is always run in a subshell, and the restrictions placed on commands in simple if state- ments apply. All processes detached with & are effec- tively nohup'd. notify [%_j_o_b] ... Notify the user asynchronously when the status of the current job or specified jobs changes. onintr [-| _l_a_b_e_l] 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 SunOS 5.8 Last change: 23 May 1997 21 User Commands csh(1) scripts and returns to the terminal command input level). With the - argument, the shell ignores all interrupts. With a _l_a_b_e_l argument, the shell executes a goto _l_a_b_e_l when an interrupt is received or a child process terminates because it was interrupted. popd [+_n ] Pop the directory stack and cd to the new top direc- tory. 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 |_d_i_r] 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. _d_i_r Push the current working directory onto the stack and change to _d_i_r. rehash Recompute the internal hash table of the contents of directories listed in the _p_a_t_h variable to account for new commands added. Recompute the internal hash table of the contents of directories listed in the _c_d_p_a_t_h variable to account for new directories added. repeat _c_o_u_n_t _c_o_m_m_a_n_d Repeat _c_o_m_m_a_n_d _c_o_u_n_t times. _c_o_m_m_a_n_d is subject to the same restrictions as with the one-line if statement. set [_v_a_r [= _v_a_l_u_e ] ] set _v_a_r[_n] = _w_o_r_d With no arguments, set displays the values of all shell variables. Multiword values are displayed as a parenthesized list. With the _v_a_r argument alone, set assigns an empty (null) value to the variable _v_a_r. With arguments of the form _v_a_r = _v_a_l_u_e set assigns _v_a_l_u_e to _v_a_r, where _v_a_l_u_e is one of: _w_o_r_d A single word (or quoted string). (_w_o_r_d_l_i_s_t) A space-separated list of words enclosed in parentheses. SunOS 5.8 Last change: 23 May 1997 22 User Commands csh(1) Values are command and filename expanded before being assigned. The form set _v_a_r[_n] = _w_o_r_d replaces the _n'th word in a multiword value with _w_o_r_d. setenv [_V_A_R [_w_o_r_d ] ] With no arguments, setenv displays all environment variables. With the _V_A_R argument, setenv sets the environment variable _V_A_R to have an empty (null) value. (By convention, environment variables are nor- mally given upper-case names.) With both _V_A_R and _w_o_r_d arguments, setenv sets the environment variable NAME to the value _w_o_r_d, 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 addition, the shell sets the PWD environment variable from the csh variable cwd whenever the latter changes. The environment variables LC_CTYPE, LC_MESSAGES, LC_TIME, LC_COLLATE, LC_NUMERIC, and LC_MONETARY take immediate effect when changed within the C shell. If any of the LC_* variables (LC_CTYPE, LC_MESSAGES, LC_TIME, LC_COLLATE, LC_NUMERIC, and LC_MONETARY) (see environ(5)) are not set in the environment, the operational behavior of csh for each corresponding locale category is determined by the value of the LANG environment variable. If LC_ALL is set, its contents are used to override both the LANG and the other LC_* variables. If none of the above variables is set in the environment, the "C" (U.S. style) locale deter- mines how csh behaves. LC_CTYPE Determines how csh handles characters. When LC_CTYPE is set to a valid value, csh can display and handle text and filenames containing valid characters for that locale. LC_MESSAGES Determines how diagnostic and informative mes- sages are presented. This includes the language and style of the messages and the correct form of affirmative and negative responses. In the "C" locale, the messages are presented in the default form found in the program itself (in most cases, U.S./English). LC_NUMERIC SunOS 5.8 Last change: 23 May 1997 23 User Commands csh(1) Determines the value of the radix character (decimal point (".") in the "C" locale) and thousand separator (empty string ("") in the "C" locale). shift [_v_a_r_i_a_b_l_e ] The components of argv, or _v_a_r_i_a_b_l_e, 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] _n_a_m_e Reads commands from _n_a_m_e. 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 terminates all nested source com- mands. -h Place commands from the file _n_a_m_e on the history list without executing them. stop %_j_o_b_i_d ... Stop the current or specified background job. stop _p_i_d ... Stop the specified process, _p_i_d. (see ps(1)). suspend Stop the shell in its tracks, much as if it had been sent a stop signal with ^Z. This is most often used to stop shells started by su. switch (_s_t_r_i_n_g) case _l_a_b_e_l: ... breaksw ... default: ... breaksw endsw Each _l_a_b_e_l is successively matched, against the speci- fied _s_t_r_i_n_g, which is first command and filename SunOS 5.8 Last change: 23 May 1997 24 User Commands csh(1) 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 [_c_o_m_m_a_n_d ] With no argument, print a summary of time used by this C shell and its children. With an optional _c_o_m_m_a_n_d, execute _c_o_m_m_a_n_d and print a summary of the time it uses. As of this writing, the time built-in command does NOT compute the last 6 fields of output, render- ing the output to erroneously report the value "0" for these fields. example %time ls -R 9.0u 11.0s 3:32 10% 0+0k 0+0io 0pf+0w (See below the "Environment Variables and Predefined Shell Variables" sub-section on the time variable.) umask [_v_a_l_u_e ] Display the file creation mask. With _v_a_l_u_e, set the file creation mask. With _v_a_l_u_e given in octal, the user can turn-off any bits, but cannot turn-on bits to allow new permissions. Common values include 077, res- tricting all permissions from everyone else; 002, giv- ing complete access to the group, and read (and direc- tory search) access to others; or 022, giving read (and directory search) but not write permission to the group and others. unalias _p_a_t_t_e_r_n Discard aliases that match (filename substitution) _p_a_t_t_e_r_n. All aliases are removed by `unalias *'. unhash Disable the internal hash tables for the _p_a_t_h and _c_d_p_a_t_h variables. unlimit [-h] [_r_e_s_o_u_r_c_e ] Remove a limitation on _r_e_s_o_u_r_c_e. If no _r_e_s_o_u_r_c_e is specified, then all resource limitations are removed. See the description of the limit command for the list SunOS 5.8 Last change: 23 May 1997 25 User Commands csh(1) of resource names. -h Remove corresponding hard limits. Only the privileged user may do this. unset _p_a_t_t_e_r_n Remove variables whose names match (filename substitu- tion) _p_a_t_t_e_r_n. All variables are removed by `unset *'; this has noticeably distasteful side effects. unsetenv _v_a_r_i_a_b_l_e Remove _v_a_r_i_a_b_l_e from the environment. As with unset, pattern matching is not performed. wait Wait for background jobs to finish (or for an inter- rupt) before prompting. while (_e_x_p_r) ... end While _e_x_p_r is true (evaluates to nonzero), repeat com- mands between the while and the matching end state- ment. break and continue may be used to terminate or continue the loop prematurely. The while and end must appear alone on their input lines. If the shell's input is a terminal, it prompts for commands with a question-mark until the end command is entered and then performs the commands in the loop. % [_j_o_b ] [&] Bring the current or indicated _j_o_b to the foreground. With the ampersand, continue running _j_o_b in the back- ground. @ [_v_a_r =_e_x_p_r] @ [_v_a_r[_n]=_e_x_p_r] With no arguments, display the values for all shell variables. With arguments, set the variable _v_a_r, or the _n'th word in the value of _v_a_r, to the value that _e_x_p_r evaluates to. (If [_n] is supplied, both _v_a_r and its _n'th component must already exist.) If the expression contains the characters >, <, &, or |, then at least this part of _e_x_p_r must be placed within parentheses. The operators *=, +=, and so forth, are available as in C. The space separating the name from the assign- ment operator is optional. Spaces are, however, SunOS 5.8 Last change: 23 May 1997 26 User Commands csh(1) mandatory in separating components of _e_x_p_r that would otherwise be single words. Special postfix operators, ++ and --, increment or decrement _n_a_m_e, respectively. Environment Variables and Predefined Shell Variables Unlike the Bourne 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 initializa- tion. 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 vari- able 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 whenever the latter changes. The following shell variables have predefined meanings: argv Argument list. Contains the list of command line argu- ments supplied to the current invocation of the shell. This variable determines the value of the positional parameters $1, $2, and so on. cdpath Contains a list of directories to be searched by the cd, chdir, and popd commands, if the directory argu- ment 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 execu- tion. 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 EOT and the ESC character have special sig- nificance 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. SunOS 5.8 Last change: 23 May 1997 27 User Commands csh(1) 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 character. 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. mail 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). nobeep Suppress the bell during command completion when ask- ing the C shell to extend an ambiguous filename. noclobber 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. noglob Inhibit filename substitution. This is most useful in shell scripts once filenames (if any) are obtained and no further expansion is desired. nonomatch Returns the filename substitution pattern, rather than an error, if the pattern is not matched. Malformed patterns still result in errors. notify If set, the shell notifies you immediately as jobs are completed, rather than waiting until just before issu- ing a prompt. SunOS 5.8 Last change: 23 May 1997 28 User Commands csh(1) path The list of directories in which to search for com- mands. path is initialized from the environment vari- able PATH, which the C shell updates whenever path changes. A null word ('') specifies the current direc- tory. The default is typically (/usr/bin .). One may override this initial search path upon csh start-up by setting it in .cshrc or .login (for login shells only). 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. prompt The string an interactive C shell prompts with. Nonin- teractive 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 _h_o_s_t_n_a_m_e% for mere mortals, or _h_o_s_t_n_a_m_e# for the privileged user. The setting of $prompt has three meanings: $prompt not set non-interactive shell, test $?prompt. $prompt set but == "" .cshrc called by the which(1) command. $prompt set and != "" normal interactive shell. savehist 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. shell 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. status 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. SunOS 5.8 Last change: 23 May 1997 29 User Commands csh(1) time 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 Kilo- bytes. %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 Kilo- bytes. %M Maximum real memory used during execution of the pro- cess. %O Number of block output operations. %P Total CPU time - U (user) plus S (system) - as a per- centage of E (elapsed) time. %S Number of seconds of CPU time consumed by the kernel on behalf of the user's process. %U Number of seconds of CPU time devoted to the user's process. %W Number of swaps. %X Average amount of shared memory used in Kilobytes. The default summary display outputs from the %U, %S, %E, %P, %X, %D, %I, %O, %F, and %W tags, in that order. verbose Display each command after history substitution takes place. Large File Behavior See largefile(5) for the description of the behavior of csh when encountering files greater than or equal to 2 Gbyte ( 2 **31 bytes). FILES ~/.cshrc SunOS 5.8 Last change: 23 May 1997 30 User Commands csh(1) Read at beginning of execution by each shell. ~/.login Read by login shells after .cshrc at login. ~/.logout Read by login shells at logout. ~/.history Saved history for use at next login. /usr/bin/sh The Bourne shell, for shell scripts not starting with a `#'. /tmp/sh* Temporary file for `<<'. /etc/passwd Source of home directories for `~_n_a_m_e'. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |______________________________|______________________________| | Availability | SUNWcsu | |______________________________|______________________________| | CSI | Enabled | |______________________________|______________________________| SEE ALSO bc(1), echo(1), login(1), ls(1), more(1), ps(1), sh(1), shell_builtins(1), tset(1B), which(1), df(1M), swap(1M), sysdef(1M), access(2), exec(2), fork(2), pipe(2), a.out(4), environ(4), ascii(5), attributes(5), environ(5), large- file(5), termio(7I) 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. WARNINGS The use of setuid shell scripts is _s_t_r_o_n_g_l_y discouraged. NOTES Words can be no longer than 1024 bytes. The system limits argument lists to 1,048,576 bytes. However, the maximum number of arguments to a command for which filename SunOS 5.8 Last change: 23 May 1997 31 User Commands csh(1) 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. When a command is restarted from a stop, the shell prints the directory it started in if this is different from the current directory; this can be misleading (that is, wrong) as the job may have changed directories internally. Shell built-in functions are not stoppable/restartable. Com- mand 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 especially noticeable if the expansion results from an alias. It can be avoided by plac- ing 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 out- put control. Commands within loops, prompted for by ?, are not placed in the _h_i_s_t_o_r_y list. Control structures should be parsed rather than being recog- nized as built-in commands. This would allow control com- mands 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 problems with : modifier usage on variable substitutions: not all of the modifiers are available, and only one modifier per substitu- tion 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 common text editors consistently do the latter when given the g flag in a substitution 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. It is up to the user to manually remove all duplicate path- names accrued from using built-in commands as SunOS 5.8 Last change: 23 May 1997 32 User Commands csh(1) set path = _p_a_t_h_n_a_m_e_s or setenv PATH = _p_a_t_h_n_a_m_e_s more than once. 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 follows: _c_o_m_m_a_n_d > _o_u_t_f_i_l_e) >& _e_r_r_o_r_f_i_l_e Although robust enough for general use, adventures into the esoteric periphery of the C shell may reveal unexpected quirks. If you start csh as a login shell and you do not have a .login in your home directory, then the csh reads in the /etc/.login. When the shell executes a shell script that attempts to exe- cute a non-existent command interpreter, the shell returns an erroneous diagnostic message that the shell script file does not exist. BUGS As of this writing, the time built-in command does NOT com- pute the last 6 fields of output, rendering the output to erroneously report the value "0" for these fields: example %time ls -R 9.0u 11.0s 3:32 10% 0+0k 0+0io 0pf+0w SunOS 5.8 Last change: 23 May 1997 33 EMACS(1) User Commands EMACS(1) NNAAMMEE emacs - GNU project Emacs SSYYNNOOPPSSIISS eemmaaccss [ _c_o_m_m_a_n_d-_l_i_n_e _s_w_i_t_c_h_e_s ] [ _f_i_l_e_s ... ] DDEESSCCRRIIPPTTIIOONN _G_N_U _E_m_a_c_s is a version of _E_m_a_c_s, written by the author of the original (PDP-10) _E_m_a_c_s, Richard Stallman. The primary documentation of GNU Emacs is in the GNU Emacs Manual, which you can read on line using Info, a subsystem of Emacs. Please look there for complete and up-to-date documentation. This man page is updated only when someone volunteers to do so; the Emacs maintainers' priority goal is to minimize the amount of time this man page takes away from other more useful projects. The user functionality of GNU Emacs encompasses everything other _E_m_a_c_s editors do, and it is easily extensible since its editing commands are written in Lisp. _E_m_a_c_s has an extensive interactive help facility, but the facility assumes that you know how to manipulate _E_m_a_c_s win- dows and buffers. CTRL-h (backspace or CTRL-h) enters the Help facility. Help Tutorial (CTRL-h t) requests an interactive tutorial which can teach beginners the fundamen- tals of _E_m_a_c_s in a few minutes. Help Apropos (CTRL-h a) helps you find a command given its functionality, Help Char- acter (CTRL-h c) describes a given character's effect, and Help Function (CTRL-h f) describes a given Lisp function specified by name. _E_m_a_c_s'_s Undo can undo several steps of modification to your buffers, so it is easy to recover from editing mistakes. _G_N_U _E_m_a_c_s'_s many special packages handle mail reading (RMail) and sending (Mail), outline editing (Outline), com- piling (Compile), running subshells within _E_m_a_c_s windows (Shell), running a Lisp read-eval-print loop (Lisp- Interaction-Mode), and automated psychotherapy (Doctor). There is an extensive reference manual, but users of other Emacses should have little trouble adapting even without a copy. Users new to _E_m_a_c_s will be able to use basic features fairly rapidly by studying the tutorial and using the self- documentation features. Emacs Options The following options are of general interest: _f_i_l_e Edit _f_i_l_e. SunOS 5.5.1 Last change: 1995 December 7 1 EMACS(1) User Commands EMACS(1) ++_n_u_m_b_e_r Go to the line specified by _n_u_m_b_e_r (do not insert a space between the "+" sign and the number). --qq Do not load an init file. --uu _u_s_e_r Load _u_s_e_r'_s init file. --tt _f_i_l_e Use specified _f_i_l_e as the terminal instead of using stdin/stdout. This must be the first argument specified in the command line. The following options are lisp-oriented (these options are processed in the order encountered): --ff _f_u_n_c_t_i_o_n Execute the lisp function _f_u_n_c_t_i_o_n. --ll _f_i_l_e Load the lisp code in the file _f_i_l_e. The following options are useful when running _E_m_a_c_s as a batch editor: --bbaattcchh Edit in batch mode. The editor will send messages to stderr. This option must be the first in the argument list. You must use -l and -f options to specify files to execute and functions to call. --kkiillll Exit _E_m_a_c_s while in batch mode. Using Emacs with X _E_m_a_c_s has been tailored to work well with the X window sys- tem. If you run _E_m_a_c_s from under X windows, it will create its own X window to display in. You will probably want to start the editor as a background process so that you can continue using your original window. _E_m_a_c_s can be started with the following X switches: --nnaammee _n_a_m_e Specifies the name which should be assigned to the initial _E_m_a_c_s window. This controls looking up X resources as well as the window title. --ttiittllee _n_a_m_e Specifies the title for the initial X window. --rr Display the _E_m_a_c_s window in reverse video. --ii Use the "kitchen sink" bitmap icon when iconifying the _E_m_a_c_s window. SunOS 5.5.1 Last change: 1995 December 7 2 EMACS(1) User Commands EMACS(1) --ffoonntt _f_o_n_t, --ffnn _f_o_n_t Set the _E_m_a_c_s window's font to that specified by _f_o_n_t. You will find the various _X fonts in the /_u_s_r/_l_i_b/_X_1_1/_f_o_n_t_s directory. Note that _E_m_a_c_s will only accept fixed width fonts. Under the X11 Release 4 font-naming conventions, any font with the value "m" or "c" in the eleventh field of the font name is a fixed width font. Furthermore, fonts whose name are of the form _w_i_d_t_hx_h_e_i_g_h_t are gen- erally fixed width, as is the font _f_i_x_e_d. See _x_l_s_f_o_n_t_s(1) for more information. When you specify a font, be sure to put a space between the switch and the font name. --bb _p_i_x_e_l_s Set the _E_m_a_c_s window's border width to the number of pixels specified by _p_i_x_e_l_s. Defaults to one pixel on each side of the window. --iibb _p_i_x_e_l_s Set the window's internal border width to the number of pixels specified by _p_i_x_e_l_s. Defaults to one pixel of padding on each side of the window. --ggeeoommeettrryy _g_e_o_m_e_t_r_y Set the _E_m_a_c_s window's width, height, and position as specified. The geometry specification is in the standard X format; see _X(1) for more information. The width and height are specified in characters; the default is 80 by 24. --ffgg _c_o_l_o_r On color displays, sets the color of the text. See the file /_u_s_r/_l_i_b/_X_1_1/_r_g_b._t_x_t for a list of valid color names. --bbgg _c_o_l_o_r On color displays, sets the color of the window's background. --bbdd _c_o_l_o_r On color displays, sets the color of the window's border. --ccrr _c_o_l_o_r On color displays, sets the color of the window's text cursor. --mmss _c_o_l_o_r On color displays, sets the color of the window's SunOS 5.5.1 Last change: 1995 December 7 3 EMACS(1) User Commands EMACS(1) mouse cursor. --dd _d_i_s_p_l_a_y_n_a_m_e, --ddiissppllaayy _d_i_s_p_l_a_y_n_a_m_e Create the _E_m_a_c_s window on the display specified by _d_i_s_p_l_a_y_n_a_m_e. Must be the first option specified in the command line. --nnww Tells _E_m_a_c_s not to use its special interface to X. If you use this switch when invoking _E_m_a_c_s from an _x_t_e_r_m(1) window, display is done in that window. This must be the first option specified in the com- mand line. You can set _X default values for your _E_m_a_c_s windows in your ._X_r_e_s_o_u_r_c_e_s file (see _x_r_d_b(1)). Use the following format: emacs.keyword:value where _v_a_l_u_e specifies the default value of _k_e_y_w_o_r_d. _E_m_a_c_s lets you set default values for the following keywords: ffoonntt ((class FFoonntt)) Sets the window's text font. rreevveerrsseeVViiddeeoo ((class RReevveerrsseeVViiddeeoo)) If _r_e_v_e_r_s_e_V_i_d_e_o'_s value is set to _o_n, the window will be displayed in reverse video. bbiittmmaappIIccoonn ((class BBiittmmaappIIccoonn)) If _b_i_t_m_a_p_I_c_o_n'_s value is set to _o_n, the window will iconify into the "kitchen sink." bboorrddeerrWWiiddtthh ((class BBoorrddeerrWWiiddtthh)) Sets the window's border width in pixels. iinntteerrnnaallBBoorrddeerr ((class BBoorrddeerrWWiiddtthh)) Sets the window's internal border width in pixels. ffoorreeggrroouunndd ((class FFoorreeggrroouunndd)) For color displays, sets the window's text color. bbaacckkggrroouunndd ((class BBaacckkggrroouunndd)) For color displays, sets the window's background color. bboorrddeerrCCoolloorr ((class BBoorrddeerrCCoolloorr)) For color displays, sets the color of the window's border. ccuurrssoorrCCoolloorr ((class FFoorreeggrroouunndd)) For color displays, sets the color of the window's text cursor. SunOS 5.5.1 Last change: 1995 December 7 4 EMACS(1) User Commands EMACS(1) ppooiinntteerrCCoolloorr ((class FFoorreeggrroouunndd)) For color displays, sets the color of the window's mouse cursor. ggeeoommeettrryy ((class GGeeoommeettrryy)) Sets the geometry of the _E_m_a_c_s window (as described above). ttiittllee ((class TTiittllee)) Sets the title of the _E_m_a_c_s window. iiccoonnNNaammee ((class TTiittllee)) Sets the icon name for the _E_m_a_c_s window icon. If you try to set color values while using a black and white display, the window's characteristics will default as fol- lows: the foreground color will be set to black, the back- ground color will be set to white, the border color will be set to grey, and the text and mouse cursors will be set to black. Using the Mouse The following lists the mouse button bindings for the _E_m_a_c_s window under X11. MOUSE BUTTON FUNCTION left Set point. middle Paste text. right Cut text into X cut buffer. SHIFT-middle Cut text into X cut buffer. SHIFT-right Paste text. CTRL-middle Cut text into X cut buffer and kill it. CTRL-right Select this window, then split it into two windows. Same as typing CTRL-x 2. CTRL-SHIFT-left X buffer menu--hold the buttons and keys down, wait for menu to appear, select buffer, and release. Move mouse out of menu and release to cancel. CTRL-SHIFT-middle X help menu--pop up index card menu for Emacs help. CTRL-SHIFT-right Select window with mouse, and delete all other windows. Same as typing CTRL-x 1. MMAANNUUAALLSS You can order printed copies of the GNU Emacs Manual from the Free Software Foundation, which develops GNU software. See the file ORDERS for ordering information. Your local Emacs maintainer might also have copies avail- able. As with all software and publications from FSF, everyone is permitted to make and distribute copies of the SunOS 5.5.1 Last change: 1995 December 7 5 EMACS(1) User Commands EMACS(1) Emacs manual. The TeX source to the manual is also included in the Emacs source distribution. FFIILLEESS /usr/local/info - files for the Info documentation browser (a subsystem of Emacs) to refer to. Currently not much of Unix is documented here, but the complete text of the Emacs reference manual is included in a convenient tree structured form. /usr/local/share/emacs/$VERSION/src - C source files and object files /usr/local/share/emacs/$VERSION/lisp - Lisp source files and compiled files that define most editing commands. Some are preloaded; others are autoloaded from this directory when used. /usr/local/share/emacs/$VERSION/etc - various programs that are used with GNU Emacs, and some files of information. /usr/local/share/emacs/$VERSION/etc/DOC.* - contains the documentation strings for the Lisp primitives and preloaded Lisp functions of GNU Emacs. They are stored here to reduce the size of Emacs proper. /usr/local/share/emacs/$VERSION/etc/OTHER.EMACSES discusses GNU Emacs vs. other versions of Emacs. /usr/local/share/emacs/$VERSION/etc/SERVICE lists people offering various services to assist users of GNU Emacs, including education, troubleshooting, porting and customiza- tion. These files also have information useful to anyone wishing to write programs in the Emacs Lisp extension language, which has not yet been fully documented. /usr/local/com/emacs/lock - holds lock files that are made for all files being modified in Emacs, to prevent simultane- ous modification of one file by two users. /usr/lib/X11/rgb.txt - list of valid X color names. BBUUGGSS There is a mailing list, bug-gnu-emacs@prep.ai.mit.edu on the internet (ucbvax!prep.ai.mit.edu!bug-gnu-emacs on UUCPnet), for reporting Emacs bugs and fixes. But before reporting something as a bug, please try to be sure that it really is a bug, not a misunderstanding or a deliberate feature. We ask you to read the section ``Reporting Emacs Bugs'' near the end of the reference manual (or Info system) for hints on how and when to report bugs. Also, include the version number of the Emacs you are running in _e_v_e_r_y bug SunOS 5.5.1 Last change: 1995 December 7 6 EMACS(1) User Commands EMACS(1) report that you send in. Do not expect a personal answer to a bug report. The pur- pose of reporting bugs is to get them fixed for everyone in the next release, if possible. For personal assistance, look in the SERVICE file (see above) for a list of people who offer it. Please do not send anything but bug reports to this mailing list. Send requests to be added to mailing lists to the special list info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding UUCP address). For more information about Emacs mailing lists, see the file /usr/local/emacs/etc/MAILINGLISTS. Bugs tend actually to be fixed if they can be isolated, so it is in your interest to report them in such a way that they can be easily repro- duced. Bugs that I know about are: shell will not work with pro- grams running in Raw mode on some Unix versions. UUNNRREESSTTRRIICCTTIIOONNSS _E_m_a_c_s is free; anyone may redistribute copies of _E_m_a_c_s to anyone under the terms stated in the _E_m_a_c_s General Public License, a copy of which accompanies each copy of _E_m_a_c_s and which also appears in the reference manual. Copies of _E_m_a_c_s may sometimes be received packaged with dis- tributions of Unix systems, but it is never included in the scope of any license covering those systems. Such inclusion violates the terms on which distribution is permitted. In fact, the primary purpose of the General Public License is to prohibit anyone from attaching any other restrictions to redistribution of _E_m_a_c_s. Richard Stallman encourages you to improve and extend _E_m_a_c_s, and urges that you contribute your extensions to the GNU library. Eventually GNU (Gnu's Not Unix) will be a complete replacement for Berkeley Unix. Everyone will be free to use, copy, study and change the GNU system. SSEEEE AALLSSOO X(1), xlsfonts(1), xterm(1), xrdb(1) AAUUTTHHOORRSS _E_m_a_c_s was written by Richard Stallman and the Free Software Foundation. Joachim Martillo and Robert Krawitz added the X features. SunOS 5.5.1 Last change: 1995 December 7 7 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) NNNNAAAAMMMMEEEE perlfunc - Perl builtin functions DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The functions in this section can serve as terms in an expression. They fall into two major categories: list operators and named unary operators. These differ in their precedence relationship with a following comma. (See the precedence table in the _p_e_r_l_o_p manpage.) List operators take more than one argument, while unary operators can never take more than one argument. Thus, a comma terminates the argument of a unary operator, but merely separates the arguments of a list operator. A unary operator generally provides a scalar context to its argument, while a list operator may provide either scalar and list contexts for its arguments. If it does both, the scalar arguments will be first, and the list argument will follow. (Note that there can only ever be one list argument.) For instance, _s_p_l_i_c_e() has three scalar arguments followed by a list. In the syntax descriptions that follow, list operators that expect a list (and provide list context for the elements of the list) are shown with LIST as an argument. Such a list may consist of any combination of scalar arguments or list values; the list values will be included in the list as if each individual element were interpolated at that point in the list, forming a longer single-dimensional list value. Elements of the LIST should be separated by commas. Any function in the list below may be used either with or without parentheses around its arguments. (The syntax descriptions omit the parens.) If you use the parens, the simple (but occasionally surprising) rule is this: It _L_O_O_K_S like a function, therefore it _I_S a function, and precedence doesn't matter. Otherwise it's a list operator or unary operator, and precedence does matter. And whitespace between the function and left parenthesis doesn't count--so you need to be careful sometimes: print 1+2+3; # Prints 6. print(1+2) + 3; # Prints 3. print (1+2)+3; # Also prints 3! print +(1+2)+3; # Prints 6. print ((1+2)+3); # Prints 6. If you run Perl with the ----wwww switch it can warn you about this. For example, the third line above produces: print (...) interpreted as function at - line 1. Useless use of integer addition in void context at - line 1. For functions that can be used in either a scalar or list 25/Mar/96 Last change: perl 5.003 with 1 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) context, non-abortive failure is generally indicated in a scalar context by returning the undefined value, and in a list context by returning the null list. Remember the following rule: _T_H_E_R_E _I_S _N_O _G_E_N_E_R_A_L _R_U_L_E _F_O_R _C_O_N_V_E_R_T_I_N_G _A _L_I_S_T _I_N_T_O _A _S_C_A_L_A_R! Each operator and function decides which sort of value it would be most appropriate to return in a scalar context. Some operators return the length of the list that would have been returned in a list context. Some operators return the first value in the list. Some operators return the last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. PPPPeeeerrrrllll FFFFuuuunnnnccccttttiiiioooonnnnssss bbbbyyyy CCCCaaaatttteeeeggggoooorrrryyyy Here are Perl's functions (including things that look like functions, like some of the keywords and named operators) arranged by category. Some functions appear in more than one place. Functions for SCALARs or strings chomp, chop, chr, crypt, hex, index, lc, lcfirst, length, oct, ord, pack, q/STRING/, qq/STRING/, reverse, rindex, sprintf, substr, tr///, uc, ucfirst, y/// Regular expressions and pattern matching m//, pos, quotemeta, s///, split, study Numeric functions abs, atan2, cos, exp, hex, int, log, oct, rand, sin, sqrt, srand Functions for real @ARRAYs pop, push, shift, splice, unshift Functions for list data grep, join, map, qw/STRING/, reverse, sort, unpack Functions for real %HASHes delete, each, exists, keys, values Input and output functions binmode, close, closedir, dbmclose, dbmopen, die, eof, fileno, flock, format, getc, print, printf, read, readdir, rewinddir, seek, seekdir, select, syscall, sysread, syswrite, tell, telldir, truncate, warn, write 25/Mar/96 Last change: perl 5.003 with 2 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Functions for fixed length data or records pack, read, syscall, sysread, syswrite, unpack, vec Functions for filehandles, files, or directories -X, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link, lstat, mkdir, open, opendir, readlink, rename, rmdir, stat, symlink, umask, unlink, utime Keywords related to the control flow of your perl program caller, continue, die, do, dump, eval, exit, goto, last, next, redo, return, sub, wantarray Keywords related to scoping caller, import, local, my, package, use Miscellaneous functions defined, dump, eval, formline, local, my, reset, scalar, undef, wantarray Functions for processes and process groups alarm, exec, fork, getpgrp, getppid, getpriority, kill, pipe, qx/STRING/, setpgrp, setpriority, sleep, system, times, wait, waitpid Keywords related to perl modules do, import, no, package, require, use Keywords related to classes and object-orientedness bless, dbmclose, dbmopen, package, ref, tie, tied, untie, use Low-level socket functions accept, bind, connect, getpeername, getsockname, getsockopt, listen, recv, send, setsockopt, shutdown, socket, socketpair System V interprocess communication functions msgctl, msgget, msgrcv, msgsnd, semctl, semget, semop, shmctl, shmget, shmread, shmwrite Fetching user and group info endgrent, endhostent, endnetent, endpwent, getgrent, getgrgid, getgrnam, getlogin, getpwent, getpwnam, getpwuid, setgrent, setpwent Fetching network info endprotoent, endservent, gethostbyaddr, gethostbyname, gethostent, getnetbyaddr, getnetbyname, getnetent, getprotobyname, getprotobynumber, getprotoent, getservbyname, getservbyport, getservent, sethostent, setnetent, setprotoent, setservent 25/Mar/96 Last change: perl 5.003 with 3 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Time-related functions gmtime, localtime, time, times Functions new in perl5 abs, bless, chomp, chr, exists, formline, glob, import, lc, lcfirst, map, my, no, qx, qw, ref, sub*, sysopen, tie, tied, uc, ucfirst, untie, use * - sub was a keyword in perl4, but in perl5 it is an operator which can be used in expressions. Functions obsoleted in perl5 dbmclose, dbmopen AAAAllllpppphhhhaaaabbbbeeeettttiiiiccccaaaallll LLLLiiiissssttttiiiinnnngggg ooooffff PPPPeeeerrrrllll FFFFuuuunnnnccccttttiiiioooonnnnssss -X FILEHANDLE -X EXPR -X A file test, where X is one of the letters listed below. This unary operator takes one argument, either a filename or a filehandle, and tests the associated file to see if something is true about it. If the argument is omitted, tests $_, except for -t, which tests STDIN. Unless otherwise documented, it returns 1 for TRUE and '' for FALSE, or the undefined value if the file doesn't exist. Despite the funny names, precedence is the same as any other named unary operator, and the argument may be parenthesized like any other unary operator. The operator may be any of: -r File is readable by effective uid/gid. -w File is writable by effective uid/gid. -x File is executable by effective uid/gid. -o File is owned by effective uid. -R File is readable by real uid/gid. -W File is writable by real uid/gid. -X File is executable by real uid/gid. -O File is owned by real uid. -e File exists. -z File has zero size. -s File has non-zero size (returns size). 25/Mar/96 Last change: perl 5.003 with 4 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) -f File is a plain file. -d File is a directory. -l File is a symbolic link. -p File is a named pipe (FIFO). -S File is a socket. -b File is a block special file. -c File is a character special file. -t Filehandle is opened to a tty. -u File has setuid bit set. -g File has setgid bit set. -k File has sticky bit set. -T File is a text file. -B File is a binary file (opposite of -T). -M Age of file in days when script started. -A Same for access time. -C Same for inode change time. The interpretation of the file permission operators -r, -R, -w, -W, -x and -X is based solely on the mode of the file and the uids and gids of the user. There may be other reasons you can't actually read, write or execute the file. Also note that, for the superuser, -r, -R, -w and -W always return 1, and -x and -X return 1 if any execute bit is set in the mode. Scripts run by the superuser may thus need to do a _s_t_a_t() in order to determine the actual mode of the file, or temporarily set the uid to something else. Example: while (<>) { chop; next unless -f $_; # ignore specials ... } Note that -s/a/b/ does not do a negated substitution. Saying -exp($foo) still works as expected, however--only single letters following a minus are interpreted as file tests. The -T and -B switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or characters with the high bit set. If too many odd characters (>30%) are found, it's a -B file, otherwise it's a -T file. Also, any file containing null in the first block is considered a binary file. 25/Mar/96 Last change: perl 5.003 with 5 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) If -T or -B is used on a filehandle, the current stdio buffer is examined rather than the first block. Both -T and -B return TRUE on a null file, or a file at EOF when testing a filehandle. Because you have to read a file to do the -T test, on most occasions you want to use a -f against the file first, as in next unless -f $file && -T $file. If any of the file tests (or either the _s_t_a_t() or _l_s_t_a_t() operators) are given the special filehandle consisting of a solitary underline, then the stat structure of the previous file test (or stat operator) is used, saving a system call. (This doesn't work with -t, and you need to remember that _l_s_t_a_t() and -l will leave values in the stat structure for the symbolic link, not the real file.) Example: print "Can do.\n" if -r $a || -w _ || -x _; stat($filename); print "Readable\n" if -r _; print "Writable\n" if -w _; print "Executable\n" if -x _; print "Setuid\n" if -u _; print "Setgid\n" if -g _; print "Sticky\n" if -k _; print "Text\n" if -T _; print "Binary\n" if -B _; abs VALUE Returns the absolute value of its argument. accept NEWSOCKET,GENERICSOCKET Accepts an incoming socket connect, just as the _a_c_c_e_p_t(2) system call does. Returns the packed address if it succeeded, FALSE otherwise. See example in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage. alarm SECONDS Arranges to have a SIGALRM delivered to this process after the specified number of seconds have elapsed. (On some machines, unfortunately, the elapsed time may be up to one second less than you specified because of how seconds are counted.) Only one timer may be counting at once. Each call disables the previous timer, and an argument of 0 may be supplied to cancel the previous timer without starting a new one. The returned value is the amount of time remaining on the previous timer. 25/Mar/96 Last change: perl 5.003 with 6 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) For delays of finer granularity than one second, you may use Perl's _s_y_s_c_a_l_l() interface to access _s_e_t_i_t_i_m_e_r(2) if your system supports it, or else see the select() entry elsewhere in this documentbelow. It is not advised to intermix _a_l_a_r_m() and _s_l_e_e_p() calls. atan2 Y,X Returns the arctangent of Y/X in the range -pi to pi. bind SOCKET,NAME Binds a network address to a socket, just as the bind system call does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage. binmode FILEHANDLE Arranges for the file to be read or written in "binary" mode in operating systems that distinguish between binary and text files. Files that are not in binary mode have CR LF sequences translated to LF on input and LF translated to CR LF on output. Binmode has no effect under Unix; in DOS and similarly archaic systems, it may be imperative- -otherwise your DOS-damaged C library may mangle your file. The key distinction between systems that need binmode and those that don't is their text file formats. Systems like Unix and Plan9 that delimit lines with a single character, and that encode that character in C as '\n', do not need binmode. The rest need it. If FILEHANDLE is an expression, the value is taken as the name of the filehandle. bless REF,CLASSNAME bless REF This function tells the referenced object (passed as REF) that it is now an object in the CLASSNAME package--or the current package if no CLASSNAME is specified, which is often the case. It returns the reference for convenience, since a _b_l_e_s_s() is often the last thing in a constructor. Always use the two-argument version if the function doing the blessing might be inherited by a derived class. See the _p_e_r_l_o_b_j manpage for more about the blessing (and blessings) of objects. caller EXPR 25/Mar/96 Last change: perl 5.003 with 7 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) caller Returns the context of the current subroutine call. In a scalar context, returns TRUE if there is a caller, that is, if we're in a subroutine or _e_v_a_l() or _r_e_q_u_i_r_e(), and FALSE otherwise. In a list context, returns ($package, $filename, $line) = caller; With EXPR, it returns some extra information that the debugger uses to print a stack trace. The value of EXPR indicates how many call frames to go back before the current one. ($package, $filename, $line, $subroutine, $hasargs, $wantargs) = caller($i); Furthermore, when called from within the DB package, caller returns more detailed information: it sets the list variable @DB::args to be the arguments with which that subroutine was invoked. chdir EXPR Changes the working directory to EXPR, if possible. If EXPR is omitted, changes to home directory. Returns TRUE upon success, FALSE otherwise. See example under _d_i_e(). chmod LIST Changes the permissions of a list of files. The first element of the list must be the numerical mode, which should probably be an octal number. Returns the number of files successfully changed. $cnt = chmod 0755, 'foo', 'bar'; chmod 0755, @executables; chomp VARIABLE chomp LIST chomp This is a slightly safer version of chop (see below). It removes any line ending that corresponds to the current value of $/ (also known as $INPUT_RECORD_SEPARATOR in the English module). It returns the number of characters removed. It's often used to remove the newline from the end of an input record when you're worried that the final record may be missing its newline. When in paragraph mode ($/ = ""), it removes all trailing newlines from the string. If VARIABLE is omitted, it chomps $_. Example: 25/Mar/96 Last change: perl 5.003 with 8 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) while (<>) { chomp; # avoid \n on last field @array = split(/:/); ... } You can actually chomp anything that's an lvalue, including an assignment: chomp($cwd = `pwd`); chomp($answer = ); If you chomp a list, each element is chomped, and the total number of characters removed is returned. chop VARIABLE chop LIST chop Chops off the last character of a string and returns the character chopped. It's used primarily to remove the newline from the end of an input record, but is much more efficient than s/\n// because it neither scans nor copies the string. If VARIABLE is omitted, chops $_. Example: while (<>) { chop; # avoid \n on last field @array = split(/:/); ... } You can actually chop anything that's an lvalue, including an assignment: chop($cwd = `pwd`); chop($answer = ); If you chop a list, each element is chopped. Only the value of the last chop is returned. Note that chop returns the last character. To return all but the last character, use substr($string, 0, -1). chown LIST Changes the owner (and group) of a list of files. The first two elements of the list must be the _N_U_M_E_R_I_C_A_L uid and gid, in that order. Returns the number of files successfully changed. 25/Mar/96 Last change: perl 5.003 with 9 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) $cnt = chown $uid, $gid, 'foo', 'bar'; chown $uid, $gid, @filenames; Here's an example that looks up non-numeric uids in the passwd file: print "User: "; chop($user = ); print "Files: " chop($pattern = ); ($login,$pass,$uid,$gid) = getpwnam($user) or die "$user not in passwd file"; @ary = <${pattern}>; # expand filenames chown $uid, $gid, @ary; On most systems, you are not allowed to change the ownership of the file unless you're the superuser, although you should be able to change the group to any of your secondary groups. On insecure systems, these restrictions may be relaxed, but this is not a portable assumption. chr NUMBER Returns the character represented by that NUMBER in the character set. For example, chr(65) is "A" in ASCII. chroot FILENAME This function works as the system call by the same name: it makes the named directory the new root directory for all further pathnames that begin with a "/" by your process and all of its children. (It doesn't change your current working directory is unaffected.) For security reasons, this call is restricted to the superuser. If FILENAME is omitted, does chroot to $_. close FILEHANDLE Closes the file or pipe associated with the file handle, returning TRUE only if stdio successfully flushes buffers and closes the system file descriptor. You don't have to close FILEHANDLE if you are immediately going to do another _o_p_e_n() on it, since _o_p_e_n() will close it for you. (See _o_p_e_n().) However, an explicit close on an input file resets the line counter ($.), while the implicit close done by _o_p_e_n() does not. Also, closing a pipe will wait for the process executing on the pipe to complete, in case you want to look at the output of the pipe afterwards. Closing a pipe 25/Mar/96 Last change: perl 5.003 with 10 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) explicitly also puts the status value of the command into $?. Example: open(OUTPUT, '|sort >foo'); # pipe to sort ... # print stuff to output close OUTPUT; # wait for sort to finish open(INPUT, 'foo'); # get sort's results FILEHANDLE may be an expression whose value gives the real filehandle name. closedir DIRHANDLE Closes a directory opened by _o_p_e_n_d_i_r(). connect SOCKET,NAME Attempts to connect to a remote socket, just as the connect system call does. Returns TRUE if it succeeded, FALSE otherwise. NAME should be a packed address of the appropriate type for the socket. See the examples in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage. continue BLOCK Actually a flow control statement rather than a function. If there is a continue BLOCK attached to a BLOCK (typically in a while or foreach), it is always executed just before the conditional is about to be evaluated again, just like the third part of a for loop in C. Thus it can be used to increment a loop variable, even when the loop has been continued via the next statement (which is similar to the C continue statement). cos EXPR Returns the cosine of EXPR (expressed in radians). If EXPR is omitted takes cosine of $_. crypt PLAINTEXT,SALT Encrypts a string exactly like the _c_r_y_p_t(3) function in the C library (assuming that you actually have a version there that has not been extirpated as a potential munition). This can prove useful for checking the password file for lousy passwords, amongst other things. Only the guys wearing white hats should do this. Here's an example that makes sure that whoever runs this program knows their own password: $pwd = (getpwuid($<))[1]; $salt = substr($pwd, 0, 2); 25/Mar/96 Last change: perl 5.003 with 11 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) system "stty -echo"; print "Password: "; chop($word = ); print "\n"; system "stty echo"; if (crypt($word, $salt) ne $pwd) { die "Sorry...\n"; } else { print "ok\n"; } Of course, typing in your own password to whoever asks you for it is unwise. dbmclose ASSOC_ARRAY [This function has been superseded by the _u_n_t_i_e() function.] Breaks the binding between a DBM file and an associative array. dbmopen ASSOC,DBNAME,MODE [This function has been superseded by the _t_i_e() function.] This binds a _d_b_m(3), _n_d_b_m(3), _s_d_b_m(3), _g_d_b_m(), or Berkeley DB file to an associative array. ASSOC is the name of the associative array. (Unlike normal open, the first argument is _N_O_T a filehandle, even though it looks like one). DBNAME is the name of the database (without the ._d_i_r or ._p_a_g extension if any). If the database does not exist, it is created with protection specified by MODE (as modified by the _u_m_a_s_k()). If your system only supports the older DBM functions, you may perform only one _d_b_m_o_p_e_n() in your program. In older versions of Perl, if your system had neither DBM nor ndbm, calling _d_b_m_o_p_e_n() produced a fatal error; it now falls back to _s_d_b_m(3). If you don't have write access to the DBM file, you can only read associative array variables, not set them. If you want to test whether you can write, either use file tests or try setting a dummy array entry inside an _e_v_a_l(), which will trap the error. Note that functions such as _k_e_y_s() and _v_a_l_u_e_s() may return huge array values when used on large DBM files. You may prefer to use the _e_a_c_h() function to iterate over large DBM files. Example: 25/Mar/96 Last change: perl 5.003 with 12 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) # print out history file offsets dbmopen(%HIST,'/usr/lib/news/history',0666); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } dbmclose(%HIST); See also the _A_n_y_D_B_M__F_i_l_e manpage for a more general description of the pros and cons of the various dbm apparoches, as well as the _D_B__F_i_l_e manpage for a particularly rich implementation. defined EXPR Returns a boolean value saying whether EXPR has a real value or not. Many operations return the undefined value under exceptional conditions, such as end of file, uninitialized variable, system error and such. This function allows you to distinguish between an undefined null scalar and a defined null scalar with operations that might return a real null string, such as referencing elements of an array. You may also check to see if arrays or subroutines exist. Use of defined on predefined variables is not guaranteed to produce intuitive results. When used on a hash array element, it tells you whether the value is defined, not whether the key exists in the hash. Use _e_x_i_s_t_s() for that. Examples: print if defined $switch{'D'}; print "$val\n" while defined($val = pop(@ary)); die "Can't readlink $sym: $!" unless defined($value = readlink $sym); eval '@foo = ()' if defined(@foo); die "No XYZ package defined" unless defined %_XYZ; sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } See also _u_n_d_e_f(). Note: many folks tend to overuse _d_e_f_i_n_e_d(), and then are surprised to discover that the number 0 and the null string are, in fact, defined concepts. For example, if you say "ab" =~ /a(.*)b/; the pattern match succeeds, and $1 is defined, despite the fact that it matched "nothing". But it didn't really match nothing--rather, it matched something that happened to be 0 characters long. 25/Mar/96 Last change: perl 5.003 with 13 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) This is all very above-board and honest. When a function returns an undefined value, it's an admission that it couldn't give you an honest answer. So you should only use _d_e_f_i_n_e_d() when you're questioning the integrity of what you're trying to do. At other times, a simple comparison to 0 or "" is what you want. delete EXPR Deletes the specified value from its hash array. Returns the deleted value, or the undefined value if nothing was deleted. Deleting from $ENV{} modifies the environment. Deleting from an array tied to a DBM file deletes the entry from the DBM file. (But deleting from a _t_i_e()d hash doesn't necessarily return anything.) The following deletes all the values of an associative array: foreach $key (keys %ARRAY) { delete $ARRAY{$key}; } (But it would be faster to use the _u_n_d_e_f() command.) Note that the EXPR can be arbitrarily complicated as long as the final operation is a hash key lookup: delete $ref->[$x][$y]{$key}; die LIST Outside of an _e_v_a_l(), prints the value of LIST to STDERR and exits with the current value of $! (errno). If $! is 0, exits with the value of ($? >> 8) (backtick `command` status). If ($? >> 8) is 0, exits with 255. Inside an _e_v_a_l(), the error message is stuffed into $@, and the _e_v_a_l() is terminated with the undefined value; this makes _d_i_e() the way to raise an exception. Equivalent examples: die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" If the value of EXPR does not end in a newline, the current script line number and input line number (if any) are also printed, and a newline is supplied. Hint: sometimes appending ", stopped" to your message will cause it to make better sense when the string "at foo line 123" is appended. Suppose you 25/Mar/96 Last change: perl 5.003 with 14 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) are running script "canasta". die "/etc/games is no good"; die "/etc/games is no good, stopped"; produce, respectively /etc/games is no good at canasta line 123. /etc/games is no good, stopped at canasta line 123. See also _e_x_i_t() and _w_a_r_n(). do BLOCK Not really a function. Returns the value of the last command in the sequence of commands indicated by BLOCK. When modified by a loop modifier, executes the BLOCK once before testing the loop condition. (On other statements the loop modifiers test the conditional first.) do SUBROUTINE(LIST) A deprecated form of subroutine call. See the _p_e_r_l_s_u_b manpage. do EXPR Uses the value of EXPR as a filename and executes the contents of the file as a Perl script. Its primary use is to include subroutines from a Perl subroutine library. do 'stat.pl'; is just like eval `cat stat.pl`; except that it's more efficient, more concise, keeps track of the current filename for error messages, and searches all the ----IIII libraries if the file isn't in the current directory (see also the @INC array in the section on _P_r_e_d_e_f_i_n_e_d _N_a_m_e_s in the _p_e_r_l_v_a_r manpage). It's the same, however, in that it does reparse the file every time you call it, so you probably don't want to do this inside a loop. Note that inclusion of library modules is better done with the _u_s_e() and _r_e_q_u_i_r_e() operators, which also do error checking and raise an exception if there's a problem. dump LABEL This causes an immediate core dump. Primarily this is so that you can use the uuuunnnndddduuuummmmpppp program to turn 25/Mar/96 Last change: perl 5.003 with 15 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) your core dump into an executable binary after having initialized all your variables at the beginning of the program. When the new binary is executed it will begin by executing a goto LABEL (with all the restrictions that goto suffers). Think of it as a goto with an intervening core dump and reincarnation. If LABEL is omitted, restarts the program from the top. WARNING: any files opened at the time of the dump will NOT be open any more when the program is reincarnated, with possible resulting confusion on the part of Perl. See also ---- uuuu option in the _p_e_r_l_r_u_n manpage. Example: #!/usr/bin/perl require 'getopt.pl'; require 'stat.pl'; %days = ( 'Sun' => 1, 'Mon' => 2, 'Tue' => 3, 'Wed' => 4, 'Thu' => 5, 'Fri' => 6, 'Sat' => 7, ); dump QUICKSTART if $ARGV[0] eq '-d'; QUICKSTART: Getopt('f'); each ASSOC_ARRAY Returns a 2-element array consisting of the key and value for the next value of an associative array, so that you can iterate over it. Entries are returned in an apparently random order. When the array is entirely read, a null array is returned (which when assigned produces a FALSE (0) value). The next call to _e_a_c_h() after that will start iterating again. The iterator can be reset only by reading all the elements from the array. You should not add elements to an array while you're iterating over it. There is a single iterator for each associative array, shared by all _e_a_c_h(), _k_e_y_s() and _v_a_l_u_e_s() function calls in the program. The following prints out your environment like the _p_r_i_n_t_e_n_v(1) program, only in a different order: 25/Mar/96 Last change: perl 5.003 with 16 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) while (($key,$value) = each %ENV) { print "$key=$value\n"; } See also _k_e_y_s() and _v_a_l_u_e_s(). eof FILEHANDLE eof () eof Returns 1 if the next read on FILEHANDLE will return end of file, or if FILEHANDLE is not open. FILEHANDLE may be an expression whose value gives the real filehandle name. (Note that this function actually reads a character and then _u_n_g_e_t_c()s it, so it is not very useful in an interactive context.) Do not read from a terminal file (or call eof(FILEHANDLE) on it) after end-of-file is reached. Filetypes such as terminals may lose the end-of-file condition if you do. An eof without an argument uses the last file read as argument. Empty parentheses () may be used to indicate the pseudofile formed of the files listed on the command line, i.e. eof() is reasonable to use inside a while (<>) loop to detect the end of only the last file. Use eof(ARGV) or eof without the parentheses to test _E_A_C_H file in a while (<>) loop. Examples: # reset line numbering on each input file while (<>) { print "$.\t$_"; close(ARGV) if (eof); # Not eof(). } # insert dashes just before last line of last file while (<>) { if (eof()) { print "--------------\n"; close(ARGV); # close or break; is needed if we # are reading from the terminal } print; } Practical hint: you almost never need to use eof in Perl, because the input operators return undef when they run out of data. eval EXPR 25/Mar/96 Last change: perl 5.003 with 17 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) eval BLOCK EXPR is parsed and executed as if it were a little Perl program. It is executed in the context of the current Perl program, so that any variable settings, subroutine or format definitions remain afterwards. The value returned is the value of the last expression evaluated, or a return statement may be used, just as with subroutines. If there is a syntax error or runtime error, or a _d_i_e() statement is executed, an undefined value is returned by _e_v_a_l(), and $@ is set to the error message. If there was no error, $@ is guaranteed to be a null string. If EXPR is omitted, evaluates $_. The final semicolon, if any, may be omitted from the expression. Note that, since _e_v_a_l() traps otherwise-fatal errors, it is useful for determining whether a particular feature (such as _s_o_c_k_e_t() or _s_y_m_l_i_n_k()) is implemented. It is also Perl's exception trapping mechanism, where the die operator is used to raise exceptions. If the code to be executed doesn't vary, you may use the eval-BLOCK form to trap run-time errors without incurring the penalty of recompiling each time. The error, if any, is still returned in $@. Examples: # make divide-by-zero non-fatal eval { $answer = $a / $b; }; warn $@ if $@; # same thing, but less efficient eval '$answer = $a / $b'; warn $@ if $@; # a compile-time error eval { $answer = }; # a run-time error eval '$answer ='; # sets $@ With an _e_v_a_l(), you should be especially careful to remember what's being looked at when: eval $x; # CASE 1 eval "$x"; # CASE 2 eval '$x'; # CASE 3 eval { $x }; # CASE 4 eval "\$$x++" # CASE 5 $$x++; # CASE 6 25/Mar/96 Last change: perl 5.003 with 18 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Cases 1 and 2 above behave identically: they run the code contained in the variable $x. (Although case 2 has misleading double quotes making the reader wonder what else might be happening (nothing is).) Cases 3 and 4 likewise behave in the same way: they run the code <$x>, which does nothing at all. (Case 4 is preferred for purely visual reasons.) Case 5 is a place where normally you _W_O_U_L_D like to use double quotes, except that in that particular situation, you can just use symbolic references instead, as in case 6. exec LIST The _e_x_e_c() function executes a system command _A_N_D _N_E_V_E_R _R_E_T_U_R_N_S. Use the _s_y_s_t_e_m() function if you want it to return. If there is more than one argument in LIST, or if LIST is an array with more than one value, calls _e_x_e_c_v_p(3) with the arguments in LIST. If there is only one scalar argument, the argument is checked for shell metacharacters. If there are any, the entire argument is passed to /bin/sh -c for parsing. If there are none, the argument is split into words and passed directly to _e_x_e_c_v_p(), which is more efficient. Note: _e_x_e_c() and _s_y_s_t_e_m() do not flush your output buffer, so you may need to set $| to avoid lost output. Examples: exec '/bin/echo', 'Your arguments are: ', @ARGV; exec "sort $outfile | uniq"; If you don't really want to execute the first argument, but want to lie to the program you are executing about its own name, you can specify the program you actually want to run as an "indirect object" (without a comma) in front of the LIST. (This always forces interpretation of the LIST as a multi-valued list, even if there is only a single scalar in the list.) Example: $shell = '/bin/csh'; exec $shell '-sh'; # pretend it's a login shell or, more directly, exec {'/bin/csh'} '-sh'; # pretend it's a login shell exists EXPR Returns TRUE if the specified hash key exists in its hash array, even if the corresponding value is 25/Mar/96 Last change: perl 5.003 with 19 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) undefined. print "Exists\n" if exists $array{$key}; print "Defined\n" if defined $array{$key}; print "True\n" if $array{$key}; A hash element can only be TRUE if it's defined, and defined if it exists, but the reverse doesn't necessarily hold true. Note that the EXPR can be arbitrarily complicated as long as the final operation is a hash key lookup: if (exists $ref->[$x][$y]{$key}) { ... } exit EXPR Evaluates EXPR and exits immediately with that value. (Actually, it calls any defined END routines first, but the END routines may not abort the exit. Likewise any object destructors that need to be called are called before exit.) Example: $ans = ; exit 0 if $ans =~ /^[Xx]/; See also _d_i_e(). If EXPR is omitted, exits with 0 status. exp EXPR Returns _e (the natural logarithm base) to the power of EXPR. If EXPR is omitted, gives exp($_). fcntl FILEHANDLE,FUNCTION,SCALAR Implements the _f_c_n_t_l(2) function. You'll probably have to say use Fcntl; first to get the correct function definitions. Argument processing and value return works just like _i_o_c_t_l() below. Note that _f_c_n_t_l() will produce a fatal error if used on a machine that doesn't implement _f_c_n_t_l(2). For example: use Fcntl; fcntl($filehandle, F_GETLK, $packed_return_buffer); fileno FILEHANDLE Returns the file descriptor for a filehandle. This is useful for constructing bitmaps for _s_e_l_e_c_t(). If 25/Mar/96 Last change: perl 5.003 with 20 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) FILEHANDLE is an expression, the value is taken as the name of the filehandle. flock FILEHANDLE,OPERATION Calls _f_l_o_c_k(2) on FILEHANDLE. See the _f_l_o_c_k(_2) manpage for definition of OPERATION. Returns TRUE for success, FALSE on failure. Will produce a fatal error if used on a machine that doesn't implement either _f_l_o_c_k(2) or _f_c_n_t_l(2). The _f_c_n_t_l(2) system call will be automatically used if _f_l_o_c_k(2) is missing from your system. This makes _f_l_o_c_k() the portable file locking strategy, although it will only lock entire files, not records. Note also that some versions of _f_l_o_c_k() cannot lock things over the network; you would need to use the more system- specific _f_c_n_t_l() for that. Here's a mailbox appender for BSD systems. $LOCK_SH = 1; $LOCK_EX = 2; $LOCK_NB = 4; $LOCK_UN = 8; sub lock { flock(MBOX,$LOCK_EX); # and, in case someone appended # while we were waiting... seek(MBOX, 0, 2); } sub unlock { flock(MBOX,$LOCK_UN); } open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}") or die "Can't open mailbox: $!"; lock(); print MBOX $msg,"\n\n"; unlock(); See also the _D_B__F_i_l_e manpage for other _f_l_o_c_k() examples. fork Does a _f_o_r_k(2) system call. Returns the child pid to the parent process and 0 to the child process, or undef if the fork is unsuccessful. Note: unflushed buffers remain unflushed in both processes, which means you may need to set $| ($AUTOFLUSH in English) or call the _a_u_t_o_f_l_u_s_h() FileHandle method to avoid duplicate output. 25/Mar/96 Last change: perl 5.003 with 21 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) If you _f_o_r_k() without ever waiting on your children, you will accumulate zombies: $SIG{CHLD} = sub { wait }; There's also the double-fork trick (error checking on _f_o_r_k() returns omitted); unless ($pid = fork) { unless (fork) { exec "what you really wanna do"; die "no exec"; # ... or ... ## (some_perl_code_here) exit 0; } exit 0; } waitpid($pid,0); See also the _p_e_r_l_i_p_c manpage for more examples of forking and reaping moribund children. format Declare a picture format with use by the _w_r_i_t_e() function. For example: format Something = Test: @<<<<<<<< @||||| @>>>>> $str, $%, '$' . int($num) . $str = "widget"; $num = $cost/$quantiy; $~ = 'Something'; write; See the _p_e_r_l_f_o_r_m manpage for many details and examples. formline PICTURE, LIST This is an internal function used by formats, though you may call it too. It formats (see the _p_e_r_l_f_o_r_m manpage) a list of values according to the contents of PICTURE, placing the output into the format output accumulator, $^A (or $ACCUMULATOR in English). Eventually, when a _w_r_i_t_e() is done, the contents of $^A are written to some filehandle, but you could also read $^A yourself and then set $^A back to "". Note that a format typically does one _f_o_r_m_l_i_n_e() per line of form, but the _f_o_r_m_l_i_n_e() function itself doesn't care how many newlines are embedded in the PICTURE. This means that the ~ and 25/Mar/96 Last change: perl 5.003 with 22 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) ~~ tokens will treat the entire PICTURE as a single line. You may therefore need to use multiple formlines to implement a single record format, just like the format compiler. Be careful if you put double quotes around the picture, since an "@" character may be taken to mean the beginning of an array name. _f_o_r_m_l_i_n_e() always returns TRUE. See the _p_e_r_l_f_o_r_m manpage for other examples. getc FILEHANDLE getc Returns the next character from the input file attached to FILEHANDLE, or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN. This is not particularly efficient. It cannot be used to get unbuffered single-characters, however. For that, try something more like: if ($BSD_STYLE) { system "stty cbreak /dev/tty 2>&1"; } else { system "stty", '-icanon', 'eol', "\001"; } $key = getc(STDIN); if ($BSD_STYLE) { system "stty -cbreak /dev/tty 2>&1"; } else { system "stty", 'icanon', 'eol', '^@'; # ascii null } print "\n"; Determination of whether to whether $BSD_STYLE should be set is left as an exercise to the reader. See also the Term::ReadKey module from your nearest CPAN site; details on CPAN can be found on the CPAN entry in the _p_e_r_l_m_o_d manpage getlogin Returns the current login from /_e_t_c/_u_t_m_p, if any. If null, use _g_e_t_p_w_u_i_d(). $login = getlogin || (getpwuid($<))[0] || "Kilroy"; Do not consider _g_e_t_l_o_g_i_n() for authorentication: it is not as secure as _g_e_t_p_w_u_i_d(). 25/Mar/96 Last change: perl 5.003 with 23 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) getpeername SOCKET Returns the packed sockaddr address of other end of the SOCKET connection. use Socket; $hersockaddr = getpeername(SOCK); ($port, $iaddr) = unpack_sockaddr_in($hersockaddr); $herhostname = gethostbyaddr($iaddr, AF_INET); $herstraddr = inet_ntoa($iaddr); getpgrp PID Returns the current process group for the specified PID, 0 for the current process. Will raise an exception if used on a machine that doesn't implement _g_e_t_p_g_r_p(2). If PID is omitted, returns process group of current process. getppid Returns the process id of the parent process. getpriority WHICH,WHO Returns the current priority for a process, a process group, or a user. (See the _g_e_t_p_r_i_o_r_i_t_y(_2) manpage.) Will raise a fatal exception if used on a machine that doesn't implement _g_e_t_p_r_i_o_r_i_t_y(2). getpwnam NAME getgrnam NAME gethostbyname NAME getnetbyname NAME getprotobyname NAME getpwuid UID getgrgid GID getservbyname NAME,PROTO gethostbyaddr ADDR,ADDRTYPE getnetbyaddr ADDR,ADDRTYPE getprotobynumber NUMBER getservbyport PORT,PROTO getpwent 25/Mar/96 Last change: perl 5.003 with 24 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) getgrent gethostent getnetent getprotoent getservent setpwent setgrent sethostent STAYOPEN setnetent STAYOPEN setprotoent STAYOPEN setservent STAYOPEN endpwent endgrent endhostent endnetent endprotoent endservent These routines perform the same functions as their counterparts in the system library. Within a list context, the return values from the various get routines are as follows: ($name,$passwd,$uid,$gid, $quota,$comment,$gcos,$dir,$shell) = getpw* ($name,$passwd,$gid,$members) = getgr* ($name,$aliases,$addrtype,$length,@addrs) = gethost* ($name,$aliases,$addrtype,$net) = getnet* ($name,$aliases,$proto) = getproto* ($name,$aliases,$port,$proto) = getserv* (If the entry doesn't exist you get a null list.) Within a scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. (If the entry doesn't exist you get the undefined value.) For 25/Mar/96 Last change: perl 5.003 with 25 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) example: $uid = getpwnam $name = getpwuid $name = getpwent $gid = getgrnam $name = getgrgid $name = getgrent etc. The $members value returned by _g_e_t_g_r*() is a space separated list of the login names of the members of the group. For the _g_e_t_h_o_s_t*() functions, if the h_errno variable is supported in C, it will be returned to you via $? if the function call fails. The @addrs value returned by a successful call is a list of the raw addresses returned by the corresponding system library call. In the Internet domain, each address is four bytes long and you can unpack it by saying something like: ($a,$b,$c,$d) = unpack('C4',$addr[0]); getsockname SOCKET Returns the packed sockaddr address of this end of the SOCKET connection. use Socket; $mysockaddr = getsockname(SOCK); ($port, $myaddr) = unpack_sockaddr_in($mysockaddr); getsockopt SOCKET,LEVEL,OPTNAME Returns the socket option requested, or undefined if there is an error. glob EXPR Returns the value of EXPR with filename expansions such as a shell would do. This is the internal function implementing the <*.*> operator, except it's easier to use. gmtime EXPR Converts a time as returned by the time function to a 9-element array with the time localized for the standard Greenwich timezone. Typically used as follows: 25/Mar/96 Last change: perl 5.003 with 26 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time); All array elements are numeric, and come straight out of a struct tm. In particular this means that $mon has the range 0..11 and $wday has the range 0..6. If EXPR is omitted, does gmtime(time()). goto LABEL goto EXPR goto &NAME The goto-LABEL form finds the statement labeled with LABEL and resumes execution there. It may not be used to go into any construct that requires initialization, such as a subroutine or a foreach loop. It also can't be used to go into a construct that is optimized away. It can be used to go almost anywhere else within the dynamic scope, including out of subroutines, but it's usually better to use some other construct such as last or die. The author of Perl has never felt the need to use this form of goto (in Perl, that is--C is another matter). The goto-EXPR form expects a label name, whose scope will be resolved dynamically. This allows for computed gotos per FORTRAN, but isn't necessarily recommended if you're optimizing for maintainability: goto ("FOO", "BAR", "GLARCH")[$i]; The goto-&NAME form is highly magical, and substitutes a call to the named subroutine for the currently running subroutine. This is used by AUTOLOAD subroutines that wish to load another subroutine and then pretend that the other subroutine had been called in the first place (except that any modifications to @_ in the current subroutine are propagated to the other subroutine.) After the goto, not even _c_a_l_l_e_r() will be able to tell that this routine was called first. grep BLOCK LIST grep EXPR,LIST Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each element) and returns the list value consisting of those elements for which the expression evaluated to TRUE. In a scalar 25/Mar/96 Last change: perl 5.003 with 27 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) context, returns the number of times the expression was TRUE. @foo = grep(!/^#/, @bar); # weed out comments or equivalently, @foo = grep {!/^#/} @bar; # weed out comments Note that, since $_ is a reference into the list value, it can be used to modify the elements of the array. While this is useful and supported, it can cause bizarre results if the LIST is not a named array. hex EXPR Interprets EXPR as a hex string and returns the corresponding decimal value. (To convert strings that might start with 0 or 0x see _o_c_t().) If EXPR is omitted, uses $_. import There is no built-in _i_m_p_o_r_t() function. It is merely an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The _u_s_e() function calls the _i_m_p_o_r_t() method for the package used. See also the use entry elsewhere in this documentthe _p_e_r_l_m_o_d manpage, and the _E_x_p_o_r_t_e_r manpage. index STR,SUBSTR,POSITION index STR,SUBSTR Returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. The return value is based at 0 (or whatever you've set the $[ variable to--but don't do that). If the substring is not found, returns one less than the base, ordinarily -1. int EXPR Returns the integer portion of EXPR. If EXPR is omitted, uses $_. ioctl FILEHANDLE,FUNCTION,SCALAR Implements the _i_o_c_t_l(2) function. You'll probably have to say require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph first to get the correct function definitions. If _i_o_c_t_l._p_h doesn't exist or doesn't have the correct 25/Mar/96 Last change: perl 5.003 with 28 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) definitions you'll have to roll your own, based on your C header files such as <_s_y_s/_i_o_c_t_l._h>. (There is a Perl script called hhhh2222pppphhhh that comes with the Perl kit which may help you in this, but it's non- trivial.) SCALAR will be read and/or written depending on the FUNCTION--a pointer to the string value of SCALAR will be passed as the third argument of the actual ioctl call. (If SCALAR has no string value but does have a numeric value, that value will be passed rather than a pointer to the string value. To guarantee this to be TRUE, add a 0 to the scalar before using it.) The _p_a_c_k() and _u_n_p_a_c_k() functions are useful for manipulating the values of structures used by _i_o_c_t_l(). The following example sets the erase character to DEL. require 'ioctl.ph'; $getp = &TIOCGETP; die "NO TIOCGETP" if $@ || !$getp; $sgttyb_t = "ccccs"; # 4 chars and a short if (ioctl(STDIN,$getp,$sgttyb)) { @ary = unpack($sgttyb_t,$sgttyb); $ary[2] = 127; $sgttyb = pack($sgttyb_t,@ary); ioctl(STDIN,&TIOCSETP,$sgttyb) || die "Can't ioctl: $!"; } The return value of ioctl (and fcntl) is as follows: if OS returns: then Perl returns: -1 undefined value 0 string "0 but true" anything else that number Thus Perl returns TRUE on success and FALSE on failure, yet you can still easily determine the actual value returned by the operating system: ($retval = ioctl(...)) || ($retval = -1); printf "System returned %d\n", $retval; join EXPR,LIST Joins the separate strings of LIST or ARRAY into a single string with fields separated by the value of EXPR, and returns the string. Example: $_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); See the split entry in the _p_e_r_l_f_u_n_c manpage. 25/Mar/96 Last change: perl 5.003 with 29 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) keys ASSOC_ARRAY Returns a normal array consisting of all the keys of the named associative array. (In a scalar context, returns the number of keys.) The keys are returned in an apparently random order, but it is the same order as either the _v_a_l_u_e_s() or _e_a_c_h() function produces (given that the associative array has not been modified). Here is yet another way to print your environment: @keys = keys %ENV; @values = values %ENV; while ($#keys >= 0) { print pop(@keys), '=', pop(@values), "\n"; } or how about sorted by key: foreach $key (sort(keys %ENV)) { print $key, '=', $ENV{$key}, "\n"; } To sort an array by value, you'll need to use a sort{} function. Here's a descending numeric sort of a hash by its values: foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash)) { printf "%4d %s\n", $hash{$key}, $key; } kill LIST Sends a signal to a list of processes. The first element of the list must be the signal to send. Returns the number of processes successfully signaled. $cnt = kill 1, $child1, $child2; kill 9, @goners; Unlike in the shell, in Perl if the _S_I_G_N_A_L is negative, it kills process groups instead of processes. (On System V, a negative _P_R_O_C_E_S_S number will also kill process groups, but that's not portable.) That means you usually want to use positive not negative signals. You may also use a signal name in quotes. See the the section on _S_i_g_n_a_l_s in the _p_e_r_l_i_p_c manpage man page for details. last LABEL 25/Mar/96 Last change: perl 5.003 with 30 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) last The last command is like the break statement in C (as used in loops); it immediately exits the loop in question. If the LABEL is omitted, the command refers to the innermost enclosing loop. The continue block, if any, is not executed: LINE: while () { last LINE if /^$/; # exit when done with header ... } lc EXPR Returns an lowercased version of EXPR. This is the internal function implementing the \L escape in double-quoted strings. Should respect any POSIX _s_e_t_l_o_c_a_l_e() settings. lcfirst EXPR Returns the value of EXPR with the first character lowercased. This is the internal function implementing the \l escape in double-quoted strings. Should respect any POSIX _s_e_t_l_o_c_a_l_e() settings. length EXPR Returns the length in characters of the value of EXPR. If EXPR is omitted, returns length of $_. link OLDFILE,NEWFILE Creates a new filename linked to the old filename. Returns 1 for success, 0 otherwise. listen SOCKET,QUEUESIZE Does the same thing that the listen system call does. Returns TRUE if it succeeded, FALSE otherwise. See example in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage. local EXPR A local modifies the listed variables to be local to the enclosing block, subroutine, eval{} or do. If more than one value is listed, the list must be placed in parens. See L for details. But you really probably want to be using _m_y() instead, because _l_o_c_a_l() isn't what most people think of as "local"). See L for details. localtime EXPR Converts a time as returned by the time function to a 9-element array with the time analyzed for the 25/Mar/96 Last change: perl 5.003 with 31 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) local timezone. Typically used as follows: ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); All array elements are numeric, and come straight out of a struct tm. In particular this means that $mon has the range 0..11 and $wday has the range 0..6. If EXPR is omitted, does _l_o_c_a_l_t_i_m_e(time). In a scalar context, prints out the _c_t_i_m_e(3) value: $now_string = localtime; # e.g. "Thu Oct 13 04:54:34 1994" Also see the _t_i_m_e_l_o_c_a_l._p_l library, and the _s_t_r_f_t_i_m_e(3) function available via the POSIX modulie. log EXPR Returns logarithm (base _e) of EXPR. If EXPR is omitted, returns log of $_. lstat FILEHANDLE lstat EXPR Does the same thing as the _s_t_a_t() function, but stats a symbolic link instead of the file the symbolic link points to. If symbolic links are unimplemented on your system, a normal _s_t_a_t() is done. m// The match operator. See the _p_e_r_l_o_p manpage. map BLOCK LIST map EXPR,LIST Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each element) and returns the list value composed of the results of each such evaluation. Evaluates BLOCK or EXPR in a list context, so each element of LIST may produce zero, one, or more elements in the returned value. @chars = map(chr, @nums); translates a list of numbers to the corresponding characters. And %hash = map { getkey($_) => $_ } @array; is just a funny way to write 25/Mar/96 Last change: perl 5.003 with 32 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) %hash = (); foreach $_ (@array) { $hash{getkey($_)} = $_; } mkdir FILENAME,MODE Creates the directory specified by FILENAME, with permissions specified by MODE (as modified by umask). If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno). msgctl ID,CMD,ARG Calls the System V IPC function _m_s_g_c_t_l(2). If CMD is &IPC_STAT, then ARG must be a variable which will hold the returned msqid_ds structure. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. msgget KEY,FLAGS Calls the System V IPC function _m_s_g_g_e_t(2). Returns the message queue id, or the undefined value if there is an error. msgsnd ID,MSG,FLAGS Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the long integer message type, which may be created with pack("l", $type). Returns TRUE if successful, or FALSE if there is an error. msgrcv ID,VAR,SIZE,TYPE,FLAGS Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of SIZE. Note that if a message is received, the message type will be the first thing in VAR, and the maximum length of VAR is SIZE plus the size of the message type. Returns TRUE if successful, or FALSE if there is an error. my EXPR A "my" declares the listed variables to be local (lexically) to the enclosing block, subroutine, eval, or do/require/use'd file. If more than one value is listed, the list must be placed in parens. See the section on _P_r_i_v_a_t_e _V_a_r_i_a_b_l_e_s _v_i_a _m_y() in the _p_e_r_l_s_u_b manpage for details. next LABEL next The next command is like the continue statement in C; it starts the next iteration of the loop: 25/Mar/96 Last change: perl 5.003 with 33 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) LINE: while () { next LINE if /^#/; # discard comments ... } Note that if there were a continue block on the above, it would get executed even on discarded lines. If the LABEL is omitted, the command refers to the innermost enclosing loop. no Module LIST See the "use" function, which "no" is the opposite of. oct EXPR Interprets EXPR as an octal string and returns the corresponding decimal value. (If EXPR happens to start off with 0x, interprets it as a hex string instead.) The following will handle decimal, octal, and hex in the standard Perl or C notation: $val = oct($val) if $val =~ /^0/; If EXPR is omitted, uses $_. open FILEHANDLE,EXPR open FILEHANDLE Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. If the filename begins with "<" or nothing, the file is opened for input. If the filename begins with ">", the file is opened for output. If the filename begins with ">>", the file is opened for appending. You can put a '+' in front of the '>' or '<' to indicate that you want both read and write access to the file; thus '+<' is usually preferred for read/write updates--the '+>' mode would clobber the file first. These correspond to the _f_o_p_e_n(3) modes of 'r', 'r+', 'w', 'w+', 'a', and 'a+'. If the filename begins with "|", the filename is interpreted as a command to which output is to be piped, and if the filename ends with a "|", the filename is interpreted See the section on _U_s_i_n_g _o_p_e_n() _f_o_r _I_P_C in the _p_e_r_l_i_p_c manpage for more examples of this. as command which pipes input to us. (You may not have a raw _o_p_e_n() to a command 25/Mar/96 Last change: perl 5.003 with 34 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) that pipes both in _a_n_d out, but see See the _o_p_e_n_2 manpage, the _o_p_e_n_3 manpage, and the section on _B_i_d_i_r_e_c_t_i_o_n_a_l _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage for alternatives.) Opening '-' opens STDIN and opening '>-' opens STDOUT. Open returns non-zero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the pid of the subprocess. If you're unfortunate enough to be running Perl on a system that distinguishes between text files and binary files (modern operating systems don't care), then you should check out the binmode entry elsewhere in this documentfor tips for dealing with this. The key distinction between systems that need binmode and those that don't is their text file formats. Systems like Unix and Plan9 that delimit lines with a single character, and that encode that character in C as '\n', do not need binmode. The rest need it. Examples: $ARTICLE = 100; open ARTICLE or die "Can't find article $ARTICLE: $!\n"; while (
) {... open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) open(DBASE, '+/tmp/Tmp$$"); # $$ is our process id # process argument list of files along with any includes foreach $file (@ARGV) { process($file, 'fh00'); } sub process { local($filename, $input) = @_; $input++; # this is a string increment unless (open($input, $filename)) { print STDERR "Can't open $filename: $!\n"; return; } 25/Mar/96 Last change: perl 5.003 with 35 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) while (<$input>) { # note use of indirection if (/^#include "(.*)"/) { process($1, $input); next; } ... # whatever } } You may also, in the Bourne shell tradition, specify an EXPR beginning with ">&", in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) which is to be duped and opened. You may use & after >, >>, <, +>, +>> and +<. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into acount any existing contents of stdio buffers.) Here is a script that saves, redirects, and restores STDOUT and STDERR: #!/usr/bin/perl open(SAVEOUT, ">&STDOUT"); open(SAVEERR, ">&STDERR"); open(STDOUT, ">foo.out") || die "Can't redirect stdout"; open(STDERR, ">&STDOUT") || die "Can't dup stdout"; select(STDERR); $| = 1; # make unbuffered select(STDOUT); $| = 1; # make unbuffered print STDOUT "stdout 1\n"; # this works for print STDERR "stderr 1\n"; # subprocesses too close(STDOUT); close(STDERR); open(STDOUT, ">&SAVEOUT"); open(STDERR, ">&SAVEERR"); print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; If you specify "<&=N", where N is a number, then Perl will do an equivalent of C's _f_d_o_p_e_n() of that file descriptor; this is more parsimonious of file descriptors. For example: open(FILEHANDLE, "<&=$fd") If you open a pipe on the command "-", i.e. either "|-" or "-|", then there is an implicit fork done, and the return value of open is the pid of the child 25/Mar/96 Last change: perl 5.003 with 36 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) within the parent process, and 0 within the child process. (Use _d_e_f_i_n_e_d($pid) to determine whether the open was successful.) The filehandle behaves normally for the parent, but i/o to that filehandle is piped from/to the STDOUT/STDIN of the child process. In the child process the filehandle isn't opened--i/o happens from/to the new STDOUT or STDIN. Typically this is used like the normal piped open when you want to exercise more control over just how the pipe command gets executed, such as when you are running setuid, and don't want to have to scan shell commands for metacharacters. The following pairs are more or less equivalent: open(FOO, "|tr '[a-z]' '[A-Z]'"); open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]'; open(FOO, "cat -n '$file'|"); open(FOO, "-|") || exec 'cat', '-n', $file; See the section on _S_a_f_e _P_i_p_e _O_p_e_n_s in the _p_e_r_l_i_p_c manpage for more examples of this. Explicitly closing any piped filehandle causes the parent process to wait for the child to finish, and returns the status value in $?. Note: on any operation which may do a fork, unflushed buffers remain unflushed in both processes, which means you may need to set $| to avoid duplicate output. Using the FileHandle constructor from the FileHandle package, you can generate anonymous filehandles which have the scope of whatever variables hold references to them, and automatically close whenever and however you leave that scope: use FileHandle; ... sub read_myfile_munged { my $ALL = shift; my $handle = new FileHandle; open($handle, "myfile") or die "myfile: $!"; $first = <$handle> or return (); # Automatically closed here. mung $first or die "mung failed"; # Or here. return $first, <$handle> if $ALL; # Or here. $first; # Or here. } The filename that is passed to open will have leading and trailing whitespace deleted. In order to open a file with arbitrary weird characters in 25/Mar/96 Last change: perl 5.003 with 37 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) it, it's necessary to protect any leading and trailing whitespace thusly: $file =~ s#^(\s)#./$1#; open(FOO, "< $file\0"); If you want a "real" C _o_p_e_n() (see the _o_p_e_n(_2) manpage on your system), then you should use the _s_y_s_o_p_e_n() function. This is another way to protect your filenames from interpretation. For example: use FileHandle; sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL, 0700) or die "sysopen $path: $!"; HANDLE->autoflush(1); HANDLE->print("stuff $$\n"); seek(HANDLE, 0, 0); print "File contains: ", ; See the seek() entry elsewhere in this documentfor some details about mixing reading and writing. opendir DIRHANDLE,EXPR Opens a directory named EXPR for processing by _r_e_a_d_d_i_r(), _t_e_l_l_d_i_r(), _s_e_e_k_d_i_r(), _r_e_w_i_n_d_d_i_r() and _c_l_o_s_e_d_i_r(). Returns TRUE if successful. DIRHANDLEs have their own namespace separate from FILEHANDLEs. ord EXPR Returns the numeric ascii value of the first character of EXPR. If EXPR is omitted, uses $_. pack TEMPLATE,LIST Takes an array or list of values and packs it into a binary structure, returning the string containing the structure. The TEMPLATE is a sequence of characters that give the order and type of values, as follows: A An ascii string, will be space padded. a An ascii string, will be null padded. b A bit string (ascending bit order, like vec()). B A bit string (descending bit order). h A hex string (low nybble first). H A hex string (high nybble first). 25/Mar/96 Last change: perl 5.003 with 38 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) c A signed char value. C An unsigned char value. s A signed short value. S An unsigned short value. i A signed integer value. I An unsigned integer value. l A signed long value. L An unsigned long value. n A short in "network" order. N A long in "network" order. v A short in "VAX" (little-endian) order. V A long in "VAX" (little-endian) order. f A single-precision float in the native format. d A double-precision float in the native format. p A pointer to a null-terminated string. P A pointer to a structure (fixed-length string). u A uuencoded string. x A null byte. X Back up a byte. @ Null fill to absolute position. Each letter may optionally be followed by a number which gives a repeat count. With all types except "a", "A", "b", "B", "h" and "H", and "P" the pack function will gobble up that many values from the LIST. A * for the repeat count means to use however many items are left. The "a" and "A" types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as necessary. (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) Likewise, the "b" and "B" fields pack a string that many bits long. The "h" and "H" fields pack a string that many nybbles long. The "P" packs a pointer to a structure of the size indicated by the length. Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats around, and the lack of a standard "network" representation, no facility for interchange has been made. This means that packed floating point data written on one machine may not be readable on another - even if both use IEEE floating point arithmetic (as the endian-ness of the memory representation is not part of the IEEE spec). Note that Perl uses doubles internally for all numeric calculation, and converting from double into float and thence back to double again will lose precision (i.e. unpack("f", 25/Mar/96 Last change: perl 5.003 with 39 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) pack("f", $foo)) will not in general equal $foo). Examples: $foo = pack("cccc",65,66,67,68); # foo eq "ABCD" $foo = pack("c4",65,66,67,68); # same thing $foo = pack("ccxxcc",65,66,67,68); # foo eq "AB\0\0CD" $foo = pack("s2",1,2); # "\1\0\2\0" on little-endian # "\0\1\0\2" on big-endian $foo = pack("a4","abcd","x","y","z"); # "abcd" $foo = pack("aaaa","abcd","x","y","z"); # "axyz" $foo = pack("a14","abcdefg"); # "abcdefg\0\0\0\0\0\0\0" $foo = pack("i9pl", gmtime); # a real struct tm (on my system anyway) sub bintodec { unpack("N", pack("B32", substr("0" x 32 . shift, -32))); } The same template may generally also be used in the unpack function. package NAMESPACE Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block (the same scope as the _l_o_c_a_l() operator). All further unqualified dynamic identifiers will be in this namespace. A package statement only affects dynamic variables--including those you've used _l_o_c_a_l() on--but _n_o_t lexical variables created with _m_y(). Typically it would be the first declaration in a file to be included by the require or use operator. You can switch into a package in more than one place; it merely influences which symbol table is used by the compiler for the rest of that block. You can refer to variables and filehandles in other packages by prefixing the identifier with the package name and a double colon: 25/Mar/96 Last change: perl 5.003 with 40 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) $Package::Variable. If the package name is null, the main package as assumed. That is, $::sail is equivalent to $main::sail. See the section on _P_a_c_k_a_g_e_s in the _p_e_r_l_m_o_d manpage for more information about packages, modules, and classes. See the _p_e_r_l_s_u_b manpage for other scoping issues. pipe READHANDLE,WRITEHANDLE Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur unless you are very careful. In addition, note that Perl's pipes use stdio buffering, so you may need to set $| to flush your WRITEHANDLE after each command, depending on the application. See the _o_p_e_n_2 manpage, the _o_p_e_n_3 manpage, and the section on _B_i_d_i_r_e_c_t_i_o_n_a_l _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage for examples of such things. pop ARRAY Pops and returns the last value of the array, shortening the array by 1. Has a similar effect to $tmp = $ARRAY[$#ARRAY--]; If there are no elements in the array, returns the undefined value. If ARRAY is omitted, pops the @ARGV array in the main program, and the @_ array in subroutines, just like _s_h_i_f_t(). pos SCALAR Returns the offset of where the last m//g search left off for the variable in question. May be modified to change that offset. print FILEHANDLE LIST print LIST print Prints a string or a comma-separated list of strings. Returns TRUE if successful. FILEHANDLE may be a scalar variable name, in which case the variable contains the name of or a reference to the filehandle, thus introducing one level of indirection. (NOTE: If FILEHANDLE is a variable and the next token is a term, it may be misinterpreted as an operator unless you interpose a + or put parens around the arguments.) If FILEHANDLE is omitted, prints by default to standard output (or to 25/Mar/96 Last change: perl 5.003 with 41 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) the last selected output channel--see _s_e_l_e_c_t()). If LIST is also omitted, prints $_ to STDOUT. To set the default output channel to something other than STDOUT use the select operation. Note that, because print takes a LIST, anything in the LIST is evaluated in a list context, and any subroutine that you call will have one or more of its expressions evaluated in a list context. Also be careful not to follow the print keyword with a left parenthesis unless you want the corresponding right parenthesis to terminate the arguments to the print--interpose a + or put parens around all the arguments. Note that if you're storing FILEHANDLES in an array or other expression, you will have to use a block returning its value instead print { $files[$i] } "stuff\n"; print { $OK ? STDOUT : STDERR } "stuff\n"; printf FILEHANDLE LIST printf LIST Equivalent to a "print FILEHANDLE _s_p_r_i_n_t_f(LIST)". The first argument of the list will be interpreted as the printf format. push ARRAY,LIST Treats ARRAY as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of LIST. Has the same effect as for $value (LIST) { $ARRAY[++$#ARRAY] = $value; } but is more efficient. Returns the new number of elements in the array. q/STRING/ qq/STRING/ qx/STRING/ qw/STRING/ Generalized quotes. See the _p_e_r_l_o_p manpage. quotemeta EXPR Returns the value of EXPR with with all regular 25/Mar/96 Last change: perl 5.003 with 42 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) expression metacharacters backslashed. This is the internal function implementing the \Q escape in double-quoted strings. rand EXPR rand Returns a random fractional number between 0 and the value of EXPR. (EXPR should be positive.) If EXPR is omitted, returns a value between 0 and 1. This function produces repeatable sequences unless _s_r_a_n_d() is invoked. See also _s_r_a_n_d(). (Note: if your rand function consistently returns numbers that are too large or too small, then your version of Perl was probably compiled with the wrong number of RANDBITS. As a workaround, you can usually multiply EXPR by the correct power of 2 to get the range you want. This will make your script unportable, however. It's better to recompile if you can.) read FILEHANDLE,SCALAR,LENGTH,OFFSET read FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE. Returns the number of bytes actually read, or undef if there was an error. SCALAR will be grown or shrunk to the length actually read. An OFFSET may be specified to place the read data at some other place than the beginning of the string. This call is actually implemented in terms of stdio's fread call. To get a true read system call, see _s_y_s_r_e_a_d(). readdir DIRHANDLE Returns the next directory entry for a directory opened by _o_p_e_n_d_i_r(). If used in a list context, returns all the rest of the entries in the directory. If there are no more entries, returns an undefined value in a scalar context or a null list in a list context. If you're planning to filetest the return values out of a _r_e_a_d_d_i_r(), you'd better prepend the directory in question. Otherwise, since we didn't _c_h_d_i_r() there, it would have been testing the wrong file. opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!"; @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR); closedir DIR; 25/Mar/96 Last change: perl 5.003 with 43 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) readlink EXPR Returns the value of a symbolic link, if symbolic links are implemented. If not, gives a fatal error. If there is some system error, returns the undefined value and sets $! (errno). If EXPR is omitted, uses $_. recv SOCKET,SCALAR,LEN,FLAGS Receives a message on a socket. Attempts to receive LENGTH bytes of data into variable SCALAR from the specified SOCKET filehandle. Actually does a C _r_e_c_v_f_r_o_m(), so that it can returns the address of the sender. Returns the undefined value if there's an error. SCALAR will be grown or shrunk to the length actually read. Takes the same flags as the system call of the same name. See the section on _U_D_P: _M_e_s_s_a_g_e _P_a_s_s_i_n_g in the _p_e_r_l_i_p_c manpage for examples. redo LABEL redo The redo command restarts the loop block without evaluating the conditional again. The continue block, if any, is not executed. If the LABEL is omitted, the command refers to the innermost enclosing loop. This command is normally used by programs that want to lie to themselves about what was just input: # a simpleminded Pascal comment stripper # (warning: assumes no { or } in strings) LINE: while () { while (s|({.*}.*){.*}|$1 |) {} s|{.*}| |; if (s|{.*| |) { $front = $_; while () { if (/}/) { # end of comment? s|^|$front{|; redo LINE; } } } print; } ref EXPR Returns a TRUE value if EXPR is a reference, FALSE otherwise. The value returned depends on the type of thing the reference is a reference to. Builtin types include: 25/Mar/96 Last change: perl 5.003 with 44 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) REF SCALAR ARRAY HASH CODE GLOB If the referenced object has been blessed into a package, then that package name is returned instead. You can think of _r_e_f() as a _t_y_p_e_o_f() operator. if (ref($r) eq "HASH") { print "r is a reference to an associative array.\n"; } if (!ref ($r) { print "r is not a reference at all.\n"; } See also the _p_e_r_l_r_e_f manpage. rename OLDNAME,NEWNAME Changes the name of a file. Returns 1 for success, 0 otherwise. Will not work across filesystem boundaries. require EXPR require Demands some semantics specified by EXPR, or by $_ if EXPR is not supplied. If EXPR is numeric, demands that the current version of Perl ($] or $PERL_VERSION) be equal or greater than EXPR. Otherwise, demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is essentially just a variety of _e_v_a_l(). Has semantics similar to the following subroutine: 25/Mar/96 Last change: perl 5.003 with 45 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) sub require { local($filename) = @_; return 1 if $INC{$filename}; local($realfilename,$result); ITER: { foreach $prefix (@INC) { $realfilename = "$prefix/$filename"; if (-f $realfilename) { $result = do $realfilename; last ITER; } } die "Can't find $filename in \@INC"; } die $@ if $@; die "$filename did not return true value" unless $result; $INC{$filename} = $realfilename; $result; } Note that the file will not be included twice under the same specified name. The file must return TRUE as the last statement to indicate successful execution of any initialization code, so it's customary to end such a file with "1;" unless you're sure it'll return TRUE otherwise. But it's better just to put the "1;", in case you add more statements. If EXPR is a bare word, the require assumes a "._p_m" extension for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace. For a yet-more-powerful import facility, see the the use() entry elsewhere in this documentthe _p_e_r_l_m_o_d manpage. reset EXPR reset Generally used in a continue block at the end of a loop to clear variables and reset ?? searches so that they work again. The expression is interpreted as a list of single characters (hyphens allowed for ranges). All variables and arrays beginning with one of those letters are reset to their pristine state. If the expression is omitted, one-match searches (?pattern?) are reset to match again. Only resets variables or searches in the current package. Always returns 1. Examples: 25/Mar/96 Last change: perl 5.003 with 46 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) reset 'X'; # reset all X variables reset 'a-z'; # reset lower case variables reset; # just reset ?? searches Resetting "A-Z" is not recommended since you'll wipe out your ARGV and ENV arrays. Only resets package variables--lexical variables are unaffected, but they clean themselves up on scope exit anyway, so anymore you probably want to use them instead. See the my entry elsewhere in this document. return LIST Returns from a subroutine or eval with the value specified. (Note that in the absence of a return a subroutine or _e_v_a_l() will automatically return the value of the last expression evaluated.) reverse LIST In a list context, returns a list value consisting of the elements of LIST in the opposite order. In a scalar context, returns a string value consisting of the bytes of the first element of LIST in the opposite order. print reverse <>; # line tac undef $/; print scalar reverse scalar <>; # byte tac rewinddir DIRHANDLE Sets the current position to the beginning of the directory for the _r_e_a_d_d_i_r() routine on DIRHANDLE. rindex STR,SUBSTR,POSITION rindex STR,SUBSTR Works just like index except that it returns the position of the LAST occurrence of SUBSTR in STR. If POSITION is specified, returns the last occurrence at or before that position. rmdir FILENAME Deletes the directory specified by FILENAME if it is empty. If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno). If FILENAME is omitted, uses $_. s/// The substitution operator. See the _p_e_r_l_o_p manpage. scalar EXPR Forces EXPR to be interpreted in a scalar context 25/Mar/96 Last change: perl 5.003 with 47 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) and returns the value of EXPR. @counts = ( scalar @a, scalar @b, scalar @c ); There is no equivalent operator to force an expression to be interpolated in a list context because it's in practice never needed. If you really wanted to do so, however, you could use the construction @{[ (some expression) ]}, but usually a simple (some expression) suffices. seek FILEHANDLE,POSITION,WHENCE Randomly positions the file pointer for FILEHANDLE, just like the _f_s_e_e_k() call of stdio. FILEHANDLE may be an expression whose value gives the name of the filehandle. The values for WHENCE are 0 to set the file pointer to POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for this from POSIX module. Returns 1 upon success, 0 otherwise. On some systems you have to do a seek whenever you switch between reading and writing. Amongst other things, this may have the effect of calling stdio's _c_l_e_a_r_e_r_r(3). A "whence" of 1 (SEEK_CUR) is useful for not moving the file pointer: seek(TEST,0,1); This is also useful for applications emulating tail -f. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a _s_e_e_k() to reset things. First the simple trick listed above to clear the filepointer. The _s_e_e_k() doesn't change the current position, but it _d_o_e_s clear the end-of- file condition on the handle, so that the next makes Perl try again to read something. Hopefully. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: for (;;) { for ($curpos = tell(FILE); $_ = ; $curpos = tell(FILE)) { # search for some stuff and put it into files } sleep($for_a_while); seek(FILE, $curpos, 0); } 25/Mar/96 Last change: perl 5.003 with 48 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) seekdir DIRHANDLE,POS Sets the current position for the _r_e_a_d_d_i_r() routine on DIRHANDLE. POS must be a value returned by _t_e_l_l_d_i_r(). Has the same caveats about possible directory compaction as the corresponding system library routine. select FILEHANDLE select Returns the currently selected filehandle. Sets the current default filehandle for output, if FILEHANDLE is supplied. This has two effects: first, a write or a print without a filehandle will default to this FILEHANDLE. Second, references to variables related to output will refer to this output channel. For example, if you have to set the top of form format for more than one output channel, you might do the following: select(REPORT1); $^ = 'report1_top'; select(REPORT2); $^ = 'report2_top'; FILEHANDLE may be an expression whose value gives the name of the actual filehandle. Thus: $oldfh = select(STDERR); $| = 1; select($oldfh); Some programmers may prefer to think of filehandles as objects with methods, preferring to write the last example as: use FileHandle; STDERR->autoflush(1); select RBITS,WBITS,EBITS,TIMEOUT This calls the _s_e_l_e_c_t(2) system call with the bitmasks specified, which can be constructed using _f_i_l_e_n_o() and _v_e_c(), along these lines: $rin = $win = $ein = ''; vec($rin,fileno(STDIN),1) = 1; vec($win,fileno(STDOUT),1) = 1; $ein = $rin | $win; If you want to select on many filehandles you might wish to write a subroutine: 25/Mar/96 Last change: perl 5.003 with 49 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) sub fhbits { local(@fhlist) = split(' ',$_[0]); local($bits); for (@fhlist) { vec($bits,fileno($_),1) = 1; } $bits; } $rin = fhbits('STDIN TTY SOCK'); The usual idiom is: ($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout); or to block until something becomes ready just do this $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); Most systems do not both to return anything useful in $timeleft, so calling _s_e_l_e_c_t() in a scalar context just returns $nfound. Any of the bitmasks can also be undef. The timeout, if specified, is in seconds, which may be fractional. Note: not all implementations are capable of returning the $timeleft. If not, they always return $timeleft equal to the supplied $timeout. You can effect a 250-microsecond sleep this way: select(undef, undef, undef, 0.25); WWWWAAAARRRRNNNNIIIINNNNGGGG: Do not attempt to mix buffered I/O (like _r_e_a_d() or ) with _s_e_l_e_c_t(). You have to use _s_y_s_r_e_a_d() instead. semctl ID,SEMNUM,CMD,ARG Calls the System V IPC function semctl. If CMD is &IPC_STAT or &GETALL, then ARG must be a variable which will hold the returned semid_ds structure or semaphore value array. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. semget KEY,NSEMS,FLAGS Calls the System V IPC function semget. Returns the semaphore id, or the undefined value if there is an error. 25/Mar/96 Last change: perl 5.003 with 50 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) semop KEY,OPSTRING Calls the System V IPC function semop to perform semaphore operations such as signaling and waiting. OPSTRING must be a packed array of semop structures. Each semop structure can be generated with pack("sss", $semnum, $semop, $semflag). The number of semaphore operations is implied by the length of OPSTRING. Returns TRUE if successful, or FALSE if there is an error. As an example, the following code waits on semaphore $semnum of semaphore id $semid: $semop = pack("sss", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop); To signal the semaphore, replace "-1" with "1". send SOCKET,MSG,FLAGS,TO send SOCKET,MSG,FLAGS Sends a message on a socket. Takes the same flags as the system call of the same name. On unconnected sockets you must specify a destination to send TO, in which case it does a C _s_e_n_d_t_o(). Returns the number of characters sent, or the undefined value if there is an error. See the section on _U_D_P: _M_e_s_s_a_g_e _P_a_s_s_i_n_g in the _p_e_r_l_i_p_c manpage for examples. setpgrp PID,PGRP Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement _s_e_t_p_g_r_p(2). setpriority WHICH,WHO,PRIORITY Sets the current priority for a process, a process group, or a user. (See _s_e_t_p_r_i_o_r_i_t_y(2).) Will produce a fatal error if used on a machine that doesn't implement _s_e_t_p_r_i_o_r_i_t_y(2). setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL Sets the socket option requested. Returns undefined if there is an error. OPTVAL may be specified as undef if you don't want to pass an argument. shift ARRAY shift Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the @ARGV array in the main program, and the 25/Mar/96 Last change: perl 5.003 with 51 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) @_ array in subroutines. (This is determined lexically.) See also _u_n_s_h_i_f_t(), _p_u_s_h(), and _p_o_p(). _S_h_i_f_t() and _u_n_s_h_i_f_t() do the same thing to the left end of an array that _p_u_s_h() and _p_o_p() do to the right end. shmctl ID,CMD,ARG Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG must be a variable which will hold the returned shmid_ds structure. Returns like ioctl: the undefined value for error, "0 but true" for zero, or the actual return value otherwise. shmget KEY,SIZE,FLAGS Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. shmread ID,VAR,POS,SIZE shmwrite ID,STRING,POS,SIZE Reads or writes the System V shared memory segment ID starting at position POS for size SIZE by attaching to it, copying in/out, and detaching from it. When reading, VAR must be a variable which will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return TRUE if successful, or FALSE if there is an error. shutdown SOCKET,HOW Shuts down a socket connection in the manner indicated by HOW, which has the same interpretation as in the system call of the same name. sin EXPR Returns the sine of EXPR (expressed in radians). If EXPR is omitted, returns sine of $_. sleep EXPR sleep Causes the script to sleep for EXPR seconds, or forever if no EXPR. May be interrupted by sending the process a SIGALRM. Returns the number of seconds actually slept. You probably cannot mix _a_l_a_r_m() and _s_l_e_e_p() calls, since _s_l_e_e_p() is often implemented using _a_l_a_r_m(). On some older systems, it may sleep up to a full second less than what you requested, depending on how it counts seconds. Most modern systems always 25/Mar/96 Last change: perl 5.003 with 52 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) sleep the full amount. For delays of finer granularity than one second, you may use Perl's _s_y_s_c_a_l_l() interface to access _s_e_t_i_t_i_m_e_r(2) if your system supports it, or else see the select() entry elsewhere in this documentbelow. socket SOCKET,DOMAIN,TYPE,PROTOCOL Opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE and PROTOCOL are specified the same as for the system call of the same name. You should "use Socket;" first to get the proper definitions imported. See the example in the section on _S_o_c_k_e_t_s: _C_l_i_e_n_t/_S_e_r_v_e_r _C_o_m_m_u_n_i_c_a_t_i_o_n in the _p_e_r_l_i_p_c manpage. socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE and PROTOCOL are specified the same as for the system call of the same name. If unimplemented, yields a fatal error. Returns TRUE if successful. sort SUBNAME LIST sort BLOCK LIST sort LIST Sorts the LIST and returns the sorted list value. Nonexistent values of arrays are stripped out. If SUBNAME or BLOCK is omitted, sorts in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the array are to be ordered. (The <=> and cmp operators are extremely useful in such routines.) SUBNAME may be a scalar variable name, in which case the value provides the name of the subroutine to use. In place of a SUBNAME, you can provide a BLOCK as an anonymous, in-line sort subroutine. In the interests of efficiency the normal calling code for subroutines is bypassed, with the following effects: the subroutine may not be a recursive subroutine, and the two elements to be compared are passed into the subroutine not via @_ but as the package global variables $a and $b (see example below). They are passed by reference, so don't modify $a and $b. And don't try to declare them as lexicals either. 25/Mar/96 Last change: perl 5.003 with 53 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Examples: # sort lexically @articles = sort @files; # same thing, but with explicit sort routine @articles = sort {$a cmp $b} @files; # now case-insensitively @articles = sort { uc($a) cmp uc($b)} @files; # same thing in reversed order @articles = sort {$b cmp $a} @files; # sort numerically ascending @articles = sort {$a <=> $b} @files; # sort numerically descending @articles = sort {$b <=> $a} @files; # sort using explicit subroutine name sub byage { $age{$a} <=> $age{$b}; # presuming integers } @sortedclass = sort byage @class; # this sorts the %age associative arrays by value # instead of key using an inline function @eldest = sort { $age{$b} <=> $age{$a} } keys %age; sub backwards { $b cmp $a; } @harry = ('dog','cat','x','Cain','Abel'); @george = ('gone','chased','yz','Punished','Axed'); print sort @harry; # prints AbelCaincatdogx print sort backwards @harry; # prints xdogcatCainAbel print sort @george, 'to', @harry; # prints AbelAxedCainPunishedcatchaseddoggonetoxyz # inefficiently sort by descending numeric compare using # the first integer after the first = sign, or the # whole record case-insensitively otherwise @new = sort { ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0] || uc($a) cmp uc($b) } @old; 25/Mar/96 Last change: perl 5.003 with 54 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) # same thing, but much more efficiently; # we'll build auxiliary indices instead # for speed @nums = @caps = (); for (@old) { push @nums, /=(\d+)/; push @caps, uc($_); } @new = @old[ sort { $nums[$b] <=> $nums[$a] || $caps[$a] cmp $caps[$b] } 0..$#old ]; # same thing using a Schwartzian Transform (no temps) @new = map { $_->[0] } sort { $b->[1] <=> $a->[1] || $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; If you're and using strict, you _M_U_S_T _N_O_T declare $a and $b as lexicals. They are package globals. That means if you're in the main package, it's @articles = sort {$main::b <=> $main::a} @files; or just @articles = sort {$::b <=> $::a} @files; but if you're in the FooPack package, it's @articles = sort {$FooPack::b <=> $FooPack::a} @files; splice ARRAY,OFFSET,LENGTH,LIST splice ARRAY,OFFSET,LENGTH splice ARRAY,OFFSET Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. Returns the elements removed from the array. The array grows or shrinks as necessary. If LENGTH is omitted, removes everything from OFFSET onward. The following equivalencies hold (assuming $[ == 0): 25/Mar/96 Last change: perl 5.003 with 55 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y) pop(@a) splice(@a,-1) shift(@a) splice(@a,0,1) unshift(@a,$x,$y) splice(@a,0,0,$x,$y) $a[$x] = $y splice(@a,$x,1,$y); Example, assuming array lengths are passed before arrays: sub aeq { # compare two list values local(@a) = splice(@_,0,shift); local(@b) = splice(@_,0,shift); return 0 unless @a == @b; # same len? while (@a) { return 0 if pop(@a) ne pop(@b); } return 1; } if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } split /PATTERN/,EXPR,LIMIT split /PATTERN/,EXPR split /PATTERN/ split Splits a string into an array of strings, and returns it. If not in a list context, returns the number of fields found and splits into the @_ array. (In a list context, you can force the split into @_ by using ?? as the pattern delimiters, but it still returns the array value.) The use of implicit split to @_ is deprecated, however. If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything matching PATTERN is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.) If LIMIT is specified and is not negative, splits into no more than that many fields (though it may split into fewer). If LIMIT is unspecified, trailing null fields are stripped (which potential users of _p_o_p() would do well to remember). If LIMIT is negative, it is treated as if an arbitrarily large LIMIT had been specified. A pattern matching the null string (not to be confused with a null pattern //, which is just one 25/Mar/96 Last change: perl 5.003 with 56 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example: print join(':', split(/ */, 'hi there')); produces the output 'h:i:t:h:e:r:e'. The LIMIT parameter can be used to partially split a line ($login, $passwd, $remainder) = split(/:/, $_, 3); When assigning to a list, if LIMIT is omitted, Perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need. If the PATTERN contains parentheses, additional array elements are created from each matching substring in the delimiter. split(/([,-])/, "1-10,20"); produces the list value (1, '-', 10, ',', 20) If you had the entire header of a normal Unix email message in $header, you could split it up into fields and their values this way: $header =~ s/\n\s+/ /g; # fix continuation lines %hdrs = (UNIX_FROM => split /^(.*?):\s*/m, $header); The pattern /PATTERN/ may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, use /$variable/o.) As a special case, specifying a PATTERN of space (' ') will split on white space just as split with no arguments does. Thus, split(' ') can be used to emulate aaaawwwwkkkk's default behavior, whereas split(/ /) will give you as many null initial fields as there are leading spaces. A split on /\s+/ is like a split(' ') except that any leading whitespace produces a null first field. A split with no 25/Mar/96 Last change: perl 5.003 with 57 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) arguments really does a split(' ', $_) internally. Example: open(passwd, '/etc/passwd'); while () { ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); ... } (Note that $shell above will still have a newline on it. See the chop, chomp, and join entries elsewhere in this document.) sprintf FORMAT,LIST Returns a string formatted by the usual printf conventions of the C language. See the _s_p_r_i_n_t_f(_3) manpage or the _p_r_i_n_t_f(_3) manpage on your system for details. (The * character for an indirectly specified length is not supported, but you can get the same effect by interpolating a variable into the pattern.) Some C libraries' implementations of _s_p_r_i_n_t_f() can dump core when fed ludicrous arguments. sqrt EXPR Return the square root of EXPR. If EXPR is omitted, returns square root of $_. srand EXPR Sets the random number seed for the rand operator. If EXPR is omitted, does srand(time). Many folks use an explicit srand(time ^ $$) instead. Of course, you'd need something much more random than that for cryptographic purposes, since it's easy to guess the current time. Checksumming the compressed output of rapidly changing operating system status programs is the usual method. Examples are posted regularly to the comp.security.unix newsgroup. stat FILEHANDLE stat EXPR Returns a 13-element array giving the status info for a file, either the file opened via FILEHANDLE, or named by EXPR. Returns a null list if the stat fails. Typically used as follows: ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, $atime,$mtime,$ctime,$blksize,$blocks) = stat($filename); 25/Mar/96 Last change: perl 5.003 with 58 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Not all fields are supported on all filesystem types. Here are the meaning of the fields: dev device number of filesystem ino inode number mode file mode (type and permissions) nlink number of (hard) links to the file uid numeric user ID of file's owner gid numer group ID of file's owner rdev the device identifier (special files only) size total size of file, in bytes atime last access time since the epoch mtime last modify time since the epoch ctime inode change time (NOT creation type!) since the epoch blksize preferred blocksize for file system I/O blocks actual number of blocks allocated (The epoch was at 00:00 January 1, 1970 GMT.) If stat is passed the special filehandle consisting of an underline, no stat is done, but the current contents of the stat structure from the last stat or filetest are returned. Example: if (-x $file && (($d) = stat(_)) && $d < 0) { print "$file is executable NFS file\n"; } (This only works on machines for which the device number is negative under NFS.) study SCALAR study Takes extra time to study SCALAR ($_ if unspecified) in anticipation of doing many pattern matches on the string before it is next modified. This may or may not save time, depending on the nature and number of patterns you are searching on, and on the distribution of character frequencies in the string to be searched--you probably want to compare runtimes with and without it to see which runs faster. Those loops which scan for many short constant strings (including the constant parts of more complex patterns) will benefit most. You may have only one study active at a time--if you study a different scalar the first is "unstudied". (The way study works is this: a linked list of every character in the string to be searched is made, so we know, for example, where all the 'k' characters are. From each search string, the rarest character is selected, based on some static frequency tables constructed from some C programs and English text. 25/Mar/96 Last change: perl 5.003 with 59 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Only those places that contain this "rarest" character are examined.) For example, here is a loop which inserts index producing entries before any line containing a certain pattern: while (<>) { study; print ".IX foo\n" if /\bfoo\b/; print ".IX bar\n" if /\bbar\b/; print ".IX blurfl\n" if /\bblurfl\b/; ... print; } In searching for /\bfoo\b/, only those locations in $_ that contain "f" will be looked at, because "f" is rarer than "o". In general, this is a big win except in pathological cases. The only question is whether it saves you more time than it took to build the linked list in the first place. Note that if you have to look for strings that you don't know till runtime, you can build an entire loop as a string and eval that to avoid recompiling all your patterns all the time. Together with undefining $/ to input entire files as one record, this can be very fast, often faster than specialized programs like _f_g_r_e_p(1). The following scans a list of files (@files) for a list of words (@words), and prints out the names of those files that contain a match: $search = 'while (<>) { study;'; foreach $word (@words) { $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n"; } $search .= "}"; @ARGV = @files; undef $/; eval $search; # this screams $/ = "\n"; # put back to normal input delim foreach $file (sort keys(%seen)) { print $file, "\n"; } sub BLOCK sub NAME 25/Mar/96 Last change: perl 5.003 with 60 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) sub NAME BLOCK This is subroutine definition, not a real function _p_e_r _s_e. With just a NAME (and possibly prototypes), it's just a forward declaration. Without a NAME, it's an anonymous function declaration, and does actually return a value: the CODE ref of the closure you just created. See the _p_e_r_l_s_u_b manpage and the _p_e_r_l_r_e_f manpage for details. substr EXPR,OFFSET,LEN substr EXPR,OFFSET Extracts a substring out of EXPR and returns it. First character is at offset 0, or whatever you've set $[ to. If OFFSET is negative, starts that far from the end of the string. If LEN is omitted, returns everything to the end of the string. If LEN is negative, leaves that many characters off the end of the string. You can use the _s_u_b_s_t_r() function as an lvalue, in which case EXPR must be an lvalue. If you assign something shorter than LEN, the string will shrink, and if you assign something longer than LEN, the string will grow to accommodate it. To keep the string the same length you may need to pad or chop your value using _s_p_r_i_n_t_f(). symlink OLDFILE,NEWFILE Creates a new filename symbolically linked to the old filename. Returns 1 for success, 0 otherwise. On systems that don't support symbolic links, produces a fatal error at run time. To check for that, use eval: $symlink_exists = (eval 'symlink("","");', $@ eq ''); syscall LIST Calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. If unimplemented, produces a fatal error. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to receive any result that might be written into a string. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add 0 to them to force them to look like numbers. 25/Mar/96 Last change: perl 5.003 with 61 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) require 'syscall.ph'; # may need to run h2ph syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9); Note that Perl only supports passing of up to 14 arguments to your system call, which in practice should usually suffice. sysopen FILEHANDLE,FILENAME,MODE sysopen FILEHANDLE,FILENAME,MODE,PERMS Opens the file whose filename is given by FILENAME, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. This function calls the underlying operating system's open function with the parameters FILENAME, MODE, PERMS. The possible values and flag bits of the MODE parameter are system-dependent; they are available via the standard module Fcntl. However, for historical reasons, some values are universal: zero means read-only, one means write-only, and two means read/write. If the file named by FILENAME does not exist and the open call creates it (typically because MODE includes the O_CREAT flag), then the value of PERMS specifies the permissions of the newly created file. If PERMS is omitted, the default value is 0666, which allows read and write for all. This default is reasonable: see umask. sysread FILEHANDLE,SCALAR,LENGTH,OFFSET sysread FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE, using the system call _r_e_a_d(2). It bypasses stdio, so mixing this with other kinds of reads may cause confusion. Returns the number of bytes actually read, or undef if there was an error. SCALAR will be grown or shrunk to the length actually read. An OFFSET may be specified to place the read data at some other place than the beginning of the string. system LIST Does exactly the same thing as "exec LIST" except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. The return value is the exit status of the program as returned by the _w_a_i_t() call. To 25/Mar/96 Last change: perl 5.003 with 62 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) get the actual exit value divide by 256. See also the exec entry elsewhere in this document. This is _N_O_T what you want to use to capture the output from a command, for that you should merely use backticks, as described in the section on `_S_T_R_I_N_G` in the _p_e_r_l_o_p manpage. syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET syswrite FILEHANDLE,SCALAR,LENGTH Attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE, using the system call _w_r_i_t_e(2). It bypasses stdio, so mixing this with prints may cause confusion. Returns the number of bytes actually written, or undef if there was an error. An OFFSET may be specified to get the write data from some other place than the beginning of the string. tell FILEHANDLE tell Returns the current file position for FILEHANDLE. FILEHANDLE may be an expression whose value gives the name of the actual filehandle. If FILEHANDLE is omitted, assumes the file last read. telldir DIRHANDLE Returns the current position of the _r_e_a_d_d_i_r() routines on DIRHANDLE. Value may be given to _s_e_e_k_d_i_r() to access a particular location in a directory. Has the same caveats about possible directory compaction as the corresponding system library routine. tie VARIABLE,CLASSNAME,LIST This function binds a variable to a package class that will provide the implementation for the variable. VARIABLE is the name of the variable to be enchanted. CLASSNAME is the name of a class implementing objects of correct type. Any additional arguments are passed to the "new" method of the class (meaning TIESCALAR, TIEARRAY, or TIEHASH). Typically these are arguments such as might be passed to the _d_b_m__o_p_e_n() function of C. The object returned by the "new" method is also returned by the _t_i_e() function, which would be useful if you want to access other methods in CLASSNAME. Note that functions such as _k_e_y_s() and _v_a_l_u_e_s() may return huge array values when used on large objects, like DBM files. You may prefer to use the _e_a_c_h() 25/Mar/96 Last change: perl 5.003 with 63 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) function to iterate over such. Example: # print out history file offsets use NDBM_File; tie(%HIST, NDBM_File, '/usr/lib/news/history', 1, 0); while (($key,$val) = each %HIST) { print $key, ' = ', unpack('L',$val), "\n"; } untie(%HIST); A class implementing an associative array should have the following methods: TIEHASH classname, LIST DESTROY this FETCH this, key STORE this, key, value DELETE this, key EXISTS this, key FIRSTKEY this NEXTKEY this, lastkey A class implementing an ordinary array should have the following methods: TIEARRAY classname, LIST DESTROY this FETCH this, key STORE this, key, value [others TBD] A class implementing a scalar should have the following methods: TIESCALAR classname, LIST DESTROY this FETCH this, STORE this, value Unlike _d_b_m_o_p_e_n(), the _t_i_e() function will not use or require a module for you--you need to do that explicitly yourself. See the _D_B__F_i_l_e manpage or the _C_o_n_f_i_g module for interesting _t_i_e() implementations. tied VARIABLE Returns a reference to the object underlying VARIABLE (the same value that was originally returned by the _t_i_e() call which bound the variable to a package.) Returns the undefined value if VARIABLE isn't tied to a package. 25/Mar/96 Last change: perl 5.003 with 64 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) time Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970. Suitable for feeding to _g_m_t_i_m_e() and _l_o_c_a_l_t_i_m_e(). times Returns a four-element array giving the user and system times, in seconds, for this process and the children of this process. ($user,$system,$cuser,$csystem) = times; tr/// The translation operator. See the _p_e_r_l_o_p manpage. truncate FILEHANDLE,LENGTH truncate EXPR,LENGTH Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified length. Produces a fatal error if truncate isn't implemented on your system. uc EXPR Returns an uppercased version of EXPR. This is the internal function implementing the \U escape in double-quoted strings. Should respect any POSIX _s_e_t_l_o_c_a_l_e() settings. ucfirst EXPR Returns the value of EXPR with the first character uppercased. This is the internal function implementing the \u escape in double-quoted strings. Should respect any POSIX _s_e_t_l_o_c_a_l_e() settings. umask EXPR umask Sets the umask for the process and returns the old one. If EXPR is omitted, merely returns current umask. undef EXPR undef Undefines the value of EXPR, which must be an lvalue. Use only on a scalar value, an entire array, or a subroutine name (using "&"). (Using _u_n_d_e_f() will probably not do what you expect on most predefined variables or DBM list values, so don't do that.) Always returns the undefined value. You can omit the EXPR, in which case nothing is undefined, but you still get an undefined value that you could, for instance, return from a subroutine. Examples: 25/Mar/96 Last change: perl 5.003 with 65 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) undef $foo; undef $bar{'blurfl'}; undef @ary; undef %assoc; undef &mysub; return (wantarray ? () : undef) if $they_blew_it; unlink LIST Deletes a list of files. Returns the number of files successfully deleted. $cnt = unlink 'a', 'b', 'c'; unlink @goners; unlink <*.bak>; Note: unlink will not delete directories unless you are superuser and the ----UUUU flag is supplied to Perl. Even if these conditions are met, be warned that unlinking a directory can inflict damage on your filesystem. Use rmdir instead. unpack TEMPLATE,EXPR Unpack does the reverse of pack: it takes a string representing a structure and expands it out into a list value, returning the array value. (In a scalar context, it merely returns the first value produced.) The TEMPLATE has the same format as in the pack function. Here's a subroutine that does substring: sub substr { local($what,$where,$howmuch) = @_; unpack("x$where a$howmuch", $what); } and then there's sub ordinal { unpack("c",$_[0]); } # same as ord() In addition, you may prefix a field with a % to indicate that you want a -bit checksum of the items instead of the items themselves. Default is a 16-bit checksum. For example, the following computes the same number as the System V sum program: while (<>) { $checksum += unpack("%16C*", $_); } $checksum %= 65536; 25/Mar/96 Last change: perl 5.003 with 66 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) The following efficiently counts the number of set bits in a bit vector: $setbits = unpack("%32b*", $selectmask); untie VARIABLE Breaks the binding between a variable and a package. (See _t_i_e().) unshift ARRAY,LIST Does the opposite of a shift. Or the opposite of a push, depending on how you look at it. Prepends list to the front of the array, and returns the new number of elements in the array. unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/; Note the LIST is prepended whole, not one element at a time, so the prepended elements stay in the same order. Use reverse to do the reverse. use Module LIST use Module Imports some semantics into the current package from the named module, generally by aliasing certain subroutine or variable names into your package. It is exactly equivalent to BEGIN { require Module; import Module LIST; } The BEGIN forces the require and import to happen at compile time. The require makes sure the module is loaded into memory if it hasn't been yet. The import is not a builtin--it's just an ordinary static method call into the "Module" package to tell the module to import the list of features back into the current package. The module can implement its import method any way it likes, though most modules just choose to derive their import method via inheritance from the Exporter class that is defined in the Exporter module. See the _E_x_p_o_r_t_e_r manpage. If you don't want your namespace altered, explicitly supply an empty list: use Module (); That is exactly equivalent to BEGIN { require Module; } 25/Mar/96 Last change: perl 5.003 with 67 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are: use integer; use diagnostics; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs); use subs qw(afunc blurfl); These pseudomodules import semantics into the current block scope, unlike ordinary modules, which import symbols into the current package (which are effective through the end of the file). There's a corresponding "no" command that unimports meanings imported by use. no integer; no strict 'refs'; See the _p_e_r_l_m_o_d manpage for a list of standard modules and pragmas. utime LIST Changes the access and modification times on each file of a list of files. The first two elements of the list must be the NUMERICAL access and modification times, in that order. Returns the number of files successfully changed. The inode modification time of each file is set to the current time. Example of a "touch" command: #!/usr/bin/perl $now = time; utime $now, $now, @ARGV; values ASSOC_ARRAY Returns a normal array consisting of all the values of the named associative array. (In a scalar context, returns the number of values.) The values are returned in an apparently random order, but it is the same order as either the _k_e_y_s() or _e_a_c_h() function would produce on the same array. See also _k_e_y_s(), _e_a_c_h(), and _s_o_r_t(). vec EXPR,OFFSET,BITS Treats the string in EXPR as a vector of unsigned integers, and returns the value of the bitfield specified by OFFSET. BITS specifies the number of bits that are reserved for each entry in the bit 25/Mar/96 Last change: perl 5.003 with 68 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) vector. This must be a power of two from 1 to 32. _v_e_c() may also be assigned to, in which case parens are needed to give the expression the correct precedence as in vec($image, $max_x * $x + $y, 8) = 3; Vectors created with _v_e_c() can also be manipulated with the logical operators |, & and ^, which will assume a bit vector operation is desired when both operands are strings. To transform a bit vector into a string or array of 0's and 1's, use these: $bits = unpack("b*", $vector); @bits = split(//, unpack("b*", $vector)); If you know the exact length in bits, it can be used in place of the *. wait Waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in $?. waitpid PID,FLAGS Waits for a particular child process to terminate and returns the pid of the deceased process, or -1 if there is no such child process. The status is returned in $?. If you say use POSIX "wait_h"; ... waitpid(-1,&WNOHANG); then you can do a non-blocking wait for any process. Non-blocking wait is only available on machines supporting either the _w_a_i_t_p_i_d(2) or _w_a_i_t_4(2) system calls. However, waiting for a particular pid with FLAGS of 0 is implemented everywhere. (Perl emulates the system call by remembering the status values of processes that have exited but have not been harvested by the Perl script yet.) wantarray Returns TRUE if the context of the currently executing subroutine is looking for a list value. Returns FALSE if the context is looking for a scalar. return wantarray ? () : undef; 25/Mar/96 Last change: perl 5.003 with 69 PERLFUNC(1) Perl Programmers Reference Guide PERLFUNC(1) warn LIST Produces a message on STDERR just like _d_i_e(), but doesn't exit or on an exception. write FILEHANDLE write EXPR write Writes a formatted record (possibly multi-line) to the specified file, using the format associated with that file. By default the format for a file is the one having the same name is the filehandle, but the format for the current output channel (see the _s_e_l_e_c_t() function) may be set explicitly by assigning the name of the format to the $~ variable. Top of form processing is handled automatically: if there is insufficient room on the current page for the formatted record, the page is advanced by writing a form feed, a special top-of-page format is used to format the new page header, and then the record is written. By default the top-of-page format is the name of the filehandle with "_TOP" appended, but it may be dynamically set to the format of your choice by assigning the name to the $^ variable while the filehandle is selected. The number of lines remaining on the current page is in variable $-, which can be set to 0 to force a new page. If FILEHANDLE is unspecified, output goes to the current default output channel, which starts out as STDOUT but may be changed by the select operator. If the FILEHANDLE is an EXPR, then the expression is evaluated and the resulting string is used to look up the name of the FILEHANDLE at run time. For more on formats, see the _p_e_r_l_f_o_r_m manpage. Note that write is _N_O_T the opposite of read. Unfortunately. y/// The translation operator. See the _p_e_r_l_o_p manpage. 25/Mar/96 Last change: perl 5.003 with 70 User Commands ls(1) NAME ls - list contents of directory SYNOPSIS /usr/bin/ls [ -aAbcCdfFgilLmnopqrRstux1 ] [ _f_i_l_e ... ] /usr/xpg4/bin/ls [ -aAbcCdfFgilLmnopqrRstux1 ] [ _f_i_l_e ... ] DESCRIPTION For each _f_i_l_e that is a directory, ls lists the contents of the directory; for each _f_i_l_e that is an ordinary file, ls repeats its name and any other information requested. The output is sorted alphabetically by default. When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. There are three major listing formats. The default format for output directed to a terminal is multi-column with entries sorted down the columns. The -1 option allows single column output and -m enables stream output format. In order to determine output formats for the -C, -x, and -m options, 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(4) 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. The mode printed under the -l option consists of ten charac- ters. The first character may be one of the following: d the entry is a directory; D the entry is a door; l the entry is a symbolic link; b the entry is a block special file; c the entry is a character special file; p the entry is a fifo (or "named pipe") special file; s the entry is an AF_UNIX address family socket; - the entry is an ordinary file; 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 SunOS 5.8 Last change: 5 May 1997 1 User Commands ls(1) file; and the last to all others. Within each set, the three characters indicate permission to read, to write, and to execute the file as a program, respectively. For a direc- tory, ``execute'' permission is interpreted to mean permis- sion to search the directory for a specified file. The char- acter after permissions is ACL indication. A plus sign is displayed if there is an ACL associated with the file. Noth- ing is displayed if there are just permissions. ls -l (the long list) prints its output as follows for the POSIX locale: -rwxrwxrwx+ 1 smith dev 10876 May 16 9:42 part2 Reading from right to left, you see that the current direc- tory holds one file, named part2. Next, the last time that file's contents were modified was 9:42 A.M. on May 16. The file contains 10,876 characters, or bytes. The owner of the file, or the user, belongs to the group dev (perhaps indi- cating ``development''), and his or her login name is smith. The number, in this case 1, indicates the number of links to file part2; see cp(1). The plus sign indicates that there is an ACL associated with the file. Finally, the dash and letters tell you that user, group, and others have permis- sions to read, write, and execute part2. The execute (x) symbol here occupies the third position of the three-character sequence. A - in the third position would have indicated a denial of execution permissions. 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 _n_o_t granted s the set-user-ID or set-group-ID bit is on, and the corresponding user or group execution bit is also on S undefined bit-state (the set-user-ID bit is on and the user execution bit is off) t the 1000 (octal) bit, or sticky bit, is on (see chmod(1)), and execution is on T the 1000 bit is turned on, and execution is off SunOS 5.8 Last change: 5 May 1997 2 User Commands ls(1) (undefined bit-state) /usr/bin/ls l mandatory locking occurs during access (the set- group-ID bit is on and the group execution bit is off) /usr/xpg4/bin/ls L mandatory locking occurs during access (the set- group-ID bit is on and the group execution bit is off) For user and group permissions, the third position is some- times occupied by a character other than x or -. s also may occupy this position, referring to the state of the set-ID bit, whether it be the user's or the group's. The ability to assume the same ID as the user during execution is, for example, used during login when you begin as root but need to assume the identity of the user you login as. In the case of the sequence of group permissions, l may occupy the third position. l refers to mandatory file and record locking. This permission describes a file's ability to allow other files to lock its reading or writing permis- sions during access. For others permissions, the third position may be occupied by t or T. These refer to the state of the sticky bit and execution permissions. OPTIONS The following options are supported: -a Lists all entries, including those that begin with a dot (.), which are normally not listed. -A Lists all entries, including those that begin with a dot (.), with the exception of the working directory (.) and the parent directory (..). -b Forces printing of non-printable characters to be in the octal \_d_d_d notation. -c Uses time of last modification of the i-node (file created, mode changed, and so forth) for sorting (-t) or printing (-l or -n). -C Multi-column output with entries sorted down the columns. This is the default output format. -d If an argument is a directory, lists only its name (not its contents); often used with -l to get the status of a directory. SunOS 5.8 Last change: 5 May 1997 3 User Commands ls(1) -f Forces each argument to be interpreted as a directory and list the name found in each slot. This option turns off -l, -t, -s, and -r, and turns on -a; the order is the order in which entries appear in the directory. -F Marks directories with a trailing slash (/), doors with a trailing greater-than sign (>), executable files with a trailing asterisk (*), FIFOs with a trailing vertical bar (|), symbolic links with a trailing at-sign (@), and AF_UNIX address family sock- ets with a trailing equals sign (=). -g The same as -l, except that the owner is not printed. -i For each file, prints the i-node number in the first column of the report. -l Lists in long format, giving mode, ACL indication, number of links, owner, group, size in bytes, and time of last modification for each file (see above). If the file is a special file, the size field instead con- tains 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' for the POSIX locale. When the LC_TIME locale category is not set to the POSIX locale, a different format of the time field may be used. Files modified within six months show `month date time'. If the file is a sym- bolic link, the filename is printed followed by "->" and the path name of the referenced file. -L If an argument is a symbolic link, lists the file or directory the link references rather than the link itself. -m Streams output format; files are listed across the page, separated by commas. -n The same as -l, except that the owner's UID and group's GID numbers are printed, rather than the asso- ciated character strings. -o The same as -l, except that the group is not printed. -p Puts a slash (/) after each filename if the file is a directory. -q Forces printing of non-printable characters in file names as the character question mark (?). -r Reverses the order of sort to get reverse alphabetic SunOS 5.8 Last change: 5 May 1997 4 User Commands ls(1) or oldest first as appropriate. -R Recursively lists subdirectories encountered. -s Gives size in blocks, including indirect blocks, for each entry. -t Sorts by time stamp (latest first) instead of by name. The default is the last modification time. (See -u and -c.) -u Uses time of last access instead of last modification for sorting (with the -t option) or printing (with the -l option). -x Multi-column output with entries sorted across rather than down the page. -1 Prints one entry per line of output. Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: -C and -1 (one), -c and -u. The last option specified in each pair determines the output format. /usr/bin/ls Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: -C and -l (ell), -m and -l (ell), -x and -l (ell). The -l option overrides the other option specified in each pair. /usr/xpg4/bin/ls Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: -C and -l (ell), -m and -l (ell), -x and -l (ell). The last option specified in each pair determines the output format. OPERANDS The following operand is supported: _f_i_l_e A path name of a file to be written. If the file specified is not found, a diagnostic message will be output on standard error. USAGE See largefile(5) for the description of the behavior of ls when encountering files greater than or equal to 2 Gbyte ( 2 **31 bytes). EXAMPLES Example 1: File permissions SunOS 5.8 Last change: 5 May 1997 5 User Commands ls(1) An example of a file's permissions is: -rwxr--r-- This describes a file that is readable, writable, and exe- cutable by the user and readable by the group and others. Another example of a file's permissions is: -rwsr-xr-x This describes a file that is readable, writable, and exe- cutable by the user, readable and executable by the group and others, and allows its user-ID to be assumed, during execution, by the user presently executing it. Another example of a file's permissions is: -rw-rwl--- This describes a file that is readable and writable only by the user and the group and can be locked during access. Example 2: Printing the names of all files This command prints the names of all files in the current directory, including those that begin with a dot (.), which normally do not print: example% ls -a Example 3: Providing file information Another example of a command line is: example% ls -aisn This command provides information on all files, including those that begin with a dot (a), the i-number-the memory address of the i-node associated with the file-printed in the left-hand column (i); the size (in blocks) of the files, printed in the column to the right of the i-numbers (s); finally, the report is displayed in the numeric version of the long list, printing the UID (instead of user name) and GID (instead of group name) numbers associated with the files. When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks, is printed. SunOS 5.8 Last change: 5 May 1997 6 User Commands ls(1) ENVIRONMENT VARIABLES See environ(5) for descriptions of the following environment variables that affect the execution of ls: LC_COLLATE, LC_CTYPE, LC_TIME, LC_MESSAGES, NLSPATH, and TZ. COLUMNS Determine the user's preferred column position width for writing multiple text-column output. If this variable contains a string representing a decimal integer, the ls utility calculates how many path name text columns to write (see -C) based on the width pro- vided. If COLUMNS is not set or is invalid, 80 is used. The column width chosen to write the names of files in any given directory will be constant. File names will not be truncated to fit into the multiple text-column output. EXIT STATUS 0 All information was written successfully. >0 An error occurred. FILES /etc/group group IDs for ls -l and ls -g /etc/passwd user IDs for ls -l and ls -o /usr/share/lib/terminfo/?/* terminal information database ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: /usr/bin/ls ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |______________________________|______________________________| | Availability | SUNWcsu | |______________________________|______________________________| | CSI | Enabled | |______________________________|______________________________| /usr/xpg4/bin/ls SunOS 5.8 Last change: 5 May 1997 7 User Commands ls(1) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |______________________________|______________________________| | Availability | SUNWxcu4 | |______________________________|______________________________| | CSI | Enabled | |______________________________|______________________________| SEE ALSO chmod(1), cp(1), setfacl(1), terminfo(4), attributes(5), environ(5), largefile(5), XPG4(5) NOTES Unprintable characters in file names may confuse the colum- nar output options. The total block count will be incorrect if there are hard links among the files. SunOS 5.8 Last change: 5 May 1997 8 User Commands ed(1) NAME ed, red - text editor SYNOPSIS /usr/bin/ed [ -s | - ] [ -p _s_t_r_i_n_g ] [ -x ] [ -C ] [ _f_i_l_e ] /usr/xpg4/bin/ed [ -s | - ] [ -p _s_t_r_i_n_g ] [ -x ] [ -C ] [ _f_i_l_e ] /usr/bin/red [ -s | - ] [ -p _s_t_r_i_n_g ] [ -x ] [ -C ] [ _f_i_l_e ] DESCRIPTION The ed utility is the standard text editor. If file is specified, ed simulates an e command (see below) on the named file; that is to say, the file is read into ed's buffer so that it can be edited. The ed utility operates on a copy of the file it is editing; changes made to the copy have no effect on the file until a w (write) command is given. The copy of the text being edited resides in a temporary file called the _b_u_f_f_e_r. There is only one buffer. The red utility is a restricted version of ed. It will only allow editing of files in the current directory. It prohi- bits executing shell commands via !_s_h_e_l_l _c_o_m_m_a_n_d. Attempts to bypass these restrictions result in an error message (_r_e_s_t_r_i_c_t_e_d _s_h_e_l_l). Both ed and red support the fspec(4) formatting capability. The default terminal mode is either stty -tabs or stty tab3, where tab stops are set at eight columns (see stty(1)). If, however, the first line of file contains a format specifica- tion, that specification will override the default mode. For example, if the first line of file contains <:t5,10,15 s72:> tab stops would be set at 5, 10, and 15, and a maximum line length of 72 would be imposed. Commands to ed have a simple and regular structure: zero, one, or two _a_d_d_r_e_s_s_e_s followed by a single-character com- mand, possibly followed by parameters to that command. These addresses specify one or more lines in the buffer. Every command that requires addresses has default addresses, so that the addresses can very often be omitted. SunOS 5.8 Last change: 18 Mar 1997 1 User Commands ed(1) In general, only one command may appear on a line. Certain commands allow the input of text. This text is placed in the appropriate place in the buffer. While ed is accepting text, it is said to be in _i_n_p_u_t _m_o_d_e. In this mode, _n_o commands are recognized; all input is merely collected. Leave input mode by typing a period (.) at the beginning of a line, fol- lowed immediately by a carriage return. /usr/bin/ed If ed executes commands with arguments, it uses the default shell /usr/bin/sh (see sh(1)). /usr/xpg4/bin/ed If ed executes commands with arguments, it uses /usr/xpg4/bin/sh, which is equivalent to /usr/bin/ksh (see ksh(1)). Regular Expressions The ed utility supports a limited form of _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n notation. Regular expressions are used in addresses to specify lines and in some commands (for example, s) to specify portions of a line that are to be substituted. To understand addressing in ed, it is necessary to know that at any time there is a _c_u_r_r_e_n_t _l_i_n_e. Generally speaking, the current line is the last line affected by a command; the exact effect on the current line is discussed under the description of each command. Internationalized Basic Regular Expressions are used for all system-supplied locales. See regex(5). ed Commands Commands may require zero, one, or two addresses. Commands that require no addresses regard the presence of an address as an error. Commands that accept one or two addresses assume default addresses when an insufficient number of addresses is given; if more addresses are given than such a command requires, the last one(s) are used. Typically, addresses are separated from each other by a comma (,). They may also be separated by a semicolon (;). In the latter case, the first address is calculated, the current line (.) is set to that value, and then the second address is calculated. This feature can be used to determine the starting line for forward and backward searches (see Rules 5 and 6, above). The second address of any two-address sequence must correspond to a line in the buffer that fol- lows the line corresponding to the first address. In the following list of ed commands, the parentheses shown prior to the command are _n_o_t part of the address; rather, they show the default address(es) for the command. SunOS 5.8 Last change: 18 Mar 1997 2 User Commands ed(1) Each address component can be preceded by zero or more blank characters. The command letter can be preceded by zero or more blank characters. If a suffix letter (l, n, or p) is given, it must immediately follow the command. The e, E, f, r, and w commands take an optional file parame- ter, separated from the command letter by one or more blank characters. If changes have been made in the buffer since the last w command that wrote the entire buffer, ed will warn the user if an attempt is made to destroy the editor buffer via the e or q commands. The ed utility will write the string: "?\n" (followed by an explanatory message if _h_e_l_p _m_o_d_e has been enabled via the H command) to standard output and will con- tinue in command mode with the current line number unchanged. If the e or q command is repeated with no inter- vening command, it will take effect. If an end-of-file is detected on standard input when a com- mand is expected, the ed utility acts as if a q command had been entered. 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 suffixed by l, n, or p in which case the current line is either listed, numbered or written, respectively, as dis- cussed below under the l, n, and p commands. (.)a <_t_e_x_t> . The append command accepts zero or more lines of text and appends it after the addressed line in the buffer. The current line (.) is left at the last inserted line, or, if there were none, at the addressed line. Address 0 is legal for this command: it causes the ``appended'' text to be placed at the beginning of the buffer. The maximum number of characters that may be entered from a terminal is 256 per line (including the new-line character). (.)c <_t_e_x_t> . The change command deletes the addressed lines from SunOS 5.8 Last change: 18 Mar 1997 3 User Commands ed(1) the buffer, then accepts zero or more lines of text that replaces these lines in the buffer. The current line (.) is left at the last line input, or, if there were none, at the first line that was not deleted; if the lines deleted were originally at the end of the buffer, the current line number will be set to the address of the new last line; if no lines remain in the buffer, the current line number will be set to 0. C Same as the X command, described later, except that ed assumes all text read in for the e and r commands is encrypted unless a null key is typed in. (.,.)d The delete command deletes the addressed lines from the buffer. The line after the last line deleted becomes the current line; if the lines deleted were originally at the end of the buffer, the new last line becomes the current line. If no lines remain in the buffer, the current line number will be set to 0. e _f_i_l_e The edit command deletes the entire contents of the buffer and then reads the contents of file into the buffer. The current line (.) is set to the last line of the buffer. If file is not given, the currently remembered file name, if any, is used (see the f com- mand). The number of bytes read will be written to standard output, unless the -s option was specified, in the following format: "%d\n" <_n_u_m_b_e_r _o_f _b_y_t_e_s _r_e_a_d> file is remembered for possible use as a default file name in subsequent e, E, r, and w commands. If file is replaced by !, the rest of the line is taken to be a shell ( sh(1)) command whose output is to be read. Such a shell command is _n_o_t remembered as the current file name. See also DIAGNOSTICS below. All marks will be discarded upon the completion of a successful e command. If the buffer has changed since the last time the entire buffer was written, the user will be warned, as described previously. E _f_i_l_e The Edit command is like e, except that the editor does not check to see if any changes have been made to the buffer since the last w command. f _f_i_l_e If file is given, the f command will change the SunOS 5.8 Last change: 18 Mar 1997 4 User Commands ed(1) currently remembered path name to file; whether the name is changed or not, it then will write the (possi- bly new) currently remembered path name to the stan- dard output in the following format: "%s\n"_p_a_t_h_n_a_m_e The current line number is unchanged. (1,$)g/_R_E/_c_o_m_m_a_n_d _l_i_s_t In the global command, the first step is to mark every line that matches the given _R_E. Then, for every such line, the given _c_o_m_m_a_n_d _l_i_s_t is executed with the current line (.) initially set to that line. When the g command completes, the current line number will have the value assigned by the last command in the command list. If there were no matching lines, the current line number will not be changed. A single command or the first of a list of commands appears on the same line as the global command. All lines of a multi-line list except the last line must be ended with a backslash (\); a, i, and c commands and associated input are permitted. The . terminating input mode may be omitted if it would be the last line of the _c_o_m_m_a_n_d _l_i_s_t. An empty command _l_i_s_t is equivalent to the p command. The g, G, v, V, and ! commands are _n_o_t per- mitted in the _c_o_m_m_a_n_d _l_i_s_t. See also the NOTES and the last paragraph before FILES below. Any character other than space or newline can be used instead of a slash to delimit the _R_E. Within the _R_E, the _R_E delimiter itself can be used as a literal character if it is preceded by a backslash. (1,$)G/_R_E/ In the interactive Global command, the first step is to mark every line that matches the given _R_E. Then, for every such line, that line is written to standard output, the current line (.) is changed to that line, and any _o_n_e command (other than one of the a, c, i, g, G, v, and V commands) may be input and is executed. After the execution of that command, the next marked line is written, and so on; a new-line acts as a null command; an & causes the re-execution of the most recent non-null command executed within the current invocation of G. Note: The commands input as part of the execution of the G command may address and affect _a_n_y lines in the buffer. The final value of the current line number will be the value set by the last command successfully executed. (Note that the last command successfully executed will be the G command itself if a command fails or the null command is SunOS 5.8 Last change: 18 Mar 1997 5 User Commands ed(1) specified.) If there were no matching lines, the current line number will not be changed. The G command can be terminated by a SIGINT signal. The G command can be terminated by an interrupt signal (ASCII DEL or BREAK). Any character other than space or newline can be used instead of a slash to delimit the _R_E. Within the _R_E, the _R_E delimiter itself can be used as a literal character if it is preceded by a backslash. h The help command gives a short error message that explains the reason for the most recent ? diagnostic. The current line number is unchanged. H The Help command causes ed to enter a mode in which error messages are written for all subsequent ? diag- nostics. It will also explain the previous ? if there was one. The H command alternately turns this mode on and off; it is initially off. The current line number is unchanged. (.)i <_t_e_x_t> . The insert command accepts zero or more lines of text and inserts it before the addressed line in the buffer. The current line (.) is left at the last inserted line, or, if there were none, at the addressed line. This command differs from the a com- mand only in the placement of the input text. Address 0 is not legal for this command. The maximum number of characters that may be entered from a terminal is 256 per line (including the new-line character). (.,.+1)j The join command joins contiguous lines by removing the appropriate new-line characters. If exactly one address is given, this command does nothing. If lines are joined, the current line number will be set to the address of the joined line; otherwise, the current line number is unchanged. (.)k_x The mark command marks the addressed line with name _x, which must be an ASCII lower-case letter (a-z). The address '_x then addresses this line; the current line (.) is unchanged. (.,.)l The l command writes to standard output the addressed lines in a visually unambiguous form. The characters ( \\, \a, \b, \f, \r, \t, \v) will be written as the corresponding escape sequence; the \n in that table is SunOS 5.8 Last change: 18 Mar 1997 6 User Commands ed(1) not applicable. Non-printable characters not in the table will be written as one three-digit octal number (with a preceding backslash character) for each byte in the character (most significant byte first). Long lines will be folded, with the point of folding indicated by writing backslash/newline character; the length at which folding occurs is unspecified, but should be appropriate for the output device. The end of each line will be marked with a $. An l command can be appended to any other command other than e, E, f, q, Q, r, w, or !. The current line number will be set to the address of the last line written. (.,.)m_a The move command repositions the addressed line(s) after the line addressed by _a. Address 0 is legal for _a and causes the addressed line(s) to be moved to the beginning of the file. It is an error if address _a falls within the range of moved lines; the current line (.) is left at the last line moved. (.,.)n The number command writes the addressed lines, preced- ing each line by its line number and a tab character; the current line (.) is left at the last line written. The n command may be appended to any command other than e, E, f, q, Q, r, w, or !. (.,.)p The print command writes the addressed lines to stan- dard output; the current line (.) is left at the last line written. The p command may be appended to any command other than e, E, f, q, Q, r, w, or !. For example, dp deletes the current line and writes the new current line. P The P command causes ed to prompt with an asterisk (*) (or _s_t_r_i_n_g, if -p is specified) for all subsequent commands. The P command alternatively turns this mode on and off; it is initially on if the -p option is specified, otherwise off. The current line is unchanged. q The quit command causes ed to exit. If the buffer has changed since the last time the entire buffer was written, the user will be warned; see DIAGNOSTICS. Q The editor exits without checking if changes have been made in the buffer since the last w command. ($)r _f_i_l_e SunOS 5.8 Last change: 18 Mar 1997 7 User Commands ed(1) The read command reads the contents of file into the buffer. If file is not given, the currently remembered file name, if any, is used (see the e and f commands). The currently remembered file name is _n_o_t changed unless file is the very first file name mentioned since ed was invoked. Address 0 is legal for r and causes the file to be read in at the beginning of the buffer. If the read is successful and the -s option was not specified, the number of characters read is written to standard output in the following format: %d\n, <_n_u_m_b_e_r _o_f _b_y_t_e_s _r_e_a_d> The current line (.) is set to the last line read. If file is replaced by !, the rest of the line is taken to be a shell command (see sh(1)) whose output is to be read. For example, $r !ls appends the current directory to the end of the file being edited. Such a shell command is _n_o_t remembered as the current file name. (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/ (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/_c_o_u_n_t, _c_o_u_n_t=[1-512] (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/g (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/l (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/n (.,.)s/_R_E/_r_e_p_l_a_c_e_m_e_n_t/p The substitute command searches each addressed line for an occurrence of the specified _R_E. Zero or more substitution commands can be specified. In each line in which a match is found, all (non-overlapped) matched strings are replaced by the _r_e_p_l_a_c_e_m_e_n_t if the global replacement indicator g appears after the com- mand. If the global indicator does not appear, only the first occurrence of the matched string is replaced. If a number _c_o_u_n_t appears after the command, only the _c_o_u_n_t-th occurrence of the matched string on each addressed line is replaced. It is an error if the substitution fails on _a_l_l addressed lines. Any charac- ter other than space or new-line may be used instead of the slash (/) to delimit the _R_E and the _r_e_p_l_a_c_e_- _m_e_n_t; the current line (.) is left at the last line on which a substitution occurred. Within the _R_E, the _R_E delimiter itself can be used as a literal character if it is preceded by a backslash. See also the last paragraph before FILES below. SunOS 5.8 Last change: 18 Mar 1997 8 User Commands ed(1) An ampersand (&) appearing in the _r_e_p_l_a_c_e_m_e_n_t is replaced by the string matching the _R_E on the current line. The special meaning of & in this context may be suppressed by preceding it by \. As a more general feature, the characters \_n, where _n is a digit, are replaced by the text matched by the _n-th regular subexpression of the specified _R_E enclosed between \( and \). When nested parenthesized subexpressions are present, _n is determined by counting occurrences of \( starting from the left. When the character % is the only character in the _r_e_p_l_a_c_e_m_e_n_t, the _r_e_p_l_a_c_e_m_e_n_t used in the most recent substitute command is used as the _r_e_p_l_a_c_e_m_e_n_t in the current substitute command; if there was no previous substitute command, the use of % in this manner is an error. The % loses its special meaning when it is in a replacement string of more than one character or is preceded by a \. For each backslash (\) encountered in scanning _r_e_p_l_a_c_e_m_e_n_t from beginning to end, the following character loses its special meaning (if any). It is unspecified what spe- cial meaning is given to any character other than &, \, %, or digits. A line may be split by substituting a new-line char- acter into it. The new-line in the _r_e_p_l_a_c_e_m_e_n_t must be escaped by preceding it by \. Such substitution can- not be done as part of a g or v command list. The current line number will be set to the address of the last line on which a substitution is performed. If no substitution is performed, the current line number is unchanged. If a line is split, a substitution is con- sidered to have been performed on each of the new lines for the purpose of determining the new current line number. A substitution is considered to have been performed even if the replacement string is identical to the string that it replaces. The substitute command supports the following indica- tors: _c_o_u_n_t Substitute for the _c_o_u_n_tth occurrence only of the _R_E found on each addressed line. _c_o_u_n_t must be between 1-512. g Globally substitute for all non-overlapping instances of the _R_E rather than just the first one. If both g and _c_o_u_n_t are specified, the results are unspecified. l Write to standard output the final line in which a substitution was made. The line will be writ- ten in the format specified for the l command. SunOS 5.8 Last change: 18 Mar 1997 9 User Commands ed(1) n Write to standard output the final line in which a substitution was made. The line will be writ- ten in the format specified for the n command. p Write to standard output the final line in which a substitution was made. The line will be writ- ten in the format specified for the p command. (.,.)t_a This command acts just like the m command, except that a _c_o_p_y of the addressed lines is placed after address a (which may be 0); the current line (.) is left at the last line copied. u The undo command nullifies the effect of the most recent command that modified anything in the buffer, namely the most recent a, c, d, g, i, j, m, r, s, t, u, v, G, or V command. All changes made to the buffer by a g, G, v, or V global command will be undone as a single change; if no changes were made by the global command (such as with g/ _R_E /p), the u command will have no effect. The current line number will be set to the value it had immediately before the command being undone started. (1,$)v/_R_E/_c_o_m_m_a_n_d _l_i_s_t This command is the same as the global command g, except that the lines marked during the first step are those that do _n_o_t match the _R_E. (1,$)V/_R_E/ This command is the same as the interactive global command G, except that the lines that are marked dur- ing the first step are those that do _n_o_t match the _R_E. (1,$)w _f_i_l_e The write command writes the addressed lines into file. If file does not exist, it is created with mode 666 (readable and writable by everyone), unless your file creation mask dictates otherwise; see the description of the umask special command on sh(1). The currently remembered file name is _n_o_t changed unless file is the very first file name mentioned since ed was invoked. If no file name is given, the currently remembered file name, if any, is used (see the e and f commands); the current line (.) is unchanged. If the command is successful, the number of characters writ- ten is printed, unless the -s option is specified in the following format: SunOS 5.8 Last change: 18 Mar 1997 10 User Commands ed(1) "%d\n",<_n_u_m_b_e_r _o_f _b_y_t_e_s _w_r_i_t_t_e_n> If file is replaced by !, the rest of the line is taken to be a shell (see sh(1)) command whose standard input is the addressed lines. Such a shell command is _n_o_t remembered as the current path name. This usage of the write command with ! is to be considered as a ``last w command that wrote the entire buffer''. (1,$)W _f_i_l_e This command is the same as the write command above, except that it appends the addressed lines to the end of file if it exists. If file does not exist, it is created as described above for the w command. X An educated guess is made to determine whether text read for the e and r commands is encrypted. A null key turns off encryption. Subsequent e, r, and w com- mands will use this key to encrypt or decrypt the text. An explicitly empty key turns off encryption. Also, see the -x option of ed. ($)= The line number of the addressed line will be written to standard output in the following format: "%d\n"<_l_i_n_e _n_u_m_b_e_r> The current line number is unchanged by this command. !_s_h_e_l_l _c_o_m_m_a_n_d The remainder of the line after the ! is sent to the UNIX system shell (see sh(1)) to be interpreted as a command. Within the text of that command, the unes- caped character % is replaced with the remembered file name; if a ! appears as the first character of the shell command, it is replaced with the text of the previous shell command. Thus, !! will repeat the last shell command. If any replacements of % or ! are per- formed, the modified line will be written to the stan- dard output before command is executed. The ! command will write: "!\n" to standard output upon completion, unless the -s