1QSTAT(1P)                  POSIX Programmer's Manual                 QSTAT(1P)
2
3
4

PROLOG

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
11

NAME

13       qstat — show status of batch jobs
14

SYNOPSIS

16       qstat [−f] job_identifier...
17
18       qstat −Q [−f] destination...
19
20       qstat −B [−f] server_name...
21

DESCRIPTION

23       The status of a batch job, batch queue, or batch server is obtained  by
24       a  request  to the server. The qstat utility is a user-accessible batch
25       client that requests the status  of  one  or  more  batch  jobs,  batch
26       queues,  or servers, and writes the status information to standard out‐
27       put.
28
29       For each successfully processed batch job_identifier, the qstat utility
30       shall display information about the corresponding batch job.
31
32       For  each  successfully  processed destination, the qstat utility shall
33       display information about the corresponding batch queue.
34
35       For each successfully processed server name, the  qstat  utility  shall
36       display information about the corresponding server.
37
38       The qstat utility shall acquire batch job status information by sending
39       a Job Status Request to a batch server. The qstat utility shall acquire
40       batch  queue  status information by sending a Queue Status Request to a
41       batch server. The qstat utility shall acquire server status information
42       by sending a Server Status Request to a batch server.
43

OPTIONS

45       The  qstat  utility  shall  conform  to  the Base Definitions volume of
46       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
47
48       The following options shall be supported by the implementation:
49
50       −f        Specify that a full display is produced.
51
52                 The minimum contents of a full display are specified  in  the
53                 STDOUT section.
54
55                 Additional  contents  and format of a full display are imple‐
56                 mentation-defined.
57
58       −Q        Specify that the operand is a destination.
59
60                 The qstat utility shall display information about each  batch
61                 queue at each destination identified as an operand.
62
63       −B        Specify that the operand is a server name.
64
65                 The qstat utility shall display information about each server
66                 identified as an operand.
67

OPERANDS

69       If the −Q option is presented to the qstat utility, the  utility  shall
70       accept  one  or more operands that conform to the syntax for a destina‐
71       tion (see Section 3.3.2, Destination).
72
73       If the −B option is presented to the qstat utility, the  utility  shall
74       accept one or more server_name operands.
75
76       If  neither the −B nor the −Q option is presented to the qstat utility,
77       the utility shall accept one or more operands that conform to the  syn‐
78       tax  for  a  batch job_identifier (see Section 3.3.1, Batch Job Identi‐
79       fier).
80

STDIN

82       Not used.
83

INPUT FILES

85       None.
86

ENVIRONMENT VARIABLES

88       The following environment  variables  shall  affect  the  execution  of
89       qstat:
90
91       HOME      Determine the pathname of the user's home directory.
92
93       LANG      Provide  a  default  value for the internationalization vari‐
94                 ables that are unset or null. (See the Base Definitions  vol‐
95                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
96                 ables the precedence of internationalization  variables  used
97                 to determine the values of locale categories.)
98
99       LC_ALL    If  set  to  a non-empty string value, override the values of
100                 all the other internationalization variables.
101
102       LC_COLLATE
103                 Determine the locale for the behavior of ranges,  equivalence
104                 classes,  and multi-character collating elements within regu‐
105                 lar expressions.
106
107       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
108                 bytes of text data as characters (for example, single-byte as
109                 opposed to multi-byte characters in arguments).
110
111       LC_MESSAGES
112                 Determine the locale that should be used to affect the format
113                 and  contents  of  diagnostic  messages  written  to standard
114                 error.
115
116       LC_NUMERIC
117                 Determine the locale for selecting the radix  character  used
118                 when writing floating-point formatted output.
119

ASYNCHRONOUS EVENTS

121       Default.
122

STDOUT

