QSELECT(1)                 POSIX Programmer's Manual                QSELECT(1)



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

NAME
       qselect -- select batch jobs

SYNOPSIS
       qselect [[-a [[op]]date__time]] [[-A account__string]] [[-c [[op]]interval]]
           [[-h hold__list]] [[-l resource__list]] [[-N name]] [[-p [[op]]priority]]
           [[-q destination]] [[-r _y|_n]] [[-s states]] [[-u user__list]]

DESCRIPTION
       To select a set of batch jobs is to return the batch job__identifiers
       for each batch job that meets a list of selection criteria. A set of
       batch jobs is selected by a request to a batch server. The qselect
       utility is a user-accessible batch client that requests the selection
       of batch jobs.

       Upon successful completion, the qselect utility shall have returned a
       list of zero or more batch job__identifiers that meet the criteria
       specified by the options and option-arguments presented to the utility.

       The qselect utility shall select batch jobs by sending a Select Jobs
       Request to a batch server. The qselect utility shall not exit until the
       server replies to each request generated.

       For each option presented to the qselect utility, the utility shall
       restrict the set of selected batch jobs as described in the OPTIONS
       section.

       The qselect utility shall not restrict selection of batch jobs except
       by authorization and as required by the options presented to the
       utility.

       When an option is specified with a mandatory or optional op component
       to the option-argument, then op shall specify a relation between the
       value of a certain batch job attribute and the value component of the
       option-argument. If an op is allowable on an option, then the
       description of the option letter indicates the op as either mandatory
       or optional. Acceptable strings for the op component, and the relation
       the string indicates, are shown in the following list:

       .eq.    The value represented by the attribute of the batch job is
               equal to the value represented by the option-argument.

       .ge.    The value represented by the attribute of the batch job is
               greater than or equal to the value represented by the option-
               argument.

       .gt.    The value represented by the attribute of the batch job is
               greater than the value represented by the option-argument.

       .lt.    The value represented by the attribute of the batch job is less
               than the value represented by the option-argument.

       .le.    The value represented by the attribute of the batch job is less
               than or equal to the value represented by the option-argument.

       .ne.    The value represented by the attribute of the batch job is not
               equal to the value represented by the option-argument.

