1QSELECT(1P) POSIX Programmer's Manual QSELECT(1P)
2
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
12 qselect — select batch jobs
13
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
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 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 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 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 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 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 .eq. The value represented by the attribute of the batch job is
51 equal to the value represented by the option-argument.
52 .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 .gt. The value represented by the attribute of the batch job is
58 greater than the value represented by the option-argument.
59 .lt. The value represented by the attribute of the batch job is less
61 than the value represented by the option-argument.
62 .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 .ne. The value represented by the attribute of the batch job is not
67 equal to the value represented by the option-argument.
68
70 The qselect utility shall conform to the Base Definitions volume of
71 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
72 The following options shall be supported by the implementation:
74 -a [op]date_time
76 Restrict selection to a specific time, or a range of times.
77 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 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 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 When comparing times, the qselect utility shall use the fol‐
95 lowing definitions for the op component of the option-argu‐
96 ment:
97 .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 .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 .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 .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 .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 .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 The qselect utility shall accept the defined character
129 strings for the op component of the option-argument.
130 -A account_string
132 Restrict selection to the batch jobs charging a specified
133 account.
134 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 The syntax of the account_string option-argument is unspeci‐
140 fied.
141 -c [op]interval
143 Restrict selection to batch jobs within a range of checkpoint
144 intervals.
145 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 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 When comparing checkpoint intervals, the qselect utility
158 shall use the following definitions for the op component of
159 the option-argument:
160 .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 .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 .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 .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 .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 .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 The qselect utility shall accept the defined character
186 strings for the op component of the option-argument.
187 The ordering relationship for the values of the interval
189 option-argument is defined to be:
190 `n' .gt. `s' .gt. `c=minutes' .ge. `c'
193 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 -h hold_list
199 Restrict selection to batch jobs that have a specific type of
200 hold.
201 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 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 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 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 u USER
220 s SYSTEM
222 o OPERATOR
224 If any of these characters are duplicated in the hold_list
226 option-argument, the duplicates shall be ignored.
227 The qselect utility shall consider it an error if any hold
229 type other than 'n' is combined with hold type 'n'.
230 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 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 -l resource_list
243 Restrict selection to batch jobs with specified resource lim‐
244 its and attributes.
245 The qselect utility shall accept a resource_list option-argu‐
247 ment with the following syntax:
248 resource_name op value [,,resource_name op value,, ...]
251 When comparing resource values, the qselect utility shall use
253 the following definitions for the op component of the option-
254 argument:
255 .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 .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 .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 .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 .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 .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 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 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 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 -N name Restrict selection to batch jobs with a specified name.
301 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 An implementation shall describe in the conformance document
310 the format it supports for matching against the Job_Name
311 attribute.
312 -p [op]priority
314 Restrict selection to batch jobs of the specified priority or
315 range of priorities.
316 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 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 When comparing priority values, the qselect utility shall use
329 the following definitions for the op component of the option-
330 argument:
331 .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 .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 .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 .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 .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 .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 -q destination
357 Restrict selection to the specified batch queue or server, or
358 both.
359 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 The destination defines a batch queue, a server, or a batch
365 queue at a server.
366 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 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 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 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 -r y|n Restrict selection to batch jobs with the specified rerun‐
388 ability status.
389 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 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 -s states Restrict selection to batch jobs in the specified states.
400 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 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 The qselect utility shall interpret the characters in the
411 states option-argument as follows:
412 e Represents the EXITING state.
414 q Represents the QUEUED state.
416 r Represents the RUNNING state.
418 t Represents the TRANSITING state.
420 h Represents the HELD state.
422 w Represents the WAITING state.
424 For each character in the states option-argument, the qselect
426 utility shall select batch jobs in the corresponding state.
427 -u user_list
429 Restrict selection to batch jobs owned by the specified user
430 names.
431 The qselect utility shall select only the batch jobs of those
433 users specified in the user_list option-argument.
434 The qselect utility shall accept a user_list option-argument
436 that conforms to the following syntax:
437 username[@host][,,username[@host],, ...]
440 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
446 None.
447
449 Not used.
450
452 None.
453
455 The following environment variables shall affect the execution of qse‐
456 lect:
457 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 LC_ALL If set to a non-empty string value, override the values of
465 all the other internationalization variables.
466 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 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 LOGNAME Determine the login name of the user.
477 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
483 Default.
484
486 The qselect utility shall write zero or more batch job_identifiers to
487 standard output.
488 The qselect utility shall separate the batch job_identifiers written to
490 standard output by white space.
491 The qselect utility shall write batch job_identifiers in the following
493 format:
494 sequence_number.server_name@server
497
499 The standard error shall be used only for diagnostic messages.
500
502 None.
503
505 None.
506
508 The following exit values shall be returned:
509 0 Successful completion.
511 >0 An error occurred.
513
515 Default.
516 The following sections are informative.
518
520 None.
521
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 qdel $(qselect -s q)
529 or:
531 qselect -s q || xargs qdel
534
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 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 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 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 The -c option allows users to restrict the selected jobs to those whose
561 checkpointing interval falls within the specified range.
562 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 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 The -q option allows users to select jobs in a specified queue.
574 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 The -s option allows users to select only those jobs that are in a cer‐
580 tain state.
581 The -u option allows users to select jobs that have been submitted to
583 execute under a particular account.
584 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 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
594 The qselect utility may be removed in a future version.
595
597 Chapter 3, Batch Environment Services, qdel, qrerun, qrls, qselect,
598 qsub, touch
599 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 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 .
619IEEE/The Open Group 2017 QSELECT(1P)