1 @node Date and Time, Resource Usage And Limitation, Arithmetic, Top
2 @c %MENU% Functions for getting the date and time and formatting them nicely
5 This chapter describes functions for manipulating dates and times,
6 including functions for determining what time it is and conversion
7 between different time representations.
10 * Time Basics:: Concepts and definitions.
11 * Elapsed Time:: Data types to represent elapsed times
12 * Processor And CPU Time:: Time a program has spent executing.
13 * Calendar Time:: Manipulation of ``real'' dates and times.
14 * Setting an Alarm:: Sending a signal after a specified time.
15 * Sleeping:: Waiting for a period of time.
23 Discussing time in a technical manual can be difficult because the word
24 ``time'' in English refers to lots of different things. In this manual,
25 we use a rigorous terminology to avoid confusion, and the only thing we
26 use the simple word ``time'' for is to talk about the abstract concept.
28 A @dfn{calendar time} is a point in the time continuum, for example
29 November 4, 1990, at 18:02.5 UTC. Sometimes this is called ``absolute
33 We don't speak of a ``date'', because that is inherent in a calendar
37 An @dfn{interval} is a contiguous part of the time continuum between two
38 calendar times, for example the hour between 9:00 and 10:00 on July 4,
42 An @dfn{elapsed time} is the length of an interval, for example, 35
43 minutes. People sometimes sloppily use the word ``interval'' to refer
44 to the elapsed time of some interval.
48 An @dfn{amount of time} is a sum of elapsed times, which need not be of
49 any specific intervals. For example, the amount of time it takes to
50 read a book might be 9 hours, independently of when and in how many
53 A @dfn{period} is the elapsed time of an interval between two events,
54 especially when they are part of a sequence of regularly repeating
56 @cindex period of time
58 @dfn{CPU time} is like calendar time, except that it is based on the
59 subset of the time continuum when a particular process is actively
60 using a CPU. CPU time is, therefore, relative to a process.
63 @dfn{Processor time} is an amount of time that a CPU is in use. In
64 fact, it's a basic system resource, since there's a limit to how much
65 can exist in any given interval (that limit is the elapsed time of the
66 interval times the number of CPUs in the processor). People often call
67 this CPU time, but we reserve the latter term in this manual for the
69 @cindex processor time
75 One way to represent an elapsed time is with a simple arithmetic data
76 type, as with the following function to compute the elapsed time between
77 two calendar times. This function is declared in @file{time.h}.
79 @deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
80 @standards{ISO, time.h}
81 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
82 The @code{difftime} function returns the number of seconds of elapsed
83 time between calendar time @var{time1} and calendar time @var{time0}, as
84 a value of type @code{double}. The difference ignores leap seconds
85 unless leap second support is enabled.
87 In @theglibc{}, you can simply subtract @code{time_t} values. But on
88 other systems, the @code{time_t} data type might use some other encoding
89 where subtraction doesn't work directly.
92 @Theglibc{} provides two data types specifically for representing
93 an elapsed time. They are used by various @glibcadj{} functions, and
94 you can use them for your own purposes too. They're exactly the same
95 except that one has a resolution in microseconds, and the other, newer
96 one, is in nanoseconds.
98 @deftp {Data Type} {struct timeval}
99 @standards{BSD, sys/time.h}
101 The @code{struct timeval} structure represents an elapsed time. It is
102 declared in @file{sys/time.h} and has the following members:
106 This represents the number of whole seconds of elapsed time.
108 @item long int tv_usec
109 This is the rest of the elapsed time (a fraction of a second),
110 represented as the number of microseconds. It is always less than one
116 @deftp {Data Type} {struct timespec}
117 @standards{POSIX.1, sys/time.h}
119 The @code{struct timespec} structure represents an elapsed time. It is
120 declared in @file{time.h} and has the following members:
124 This represents the number of whole seconds of elapsed time.
126 @item long int tv_nsec
127 This is the rest of the elapsed time (a fraction of a second),
128 represented as the number of nanoseconds. It is always less than one
134 It is often necessary to subtract two values of type @w{@code{struct
135 timeval}} or @w{@code{struct timespec}}. Here is the best way to do
136 this. It works even on some peculiar operating systems where the
137 @code{tv_sec} member has an unsigned type.
140 @include timeval_subtract.c.texi
143 Common functions that use @code{struct timeval} are @code{gettimeofday}
144 and @code{settimeofday}.
147 There are no @glibcadj{} functions specifically oriented toward
148 dealing with elapsed times, but the calendar time, processor time, and
149 alarm and sleeping functions have a lot to do with them.
152 @node Processor And CPU Time
153 @section Processor And CPU Time
155 If you're trying to optimize your program or measure its efficiency,
156 it's very useful to know how much processor time it uses. For that,
157 calendar time and elapsed times are useless because a process may spend
158 time waiting for I/O or for other processes to use the CPU. However,
159 you can get the information with the functions in this section.
161 CPU time (@pxref{Time Basics}) is represented by the data type
162 @code{clock_t}, which is a number of @dfn{clock ticks}. It gives the
163 total amount of time a process has actively used a CPU since some
164 arbitrary event. On @gnusystems{}, that event is the creation of the
165 process. While arbitrary in general, the event is always the same event
166 for any particular process, so you can always measure how much time on
167 the CPU a particular computation takes by examining the process' CPU
168 time before and after the computation.
173 On @gnulinuxhurdsystems{}, @code{clock_t} is equivalent to @code{long int} and
174 @code{CLOCKS_PER_SEC} is an integer value. But in other systems, both
175 @code{clock_t} and the macro @code{CLOCKS_PER_SEC} can be either integer
176 or floating-point types. Casting CPU time values to @code{double}, as
177 in the example above, makes sure that operations such as arithmetic and
178 printing work properly and consistently no matter what the underlying
181 Note that the clock can wrap around. On a 32bit system with
182 @code{CLOCKS_PER_SEC} set to one million this function will return the
183 same value approximately every 72 minutes.
185 For additional functions to examine a process' use of processor time,
186 and to control it, see @ref{Resource Usage And Limitation}.
190 * CPU Time:: The @code{clock} function.
191 * Processor Time:: The @code{times} function.
195 @subsection CPU Time Inquiry
197 To get a process' CPU time, you can use the @code{clock} function. This
198 facility is declared in the header file @file{time.h}.
201 In typical usage, you call the @code{clock} function at the beginning
202 and end of the interval you want to time, subtract the values, and then
203 divide by @code{CLOCKS_PER_SEC} (the number of clock ticks per second)
204 to get processor time, like this:
211 double cpu_time_used;
214 @dots{} /* @r{Do the work.} */
216 cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
220 Do not use a single CPU time as an amount of time; it doesn't work that
221 way. Either do a subtraction as shown above or query processor time
222 directly. @xref{Processor Time}.
224 Different computers and operating systems vary wildly in how they keep
225 track of CPU time. It's common for the internal processor clock
226 to have a resolution somewhere between a hundredth and millionth of a
229 @deftypevr Macro int CLOCKS_PER_SEC
230 @standards{ISO, time.h}
231 The value of this macro is the number of clock ticks per second measured
232 by the @code{clock} function. POSIX requires that this value be one
233 million independent of the actual resolution.
236 @deftp {Data Type} clock_t
237 @standards{ISO, time.h}
238 This is the type of the value returned by the @code{clock} function.
239 Values of type @code{clock_t} are numbers of clock ticks.
242 @deftypefun clock_t clock (void)
243 @standards{ISO, time.h}
244 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
245 @c On Hurd, this calls task_info twice and adds user and system time
246 @c from both basic and thread time info structs. On generic posix,
247 @c calls times and adds utime and stime. On bsd, calls getrusage and
248 @c safely converts stime and utime to clock. On linux, calls
250 This function returns the calling process' current CPU time. If the CPU
251 time is not available or cannot be represented, @code{clock} returns the
252 value @code{(clock_t)(-1)}.
257 @subsection Processor Time Inquiry
259 The @code{times} function returns information about a process'
260 consumption of processor time in a @w{@code{struct tms}} object, in
261 addition to the process' CPU time. @xref{Time Basics}. You should
262 include the header file @file{sys/times.h} to use this facility.
263 @cindex processor time
267 @deftp {Data Type} {struct tms}
268 @standards{POSIX.1, sys/times.h}
269 The @code{tms} structure is used to return information about process
270 times. It contains at least the following members:
273 @item clock_t tms_utime
274 This is the total processor time the calling process has used in
275 executing the instructions of its program.
277 @item clock_t tms_stime
278 This is the processor time the system has used on behalf of the calling
281 @item clock_t tms_cutime
282 This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
283 values of all terminated child processes of the calling process, whose
284 status has been reported to the parent process by @code{wait} or
285 @code{waitpid}; see @ref{Process Completion}. In other words, it
286 represents the total processor time used in executing the instructions
287 of all the terminated child processes of the calling process, excluding
288 child processes which have not yet been reported by @code{wait} or
290 @cindex child process
292 @item clock_t tms_cstime
293 This is similar to @code{tms_cutime}, but represents the total processor
294 time the system has used on behalf of all the terminated child processes
295 of the calling process.
298 All of the times are given in numbers of clock ticks. Unlike CPU time,
299 these are the actual amounts of time; not relative to any event.
300 @xref{Creating a Process}.
303 @deftypevr Macro int CLK_TCK
304 @standards{POSIX.1, time.h}
305 This is an obsolete name for the number of clock ticks per second. Use
306 @code{sysconf (_SC_CLK_TCK)} instead.
309 @deftypefun clock_t times (struct tms *@var{buffer})
310 @standards{POSIX.1, sys/times.h}
311 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
312 @c On HURD, this calls task_info twice, for basic and thread times info,
313 @c adding user and system times into tms, and then gettimeofday, to
314 @c compute the real time. On BSD, it calls getclktck, getrusage (twice)
315 @c and time. On Linux, it's a syscall with special handling to account
316 @c for clock_t counts that look like error values.
317 The @code{times} function stores the processor time information for
318 the calling process in @var{buffer}.
320 The return value is the number of clock ticks since an arbitrary point
321 in the past, e.g. since system start-up. @code{times} returns
322 @code{(clock_t)(-1)} to indicate failure.
325 @strong{Portability Note:} The @code{clock} function described in
326 @ref{CPU Time} is specified by the @w{ISO C} standard. The
327 @code{times} function is a feature of POSIX.1. On @gnusystems{}, the
328 CPU time is defined to be equivalent to the sum of the @code{tms_utime}
329 and @code{tms_stime} fields returned by @code{times}.
332 @section Calendar Time
334 This section describes facilities for keeping track of calendar time.
337 @Theglibc{} represents calendar time three ways:
341 @dfn{Simple time} (the @code{time_t} data type) is a compact
342 representation, typically giving the number of seconds of elapsed time
343 since some implementation-specific base time.
347 There is also a "high-resolution time" representation. Like simple
348 time, this represents a calendar time as an elapsed time since a base
349 time, but instead of measuring in whole seconds, it uses a @code{struct
350 timeval} data type, which includes fractions of a second. Use this time
351 representation instead of simple time when you need greater precision.
352 @cindex high-resolution time
355 @dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data
356 type) represents a calendar time as a set of components specifying the
357 year, month, and so on in the Gregorian calendar, for a specific time
358 zone. This calendar time representation is usually used only to
359 communicate with people.
361 @cindex broken-down time
362 @cindex Gregorian calendar
363 @cindex calendar, Gregorian
367 * Simple Calendar Time:: Facilities for manipulating calendar time.
368 * High-Resolution Calendar:: A time representation with greater precision.
369 * Broken-down Time:: Facilities for manipulating local time.
370 * High Accuracy Clock:: Maintaining a high accuracy system clock.
371 * Formatting Calendar Time:: Converting times to strings.
372 * Parsing Date and Time:: Convert textual time and date information back
373 into broken-down time values.
374 * TZ Variable:: How users specify the time zone.
375 * Time Zone Functions:: Functions to examine or specify the time zone.
376 * Time Functions Example:: An example program showing use of some of
380 @node Simple Calendar Time
381 @subsection Simple Calendar Time
383 This section describes the @code{time_t} data type for representing calendar
384 time as simple time, and the functions which operate on simple time objects.
385 These facilities are declared in the header file @file{time.h}.
389 @deftp {Data Type} time_t
390 @standards{ISO, time.h}
391 This is the data type used to represent simple time. Sometimes, it also
392 represents an elapsed time. When interpreted as a calendar time value,
393 it represents the number of seconds elapsed since 00:00:00 on January 1,
394 1970, Coordinated Universal Time. (This calendar time is sometimes
395 referred to as the @dfn{epoch}.) POSIX requires that this count not
396 include leap seconds, but on some systems this count includes leap seconds
397 if you set @code{TZ} to certain values (@pxref{TZ Variable}).
399 Note that a simple time has no concept of local time zone. Calendar
400 Time @var{T} is the same instant in time regardless of where on the
401 globe the computer is.
403 In @theglibc{}, @code{time_t} is equivalent to @code{long int}.
404 In other systems, @code{time_t} might be either an integer or
408 The function @code{difftime} tells you the elapsed time between two
409 simple calendar times, which is not always as easy to compute as just
410 subtracting. @xref{Elapsed Time}.
412 @deftypefun time_t time (time_t *@var{result})
413 @standards{ISO, time.h}
414 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
415 The @code{time} function returns the current calendar time as a value of
416 type @code{time_t}. If the argument @var{result} is not a null pointer,
417 the calendar time value is also stored in @code{*@var{result}}. If the
418 current calendar time is not available, the value
419 @w{@code{(time_t)(-1)}} is returned.
422 @c The GNU C library implements stime() with a call to settimeofday() on
424 @deftypefun int stime (const time_t *@var{newtime})
425 @standards{SVID, time.h}
426 @standards{XPG, time.h}
427 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
428 @c On unix, this is implemented in terms of settimeofday.
429 @code{stime} sets the system clock, i.e., it tells the system that the
430 current calendar time is @var{newtime}, where @code{newtime} is
431 interpreted as described in the above definition of @code{time_t}.
433 @code{settimeofday} is a newer function which sets the system clock to
434 better than one second precision. @code{settimeofday} is generally a
435 better choice than @code{stime}. @xref{High-Resolution Calendar}.
437 Only the superuser can set the system clock.
439 If the function succeeds, the return value is zero. Otherwise, it is
440 @code{-1} and @code{errno} is set accordingly:
444 The process is not superuser.
450 @node High-Resolution Calendar
451 @subsection High-Resolution Calendar
453 The @code{time_t} data type used to represent simple times has a
454 resolution of only one second. Some applications need more precision.
456 So, @theglibc{} also contains functions which are capable of
457 representing calendar times to a higher resolution than one second. The
458 functions and the associated data types described in this section are
459 declared in @file{sys/time.h}.
462 @deftp {Data Type} {struct timezone}
463 @standards{BSD, sys/time.h}
464 The @code{struct timezone} structure is used to hold minimal information
465 about the local time zone. It has the following members:
468 @item int tz_minuteswest
469 This is the number of minutes west of UTC.
472 If nonzero, Daylight Saving Time applies during some part of the year.
475 The @code{struct timezone} type is obsolete and should never be used.
476 Instead, use the facilities described in @ref{Time Zone Functions}.
479 @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
480 @standards{BSD, sys/time.h}
481 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
482 @c On most GNU/Linux systems this is a direct syscall, but the posix/
483 @c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and
484 @c localtime_r, saving and restoring tzname in an unsafe manner.
485 @c On some GNU/Linux variants, ifunc resolvers are used in shared libc
486 @c for vdso resolution. ifunc-vdso-revisit.
487 The @code{gettimeofday} function returns the current calendar time as
488 the elapsed time since the epoch in the @code{struct timeval} structure
489 indicated by @var{tp}. (@pxref{Elapsed Time} for a description of
490 @code{struct timeval}). Information about the time zone is returned in
491 the structure pointed to by @var{tzp}. If the @var{tzp} argument is a null
492 pointer, time zone information is ignored.
494 The return value is @code{0} on success and @code{-1} on failure. The
495 following @code{errno} error condition is defined for this function:
499 The operating system does not support getting time zone information, and
500 @var{tzp} is not a null pointer. @gnusystems{} do not
501 support using @w{@code{struct timezone}} to represent time zone
502 information; that is an obsolete feature of 4.3 BSD.
503 Instead, use the facilities described in @ref{Time Zone Functions}.
507 @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
508 @standards{BSD, sys/time.h}
509 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
510 @c On HURD, it calls host_set_time with a privileged port. On other
511 @c unix systems, it's a syscall.
512 The @code{settimeofday} function sets the current calendar time in the
513 system clock according to the arguments. As for @code{gettimeofday},
514 the calendar time is represented as the elapsed time since the epoch.
515 As for @code{gettimeofday}, time zone information is ignored if
516 @var{tzp} is a null pointer.
518 You must be a privileged user in order to use @code{settimeofday}.
520 Some kernels automatically set the system clock from some source such as
521 a hardware clock when they start up. Others, including Linux, place the
522 system clock in an ``invalid'' state (in which attempts to read the clock
523 fail). A call of @code{stime} removes the system clock from an invalid
524 state, and system startup scripts typically run a program that calls
527 @code{settimeofday} causes a sudden jump forwards or backwards, which
528 can cause a variety of problems in a system. Use @code{adjtime} (below)
529 to make a smooth transition from one time to another by temporarily
530 speeding up or slowing down the clock.
532 With a Linux kernel, @code{adjtimex} does the same thing and can also
533 make permanent changes to the speed of the system clock so it doesn't
534 need to be corrected as often.
536 The return value is @code{0} on success and @code{-1} on failure. The
537 following @code{errno} error conditions are defined for this function:
541 This process cannot set the clock because it is not privileged.
544 The operating system does not support setting time zone information, and
545 @var{tzp} is not a null pointer.
549 @c On Linux, GNU libc implements adjtime() as a call to adjtimex().
550 @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
551 @standards{BSD, sys/time.h}
552 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
553 @c On hurd and mach, call host_adjust_time with a privileged port. On
554 @c Linux, it's implemented in terms of adjtimex. On other unixen, it's
556 This function speeds up or slows down the system clock in order to make
557 a gradual adjustment. This ensures that the calendar time reported by
558 the system clock is always monotonically increasing, which might not
559 happen if you simply set the clock.
561 The @var{delta} argument specifies a relative adjustment to be made to
562 the clock time. If negative, the system clock is slowed down for a
563 while until it has lost this much elapsed time. If positive, the system
564 clock is speeded up for a while.
566 If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
567 function returns information about any previous time adjustment that
568 has not yet completed.
570 This function is typically used to synchronize the clocks of computers
571 in a local network. You must be a privileged user to use it.
573 With a Linux kernel, you can use the @code{adjtimex} function to
574 permanently change the clock speed.
576 The return value is @code{0} on success and @code{-1} on failure. The
577 following @code{errno} error condition is defined for this function:
581 You do not have privilege to set the time.
585 @strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday},
586 and @code{adjtime} functions are derived from BSD.
589 Symbols for the following function are declared in @file{sys/timex.h}.
591 @deftypefun int adjtimex (struct timex *@var{timex})
592 @standards{GNU, sys/timex.h}
593 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
594 @c It's a syscall, only available on linux.
596 @code{adjtimex} is functionally identical to @code{ntp_adjtime}.
597 @xref{High Accuracy Clock}.
599 This function is present only with a Linux kernel.
603 @node Broken-down Time
604 @subsection Broken-down Time
605 @cindex broken-down time
606 @cindex calendar time and broken-down time
608 Calendar time is represented by the usual @glibcadj{} functions as an
609 elapsed time since a fixed base calendar time. This is convenient for
610 computation, but has no relation to the way people normally think of
611 calendar time. By contrast, @dfn{broken-down time} is a binary
612 representation of calendar time separated into year, month, day, and so
613 on. Broken-down time values are not useful for calculations, but they
614 are useful for printing human readable time information.
616 A broken-down time value is always relative to a choice of time
617 zone, and it also indicates which time zone that is.
619 The symbols in this section are declared in the header file @file{time.h}.
621 @deftp {Data Type} {struct tm}
622 @standards{ISO, time.h}
623 This is the data type used to represent a broken-down time. The structure
624 contains at least the following members, which can appear in any order.
628 This is the number of full seconds since the top of the minute (normally
629 in the range @code{0} through @code{59}, but the actual upper limit is
630 @code{60}, to allow for leap seconds if leap second support is
635 This is the number of full minutes since the top of the hour (in the
636 range @code{0} through @code{59}).
639 This is the number of full hours past midnight (in the range @code{0} through
643 This is the ordinal day of the month (in the range @code{1} through @code{31}).
644 Watch out for this one! As the only ordinal number in the structure, it is
645 inconsistent with the rest of the structure.
648 This is the number of full calendar months since the beginning of the
649 year (in the range @code{0} through @code{11}). Watch out for this one!
650 People usually use ordinal numbers for month-of-year (where January = 1).
653 This is the number of full calendar years since 1900.
656 This is the number of full days since Sunday (in the range @code{0} through
660 This is the number of full days since the beginning of the year (in the
661 range @code{0} through @code{365}).
664 @cindex Daylight Saving Time
666 This is a flag that indicates whether Daylight Saving Time is (or was, or
667 will be) in effect at the time described. The value is positive if
668 Daylight Saving Time is in effect, zero if it is not, and negative if the
669 information is not available.
671 @item long int tm_gmtoff
672 This field describes the time zone that was used to compute this
673 broken-down time value, including any adjustment for daylight saving; it
674 is the number of seconds that you must add to UTC to get local time.
675 You can also think of this as the number of seconds east of UTC. For
676 example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}.
677 The @code{tm_gmtoff} field is derived from BSD and is a GNU library
678 extension; it is not visible in a strict @w{ISO C} environment.
680 @item const char *tm_zone
681 This field is the name for the time zone that was used to compute this
682 broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and
683 GNU extension, and is not visible in a strict @w{ISO C} environment.
688 @deftypefun {struct tm *} localtime (const time_t *@var{time})
689 @standards{ISO, time.h}
690 @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
691 @c Calls tz_convert with a static buffer.
692 @c localtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
693 @c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
694 The @code{localtime} function converts the simple time pointed to by
695 @var{time} to broken-down time representation, expressed relative to the
696 user's specified time zone.
698 The return value is a pointer to a static broken-down time structure, which
699 might be overwritten by subsequent calls to @code{ctime}, @code{gmtime},
700 or @code{localtime}. (But no other library function overwrites the contents
703 The return value is the null pointer if @var{time} cannot be represented
704 as a broken-down time; typically this is because the year cannot fit into
707 Calling @code{localtime} also sets the current time zone as if
708 @code{tzset} were called. @xref{Time Zone Functions}.
711 Using the @code{localtime} function is a big problem in multi-threaded
712 programs. The result is returned in a static buffer and this is used in
713 all threads. POSIX.1c introduced a variant of this function.
715 @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp})
716 @standards{POSIX.1c, time.h}
717 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
718 @c localtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
719 @c tz_convert(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
720 @c libc_lock_lock dup @asulock @aculock
721 @c tzset_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
722 @c always called with tzset_lock held
723 @c sets static is_initialized before initialization;
724 @c reads and sets old_tz; sets tz_rules.
725 @c some of the issues only apply on the first call.
726 @c subsequent calls only trigger these when called by localtime;
727 @c otherwise, they're ok.
728 @c getenv dup @mtsenv
731 @c tzfile_read @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
734 @c getenv dup @mtsenv
735 @c asprintf dup @mtslocale @ascuheap @acsmem
737 @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
740 @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
741 @c free dup @ascuheap @acsmem
742 @c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive]
743 @c fread_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
747 @c fseek dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
748 @c ftello dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
749 @c malloc dup @ascuheap @acsmem
752 @c getc_unlocked ok [no @mtasurace:stream @asucorrupt @acucorrupt]
753 @c tzstring dup @ascuheap @acsmem
754 @c compute_tzname_max dup ok [guarded by tzset_lock]
756 @c update_vars ok [guarded by tzset_lock]
757 @c sets daylight, timezone, tzname and tzname_cur_max;
758 @c called only with tzset_lock held, unless tzset_parse_tz
759 @c (internal, but not static) gets called by users; given the its
760 @c double-underscore-prefixed name, this interface violation could
761 @c be regarded as undefined behavior.
763 @c tzset_parse_tz @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
764 @c sscanf dup @mtslocale @ascuheap @acsmem
765 @c isalnum dup @mtsenv
766 @c tzstring @ascuheap @acsmem
767 @c reads and changes tzstring_list without synchronization, but
768 @c only called with tzset_lock held (save for interface violations)
770 @c malloc dup @ascuheap @acsmem
772 @c isdigit dup @mtslocale
774 @c tzfile_default @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
775 @c sets tzname, timezone, types, zone_names, rule_*off, etc; no guards
777 @c tzfile_read dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
779 @c compute_tzname_max ok [if guarded by tzset_lock]
780 @c iterates over zone_names; no guards
781 @c free dup @ascuheap @acsmem
782 @c strtoul dup @mtslocale
783 @c update_vars dup ok
784 @c tzfile_compute(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
785 @c sets tzname; no guards. with !use_localtime, as in gmtime, it's ok
786 @c tzstring dup @acsuheap @acsmem
787 @c tzset_parse_tz dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
796 @c libc_lock_unlock dup @aculock
798 The @code{localtime_r} function works just like the @code{localtime}
799 function. It takes a pointer to a variable containing a simple time
800 and converts it to the broken-down time format.
802 But the result is not placed in a static buffer. Instead it is placed
803 in the object of type @code{struct tm} to which the parameter
804 @var{resultp} points.
806 If the conversion is successful the function returns a pointer to the
807 object the result was written into, i.e., it returns @var{resultp}.
811 @deftypefun {struct tm *} gmtime (const time_t *@var{time})
812 @standards{ISO, time.h}
813 @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
814 @c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
815 @c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
816 This function is similar to @code{localtime}, except that the broken-down
817 time is expressed as Coordinated Universal Time (UTC) (formerly called
818 Greenwich Mean Time (GMT)) rather than relative to a local time zone.
822 As for the @code{localtime} function we have the problem that the result
823 is placed in a static variable. POSIX.1c also provides a replacement for
826 @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp})
827 @standards{POSIX.1c, time.h}
828 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
829 @c You'd think tz_convert could avoid some safety issues with
830 @c !use_localtime, but no such luck: tzset_internal will always bring
831 @c about all possible AS and AC problems when it's first called.
832 @c Calling any of localtime,gmtime_r once would run the initialization
833 @c and avoid the heap, mem and fd issues in gmtime* in subsequent calls,
834 @c but the unsafe locking would remain.
835 @c gmtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
836 @c tz_convert(gmtime_r) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
837 This function is similar to @code{localtime_r}, except that it converts
838 just like @code{gmtime} the given time as Coordinated Universal Time.
840 If the conversion is successful the function returns a pointer to the
841 object the result was written into, i.e., it returns @var{resultp}.
845 @deftypefun time_t mktime (struct tm *@var{brokentime})
846 @standards{ISO, time.h}
847 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
848 @c mktime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
849 @c passes a static localtime_offset to mktime_internal; it is read
850 @c once, used as an initial guess, and updated at the end, but not
851 @c used except as a guess for subsequent calls, so it should be safe.
852 @c Even though a compiler might delay the load and perform it multiple
853 @c times (bug 16346), there are at least two unconditional uses of the
854 @c auto variable in which the first load is stored, separated by a
855 @c call to an external function, and a conditional change of the
856 @c variable before the external call, so refraining from allocating a
857 @c local variable at the first load would be a very bad optimization.
858 @c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
859 @c mktime_internal(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
861 @c ranged_convert(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
862 @c *convert = localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
864 @c guess_time_tm dup ok
869 @c time_t_int_add_ok ok
870 The @code{mktime} function converts a broken-down time structure to a
871 simple time representation. It also normalizes the contents of the
872 broken-down time structure, and fills in some components based on the
873 values of the others.
875 The @code{mktime} function ignores the specified contents of the
876 @code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone}
877 members of the broken-down time
878 structure. It uses the values of the other components to determine the
879 calendar time; it's permissible for these components to have
880 unnormalized values outside their normal ranges. The last thing that
881 @code{mktime} does is adjust the components of the @var{brokentime}
882 structure, including the members that were initially ignored.
884 If the specified broken-down time cannot be represented as a simple time,
885 @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
886 the contents of @var{brokentime}.
888 Calling @code{mktime} also sets the current time zone as if
889 @code{tzset} were called; @code{mktime} uses this information instead
890 of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone}
891 members. @xref{Time Zone Functions}.
894 @deftypefun time_t timelocal (struct tm *@var{brokentime})
895 @standards{???, time.h}
896 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
899 @code{timelocal} is functionally identical to @code{mktime}, but more
900 mnemonically named. Note that it is the inverse of the @code{localtime}
903 @strong{Portability note:} @code{mktime} is essentially universally
904 available. @code{timelocal} is rather rare.
908 @deftypefun time_t timegm (struct tm *@var{brokentime})
909 @standards{???, time.h}
910 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
911 @c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
912 @c gmtime_offset triggers the same caveats as localtime_offset in mktime.
913 @c although gmtime_r, as called by mktime, might save some issues,
914 @c tzset calls tzset_internal with always, which forces
915 @c reinitialization, so all issues may arise.
916 @c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
917 @c mktime_internal(gmtime_r) @asulock @aculock
918 @c ..gmtime_r @asulock @aculock
920 @c tz_convert(!use_localtime) @asulock @aculock
921 @c ... dup @asulock @aculock
922 @c tzfile_compute(!use_localtime) ok
924 @code{timegm} is functionally identical to @code{mktime} except it
925 always takes the input values to be Coordinated Universal Time (UTC)
926 regardless of any local time zone setting.
928 Note that @code{timegm} is the inverse of @code{gmtime}.
930 @strong{Portability note:} @code{mktime} is essentially universally
931 available. @code{timegm} is rather rare. For the most portable
932 conversion from a UTC broken-down time to a simple time, set
933 the @code{TZ} environment variable to UTC, call @code{mktime}, then set
940 @node High Accuracy Clock
941 @subsection High Accuracy Clock
943 @cindex time, high precision
944 @cindex clock, high accuracy
946 @c On Linux, GNU libc implements ntp_gettime() and npt_adjtime() as calls
948 The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an
949 interface to monitor and manipulate the system clock to maintain high
950 accuracy time. For example, you can fine tune the speed of the clock
951 or synchronize it with another time source.
953 A typical use of these functions is by a server implementing the Network
954 Time Protocol to synchronize the clocks of multiple systems and high
957 These functions are declared in @file{sys/timex.h}.
959 @tindex struct ntptimeval
960 @deftp {Data Type} {struct ntptimeval}
961 This structure is used for information about the system clock. It
962 contains the following members:
964 @item struct timeval time
965 This is the current calendar time, expressed as the elapsed time since
966 the epoch. The @code{struct timeval} data type is described in
969 @item long int maxerror
970 This is the maximum error, measured in microseconds. Unless updated
971 via @code{ntp_adjtime} periodically, this value will reach some
972 platform-specific maximum value.
974 @item long int esterror
975 This is the estimated error, measured in microseconds. This value can
976 be set by @code{ntp_adjtime} to indicate the estimated offset of the
977 system clock from the true calendar time.
981 @deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
982 @standards{GNU, sys/timex.h}
983 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
984 @c Wrapper for adjtimex.
985 The @code{ntp_gettime} function sets the structure pointed to by
986 @var{tptr} to current values. The elements of the structure afterwards
987 contain the values the timer implementation in the kernel assumes. They
988 might or might not be correct. If they are not, an @code{ntp_adjtime}
991 The return value is @code{0} on success and other values on failure. The
992 following @code{errno} error conditions are defined for this function:
996 The precision clock model is not properly set up at the moment, thus the
997 clock must be considered unsynchronized, and the values should be
1002 @tindex struct timex
1003 @deftp {Data Type} {struct timex}
1004 This structure is used to control and monitor the system clock. It
1005 contains the following members:
1007 @item unsigned int modes
1008 This variable controls whether and which values are set. Several
1009 symbolic constants have to be combined with @emph{binary or} to specify
1010 the effective mode. These constants start with @code{MOD_}.
1012 @item long int offset
1013 This value indicates the current offset of the system clock from the true
1014 calendar time. The value is given in microseconds. If bit
1015 @code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other
1016 dependent values) can be set. The offset's absolute value must not
1017 exceed @code{MAXPHASE}.
1020 @item long int frequency
1021 This value indicates the difference in frequency between the true
1022 calendar time and the system clock. The value is expressed as scaled
1023 PPM (parts per million, 0.0001%). The scaling is @code{1 <<
1024 SHIFT_USEC}. The value can be set with bit @code{MOD_FREQUENCY}, but
1025 the absolute value must not exceed @code{MAXFREQ}.
1027 @item long int maxerror
1028 This is the maximum error, measured in microseconds. A new value can be
1029 set using bit @code{MOD_MAXERROR}. Unless updated via
1030 @code{ntp_adjtime} periodically, this value will increase steadily
1031 and reach some platform-specific maximum value.
1033 @item long int esterror
1034 This is the estimated error, measured in microseconds. This value can
1035 be set using bit @code{MOD_ESTERROR}.
1038 This variable reflects the various states of the clock machinery. There
1039 are symbolic constants for the significant bits, starting with
1040 @code{STA_}. Some of these flags can be updated using the
1041 @code{MOD_STATUS} bit.
1043 @item long int constant
1044 This value represents the bandwidth or stiffness of the PLL (phase
1045 locked loop) implemented in the kernel. The value can be changed using
1046 bit @code{MOD_TIMECONST}.
1048 @item long int precision
1049 This value represents the accuracy or the maximum error when reading the
1050 system clock. The value is expressed in microseconds.
1052 @item long int tolerance
1053 This value represents the maximum frequency error of the system clock in
1054 scaled PPM. This value is used to increase the @code{maxerror} every
1057 @item struct timeval time
1058 The current calendar time.
1061 The elapsed time between clock ticks in microseconds. A clock tick is a
1062 periodic timer interrupt on which the system clock is based.
1064 @item long int ppsfreq
1065 This is the first of a few optional variables that are present only if
1066 the system clock can use a PPS (pulse per second) signal to discipline
1067 the system clock. The value is expressed in scaled PPM and it denotes
1068 the difference in frequency between the system clock and the PPS signal.
1070 @item long int jitter
1071 This value expresses a median filtered average of the PPS signal's
1072 dispersion in microseconds.
1075 This value is a binary exponent for the duration of the PPS calibration
1076 interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}.
1078 @item long int stabil
1079 This value represents the median filtered dispersion of the PPS
1080 frequency in scaled PPM.
1082 @item long int jitcnt
1083 This counter represents the number of pulses where the jitter exceeded
1084 the allowed maximum @code{MAXTIME}.
1086 @item long int calcnt
1087 This counter reflects the number of successful calibration intervals.
1089 @item long int errcnt
1090 This counter represents the number of calibration errors (caused by
1091 large offsets or jitter).
1093 @item long int stbcnt
1094 This counter denotes the number of calibrations where the stability
1095 exceeded the threshold.
1099 @deftypefun int ntp_adjtime (struct timex *@var{tptr})
1100 @standards{GNU, sys/timex.h}
1101 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1102 @c Alias to adjtimex syscall.
1103 The @code{ntp_adjtime} function sets the structure specified by
1104 @var{tptr} to current values.
1106 In addition, @code{ntp_adjtime} updates some settings to match what you
1107 pass to it in *@var{tptr}. Use the @code{modes} element of *@var{tptr}
1108 to select what settings to update. You can set @code{offset},
1109 @code{freq}, @code{maxerror}, @code{esterror}, @code{status},
1110 @code{constant}, and @code{tick}.
1112 @code{modes} = zero means set nothing.
1114 Only the superuser can update settings.
1116 @c On Linux, ntp_adjtime() also does the adjtime() function if you set
1117 @c modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc implements
1118 @c adjtime()). But this should be considered an internal function because
1119 @c it's so inconsistent with the rest of what ntp_adjtime() does and is
1120 @c forced in an ugly way into the struct timex. So we don't document it
1121 @c and instead document adjtime() as the way to achieve the function.
1123 The return value is @code{0} on success and other values on failure. The
1124 following @code{errno} error conditions are defined for this function:
1128 The high accuracy clock model is not properly set up at the moment, thus the
1129 clock must be considered unsynchronized, and the values should be
1130 treated with care. Another reason could be that the specified new values
1134 The process specified a settings update, but is not superuser.
1138 For more details see RFC1305 (Network Time Protocol, Version 3) and
1141 @strong{Portability note:} Early versions of @theglibc{} did not
1142 have this function but did have the synonymous @code{adjtimex}.
1147 @node Formatting Calendar Time
1148 @subsection Formatting Calendar Time
1150 The functions described in this section format calendar time values as
1151 strings. These functions are declared in the header file @file{time.h}.
1154 @deftypefun {char *} asctime (const struct tm *@var{brokentime})
1155 @standards{ISO, time.h}
1156 @safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}}
1157 @c asctime @mtasurace:asctime @mtslocale
1158 @c Uses a static buffer.
1159 @c asctime_internal @mtslocale
1160 @c snprintf dup @mtslocale [no @acsuheap @acsmem]
1161 @c ab_day_name @mtslocale
1162 @c ab_month_name @mtslocale
1163 The @code{asctime} function converts the broken-down time value that
1164 @var{brokentime} points to into a string in a standard format:
1167 "Tue May 21 13:46:22 1991\n"
1170 The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
1171 @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
1173 The abbreviations for the months are: @samp{Jan}, @samp{Feb},
1174 @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
1175 @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
1177 The return value points to a statically allocated string, which might be
1178 overwritten by subsequent calls to @code{asctime} or @code{ctime}.
1179 (But no other library function overwrites the contents of this
1183 @deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer})
1184 @standards{POSIX.1c, time.h}
1185 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1186 @c asctime_r @mtslocale
1187 @c asctime_internal dup @mtslocale
1188 This function is similar to @code{asctime} but instead of placing the
1189 result in a static buffer it writes the string in the buffer pointed to
1190 by the parameter @var{buffer}. This buffer should have room
1191 for at least 26 bytes, including the terminating null.
1193 If no error occurred the function returns a pointer to the string the
1194 result was written into, i.e., it returns @var{buffer}. Otherwise
1195 it returns @code{NULL}.
1199 @deftypefun {char *} ctime (const time_t *@var{time})
1200 @standards{ISO, time.h}
1201 @safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1202 @c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1203 @c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1204 @c asctime dup @mtasurace:asctime @mtslocale
1205 The @code{ctime} function is similar to @code{asctime}, except that you
1206 specify the calendar time argument as a @code{time_t} simple time value
1207 rather than in broken-down local time format. It is equivalent to
1210 asctime (localtime (@var{time}))
1213 Calling @code{ctime} also sets the current time zone as if
1214 @code{tzset} were called. @xref{Time Zone Functions}.
1217 @deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer})
1218 @standards{POSIX.1c, time.h}
1219 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1220 @c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1221 @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1222 @c asctime_r dup @mtslocale
1223 This function is similar to @code{ctime}, but places the result in the
1224 string pointed to by @var{buffer}. It is equivalent to (written using
1225 gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}):
1228 (@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @})
1231 If no error occurred the function returns a pointer to the string the
1232 result was written into, i.e., it returns @var{buffer}. Otherwise
1233 it returns @code{NULL}.
1237 @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
1238 @standards{ISO, time.h}
1239 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
1240 @c strftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1241 @c strftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1242 @c strftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1244 @c memset_zero dup ok
1245 @c memset_space dup ok
1247 @c mbrlen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
1251 @c memcpy_lowcase ok
1254 @c memcpy_uppcase ok
1262 @c strftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1264 @c nl_get_era_entry @ascuheap @asulock @acsmem @aculock
1265 @c nl_init_era_entries @ascuheap @asulock @acsmem @aculock
1266 @c libc_rwlock_wrlock dup @asulock @aculock
1267 @c malloc dup @ascuheap @acsmem
1269 @c free dup @ascuheap @acsmem
1270 @c realloc dup @ascuheap @acsmem
1274 @c libc_rwlock_unlock dup @asulock @aculock
1277 @c DO_NUMBER_SPACEPAD ok
1278 @c nl_get_alt_digit @ascuheap @asulock @acsmem @aculock
1279 @c libc_rwlock_wrlock dup @asulock @aculock
1280 @c nl_init_alt_digit @ascuheap @acsmem
1281 @c malloc dup @ascuheap @acsmem
1284 @c libc_rwlock_unlock dup @aculock
1289 @c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1292 @c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1293 @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1294 @c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1296 This function is similar to the @code{sprintf} function (@pxref{Formatted
1297 Input}), but the conversion specifications that can appear in the format
1298 template @var{template} are specialized for printing components of the date
1299 and time @var{brokentime} according to the locale currently specified for
1300 time conversion (@pxref{Locales}) and the current time zone
1301 (@pxref{Time Zone Functions}).
1303 Ordinary characters appearing in the @var{template} are copied to the
1304 output string @var{s}; this can include multibyte character sequences.
1305 Conversion specifiers are introduced by a @samp{%} character, followed
1306 by an optional flag which can be one of the following. These flags
1307 are all GNU extensions. The first three affect only the output of
1312 The number is padded with spaces.
1315 The number is not padded at all.
1318 The number is padded with zeros even if the format specifies padding
1322 The output uses uppercase characters, but only if this is possible
1323 (@pxref{Case Conversion}).
1326 The default action is to pad the number with zeros to keep it a constant
1327 width. Numbers that do not have a range indicated below are never
1328 padded, since there is no natural width for them.
1330 Following the flag an optional specification of the width is possible.
1331 This is specified in decimal notation. If the natural size of the
1332 output of the field has less than the specified number of characters,
1333 the result is written right adjusted and space padded to the given
1336 An optional modifier can follow the optional flag and width
1337 specification. The modifiers, which were first standardized by
1338 POSIX.2-1992 and by @w{ISO C99}, are:
1342 Use the locale's alternative representation for date and time. This
1343 modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X},
1344 @code{%y} and @code{%Y} format specifiers. In a Japanese locale, for
1345 example, @code{%Ex} might yield a date format based on the Japanese
1349 With all format specifiers that produce numbers: use the locale's
1350 alternative numeric symbols.
1352 With @code{%B}, @code{%b}, and @code{%h}: use the grammatical form for
1353 month names that is appropriate when the month is named by itself,
1354 rather than the form that is appropriate when the month is used as
1355 part of a complete date. This is a GNU extension.
1358 If the format supports the modifier but no alternative representation
1359 is available, it is ignored.
1361 The conversion specifier ends with a format specifier taken from the
1362 following list. The whole @samp{%} sequence is replaced in the output
1367 The abbreviated weekday name according to the current locale.
1370 The full weekday name according to the current locale.
1373 The abbreviated month name according to the current locale, in the
1374 grammatical form used when the month is part of a complete date.
1375 As a GNU extension, the @code{O} modifier can be used (@code{%Ob})
1376 to get the grammatical form used when the month is named by itself.
1379 The full month name according to the current locale, in the
1380 grammatical form used when the month is part of a complete date.
1381 As a GNU extension, the @code{O} modifier can be used (@code{%OB})
1382 to get the grammatical form used when the month is named by itself.
1384 Note that not all languages need two different forms of the month
1385 names, so the text produced by @code{%B} and @code{%OB}, and by
1386 @code{%b} and @code{%Ob}, may or may not be the same, depending on
1390 The preferred calendar time representation for the current locale.
1393 The century of the year. This is equivalent to the greatest integer not
1394 greater than the year divided by 100.
1396 If the @code{E} modifier is specified (@code{%EC}), instead produces
1397 the name of the period for the year (e.g.@: an era name) in the
1398 locale's alternative calendar.
1400 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1403 The day of the month as a decimal number (range @code{01} through @code{31}).
1406 The date using the format @code{%m/%d/%y}.
1408 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1411 The day of the month like with @code{%d}, but padded with spaces (range
1412 @code{ 1} through @code{31}).
1414 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1417 The date using the format @code{%Y-%m-%d}. This is the form specified
1418 in the @w{ISO 8601} standard and is the preferred form for all uses.
1420 This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
1423 The year corresponding to the ISO week number, but without the century
1424 (range @code{00} through @code{99}). This has the same format and value
1425 as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
1426 to the previous or next year, that year is used instead.
1428 This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
1431 The year corresponding to the ISO week number. This has the same format
1432 and value as @code{%Y}, except that if the ISO week number (see
1433 @code{%V}) belongs to the previous or next year, that year is used
1436 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1437 but was previously available as a GNU extension.
1440 The abbreviated month name according to the current locale. The action
1441 is the same as for @code{%b}.
1443 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1446 The hour as a decimal number, using a 24-hour clock (range @code{00} through
1450 The hour as a decimal number, using a 12-hour clock (range @code{01} through
1454 The day of the year as a decimal number (range @code{001} through @code{366}).
1457 The hour as a decimal number, using a 24-hour clock like @code{%H}, but
1458 padded with spaces (range @code{ 0} through @code{23}).
1460 This format is a GNU extension.
1463 The hour as a decimal number, using a 12-hour clock like @code{%I}, but
1464 padded with spaces (range @code{ 1} through @code{12}).
1466 This format is a GNU extension.
1469 The month as a decimal number (range @code{01} through @code{12}).
1472 The minute as a decimal number (range @code{00} through @code{59}).
1475 A single @samp{\n} (newline) character.
1477 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1480 Either @samp{AM} or @samp{PM}, according to the given time value; or the
1481 corresponding strings for the current locale. Noon is treated as
1482 @samp{PM} and midnight as @samp{AM}. In most locales
1483 @samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"}
1484 yields an empty string.
1487 We currently have a problem with makeinfo. Write @samp{AM} and @samp{am}
1488 both results in `am'. I.e., the difference in case is not visible anymore.
1491 Either @samp{am} or @samp{pm}, according to the given time value; or the
1492 corresponding strings for the current locale, printed in lowercase
1493 characters. Noon is treated as @samp{pm} and midnight as @samp{am}. In
1494 most locales @samp{AM}/@samp{PM} format is not supported, in such cases
1495 @code{"%P"} yields an empty string.
1497 This format is a GNU extension.
1500 The complete calendar time using the AM/PM format of the current locale.
1502 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1503 In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}.
1506 The hour and minute in decimal numbers using the format @code{%H:%M}.
1508 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1509 but was previously available as a GNU extension.
1512 The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
1513 Leap seconds are not counted unless leap second support is available.
1515 This format is a GNU extension.
1518 The seconds as a decimal number (range @code{00} through @code{60}).
1521 A single @samp{\t} (tabulator) character.
1523 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1526 The time of day using decimal numbers using the format @code{%H:%M:%S}.
1528 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1531 The day of the week as a decimal number (range @code{1} through
1532 @code{7}), Monday being @code{1}.
1534 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1537 The week number of the current year as a decimal number (range @code{00}
1538 through @code{53}), starting with the first Sunday as the first day of
1539 the first week. Days preceding the first Sunday in the year are
1540 considered to be in week @code{00}.
1543 The @w{ISO 8601:1988} week number as a decimal number (range @code{01}
1544 through @code{53}). ISO weeks start with Monday and end with Sunday.
1545 Week @code{01} of a year is the first week which has the majority of its
1546 days in that year; this is equivalent to the week containing the year's
1547 first Thursday, and it is also equivalent to the week containing January
1548 4. Week @code{01} of a year can contain days from the previous year.
1549 The week before week @code{01} of a year is the last week (@code{52} or
1550 @code{53}) of the previous year even if it contains days from the new
1553 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1556 The day of the week as a decimal number (range @code{0} through
1557 @code{6}), Sunday being @code{0}.
1560 The week number of the current year as a decimal number (range @code{00}
1561 through @code{53}), starting with the first Monday as the first day of
1562 the first week. All days preceding the first Monday in the year are
1563 considered to be in week @code{00}.
1566 The preferred date representation for the current locale.
1569 The preferred time of day representation for the current locale.
1572 The year without a century as a decimal number (range @code{00} through
1573 @code{99}). This is equivalent to the year modulo 100.
1575 If the @code{E} modifier is specified (@code{%Ey}), instead produces
1576 the year number according to a locale-specific alternative calendar.
1577 Unlike @code{%y}, the number is @emph{not} reduced modulo 100.
1578 However, by default it is zero-padded to a minimum of two digits (this
1579 can be overridden by an explicit field width or by the @code{_} and
1583 The year as a decimal number, using the Gregorian calendar. Years
1584 before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
1586 If the @code{E} modifier is specified (@code{%EY}), instead produces a
1587 complete representation of the year according to the locale's
1588 alternative calendar. Generally this will be some combination of the
1589 information produced by @code{%EC} and @code{Ey}. As a GNU extension,
1590 the formatting flags @code{_} or @code{-} may be used with this
1591 conversion specifier; they affect how the year number is printed.
1594 @w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
1595 @code{-0600} or @code{+0100}), or nothing if no time zone is
1598 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1599 but was previously available as a GNU extension.
1601 In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format
1602 @w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent
1603 @w{@samp{"%a, %d %b %Y %T %z"}}).
1606 The time zone abbreviation (empty if the time zone can't be determined).
1609 A literal @samp{%} character.
1612 The @var{size} parameter can be used to specify the maximum number of
1613 characters to be stored in the array @var{s}, including the terminating
1614 null character. If the formatted time requires more than @var{size}
1615 characters, @code{strftime} returns zero and the contents of the array
1616 @var{s} are undefined. Otherwise the return value indicates the
1617 number of characters placed in the array @var{s}, not including the
1618 terminating null character.
1620 @emph{Warning:} This convention for the return value which is prescribed
1621 in @w{ISO C} can lead to problems in some situations. For certain
1622 format strings and certain locales the output really can be the empty
1623 string and this cannot be discovered by testing the return value only.
1624 E.g., in most locales the AM/PM time format is not supported (most of
1625 the world uses the 24 hour time representation). In such locales
1626 @code{"%p"} will return the empty string, i.e., the return value is
1627 zero. To detect situations like this something similar to the following
1628 code should be used:
1632 len = strftime (buf, bufsize, format, tp);
1633 if (len == 0 && buf[0] != '\0')
1635 /* Something went wrong in the strftime call. */
1640 If @var{s} is a null pointer, @code{strftime} does not actually write
1641 anything, but instead returns the number of characters it would have written.
1643 Calling @code{strftime} also sets the current time zone as if
1644 @code{tzset} were called; @code{strftime} uses this information
1645 instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone}
1646 members. @xref{Time Zone Functions}.
1648 For an example of @code{strftime}, see @ref{Time Functions Example}.
1651 @deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime})
1652 @standards{ISO/Amend1, time.h}
1653 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
1654 @c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1655 @c wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1656 @c wcsftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1658 @c memset_zero dup ok
1659 @c memset_space dup ok
1663 @c memcpy_lowcase ok
1665 @c towlower_l dup ok
1666 @c memcpy_uppcase ok
1668 @c towupper_l dup ok
1671 @c widen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1673 @c mbsrtowcs_l @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
1677 @c wcsftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1679 @c nl_get_era_entry dup @ascuheap @asulock @acsmem @aculock
1681 @c DO_NUMBER_SPACEPAD ok
1682 @c nl_get_walt_digit dup @ascuheap @asulock @acsmem @aculock
1683 @c libc_rwlock_wrlock dup @asulock @aculock
1684 @c nl_init_alt_digit dup @ascuheap @acsmem
1685 @c malloc dup @ascuheap @acsmem
1688 @c libc_rwlock_unlock dup @aculock
1693 @c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1696 @c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1697 @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1698 @c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1700 The @code{wcsftime} function is equivalent to the @code{strftime}
1701 function with the difference that it operates on wide character
1702 strings. The buffer where the result is stored, pointed to by @var{s},
1703 must be an array of wide characters. The parameter @var{size} which
1704 specifies the size of the output buffer gives the number of wide
1705 characters, not the number of bytes.
1707 Also the format string @var{template} is a wide character string. Since
1708 all characters needed to specify the format string are in the basic
1709 character set it is portably possible to write format strings in the C
1710 source code using the @code{L"@dots{}"} notation. The parameter
1711 @var{brokentime} has the same meaning as in the @code{strftime} call.
1713 The @code{wcsftime} function supports the same flags, modifiers, and
1714 format specifiers as the @code{strftime} function.
1716 The return value of @code{wcsftime} is the number of wide characters
1717 stored in @code{s}. When more characters would have to be written than
1718 can be placed in the buffer @var{s} the return value is zero, with the
1719 same problems indicated in the @code{strftime} documentation.
1722 @node Parsing Date and Time
1723 @subsection Convert textual time and date information back
1725 The @w{ISO C} standard does not specify any functions which can convert
1726 the output of the @code{strftime} function back into a binary format.
1727 This led to a variety of more-or-less successful implementations with
1728 different interfaces over the years. Then the Unix standard was
1729 extended by the addition of two functions: @code{strptime} and
1730 @code{getdate}. Both have strange interfaces but at least they are
1734 * Low-Level Time String Parsing:: Interpret string according to given format.
1735 * General Time String Parsing:: User-friendly function to parse data and
1739 @node Low-Level Time String Parsing
1740 @subsubsection Interpret string according to given format
1742 The first function is rather low-level. It is nevertheless frequently
1743 used in software since it is better known. Its interface and
1744 implementation are heavily influenced by the @code{getdate} function,
1745 which is defined and implemented in terms of calls to @code{strptime}.
1747 @deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp})
1748 @standards{XPG4, time.h}
1749 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1750 @c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1751 @c strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1758 @c strncasecmp_l dup ok
1760 @c recursive @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1761 @c strptime_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1764 @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1765 @c nl_select_era_entry @ascuheap @asulock @acsmem @aculock
1766 @c nl_init_era_entries dup @ascuheap @asulock @acsmem @aculock
1767 @c get_alt_number dup @ascuheap @asulock @acsmem @aculock
1768 @c nl_parse_alt_digit dup @ascuheap @asulock @acsmem @aculock
1769 @c libc_rwlock_wrlock dup @asulock @aculock
1770 @c nl_init_alt_digit dup @ascuheap @acsmem
1771 @c libc_rwlock_unlock dup @aculock
1772 @c get_number dup ok
1773 @c day_of_the_week ok
1774 @c day_of_the_year ok
1775 The @code{strptime} function parses the input string @var{s} according
1776 to the format string @var{fmt} and stores its results in the
1779 The input string could be generated by a @code{strftime} call or
1780 obtained any other way. It does not need to be in a human-recognizable
1781 format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even
1782 though it is ambiguous without context. As long as the format string
1783 @var{fmt} matches the input string the function will succeed.
1785 The user has to make sure, though, that the input can be parsed in a
1786 unambiguous way. The string @code{"1999112"} can be parsed using the
1787 format @code{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2. It
1788 is necessary to add appropriate separators to reliably get results.
1790 The format string consists of the same components as the format string
1791 of the @code{strftime} function. The only difference is that the flags
1792 @code{_}, @code{-}, @code{0}, and @code{^} are not allowed.
1793 @comment Is this really the intention? --drepper
1794 Several of the distinct formats of @code{strftime} do the same work in
1795 @code{strptime} since differences like case of the input do not matter.
1796 For reasons of symmetry all formats are supported, though.
1798 The modifiers @code{E} and @code{O} are also allowed everywhere the
1799 @code{strftime} function allows them.
1806 The weekday name according to the current locale, in abbreviated form or
1812 A month name according to the current locale. All three specifiers
1813 will recognize both abbreviated and full month names. If the
1814 locale provides two different grammatical forms of month names,
1815 all three specifiers will recognize both forms.
1817 As a GNU extension, the @code{O} modifier can be used with these
1818 specifiers; it has no effect, as both grammatical forms of month
1819 names are recognized.
1822 The date and time representation for the current locale.
1825 Like @code{%c} but the locale's alternative date and time format is used.
1828 The century of the year.
1830 It makes sense to use this format only if the format string also
1831 contains the @code{%y} format.
1834 The locale's representation of the period.
1836 Unlike @code{%C} it sometimes makes sense to use this format since some
1837 cultures represent years relative to the beginning of eras instead of
1838 using the Gregorian years.
1842 The day of the month as a decimal number (range @code{1} through @code{31}).
1843 Leading zeroes are permitted but not required.
1847 Same as @code{%d} but using the locale's alternative numeric symbols.
1849 Leading zeroes are permitted but not required.
1852 Equivalent to @code{%m/%d/%y}.
1855 Equivalent to @code{%Y-%m-%d}, which is the @w{ISO 8601} date
1858 This is a GNU extension following an @w{ISO C99} extension to
1862 The year corresponding to the ISO week number, but without the century
1863 (range @code{00} through @code{99}).
1865 @emph{Note:} Currently, this is not fully implemented. The format is
1866 recognized, input is consumed but no field in @var{tm} is set.
1868 This format is a GNU extension following a GNU extension of @code{strftime}.
1871 The year corresponding to the ISO week number.
1873 @emph{Note:} Currently, this is not fully implemented. The format is
1874 recognized, input is consumed but no field in @var{tm} is set.
1876 This format is a GNU extension following a GNU extension of @code{strftime}.
1880 The hour as a decimal number, using a 24-hour clock (range @code{00} through
1883 @code{%k} is a GNU extension following a GNU extension of @code{strftime}.
1886 Same as @code{%H} but using the locale's alternative numeric symbols.
1890 The hour as a decimal number, using a 12-hour clock (range @code{01} through
1893 @code{%l} is a GNU extension following a GNU extension of @code{strftime}.
1896 Same as @code{%I} but using the locale's alternative numeric symbols.
1899 The day of the year as a decimal number (range @code{1} through @code{366}).
1901 Leading zeroes are permitted but not required.
1904 The month as a decimal number (range @code{1} through @code{12}).
1906 Leading zeroes are permitted but not required.
1909 Same as @code{%m} but using the locale's alternative numeric symbols.
1912 The minute as a decimal number (range @code{0} through @code{59}).
1914 Leading zeroes are permitted but not required.
1917 Same as @code{%M} but using the locale's alternative numeric symbols.
1921 Matches any white space.
1925 The locale-dependent equivalent to @samp{AM} or @samp{PM}.
1927 This format is not useful unless @code{%I} or @code{%l} is also used.
1928 Another complication is that the locale might not define these values at
1929 all and therefore the conversion fails.
1931 @code{%P} is a GNU extension following a GNU extension to @code{strftime}.
1934 The complete time using the AM/PM format of the current locale.
1936 A complication is that the locale might not define this format at all
1937 and therefore the conversion fails.
1940 The hour and minute in decimal numbers using the format @code{%H:%M}.
1942 @code{%R} is a GNU extension following a GNU extension to @code{strftime}.
1945 The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
1946 Leap seconds are not counted unless leap second support is available.
1948 @code{%s} is a GNU extension following a GNU extension to @code{strftime}.
1951 The seconds as a decimal number (range @code{0} through @code{60}).
1953 Leading zeroes are permitted but not required.
1955 @strong{NB:} The Unix specification says the upper bound on this value
1956 is @code{61}, a result of a decision to allow double leap seconds. You
1957 will not see the value @code{61} because no minute has more than one
1958 leap second, but the myth persists.
1961 Same as @code{%S} but using the locale's alternative numeric symbols.
1964 Equivalent to the use of @code{%H:%M:%S} in this place.
1967 The day of the week as a decimal number (range @code{1} through
1968 @code{7}), Monday being @code{1}.
1970 Leading zeroes are permitted but not required.
1972 @emph{Note:} Currently, this is not fully implemented. The format is
1973 recognized, input is consumed but no field in @var{tm} is set.
1976 The week number of the current year as a decimal number (range @code{0}
1979 Leading zeroes are permitted but not required.
1982 Same as @code{%U} but using the locale's alternative numeric symbols.
1985 The @w{ISO 8601:1988} week number as a decimal number (range @code{1}
1988 Leading zeroes are permitted but not required.
1990 @emph{Note:} Currently, this is not fully implemented. The format is
1991 recognized, input is consumed but no field in @var{tm} is set.
1994 The day of the week as a decimal number (range @code{0} through
1995 @code{6}), Sunday being @code{0}.
1997 Leading zeroes are permitted but not required.
1999 @emph{Note:} Currently, this is not fully implemented. The format is
2000 recognized, input is consumed but no field in @var{tm} is set.
2003 Same as @code{%w} but using the locale's alternative numeric symbols.
2006 The week number of the current year as a decimal number (range @code{0}
2009 Leading zeroes are permitted but not required.
2011 @emph{Note:} Currently, this is not fully implemented. The format is
2012 recognized, input is consumed but no field in @var{tm} is set.
2015 Same as @code{%W} but using the locale's alternative numeric symbols.
2018 The date using the locale's date format.
2021 Like @code{%x} but the locale's alternative data representation is used.
2024 The time using the locale's time format.
2027 Like @code{%X} but the locale's alternative time representation is used.
2030 The year without a century as a decimal number (range @code{0} through
2033 Leading zeroes are permitted but not required.
2035 Note that it is questionable to use this format without
2036 the @code{%C} format. The @code{strptime} function does regard input
2037 values in the range @math{68} to @math{99} as the years @math{1969} to
2038 @math{1999} and the values @math{0} to @math{68} as the years
2039 @math{2000} to @math{2068}. But maybe this heuristic fails for some
2042 Therefore it is best to avoid @code{%y} completely and use @code{%Y}
2046 The offset from @code{%EC} in the locale's alternative representation.
2049 The offset of the year (from @code{%C}) using the locale's alternative
2053 The year as a decimal number, using the Gregorian calendar.
2056 The full alternative year representation.
2059 The offset from GMT in @w{ISO 8601}/RFC822 format.
2064 @emph{Note:} Currently, this is not fully implemented. The format is
2065 recognized, input is consumed but no field in @var{tm} is set.
2068 A literal @samp{%} character.
2071 All other characters in the format string must have a matching character
2072 in the input string. Exceptions are white spaces in the input string
2073 which can match zero or more whitespace characters in the format string.
2075 @strong{Portability Note:} The XPG standard advises applications to use
2076 at least one whitespace character (as specified by @code{isspace}) or
2077 other non-alphanumeric characters between any two conversion
2078 specifications. @Theglibc{} does not have this limitation but
2079 other libraries might have trouble parsing formats like
2080 @code{"%d%m%Y%H%M%S"}.
2082 The @code{strptime} function processes the input string from right to
2083 left. Each of the three possible input elements (white space, literal,
2084 or format) are handled one after the other. If the input cannot be
2085 matched to the format string the function stops. The remainder of the
2086 format and input strings are not processed.
2088 The function returns a pointer to the first character it was unable to
2089 process. If the input string contains more characters than required by
2090 the format string the return value points right after the last consumed
2091 input character. If the whole input string is consumed the return value
2092 points to the @code{NULL} byte at the end of the string. If an error
2093 occurs, i.e., @code{strptime} fails to match all of the format string,
2094 the function returns @code{NULL}.
2097 The specification of the function in the XPG standard is rather vague,
2098 leaving out a few important pieces of information. Most importantly, it
2099 does not specify what happens to those elements of @var{tm} which are
2100 not directly initialized by the different formats. The
2101 implementations on different Unix systems vary here.
2103 The @glibcadj{} implementation does not touch those fields which are not
2104 directly initialized. Exceptions are the @code{tm_wday} and
2105 @code{tm_yday} elements, which are recomputed if any of the year, month,
2106 or date elements changed. This has two implications:
2110 Before calling the @code{strptime} function for a new input string, you
2111 should prepare the @var{tm} structure you pass. Normally this will mean
2112 initializing all values to zero. Alternatively, you can set all
2113 fields to values like @code{INT_MAX}, allowing you to determine which
2114 elements were set by the function call. Zero does not work here since
2115 it is a valid value for many of the fields.
2117 Careful initialization is necessary if you want to find out whether a
2118 certain field in @var{tm} was initialized by the function call.
2121 You can construct a @code{struct tm} value with several consecutive
2122 @code{strptime} calls. A useful application of this is e.g. the parsing
2123 of two separate strings, one containing date information and the other
2124 time information. By parsing one after the other without clearing the
2125 structure in-between, you can construct a complete broken-down time.
2128 The following example shows a function which parses a string which
2129 contains the date information in either US style or @w{ISO 8601} form:
2133 parse_date (const char *input, struct tm *tm)
2137 /* @r{First clear the result structure.} */
2138 memset (tm, '\0', sizeof (*tm));
2140 /* @r{Try the ISO format first.} */
2141 cp = strptime (input, "%F", tm);
2144 /* @r{Does not match. Try the US form.} */
2145 cp = strptime (input, "%D", tm);
2152 @node General Time String Parsing
2153 @subsubsection A More User-friendly Way to Parse Times and Dates
2155 The Unix standard defines another function for parsing date strings.
2156 The interface is weird, but if the function happens to suit your
2157 application it is just fine. It is problematic to use this function
2158 in multi-threaded programs or libraries, since it returns a pointer to
2159 a static variable, and uses a global variable and global state (an
2160 environment variable).
2163 @standards{Unix98, time.h}
2164 This variable of type @code{int} contains the error code of the last
2165 unsuccessful call to @code{getdate}. Defined values are:
2169 The environment variable @code{DATEMSK} is not defined or null.
2171 The template file denoted by the @code{DATEMSK} environment variable
2174 Information about the template file cannot retrieved.
2176 The template file is not a regular file.
2178 An I/O error occurred while reading the template file.
2180 Not enough memory available to execute the function.
2182 The template file contains no matching template.
2184 The input date is invalid, but would match a template otherwise. This
2185 includes dates like February 31st, and dates which cannot be represented
2186 in a @code{time_t} variable.
2190 @deftypefun {struct tm *} getdate (const char *@var{string})
2191 @standards{Unix98, time.h}
2192 @safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2193 @c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2194 @c getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2195 The interface to @code{getdate} is the simplest possible for a function
2196 to parse a string and return the value. @var{string} is the input
2197 string and the result is returned in a statically-allocated variable.
2199 The details about how the string is processed are hidden from the user.
2200 In fact, they can be outside the control of the program. Which formats
2201 are recognized is controlled by the file named by the environment
2202 variable @code{DATEMSK}. This file should contain
2203 lines of valid format strings which could be passed to @code{strptime}.
2205 The @code{getdate} function reads these format strings one after the
2206 other and tries to match the input string. The first line which
2207 completely matches the input string is used.
2209 Elements not initialized through the format string retain the values
2210 present at the time of the @code{getdate} function call.
2212 The formats recognized by @code{getdate} are the same as for
2213 @code{strptime}. See above for an explanation. There are only a few
2214 extensions to the @code{strptime} behavior:
2218 If the @code{%Z} format is given the broken-down time is based on the
2219 current time of the timezone matched, not of the current timezone of the
2220 runtime environment.
2222 @emph{Note}: This is not implemented (currently). The problem is that
2223 timezone names are not unique. If a fixed timezone is assumed for a
2224 given string (say @code{EST} meaning US East Coast time), then uses for
2225 countries other than the USA will fail. So far we have found no good
2229 If only the weekday is specified the selected day depends on the current
2230 date. If the current weekday is greater than or equal to the @code{tm_wday}
2231 value the current week's day is chosen, otherwise the day next week is chosen.
2234 A similar heuristic is used when only the month is given and not the
2235 year. If the month is greater than or equal to the current month, then
2236 the current year is used. Otherwise it wraps to next year. The first
2237 day of the month is assumed if one is not explicitly specified.
2240 The current hour, minute, and second are used if the appropriate value is
2241 not set through the format.
2244 If no date is given tomorrow's date is used if the time is
2245 smaller than the current time. Otherwise today's date is taken.
2248 It should be noted that the format in the template file need not only
2249 contain format elements. The following is a list of possible format
2250 strings (taken from the Unix standard):
2254 %A %B %d, %Y %H:%M:%S
2259 at %A the %dst of %B in %Y
2260 run job at %I %p,%B %dnd
2261 %A den %d. %B %Y %H.%M Uhr
2264 As you can see, the template list can contain very specific strings like
2265 @code{run job at %I %p,%B %dnd}. Using the above list of templates and
2266 assuming the current time is Mon Sep 22 12:19:47 EDT 1986, we can obtain the
2267 following results for the given input.
2269 @multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
2270 @item Input @tab Match @tab Result
2271 @item Mon @tab %a @tab Mon Sep 22 12:19:47 EDT 1986
2272 @item Sun @tab %a @tab Sun Sep 28 12:19:47 EDT 1986
2273 @item Fri @tab %a @tab Fri Sep 26 12:19:47 EDT 1986
2274 @item September @tab %B @tab Mon Sep 1 12:19:47 EDT 1986
2275 @item January @tab %B @tab Thu Jan 1 12:19:47 EST 1987
2276 @item December @tab %B @tab Mon Dec 1 12:19:47 EST 1986
2277 @item Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986
2278 @item Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987
2279 @item Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986
2280 @item Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989
2281 @item Fri 9 @tab %a %H @tab Fri Sep 26 09:00:00 EDT 1986
2282 @item Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987
2283 @item 10:30 @tab %H:%M @tab Tue Sep 23 10:30:00 EDT 1986
2284 @item 13:30 @tab %H:%M @tab Mon Sep 22 13:30:00 EDT 1986
2287 The return value of the function is a pointer to a static variable of
2288 type @w{@code{struct tm}}, or a null pointer if an error occurred. The
2289 result is only valid until the next @code{getdate} call, making this
2290 function unusable in multi-threaded applications.
2292 The @code{errno} variable is @emph{not} changed. Error conditions are
2293 stored in the global variable @code{getdate_err}. See the
2294 description above for a list of the possible error values.
2296 @emph{Warning:} The @code{getdate} function should @emph{never} be
2297 used in SUID-programs. The reason is obvious: using the
2298 @code{DATEMSK} environment variable you can get the function to open
2299 any arbitrary file and chances are high that with some bogus input
2300 (such as a binary file) the program will crash.
2303 @deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp})
2304 @standards{GNU, time.h}
2305 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2306 @c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2307 @c getenv dup @mtsenv
2310 @c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
2311 @c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive]
2312 @c isspace dup @mtslocale
2314 @c malloc dup @ascuheap @acsmem
2315 @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
2317 @c getline dup @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt, exclusive]
2318 @c strptime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2319 @c feof_unlocked dup ok
2320 @c free dup @ascuheap @acsmem
2321 @c ferror_unlocked dup dup ok
2323 @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2324 @c first_wday @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2326 @c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2328 @c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2329 The @code{getdate_r} function is the reentrant counterpart of
2330 @code{getdate}. It does not use the global variable @code{getdate_err}
2331 to signal an error, but instead returns an error code. The same error
2332 codes as described in the @code{getdate_err} documentation above are
2333 used, with 0 meaning success.
2335 Moreover, @code{getdate_r} stores the broken-down time in the variable
2336 of type @code{struct tm} pointed to by the second argument, rather than
2337 in a static variable.
2339 This function is not defined in the Unix standard. Nevertheless it is
2340 available on some other Unix systems as well.
2342 The warning against using @code{getdate} in SUID-programs applies to
2343 @code{getdate_r} as well.
2347 @subsection Specifying the Time Zone with @code{TZ}
2349 In POSIX systems, a user can specify the time zone by means of the
2350 @code{TZ} environment variable. For information about how to set
2351 environment variables, see @ref{Environment Variables}. The functions
2352 for accessing the time zone are declared in @file{time.h}.
2356 You should not normally need to set @code{TZ}. If the system is
2357 configured properly, the default time zone will be correct. You might
2358 set @code{TZ} if you are using a computer over a network from a
2359 different time zone, and would like times reported to you in the time
2360 zone local to you, rather than what is local to the computer.
2362 In POSIX.1 systems the value of the @code{TZ} variable can be in one of
2363 three formats. With @theglibc{}, the most common format is the
2364 last one, which can specify a selection from a large database of time
2365 zone information for many regions of the world. The first two formats
2366 are used to describe the time zone information directly, which is both
2367 more cumbersome and less precise. But the POSIX.1 standard only
2368 specifies the details of the first two formats, so it is good to be
2369 familiar with them in case you come across a POSIX.1 system that doesn't
2370 support a time zone information database.
2372 The first format is used when there is no Daylight Saving Time (or
2373 summer time) in the local time zone:
2376 @r{@var{std} @var{offset}}
2379 The @var{std} string specifies the name of the time zone. It must be
2380 three or more characters long and must not contain a leading colon,
2381 embedded digits, commas, nor plus and minus signs. There is no space
2382 character separating the time zone name from the @var{offset}, so these
2383 restrictions are necessary to parse the specification correctly.
2385 The @var{offset} specifies the time value you must add to the local time
2386 to get a Coordinated Universal Time value. It has syntax like
2387 [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This
2388 is positive if the local time zone is west of the Prime Meridian and
2389 negative if it is east. The hour must be between @code{0} and
2390 @code{24}, and the minute and seconds between @code{0} and @code{59}.
2392 For example, here is how we would specify Eastern Standard Time, but
2393 without any Daylight Saving Time alternative:
2399 The second format is used when there is Daylight Saving Time:
2402 @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
2405 The initial @var{std} and @var{offset} specify the standard time zone, as
2406 described above. The @var{dst} string and @var{offset} specify the name
2407 and offset for the corresponding Daylight Saving Time zone; if the
2408 @var{offset} is omitted, it defaults to one hour ahead of standard time.
2410 The remainder of the specification describes when Daylight Saving Time is
2411 in effect. The @var{start} field is when Daylight Saving Time goes into
2412 effect and the @var{end} field is when the change is made back to standard
2413 time. The following formats are recognized for these fields:
2417 This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
2418 February 29 is never counted, even in leap years.
2421 This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
2422 February 29 is counted in leap years.
2424 @item M@var{m}.@var{w}.@var{d}
2425 This specifies day @var{d} of week @var{w} of month @var{m}. The day
2426 @var{d} must be between @code{0} (Sunday) and @code{6}. The week
2427 @var{w} must be between @code{1} and @code{5}; week @code{1} is the
2428 first week in which day @var{d} occurs, and week @code{5} specifies the
2429 @emph{last} @var{d} day in the month. The month @var{m} should be
2430 between @code{1} and @code{12}.
2433 The @var{time} fields specify when, in the local time currently in
2434 effect, the change to the other time occurs. If omitted, the default is
2435 @code{02:00:00}. The hours part of the time fields can range from
2436 @minus{}167 through 167; this is an extension to POSIX.1, which allows
2437 only the range 0 through 24.
2439 Here are some example @code{TZ} values, including the appropriate
2440 Daylight Saving Time and its dates of applicability. In North
2441 American Eastern Standard Time (EST) and Eastern Daylight Time (EDT),
2442 the normal offset from UTC is 5 hours; since this is
2443 west of the prime meridian, the sign is positive. Summer time begins on
2444 March's second Sunday at 2:00am, and ends on November's first Sunday
2448 EST+5EDT,M3.2.0/2,M11.1.0/2
2451 Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours
2452 ahead of the prime meridian in winter, springing forward an hour on
2453 March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or
2454 after March 23), and falling back on October's last Sunday at 02:00.
2457 IST-2IDT,M3.4.4/26,M10.5.0
2460 Western Argentina Summer Time (WARST) is 3 hours behind the prime
2461 meridian all year. There is a dummy fall-back transition on December
2462 31 at 25:00 daylight saving time (i.e., 24:00 standard time,
2463 equivalent to January 1 at 00:00 standard time), and a simultaneous
2464 spring-forward transition on January 1 at 00:00 standard time, so
2465 daylight saving time is in effect all year and the initial @code{WART}
2469 WART4WARST,J1/0,J365/25
2472 Western Greenland Time (WGT) and Western Greenland Summer Time (WGST)
2473 are 3 hours behind UTC in the winter. Its clocks follow the European
2474 Union rules of springing forward by one hour on March's last Sunday at
2475 01:00 UTC (@minus{}02:00 local time) and falling back on October's
2476 last Sunday at 01:00 UTC (@minus{}01:00 local time).
2479 WGT3WGST,M3.5.0/-2,M10.5.0/-1
2482 The schedule of Daylight Saving Time in any particular jurisdiction has
2483 changed over the years. To be strictly correct, the conversion of dates
2484 and times in the past should be based on the schedule that was in effect
2485 then. However, this format has no facilities to let you specify how the
2486 schedule has changed from year to year. The most you can do is specify
2487 one particular schedule---usually the present day schedule---and this is
2488 used to convert any date, no matter when. For precise time zone
2489 specifications, it is best to use the time zone information database
2492 The third format looks like this:
2498 Each operating system interprets this format differently; in
2499 @theglibc{}, @var{characters} is the name of a file which describes the time
2502 @pindex /etc/localtime
2504 If the @code{TZ} environment variable does not have a value, the
2505 operation chooses a time zone by default. In @theglibc{}, the
2506 default time zone is like the specification @samp{TZ=:/etc/localtime}
2507 (or @samp{TZ=:/usr/local/etc/localtime}, depending on how @theglibc{}
2508 was configured; @pxref{Installation}). Other C libraries use their own
2509 rule for choosing the default time zone, so there is little we can say
2512 @cindex time zone database
2513 @pindex /usr/share/zoneinfo
2515 If @var{characters} begins with a slash, it is an absolute file name;
2516 otherwise the library looks for the file
2517 @w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo}
2518 directory contains data files describing local time zones in many
2519 different parts of the world. The names represent major cities, with
2520 subdirectories for geographical areas; for example,
2521 @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
2522 These data files are installed by the system administrator, who also
2523 sets @file{/etc/localtime} to point to the data file for the local time
2524 zone. The files typically come from the @url{http://www.iana.org/time-zones,
2525 Time Zone Database} of time zone and daylight saving time
2526 information for most regions of the world, which is maintained by a
2527 community of volunteers and put in the public domain.
2529 @node Time Zone Functions
2530 @subsection Functions and Variables for Time Zones
2532 @deftypevar {char *} tzname [2]
2533 @standards{POSIX.1, time.h}
2534 The array @code{tzname} contains two strings, which are the standard
2535 names of the pair of time zones (standard and Daylight
2536 Saving) that the user has selected. @code{tzname[0]} is the name of
2537 the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
2538 is the name for the time zone when Daylight Saving Time is in use (for
2539 example, @code{"EDT"}). These correspond to the @var{std} and @var{dst}
2540 strings (respectively) from the @code{TZ} environment variable. If
2541 Daylight Saving Time is never used, @code{tzname[1]} is the empty string.
2543 The @code{tzname} array is initialized from the @code{TZ} environment
2544 variable whenever @code{tzset}, @code{ctime}, @code{strftime},
2545 @code{mktime}, or @code{localtime} is called. If multiple abbreviations
2546 have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War
2547 Time and Eastern Daylight Time), the array contains the most recent
2550 The @code{tzname} array is required for POSIX.1 compatibility, but in
2551 GNU programs it is better to use the @code{tm_zone} member of the
2552 broken-down time structure, since @code{tm_zone} reports the correct
2553 abbreviation even when it is not the latest one.
2555 Though the strings are declared as @code{char *} the user must refrain
2556 from modifying these strings. Modifying the strings will almost certainly
2561 @deftypefun void tzset (void)
2562 @standards{POSIX.1, time.h}
2563 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2564 @c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2565 @c libc_lock_lock dup @asulock @aculock
2566 @c tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2567 @c libc_lock_unlock dup @aculock
2568 The @code{tzset} function initializes the @code{tzname} variable from
2569 the value of the @code{TZ} environment variable. It is not usually
2570 necessary for your program to call this function, because it is called
2571 automatically when you use the other time conversion functions that
2572 depend on the time zone.
2575 The following variables are defined for compatibility with System V
2576 Unix. Like @code{tzname}, these variables are set by calling
2577 @code{tzset} or the other time conversion functions.
2579 @deftypevar {long int} timezone
2580 @standards{SVID, time.h}
2581 This contains the difference between UTC and the latest local standard
2582 time, in seconds west of UTC. For example, in the U.S. Eastern time
2583 zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member
2584 of the broken-down time structure, this value is not adjusted for
2585 daylight saving, and its sign is reversed. In GNU programs it is better
2586 to use @code{tm_gmtoff}, since it contains the correct offset even when
2587 it is not the latest one.
2590 @deftypevar int daylight
2591 @standards{SVID, time.h}
2592 This variable has a nonzero value if Daylight Saving Time rules apply.
2593 A nonzero value does not necessarily mean that Daylight Saving Time is
2594 now in effect; it means only that Daylight Saving Time is sometimes in
2598 @node Time Functions Example
2599 @subsection Time Functions Example
2601 Here is an example program showing the use of some of the calendar time
2605 @include strftim.c.texi
2608 It produces output like this:
2611 Wed Jul 31 13:02:36 1991
2612 Today is Wednesday, July 31.
2613 The time is 01:02 PM.
2617 @node Setting an Alarm
2618 @section Setting an Alarm
2620 The @code{alarm} and @code{setitimer} functions provide a mechanism for a
2621 process to interrupt itself in the future. They do this by setting a
2622 timer; when the timer expires, the process receives a signal.
2624 @cindex setting an alarm
2625 @cindex interval timer, setting
2626 @cindex alarms, setting
2627 @cindex timers, setting
2628 Each process has three independent interval timers available:
2632 A real-time timer that counts elapsed time. This timer sends a
2633 @code{SIGALRM} signal to the process when it expires.
2634 @cindex real-time timer
2635 @cindex timer, real-time
2638 A virtual timer that counts processor time used by the process. This timer
2639 sends a @code{SIGVTALRM} signal to the process when it expires.
2640 @cindex virtual timer
2641 @cindex timer, virtual
2644 A profiling timer that counts both processor time used by the process,
2645 and processor time spent in system calls on behalf of the process. This
2646 timer sends a @code{SIGPROF} signal to the process when it expires.
2647 @cindex profiling timer
2648 @cindex timer, profiling
2650 This timer is useful for profiling in interpreters. The interval timer
2651 mechanism does not have the fine granularity necessary for profiling
2653 @c @xref{profil} !!!
2656 You can only have one timer of each kind set at any given time. If you
2657 set a timer that has not yet expired, that timer is simply reset to the
2660 You should establish a handler for the appropriate alarm signal using
2661 @code{signal} or @code{sigaction} before issuing a call to
2662 @code{setitimer} or @code{alarm}. Otherwise, an unusual chain of events
2663 could cause the timer to expire before your program establishes the
2664 handler. In this case it would be terminated, since termination is the
2665 default action for the alarm signals. @xref{Signal Handling}.
2667 To be able to use the alarm function to interrupt a system call which
2668 might block otherwise indefinitely it is important to @emph{not} set the
2669 @code{SA_RESTART} flag when registering the signal handler using
2670 @code{sigaction}. When not using @code{sigaction} things get even
2671 uglier: the @code{signal} function has fixed semantics with respect
2672 to restarts. The BSD semantics for this function is to set the flag.
2673 Therefore, if @code{sigaction} for whatever reason cannot be used, it is
2674 necessary to use @code{sysv_signal} and not @code{signal}.
2676 The @code{setitimer} function is the primary means for setting an alarm.
2677 This facility is declared in the header file @file{sys/time.h}. The
2678 @code{alarm} function, declared in @file{unistd.h}, provides a somewhat
2679 simpler interface for setting the real-time timer.
2683 @deftp {Data Type} {struct itimerval}
2684 @standards{BSD, sys/time.h}
2685 This structure is used to specify when a timer should expire. It contains
2686 the following members:
2688 @item struct timeval it_interval
2689 This is the period between successive timer interrupts. If zero, the
2690 alarm will only be sent once.
2692 @item struct timeval it_value
2693 This is the period between now and the first timer interrupt. If zero,
2694 the alarm is disabled.
2697 The @code{struct timeval} data type is described in @ref{Elapsed Time}.
2700 @deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old})
2701 @standards{BSD, sys/time.h}
2702 @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
2703 @c This function is marked with @mtstimer because the same set of timers
2704 @c is shared by all threads of a process, so calling it in one thread
2705 @c may interfere with timers set by another thread. This interference
2706 @c is not regarded as destructive, because the interface specification
2707 @c makes this overriding while returning the previous value the expected
2708 @c behavior, and the kernel will serialize concurrent calls so that the
2709 @c last one prevails, with each call getting the timer information from
2710 @c the timer installed by the previous call in that serialization.
2711 The @code{setitimer} function sets the timer specified by @var{which}
2712 according to @var{new}. The @var{which} argument can have a value of
2713 @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
2715 If @var{old} is not a null pointer, @code{setitimer} returns information
2716 about any previous unexpired timer of the same kind in the structure it
2719 The return value is @code{0} on success and @code{-1} on failure. The
2720 following @code{errno} error conditions are defined for this function:
2724 The timer period is too large.
2728 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
2729 @standards{BSD, sys/time.h}
2730 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2731 The @code{getitimer} function stores information about the timer specified
2732 by @var{which} in the structure pointed at by @var{old}.
2734 The return value and error conditions are the same as for @code{setitimer}.
2739 @standards{BSD, sys/time.h}
2740 This constant can be used as the @var{which} argument to the
2741 @code{setitimer} and @code{getitimer} functions to specify the real-time
2744 @item ITIMER_VIRTUAL
2745 @standards{BSD, sys/time.h}
2746 This constant can be used as the @var{which} argument to the
2747 @code{setitimer} and @code{getitimer} functions to specify the virtual
2751 @standards{BSD, sys/time.h}
2752 This constant can be used as the @var{which} argument to the
2753 @code{setitimer} and @code{getitimer} functions to specify the profiling
2757 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
2758 @standards{POSIX.1, unistd.h}
2759 @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
2760 @c Wrapper for setitimer.
2761 The @code{alarm} function sets the real-time timer to expire in
2762 @var{seconds} seconds. If you want to cancel any existing alarm, you
2763 can do this by calling @code{alarm} with a @var{seconds} argument of
2766 The return value indicates how many seconds remain before the previous
2767 alarm would have been sent. If there was no previous alarm, @code{alarm}
2771 The @code{alarm} function could be defined in terms of @code{setitimer}
2776 alarm (unsigned int seconds)
2778 struct itimerval old, new;
2779 new.it_interval.tv_usec = 0;
2780 new.it_interval.tv_sec = 0;
2781 new.it_value.tv_usec = 0;
2782 new.it_value.tv_sec = (long int) seconds;
2783 if (setitimer (ITIMER_REAL, &new, &old) < 0)
2786 return old.it_value.tv_sec;
2790 There is an example showing the use of the @code{alarm} function in
2791 @ref{Handler Returns}.
2793 If you simply want your process to wait for a given number of seconds,
2794 you should use the @code{sleep} function. @xref{Sleeping}.
2796 You shouldn't count on the signal arriving precisely when the timer
2797 expires. In a multiprocessing environment there is typically some
2798 amount of delay involved.
2800 @strong{Portability Note:} The @code{setitimer} and @code{getitimer}
2801 functions are derived from BSD Unix, while the @code{alarm} function is
2802 specified by the POSIX.1 standard. @code{setitimer} is more powerful than
2803 @code{alarm}, but @code{alarm} is more widely used.
2808 The function @code{sleep} gives a simple way to make the program wait
2809 for a short interval. If your program doesn't use signals (except to
2810 terminate), then you can expect @code{sleep} to wait reliably throughout
2811 the specified interval. Otherwise, @code{sleep} can return sooner if a
2812 signal arrives; if you want to wait for a given interval regardless of
2813 signals, use @code{select} (@pxref{Waiting for I/O}) and don't specify
2814 any descriptors to wait for.
2815 @c !!! select can get EINTR; using SA_RESTART makes sleep win too.
2817 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
2818 @standards{POSIX.1, unistd.h}
2819 @safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}}
2820 @c On Mach, it uses ports and calls time. On generic posix, it calls
2821 @c nanosleep. On Linux, it temporarily blocks SIGCHLD, which is MT- and
2822 @c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!).
2823 The @code{sleep} function waits for @var{seconds} seconds or until a signal
2824 is delivered, whichever happens first.
2826 If @code{sleep} returns because the requested interval is over,
2827 it returns a value of zero. If it returns because of delivery of a
2828 signal, its return value is the remaining time in the sleep interval.
2830 The @code{sleep} function is declared in @file{unistd.h}.
2833 Resist the temptation to implement a sleep for a fixed amount of time by
2834 using the return value of @code{sleep}, when nonzero, to call
2835 @code{sleep} again. This will work with a certain amount of accuracy as
2836 long as signals arrive infrequently. But each signal can cause the
2837 eventual wakeup time to be off by an additional second or so. Suppose a
2838 few signals happen to arrive in rapid succession by bad luck---there is
2839 no limit on how much this could shorten or lengthen the wait.
2841 Instead, compute the calendar time at which the program should stop
2842 waiting, and keep trying to wait until that calendar time. This won't
2843 be off by more than a second. With just a little more work, you can use
2844 @code{select} and make the waiting period quite accurate. (Of course,
2845 heavy system load can cause additional unavoidable delays---unless the
2846 machine is dedicated to one application, there is no way you can avoid
2849 On some systems, @code{sleep} can do strange things if your program uses
2850 @code{SIGALRM} explicitly. Even if @code{SIGALRM} signals are being
2851 ignored or blocked when @code{sleep} is called, @code{sleep} might
2852 return prematurely on delivery of a @code{SIGALRM} signal. If you have
2853 established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
2854 signal is delivered while the process is sleeping, the action taken
2855 might be just to cause @code{sleep} to return instead of invoking your
2856 handler. And, if @code{sleep} is interrupted by delivery of a signal
2857 whose handler requests an alarm or alters the handling of @code{SIGALRM},
2858 this handler and @code{sleep} will interfere.
2860 On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in
2861 the same program, because @code{sleep} does not work by means of
2864 @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
2865 @standards{POSIX.1, time.h}
2866 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2867 @c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses
2869 If resolution to seconds is not enough the @code{nanosleep} function can
2870 be used. As the name suggests the sleep interval can be specified in
2871 nanoseconds. The actual elapsed time of the sleep interval might be
2872 longer since the system rounds the elapsed time you request up to the
2873 next integer multiple of the actual resolution the system can deliver.
2875 *@code{requested_time} is the elapsed time of the interval you want to
2878 The function returns as *@code{remaining} the elapsed time left in the
2879 interval for which you requested to sleep. If the interval completed
2880 without getting interrupted by a signal, this is zero.
2882 @code{struct timespec} is described in @xref{Elapsed Time}.
2884 If the function returns because the interval is over the return value is
2885 zero. If the function returns @math{-1} the global variable @code{errno}
2886 is set to the following values:
2890 The call was interrupted because a signal was delivered to the thread.
2891 If the @var{remaining} parameter is not the null pointer the structure
2892 pointed to by @var{remaining} is updated to contain the remaining
2896 The nanosecond value in the @var{requested_time} parameter contains an
2897 illegal value. Either the value is negative or greater than or equal to
2901 This function is a cancellation point in multi-threaded programs. This
2902 is a problem if the thread allocates some resources (like memory, file
2903 descriptors, semaphores or whatever) at the time @code{nanosleep} is
2904 called. If the thread gets canceled these resources stay allocated
2905 until the program ends. To avoid this calls to @code{nanosleep} should
2906 be protected using cancellation handlers.
2907 @c ref pthread_cleanup_push / pthread_cleanup_pop
2909 The @code{nanosleep} function is declared in @file{time.h}.