]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | @node Date and Time, Non-Local Exits, Arithmetic, Top |
2 | @chapter Date and Time | |
3 | ||
4 | This chapter describes functions for manipulating dates and times, | |
5 | including functions for determining what the current time is and | |
6 | conversion between different time representations. | |
7 | ||
8 | The time functions fall into three main categories: | |
9 | ||
10 | @itemize @bullet | |
01cdeca0 | 11 | @item |
28f540f4 RM |
12 | Functions for measuring elapsed CPU time are discussed in @ref{Processor |
13 | Time}. | |
14 | ||
15 | @item | |
16 | Functions for measuring absolute clock or calendar time are discussed in | |
17 | @ref{Calendar Time}. | |
18 | ||
19 | @item | |
20 | Functions for setting alarms and timers are discussed in @ref{Setting | |
21 | an Alarm}. | |
22 | @end itemize | |
23 | ||
24 | @menu | |
25 | * Processor Time:: Measures processor time used by a program. | |
26 | * Calendar Time:: Manipulation of ``real'' dates and times. | |
27 | * Setting an Alarm:: Sending a signal after a specified time. | |
28 | * Sleeping:: Waiting for a period of time. | |
29 | * Resource Usage:: Measuring various resources used. | |
30 | * Limits on Resources:: Specifying limits on resource usage. | |
31 | * Priority:: Reading or setting process run priority. | |
32 | @end menu | |
33 | ||
34 | @node Processor Time | |
35 | @section Processor Time | |
36 | ||
37 | If you're trying to optimize your program or measure its efficiency, it's | |
38 | very useful to be able to know how much @dfn{processor time} or @dfn{CPU | |
39 | time} it has used at any given point. Processor time is different from | |
40 | actual wall clock time because it doesn't include any time spent waiting | |
41 | for I/O or when some other process is running. Processor time is | |
42 | represented by the data type @code{clock_t}, and is given as a number of | |
43 | @dfn{clock ticks} relative to an arbitrary base time marking the beginning | |
44 | of a single program invocation. | |
45 | @cindex CPU time | |
46 | @cindex processor time | |
47 | @cindex clock ticks | |
48 | @cindex ticks, clock | |
49 | @cindex time, elapsed CPU | |
50 | ||
51 | @menu | |
52 | * Basic CPU Time:: The @code{clock} function. | |
53 | * Detailed CPU Time:: The @code{times} function. | |
54 | @end menu | |
55 | ||
56 | @node Basic CPU Time | |
57 | @subsection Basic CPU Time Inquiry | |
58 | ||
59 | To get the elapsed CPU time used by a process, you can use the | |
60 | @code{clock} function. This facility is declared in the header file | |
61 | @file{time.h}. | |
62 | @pindex time.h | |
63 | ||
64 | In typical usage, you call the @code{clock} function at the beginning and | |
65 | end of the interval you want to time, subtract the values, and then divide | |
66 | by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this: | |
67 | ||
68 | @smallexample | |
69 | @group | |
70 | #include <time.h> | |
71 | ||
72 | clock_t start, end; | |
73 | double elapsed; | |
74 | ||
75 | start = clock(); | |
76 | @dots{} /* @r{Do the work.} */ | |
77 | end = clock(); | |
78 | elapsed = ((double) (end - start)) / CLOCKS_PER_SEC; | |
79 | @end group | |
80 | @end smallexample | |
81 | ||
82 | Different computers and operating systems vary wildly in how they keep | |
83 | track of processor time. It's common for the internal processor clock | |
84 | to have a resolution somewhere between hundredths and millionths of a | |
85 | second. | |
86 | ||
87 | In the GNU system, @code{clock_t} is equivalent to @code{long int} and | |
88 | @code{CLOCKS_PER_SEC} is an integer value. But in other systems, both | |
89 | @code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be | |
90 | either integer or floating-point types. Casting processor time values | |
91 | to @code{double}, as in the example above, makes sure that operations | |
92 | such as arithmetic and printing work properly and consistently no matter | |
93 | what the underlying representation is. | |
94 | ||
95 | @comment time.h | |
f65fd747 | 96 | @comment ISO |
28f540f4 RM |
97 | @deftypevr Macro int CLOCKS_PER_SEC |
98 | The value of this macro is the number of clock ticks per second measured | |
99 | by the @code{clock} function. | |
100 | @end deftypevr | |
101 | ||
102 | @comment time.h | |
103 | @comment POSIX.1 | |
104 | @deftypevr Macro int CLK_TCK | |
01cdeca0 | 105 | This is an obsolete name for @code{CLOCKS_PER_SEC}. |
28f540f4 RM |
106 | @end deftypevr |
107 | ||
108 | @comment time.h | |
f65fd747 | 109 | @comment ISO |
28f540f4 RM |
110 | @deftp {Data Type} clock_t |
111 | This is the type of the value returned by the @code{clock} function. | |
112 | Values of type @code{clock_t} are in units of clock ticks. | |
113 | @end deftp | |
114 | ||
115 | @comment time.h | |
f65fd747 | 116 | @comment ISO |
28f540f4 RM |
117 | @deftypefun clock_t clock (void) |
118 | This function returns the elapsed processor time. The base time is | |
119 | arbitrary but doesn't change within a single process. If the processor | |
120 | time is not available or cannot be represented, @code{clock} returns the | |
121 | value @code{(clock_t)(-1)}. | |
122 | @end deftypefun | |
123 | ||
124 | ||
125 | @node Detailed CPU Time | |
126 | @subsection Detailed Elapsed CPU Time Inquiry | |
127 | ||
128 | The @code{times} function returns more detailed information about | |
129 | elapsed processor time in a @w{@code{struct tms}} object. You should | |
130 | include the header file @file{sys/times.h} to use this facility. | |
131 | @pindex sys/times.h | |
132 | ||
133 | @comment sys/times.h | |
134 | @comment POSIX.1 | |
135 | @deftp {Data Type} {struct tms} | |
136 | The @code{tms} structure is used to return information about process | |
137 | times. It contains at least the following members: | |
138 | ||
139 | @table @code | |
140 | @item clock_t tms_utime | |
141 | This is the CPU time used in executing the instructions of the calling | |
142 | process. | |
143 | ||
144 | @item clock_t tms_stime | |
145 | This is the CPU time used by the system on behalf of the calling process. | |
146 | ||
147 | @item clock_t tms_cutime | |
148 | This is the sum of the @code{tms_utime} values and the @code{tms_cutime} | |
149 | values of all terminated child processes of the calling process, whose | |
150 | status has been reported to the parent process by @code{wait} or | |
151 | @code{waitpid}; see @ref{Process Completion}. In other words, it | |
152 | represents the total CPU time used in executing the instructions of all | |
153 | the terminated child processes of the calling process, excluding child | |
154 | processes which have not yet been reported by @code{wait} or | |
155 | @code{waitpid}. | |
156 | ||
157 | @item clock_t tms_cstime | |
158 | This is similar to @code{tms_cutime}, but represents the total CPU time | |
159 | used by the system on behalf of all the terminated child processes of the | |
160 | calling process. | |
161 | @end table | |
162 | ||
163 | All of the times are given in clock ticks. These are absolute values; in a | |
164 | newly created process, they are all zero. @xref{Creating a Process}. | |
165 | @end deftp | |
166 | ||
167 | @comment sys/times.h | |
168 | @comment POSIX.1 | |
169 | @deftypefun clock_t times (struct tms *@var{buffer}) | |
170 | The @code{times} function stores the processor time information for | |
171 | the calling process in @var{buffer}. | |
172 | ||
173 | The return value is the same as the value of @code{clock()}: the elapsed | |
174 | real time relative to an arbitrary base. The base is a constant within a | |
175 | particular process, and typically represents the time since system | |
176 | start-up. A value of @code{(clock_t)(-1)} is returned to indicate failure. | |
177 | @end deftypefun | |
178 | ||
179 | @strong{Portability Note:} The @code{clock} function described in | |
f65fd747 | 180 | @ref{Basic CPU Time}, is specified by the @w{ISO C} standard. The |
28f540f4 RM |
181 | @code{times} function is a feature of POSIX.1. In the GNU system, the |
182 | value returned by the @code{clock} function is equivalent to the sum of | |
183 | the @code{tms_utime} and @code{tms_stime} fields returned by | |
184 | @code{times}. | |
185 | ||
186 | @node Calendar Time | |
187 | @section Calendar Time | |
188 | ||
189 | This section describes facilities for keeping track of dates and times | |
190 | according to the Gregorian calendar. | |
191 | @cindex Gregorian calendar | |
192 | @cindex time, calendar | |
193 | @cindex date and time | |
194 | ||
195 | There are three representations for date and time information: | |
196 | ||
197 | @itemize @bullet | |
01cdeca0 RM |
198 | @item |
199 | @dfn{Calendar time} (the @code{time_t} data type) is a compact | |
28f540f4 RM |
200 | representation, typically giving the number of seconds elapsed since |
201 | some implementation-specific base time. | |
202 | @cindex calendar time | |
203 | ||
204 | @item | |
205 | There is also a @dfn{high-resolution time} representation (the @code{struct | |
206 | timeval} data type) that includes fractions of a second. Use this time | |
207 | representation instead of ordinary calendar time when you need greater | |
208 | precision. | |
209 | @cindex high-resolution time | |
210 | ||
211 | @item | |
212 | @dfn{Local time} or @dfn{broken-down time} (the @code{struct | |
213 | tm} data type) represents the date and time as a set of components | |
214 | specifying the year, month, and so on, for a specific time zone. | |
215 | This time representation is usually used in conjunction with formatting | |
216 | date and time values. | |
217 | @cindex local time | |
218 | @cindex broken-down time | |
219 | @end itemize | |
220 | ||
221 | @menu | |
222 | * Simple Calendar Time:: Facilities for manipulating calendar time. | |
223 | * High-Resolution Calendar:: A time representation with greater precision. | |
224 | * Broken-down Time:: Facilities for manipulating local time. | |
225 | * Formatting Date and Time:: Converting times to strings. | |
226 | * TZ Variable:: How users specify the time zone. | |
01cdeca0 | 227 | * Time Zone Functions:: Functions to examine or specify the time zone. |
28f540f4 RM |
228 | * Time Functions Example:: An example program showing use of some of |
229 | the time functions. | |
230 | @end menu | |
231 | ||
232 | @node Simple Calendar Time | |
233 | @subsection Simple Calendar Time | |
234 | ||
235 | This section describes the @code{time_t} data type for representing | |
236 | calendar time, and the functions which operate on calendar time objects. | |
237 | These facilities are declared in the header file @file{time.h}. | |
238 | @pindex time.h | |
239 | ||
240 | @cindex epoch | |
241 | @comment time.h | |
f65fd747 | 242 | @comment ISO |
28f540f4 | 243 | @deftp {Data Type} time_t |
60092701 RM |
244 | This is the data type used to represent calendar time. |
245 | When interpreted as an absolute time | |
28f540f4 RM |
246 | value, it represents the number of seconds elapsed since 00:00:00 on |
247 | January 1, 1970, Coordinated Universal Time. (This date is sometimes | |
60092701 RM |
248 | referred to as the @dfn{epoch}.) POSIX requires that this count |
249 | ignore leap seconds, but on some hosts this count includes leap seconds | |
250 | if you set @code{TZ} to certain values (@pxref{TZ Variable}). | |
28f540f4 | 251 | |
60092701 | 252 | In the GNU C library, @code{time_t} is equivalent to @code{long int}. |
28f540f4 RM |
253 | In other systems, @code{time_t} might be either an integer or |
254 | floating-point type. | |
255 | @end deftp | |
256 | ||
257 | @comment time.h | |
f65fd747 | 258 | @comment ISO |
28f540f4 RM |
259 | @deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) |
260 | The @code{difftime} function returns the number of seconds elapsed | |
261 | between time @var{time1} and time @var{time0}, as a value of type | |
60092701 RM |
262 | @code{double}. The difference ignores leap seconds unless leap |
263 | second support is enabled. | |
28f540f4 RM |
264 | |
265 | In the GNU system, you can simply subtract @code{time_t} values. But on | |
266 | other systems, the @code{time_t} data type might use some other encoding | |
267 | where subtraction doesn't work directly. | |
268 | @end deftypefun | |
269 | ||
270 | @comment time.h | |
f65fd747 | 271 | @comment ISO |
28f540f4 RM |
272 | @deftypefun time_t time (time_t *@var{result}) |
273 | The @code{time} function returns the current time as a value of type | |
274 | @code{time_t}. If the argument @var{result} is not a null pointer, the | |
01cdeca0 | 275 | time value is also stored in @code{*@var{result}}. If the calendar |
28f540f4 RM |
276 | time is not available, the value @w{@code{(time_t)(-1)}} is returned. |
277 | @end deftypefun | |
278 | ||
279 | ||
280 | @node High-Resolution Calendar | |
281 | @subsection High-Resolution Calendar | |
282 | ||
01cdeca0 | 283 | The @code{time_t} data type used to represent calendar times has a |
28f540f4 RM |
284 | resolution of only one second. Some applications need more precision. |
285 | ||
286 | So, the GNU C library also contains functions which are capable of | |
287 | representing calendar times to a higher resolution than one second. The | |
288 | functions and the associated data types described in this section are | |
289 | declared in @file{sys/time.h}. | |
290 | @pindex sys/time.h | |
291 | ||
292 | @comment sys/time.h | |
293 | @comment BSD | |
294 | @deftp {Data Type} {struct timeval} | |
295 | The @code{struct timeval} structure represents a calendar time. It | |
296 | has the following members: | |
297 | ||
298 | @table @code | |
299 | @item long int tv_sec | |
300 | This represents the number of seconds since the epoch. It is equivalent | |
301 | to a normal @code{time_t} value. | |
302 | ||
303 | @item long int tv_usec | |
304 | This is the fractional second value, represented as the number of | |
305 | microseconds. | |
306 | ||
307 | Some times struct timeval values are used for time intervals. Then the | |
308 | @code{tv_sec} member is the number of seconds in the interval, and | |
309 | @code{tv_usec} is the number of additional microseconds. | |
310 | @end table | |
311 | @end deftp | |
312 | ||
313 | @comment sys/time.h | |
314 | @comment BSD | |
315 | @deftp {Data Type} {struct timezone} | |
316 | The @code{struct timezone} structure is used to hold minimal information | |
317 | about the local time zone. It has the following members: | |
318 | ||
319 | @table @code | |
320 | @item int tz_minuteswest | |
f0f1bf85 | 321 | This is the number of minutes west of UTC. |
28f540f4 RM |
322 | |
323 | @item int tz_dsttime | |
f0f1bf85 | 324 | If nonzero, daylight saving time applies during some part of the year. |
28f540f4 RM |
325 | @end table |
326 | ||
327 | The @code{struct timezone} type is obsolete and should never be used. | |
328 | Instead, use the facilities described in @ref{Time Zone Functions}. | |
329 | @end deftp | |
330 | ||
331 | It is often necessary to subtract two values of type @w{@code{struct | |
332 | timeval}}. Here is the best way to do this. It works even on some | |
333 | peculiar operating systems where the @code{tv_sec} member has an | |
334 | unsigned type. | |
335 | ||
336 | @smallexample | |
337 | /* @r{Subtract the `struct timeval' values X and Y,} | |
338 | @r{storing the result in RESULT.} | |
339 | @r{Return 1 if the difference is negative, otherwise 0.} */ | |
340 | ||
341 | int | |
342 | timeval_subtract (result, x, y) | |
343 | struct timeval *result, *x, *y; | |
344 | @{ | |
345 | /* @r{Perform the carry for the later subtraction by updating @var{y}.} */ | |
346 | if (x->tv_usec < y->tv_usec) @{ | |
347 | int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1; | |
348 | y->tv_usec -= 1000000 * nsec; | |
349 | y->tv_sec += nsec; | |
350 | @} | |
351 | if (x->tv_usec - y->tv_usec > 1000000) @{ | |
352 | int nsec = (y->tv_usec - x->tv_usec) / 1000000; | |
353 | y->tv_usec += 1000000 * nsec; | |
354 | y->tv_sec -= nsec; | |
355 | @} | |
356 | ||
357 | /* @r{Compute the time remaining to wait.} | |
358 | @r{@code{tv_usec} is certainly positive.} */ | |
359 | result->tv_sec = x->tv_sec - y->tv_sec; | |
360 | result->tv_usec = x->tv_usec - y->tv_usec; | |
361 | ||
362 | /* @r{Return 1 if result is negative.} */ | |
363 | return x->tv_sec < y->tv_sec; | |
364 | @} | |
365 | @end smallexample | |
366 | ||
367 | @comment sys/time.h | |
368 | @comment BSD | |
369 | @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) | |
370 | The @code{gettimeofday} function returns the current date and time in the | |
371 | @code{struct timeval} structure indicated by @var{tp}. Information about the | |
372 | time zone is returned in the structure pointed at @var{tzp}. If the @var{tzp} | |
373 | argument is a null pointer, time zone information is ignored. | |
374 | ||
375 | The return value is @code{0} on success and @code{-1} on failure. The | |
376 | following @code{errno} error condition is defined for this function: | |
377 | ||
378 | @table @code | |
379 | @item ENOSYS | |
380 | The operating system does not support getting time zone information, and | |
381 | @var{tzp} is not a null pointer. The GNU operating system does not | |
382 | support using @w{@code{struct timezone}} to represent time zone | |
383 | information; that is an obsolete feature of 4.3 BSD. | |
384 | Instead, use the facilities described in @ref{Time Zone Functions}. | |
385 | @end table | |
386 | @end deftypefun | |
387 | ||
388 | @comment sys/time.h | |
389 | @comment BSD | |
390 | @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) | |
391 | The @code{settimeofday} function sets the current date and time | |
392 | according to the arguments. As for @code{gettimeofday}, time zone | |
393 | information is ignored if @var{tzp} is a null pointer. | |
394 | ||
395 | You must be a privileged user in order to use @code{settimeofday}. | |
396 | ||
397 | The return value is @code{0} on success and @code{-1} on failure. The | |
398 | following @code{errno} error conditions are defined for this function: | |
399 | ||
400 | @table @code | |
401 | @item EPERM | |
402 | This process cannot set the time because it is not privileged. | |
403 | ||
404 | @item ENOSYS | |
405 | The operating system does not support setting time zone information, and | |
406 | @var{tzp} is not a null pointer. | |
407 | @end table | |
408 | @end deftypefun | |
409 | ||
410 | @comment sys/time.h | |
411 | @comment BSD | |
412 | @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) | |
413 | This function speeds up or slows down the system clock in order to make | |
414 | gradual adjustments in the current time. This ensures that the time | |
415 | reported by the system clock is always monotonically increasing, which | |
416 | might not happen if you simply set the current time. | |
417 | ||
418 | The @var{delta} argument specifies a relative adjustment to be made to | |
419 | the current time. If negative, the system clock is slowed down for a | |
420 | while until it has lost this much time. If positive, the system clock | |
421 | is speeded up for a while. | |
422 | ||
423 | If the @var{olddelta} argument is not a null pointer, the @code{adjtime} | |
424 | function returns information about any previous time adjustment that | |
425 | has not yet completed. | |
426 | ||
427 | This function is typically used to synchronize the clocks of computers | |
428 | in a local network. You must be a privileged user to use it. | |
429 | The return value is @code{0} on success and @code{-1} on failure. The | |
430 | following @code{errno} error condition is defined for this function: | |
431 | ||
432 | @table @code | |
433 | @item EPERM | |
434 | You do not have privilege to set the time. | |
435 | @end table | |
436 | @end deftypefun | |
437 | ||
438 | @strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday}, | |
01cdeca0 | 439 | and @code{adjtime} functions are derived from BSD. |
28f540f4 RM |
440 | |
441 | ||
442 | @node Broken-down Time | |
443 | @subsection Broken-down Time | |
444 | @cindex broken-down time | |
445 | @cindex calendar time and broken-down time | |
446 | ||
447 | Calendar time is represented as a number of seconds. This is convenient | |
448 | for calculation, but has no resemblance to the way people normally | |
449 | represent dates and times. By contrast, @dfn{broken-down time} is a binary | |
450 | representation separated into year, month, day, and so on. Broken down | |
451 | time values are not useful for calculations, but they are useful for | |
452 | printing human readable time. | |
453 | ||
454 | A broken-down time value is always relative to a choice of local time | |
455 | zone, and it also indicates which time zone was used. | |
456 | ||
457 | The symbols in this section are declared in the header file @file{time.h}. | |
458 | ||
459 | @comment time.h | |
f65fd747 | 460 | @comment ISO |
28f540f4 RM |
461 | @deftp {Data Type} {struct tm} |
462 | This is the data type used to represent a broken-down time. The structure | |
463 | contains at least the following members, which can appear in any order: | |
464 | ||
465 | @table @code | |
466 | @item int tm_sec | |
467 | This is the number of seconds after the minute, normally in the range | |
ec4b0518 | 468 | @code{0} through @code{59}. (The actual upper limit is @code{60}, to allow |
60092701 | 469 | for leap seconds if leap second support is available.) |
28f540f4 RM |
470 | @cindex leap second |
471 | ||
472 | @item int tm_min | |
ec4b0518 | 473 | This is the number of minutes after the hour, in the range @code{0} through |
28f540f4 RM |
474 | @code{59}. |
475 | ||
476 | @item int tm_hour | |
ec4b0518 | 477 | This is the number of hours past midnight, in the range @code{0} through |
28f540f4 RM |
478 | @code{23}. |
479 | ||
480 | @item int tm_mday | |
ec4b0518 | 481 | This is the day of the month, in the range @code{1} through @code{31}. |
28f540f4 RM |
482 | |
483 | @item int tm_mon | |
ec4b0518 | 484 | This is the number of months since January, in the range @code{0} through |
28f540f4 RM |
485 | @code{11}. |
486 | ||
487 | @item int tm_year | |
488 | This is the number of years since @code{1900}. | |
489 | ||
490 | @item int tm_wday | |
ec4b0518 UD |
491 | This is the number of days since Sunday, in the range @code{0} through |
492 | @code{6}. | |
28f540f4 RM |
493 | |
494 | @item int tm_yday | |
ec4b0518 | 495 | This is the number of days since January 1, in the range @code{0} through |
28f540f4 RM |
496 | @code{365}. |
497 | ||
498 | @item int tm_isdst | |
499 | @cindex Daylight Saving Time | |
500 | @cindex summer time | |
501 | This is a flag that indicates whether Daylight Saving Time is (or was, or | |
502 | will be) in effect at the time described. The value is positive if | |
503 | Daylight Saving Time is in effect, zero if it is not, and negative if the | |
504 | information is not available. | |
505 | ||
506 | @item long int tm_gmtoff | |
507 | This field describes the time zone that was used to compute this | |
f0f1bf85 UD |
508 | broken-down time value, including any adjustment for daylight saving; it |
509 | is the number of seconds that you must add to UTC to get local time. | |
510 | You can also think of this as the number of seconds east of UTC. For | |
511 | example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}. | |
512 | The @code{tm_gmtoff} field is derived from BSD and is a GNU library | |
f65fd747 | 513 | extension; it is not visible in a strict @w{ISO C} environment. |
28f540f4 RM |
514 | |
515 | @item const char *tm_zone | |
f0f1bf85 UD |
516 | This field is the name for the time zone that was used to compute this |
517 | broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and | |
f65fd747 | 518 | GNU extension, and is not visible in a strict @w{ISO C} environment. |
28f540f4 RM |
519 | @end table |
520 | @end deftp | |
521 | ||
522 | @comment time.h | |
f65fd747 | 523 | @comment ISO |
28f540f4 RM |
524 | @deftypefun {struct tm *} localtime (const time_t *@var{time}) |
525 | The @code{localtime} function converts the calendar time pointed to by | |
526 | @var{time} to broken-down time representation, expressed relative to the | |
527 | user's specified time zone. | |
528 | ||
529 | The return value is a pointer to a static broken-down time structure, which | |
60092701 RM |
530 | might be overwritten by subsequent calls to @code{ctime}, @code{gmtime}, |
531 | or @code{localtime}. (But no other library function overwrites the contents | |
532 | of this object.) | |
28f540f4 | 533 | |
fe0ec73e UD |
534 | The return value is the null pointer if @var{time} cannot be represented |
535 | as a broken-down time; typically this is because the year cannot fit into | |
536 | an @code{int}. | |
537 | ||
28f540f4 RM |
538 | Calling @code{localtime} has one other effect: it sets the variable |
539 | @code{tzname} with information about the current time zone. @xref{Time | |
540 | Zone Functions}. | |
541 | @end deftypefun | |
542 | ||
0413b54c UD |
543 | Using the @code{localtime} function is a big problem in multi-threaded |
544 | programs. The result is returned in a static buffer and this is used in | |
545 | all threads. POSIX.1c introduced a varient of this function. | |
546 | ||
547 | @comment time.h | |
548 | @comment POSIX.1c | |
549 | @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) | |
550 | The @code{localtime_r} function works just like the @code{localtime} | |
551 | function. It takes a pointer to a variable containing the calendar time | |
552 | and converts it to the broken-down time format. | |
553 | ||
554 | But the result is not placed in a static buffer. Instead it is placed | |
555 | in the object of type @code{struct tm} to which the parameter | |
556 | @var{resultp} points. | |
557 | ||
558 | If the conversion is successful the function returns a pointer to the | |
559 | object the result was written into, i.e., it returns @var{resultp}. | |
560 | @end deftypefun | |
561 | ||
562 | ||
28f540f4 | 563 | @comment time.h |
f65fd747 | 564 | @comment ISO |
28f540f4 RM |
565 | @deftypefun {struct tm *} gmtime (const time_t *@var{time}) |
566 | This function is similar to @code{localtime}, except that the broken-down | |
567 | time is expressed as Coordinated Universal Time (UTC)---that is, as | |
f0f1bf85 | 568 | Greenwich Mean Time (GMT)---rather than relative to the local time zone. |
28f540f4 RM |
569 | |
570 | Recall that calendar times are @emph{always} expressed in coordinated | |
571 | universal time. | |
572 | @end deftypefun | |
573 | ||
0413b54c | 574 | As for the @code{localtime} function we have the problem that the result |
f2ea0f5b | 575 | is placed in a static variable. POSIX.1c also provides a replacement for |
0413b54c UD |
576 | @code{gmtime}. |
577 | ||
578 | @comment time.h | |
579 | @comment POSIX.1c | |
580 | @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) | |
581 | This function is similar to @code{localtime_r}, except that it converts | |
582 | just like @code{gmtime} the given time as Coordinated Universal Time. | |
583 | ||
584 | If the conversion is successful the function returns a pointer to the | |
585 | object the result was written into, i.e., it returns @var{resultp}. | |
586 | @end deftypefun | |
587 | ||
588 | ||
28f540f4 | 589 | @comment time.h |
f65fd747 | 590 | @comment ISO |
28f540f4 RM |
591 | @deftypefun time_t mktime (struct tm *@var{brokentime}) |
592 | The @code{mktime} function is used to convert a broken-down time structure | |
593 | to a calendar time representation. It also ``normalizes'' the contents of | |
594 | the broken-down time structure, by filling in the day of week and day of | |
595 | year based on the other date and time components. | |
596 | ||
597 | The @code{mktime} function ignores the specified contents of the | |
598 | @code{tm_wday} and @code{tm_yday} members of the broken-down time | |
599 | structure. It uses the values of the other components to compute the | |
600 | calendar time; it's permissible for these components to have | |
601 | unnormalized values outside of their normal ranges. The last thing that | |
602 | @code{mktime} does is adjust the components of the @var{brokentime} | |
603 | structure (including the @code{tm_wday} and @code{tm_yday}). | |
604 | ||
605 | If the specified broken-down time cannot be represented as a calendar time, | |
606 | @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify | |
607 | the contents of @var{brokentime}. | |
608 | ||
609 | Calling @code{mktime} also sets the variable @code{tzname} with | |
610 | information about the current time zone. @xref{Time Zone Functions}. | |
611 | @end deftypefun | |
612 | ||
613 | @node Formatting Date and Time | |
614 | @subsection Formatting Date and Time | |
615 | ||
616 | The functions described in this section format time values as strings. | |
617 | These functions are declared in the header file @file{time.h}. | |
618 | @pindex time.h | |
619 | ||
620 | @comment time.h | |
f65fd747 | 621 | @comment ISO |
28f540f4 RM |
622 | @deftypefun {char *} asctime (const struct tm *@var{brokentime}) |
623 | The @code{asctime} function converts the broken-down time value that | |
624 | @var{brokentime} points to into a string in a standard format: | |
625 | ||
626 | @smallexample | |
627 | "Tue May 21 13:46:22 1991\n" | |
628 | @end smallexample | |
629 | ||
630 | The abbreviations for the days of week are: @samp{Sun}, @samp{Mon}, | |
631 | @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}. | |
632 | ||
633 | The abbreviations for the months are: @samp{Jan}, @samp{Feb}, | |
634 | @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug}, | |
635 | @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}. | |
636 | ||
637 | The return value points to a statically allocated string, which might be | |
60092701 | 638 | overwritten by subsequent calls to @code{asctime} or @code{ctime}. |
28f540f4 RM |
639 | (But no other library function overwrites the contents of this |
640 | string.) | |
641 | @end deftypefun | |
642 | ||
0413b54c UD |
643 | @comment time.h |
644 | @comment POSIX.1c | |
645 | @deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) | |
646 | This function is similar to @code{asctime} but instead of placing the | |
647 | result in a static buffer it writes the string in the buffer pointed to | |
648 | by the parameter @var{buffer}. This buffer should have at least room | |
649 | for 16 bytes. | |
650 | ||
651 | If no error occurred the function returns a pointer to the string the | |
652 | result was written into, i.e., it returns @var{buffer}. Otherwise | |
653 | return @code{NULL}. | |
654 | @end deftypefun | |
655 | ||
656 | ||
28f540f4 | 657 | @comment time.h |
f65fd747 | 658 | @comment ISO |
28f540f4 RM |
659 | @deftypefun {char *} ctime (const time_t *@var{time}) |
660 | The @code{ctime} function is similar to @code{asctime}, except that the | |
661 | time value is specified as a @code{time_t} calendar time value rather | |
662 | than in broken-down local time format. It is equivalent to | |
663 | ||
664 | @smallexample | |
665 | asctime (localtime (@var{time})) | |
666 | @end smallexample | |
667 | ||
668 | @code{ctime} sets the variable @code{tzname}, because @code{localtime} | |
669 | does so. @xref{Time Zone Functions}. | |
670 | @end deftypefun | |
671 | ||
0413b54c UD |
672 | @comment time.h |
673 | @comment POSIX.1c | |
674 | @deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) | |
675 | This function is similar to @code{ctime}, only that it places the result | |
676 | in the string pointed to by @var{buffer}. It is equivalent to (written | |
677 | using gcc extensions, @xref{Statement Exprs,,,gcc,Porting and Using gcc}.): | |
678 | ||
679 | @smallexample | |
680 | (@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @}) | |
681 | @end smallexample | |
682 | ||
683 | If no error occurred the function returns a pointer to the string the | |
684 | result was written into, i.e., it returns @var{buffer}. Otherwise | |
685 | return @code{NULL}. | |
686 | @end deftypefun | |
687 | ||
688 | ||
28f540f4 | 689 | @comment time.h |
f65fd747 | 690 | @comment ISO |
ec4b0518 | 691 | @comment POSIX.2 |
28f540f4 RM |
692 | @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) |
693 | This function is similar to the @code{sprintf} function (@pxref{Formatted | |
694 | Input}), but the conversion specifications that can appear in the format | |
695 | template @var{template} are specialized for printing components of the date | |
696 | and time @var{brokentime} according to the locale currently specified for | |
697 | time conversion (@pxref{Locales}). | |
698 | ||
699 | Ordinary characters appearing in the @var{template} are copied to the | |
700 | output string @var{s}; this can include multibyte character sequences. | |
ec4b0518 | 701 | Conversion specifiers are introduced by a @samp{%} character, followed |
a2b08ee5 UD |
702 | by an optional flag which can be one of the following. These flags |
703 | are all GNU extensions. The first three affect only the output of | |
704 | numbers: | |
2de99474 UD |
705 | |
706 | @table @code | |
707 | @item _ | |
708 | The number is padded with spaces. | |
709 | ||
710 | @item - | |
711 | The number is not padded at all. | |
860d3729 UD |
712 | |
713 | @item 0 | |
7e3be507 | 714 | The number is padded with zeros even if the format specifies padding |
860d3729 | 715 | with spaces. |
7e3be507 UD |
716 | |
717 | @item ^ | |
718 | The output uses uppercase characters, but only if this is possible | |
719 | (@pxref{Case Conversion}). | |
2de99474 UD |
720 | @end table |
721 | ||
ec4b0518 UD |
722 | The default action is to pad the number with zeros to keep it a constant |
723 | width. Numbers that do not have a range indicated below are never | |
724 | padded, since there is no natural width for them. | |
725 | ||
860d3729 UD |
726 | Following the flag an optional specification of the width is possible. |
727 | This is specified in decimal notation. If the natural size of the | |
5b826692 | 728 | output is of the field has less than the specified number of characters, |
860d3729 UD |
729 | the result is written right adjusted and space padded to the given |
730 | size. | |
731 | ||
732 | An optional modifier can follow the optional flag and width | |
733 | specification. The modifiers, which are POSIX.2 extensions, are: | |
ec4b0518 UD |
734 | |
735 | @table @code | |
736 | @item E | |
737 | Use the locale's alternate representation for date and time. This | |
738 | modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X}, | |
739 | @code{%y} and @code{%Y} format specifiers. In a Japanese locale, for | |
740 | example, @code{%Ex} might yield a date format based on the Japanese | |
741 | Emperors' reigns. | |
742 | ||
743 | @item O | |
744 | Use the locale's alternate numeric symbols for numbers. This modifier | |
745 | applies only to numeric format specifiers. | |
746 | @end table | |
747 | ||
860d3729 UD |
748 | If the format supports the modifier but no alternate representation |
749 | is available, it is ignored. | |
ec4b0518 UD |
750 | |
751 | The conversion specifier ends with a format specifier taken from the | |
752 | following list. The whole @samp{%} sequence is replaced in the output | |
753 | string as follows: | |
28f540f4 RM |
754 | |
755 | @table @code | |
756 | @item %a | |
757 | The abbreviated weekday name according to the current locale. | |
758 | ||
759 | @item %A | |
760 | The full weekday name according to the current locale. | |
761 | ||
762 | @item %b | |
763 | The abbreviated month name according to the current locale. | |
764 | ||
765 | @item %B | |
766 | The full month name according to the current locale. | |
767 | ||
768 | @item %c | |
769 | The preferred date and time representation for the current locale. | |
770 | ||
2de99474 | 771 | @item %C |
ec4b0518 UD |
772 | The century of the year. This is equivalent to the greatest integer not |
773 | greater than the year divided by 100. | |
774 | ||
775 | This format is a POSIX.2 extension. | |
2de99474 | 776 | |
28f540f4 | 777 | @item %d |
ec4b0518 | 778 | The day of the month as a decimal number (range @code{01} through @code{31}). |
28f540f4 | 779 | |
2de99474 UD |
780 | @item %D |
781 | The date using the format @code{%m/%d/%y}. | |
782 | ||
ec4b0518 | 783 | This format is a POSIX.2 extension. |
2de99474 | 784 | |
ec4b0518 | 785 | @item %e |
2de99474 | 786 | The day of the month like with @code{%d}, but padded with blank (range |
ec4b0518 UD |
787 | @code{ 1} through @code{31}). |
788 | ||
789 | This format is a POSIX.2 extension. | |
790 | ||
fe0ec73e UD |
791 | @item %f |
792 | The day of the week as a decimal number (range @code{1} through | |
793 | @code{7}), Monday being @code{1}. | |
794 | ||
795 | This format is a @w{ISO C 9X} extension. | |
796 | ||
797 | @item %F | |
798 | The date using the format @code{%Y-%m-%d}. This is the form specified | |
799 | in the @w{ISO 8601} standard and is the preferred form for all uses. | |
800 | ||
801 | This format is a @w{ISO C 9X} extension. | |
802 | ||
ec4b0518 UD |
803 | @item %g |
804 | The year corresponding to the ISO week number, but without the century | |
805 | (range @code{00} through @code{99}). This has the same format and value | |
806 | as @code{%y}, except that if the ISO week number (see @code{%V}) belongs | |
807 | to the previous or next year, that year is used instead. | |
808 | ||
809 | This format is a GNU extension. | |
810 | ||
811 | @item %G | |
812 | The year corresponding to the ISO week number. This has the same format | |
813 | and value as @code{%Y}, except that if the ISO week number (see | |
814 | @code{%V}) belongs to the previous or next year, that year is used | |
815 | instead. | |
2de99474 UD |
816 | |
817 | This format is a GNU extension. | |
818 | ||
819 | @item %h | |
820 | The abbreviated month name according to the current locale. The action | |
821 | is the same as for @code{%b}. | |
822 | ||
ec4b0518 | 823 | This format is a POSIX.2 extension. |
2de99474 | 824 | |
28f540f4 | 825 | @item %H |
ec4b0518 | 826 | The hour as a decimal number, using a 24-hour clock (range @code{00} through |
28f540f4 RM |
827 | @code{23}). |
828 | ||
829 | @item %I | |
ec4b0518 | 830 | The hour as a decimal number, using a 12-hour clock (range @code{01} through |
28f540f4 RM |
831 | @code{12}). |
832 | ||
833 | @item %j | |
ec4b0518 | 834 | The day of the year as a decimal number (range @code{001} through @code{366}). |
28f540f4 | 835 | |
2de99474 UD |
836 | @item %k |
837 | The hour as a decimal number, using a 24-hour clock like @code{%H}, but | |
ec4b0518 | 838 | padded with blank (range @code{ 0} through @code{23}). |
2de99474 UD |
839 | |
840 | This format is a GNU extension. | |
841 | ||
842 | @item %l | |
843 | The hour as a decimal number, using a 12-hour clock like @code{%I}, but | |
ec4b0518 | 844 | padded with blank (range @code{ 1} through @code{12}). |
2de99474 UD |
845 | |
846 | This format is a GNU extension. | |
847 | ||
28f540f4 | 848 | @item %m |
ec4b0518 | 849 | The month as a decimal number (range @code{01} through @code{12}). |
28f540f4 RM |
850 | |
851 | @item %M | |
ec4b0518 | 852 | The minute as a decimal number (range @code{00} through @code{59}). |
28f540f4 | 853 | |
2de99474 UD |
854 | @item %n |
855 | A single @samp{\n} (newline) character. | |
856 | ||
ec4b0518 | 857 | This format is a POSIX.2 extension. |
2de99474 | 858 | |
28f540f4 | 859 | @item %p |
ec4b0518 UD |
860 | Either @samp{AM} or @samp{PM}, according to the given time value; or the |
861 | corresponding strings for the current locale. Noon is treated as | |
862 | @samp{PM} and midnight as @samp{AM}. | |
28f540f4 | 863 | |
7e3be507 UD |
864 | @ignore |
865 | We currently have a problem with makeinfo. Write @samp{AM} and @samp{am} | |
866 | both results in `am'. I.e., the difference in case is not visible anymore. | |
867 | @end ignore | |
868 | @item %P | |
869 | Either @samp{am} or @samp{pm}, according to the given time value; or the | |
870 | corresponding strings for the current locale, printed in lowercase | |
871 | characters. Noon is treated as @samp{pm} and midnight as @samp{am}. | |
872 | ||
873 | This format is a GNU extension. | |
874 | ||
2de99474 | 875 | @item %r |
ec4b0518 | 876 | The complete time using the AM/PM format of the current locale. |
2de99474 | 877 | |
ec4b0518 | 878 | This format is a POSIX.2 extension. |
2de99474 UD |
879 | |
880 | @item %R | |
881 | The hour and minute in decimal numbers using the format @code{%H:%M}. | |
882 | ||
883 | This format is a GNU extension. | |
884 | ||
885 | @item %s | |
ec4b0518 UD |
886 | The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. |
887 | Leap seconds are not counted unless leap second support is available. | |
2de99474 UD |
888 | |
889 | This format is a GNU extension. | |
890 | ||
28f540f4 | 891 | @item %S |
ec4b0518 | 892 | The second as a decimal number (range @code{00} through @code{60}). |
28f540f4 | 893 | |
2de99474 UD |
894 | @item %t |
895 | A single @samp{\t} (tabulator) character. | |
896 | ||
ec4b0518 | 897 | This format is a POSIX.2 extension. |
2de99474 UD |
898 | |
899 | @item %T | |
900 | The time using decimal numbers using the format @code{%H:%M:%S}. | |
901 | ||
ec4b0518 UD |
902 | This format is a POSIX.2 extension. |
903 | ||
904 | @item %u | |
905 | The day of the week as a decimal number (range @code{1} through | |
906 | @code{7}), Monday being @code{1}. | |
907 | ||
908 | This format is a POSIX.2 extension. | |
2de99474 | 909 | |
28f540f4 | 910 | @item %U |
ec4b0518 UD |
911 | The week number of the current year as a decimal number (range @code{00} |
912 | through @code{53}), starting with the first Sunday as the first day of | |
913 | the first week. Days preceding the first Sunday in the year are | |
914 | considered to be in week @code{00}. | |
7c713e28 RM |
915 | |
916 | @item %V | |
ec4b0518 UD |
917 | The @w{ISO 8601:1988} week number as a decimal number (range @code{01} |
918 | through @code{53}). ISO weeks start with Monday and end with Sunday. | |
919 | Week @code{01} of a year is the first week which has the majority of its | |
920 | days in that year; this is equivalent to the week containing the year's | |
921 | first Thursday, and it is also equivalent to the week containing January | |
922 | 4. Week @code{01} of a year can contain days from the previous year. | |
923 | The week before week @code{01} of a year is the last week (@code{52} or | |
924 | @code{53}) of the previous year even if it contains days from the new | |
925 | year. | |
926 | ||
927 | This format is a POSIX.2 extension. | |
28f540f4 | 928 | |
2de99474 | 929 | @item %w |
ec4b0518 UD |
930 | The day of the week as a decimal number (range @code{0} through |
931 | @code{6}), Sunday being @code{0}. | |
2de99474 | 932 | |
28f540f4 | 933 | @item %W |
ec4b0518 UD |
934 | The week number of the current year as a decimal number (range @code{00} |
935 | through @code{53}), starting with the first Monday as the first day of | |
936 | the first week. All days preceding the first Monday in the year are | |
937 | considered to be in week @code{00}. | |
28f540f4 | 938 | |
28f540f4 RM |
939 | @item %x |
940 | The preferred date representation for the current locale, but without the | |
941 | time. | |
942 | ||
943 | @item %X | |
944 | The preferred time representation for the current locale, but with no date. | |
945 | ||
946 | @item %y | |
ec4b0518 UD |
947 | The year without a century as a decimal number (range @code{00} through |
948 | @code{99}). This is equivalent to the year modulo 100. | |
28f540f4 RM |
949 | |
950 | @item %Y | |
ec4b0518 UD |
951 | The year as a decimal number, using the Gregorian calendar. Years |
952 | before the year @code{1} are numbered @code{0}, @code{-1}, and so on. | |
28f540f4 | 953 | |
2de99474 | 954 | @item %z |
f0f1bf85 UD |
955 | @w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g., |
956 | @code{-0600} or @code{+0100}), or nothing if no time zone is | |
957 | determinable. | |
2de99474 | 958 | |
ec4b0518 UD |
959 | This format is a GNU extension. |
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 | ||
1006 | @node TZ Variable | |
1007 | @subsection Specifying the Time Zone with @code{TZ} | |
1008 | ||
1009 | In POSIX systems, a user can specify the time zone by means of the | |
1010 | @code{TZ} environment variable. For information about how to set | |
1011 | environment variables, see @ref{Environment Variables}. The functions | |
1012 | for accessing the time zone are declared in @file{time.h}. | |
1013 | @pindex time.h | |
1014 | @cindex time zone | |
1015 | ||
1016 | You should not normally need to set @code{TZ}. If the system is | |
f0f1bf85 | 1017 | configured properly, the default time zone will be correct. You might |
28f540f4 | 1018 | set @code{TZ} if you are using a computer over the network from a |
f0f1bf85 | 1019 | different time zone, and would like times reported to you in the time zone |
28f540f4 RM |
1020 | that local for you, rather than what is local for the computer. |
1021 | ||
1022 | In POSIX.1 systems the value of the @code{TZ} variable can be of one of | |
1023 | three formats. With the GNU C library, the most common format is the | |
1024 | last one, which can specify a selection from a large database of time | |
1025 | zone information for many regions of the world. The first two formats | |
1026 | are used to describe the time zone information directly, which is both | |
1027 | more cumbersome and less precise. But the POSIX.1 standard only | |
1028 | specifies the details of the first two formats, so it is good to be | |
1029 | familiar with them in case you come across a POSIX.1 system that doesn't | |
1030 | support a time zone information database. | |
1031 | ||
1032 | The first format is used when there is no Daylight Saving Time (or | |
1033 | summer time) in the local time zone: | |
1034 | ||
1035 | @smallexample | |
1036 | @r{@var{std} @var{offset}} | |
1037 | @end smallexample | |
1038 | ||
1039 | The @var{std} string specifies the name of the time zone. It must be | |
1040 | three or more characters long and must not contain a leading colon or | |
1041 | embedded digits, commas, or plus or minus signs. There is no space | |
1042 | character separating the time zone name from the @var{offset}, so these | |
1043 | restrictions are necessary to parse the specification correctly. | |
1044 | ||
1045 | The @var{offset} specifies the time value one must add to the local time | |
1046 | to get a Coordinated Universal Time value. It has syntax like | |
1047 | [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This | |
1048 | is positive if the local time zone is west of the Prime Meridian and | |
1049 | negative if it is east. The hour must be between @code{0} and | |
01cdeca0 | 1050 | @code{23}, and the minute and seconds between @code{0} and @code{59}. |
28f540f4 RM |
1051 | |
1052 | For example, here is how we would specify Eastern Standard Time, but | |
f0f1bf85 | 1053 | without any daylight saving time alternative: |
28f540f4 RM |
1054 | |
1055 | @smallexample | |
1056 | EST+5 | |
1057 | @end smallexample | |
1058 | ||
1059 | The second format is used when there is Daylight Saving Time: | |
1060 | ||
1061 | @smallexample | |
1062 | @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]} | |
1063 | @end smallexample | |
1064 | ||
1065 | The initial @var{std} and @var{offset} specify the standard time zone, as | |
1066 | described above. The @var{dst} string and @var{offset} specify the name | |
f0f1bf85 | 1067 | and offset for the corresponding daylight saving time time zone; if the |
28f540f4 RM |
1068 | @var{offset} is omitted, it defaults to one hour ahead of standard time. |
1069 | ||
f0f1bf85 UD |
1070 | The remainder of the specification describes when daylight saving time is |
1071 | in effect. The @var{start} field is when daylight saving time goes into | |
28f540f4 RM |
1072 | effect and the @var{end} field is when the change is made back to standard |
1073 | time. The following formats are recognized for these fields: | |
1074 | ||
1075 | @table @code | |
1076 | @item J@var{n} | |
1077 | This specifies the Julian day, with @var{n} between @code{1} and @code{365}. | |
1078 | February 29 is never counted, even in leap years. | |
1079 | ||
1080 | @item @var{n} | |
1081 | This specifies the Julian day, with @var{n} between @code{0} and @code{365}. | |
1082 | February 29 is counted in leap years. | |
1083 | ||
1084 | @item M@var{m}.@var{w}.@var{d} | |
1085 | This specifies day @var{d} of week @var{w} of month @var{m}. The day | |
1086 | @var{d} must be between @code{0} (Sunday) and @code{6}. The week | |
1087 | @var{w} must be between @code{1} and @code{5}; week @code{1} is the | |
1088 | first week in which day @var{d} occurs, and week @code{5} specifies the | |
1089 | @emph{last} @var{d} day in the month. The month @var{m} should be | |
1090 | between @code{1} and @code{12}. | |
1091 | @end table | |
1092 | ||
1093 | The @var{time} fields specify when, in the local time currently in | |
1094 | effect, the change to the other time occurs. If omitted, the default is | |
1095 | @code{02:00:00}. | |
1096 | ||
1097 | For example, here is how one would specify the Eastern time zone in the | |
1098 | United States, including the appropriate daylight saving time and its dates | |
f0f1bf85 | 1099 | of applicability. The normal offset from UTC is 5 hours; since this is |
28f540f4 RM |
1100 | west of the prime meridian, the sign is positive. Summer time begins on |
1101 | the first Sunday in April at 2:00am, and ends on the last Sunday in October | |
1102 | at 2:00am. | |
1103 | ||
1104 | @smallexample | |
f0f1bf85 | 1105 | EST+5EDT,M4.1.0/2,M10.5.0/2 |
28f540f4 RM |
1106 | @end smallexample |
1107 | ||
f0f1bf85 | 1108 | The schedule of daylight saving time in any particular jurisdiction has |
28f540f4 RM |
1109 | changed over the years. To be strictly correct, the conversion of dates |
1110 | and times in the past should be based on the schedule that was in effect | |
1111 | then. However, this format has no facilities to let you specify how the | |
1112 | schedule has changed from year to year. The most you can do is specify | |
1113 | one particular schedule---usually the present day schedule---and this is | |
1114 | used to convert any date, no matter when. For precise time zone | |
1115 | specifications, it is best to use the time zone information database | |
1116 | (see below). | |
1117 | ||
1118 | The third format looks like this: | |
1119 | ||
1120 | @smallexample | |
1121 | :@var{characters} | |
1122 | @end smallexample | |
1123 | ||
1124 | Each operating system interprets this format differently; in the GNU C | |
1125 | library, @var{characters} is the name of a file which describes the time | |
1126 | zone. | |
1127 | ||
1128 | @pindex /etc/localtime | |
1129 | @pindex localtime | |
1130 | If the @code{TZ} environment variable does not have a value, the | |
1131 | operation chooses a time zone by default. In the GNU C library, the | |
1132 | default time zone is like the specification @samp{TZ=:/etc/localtime} | |
1133 | (or @samp{TZ=:/usr/local/etc/localtime}, depending on how GNU C library | |
1134 | was configured; @pxref{Installation}). Other C libraries use their own | |
1135 | rule for choosing the default time zone, so there is little we can say | |
1136 | about them. | |
1137 | ||
1138 | @cindex time zone database | |
1139 | @pindex /share/lib/zoneinfo | |
1140 | @pindex zoneinfo | |
1141 | If @var{characters} begins with a slash, it is an absolute file name; | |
1142 | otherwise the library looks for the file | |
1143 | @w{@file{/share/lib/zoneinfo/@var{characters}}}. The @file{zoneinfo} | |
1144 | directory contains data files describing local time zones in many | |
1145 | different parts of the world. The names represent major cities, with | |
1146 | subdirectories for geographical areas; for example, | |
1147 | @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}. | |
1148 | These data files are installed by the system administrator, who also | |
1149 | sets @file{/etc/localtime} to point to the data file for the local time | |
1150 | zone. The GNU C library comes with a large database of time zone | |
1151 | information for most regions of the world, which is maintained by a | |
1152 | community of volunteers and put in the public domain. | |
1153 | ||
1154 | @node Time Zone Functions | |
1155 | @subsection Functions and Variables for Time Zones | |
1156 | ||
1157 | @comment time.h | |
1158 | @comment POSIX.1 | |
2c6fe0bd | 1159 | @deftypevar {char *} tzname [2] |
28f540f4 | 1160 | The array @code{tzname} contains two strings, which are the standard |
60092701 | 1161 | names of the pair of time zones (standard and daylight |
f0f1bf85 | 1162 | saving) that the user has selected. @code{tzname[0]} is the name of |
28f540f4 | 1163 | the standard time zone (for example, @code{"EST"}), and @code{tzname[1]} |
f0f1bf85 | 1164 | is the name for the time zone when daylight saving time is in use (for |
28f540f4 | 1165 | example, @code{"EDT"}). These correspond to the @var{std} and @var{dst} |
f0f1bf85 UD |
1166 | strings (respectively) from the @code{TZ} environment variable. If |
1167 | daylight saving time is never used, @code{tzname[1]} is the empty string. | |
28f540f4 RM |
1168 | |
1169 | The @code{tzname} array is initialized from the @code{TZ} environment | |
1170 | variable whenever @code{tzset}, @code{ctime}, @code{strftime}, | |
f0f1bf85 UD |
1171 | @code{mktime}, or @code{localtime} is called. If multiple abbreviations |
1172 | have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War | |
1173 | Time and Eastern Daylight Time), the array contains the most recent | |
1174 | abbreviation. | |
1175 | ||
1176 | The @code{tzname} array is required for POSIX.1 compatibility, but in | |
1177 | GNU programs it is better to use the @code{tm_zone} member of the | |
1178 | broken-down time structure, since @code{tm_zone} reports the correct | |
1179 | abbreviation even when it is not the latest one. | |
1180 | ||
0413b54c | 1181 | Though the strings are declared as @code{char *} the user must stay away |
f2ea0f5b | 1182 | from modifying these strings. Modifying the strings will almost certainly |
0413b54c UD |
1183 | lead to trouble. |
1184 | ||
28f540f4 RM |
1185 | @end deftypevar |
1186 | ||
1187 | @comment time.h | |
1188 | @comment POSIX.1 | |
1189 | @deftypefun void tzset (void) | |
1190 | The @code{tzset} function initializes the @code{tzname} variable from | |
1191 | the value of the @code{TZ} environment variable. It is not usually | |
1192 | necessary for your program to call this function, because it is called | |
1193 | automatically when you use the other time conversion functions that | |
1194 | depend on the time zone. | |
1195 | @end deftypefun | |
1196 | ||
1197 | The following variables are defined for compatibility with System V | |
f0f1bf85 UD |
1198 | Unix. Like @code{tzname}, these variables are set by calling |
1199 | @code{tzset} or the other time conversion functions. | |
28f540f4 RM |
1200 | |
1201 | @comment time.h | |
1202 | @comment SVID | |
1203 | @deftypevar {long int} timezone | |
f0f1bf85 UD |
1204 | This contains the difference between UTC and the latest local standard |
1205 | time, in seconds west of UTC. For example, in the U.S. Eastern time | |
1206 | zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member | |
1207 | of the broken-down time structure, this value is not adjusted for | |
1208 | daylight saving, and its sign is reversed. In GNU programs it is better | |
1209 | to use @code{tm_gmtoff}, since it contains the correct offset even when | |
1210 | it is not the latest one. | |
28f540f4 RM |
1211 | @end deftypevar |
1212 | ||
1213 | @comment time.h | |
1214 | @comment SVID | |
1215 | @deftypevar int daylight | |
60092701 RM |
1216 | This variable has a nonzero value if daylight savings time rules apply. |
1217 | A nonzero value does not necessarily mean that daylight savings time is | |
1218 | now in effect; it means only that daylight savings time is sometimes in | |
1219 | effect. | |
28f540f4 RM |
1220 | @end deftypevar |
1221 | ||
1222 | @node Time Functions Example | |
1223 | @subsection Time Functions Example | |
1224 | ||
1225 | Here is an example program showing the use of some of the local time and | |
1226 | calendar time functions. | |
1227 | ||
1228 | @smallexample | |
1229 | @include strftim.c.texi | |
1230 | @end smallexample | |
1231 | ||
1232 | It produces output like this: | |
1233 | ||
1234 | @smallexample | |
1235 | Wed Jul 31 13:02:36 1991 | |
1236 | Today is Wednesday, July 31. | |
1237 | The time is 01:02 PM. | |
1238 | @end smallexample | |
1239 | ||
1240 | ||
1241 | @node Setting an Alarm | |
1242 | @section Setting an Alarm | |
1243 | ||
1244 | The @code{alarm} and @code{setitimer} functions provide a mechanism for a | |
1245 | process to interrupt itself at some future time. They do this by setting a | |
1246 | timer; when the timer expires, the process receives a signal. | |
1247 | ||
1248 | @cindex setting an alarm | |
1249 | @cindex interval timer, setting | |
1250 | @cindex alarms, setting | |
1251 | @cindex timers, setting | |
1252 | Each process has three independent interval timers available: | |
1253 | ||
1254 | @itemize @bullet | |
01cdeca0 | 1255 | @item |
28f540f4 RM |
1256 | A real-time timer that counts clock time. This timer sends a |
1257 | @code{SIGALRM} signal to the process when it expires. | |
1258 | @cindex real-time timer | |
1259 | @cindex timer, real-time | |
1260 | ||
01cdeca0 | 1261 | @item |
28f540f4 RM |
1262 | A virtual timer that counts CPU time used by the process. This timer |
1263 | sends a @code{SIGVTALRM} signal to the process when it expires. | |
1264 | @cindex virtual timer | |
1265 | @cindex timer, virtual | |
1266 | ||
01cdeca0 | 1267 | @item |
28f540f4 RM |
1268 | A profiling timer that counts both CPU time used by the process, and CPU |
1269 | time spent in system calls on behalf of the process. This timer sends a | |
1270 | @code{SIGPROF} signal to the process when it expires. | |
1271 | @cindex profiling timer | |
1272 | @cindex timer, profiling | |
1273 | ||
1274 | This timer is useful for profiling in interpreters. The interval timer | |
1275 | mechanism does not have the fine granularity necessary for profiling | |
1276 | native code. | |
1277 | @c @xref{profil} !!! | |
1278 | @end itemize | |
1279 | ||
1280 | You can only have one timer of each kind set at any given time. If you | |
1281 | set a timer that has not yet expired, that timer is simply reset to the | |
1282 | new value. | |
1283 | ||
1284 | You should establish a handler for the appropriate alarm signal using | |
1285 | @code{signal} or @code{sigaction} before issuing a call to @code{setitimer} | |
1286 | or @code{alarm}. Otherwise, an unusual chain of events could cause the | |
1287 | timer to expire before your program establishes the handler, and in that | |
1288 | case it would be terminated, since that is the default action for the alarm | |
1289 | signals. @xref{Signal Handling}. | |
1290 | ||
1291 | The @code{setitimer} function is the primary means for setting an alarm. | |
1292 | This facility is declared in the header file @file{sys/time.h}. The | |
1293 | @code{alarm} function, declared in @file{unistd.h}, provides a somewhat | |
1294 | simpler interface for setting the real-time timer. | |
1295 | @pindex unistd.h | |
1296 | @pindex sys/time.h | |
1297 | ||
1298 | @comment sys/time.h | |
1299 | @comment BSD | |
1300 | @deftp {Data Type} {struct itimerval} | |
1301 | This structure is used to specify when a timer should expire. It contains | |
1302 | the following members: | |
1303 | @table @code | |
1304 | @item struct timeval it_interval | |
1305 | This is the interval between successive timer interrupts. If zero, the | |
1306 | alarm will only be sent once. | |
1307 | ||
1308 | @item struct timeval it_value | |
1309 | This is the interval to the first timer interrupt. If zero, the alarm is | |
1310 | disabled. | |
1311 | @end table | |
1312 | ||
1313 | The @code{struct timeval} data type is described in @ref{High-Resolution | |
1314 | Calendar}. | |
1315 | @end deftp | |
1316 | ||
1317 | @comment sys/time.h | |
1318 | @comment BSD | |
1319 | @deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old}) | |
01cdeca0 | 1320 | The @code{setitimer} function sets the timer specified by @var{which} |
28f540f4 RM |
1321 | according to @var{new}. The @var{which} argument can have a value of |
1322 | @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}. | |
1323 | ||
1324 | If @var{old} is not a null pointer, @code{setitimer} returns information | |
1325 | about any previous unexpired timer of the same kind in the structure it | |
1326 | points to. | |
1327 | ||
1328 | The return value is @code{0} on success and @code{-1} on failure. The | |
1329 | following @code{errno} error conditions are defined for this function: | |
1330 | ||
1331 | @table @code | |
1332 | @item EINVAL | |
1333 | The timer interval was too large. | |
1334 | @end table | |
1335 | @end deftypefun | |
1336 | ||
1337 | @comment sys/time.h | |
1338 | @comment BSD | |
1339 | @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old}) | |
1340 | The @code{getitimer} function stores information about the timer specified | |
1341 | by @var{which} in the structure pointed at by @var{old}. | |
1342 | ||
1343 | The return value and error conditions are the same as for @code{setitimer}. | |
1344 | @end deftypefun | |
1345 | ||
1346 | @comment sys/time.h | |
1347 | @comment BSD | |
1348 | @table @code | |
1349 | @item ITIMER_REAL | |
1350 | @findex ITIMER_REAL | |
1351 | This constant can be used as the @var{which} argument to the | |
1352 | @code{setitimer} and @code{getitimer} functions to specify the real-time | |
1353 | timer. | |
1354 | ||
1355 | @comment sys/time.h | |
1356 | @comment BSD | |
1357 | @item ITIMER_VIRTUAL | |
1358 | @findex ITIMER_VIRTUAL | |
1359 | This constant can be used as the @var{which} argument to the | |
1360 | @code{setitimer} and @code{getitimer} functions to specify the virtual | |
1361 | timer. | |
1362 | ||
1363 | @comment sys/time.h | |
1364 | @comment BSD | |
1365 | @item ITIMER_PROF | |
1366 | @findex ITIMER_PROF | |
1367 | This constant can be used as the @var{which} argument to the | |
1368 | @code{setitimer} and @code{getitimer} functions to specify the profiling | |
1369 | timer. | |
1370 | @end table | |
1371 | ||
1372 | @comment unistd.h | |
1373 | @comment POSIX.1 | |
1374 | @deftypefun {unsigned int} alarm (unsigned int @var{seconds}) | |
1375 | The @code{alarm} function sets the real-time timer to expire in | |
1376 | @var{seconds} seconds. If you want to cancel any existing alarm, you | |
1377 | can do this by calling @code{alarm} with a @var{seconds} argument of | |
1378 | zero. | |
1379 | ||
1380 | The return value indicates how many seconds remain before the previous | |
1381 | alarm would have been sent. If there is no previous alarm, @code{alarm} | |
1382 | returns zero. | |
1383 | @end deftypefun | |
1384 | ||
1385 | The @code{alarm} function could be defined in terms of @code{setitimer} | |
1386 | like this: | |
1387 | ||
1388 | @smallexample | |
1389 | unsigned int | |
1390 | alarm (unsigned int seconds) | |
1391 | @{ | |
1392 | struct itimerval old, new; | |
1393 | new.it_interval.tv_usec = 0; | |
1394 | new.it_interval.tv_sec = 0; | |
1395 | new.it_value.tv_usec = 0; | |
1396 | new.it_value.tv_sec = (long int) seconds; | |
1397 | if (setitimer (ITIMER_REAL, &new, &old) < 0) | |
1398 | return 0; | |
1399 | else | |
1400 | return old.it_value.tv_sec; | |
1401 | @} | |
1402 | @end smallexample | |
1403 | ||
1404 | There is an example showing the use of the @code{alarm} function in | |
1405 | @ref{Handler Returns}. | |
1406 | ||
1407 | If you simply want your process to wait for a given number of seconds, | |
1408 | you should use the @code{sleep} function. @xref{Sleeping}. | |
1409 | ||
1410 | You shouldn't count on the signal arriving precisely when the timer | |
1411 | expires. In a multiprocessing environment there is typically some | |
1412 | amount of delay involved. | |
1413 | ||
1414 | @strong{Portability Note:} The @code{setitimer} and @code{getitimer} | |
1415 | functions are derived from BSD Unix, while the @code{alarm} function is | |
1416 | specified by the POSIX.1 standard. @code{setitimer} is more powerful than | |
1417 | @code{alarm}, but @code{alarm} is more widely used. | |
1418 | ||
1419 | @node Sleeping | |
1420 | @section Sleeping | |
1421 | ||
1422 | The function @code{sleep} gives a simple way to make the program wait | |
1423 | for short periods of time. If your program doesn't use signals (except | |
1424 | to terminate), then you can expect @code{sleep} to wait reliably for | |
1425 | the specified amount of time. Otherwise, @code{sleep} can return sooner | |
1426 | if a signal arrives; if you want to wait for a given period regardless | |
1427 | of signals, use @code{select} (@pxref{Waiting for I/O}) and don't | |
1428 | specify any descriptors to wait for. | |
1429 | @c !!! select can get EINTR; using SA_RESTART makes sleep win too. | |
1430 | ||
1431 | @comment unistd.h | |
1432 | @comment POSIX.1 | |
1433 | @deftypefun {unsigned int} sleep (unsigned int @var{seconds}) | |
1434 | The @code{sleep} function waits for @var{seconds} or until a signal | |
01cdeca0 | 1435 | is delivered, whichever happens first. |
28f540f4 RM |
1436 | |
1437 | If @code{sleep} function returns because the requested time has | |
1438 | elapsed, it returns a value of zero. If it returns because of delivery | |
1439 | of a signal, its return value is the remaining time in the sleep period. | |
1440 | ||
1441 | The @code{sleep} function is declared in @file{unistd.h}. | |
1442 | @end deftypefun | |
1443 | ||
1444 | Resist the temptation to implement a sleep for a fixed amount of time by | |
1445 | using the return value of @code{sleep}, when nonzero, to call | |
1446 | @code{sleep} again. This will work with a certain amount of accuracy as | |
1447 | long as signals arrive infrequently. But each signal can cause the | |
1448 | eventual wakeup time to be off by an additional second or so. Suppose a | |
1449 | few signals happen to arrive in rapid succession by bad luck---there is | |
1450 | no limit on how much this could shorten or lengthen the wait. | |
1451 | ||
1452 | Instead, compute the time at which the program should stop waiting, and | |
1453 | keep trying to wait until that time. This won't be off by more than a | |
1454 | second. With just a little more work, you can use @code{select} and | |
1455 | make the waiting period quite accurate. (Of course, heavy system load | |
01cdeca0 | 1456 | can cause unavoidable additional delays---unless the machine is |
28f540f4 RM |
1457 | dedicated to one application, there is no way you can avoid this.) |
1458 | ||
1459 | On some systems, @code{sleep} can do strange things if your program uses | |
1460 | @code{SIGALRM} explicitly. Even if @code{SIGALRM} signals are being | |
1461 | ignored or blocked when @code{sleep} is called, @code{sleep} might | |
1462 | return prematurely on delivery of a @code{SIGALRM} signal. If you have | |
1463 | established a handler for @code{SIGALRM} signals and a @code{SIGALRM} | |
1464 | signal is delivered while the process is sleeping, the action taken | |
1465 | might be just to cause @code{sleep} to return instead of invoking your | |
1466 | handler. And, if @code{sleep} is interrupted by delivery of a signal | |
1467 | whose handler requests an alarm or alters the handling of @code{SIGALRM}, | |
1468 | this handler and @code{sleep} will interfere. | |
1469 | ||
1470 | On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in | |
1471 | the same program, because @code{sleep} does not work by means of | |
1472 | @code{SIGALRM}. | |
1473 | ||
dfd2257a UD |
1474 | @comment time.h |
1475 | @comment POSIX.1 | |
1476 | @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) | |
1477 | If the resolution of seconds is not enough the @code{nanosleep} function | |
1478 | can be used. As the name suggests the sleeping period can be specified | |
1479 | in nanoseconds. The actual period of waiting time might be longer since | |
1480 | the requested time in the @var{requested_time} parameter is rounded up | |
1481 | to the next integer multiple of the actual resolution of the system. | |
1482 | ||
1483 | If the function returns because the time has elapsed the return value is | |
1484 | zero. If the function return @math{-1} the global variable @var{errno} | |
1485 | is set to the following values: | |
1486 | ||
1487 | @table @code | |
1488 | @item EINTR | |
1489 | The call was interrupted because a signal was delivered to the thread. | |
1490 | If the @var{remaining} parameter is not the null pointer the structure | |
1491 | pointed to by @var{remaining} is updated to contain the remaining time. | |
1492 | ||
1493 | @item EINVAL | |
1494 | The nanosecond value in the @var{requested_time} parameter contains an | |
1495 | illegal value. Either the value is negative or greater than or equal to | |
1496 | 1000 million. | |
1497 | @end table | |
1498 | ||
1499 | This function is a cancelation point in multi-threaded programs. This | |
1500 | is a problem if the thread allocates some resources (like memory, file | |
1501 | descriptors, semaphores or whatever) at the time @code{nanosleep} is | |
1502 | called. If the thread gets canceled these resources stay allocated | |
1503 | until the program ends. To avoid this calls to @code{nanosleep} should | |
1504 | be protected using cancelation handlers. | |
1505 | @c ref pthread_cleanup_push / pthread_cleanup_pop | |
1506 | ||
1507 | The @code{nanosleep} function is declared in @file{time.h}. | |
1508 | @end deftypefun | |
1509 | ||
28f540f4 RM |
1510 | @node Resource Usage |
1511 | @section Resource Usage | |
1512 | ||
1513 | @pindex sys/resource.h | |
1514 | The function @code{getrusage} and the data type @code{struct rusage} | |
1515 | are used for examining the usage figures of a process. They are declared | |
1516 | in @file{sys/resource.h}. | |
1517 | ||
1518 | @comment sys/resource.h | |
1519 | @comment BSD | |
1520 | @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) | |
1521 | This function reports the usage totals for processes specified by | |
1522 | @var{processes}, storing the information in @code{*@var{rusage}}. | |
1523 | ||
1524 | In most systems, @var{processes} has only two valid values: | |
1525 | ||
1526 | @table @code | |
1527 | @comment sys/resource.h | |
1528 | @comment BSD | |
1529 | @item RUSAGE_SELF | |
1530 | Just the current process. | |
1531 | ||
1532 | @comment sys/resource.h | |
1533 | @comment BSD | |
1534 | @item RUSAGE_CHILDREN | |
1535 | All child processes (direct and indirect) that have terminated already. | |
1536 | @end table | |
1537 | ||
1538 | In the GNU system, you can also inquire about a particular child process | |
1539 | by specifying its process ID. | |
1540 | ||
1541 | The return value of @code{getrusage} is zero for success, and @code{-1} | |
1542 | for failure. | |
1543 | ||
1544 | @table @code | |
1545 | @item EINVAL | |
1546 | The argument @var{processes} is not valid. | |
1547 | @end table | |
1548 | @end deftypefun | |
1549 | ||
1550 | One way of getting usage figures for a particular child process is with | |
1551 | the function @code{wait4}, which returns totals for a child when it | |
1552 | terminates. @xref{BSD Wait Functions}. | |
1553 | ||
1554 | @comment sys/resource.h | |
1555 | @comment BSD | |
1556 | @deftp {Data Type} {struct rusage} | |
1557 | This data type records a collection usage amounts for various sorts of | |
1558 | resources. It has the following members, and possibly others: | |
1559 | ||
1560 | @table @code | |
1561 | @item struct timeval ru_utime | |
1562 | Time spent executing user instructions. | |
1563 | ||
1564 | @item struct timeval ru_stime | |
1565 | Time spent in operating system code on behalf of @var{processes}. | |
1566 | ||
1567 | @item long int ru_maxrss | |
1568 | The maximum resident set size used, in kilobytes. That is, the maximum | |
1569 | number of kilobytes that @var{processes} used in real memory simultaneously. | |
1570 | ||
1571 | @item long int ru_ixrss | |
1572 | An integral value expressed in kilobytes times ticks of execution, which | |
1573 | indicates the amount of memory used by text that was shared with other | |
1574 | processes. | |
1575 | ||
1576 | @item long int ru_idrss | |
1577 | An integral value expressed the same way, which is the amount of | |
1578 | unshared memory used in data. | |
1579 | ||
1580 | @item long int ru_isrss | |
1581 | An integral value expressed the same way, which is the amount of | |
1582 | unshared memory used in stack space. | |
1583 | ||
1584 | @item long int ru_minflt | |
1585 | The number of page faults which were serviced without requiring any I/O. | |
1586 | ||
1587 | @item long int ru_majflt | |
1588 | The number of page faults which were serviced by doing I/O. | |
1589 | ||
1590 | @item long int ru_nswap | |
1591 | The number of times @var{processes} was swapped entirely out of main memory. | |
1592 | ||
1593 | @item long int ru_inblock | |
1594 | The number of times the file system had to read from the disk on behalf | |
1595 | of @var{processes}. | |
1596 | ||
1597 | @item long int ru_oublock | |
1598 | The number of times the file system had to write to the disk on behalf | |
1599 | of @var{processes}. | |
1600 | ||
1601 | @item long int ru_msgsnd | |
1602 | Number of IPC messages sent. | |
1603 | ||
1604 | @item long ru_msgrcv | |
1605 | Number of IPC messages received. | |
1606 | ||
1607 | @item long int ru_nsignals | |
1608 | Number of signals received. | |
1609 | ||
1610 | @item long int ru_nvcsw | |
1611 | The number of times @var{processes} voluntarily invoked a context switch | |
1612 | (usually to wait for some service). | |
1613 | ||
1614 | @item long int ru_nivcsw | |
1615 | The number of times an involuntary context switch took place (because | |
1616 | the time slice expired, or another process of higher priority became | |
1617 | runnable). | |
1618 | @end table | |
1619 | @end deftp | |
1620 | ||
1621 | An additional historical function for examining usage figures, | |
1622 | @code{vtimes}, is supported but not documented here. It is declared in | |
1623 | @file{sys/vtimes.h}. | |
1624 | ||
1625 | @node Limits on Resources | |
1626 | @section Limiting Resource Usage | |
1627 | @cindex resource limits | |
1628 | @cindex limits on resource usage | |
1629 | @cindex usage limits | |
1630 | ||
1631 | You can specify limits for the resource usage of a process. When the | |
1632 | process tries to exceed a limit, it may get a signal, or the system call | |
1633 | by which it tried to do so may fail, depending on the limit. Each | |
1634 | process initially inherits its limit values from its parent, but it can | |
1635 | subsequently change them. | |
1636 | ||
1637 | @pindex sys/resource.h | |
1638 | The symbols in this section are defined in @file{sys/resource.h}. | |
1639 | ||
1640 | @comment sys/resource.h | |
1641 | @comment BSD | |
1642 | @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) | |
1643 | Read the current value and the maximum value of resource @var{resource} | |
1644 | and store them in @code{*@var{rlp}}. | |
1645 | ||
1646 | The return value is @code{0} on success and @code{-1} on failure. The | |
1647 | only possible @code{errno} error condition is @code{EFAULT}. | |
1648 | @end deftypefun | |
1649 | ||
1650 | @comment sys/resource.h | |
1651 | @comment BSD | |
1652 | @deftypefun int setrlimit (int @var{resource}, struct rlimit *@var{rlp}) | |
1653 | Store the current value and the maximum value of resource @var{resource} | |
1654 | in @code{*@var{rlp}}. | |
1655 | ||
1656 | The return value is @code{0} on success and @code{-1} on failure. The | |
1657 | following @code{errno} error condition is possible: | |
1658 | ||
1659 | @table @code | |
1660 | @item EPERM | |
1661 | You tried to change the maximum permissible limit value, | |
1662 | but you don't have privileges to do so. | |
1663 | @end table | |
1664 | @end deftypefun | |
1665 | ||
1666 | @comment sys/resource.h | |
1667 | @comment BSD | |
1668 | @deftp {Data Type} {struct rlimit} | |
1669 | This structure is used with @code{getrlimit} to receive limit values, | |
1670 | and with @code{setrlimit} to specify limit values. It has two fields: | |
1671 | ||
1672 | @table @code | |
1673 | @item rlim_cur | |
1674 | The current value of the limit in question. | |
1675 | This is also called the ``soft limit''. | |
1676 | @cindex soft limit | |
1677 | ||
1678 | @item rlim_max | |
1679 | The maximum permissible value of the limit in question. You cannot set | |
1680 | the current value of the limit to a larger number than this maximum. | |
1681 | Only the super user can change the maximum permissible value. | |
1682 | This is also called the ``hard limit''. | |
1683 | @cindex hard limit | |
1684 | @end table | |
1685 | ||
1686 | In @code{getrlimit}, the structure is an output; it receives the current | |
1687 | values. In @code{setrlimit}, it specifies the new values. | |
1688 | @end deftp | |
1689 | ||
1690 | Here is a list of resources that you can specify a limit for. | |
1691 | Those that are sizes are measured in bytes. | |
1692 | ||
1693 | @table @code | |
1694 | @comment sys/resource.h | |
1695 | @comment BSD | |
1696 | @item RLIMIT_CPU | |
1697 | @vindex RLIMIT_CPU | |
1698 | The maximum amount of cpu time the process can use. If it runs for | |
1699 | longer than this, it gets a signal: @code{SIGXCPU}. The value is | |
1700 | measured in seconds. @xref{Operation Error Signals}. | |
1701 | ||
1702 | @comment sys/resource.h | |
1703 | @comment BSD | |
1704 | @item RLIMIT_FSIZE | |
1705 | @vindex RLIMIT_FSIZE | |
1706 | The maximum size of file the process can create. Trying to write a | |
1707 | larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error | |
1708 | Signals}. | |
1709 | ||
1710 | @comment sys/resource.h | |
1711 | @comment BSD | |
1712 | @item RLIMIT_DATA | |
1713 | @vindex RLIMIT_DATA | |
1714 | The maximum size of data memory for the process. If the process tries | |
1715 | to allocate data memory beyond this amount, the allocation function | |
1716 | fails. | |
1717 | ||
1718 | @comment sys/resource.h | |
1719 | @comment BSD | |
1720 | @item RLIMIT_STACK | |
1721 | @vindex RLIMIT_STACK | |
1722 | The maximum stack size for the process. If the process tries to extend | |
1723 | its stack past this size, it gets a @code{SIGSEGV} signal. | |
1724 | @xref{Program Error Signals}. | |
1725 | ||
1726 | @comment sys/resource.h | |
1727 | @comment BSD | |
1728 | @item RLIMIT_CORE | |
1729 | @vindex RLIMIT_CORE | |
1730 | The maximum size core file that this process can create. If the process | |
1731 | terminates and would dump a core file larger than this maximum size, | |
1732 | then no core file is created. So setting this limit to zero prevents | |
1733 | core files from ever being created. | |
1734 | ||
1735 | @comment sys/resource.h | |
1736 | @comment BSD | |
1737 | @item RLIMIT_RSS | |
1738 | @vindex RLIMIT_RSS | |
1739 | The maximum amount of physical memory that this process should get. | |
1740 | This parameter is a guide for the system's scheduler and memory | |
1741 | allocator; the system may give the process more memory when there is a | |
1742 | surplus. | |
1743 | ||
1744 | @comment sys/resource.h | |
1745 | @comment BSD | |
1746 | @item RLIMIT_MEMLOCK | |
1747 | The maximum amount of memory that can be locked into physical memory (so | |
1748 | it will never be paged out). | |
1749 | ||
1750 | @comment sys/resource.h | |
1751 | @comment BSD | |
1752 | @item RLIMIT_NPROC | |
1753 | The maximum number of processes that can be created with the same user ID. | |
1754 | If you have reached the limit for your user ID, @code{fork} will fail | |
1755 | with @code{EAGAIN}. @xref{Creating a Process}. | |
1756 | ||
1757 | @comment sys/resource.h | |
1758 | @comment BSD | |
1759 | @item RLIMIT_NOFILE | |
1760 | @vindex RLIMIT_NOFILE | |
1761 | @itemx RLIMIT_OFILE | |
1762 | @vindex RLIMIT_OFILE | |
1763 | The maximum number of files that the process can open. If it tries to | |
1764 | open more files than this, it gets error code @code{EMFILE}. | |
1765 | @xref{Error Codes}. Not all systems support this limit; GNU does, and | |
1766 | 4.4 BSD does. | |
1767 | ||
1768 | @comment sys/resource.h | |
1769 | @comment BSD | |
1770 | @item RLIM_NLIMITS | |
1771 | @vindex RLIM_NLIMITS | |
1772 | The number of different resource limits. Any valid @var{resource} | |
1773 | operand must be less than @code{RLIM_NLIMITS}. | |
1774 | @end table | |
1775 | ||
1776 | @comment sys/resource.h | |
1777 | @comment BSD | |
310b3460 | 1778 | @deftypevr Constant int RLIM_INFINITY |
28f540f4 RM |
1779 | This constant stands for a value of ``infinity'' when supplied as |
1780 | the limit value in @code{setrlimit}. | |
310b3460 | 1781 | @end deftypevr |
28f540f4 RM |
1782 | |
1783 | @c ??? Someone want to finish these? | |
1784 | Two historical functions for setting resource limits, @code{ulimit} and | |
1785 | @code{vlimit}, are not documented here. The latter is declared in | |
1786 | @file{sys/vlimit.h} and comes from BSD. | |
1787 | ||
1788 | @node Priority | |
1789 | @section Process Priority | |
1790 | @cindex process priority | |
1791 | @cindex priority of a process | |
1792 | ||
1793 | @pindex sys/resource.h | |
1794 | When several processes try to run, their respective priorities determine | |
1795 | what share of the CPU each process gets. This section describes how you | |
1796 | can read and set the priority of a process. All these functions and | |
1797 | macros are declared in @file{sys/resource.h}. | |
1798 | ||
1799 | The range of valid priority values depends on the operating system, but | |
1800 | typically it runs from @code{-20} to @code{20}. A lower priority value | |
1801 | means the process runs more often. These constants describe the range of | |
1802 | priority values: | |
1803 | ||
1804 | @table @code | |
1805 | @comment sys/resource.h | |
1806 | @comment BSD | |
1807 | @item PRIO_MIN | |
1808 | @vindex PRIO_MIN | |
1809 | The smallest valid priority value. | |
1810 | ||
1811 | @comment sys/resource.h | |
1812 | @comment BSD | |
1813 | @item PRIO_MAX | |
1814 | @vindex PRIO_MAX | |
74015205 | 1815 | The largest valid priority value. |
28f540f4 RM |
1816 | @end table |
1817 | ||
1818 | @comment sys/resource.h | |
1819 | @comment BSD | |
1820 | @deftypefun int getpriority (int @var{class}, int @var{id}) | |
1821 | Read the priority of a class of processes; @var{class} and @var{id} | |
1822 | specify which ones (see below). If the processes specified do not all | |
1823 | have the same priority, this returns the smallest value that any of them | |
1824 | has. | |
1825 | ||
1826 | The return value is the priority value on success, and @code{-1} on | |
1827 | failure. The following @code{errno} error condition are possible for | |
1828 | this function: | |
1829 | ||
1830 | @table @code | |
1831 | @item ESRCH | |
1832 | The combination of @var{class} and @var{id} does not match any existing | |
1833 | process. | |
1834 | ||
1835 | @item EINVAL | |
1836 | The value of @var{class} is not valid. | |
1837 | @end table | |
1838 | ||
1839 | When the return value is @code{-1}, it could indicate failure, or it | |
1840 | could be the priority value. The only way to make certain is to set | |
1841 | @code{errno = 0} before calling @code{getpriority}, then use @code{errno | |
1842 | != 0} afterward as the criterion for failure. | |
1843 | @end deftypefun | |
1844 | ||
1845 | @comment sys/resource.h | |
1846 | @comment BSD | |
1847 | @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority}) | |
1848 | Set the priority of a class of processes to @var{priority}; @var{class} | |
1849 | and @var{id} specify which ones (see below). | |
1850 | ||
1851 | The return value is @code{0} on success and @code{-1} on failure. The | |
1852 | following @code{errno} error condition are defined for this function: | |
1853 | ||
1854 | @table @code | |
1855 | @item ESRCH | |
1856 | The combination of @var{class} and @var{id} does not match any existing | |
1857 | process. | |
1858 | ||
1859 | @item EINVAL | |
1860 | The value of @var{class} is not valid. | |
1861 | ||
1862 | @item EPERM | |
1863 | You tried to set the priority of some other user's process, and you | |
1864 | don't have privileges for that. | |
1865 | ||
1866 | @item EACCES | |
1867 | You tried to lower the priority of a process, and you don't have | |
1868 | privileges for that. | |
1869 | @end table | |
1870 | @end deftypefun | |
1871 | ||
1872 | The arguments @var{class} and @var{id} together specify a set of | |
1873 | processes you are interested in. These are the possible values for | |
1874 | @var{class}: | |
1875 | ||
1876 | @table @code | |
1877 | @comment sys/resource.h | |
1878 | @comment BSD | |
1879 | @item PRIO_PROCESS | |
1880 | @vindex PRIO_PROCESS | |
1881 | Read or set the priority of one process. The argument @var{id} is a | |
1882 | process ID. | |
1883 | ||
1884 | @comment sys/resource.h | |
1885 | @comment BSD | |
1886 | @item PRIO_PGRP | |
1887 | @vindex PRIO_PGRP | |
1888 | Read or set the priority of one process group. The argument @var{id} is | |
1889 | a process group ID. | |
1890 | ||
1891 | @comment sys/resource.h | |
1892 | @comment BSD | |
1893 | @item PRIO_USER | |
1894 | @vindex PRIO_USER | |
1895 | Read or set the priority of one user's processes. The argument @var{id} | |
1896 | is a user ID. | |
1897 | @end table | |
1898 | ||
1899 | If the argument @var{id} is 0, it stands for the current process, | |
1900 | current process group, or the current user, according to @var{class}. | |
1901 | ||
1902 | @c ??? I don't know where we should say this comes from. | |
1903 | @comment Unix | |
1904 | @comment dunno.h | |
1905 | @deftypefun int nice (int @var{increment}) | |
1906 | Increment the priority of the current process by @var{increment}. | |
1907 | The return value is the same as for @code{setpriority}. | |
1908 | ||
1909 | Here is an equivalent definition for @code{nice}: | |
1910 | ||
1911 | @smallexample | |
1912 | int | |
1913 | nice (int increment) | |
1914 | @{ | |
1915 | int old = getpriority (PRIO_PROCESS, 0); | |
1916 | return setpriority (PRIO_PROCESS, 0, old + increment); | |
1917 | @} | |
1918 | @end smallexample | |
1919 | @end deftypefun |