1QSELECT(1P)                POSIX Programmer's Manual               QSELECT(1P)
2
3
4

PROLOG

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

NAME

12       qselect — select batch jobs
13

SYNOPSIS

15       qselect [-a [op]date_time] [-A account_string] [-c [op]interval]
16           [-h hold_list] [-l resource_list] [-N name] [-p [op]priority]
17           [-q destination] [-r y|n] [-s states] [-u user_list]
18

DESCRIPTION

20       To select a set of batch jobs is to return  the  batch  job_identifiers
21       for  each  batch  job that meets a list of selection criteria. A set of
22       batch jobs is selected by a request to  a  batch  server.  The  qselect
23       utility  is  a user-accessible batch client that requests the selection
24       of batch jobs.
25
26       Upon successful completion, the qselect utility shall have  returned  a
27       list of zero or more batch job_identifiers that meet the criteria spec‐
28       ified by the options and option-arguments presented to the utility.
29
30       The qselect utility shall select batch jobs by sending  a  Select  Jobs
31       Request to a batch server. The qselect utility shall not exit until the
32       server replies to each request generated.
33
34       For each option presented to the qselect  utility,  the  utility  shall
35       restrict  the  set  of  selected batch jobs as described in the OPTIONS
36       section.
37
38       The qselect utility shall not restrict selection of batch  jobs  except
39       by  authorization and as required by the options presented to the util‐
40       ity.
41
42       When an option is specified with a mandatory or optional  op  component
43       to  the  option-argument,  then op shall specify a relation between the
44       value of a certain batch job attribute and the value component  of  the
45       option-argument.  If an op is allowable on an option, then the descrip‐
46       tion of the option letter indicates  the  op  as  either  mandatory  or
47       optional. Acceptable strings for the op component, and the relation the
48       string indicates, are shown in the following list:
49
50       .eq.    The value represented by the attribute  of  the  batch  job  is
51               equal to the value represented by the option-argument.
52
53       .ge.    The  value  represented  by  the  attribute of the batch job is
54               greater than or equal to the value represented by  the  option-
55               argument.
56
57       .gt.    The  value  represented  by  the  attribute of the batch job is
58               greater than the value represented by the option-argument.
59
60       .lt.    The value represented by the attribute of the batch job is less
61               than the value represented by the option-argument.
62
63       .le.    The value represented by the attribute of the batch job is less
64               than or equal to the value represented by the option-argument.
65
66       .ne.    The value represented by the attribute of the batch job is  not
67               equal to the value represented by the option-argument.
68

OPTIONS

