1QSTAT(1P) POSIX Programmer's Manual QSTAT(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 qstat — show status of batch jobs
13
15 qstat [-f] job_identifier...
16 qstat -Q [-f] destination...
18 qstat -B [-f] server_name...
20
22 The status of a batch job, batch queue, or batch server is obtained by
23 a request to the server. The qstat utility is a user-accessible batch
24 client that requests the status of one or more batch jobs, batch
25 queues, or servers, and writes the status information to standard out‐
26 put.
27 For each successfully processed batch job_identifier, the qstat utility
29 shall display information about the corresponding batch job.
30 For each successfully processed destination, the qstat utility shall
32 display information about the corresponding batch queue.
33 For each successfully processed server name, the qstat utility shall
35 display information about the corresponding server.
36 The qstat utility shall acquire batch job status information by sending
38 a Job Status Request to a batch server. The qstat utility shall acquire
39 batch queue status information by sending a Queue Status Request to a
40 batch server. The qstat utility shall acquire server status information
41 by sending a Server Status Request to a batch server.
42
44 The qstat utility shall conform to the Base Definitions volume of
45 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
46 The following options shall be supported by the implementation:
48 -f Specify that a full display is produced.
50 The minimum contents of a full display are specified in the
52 STDOUT section.
53 Additional contents and format of a full display are imple‐
55 mentation-defined.
56 -Q Specify that the operand is a destination.
58 The qstat utility shall display information about each batch
60 queue at each destination identified as an operand.
61 -B Specify that the operand is a server name.
63 The qstat utility shall display information about each server
65 identified as an operand.
66
68 If the -Q option is presented to the qstat utility, the utility shall
69 accept one or more operands that conform to the syntax for a destina‐
70 tion (see Section 3.3.2, Destination).
71 If the -B option is presented to the qstat utility, the utility shall
73 accept one or more server_name operands.
74 If neither the -B nor the -Q option is presented to the qstat utility,
76 the utility shall accept one or more operands that conform to the syn‐
77 tax for a batch job_identifier (see Section 3.3.1, Batch Job Identi‐
78 fier).
79
81 Not used.
82
84 None.
85
87 The following environment variables shall affect the execution of
88 qstat:
89 HOME Determine the pathname of the user's home directory.
91 LANG Provide a default value for the internationalization vari‐
93 ables that are unset or null. (See the Base Definitions vol‐
94 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
95 ables the precedence of internationalization variables used
96 to determine the values of locale categories.)
97 LC_ALL If set to a non-empty string value, override the values of
99 all the other internationalization variables.
100 LC_COLLATE
102 Determine the locale for the behavior of ranges, equivalence
103 classes, and multi-character collating elements within regu‐
104 lar expressions.
105 LC_CTYPE Determine the locale for the interpretation of sequences of
107 bytes of text data as characters (for example, single-byte as
108 opposed to multi-byte characters in arguments).
109 LC_MESSAGES
111 Determine the locale that should be used to affect the format
112 and contents of diagnostic messages written to standard
113 error.
114 LC_NUMERIC
116 Determine the locale for selecting the radix character used
117 when writing floating-point formatted output.
118
120 Default.
121
123 If an operand presented to the qstat utility is a batch job_identifier
124 and the -f option is not specified, the qstat utility shall display the
125 following items on a single line, in the stated order, with white space
126 between each item, for each successfully processed operand:
127 * The batch job_identifier
129 * The batch job name
131 * The Job_Owner attribute
133 * The CPU time used by the batch job
135 * The batch job state
137 * The batch job location
139 If an operand presented to the qstat utility is a batch job_identifier
141 and the -f option is specified, the qstat utility shall display the
142 following items for each success fully processed operand:
143 * The batch job_identifier
145 * The batch job name
147 * The Job_Owner attribute
149 * The execution user ID
151 * The CPU time used by the batch job
153 * The batch job state
155 * The batch job location
157 * Additional implementation-defined information, if any, about the
159 batch job or batch queue
160 If an operand presented to the qstat utility is a destination, the -Q
162 option is specified, and the -f option is not specified, the qstat
163 utility shall display the following items on a single line, in the
164 stated order, with white space between each item, for each successfully
165 processed operand:
166 * The batch queue name
168 * The maximum number of batch jobs that shall be run in the batch
170 queue concurrently
171 * The total number of batch jobs in the batch queue
173 * The status of the batch queue
175 * For each state, the number of batch jobs in that state in the batch
177 queue and the name of the state
178 * The type of batch queue (execution or routing)
180 If the operands presented to the qstat utility are destinations, the -Q
182 option is specified, and the -f option is specified, the qstat utility
183 shall display the following items for each successfully processed oper‐
184 and:
185 * The batch queue name
187 * The maximum number of batch jobs that shall be run in the batch
189 queue concurrently
190 * The total number of batch jobs in the batch queue
192 * The status of the batch queue
194 * For each state, the number of batch jobs in that state in the batch
196 queue and the name of the state
197 * The type of batch queue (execution or routing)
199 * Additional implementation-defined information, if any, about the
201 batch queue
202 If the operands presented to the qstat utility are batch server names,
204 the -B option is specified, and the -f option is not specified, the
205 qstat utility shall display the following items on a single line, in
206 the stated order, with white space between each item, for each success‐
207 fully processed operand:
208 * The batch server name
210 * The maximum number of batch jobs that shall be run in the batch
212 queue concurrently
213 * The total number of batch jobs managed by the batch server
215 * The status of the batch server
217 * For each state, the number of batch jobs in that state and the name
219 of the state
220 If the operands presented to the qstat utility are server names, the -B
222 option is specified, and the -f option is specified, the qstat utility
223 shall display the following items for each successfully processed oper‐
224 and:
225 * The server name
227 * The maximum number of batch jobs that shall be run in the batch
229 queue concurrently
230 * The total number of batch jobs managed by the server
232 * The status of the server
234 * For each state, the number of batch jobs in that state and the name
236 of the state
237 * Additional implementation-defined information, if any, about the
239 server
240
242 The standard error shall be used only for diagnostic messages.
243
245 None.
246
248 None.
249
251 The following exit values shall be returned:
252 0 Successful completion.
254 >0 An error occurred.
256
258 In addition to the default behavior, the qstat utility shall not be
259 required to write a diagnostic message to standard error when the error
260 reply received from a batch server indicates that the batch job_identi‐
261 fier does not exist on the server. Whether or not the qstat utility
262 waits to output the diagnostic message while attempting to locate the
263 batch job on other servers is implementation-defined.
264 The following sections are informative.
266
268 None.
269
271 None.
272
274 The qstat utility allows users to display the status of jobs and list
275 the batch jobs in queues.
276 The operands of the qstat utility may be either job identifiers, queues
278 (specified as destination identifiers), or batch server names. The -Q
279 and -B options, or absence thereof, indicate the nature of the oper‐
280 ands.
281 The other options of the qstat utility allow the user to control the
283 amount of information displayed and the format in which it is dis‐
284 played. Should a user wish to display the status of a set of jobs that
285 match a selection criteria, the qselect utility may be used to acquire
286 such a list.
287 The -f option allows users to request a ``full'' display in an imple‐
289 mentation-defined format.
290 Historically, the qstat utility has been a part of the NQS and its de‐
292 rivatives, the existing practice on which it is based.
293
295 The qstat utility may be removed in a future version.
296
298 Chapter 3, Batch Environment Services, qselect
299 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
301 Variables, Section 12.2, Utility Syntax Guidelines
302
304 Portions of this text are reprinted and reproduced in electronic form
305 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
306 table Operating System Interface (POSIX), The Open Group Base Specifi‐
307 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
308 Electrical and Electronics Engineers, Inc and The Open Group. In the
309 event of any discrepancy between this version and the original IEEE and
310 The Open Group Standard, the original IEEE and The Open Group Standard
311 is the referee document. The original Standard can be obtained online
312 at http://www.opengroup.org/unix/online.html .
313 Any typographical or formatting errors that appear in this page are
315 most likely to have been introduced during the conversion of the source
316 files to man page format. To report such errors, see https://www.ker‐
317 nel.org/doc/man-pages/reporting_bugs.html .
318IEEE/The Open Group 2017 QSTAT(1P)