1QSELECT(P) POSIX Programmer's Manual QSELECT(P)
2
3
4
6 qselect - select batch jobs
7
9 qselect [-a [op]date_time][-A account_string][-c [op]interval]
10 [-h hold_list][-l resource_list][-N name][-p [op]priority]
11 [-q destination][-r y|n][-s states][-u user_list]
12
14 To select a set of batch jobs is to return the batch job_identifiers
15 for each batch job that meets a list of selection criteria. A set of
16 batch jobs is selected by a request to a batch server. The qselect
17 utility is a user-accessible batch client that requests the selection
18 of batch jobs.
19
20 Upon successful completion, the qselect utility shall have returned a
21 list of zero or more batch job_identifiers that meet the criteria spec‐
22 ified by the options and option-arguments presented to the utility.
23
24 The qselect utility shall select batch jobs by sending a Select Jobs
25 Request to a batch server. The qselect utility shall not exit until the
26 server replies to each request generated.
27
28 For each option presented to the qselect utility, the utility shall
29 restrict the set of selected batch jobs as described in the OPTIONS
30 section.
31
32 The qselect utility shall not restrict selection of batch jobs except
33 by authorization and as required by the options presented to the util‐
34 ity.
35
36 When an option is specified with a mandatory or optional op component
37 to the option-argument, then op shall specify a relation between the
38 value of a certain batch job attribute and the value component of the
39 option-argument. If an op is allowable on an option, then the descrip‐
40 tion of the option letter indicates the op as either mandatory or
41 optional. Acceptable strings for the op component, and the relation the
42 string indicates, are shown in the following list:
43
44 .eq. The value represented by the attribute of the batch job is equal
45 to the value represented by the option-argument.
46
47 .ge. The value represented by the attribute of the batch job is
48 greater than or equal to the value represented by the option-
49 argument.
50
51 .gt. The value represented by the attribute of the batch job is
52 greater than the value represented by the option-argument.
53
54 .lt. The value represented by the attribute of the batch job is less
55 than the value represented by the option-argument.
56
57 .le. The value represented by the attribute of the batch job is less
58 than or equal to the value represented by the option-argument.
59
60 .ne. The value represented by the attribute of the batch job is not
61 equal to the value represented by the option-argument.
62
63
65 The qselect utility shall conform to the Base Definitions volume of
66 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
67
68 The following options shall be supported by the implementation:
69
70 -a [op]date_time
71
72 Restrict selection to a specific time, or a range of times.
73
74 The qselect utility shall select only batch jobs for which the value of
75 the Execution_Time attribute is related to the Epoch equivalent of the
76 local time expressed by the value of the date_time component of the
77 option-argument in the manner indicated by the value of the op compo‐
78 nent of the option-argument.
79
80 The qselect utility shall accept a date_time component of the option-
81 argument that conforms to the syntax of the time operand of the touch
82 utility.
83
84 If the op component of the option-argument is not presented to the qse‐
85 lect utility, the utility shall select batch jobs for which the Execu‐
86 tion_Time attribute is equal to the date_time component of the option-
87 argument.
88
89 When comparing times, the qselect utility shall use the following defi‐
90 nitions for the op component of the option-argument:
91
92 .eq.
93 The time represented by value of the Execution_Time attribute of
94 the batch job is equal to the time represented by the date_time
95 component of the option-argument.
96
97 .ge.
98 The time represented by value of the Execution_Time attribute of
99 the batch job is after or equal to the time represented by the
100 date_time component of the option-argument.
101
102 .gt.
103 The time represented by value of the Execution_Time attribute of
104 the batch job is after the time represented by the date_time
105 component of the option-argument.
106
107 .lt.
108 The time represented by value of the Execution_Time attribute of
109 the batch job is before the time represented by the date_time
110 component of the option-argument.
111
112 .le.
113 The time represented by value of the Execution_Time attribute of
114 the batch job is before or equal to the time represented by the
115 date_time component of the option-argument.
116
117 .ne.
118 The time represented by value of the Execution_Time attribute of
119 the batch job is not equal to the time represented by the
120 date_time component of the option-argument.
121
122
123 The qselect utility shall accept the defined character strings for the
124 op component of the option-argument.
125
126 -A account_string
127
128 Restrict selection to the batch jobs charging a specified
129 account.
130
131 The qselect utility shall select only batch jobs for which the value of
132 the Account_Name attribute of the batch job matchs the value of the
133 account_string option-argument.
134
135 The syntax of the account_string option-argument is unspecified.
136
137 -c [op]interval
138
139 Restrict selection to batch jobs within a range of checkpoint
140 intervals.
141
142 The qselect utility shall select only batch jobs for which the value of
143 the Checkpoint attribute relates to the value of the interval component
144 of the option-argument in the manner indicated by the value of the op
145 component of the option-argument.
146
147 If the op component of the option-argument is omitted, the qselect
148 utility shall select batch jobs for which the value of the Checkpoint
149 attribute is equal to the value of the interval component of the
150 option-argument.
151
152 When comparing checkpoint intervals, the qselect utility shall use the
153 following definitions for the op component of the option-argument:
154
155 .eq.
156 The value of the Checkpoint attribute of the batch job equals
157 the value of the interval component of the option-argument.
158
159 .ge.
160 The value of the Checkpoint attribute of the batch job is
161 greater than or equal to the value of the interval component
162 option-argument.
163
164 .gt.
165 The value of the Checkpoint attribute of the batch job is
166 greater than the value of the interval component option-argu‐
167 ment.
168
169 .lt.
170 The value of the Checkpoint attribute of the batch job is less
171 than the value of the interval component option-argument.
172
173 .le.
174 The value of the Checkpoint attribute of the batch job is less
175 than or equal to the value of the interval component option-
176 argument.
177
178 .ne.
179 The value of the Checkpoint attribute of the batch job does not
180 equal the value of the interval component option-argument.
181
182
183 The qselect utility shall accept the defined character strings for the
184 op component of the option-argument.
185
186 The ordering relationship for the values of the interval option-argu‐
187 ment is defined to be:
188
189
190 `n' .gt. `s' .gt. `c=minutes' .ge. `c'
191 When comparing Checkpoint attributes with an interval having the value
192 of the single character 'u' , only equality or inequality are valid
193 comparisons.
194
195 -h hold_list
196 Restrict selection to batch jobs that have a specific type of
197 hold.
198
199 The qselect utility shall select only batch jobs for which the value of
200 the Hold_Types attribute matches the value of the hold_list option-
201 argument.
202
203 The qselect -h option shall accept a value for the hold_list option-
204 argument that is a string of alphanumeric characters in the portable
205 character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
206 Section 6.1, Portable Character Set).
207
208 The qselect utility shall accept a value for the hold_list option-argu‐
209 ment that is a string of one or more of the characters 'u' , 's' , or
210 'o' , or the single character 'n' .
211
212 Each unique character in the hold_list option-argument of the qselect
213 utility is defined as follows, each representing a different hold type:
214
215 u
216 USER
217
218 s
219 SYSTEM
220
221 o
222 OPERATOR
223
224
225 If any of these characters are duplicated in the hold_list option-argu‐
226 ment, the duplicates shall be ignored.
227
228 The qselect utility shall consider it an error if any hold type other
229 than 'n' is combined with hold type 'n' .
230
231 Strictly conforming applications shall not repeat any of the characters
232 'u' , 's' , 'o' , or 'n' within the hold_list option-argument. The qse‐
233 lect utility shall permit the repetition of characters, but shall not
234 assign additional meaning to the repeated characters.
235
236 An implementation may define other hold types. The conformance document
237 for an implementation shall describe any additional hold types, how
238 they are specified, their internal behavior, and how they affect the
239 behavior of the utility.
240
241 -l resource_list
242
243 Restrict selection to batch jobs with specified resource limits
244 and attributes.
245
246 The qselect utility shall accept a resource_list option-argument with
247 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 the fol‐
253 lowing definitions for the op component of the option-argument:
254
255 .eq.
256 The value of the resource of the same name in the Resource_List
257 attribute of the batch job equals the value of the value compo‐
258 nent of the option-argument.
259
260 .ge.
261 The value of the resource of the same name in the Resource_List
262 attribute of the batch job is greater than or equal to the value
263 of the value component of the option-argument.
264
265 .gt.
266 The value of the resource of the same name in the Resource_List
267 attribute of the batch job is greater than the value of the
268 value component of the option-argument.
269
270 .lt.
271 The value of the resource of the same name in the Resource_List
272 attribute of the batch job is less than the value of the value
273 component of the option-argument.
274
275 .ne.
276 The value of the resource of the same name in the Resource_List
277 attribute of the batch job does not equal the value of the value
278 component of the option-argument.
279
280 .le.
281 The value of the resource of the same name in the Resource_List
282 attribute of the batch job is less than or equal to the value of
283 the value component of the option-argument.
284
285
286 When comparing the limit of a Resource_List attribute with the value
287 component of the option-argument, if the limit, the value, or both are
288 non-numeric, only equality or inequality are valid comparisons.
289
290 The qselect utility shall select only batch jobs for which the values
291 of the resource_names listed in the resource_list option-argument match
292 the corresponding limits of the Resource_List attribute of the batch
293 job.
294
295 Limits of resource_names present in the Resource_List attribute of the
296 batch job that have no corresponding values in the resource_list
297 option-argument shall not be considered when selecting batch jobs.
298
299 -N name
300 Restrict selection to batch jobs with a specified name.
301
302 The qselect utility shall select only batch jobs for which the value of
303 the Job_Name attribute matches the value of the name option-argument.
304 The string specified in the name option-argument shall be passed, unin‐
305 terpreted, to the server. This allows an implementation to match "wild‐
306 card" patterns against batch job names.
307
308 An implementation shall describe in the conformance document the format
309 it supports for matching against the Job_Name attribute.
310
311 -p [op]priority
312
313 Restrict selection to batch jobs of the specified priority or
314 range of priorities.
315
316 The qselect utility shall select only batch jobs for which the value of
317 the Priority attribute of the batch job relates to the value of the
318 priority component of the option-argument in the manner indicated by
319 the value of the op component of the option-argument.
320
321 If the op component of the option-argument is omitted, the qselect
322 utility shall select batch jobs for which the value of the Priority
323 attribute of the batch job is equal to the value of the priority compo‐
324 nent of the option-argument.
325
326 When comparing priority values, the qselect utility shall use the fol‐
327 lowing definitions for the op component of the option-argument:
328
329 .eq.
330 The value of the Priority attribute of the batch job equals the
331 value of the priority component of the option-argument.
332
333 .ge.
334 The value of the Priority attribute of the batch job is greater
335 than or equal to the value of the priority component option-
336 argument.
337
338 .gt.
339 The value of the Priority attribute of the batch job is greater
340 than the value of the priority component option-argument.
341
342 .lt.
343 The value of the Priority attribute of the batch job is less
344 than the value of the priority component option-argument.
345
346 .lt.
347 The value of the Priority attribute of the batch job is less
348 than or equal to the value of the priority component option-
349 argument.
350
351 .ne.
352 The value of the Priority attribute of the batch job does not
353 equal the value of the priority component option-argument.
354
355
356 -q destination
357
358 Restrict selection to the specified batch queue or server, or
359 both.
360
361 The qselect utility shall select only batch jobs that are located at
362 the destination indicated by the value of the destination option-argu‐
363 ment.
364
365 The destination defines a batch queue, a server, or a batch queue at a
366 server.
367
368 The qselect utility shall accept an option-argument for the -q option
369 that conforms to the syntax for a destination. If the -q option is not
370 presented to the qselect utility, the utility shall select batch jobs
371 from all batch queues at the default batch server.
372
373 If the option-argument describes only a batch queue, the qselect util‐
374 ity shall select only batch jobs from the batch queue of the specified
375 name at the default batch server. The means by which qselect determines
376 the default server is implementation-defined.
377
378 If the option-argument describes only a batch server, the qselect util‐
379 ity shall select batch jobs from all the batch queues at that batch
380 server.
381
382 If the option-argument describes both a batch queue and a batch server,
383 the qselect utility shall select only batch jobs from the specified
384 batch queue at the specified server.
385
386 -r y|n
387 Restrict selection to batch jobs with the specified rerunability
388 status.
389
390 The qselect utility shall select only batch jobs for which the value of
391 the Rerunable attribute of the batch job matches the value of the
392 option-argument.
393
394 The qselect utility shall accept a value for the option-argument that
395 consists of either the single character 'y' or the single character 'n'
396 . The character 'y' represents the value TRUE, and the character 'n'
397 represents the value FALSE.
398
399 -s states
400 Restrict selection to batch jobs in the specified states.
401
402 The qselect utility shall accept an option-argument that consists of
403 any combination of the characters 'e' , 'q' , 'r' , 'w' , 'h' , and 't'
404 .
405
406 Conforming applications shall not repeat any character in the option-
407 argument. The qselect utility shall permit the repetition of charac‐
408 ters in the option-argument, but shall not assign additional meaning to
409 repeated characters.
410
411 The qselect utility shall interpret the characters in the states
412 option-argument as follows:
413
414 e
415 Represents the EXITING state.
416
417 q
418 Represents the QUEUED state.
419
420 r
421 Represents the RUNNING state.
422
423 t
424 Represents the TRANSITING state.
425
426 h
427 Represents the HELD state.
428
429 w
430 Represents the WAITING state.
431
432
433 For each character in the states option-argument, the qselect utility
434 shall select batch jobs in the corresponding state.
435
436 -u user_list
437 Restrict selection to batch jobs owned by the specified user
438 names.
439
440 The qselect utility shall select only the batch jobs of those users
441 specified in the user_list option-argument.
442
443 The qselect utility shall accept a user_list option-argument that con‐
444 forms to the following syntax:
445
446
447 username[@host][,,username[@host],, ...]
448
449 The qselect utility shall accept only one user name that is missing a
450 corresponding host name. The qselect utility shall accept only one user
451 name per named host.
452
453
455 None.
456
458 Not used.
459
461 None.
462
464 The following environment variables shall affect the execution of qse‐
465 lect:
466
467 LANG Provide a default value for the internationalization variables
468 that are unset or null. (See the Base Definitions volume of
469 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
470 ables for the precedence of internationalization variables used
471 to determine the values of locale categories.)
472
473 LC_ALL If set to a non-empty string value, override the values of all
474 the other internationalization variables.
475
476 LC_CTYPE
477 Determine the locale for the interpretation of sequences of
478 bytes of text data as characters (for example, single-byte as
479 opposed to multi-byte characters in arguments).
480
481 LC_MESSAGES
482 Determine the locale that should be used to affect the format
483 and contents of diagnostic messages written to standard error.
484
485 LOGNAME
486 Determine the login name of the user.
487
488 TZ Determine the timezone used to interpret the date-time option-
489 argument. If TZ is unset or null, an unspecified default time‐
490 zone shall be used.
491
492
494 Default.
495
497 The qselect utility shall write zero or more batch job_identifiers to
498 standard output.
499
500 The qselect utility shall separate the batch job_identifiers written to
501 standard output by white space.
502
503 The qselect utility shall write batch job_identifiers in the following
504 format:
505
506
507 sequence_number.server_name@server
508
510 The standard error shall be used only for diagnostic messages.
511
513 None.
514
516 None.
517
519 The following exit values shall be returned:
520
521 0 Successful completion.
522
523 >0 An error occurred.
524
525
527 Default.
528
529 The following sections are informative.
530
532 None.
533
535 The following example shows how a user might use the qselect utility in
536 conjunction with the qdel utility to delete all of his or her jobs in
537 the queued state without affecting any jobs that are already running:
538
539
540 qdel $(qselect -s q)
541
542 or:
543
544
545 qselect -s q || xargs qdel
546
548 The qselect utility allows users to acquire a list of job identifiers
549 that match user-specified selection criteria. The list of identifiers
550 returned by the qselect utility conforms to the syntax of the batch job
551 identifier list processed by a utility such as qmove, qdel, and qrls.
552 The qselect utility is thus a powerful tool for causing another batch
553 system utility to act upon a set of jobs that match a list of selection
554 criteria.
555
556 The options of the qselect utility let the user apply a number of use‐
557 ful filters for selecting jobs. Each option further restricts the
558 selection of jobs. Many of the selection options allow the specifica‐
559 tion of a relational operator. The FORTRAN-like syntax of the operator-
560 that is, ".lt." - was chosen rather than the C-like "<=" meta-charac‐
561 ters.
562
563 The -a option allows users to restrict the selected jobs to those that
564 have been submitted (or altered) to wait until a particular time. The
565 time period is determined by the argument of this option, which
566 includes both a time and an operator-it is thus possible to select jobs
567 waiting until a specific time, jobs waiting until after a certain time,
568 or those waiting for a time before the specified time.
569
570 The -A option allows users to restrict the selected jobs to those that
571 have been submitted (or altered) to charge a particular account.
572
573 The -c option allows users to restrict the selected jobs to those whose
574 checkpointing interval falls within the specified range.
575
576 The -l option allows users to select those jobs whose resource limits
577 fall within the range indicated by the value of the option. For exam‐
578 ple, a user could select those jobs for which the CPU time limit is
579 greater than two hours.
580
581 The -N option allows users to select jobs by job name. For instance,
582 all the parts of a task that have been divided in parallel jobs might
583 be given the same name, and thus manipulated as a group by means of
584 this option.
585
586 The -q option allows users to select jobs in a specified queue.
587
588 The -r option allows users to select only those jobs with a specified
589 rerun criteria. For instance, a user might select only those jobs that
590 can be rerun for use with the qrerun utility.
591
592 The -s option allows users to select only those jobs that are in a cer‐
593 tain state.
594
595 The -u option allows users to select jobs that have been submitted to
596 execute under a particular account.
597
598 The selection criteria provided by the options of the qselect utility
599 allow users to select jobs based on all the appropriate attributes that
600 can be assigned to jobs by the qsub utility.
601
602 Historically, the qselect utility has not been a part of existing prac‐
603 tice; it is an improvement that has been introduced in this volume of
604 IEEE Std 1003.1-2001.
605
607 None.
608
610 qdel , qrerun , qrls , qselect , qsub , touch , Batch Environment Ser‐
611 vices
612
614 Portions of this text are reprinted and reproduced in electronic form
615 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
616 -- Portable Operating System Interface (POSIX), The Open Group Base
617 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
618 Electrical and Electronics Engineers, Inc and The Open Group. In the
619 event of any discrepancy between this version and the original IEEE and
620 The Open Group Standard, the original IEEE and The Open Group Standard
621 is the referee document. The original Standard can be obtained online
622 at http://www.opengroup.org/unix/online.html .
623
624
625
626IEEE/The Open Group 2003 QSELECT(P)