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|--xml] [-l] [-n [-1]] [-s] [-G|-M] [-R] [-u
13 user_list] [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 ex‐
45 ecutable 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, at‐
64 tributes are not folded to fit in a terminal window. This is
65 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 --xml 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 ap‐
115 pended 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 op‐
153 tion 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 be‐
180 ing 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 When any of the above options or the -R option is used to request an
191 alternative display format, a column with the requested memory for the
192 job is displayed. If more than one type of memory is requested for the
193 job, either through server or queue parameters or command line, only
194 one value can be displayed. The value displayed depends on the order
195 the memory types are evaluated with the last type evaluated being the
196 value displayed. The order of evaluation is dmem, mem, pmem, pvmem,
197 vmem.
198 - the job identifier assigned by PBS.
200 - the job owner.
202 - The queue in which the job currently resides.
204 - The job name given by the submitter.
206 - The session id (if the job is running).
208 - The number of nodes requested by the job.
210 - The number of cpus or tasks requested by the job.
212 - The amount of memory requested by the job.
214 - Either the cpu time, if specified, or wall time requested by
216 the job, (hh:mm).
217 - The job's current state.
219 - The amount of cpu time or wall time used by the job (hh:mm).
221 If the -R option is provided, the line contains:
222 - the job identifier assigned by PBS.
224 - the job owner.
226 - The queue in which the job currently resides.
228 - The number of nodes requested by the job.
230 - The number of cpus or tasks requested by the job.
232 - The amount of memory requested by the job.
234 - Either the cpu time or wall time requested by the job.
236 - The job's current state.
238 - The amount of cpu time or wall time used by the job.
240 - The amount of SRFS space requested on the big file system.
242 - The amount of SRFS space requested on the fast file system.
244 - The amount of space requested on the parallel I/O file sys‐
246 tem.
247 The last three fields may not contain useful information at all sites
248 or on all systems.
249 Note: Remaining walltime does not account for walltime multiplication
250 factors.
251 Displaying Queue Status
254 If queue status is being displayed and the -f option was not specified,
256 the following items are displayed on a single line, in the specified
257 order, separated by white space:
258 - the queue name
260 - the maximum number of jobs that may be run in the queue
262 concurrently
263 - the total number of jobs in the queue
265 - the enable or disabled status of the queue
267 - the started or stopped status of the queue
269 - for each job state, the name of the state and the number of
271 jobs in the queue in that state.
272 - the type of queue, execution or routing.
274 If queue status is being displayed and the -f option is specified, the
276 output will depend on whether qstat was compiled to use a Tcl inter‐
277 preter. See the configuration section for details. If Tcl is not be‐
278 ing used, the full display for each queue consists of the header line:
279 Queue: queue_name
280 Followed by one line per queue attribute of the form:
281 attribute_name = value
282 If the -q option is specified, queue information is displayed in the
284 alternative format: The following information is displayed on a single
285 line:
286 - the queue name
288 - the maximum amount of memory a job in the queue may request
290 - the maximum amount of cpu time a job in the queue may request
292 - the maximum amount of wall time a job in the queue may re‐
294 quest
295 - the maximum amount of nodes a job in the queue may request
297 - the number of jobs in the queue in the running state
299 - the number of jobs in the queue in the queued state
301 - the maximum number (limit) of jobs that may be run in the
303 queue concurrently
304 - the state of the queue given by a pair of letters:
306 - either the letter E if the queue is Enabled or D if Dis‐
307 abled, and
308 - either the letter R if the queue is Running (started) or S
309 if Stopped.
310 Displaying Server Status
313 If batch server status is being displayed and the -f option is not
315 specified, the following items are displayed on a single line, in the
316 specified order, separated by white space:
317 - the server name
319 - the maximum number of jobs that the server may run concur‐
321 rently
322 - the total number of jobs currently managed by the server
324 - the status of the server
326 - for each job state, the name of the state and the number of
328 jobs in the server in that state
329 If server status is being displayed and the -f option is specified, the
331 output will depend on whether qstat was compiled to use a Tcl inter‐
332 preter. See the configuration section for details. If Tcl is not be‐
333 ing used, the full display for the server consist of the header line:
334 Server: server name
335 Followed by one line per server attribute of the form:
336 attribute_name = value
337
339 The qstat command will write a diagnostic message to standard error for
340 each error occurrence.
341
343 If qstat is compiled with an option to include a Tcl interpreter, using
344 the -f flag to get a full display causes a check to be made for a
345 script file to use to output the requested information. The first lo‐
346 cation checked is $HOME/.qstatrc. If this does not exist, the next lo‐
347 cation checked is administrator configured. If one of these is found,
348 a Tcl interpreter is started and the script file is passed to it along
349 with three global variables. The command line arguments are split into
350 two variable named flags and operands . The status information is
351 passed in a variable named objects . All of these variables are Tcl
352 lists. The flags list contains the name of the command (usually "qs‐
353 tat") as its first element. Any other elements are command line option
354 flags with any options they use, presented in the order given on the
355 command line. They are broken up individually so that if two flags are
356 given together on the command line, they are separated in the list.
357 For example, if the user typed
358 qstat -QfWbigdisplay
360 the flags list would contain
362 qstat -Q -f -W bigdisplay
364 The operands list contains all other command line arguments following
366 the flags. There will always be at least one element in operands be‐
367 cause if no operands are typed by the user, the default destination or
368 server name is used. The objects list contains all the information re‐
369 trieved from the server(s) so the Tcl interpreter can run once to for‐
370 mat the entire output. This list has the same number of elements as
371 the operands list. Each element is another list with two elements.
372 The first element is a string giving the type of objects to be found in
373 the second. The string can take the values "server", "queue", "job" or
374 "error". The second element will be a list in which each element is a
375 single batch status object of the type given by the string discussed
376 above. In the case of "error", the list will be empty. Each object is
377 again a list. The first element is the name of the object. The second
378 is a list of attributes. The third element will be the object text.
379 All three of these object elements correspond with fields in the struc‐
380 ture batch_status which is described in detail for each type of object
381 by the man pages for pbs_statjob(3), pbs_statque(3), and pbs_stat‐
382 server(3). Each attribute in the second element list whose elements
383 correspond with the attrl structure. Each will be a list with two ele‐
384 ments. The first will be the attribute name and the second will be the
385 attribute value.
386
388 Upon successful processing of all the operands presented to the qstat
389 command, the exit status will be a value of zero.
390 If the qstat command fails to process any operand, the command exits
392 with a value greater than zero.
393
395 qalter(1B), qsub(1B), pbs_alterjob(3B), pbs_statjob(3B),
396 pbs_statque(3B), pbs_statserver(3B), pbs_submit(3B), pbs_job_at‐
397 tributes(7B), pbs_queue_attributes(7B), pbs_server_attributes(7B),
398 pbs_resources_*(7B) where * is system type, and the PBS ERS.
399Local qstat(1B)