# qstat

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           qstat — show status of batch jobs
    


## SYNOPSIS



           qstat **[** -f**]**_job_identifier_...
    
           qstat -Q **[** -f**]**_destination_...
    
           qstat -B **[** -f**]**_server_name_...
    


## DESCRIPTION



           The status of a batch job, batch queue, or batch server is
           obtained by a request to the server. The _qstat_ utility is a user-
           accessible batch client that requests the status of one or more
           batch jobs, batch queues, or servers, and writes the status
           information to standard output.
    
           For each successfully processed batch _job_identifier_ , the _qstat_
           utility shall display information about the corresponding batch
           job.
    
           For each successfully processed destination, the _qstat_ utility
           shall display information about the corresponding batch queue.
    
           For each successfully processed server name, the _qstat_ utility
           shall display information about the corresponding server.
    
           The _qstat_ utility shall acquire batch job status information by
           sending a _Job Status Request_ to a batch server. The _qstat_ utility
           shall acquire batch queue status information by sending a _Queue_
           _Status Request_ to a batch server. The _qstat_ utility shall acquire
           server status information by sending a _Server Status Request_ to a
           batch server.
    


## OPTIONS



           The _qstat_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported by the implementation:
    
           **-f** Specify that a full display is produced.
    
                     The minimum contents of a full display are specified in
                     the STDOUT section.
    
                     Additional contents and format of a full display are
                     implementation-defined.
    
           **-Q** Specify that the operand is a destination.
    
                     The _qstat_ utility shall display information about each
                     batch queue at each destination identified as an
                     operand.
    
           **-B** Specify that the operand is a server name.
    
                     The _qstat_ utility shall display information about each
                     server identified as an operand.
    


## OPERANDS



           If the **-Q** option is presented to the _qstat_ utility, the utility
           shall accept one or more operands that conform to the syntax for a
           destination (see _Section 3.3.2_ , _Destination_).
    
           If the **-B** option is presented to the _qstat_ utility, the utility
           shall accept one or more _server_name_ operands.
    
           If neither the **-B** nor the **-Q** option is presented to the _qstat_
           utility, the utility shall accept one or more operands that
           conform to the syntax for a batch _job_identifier_ (see _Section_
           _3.3.1_ , _Batch Job Identifier_).
    


## STDIN



           Not used.
    


## INPUT FILES



           None.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _qstat_ :
    
           _HOME_      Determine the pathname of the user's home directory.
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_COLLATE_
                     Determine the locale for the behavior of ranges,
                     equivalence classes, and multi-character collating
                     elements within regular expressions.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte as opposed to multi-byte characters in
                     arguments).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _LC_NUMERIC_
                     Determine the locale for selecting the radix character
                     used when writing floating-point formatted output.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           If an operand presented to the _qstat_ utility is a batch
           _job_identifier_ and the **-f** option is not specified, the _qstat_
           utility shall display the following items on a single line, in the
           stated order, with white space between each item, for each
           successfully processed operand:
    
            *  The batch _job_identifier_
    
            *  The batch job name
    
            *  The _Job_Owner_ attribute
    
            *  The CPU time used by the batch job
    
            *  The batch job state
    
            *  The batch job location
    
           If an operand presented to the _qstat_ utility is a batch
           _job_identifier_ and the **-f** option is specified, the _qstat_ utility
           shall display the following items for each success fully processed
           operand:
    
            *  The batch _job_identifier_
    
            *  The batch job name
    
            *  The _Job_Owner_ attribute
    
            *  The execution user ID
    
            *  The CPU time used by the batch job
    
            *  The batch job state
    
            *  The batch job location
    
            *  Additional implementation-defined information, if any, about
               the batch job or batch queue
    
           If an operand presented to the _qstat_ utility is a destination, the
           **-Q** option is specified, and the **-f** option is not specified, the
           _qstat_ utility shall display the following items on a single line,
           in the stated order, with white space between each item, for each
           successfully processed operand:
    
            *  The batch queue name
    
            *  The maximum number of batch jobs that shall be run in the
               batch queue concurrently
    
            *  The total number of batch jobs in the batch queue
    
            *  The status of the batch queue
    
            *  For each state, the number of batch jobs in that state in the
               batch queue and the name of the state
    
            *  The type of batch queue (execution or routing)
    
           If the operands presented to the _qstat_ utility are destinations,
           the **-Q** option is specified, and the **-f** option is specified, the
           _qstat_ utility shall display the following items for each
           successfully processed operand:
    
            *  The batch queue name
    
            *  The maximum number of batch jobs that shall be run in the
               batch queue concurrently
    
            *  The total number of batch jobs in the batch queue
    
            *  The status of the batch queue
    
            *  For each state, the number of batch jobs in that state in the
               batch queue and the name of the state
    
            *  The type of batch queue (execution or routing)
    
            *  Additional implementation-defined information, if any, about
               the batch queue
    
           If the operands presented to the _qstat_ utility are batch server
           names, the **-B** option is specified, and the **-f** option is not
           specified, the _qstat_ utility shall display the following items on
           a single line, in the stated order, with white space between each
           item, for each successfully processed operand:
    
            *  The batch server name
    
            *  The maximum number of batch jobs that shall be run in the
               batch queue concurrently
    
            *  The total number of batch jobs managed by the batch server
    
            *  The status of the batch server
    
            *  For each state, the number of batch jobs in that state and the
               name of the state
    
           If the operands presented to the _qstat_ utility are server names,
           the **-B** option is specified, and the **-f** option is specified, the
           _qstat_ utility shall display the following items for each
           successfully processed operand:
    
            *  The server name
    
            *  The maximum number of batch jobs that shall be run in the
               batch queue concurrently
    
            *  The total number of batch jobs managed by the server
    
            *  The status of the server
    
            *  For each state, the number of batch jobs in that state and the
               name of the state
    
            *  Additional implementation-defined information, if any, about
               the server
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           In addition to the default behavior, the _qstat_ utility shall not
           be required to write a diagnostic message to standard error when
           the error reply received from a batch server indicates that the
           batch _job_identifier_ does not exist on the server. Whether or not
           the _qstat_ utility waits to output the diagnostic message while
           attempting to locate the batch job on other servers is
           implementation-defined.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           None.
    


## EXAMPLES



           None.
    


## RATIONALE



           The _qstat_ utility allows users to display the status of jobs and
           list the batch jobs in queues.
    
           The operands of the _qstat_ utility may be either job identifiers,
           queues (specified as destination identifiers), or batch server
           names. The **-Q** and **-B** options, or absence thereof, indicate the
           nature of the operands.
    
           The other options of the _qstat_ utility allow the user to control
           the amount of information displayed and the format in which it is
           displayed. Should a user wish to display the status of a set of
           jobs that match a selection criteria, the _qselect_ utility may be
           used to acquire such a list.
    
           The **-f** option allows users to request a ``full'' display in an
           implementation-defined format.
    
           Historically, the _qstat_ utility has been a part of the NQS and its
           derivatives, the existing practice on which it is based.
    


## FUTURE DIRECTIONS



           The _qstat_ utility may be removed in a future version.
    


* * *