logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

qsub.1p (38374B)


  1. '\" et
  2. .TH QSUB "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. qsub
  12. \(em submit a script
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. qsub \fB[\fR-a \fIdate_time\fB] [\fR-A \fIaccount_string\fB] [\fR-c \fIinterval\fB]
  17. [\fR-C \fIdirective_prefix\fB] [\fR-e \fIpath_name\fB] [\fR-h\fB] [\fR-j \fIjoin_list\fB]
  18. [\fR-k \fIkeep_list\fB] [\fR-m \fImail_options\fB] [\fR-M \fImail_list\fB] [\fR-N \fIname\fB]
  19. [\fR-o \fIpath_name\fB] [\fR-p \fIpriority\fB] [\fR-q \fIdestination\fB] [\fR-r \fIy\fR|\fIn\fB]
  20. [\fR-S \fIpath_name_list\fB] [\fR-u \fIuser_list\fB] [\fR-v \fIvariable_list\fB] [\fR-V\fB]
  21. [\fR-z\fB] [\fIscript\fB]\fR
  22. .fi
  23. .SH DESCRIPTION
  24. To submit a script is to create a batch job that executes the script. A
  25. script is submitted by a request to a batch server. The
  26. .IR qsub
  27. utility is a user-accessible batch client that submits a script.
  28. .P
  29. Upon successful completion, the
  30. .IR qsub
  31. utility shall have created a batch job that will execute the submitted
  32. script.
  33. .P
  34. The
  35. .IR qsub
  36. utility shall submit a script by sending a
  37. .IR "Queue Job Request"
  38. to a batch server.
  39. .P
  40. The
  41. .IR qsub
  42. utility shall place the value of the following environment variables in
  43. the
  44. .IR Variable_List
  45. attribute of the batch job:
  46. .IR HOME ,
  47. .IR LANG ,
  48. .IR LOGNAME ,
  49. .IR PATH ,
  50. .IR MAIL ,
  51. .IR SHELL ,
  52. and
  53. .IR TZ .
  54. The name of the environment variable shall be the current name prefixed
  55. with the string PBS_O_.
  56. .TP 10
  57. .BR Note:
  58. If the current value of the
  59. .IR HOME
  60. variable in the environment space of the
  61. .IR qsub
  62. utility is
  63. .BR /aa/bb/cc ,
  64. then
  65. .IR qsub
  66. shall place
  67. .IR PBS_O_HOME =\c
  68. .BR /aa/bb/cc
  69. in the
  70. .IR Variable_List
  71. attribute of the batch job.
  72. .P
  73. .P
  74. In addition to the variables described above, the
  75. .IR qsub
  76. utility shall add the following variables with the indicated values to
  77. the variable list:
  78. .IP "\fIPBS_O_WORKDIR\fP" 14
  79. The absolute path of the current working directory of the
  80. .IR qsub
  81. utility process.
  82. .IP "\fIPBS_O_HOST\fP" 14
  83. The name of the host on which the
  84. .IR qsub
  85. utility is running.
  86. .SH OPTIONS
  87. The
  88. .IR qsub
  89. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  90. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  91. .P
  92. The following options shall be supported by the implementation:
  93. .IP "\fB\-a\ \fIdate_time\fR" 10
  94. Define the time at which a batch job becomes eligible for execution.
  95. .RS 10
  96. .P
  97. The
  98. .IR qsub
  99. utility shall accept an option-argument that conforms to the syntax of
  100. the
  101. .IR time
  102. operand of the
  103. .IR touch
  104. utility.
  105. .br
  106. .sp
  107. .ce 1
  108. \fBTable 4-19: Environment Variable Values (Utilities)\fR
  109. .TS
  110. center box tab(!);
  111. cB | cB
  112. lI | lI.
  113. Variable Name!Value at qsub Time
  114. _
  115. PBS_O_HOME!HOME
  116. PBS_O_HOST!\fRClient host name\fP
  117. PBS_O_LANG!LANG
  118. PBS_O_LOGNAME!LOGNAME
  119. PBS_O_PATH!PATH
  120. PBS_O_MAIL!MAIL
  121. PBS_O_SHELL!SHELL
  122. PBS_O_TZ!TZ
  123. PBS_O_WORKDIR!\fRCurrent working directory\fP
  124. .TE
  125. .TP 10
  126. .BR Note:
  127. The server that initiates execution of the batch job will add other
  128. variables to the batch job's environment; see
  129. .IR "Section 3.2.2.1" ", " "Batch Job Execution".
  130. .P
  131. .P
  132. The
  133. .IR qsub
  134. utility shall set the
  135. .IR Execution_Time
  136. attribute of the batch job to the number of seconds since the Epoch
  137. that is equivalent to the local time expressed by the value of the
  138. .IR date_time
  139. option-argument. The Epoch is defined in the Base Definitions volume of POSIX.1\(hy2017,
  140. .IR "Section 3.150" ", " "Epoch".
  141. .P
  142. If the
  143. .BR \-a
  144. option is not presented to the
  145. .IR qsub
  146. utility, the utility shall set the
  147. .IR Execution_Time
  148. attribute of the batch job to a time (number of seconds since the
  149. Epoch) that is earlier than the time at which the utility exits.
  150. .RE
  151. .IP "\fB\-A\ \fIaccount_string\fR" 10
  152. .br
  153. Define the account to which the resource consumption of the batch job
  154. should be charged.
  155. .RS 10
  156. .P
  157. The syntax of the
  158. .IR account_string
  159. option-argument is unspecified.
  160. .P
  161. The
  162. .IR qsub
  163. utility shall set the
  164. .IR Account_Name
  165. attribute of the batch job to the value of the
  166. .IR account_string
  167. option-argument.
  168. .P
  169. If the
  170. .BR \-A
  171. option is not presented to the
  172. .IR qsub
  173. utility, the utility shall omit the
  174. .IR Account_Name
  175. attribute from the attributes of the batch job.
  176. .RE
  177. .IP "\fB\-c\ \fIinterval\fR" 10
  178. Define whether the batch job should be checkpointed, and if so, how
  179. often.
  180. .RS 10
  181. .P
  182. The
  183. .IR qsub
  184. utility shall accept a value for the interval option-argument that is
  185. one of the following:
  186. .IP "\fRn\fR" 10
  187. No checkpointing shall be performed on the batch job
  188. (NO_CHECKPOINT).
  189. .IP "\fRs\fR" 10
  190. Checkpointing shall be performed only when the batch server is shut
  191. down (CHECKPOINT_AT_SHUTDOWN).
  192. .IP "\fRc\fR" 10
  193. Automatic periodic checkpointing shall be performed at the
  194. .IR Minimum_Cpu_Interval
  195. attribute of the batch queue, in units of CPU minutes
  196. (CHECKPOINT_AT_MIN_CPU_INTERVAL).
  197. .IP "\fRc\fR=\fIminutes\fR" 10
  198. Automatic periodic checkpointing shall be performed every
  199. .IR minutes
  200. of CPU time, or every
  201. .IR Minimum_Cpu_Interval
  202. minutes, whichever is greater. The
  203. .IR minutes
  204. argument shall conform to the syntax for unsigned integers and shall be
  205. greater than zero.
  206. .P
  207. The
  208. .IR qsub
  209. utility shall set the
  210. .IR Checkpoint
  211. attribute of the batch job to the value of the
  212. .IR interval
  213. option-argument.
  214. .P
  215. If the
  216. .BR \-c
  217. option is not presented to the
  218. .IR qsub
  219. utility, the utility shall set the
  220. .IR Checkpoint
  221. attribute of the batch job to the single character
  222. .BR 'u'
  223. (CHECKPOINT_UNSPECIFIED).
  224. .RE
  225. .IP "\fB\-C\ \fIdirective_prefix\fR" 10
  226. .br
  227. Define the prefix that declares a directive to the
  228. .IR qsub
  229. utility within the script.
  230. .RS 10
  231. .P
  232. The
  233. .IR directive_prefix
  234. is not a batch job attribute; it affects the behavior of the
  235. .IR qsub
  236. utility.
  237. .P
  238. If the
  239. .BR \-C
  240. option is presented to the
  241. .IR qsub
  242. utility, and the value of the
  243. .IR directive_prefix
  244. option-argument is the null string, the utility shall not scan the
  245. script file for directives. If the
  246. .BR \-C
  247. option is not presented to the
  248. .IR qsub
  249. utility, then the value of the
  250. .IR PBS_DPREFIX
  251. environment variable is used. If the environment variable is not
  252. defined, then #PBS encoded in the portable character set is the
  253. default.
  254. .RE
  255. .IP "\fB\-e\ \fIpath_name\fR" 10
  256. .br
  257. Define the path to be used for the standard error stream of the batch
  258. job.
  259. .RS 10
  260. .P
  261. The
  262. .IR qsub
  263. utility shall accept a
  264. .IR path_name
  265. option-argument which can be preceded by a host name element of the
  266. form
  267. .IR hostname :.
  268. .P
  269. If the
  270. .IR path_name
  271. option-argument constitutes an absolute pathname, the
  272. .IR qsub
  273. utility shall set the
  274. .IR Error_Path
  275. attribute of the batch job to the value of the
  276. .IR path_name
  277. option-argument.
  278. .P
  279. If the
  280. .IR path_name
  281. option-argument constitutes a relative pathname and no host name
  282. element is specified, the
  283. .IR qsub
  284. utility shall set the
  285. .IR Error_Path
  286. attribute of the batch job to the value of the absolute pathname
  287. derived by expanding the
  288. .IR path_name
  289. option-argument relative to the current directory of the process
  290. executing
  291. .IR qsub .
  292. .P
  293. If the
  294. .IR path_name
  295. option-argument constitutes a relative pathname and a host name
  296. element is specified, the
  297. .IR qsub
  298. utility shall set the
  299. .IR Error_Path
  300. attribute of the batch job to the value of the
  301. .IR path_name
  302. option-argument without expansion. The host name element shall be
  303. included.
  304. .P
  305. If the
  306. .IR path_name
  307. option-argument does not include a host name element, the
  308. .IR qsub
  309. utility shall prefix the pathname with
  310. .IR hostname :,
  311. where
  312. .IR hostname
  313. is the name of the host upon which the
  314. .IR qsub
  315. utility is being executed.
  316. .P
  317. If the
  318. .BR \-e
  319. option is not presented to the
  320. .IR qsub
  321. utility, the utility shall set the
  322. .IR Error_Path
  323. attribute of the batch job to the host name and path of the current
  324. directory of the submitting process and the default filename.
  325. .P
  326. The default filename for standard error has the following format:
  327. .sp
  328. .RS 4
  329. .nf
  330. \fIjob_name\fR.e\fIsequence_number\fR
  331. .fi
  332. .P
  333. .RE
  334. .RE
  335. .IP "\fB\-h\fR" 10
  336. Specify that a USER hold is applied to the batch job.
  337. .RS 10
  338. .P
  339. The
  340. .IR qsub
  341. utility shall set the value of the
  342. .IR Hold_Types
  343. attribute of the batch job to the value USER.
  344. .P
  345. If the
  346. .BR \-h
  347. option is not presented to the
  348. .IR qsub
  349. utility, the utility shall set the
  350. .IR Hold_Types
  351. attribute of the batch job to the value NO_HOLD.
  352. .RE
  353. .IP "\fB\-j\ \fIjoin_list\fR" 10
  354. Define which streams of the batch job are to be merged. The
  355. .IR qsub
  356. .BR \-j
  357. option shall accept a value for the
  358. .IR join_list
  359. option-argument that is a string of alphanumeric characters in the
  360. portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
  361. .IR "Section 6.1" ", " "Portable Character Set").
  362. .RS 10
  363. .P
  364. The
  365. .IR qsub
  366. utility shall accept a
  367. .IR join_list
  368. option-argument that consists of one or more of the characters
  369. .BR 'e'
  370. and
  371. .BR 'o' ,
  372. or the single character
  373. .BR 'n' .
  374. .P
  375. All of the other batch job output streams specified will be merged into
  376. the output stream represented by the character listed first in the
  377. .IR join_list
  378. option-argument.
  379. .P
  380. For each unique character in the
  381. .IR join_list
  382. option-argument, the
  383. .IR qsub
  384. utility shall add a value to the
  385. .IR Join_Path
  386. attribute of the batch job as follows, each representing a different
  387. batch job stream to join:
  388. .IP "\fRe\fR" 6
  389. The standard error of the batch job (JOIN_STD_ERROR).
  390. .IP "\fRo\fR" 6
  391. The standard output of the batch job (JOIN_STD_OUTPUT).
  392. .P
  393. An existing
  394. .IR Join_Path
  395. attribute can be cleared by the following join type:
  396. .IP "\fRn\fR" 6
  397. NO_JOIN
  398. .P
  399. If
  400. .BR 'n'
  401. is specified, then no files are joined. The
  402. .IR qsub
  403. utility shall consider it an error if any join type other than
  404. .BR 'n'
  405. is combined with join type
  406. .BR 'n' .
  407. .P
  408. Strictly conforming applications shall not repeat any of the characters
  409. .BR 'e' ,
  410. .BR 'o' ,
  411. or
  412. .BR 'n'
  413. within the
  414. .IR join_list
  415. option-argument. The
  416. .IR qsub
  417. utility shall permit the repetition of characters, but shall not assign
  418. additional meaning to the repeated characters.
  419. .P
  420. An implementation may define other join types. The conformance document
  421. for an implementation shall describe any additional batch job streams,
  422. how they are specified, their internal behavior, and how they affect
  423. the behavior of the utility.
  424. .P
  425. If the
  426. .BR \-j
  427. option is not presented to the
  428. .IR qsub
  429. utility, the utility shall set the value of the
  430. .IR Join_Path
  431. attribute of the batch job to NO_JOIN.
  432. .RE
  433. .IP "\fB\-k\ \fIkeep_list\fR" 10
  434. Define which output of the batch job to retain on the execution host.
  435. .RS 10
  436. .P
  437. The
  438. .IR qsub
  439. .BR \-k
  440. option shall accept a value for the
  441. .IR keep_list
  442. option-argument that is a string of alphanumeric characters in the
  443. portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
  444. .IR "Section 6.1" ", " "Portable Character Set").
  445. .P
  446. The
  447. .IR qsub
  448. utility shall accept a
  449. .IR keep_list
  450. option-argument that consists of one or more of the characters
  451. .BR 'e'
  452. and
  453. .BR 'o' ,
  454. or the single character
  455. .BR 'n' .
  456. .P
  457. For each unique character in the
  458. .IR keep_list
  459. option-argument, the
  460. .IR qsub
  461. utility shall add a value to the
  462. .IR Keep_Files
  463. attribute of the batch job as follows, each representing a different
  464. batch job stream to keep:
  465. .IP "\fRe\fR" 6
  466. The standard error of the batch job (KEEP_STD_ERROR).
  467. .IP "\fRo\fR" 6
  468. The standard output of the batch job (KEEP_STD_OUTPUT).
  469. .P
  470. If both
  471. .BR 'e'
  472. and
  473. .BR 'o'
  474. are specified, then both files are retained. An existing
  475. .IR Keep_Files
  476. attribute can be cleared by the following keep type:
  477. .IP "\fRn\fR" 6
  478. NO_KEEP
  479. .P
  480. If
  481. .BR 'n'
  482. is specified, then no files are retained. The
  483. .IR qsub
  484. utility shall consider it an error if any keep type other than
  485. .BR 'n'
  486. is combined with keep type
  487. .BR 'n' .
  488. .P
  489. Strictly conforming applications shall not repeat any of the characters
  490. .BR 'e' ,
  491. .BR 'o' ,
  492. or
  493. .BR 'n'
  494. within the
  495. .IR keep_list
  496. option-argument. The
  497. .IR qsub
  498. utility shall permit the repetition of characters, but shall not assign
  499. additional meaning to the repeated characters.
  500. .P
  501. An implementation may define other keep types. The conformance document
  502. for an implementation shall describe any additional keep types, how
  503. they are specified, their internal behavior, and how they affect the
  504. behavior of the utility. If the
  505. .BR \-k
  506. option is not presented to the
  507. .IR qsub
  508. utility, the utility shall set the
  509. .IR Keep_Files
  510. attribute of the batch job to the value NO_KEEP.
  511. .RE
  512. .IP "\fB\-m\ \fImail_options\fR" 10
  513. .br
  514. Define the points in the execution of the batch job at which the batch
  515. server that manages the batch job shall send mail about a change in the
  516. state of the batch job.
  517. .RS 10
  518. .P
  519. The
  520. .IR qsub
  521. .BR \-m
  522. option shall accept a value for the
  523. .IR mail_options
  524. option-argument that is a string of alphanumeric characters in the
  525. portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
  526. .IR "Section 6.1" ", " "Portable Character Set").
  527. .P
  528. The
  529. .IR qsub
  530. utility shall accept a value for the
  531. .IR mail_options
  532. option-argument that is a string of one or more of the characters
  533. .BR 'e' ,
  534. .BR 'b' ,
  535. and
  536. .BR 'a' ,
  537. or the single character
  538. .BR 'n' .
  539. .P
  540. For each unique character in the
  541. .IR mail_options
  542. option-argument, the
  543. .IR qsub
  544. utility shall add a value to the
  545. .IR Mail_Users
  546. attribute of the batch job as follows, each representing a different
  547. time during the life of a batch job at which to send mail:
  548. .IP "\fRe\fR" 6
  549. MAIL_AT_EXIT
  550. .IP "\fRb\fR" 6
  551. MAIL_AT_BEGINNING
  552. .IP "\fRa\fR" 6
  553. MAIL_AT_ABORT
  554. .P
  555. If any of these characters are duplicated in the
  556. .IR mail_options
  557. option-argument, the duplicates shall be ignored.
  558. .P
  559. An existing
  560. .IR Mail_Points
  561. attribute can be cleared by the following mail type:
  562. .IP "\fRn\fR" 6
  563. NO_MAIL
  564. .P
  565. If
  566. .BR 'n'
  567. is specified, then mail is not sent. The
  568. .IR qsub
  569. utility shall consider it an error if any mail type other than
  570. .BR 'n'
  571. is combined with mail type
  572. .BR 'n' .
  573. .P
  574. Strictly conforming applications shall not repeat any of the characters
  575. .BR 'e' ,
  576. .BR 'b' ,
  577. .BR 'a' ,
  578. or
  579. .BR 'n'
  580. within the
  581. .IR mail_options
  582. option-argument.
  583. .P
  584. The
  585. .IR qsub
  586. utility shall permit the repetition of characters, but shall not assign
  587. additional meaning to the repeated characters. An implementation may
  588. define other mail types. The conformance document for an implementation
  589. shall describe any additional mail types, how they are specified, their
  590. internal behavior, and how they affect the behavior of the utility.
  591. .P
  592. If the
  593. .BR \-m
  594. option is not presented to the
  595. .IR qsub
  596. utility, the utility shall set the
  597. .IR Mail_Points
  598. attribute to the value MAIL_AT_ABORT.
  599. .RE
  600. .IP "\fB\-M\ \fImail_list\fR" 10
  601. Define the list of users to which a batch server that executes the
  602. batch job shall send mail, if the server sends mail about the batch
  603. job.
  604. .RS 10
  605. .P
  606. The syntax of the
  607. .IR mail_list
  608. option-argument is unspecified.
  609. .P
  610. If the implementation of the
  611. .IR qsub
  612. utility uses a name service to locate users, the utility should accept
  613. the syntax used by the name service.
  614. .P
  615. If the implementation of the
  616. .IR qsub
  617. utility does not use a name service to locate users, the implementation
  618. should accept the following syntax for user names:
  619. .sp
  620. .RS 4
  621. .nf
  622. \fImail_address\fB[\fR,,\fImail_address\fR,, ...\fB]\fR
  623. .fi
  624. .P
  625. .RE
  626. .P
  627. The interpretation of
  628. .IR mail_address
  629. is implementation-defined.
  630. .P
  631. The
  632. .IR qsub
  633. utility shall set the
  634. .IR Mail_Users
  635. attribute of the batch job to the value of the
  636. .IR mail_list
  637. option-argument.
  638. .P
  639. If the
  640. .BR \-M
  641. option is not presented to the
  642. .IR qsub
  643. utility, the utility shall place only the user name and host name for
  644. the current process in the
  645. .IR Mail_Users
  646. attribute of the batch job.
  647. .RE
  648. .IP "\fB\-N\ \fIname\fR" 10
  649. Define the name of the batch job.
  650. .RS 10
  651. .P
  652. The
  653. .IR qsub
  654. .BR \-N
  655. option shall accept a value for the
  656. .IR name
  657. option-argument that is a string of up to 15 alphanumeric characters in
  658. the portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
  659. .IR "Section 6.1" ", " "Portable Character Set")
  660. where the first character is alphabetic.
  661. .P
  662. The
  663. .IR qsub
  664. utility shall set the value of the
  665. .IR Job_Name
  666. attribute of the batch job to the value of the
  667. .IR name
  668. option-argument.
  669. .P
  670. If the
  671. .BR \-N
  672. option is not presented to the
  673. .IR qsub
  674. utility, the utility shall set the
  675. .IR Job_Name
  676. attribute of the batch job to the name of the
  677. .IR script
  678. argument from which the directory specification if any, has been
  679. removed.
  680. .P
  681. If the
  682. .BR \-N
  683. option is not presented to the
  684. .IR qsub
  685. utility, and the script is read from standard input, the utility shall
  686. set the
  687. .IR Job_Name
  688. attribute of the batch job to the value STDIN.
  689. .RE
  690. .IP "\fB\-o\ \fIpath_name\fR" 10
  691. .br
  692. Define the path for the standard output of the batch job.
  693. .RS 10
  694. .P
  695. The
  696. .IR qsub
  697. utility shall accept a
  698. .IR path_name
  699. option-argument that conforms to the syntax of the
  700. .IR path_name
  701. element defined in the System Interfaces volume of POSIX.1\(hy2017, which can be preceded by a host name
  702. element of the form
  703. .IR hostname :.
  704. .P
  705. If the
  706. .IR path_name
  707. option-argument constitutes an absolute pathname, the
  708. .IR qsub
  709. utility shall set the
  710. .IR Output_Path
  711. attribute of the batch job to the value of the
  712. .IR path_name
  713. option-argument without expansion.
  714. .P
  715. If the
  716. .IR path_name
  717. option-argument constitutes a relative pathname and no host name
  718. element is specified, the
  719. .IR qsub
  720. utility shall set the
  721. .IR Output_Path
  722. attribute of the batch job to the pathname derived by expanding the
  723. value of the
  724. .IR path_name
  725. option-argument relative to the current directory of the process
  726. executing the
  727. .IR qsub .
  728. .P
  729. If the
  730. .IR path_name
  731. option-argument constitutes a relative pathname and a host name
  732. element is specified, the
  733. .IR qsub
  734. utility shall set the
  735. .IR Output_Path
  736. attribute of the batch job to the value of the
  737. .IR path_name
  738. option-argument without expansion.
  739. .P
  740. If the
  741. .IR path_name
  742. option-argument does not specify a host name element, the
  743. .IR qsub
  744. utility shall prefix the pathname with
  745. .IR hostname :,
  746. where
  747. .IR hostname
  748. is the name of the host upon which the
  749. .IR qsub
  750. utility is executing.
  751. .P
  752. If the
  753. .BR \-o
  754. option is not presented to the
  755. .IR qsub
  756. utility, the utility shall set the
  757. .IR Output_Path
  758. attribute of the batch job to the host name and path of the current
  759. directory of the submitting process and the default filename.
  760. .P
  761. The default filename for standard output has the following format:
  762. .sp
  763. .RS 4
  764. .nf
  765. \fIjob_name\fR.o\fIsequence_number\fR
  766. .fi
  767. .P
  768. .RE
  769. .RE
  770. .IP "\fB\-p\ \fIpriority\fR" 10
  771. Define the priority the batch job should have relative to other batch
  772. jobs owned by the batch server.
  773. .RS 10
  774. .P
  775. The
  776. .IR qsub
  777. utility shall set the
  778. .IR Priority
  779. attribute of the batch job to the value of the
  780. .IR priority
  781. option-argument.
  782. .P
  783. If the
  784. .BR \-p
  785. option is not presented to the
  786. .IR qsub
  787. utility, the value of the
  788. .IR Priority
  789. attribute is implementation-defined.
  790. .P
  791. The
  792. .IR qsub
  793. utility shall accept a value for the
  794. .IR priority
  795. option-argument that conforms to the syntax for signed decimal
  796. integers, and which is not less than \-1\|024 and not greater than
  797. 1\|023.
  798. .RE
  799. .IP "\fB\-q\ \fIdestination\fR" 10
  800. .br
  801. Define the destination of the batch job.
  802. .RS 10
  803. .P
  804. The destination is not a batch job attribute; it determines the batch
  805. server, and possibly the batch queue, to which the
  806. .IR qsub
  807. utility batch queues the batch job.
  808. .P
  809. The
  810. .IR qsub
  811. utility shall submit the script to the batch server named by the
  812. .IR destination
  813. option-argument or the server that owns the batch queue named in the
  814. .IR destination
  815. option-argument.
  816. .P
  817. The
  818. .IR qsub
  819. utility shall accept an option-argument for the
  820. .BR \-q
  821. option that conforms to the syntax for a destination (see
  822. .IR "Section 3.3.2" ", " "Destination").
  823. .P
  824. If the
  825. .BR \-q
  826. option is not presented to the
  827. .IR qsub
  828. utility, the
  829. .IR qsub
  830. utility shall submit the batch job to the default destination. The
  831. mechanism for determining the default destination is
  832. implementation-defined.
  833. .RE
  834. .IP "\fB\-r\ \fIy\fR|\fIn\fR" 10
  835. Define whether the batch job is rerunnable.
  836. .RS 10
  837. .P
  838. If the value of the option-argument is
  839. .IR y ,
  840. the
  841. .IR qsub
  842. utility shall set the
  843. .IR Rerunable
  844. attribute of the batch job to TRUE.
  845. .P
  846. If the value of the option-argument is
  847. .IR n ,
  848. the
  849. .IR qsub
  850. utility shall set the
  851. .IR Rerunable
  852. attribute of the batch job to FALSE.
  853. .P
  854. If the
  855. .BR \-r
  856. option is not presented to the
  857. .IR qsub
  858. utility, the utility shall set the
  859. .IR Rerunable
  860. attribute of the batch job to TRUE.
  861. .RE
  862. .IP "\fB\-S\ \fIpath_name_list\fR" 10
  863. .br
  864. Define the pathname to the shell under which the batch job is to
  865. execute.
  866. .RS 10
  867. .P
  868. The
  869. .IR qsub
  870. utility shall accept a
  871. .IR path_name_list
  872. option-argument that conforms to the following syntax:
  873. .sp
  874. .RS 4
  875. .nf
  876. \fIpathname\fB[\fR@\fIhost\fB][\fR,,\fIpathname\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
  877. .fi
  878. .P
  879. .RE
  880. .P
  881. The
  882. .IR qsub
  883. utility shall allow only one pathname for a given host name. The
  884. .IR qsub
  885. utility shall allow only one pathname that is missing a corresponding
  886. host name.
  887. .P
  888. The
  889. .IR qsub
  890. utility shall add a value to the
  891. .IR Shell_Path_List
  892. attribute of the batch job for each entry in the
  893. .IR path_name_list
  894. option-argument.
  895. .P
  896. If the
  897. .BR \-S
  898. option is not presented to the
  899. .IR qsub
  900. utility, the utility shall set the
  901. .IR Shell_Path_List
  902. attribute of the batch job to the null string.
  903. .P
  904. The conformance document for an implementation shall describe the
  905. mechanism used to set the default shell and determine the current value
  906. of the default shell. An implementation shall provide a means for the
  907. installation to set the default shell to the login shell of the user
  908. under which the batch job is to execute. See
  909. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  910. for a means of removing
  911. .IR keyword =\c
  912. .IR value
  913. (and
  914. .IR value @\c
  915. .IR keyword )
  916. pairs and other general rules for list-oriented batch job attributes.
  917. .RE
  918. .IP "\fB\-u\ \fIuser_list\fR" 10
  919. Define the user name under which the batch job is to execute.
  920. .RS 10
  921. .P
  922. The
  923. .IR qsub
  924. utility shall accept a
  925. .IR user_list
  926. option-argument that conforms to the following syntax:
  927. .sp
  928. .RS 4
  929. .nf
  930. \fIusername\fB[\fR@\fIhost\fB][\fR,,\fIusername\fB[\fR@\fIhost\fB]\fR,, ...\fB]\fR
  931. .fi
  932. .P
  933. .RE
  934. .P
  935. The
  936. .IR qsub
  937. utility shall accept only one user name that is missing a corresponding
  938. host name. The
  939. .IR qsub
  940. utility shall accept only one user name per named host.
  941. .P
  942. The
  943. .IR qsub
  944. utility shall add a value to the
  945. .IR User_List
  946. attribute of the batch job for each entry in the
  947. .IR user_list
  948. option-argument.
  949. .P
  950. If the
  951. .BR \-u
  952. option is not presented to the
  953. .IR qsub
  954. utility, the utility shall set the
  955. .IR User_List
  956. attribute of the batch job to the user name from which the utility is
  957. executing. See
  958. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  959. for a means of removing
  960. .IR keyword =\c
  961. .IR value
  962. (and
  963. .IR value @\c
  964. .IR keyword )
  965. pairs and other general rules for list-oriented batch job attributes.
  966. .RE
  967. .IP "\fB\-v\ \fIvariable_list\fR" 10
  968. .br
  969. Add to the list of variables that are exported to the session leader of
  970. the batch job.
  971. .RS 10
  972. .P
  973. A
  974. .IR variable_list
  975. is a set of strings of either the form <\c
  976. .IR variable >
  977. or <\c
  978. .IR variable =\c
  979. .IR value >,
  980. delimited by
  981. <comma>
  982. characters.
  983. .P
  984. If the
  985. .BR \-v
  986. option is presented to the
  987. .IR qsub
  988. utility, the utility shall also add, to the environment
  989. .IR Variable_List
  990. attribute of the batch job, every variable named in the environment
  991. .IR variable_list
  992. option-argument and, optionally, values of specified variables.
  993. .P
  994. If a value is not provided on the command line, the
  995. .IR qsub
  996. utility shall set the value of each variable in the environment
  997. .IR Variable_List
  998. attribute of the batch job to the value of the corresponding
  999. environment variable for the process in which the utility is executing;
  1000. see
  1001. .IR "Table 4-19, Environment Variable Values (Utilities)".
  1002. .P
  1003. A conforming application shall not repeat a variable in the environment
  1004. .IR variable_list
  1005. option-argument.
  1006. .P
  1007. The
  1008. .IR qsub
  1009. utility shall not repeat a variable in the environment
  1010. .IR Variable_List
  1011. attribute of the batch job. See
  1012. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  1013. for a means of removing
  1014. .IR keyword =\c
  1015. .IR value
  1016. (and
  1017. .IR value @\c
  1018. .IR keyword )
  1019. pairs and other general rules for list-oriented batch job attributes.
  1020. .RE
  1021. .IP "\fB\-V\fR" 10
  1022. Specify that all of the environment variables of the process are
  1023. exported to the context of the batch job.
  1024. .RS 10
  1025. .P
  1026. The
  1027. .IR qsub
  1028. utility shall place every environment variable in the process in which
  1029. the utility is executing in the list and shall set the value of each
  1030. variable in the attribute to the value of that variable in the
  1031. process.
  1032. .RE
  1033. .IP "\fB\-z\fR" 10
  1034. Specify that the utility does not write the batch
  1035. .IR job_identifier
  1036. of the created batch job to standard output.
  1037. .RS 10
  1038. .P
  1039. If the
  1040. .BR \-z
  1041. option is presented to the
  1042. .IR qsub
  1043. utility, the utility shall not write the batch
  1044. .IR job_identifier
  1045. of the created batch job to standard output.
  1046. .P
  1047. If the
  1048. .BR \-z
  1049. option is not presented to the
  1050. .IR qsub
  1051. utility, the utility shall write the identifier of the created batch
  1052. job to standard output.
  1053. .RE
  1054. .SH OPERANDS
  1055. The
  1056. .IR qsub
  1057. utility shall accept a
  1058. .IR script
  1059. operand that indicates the path to the script of the batch job.
  1060. .P
  1061. If the
  1062. .IR script
  1063. operand is not presented to the
  1064. .IR qsub
  1065. utility, or if the operand is the single-character string
  1066. .BR '\-' ,
  1067. the utility shall read the script from standard input.
  1068. .P
  1069. If the script represents a partial path, the
  1070. .IR qsub
  1071. utility shall expand the path relative to the current directory of the
  1072. process executing the utility.
  1073. .SH STDIN
  1074. The
  1075. .IR qsub
  1076. utility reads the script of the batch job from standard input if the
  1077. script operand is omitted or is the single character
  1078. .BR '\-' .
  1079. .SH "INPUT FILES"
  1080. In addition to binding the file indicated by the
  1081. .IR script
  1082. operand to the batch job, the
  1083. .IR qsub
  1084. utility reads the script file and acts on directives in the script.
  1085. .SH "ENVIRONMENT VARIABLES"
  1086. The following environment variables shall affect the execution of
  1087. .IR qsub :
  1088. .IP "\fILANG\fP" 10
  1089. Provide a default value for the internationalization variables that are
  1090. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  1091. .IR "Section 8.2" ", " "Internationalization Variables"
  1092. the precedence of internationalization variables used to determine the
  1093. values of locale categories.)
  1094. .IP "\fILC_ALL\fP" 10
  1095. If set to a non-empty string value, override the values of all the
  1096. other internationalization variables.
  1097. .IP "\fILC_CTYPE\fP" 10
  1098. Determine the locale for the interpretation of sequences of bytes of
  1099. text data as characters (for example, single-byte as opposed to
  1100. multi-byte characters in arguments).
  1101. .IP "\fILC_MESSAGES\fP" 10
  1102. .br
  1103. Determine the locale that should be used to affect the format and
  1104. contents of diagnostic messages written to standard error.
  1105. .IP "\fILOGNAME\fP" 10
  1106. Determine the login name of the user.
  1107. .IP "\fIPBS_DPREFIX\fP" 10
  1108. .br
  1109. Determine the default prefix for directives within the script.
  1110. .IP "\fISHELL\fP" 10
  1111. Determine the pathname of the preferred command language interpreter
  1112. of the user.
  1113. .IP "\fITZ\fP" 10
  1114. Determine the timezone used to interpret the
  1115. .IR date-time
  1116. option-argument. If
  1117. .IR TZ
  1118. is unset or null, an unspecified default timezone shall be used.
  1119. .SH "ASYNCHRONOUS EVENTS"
  1120. Once created, a batch job exists until it exits, aborts, or is
  1121. deleted.
  1122. .P
  1123. After a batch job is created by the
  1124. .IR qsub
  1125. utility, batch servers might route, execute, modify, or delete the
  1126. batch job.
  1127. .SH STDOUT
  1128. The
  1129. .IR qsub
  1130. utility writes the batch
  1131. .IR job_identifier
  1132. assigned to the batch job to standard output, unless the
  1133. .BR \-z
  1134. option is specified.
  1135. .SH STDERR
  1136. The standard error shall be used only for diagnostic messages.
  1137. .SH "OUTPUT FILES"
  1138. None.
  1139. .SH "EXTENDED DESCRIPTION"
  1140. .SS "Script Preservation"
  1141. .P
  1142. The
  1143. .IR qsub
  1144. utility shall make the script available to the server executing the
  1145. batch job in such a way that the server executes the script as it
  1146. exists at the time of submission.
  1147. .P
  1148. The
  1149. .IR qsub
  1150. utility can send a copy of the script to the server with the
  1151. .IR "Queue Job Request"
  1152. or store a temporary copy of the script in a location specified to the
  1153. server.
  1154. .SS "Option Specification"
  1155. .P
  1156. A script can contain directives to the
  1157. .IR qsub
  1158. utility.
  1159. .P
  1160. The
  1161. .IR qsub
  1162. utility shall scan the lines of the script for directives, skipping
  1163. blank lines, until the first line that begins with a string other than
  1164. the directive string; if directives occur on subsequent lines, the
  1165. utility shall ignore those directives.
  1166. .P
  1167. Lines are separated by a
  1168. <newline>.
  1169. If the first line of the script begins with
  1170. .BR \(dq#!\(dq
  1171. or a
  1172. <colon>
  1173. (\c
  1174. .BR ':' ),
  1175. then it is skipped. The
  1176. .IR qsub
  1177. utility shall process a line in the script as a directive if and only
  1178. if the string of characters from the first non-white-space character on
  1179. the line until the first
  1180. <space>
  1181. or
  1182. <tab>
  1183. on the line match the directive prefix. If a line in the script
  1184. contains a directive and the final characters of the line are
  1185. <backslash>
  1186. and
  1187. <newline>,
  1188. then the next line shall be interpreted as a continuation of that
  1189. directive.
  1190. .P
  1191. The
  1192. .IR qsub
  1193. utility shall process the options and option-arguments contained on the
  1194. directive prefix line using the same syntax as if the options were
  1195. input on the
  1196. .IR qsub
  1197. utility.
  1198. .P
  1199. The
  1200. .IR qsub
  1201. utility shall continue to process a directive prefix line until after a
  1202. <newline>
  1203. is encountered. An implementation may ignore lines which, according to
  1204. the syntax of the shell that will interpret the script, are comments.
  1205. An implementation shall describe in the conformance document the format
  1206. of any shell comments that it will recognize.
  1207. .P
  1208. If an option is present in both a directive and the arguments to the
  1209. .IR qsub
  1210. utility, the utility shall ignore the option and the corresponding
  1211. option-argument, if any, in the directive.
  1212. .P
  1213. If an option that is present in the directive is not present in the
  1214. arguments to the
  1215. .IR qsub
  1216. utility, the utility shall process the option and the option-argument,
  1217. if any.
  1218. .P
  1219. In order of preference, the
  1220. .IR qsub
  1221. utility shall select the directive prefix from one of the following
  1222. sources:
  1223. .IP " *" 4
  1224. If the
  1225. .BR \-C
  1226. option is presented to the utility, the value of the
  1227. .IR directive_prefix
  1228. option-argument
  1229. .IP " *" 4
  1230. If the environment variable
  1231. .IR PBS_DPREFIX
  1232. is defined, the value of that variable
  1233. .IP " *" 4
  1234. The four-character string
  1235. .BR \(dq#PBS\(dq
  1236. encoded in the portable character set
  1237. .P
  1238. If the
  1239. .BR \-C
  1240. option is present in the script file it shall be ignored.
  1241. .SH "EXIT STATUS"
  1242. The following exit values shall be returned:
  1243. .IP "\00" 6
  1244. Successful completion.
  1245. .IP >0 6
  1246. An error occurred.
  1247. .SH "CONSEQUENCES OF ERRORS"
  1248. Default.
  1249. .LP
  1250. .IR "The following sections are informative."
  1251. .SH "APPLICATION USAGE"
  1252. None.
  1253. .SH EXAMPLES
  1254. None.
  1255. .SH RATIONALE
  1256. The
  1257. .IR qsub
  1258. utility allows users to create a batch job that will process the script
  1259. specified as the operand of the utility.
  1260. .P
  1261. The options of the
  1262. .IR qsub
  1263. utility allow users to control many aspects of the queuing and
  1264. execution of a batch job.
  1265. .P
  1266. The
  1267. .BR \-a
  1268. option allows users to designate the time after which the batch job
  1269. will become eligible to run. By specifying an execution time, users can
  1270. take advantage of resources at off-peak hours, synchronize jobs with
  1271. chronologically predictable events, and perhaps take advantage of
  1272. off-peak pricing of computing time. For these reasons and others, a
  1273. timing option is existing practice on the part of almost every batch
  1274. system, including NQS.
  1275. .P
  1276. The
  1277. .BR \-A
  1278. option allows users to specify the account that will be charged for the
  1279. batch job. Support for account is not mandatory for conforming batch
  1280. servers.
  1281. .P
  1282. The
  1283. .BR \-C
  1284. option allows users to prescribe the prefix for directives within the
  1285. script file. The default prefix
  1286. .BR \(dq#PBS\(dq
  1287. may be inappropriate if the script will be interpreted with an
  1288. alternate shell, as specified by the
  1289. .BR \-S
  1290. option.
  1291. .P
  1292. The
  1293. .BR \-c
  1294. option allows users to establish the checkpointing interval for their
  1295. jobs. A checkpointing system, which is not defined by this volume of POSIX.1\(hy2017, allows
  1296. recovery of a batch job at the most recent checkpoint in the event of a
  1297. crash. Checkpointing is typically used for jobs that consume expensive
  1298. computing time or must meet a critical schedule. Users should be
  1299. allowed to make the tradeoff between the overhead of checkpointing and
  1300. the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2017
  1301. provides the checkpointing interval option. Support for checkpointing
  1302. is optional for batch servers.
  1303. .P
  1304. The
  1305. .BR \-e
  1306. option allows users to redirect the standard error streams of their
  1307. jobs to a non-default path. For example, if the submitted script
  1308. generally produces a great deal of useless error output, a user might
  1309. redirect the standard error output to the null device. Or, if the file
  1310. system holding the default location (the home directory of the user)
  1311. has too little free space, the user might redirect the standard error
  1312. stream to a file in another file system.
  1313. .P
  1314. The
  1315. .BR \-h
  1316. option allows users to create a batch job that is held until explicitly
  1317. released. The ability to create a held job is useful when some external
  1318. event must complete before the batch job can execute. For example, the
  1319. user might submit a held job and release it when the system load has
  1320. dropped.
  1321. .P
  1322. The
  1323. .BR \-j
  1324. option allows users to merge the standard error of a batch job into its
  1325. standard output stream, which has the advantage of showing the
  1326. sequential relationship between output and error messages.
  1327. .P
  1328. The
  1329. .BR \-m
  1330. option allows users to designate those points in the execution of a
  1331. batch job at which mail will be sent to the submitting user, or to the
  1332. account(s) indicated by the
  1333. .BR \-M
  1334. option. By requesting mail notification at points of interest in the
  1335. life of a job, the submitting user, or other designated users, can
  1336. track the progress of a batch job.
  1337. .P
  1338. The
  1339. .BR \-N
  1340. option allows users to associate a name with the batch job. The job
  1341. name in no way affects the processing of the batch job, but rather
  1342. serves as a mnemonic handle for users. For example, the batch job name
  1343. can help the user distinguish between multiple jobs listed by the
  1344. .IR qstat
  1345. utility.
  1346. .P
  1347. The
  1348. .BR \-o
  1349. option allows users to redirect the standard output stream. A user
  1350. might, for example, wish to redirect to the null device the standard
  1351. output stream of a job that produces copious yet superfluous output.
  1352. .P
  1353. The
  1354. .BR \-P
  1355. option allows users to designate the relative priority of a batch job
  1356. for selection from a queue.
  1357. .P
  1358. The
  1359. .BR \-q
  1360. option allows users to specify an initial queue for the batch job. If
  1361. the user specifies a routing queue, the batch server routes the
  1362. batch job to another queue for execution or further routing. If the
  1363. user specifies a non-routing queue, the batch server of the queue
  1364. eventually executes the batch job.
  1365. .P
  1366. The
  1367. .BR \-r
  1368. option allows users to control whether the submitted job will be rerun
  1369. if the controlling batch node fails during execution of the batch job.
  1370. The
  1371. .BR \-r
  1372. option likewise allows users to indicate whether or not the batch job
  1373. is eligible to be rerun by the
  1374. .IR qrerun
  1375. utility. Some jobs cannot be correctly rerun because of changes they
  1376. make in the state of databases or other aspects of their environment.
  1377. This volume of POSIX.1\(hy2017 specifies that the default, if the
  1378. .BR \-r
  1379. option is not presented to the utility, will be that the batch job
  1380. cannot be rerun, since the result of rerunning a non-rerunnable job
  1381. might be catastrophic.
  1382. .P
  1383. The
  1384. .BR \-S
  1385. option allows users to specify the program (usually a shell) that will
  1386. be invoked to process the script of the batch job. This option has been
  1387. modified to allow a list of shell names and locations associated with
  1388. different hosts.
  1389. .P
  1390. The
  1391. .BR \-u
  1392. option is useful when the submitting user is authorized to use more
  1393. than one account on a given host, in which case the
  1394. .BR \-u
  1395. option allows the user to select from among those accounts. The
  1396. option-argument is a list of user-host pairs, so that the submitting
  1397. user can provide different user identifiers for different nodes in the
  1398. event the batch job is routed. The
  1399. .BR \-u
  1400. option provides a lot of flexibility to accommodate sites with complex
  1401. account structures. Users that have the same user identifier on all the
  1402. hosts they are authorized to use will not need to use the
  1403. .BR \-u
  1404. option.
  1405. .P
  1406. The
  1407. .BR \-V
  1408. option allows users to export all their current environment variables,
  1409. as of the time the batch job is submitted, to the context of the
  1410. processes of the batch job.
  1411. .P
  1412. The
  1413. .BR \-v
  1414. option allows users to export specific environment variables from their
  1415. current process to the processes of the batch job.
  1416. .P
  1417. The
  1418. .BR \-z
  1419. option allows users to suppress the writing of the batch job identifier
  1420. to standard output. The
  1421. .BR \-z
  1422. option is an existing NQS practice that has been standardized.
  1423. .P
  1424. Historically, the
  1425. .IR qsub
  1426. utility has served the batch job-submission function in the NQS system,
  1427. the existing practice on which it is based. Some changes and additions
  1428. have been made to the
  1429. .IR qsub
  1430. utility in this volume of POSIX.1\(hy2017, \fIvis-a-vis\fP NQS, as a result of the growing pool
  1431. of experience with distributed batch systems.
  1432. .P
  1433. The set of features of the
  1434. .IR qsub
  1435. utility as defined in this volume of POSIX.1\(hy2017 appears to incorporate all the common
  1436. existing practice on potentially conforming platforms.
  1437. .SH "FUTURE DIRECTIONS"
  1438. The
  1439. .IR qsub
  1440. utility may be removed in a future version.
  1441. .SH "SEE ALSO"
  1442. .IR "Chapter 3" ", " "Batch Environment Services",
  1443. .IR "\fIqrerun\fR\^",
  1444. .IR "\fIqstat\fR\^",
  1445. .IR "\fItouch\fR\^"
  1446. .P
  1447. The Base Definitions volume of POSIX.1\(hy2017,
  1448. .IR "Section 3.150" ", " "Epoch",
  1449. .IR "Section 6.1" ", " "Portable Character Set",
  1450. .IR "Chapter 8" ", " "Environment Variables",
  1451. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  1452. .\"
  1453. .SH COPYRIGHT
  1454. Portions of this text are reprinted and reproduced in electronic form
  1455. from IEEE Std 1003.1-2017, Standard for Information Technology
  1456. -- Portable Operating System Interface (POSIX), The Open Group Base
  1457. Specifications Issue 7, 2018 Edition,
  1458. Copyright (C) 2018 by the Institute of
  1459. Electrical and Electronics Engineers, Inc and The Open Group.
  1460. In the event of any discrepancy between this version and the original IEEE and
  1461. The Open Group Standard, the original IEEE and The Open Group Standard
  1462. is the referee document. The original Standard can be obtained online at
  1463. http://www.opengroup.org/unix/online.html .
  1464. .PP
  1465. Any typographical or formatting errors that appear
  1466. in this page are most likely
  1467. to have been introduced during the conversion of the source files to
  1468. man page format. To report such errors, see
  1469. https://www.kernel.org/doc/man-pages/reporting_bugs.html .