Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
qstat(1B)			      PBS			     qstat(1B)

NAME
       qstat - show status of pbs batch	jobs

SYNOPSIS
       qstat  [-f [-1]]	[-l] [-W site_specific]	[-x] [job_identifier...	| des-
       tination...]

       qstat [-a|-i|-r|-e] [-l]	[-n [-1]] [-s]	[-G|-M]	 [-R]  [-u  user_list]
       [job_identifier... |  destination...]

       qstat -Q	[-f [-1]][-W site_specific] [-l] [destination...]

       qstat -q	[-G|-M]	[-l] [destination...]

       qstat -B	[-f [-1]][-W site_specific] [-l] [server_name...]

       qstat -t

DESCRIPTION
       The  qstat  command is used to request the status of jobs, queues, or a
       batch server.  The requested status is written to standard out.

       When requesting job status, synopsis format 1 or	2, qstat  will	output
       information  about each job_identifier or all jobs at each destination.
       Jobs for	which the user does not	have status  privilege	are  not  dis-
       played.

       When  requesting	 queue	or server status, synopsis format 3 through 5,
       qstat will output information about each	destination.

OPTIONS
       -f	 Specifies that	a full status display be written  to  standard
		 out.

       -a	 "All"	jobs  are displayed in the alternative format, see the
		 Standard Output section.  If the operand is a destination id,
		 all  jobs  at that destination	are displayed.	If the operand
		 is a job id, information about	that job is displayed.

       -e	 If the	operand	is a job id or not specified, only jobs	in ex-
		 ecutable  queues  are	displayed.  Setting the	PBS_QSTAT_EXE-
		 CONLY environment variable will also enable this option.

       -i	 Job status is displayed in the	 alternative  format.	For  a
		 destination  id  operand, status for jobs at that destination
		 which are not running	are  displayed.	  This	includes  jobs
		 which	are  queued,  held or waiting.	If an operand is a job
		 id, status for	that job is displayed regardless of its	state.

       -r	 If an operand is a job	id, status for that job	is  displayed.
		 For  a	destination id operand,	status for jobs	at that	desti-
		 nation	which are running are displayed,  this	includes  jobs
		 which are suspended.

       -n	 In  addition  to  the basic information, nodes	allocated to a
		 job are listed.

       -1	 In combination	with -n, the -1	option puts all	of  the	 nodes
		 on  the same line as the job ID.  In combination with -f, at-
		 tributes are not folded to fit	in a terminal window.  This is
		 intended to ease the parsing of the qstat output.

       -s	 In addition to	the basic information, any comment provided by
		 the batch administrator or scheduler is shown.

       -G	 Show size information in giga-bytes.

       -M	 Show size information,	disk or	memory in mega-words.	A word
		 is considered to be 8 bytes.

       -R	 In  addition  to other	information, disk reservation informa-
		 tion is shown.	 Not applicable	to all systems.

       -t	 Normal	qstat output displays a	summary	of the	array  instead
		 of the	entire array, job for job. qstat -t expands the	output
		 to display the	entire array. Note that	arrays are  now	 named
		 with brackets following the array name; for example:

		 echo sleep 20 | qsub -t 0-299 189[].pali

		 Individual  jobs in the array are now also noted using	square
		 brackets instead of dashes; for example, here is part of  the
		 output	of qstat -t for	the preceding array:

		 189[299].napali STDIN[299] dbeer 0 Q batch

       -u	 Job status is displayed in the	alternative format.  If	an op-
		 erand is a job	id, status for that job	is displayed.	For  a
		 destination  id  operand, status for jobs at that destination
		 which are owned by the	user(s)	listed in user_list  are  dis-
		 played.  The syntax of	the user_list is:
		     user_name[@host][,user_name[@host],...]
		 Host  names  may  be  wild  carded  on	 the  left  end,  e.g.
		 "*.nasa.gov".	User_name without a "@host" is	equivalent  to
		 "user_name@*",	that is	at any host.

       -Q	 Specifies  that  the request is for queue status and that the
		 operands are destination identifiers.

       -q	 Specifies that	the request is for queue status	 which	should
		 be shown in the alternative format.

       -B	 Specifies  that  the  request	is for batch server status and
		 that the operands are the names of servers.

       -x	 Specifies that	the output is to be  displayed	in  XML	 form.
		 This  option  is  only	valid with the -f option or by itself,
		 which will also specify the -f	full status display.

       -l	 Specifies that	the long name of the job (or the job name  ap-
		 pended	with the suffix	alias) should be displayed.