70       The  qselect  utility  shall  conform to the Base Definitions volume of
71       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
72
73       The following options shall be supported by the implementation:
74
75       -a [op]date_time
76                 Restrict selection to a specific time, or a range of times.
77
78                 The qselect utility shall select only batch  jobs  for  which
79                 the  value  of the Execution_Time attribute is related to the
80                 Epoch equivalent of the local time expressed by the value  of
81                 the  date_time component of the option-argument in the manner
82                 indicated by the value of the op  component  of  the  option-
83                 argument.
84
85                 The qselect utility shall accept a date_time component of the
86                 option-argument that conforms to the syntax of the time oper‐
87                 and of the touch utility.
88
89                 If  the  op component of the option-argument is not presented
90                 to the qselect utility, the utility shall select  batch  jobs
91                 for  which  the  Execution_Time  attribute  is  equal  to the
92                 date_time component of the option-argument.
93
94                 When comparing times, the qselect utility shall use the  fol‐
95                 lowing  definitions  for the op component of the option-argu‐
96                 ment:
97
98                 .eq.    The time represented by value of  the  Execution_Time
99                         attribute  of the batch job is equal to the time rep‐
100                         resented by the date_time component  of  the  option-
101                         argument.
102
103                 .ge.    The  time  represented by value of the Execution_Time
104                         attribute of the batch job is after or equal  to  the
105                         time  represented  by  the date_time component of the
106                         option-argument.
107
108                 .gt.    The time represented by value of  the  Execution_Time
109                         attribute  of  the batch job is after the time repre‐
110                         sented by the date_time component of the option-argu‐
111                         ment.
112
113                 .lt.    The  time  represented by value of the Execution_Time
114                         attribute of the batch job is before the time  repre‐
115                         sented by the date_time component of the option-argu‐
116                         ment.
117
118                 .le.    The time represented by value of  the  Execution_Time
119                         attribute  of the batch job is before or equal to the
120                         time represented by the date_time  component  of  the
121                         option-argument.
122
123                 .ne.    The  time  represented by value of the Execution_Time
124                         attribute of the batch job is not equal to  the  time
125                         represented by the date_time component of the option-
126                         argument.
127
128                 The  qselect  utility  shall  accept  the  defined  character
129                 strings for the op component of the option-argument.
130
131       -A account_string
132                 Restrict  selection  to  the  batch jobs charging a specified
133                 account.
134
135                 The qselect utility shall select only batch  jobs  for  which
136                 the  value  of  the  Account_Name  attribute of the batch job
137                 matches the value of the account_string option-argument.
138
139                 The syntax of the account_string option-argument is  unspeci‐
140                 fied.
141
142       -c [op]interval
143                 Restrict selection to batch jobs within a range of checkpoint
144                 intervals.
145
146                 The qselect utility shall select only batch  jobs  for  which
147                 the value of the Checkpoint attribute relates to the value of
148                 the interval component of the option-argument in  the  manner
149                 indicated  by  the  value  of the op component of the option-
150                 argument.
151
152                 If the op component of the option-argument  is  omitted,  the
153                 qselect  utility  shall select batch jobs for which the value
154                 of the Checkpoint attribute is equal  to  the  value  of  the
155                 interval component of the option-argument.
156
157                 When  comparing  checkpoint  intervals,  the  qselect utility
158                 shall use the following definitions for the op  component  of
159                 the option-argument:
160
161                 .eq.    The  value  of  the Checkpoint attribute of the batch
162                         job equals the value of the interval component of the
163                         option-argument.
164
165                 .ge.    The  value  of  the Checkpoint attribute of the batch
166                         job is greater than or equal  to  the  value  of  the
167                         interval component option-argument.
168
169                 .gt.    The  value  of  the Checkpoint attribute of the batch
170                         job is greater than the value of the interval  compo‐
171                         nent option-argument.
172
173                 .lt.    The  value  of  the Checkpoint attribute of the batch
174                         job is less than the value of the interval  component
175                         option-argument.
176
177                 .le.    The  value  of  the Checkpoint attribute of the batch
178                         job is less than or equal to the value of the  inter‐
179                         val component option-argument.
180
181                 .ne.    The  value  of  the Checkpoint attribute of the batch
182                         job does not equal the value of the  interval  compo‐
183                         nent option-argument.
184
185                 The  qselect  utility  shall  accept  the  defined  character
186                 strings for the op component of the option-argument.
187
188                 The ordering relationship for  the  values  of  the  interval
189                 option-argument is defined to be:
190
191
192                     `n' .gt. `s' .gt. `c=minutes' .ge. `c'
193
194                 When  comparing Checkpoint attributes with an interval having
195                 the value of the  single  character  'u',  only  equality  or
196                 inequality are valid comparisons.
197
198       -h hold_list
199                 Restrict selection to batch jobs that have a specific type of
200                 hold.
201
202                 The qselect utility shall select only batch  jobs  for  which
203                 the  value  of  the Hold_Types attribute matches the value of
204                 the hold_list option-argument.
205
206                 The qselect -h option shall accept a value for the  hold_list
207                 option-argument  that  is a string of alphanumeric characters
208                 in the portable character set (see the Base Definitions  vol‐
209                 ume of POSIX.1‐2017, Section 6.1, Portable Character Set).
210
211                 The  qselect  utility  shall accept a value for the hold_list
212                 option-argument that is a string of one or more of the  char‐
213                 acters 'u', 's', or 'o', or the single character 'n'.
214
215                 Each unique character in the hold_list option-argument of the
216                 qselect utility is defined as follows,  each  representing  a
217                 different hold type:
218
219                 u     USER
220
221                 s     SYSTEM
222
223                 o     OPERATOR
224
225                 If  any  of  these characters are duplicated in the hold_list
226                 option-argument, the duplicates shall be ignored.
227
228                 The qselect utility shall consider it an error  if  any  hold
229                 type other than 'n' is combined with hold type 'n'.
230
231                 Strictly  conforming applications shall not repeat any of the
232                 characters 'u', 's', 'o', or 'n' within the hold_list option-
233                 argument.  The qselect utility shall permit the repetition of
234                 characters, but shall not assign additional  meaning  to  the
235                 repeated characters.
236
237                 An  implementation  may  define other hold types. The confor‐
238                 mance document for an implementation shall describe any addi‐
239                 tional  hold  types,  how  they are specified, their internal
240                 behavior, and how they affect the behavior of the utility.
241
242       -l resource_list
243                 Restrict selection to batch jobs with specified resource lim‐
244                 its and attributes.
245
246                 The qselect utility shall accept a resource_list option-argu‐
247                 ment with the following syntax:
248
249
250                     resource_name op value [,,resource_name op value,, ...]
251
252                 When comparing resource values, the qselect utility shall use
253                 the following definitions for the op component of the option-
254                 argument:
255
256                 .eq.    The value of the resource of the  same  name  in  the
257                         Resource_List  attribute  of the batch job equals the
258                         value of the value component of the option-argument.
259
260                 .ge.    The value of the resource of the  same  name  in  the
261                         Resource_List  attribute  of the batch job is greater
262                         than or equal to the value of the value component  of
263                         the option-argument.
264
265                 .gt.    The  value  of  the  resource of the same name in the
266                         Resource_List attribute of the batch job  is  greater
267                         than  the value of the value component of the option-
268                         argument.
269
270                 .lt.    The value of the resource of the  same  name  in  the
271                         Resource_List attribute of the batch job is less than
272                         the value of the value component of the  option-argu‐
273                         ment.
274
275                 .ne.    The  value  of  the  resource of the same name in the
276                         Resource_List attribute of the  batch  job  does  not
277                         equal the value of the value component of the option-
278                         argument.
279
280                 .le.    The value of the resource of the  same  name  in  the
281                         Resource_List attribute of the batch job is less than
282                         or equal to the value of the value component  of  the
283                         option-argument.
284
285                 When  comparing  the  limit of a Resource_List attribute with
286                 the value component of the option-argument, if the limit, the
287                 value,  or  both are non-numeric, only equality or inequality
288                 are valid comparisons.
289
290                 The qselect utility shall select only batch  jobs  for  which
291                 the  values of the resource_names listed in the resource_list
292                 option-argument  match  the  corresponding  limits   of   the
293                 Resource_List attribute of the batch job.
294
295                 Limits   of   resource_names  present  in  the  Resource_List
296                 attribute of the batch job that have no corresponding  values
297                 in  the resource_list option-argument shall not be considered
298                 when selecting batch jobs.
299
300       -N name   Restrict selection to batch jobs with a specified name.
301
302                 The qselect utility shall select only batch  jobs  for  which
303                 the  value of the Job_Name attribute matches the value of the
304                 name  option-argument.  The  string  specified  in  the  name
305                 option-argument   shall  be  passed,  uninterpreted,  to  the
306                 server. This allows an implementation to  match  ``wildcard''
307                 patterns against batch job names.
308
309                 An  implementation shall describe in the conformance document
310                 the format it supports  for  matching  against  the  Job_Name
311                 attribute.
312
313       -p [op]priority
314                 Restrict selection to batch jobs of the specified priority or
315                 range of priorities.
316
317                 The qselect utility shall select only batch  jobs  for  which
318                 the  value of the Priority attribute of the batch job relates
319                 to the value of the priority component of the option-argument
320                 in  the  manner indicated by the value of the op component of
321                 the option-argument.
322
323                 If the op component of the option-argument  is  omitted,  the
324                 qselect  utility  shall select batch jobs for which the value
325                 of the Priority attribute of the batch job is  equal  to  the
326                 value of the priority component of the option-argument.
327
328                 When comparing priority values, the qselect utility shall use
329                 the following definitions for the op component of the option-
330                 argument:
331
332                 .eq.    The  value of the Priority attribute of the batch job
333                         equals the value of the  priority  component  of  the
334                         option-argument.
335
336                 .ge.    The  value of the Priority attribute of the batch job
337                         is greater than or equal to the value of the priority
338                         component option-argument.
339
340                 .gt.    The  value of the Priority attribute of the batch job
341                         is greater than the value of the  priority  component
342                         option-argument.
343
344                 .lt.    The  value of the Priority attribute of the batch job
345                         is less than the  value  of  the  priority  component
346                         option-argument.
347
348                 .lt.    The  value of the Priority attribute of the batch job
349                         is less than or equal to the value  of  the  priority
350                         component option-argument.
351
352                 .ne.    The  value of the Priority attribute of the batch job
353                         does not equal the value of  the  priority  component
354                         option-argument.
355
356       -q destination
357                 Restrict selection to the specified batch queue or server, or
358                 both.
359
360                 The qselect utility shall select only  batch  jobs  that  are
361                 located at the destination indicated by the value of the des‐
362                 tination option-argument.
363
364                 The destination defines a batch queue, a server, or  a  batch
365                 queue at a server.
366
367                 The  qselect  utility shall accept an option-argument for the
368                 -q option that conforms to the syntax for a  destination.  If
369                 the  -q  option  is not presented to the qselect utility, the
370                 utility shall select batch jobs from all batch queues at  the
371                 default batch server.
372
373                 If the option-argument describes only a batch queue, the qse‐
374                 lect utility shall select only  batch  jobs  from  the  batch
375                 queue  of the specified name at the default batch server. The
376                 means by which  qselect  determines  the  default  server  is
377                 implementation-defined.
378
379                 If  the  option-argument  describes  only a batch server, the
380                 qselect utility shall select batch jobs from  all  the  batch
381                 queues at that batch server.
382
383                 If  the  option-argument  describes  both a batch queue and a
384                 batch server, the qselect utility  shall  select  only  batch
385                 jobs from the specified batch queue at the specified server.
386
387       -r y|n    Restrict  selection  to  batch jobs with the specified rerun‐
388                 ability status.
389
390                 The qselect utility shall select only batch  jobs  for  which
391                 the value of the Rerunable attribute of the batch job matches
392                 the value of the option-argument.
393
394                 The qselect utility shall accept a value for the option-argu‐
395                 ment  that consists of either the single character 'y' or the
396                 single character 'n'.  The character 'y' represents the value
397                 TRUE, and the character 'n' represents the value FALSE.
398
399       -s states Restrict selection to batch jobs in the specified states.
400
401                 The qselect utility shall accept an option-argument that con‐
402                 sists of any combination of the  characters  'e',  'q',  'r',
403                 'w', 'h', and 't'.
404
405                 Conforming applications shall not repeat any character in the
406                 option-argument. The qselect utility shall permit the repeti‐
407                 tion  of  characters  in  the  option-argument, but shall not
408                 assign additional meaning to repeated characters.
409
410                 The qselect utility shall interpret  the  characters  in  the
411                 states option-argument as follows:
412
413                 e     Represents the EXITING state.
414
415                 q     Represents the QUEUED state.
416
417                 r     Represents the RUNNING state.
418
419                 t     Represents the TRANSITING state.
420
421                 h     Represents the HELD state.
422
423                 w     Represents the WAITING state.
424
425                 For each character in the states option-argument, the qselect
426                 utility shall select batch jobs in the corresponding state.
427
428       -u user_list
429                 Restrict selection to batch jobs owned by the specified  user
430                 names.
431
432                 The qselect utility shall select only the batch jobs of those
433                 users specified in the user_list option-argument.
434
435                 The qselect utility shall accept a user_list  option-argument
436                 that conforms to the following syntax:
437
438
439                     username[@host][,,username[@host],, ...]
440
441                 The  qselect  utility shall accept only one user name that is
442                 missing a corresponding host name. The qselect utility  shall
443                 accept only one user name per named host.
444

OPERANDS

446       None.
447

STDIN

449       Not used.
450

INPUT FILES

452       None.
453

ENVIRONMENT VARIABLES

455       The  following environment variables shall affect the execution of qse‐
456       lect:
457
458       LANG      Provide a default value for  the  internationalization  vari‐
459                 ables  that are unset or null. (See the Base Definitions vol‐
460                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
461                 ables  the  precedence of internationalization variables used
462                 to determine the values of locale categories.)
463
464       LC_ALL    If set to a non-empty string value, override  the  values  of
465                 all the other internationalization variables.
466
467       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
468                 bytes of text data as characters (for example, single-byte as
469                 opposed to multi-byte characters in arguments).
470
471       LC_MESSAGES
472                 Determine the locale that should be used to affect the format
473                 and contents  of  diagnostic  messages  written  to  standard
474                 error.
475
476       LOGNAME   Determine the login name of the user.
477
478       TZ        Determine  the  timezone  used  to  interpret  the  date-time
479                 option-argument. If TZ  is  unset  or  null,  an  unspecified
480                 default timezone shall be used.
481

ASYNCHRONOUS EVENTS

483       Default.
484

STDOUT

486       The  qselect  utility shall write zero or more batch job_identifiers to
487       standard output.
488
489       The qselect utility shall separate the batch job_identifiers written to
490       standard output by white space.
491
492       The  qselect utility shall write batch job_identifiers in the following
493       format:
494
495
496           sequence_number.server_name@server
497

STDERR

499       The standard error shall be used only for diagnostic messages.
500

OUTPUT FILES

502       None.
503

EXTENDED DESCRIPTION

505       None.
506

EXIT STATUS

508       The following exit values shall be returned:
509
510        0    Successful completion.
511
512       >0    An error occurred.
513

CONSEQUENCES OF ERRORS

515       Default.
516
517       The following sections are informative.
518

APPLICATION USAGE

520       None.
521

EXAMPLES

523       The following example shows how a user might use the qselect utility in
524       conjunction  with  the qdel utility to delete all of his or her jobs in
525       the queued state without affecting any jobs that are already running:
526
527
528           qdel $(qselect -s q)
529
530       or:
531
532
533           qselect -s q || xargs qdel
534

RATIONALE

536       The qselect utility allows users to acquire a list of  job  identifiers
537       that  match  user-specified selection criteria. The list of identifiers
538       returned by the qselect utility conforms to the syntax of the batch job
539       identifier  list  processed by a utility such as qmove, qdel, and qrls.
540       The qselect utility is thus a powerful tool for causing  another  batch
541       system utility to act upon a set of jobs that match a list of selection
542       criteria.
543
544       The options of the qselect utility let the user apply a number of  use‐
545       ful  filters  for  selecting  jobs.  Each  option further restricts the
546       selection of jobs. Many of the selection options allow  the  specifica‐
547       tion of a relational operator. The FORTRAN-like syntax of the operator—
548       that is, ".lt."—was chosen rather than the C-like "<=" meta-characters.
549
550       The -a option allows users to restrict the selected jobs to those  that
551       have  been  submitted (or altered) to wait until a particular time. The
552       time period is  determined  by  the  argument  of  this  option,  which
553       includes both a time and an operator—it is thus possible to select jobs
554       waiting until a specific time, jobs waiting until after a certain time,
555       or those waiting for a time before the specified time.
556
557       The  -A option allows users to restrict the selected jobs to those that
558       have been submitted (or altered) to charge a particular account.
559
560       The -c option allows users to restrict the selected jobs to those whose
561       checkpointing interval falls within the specified range.
562
563       The  -l  option allows users to select those jobs whose resource limits
564       fall within the range indicated by the value of the option.  For  exam‐
565       ple,  a  user  could  select those jobs for which the CPU time limit is
566       greater than two hours.
567
568       The -N option allows users to select jobs by job  name.  For  instance,
569       all  the  parts of a task that have been divided in parallel jobs might
570       be given the same name, and thus manipulated as a  group  by  means  of
571       this option.
572
573       The -q option allows users to select jobs in a specified queue.
574
575       The  -r  option allows users to select only those jobs with a specified
576       rerun criteria. For instance, a user might select only those jobs  that
577       can be rerun for use with the qrerun utility.
578
579       The -s option allows users to select only those jobs that are in a cer‐
580       tain state.
581
582       The -u option allows users to select jobs that have been  submitted  to
583       execute under a particular account.
584
585       The  selection  criteria provided by the options of the qselect utility
586       allow users to select jobs based on all the appropriate attributes that
587       can be assigned to jobs by the qsub utility.
588
589       Historically, the qselect utility has not been a part of existing prac‐
590       tice; it is an improvement that has been introduced in this  volume  of
591       POSIX.1‐2017.
592

FUTURE DIRECTIONS

594       The qselect utility may be removed in a future version.
595

SEE ALSO

597       Chapter  3,  Batch  Environment  Services, qdel, qrerun, qrls, qselect,
598       qsub, touch
599
600       The Base Definitions volume  of  POSIX.1‐2017,  Section  6.1,  Portable
601       Character  Set, Chapter 8, Environment Variables, Section 12.2, Utility
602       Syntax Guidelines
603
605       Portions of this text are reprinted and reproduced in  electronic  form
606       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
607       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
608       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
609       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
610       event of any discrepancy between this version and the original IEEE and
611       The Open Group Standard, the original IEEE and The Open Group  Standard
612       is  the  referee document. The original Standard can be obtained online
613       at http://www.opengroup.org/unix/online.html .
614
615       Any typographical or formatting errors that appear  in  this  page  are
616       most likely to have been introduced during the conversion of the source
617       files to man page format. To report such errors,  see  https://www.ker
618       nel.org/doc/man-pages/reporting_bugs.html .
619
620
621
622IEEE/The Open Group                  2017                          QSELECT(1P)
Impressum