OPTIONS
       The qselect 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:

       -a [[op]]date__time
                 Restrict selection to a specific time, or a range of times.

                 The qselect utility shall select only batch jobs for which
                 the value of the Execution__Time attribute is related to the
                 Epoch equivalent of the local time expressed by the value of
                 the date__time component of the option-argument in the manner
                 indicated by the value of the op component of the option-
                 argument.

                 The qselect utility shall accept a date__time component of the
                 option-argument that conforms to the syntax of the time
                 operand of the touch utility.

                 If the op component of the option-argument is not presented
                 to the qselect utility, the utility shall select batch jobs
                 for which the Execution__Time attribute is equal to the
                 date__time component of the option-argument.

                 When comparing times, the qselect utility shall use the
                 following definitions for the op component of the option-
                 argument:

                 .eq.    The time represented by value of the Execution__Time
                         attribute of the batch job is equal to the time
                         represented by the date__time component of the option-
                         argument.

                 .ge.    The time represented by value of the Execution__Time
                         attribute of the batch job is after or equal to the
                         time represented by the date__time component of the
                         option-argument.

                 .gt.    The time represented by value of the Execution__Time
                         attribute of the batch job is after the time
                         represented by the date__time component of the option-
                         argument.

                 .lt.    The time represented by value of the Execution__Time
                         attribute of the batch job is before the time
                         represented by the date__time component of the option-
                         argument.

                 .le.    The time represented by value of the Execution__Time
                         attribute of the batch job is before or equal to the
                         time represented by the date__time component of the
                         option-argument.

                 .ne.    The time represented by value of the Execution__Time
                         attribute of the batch job is not equal to the time
                         represented by the date__time component of the option-
                         argument.

                 The qselect utility shall accept the defined character
                 strings for the op component of the option-argument.

       -A account__string
                 Restrict selection to the batch jobs charging a specified
                 account.

                 The qselect utility shall select only batch jobs for which
                 the value of the Account__Name attribute of the batch job
                 matches the value of the account__string option-argument.

                 The syntax of the account__string option-argument is
                 unspecified.

       -c [[op]]interval
                 Restrict selection to batch jobs within a range of checkpoint
                 intervals.

                 The qselect utility shall select only batch jobs for which
                 the value of the Checkpoint attribute relates to the value of
                 the interval component of the option-argument in the manner
                 indicated by the value of the op component of the option-
                 argument.

                 If the op component of the option-argument is omitted, the
                 qselect utility shall select batch jobs for which the value
                 of the Checkpoint attribute is equal to the value of the
                 interval component of the option-argument.

                 When comparing checkpoint intervals, the qselect utility
                 shall use the following definitions for the op component of
                 the option-argument:

                 .eq.    The value of the Checkpoint attribute of the batch
                         job equals the value of the interval component of the
                         option-argument.

                 .ge.    The value of the Checkpoint attribute of the batch
                         job is greater than or equal to the value of the
                         interval component option-argument.

                 .gt.    The value of the Checkpoint attribute of the batch
                         job is greater than the value of the interval
                         component option-argument.

                 .lt.    The value of the Checkpoint attribute of the batch
                         job is less than the value of the interval component
                         option-argument.

                 .le.    The value of the Checkpoint attribute of the batch
                         job is less than or equal to the value of the
                         interval component option-argument.

                 .ne.    The value of the Checkpoint attribute of the batch
                         job does not equal the value of the interval
                         component option-argument.

                 The qselect utility shall accept the defined character
                 strings for the op component of the option-argument.

                 The ordering relationship for the values of the interval
                 option-argument is defined to be:


                     `n' .gt. `s' .gt. `c=minutes' .ge. `c'

                 When comparing Checkpoint attributes with an interval having
                 the value of the single character 'u', only equality or
                 inequality are valid comparisons.

       -h hold__list
                 Restrict selection to batch jobs that have a specific type of
                 hold.

                 The qselect utility shall select only batch jobs for which
                 the value of the Hold__Types attribute matches the value of
                 the hold__list option-argument.

                 The qselect -h option shall accept a value for the hold__list
                 option-argument that is a string of alphanumeric characters
                 in the portable character set (see the Base Definitions
                 volume of POSIX.1-2017, Section 6.1, Portable Character Set).

                 The qselect utility shall accept a value for the hold__list
                 option-argument that is a string of one or more of the
                 characters 'u', 's', or 'o', or the single character 'n'.

                 Each unique character in the hold__list option-argument of the
                 qselect utility is defined as follows, each representing a
                 different hold type:

                 u     USER

                 s     SYSTEM

                 o     OPERATOR

                 If any of these characters are duplicated in the hold__list
                 option-argument, the duplicates shall be ignored.

                 The qselect utility shall consider it an error if any hold
                 type other than 'n' is combined with hold type 'n'.

                 Strictly conforming applications shall not repeat any of the
                 characters 'u', 's', 'o', or 'n' within the hold__list option-
                 argument. The qselect utility shall permit the repetition of
                 characters, but shall not assign additional meaning to the
                 repeated characters.

                 An implementation may define other hold types. The
                 conformance document for an implementation shall describe any
                 additional hold types, how they are specified, their internal
                 behavior, and how they affect the behavior of the utility.

       -l resource__list
                 Restrict selection to batch jobs with specified resource
                 limits and attributes.

                 The qselect utility shall accept a resource__list option-
                 argument with the following syntax:


                     resource__name op value [[,,resource__name op value,, ...]]

                 When comparing resource values, the qselect utility shall use
                 the following definitions for the op component of the option-
                 argument:

                 .eq.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job equals the
                         value of the value component of the option-argument.

                 .ge.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job is greater
                         than or equal to the value of the value component of
                         the option-argument.

                 .gt.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job is greater
                         than the value of the value component of the option-
                         argument.

                 .lt.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job is less than
                         the value of the value component of the option-
                         argument.

                 .ne.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job does not
                         equal the value of the value component of the option-
                         argument.

                 .le.    The value of the resource of the same name in the
                         Resource__List attribute of the batch job is less than
                         or equal to the value of the value component of the
                         option-argument.

                 When comparing the limit of a Resource__List attribute with
                 the value component of the option-argument, if the limit, the
                 value, or both are non-numeric, only equality or inequality
                 are valid comparisons.

                 The qselect utility shall select only batch jobs for which
                 the values of the resource__names listed in the resource__list
                 option-argument match the corresponding limits of the
                 Resource__List attribute of the batch job.

                 Limits of resource__names present in the Resource__List
                 attribute of the batch job that have no corresponding values
                 in the resource__list option-argument shall not be considered
                 when selecting batch jobs.

       -N name   Restrict selection to batch jobs with a specified name.

                 The qselect utility shall select only batch jobs for which
                 the value of the Job__Name attribute matches the value of the
                 name option-argument. The string specified in the name
                 option-argument shall be passed, uninterpreted, to the
                 server. This allows an implementation to match ``wildcard''
                 patterns against batch job names.

                 An implementation shall describe in the conformance document
                 the format it supports for matching against the Job__Name
                 attribute.

       -p [[op]]priority
                 Restrict selection to batch jobs of the specified priority or
                 range of priorities.

                 The qselect utility shall select only batch jobs for which
                 the value of the Priority attribute of the batch job relates
                 to the value of the priority component of the option-argument
                 in the manner indicated by the value of the op component of
                 the option-argument.

                 If the op component of the option-argument is omitted, the
                 qselect utility shall select batch jobs for which the value
                 of the Priority attribute of the batch job is equal to the
                 value of the priority component of the option-argument.

                 When comparing priority values, the qselect utility shall use
                 the following definitions for the op component of the option-
                 argument:

                 .eq.    The value of the Priority attribute of the batch job
                         equals the value of the priority component of the
                         option-argument.

                 .ge.    The value of the Priority attribute of the batch job
                         is greater than or equal to the value of the priority
                         component option-argument.

                 .gt.    The value of the Priority attribute of the batch job
                         is greater than the value of the priority component
                         option-argument.

                 .lt.    The value of the Priority attribute of the batch job
                         is less than the value of the priority component
                         option-argument.

                 .lt.    The value of the Priority attribute of the batch job
                         is less than or equal to the value of the priority
                         component option-argument.

                 .ne.    The value of the Priority attribute of the batch job
                         does not equal the value of the priority component
                         option-argument.

       -q destination
                 Restrict selection to the specified batch queue or server, or
                 both.

                 The qselect utility shall select only batch jobs that are
                 located at the destination indicated by the value of the
                 destination option-argument.

                 The destination defines a batch queue, a server, or a batch
                 queue at a server.

                 The qselect utility shall accept an option-argument for the
                 -q option that conforms to the syntax for a destination. If
                 the -q option is not presented to the qselect utility, the
                 utility shall select batch jobs from all batch queues at the
                 default batch server.

                 If the option-argument describes only a batch queue, the
                 qselect utility shall select only batch jobs from the batch
                 queue of the specified name at the default batch server. The
                 means by which qselect determines the default server is
                 implementation-defined.

                 If the option-argument describes only a batch server, the
                 qselect utility shall select batch jobs from all the batch
                 queues at that batch server.

                 If the option-argument describes both a batch queue and a
                 batch server, the qselect utility shall select only batch
                 jobs from the specified batch queue at the specified server.

       -r y|n    Restrict selection to batch jobs with the specified
                 rerunability status.

                 The qselect utility shall select only batch jobs for which
                 the value of the Rerunable attribute of the batch job matches
                 the value of the option-argument.

                 The qselect utility shall accept a value for the option-
                 argument that consists of either the single character 'y' or
                 the single character 'n'.  The character 'y' represents the
                 value TRUE, and the character 'n' represents the value FALSE.

       -s states Restrict selection to batch jobs in the specified states.

                 The qselect utility shall accept an option-argument that
                 consists of any combination of the characters 'e', 'q', 'r',
                 'w', 'h', and 't'.

                 Conforming applications shall not repeat any character in the
                 option-argument. The qselect utility shall permit the
                 repetition of characters in the option-argument, but shall
                 not assign additional meaning to repeated characters.

                 The qselect utility shall interpret the characters in the
                 states option-argument as follows:

                 e     Represents the EXITING state.

                 q     Represents the QUEUED state.

                 r     Represents the RUNNING state.

                 t     Represents the TRANSITING state.

                 h     Represents the HELD state.

                 w     Represents the WAITING state.

                 For each character in the states option-argument, the qselect
                 utility shall select batch jobs in the corresponding state.

       -u user__list
                 Restrict selection to batch jobs owned by the specified user
                 names.

                 The qselect utility shall select only the batch jobs of those
                 users specified in the user__list option-argument.

                 The qselect utility shall accept a user__list option-argument
                 that conforms to the following syntax:


                     username[[@host]][[,,username[[@host]],, ...]]

                 The qselect utility shall accept only one user name that is
                 missing a corresponding host name. The qselect utility shall
                 accept only one user name per named host.

OPERANDS
       None.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of
       qselect:

       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__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.

       LOGNAME   Determine the login name of the user.

       TZ        Determine the timezone used to interpret the date-time
                 option-argument. If TZ is unset or null, an unspecified
                 default timezone shall be used.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       The qselect utility shall write zero or more batch job__identifiers to
       standard output.

       The qselect utility shall separate the batch job__identifiers written to
       standard output by white space.

       The qselect utility shall write batch job__identifiers in the following
       format:


           sequence__number.server__name@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
       Default.

       The following sections are informative.

APPLICATION USAGE
       None.

EXAMPLES
       The following example shows how a user might use the qselect utility in
       conjunction with the qdel utility to delete all of his or her jobs in
       the queued state without affecting any jobs that are already running:


           qdel $(qselect -s q)

       or:


           qselect -s q || xargs qdel

RATIONALE
       The qselect utility allows users to acquire a list of job identifiers
       that match user-specified selection criteria. The list of identifiers
       returned by the qselect utility conforms to the syntax of the batch job
       identifier list processed by a utility such as qmove, qdel, and qrls.
       The qselect utility is thus a powerful tool for causing another batch
       system utility to act upon a set of jobs that match a list of selection
       criteria.

       The options of the qselect utility let the user apply a number of
       useful filters for selecting jobs. Each option further restricts the
       selection of jobs. Many of the selection options allow the
       specification of a relational operator. The FORTRAN-like syntax of the
       operator--that is, ""..lltt..""--was chosen rather than the C-like ""<<=="" meta-
       characters.

       The -a option allows users to restrict the selected jobs to those that
       have been submitted (or altered) to wait until a particular time. The
       time period is determined by the argument of this option, which
       includes both a time and an operator--it is thus possible to select
       jobs waiting until a specific time, jobs waiting until after a certain
       time, or those waiting for a time before the specified time.

       The -A option allows users to restrict the selected jobs to those that
       have been submitted (or altered) to charge a particular account.

       The -c option allows users to restrict the selected jobs to those whose
       checkpointing interval falls within the specified range.

       The -l option allows users to select those jobs whose resource limits
       fall within the range indicated by the value of the option. For
       example, a user could select those jobs for which the CPU time limit is
       greater than two hours.

       The -N option allows users to select jobs by job name. For instance,
       all the parts of a task that have been divided in parallel jobs might
       be given the same name, and thus manipulated as a group by means of
       this option.

       The -q option allows users to select jobs in a specified queue.

       The -r option allows users to select only those jobs with a specified
       rerun criteria. For instance, a user might select only those jobs that
       can be rerun for use with the qrerun utility.

       The -s option allows users to select only those jobs that are in a
       certain state.

       The -u option allows users to select jobs that have been submitted to
       execute under a particular account.

       The selection criteria provided by the options of the qselect utility
       allow users to select jobs based on all the appropriate attributes that
       can be assigned to jobs by the qsub utility.

       Historically, the qselect utility has not been a part of existing
       practice; it is an improvement that has been introduced in this volume
       of POSIX.1-2017.

FUTURE DIRECTIONS
       The qselect utility may be removed in a future version.

SEE ALSO
       Chapter _3, Batch Environment Services, qdel, qrerun, qrls, qselect,
       qsub, touch

       The Base Definitions volume of POSIX.1-2017, Section 6.1, Portable
       Character Set, Chapter _8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                           QSELECT(1)
