1qstat(1B) PBS qstat(1B)
2
6 qstat - show status of pbs batch jobs
7
9 qstat [-f [-1]] [-l] [-W site_specific] [-x] [job_identifier... | des‐
10 tination...]
11 qstat [-a|-i|-r|-e] [-l] [-n [-1]] [-s] [-G|-M] [-R] [-u user_list]
13 [job_identifier... | destination...]
14 qstat -Q [-f [-1]][-W site_specific] [-l] [destination...]
16 qstat -q [-G|-M] [-l] [destination...]
18 qstat -B [-f [-1]][-W site_specific] [-l] [server_name...]
20 qstat -t
22
24 The qstat command is used to request the status of jobs, queues, or a
25 batch server. The requested status is written to standard out.
26 When requesting job status, synopsis format 1 or 2, qstat will output
28 information about each job_identifier or all jobs at each destination.
29 Jobs for which the user does not have status privilege are not dis‐
30 played.
31 When requesting queue or server status, synopsis format 3 through 5,
33 qstat will output information about each destination.
34
36 -f Specifies that a full status display be written to standard
37 out.
38 -a "All" jobs are displayed in the alternative format, see the
40 Standard Output section. If the operand is a destination id,
41 all jobs at that destination are displayed. If the operand
42 is a job id, information about that job is displayed.
43 -e If the operand is a job id or not specified, only jobs in
45 executable queues are displayed. Setting the PBS_QSTAT_EXE‐
46 CONLY environment variable will also enable this option.
47 -i Job status is displayed in the alternative format. For a
49 destination id operand, status for jobs at that destination
50 which are not running are displayed. This includes jobs
51 which are queued, held or waiting. If an operand is a job
52 id, status for that job is displayed regardless of its state.
53 -r If an operand is a job id, status for that job is displayed.
55 For a destination id operand, status for jobs at that desti‐
56 nation which are running are displayed, this includes jobs
57 which are suspended.
58 -n In addition to the basic information, nodes allocated to a
60 job are listed.
61 -1 In combination with -n, the -1 option puts all of the nodes
63 on the same line as the job ID. In combination with -f,
64 attributes are not folded to fit in a terminal window. This
65 is intended to ease the parsing of the qstat output.
66 -s In addition to the basic information, any comment provided by
68 the batch administrator or scheduler is shown.
69 -G Show size information in giga-bytes.
71 -M Show size information, disk or memory in mega-words. A word
73 is considered to be 8 bytes.
74 -R In addition to other information, disk reservation informa‐
76 tion is shown. Not applicable to all systems.
77 -t Normal qstat output displays a summary of the array instead
79 of the entire array, job for job. qstat -t expands the output
80 to display the entire array. Note that arrays are now named
81 with brackets following the array name; for example:
82 echo sleep 20 | qsub -t 0-299 189[].pali
84 Individual jobs in the array are now also noted using square
86 brackets instead of dashes; for example, here is part of the
87 output of qstat -t for the preceding array:
88 189[299].napali STDIN[299] dbeer 0 Q batch
90 -u Job status is displayed in the alternative format. If an op‐
92 erand is a job id, status for that job is displayed. For a
93 destination id operand, status for jobs at that destination
94 which are owned by the user(s) listed in user_list are dis‐
95 played. The syntax of the user_list is:
96 user_name[@host][,user_name[@host],...]
97 Host names may be wild carded on the left end, e.g.
98 "*.nasa.gov". User_name without a "@host" is equivalent to
99 "user_name@*", that is at any host.
100 -Q Specifies that the request is for queue status and that the
102 operands are destination identifiers.
103 -q Specifies that the request is for queue status which should
105 be shown in the alternative format.
106 -B Specifies that the request is for batch server status and
108 that the operands are the names of servers.
109 -x Specifies that the output is to be displayed in XML form.
111 This option is only valid with the -f option or by itself,
112 which will also specify the -f full status display.
113 -l Specifies that the long name of the job (or the job name
115 appended with the suffix alias) should be displayed.
116
118 If neither the -Q nor the -B option is given, the operands on the qstat
119 command must be either job identifiers or destinations identifiers.
120 If the operand is a job identifier, it must be in the following form:
122 sequence_number[.server_name][@server]
123 where sequence_number.server_name is the job identifier assigned at
124 submittal time, see qsub. If the .server_name is omitted, the name of
125 the default server will be used. If @server is supplied, the request
126 will be for the job identifier currently at that Server.
127 If the operand is a destination identifier, it is one of the following
129 three forms:
130 queue
131 @server
132 queue@server
133 If queue is specified, the request is for status of all jobs in that
134 queue at the default server. If the @server form is given, the request
135 is for status of all jobs at that server. If a full destination iden‐
136 tifier, queue@server, is given, the request is for status of all jobs
137 in the named queue at the named server.
138 If the -Q option is given, the operands are destination identifiers as
140 specified above. If queue is specified, the status of that queue at
141 the default server will be given. If queue@server is specified, the
142 status of the named queue at the named server will be given. If
143 @server is specified, the status of all queues at the named server will
144 be given. If no destination is specified, the status of all queues at
145 the default server will be given.
146 If the -B option is given, the operand is the name of a server.
148
150 Displaying Job Status
151 If job status is being displayed in the default format and the -f
153 option is not specified, the following items are displayed on a single
154 line, in the specified order, separated by white space:
155 - the job identifier assigned by PBS.
157 - the job name given by the submitter.
159 - the job owner
161 - the CPU time used
163 - the job state:
165 C - Job is completed after having run/
166 E - Job is exiting after having run.
167 H - Job is held.
168 Q - job is queued, eligible to run or routed.
169 R - job is running.
170 T - job is being moved to new location.
171 W - job is waiting for its execution time
172 (-a option) to be reached.
173 S - (Unicos only) job is suspend.
174 - the queue in which the job resides
176 If job status is being displayed and the -f option is specified, the
178 output will depend on whether qstat was compiled to use a Tcl inter‐
179 preter. See the configuration section for details. If Tcl is not
180 being used, full display for each job consists of the header line:
181 Job Id: job identifier
182 Followed by one line per job attribute of the form:
183 attribute_name = value
184 If any of the options -a, -i, -r, -u, -n, -s, -G or -M are provided,
186 the alternative display format for jobs is used. The following items
187 are displayed on a single line, in the specified order, separated by
188 white space:
189 - the job identifier assigned by PBS.
191 - the job owner.
193 - The queue in which the job currently resides.
195 - The job name given by the submitter.
197 - The session id (if the job is running).
199 - The number of nodes requested by the job.
201 - The number of cpus or tasks requested by the job.
203 - The amount of memory requested by the job.
205 - Either the cpu time, if specified, or wall time requested by
207 the job, (hh:mm).
208 - The job's current state.
210 - The amount of cpu time or wall time used by the job (hh:mm).
212 If the -R option is provided, the line contains:
213 - the job identifier assigned by PBS.
215 - the job owner.
217 - The queue in which the job currently resides.
219 - The number of nodes requested by the job.
221 - The number of cpus or tasks requested by the job.
223 - The amount of memory requested by the job.
225 - Either the cpu time or wall time requested by the job.
227 - The job's current state.
229 - The amount of cpu time or wall time used by the job.
231 - The amount of SRFS space requested on the big file system.
233 - The amount of SRFS space requested on the fast file system.
235 - The amount of space requested on the parallel I/O file sys‐
237 tem.
238 The last three fields may not contain useful information at all sites
239 or on all systems.
240 Note: Remaining walltime does not account for walltime multiplication
241 factors.
242 Displaying Queue Status
245 If queue status is being displayed and the -f option was not specified,
247 the following items are displayed on a single line, in the specified
248 order, separated by white space:
249 - the queue name
251 - the maximum number of jobs that may be run in the queue
253 concurrently
254 - the total number of jobs in the queue
256 - the enable or disabled status of the queue
258 - the started or stopped status of the queue
260 - for each job state, the name of the state and the number of
262 jobs in the queue in that state.
263 - the type of queue, execution or routing.
265 If queue status is being displayed and the -f option is specified, the
267 output will depend on whether qstat was compiled to use a Tcl inter‐
268 preter. See the configuration section for details. If Tcl is not
269 being used, the full display for each queue consists of the header
270 line:
271 Queue: queue_name
272 Followed by one line per queue attribute of the form:
273 attribute_name = value
274 If the -q option is specified, queue information is displayed in the
276 alternative format: The following information is displayed on a single
277 line:
278 - the queue name
280 - the maximum amount of memory a job in the queue may request
282 - the maximum amount of cpu time a job in the queue may request
284 - the maximum amount of wall time a job in the queue may
286 request
287 - the maximum amount of nodes a job in the queue may request
289 - the number of jobs in the queue in the running state
291 - the number of jobs in the queue in the queued state
293 - the maximum number (limit) of jobs that may be run in the
295 queue concurrently
296 - the state of the queue given by a pair of letters:
298 - either the letter E if the queue is Enabled or D if Dis‐
299 abled, and
300 - either the letter R if the queue is Running (started) or S
301 if Stopped.
302 Displaying Server Status
305 If batch server status is being displayed and the -f option is not
307 specified, the following items are displayed on a single line, in the
308 specified order, separated by white space:
309 - the server name
311 - the maximum number of jobs that the server may run concur‐
313 rently
314 - the total number of jobs currently managed by the server
316 - the status of the server
318 - for each job state, the name of the state and the number of
320 jobs in the server in that state
321 If server status is being displayed and the -f option is specified, the
323 output will depend on whether qstat was compiled to use a Tcl inter‐
324 preter. See the configuration section for details. If Tcl is not
325 being used, the full display for the server consist of the header line:
326 Server: server name
327 Followed by one line per server attribute of the form:
328 attribute_name = value
329
331 The qstat command will write a diagnostic message to standard error for
332 each error occurrence.
333
335 If qstat is compiled with an option to include a Tcl interpreter, using
336 the -f flag to get a full display causes a check to be made for a
337 script file to use to output the requested information. The first
338 location checked is $HOME/.qstatrc. If this does not exist, the next
339 location checked is administrator configured. If one of these is
340 found, a Tcl interpreter is started and the script file is passed to it
341 along with three global variables. The command line arguments are
342 split into two variable named flags and operands . The status informa‐
343 tion is passed in a variable named objects . All of these variables
344 are Tcl lists. The flags list contains the name of the command (usu‐
345 ally "qstat") as its first element. Any other elements are command
346 line option flags with any options they use, presented in the order
347 given on the command line. They are broken up individually so that if
348 two flags are given together on the command line, they are separated in
349 the list. For example, if the user typed
350 qstat -QfWbigdisplay
352 the flags list would contain
354 qstat -Q -f -W bigdisplay
356 The operands list contains all other command line arguments following
358 the flags. There will always be at least one element in operands
359 because if no operands are typed by the user, the default destination
360 or server name is used. The objects list contains all the information
361 retrieved from the server(s) so the Tcl interpreter can run once to
362 format the entire output. This list has the same number of elements as
363 the operands list. Each element is another list with two elements.
364 The first element is a string giving the type of objects to be found in
365 the second. The string can take the values "server", "queue", "job" or
366 "error". The second element will be a list in which each element is a
367 single batch status object of the type given by the string discussed
368 above. In the case of "error", the list will be empty. Each object is
369 again a list. The first element is the name of the object. The second
370 is a list of attributes. The third element will be the object text.
371 All three of these object elements correspond with fields in the struc‐
372 ture batch_status which is described in detail for each type of object
373 by the man pages for pbs_statjob(3), pbs_statque(3), and pbs_stat‐
374 server(3). Each attribute in the second element list whose elements
375 correspond with the attrl structure. Each will be a list with two ele‐
376 ments. The first will be the attribute name and the second will be the
377 attribute value.
378
380 Upon successful processing of all the operands presented to the qstat
381 command, the exit status will be a value of zero.
382 If the qstat command fails to process any operand, the command exits
384 with a value greater than zero.
385
387 qalter(1B), qsub(1B), pbs_alterjob(3B), pbs_statjob(3B),
388 pbs_statque(3B), pbs_statserver(3B), pbs_submit(3B),
389 pbs_job_attributes(7B), pbs_queue_attributes(7B),
390 pbs_server_attributes(7B), pbs_resources_*(7B) where * is system type,
391 and the PBS ERS.
392Local qstat(1B)