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.15 jobs - Display status of jobs in the current session 5.15.1 Synopsis jobs [ -l | -p ] [_j_o_b__i_d ...] 5.15.2 Description The jobs utility shall display the status of jobs that were started in the current shell environment; see 3.12. When jobs reports the termination status of a job, the shell shall remove 7 its process ID from the list of those ``known in the current shell execution environment''; see 3.9.3.1. 5.15.3 Options The jobs utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -l (The letter ell.) Provide more information about each job listed. This information shall include the job number, current job, process group ID, state, and the command that formed the job. -p Display only the process IDs for the process group leaders of the selected jobs. By default, the jobs utility shall display the status of all stopped jobs, running background jobs, and all jobs whose status has changed and 7 have not been reported by the shell. 7 5.15.4 Operands The following operand shall be supported by the implementation: _j_o_b__i_d Specifies the jobs for which the status is to be displayed. If no _j_o_b__i_d is given, the status information for all jobs shall be displayed. The format of _j_o_b__i_d is described in 2.2.2.206. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.15 jobs - Display status of jobs in the current session 195 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX 5.15.5 External Influences 5.15.5.1 Standard Input None. 5.15.5.2 Input Files None. 5.15.5.3 Environment Variables The following environment variables shall affect the execution of jobs: 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. 5.15.5.4 Asynchronous Events Default. 5.15.6 External Effects 5.15.6.1 Standard Output If the -p option is specified, the output shall consist of one line for each process ID: "%d\n", <_p_r_o_c_e_s_s _I_D> Otherwise, if the -l option is not specified, the output shall be a series of lines of the form: Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 196 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 "[%d] %c %s %s\n", <_j_o_b-_n_u_m_b_e_r>, <_c_u_r_r_e_n_t>, <_s_t_a_t_e>, <_c_o_m_m_a_n_d> where the fields shall be as follows: <_c_u_r_r_e_n_t> The character + identifies the job that would be used as a default for the fg or bg utilities; this job can also be specified using the _j_o_b__i_d "%+" or "%%". The character - identifies the job that would become the default if the current default job were to exit; this job can also be specified using the _j_o_b__i_d "%-". For other jobs, this field is a . At most one job can be identified with + and at most one job can be identified with -. If there is any suspended job, then the current job shall be a suspended job. If there are at least two suspended jobs, then the previous job shall also be a suspended job. <_j_o_b-_n_u_m_b_e_r> A number that can be used to identify the process group to the wait, fg, bg, and kill utilities. Using these utilities, the job can be identified by prefixing the job number with %. <_s_t_a_t_e> One of the following strings (in the POSIX Locale): Running Indicates that the job has not been suspended by a signal and has not exited. Done Indicates that the job completed and returned exit status zero. Done(_c_o_d_e) Indicates that the job completed normally and that it exited with the specified nonzero exit status, _c_o_d_e, expressed as a decimal number. Stopped Stopped (SIGTSTP) Either indicates that the job was suspended by the SIGTSTP signal. Stopped (SIGSTOP) Indicates that the job was suspended by the SIGSTOP signal. Stopped (SIGTTIN) Indicates that the job was suspended by the SIGTTIN signal. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.15 jobs - Display status of jobs in the current session 197 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX Stopped (SIGTTOU) Indicates that the job was suspended by the SIGTTOU signal. The implementation may substitute the string Suspended in place of Stopped. If the job was terminated by a signal, the format of <_s_t_a_t_e> is unspecified, but it shall be visibly distinct from all of the other <_s_t_a_t_e> formats shown here and shall indicate the name or description of the signal causing the termination. <_c_o_m_m_a_n_d> The associated command that was given to the shell. If the -l option is specified, a field containing the process group ID shall be inserted before the <_s_t_a_t_e> field. Also, more processes in a process group may be output on separate lines, using only the process ID and <_c_o_m_m_a_n_d> fields. 5.15.6.2 Standard Error Used only for diagnostic messages. 5.15.6.3 Output Files None. 5.15.7 Extended Description None. 5.15.8 Exit Status The jobs utility shall exit with one of the following values: 0 Successful completion. >0 An error occurred. 5.15.9 Consequences of Errors Default. BEGIN_RATIONALE Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 198 5 User Portability Utilities Option PART 2: SHELL AND UTILITIES -- Amd. 1: UPE P1003.2a/D8 5.15.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 Both %% and %+ are used to refer to the current job. Both forms are of equal validity--the %% mirroring $$ and %+ mirroring the output of jobs. Both forms reflect historical practice of the KornShell and the C-Shell with job control. The -p option is historical practice in the KornShell and the System V jsh. It is the only way to find out the process group of a job because different implementations have different strategies for defining the process group of the job. Usage such as $(jobs -p) provides a way of referring to the process group of the job in an implementation- independent way. The jobs utility will not work as expected when it is operating in its own utility execution environment because that environment will have no applicable jobs to manipulate. See the rationale for bg. For this reason, jobs is generally implemented as a shell regular built-in. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The extensions to the shell specified in POSIX.2 and POSIX.2a have mostly been based on features provided by the KornShell. The job control features provided by bg, fg, and jobs are also based on the KornShell. The developers of the standard examined the characteristics of the C- Shell versions of these utilities and found that differences exist. Despite widespread use of the C-Shell, the KornShell versions were selected for this standard to maintain a degree of uniformity with the rest of the KornShell features selected (such as the very popular command-line editing features). The output for terminated jobs is left unspecified to accommodate various historical systems. The following formats have been witnessed: (1) Killed(_s_i_g_n_a_l _n_a_m_e) (2) _s_i_g_n_a_l _n_a_m_e (3) _s_i_g_n_a_l _n_a_m_e(_c_o_r_e_d_u_m_p) (4) _s_i_g_n_a_l _d_e_s_c_r_i_p_t_i_o_n - _c_o_r_e _d_u_m_p_e_d Most users should be able to figure these out, although it means that applications will have trouble parsing them. The calculation of job IDs was not described since this would suggest an implementation, which may impose unnecessary restrictions. Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 5.15 jobs - Display status of jobs in the current session 199 P1003.2a/D8 INFORMATION TECHNOLOGY--POSIX In an earlier draft, a -n option was included to ``Display the status of jobs that have changed, exited, or stopped since the last status report.'' It was removed because the shell always writes any changed status of jobs before each prompt. Thus, jobs -n is a no-op. END_RATIONALE 5.16 man - Display system documentation 5.16.1 Synopsis man [-k] _n_a_m_e ... 5.16.2 Description The man utility shall write information about each of the _n_a_m_e operands. If _n_a_m_e is the name of a standard utility, man shall at a minimum write a message describing the syntax used by the standard utility, its options, and operands. If more information is available, the man utility shall provide it in an implementation-defined manner. An implementation may provide information for values of _n_a_m_e other than the standard utilities. Standard utilities that are listed as optional and that are not supported by the implementation either shall cause a brief message indicating that fact to be displayed or shall cause a full display of information as described previously. 5.16.3 Options The man utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following option shall be supported by the implementation: -k Interpret _n_a_m_e operands as keywords to be used in searching a utilities summary database that contains a brief ``purpose'' entry for each standard utility and write lines from the summary database that match any of the keywords. The keyword search shall produce results that are the equivalent of the output of the following command: Copyright (c) 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 200 5 User Portability Utilities Option