OPERANDS
       If neither the -Q nor the -B option is given, the operands on the qstat
       command must be either job identifiers or destinations identifiers.

       If the operand is a job identifier, it must be in the following form:
	    sequence_number[.server_name][@server]
       where sequence_number.server_name is the	 job  identifier  assigned  at
       submittal  time,	see qsub.  If the .server_name is omitted, the name of
       the default server will be used.	 If @server is supplied,  the  request
       will be for the job identifier currently	at that	Server.

       If  the operand is a destination	identifier, it is one of the following
       three forms:
	    queue
	    @server
	    queue@server
       If queue	is specified, the request is for status	of all	jobs  in  that
       queue at	the default server.  If	the @server form is given, the request
       is for status of	all jobs at that server.  If a full destination	 iden-
       tifier,	queue@server,  is given, the request is	for status of all jobs
       in the named queue at the named server.

       If the -Q option	is given, the operands are destination identifiers  as
       specified  above.   If  queue is	specified, the status of that queue at
       the default server will be given.  If queue@server  is  specified,  the
       status  of  the	named  queue  at  the  named server will be given.  If
       @server is specified, the status	of all queues at the named server will
       be  given.  If no destination is	specified, the status of all queues at
       the default server will be given.

       If the -B option	is given, the operand is the name of a server.

STANDARD OUTPUT
       Displaying Job Status

       If job status is	being displayed	in the default format and the  -f  op-
       tion  is	 not  specified, the following items are displayed on a	single
       line, in	the specified order, separated by white	space:

	      -	 the job identifier assigned by	PBS.

	      -	 the job name given by the submitter.

	      -	 the job owner

	      -	 the CPU time used

	      -	 the job state:
		   C -	   Job is completed after having run/
		   E -	Job is exiting after having run.
		   H -	Job is held.
		   Q -	job is queued, eligible	to run or routed.
		   R -	job is running.
		   T -	job is being moved to new location.
		   W -	job is waiting for its execution time
			(-a option) to be reached.
		   S -	(Unicos	only) job is suspend.

	      -	 the queue in which the	job resides

       If job status is	being displayed	and the	-f option  is  specified,  the
       output  will  depend  on	whether	qstat was compiled to use a Tcl	inter-
       preter.	See the	configuration section for details.  If Tcl is not  be-
       ing used, full display for each job consists of the header line:
	   Job Id:  job	identifier
       Followed	by one line per	job attribute of the form:
	   attribute_name = value

       If  any	of  the	options	-a, -i,	-r, -u,	-n, -s,	-G or -M are provided,
       the alternative display format for jobs is used.	 The  following	 items
       are  displayed  on  a single line, in the specified order, separated by
       white space:

	      -	 the job identifier assigned by	PBS.

	      -	 the job owner.

	      -	 The queue in which the	job currently resides.

	      -	 The job name given by the submitter.

	      -	 The session id	(if the	job is running).

	      -	 The number of nodes requested by the job.

	      -	 The number of cpus or tasks requested by the job.

	      -	 The amount of memory requested	by the job.

	      -	 Either	the cpu	time, if specified, or wall time requested  by
		 the job, (hh:mm).

	      -	 The job's current state.

	      -	 The amount of cpu time	or wall	time used by the job (hh:mm).
       If the -R option	is provided, the line contains:

	      -	 the job identifier assigned by	PBS.

	      -	 the job owner.

	      -	 The queue in which the	job currently resides.

	      -	 The number of nodes requested by the job.

	      -	 The number of cpus or tasks requested by the job.

	      -	 The amount of memory requested	by the job.

	      -	 Either	the cpu	time or	wall time requested by the job.

	      -	 The job's current state.

	      -	 The amount of cpu time	or wall	time used by the job.

	      -	 The amount of SRFS space requested on the big file system.

	      -	 The amount of SRFS space requested on the fast	file system.

	      -	 The  amount  of space requested on the	parallel I/O file sys-
		 tem.
       The last	three fields may not contain useful information	at  all	 sites
       or on all systems.
       Note:  Remaining	 walltime does not account for walltime	multiplication
       factors.

       Displaying Queue	Status

       If queue	status is being	displayed and the -f option was	not specified,
       the  following  items  are displayed on a single	line, in the specified
       order, separated	by white space:

	    -	   the queue name

	    -	   the maximum number of jobs that may be  run	in  the	 queue
		   concurrently

	    -	   the total number of jobs in the queue

	    -	   the enable or disabled status of the	queue

	    -	   the started or stopped status of the	queue

	    -	   for each job	state, the name	of the state and the number of
		   jobs	in the queue in	that state.

	    -	   the type of queue, execution	or routing.

       If queue	status is being	displayed and the -f option is specified,  the
       output  will  depend  on	whether	qstat was compiled to use a Tcl	inter-
       preter.	See the	configuration section for details.  If Tcl is not  be-
       ing used, the full display for each queue consists of the header	line:
	   Queue:  queue_name
       Followed	by one line per	queue attribute	of the form:
	   attribute_name = value

       If  the	-q  option is specified, queue information is displayed	in the
       alternative format:  The	following information is displayed on a	single
       line:

	      -	 the queue name

	      -	 the maximum amount of memory a	job in the queue may request

	      -	 the maximum amount of cpu time	a job in the queue may request

	      -	 the  maximum  amount  of wall time a job in the queue may re-
		 quest

	      -	 the maximum amount of nodes a job in the queue	may request

	      -	 the number of jobs in the queue in the	running	state

	      -	 the number of jobs in the queue in the	queued state

	      -	 the maximum number (limit) of jobs that may  be  run  in  the
		 queue concurrently

	      -	 the state of the queue	given by a pair	of letters:
		 -  either  the	 letter	E if the queue is Enabled or D if Dis-
		 abled,	and
		 - either the letter R if the queue is Running (started) or  S
		 if Stopped.

       Displaying Server Status

       If  batch  server  status  is  being displayed and the -f option	is not
       specified, the following	items are displayed on a single	line,  in  the
       specified order,	separated by white space:

	    -	   the server name

	    -	   the	maximum	number of jobs that the	server may run concur-
		   rently

	    -	   the total number of jobs currently managed by the server

	    -	   the status of the server

	    -	   for each job	state, the name	of the state and the number of
		   jobs	in the server in that state

       If server status	is being displayed and the -f option is	specified, the
       output will depend on whether qstat was compiled	to use	a  Tcl	inter-
       preter.	 See the configuration section for details.  If	Tcl is not be-
       ing used, the full display for the server consist of the	header line:
	   Server:  server name
       Followed	by one line per	server attribute of the	form:
	   attribute_name = value