124       If  an operand presented to the qstat utility is a batch job_identifier
125       and the −f option is not specified, the qstat utility shall display the
126       following items on a single line, in the stated order, with white space
127       between each item, for each successfully processed operand:
128
129        *  The batch job_identifier
130
131        *  The batch job name
132
133        *  The Job_Owner attribute
134
135        *  The CPU time used by the batch job
136
137        *  The batch job state
138
139        *  The batch job location
140
141       If an operand presented to the qstat utility is a batch  job_identifier
142       and  the  −f  option  is specified, the qstat utility shall display the
143       following items for each success fully processed operand:
144
145        *  The batch job_identifier
146
147        *  The batch job name
148
149        *  The Job_Owner attribute
150
151        *  The execution user ID
152
153        *  The CPU time used by the batch job
154
155        *  The batch job state
156
157        *  The batch job location
158
159        *  Additional implementation-defined information, if  any,  about  the
160           batch job or batch queue
161
162       If  an  operand presented to the qstat utility is a destination, the −Q
163       option is specified, and the −f option  is  not  specified,  the  qstat
164       utility  shall  display  the  following  items on a single line, in the
165       stated order, with white space between each item, for each successfully
166       processed operand:
167
168        *  The batch queue name
169
170        *  The  maximum  number  of  batch jobs that shall be run in the batch
171           queue concurrently
172
173        *  The total number of batch jobs in the batch queue
174
175        *  The status of the batch queue
176
177        *  For each state, the number of batch jobs in that state in the batch
178           queue and the name of the state
179
180        *  The type of batch queue (execution or routing)
181
182       If the operands presented to the qstat utility are destinations, the −Q
183       option is specified, and the −f option is specified, the qstat  utility
184       shall display the following items for each successfully processed oper‐
185       and:
186
187        *  The batch queue name
188
189        *  The maximum number of batch jobs that shall be  run  in  the  batch
190           queue concurrently
191
192        *  The total number of batch jobs in the batch queue
193
194        *  The status of the batch queue
195
196        *  For each state, the number of batch jobs in that state in the batch
197           queue and the name of the state
198
199        *  The type of batch queue (execution or routing)
200
201        *  Additional implementation-defined information, if  any,  about  the
202           batch queue
203
204       If  the operands presented to the qstat utility are batch server names,
205       the −B option is specified, and the −f option  is  not  specified,  the
206       qstat  utility  shall  display the following items on a single line, in
207       the stated order, with white space between each item, for each success‐
208       fully processed operand:
209
210        *  The batch server name
211
212        *  The  maximum  number  of  batch jobs that shall be run in the batch
213           queue concurrently
214
215        *  The total number of batch jobs managed by the batch server
216
217        *  The status of the batch server
218
219        *  For each state, the number of batch jobs in that state and the name
220           of the state
221
222       If the operands presented to the qstat utility are server names, the −B
223       option is specified, and the −f option is specified, the qstat  utility
224       shall display the following items for each successfully processed oper‐
225       and:
226
227        *  The server name
228
229        *  The maximum number of batch jobs that shall be  run  in  the  batch
230           queue concurrently
231
232        *  The total number of batch jobs managed by the server
233
234        *  The status of the server
235
236        *  For each state, the number of batch jobs in that state and the name
237           of the state
238
239        *  Additional implementation-defined information, if  any,  about  the
240           server
241

STDERR

243       The standard error shall be used only for diagnostic messages.
244

OUTPUT FILES

246       None.
247

EXTENDED DESCRIPTION

249       None.
250

EXIT STATUS

252       The following exit values shall be returned:
253
254        0    Successful completion.
255
256       >0    An error occurred.
257

CONSEQUENCES OF ERRORS

259       In  addition  to  the  default behavior, the qstat utility shall not be
260       required to write a diagnostic message to standard error when the error
261       reply received from a batch server indicates that the batch job_identi‐
262       fier does not exist on the server. Whether or  not  the  qstat  utility
263       waits  to  output the diagnostic message while attempting to locate the
264       batch job on other servers is implementation-defined.
265
266       The following sections are informative.
267

APPLICATION USAGE

269       None.
270

EXAMPLES

272       None.
273

RATIONALE

275       The qstat utility allows users to display the status of jobs  and  list
276       the batch jobs in queues.
277
278       The operands of the qstat utility may be either job identifiers, queues
279       (specified as destination identifiers), or batch server names.  The  −Q
280       and  −B  options,  or absence thereof, indicate the nature of the oper‐
281       ands.
282
283       The other options of the qstat utility allow the user  to  control  the
284       amount  of  information  displayed  and  the format in which it is dis‐
285       played. Should a user wish to display the status of a set of jobs  that
286       match  a selection criteria, the qselect utility may be used to acquire
287       such a list.
288
289       The −f option allows users to request a ``full'' display in  an  imple‐
290       mentation-defined format.
291
292       Historically,  the qstat utility has been a part of the NQS and its de‐
293       rivatives, the existing practice on which it is based.
294

FUTURE DIRECTIONS

296       The qstat utility may be removed in a future version.
297

SEE ALSO

299       Chapter 3, Batch Environment Services, qselect
300
301       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
302       Variables, Section 12.2, Utility Syntax Guidelines
303
305       Portions  of  this text are reprinted and reproduced in electronic form
306       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
307       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
308       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
309       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
310       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
311       event of any discrepancy between this version and the original IEEE and
312       The Open Group Standard, the original IEEE and The Open Group  Standard
313       is  the  referee document. The original Standard can be obtained online
314       at http://www.unix.org/online.html .
315
316       Any typographical or formatting errors that appear  in  this  page  are
317       most likely to have been introduced during the conversion of the source
318       files to man page format. To report such errors,  see  https://www.ker
319       nel.org/doc/man-pages/reporting_bugs.html .
320
321
322
323IEEE/The Open Group                  2013                            QSTAT(1P)
Impressum