IEEE P1003.2a Draft 8 - December 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 -- Amd. 1: UPE P1003.2a/D8 5.18.8 Exit Status The more utility shall exit with one of the following values: 0 Successful completion. >0 An error occurred. 5.18.9 Consequences of Errors If an error is encountered accessing a file when using the :n command, more shall attempt to examine the next file in the argument list, but the final exit status shall be affected. If an error is encountered accessing a file via the :p command, more shall attempt to examine the previous file in the argument list, but the final exit status shall be affected. If an error is encountered accessing a file via the :e command, more shall remain in the current file and the final exit status shall not be affected. BEGIN_RATIONALE 5.18.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_a) _U_s_a_g_e_,__E_x_a_m_p_l_e_s The text stating ``from a nonrewindable stream ... implementations may limit the amount of backward motion supported'' would allow an implementation that permitted no backward motion beyond text already on the screen. It was not possible to require a minimum amount of backward motion that would be effective for all conceivable device types. The implementation should allow the user to back up as far as possible, within device and reasonable memory allocation constraints. The -p allows arbitrary commands to be executed at the start of each 8 file. Examples are: 8 more -p G file1 file2 Examine each file starting with its last 8 screenful. 8 more -p 100 file1 file2 Examine each file starting with line 100 8 in the current position (usually the 8 third line, so line 98 would be the first 8 line written). 8 more -p /100 file1 file2 Examine each file starting with the first 8 line containing the string 100 in the 8 current position 8 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.18 more - Display files on a page-by-page basis 221 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The more utility, available in BSD and BSD-derived systems, was chosen as the prototype for the POSIX.2 file display program since it is more widely available than either the public-domain program less or pg, a pager provided in System V. The 4.4BSD more is the model for the features selected; it is almost fully upward-compatible from the 4.3BSD version in wide use and has become more amenable for vi users. Several features originally derived from various file editors, found in both less and pg, have been added to this specification as they have proved extremely popular with users. There are inconsistencies between more and vi that result from historical practice. For example, the single-character commands h, f, b, and are screen movers in more, but cursor movers in vi. These inconsistencies were maintained because the cursor movements are not applicable to more and the powerful functionality achieved without the use of the control key justifies the differences in most users' minds. The tags interface has been included in a program that is not a text editor because it promotes another degree of consistent operation with vi. It is conceivable that the paging environment of more would be superior for browsing source code files in some circumstances. The operating mode referred to for block-mode terminals effectively adds a to each synopsis line that currently has none. So, for example, d would page one screenful. The mode could be triggered by a command-line option, environment variable, or some other method. The details are not imposed by POSIX.2 because there are so few systems known to support such terminals. Nevertheless, it was felt that all systems should be able to support more given the exception cited for this small community of terminals because, in comparison to vi, the cursor movements are few and the command set relatively amenable to the optional s. Some versions of more provide a shell escaping mechanism similar to the 7 ex ! command. The working group did not feel this was necessary in a 7 paginator, particularly given the wide acceptance of multiple window 7 terminals and job control features. (It chose to retain such features in 7 the editors and mailx because the shell interaction also gives an 7 opportunity to modify the editing buffer, which is not applicable to 7 more). 7 The -p (position) option replaces the + command because of the utility 8 syntax guidelines. In earlier drafts, it took a _p_a_t_t_e_r_n argument, but 8 historical less provided the more general facility of a command. It 8 would have been desirable to use the same -c as ex and vi, but the letter 8 was already in use. 8 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 222 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 When the standard output is not a terminal, none of the filter- 8 modification options are effective. This is based on historical 8 practice. For example, a typical implementation of man pipes its output 8 through more -s to squeeze excess white space for terminal users. When 8 man is piped to lp, however, it is undesirable for this squeezing to 8 happen. 8 END_RATIONALE 8 5.19 newgrp - Change to a new group 5.19.1 Synopsis newgrp [-l] [_g_r_o_u_p] _O_b_s_o_l_e_s_c_e_n_t _V_e_r_s_i_o_n: newgrp [-] [_g_r_o_u_p] 5.19.2 Description The newgrp utility shall create a new shell execution environment with a new real and effective group identification. Of the attributes listed in 3.12, the new shell execution environment shall retain the working directory, file creation mask, and exported variables from the previous environment (i.e., open files, traps, unexported variables, alias definitions, shell functions, and set options may be lost). All other aspects of the process environment that are preserved by the _e_x_e_c family of functions in POSIX.1 {8} also shall be preserved by newgrp; whether other aspects are preserved is unspecified. A new shell execution environment shall be created whether or not newgrp is able to change to the requested new group. If the POSIX.1 {8} {NGROUPS_MAX} is greater than 1, newgrp shall add the specified group to the supplemental groups for the process, if there is room to add another group. With no operands, newgrp shall change the effective group back to the group(s) identified in the user's user entry, and if {NGROUPS_MAX} is greater than 1, shall set the list of supplementary groups to that set in the user's group database entries. If a password is required for the specified group, and the user is not listed as a member of that group in the group database, the user shall be prompted to enter the correct password for that group. If the user is Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.19 newgrp - Change to a new group 223 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX listed as a member of that group, no password shall be requested. If no password is required for the specified group, it is implementation defined whether users not listed as members of that group can change to that group. Whether or not a password is required, implementation- defined system accounting mechanisms may impose additional authorization restrictions that may cause newgrp to exit with an error status. 5.19.3 Options The newgrp utility shall conform to the utility argument syntax guidelines described in 2.10.2, except that the obsolescent version uses - in a nonstandard manner. The following option shall be supported by the implementation: -l (The letter ell.) - (Obsolescent.) Change the environment to what would be expected if the user actually logged in again. 5.19.4 Operands The following operand shall be supported by the implementation: _g_r_o_u_p A group name from the group database or a nonnegative numeric group ID. Either specifies the group ID to which the real and effective group IDs shall be set. If _g_r_o_u_p is a nonnegative numeric string and exists in the group database as a group name [see _g_e_t_g_r_n_a_m() in POSIX.1 {8} 9.2.1], the numeric group ID associated with that group name shall be used as the group ID. 5.19.5 External Influences 5.19.5.1 Standard Input None. 5.19.5.2 Input Files The file /dev/tty shall be used to read a single line of text for password checking, when one is required. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 224 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.19.5.3 Environment Variables The following environment variables shall affect the execution of newgrp: 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_CTYPE This variable shall determine 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. 5.19.5.4 Asynchronous Events Default. 5.19.6 External Effects 5.19.6.1 Standard Output None. 5.19.6.2 Standard Error Used for diagnostic messages and a prompt string for a password, if one is required. 5.19.6.3 Output Files None. 5.19.7 Extended Description None. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.19 newgrp - Change to a new group 225 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX 5.19.8 Exit Status If newgrp succeeds, the exit status shall be the exit status of the shell. Otherwise, the newgrp utility shall exit with the following value: >0 An error occurred. 5.19.9 Consequences of Errors The invoking shell may terminate. BEGIN_RATIONALE 5.19.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_a) _U_s_a_g_e_,__E_x_a_m_p_l_e_s None. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e Most historical implementations use one of the _e_x_e_c functions to implement the behavior of newgrp. Errors detected before the _e_x_e_c leave the environment unchanged, while errors detected after the _e_x_e_c leave the user in a changed environment. While it would be useful to have newgrp issue a diagnostic message to tell the user that the environment changed, it would be inappropriate to require this change to some historical implementations. The password mechanism is allowed in the group file, but how this would be implemented is not specified. The newgrp utility was retained in POSIX.2 even given the existence of the multiple group permissions feature in POSIX.1 {8}, because it allows files to be created with a specific group ownership. In some systems, the group ownership is determined by the group of the parent directory in which a file is created, as allowed by POSIX.1 {8}; on such systems, 8 newgrp does not affect the group ownership in directories where the 8 parent directory dictates it. However, POSIX.1 {8} allows systems to 8 omit this feature; therefore, the newgrp functionality is still required on those systems. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 226 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.20 nice - Invoke a utility with an altered system scheduling priority 5.20.1 Synopsis nice [-n _i_n_c_r_e_m_e_n_t] _u_t_i_l_i_t_y [_a_r_g_u_m_e_n_t ...] _O_b_s_o_l_e_s_c_e_n_t _V_e_r_s_i_o_n: nice [-_i_n_c_r_e_m_e_n_t] _u_t_i_l_i_t_y [_a_r_g_u_m_e_n_t ...] 5.20.2 Description The nice utility shall invoke a utility, requesting that it be run with a 7 different system scheduling priority (see 2.2.2.212). With no options 7 and only if the user has appropriate privileges, the executed utility 7 shall be run with a system scheduling priority that is some 7 implementation-defined quantity less than or equal to the system 7 scheduling priority of the current process. If the user lacks 7 appropriate privileges to affect the system scheduling priority in the 7 requested manner, the nice utility shall not affect the system scheduling 7 priority; in this case, a warning message may be written to standard 8 error, but this shall not prevent the invocation of _u_t_i_l_i_t_y or affect the 8 exit status. 8 5.20.3 Options The nice utility shall conform to the utility argument syntax guidelines described in 2.10.2, except that the obsolescent version allows a multidigit decimal integer as an option name. The following option shall be supported by the implementation: -n _i_n_c_r_e_m_e_n_t -_i_n_c_r_e_m_e_n_t (Obsolescent.) Specify how the system scheduling priority of the executed utility shall be adjusted. The _i_n_c_r_e_m_e_n_t option-argument shall be a positive or negative decimal integer that shall be used to modify the system scheduling priority of the executed utility in an implementation-defined manner. Positive _i_n_c_r_e_m_e_n_t values shall cause a lower or unchanged system scheduling priority. Negative _i_n_c_r_e_m_e_n_t values may require appropriate privileges and shall cause a higher or unchanged system scheduling priority. The system scheduling priority shall be bounded in an implementation-defined manner. If the requested _i_n_c_r_e_m_e_n_t Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.20 nice - Invoke a utility with an altered system scheduling priority227 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX would raise or lower the system scheduling priority of the executed utility beyond implementation-defined limits, then the limit whose value was exceeded shall be used. 5.20.4 Operands The following operands shall be supported by the implementation: _u_t_i_l_i_t_y The name of a utility that is to be invoked. If the _u_t_i_l_i_t_y operand names any of the special built-in utilities in 3.14, the results are undefined. _a_r_g_u_m_e_n_t Any string to be supplied as an argument when invoking the utility named by the _u_t_i_l_i_t_y operand. 5.20.5 External Influences 5.20.5.1 Standard Input None. 5.20.5.2 Input Files None. 5.20.5.3 Environment Variables The following environment variables shall affect the execution of nice: 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_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. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 228 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 PATH This variable shall determine the search path used to locate the utility to be invoked. See 2.6. 5.20.5.4 Asynchronous Events Default. 5.20.6 External Effects 5.20.6.1 Standard Output None. 5.20.6.2 Standard Error Used only for diagnostic messages. 5.20.6.3 Output Files None. 5.20.7 Extended Description None. 5.20.8 Exit Status If the _u_t_i_l_i_t_y utility is invoked, the exit status of nice shall be the 7 exit status of _u_t_i_l_i_t_y; otherwise, the nice utility shall exit with one 7 of the following values: 7 1-125 An error occurred in the nice utility. 7 126 The utility specified by _u_t_i_l_i_t_y was found but could not be 7 invoked. 7 127 The utility specified by _u_t_i_l_i_t_y could not be found. 7 5.20.9 Consequences of Errors Default. BEGIN_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.20 nice - Invoke a utility with an altered system scheduling priority229 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX 5.20.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_a) _U_s_a_g_e_,__E_x_a_m_p_l_e_s Note that, in the obsolescent version, -5 is a positive _i_n_c_r_e_m_e_n_t, while --5 is a negative _i_n_c_r_e_m_e_n_t. While this might appear counterintuitive, it is how historical versions of nice work. The only guaranteed portable uses of this utility are: nice _u_t_i_l_i_t_y Run _u_t_i_l_i_t_y with the default lower system scheduling priority. nice -n <_p_o_s_i_t_i_v_e _i_n_t_e_g_e_r> _u_t_i_l_i_t_y Run _u_t_i_l_i_t_y with a lower system scheduling priority. On some systems they will have no discernible effect on the invoked utility and on others they will be exactly equivalent. Historical systems have frequently supported the <_p_o_s_i_t_i_v_e _i_n_t_e_g_e_r> up to 20. Since there is no error penalty associated with guessing a number that is too high, users without access to the system conformance document (to see what limits are actually in place) could use the historical 1 to 20 range or attempt to use very large numbers if the job should be truly low priority. The system scheduling priority value of a process can be displayed using the command: ps -o nice The command, env, nice, nohup, time, and xargs utilities have been 7 specified to use exit code 127 if an error occurs so that applications 7 can distinguish ``failure to find a utility'' from ``invoked utility 7 exited with an error indication.'' The value 127 was chosen because it 7 is not commonly used for other meanings; most utilities use small values 7 for ``normal error conditions'' and the values above 128 can be confused 7 with termination due to receipt of a signal. The value 126 was chosen in 7 a similar manner to indicate that the utility could be found, but not 7 invoked. Some scripts produce meaningful error messages differentiating 7 the 126 and 127 cases. The distinction between exit codes 126 and 127 is 8 based on KornShell practice that uses 127 when all attempts to _e_x_e_c the 8 utility fail with [ENOENT], and uses 126 when any attempt to _e_x_e_c the 8 utility fails for any other reason. In System V, the exit status from 8 nice, when nice detects an error, is 2. In 4.3BSD the status is 1. 7 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 230 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e Due to the text about the limits of the system scheduling priority being implementation defined, nice is not required to actually change the priority of the executed command; the limits could be zero differences from the system default, although the implementor is required to document this fact in the conformance document. Because of this, including this utility in POSIX.2 does not require implementations to support something like the traditional _n_i_c_e() system call. In particular, a POSIX.2 implementation could run on a nonextended POSIX.1 {8} implementation simply by supplying the following nice utility. (The example supports only the nonobsolescent form for illustrative purposes.) #include extern int optind; extern char *optarg; #define USAGE "Usage: nice [-n incr] [ ...]\n" int main(int argc, char *argv[]); { int i; while ((i = getopt(argc, argv, "n:")) != EOF) { switch (i) { default: fprintf(stderr, USAGE); exit(127); case 'n': /* ignore increment */ break; } } argc -= optind; argv += optind; if (argc > 0) { execvp(argv[0], &argv[0]); perror(argv[0]); } else { fprintf(stderr, USAGE); } exit(127); } On systems that choose this approach, nice is a benign no-op. On the vast majority of systems that support nice historically, it becomes more useful. The developers of the standard considered this a quality of implementation issue and resisted calls to omit nice unless it could be guaranteed to have a discernible effect on all systems. The efficacy of nice is a legitimate procurement consideration. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.20 nice - Invoke a utility with an altered system scheduling priority231 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX The 4.3BSD version of nice does not check if _i_n_c_r_e_m_e_n_t is a valid decimal integer. The command "nice -x utility", for example, would be treated the same as the command "nice --1 utility". If the user does not have appropriate privileges, this will result in a ``permission denied'' error. This is considered a bug. When a user without appropriate privileges gives a negative _i_n_c_r_e_m_e_n_t, System V treats it like the command "nice -0 utility", while 4.3BSD writes a ``permission denied'' message and does not run the utility. Neither was considered clearly superior, so the behavior was left unspecified. The C-shell has a built-in version of nice that has a different interface from the one described here. The term ``utility'' is used, rather than ``command,'' to highlight the fact that shell compound commands, pipelines, etc., cannot be used. Special built-ins also cannot be used. However, ``utility'' includes user application programs and shell scripts, not just utilities defined in this standard. Historical implementations of nice provide a priority range of 40 or 41 discrete steps, with the default priority being the midpoint of that range. By default they lower the priority of the executed utility by 10. Some historical documentation states that the _i_n_c_r_e_m_e_n_t value must be within a fixed range. This is misleading; the valid _i_n_c_r_e_m_e_n_t values on any invocation are determined by the current process priority, which is not always the default. The two limits in a previous draft, {POSIX2_MAX_NICE} and {POSIX2_MIN_NICE}, were removed when the nice description was reworded to allow users to exceed the system's range with impunity. The definition of _s_y_s_t_e_m _s_c_h_e_d_u_l_i_n_g _p_r_i_o_r_i_t_y is not intended to suggest 7 that all processes in a system have priorities that are comparable. 7 Scheduling policy extensions such as the realtime priorities in POSIX.4 7 make the notion of a single underlying priority for all scheduling 7 policies problematic. Some systems may implement the nice-_r_e_l_a_t_e_d 7 features to affect all processes on the system, others to affect just the 7 general time-sharing activities implied by POSIX.2, and others may have 7 no effect at all. Because of the use of ``implementation defined'' in 7 nice and renice, a wide range of implementation strategies are possible. 7 END_RATIONALE 7 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 232 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.21 nm - Write the name list of an object file This utility shall be provided on systems that support both the User 7 Portability Utilities Option and the Software Development Utilities 7 Option. On other systems it is optional. 7 5.21.1 Synopsis nm [-APv] [ -g | -u ] [-t _f_o_r_m_a_t] _f_i_l_e ... 5.21.2 Description The nm utility shall display symbolic information appearing in the object file, executable file, or object-file library named by _f_i_l_e. If no symbolic information is available for a valid input file, the nm utility shall report that fact, but not consider that an error condition. The default base used when numeric values are written is unspecified. 5.21.3 Options The nm utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -A Write the full pathname or library name of an object on each line. -g Write only external (global) symbol information. -P Write information in a portable output format, as specified in 5.21.6.1. -t _f_o_r_m_a_t Write each numeric value in the specified format. The format shall be dependent on the single character used as the _f_o_r_m_a_t option-argument: d The offset shall be written in decimal. o The offset shall be written in octal. x The offset shall be written in hexadecimal. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.21 nm - Write the name list of an object file 233 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX -u Write only undefined symbols. -v Sort output by value instead of alphabetically. 5.21.4 Operands The following operand shall be supported by the implementation: _f_i_l_e A pathname of an object file, executable file, or object- file library. 5.21.5 External Influences 5.21.5.1 Standard Input See Input Files. 5.21.5.2 Input Files The input file shall be an object file, an object-file library whose 7 format is the same as those produced by the ar utility for link editing 7 (see 6.1), or an executable file. The _n_m utility may accept additional 7 implementation-defined object library formats for the input file. 7 5.21.5.3 Environment Variables The following environment variables shall affect the execution of nm: 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 character collation information for the symbol-name and symbol-value collation sequences. 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 7 characters in arguments). 7 Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 234 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 LC_MESSAGES This variable shall determine the language in which messages should be written. 5.21.5.4 Asynchronous Events Default. 5.21.6 External Effects 5.21.6.1 Standard Output If symbolic information is present in the input file(s), then for each 7 file, or for each member of an archive, the nm utility shall write the 7 following information to standard output. By default, the format is unspecified, but the output shall be sorted alphabetically by symbol name. - Library or object name, if -A is specified. - Symbol name. - Symbol type, which shall either be one of the following single 7 characters or an implementation-defined type represented by a 7 single character: 7 A Global absolute symbol a Local absolute symbol B Global ``bss'' (i.e., uninitialized data space) symbol b Local bss symbol D Global data symbol d Local data symbol T Global text symbol t Local text symbol U Undefined symbol - Value of the symbol. - The size associated with the symbol, if applicable. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.21 nm - Write the name list of an object file 235 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX This information may be supplemented by additional information specific to the implementation. If the -P option is specified, the previous information shall be displayed using the following portable format. The three versions differ depending on whether -t d, -t o, or -t x was specified, respectively: "%s: %s %s %d %d\n", <_l_i_b_r_a_r_y/_o_b_j_e_c_t _n_a_m_e>, <_n_a_m_e>, <_t_y_p_e>, <_v_a_l_u_e>, <_s_i_z_e> "%s: %s %s %o %o\n", <_l_i_b_r_a_r_y/_o_b_j_e_c_t _n_a_m_e>, <_n_a_m_e>, <_t_y_p_e>, <_v_a_l_u_e>, <_s_i_z_e> "%s: %s %s %x %x\n", <_l_i_b_r_a_r_y/_o_b_j_e_c_t _n_a_m_e>, <_n_a_m_e>, <_t_y_p_e>, <_v_a_l_u_e>, <_s_i_z_e> where <_l_i_b_r_a_r_y/_o_b_j_e_c_t _n_a_m_e> and its trailing colon and s are omitted when -A is not specified and <_s_i_z_e> and its preceding s are omitted when inapplicable to the symbol type. 5.21.6.2 Standard Error Used only for diagnostic messages. 5.21.6.3 Output Files None. 5.21.7 Extended Description None. 5.21.8 Exit Status The nm 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. 236 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.21.9 Consequences of Errors Default. BEGIN_RATIONALE 5.21.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_a) _U_s_a_g_e_,__E_x_a_m_p_l_e_s Historical implementations of nm have used different bases for numeric output and supplied different default types of symbols that were reported. The -t _f_o_r_m_a_t option, similar to that used in od and strings, can be used to specify the numeric base; -g and -u can be used to restrict the amount of output or the types of symbols included in the output. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The option list was significantly reduced from that provided by historical implementations. The nm description is a subset of both the System V and BSD nm utilities with no specified default output. 7 It was recognized that mechanisms for dynamic linking make this utility less meaningful when applied to a library, but the value of nm during software development was judged to outweigh other limitations. The compromise of using -t _f_o_r_m_a_t versus using -d, -o, and other similar options was necessary because of differences in the meaning of -o between implementations. The -o option from BSD has been provided here as -A to avoid collision with the -o from System V (which has been provided here as -t o). The default output format of nm is not specified because of differences in historical implementations. The P option was added to satisfy balloting objections relating to the use of nm in scripts as well as interactively. Some type of portable format was required. The format given in 5.21.6.1 uses spaces between the fields, which may be any number of s required to get the columns to line up. The single-character types were selected to match historical practice and the requirement that implementation additions also be single characters make parsing the information easier for shell scripts. END_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.21 nm - Write the name list of an object file 237 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX 5.22 patch - Apply changes to files 5.22.1 Synopsis patch [-blNR] [ -c | -e | -n ] [-d _d_i_r] [-D _d_e_f_i_n_e] [-i _p_a_t_c_h_f_i_l_e] 7 [-o _o_u_t_f_i_l_e] [-r _r_e_j_e_c_t_f_i_l_e] [_f_i_l_e] 8 5.22.2 Description The patch utility shall read a source (``patch'') file containing any of the three forms of difference (``diff'') listings produced by the diff (see 4.17) utility (normal, context, or in the style of ed; see 4.20) and apply those differences to a file. By default, patch shall read from the standard input. The patch utility shall attempt to determine the type of the diff listing, unless overruled by a -c, -e, or -n option. If the patch file contains more than one patch, patch shall attempt to apply each of them as if they came from separate patch files. (In this 7 case the name of the patch file must be determinable for each diff 7 listing.) 7 5.22.3 Options The patch utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -b Save a copy of the original contents of each modified 7 file, before the differences are applied, in a file of the 7 same name with the suffix .orig appended to it. If the 7 file already exists, it shall be overwritten; if multiple 7 patches are applied to the same file, the .orig file shall 7 be written only for the first patch. When the -o _o_u_t_f_i_l_e 8 option is also specified, _f_i_l_e.orig shall not be created 7 but, if _o_u_t_f_i_l_e already exists, _o_u_t_f_i_l_e.orig shall be 7 created. 7 -c Interpret the patch file as a context diff (the output of the utility diff when the -c or -C options are specified). -d _d_i_r Change the current directory to _d_i_r before processing as described in 5.22.7. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 238 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 -D _d_e_f_i_n_e Mark changes with the C preprocessor construct: #ifdef _d_e_f_i_n_e ... #endif The option-argument _d_e_f_i_n_e shall be used as the differentiating symbol. -e Interpret the patch file as an ed script, rather than a diff script. -i _p_a_t_c_h_f_i_l_e Read the patch information from the file named by the pathname _p_a_t_c_h_f_i_l_e, rather than the standard input. -l (The letter ell.) Cause any sequence of s in the diff script to match any sequence of s in the input file. Other characters shall be matched exactly. -n Interpret the script as a normal diff. -N Ignore patches where the differences have already been 7 applied to the file; by default, already-applied patches 7 shall be rejected. 7 -o _o_u_t_f_i_l_e Instead of modifying the files (specified by the _f_i_l_e 7 operand or the diff listings) directly, write a copy of 7 the file referenced by each patch, with the appropriate 7 differences applied, to _o_u_t_f_i_l_e. Multiple patches for a 7 single file shall be applied to the intermediate versions 7 of the file created by any previous patches, and shall 7 result in multiple, concatenated versions of the file 7 being written to _o_u_t_f_i_l_e. 7 8 -R Reverse the sense of the patch script; i.e., assume that the diff script was created from the new version to the old version. The -R option cannot be used with ed scripts. The patch utility attempts to reverse each portion of the script before applying it. Rejected differences shall be saved in swapped format. If this option is not specified, and until a portion of the patch file is successfully applied, patch attempts to apply each portion in its ``reversed'' sense as well as in its normal sense. If the attempt is successful, the user shall be prompted to determine if the -R option should be set. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.22 patch - Apply changes to files 239 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX -r _r_e_j_e_c_t_f_i_l_e Override the default reject file name. In the default 7 case, the reject file shall have the same name as the 7 output file, with the suffix .rej appended to it. See 7 5.22.7.3. 7 5.22.4 Operands The following operand shall be supported by the implementation: _f_i_l_e A pathname of a file to patch. 5.22.5 External Influences 5.22.5.1 Standard Input See Input Files. 5.22.5.2 Input Files Input files shall be text files. 5.22.5.3 Environment Variables The following environment variables shall affect the execution of patch: 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_CTYPE This variable shall determine 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 processing of 7 affirmative responses and the language in which 7 messages should be written. 7 LC_TIME This variable shall determine the locale for recognizing the format of file time stamps written by the diff utility in a context-diff input file. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 240 5 User Portability Utilities Option