IEEE P1003.2 Draft 11.2 - September 1991 Copyright (c) 1991 by the Institute of Electrical and Electronics Engineers, Inc. 345 East 47th Street New York, NY 10017, USA All rights reserved as an unpublished work. This is an unapproved and unpublished IEEE Standards Draft, subject to change. The publication, distribution, or copying of this draft, as well as all derivative works based on this draft, is expressly prohibited except as set forth below. Permission is hereby granted for IEEE Standards Committee participants to reproduce this document for purposes of IEEE standardization activities only, and subject to the restrictions contained herein. Permission is hereby also granted for member bodies and technical committees of ISO and IEC to reproduce this document for purposes of developing a national position, subject to the restrictions contained herein. Permission is hereby also granted to the preceding entities to make limited copies of this document in an electronic form only for the stated activities. The following restrictions apply to reproducing or transmitting the document in any form: 1) all copies or portions thereof must identify the document's IEEE project number and draft number, and must be accompanied by this entire notice in a prominent location; 2) no portion of this document may be redistributed in any modified or abridged form without the prior approval of the IEEE Standards Department. Other entities seeking permission to reproduce this document, or any portion thereof, for standardization or other activities, must contact the IEEE Standards Department for the appropriate license. Use of information contained in this unapproved draft is at your own risk. IEEE Standards Department Copyright and Permissions 445 Hoes Lane, P.O. Box 1331 Piscataway, NJ 08855-1331, USA +1 (908) 562-3800 +1 (908) 562-1571 [FAX] Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.28.5 External Influences 4.28.5.1 Standard Input The standard input shall be used only if no _f_i_l_e operands are specified. See Input Files. 4.28.5.2 Input Files The input files shall be text files. 4.28.5.3 Environment Variables The following environment variables shall affect the execution of grep: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_COLLATE This variable shall determine the locale for the behavior of ranges, equivalence classes, and multicharacter collating elements within regular expressions. LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments) and the behavior of character classes within regular expressions. LC_MESSAGES This variable shall determine the language in which messages should be written. 4.28.5.4 Asynchronous Events Default. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.28 grep - File pattern searcher 541 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.28.6 External Effects 4.28.6.1 Standard Output If the -l option is in effect, and the -q option is not, a single output line shall be written for each file containing at least one selected input line: "%s\n", _f_i_l_e Otherwise, if more than one _f_i_l_e argument appears, and -q is not specified, the grep utility shall prefix each output line by: "%s:", _f_i_l_e The remainder of each output line shall depend on the other options specified: - If the -c option is in effect, the remainder of each output line shall contain: "%d\n", <_c_o_u_n_t> - Otherwise, if -c is not in effect and the -n option is in effect, the following shall be written to standard output: "%d:", <_l_i_n_e _n_u_m_b_e_r> - Finally, the following shall be written to standard output: "%s", <_s_e_l_e_c_t_e_d-_l_i_n_e _c_o_n_t_e_n_t_s> 4.28.6.2 Standard Error Used only for diagnostic messages. 4.28.6.3 Output Files None. 4.28.7 Extended Description None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 542 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.28.8 Exit Status The grep utility shall exit with one of the following values: 0 One or more lines were selected. 1 No lines were selected. >1 An error occurred. 4.28.9 Consequences of Errors If the -q option is specified, the exit status shall be zero if an input line is selected, even if an error was detected. Otherwise, default actions shall be performed. BEGIN_RATIONALE 4.28.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e This grep has been enhanced in an upward-compatible way to provide the exact functionality of the historical egrep and fgrep commands as well. It was the clear intention of the working group to consolidate the three greps into a single command. The old egrep and fgrep commands are likely to be supported for many 1 years to come as implementation extensions, allowing existing applications to operate unmodified. To find all uses of the word Posix (in any case) in the file text.mm, and write with line numbers: grep -i -n posix text.mm To find all empty lines in the standard input: 2 grep ^$ or grep -v . Both of the following commands print all lines containing strings abc or def or both: Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.28 grep - File pattern searcher 543 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX grep -E 'abc def' grep -F 'abc def' Both of the following commands print all lines matching exactly abc or def: grep -E '^abc$ ^def$' grep -F -x 'abc def' _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The -e _p_a_t_t_e_r_n__l_i_s_t option has the same effect as the _p_a_t_t_e_r_n__l_i_s_t operand, but is useful when _p_a_t_t_e_r_n__l_i_s_t begins with the hyphen delimiter. It is also useful when it is more convenient to provide multiple patterns as separate arguments. Earlier drafts did not show that the -c, -l, and -q options were mutually exclusive. This has been fixed to more closely align with historical practice and documentation. Historical implementations usually silently ignored all but one of multiply specified -e and -f options, but were not consistent as to which specification was actually used. POSIX.2 requires that the nonobsolescent forms accept multiple -e and -f options and use all of the patterns specified while matching input text lines. [Note that the order of evaluation is not specified. If an implementation finds a null string as a pattern, it is allowed to use that pattern first (matching every line) and effectively ignore any other patterns.] The -b option was removed from the Options subclause, since block numbers are implementation dependent. The System V restriction on using - to mean standard input was lifted. A definition of action taken when given a null RE or ERE is specified. This is an error condition in some historical implementations. The -l option previously indicated that its use was undefined when no files were explicitly named. This behavior was historical and placed an unnecessary restriction on future implementations. It has been removed. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 544 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 The -q option was added at the suggestion of members of the balloting group as a means of easily determining whether or not a pattern (or string) exists in a group of files. When searching several files, it provides a performance improvement (because it can quit as soon as it finds the first match) and requires less care by the user in choosing the set of files to supply as arguments (because it will exit zero if it finds a match even if grep detected an access or read error on earlier file operands). The historical BSD grep -s option practice is easily duplicated by redirecting standard output to /dev/null. The -s option required here is from System V. The -x option, historically available only with fgrep, is available here for all of the nonobsolescent versions. END_RATIONALE 4.29 head - Copy the first part of files 4.29.1 Synopsis head [-n _n_u_m_b_e_r] [_f_i_l_e ...] _O_b_s_o_l_e_s_c_e_n_t _v_e_r_s_i_o_n: head [-_n_u_m_b_e_r] [_f_i_l_e ...] 4.29.2 Description The head utility shall copy its input files to the standard output, ending the output for each file at a designated point. Copying shall end at the point in each input file indicated by the -n _n_u_m_b_e_r option (or the obsolescent version's -_n_u_m_b_e_r argument). The option-argument _n_u_m_b_e_r shall be counted in units of lines. 4.29.3 Options The head utility shall conform to the utility argument syntax guidelines described in standard described in 2.10.2, except that the obsolescent version accepts multicharacter numeric options. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.29 head - Copy the first part of files 545 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX The following option shall be supported by the implementation in the nonobsolescent version: -n _n_u_m_b_e_r The first _n_u_m_b_e_r lines of each input file shall be copied to standard output. The _n_u_m_b_e_r option argument shall be a positive decimal integer. If no options are specified, head shall act as if -n 10 had been specified. In the obsolescent version, the following option shall be supported by the implementation: -_n_u_m_b_e_r The _n_u_m_b_e_r argument is a positive decimal integer with the same effect as the -n_n_u_m_b_e_r option in the nonobsolescent version. 4.29.4 Operands The following operand shall be supported by the implementation: _f_i_l_e A pathname of an input file. If no _f_i_l_e operands are specified, the standard input shall be used. 4.29.5 External Influences 4.29.5.1 Standard Input The standard input shall be used only if no _f_i_l_e operands are specified. See Input Files. 4.29.5.2 Input Files Input files shall be text files, but the line length shall not be restricted to {LINE_MAX} bytes. 4.29.5.3 Environment Variables The following environment variables shall affect the execution of head: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 546 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files). LC_MESSAGES This variable shall determine the language in which messages should be written. 4.29.5.4 Asynchronous Events Default. 4.29.6 External Effects 4.29.6.1 Standard Output The standard output shall contain designated portions of the input file(s). If multiple _f_i_l_e operands are specified, head shall precede the output for each with the header: "\n==> %s <==\n", <_p_a_t_h_n_a_m_e> except that the first header written shall not include the initial . 4.29.6.2 Standard Error Used only for diagnostic messages. 4.29.6.3 Output Files None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.29 head - Copy the first part of files 547 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.29.7 Extended Description None. 4.29.8 Exit Status The head utility shall exit with one of the following values: 0 Successful completion. >0 An error occurred. 4.29.9 Consequences of Errors Default. BEGIN_RATIONALE 4.29.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _U_s_a_g_e_,__E_x_a_m_p_l_e_s The nonobsolescent version of head was created to allow conformance to the Utility Syntax Guidelines. The -n option was added to this new interface so that head and tail would be more logically related. To write the first ten lines of all files (except those with a leading period) in the directory: head * _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The head utility was not in early drafts. It was felt that head, and its frequent companion, tail, were useful mostly to interactive users, and not application programs. However, balloting input suggested that these utilities actually do find significant use in scripts, such as to write out portions of log files. Although it is possible to simulate head with sed 10q for a single file, the working group decided that the popularity of head on historical BSD systems warranted its inclusion alongside tail. An earlier draft had the synopsis line: head [ -c | -l ] [-n _n_u_m_b_e_r] [_f_i_l_e ...] Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 548 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 This was changed to the current form based on comments and objections noting that -c has not been provided by historical versions of head and other utilities in POSIX.2 provide similar functionality. Also, -l was changed to -n to match a similar change in tail. END_RATIONALE 4.30 id - Return user identity 4.30.1 Synopsis id [_u_s_e_r] id -G [-n] [_u_s_e_r] id -g [-nr] [_u_s_e_r] id -u [-nr] [_u_s_e_r] 4.30.2 Description If no _u_s_e_r operand is provided, the id utility shall write the user and group IDs and the corresponding user and group names of the invoking process to standard output. If the effective and real IDs do not match, both shall be written. If multiple groups are supported by the underlying system (see the description of {NGROUPS_MAX} in POSIX.1 {8}), the supplementary group affiliations of the invoking process also shall be written. If a _u_s_e_r operand is provided and the process has the appropriate privileges, the user and group IDs of the selected user shall be written. In this case, effective IDs shall be assumed to be identical to real IDs. 1 If the selected user has more than one allowable group membership listed 1 in the group database (see POSIX.1 {8} section 9.1), these shall be 1 written in the same manner as the supplementary groups described in the 1 preceding paragraph. 1 4.30.3 Options The id utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.30 id - Return user identity 549 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX -G Output all different group IDs (effective, real, and supplementary) only, using the format "%u\n". If there is more than one distinct group affiliation, output each such affiliation, using the format " %u", before the is output. -g Output only the effective group ID, using the format "%u\n". -n Output the name in the format "%s" instead of the numeric ID using the format "%u". -r Output the real ID instead of the effective ID. -u Output only the effective user ID, using the format "%u\n". 4.30.4 Operands The following operand shall be supported by the implementation: _u_s_e_r The login name for which information is to be written. 4.30.5 External Influences 4.30.5.1 Standard Input None. 4.30.5.2 Input Files None. 4.30.5.3 Environment Variables The following environment variables shall affect the execution of id: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 550 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments). LC_MESSAGES This variable shall determine the language in which messages should be written. 4.30.5.4 Asynchronous Events Default. 4.30.6 External Effects 4.30.6.1 Standard Output The following formats shall be used when the LC_MESSAGES locale category specifies the POSIX Locale. In other locales, the strings uid, gid, euid, egid, and groups may be replaced with more appropriate strings corresponding to the locale. "uid=%u(%s) gid=%u(%s)\n", <_r_e_a_l _u_s_e_r _I_D>, <_u_s_e_r-_n_a_m_e>, <_r_e_a_l _g_r_o_u_p _I_D>, <_g_r_o_u_p-_n_a_m_e> If the effective and real user IDs do not match, the following shall be inserted immediately before the \n character in the previous format: " euid=%u(%s)", with the following arguments added at the end of the argument list: <_e_f_f_e_c_t_i_v_e _u_s_e_r _I_D>, <_e_f_f_e_c_t_i_v_e _u_s_e_r-_n_a_m_e> If the effective and real group IDs do not match, the following shall be inserted directly before the \n character in the format string (and after any addition resulting from the effective and real user IDs not matching): " egid=%u(%s)", with the following arguments added at the end of the argument list: <_e_f_f_e_c_t_i_v_e _g_r_o_u_p-_I_D>, <_e_f_f_e_c_t_i_v_e _g_r_o_u_p _n_a_m_e> If the process has supplementary group affiliations or the selected user 1 is allowed to belong to multiple groups, the first shall be added 1 directly before the character in the format string: Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.30 id - Return user identity 551 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX " groups=%u(%s)" with the following arguments added at the end of the argument list: <_s_u_p_p_l_e_m_e_n_t_a_r_y _g_r_o_u_p _I_D>, <_s_u_p_p_l_e_m_e_n_t_a_r_y _g_r_o_u_p _n_a_m_e> and the necessary number of the following added after that for any remaining supplementary group IDs: ",%u(%s)" and the necessary number of the following arguments added at the end of the argument list: <_s_u_p_p_l_e_m_e_n_t_a_r_y _g_r_o_u_p _I_D>, <_s_u_p_p_l_e_m_e_n_t_a_r_y _g_r_o_u_p _n_a_m_e> If any of the user ID, group ID, effective user ID, effective group ID, 1 or supplementary/multiple group IDs cannot be mapped by the system into 1 printable user or group names, the corresponding (%s) and name argument shall be omitted from the corresponding format string. When any of the options are specified, the output format shall be as described under 4.30.3. 4.30.6.2 Standard Error Used only for diagnostic messages. 4.30.6.3 Output Files None. 4.30.7 Extended Description None. 4.30.8 Exit Status The id utility shall exit with one of the following values: 0 Successful completion. >0 An error occurred. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 552 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.30.9 Consequences of Errors Default. BEGIN_RATIONALE 4.30.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e The functionality provided by the 4BSD groups utility can be simulated using: id -Gn [_u_s_e_r] Note that output produced by the -G option and by the default case could potentially produce very long lines on systems that support large numbers of supplementary groups. (On systems with user and group IDs that are 32-bit integers and with group names with a maximum of 8 bytes per name, 93 supplementary groups plus distinct effective and real group and user IDs could theoretically overflow the 2048-byte {LINE_MAX} text file line limit on the default output case. It would take about 186 supplementary groups to overflow the 2048-byte barrier using id -G.) This is not expected to be a problem in practice, but in cases where it is a concern, applications should consider using fold -s (see 4.25) before postprocessing the output of id. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The 4BSD command groups was considered, but was not used as it did not provide the functionality of the id utility of the _S_V_I_D. Also, it was thought that it would be easier to modify id to provide the additional functionality necessary to systems with multiple groups than to invent another command. The options -u, -g, -n, and -r were added to ease the use of id with shell commands substitution. Without these options it is necessary to use some preprocessor such as sed to select the desired piece of information. Since output such as that produced by id -u -n is wanted frequently, it seemed desirable to add the options. END_RATIONALE Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.30 id - Return user identity 553 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.31 join - Relational database operator 4.31.1 Synopsis join [ -a _f_i_l_e__n_u_m_b_e_r | -v _f_i_l_e__n_u_m_b_e_r ] [-e _s_t_r_i_n_g] [-o _l_i_s_t] [-t _c_h_a_r] [-1 _f_i_e_l_d] [-2 _f_i_e_l_d] _f_i_l_e_1 _f_i_l_e_2 _O_b_s_o_l_e_s_c_e_n_t _v_e_r_s_i_o_n: join [-_a _f_i_l_e__n_u_m_b_e_r] [-e _s_t_r_i_n_g] [-j _f_i_e_l_d] [-j1 _f_i_e_l_d] [-j2 _f_i_e_l_d] [-o _l_i_s_t ...] [-t _c_h_a_r] _f_i_l_e_1 _f_i_l_e_2 4.31.2 Description The join utility shall perform an ``equality join'' on the files _f_i_l_e_1 and _f_i_l_e_2. The joined files shall be written to the standard output. The ``join field'' is a field in each file on which the files are compared. There shall be one line in the output for each pair of lines in _f_i_l_e_1 and _f_i_l_e_2 that have identical join fields. The output line by default shall consist of the join field, then the remaining fields from _f_i_l_e_1, then the remaining fields from _f_i_l_e_2. This format can be changed by using the -o option (see below). The -a option can be used to add unmatched lines to the output. The -v option can be used to output only unmatched lines. By default, the files _f_i_l_e_1 and _f_i_l_e_2 should be ordered in the collating sequence of sort -b (see 4.58) on the fields on which they are to be joined, by default the first in each line. All selected output shall be written in the same collating sequence. The default input field separators shall be s. In this case, multiple separators shall count as one field separator, and leading separators shall be ignored. The default output field separator shall be a . The field separator and collating sequence can be changed by using the -t option (see below). If the input files are not in the appropriate collating sequence, the results are unspecified. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 554 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.31.3 Options The join utility shall conform to the utility argument syntax guidelines described in 2.10.2. The obsolescent version does not follow the utility argument syntax guidelines: the -j1 and -j2 options are multicharacter options and the -o option takes multiple arguments. The following options shall be supported by the implementation: -a _f_i_l_e__n_u_m_b_e_r Produce a line for each unpairable line in file _f_i_l_e__n_u_m_b_e_r, where _f_i_l_e__n_u_m_b_e_r is 1 or 2, in addition to the default output. If both -a 1 and -a 2 are specified, all unpairable lines shall be output. -e _s_t_r_i_n_g Replace empty output fields by string _s_t_r_i_n_g. -j _f_i_e_l_d (Obsolescent.) Equivalent to: -1 _f_i_e_l_d -2 _f_i_e_l_d -j1 _f_i_e_l_d (Obsolescent.) Equivalent to: -1 _f_i_e_l_d -j2 _f_i_e_l_d (Obsolescent.) Equivalent to: -2 _f_i_e_l_d -o _l_i_s_t Construct the output line to comprise the fields specified in _l_i_s_t, each element of which has the form _f_i_l_e__n_u_m_b_e_r._f_i_e_l_d, where _f_i_l_e__n_u_m_b_e_r is a file number and _f_i_e_l_d is a decimal integer field number. The elements of _l_i_s_t are either comma- or -separated, as specified in Guideline 8 in 2.10.2. The fields specified by _l_i_s_t shall be written for all selected output lines. Fields selected by _l_i_s_t that do not appear in the input shall be treated as empty output fields. (See the -e option.) The join field shall not be written unless specifically requested. The _l_i_s_t shall be a single command line argument. However, as an obsolescent feature, the argument _l_i_s_t can be multiple arguments on the command line. If this is the case, and if the -o option is the last option before _f_i_l_e_1, and if _f_i_l_e_1 is of the form _s_t_r_i_n_g._s_t_r_i_n_g, the results are undefined. -t _c_h_a_r Use character _c_h_a_r as a separator, for both input and output. Every appearance of _c_h_a_r in a line shall be significant. When this option is specified, the collating sequence should be the same as sort without the -b option. -v _f_i_l_e__n_u_m_b_e_r Instead of the default output, produce a line only for each unpairable line in _f_i_l_e__n_u_m_b_e_r, where _f_i_l_e__n_u_m_b_e_r is 1 or 2. If both -v 1 and -v 2 are specified, all Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.31 join - Relational database operator 555 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX unpairable lines shall be output. -1 _f_i_e_l_d Join on the _f_i_e_l_dth field of file 1. Fields are decimal integers starting with 1. -2 _f_i_e_l_d Join on the _f_i_e_l_dth field of file 2. Fields are decimal integers starting with 1. 4.31.4 Operands The following operands shall be supported by the implementation: _f_i_l_e_1 _f_i_l_e_2 A pathname of a file to be joined. If either of the _f_i_l_e_1 or _f_i_l_e_2 operands is -, the standard input is used in its place. 4.31.5 External Influences 4.31.5.1 Standard Input The standard input shall be used only if the _f_i_l_e_1 or _f_i_l_e_2 operand is -. See Input Files. 4.31.5.2 Input Files The input files shall be text files. 4.31.5.3 Environment Variables The following environment variables shall affect the execution of join: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_COLLATE This variable shall determine the collating sequence join expects to have been used when the input files were sorted. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 556 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files). LC_MESSAGES This variable shall determine the language in which messages should be written. 4.31.5.4 Asynchronous Events Default. 4.31.6 External Effects 4.31.6.1 Standard Output The join utility output shall be a concatenation of selected character fields. When the -o option is not specified, the output shall be: "%s%s%s\n", <_j_o_i_n _f_i_e_l_d>, <_o_t_h_e_r _f_i_l_e_1 _f_i_e_l_d_s>, <_o_t_h_e_r _f_i_l_e_2 _f_i_e_l_d_s> If the join field is not the first field in either file, the <_o_t_h_e_r _f_i_l_e _f_i_e_l_d_s> are: <_f_i_e_l_d_s _p_r_e_c_e_d_i_n_g _j_o_i_n _f_i_e_l_d>, <_f_i_e_l_d_s _f_o_l_l_o_w_i_n_g _j_o_i_n _f_i_e_l_d> When the -o option is specified, the output format shall be: "%s\n", <_c_o_n_c_a_t_e_n_a_t_i_o_n _o_f _f_i_e_l_d_s> where the concatenation of fields is described by the -o option, above. For either format, each field (except the last) shall be written with its trailing separator character. If the separator is the default (s), a single character shall be written after each field (except the last). 4.31.6.2 Standard Error Used only for diagnostic messages. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.31 join - Relational database operator 557 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.31.6.3 Output Files None. 4.31.7 Extended Description None. 4.31.8 Exit Status The join utility shall exit with one of the following values: 0 All input files were output successfully. >0 An error occurred. 4.31.9 Consequences of Errors Default. BEGIN_RATIONALE 4.31.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e Pathnames consisting of numeric digits should not be specified directly following the -o list. The developers of the standard believed that join should operate as documented in the _S_V_I_D and BSD, not as historically implemented. Historical implementations do not behave as documented in these areas: (1) Most implementations of join require using the -o option when using the -e option. (2) Most implementations do not parse the -o option as documented, and parse the elements as separate _a_r_g_v items, until the item is not of the form _f_i_l_e__n_u_m_b_e_r._f_i_e_l_d. This behavior is permitted as an obsolescent usage of the utility. To ensure maximum portability, _f_i_l_e_1 should not be of the form _s_t_r_i_n_g._s_t_r_i_n_g. A suitable alternative to guarantee portability would be to put the -- flag before any _f_i_l_e_1 operand. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 558 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 The obsolescent -j, -j1, and -j2 options have been described to show how they have been used in historical implementations. Earlier drafts showed -j _f_i_l_e__n_u_m_b_e_r _f_i_e_l_d, but a space was never allowed before the _f_i_l_e__n_u_m_b_e_r and two option arguments were never intended. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The ability to specify _f_i_l_e_2 as - is not historical practice; it was added for completeness. As a result of a balloting comment, the -v option was added to the nonobsolescent version. This option was felt necessary because it permitted the writing of _o_n_l_y those lines that do not match on the join field, as opposed to the -a option, which prints both lines that do and do not match. This additional facility is parallel with the -v option of grep. END_RATIONALE 4.32 kill - Terminate or signal processes 4.32.1 Synopsis kill -s _s_i_g_n_a_l__n_a_m_e _p_i_d ... kill -l [_e_x_i_t__s_t_a_t_u_s] _O_b_s_o_l_e_s_c_e_n_t _V_e_r_s_i_o_n_s: kill [-_s_i_g_n_a_l__n_a_m_e] _p_i_d ... kill [-_s_i_g_n_a_l__n_u_m_b_e_r] _p_i_d ... 4.32.2 Description The kill utility shall send a signal to the process(es) specified by each _p_i_d operand. For each _p_i_d operand, the kill utility shall perform actions equivalent to the POSIX.1 {8} _k_i_l_l() function called with the following arguments: (1) The value of the _p_i_d operand shall be used as the _p_i_d argument. (2) The _s_i_g argument is the value specified by the -s option, -_s_i_g_n_a_l__n_u_m_b_e_r option, or the -_s_i_g_n_a_l__n_a_m_e option, or by SIGTERM, if none of these options is specified. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.32 kill - Terminate or signal processes 559 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.32.3 Options The kill utility shall conform to the utility argument syntax guidelines described in 2.10.2, except that in the obsolescent form, the -_s_i_g_n_a_l__n_u_m_b_e_r and -_s_i_g_n_a_l__n_a_m_e options are usually more than a single character. The following options shall be supported by the implementation: -l (The letter ell.) Write all values of _s_i_g_n_a_l__n_a_m_e supported by the implementation, if no operand is given. If an _e_x_i_t__s_t_a_t_u_s operand is given and it is a value of the ? shell special parameter (see 3.5.2 and wait in 4.70) corresponding to a process that was terminated by a signal, the _s_i_g_n_a_l__n_a_m_e corresponding to the signal that terminated the process shall be written. If an _e_x_i_t__s_t_a_t_u_s operand is given and it is the unsigned decimal integer value of a signal number, the _s_i_g_n_a_l__n_a_m_e (the POSIX.1 {8}-defined symbolic constant name without the SIG prefix) corresponding to that signal shall be written. Otherwise, the results are unspecified. -s _s_i_g_n_a_l__n_a_m_e Specify the signal to send, using one of the symbolic names defined for Required Signals or Job Control Signals in POSIX.1 {8} 3.3.1.1. Values of _s_i_g_n_a_l__n_a_m_e shall be recognized in a case-independent fashion, without the SIG prefix. In addition, the symbolic name 0 shall be recognized, representing the signal value zero. The corresponding signal shall be sent instead of SIGTERM. -_s_i_g_n_a_l__n_a_m_e (Obsolescent.) Equivalent to -s _s_i_g_n_a_l__n_a_m_e. -_s_i_g_n_a_l__n_u_m_b_e_r (Obsolescent.) Specify a nonnegative decimal integer, _s_i_g_n_a_l__n_u_m_b_e_r, representing the signal to be used instead of SIGTERM, as the _s_i_g argument in the effective call to _k_i_l_l(). The correspondence between integer values and the _s_i_g value used is shown in the following table. _ssss_iiii_gggg_nnnn_aaaa_llll______nnnn_uuuu_mmmm_bbbb_eeee_rrrr _ssss_iiii_gggg Value _____________ _________ 0 0 1 SIGHUP 2 SIGINT 3 SIGQUIT 6 SIGABRT Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 560 4 Execution Environment Utilities