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
22 The qstat command is used to request the status of jobs, queues, or a
23 batch server. The requested status is written to standard out.
24 When requesting job status, synopsis format 1 or 2, qstat will output
26 information about each job_identifier or all jobs at each destination.
27 Jobs for which the user does not have status privilege are not dis‐
28 played.
29 When requesting queue or server status, synopsis format 3 through 5,
31 qstat will output information about each destination.
32
34 -f Specifies that a full status display be written to standard
35 out.
36 -a "All" jobs are displayed in the alternative format, see the
38 Standard Output section. If the operand is a destination id,
39 all jobs at that destination are displayed. If the operand
40 is a job id, information about that job is displayed.
41 -e If the operand is a job id or not specified, only jobs in
43 executable queues are displayed. Setting the PBS_QSTAT_EXE‐
44 CONLY environment variable will also enable this option.
45 -i Job status is displayed in the alternative format. For a
47 destination id operand, status for jobs at that destination
48 which are not running are displayed. This includes jobs
49 which are queued, held or waiting. If an operand is a job
50 id, status for that job is displayed regardless of its state.
51 -r If an operand is a job id, status for that job is displayed.
53 For a destination id operand, status for jobs at that desti‐
54 nation which are running are displayed, this includes jobs
55 which are suspended.
56 -n In addition to the basic information, nodes allocated to a
58 job are listed.
59 -1 In combination with -n, the -1 option puts all of the nodes
61 on the same line as the job ID. In combination with -f,
62 attributes are not folded to fit in a terminal window. This
63 is intended to ease the parsing of the qstat output.
64 -s In addition to the basic information, any comment provided by
66 the batch administrator or scheduler is shown.
67 -G Show size information in giga-bytes.
69 -M Show size information, disk or memory in mega-words. A word
71 is considered to be 8 bytes.
72 -R In addition to other information, disk reservation informa‐
74 tion is shown. Not applicable to all systems.
75 -u Job status is displayed in the alternative format. If an op‐
77 erand is a job id, status for that job is displayed. For a
78 destination id operand, status for jobs at that destination
79 which are owned by the user(s) listed in user_list are dis‐
80 played. The syntax of the user_list is:
81 user_name[@host][,user_name[@host],...]
82 Host names may be wild carded on the left end, e.g.
83 "*.nasa.gov". User_name without a "@host" is equivalent to
84 "user_name@*", that is at any host.
85 -Q Specifies that the request is for queue status and that the
87 operands are destination identifiers.
88 -q Specifies that the request is for queue status which should
90 be shown in the alternative format.
91 -B Specifies that the request is for batch server status and
93 that the operands are the names of servers.
94 -x Specifies that the output is to be displayed in XML form.
96 This option is only valid with the -f option or by itself,
97 which will also specify the -f full status display.
98 -l Specifies that the long name of the job (or the job name
100 appended with the suffix alias) should be displayed.
101
103 If neither the -Q nor the -B option is given, the operands on the qstat
104 command must be either job identifiers or destinations identifiers.
105 If the operand is a job identifier, it must be in the following form:
107 sequence_number[.server_name][@server]
108 where sequence_number.server_name is the job identifier assigned at
109 submittal time, see qsub. If the .server_name is omitted, the name of
110 the default server will be used. If @server is supplied, the request
111 will be for the job identifier currently at that Server.
112 If the operand is a destination identifier, it is one of the following
114 three forms:
115 queue
116 @server
117 queue@server
118 If queue is specified, the request is for status of all jobs in that
119 queue at the default server. If the @server form is given, the request
120 is for status of all jobs at that server. If a full destination iden‐
121 tifier, queue@server, is given, the request is for status of all jobs
122 in the named queue at the named server.
123 If the -Q option is given, the operands are destination identifiers as
125 specified above. If queue is specified, the status of that queue at
126 the default server will be given. If queue@server is specified, the
127 status of the named queue at the named server will be given. If
128 @server is specified, the status of all queues at the named server will
129 be given. If no destination is specified, the status of all queues at
130 the default server will be given.
131 If the -B option is given, the operand is the name of a server.
133
135 Displaying Job Status
136 If job status is being displayed in the default format and the -f
138 option is not specified, the following items are displayed on a single
139 line, in the specified order, separated by white space:
140 - the job identifier assigned by PBS.
142 - the job name given by the submitter.
144 - the job owner
146 - the CPU time used
148 - the job state:
150 C - Job is completed after having run/
151 E - Job is exiting after having run.
152 H - Job is held.
153 Q - job is queued, eligible to run or routed.
154 R - job is running.
155 T - job is being moved to new location.
156 W - job is waiting for its execution time
157 (-a option) to be reached.
158 S - (Unicos only) job is suspend.
159 - the queue in which the job resides
161 If job status is being displayed and the -f option is specified, the
163 output will depend on whether qstat was compiled to use a Tcl inter‐
164 preter. See the configuration section for details. If Tcl is not
165 being used, full display for each job consists of the header line:
166 Job Id: job identifier
167 Followed by one line per job attribute of the form:
168 attribute_name = value
169 If any of the options -a, -i, -r, -u, -n, -s, -G or -M are provided,
171 the alternative display format for jobs is used. The following items
172 are displayed on a single line, in the specified order, separated by
173 white space:
174 - the job identifier assigned by PBS.
176 - the job owner.
178 - The queue in which the job currently resides.
180 - The job name given by the submitter.
182 - The session id (if the job is running).
184 - The number of nodes requested by the job.
186 - The number of cpus or tasks requested by the job.
188 - The amount of memory requested by the job.
190 - Either the cpu time, if specified, or wall time requested by
192 the job, (hh:mm).
193 - The job's current state.
195 - The amount of cpu time or wall time used by the job (hh:mm).
197 If the -R option is provided, the line contains:
198 - the job identifier assigned by PBS.
200 - the job owner.
202 - The queue in which the job currently resides.
204 - The number of nodes requested by the job.
206 - The number of cpus or tasks requested by the job.
208 - The amount of memory requested by the job.
210 - Either the cpu time or wall time requested by the job.
212 - The job's current state.
214 - The amount of cpu time or wall time used by the job.
216 - The amount of SRFS space requested on the big file system.
218 - The amount of SRFS space requested on the fast file system.
220 - The amount of space requested on the parallel I/O file sys‐
222 tem.
223 The last three fields may not contain useful information at all sites
224 or on all systems.
225 Note: Remaining walltime does not account for walltime multiplication
226 factors.
227 Displaying Queue Status
230 If queue status is being displayed and the -f option was not specified,
232 the following items are displayed on a single line, in the specified
233 order, separated by white space:
234 - the queue name
236 - the maximum number of jobs that may be run in the queue
238 concurrently
239 - the total number of jobs in the queue
241 - the enable or disabled status of the queue
243 - the started or stopped status of the queue
245 - for each job state, the name of the state and the number of
247 jobs in the queue in that state.
248 - the type of queue, execution or routing.
250 If queue status is being displayed and the -f option is specified, the
252 output will depend on whether qstat was compiled to use a Tcl inter‐
253 preter. See the configuration section for details. If Tcl is not
254 being used, the full display for each queue consists of the header
255 line:
256 Queue: queue_name
257 Followed by one line per queue attribute of the form:
258 attribute_name = value
259 If the -q option is specified, queue information is displayed in the
261 alternative format: The following information is displayed on a single
262 line:
263 - the queue name
265 - the maximum amount of memory a job in the queue may request
267 - the maximum amount of cpu time a job in the queue may request
269 - the maximum amount of wall time a job in the queue may
271 request
272 - the maximum amount of nodes a job in the queue may request
274 - the number of jobs in the queue in the running state
276 - the number of jobs in the queue in the queued state
278 - the maximum number (limit) of jobs that may be run in the
280 queue concurrently
281 - the state of the queue given by a pair of letters:
283 - either the letter E if the queue is Enabled or D if Dis‐
284 abled, and
285 - either the letter R if the queue is Running (started) or S
286 if Stopped.
287 Displaying Server Status
290 If batch server status is being displayed and the -f option is not
292 specified, the following items are displayed on a single line, in the
293 specified order, separated by white space:
294 - the server name
296 - the maximum number of jobs that the server may run concur‐
298 rently
299 - the total number of jobs currently managed by the server
301 - the status of the server
303 - for each job state, the name of the state and the number of
305 jobs in the server in that state
306 If server status is being displayed and the -f option is specified, the
308 output will depend on whether qstat was compiled to use a Tcl inter‐
309 preter. See the configuration section for details. If Tcl is not
310 being used, the full display for the server consist of the header line:
311 Server: server name
312 Followed by one line per server attribute of the form:
313 attribute_name = value
314
316 The qstat command will write a diagnostic message to standard error for
317 each error occurrence.
318
320 If qstat is compiled with an option to include a Tcl interpreter, using
321 the -f flag to get a full display causes a check to be made for a
322 script file to use to output the requested information. The first
323 location checked is $HOME/.qstatrc. If this does not exist, the next
324 location checked is administrator configured. If one of these is
325 found, a Tcl interpreter is started and the script file is passed to it
326 along with three global variables. The command line arguments are
327 split into two variable named flags and operands . The status informa‐
328 tion is passed in a variable named objects . All of these variables
329 are Tcl lists. The flags list contains the name of the command (usu‐
330 ally "qstat") as its first element. Any other elements are command
331 line option flags with any options they use, presented in the order
332 given on the command line. They are broken up individually so that if
333 two flags are given together on the command line, they are separated in
334 the list. For example, if the user typed
335 qstat -QfWbigdisplay
337 the flags list would contain
339 qstat -Q -f -W bigdisplay
341 The operands list contains all other command line arguments following
343 the flags. There will always be at least one element in operands
344 because if no operands are typed by the user, the default destination
345 or server name is used. The objects list contains all the information
346 retrieved from the server(s) so the Tcl interpreter can run once to
347 format the entire output. This list has the same number of elements as
348 the operands list. Each element is another list with two elements.
349 The first element is a string giving the type of objects to be found in
350 the second. The string can take the values "server", "queue", "job" or
351 "error". The second element will be a list in which each element is a
352 single batch status object of the type given by the string discussed
353 above. In the case of "error", the list will be empty. Each object is
354 again a list. The first element is the name of the object. The second
355 is a list of attributes. The third element will be the object text.
356 All three of these object elements correspond with fields in the struc‐
357 ture batch_status which is described in detail for each type of object
358 by the man pages for pbs_statjob(3), pbs_statque(3), and pbs_stat‐
359 server(3). Each attribute in the second element list whose elements
360 correspond with the attrl structure. Each will be a list with two ele‐
361 ments. The first will be the attribute name and the second will be the
362 attribute value.
363
365 Upon successful processing of all the operands presented to the qstat
366 command, the exit status will be a value of zero.
367 If the qstat command fails to process any operand, the command exits
369 with a value greater than zero.
370
372 qalter(1B), qsub(1B), pbs_alterjob(3B), pbs_statjob(3B),
373 pbs_statque(3B), pbs_statserver(3B), pbs_submit(3B),
374 pbs_job_attributes(7B), pbs_queue_attributes(7B),
375 pbs_server_attributes(7B), pbs_resources_*(7B) where * is system type,
376 and the PBS ERS.
377Local qstat(1B)