powerpc: Update AT_HWCAP2 bits
[glibc.git] / manual / time.texi
blob33aa221428032a38b7689946a33fe697214f9120
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
3 @chapter Date and Time
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.
9 @menu
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.
16 @end menu
19 @node Time Basics
20 @section Time Basics
21 @cindex 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
30 time''.
31 @cindex calendar time
33 We don't speak of a ``date'', because that is inherent in a calendar
34 time.
35 @cindex date
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,
39 1980.
40 @cindex interval
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.
45 @cindex elapsed time
46 @cindex time, elapsed
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
51 sittings it is read.
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
55 events.
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.
61 @cindex CPU time
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
68 definition above.
69 @cindex processor time
71 @node Elapsed Time
72 @section Elapsed Time
73 @cindex elapsed 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.
90 @end deftypefun
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}
100 @cindex timeval
101 The @code{struct timeval} structure represents an elapsed time.  It is
102 declared in @file{sys/time.h} and has the following members:
104 @table @code
105 @item time_t tv_sec
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
111 million.
113 @end table
114 @end deftp
116 @deftp {Data Type} {struct timespec}
117 @standards{POSIX.1, sys/time.h}
118 @cindex timespec
119 The @code{struct timespec} structure represents an elapsed time.  It is
120 declared in @file{time.h} and has the following members:
122 @table @code
123 @item time_t tv_sec
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
129 billion.
131 @end table
132 @end deftp
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.
139 @smallexample
140 @include timeval_subtract.c.texi
141 @end smallexample
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.
169 @cindex CPU time
170 @cindex clock ticks
171 @cindex ticks, clock
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
179 representation is.
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}.
189 @menu
190 * CPU Time::                    The @code{clock} function.
191 * Processor Time::              The @code{times} function.
192 @end menu
194 @node CPU Time
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}.
199 @pindex 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:
206 @smallexample
207 @group
208 #include <time.h>
210 clock_t start, end;
211 double cpu_time_used;
213 start = clock();
214 @dots{} /* @r{Do the work.} */
215 end = clock();
216 cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
217 @end group
218 @end smallexample
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
227 second.
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.
234 @end deftypevr
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.
240 @end deftp
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
249 @c clock_gettime.
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)}.
253 @end deftypefun
256 @node Processor Time
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
264 @cindex CPU time
265 @pindex sys/times.h
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:
272 @table @code
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
279 process.
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
289 @code{waitpid}.
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.
296 @end table
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}.
301 @end deftp
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.
307 @end deftypevr
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.
323 @end deftypefun
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}.
331 @node Calendar Time
332 @section Calendar Time
334 This section describes facilities for keeping track of calendar time.
335 @xref{Time Basics}.
337 @Theglibc{} represents calendar time three ways:
339 @itemize @bullet
340 @item
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.
344 @cindex simple time
346 @item
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
354 @item
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.
360 @cindex local time
361 @cindex broken-down time
362 @cindex Gregorian calendar
363 @cindex calendar, Gregorian
364 @end itemize
366 @menu
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
377                                  the time functions.
378 @end menu
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}.
386 @pindex time.h
388 @cindex epoch
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
405 floating-point type.
406 @end deftp
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.
420 @end deftypefun
422 @c The GNU C library implements stime() with a call to settimeofday() on
423 @c Linux.
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:
442 @table @code
443 @item EPERM
444 The process is not superuser.
445 @end table
446 @end deftypefun
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}.
460 @pindex 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:
467 @table @code
468 @item int tz_minuteswest
469 This is the number of minutes west of UTC.
471 @item int tz_dsttime
472 If nonzero, Daylight Saving Time applies during some part of the year.
473 @end table
475 The @code{struct timezone} type is obsolete and should never be used.
476 Instead, use the facilities described in @ref{Time Zone Functions}.
477 @end deftp
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:
497 @table @code
498 @item ENOSYS
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}.
504 @end table
505 @end deftypefun
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
525 @code{stime}.
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:
539 @table @code
540 @item EPERM
541 This process cannot set the clock because it is not privileged.
543 @item ENOSYS
544 The operating system does not support setting time zone information, and
545 @var{tzp} is not a null pointer.
546 @end table
547 @end deftypefun
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
555 @c a syscall.
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:
579 @table @code
580 @item EPERM
581 You do not have privilege to set the time.
582 @end table
583 @end deftypefun
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.
601 @end deftypefun
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.
626 @table @code
627 @item int tm_sec
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
631 available).
632 @cindex leap second
634 @item int tm_min
635 This is the number of full minutes since the top of the hour (in the
636 range @code{0} through @code{59}).
638 @item int tm_hour
639 This is the number of full hours past midnight (in the range @code{0} through
640 @code{23}).
642 @item int tm_mday
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.
647 @item int tm_mon
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).
652 @item int tm_year
653 This is the number of full calendar years since 1900.
655 @item int tm_wday
656 This is the number of full days since Sunday (in the range @code{0} through
657 @code{6}).
659 @item int tm_yday
660 This is the number of full days since the beginning of the year (in the
661 range @code{0} through @code{365}).
663 @item int tm_isdst
664 @cindex Daylight Saving Time
665 @cindex summer 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.
684 @end table
685 @end deftp
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
701 of this object.)
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
705 an @code{int}.
707 Calling @code{localtime} also sets the current time zone as if
708 @code{tzset} were called.  @xref{Time Zone Functions}.
709 @end deftypefun
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
729 @c    strcmp dup ok
730 @c    strdup @ascuheap
731 @c    tzfile_read @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
732 @c     memcmp dup ok
733 @c     strstr dup ok
734 @c     getenv dup @mtsenv
735 @c     asprintf dup @mtslocale @ascuheap @acsmem
736 @c     stat64 dup ok
737 @c     fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
738 @c     fileno dup ok
739 @c     fstat64 dup ok
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]
744 @c     memcpy dup ok
745 @c     decode ok
746 @c      bswap_32 dup ok
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
750 @c     decode64 ok
751 @c      bswap_64 dup ok
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]
755 @c    memset dup ok
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.
762 @c     strlen ok
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)
769 @c      strlen dup ok
770 @c      malloc dup @ascuheap @acsmem
771 @c      strcpy dup ok
772 @c     isdigit dup @mtslocale
773 @c     compute_offset ok
774 @c     tzfile_default @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
775 @c       sets tzname, timezone, types, zone_names, rule_*off, etc; no guards
776 @c      strlen dup ok
777 @c      tzfile_read dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
778 @c      mempcpy dup ok
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
788 @c    offtime dup ok
789 @c    tz_compute dup ok
790 @c    strcmp dup ok
791 @c   offtime ok
792 @c    isleap dup ok
793 @c   tz_compute ok
794 @c    compute_change ok
795 @c     isleap ok
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}.
808 @end deftypefun
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.
820 @end deftypefun
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
824 @code{gmtime}.
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}.
842 @end deftypefun
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
860 @c   ydhms_diff ok
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
863 @c    time_t_avg dup ok
864 @c   guess_time_tm dup ok
865 @c    ydhms_diff dup ok
866 @c    time_t_add_ok ok
867 @c     time_t_avg ok
868 @c   isdst_differ 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}.
892 @end deftypefun
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{}}}
897 @c Alias to mktime.
899 @code{timelocal} is functionally identical to @code{mktime}, but more
900 mnemonically named.  Note that it is the inverse of the @code{localtime}
901 function.
903 @strong{Portability note:}  @code{mktime} is essentially universally
904 available.  @code{timelocal} is rather rare.
906 @end deftypefun
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
919 @c    ... dup ok
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
934 @code{TZ} back.
936 @end deftypefun
940 @node High Accuracy Clock
941 @subsection High Accuracy Clock
943 @cindex time, high precision
944 @cindex clock, high accuracy
945 @pindex sys/timex.h
946 @c On Linux, GNU libc implements ntp_gettime() and npt_adjtime() as calls
947 @c to adjtimex().
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
955 precision clocks.
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:
963 @table @code
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
967 @ref{Elapsed Time}.
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.
978 @end table
979 @end deftp
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}
989 call is necessary.
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:
994 @vtable @code
995 @item TIME_ERROR
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
998 treated with care.
999 @end vtable
1000 @end deftypefun
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:
1006 @table @code
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}.
1037 @item int status
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
1055 second.
1057 @item struct timeval time
1058 The current calendar time.
1060 @item long int tick
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.
1074 @item int shift
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.
1096 @end table
1097 @end deftp
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:
1126 @table @code
1127 @item TIME_ERROR
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
1131 are not allowed.
1133 @item EPERM
1134 The process specified a settings update, but is not superuser.
1136 @end table
1138 For more details see RFC1305 (Network Time Protocol, Version 3) and
1139 related documents.
1141 @strong{Portability note:} Early versions of @theglibc{} did not
1142 have this function but did have the synonymous @code{adjtimex}.
1144 @end deftypefun
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}.
1152 @pindex 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:
1166 @smallexample
1167 "Tue May 21 13:46:22 1991\n"
1168 @end smallexample
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
1180 string.)
1181 @end deftypefun
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}.
1196 @end deftypefun
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
1209 @smallexample
1210 asctime (localtime (@var{time}))
1211 @end smallexample
1213 Calling @code{ctime} also sets the current time zone as if
1214 @code{tzset} were called.  @xref{Time Zone Functions}.
1215 @end deftypefun
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}):
1227 @smallexample
1228 (@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @})
1229 @end smallexample
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}.
1234 @end deftypefun
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
1243 @c    add ok
1244 @c     memset_zero dup ok
1245 @c     memset_space dup ok
1246 @c    strlen dup ok
1247 @c    mbrlen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
1248 @c    mbsinit dup ok
1249 @c    cpy ok
1250 @c     add dup ok
1251 @c     memcpy_lowcase ok
1252 @c      TOLOWER ok
1253 @c       tolower_l ok
1254 @c     memcpy_uppcase ok
1255 @c      TOUPPER ok
1256 @c       toupper_l ok
1257 @c     MEMCPY ok
1258 @c      memcpy dup ok
1259 @c    ISDIGIT ok
1260 @c    STRLEN ok
1261 @c     strlen dup ok
1262 @c    strftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1263 @c    TOUPPER dup ok
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
1268 @c      memset dup ok
1269 @c      free dup @ascuheap @acsmem
1270 @c      realloc dup @ascuheap @acsmem
1271 @c      memcpy dup ok
1272 @c      strchr dup ok
1273 @c      wcschr dup ok
1274 @c      libc_rwlock_unlock dup @asulock @aculock
1275 @c     ERA_DATE_CMP ok
1276 @c    DO_NUMBER ok
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
1282 @c      memset dup ok
1283 @c      strchr dup ok
1284 @c     libc_rwlock_unlock dup @aculock
1285 @c    memset_space ok
1286 @c     memset dup ok
1287 @c    memset_zero ok
1288 @c     memset dup ok
1289 @c    mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1290 @c    iso_week_days ok
1291 @c    isleap ok
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
1295 @c    tm_diff ok
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
1308 numbers:
1310 @table @code
1311 @item _
1312 The number is padded with spaces.
1314 @item -
1315 The number is not padded at all.
1317 @item 0
1318 The number is padded with zeros even if the format specifies padding
1319 with spaces.
1321 @item ^
1322 The output uses uppercase characters, but only if this is possible
1323 (@pxref{Case Conversion}).
1324 @end table
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
1334 size.
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:
1340 @table @code
1341 @item E
1342 Use the locale's alternate 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
1346 Emperors' reigns.
1348 @item O
1349 Use the locale's alternate numeric symbols for numbers.  This modifier
1350 applies only to numeric format specifiers.
1351 @end table
1353 If the format supports the modifier but no alternate representation
1354 is available, it is ignored.
1356 The conversion specifier ends with a format specifier taken from the
1357 following list.  The whole @samp{%} sequence is replaced in the output
1358 string as follows:
1360 @table @code
1361 @item %a
1362 The abbreviated weekday name according to the current locale.
1364 @item %A
1365 The full weekday name according to the current locale.
1367 @item %b
1368 The abbreviated month name according to the current locale.
1370 @item %B
1371 The full month name according to the current locale.
1373 Using @code{%B} together with @code{%d} produces grammatically
1374 incorrect results for some locales.
1376 @item %c
1377 The preferred calendar time representation for the current locale.
1379 @item %C
1380 The century of the year.  This is equivalent to the greatest integer not
1381 greater than the year divided by 100.
1383 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1385 @item %d
1386 The day of the month as a decimal number (range @code{01} through @code{31}).
1388 @item %D
1389 The date using the format @code{%m/%d/%y}.
1391 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1393 @item %e
1394 The day of the month like with @code{%d}, but padded with spaces (range
1395 @code{ 1} through @code{31}).
1397 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1399 @item %F
1400 The date using the format @code{%Y-%m-%d}.  This is the form specified
1401 in the @w{ISO 8601} standard and is the preferred form for all uses.
1403 This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
1405 @item %g
1406 The year corresponding to the ISO week number, but without the century
1407 (range @code{00} through @code{99}).  This has the same format and value
1408 as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
1409 to the previous or next year, that year is used instead.
1411 This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
1413 @item %G
1414 The year corresponding to the ISO week number.  This has the same format
1415 and value as @code{%Y}, except that if the ISO week number (see
1416 @code{%V}) belongs to the previous or next year, that year is used
1417 instead.
1419 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1420 but was previously available as a GNU extension.
1422 @item %h
1423 The abbreviated month name according to the current locale.  The action
1424 is the same as for @code{%b}.
1426 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1428 @item %H
1429 The hour as a decimal number, using a 24-hour clock (range @code{00} through
1430 @code{23}).
1432 @item %I
1433 The hour as a decimal number, using a 12-hour clock (range @code{01} through
1434 @code{12}).
1436 @item %j
1437 The day of the year as a decimal number (range @code{001} through @code{366}).
1439 @item %k
1440 The hour as a decimal number, using a 24-hour clock like @code{%H}, but
1441 padded with spaces (range @code{ 0} through @code{23}).
1443 This format is a GNU extension.
1445 @item %l
1446 The hour as a decimal number, using a 12-hour clock like @code{%I}, but
1447 padded with spaces (range @code{ 1} through @code{12}).
1449 This format is a GNU extension.
1451 @item %m
1452 The month as a decimal number (range @code{01} through @code{12}).
1454 @item %M
1455 The minute as a decimal number (range @code{00} through @code{59}).
1457 @item %n
1458 A single @samp{\n} (newline) character.
1460 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1462 @item %p
1463 Either @samp{AM} or @samp{PM}, according to the given time value; or the
1464 corresponding strings for the current locale.  Noon is treated as
1465 @samp{PM} and midnight as @samp{AM}.  In most locales
1466 @samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"}
1467 yields an empty string.
1469 @ignore
1470 We currently have a problem with makeinfo.  Write @samp{AM} and @samp{am}
1471 both results in `am'.  I.e., the difference in case is not visible anymore.
1472 @end ignore
1473 @item %P
1474 Either @samp{am} or @samp{pm}, according to the given time value; or the
1475 corresponding strings for the current locale, printed in lowercase
1476 characters.  Noon is treated as @samp{pm} and midnight as @samp{am}.  In
1477 most locales @samp{AM}/@samp{PM} format is not supported, in such cases
1478 @code{"%P"} yields an empty string.
1480 This format is a GNU extension.
1482 @item %r
1483 The complete calendar time using the AM/PM format of the current locale.
1485 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1486 In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}.
1488 @item %R
1489 The hour and minute in decimal numbers using the format @code{%H:%M}.
1491 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1492 but was previously available as a GNU extension.
1494 @item %s
1495 The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
1496 Leap seconds are not counted unless leap second support is available.
1498 This format is a GNU extension.
1500 @item %S
1501 The seconds as a decimal number (range @code{00} through @code{60}).
1503 @item %t
1504 A single @samp{\t} (tabulator) character.
1506 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1508 @item %T
1509 The time of day using decimal numbers using the format @code{%H:%M:%S}.
1511 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1513 @item %u
1514 The day of the week as a decimal number (range @code{1} through
1515 @code{7}), Monday being @code{1}.
1517 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1519 @item %U
1520 The week number of the current year as a decimal number (range @code{00}
1521 through @code{53}), starting with the first Sunday as the first day of
1522 the first week.  Days preceding the first Sunday in the year are
1523 considered to be in week @code{00}.
1525 @item %V
1526 The @w{ISO 8601:1988} week number as a decimal number (range @code{01}
1527 through @code{53}).  ISO weeks start with Monday and end with Sunday.
1528 Week @code{01} of a year is the first week which has the majority of its
1529 days in that year; this is equivalent to the week containing the year's
1530 first Thursday, and it is also equivalent to the week containing January
1531 4.  Week @code{01} of a year can contain days from the previous year.
1532 The week before week @code{01} of a year is the last week (@code{52} or
1533 @code{53}) of the previous year even if it contains days from the new
1534 year.
1536 This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
1538 @item %w
1539 The day of the week as a decimal number (range @code{0} through
1540 @code{6}), Sunday being @code{0}.
1542 @item %W
1543 The week number of the current year as a decimal number (range @code{00}
1544 through @code{53}), starting with the first Monday as the first day of
1545 the first week.  All days preceding the first Monday in the year are
1546 considered to be in week @code{00}.
1548 @item %x
1549 The preferred date representation for the current locale.
1551 @item %X
1552 The preferred time of day representation for the current locale.
1554 @item %y
1555 The year without a century as a decimal number (range @code{00} through
1556 @code{99}).  This is equivalent to the year modulo 100.
1558 @item %Y
1559 The year as a decimal number, using the Gregorian calendar.  Years
1560 before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
1562 @item %z
1563 @w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
1564 @code{-0600} or @code{+0100}), or nothing if no time zone is
1565 determinable.
1567 This format was first standardized by @w{ISO C99} and by POSIX.1-2001
1568 but was previously available as a GNU extension.
1570 In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format
1571 @w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent
1572 @w{@samp{"%a, %d %b %Y %T %z"}}).
1574 @item %Z
1575 The time zone abbreviation (empty if the time zone can't be determined).
1577 @item %%
1578 A literal @samp{%} character.
1579 @end table
1581 The @var{size} parameter can be used to specify the maximum number of
1582 characters to be stored in the array @var{s}, including the terminating
1583 null character.  If the formatted time requires more than @var{size}
1584 characters, @code{strftime} returns zero and the contents of the array
1585 @var{s} are undefined.  Otherwise the return value indicates the
1586 number of characters placed in the array @var{s}, not including the
1587 terminating null character.
1589 @emph{Warning:} This convention for the return value which is prescribed
1590 in @w{ISO C} can lead to problems in some situations.  For certain
1591 format strings and certain locales the output really can be the empty
1592 string and this cannot be discovered by testing the return value only.
1593 E.g., in most locales the AM/PM time format is not supported (most of
1594 the world uses the 24 hour time representation).  In such locales
1595 @code{"%p"} will return the empty string, i.e., the return value is
1596 zero.  To detect situations like this something similar to the following
1597 code should be used:
1599 @smallexample
1600 buf[0] = '\1';
1601 len = strftime (buf, bufsize, format, tp);
1602 if (len == 0 && buf[0] != '\0')
1603   @{
1604     /* Something went wrong in the strftime call.  */
1605     @dots{}
1606   @}
1607 @end smallexample
1609 If @var{s} is a null pointer, @code{strftime} does not actually write
1610 anything, but instead returns the number of characters it would have written.
1612 Calling @code{strftime} also sets the current time zone as if
1613 @code{tzset} were called; @code{strftime} uses this information
1614 instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone}
1615 members.  @xref{Time Zone Functions}.
1617 For an example of @code{strftime}, see @ref{Time Functions Example}.
1618 @end deftypefun
1620 @deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime})
1621 @standards{ISO/Amend1, time.h}
1622 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
1623 @c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1624 @c  wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1625 @c   wcsftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1626 @c    add ok
1627 @c     memset_zero dup ok
1628 @c     memset_space dup ok
1629 @c    wcslen dup ok
1630 @c    cpy ok
1631 @c     add dup ok
1632 @c     memcpy_lowcase ok
1633 @c      TOLOWER ok
1634 @c       towlower_l dup ok
1635 @c     memcpy_uppcase ok
1636 @c      TOUPPER ok
1637 @c       towupper_l dup ok
1638 @c     MEMCPY ok
1639 @c      wmemcpy dup ok
1640 @c    widen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1641 @c     memset dup ok
1642 @c     mbsrtowcs_l @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
1643 @c    ISDIGIT ok
1644 @c    STRLEN ok
1645 @c     wcslen dup ok
1646 @c    wcsftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
1647 @c    TOUPPER dup ok
1648 @c    nl_get_era_entry dup @ascuheap @asulock @acsmem @aculock
1649 @c    DO_NUMBER ok
1650 @c    DO_NUMBER_SPACEPAD ok
1651 @c    nl_get_walt_digit dup @ascuheap @asulock @acsmem @aculock
1652 @c     libc_rwlock_wrlock dup @asulock @aculock
1653 @c     nl_init_alt_digit dup @ascuheap @acsmem
1654 @c     malloc dup @ascuheap @acsmem
1655 @c     memset dup ok
1656 @c     wcschr dup ok
1657 @c     libc_rwlock_unlock dup @aculock
1658 @c    memset_space ok
1659 @c     wmemset dup ok
1660 @c    memset_zero ok
1661 @c     wmemset dup ok
1662 @c    mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1663 @c    iso_week_days ok
1664 @c    isleap ok
1665 @c    tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1666 @c    localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1667 @c    gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1668 @c    tm_diff ok
1669 The @code{wcsftime} function is equivalent to the @code{strftime}
1670 function with the difference that it operates on wide character
1671 strings.  The buffer where the result is stored, pointed to by @var{s},
1672 must be an array of wide characters.  The parameter @var{size} which
1673 specifies the size of the output buffer gives the number of wide
1674 characters, not the number of bytes.
1676 Also the format string @var{template} is a wide character string.  Since
1677 all characters needed to specify the format string are in the basic
1678 character set it is portably possible to write format strings in the C
1679 source code using the @code{L"@dots{}"} notation.  The parameter
1680 @var{brokentime} has the same meaning as in the @code{strftime} call.
1682 The @code{wcsftime} function supports the same flags, modifiers, and
1683 format specifiers as the @code{strftime} function.
1685 The return value of @code{wcsftime} is the number of wide characters
1686 stored in @code{s}.  When more characters would have to be written than
1687 can be placed in the buffer @var{s} the return value is zero, with the
1688 same problems indicated in the @code{strftime} documentation.
1689 @end deftypefun
1691 @node Parsing Date and Time
1692 @subsection Convert textual time and date information back
1694 The @w{ISO C} standard does not specify any functions which can convert
1695 the output of the @code{strftime} function back into a binary format.
1696 This led to a variety of more-or-less successful implementations with
1697 different interfaces over the years.  Then the Unix standard was
1698 extended by the addition of two functions: @code{strptime} and
1699 @code{getdate}.  Both have strange interfaces but at least they are
1700 widely available.
1702 @menu
1703 * Low-Level Time String Parsing::  Interpret string according to given format.
1704 * General Time String Parsing::    User-friendly function to parse data and
1705                                     time strings.
1706 @end menu
1708 @node Low-Level Time String Parsing
1709 @subsubsection Interpret string according to given format
1711 The first function is rather low-level.  It is nevertheless frequently
1712 used in software since it is better known.  Its interface and
1713 implementation are heavily influenced by the @code{getdate} function,
1714 which is defined and implemented in terms of calls to @code{strptime}.
1716 @deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp})
1717 @standards{XPG4, time.h}
1718 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1719 @c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1720 @c  strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1721 @c   memset dup ok
1722 @c   ISSPACE ok
1723 @c    isspace_l dup ok
1724 @c   match_char ok
1725 @c   match_string ok
1726 @c    strlen dup ok
1727 @c    strncasecmp_l dup ok
1728 @c   strcmp dup ok
1729 @c   recursive @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1730 @c    strptime_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1731 @c   get_number ok
1732 @c    ISSPACE dup ok
1733 @c   localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1734 @c   nl_select_era_entry @ascuheap @asulock @acsmem @aculock
1735 @c    nl_init_era_entries dup @ascuheap @asulock @acsmem @aculock
1736 @c   get_alt_number dup @ascuheap @asulock @acsmem @aculock
1737 @c    nl_parse_alt_digit dup @ascuheap @asulock @acsmem @aculock
1738 @c     libc_rwlock_wrlock dup @asulock @aculock
1739 @c     nl_init_alt_digit dup @ascuheap @acsmem
1740 @c     libc_rwlock_unlock dup @aculock
1741 @c    get_number dup ok
1742 @c   day_of_the_week ok
1743 @c   day_of_the_year ok
1744 The @code{strptime} function parses the input string @var{s} according
1745 to the format string @var{fmt} and stores its results in the
1746 structure @var{tp}.
1748 The input string could be generated by a @code{strftime} call or
1749 obtained any other way.  It does not need to be in a human-recognizable
1750 format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even
1751 though it is ambiguous without context.  As long as the format string
1752 @var{fmt} matches the input string the function will succeed.
1754 The user has to make sure, though, that the input can be parsed in a
1755 unambiguous way.  The string @code{"1999112"} can be parsed using the
1756 format @code{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2.  It
1757 is necessary to add appropriate separators to reliably get results.
1759 The format string consists of the same components as the format string
1760 of the @code{strftime} function.  The only difference is that the flags
1761 @code{_}, @code{-}, @code{0}, and @code{^} are not allowed.
1762 @comment Is this really the intention?  --drepper
1763 Several of the distinct formats of @code{strftime} do the same work in
1764 @code{strptime} since differences like case of the input do not matter.
1765 For reasons of symmetry all formats are supported, though.
1767 The modifiers @code{E} and @code{O} are also allowed everywhere the
1768 @code{strftime} function allows them.
1770 The formats are:
1772 @table @code
1773 @item %a
1774 @itemx %A
1775 The weekday name according to the current locale, in abbreviated form or
1776 the full name.
1778 @item %b
1779 @itemx %B
1780 @itemx %h
1781 The month name according to the current locale, in abbreviated form or
1782 the full name.
1784 @item %c
1785 The date and time representation for the current locale.
1787 @item %Ec
1788 Like @code{%c} but the locale's alternative date and time format is used.
1790 @item %C
1791 The century of the year.
1793 It makes sense to use this format only if the format string also
1794 contains the @code{%y} format.
1796 @item %EC
1797 The locale's representation of the period.
1799 Unlike @code{%C} it sometimes makes sense to use this format since some
1800 cultures represent years relative to the beginning of eras instead of
1801 using the Gregorian years.
1803 @item %d
1804 @item %e
1805 The day of the month as a decimal number (range @code{1} through @code{31}).
1806 Leading zeroes are permitted but not required.
1808 @item %Od
1809 @itemx %Oe
1810 Same as @code{%d} but using the locale's alternative numeric symbols.
1812 Leading zeroes are permitted but not required.
1814 @item %D
1815 Equivalent to @code{%m/%d/%y}.
1817 @item %F
1818 Equivalent to @code{%Y-%m-%d}, which is the @w{ISO 8601} date
1819 format.
1821 This is a GNU extension following an @w{ISO C99} extension to
1822 @code{strftime}.
1824 @item %g
1825 The year corresponding to the ISO week number, but without the century
1826 (range @code{00} through @code{99}).
1828 @emph{Note:} Currently, this is not fully implemented.  The format is
1829 recognized, input is consumed but no field in @var{tm} is set.
1831 This format is a GNU extension following a GNU extension of @code{strftime}.
1833 @item %G
1834 The year corresponding to the ISO week number.
1836 @emph{Note:} Currently, this is not fully implemented.  The format is
1837 recognized, input is consumed but no field in @var{tm} is set.
1839 This format is a GNU extension following a GNU extension of @code{strftime}.
1841 @item %H
1842 @itemx %k
1843 The hour as a decimal number, using a 24-hour clock (range @code{00} through
1844 @code{23}).
1846 @code{%k} is a GNU extension following a GNU extension of @code{strftime}.
1848 @item %OH
1849 Same as @code{%H} but using the locale's alternative numeric symbols.
1851 @item %I
1852 @itemx %l
1853 The hour as a decimal number, using a 12-hour clock (range @code{01} through
1854 @code{12}).
1856 @code{%l} is a GNU extension following a GNU extension of @code{strftime}.
1858 @item %OI
1859 Same as @code{%I} but using the locale's alternative numeric symbols.
1861 @item %j
1862 The day of the year as a decimal number (range @code{1} through @code{366}).
1864 Leading zeroes are permitted but not required.
1866 @item %m
1867 The month as a decimal number (range @code{1} through @code{12}).
1869 Leading zeroes are permitted but not required.
1871 @item %Om
1872 Same as @code{%m} but using the locale's alternative numeric symbols.
1874 @item %M
1875 The minute as a decimal number (range @code{0} through @code{59}).
1877 Leading zeroes are permitted but not required.
1879 @item %OM
1880 Same as @code{%M} but using the locale's alternative numeric symbols.
1882 @item %n
1883 @itemx %t
1884 Matches any white space.
1886 @item %p
1887 @item %P
1888 The locale-dependent equivalent to @samp{AM} or @samp{PM}.
1890 This format is not useful unless @code{%I} or @code{%l} is also used.
1891 Another complication is that the locale might not define these values at
1892 all and therefore the conversion fails.
1894 @code{%P} is a GNU extension following a GNU extension to @code{strftime}.
1896 @item %r
1897 The complete time using the AM/PM format of the current locale.
1899 A complication is that the locale might not define this format at all
1900 and therefore the conversion fails.
1902 @item %R
1903 The hour and minute in decimal numbers using the format @code{%H:%M}.
1905 @code{%R} is a GNU extension following a GNU extension to @code{strftime}.
1907 @item %s
1908 The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
1909 Leap seconds are not counted unless leap second support is available.
1911 @code{%s} is a GNU extension following a GNU extension to @code{strftime}.
1913 @item %S
1914 The seconds as a decimal number (range @code{0} through @code{60}).
1916 Leading zeroes are permitted but not required.
1918 @strong{NB:} The Unix specification says the upper bound on this value
1919 is @code{61}, a result of a decision to allow double leap seconds.  You
1920 will not see the value @code{61} because no minute has more than one
1921 leap second, but the myth persists.
1923 @item %OS
1924 Same as @code{%S} but using the locale's alternative numeric symbols.
1926 @item %T
1927 Equivalent to the use of @code{%H:%M:%S} in this place.
1929 @item %u
1930 The day of the week as a decimal number (range @code{1} through
1931 @code{7}), Monday being @code{1}.
1933 Leading zeroes are permitted but not required.
1935 @emph{Note:} Currently, this is not fully implemented.  The format is
1936 recognized, input is consumed but no field in @var{tm} is set.
1938 @item %U
1939 The week number of the current year as a decimal number (range @code{0}
1940 through @code{53}).
1942 Leading zeroes are permitted but not required.
1944 @item %OU
1945 Same as @code{%U} but using the locale's alternative numeric symbols.
1947 @item %V
1948 The @w{ISO 8601:1988} week number as a decimal number (range @code{1}
1949 through @code{53}).
1951 Leading zeroes are permitted but not required.
1953 @emph{Note:} Currently, this is not fully implemented.  The format is
1954 recognized, input is consumed but no field in @var{tm} is set.
1956 @item %w
1957 The day of the week as a decimal number (range @code{0} through
1958 @code{6}), Sunday being @code{0}.
1960 Leading zeroes are permitted but not required.
1962 @emph{Note:} Currently, this is not fully implemented.  The format is
1963 recognized, input is consumed but no field in @var{tm} is set.
1965 @item %Ow
1966 Same as @code{%w} but using the locale's alternative numeric symbols.
1968 @item %W
1969 The week number of the current year as a decimal number (range @code{0}
1970 through @code{53}).
1972 Leading zeroes are permitted but not required.
1974 @emph{Note:} Currently, this is not fully implemented.  The format is
1975 recognized, input is consumed but no field in @var{tm} is set.
1977 @item %OW
1978 Same as @code{%W} but using the locale's alternative numeric symbols.
1980 @item %x
1981 The date using the locale's date format.
1983 @item %Ex
1984 Like @code{%x} but the locale's alternative data representation is used.
1986 @item %X
1987 The time using the locale's time format.
1989 @item %EX
1990 Like @code{%X} but the locale's alternative time representation is used.
1992 @item %y
1993 The year without a century as a decimal number (range @code{0} through
1994 @code{99}).
1996 Leading zeroes are permitted but not required.
1998 Note that it is questionable to use this format without
1999 the @code{%C} format.  The @code{strptime} function does regard input
2000 values in the range @math{68} to @math{99} as the years @math{1969} to
2001 @math{1999} and the values @math{0} to @math{68} as the years
2002 @math{2000} to @math{2068}.  But maybe this heuristic fails for some
2003 input data.
2005 Therefore it is best to avoid @code{%y} completely and use @code{%Y}
2006 instead.
2008 @item %Ey
2009 The offset from @code{%EC} in the locale's alternative representation.
2011 @item %Oy
2012 The offset of the year (from @code{%C}) using the locale's alternative
2013 numeric symbols.
2015 @item %Y
2016 The year as a decimal number, using the Gregorian calendar.
2018 @item %EY
2019 The full alternative year representation.
2021 @item %z
2022 The offset from GMT in @w{ISO 8601}/RFC822 format.
2024 @item %Z
2025 The timezone name.
2027 @emph{Note:} Currently, this is not fully implemented.  The format is
2028 recognized, input is consumed but no field in @var{tm} is set.
2030 @item %%
2031 A literal @samp{%} character.
2032 @end table
2034 All other characters in the format string must have a matching character
2035 in the input string.  Exceptions are white spaces in the input string
2036 which can match zero or more whitespace characters in the format string.
2038 @strong{Portability Note:} The XPG standard advises applications to use
2039 at least one whitespace character (as specified by @code{isspace}) or
2040 other non-alphanumeric characters between any two conversion
2041 specifications.  @Theglibc{} does not have this limitation but
2042 other libraries might have trouble parsing formats like
2043 @code{"%d%m%Y%H%M%S"}.
2045 The @code{strptime} function processes the input string from right to
2046 left.  Each of the three possible input elements (white space, literal,
2047 or format) are handled one after the other.  If the input cannot be
2048 matched to the format string the function stops.  The remainder of the
2049 format and input strings are not processed.
2051 The function returns a pointer to the first character it was unable to
2052 process.  If the input string contains more characters than required by
2053 the format string the return value points right after the last consumed
2054 input character.  If the whole input string is consumed the return value
2055 points to the @code{NULL} byte at the end of the string.  If an error
2056 occurs, i.e., @code{strptime} fails to match all of the format string,
2057 the function returns @code{NULL}.
2058 @end deftypefun
2060 The specification of the function in the XPG standard is rather vague,
2061 leaving out a few important pieces of information.  Most importantly, it
2062 does not specify what happens to those elements of @var{tm} which are
2063 not directly initialized by the different formats.  The
2064 implementations on different Unix systems vary here.
2066 The @glibcadj{} implementation does not touch those fields which are not
2067 directly initialized.  Exceptions are the @code{tm_wday} and
2068 @code{tm_yday} elements, which are recomputed if any of the year, month,
2069 or date elements changed.  This has two implications:
2071 @itemize @bullet
2072 @item
2073 Before calling the @code{strptime} function for a new input string, you
2074 should prepare the @var{tm} structure you pass.  Normally this will mean
2075 initializing all values to zero.  Alternatively, you can set all
2076 fields to values like @code{INT_MAX}, allowing you to determine which
2077 elements were set by the function call.  Zero does not work here since
2078 it is a valid value for many of the fields.
2080 Careful initialization is necessary if you want to find out whether a
2081 certain field in @var{tm} was initialized by the function call.
2083 @item
2084 You can construct a @code{struct tm} value with several consecutive
2085 @code{strptime} calls.  A useful application of this is e.g. the parsing
2086 of two separate strings, one containing date information and the other
2087 time information.  By parsing one after the other without clearing the
2088 structure in-between, you can construct a complete broken-down time.
2089 @end itemize
2091 The following example shows a function which parses a string which
2092 contains the date information in either US style or @w{ISO 8601} form:
2094 @smallexample
2095 const char *
2096 parse_date (const char *input, struct tm *tm)
2098   const char *cp;
2100   /* @r{First clear the result structure.}  */
2101   memset (tm, '\0', sizeof (*tm));
2103   /* @r{Try the ISO format first.}  */
2104   cp = strptime (input, "%F", tm);
2105   if (cp == NULL)
2106     @{
2107       /* @r{Does not match.  Try the US form.}  */
2108       cp = strptime (input, "%D", tm);
2109     @}
2111   return cp;
2113 @end smallexample
2115 @node General Time String Parsing
2116 @subsubsection A More User-friendly Way to Parse Times and Dates
2118 The Unix standard defines another function for parsing date strings.
2119 The interface is weird, but if the function happens to suit your
2120 application it is just fine.  It is problematic to use this function
2121 in multi-threaded programs or libraries, since it returns a pointer to
2122 a static variable, and uses a global variable and global state (an
2123 environment variable).
2125 @defvar getdate_err
2126 @standards{Unix98, time.h}
2127 This variable of type @code{int} contains the error code of the last
2128 unsuccessful call to @code{getdate}.  Defined values are:
2130 @table @math
2131 @item 1
2132 The environment variable @code{DATEMSK} is not defined or null.
2133 @item 2
2134 The template file denoted by the @code{DATEMSK} environment variable
2135 cannot be opened.
2136 @item 3
2137 Information about the template file cannot retrieved.
2138 @item 4
2139 The template file is not a regular file.
2140 @item 5
2141 An I/O error occurred while reading the template file.
2142 @item 6
2143 Not enough memory available to execute the function.
2144 @item 7
2145 The template file contains no matching template.
2146 @item 8
2147 The input date is invalid, but would match a template otherwise.  This
2148 includes dates like February 31st, and dates which cannot be represented
2149 in a @code{time_t} variable.
2150 @end table
2151 @end defvar
2153 @deftypefun {struct tm *} getdate (const char *@var{string})
2154 @standards{Unix98, time.h}
2155 @safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2156 @c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2157 @c  getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2158 The interface to @code{getdate} is the simplest possible for a function
2159 to parse a string and return the value.  @var{string} is the input
2160 string and the result is returned in a statically-allocated variable.
2162 The details about how the string is processed are hidden from the user.
2163 In fact, they can be outside the control of the program.  Which formats
2164 are recognized is controlled by the file named by the environment
2165 variable @code{DATEMSK}.  This file should contain
2166 lines of valid format strings which could be passed to @code{strptime}.
2168 The @code{getdate} function reads these format strings one after the
2169 other and tries to match the input string.  The first line which
2170 completely matches the input string is used.
2172 Elements not initialized through the format string retain the values
2173 present at the time of the @code{getdate} function call.
2175 The formats recognized by @code{getdate} are the same as for
2176 @code{strptime}.  See above for an explanation.  There are only a few
2177 extensions to the @code{strptime} behavior:
2179 @itemize @bullet
2180 @item
2181 If the @code{%Z} format is given the broken-down time is based on the
2182 current time of the timezone matched, not of the current timezone of the
2183 runtime environment.
2185 @emph{Note}: This is not implemented (currently).  The problem is that
2186 timezone names are not unique.  If a fixed timezone is assumed for a
2187 given string (say @code{EST} meaning US East Coast time), then uses for
2188 countries other than the USA will fail.  So far we have found no good
2189 solution to this.
2191 @item
2192 If only the weekday is specified the selected day depends on the current
2193 date.  If the current weekday is greater than or equal to the @code{tm_wday}
2194 value the current week's day is chosen, otherwise the day next week is chosen.
2196 @item
2197 A similar heuristic is used when only the month is given and not the
2198 year.  If the month is greater than or equal to the current month, then
2199 the current year is used.  Otherwise it wraps to next year.  The first
2200 day of the month is assumed if one is not explicitly specified.
2202 @item
2203 The current hour, minute, and second are used if the appropriate value is
2204 not set through the format.
2206 @item
2207 If no date is given tomorrow's date is used if the time is
2208 smaller than the current time.  Otherwise today's date is taken.
2209 @end itemize
2211 It should be noted that the format in the template file need not only
2212 contain format elements.  The following is a list of possible format
2213 strings (taken from the Unix standard):
2215 @smallexample
2217 %A %B %d, %Y %H:%M:%S
2220 %m/%d/%y %I %p
2221 %d,%m,%Y %H:%M
2222 at %A the %dst of %B in %Y
2223 run job at %I %p,%B %dnd
2224 %A den %d. %B %Y %H.%M Uhr
2225 @end smallexample
2227 As you can see, the template list can contain very specific strings like
2228 @code{run job at %I %p,%B %dnd}.  Using the above list of templates and
2229 assuming the current time is Mon Sep 22 12:19:47 EDT 1986, we can obtain the
2230 following results for the given input.
2232 @multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
2233 @item        Input @tab     Match @tab Result
2234 @item        Mon @tab       %a @tab    Mon Sep 22 12:19:47 EDT 1986
2235 @item        Sun @tab       %a @tab    Sun Sep 28 12:19:47 EDT 1986
2236 @item        Fri @tab       %a @tab    Fri Sep 26 12:19:47 EDT 1986
2237 @item        September @tab %B @tab    Mon Sep 1 12:19:47 EDT 1986
2238 @item        January @tab   %B @tab    Thu Jan 1 12:19:47 EST 1987
2239 @item        December @tab  %B @tab    Mon Dec 1 12:19:47 EST 1986
2240 @item        Sep Mon @tab   %b %a @tab Mon Sep 1 12:19:47 EDT 1986
2241 @item        Jan Fri @tab   %b %a @tab Fri Jan 2 12:19:47 EST 1987
2242 @item        Dec Mon @tab   %b %a @tab Mon Dec 1 12:19:47 EST 1986
2243 @item        Jan Wed 1989 @tab  %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989
2244 @item        Fri 9 @tab     %a %H @tab Fri Sep 26 09:00:00 EDT 1986
2245 @item        Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987
2246 @item        10:30 @tab     %H:%M @tab Tue Sep 23 10:30:00 EDT 1986
2247 @item        13:30 @tab     %H:%M @tab Mon Sep 22 13:30:00 EDT 1986
2248 @end multitable
2250 The return value of the function is a pointer to a static variable of
2251 type @w{@code{struct tm}}, or a null pointer if an error occurred.  The
2252 result is only valid until the next @code{getdate} call, making this
2253 function unusable in multi-threaded applications.
2255 The @code{errno} variable is @emph{not} changed.  Error conditions are
2256 stored in the global variable @code{getdate_err}.  See the
2257 description above for a list of the possible error values.
2259 @emph{Warning:} The @code{getdate} function should @emph{never} be
2260 used in SUID-programs.  The reason is obvious: using the
2261 @code{DATEMSK} environment variable you can get the function to open
2262 any arbitrary file and chances are high that with some bogus input
2263 (such as a binary file) the program will crash.
2264 @end deftypefun
2266 @deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp})
2267 @standards{GNU, time.h}
2268 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2269 @c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2270 @c  getenv dup @mtsenv
2271 @c  stat64 dup ok
2272 @c  access dup ok
2273 @c  fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
2274 @c  fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive]
2275 @c  isspace dup @mtslocale
2276 @c  strlen dup ok
2277 @c  malloc dup @ascuheap @acsmem
2278 @c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
2279 @c  memcpy dup ok
2280 @c  getline dup @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt, exclusive]
2281 @c  strptime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2282 @c  feof_unlocked dup ok
2283 @c  free dup @ascuheap @acsmem
2284 @c  ferror_unlocked dup dup ok
2285 @c  time dup ok
2286 @c  localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2287 @c  first_wday @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2288 @c   memset dup ok
2289 @c   mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2290 @c  check_mday ok
2291 @c  mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2292 The @code{getdate_r} function is the reentrant counterpart of
2293 @code{getdate}.  It does not use the global variable @code{getdate_err}
2294 to signal an error, but instead returns an error code.  The same error
2295 codes as described in the @code{getdate_err} documentation above are
2296 used, with 0 meaning success.
2298 Moreover, @code{getdate_r} stores the broken-down time in the variable
2299 of type @code{struct tm} pointed to by the second argument, rather than
2300 in a static variable.
2302 This function is not defined in the Unix standard.  Nevertheless it is
2303 available on some other Unix systems as well.
2305 The warning against using @code{getdate} in SUID-programs applies to
2306 @code{getdate_r} as well.
2307 @end deftypefun
2309 @node TZ Variable
2310 @subsection Specifying the Time Zone with @code{TZ}
2312 In POSIX systems, a user can specify the time zone by means of the
2313 @code{TZ} environment variable.  For information about how to set
2314 environment variables, see @ref{Environment Variables}.  The functions
2315 for accessing the time zone are declared in @file{time.h}.
2316 @pindex time.h
2317 @cindex time zone
2319 You should not normally need to set @code{TZ}.  If the system is
2320 configured properly, the default time zone will be correct.  You might
2321 set @code{TZ} if you are using a computer over a network from a
2322 different time zone, and would like times reported to you in the time
2323 zone local to you, rather than what is local to the computer.
2325 In POSIX.1 systems the value of the @code{TZ} variable can be in one of
2326 three formats.  With @theglibc{}, the most common format is the
2327 last one, which can specify a selection from a large database of time
2328 zone information for many regions of the world.  The first two formats
2329 are used to describe the time zone information directly, which is both
2330 more cumbersome and less precise.  But the POSIX.1 standard only
2331 specifies the details of the first two formats, so it is good to be
2332 familiar with them in case you come across a POSIX.1 system that doesn't
2333 support a time zone information database.
2335 The first format is used when there is no Daylight Saving Time (or
2336 summer time) in the local time zone:
2338 @smallexample
2339 @r{@var{std} @var{offset}}
2340 @end smallexample
2342 The @var{std} string specifies the name of the time zone.  It must be
2343 three or more characters long and must not contain a leading colon,
2344 embedded digits, commas, nor plus and minus signs.  There is no space
2345 character separating the time zone name from the @var{offset}, so these
2346 restrictions are necessary to parse the specification correctly.
2348 The @var{offset} specifies the time value you must add to the local time
2349 to get a Coordinated Universal Time value.  It has syntax like
2350 [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  This
2351 is positive if the local time zone is west of the Prime Meridian and
2352 negative if it is east.  The hour must be between @code{0} and
2353 @code{24}, and the minute and seconds between @code{0} and @code{59}.
2355 For example, here is how we would specify Eastern Standard Time, but
2356 without any Daylight Saving Time alternative:
2358 @smallexample
2359 EST+5
2360 @end smallexample
2362 The second format is used when there is Daylight Saving Time:
2364 @smallexample
2365 @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
2366 @end smallexample
2368 The initial @var{std} and @var{offset} specify the standard time zone, as
2369 described above.  The @var{dst} string and @var{offset} specify the name
2370 and offset for the corresponding Daylight Saving Time zone; if the
2371 @var{offset} is omitted, it defaults to one hour ahead of standard time.
2373 The remainder of the specification describes when Daylight Saving Time is
2374 in effect.  The @var{start} field is when Daylight Saving Time goes into
2375 effect and the @var{end} field is when the change is made back to standard
2376 time.  The following formats are recognized for these fields:
2378 @table @code
2379 @item J@var{n}
2380 This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
2381 February 29 is never counted, even in leap years.
2383 @item @var{n}
2384 This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
2385 February 29 is counted in leap years.
2387 @item M@var{m}.@var{w}.@var{d}
2388 This specifies day @var{d} of week @var{w} of month @var{m}.  The day
2389 @var{d} must be between @code{0} (Sunday) and @code{6}.  The week
2390 @var{w} must be between @code{1} and @code{5}; week @code{1} is the
2391 first week in which day @var{d} occurs, and week @code{5} specifies the
2392 @emph{last} @var{d} day in the month.  The month @var{m} should be
2393 between @code{1} and @code{12}.
2394 @end table
2396 The @var{time} fields specify when, in the local time currently in
2397 effect, the change to the other time occurs.  If omitted, the default is
2398 @code{02:00:00}.  The hours part of the time fields can range from
2399 @minus{}167 through 167; this is an extension to POSIX.1, which allows
2400 only the range 0 through 24.
2402 Here are some example @code{TZ} values, including the appropriate
2403 Daylight Saving Time and its dates of applicability.  In North
2404 American Eastern Standard Time (EST) and Eastern Daylight Time (EDT),
2405 the normal offset from UTC is 5 hours; since this is
2406 west of the prime meridian, the sign is positive.  Summer time begins on
2407 March's second Sunday at 2:00am, and ends on November's first Sunday
2408 at 2:00am.
2410 @smallexample
2411 EST+5EDT,M3.2.0/2,M11.1.0/2
2412 @end smallexample
2414 Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours
2415 ahead of the prime meridian in winter, springing forward an hour on
2416 March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or
2417 after March 23), and falling back on October's last Sunday at 02:00.
2419 @smallexample
2420 IST-2IDT,M3.4.4/26,M10.5.0
2421 @end smallexample
2423 Western Argentina Summer Time (WARST) is 3 hours behind the prime
2424 meridian all year.  There is a dummy fall-back transition on December
2425 31 at 25:00 daylight saving time (i.e., 24:00 standard time,
2426 equivalent to January 1 at 00:00 standard time), and a simultaneous
2427 spring-forward transition on January 1 at 00:00 standard time, so
2428 daylight saving time is in effect all year and the initial @code{WART}
2429 is a placeholder.
2431 @smallexample
2432 WART4WARST,J1/0,J365/25
2433 @end smallexample
2435 Western Greenland Time (WGT) and Western Greenland Summer Time (WGST)
2436 are 3 hours behind UTC in the winter.  Its clocks follow the European
2437 Union rules of springing forward by one hour on March's last Sunday at
2438 01:00 UTC (@minus{}02:00 local time) and falling back on October's
2439 last Sunday at 01:00 UTC (@minus{}01:00 local time).
2441 @smallexample
2442 WGT3WGST,M3.5.0/-2,M10.5.0/-1
2443 @end smallexample
2445 The schedule of Daylight Saving Time in any particular jurisdiction has
2446 changed over the years.  To be strictly correct, the conversion of dates
2447 and times in the past should be based on the schedule that was in effect
2448 then.  However, this format has no facilities to let you specify how the
2449 schedule has changed from year to year.  The most you can do is specify
2450 one particular schedule---usually the present day schedule---and this is
2451 used to convert any date, no matter when.  For precise time zone
2452 specifications, it is best to use the time zone information database
2453 (see below).
2455 The third format looks like this:
2457 @smallexample
2458 :@var{characters}
2459 @end smallexample
2461 Each operating system interprets this format differently; in
2462 @theglibc{}, @var{characters} is the name of a file which describes the time
2463 zone.
2465 @pindex /etc/localtime
2466 @pindex localtime
2467 If the @code{TZ} environment variable does not have a value, the
2468 operation chooses a time zone by default.  In @theglibc{}, the
2469 default time zone is like the specification @samp{TZ=:/etc/localtime}
2470 (or @samp{TZ=:/usr/local/etc/localtime}, depending on how @theglibc{}
2471 was configured; @pxref{Installation}).  Other C libraries use their own
2472 rule for choosing the default time zone, so there is little we can say
2473 about them.
2475 @cindex time zone database
2476 @pindex /usr/share/zoneinfo
2477 @pindex zoneinfo
2478 If @var{characters} begins with a slash, it is an absolute file name;
2479 otherwise the library looks for the file
2480 @w{@file{/usr/share/zoneinfo/@var{characters}}}.  The @file{zoneinfo}
2481 directory contains data files describing local time zones in many
2482 different parts of the world.  The names represent major cities, with
2483 subdirectories for geographical areas; for example,
2484 @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
2485 These data files are installed by the system administrator, who also
2486 sets @file{/etc/localtime} to point to the data file for the local time
2487 zone.  The files typically come from the @url{http://www.iana.org/time-zones,
2488 Time Zone Database} of time zone and daylight saving time
2489 information for most regions of the world, which is maintained by a
2490 community of volunteers and put in the public domain.
2492 @node Time Zone Functions
2493 @subsection Functions and Variables for Time Zones
2495 @deftypevar {char *} tzname [2]
2496 @standards{POSIX.1, time.h}
2497 The array @code{tzname} contains two strings, which are the standard
2498 names of the pair of time zones (standard and Daylight
2499 Saving) that the user has selected.  @code{tzname[0]} is the name of
2500 the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
2501 is the name for the time zone when Daylight Saving Time is in use (for
2502 example, @code{"EDT"}).  These correspond to the @var{std} and @var{dst}
2503 strings (respectively) from the @code{TZ} environment variable.  If
2504 Daylight Saving Time is never used, @code{tzname[1]} is the empty string.
2506 The @code{tzname} array is initialized from the @code{TZ} environment
2507 variable whenever @code{tzset}, @code{ctime}, @code{strftime},
2508 @code{mktime}, or @code{localtime} is called.  If multiple abbreviations
2509 have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War
2510 Time and Eastern Daylight Time), the array contains the most recent
2511 abbreviation.
2513 The @code{tzname} array is required for POSIX.1 compatibility, but in
2514 GNU programs it is better to use the @code{tm_zone} member of the
2515 broken-down time structure, since @code{tm_zone} reports the correct
2516 abbreviation even when it is not the latest one.
2518 Though the strings are declared as @code{char *} the user must refrain
2519 from modifying these strings.  Modifying the strings will almost certainly
2520 lead to trouble.
2522 @end deftypevar
2524 @deftypefun void tzset (void)
2525 @standards{POSIX.1, time.h}
2526 @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
2527 @c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2528 @c  libc_lock_lock dup @asulock @aculock
2529 @c  tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
2530 @c  libc_lock_unlock dup @aculock
2531 The @code{tzset} function initializes the @code{tzname} variable from
2532 the value of the @code{TZ} environment variable.  It is not usually
2533 necessary for your program to call this function, because it is called
2534 automatically when you use the other time conversion functions that
2535 depend on the time zone.
2536 @end deftypefun
2538 The following variables are defined for compatibility with System V
2539 Unix.  Like @code{tzname}, these variables are set by calling
2540 @code{tzset} or the other time conversion functions.
2542 @deftypevar {long int} timezone
2543 @standards{SVID, time.h}
2544 This contains the difference between UTC and the latest local standard
2545 time, in seconds west of UTC.  For example, in the U.S. Eastern time
2546 zone, the value is @code{5*60*60}.  Unlike the @code{tm_gmtoff} member
2547 of the broken-down time structure, this value is not adjusted for
2548 daylight saving, and its sign is reversed.  In GNU programs it is better
2549 to use @code{tm_gmtoff}, since it contains the correct offset even when
2550 it is not the latest one.
2551 @end deftypevar
2553 @deftypevar int daylight
2554 @standards{SVID, time.h}
2555 This variable has a nonzero value if Daylight Saving Time rules apply.
2556 A nonzero value does not necessarily mean that Daylight Saving Time is
2557 now in effect; it means only that Daylight Saving Time is sometimes in
2558 effect.
2559 @end deftypevar
2561 @node Time Functions Example
2562 @subsection Time Functions Example
2564 Here is an example program showing the use of some of the calendar time
2565 functions.
2567 @smallexample
2568 @include strftim.c.texi
2569 @end smallexample
2571 It produces output like this:
2573 @smallexample
2574 Wed Jul 31 13:02:36 1991
2575 Today is Wednesday, July 31.
2576 The time is 01:02 PM.
2577 @end smallexample
2580 @node Setting an Alarm
2581 @section Setting an Alarm
2583 The @code{alarm} and @code{setitimer} functions provide a mechanism for a
2584 process to interrupt itself in the future.  They do this by setting a
2585 timer; when the timer expires, the process receives a signal.
2587 @cindex setting an alarm
2588 @cindex interval timer, setting
2589 @cindex alarms, setting
2590 @cindex timers, setting
2591 Each process has three independent interval timers available:
2593 @itemize @bullet
2594 @item
2595 A real-time timer that counts elapsed time.  This timer sends a
2596 @code{SIGALRM} signal to the process when it expires.
2597 @cindex real-time timer
2598 @cindex timer, real-time
2600 @item
2601 A virtual timer that counts processor time used by the process.  This timer
2602 sends a @code{SIGVTALRM} signal to the process when it expires.
2603 @cindex virtual timer
2604 @cindex timer, virtual
2606 @item
2607 A profiling timer that counts both processor time used by the process,
2608 and processor time spent in system calls on behalf of the process.  This
2609 timer sends a @code{SIGPROF} signal to the process when it expires.
2610 @cindex profiling timer
2611 @cindex timer, profiling
2613 This timer is useful for profiling in interpreters.  The interval timer
2614 mechanism does not have the fine granularity necessary for profiling
2615 native code.
2616 @c @xref{profil} !!!
2617 @end itemize
2619 You can only have one timer of each kind set at any given time.  If you
2620 set a timer that has not yet expired, that timer is simply reset to the
2621 new value.
2623 You should establish a handler for the appropriate alarm signal using
2624 @code{signal} or @code{sigaction} before issuing a call to
2625 @code{setitimer} or @code{alarm}.  Otherwise, an unusual chain of events
2626 could cause the timer to expire before your program establishes the
2627 handler.  In this case it would be terminated, since termination is the
2628 default action for the alarm signals.  @xref{Signal Handling}.
2630 To be able to use the alarm function to interrupt a system call which
2631 might block otherwise indefinitely it is important to @emph{not} set the
2632 @code{SA_RESTART} flag when registering the signal handler using
2633 @code{sigaction}.  When not using @code{sigaction} things get even
2634 uglier: the @code{signal} function has fixed semantics with respect
2635 to restarts.  The BSD semantics for this function is to set the flag.
2636 Therefore, if @code{sigaction} for whatever reason cannot be used, it is
2637 necessary to use @code{sysv_signal} and not @code{signal}.
2639 The @code{setitimer} function is the primary means for setting an alarm.
2640 This facility is declared in the header file @file{sys/time.h}.  The
2641 @code{alarm} function, declared in @file{unistd.h}, provides a somewhat
2642 simpler interface for setting the real-time timer.
2643 @pindex unistd.h
2644 @pindex sys/time.h
2646 @deftp {Data Type} {struct itimerval}
2647 @standards{BSD, sys/time.h}
2648 This structure is used to specify when a timer should expire.  It contains
2649 the following members:
2650 @table @code
2651 @item struct timeval it_interval
2652 This is the period between successive timer interrupts.  If zero, the
2653 alarm will only be sent once.
2655 @item struct timeval it_value
2656 This is the period between now and the first timer interrupt.  If zero,
2657 the alarm is disabled.
2658 @end table
2660 The @code{struct timeval} data type is described in @ref{Elapsed Time}.
2661 @end deftp
2663 @deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old})
2664 @standards{BSD, sys/time.h}
2665 @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
2666 @c This function is marked with @mtstimer because the same set of timers
2667 @c is shared by all threads of a process, so calling it in one thread
2668 @c may interfere with timers set by another thread.  This interference
2669 @c is not regarded as destructive, because the interface specification
2670 @c makes this overriding while returning the previous value the expected
2671 @c behavior, and the kernel will serialize concurrent calls so that the
2672 @c last one prevails, with each call getting the timer information from
2673 @c the timer installed by the previous call in that serialization.
2674 The @code{setitimer} function sets the timer specified by @var{which}
2675 according to @var{new}.  The @var{which} argument can have a value of
2676 @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
2678 If @var{old} is not a null pointer, @code{setitimer} returns information
2679 about any previous unexpired timer of the same kind in the structure it
2680 points to.
2682 The return value is @code{0} on success and @code{-1} on failure.  The
2683 following @code{errno} error conditions are defined for this function:
2685 @table @code
2686 @item EINVAL
2687 The timer period is too large.
2688 @end table
2689 @end deftypefun
2691 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
2692 @standards{BSD, sys/time.h}
2693 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2694 The @code{getitimer} function stores information about the timer specified
2695 by @var{which} in the structure pointed at by @var{old}.
2697 The return value and error conditions are the same as for @code{setitimer}.
2698 @end deftypefun
2700 @vtable @code
2701 @item ITIMER_REAL
2702 @standards{BSD, sys/time.h}
2703 This constant can be used as the @var{which} argument to the
2704 @code{setitimer} and @code{getitimer} functions to specify the real-time
2705 timer.
2707 @item ITIMER_VIRTUAL
2708 @standards{BSD, sys/time.h}
2709 This constant can be used as the @var{which} argument to the
2710 @code{setitimer} and @code{getitimer} functions to specify the virtual
2711 timer.
2713 @item ITIMER_PROF
2714 @standards{BSD, sys/time.h}
2715 This constant can be used as the @var{which} argument to the
2716 @code{setitimer} and @code{getitimer} functions to specify the profiling
2717 timer.
2718 @end vtable
2720 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
2721 @standards{POSIX.1, unistd.h}
2722 @safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
2723 @c Wrapper for setitimer.
2724 The @code{alarm} function sets the real-time timer to expire in
2725 @var{seconds} seconds.  If you want to cancel any existing alarm, you
2726 can do this by calling @code{alarm} with a @var{seconds} argument of
2727 zero.
2729 The return value indicates how many seconds remain before the previous
2730 alarm would have been sent.  If there was no previous alarm, @code{alarm}
2731 returns zero.
2732 @end deftypefun
2734 The @code{alarm} function could be defined in terms of @code{setitimer}
2735 like this:
2737 @smallexample
2738 unsigned int
2739 alarm (unsigned int seconds)
2741   struct itimerval old, new;
2742   new.it_interval.tv_usec = 0;
2743   new.it_interval.tv_sec = 0;
2744   new.it_value.tv_usec = 0;
2745   new.it_value.tv_sec = (long int) seconds;
2746   if (setitimer (ITIMER_REAL, &new, &old) < 0)
2747     return 0;
2748   else
2749     return old.it_value.tv_sec;
2751 @end smallexample
2753 There is an example showing the use of the @code{alarm} function in
2754 @ref{Handler Returns}.
2756 If you simply want your process to wait for a given number of seconds,
2757 you should use the @code{sleep} function.  @xref{Sleeping}.
2759 You shouldn't count on the signal arriving precisely when the timer
2760 expires.  In a multiprocessing environment there is typically some
2761 amount of delay involved.
2763 @strong{Portability Note:} The @code{setitimer} and @code{getitimer}
2764 functions are derived from BSD Unix, while the @code{alarm} function is
2765 specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
2766 @code{alarm}, but @code{alarm} is more widely used.
2768 @node Sleeping
2769 @section Sleeping
2771 The function @code{sleep} gives a simple way to make the program wait
2772 for a short interval.  If your program doesn't use signals (except to
2773 terminate), then you can expect @code{sleep} to wait reliably throughout
2774 the specified interval.  Otherwise, @code{sleep} can return sooner if a
2775 signal arrives; if you want to wait for a given interval regardless of
2776 signals, use @code{select} (@pxref{Waiting for I/O}) and don't specify
2777 any descriptors to wait for.
2778 @c !!! select can get EINTR; using SA_RESTART makes sleep win too.
2780 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
2781 @standards{POSIX.1, unistd.h}
2782 @safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}}
2783 @c On Mach, it uses ports and calls time.  On generic posix, it calls
2784 @c nanosleep.  On Linux, it temporarily blocks SIGCHLD, which is MT- and
2785 @c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!).
2786 The @code{sleep} function waits for @var{seconds} seconds or until a signal
2787 is delivered, whichever happens first.
2789 If @code{sleep} returns because the requested interval is over,
2790 it returns a value of zero.  If it returns because of delivery of a
2791 signal, its return value is the remaining time in the sleep interval.
2793 The @code{sleep} function is declared in @file{unistd.h}.
2794 @end deftypefun
2796 Resist the temptation to implement a sleep for a fixed amount of time by
2797 using the return value of @code{sleep}, when nonzero, to call
2798 @code{sleep} again.  This will work with a certain amount of accuracy as
2799 long as signals arrive infrequently.  But each signal can cause the
2800 eventual wakeup time to be off by an additional second or so.  Suppose a
2801 few signals happen to arrive in rapid succession by bad luck---there is
2802 no limit on how much this could shorten or lengthen the wait.
2804 Instead, compute the calendar time at which the program should stop
2805 waiting, and keep trying to wait until that calendar time.  This won't
2806 be off by more than a second.  With just a little more work, you can use
2807 @code{select} and make the waiting period quite accurate.  (Of course,
2808 heavy system load can cause additional unavoidable delays---unless the
2809 machine is dedicated to one application, there is no way you can avoid
2810 this.)
2812 On some systems, @code{sleep} can do strange things if your program uses
2813 @code{SIGALRM} explicitly.  Even if @code{SIGALRM} signals are being
2814 ignored or blocked when @code{sleep} is called, @code{sleep} might
2815 return prematurely on delivery of a @code{SIGALRM} signal.  If you have
2816 established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
2817 signal is delivered while the process is sleeping, the action taken
2818 might be just to cause @code{sleep} to return instead of invoking your
2819 handler.  And, if @code{sleep} is interrupted by delivery of a signal
2820 whose handler requests an alarm or alters the handling of @code{SIGALRM},
2821 this handler and @code{sleep} will interfere.
2823 On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in
2824 the same program, because @code{sleep} does not work by means of
2825 @code{SIGALRM}.
2827 @deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
2828 @standards{POSIX.1, time.h}
2829 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2830 @c On Linux, it's a syscall.  On Mach, it calls gettimeofday and uses
2831 @c ports.
2832 If resolution to seconds is not enough the @code{nanosleep} function can
2833 be used.  As the name suggests the sleep interval can be specified in
2834 nanoseconds.  The actual elapsed time of the sleep interval might be
2835 longer since the system rounds the elapsed time you request up to the
2836 next integer multiple of the actual resolution the system can deliver.
2838 *@code{requested_time} is the elapsed time of the interval you want to
2839 sleep.
2841 The function returns as *@code{remaining} the elapsed time left in the
2842 interval for which you requested to sleep.  If the interval completed
2843 without getting interrupted by a signal, this is zero.
2845 @code{struct timespec} is described in @xref{Elapsed Time}.
2847 If the function returns because the interval is over the return value is
2848 zero.  If the function returns @math{-1} the global variable @var{errno}
2849 is set to the following values:
2851 @table @code
2852 @item EINTR
2853 The call was interrupted because a signal was delivered to the thread.
2854 If the @var{remaining} parameter is not the null pointer the structure
2855 pointed to by @var{remaining} is updated to contain the remaining
2856 elapsed time.
2858 @item EINVAL
2859 The nanosecond value in the @var{requested_time} parameter contains an
2860 illegal value.  Either the value is negative or greater than or equal to
2861 1000 million.
2862 @end table
2864 This function is a cancellation point in multi-threaded programs.  This
2865 is a problem if the thread allocates some resources (like memory, file
2866 descriptors, semaphores or whatever) at the time @code{nanosleep} is
2867 called.  If the thread gets canceled these resources stay allocated
2868 until the program ends.  To avoid this calls to @code{nanosleep} should
2869 be protected using cancellation handlers.
2870 @c ref pthread_cleanup_push / pthread_cleanup_pop
2872 The @code{nanosleep} function is declared in @file{time.h}.
2873 @end deftypefun