]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node Date and Time, Non-Local Exits, Arithmetic, Top |
7a68c94a | 2 | @c %MENU% Functions for getting the date and time and formatting them nicely |
28f540f4 RM |
3 | @chapter Date and Time |
4 | ||
5 | This chapter describes functions for manipulating dates and times, | |
6 | including functions for determining what the current time is and | |
7 | conversion between different time representations. | |
8 | ||
9 | The time functions fall into three main categories: | |
10 | ||
11 | @itemize @bullet | |
01cdeca0 | 12 | @item |
28f540f4 RM |
13 | Functions for measuring elapsed CPU time are discussed in @ref{Processor |
14 | Time}. | |
15 | ||
16 | @item | |
17 | Functions for measuring absolute clock or calendar time are discussed in | |
18 | @ref{Calendar Time}. | |
19 | ||
20 | @item | |
21 | Functions for setting alarms and timers are discussed in @ref{Setting | |
22 | an Alarm}. | |
23 | @end itemize | |
24 | ||
25 | @menu | |
26 | * Processor Time:: Measures processor time used by a program. | |
27 | * Calendar Time:: Manipulation of ``real'' dates and times. | |
28 | * Setting an Alarm:: Sending a signal after a specified time. | |
29 | * Sleeping:: Waiting for a period of time. | |
30 | * Resource Usage:: Measuring various resources used. | |
31 | * Limits on Resources:: Specifying limits on resource usage. | |
32 | * Priority:: Reading or setting process run priority. | |
33 | @end menu | |
34 | ||
35 | @node Processor Time | |
36 | @section Processor Time | |
37 | ||
38 | If you're trying to optimize your program or measure its efficiency, it's | |
39 | very useful to be able to know how much @dfn{processor time} or @dfn{CPU | |
40 | time} it has used at any given point. Processor time is different from | |
41 | actual wall clock time because it doesn't include any time spent waiting | |
42 | for I/O or when some other process is running. Processor time is | |
43 | represented by the data type @code{clock_t}, and is given as a number of | |
44 | @dfn{clock ticks} relative to an arbitrary base time marking the beginning | |
45 | of a single program invocation. | |
46 | @cindex CPU time | |
47 | @cindex processor time | |
48 | @cindex clock ticks | |
49 | @cindex ticks, clock | |
50 | @cindex time, elapsed CPU | |
51 | ||
52 | @menu | |
53 | * Basic CPU Time:: The @code{clock} function. | |
54 | * Detailed CPU Time:: The @code{times} function. | |
55 | @end menu | |
56 | ||
57 | @node Basic CPU Time | |
58 | @subsection Basic CPU Time Inquiry | |
59 | ||
60 | To get the elapsed CPU time used by a process, you can use the | |
61 | @code{clock} function. This facility is declared in the header file | |
62 | @file{time.h}. | |
63 | @pindex time.h | |
64 | ||
65 | In typical usage, you call the @code{clock} function at the beginning and | |
66 | end of the interval you want to time, subtract the values, and then divide | |
67 | by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this: | |
68 | ||
69 | @smallexample | |
70 | @group | |
71 | #include <time.h> | |
72 | ||
73 | clock_t start, end; | |
74 | double elapsed; | |
75 | ||
76 | start = clock(); | |
77 | @dots{} /* @r{Do the work.} */ | |
78 | end = clock(); | |
79 | elapsed = ((double) (end - start)) / CLOCKS_PER_SEC; | |
80 | @end group | |
81 | @end smallexample | |
82 | ||
83 | Different computers and operating systems vary wildly in how they keep | |
84 | track of processor time. It's common for the internal processor clock | |
e9dcb080 | 85 | to have a resolution somewhere between hundredth and millionth of a |
28f540f4 RM |
86 | second. |
87 | ||
88 | In the GNU system, @code{clock_t} is equivalent to @code{long int} and | |
89 | @code{CLOCKS_PER_SEC} is an integer value. But in other systems, both | |
90 | @code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be | |
91 | either integer or floating-point types. Casting processor time values | |
92 | to @code{double}, as in the example above, makes sure that operations | |
93 | such as arithmetic and printing work properly and consistently no matter | |
94 | what the underlying representation is. | |
95 | ||
96 | @comment time.h | |
f65fd747 | 97 | @comment ISO |
28f540f4 RM |
98 | @deftypevr Macro int CLOCKS_PER_SEC |
99 | The value of this macro is the number of clock ticks per second measured | |
100 | by the @code{clock} function. | |
101 | @end deftypevr | |
102 | ||
103 | @comment time.h | |
104 | @comment POSIX.1 | |
105 | @deftypevr Macro int CLK_TCK | |
01cdeca0 | 106 | This is an obsolete name for @code{CLOCKS_PER_SEC}. |
28f540f4 RM |
107 | @end deftypevr |
108 | ||
109 | @comment time.h | |
f65fd747 | 110 | @comment ISO |
28f540f4 RM |
111 | @deftp {Data Type} clock_t |
112 | This is the type of the value returned by the @code{clock} function. | |
113 | Values of type @code{clock_t} are in units of clock ticks. | |
114 | @end deftp | |
115 | ||
116 | @comment time.h | |
f65fd747 | 117 | @comment ISO |
28f540f4 RM |
118 | @deftypefun clock_t clock (void) |
119 | This function returns the elapsed processor time. The base time is | |
120 | arbitrary but doesn't change within a single process. If the processor | |
121 | time is not available or cannot be represented, @code{clock} returns the | |
122 | value @code{(clock_t)(-1)}. | |
123 | @end deftypefun | |
124 | ||
125 | ||
126 | @node Detailed CPU Time | |
127 | @subsection Detailed Elapsed CPU Time Inquiry | |
128 | ||
129 | The @code{times} function returns more detailed information about | |
130 | elapsed processor time in a @w{@code{struct tms}} object. You should | |
131 | include the header file @file{sys/times.h} to use this facility. | |
132 | @pindex sys/times.h | |
133 | ||
134 | @comment sys/times.h | |
135 | @comment POSIX.1 | |
136 | @deftp {Data Type} {struct tms} | |
137 | The @code{tms} structure is used to return information about process | |
138 | times. It contains at least the following members: | |
139 | ||
140 | @table @code | |
141 | @item clock_t tms_utime | |
142 | This is the CPU time used in executing the instructions of the calling | |
143 | process. | |
144 | ||
145 | @item clock_t tms_stime | |
146 | This is the CPU time used by the system on behalf of the calling process. | |
147 | ||
148 | @item clock_t tms_cutime | |
149 | This is the sum of the @code{tms_utime} values and the @code{tms_cutime} | |
150 | values of all terminated child processes of the calling process, whose | |
151 | status has been reported to the parent process by @code{wait} or | |
152 | @code{waitpid}; see @ref{Process Completion}. In other words, it | |
153 | represents the total CPU time used in executing the instructions of all | |
154 | the terminated child processes of the calling process, excluding child | |
155 | processes which have not yet been reported by @code{wait} or | |
156 | @code{waitpid}. | |
157 | ||
158 | @item clock_t tms_cstime | |
159 | This is similar to @code{tms_cutime}, but represents the total CPU time | |
160 | used by the system on behalf of all the terminated child processes of the | |
161 | calling process. | |
162 | @end table | |
163 | ||
164 | All of the times are given in clock ticks. These are absolute values; in a | |
165 | newly created process, they are all zero. @xref{Creating a Process}. | |
166 | @end deftp | |
167 | ||
168 | @comment sys/times.h | |
169 | @comment POSIX.1 | |
170 | @deftypefun clock_t times (struct tms *@var{buffer}) | |
171 | The @code{times} function stores the processor time information for | |
172 | the calling process in @var{buffer}. | |
173 | ||
174 | The return value is the same as the value of @code{clock()}: the elapsed | |
175 | real time relative to an arbitrary base. The base is a constant within a | |
176 | particular process, and typically represents the time since system | |
177 | start-up. A value of @code{(clock_t)(-1)} is returned to indicate failure. | |
178 | @end deftypefun | |
179 | ||
180 | @strong{Portability Note:} The @code{clock} function described in | |
f65fd747 | 181 | @ref{Basic CPU Time}, is specified by the @w{ISO C} standard. The |
28f540f4 RM |
182 | @code{times} function is a feature of POSIX.1. In the GNU system, the |
183 | value returned by the @code{clock} function is equivalent to the sum of | |
184 | the @code{tms_utime} and @code{tms_stime} fields returned by | |
185 | @code{times}. | |
186 | ||
187 | @node Calendar Time | |
188 | @section Calendar Time | |
189 | ||
190 | This section describes facilities for keeping track of dates and times | |
191 | according to the Gregorian calendar. | |
192 | @cindex Gregorian calendar | |
193 | @cindex time, calendar | |
194 | @cindex date and time | |
195 | ||
196 | There are three representations for date and time information: | |
197 | ||
198 | @itemize @bullet | |
01cdeca0 RM |
199 | @item |
200 | @dfn{Calendar time} (the @code{time_t} data type) is a compact | |
28f540f4 RM |
201 | representation, typically giving the number of seconds elapsed since |
202 | some implementation-specific base time. | |
203 | @cindex calendar time | |
204 | ||
205 | @item | |
206 | There is also a @dfn{high-resolution time} representation (the @code{struct | |
207 | timeval} data type) that includes fractions of a second. Use this time | |
208 | representation instead of ordinary calendar time when you need greater | |
209 | precision. | |
210 | @cindex high-resolution time | |
211 | ||
212 | @item | |
213 | @dfn{Local time} or @dfn{broken-down time} (the @code{struct | |
214 | tm} data type) represents the date and time as a set of components | |
215 | specifying the year, month, and so on, for a specific time zone. | |
216 | This time representation is usually used in conjunction with formatting | |
217 | date and time values. | |
218 | @cindex local time | |
219 | @cindex broken-down time | |
220 | @end itemize | |
221 | ||
222 | @menu | |
223 | * Simple Calendar Time:: Facilities for manipulating calendar time. | |
224 | * High-Resolution Calendar:: A time representation with greater precision. | |
225 | * Broken-down Time:: Facilities for manipulating local time. | |
226 | * Formatting Date and Time:: Converting times to strings. | |
e9dcb080 UD |
227 | * Parsing Date and Time:: Convert textual time and date information back |
228 | into broken-down time values. | |
28f540f4 | 229 | * TZ Variable:: How users specify the time zone. |
01cdeca0 | 230 | * Time Zone Functions:: Functions to examine or specify the time zone. |
28f540f4 RM |
231 | * Time Functions Example:: An example program showing use of some of |
232 | the time functions. | |
233 | @end menu | |
234 | ||
235 | @node Simple Calendar Time | |
236 | @subsection Simple Calendar Time | |
237 | ||
238 | This section describes the @code{time_t} data type for representing | |
239 | calendar time, and the functions which operate on calendar time objects. | |
240 | These facilities are declared in the header file @file{time.h}. | |
241 | @pindex time.h | |
242 | ||
243 | @cindex epoch | |
244 | @comment time.h | |
f65fd747 | 245 | @comment ISO |
28f540f4 | 246 | @deftp {Data Type} time_t |
60092701 RM |
247 | This is the data type used to represent calendar time. |
248 | When interpreted as an absolute time | |
28f540f4 RM |
249 | value, it represents the number of seconds elapsed since 00:00:00 on |
250 | January 1, 1970, Coordinated Universal Time. (This date is sometimes | |
60092701 RM |
251 | referred to as the @dfn{epoch}.) POSIX requires that this count |
252 | ignore leap seconds, but on some hosts this count includes leap seconds | |
253 | if you set @code{TZ} to certain values (@pxref{TZ Variable}). | |
28f540f4 | 254 | |
60092701 | 255 | In the GNU C library, @code{time_t} is equivalent to @code{long int}. |
28f540f4 RM |
256 | In other systems, @code{time_t} might be either an integer or |
257 | floating-point type. | |
258 | @end deftp | |
259 | ||
260 | @comment time.h | |
f65fd747 | 261 | @comment ISO |
28f540f4 RM |
262 | @deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) |
263 | The @code{difftime} function returns the number of seconds elapsed | |
264 | between time @var{time1} and time @var{time0}, as a value of type | |
60092701 RM |
265 | @code{double}. The difference ignores leap seconds unless leap |
266 | second support is enabled. | |
28f540f4 RM |
267 | |
268 | In the GNU system, you can simply subtract @code{time_t} values. But on | |
269 | other systems, the @code{time_t} data type might use some other encoding | |
270 | where subtraction doesn't work directly. | |
271 | @end deftypefun | |
272 | ||
273 | @comment time.h | |
f65fd747 | 274 | @comment ISO |
28f540f4 RM |
275 | @deftypefun time_t time (time_t *@var{result}) |
276 | The @code{time} function returns the current time as a value of type | |
277 | @code{time_t}. If the argument @var{result} is not a null pointer, the | |
01cdeca0 | 278 | time value is also stored in @code{*@var{result}}. If the calendar |
28f540f4 RM |
279 | time is not available, the value @w{@code{(time_t)(-1)}} is returned. |
280 | @end deftypefun | |
281 | ||
282 | ||
283 | @node High-Resolution Calendar | |
284 | @subsection High-Resolution Calendar | |
285 | ||
01cdeca0 | 286 | The @code{time_t} data type used to represent calendar times has a |
28f540f4 RM |
287 | resolution of only one second. Some applications need more precision. |
288 | ||
289 | So, the GNU C library also contains functions which are capable of | |
290 | representing calendar times to a higher resolution than one second. The | |
291 | functions and the associated data types described in this section are | |
292 | declared in @file{sys/time.h}. | |
293 | @pindex sys/time.h | |
294 | ||
295 | @comment sys/time.h | |
296 | @comment BSD | |
297 | @deftp {Data Type} {struct timeval} | |
298 | The @code{struct timeval} structure represents a calendar time. It | |
299 | has the following members: | |
300 | ||
301 | @table @code | |
302 | @item long int tv_sec | |
303 | This represents the number of seconds since the epoch. It is equivalent | |
304 | to a normal @code{time_t} value. | |
305 | ||
306 | @item long int tv_usec | |
307 | This is the fractional second value, represented as the number of | |
308 | microseconds. | |
309 | ||
310 | Some times struct timeval values are used for time intervals. Then the | |
311 | @code{tv_sec} member is the number of seconds in the interval, and | |
312 | @code{tv_usec} is the number of additional microseconds. | |
313 | @end table | |
314 | @end deftp | |
315 | ||
316 | @comment sys/time.h | |
317 | @comment BSD | |
318 | @deftp {Data Type} {struct timezone} | |
319 | The @code{struct timezone} structure is used to hold minimal information | |
320 | about the local time zone. It has the following members: | |
321 | ||
322 | @table @code | |
323 | @item int tz_minuteswest | |
f0f1bf85 | 324 | This is the number of minutes west of UTC. |
28f540f4 RM |
325 | |
326 | @item int tz_dsttime | |
f0f1bf85 | 327 | If nonzero, daylight saving time applies during some part of the year. |
28f540f4 RM |
328 | @end table |
329 | ||
330 | The @code{struct timezone} type is obsolete and should never be used. | |
331 | Instead, use the facilities described in @ref{Time Zone Functions}. | |
332 | @end deftp | |
333 | ||
334 | It is often necessary to subtract two values of type @w{@code{struct | |
335 | timeval}}. Here is the best way to do this. It works even on some | |
336 | peculiar operating systems where the @code{tv_sec} member has an | |
337 | unsigned type. | |
338 | ||
339 | @smallexample | |
340 | /* @r{Subtract the `struct timeval' values X and Y,} | |
341 | @r{storing the result in RESULT.} | |
342 | @r{Return 1 if the difference is negative, otherwise 0.} */ | |
343 | ||
344 | int | |
345 | timeval_subtract (result, x, y) | |
346 | struct timeval *result, *x, *y; | |
347 | @{ | |
348 | /* @r{Perform the carry for the later subtraction by updating @var{y}.} */ | |
349 | if (x->tv_usec < y->tv_usec) @{ | |
350 | int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1; | |
351 | y->tv_usec -= 1000000 * nsec; | |
352 | y->tv_sec += nsec; | |
353 | @} | |
354 | if (x->tv_usec - y->tv_usec > 1000000) @{ | |
355 | int nsec = (y->tv_usec - x->tv_usec) / 1000000; | |
356 | y->tv_usec += 1000000 * nsec; | |
357 | y->tv_sec -= nsec; | |
358 | @} | |
359 | ||
360 | /* @r{Compute the time remaining to wait.} | |
361 | @r{@code{tv_usec} is certainly positive.} */ | |
362 | result->tv_sec = x->tv_sec - y->tv_sec; | |
363 | result->tv_usec = x->tv_usec - y->tv_usec; | |
364 | ||
365 | /* @r{Return 1 if result is negative.} */ | |
366 | return x->tv_sec < y->tv_sec; | |
367 | @} | |
368 | @end smallexample | |
369 | ||
370 | @comment sys/time.h | |
371 | @comment BSD | |
372 | @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) | |
373 | The @code{gettimeofday} function returns the current date and time in the | |
374 | @code{struct timeval} structure indicated by @var{tp}. Information about the | |
375 | time zone is returned in the structure pointed at @var{tzp}. If the @var{tzp} | |
376 | argument is a null pointer, time zone information is ignored. | |
377 | ||
378 | The return value is @code{0} on success and @code{-1} on failure. The | |
379 | following @code{errno} error condition is defined for this function: | |
380 | ||
381 | @table @code | |
382 | @item ENOSYS | |
383 | The operating system does not support getting time zone information, and | |
384 | @var{tzp} is not a null pointer. The GNU operating system does not | |
385 | support using @w{@code{struct timezone}} to represent time zone | |
386 | information; that is an obsolete feature of 4.3 BSD. | |
387 | Instead, use the facilities described in @ref{Time Zone Functions}. | |
388 | @end table | |
389 | @end deftypefun | |
390 | ||
391 | @comment sys/time.h | |
392 | @comment BSD | |
393 | @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) | |
394 | The @code{settimeofday} function sets the current date and time | |
395 | according to the arguments. As for @code{gettimeofday}, time zone | |
396 | information is ignored if @var{tzp} is a null pointer. | |
397 | ||
398 | You must be a privileged user in order to use @code{settimeofday}. | |
399 | ||
400 | The return value is @code{0} on success and @code{-1} on failure. The | |
401 | following @code{errno} error conditions are defined for this function: | |
402 | ||
403 | @table @code | |
404 | @item EPERM | |
405 | This process cannot set the time because it is not privileged. | |
406 | ||
407 | @item ENOSYS | |
408 | The operating system does not support setting time zone information, and | |
409 | @var{tzp} is not a null pointer. | |
410 | @end table | |
411 | @end deftypefun | |
412 | ||
413 | @comment sys/time.h | |
414 | @comment BSD | |
415 | @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) | |
416 | This function speeds up or slows down the system clock in order to make | |
417 | gradual adjustments in the current time. This ensures that the time | |
418 | reported by the system clock is always monotonically increasing, which | |
419 | might not happen if you simply set the current time. | |
420 | ||
421 | The @var{delta} argument specifies a relative adjustment to be made to | |
422 | the current time. If negative, the system clock is slowed down for a | |
423 | while until it has lost this much time. If positive, the system clock | |
424 | is speeded up for a while. | |
425 | ||
426 | If the @var{olddelta} argument is not a null pointer, the @code{adjtime} | |
427 | function returns information about any previous time adjustment that | |
428 | has not yet completed. | |
429 | ||
430 | This function is typically used to synchronize the clocks of computers | |
431 | in a local network. You must be a privileged user to use it. | |
432 | The return value is @code{0} on success and @code{-1} on failure. The | |
433 | following @code{errno} error condition is defined for this function: | |
434 | ||
435 | @table @code | |
436 | @item EPERM | |
437 | You do not have privilege to set the time. | |
438 | @end table | |
439 | @end deftypefun | |
440 | ||
441 | @strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday}, | |
01cdeca0 | 442 | and @code{adjtime} functions are derived from BSD. |
28f540f4 RM |
443 | |
444 | ||
445 | @node Broken-down Time | |
446 | @subsection Broken-down Time | |
447 | @cindex broken-down time | |
448 | @cindex calendar time and broken-down time | |
449 | ||
450 | Calendar time is represented as a number of seconds. This is convenient | |
451 | for calculation, but has no resemblance to the way people normally | |
452 | represent dates and times. By contrast, @dfn{broken-down time} is a binary | |
453 | representation separated into year, month, day, and so on. Broken down | |
454 | time values are not useful for calculations, but they are useful for | |
455 | printing human readable time. | |
456 | ||
457 | A broken-down time value is always relative to a choice of local time | |
458 | zone, and it also indicates which time zone was used. | |
459 | ||
460 | The symbols in this section are declared in the header file @file{time.h}. | |
461 | ||
462 | @comment time.h | |
f65fd747 | 463 | @comment ISO |
28f540f4 RM |
464 | @deftp {Data Type} {struct tm} |
465 | This is the data type used to represent a broken-down time. The structure | |
466 | contains at least the following members, which can appear in any order: | |
467 | ||
468 | @table @code | |
469 | @item int tm_sec | |
470 | This is the number of seconds after the minute, normally in the range | |
ec4b0518 | 471 | @code{0} through @code{59}. (The actual upper limit is @code{60}, to allow |
60092701 | 472 | for leap seconds if leap second support is available.) |
28f540f4 RM |
473 | @cindex leap second |
474 | ||
475 | @item int tm_min | |
ec4b0518 | 476 | This is the number of minutes after the hour, in the range @code{0} through |
28f540f4 RM |
477 | @code{59}. |
478 | ||
479 | @item int tm_hour | |
ec4b0518 | 480 | This is the number of hours past midnight, in the range @code{0} through |
28f540f4 RM |
481 | @code{23}. |
482 | ||
483 | @item int tm_mday | |
ec4b0518 | 484 | This is the day of the month, in the range @code{1} through @code{31}. |
28f540f4 RM |
485 | |
486 | @item int tm_mon | |
ec4b0518 | 487 | This is the number of months since January, in the range @code{0} through |
28f540f4 RM |
488 | @code{11}. |
489 | ||
490 | @item int tm_year | |
491 | This is the number of years since @code{1900}. | |
492 | ||
493 | @item int tm_wday | |
ec4b0518 UD |
494 | This is the number of days since Sunday, in the range @code{0} through |
495 | @code{6}. | |
28f540f4 RM |
496 | |
497 | @item int tm_yday | |
ec4b0518 | 498 | This is the number of days since January 1, in the range @code{0} through |
28f540f4 RM |
499 | @code{365}. |
500 | ||
501 | @item int tm_isdst | |
502 | @cindex Daylight Saving Time | |
503 | @cindex summer time | |
504 | This is a flag that indicates whether Daylight Saving Time is (or was, or | |
505 | will be) in effect at the time described. The value is positive if | |
506 | Daylight Saving Time is in effect, zero if it is not, and negative if the | |
507 | information is not available. | |
508 | ||
509 | @item long int tm_gmtoff | |
510 | This field describes the time zone that was used to compute this | |
f0f1bf85 UD |
511 | broken-down time value, including any adjustment for daylight saving; it |
512 | is the number of seconds that you must add to UTC to get local time. | |
513 | You can also think of this as the number of seconds east of UTC. For | |
514 | example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}. | |
515 | The @code{tm_gmtoff} field is derived from BSD and is a GNU library | |
f65fd747 | 516 | extension; it is not visible in a strict @w{ISO C} environment. |
28f540f4 RM |
517 | |
518 | @item const char *tm_zone | |
f0f1bf85 UD |
519 | This field is the name for the time zone that was used to compute this |
520 | broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and | |
f65fd747 | 521 | GNU extension, and is not visible in a strict @w{ISO C} environment. |
28f540f4 RM |
522 | @end table |
523 | @end deftp | |
524 | ||
525 | @comment time.h | |
f65fd747 | 526 | @comment ISO |
28f540f4 RM |
527 | @deftypefun {struct tm *} localtime (const time_t *@var{time}) |
528 | The @code{localtime} function converts the calendar time pointed to by | |
529 | @var{time} to broken-down time representation, expressed relative to the | |
530 | user's specified time zone. | |
531 | ||
532 | The return value is a pointer to a static broken-down time structure, which | |
60092701 RM |
533 | might be overwritten by subsequent calls to @code{ctime}, @code{gmtime}, |
534 | or @code{localtime}. (But no other library function overwrites the contents | |
535 | of this object.) | |
28f540f4 | 536 | |
fe0ec73e UD |
537 | The return value is the null pointer if @var{time} cannot be represented |
538 | as a broken-down time; typically this is because the year cannot fit into | |
539 | an @code{int}. | |
540 | ||
28f540f4 RM |
541 | Calling @code{localtime} has one other effect: it sets the variable |
542 | @code{tzname} with information about the current time zone. @xref{Time | |
543 | Zone Functions}. | |
544 | @end deftypefun | |
545 | ||
0413b54c UD |
546 | Using the @code{localtime} function is a big problem in multi-threaded |
547 | programs. The result is returned in a static buffer and this is used in | |
548 | all threads. POSIX.1c introduced a varient of this function. | |
549 | ||
550 | @comment time.h | |
551 | @comment POSIX.1c | |
552 | @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) | |
553 | The @code{localtime_r} function works just like the @code{localtime} | |
554 | function. It takes a pointer to a variable containing the calendar time | |
555 | and converts it to the broken-down time format. | |
556 | ||
557 | But the result is not placed in a static buffer. Instead it is placed | |
558 | in the object of type @code{struct tm} to which the parameter | |
559 | @var{resultp} points. | |
560 | ||
561 | If the conversion is successful the function returns a pointer to the | |
562 | object the result was written into, i.e., it returns @var{resultp}. | |
563 | @end deftypefun | |
564 | ||
565 | ||
28f540f4 | 566 | @comment time.h |
f65fd747 | 567 | @comment ISO |
28f540f4 RM |
568 | @deftypefun {struct tm *} gmtime (const time_t *@var{time}) |
569 | This function is similar to @code{localtime}, except that the broken-down | |
570 | time is expressed as Coordinated Universal Time (UTC)---that is, as | |
f0f1bf85 | 571 | Greenwich Mean Time (GMT)---rather than relative to the local time zone. |
28f540f4 RM |
572 | |
573 | Recall that calendar times are @emph{always} expressed in coordinated | |
574 | universal time. | |
575 | @end deftypefun | |
576 | ||
0413b54c | 577 | As for the @code{localtime} function we have the problem that the result |
f2ea0f5b | 578 | is placed in a static variable. POSIX.1c also provides a replacement for |
0413b54c UD |
579 | @code{gmtime}. |
580 | ||
581 | @comment time.h | |
582 | @comment POSIX.1c | |
583 | @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) | |
584 | This function is similar to @code{localtime_r}, except that it converts | |
585 | just like @code{gmtime} the given time as Coordinated Universal Time. | |
586 | ||
587 | If the conversion is successful the function returns a pointer to the | |
588 | object the result was written into, i.e., it returns @var{resultp}. | |
589 | @end deftypefun | |
590 | ||
591 | ||
28f540f4 | 592 | @comment time.h |
f65fd747 | 593 | @comment ISO |
28f540f4 RM |
594 | @deftypefun time_t mktime (struct tm *@var{brokentime}) |
595 | The @code{mktime} function is used to convert a broken-down time structure | |
596 | to a calendar time representation. It also ``normalizes'' the contents of | |
597 | the broken-down time structure, by filling in the day of week and day of | |
598 | year based on the other date and time components. | |
599 | ||
600 | The @code{mktime} function ignores the specified contents of the | |
601 | @code{tm_wday} and @code{tm_yday} members of the broken-down time | |
602 | structure. It uses the values of the other components to compute the | |
603 | calendar time; it's permissible for these components to have | |
604 | unnormalized values outside of their normal ranges. The last thing that | |
605 | @code{mktime} does is adjust the components of the @var{brokentime} | |
606 | structure (including the @code{tm_wday} and @code{tm_yday}). | |
607 | ||
608 | If the specified broken-down time cannot be represented as a calendar time, | |
609 | @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify | |
610 | the contents of @var{brokentime}. | |
611 | ||
612 | Calling @code{mktime} also sets the variable @code{tzname} with | |
613 | information about the current time zone. @xref{Time Zone Functions}. | |
614 | @end deftypefun | |
615 | ||
616 | @node Formatting Date and Time | |
617 | @subsection Formatting Date and Time | |
618 | ||
619 | The functions described in this section format time values as strings. | |
620 | These functions are declared in the header file @file{time.h}. | |
621 | @pindex time.h | |
622 | ||
623 | @comment time.h | |
f65fd747 | 624 | @comment ISO |
28f540f4 RM |
625 | @deftypefun {char *} asctime (const struct tm *@var{brokentime}) |
626 | The @code{asctime} function converts the broken-down time value that | |
627 | @var{brokentime} points to into a string in a standard format: | |
628 | ||
629 | @smallexample | |
630 | "Tue May 21 13:46:22 1991\n" | |
631 | @end smallexample | |
632 | ||
633 | The abbreviations for the days of week are: @samp{Sun}, @samp{Mon}, | |
634 | @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}. | |
635 | ||
636 | The abbreviations for the months are: @samp{Jan}, @samp{Feb}, | |
637 | @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug}, | |
638 | @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}. | |
639 | ||
640 | The return value points to a statically allocated string, which might be | |
60092701 | 641 | overwritten by subsequent calls to @code{asctime} or @code{ctime}. |
28f540f4 RM |
642 | (But no other library function overwrites the contents of this |
643 | string.) | |
644 | @end deftypefun | |
645 | ||
0413b54c UD |
646 | @comment time.h |
647 | @comment POSIX.1c | |
648 | @deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) | |
649 | This function is similar to @code{asctime} but instead of placing the | |
650 | result in a static buffer it writes the string in the buffer pointed to | |
651 | by the parameter @var{buffer}. This buffer should have at least room | |
652 | for 16 bytes. | |
653 | ||
654 | If no error occurred the function returns a pointer to the string the | |
655 | result was written into, i.e., it returns @var{buffer}. Otherwise | |
656 | return @code{NULL}. | |
657 | @end deftypefun | |
658 | ||
659 | ||
28f540f4 | 660 | @comment time.h |
f65fd747 | 661 | @comment ISO |
28f540f4 RM |
662 | @deftypefun {char *} ctime (const time_t *@var{time}) |
663 | The @code{ctime} function is similar to @code{asctime}, except that the | |
664 | time value is specified as a @code{time_t} calendar time value rather | |
665 | than in broken-down local time format. It is equivalent to | |
666 | ||
667 | @smallexample | |
668 | asctime (localtime (@var{time})) | |
669 | @end smallexample | |
670 | ||
671 | @code{ctime} sets the variable @code{tzname}, because @code{localtime} | |
672 | does so. @xref{Time Zone Functions}. | |
673 | @end deftypefun | |
674 | ||
0413b54c UD |
675 | @comment time.h |
676 | @comment POSIX.1c | |
677 | @deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) | |
678 | This function is similar to @code{ctime}, only that it places the result | |
679 | in the string pointed to by @var{buffer}. It is equivalent to (written | |
8b7fb588 | 680 | using gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}): |
0413b54c UD |
681 | |
682 | @smallexample | |
683 | (@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @}) | |
684 | @end smallexample | |
685 | ||
686 | If no error occurred the function returns a pointer to the string the | |
687 | result was written into, i.e., it returns @var{buffer}. Otherwise | |
688 | return @code{NULL}. | |
689 | @end deftypefun | |
690 | ||
691 | ||
28f540f4 | 692 | @comment time.h |
f65fd747 | 693 | @comment ISO |
28f540f4 RM |
694 | @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) |
695 | This function is similar to the @code{sprintf} function (@pxref{Formatted | |
696 | Input}), but the conversion specifications that can appear in the format | |
697 | template @var{template} are specialized for printing components of the date | |
698 | and time @var{brokentime} according to the locale currently specified for | |
699 | time conversion (@pxref{Locales}). | |
700 | ||
701 | Ordinary characters appearing in the @var{template} are copied to the | |
702 | output string @var{s}; this can include multibyte character sequences. | |
ec4b0518 | 703 | Conversion specifiers are introduced by a @samp{%} character, followed |
a2b08ee5 UD |
704 | by an optional flag which can be one of the following. These flags |
705 | are all GNU extensions. The first three affect only the output of | |
706 | numbers: | |
2de99474 UD |
707 | |
708 | @table @code | |
709 | @item _ | |
710 | The number is padded with spaces. | |
711 | ||
712 | @item - | |
713 | The number is not padded at all. | |
860d3729 UD |
714 | |
715 | @item 0 | |
7e3be507 | 716 | The number is padded with zeros even if the format specifies padding |
860d3729 | 717 | with spaces. |
7e3be507 UD |
718 | |
719 | @item ^ | |
720 | The output uses uppercase characters, but only if this is possible | |
721 | (@pxref{Case Conversion}). | |
2de99474 UD |
722 | @end table |
723 | ||
ec4b0518 UD |
724 | The default action is to pad the number with zeros to keep it a constant |
725 | width. Numbers that do not have a range indicated below are never | |
726 | padded, since there is no natural width for them. | |
727 | ||
860d3729 UD |
728 | Following the flag an optional specification of the width is possible. |
729 | This is specified in decimal notation. If the natural size of the | |
5b826692 | 730 | output is of the field has less than the specified number of characters, |
860d3729 UD |
731 | the result is written right adjusted and space padded to the given |
732 | size. | |
733 | ||
734 | An optional modifier can follow the optional flag and width | |
735 | specification. The modifiers, which are POSIX.2 extensions, are: | |
ec4b0518 UD |
736 | |
737 | @table @code | |
738 | @item E | |
739 | Use the locale's alternate representation for date and time. This | |
740 | modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X}, | |
741 | @code{%y} and @code{%Y} format specifiers. In a Japanese locale, for | |
742 | example, @code{%Ex} might yield a date format based on the Japanese | |
743 | Emperors' reigns. | |
744 | ||
745 | @item O | |
746 | Use the locale's alternate numeric symbols for numbers. This modifier | |
747 | applies only to numeric format specifiers. | |
748 | @end table | |
749 | ||
860d3729 UD |
750 | If the format supports the modifier but no alternate representation |
751 | is available, it is ignored. | |
ec4b0518 UD |
752 | |
753 | The conversion specifier ends with a format specifier taken from the | |
754 | following list. The whole @samp{%} sequence is replaced in the output | |
755 | string as follows: | |
28f540f4 RM |
756 | |
757 | @table @code | |
758 | @item %a | |
759 | The abbreviated weekday name according to the current locale. | |
760 | ||
761 | @item %A | |
762 | The full weekday name according to the current locale. | |
763 | ||
764 | @item %b | |
765 | The abbreviated month name according to the current locale. | |
766 | ||
767 | @item %B | |
768 | The full month name according to the current locale. | |
769 | ||
770 | @item %c | |
771 | The preferred date and time representation for the current locale. | |
772 | ||
2de99474 | 773 | @item %C |
ec4b0518 UD |
774 | The century of the year. This is equivalent to the greatest integer not |
775 | greater than the year divided by 100. | |
776 | ||
777 | This format is a POSIX.2 extension. | |
2de99474 | 778 | |
28f540f4 | 779 | @item %d |
ec4b0518 | 780 | The day of the month as a decimal number (range @code{01} through @code{31}). |
28f540f4 | 781 | |
2de99474 UD |
782 | @item %D |
783 | The date using the format @code{%m/%d/%y}. | |
784 | ||
ec4b0518 | 785 | This format is a POSIX.2 extension. |
2de99474 | 786 | |
ec4b0518 | 787 | @item %e |
2de99474 | 788 | The day of the month like with @code{%d}, but padded with blank (range |
ec4b0518 UD |
789 | @code{ 1} through @code{31}). |
790 | ||
791 | This format is a POSIX.2 extension. | |
792 | ||
fe0ec73e UD |
793 | @item %F |
794 | The date using the format @code{%Y-%m-%d}. This is the form specified | |
795 | in the @w{ISO 8601} standard and is the preferred form for all uses. | |
796 | ||
797 | This format is a @w{ISO C 9X} extension. | |
798 | ||
ec4b0518 UD |
799 | @item %g |
800 | The year corresponding to the ISO week number, but without the century | |
801 | (range @code{00} through @code{99}). This has the same format and value | |
802 | as @code{%y}, except that if the ISO week number (see @code{%V}) belongs | |
803 | to the previous or next year, that year is used instead. | |
804 | ||
805 | This format is a GNU extension. | |
806 | ||
807 | @item %G | |
808 | The year corresponding to the ISO week number. This has the same format | |
809 | and value as @code{%Y}, except that if the ISO week number (see | |
810 | @code{%V}) belongs to the previous or next year, that year is used | |
811 | instead. | |
2de99474 UD |
812 | |
813 | This format is a GNU extension. | |
814 | ||
815 | @item %h | |
816 | The abbreviated month name according to the current locale. The action | |
817 | is the same as for @code{%b}. | |
818 | ||
ec4b0518 | 819 | This format is a POSIX.2 extension. |
2de99474 | 820 | |
28f540f4 | 821 | @item %H |
ec4b0518 | 822 | The hour as a decimal number, using a 24-hour clock (range @code{00} through |
28f540f4 RM |
823 | @code{23}). |
824 | ||
825 | @item %I | |
ec4b0518 | 826 | The hour as a decimal number, using a 12-hour clock (range @code{01} through |
28f540f4 RM |
827 | @code{12}). |
828 | ||
829 | @item %j | |
ec4b0518 | 830 | The day of the year as a decimal number (range @code{001} through @code{366}). |
28f540f4 | 831 | |
2de99474 UD |
832 | @item %k |
833 | The hour as a decimal number, using a 24-hour clock like @code{%H}, but | |
ec4b0518 | 834 | padded with blank (range @code{ 0} through @code{23}). |
2de99474 UD |
835 | |
836 | This format is a GNU extension. | |
837 | ||
838 | @item %l | |
839 | The hour as a decimal number, using a 12-hour clock like @code{%I}, but | |
ec4b0518 | 840 | padded with blank (range @code{ 1} through @code{12}). |
2de99474 UD |
841 | |
842 | This format is a GNU extension. | |
843 | ||
28f540f4 | 844 | @item %m |
ec4b0518 | 845 | The month as a decimal number (range @code{01} through @code{12}). |
28f540f4 RM |
846 | |
847 | @item %M | |
ec4b0518 | 848 | The minute as a decimal number (range @code{00} through @code{59}). |
28f540f4 | 849 | |
2de99474 UD |
850 | @item %n |
851 | A single @samp{\n} (newline) character. | |
852 | ||
ec4b0518 | 853 | This format is a POSIX.2 extension. |
2de99474 | 854 | |
28f540f4 | 855 | @item %p |
ec4b0518 UD |
856 | Either @samp{AM} or @samp{PM}, according to the given time value; or the |
857 | corresponding strings for the current locale. Noon is treated as | |
858 | @samp{PM} and midnight as @samp{AM}. | |
28f540f4 | 859 | |
7e3be507 UD |
860 | @ignore |
861 | We currently have a problem with makeinfo. Write @samp{AM} and @samp{am} | |
862 | both results in `am'. I.e., the difference in case is not visible anymore. | |
863 | @end ignore | |
864 | @item %P | |
865 | Either @samp{am} or @samp{pm}, according to the given time value; or the | |
866 | corresponding strings for the current locale, printed in lowercase | |
867 | characters. Noon is treated as @samp{pm} and midnight as @samp{am}. | |
868 | ||
869 | This format is a GNU extension. | |
870 | ||
2de99474 | 871 | @item %r |
ec4b0518 | 872 | The complete time using the AM/PM format of the current locale. |
2de99474 | 873 | |
ec4b0518 | 874 | This format is a POSIX.2 extension. |
2de99474 UD |
875 | |
876 | @item %R | |
877 | The hour and minute in decimal numbers using the format @code{%H:%M}. | |
878 | ||
879 | This format is a GNU extension. | |
880 | ||
881 | @item %s | |
ec4b0518 UD |
882 | The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. |
883 | Leap seconds are not counted unless leap second support is available. | |
2de99474 UD |
884 | |
885 | This format is a GNU extension. | |
886 | ||
28f540f4 | 887 | @item %S |
e9dcb080 | 888 | The seconds as a decimal number (range @code{00} through @code{60}). |
28f540f4 | 889 | |
2de99474 UD |
890 | @item %t |
891 | A single @samp{\t} (tabulator) character. | |
892 | ||
ec4b0518 | 893 | This format is a POSIX.2 extension. |
2de99474 UD |
894 | |
895 | @item %T | |
896 | The time using decimal numbers using the format @code{%H:%M:%S}. | |
897 | ||
ec4b0518 UD |
898 | This format is a POSIX.2 extension. |
899 | ||
900 | @item %u | |
901 | The day of the week as a decimal number (range @code{1} through | |
902 | @code{7}), Monday being @code{1}. | |
903 | ||
904 | This format is a POSIX.2 extension. | |
2de99474 | 905 | |
28f540f4 | 906 | @item %U |
ec4b0518 UD |
907 | The week number of the current year as a decimal number (range @code{00} |
908 | through @code{53}), starting with the first Sunday as the first day of | |
909 | the first week. Days preceding the first Sunday in the year are | |
910 | considered to be in week @code{00}. | |
7c713e28 RM |
911 | |
912 | @item %V | |
ec4b0518 UD |
913 | The @w{ISO 8601:1988} week number as a decimal number (range @code{01} |
914 | through @code{53}). ISO weeks start with Monday and end with Sunday. | |
915 | Week @code{01} of a year is the first week which has the majority of its | |
916 | days in that year; this is equivalent to the week containing the year's | |
917 | first Thursday, and it is also equivalent to the week containing January | |
918 | 4. Week @code{01} of a year can contain days from the previous year. | |
919 | The week before week @code{01} of a year is the last week (@code{52} or | |
920 | @code{53}) of the previous year even if it contains days from the new | |
921 | year. | |
922 | ||
923 | This format is a POSIX.2 extension. | |
28f540f4 | 924 | |
2de99474 | 925 | @item %w |
ec4b0518 UD |
926 | The day of the week as a decimal number (range @code{0} through |
927 | @code{6}), Sunday being @code{0}. | |
2de99474 | 928 | |
28f540f4 | 929 | @item %W |
ec4b0518 UD |
930 | The week number of the current year as a decimal number (range @code{00} |
931 | through @code{53}), starting with the first Monday as the first day of | |
932 | the first week. All days preceding the first Monday in the year are | |
933 | considered to be in week @code{00}. | |
28f540f4 | 934 | |
28f540f4 RM |
935 | @item %x |
936 | The preferred date representation for the current locale, but without the | |
937 | time. | |
938 | ||
939 | @item %X | |
940 | The preferred time representation for the current locale, but with no date. | |
941 | ||
942 | @item %y | |
ec4b0518 UD |
943 | The year without a century as a decimal number (range @code{00} through |
944 | @code{99}). This is equivalent to the year modulo 100. | |
28f540f4 RM |
945 | |
946 | @item %Y | |
ec4b0518 UD |
947 | The year as a decimal number, using the Gregorian calendar. Years |
948 | before the year @code{1} are numbered @code{0}, @code{-1}, and so on. | |
28f540f4 | 949 | |
2de99474 | 950 | @item %z |
f0f1bf85 UD |
951 | @w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g., |
952 | @code{-0600} or @code{+0100}), or nothing if no time zone is | |
953 | determinable. | |
2de99474 | 954 | |
ec4b0518 UD |
955 | This format is a GNU extension. |
956 | ||
e9dcb080 UD |
957 | A full @w{RFC 822} timestamp is generated by the format |
958 | @w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent | |
eeabe877 | 959 | @w{@samp{"%a, %d %b %Y %T %z"}}). |
e1350332 | 960 | |
28f540f4 | 961 | @item %Z |
ec4b0518 | 962 | The time zone abbreviation (empty if the time zone can't be determined). |
28f540f4 RM |
963 | |
964 | @item %% | |
965 | A literal @samp{%} character. | |
966 | @end table | |
967 | ||
968 | The @var{size} parameter can be used to specify the maximum number of | |
969 | characters to be stored in the array @var{s}, including the terminating | |
970 | null character. If the formatted time requires more than @var{size} | |
0413b54c | 971 | characters, @code{strftime} returns zero and the content of the array |
55c14926 UD |
972 | @var{s} is indetermined. Otherwise the return value indicates the |
973 | number of characters placed in the array @var{s}, not including the | |
974 | terminating null character. | |
975 | ||
976 | @emph{Warning:} This convention for the return value which is prescribed | |
977 | in @w{ISO C} can lead to problems in some situations. For certain | |
978 | format strings and certain locales the output really can be the empty | |
979 | string and this cannot be discovered by testing the return value only. | |
980 | E.g., in most locales the AM/PM time format is not supported (most of | |
981 | the world uses the 24 hour time representation). In such locales | |
982 | @code{"%p"} will return the empty string, i.e., the return value is | |
983 | zero. To detect situations like this something similar to the following | |
984 | code should be used: | |
985 | ||
986 | @smallexample | |
987 | buf[0] = '\1'; | |
988 | len = strftime (buf, bufsize, format, tp); | |
989 | if (len == 0 && buf[0] != '\0') | |
990 | @{ | |
991 | /* Something went wrong in the strftime call. */ | |
992 | @dots{} | |
993 | @} | |
994 | @end smallexample | |
28f540f4 RM |
995 | |
996 | If @var{s} is a null pointer, @code{strftime} does not actually write | |
997 | anything, but instead returns the number of characters it would have written. | |
998 | ||
860d3729 UD |
999 | According to POSIX.1 every call to @code{strftime} implies a call to |
1000 | @code{tzset}. So the contents of the environment variable @code{TZ} | |
1001 | is examined before any output is produced. | |
1002 | ||
28f540f4 RM |
1003 | For an example of @code{strftime}, see @ref{Time Functions Example}. |
1004 | @end deftypefun | |
1005 | ||
e9dcb080 UD |
1006 | @node Parsing Date and Time |
1007 | @subsection Convert textual time and date information back | |
1008 | ||
1009 | The @w{ISO C} standard does not specify any functions which can convert | |
1010 | the output of the @code{strftime} function back into a binary format. | |
1011 | This lead to variety of more or less successful implementations with | |
1012 | different interfaces over the years. Then the Unix standard got | |
1013 | extended by two functions: @code{strptime} and @code{getdate}. Both | |
1014 | have kind of strange interfaces but at least they are widely available. | |
1015 | ||
1016 | @menu | |
1017 | * Low-Level Time String Parsing:: Interpret string according to given format. | |
1018 | * General Time String Parsing:: User-friendly function to parse data and | |
1019 | time strings. | |
1020 | @end menu | |
1021 | ||
1022 | @node Low-Level Time String Parsing | |
1023 | @subsubsection Interpret string according to given format | |
1024 | ||
1025 | The first function is a rather low-level interface. It is nevertheless | |
1026 | frequently used in user programs since it is better known. Its | |
1027 | implementation and the interface though is heavily influenced by the | |
1028 | @code{getdate} function which is defined and implemented in terms of | |
1029 | calls to @code{strptime}. | |
1030 | ||
1031 | @comment time.h | |
1032 | @comment XPG4 | |
1033 | @deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp}) | |
1034 | The @code{strptime} function parses the input string @var{s} according | |
1035 | to the format string @var{fmt} and stores the found values in the | |
1036 | structure @var{tp}. | |
1037 | ||
1038 | The input string can be retrieved in any way. It does not matter | |
1039 | whether it was generated by a @code{strftime} call or made up directly | |
1040 | by a program. It is also not necessary that the content is in any | |
1041 | human-recognizable format. I.e., it is OK if a date is written like | |
1042 | @code{"02:1999:9"} which is not understandable without context. As long | |
1043 | the format string @var{fmt} matches the format of the input string | |
1044 | everything goes. | |
1045 | ||
1046 | The format string consists of the same components as the format string | |
1047 | for the @code{strftime} function. The only difference is that the flags | |
1048 | @code{_}, @code{-}, @code{0}, and @code{^} are not allowed. | |
1049 | @comment Is this really the intention? --drepper | |
1050 | Several of the formats which @code{strftime} handled differently do the | |
1051 | same work in @code{strptime} since differences like case of the output | |
1052 | do not matter. For symmetry reasons all formats are supported, though. | |
1053 | ||
1054 | The modifiers @code{E} and @code{O} are also allowed everywhere the | |
1055 | @code{strftime} function allows them. | |
1056 | ||
1057 | The formats are: | |
1058 | ||
1059 | @table @code | |
1060 | @item %a | |
1061 | @itemx %A | |
1062 | The weekday name according to the current locale, in abbreviated form or | |
1063 | the full name. | |
1064 | ||
1065 | @item %b | |
1066 | @itemx %B | |
1067 | @itemx %h | |
1068 | The month name according to the current locale, in abbreviated form or | |
1069 | the full name. | |
1070 | ||
1071 | @item %c | |
1072 | The date and time representation for the current locale. | |
1073 | ||
1074 | @item %Ec | |
1075 | Like @code{%c} but the locale's alternative date and time format is used. | |
1076 | ||
1077 | @item %C | |
1078 | The century of the year. | |
1079 | ||
1080 | It makes sense to use this format only if the format string also | |
1081 | contains the @code{%y} format. | |
1082 | ||
1083 | @item %EC | |
1084 | The locale's representation of the period. | |
1085 | ||
1086 | Unlike @code{%C} it makes sometimes sense to use this format since in | |
1087 | some cultures it is required to specify years relative to periods | |
1088 | instead of using the Gregorian years. | |
1089 | ||
1090 | @item %d | |
1091 | @item %e | |
1092 | The day of the month as a decimal number (range @code{1} through @code{31}). | |
1093 | Leading zeroes are permitted but not required. | |
1094 | ||
1095 | @item %Od | |
1096 | @itemx %Oe | |
1097 | Same as @code{%d} but the locale's alternative numeric symbols are used. | |
1098 | ||
1099 | Leading zeroes are permitted but not required. | |
1100 | ||
1101 | @item %D | |
1102 | Equivalent to the use of @code{%m/%d/%y} in this place. | |
1103 | ||
1104 | @item %F | |
1105 | Equivalent to the use of @code{%Y-%m-%d} which is the @w{ISO 8601} date | |
1106 | format. | |
1107 | ||
1108 | This is a GNU extension following an @w{ISO C 9X} extension to | |
1109 | @code{strftime}. | |
1110 | ||
1111 | @item %g | |
1112 | The year corresponding to the ISO week number, but without the century | |
1113 | (range @code{00} through @code{99}). | |
1114 | ||
1115 | @emph{Note:} This is not really implemented currently. The format is | |
1116 | recognized, input is consumed but no field in @var{tm} is set. | |
1117 | ||
1118 | This format is a GNU extension following a GNU extension of @code{strftime}. | |
1119 | ||
1120 | @item %G | |
1121 | The year corresponding to the ISO week number. | |
1122 | ||
1123 | @emph{Note:} This is not really implemented currently. The format is | |
1124 | recognized, input is consumed but no field in @var{tm} is set. | |
1125 | ||
1126 | This format is a GNU extension following a GNU extension of @code{strftime}. | |
1127 | ||
1128 | @item %H | |
1129 | @itemx %k | |
1130 | The hour as a decimal number, using a 24-hour clock (range @code{00} through | |
1131 | @code{23}). | |
1132 | ||
1133 | @code{%k} is a GNU extension following a GNU extension of @code{strftime}. | |
1134 | ||
1135 | @item %OH | |
1136 | Same as @code{%H} but using the locale's alternative numeric symbols are used. | |
1137 | ||
1138 | @item %I | |
1139 | @itemx %l | |
1140 | The hour as a decimal number, using a 12-hour clock (range @code{01} through | |
1141 | @code{12}). | |
1142 | ||
1143 | @code{%l} is a GNU extension following a GNU extension of @code{strftime}. | |
1144 | ||
1145 | @item %OI | |
1146 | Same as @code{%I} but using the locale's alternative numeric symbols are used. | |
1147 | ||
1148 | @item %j | |
1149 | The day of the year as a decimal number (range @code{1} through @code{366}). | |
1150 | ||
1151 | Leading zeroes are permitted but not required. | |
1152 | ||
1153 | @item %m | |
1154 | The month as a decimal number (range @code{1} through @code{12}). | |
1155 | ||
1156 | Leading zeroes are permitted but not required. | |
1157 | ||
1158 | @item %Om | |
1159 | Same as @code{%m} but using the locale's alternative numeric symbols are used. | |
1160 | ||
1161 | @item %M | |
1162 | The minute as a decimal number (range @code{0} through @code{59}). | |
1163 | ||
1164 | Leading zeroes are permitted but not required. | |
1165 | ||
1166 | @item %OM | |
1167 | Same as @code{%M} but using the locale's alternative numeric symbols are used. | |
1168 | ||
1169 | @item %n | |
1170 | @itemx %t | |
1171 | Matches any white space. | |
1172 | ||
1173 | @item %p | |
1174 | @item %P | |
1175 | The locale-dependent equivalent to @samp{AM} or @samp{PM}. | |
1176 | ||
1177 | This format is not useful unless @code{%I} or @code{%l} is also used. | |
1178 | Another complication is that the locale might not define these values at | |
1179 | all and therefore the conversion fails. | |
1180 | ||
1181 | @code{%P} is a GNU extension following a GNU extension to @code{strftime}. | |
1182 | ||
1183 | @item %r | |
1184 | The complete time using the AM/PM format of the current locale. | |
1185 | ||
1186 | A complication is that the locale might not define this format at all | |
1187 | and therefore the conversion fails. | |
1188 | ||
1189 | @item %R | |
1190 | The hour and minute in decimal numbers using the format @code{%H:%M}. | |
1191 | ||
1192 | @code{%R} is a GNU extension following a GNU extension to @code{strftime}. | |
1193 | ||
1194 | @item %s | |
1195 | The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. | |
1196 | Leap seconds are not counted unless leap second support is available. | |
1197 | ||
1198 | @code{%s} is a GNU extension following a GNU extension to @code{strftime}. | |
1199 | ||
1200 | @item %S | |
1201 | The seconds as a decimal number (range @code{0} through @code{61}). | |
1202 | ||
1203 | Leading zeroes are permitted but not required. | |
1204 | ||
1205 | Please note the nonsense with @code{61} being allowed. This is what the | |
1206 | Unix specification says. They followed the stupid decision once made to | |
1207 | allow double leap seconds. These do not exist but the myth persists. | |
1208 | ||
1209 | @item %OS | |
1210 | Same as @code{%S} but using the locale's alternative numeric symbols are used. | |
1211 | ||
1212 | @item %T | |
1213 | Equivalent to the use of @code{%H:%M:%S} in this place. | |
1214 | ||
1215 | @item %u | |
1216 | The day of the week as a decimal number (range @code{1} through | |
1217 | @code{7}), Monday being @code{1}. | |
1218 | ||
1219 | Leading zeroes are permitted but not required. | |
1220 | ||
1221 | @emph{Note:} This is not really implemented currently. The format is | |
1222 | recognized, input is consumed but no field in @var{tm} is set. | |
1223 | ||
1224 | @item %U | |
1225 | The week number of the current year as a decimal number (range @code{0} | |
1226 | through @code{53}). | |
1227 | ||
1228 | Leading zeroes are permitted but not required. | |
1229 | ||
1230 | @item %OU | |
1231 | Same as @code{%U} but using the locale's alternative numeric symbols are used. | |
1232 | ||
1233 | @item %V | |
1234 | The @w{ISO 8601:1988} week number as a decimal number (range @code{1} | |
1235 | through @code{53}). | |
1236 | ||
1237 | Leading zeroes are permitted but not required. | |
1238 | ||
1239 | @emph{Note:} This is not really implemented currently. The format is | |
1240 | recognized, input is consumed but no field in @var{tm} is set. | |
1241 | ||
1242 | @item %w | |
1243 | The day of the week as a decimal number (range @code{0} through | |
1244 | @code{6}), Sunday being @code{0}. | |
1245 | ||
1246 | Leading zeroes are permitted but not required. | |
1247 | ||
1248 | @emph{Note:} This is not really implemented currently. The format is | |
1249 | recognized, input is consumed but no field in @var{tm} is set. | |
1250 | ||
1251 | @item %Ow | |
1252 | Same as @code{%w} but using the locale's alternative numeric symbols are used. | |
1253 | ||
1254 | @item %W | |
1255 | The week number of the current year as a decimal number (range @code{0} | |
1256 | through @code{53}). | |
1257 | ||
1258 | Leading zeroes are permitted but not required. | |
1259 | ||
1260 | @emph{Note:} This is not really implemented currently. The format is | |
1261 | recognized, input is consumed but no field in @var{tm} is set. | |
1262 | ||
1263 | @item %OW | |
1264 | Same as @code{%W} but using the locale's alternative numeric symbols are used. | |
1265 | ||
1266 | @item %x | |
1267 | The date using the locale's date format. | |
1268 | ||
1269 | @item %Ex | |
1270 | Like @code{%x} but the locale's alternative data representation is used. | |
1271 | ||
1272 | @item %X | |
1273 | The time using the locale's time format. | |
1274 | ||
1275 | @item %EX | |
1276 | Like @code{%X} but the locale's alternative time representation is used. | |
1277 | ||
1278 | @item %y | |
1279 | The year without a century as a decimal number (range @code{0} through | |
1280 | @code{99}). | |
1281 | ||
1282 | Leading zeroes are permitted but not required. | |
1283 | ||
1284 | Please note that it is at least questionable to use this format without | |
1285 | the @code{%C} format. The @code{strptime} function does regard input | |
1286 | values in the range @math{68} to @math{99} as the years @math{1969} to | |
1287 | @math{1999} and the values @math{0} to @math{68} as the years | |
1288 | @math{2000} to @math{2068}. But maybe this heuristic fails for some | |
1289 | input data. | |
1290 | ||
1291 | Therefore it is best to avoid @code{%y} completely and use @code{%Y} | |
1292 | instead. | |
1293 | ||
1294 | @item %Ey | |
1295 | The offset from @code{%EC} in the locale's alternative representation. | |
1296 | ||
1297 | @item %Oy | |
1298 | The offset of the year (from @code{%C}) using the locale's alternative | |
1299 | numeric symbols. | |
1300 | ||
1301 | @item %Y | |
1302 | The year as a decimal number, using the Gregorian calendar. | |
1303 | ||
1304 | @item %EY | |
1305 | The full alternative year representation. | |
1306 | ||
1307 | @item %z | |
1308 | Equivalent to the use of @code{%a, %d %b %Y %H:%M:%S %z} in this place. | |
1309 | This is the full @w{ISO 8601} date and time format. | |
1310 | ||
1311 | @item %Z | |
1312 | The timezone name. | |
1313 | ||
1314 | @emph{Note:} This is not really implemented currently. The format is | |
1315 | recognized, input is consumed but no field in @var{tm} is set. | |
1316 | ||
1317 | @item %% | |
1318 | A literal @samp{%} character. | |
1319 | @end table | |
1320 | ||
1321 | All other characters in the format string must have a matching character | |
1322 | in the input string. Exceptions are white spaces in the input string | |
1323 | which can match zero or more white space characters in the input string. | |
1324 | ||
1325 | The @code{strptime} function processes the input string from right to | |
1326 | left. Each of the three possible input elements (white space, literal, | |
1327 | or format) are handled one after the other. If the input cannot be | |
1328 | matched to the format string the function stops. The remainder of the | |
1329 | format and input strings are not processed. | |
1330 | ||
1331 | The return value of the function is a pointer to the first character not | |
1332 | processed in this function call. In the case of an error the return | |
1333 | value points to the first character not matched. In case the input | |
1334 | string contains more than required by the format string the return value | |
1335 | points right after the last consumed input character. In case the whole | |
1336 | input string is consumed the return value points to the NUL byte at the | |
1337 | end of the string. | |
1338 | @end deftypefun | |
1339 | ||
1340 | The specification of the function in the XPG standard is rather vague. | |
1341 | It leaves out a few important pieces of information. Most important it | |
1342 | does not specify what happens to those elements of @var{tm} which are | |
1343 | not directly initialized by the different formats. Various | |
1344 | implementations on different Unix systems vary here. | |
1345 | ||
1346 | The GNU libc implementation does not touch those fields which are not | |
1347 | directly initialized. Exceptions are the @code{tm_wday} and | |
1348 | @code{tm_yday} elements which are recomputed if any of the year, month, | |
1349 | or date elements changed. This has two implications: | |
1350 | ||
1351 | @itemize @bullet | |
1352 | @item | |
1353 | Before calling the @code{strptime} function for a new input string one | |
1354 | has to prepare the structure passed in as the @var{tm}. Normally this | |
1355 | will mean that all values are initialized to zero. Alternatively one | |
1356 | can use all fields to values like @code{INT_MAX} which allows to | |
1357 | determine which elements were set by the function call. Zero does not | |
1358 | work here since it is a valid value for many of the fields. | |
1359 | ||
1360 | Careful initialization is necessary if one wants to find out whether a | |
1361 | certain field in @var{tm} was initialized by the function call. | |
1362 | ||
1363 | @item | |
1364 | One can construct a @code{struct tm} value in several @code{strptime} | |
1365 | calls in a row. A useful application of this is for example the parsing | |
1366 | of two separate strings, one containing the date information, the other | |
1367 | the time information. By parsing both one after the other without | |
1368 | clearing the structure in between one can construct a complete | |
1369 | broken-down time. | |
1370 | @end itemize | |
1371 | ||
1372 | The following example shows a function which parses a string which is | |
1373 | supposed to contain the date information in either US style or @w{ISO | |
1374 | 8601} form. | |
1375 | ||
1376 | @smallexample | |
1377 | const char * | |
1378 | parse_date (const char *input, struct tm *tm) | |
1379 | @{ | |
1380 | const char *cp; | |
1381 | ||
1382 | /* @r{First clear the result structure.} */ | |
1383 | memset (tm, '\0', sizeof (*tm)); | |
1384 | ||
1385 | /* @r{Try the ISO format first.} */ | |
1386 | cp = strptime (input, "%F", tm); | |
1387 | if (cp == NULL) | |
1388 | @{ | |
1389 | /* @r{Does not match. Try the US form.} */ | |
1390 | cp = strptime (input, "%D", tm); | |
1391 | @} | |
1392 | ||
1393 | return cp; | |
1394 | @} | |
1395 | @end smallexample | |
1396 | ||
1397 | @node General Time String Parsing | |
1398 | @subsubsection A user-friendlier way to parse times and dates | |
1399 | ||
1400 | The Unix standard defines another function to parse date strings. The | |
1401 | interface is, mildly said, weird. But if this function fits into the | |
1402 | application to be written it is just fine. It is a problem when using | |
1403 | this function in multi-threaded programs or in libraries since it | |
1404 | returns a pointer to a static variable, uses a global variable, and a | |
1405 | global state (an environment variable). | |
1406 | ||
1407 | @comment time.h | |
1408 | @comment Unix98 | |
1409 | @defvar getdate_err | |
1410 | This variable of type @code{int} will contain the error code of the last | |
1411 | unsuccessful call of the @code{getdate} function. Defined values are: | |
1412 | ||
1413 | @table @math | |
1414 | @item 1 | |
1415 | The environment variable @code{DATEMSK} is not defined or null. | |
1416 | @item 2 | |
1417 | The template file denoted by the @code{DATEMSK} environment variable | |
1418 | cannot be opened. | |
1419 | @item 3 | |
1420 | Information about the template file cannot retrieved. | |
1421 | @item 4 | |
1422 | The template file is no regular file. | |
1423 | @item 5 | |
1424 | An I/O error occurred while reading the template file. | |
1425 | @item 6 | |
1426 | Not enough memory available to execute the function. | |
1427 | @item 7 | |
1428 | The template file contains no matching template. | |
1429 | @item 8 | |
1430 | The input string is invalid for a template which would match otherwise. | |
1431 | This includes error like February 31st, or return values which can be | |
1432 | represented using @code{time_t}. | |
1433 | @end table | |
1434 | @end defvar | |
1435 | ||
1436 | @comment time.h | |
1437 | @comment Unix98 | |
1438 | @deftypefun {struct tm *} getdate (const char *@var{string}) | |
1439 | The interface of the @code{getdate} function is the simplest possible | |
1440 | for a function to parse a string and return the value. @var{string} is | |
1441 | the input string and the result is passed to the user in a statically | |
1442 | allocated variable. | |
1443 | ||
1444 | The details about how the string is processed is hidden from the user. | |
1445 | In fact, it can be outside the control of the program. Which formats | |
1446 | are recognized is controlled by the file named by the environment | |
1447 | variable @code{DATEMSK}. The content of the named file should contain | |
1448 | lines of valid format strings which could be passed to @code{strptime}. | |
1449 | ||
1450 | The @code{getdate} function reads these format strings one after the | |
1451 | other and tries to match the input string. The first line which | |
1452 | completely matches the input string is used. | |
1453 | ||
1454 | Elements which were not initialized through the format string get | |
1455 | assigned the values of the time the @code{getdate} function is called. | |
1456 | ||
1457 | The format elements recognized by @code{getdate} are the same as for | |
1458 | @code{strptime}. See above for an explanation. There are only a few | |
1459 | extension to the @code{strptime} behavior: | |
1460 | ||
1461 | @itemize @bullet | |
1462 | @item | |
1463 | If the @code{%Z} format is given the broken-down time is based on the | |
1464 | current time in the timezone matched, not in the current timezone of the | |
1465 | runtime environment. | |
1466 | ||
1467 | @emph{Note}: This is not implemented (currently). The problem is that | |
1468 | timezone names are not unique. If a fixed timezone is assumed for a | |
1469 | given string (say @code{EST} meaning US East Coast time) uses for | |
1470 | countries other than the USA will fail. So far we have found no good | |
1471 | solution for this. | |
1472 | ||
1473 | @item | |
1474 | If only the weekday is specified the selected day depends on the current | |
1475 | date. If the current weekday is greater or equal to the @code{tm_wday} | |
1476 | value this weeks day is selected. Otherwise next weeks day. | |
1477 | ||
1478 | @item | |
1479 | A similar heuristic is used if only the month is given, not the year. | |
1480 | For value corresponding to the current or a later month the current year | |
1481 | s used. Otherwise the next year. The first day of the month is assumed | |
1482 | if it is not explicitly specified. | |
1483 | ||
1484 | @item | |
1485 | The current hour, minute, and second is used if the appropriate value is | |
1486 | not set through the format. | |
1487 | ||
1488 | @item | |
1489 | If no date is given the date for the next day is used if the time is | |
1490 | smaller than the current time. Otherwise it is the same day. | |
1491 | @end itemize | |
1492 | ||
1493 | It should be noted that the format in the template file need not only | |
1494 | contain format elements. The following is a list of possible format | |
1495 | strings (taken from the Unix standard): | |
1496 | ||
1497 | @smallexample | |
1498 | %m | |
1499 | %A %B %d, %Y %H:%M:%S | |
1500 | %A | |
1501 | %B | |
1502 | %m/%d/%y %I %p | |
1503 | %d,%m,%Y %H:%M | |
1504 | at %A the %dst of %B in %Y | |
1505 | run job at %I %p,%B %dnd | |
1506 | %A den %d. %B %Y %H.%M Uhr | |
1507 | @end smallexample | |
1508 | ||
1509 | As one can see the template list can contain very specific strings like | |
1510 | @code{run job at %I %p,%B %dnd}. Using the above list of templates and | |
1511 | assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can get the | |
1512 | The results for the given input. | |
1513 | ||
1514 | @multitable {xxxxxxxxxxxx} {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
1515 | @item Mon @tab %a @tab Mon Sep 22 12:19:47 EDT 1986 | |
1516 | @item Sun @tab %a @tab Sun Sep 28 12:19:47 EDT 1986 | |
1517 | @item Fri @tab %a @tab Fri Sep 26 12:19:47 EDT 1986 | |
1518 | @item September @tab %B @tab Mon Sep 1 12:19:47 EDT 1986 | |
1519 | @item January @tab %B @tab Thu Jan 1 12:19:47 EST 1987 | |
1520 | @item December @tab %B @tab Mon Dec 1 12:19:47 EST 1986 | |
1521 | @item Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986 | |
1522 | @item Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987 | |
1523 | @item Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986 | |
1524 | @item Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989 | |
1525 | @item Fri 9 @tab %a %H @tab Fri Sep 26 09:00:00 EDT 1986 | |
1526 | @item Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987 | |
1527 | @item 10:30 @tab %H:%M @tab Tue Sep 23 10:30:00 EDT 1986 | |
1528 | @item 13:30 @tab %H:%M @tab Mon Sep 22 13:30:00 EDT 1986 | |
1529 | @end multitable | |
1530 | ||
1531 | The return value of the function is a pointer to a static variable of | |
1532 | type @w{@code{struct tm}} or a null pointer if an error occurred. The | |
1533 | result in the variable pointed to by the return value is only valid | |
1534 | until the next @code{getdate} call which makes this function unusable in | |
1535 | multi-threaded applications. | |
1536 | ||
1537 | The @code{errno} variable is @emph{not} changed. Error conditions are | |
1538 | signalled using the global variable @code{getdate_err}. See the | |
1539 | description above for a list of the possible error values. | |
1540 | @end deftypefun | |
1541 | ||
28f540f4 RM |
1542 | @node TZ Variable |
1543 | @subsection Specifying the Time Zone with @code{TZ} | |
1544 | ||
1545 | In POSIX systems, a user can specify the time zone by means of the | |
1546 | @code{TZ} environment variable. For information about how to set | |
1547 | environment variables, see @ref{Environment Variables}. The functions | |
1548 | for accessing the time zone are declared in @file{time.h}. | |
1549 | @pindex time.h | |
1550 | @cindex time zone | |
1551 | ||
1552 | You should not normally need to set @code{TZ}. If the system is | |
f0f1bf85 | 1553 | configured properly, the default time zone will be correct. You might |
28f540f4 | 1554 | set @code{TZ} if you are using a computer over the network from a |
f0f1bf85 | 1555 | different time zone, and would like times reported to you in the time zone |
28f540f4 RM |
1556 | that local for you, rather than what is local for the computer. |
1557 | ||
1558 | In POSIX.1 systems the value of the @code{TZ} variable can be of one of | |
1559 | three formats. With the GNU C library, the most common format is the | |
1560 | last one, which can specify a selection from a large database of time | |
1561 | zone information for many regions of the world. The first two formats | |
1562 | are used to describe the time zone information directly, which is both | |
1563 | more cumbersome and less precise. But the POSIX.1 standard only | |
1564 | specifies the details of the first two formats, so it is good to be | |
1565 | familiar with them in case you come across a POSIX.1 system that doesn't | |
1566 | support a time zone information database. | |
1567 | ||
1568 | The first format is used when there is no Daylight Saving Time (or | |
1569 | summer time) in the local time zone: | |
1570 | ||
1571 | @smallexample | |
1572 | @r{@var{std} @var{offset}} | |
1573 | @end smallexample | |
1574 | ||
1575 | The @var{std} string specifies the name of the time zone. It must be | |
1576 | three or more characters long and must not contain a leading colon or | |
1577 | embedded digits, commas, or plus or minus signs. There is no space | |
1578 | character separating the time zone name from the @var{offset}, so these | |
1579 | restrictions are necessary to parse the specification correctly. | |
1580 | ||
1581 | The @var{offset} specifies the time value one must add to the local time | |
1582 | to get a Coordinated Universal Time value. It has syntax like | |
1583 | [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This | |
1584 | is positive if the local time zone is west of the Prime Meridian and | |
1585 | negative if it is east. The hour must be between @code{0} and | |
01cdeca0 | 1586 | @code{23}, and the minute and seconds between @code{0} and @code{59}. |
28f540f4 RM |
1587 | |
1588 | For example, here is how we would specify Eastern Standard Time, but | |
f0f1bf85 | 1589 | without any daylight saving time alternative: |
28f540f4 RM |
1590 | |
1591 | @smallexample | |
1592 | EST+5 | |
1593 | @end smallexample | |
1594 | ||
1595 | The second format is used when there is Daylight Saving Time: | |
1596 | ||
1597 | @smallexample | |
1598 | @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]} | |
1599 | @end smallexample | |
1600 | ||
1601 | The initial @var{std} and @var{offset} specify the standard time zone, as | |
1602 | described above. The @var{dst} string and @var{offset} specify the name | |
fed8f7f7 | 1603 | and offset for the corresponding daylight saving time zone; if the |
28f540f4 RM |
1604 | @var{offset} is omitted, it defaults to one hour ahead of standard time. |
1605 | ||
f0f1bf85 UD |
1606 | The remainder of the specification describes when daylight saving time is |
1607 | in effect. The @var{start} field is when daylight saving time goes into | |
28f540f4 RM |
1608 | effect and the @var{end} field is when the change is made back to standard |
1609 | time. The following formats are recognized for these fields: | |
1610 | ||
1611 | @table @code | |
1612 | @item J@var{n} | |
1613 | This specifies the Julian day, with @var{n} between @code{1} and @code{365}. | |
1614 | February 29 is never counted, even in leap years. | |
1615 | ||
1616 | @item @var{n} | |
1617 | This specifies the Julian day, with @var{n} between @code{0} and @code{365}. | |
1618 | February 29 is counted in leap years. | |
1619 | ||
1620 | @item M@var{m}.@var{w}.@var{d} | |
1621 | This specifies day @var{d} of week @var{w} of month @var{m}. The day | |
1622 | @var{d} must be between @code{0} (Sunday) and @code{6}. The week | |
1623 | @var{w} must be between @code{1} and @code{5}; week @code{1} is the | |
1624 | first week in which day @var{d} occurs, and week @code{5} specifies the | |
1625 | @emph{last} @var{d} day in the month. The month @var{m} should be | |
1626 | between @code{1} and @code{12}. | |
1627 | @end table | |
1628 | ||
1629 | The @var{time} fields specify when, in the local time currently in | |
1630 | effect, the change to the other time occurs. If omitted, the default is | |
1631 | @code{02:00:00}. | |
1632 | ||
1633 | For example, here is how one would specify the Eastern time zone in the | |
1634 | United States, including the appropriate daylight saving time and its dates | |
f0f1bf85 | 1635 | of applicability. The normal offset from UTC is 5 hours; since this is |
28f540f4 RM |
1636 | west of the prime meridian, the sign is positive. Summer time begins on |
1637 | the first Sunday in April at 2:00am, and ends on the last Sunday in October | |
1638 | at 2:00am. | |
1639 | ||
1640 | @smallexample | |
f0f1bf85 | 1641 | EST+5EDT,M4.1.0/2,M10.5.0/2 |
28f540f4 RM |
1642 | @end smallexample |
1643 | ||
f0f1bf85 | 1644 | The schedule of daylight saving time in any particular jurisdiction has |
28f540f4 RM |
1645 | changed over the years. To be strictly correct, the conversion of dates |
1646 | and times in the past should be based on the schedule that was in effect | |
1647 | then. However, this format has no facilities to let you specify how the | |
1648 | schedule has changed from year to year. The most you can do is specify | |
1649 | one particular schedule---usually the present day schedule---and this is | |
1650 | used to convert any date, no matter when. For precise time zone | |
1651 | specifications, it is best to use the time zone information database | |
1652 | (see below). | |
1653 | ||
1654 | The third format looks like this: | |
1655 | ||
1656 | @smallexample | |
1657 | :@var{characters} | |
1658 | @end smallexample | |
1659 | ||
1660 | Each operating system interprets this format differently; in the GNU C | |
1661 | library, @var{characters} is the name of a file which describes the time | |
1662 | zone. | |
1663 | ||
1664 | @pindex /etc/localtime | |
1665 | @pindex localtime | |
1666 | If the @code{TZ} environment variable does not have a value, the | |
1667 | operation chooses a time zone by default. In the GNU C library, the | |
1668 | default time zone is like the specification @samp{TZ=:/etc/localtime} | |
1669 | (or @samp{TZ=:/usr/local/etc/localtime}, depending on how GNU C library | |
1670 | was configured; @pxref{Installation}). Other C libraries use their own | |
1671 | rule for choosing the default time zone, so there is little we can say | |
1672 | about them. | |
1673 | ||
1674 | @cindex time zone database | |
1675 | @pindex /share/lib/zoneinfo | |
1676 | @pindex zoneinfo | |
1677 | If @var{characters} begins with a slash, it is an absolute file name; | |
1678 | otherwise the library looks for the file | |
1679 | @w{@file{/share/lib/zoneinfo/@var{characters}}}. The @file{zoneinfo} | |
1680 | directory contains data files describing local time zones in many | |
1681 | different parts of the world. The names represent major cities, with | |
1682 | subdirectories for geographical areas; for example, | |
1683 | @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}. | |
1684 | These data files are installed by the system administrator, who also | |
1685 | sets @file{/etc/localtime} to point to the data file for the local time | |
1686 | zone. The GNU C library comes with a large database of time zone | |
1687 | information for most regions of the world, which is maintained by a | |
1688 | community of volunteers and put in the public domain. | |
1689 | ||
1690 | @node Time Zone Functions | |
1691 | @subsection Functions and Variables for Time Zones | |
1692 | ||
1693 | @comment time.h | |
1694 | @comment POSIX.1 | |
2c6fe0bd | 1695 | @deftypevar {char *} tzname [2] |
28f540f4 | 1696 | The array @code{tzname} contains two strings, which are the standard |
60092701 | 1697 | names of the pair of time zones (standard and daylight |
f0f1bf85 | 1698 | saving) that the user has selected. @code{tzname[0]} is the name of |
28f540f4 | 1699 | the standard time zone (for example, @code{"EST"}), and @code{tzname[1]} |
f0f1bf85 | 1700 | is the name for the time zone when daylight saving time is in use (for |
28f540f4 | 1701 | example, @code{"EDT"}). These correspond to the @var{std} and @var{dst} |
f0f1bf85 UD |
1702 | strings (respectively) from the @code{TZ} environment variable. If |
1703 | daylight saving time is never used, @code{tzname[1]} is the empty string. | |
28f540f4 RM |
1704 | |
1705 | The @code{tzname} array is initialized from the @code{TZ} environment | |
1706 | variable whenever @code{tzset}, @code{ctime}, @code{strftime}, | |
f0f1bf85 UD |
1707 | @code{mktime}, or @code{localtime} is called. If multiple abbreviations |
1708 | have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War | |
1709 | Time and Eastern Daylight Time), the array contains the most recent | |
1710 | abbreviation. | |
1711 | ||
1712 | The @code{tzname} array is required for POSIX.1 compatibility, but in | |
1713 | GNU programs it is better to use the @code{tm_zone} member of the | |
1714 | broken-down time structure, since @code{tm_zone} reports the correct | |
1715 | abbreviation even when it is not the latest one. | |
1716 | ||
0413b54c | 1717 | Though the strings are declared as @code{char *} the user must stay away |
f2ea0f5b | 1718 | from modifying these strings. Modifying the strings will almost certainly |
0413b54c UD |
1719 | lead to trouble. |
1720 | ||
28f540f4 RM |
1721 | @end deftypevar |
1722 | ||
1723 | @comment time.h | |
1724 | @comment POSIX.1 | |
1725 | @deftypefun void tzset (void) | |
1726 | The @code{tzset} function initializes the @code{tzname} variable from | |
1727 | the value of the @code{TZ} environment variable. It is not usually | |
1728 | necessary for your program to call this function, because it is called | |
1729 | automatically when you use the other time conversion functions that | |
1730 | depend on the time zone. | |
1731 | @end deftypefun | |
1732 | ||
1733 | The following variables are defined for compatibility with System V | |
f0f1bf85 UD |
1734 | Unix. Like @code{tzname}, these variables are set by calling |
1735 | @code{tzset} or the other time conversion functions. | |
28f540f4 RM |
1736 | |
1737 | @comment time.h | |
1738 | @comment SVID | |
1739 | @deftypevar {long int} timezone | |
f0f1bf85 UD |
1740 | This contains the difference between UTC and the latest local standard |
1741 | time, in seconds west of UTC. For example, in the U.S. Eastern time | |
1742 | zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member | |
1743 | of the broken-down time structure, this value is not adjusted for | |
1744 | daylight saving, and its sign is reversed. In GNU programs it is better | |
1745 | to use @code{tm_gmtoff}, since it contains the correct offset even when | |
1746 | it is not the latest one. | |
28f540f4 RM |
1747 | @end deftypevar |
1748 | ||
1749 | @comment time.h | |
1750 | @comment SVID | |
1751 | @deftypevar int daylight | |
60092701 RM |
1752 | This variable has a nonzero value if daylight savings time rules apply. |
1753 | A nonzero value does not necessarily mean that daylight savings time is | |
1754 | now in effect; it means only that daylight savings time is sometimes in | |
1755 | effect. | |
28f540f4 RM |
1756 | @end deftypevar |
1757 | ||
1758 | @node Time Functions Example | |
1759 | @subsection Time Functions Example | |
1760 | ||
1761 | Here is an example program showing the use of some of the local time and | |
1762 | calendar time functions. | |
1763 | ||
1764 | @smallexample | |
1765 | @include strftim.c.texi | |
1766 | @end smallexample | |
1767 | ||
1768 | It produces output like this: | |
1769 | ||
1770 | @smallexample | |
1771 | Wed Jul 31 13:02:36 1991 | |
1772 | Today is Wednesday, July 31. | |
1773 | The time is 01:02 PM. | |
1774 | @end smallexample | |
1775 | ||
1776 | ||
1777 | @node Setting an Alarm | |
1778 | @section Setting an Alarm | |
1779 | ||
1780 | The @code{alarm} and @code{setitimer} functions provide a mechanism for a | |
1781 | process to interrupt itself at some future time. They do this by setting a | |
1782 | timer; when the timer expires, the process receives a signal. | |
1783 | ||
1784 | @cindex setting an alarm | |
1785 | @cindex interval timer, setting | |
1786 | @cindex alarms, setting | |
1787 | @cindex timers, setting | |
1788 | Each process has three independent interval timers available: | |
1789 | ||
1790 | @itemize @bullet | |
01cdeca0 | 1791 | @item |
28f540f4 RM |
1792 | A real-time timer that counts clock time. This timer sends a |
1793 | @code{SIGALRM} signal to the process when it expires. | |
1794 | @cindex real-time timer | |
1795 | @cindex timer, real-time | |
1796 | ||
01cdeca0 | 1797 | @item |
28f540f4 RM |
1798 | A virtual timer that counts CPU time used by the process. This timer |
1799 | sends a @code{SIGVTALRM} signal to the process when it expires. | |
1800 | @cindex virtual timer | |
1801 | @cindex timer, virtual | |
1802 | ||
01cdeca0 | 1803 | @item |
28f540f4 RM |
1804 | A profiling timer that counts both CPU time used by the process, and CPU |
1805 | time spent in system calls on behalf of the process. This timer sends a | |
1806 | @code{SIGPROF} signal to the process when it expires. | |
1807 | @cindex profiling timer | |
1808 | @cindex timer, profiling | |
1809 | ||
1810 | This timer is useful for profiling in interpreters. The interval timer | |
1811 | mechanism does not have the fine granularity necessary for profiling | |
1812 | native code. | |
1813 | @c @xref{profil} !!! | |
1814 | @end itemize | |
1815 | ||
1816 | You can only have one timer of each kind set at any given time. If you | |
1817 | set a timer that has not yet expired, that timer is simply reset to the | |
1818 | new value. | |
1819 | ||
1820 | You should establish a handler for the appropriate alarm signal using | |
1821 | @code{signal} or @code{sigaction} before issuing a call to @code{setitimer} | |
1822 | or @code{alarm}. Otherwise, an unusual chain of events could cause the | |
1823 | timer to expire before your program establishes the handler, and in that | |
1824 | case it would be terminated, since that is the default action for the alarm | |
1825 | signals. @xref{Signal Handling}. | |
1826 | ||
1827 | The @code{setitimer} function is the primary means for setting an alarm. | |
1828 | This facility is declared in the header file @file{sys/time.h}. The | |
1829 | @code{alarm} function, declared in @file{unistd.h}, provides a somewhat | |
1830 | simpler interface for setting the real-time timer. | |
1831 | @pindex unistd.h | |
1832 | @pindex sys/time.h | |
1833 | ||
1834 | @comment sys/time.h | |
1835 | @comment BSD | |
1836 | @deftp {Data Type} {struct itimerval} | |
1837 | This structure is used to specify when a timer should expire. It contains | |
1838 | the following members: | |
1839 | @table @code | |
1840 | @item struct timeval it_interval | |
1841 | This is the interval between successive timer interrupts. If zero, the | |
1842 | alarm will only be sent once. | |
1843 | ||
1844 | @item struct timeval it_value | |
1845 | This is the interval to the first timer interrupt. If zero, the alarm is | |
1846 | disabled. | |
1847 | @end table | |
1848 | ||
1849 | The @code{struct timeval} data type is described in @ref{High-Resolution | |
1850 | Calendar}. | |
1851 | @end deftp | |
1852 | ||
1853 | @comment sys/time.h | |
1854 | @comment BSD | |
1855 | @deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old}) | |
01cdeca0 | 1856 | The @code{setitimer} function sets the timer specified by @var{which} |
28f540f4 RM |
1857 | according to @var{new}. The @var{which} argument can have a value of |
1858 | @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}. | |
1859 | ||
1860 | If @var{old} is not a null pointer, @code{setitimer} returns information | |
1861 | about any previous unexpired timer of the same kind in the structure it | |
1862 | points to. | |
1863 | ||
1864 | The return value is @code{0} on success and @code{-1} on failure. The | |
1865 | following @code{errno} error conditions are defined for this function: | |
1866 | ||
1867 | @table @code | |
1868 | @item EINVAL | |
1869 | The timer interval was too large. | |
1870 | @end table | |
1871 | @end deftypefun | |
1872 | ||
1873 | @comment sys/time.h | |
1874 | @comment BSD | |
1875 | @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old}) | |
1876 | The @code{getitimer} function stores information about the timer specified | |
1877 | by @var{which} in the structure pointed at by @var{old}. | |
1878 | ||
1879 | The return value and error conditions are the same as for @code{setitimer}. | |
1880 | @end deftypefun | |
1881 | ||
1882 | @comment sys/time.h | |
1883 | @comment BSD | |
1884 | @table @code | |
1885 | @item ITIMER_REAL | |
1886 | @findex ITIMER_REAL | |
1887 | This constant can be used as the @var{which} argument to the | |
1888 | @code{setitimer} and @code{getitimer} functions to specify the real-time | |
1889 | timer. | |
1890 | ||
1891 | @comment sys/time.h | |
1892 | @comment BSD | |
1893 | @item ITIMER_VIRTUAL | |
1894 | @findex ITIMER_VIRTUAL | |
1895 | This constant can be used as the @var{which} argument to the | |
1896 | @code{setitimer} and @code{getitimer} functions to specify the virtual | |
1897 | timer. | |
1898 | ||
1899 | @comment sys/time.h | |
1900 | @comment BSD | |
1901 | @item ITIMER_PROF | |
1902 | @findex ITIMER_PROF | |
1903 | This constant can be used as the @var{which} argument to the | |
1904 | @code{setitimer} and @code{getitimer} functions to specify the profiling | |
1905 | timer. | |
1906 | @end table | |
1907 | ||
1908 | @comment unistd.h | |
1909 | @comment POSIX.1 | |
1910 | @deftypefun {unsigned int} alarm (unsigned int @var{seconds}) | |
1911 | The @code{alarm} function sets the real-time timer to expire in | |
1912 | @var{seconds} seconds. If you want to cancel any existing alarm, you | |
1913 | can do this by calling @code{alarm} with a @var{seconds} argument of | |
1914 | zero. | |
1915 | ||
1916 | The return value indicates how many seconds remain before the previous | |
1917 | alarm would have been sent. If there is no previous alarm, @code{alarm} | |
1918 | returns zero. | |
1919 | @end deftypefun | |
1920 | ||
1921 | The @code{alarm} function could be defined in terms of @code{setitimer} | |
1922 | like this: | |
1923 | ||
1924 | @smallexample | |
1925 | unsigned int | |
1926 | alarm (unsigned int seconds) | |
1927 | @{ | |
1928 | struct itimerval old, new; | |
1929 | new.it_interval.tv_usec = 0; | |
1930 | new.it_interval.tv_sec = 0; | |
1931 | new.it_value.tv_usec = 0; | |
1932 | new.it_value.tv_sec = (long int) seconds; | |
1933 | if (setitimer (ITIMER_REAL, &new, &old) < 0) | |
1934 | return 0; | |
1935 | else | |
1936 | return old.it_value.tv_sec; | |
1937 | @} | |
1938 | @end smallexample | |
1939 | ||
1940 | There is an example showing the use of the @code{alarm} function in | |
1941 | @ref{Handler Returns}. | |
1942 | ||
1943 | If you simply want your process to wait for a given number of seconds, | |
1944 | you should use the @code{sleep} function. @xref{Sleeping}. | |
1945 | ||
1946 | You shouldn't count on the signal arriving precisely when the timer | |
1947 | expires. In a multiprocessing environment there is typically some | |
1948 | amount of delay involved. | |
1949 | ||
1950 | @strong{Portability Note:} The @code{setitimer} and @code{getitimer} | |
1951 | functions are derived from BSD Unix, while the @code{alarm} function is | |
1952 | specified by the POSIX.1 standard. @code{setitimer} is more powerful than | |
1953 | @code{alarm}, but @code{alarm} is more widely used. | |
1954 | ||
1955 | @node Sleeping | |
1956 | @section Sleeping | |
1957 | ||
1958 | The function @code{sleep} gives a simple way to make the program wait | |
1959 | for short periods of time. If your program doesn't use signals (except | |
1960 | to terminate), then you can expect @code{sleep} to wait reliably for | |
1961 | the specified amount of time. Otherwise, @code{sleep} can return sooner | |
1962 | if a signal arrives; if you want to wait for a given period regardless | |
1963 | of signals, use @code{select} (@pxref{Waiting for I/O}) and don't | |
1964 | specify any descriptors to wait for. | |
1965 | @c !!! select can get EINTR; using SA_RESTART makes sleep win too. | |
1966 | ||
1967 | @comment unistd.h | |
1968 | @comment POSIX.1 | |
1969 | @deftypefun {unsigned int} sleep (unsigned int @var{seconds}) | |
1970 | The @code{sleep} function waits for @var{seconds} or until a signal | |
01cdeca0 | 1971 | is delivered, whichever happens first. |
28f540f4 RM |
1972 | |
1973 | If @code{sleep} function returns because the requested time has | |
1974 | elapsed, it returns a value of zero. If it returns because of delivery | |
1975 | of a signal, its return value is the remaining time in the sleep period. | |
1976 | ||
1977 | The @code{sleep} function is declared in @file{unistd.h}. | |
1978 | @end deftypefun | |
1979 | ||
1980 | Resist the temptation to implement a sleep for a fixed amount of time by | |
1981 | using the return value of @code{sleep}, when nonzero, to call | |
1982 | @code{sleep} again. This will work with a certain amount of accuracy as | |
1983 | long as signals arrive infrequently. But each signal can cause the | |
1984 | eventual wakeup time to be off by an additional second or so. Suppose a | |
1985 | few signals happen to arrive in rapid succession by bad luck---there is | |
1986 | no limit on how much this could shorten or lengthen the wait. | |
1987 | ||
1988 | Instead, compute the time at which the program should stop waiting, and | |
1989 | keep trying to wait until that time. This won't be off by more than a | |
1990 | second. With just a little more work, you can use @code{select} and | |
1991 | make the waiting period quite accurate. (Of course, heavy system load | |
01cdeca0 | 1992 | can cause unavoidable additional delays---unless the machine is |
28f540f4 RM |
1993 | dedicated to one application, there is no way you can avoid this.) |
1994 | ||
1995 | On some systems, @code{sleep} can do strange things if your program uses | |
1996 | @code{SIGALRM} explicitly. Even if @code{SIGALRM} signals are being | |
1997 | ignored or blocked when @code{sleep} is called, @code{sleep} might | |
1998 | return prematurely on delivery of a @code{SIGALRM} signal. If you have | |
1999 | established a handler for @code{SIGALRM} signals and a @code{SIGALRM} | |
2000 | signal is delivered while the process is sleeping, the action taken | |
2001 | might be just to cause @code{sleep} to return instead of invoking your | |
2002 | handler. And, if @code{sleep} is interrupted by delivery of a signal | |
2003 | whose handler requests an alarm or alters the handling of @code{SIGALRM}, | |
2004 | this handler and @code{sleep} will interfere. | |
2005 | ||
2006 | On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in | |
2007 | the same program, because @code{sleep} does not work by means of | |
2008 | @code{SIGALRM}. | |
2009 | ||
dfd2257a UD |
2010 | @comment time.h |
2011 | @comment POSIX.1 | |
2012 | @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) | |
2013 | If the resolution of seconds is not enough the @code{nanosleep} function | |
2014 | can be used. As the name suggests the sleeping period can be specified | |
2015 | in nanoseconds. The actual period of waiting time might be longer since | |
2016 | the requested time in the @var{requested_time} parameter is rounded up | |
2017 | to the next integer multiple of the actual resolution of the system. | |
2018 | ||
2019 | If the function returns because the time has elapsed the return value is | |
2020 | zero. If the function return @math{-1} the global variable @var{errno} | |
2021 | is set to the following values: | |
2022 | ||
2023 | @table @code | |
2024 | @item EINTR | |
2025 | The call was interrupted because a signal was delivered to the thread. | |
2026 | If the @var{remaining} parameter is not the null pointer the structure | |
2027 | pointed to by @var{remaining} is updated to contain the remaining time. | |
2028 | ||
2029 | @item EINVAL | |
2030 | The nanosecond value in the @var{requested_time} parameter contains an | |
2031 | illegal value. Either the value is negative or greater than or equal to | |
2032 | 1000 million. | |
2033 | @end table | |
2034 | ||
2035 | This function is a cancelation point in multi-threaded programs. This | |
2036 | is a problem if the thread allocates some resources (like memory, file | |
2037 | descriptors, semaphores or whatever) at the time @code{nanosleep} is | |
2038 | called. If the thread gets canceled these resources stay allocated | |
2039 | until the program ends. To avoid this calls to @code{nanosleep} should | |
2040 | be protected using cancelation handlers. | |
2041 | @c ref pthread_cleanup_push / pthread_cleanup_pop | |
2042 | ||
2043 | The @code{nanosleep} function is declared in @file{time.h}. | |
2044 | @end deftypefun | |
2045 | ||
28f540f4 RM |
2046 | @node Resource Usage |
2047 | @section Resource Usage | |
2048 | ||
2049 | @pindex sys/resource.h | |
2050 | The function @code{getrusage} and the data type @code{struct rusage} | |
2051 | are used for examining the usage figures of a process. They are declared | |
2052 | in @file{sys/resource.h}. | |
2053 | ||
2054 | @comment sys/resource.h | |
2055 | @comment BSD | |
2056 | @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) | |
2057 | This function reports the usage totals for processes specified by | |
2058 | @var{processes}, storing the information in @code{*@var{rusage}}. | |
2059 | ||
2060 | In most systems, @var{processes} has only two valid values: | |
2061 | ||
2062 | @table @code | |
2063 | @comment sys/resource.h | |
2064 | @comment BSD | |
2065 | @item RUSAGE_SELF | |
2066 | Just the current process. | |
2067 | ||
2068 | @comment sys/resource.h | |
2069 | @comment BSD | |
2070 | @item RUSAGE_CHILDREN | |
2071 | All child processes (direct and indirect) that have terminated already. | |
2072 | @end table | |
2073 | ||
2074 | In the GNU system, you can also inquire about a particular child process | |
2075 | by specifying its process ID. | |
2076 | ||
2077 | The return value of @code{getrusage} is zero for success, and @code{-1} | |
2078 | for failure. | |
2079 | ||
2080 | @table @code | |
2081 | @item EINVAL | |
2082 | The argument @var{processes} is not valid. | |
2083 | @end table | |
2084 | @end deftypefun | |
2085 | ||
2086 | One way of getting usage figures for a particular child process is with | |
2087 | the function @code{wait4}, which returns totals for a child when it | |
2088 | terminates. @xref{BSD Wait Functions}. | |
2089 | ||
2090 | @comment sys/resource.h | |
2091 | @comment BSD | |
2092 | @deftp {Data Type} {struct rusage} | |
2093 | This data type records a collection usage amounts for various sorts of | |
2094 | resources. It has the following members, and possibly others: | |
2095 | ||
2096 | @table @code | |
2097 | @item struct timeval ru_utime | |
2098 | Time spent executing user instructions. | |
2099 | ||
2100 | @item struct timeval ru_stime | |
2101 | Time spent in operating system code on behalf of @var{processes}. | |
2102 | ||
2103 | @item long int ru_maxrss | |
2104 | The maximum resident set size used, in kilobytes. That is, the maximum | |
2105 | number of kilobytes that @var{processes} used in real memory simultaneously. | |
2106 | ||
2107 | @item long int ru_ixrss | |
2108 | An integral value expressed in kilobytes times ticks of execution, which | |
2109 | indicates the amount of memory used by text that was shared with other | |
2110 | processes. | |
2111 | ||
2112 | @item long int ru_idrss | |
2113 | An integral value expressed the same way, which is the amount of | |
2114 | unshared memory used in data. | |
2115 | ||
2116 | @item long int ru_isrss | |
2117 | An integral value expressed the same way, which is the amount of | |
2118 | unshared memory used in stack space. | |
2119 | ||
2120 | @item long int ru_minflt | |
2121 | The number of page faults which were serviced without requiring any I/O. | |
2122 | ||
2123 | @item long int ru_majflt | |
2124 | The number of page faults which were serviced by doing I/O. | |
2125 | ||
2126 | @item long int ru_nswap | |
2127 | The number of times @var{processes} was swapped entirely out of main memory. | |
2128 | ||
2129 | @item long int ru_inblock | |
2130 | The number of times the file system had to read from the disk on behalf | |
2131 | of @var{processes}. | |
2132 | ||
2133 | @item long int ru_oublock | |
2134 | The number of times the file system had to write to the disk on behalf | |
2135 | of @var{processes}. | |
2136 | ||
2137 | @item long int ru_msgsnd | |
2138 | Number of IPC messages sent. | |
2139 | ||
2140 | @item long ru_msgrcv | |
2141 | Number of IPC messages received. | |
2142 | ||
2143 | @item long int ru_nsignals | |
2144 | Number of signals received. | |
2145 | ||
2146 | @item long int ru_nvcsw | |
2147 | The number of times @var{processes} voluntarily invoked a context switch | |
2148 | (usually to wait for some service). | |
2149 | ||
2150 | @item long int ru_nivcsw | |
2151 | The number of times an involuntary context switch took place (because | |
2152 | the time slice expired, or another process of higher priority became | |
2153 | runnable). | |
2154 | @end table | |
2155 | @end deftp | |
2156 | ||
2157 | An additional historical function for examining usage figures, | |
2158 | @code{vtimes}, is supported but not documented here. It is declared in | |
2159 | @file{sys/vtimes.h}. | |
2160 | ||
2161 | @node Limits on Resources | |
2162 | @section Limiting Resource Usage | |
2163 | @cindex resource limits | |
2164 | @cindex limits on resource usage | |
2165 | @cindex usage limits | |
2166 | ||
2167 | You can specify limits for the resource usage of a process. When the | |
2168 | process tries to exceed a limit, it may get a signal, or the system call | |
2169 | by which it tried to do so may fail, depending on the limit. Each | |
2170 | process initially inherits its limit values from its parent, but it can | |
2171 | subsequently change them. | |
2172 | ||
2173 | @pindex sys/resource.h | |
2174 | The symbols in this section are defined in @file{sys/resource.h}. | |
2175 | ||
2176 | @comment sys/resource.h | |
2177 | @comment BSD | |
2178 | @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) | |
2179 | Read the current value and the maximum value of resource @var{resource} | |
2180 | and store them in @code{*@var{rlp}}. | |
2181 | ||
2182 | The return value is @code{0} on success and @code{-1} on failure. The | |
2183 | only possible @code{errno} error condition is @code{EFAULT}. | |
a3a4a74e UD |
2184 | |
2185 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
2186 | 32 bits system this function is in fact @code{getrlimit64}. I.e., the | |
2187 | LFS interface transparently replaces the old interface. | |
2188 | @end deftypefun | |
2189 | ||
2190 | @comment sys/resource.h | |
2191 | @comment Unix98 | |
2192 | @deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) | |
2193 | This function is similar to the @code{getrlimit} but its second | |
2194 | parameter is a pointer to a variable of type @code{struct rlimit64} | |
2195 | which allows this function to read values which wouldn't fit in the | |
2196 | member of a @code{struct rlimit}. | |
2197 | ||
2198 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 | |
2199 | bits machine this function is available under the name @code{getrlimit} | |
2200 | and so transparently replaces the old interface. | |
28f540f4 RM |
2201 | @end deftypefun |
2202 | ||
2203 | @comment sys/resource.h | |
2204 | @comment BSD | |
a3a4a74e | 2205 | @deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) |
28f540f4 RM |
2206 | Store the current value and the maximum value of resource @var{resource} |
2207 | in @code{*@var{rlp}}. | |
2208 | ||
2209 | The return value is @code{0} on success and @code{-1} on failure. The | |
2210 | following @code{errno} error condition is possible: | |
2211 | ||
2212 | @table @code | |
2213 | @item EPERM | |
2214 | You tried to change the maximum permissible limit value, | |
2215 | but you don't have privileges to do so. | |
2216 | @end table | |
a3a4a74e UD |
2217 | |
2218 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
2219 | 32 bits system this function is in fact @code{setrlimit64}. I.e., the | |
2220 | LFS interface transparently replaces the old interface. | |
2221 | @end deftypefun | |
2222 | ||
2223 | @comment sys/resource.h | |
2224 | @comment Unix98 | |
2225 | @deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) | |
2226 | This function is similar to the @code{setrlimit} but its second | |
2227 | parameter is a pointer to a variable of type @code{struct rlimit64} | |
2228 | which allows this function to set values which wouldn't fit in the | |
2229 | member of a @code{struct rlimit}. | |
2230 | ||
2231 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 | |
2232 | bits machine this function is available under the name @code{setrlimit} | |
2233 | and so transparently replaces the old interface. | |
28f540f4 RM |
2234 | @end deftypefun |
2235 | ||
2236 | @comment sys/resource.h | |
2237 | @comment BSD | |
2238 | @deftp {Data Type} {struct rlimit} | |
2239 | This structure is used with @code{getrlimit} to receive limit values, | |
2240 | and with @code{setrlimit} to specify limit values. It has two fields: | |
2241 | ||
2242 | @table @code | |
a3a4a74e | 2243 | @item rlim_t rlim_cur |
28f540f4 RM |
2244 | The current value of the limit in question. |
2245 | This is also called the ``soft limit''. | |
2246 | @cindex soft limit | |
2247 | ||
a3a4a74e | 2248 | @item rlim_t rlim_max |
28f540f4 RM |
2249 | The maximum permissible value of the limit in question. You cannot set |
2250 | the current value of the limit to a larger number than this maximum. | |
2251 | Only the super user can change the maximum permissible value. | |
2252 | This is also called the ``hard limit''. | |
2253 | @cindex hard limit | |
2254 | @end table | |
2255 | ||
2256 | In @code{getrlimit}, the structure is an output; it receives the current | |
2257 | values. In @code{setrlimit}, it specifies the new values. | |
2258 | @end deftp | |
2259 | ||
a3a4a74e UD |
2260 | For the LFS functions a similar type is defined in @file{sys/resource.h}. |
2261 | ||
2262 | @comment sys/resource.h | |
2263 | @comment Unix98 | |
2264 | @deftp {Data Type} {struct rlimit64} | |
2265 | This structure is used with @code{getrlimit64} to receive limit values, | |
2266 | and with @code{setrlimit64} to specify limit values. It has two fields: | |
2267 | ||
2268 | @table @code | |
2269 | @item rlim64_t rlim_cur | |
2270 | The current value of the limit in question. | |
2271 | This is also called the ``soft limit''. | |
2272 | ||
2273 | @item rlim64_t rlim_max | |
2274 | The maximum permissible value of the limit in question. You cannot set | |
2275 | the current value of the limit to a larger number than this maximum. | |
2276 | Only the super user can change the maximum permissible value. | |
2277 | This is also called the ``hard limit''. | |
2278 | @end table | |
2279 | ||
2280 | In @code{getrlimit64}, the structure is an output; it receives the current | |
2281 | values. In @code{setrlimit64}, it specifies the new values. | |
2282 | @end deftp | |
2283 | ||
28f540f4 RM |
2284 | Here is a list of resources that you can specify a limit for. |
2285 | Those that are sizes are measured in bytes. | |
2286 | ||
2287 | @table @code | |
2288 | @comment sys/resource.h | |
2289 | @comment BSD | |
2290 | @item RLIMIT_CPU | |
2291 | @vindex RLIMIT_CPU | |
2292 | The maximum amount of cpu time the process can use. If it runs for | |
2293 | longer than this, it gets a signal: @code{SIGXCPU}. The value is | |
2294 | measured in seconds. @xref{Operation Error Signals}. | |
2295 | ||
2296 | @comment sys/resource.h | |
2297 | @comment BSD | |
2298 | @item RLIMIT_FSIZE | |
2299 | @vindex RLIMIT_FSIZE | |
2300 | The maximum size of file the process can create. Trying to write a | |
2301 | larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error | |
2302 | Signals}. | |
2303 | ||
2304 | @comment sys/resource.h | |
2305 | @comment BSD | |
2306 | @item RLIMIT_DATA | |
2307 | @vindex RLIMIT_DATA | |
2308 | The maximum size of data memory for the process. If the process tries | |
2309 | to allocate data memory beyond this amount, the allocation function | |
2310 | fails. | |
2311 | ||
2312 | @comment sys/resource.h | |
2313 | @comment BSD | |
2314 | @item RLIMIT_STACK | |
2315 | @vindex RLIMIT_STACK | |
2316 | The maximum stack size for the process. If the process tries to extend | |
2317 | its stack past this size, it gets a @code{SIGSEGV} signal. | |
2318 | @xref{Program Error Signals}. | |
2319 | ||
2320 | @comment sys/resource.h | |
2321 | @comment BSD | |
2322 | @item RLIMIT_CORE | |
2323 | @vindex RLIMIT_CORE | |
2324 | The maximum size core file that this process can create. If the process | |
2325 | terminates and would dump a core file larger than this maximum size, | |
2326 | then no core file is created. So setting this limit to zero prevents | |
2327 | core files from ever being created. | |
2328 | ||
2329 | @comment sys/resource.h | |
2330 | @comment BSD | |
2331 | @item RLIMIT_RSS | |
2332 | @vindex RLIMIT_RSS | |
2333 | The maximum amount of physical memory that this process should get. | |
2334 | This parameter is a guide for the system's scheduler and memory | |
2335 | allocator; the system may give the process more memory when there is a | |
2336 | surplus. | |
2337 | ||
2338 | @comment sys/resource.h | |
2339 | @comment BSD | |
2340 | @item RLIMIT_MEMLOCK | |
2341 | The maximum amount of memory that can be locked into physical memory (so | |
2342 | it will never be paged out). | |
2343 | ||
2344 | @comment sys/resource.h | |
2345 | @comment BSD | |
2346 | @item RLIMIT_NPROC | |
2347 | The maximum number of processes that can be created with the same user ID. | |
2348 | If you have reached the limit for your user ID, @code{fork} will fail | |
2349 | with @code{EAGAIN}. @xref{Creating a Process}. | |
2350 | ||
2351 | @comment sys/resource.h | |
2352 | @comment BSD | |
2353 | @item RLIMIT_NOFILE | |
2354 | @vindex RLIMIT_NOFILE | |
2355 | @itemx RLIMIT_OFILE | |
2356 | @vindex RLIMIT_OFILE | |
2357 | The maximum number of files that the process can open. If it tries to | |
2358 | open more files than this, it gets error code @code{EMFILE}. | |
2359 | @xref{Error Codes}. Not all systems support this limit; GNU does, and | |
2360 | 4.4 BSD does. | |
2361 | ||
2362 | @comment sys/resource.h | |
2363 | @comment BSD | |
2364 | @item RLIM_NLIMITS | |
2365 | @vindex RLIM_NLIMITS | |
2366 | The number of different resource limits. Any valid @var{resource} | |
2367 | operand must be less than @code{RLIM_NLIMITS}. | |
2368 | @end table | |
2369 | ||
2370 | @comment sys/resource.h | |
2371 | @comment BSD | |
310b3460 | 2372 | @deftypevr Constant int RLIM_INFINITY |
28f540f4 RM |
2373 | This constant stands for a value of ``infinity'' when supplied as |
2374 | the limit value in @code{setrlimit}. | |
310b3460 | 2375 | @end deftypevr |
28f540f4 RM |
2376 | |
2377 | @c ??? Someone want to finish these? | |
2378 | Two historical functions for setting resource limits, @code{ulimit} and | |
2379 | @code{vlimit}, are not documented here. The latter is declared in | |
2380 | @file{sys/vlimit.h} and comes from BSD. | |
2381 | ||
2382 | @node Priority | |
2383 | @section Process Priority | |
2384 | @cindex process priority | |
2385 | @cindex priority of a process | |
2386 | ||
2387 | @pindex sys/resource.h | |
2388 | When several processes try to run, their respective priorities determine | |
2389 | what share of the CPU each process gets. This section describes how you | |
2390 | can read and set the priority of a process. All these functions and | |
2391 | macros are declared in @file{sys/resource.h}. | |
2392 | ||
2393 | The range of valid priority values depends on the operating system, but | |
2394 | typically it runs from @code{-20} to @code{20}. A lower priority value | |
2395 | means the process runs more often. These constants describe the range of | |
2396 | priority values: | |
2397 | ||
2398 | @table @code | |
2399 | @comment sys/resource.h | |
2400 | @comment BSD | |
2401 | @item PRIO_MIN | |
2402 | @vindex PRIO_MIN | |
2403 | The smallest valid priority value. | |
2404 | ||
2405 | @comment sys/resource.h | |
2406 | @comment BSD | |
2407 | @item PRIO_MAX | |
2408 | @vindex PRIO_MAX | |
74015205 | 2409 | The largest valid priority value. |
28f540f4 RM |
2410 | @end table |
2411 | ||
2412 | @comment sys/resource.h | |
2413 | @comment BSD | |
2414 | @deftypefun int getpriority (int @var{class}, int @var{id}) | |
2415 | Read the priority of a class of processes; @var{class} and @var{id} | |
2416 | specify which ones (see below). If the processes specified do not all | |
2417 | have the same priority, this returns the smallest value that any of them | |
2418 | has. | |
2419 | ||
2420 | The return value is the priority value on success, and @code{-1} on | |
2421 | failure. The following @code{errno} error condition are possible for | |
2422 | this function: | |
2423 | ||
2424 | @table @code | |
2425 | @item ESRCH | |
2426 | The combination of @var{class} and @var{id} does not match any existing | |
2427 | process. | |
2428 | ||
2429 | @item EINVAL | |
2430 | The value of @var{class} is not valid. | |
2431 | @end table | |
2432 | ||
2433 | When the return value is @code{-1}, it could indicate failure, or it | |
2434 | could be the priority value. The only way to make certain is to set | |
2435 | @code{errno = 0} before calling @code{getpriority}, then use @code{errno | |
2436 | != 0} afterward as the criterion for failure. | |
2437 | @end deftypefun | |
2438 | ||
2439 | @comment sys/resource.h | |
2440 | @comment BSD | |
2441 | @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority}) | |
2442 | Set the priority of a class of processes to @var{priority}; @var{class} | |
2443 | and @var{id} specify which ones (see below). | |
2444 | ||
2445 | The return value is @code{0} on success and @code{-1} on failure. The | |
2446 | following @code{errno} error condition are defined for this function: | |
2447 | ||
2448 | @table @code | |
2449 | @item ESRCH | |
2450 | The combination of @var{class} and @var{id} does not match any existing | |
2451 | process. | |
2452 | ||
2453 | @item EINVAL | |
2454 | The value of @var{class} is not valid. | |
2455 | ||
2456 | @item EPERM | |
2457 | You tried to set the priority of some other user's process, and you | |
2458 | don't have privileges for that. | |
2459 | ||
2460 | @item EACCES | |
2461 | You tried to lower the priority of a process, and you don't have | |
2462 | privileges for that. | |
2463 | @end table | |
2464 | @end deftypefun | |
2465 | ||
2466 | The arguments @var{class} and @var{id} together specify a set of | |
2467 | processes you are interested in. These are the possible values for | |
2468 | @var{class}: | |
2469 | ||
2470 | @table @code | |
2471 | @comment sys/resource.h | |
2472 | @comment BSD | |
2473 | @item PRIO_PROCESS | |
2474 | @vindex PRIO_PROCESS | |
2475 | Read or set the priority of one process. The argument @var{id} is a | |
2476 | process ID. | |
2477 | ||
2478 | @comment sys/resource.h | |
2479 | @comment BSD | |
2480 | @item PRIO_PGRP | |
2481 | @vindex PRIO_PGRP | |
2482 | Read or set the priority of one process group. The argument @var{id} is | |
2483 | a process group ID. | |
2484 | ||
2485 | @comment sys/resource.h | |
2486 | @comment BSD | |
2487 | @item PRIO_USER | |
2488 | @vindex PRIO_USER | |
2489 | Read or set the priority of one user's processes. The argument @var{id} | |
2490 | is a user ID. | |
2491 | @end table | |
2492 | ||
2493 | If the argument @var{id} is 0, it stands for the current process, | |
2494 | current process group, or the current user, according to @var{class}. | |
2495 | ||
2496 | @c ??? I don't know where we should say this comes from. | |
2497 | @comment Unix | |
2498 | @comment dunno.h | |
2499 | @deftypefun int nice (int @var{increment}) | |
2500 | Increment the priority of the current process by @var{increment}. | |
2501 | The return value is the same as for @code{setpriority}. | |
2502 | ||
2503 | Here is an equivalent definition for @code{nice}: | |
2504 | ||
2505 | @smallexample | |
2506 | int | |
2507 | nice (int increment) | |
2508 | @{ | |
2509 | int old = getpriority (PRIO_PROCESS, 0); | |
2510 | return setpriority (PRIO_PROCESS, 0, old + increment); | |
2511 | @} | |
2512 | @end smallexample | |
2513 | @end deftypefun |