STANDARD ERROR
       The qstat command will write a diagnostic message to standard error for
       each error occurrence.

CONFIGURATION
       If qstat	is compiled with an option to include a	Tcl interpreter, using
       the -f flag to get a full display causes	a  check  to  be  made	for  a
       script  file to use to output the requested information.	 The first lo-
       cation checked is $HOME/.qstatrc.  If this does not exist, the next lo-
       cation  checked is administrator	configured.  If	one of these is	found,
       a Tcl interpreter is started and	the script file	is passed to it	 along
       with three global variables.  The command line arguments	are split into
       two variable named flags	and operands  .	  The  status  information  is
       passed  in  a  variable named objects .	All of these variables are Tcl
       lists.  The flags list contains the name	of the command	(usually  "qs-
       tat") as	its first element.  Any	other elements are command line	option
       flags with any options they use,	presented in the order	given  on  the
       command line.  They are broken up individually so that if two flags are
       given together on the command line, they	are  separated	in  the	 list.
       For example, if the user	typed

       qstat -QfWbigdisplay

       the flags list would contain

       qstat -Q	-f -W bigdisplay

       The  operands  list contains all	other command line arguments following
       the flags.  There will always be	at least one element in	 operands  be-
       cause  if no operands are typed by the user, the	default	destination or
       server name is used.  The objects list contains all the information re-
       trieved	from the server(s) so the Tcl interpreter can run once to for-
       mat the entire output.  This list has the same number  of  elements  as
       the  operands  list.   Each  element is another list with two elements.
       The first element is a string giving the	type of	objects	to be found in
       the second.  The	string can take	the values "server", "queue", "job" or
       "error".	 The second element will be a list in which each element is  a
       single  batch  status  object of	the type given by the string discussed
       above.  In the case of "error", the list	will be	empty.	Each object is
       again a list.  The first	element	is the name of the object.  The	second
       is a list of attributes.	 The third element will	be  the	 object	 text.
       All three of these object elements correspond with fields in the	struc-
       ture batch_status which is described in detail for each type of	object
       by  the	man  pages  for	 pbs_statjob(3), pbs_statque(3), and pbs_stat-
       server(3).  Each	attribute in the second	element	 list  whose  elements
       correspond with the attrl structure.  Each will be a list with two ele-
       ments.  The first will be the attribute name and	the second will	be the
       attribute value.

EXIT STATUS
       Upon  successful	 processing of all the operands	presented to the qstat
       command,	the exit status	will be	a value	of zero.

       If the qstat command fails to process any operand,  the	command	 exits
       with a value greater than zero.

SEE ALSO
       qalter(1B),	qsub(1B),      pbs_alterjob(3B),      pbs_statjob(3B),
       pbs_statque(3B),	  pbs_statserver(3B),	pbs_submit(3B),	   pbs_job_at-
       tributes(7B),	pbs_queue_attributes(7B),   pbs_server_attributes(7B),
       pbs_resources_*(7B) where * is system type, and the PBS ERS.

Local								     qstat(1B)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STANDARD OUTPUT | STANDARD ERROR | CONFIGURATION | EXIT STATUS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=qstat&sektion=1b&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help