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

NAME

12       qstat — show status of batch jobs
13

SYNOPSIS

15       qstat [-f] job_identifier...
16
17       qstat -Q [-f] destination...
18
19       qstat -B [-f] server_name...
20

DESCRIPTION

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
28       For each successfully processed batch job_identifier, the qstat utility
29       shall display information about the corresponding batch job.
30
31       For  each  successfully  processed destination, the qstat utility shall
32       display information about the corresponding batch queue.
33
34       For each successfully processed server name, the  qstat  utility  shall
35       display information about the corresponding server.
36
37       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

OPTIONS

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

OPERANDS

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
72       If the -B option is presented to the qstat utility, the  utility  shall
73       accept one or more server_name operands.
74
75       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

STDIN

81       Not used.
82

INPUT FILES

84       None.
85

ENVIRONMENT VARIABLES

87       The following environment  variables  shall  affect  the  execution  of
88       qstat:
89
90       HOME      Determine the pathname of the user's home directory.
91
92       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
98       LC_ALL    If  set  to  a non-empty string value, override the values of
99                 all the other internationalization variables.
100
101       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
106       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
110       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
115       LC_NUMERIC
116                 Determine the locale for selecting the radix  character  used
117                 when writing floating-point formatted output.
118

ASYNCHRONOUS EVENTS

120       Default.
121

STDOUT

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
128        *  The batch job_identifier
129
130        *  The batch job name
131
132        *  The Job_Owner attribute
133
134        *  The CPU time used by the batch job
135
136        *  The batch job state
137
138        *  The batch job location
139
140       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
144        *  The batch job_identifier
145
146        *  The batch job name
147
148        *  The Job_Owner attribute
149
150        *  The execution user ID
151
152        *  The CPU time used by the batch job
153
154        *  The batch job state
155
156        *  The batch job location
157
158        *  Additional implementation-defined information, if  any,  about  the
159           batch job or batch queue
160
161       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
167        *  The batch queue name
168
169        *  The  maximum  number  of  batch jobs that shall be run in the batch
170           queue concurrently
171
172        *  The total number of batch jobs in the batch queue
173
174        *  The status of the batch queue
175
176        *  For each state, the number of batch jobs in that state in the batch
177           queue and the name of the state
178
179        *  The type of batch queue (execution or routing)
180
181       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
186        *  The batch queue name
187
188        *  The maximum number of batch jobs that shall be  run  in  the  batch
189           queue concurrently
190
191        *  The total number of batch jobs in the batch queue
192
193        *  The status of the batch queue
194
195        *  For each state, the number of batch jobs in that state in the batch
196           queue and the name of the state
197
198        *  The type of batch queue (execution or routing)
199
200        *  Additional implementation-defined information, if  any,  about  the
201           batch queue
202
203       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
209        *  The batch server name
210
211        *  The  maximum  number  of  batch jobs that shall be run in the batch
212           queue concurrently
213
214        *  The total number of batch jobs managed by the batch server
215
216        *  The status of the batch server
217
218        *  For each state, the number of batch jobs in that state and the name
219           of the state
220
221       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
226        *  The server name
227
228        *  The maximum number of batch jobs that shall be  run  in  the  batch
229           queue concurrently
230
231        *  The total number of batch jobs managed by the server
232
233        *  The status of the server
234
235        *  For each state, the number of batch jobs in that state and the name
236           of the state
237
238        *  Additional implementation-defined information, if  any,  about  the
239           server
240

STDERR

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

OUTPUT FILES

245       None.
246

EXTENDED DESCRIPTION

248       None.
249

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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
265       The following sections are informative.
266

APPLICATION USAGE

268       None.
269

EXAMPLES

271       None.
272

RATIONALE

274       The qstat utility allows users to display the status of jobs  and  list
275       the batch jobs in queues.
276
277       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
282       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
288       The -f option allows users to request a ``full'' display in  an  imple‐
289       mentation-defined format.
290
291       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

FUTURE DIRECTIONS

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

SEE ALSO

298       Chapter 3, Batch Environment Services, qselect
299
300       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
314       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 .
318
319
320
321IEEE/The Open Group                  2017                            QSTAT(1P)
Impressum