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
13 qselect — select batch jobs
14
16 qselect [−a [op]date_time] [−A account_string] [−c [op]interval]
17 [−h hold_list] [−l resource_list] [−N name] [−p [op]priority]
18 [−q destination] [−r y|n] [−s states] [−u user_list]
19
21 To select a set of batch jobs is to return the batch job_identifiers
22 for each batch job that meets a list of selection criteria. A set of
23 batch jobs is selected by a request to a batch server. The qselect
24 utility is a user-accessible batch client that requests the selection
25 of batch jobs.
26 Upon successful completion, the qselect utility shall have returned a
28 list of zero or more batch job_identifiers that meet the criteria spec‐
29 ified by the options and option-arguments presented to the utility.
30 The qselect utility shall select batch jobs by sending a Select Jobs
32 Request to a batch server. The qselect utility shall not exit until the
33 server replies to each request generated.
34 For each option presented to the qselect utility, the utility shall
36 restrict the set of selected batch jobs as described in the OPTIONS
37 section.
38 The qselect utility shall not restrict selection of batch jobs except
40 by authorization and as required by the options presented to the util‐
41 ity.
42 When an option is specified with a mandatory or optional op component
44 to the option-argument, then op shall specify a relation between the
45 value of a certain batch job attribute and the value component of the
46 option-argument. If an op is allowable on an option, then the descrip‐
47 tion of the option letter indicates the op as either mandatory or
48 optional. Acceptable strings for the op component, and the relation the
49 string indicates, are shown in the following list:
50 .eq. The value represented by the attribute of the batch job is
52 equal to the value represented by the option-argument.
53 .ge. The value represented by the attribute of the batch job is
55 greater than or equal to the value represented by the option-
56 argument.
57 .gt. The value represented by the attribute of the batch job is
59 greater than the value represented by the option-argument.
60 .lt. The value represented by the attribute of the batch job is less
62 than the value represented by the option-argument.
63 .le. The value represented by the attribute of the batch job is less
65 than or equal to the value represented by the option-argument.
66 .ne. The value represented by the attribute of the batch job is not
68 equal to the value represented by the option-argument.
69
71 The qselect utility shall conform to the Base Definitions volume of
72 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
73 The following options shall be supported by the implementation:
75 −a [op]date_time
77 Restrict selection to a specific time, or a range of times.
78 The qselect utility shall select only batch jobs for which
80 the value of the Execution_Time attribute is related to the
81 Epoch equivalent of the local time expressed by the value of
82 the date_time component of the option-argument in the manner
83 indicated by the value of the op component of the option-
84 argument.
85 The qselect utility shall accept a date_time component of the
87 option-argument that conforms to the syntax of the time oper‐
88 and of the touch utility.
89 If the op component of the option-argument is not presented
91 to the qselect utility, the utility shall select batch jobs
92 for which the Execution_Time attribute is equal to the
93 date_time component of the option-argument.
94 When comparing times, the qselect utility shall use the fol‐
96 lowing definitions for the op component of the option-argu‐
97 ment:
98 .eq. The time represented by value of the Execution_Time
100 attribute of the batch job is equal to the time rep‐
101 resented by the date_time component of the option-
102 argument.
103 .ge. The time represented by value of the Execution_Time
105 attribute of the batch job is after or equal to the
106 time represented by the date_time component of the
107 option-argument.
108 .gt. The time represented by value of the Execution_Time
110 attribute of the batch job is after the time repre‐
111 sented by the date_time component of the option-argu‐
112 ment.
113 .lt. The time represented by value of the Execution_Time
115 attribute of the batch job is before the time repre‐
116 sented by the date_time component of the option-argu‐
117 ment.
118 .le. The time represented by value of the Execution_Time
120 attribute of the batch job is before or equal to the
121 time represented by the date_time component of the
122 option-argument.
123 .ne. The time represented by value of the Execution_Time
125 attribute of the batch job is not equal to the time
126 represented by the date_time component of the option-
127 argument.
128 The qselect utility shall accept the defined character
130 strings for the op component of the option-argument.
131 −A account_string
133 Restrict selection to the batch jobs charging a specified
134 account.
135 The qselect utility shall select only batch jobs for which
137 the value of the Account_Name attribute of the batch job
138 matches the value of the account_string option-argument.
139 The syntax of the account_string option-argument is unspeci‐
141 fied.
142 −c [op]interval
144 Restrict selection to batch jobs within a range of checkpoint
145 intervals.
146 The qselect utility shall select only batch jobs for which
148 the value of the Checkpoint attribute relates to the value of
149 the interval component of the option-argument in the manner
150 indicated by the value of the op component of the option-
151 argument.
152 If the op component of the option-argument is omitted, the
154 qselect utility shall select batch jobs for which the value
155 of the Checkpoint attribute is equal to the value of the
156 interval component of the option-argument.
157 When comparing checkpoint intervals, the qselect utility
159 shall use the following definitions for the op component of
160 the option-argument:
161 .eq. The value of the Checkpoint attribute of the batch
163 job equals the value of the interval component of the
164 option-argument.
165 .ge. The value of the Checkpoint attribute of the batch
167 job is greater than or equal to the value of the
168 interval component option-argument.
169 .gt. The value of the Checkpoint attribute of the batch
171 job is greater than the value of the interval compo‐
172 nent option-argument.
173 .lt. The value of the Checkpoint attribute of the batch
175 job is less than the value of the interval component
176 option-argument.
177 .le. The value of the Checkpoint attribute of the batch
179 job is less than or equal to the value of the inter‐
180 val component option-argument.
181 .ne. The value of the Checkpoint attribute of the batch
183 job does not equal the value of the interval compo‐
184 nent option-argument.
185 The qselect utility shall accept the defined character
187 strings for the op component of the option-argument.
188 The ordering relationship for the values of the interval
190 option-argument is defined to be:
191 `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‐2008, 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,, ...]
250 When comparing resource values, the qselect utility shall use
252 the following definitions for the op component of the option-
253 argument:
254 .eq. The value of the resource of the same name in the
256 Resource_List attribute of the batch job equals the
257 value of the value component of the option-argument.
258 .ge. The value of the resource of the same name in the
260 Resource_List attribute of the batch job is greater
261 than or equal to the value of the value component of
262 the option-argument.
263 .gt. The value of the resource of the same name in the
265 Resource_List attribute of the batch job is greater
266 than the value of the value component of the option-
267 argument.
268 .lt. The value of the resource of the same name in the
270 Resource_List attribute of the batch job is less than
271 the value of the value component of the option-argu‐
272 ment.
273 .ne. The value of the resource of the same name in the
275 Resource_List attribute of the batch job does not
276 equal the value of the value component of the option-
277 argument.
278 .le. The value of the resource of the same name in the
280 Resource_List attribute of the batch job is less than
281 or equal to the value of the value component of the
282 option-argument.
283 When comparing the limit of a Resource_List attribute with
285 the value component of the option-argument, if the limit, the
286 value, or both are non-numeric, only equality or inequality
287 are valid comparisons.
288 The qselect utility shall select only batch jobs for which
290 the values of the resource_names listed in the resource_list
291 option-argument match the corresponding limits of the
292 Resource_List attribute of the batch job.
293 Limits of resource_names present in the Resource_List
295 attribute of the batch job that have no corresponding values
296 in the resource_list option-argument shall not be considered
297 when selecting batch jobs.
298 −N name Restrict selection to batch jobs with a specified name.
300 The qselect utility shall select only batch jobs for which
302 the value of the Job_Name attribute matches the value of the
303 name option-argument. The string specified in the name
304 option-argument shall be passed, uninterpreted, to the
305 server. This allows an implementation to match ``wildcard''
306 patterns against batch job names.
307 An implementation shall describe in the conformance document
309 the format it supports for matching against the Job_Name
310 attribute.
311 −p [op]priority
313 Restrict selection to batch jobs of the specified priority or
314 range of priorities.
315 The qselect utility shall select only batch jobs for which
317 the value of the Priority attribute of the batch job relates
318 to the value of the priority component of the option-argument
319 in the manner indicated by the value of the op component of
320 the option-argument.
321 If the op component of the option-argument is omitted, the
323 qselect utility shall select batch jobs for which the value
324 of the Priority attribute of the batch job is equal to the
325 value of the priority component of the option-argument.
326 When comparing priority values, the qselect utility shall use
328 the following definitions for the op component of the option-
329 argument:
330 .eq. The value of the Priority attribute of the batch job
332 equals the value of the priority component of the
333 option-argument.
334 .ge. The value of the Priority attribute of the batch job
336 is greater than or equal to the value of the priority
337 component option-argument.
338 .gt. The value of the Priority attribute of the batch job
340 is greater than the value of the priority component
341 option-argument.
342 .lt. The value of the Priority attribute of the batch job
344 is less than the value of the priority component
345 option-argument.
346 .lt. The value of the Priority attribute of the batch job
348 is less than or equal to the value of the priority
349 component option-argument.
350 .ne. The value of the Priority attribute of the batch job
352 does not equal the value of the priority component
353 option-argument.
354 −q destination
356 Restrict selection to the specified batch queue or server, or
357 both.
358 The qselect utility shall select only batch jobs that are
360 located at the destination indicated by the value of the des‐
361 tination option-argument.
362 The destination defines a batch queue, a server, or a batch
364 queue at a server.
365 The qselect utility shall accept an option-argument for the
367 −q option that conforms to the syntax for a destination. If
368 the −q option is not presented to the qselect utility, the
369 utility shall select batch jobs from all batch queues at the
370 default batch server.
371 If the option-argument describes only a batch queue, the qse‐
373 lect utility shall select only batch jobs from the batch
374 queue of the specified name at the default batch server. The
375 means by which qselect determines the default server is
376 implementation-defined.
377 If the option-argument describes only a batch server, the
379 qselect utility shall select batch jobs from all the batch
380 queues at that batch server.
381 If the option-argument describes both a batch queue and a
383 batch server, the qselect utility shall select only batch
384 jobs from the specified batch queue at the specified server.
385 −r y|n Restrict selection to batch jobs with the specified rerun‐
387 ability status.
388 The qselect utility shall select only batch jobs for which
390 the value of the Rerunable attribute of the batch job matches
391 the value of the option-argument.
392 The qselect utility shall accept a value for the option-argu‐
394 ment that consists of either the single character 'y' or the
395 single character 'n'. The character 'y' represents the value
396 TRUE, and the character 'n' represents the value FALSE.
397 −s states Restrict selection to batch jobs in the specified states.
399 The qselect utility shall accept an option-argument that con‐
401 sists of any combination of the characters 'e', 'q', 'r',
402 'w', 'h', and 't'.
403 Conforming applications shall not repeat any character in the
405 option-argument. The qselect utility shall permit the repeti‐
406 tion of characters in the option-argument, but shall not
407 assign additional meaning to repeated characters.
408 The qselect utility shall interpret the characters in the
410 states option-argument as follows:
411 e Represents the EXITING state.
413 q Represents the QUEUED state.
415 r Represents the RUNNING state.
417 t Represents the TRANSITING state.
419 h Represents the HELD state.
421 w Represents the WAITING state.
423 For each character in the states option-argument, the qselect
425 utility shall select batch jobs in the corresponding state.
426 −u user_list
428 Restrict selection to batch jobs owned by the specified user
429 names.
430 The qselect utility shall select only the batch jobs of those
432 users specified in the user_list option-argument.
433 The qselect utility shall accept a user_list option-argument
435 that conforms to the following syntax:
436 username[@host][,,username[@host],, ...]
438 The qselect utility shall accept only one user name that is
440 missing a corresponding host name. The qselect utility shall
441 accept only one user name per named host.
442
444 None.
445
447 Not used.
448
450 None.
451
453 The following environment variables shall affect the execution of qse‐
454 lect:
455 LANG Provide a default value for the internationalization vari‐
457 ables that are unset or null. (See the Base Definitions vol‐
458 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
459 ables the precedence of internationalization variables used
460 to determine the values of locale categories.)
461 LC_ALL If set to a non-empty string value, override the values of
463 all the other internationalization variables.
464 LC_CTYPE Determine the locale for the interpretation of sequences of
466 bytes of text data as characters (for example, single-byte as
467 opposed to multi-byte characters in arguments).
468 LC_MESSAGES
470 Determine the locale that should be used to affect the format
471 and contents of diagnostic messages written to standard
472 error.
473 LOGNAME Determine the login name of the user.
475 TZ Determine the timezone used to interpret the date-time
477 option-argument. If TZ is unset or null, an unspecified
478 default timezone shall be used.
479
481 Default.
482
484 The qselect utility shall write zero or more batch job_identifiers to
485 standard output.
486 The qselect utility shall separate the batch job_identifiers written to
488 standard output by white space.
489 The qselect utility shall write batch job_identifiers in the following
491 format:
492 sequence_number.server_name@server
494
496 The standard error shall be used only for diagnostic messages.
497
499 None.
500
502 None.
503
505 The following exit values shall be returned:
506 0 Successful completion.
508 >0 An error occurred.
510
512 Default.
513 The following sections are informative.
515
517 None.
518
520 The following example shows how a user might use the qselect utility in
521 conjunction with the qdel utility to delete all of his or her jobs in
522 the queued state without affecting any jobs that are already running:
523 qdel $(qselect −s q)
525 or:
527 qselect −s q || xargs qdel
529
531 The qselect utility allows users to acquire a list of job identifiers
532 that match user-specified selection criteria. The list of identifiers
533 returned by the qselect utility conforms to the syntax of the batch job
534 identifier list processed by a utility such as qmove, qdel, and qrls.
535 The qselect utility is thus a powerful tool for causing another batch
536 system utility to act upon a set of jobs that match a list of selection
537 criteria.
538 The options of the qselect utility let the user apply a number of use‐
540 ful filters for selecting jobs. Each option further restricts the
541 selection of jobs. Many of the selection options allow the specifica‐
542 tion of a relational operator. The FORTRAN-like syntax of the operator—
543 that is, ".lt."—was chosen rather than the C-like "<=" meta-characters.
544 The −a option allows users to restrict the selected jobs to those that
546 have been submitted (or altered) to wait until a particular time. The
547 time period is determined by the argument of this option, which
548 includes both a time and an operator—it is thus possible to select jobs
549 waiting until a specific time, jobs waiting until after a certain time,
550 or those waiting for a time before the specified time.
551 The −A option allows users to restrict the selected jobs to those that
553 have been submitted (or altered) to charge a particular account.
554 The −c option allows users to restrict the selected jobs to those whose
556 checkpointing interval falls within the specified range.
557 The −l option allows users to select those jobs whose resource limits
559 fall within the range indicated by the value of the option. For exam‐
560 ple, a user could select those jobs for which the CPU time limit is
561 greater than two hours.
562 The −N option allows users to select jobs by job name. For instance,
564 all the parts of a task that have been divided in parallel jobs might
565 be given the same name, and thus manipulated as a group by means of
566 this option.
567 The −q option allows users to select jobs in a specified queue.
569 The −r option allows users to select only those jobs with a specified
571 rerun criteria. For instance, a user might select only those jobs that
572 can be rerun for use with the qrerun utility.
573 The −s option allows users to select only those jobs that are in a cer‐
575 tain state.
576 The −u option allows users to select jobs that have been submitted to
578 execute under a particular account.
579 The selection criteria provided by the options of the qselect utility
581 allow users to select jobs based on all the appropriate attributes that
582 can be assigned to jobs by the qsub utility.
583 Historically, the qselect utility has not been a part of existing prac‐
585 tice; it is an improvement that has been introduced in this volume of
586 POSIX.1‐2008.
587
589 The qselect utility may be removed in a future version.
590
592 Chapter 3, Batch Environment Services, qdel, qrerun, qrls, qselect,
593 qsub, touch
594 The Base Definitions volume of POSIX.1‐2008, Section 6.1, Portable
596 Character Set, Chapter 8, Environment Variables, Section 12.2, Utility
597 Syntax Guidelines
598
600 Portions of this text are reprinted and reproduced in electronic form
601 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
602 -- Portable Operating System Interface (POSIX), The Open Group Base
603 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
604 cal and Electronics Engineers, Inc and The Open Group. (This is
605 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
606 event of any discrepancy between this version and the original IEEE and
607 The Open Group Standard, the original IEEE and The Open Group Standard
608 is the referee document. The original Standard can be obtained online
609 at http://www.unix.org/online.html .
610 Any typographical or formatting errors that appear in this page are
612 most likely to have been introduced during the conversion of the source
613 files to man page format. To report such errors, see https://www.ker‐
614 nel.org/doc/man-pages/reporting_bugs.html .
615IEEE/The Open Group 2013 QSELECT(1P)