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

time.1p (10522B)


  1. '\" et
  2. .TH TIME "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. time
  12. \(em time a simple command
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. time \fB[\fR-p\fB] \fIutility \fB[\fIargument\fR...\fB]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR time
  21. utility shall invoke the utility named by the
  22. .IR utility
  23. operand with arguments supplied as the
  24. .IR argument
  25. operands and write a message to standard error that lists timing
  26. statistics for the utility. The message shall include the following
  27. information:
  28. .IP " *" 4
  29. The elapsed (real) time between invocation of
  30. .IR utility
  31. and its termination.
  32. .IP " *" 4
  33. The User CPU time, equivalent to the sum of the
  34. .IR tms_utime
  35. and
  36. .IR tms_cutime
  37. fields returned by the
  38. \fItimes\fR()
  39. function defined in the System Interfaces volume of POSIX.1\(hy2017 for the process in which
  40. .IR utility
  41. is executed.
  42. .IP " *" 4
  43. The System CPU time, equivalent to the sum of the
  44. .IR tms_stime
  45. and
  46. .IR tms_cstime
  47. fields returned by the
  48. \fItimes\fR()
  49. function for the process in which
  50. .IR utility
  51. is executed.
  52. .P
  53. The precision of the timing shall be no less than the granularity
  54. defined for the size of the clock tick unit on the system, but the
  55. results shall be reported in terms of standard time units (for example,
  56. 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers of
  57. clock ticks.
  58. .P
  59. When
  60. .IR time
  61. is used as part of a pipeline, the times reported are unspecified,
  62. except when it is the sole command within a grouping command (see
  63. .IR "Section 2.9.4.1" ", " "Grouping Commands")
  64. in that pipeline. For example, the commands on the left are
  65. unspecified; those on the right report on utilities
  66. .BR a
  67. and
  68. .BR c ,
  69. respectively:
  70. .sp
  71. .RS 4
  72. .nf
  73. time a | b | c { time a; } | b | c
  74. a | b | time c a | b | (time c)
  75. .fi
  76. .P
  77. .RE
  78. .SH OPTIONS
  79. The
  80. .IR time
  81. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  82. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  83. .P
  84. The following option shall be supported:
  85. .IP "\fB\-p\fP" 10
  86. Write the timing output to standard error in the format shown in the
  87. STDERR section.
  88. .SH OPERANDS
  89. The following operands shall be supported:
  90. .IP "\fIutility\fR" 10
  91. The name of a utility that is to be invoked. If the
  92. .IR utility
  93. operand names any of the special built-in utilities in
  94. .IR "Section 2.14" ", " "Special Built-In Utilities",
  95. the results are undefined.
  96. .IP "\fIargument\fR" 10
  97. Any string to be supplied as an argument when invoking the utility
  98. named by the
  99. .IR utility
  100. operand.
  101. .SH STDIN
  102. Not used.
  103. .SH "INPUT FILES"
  104. None.
  105. .SH "ENVIRONMENT VARIABLES"
  106. The following environment variables shall affect the execution of
  107. .IR time :
  108. .IP "\fILANG\fP" 10
  109. Provide a default value for the internationalization variables that are
  110. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  111. .IR "Section 8.2" ", " "Internationalization Variables"
  112. for the precedence of internationalization variables used to determine
  113. the values of locale categories.)
  114. .IP "\fILC_ALL\fP" 10
  115. If set to a non-empty string value, override the values of all the
  116. other internationalization variables.
  117. .IP "\fILC_CTYPE\fP" 10
  118. Determine the locale for the interpretation of sequences of bytes of
  119. text data as characters (for example, single-byte as opposed to
  120. multi-byte characters in arguments).
  121. .IP "\fILC_MESSAGES\fP" 10
  122. .br
  123. Determine the locale that should be used to affect the format and
  124. contents of diagnostic and informative messages written to standard
  125. error.
  126. .IP "\fILC_NUMERIC\fP" 10
  127. .br
  128. Determine the locale for numeric formatting.
  129. .IP "\fINLSPATH\fP" 10
  130. Determine the location of message catalogs for the processing of
  131. .IR LC_MESSAGES .
  132. .IP "\fIPATH\fP" 10
  133. Determine the search path that shall be used to locate the utility to
  134. be invoked; see the Base Definitions volume of POSIX.1\(hy2017,
  135. .IR "Chapter 8" ", " "Environment Variables".
  136. .SH "ASYNCHRONOUS EVENTS"
  137. Default.
  138. .SH STDOUT
  139. Not used.
  140. .SH STDERR
  141. If the
  142. .IR utility
  143. utility is invoked, the standard error shall be used to write the
  144. timing statistics and may be used to write a diagnostic message if the
  145. utility terminates abnormally; otherwise, the standard error shall be
  146. used to write diagnostic messages and may also be used to write the
  147. timing statistics.
  148. .P
  149. If
  150. .BR \-p
  151. is specified, the following format shall be used for the timing
  152. statistics in the POSIX locale:
  153. .sp
  154. .RS 4
  155. .nf
  156. "real %f\enuser %f\ensys %f\en", <\fIreal seconds\fR>, <\fIuser seconds\fR>,
  157. <\fIsystem seconds\fR>
  158. .fi
  159. .P
  160. .RE
  161. .P
  162. where each floating-point number shall be expressed in seconds. The
  163. precision used may be less than the default six digits of
  164. .BR %f ,
  165. but shall be sufficiently precise to accommodate the size of the clock
  166. tick on the system (for example, if there were 60 clock ticks per
  167. second, at least two digits shall follow the radix character). The
  168. number of digits following the radix character shall be no less than
  169. one, even if this always results in a trailing zero. The implementation
  170. may append white space and additional information following the format
  171. shown here. The implementation may also prepend a single empty line
  172. before the format shown here.
  173. .SH "OUTPUT FILES"
  174. None.
  175. .SH "EXTENDED DESCRIPTION"
  176. None.
  177. .SH "EXIT STATUS"
  178. If the
  179. .IR utility
  180. utility is invoked, the exit status of
  181. .IR time
  182. shall be the exit status of
  183. .IR utility ;
  184. otherwise, the
  185. .IR time
  186. utility shall exit with one of the following values:
  187. .IP "1\(hy125" 8
  188. An error occurred in the
  189. .IR time
  190. utility.
  191. .IP "\0\0126" 8
  192. The utility specified by
  193. .IR utility
  194. was found but could not be invoked.
  195. .IP "\0\0127" 8
  196. The utility specified by
  197. .IR utility
  198. could not be found.
  199. .SH "CONSEQUENCES OF ERRORS"
  200. Default.
  201. .LP
  202. .IR "The following sections are informative."
  203. .SH "APPLICATION USAGE"
  204. The
  205. .IR command ,
  206. .IR env ,
  207. .IR nice ,
  208. .IR nohup ,
  209. .IR time ,
  210. and
  211. .IR xargs
  212. utilities have been specified to use exit code 127 if an error occurs
  213. so that applications can distinguish ``failure to find a utility'' from
  214. ``invoked utility exited with an error indication''. The value 127 was
  215. chosen because it is not commonly used for other meanings; most
  216. utilities use small values for ``normal error conditions'' and the
  217. values above 128 can be confused with termination due to receipt of a
  218. signal. The value 126 was chosen in a similar manner to indicate that
  219. the utility could be found, but not invoked. Some scripts produce
  220. meaningful error messages differentiating the 126 and 127 cases. The
  221. distinction between exit codes 126 and 127 is based on KornShell
  222. practice that uses 127 when all attempts to
  223. .IR exec
  224. the utility fail with
  225. .BR [ENOENT] ,
  226. and uses 126 when any attempt to
  227. .IR exec
  228. the utility fails for any other reason.
  229. .SH EXAMPLES
  230. It is frequently desirable to apply
  231. .IR time
  232. to pipelines or lists of commands. This can be done by placing
  233. pipelines and command lists in a single file; this file can then be
  234. invoked as a utility, and the
  235. .IR time
  236. applies to everything in the file.
  237. .P
  238. Alternatively, the following command can be used to apply
  239. .IR time
  240. to a complex command:
  241. .sp
  242. .RS 4
  243. .nf
  244. time sh -c \(aq\fIcomplex-command-line\fP\(aq
  245. .fi
  246. .P
  247. .RE
  248. .SH RATIONALE
  249. When the
  250. .IR time
  251. utility was originally proposed to be included in the ISO\ POSIX\(hy2:\|1993 standard,
  252. questions were raised about its suitability for inclusion on
  253. the grounds that it was not useful for conforming applications,
  254. specifically:
  255. .IP " *" 4
  256. The underlying CPU definitions from the System Interfaces volume of POSIX.1\(hy2017 are
  257. vague, so the numeric output could not be compared accurately between
  258. systems or even between invocations.
  259. .IP " *" 4
  260. The creation of portable benchmark programs was outside the scope this volume of POSIX.1\(hy2017.
  261. .P
  262. However,
  263. .IR time
  264. does fit in the scope of user portability. Human judgement can be
  265. applied to the analysis of the output, and it could be very useful in
  266. hands-on debugging of applications or in providing subjective measures
  267. of system performance. Hence it has been included in this volume of POSIX.1\(hy2017.
  268. .P
  269. The default output format has been left unspecified because historical
  270. implementations differ greatly in their style of depicting this numeric
  271. output. The
  272. .BR \-p
  273. option was invented to provide scripts with a common means of obtaining
  274. this information.
  275. .P
  276. In the KornShell,
  277. .IR time
  278. is a shell reserved word that can be used to time an entire pipeline,
  279. rather than just a simple command. The POSIX definition has been
  280. worded to allow this implementation. Consideration was given to
  281. invalidating this approach because of the historical model from the C
  282. shell and System V shell. However, since the System V
  283. .IR time
  284. utility historically has not produced accurate results in pipeline
  285. timing (because the constituent processes are not all owned by the same
  286. parent process, as allowed by POSIX), it did not seem worthwhile to
  287. break historical KornShell usage.
  288. .P
  289. The term
  290. .IR utility
  291. is used, rather than
  292. .IR command ,
  293. to highlight the fact that shell compound commands, pipelines, special
  294. built-ins, and so on, cannot be used directly.
  295. However,
  296. .IR utility
  297. includes user application programs and shell scripts, not just the
  298. standard utilities.
  299. .SH "FUTURE DIRECTIONS"
  300. None.
  301. .SH "SEE ALSO"
  302. .IR "Chapter 2" ", " "Shell Command Language",
  303. .IR "\fIsh\fR\^"
  304. .P
  305. The Base Definitions volume of POSIX.1\(hy2017,
  306. .IR "Chapter 8" ", " "Environment Variables",
  307. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  308. .P
  309. The System Interfaces volume of POSIX.1\(hy2017,
  310. .IR "\fItimes\fR\^(\|)"
  311. .\"
  312. .SH COPYRIGHT
  313. Portions of this text are reprinted and reproduced in electronic form
  314. from IEEE Std 1003.1-2017, Standard for Information Technology
  315. -- Portable Operating System Interface (POSIX), The Open Group Base
  316. Specifications Issue 7, 2018 Edition,
  317. Copyright (C) 2018 by the Institute of
  318. Electrical and Electronics Engineers, Inc and The Open Group.
  319. In the event of any discrepancy between this version and the original IEEE and
  320. The Open Group Standard, the original IEEE and The Open Group Standard
  321. is the referee document. The original Standard can be obtained online at
  322. http://www.opengroup.org/unix/online.html .
  323. .PP
  324. Any typographical or formatting errors that appear
  325. in this page are most likely
  326. to have been introduced during the conversion of the source files to
  327. man page format. To report such errors, see
  328. https://www.kernel.org/doc/man-pages/reporting_bugs.html .