diff options
Diffstat (limited to 'REORG.TODO/manual/time.texi')
| -rw-r--r-- | REORG.TODO/manual/time.texi | 2922 |
1 files changed, 2922 insertions, 0 deletions
diff --git a/REORG.TODO/manual/time.texi b/REORG.TODO/manual/time.texi new file mode 100644 index 0000000000..dccb979955 --- /dev/null +++ b/REORG.TODO/manual/time.texi @@ -0,0 +1,2922 @@ +@node Date and Time, Resource Usage And Limitation, Arithmetic, Top +@c %MENU% Functions for getting the date and time and formatting them nicely +@chapter Date and Time + +This chapter describes functions for manipulating dates and times, +including functions for determining what time it is and conversion +between different time representations. + +@menu +* Time Basics:: Concepts and definitions. +* Elapsed Time:: Data types to represent elapsed times +* Processor And CPU Time:: Time a program has spent executing. +* Calendar Time:: Manipulation of ``real'' dates and times. +* Setting an Alarm:: Sending a signal after a specified time. +* Sleeping:: Waiting for a period of time. +@end menu + + +@node Time Basics +@section Time Basics +@cindex time + +Discussing time in a technical manual can be difficult because the word +``time'' in English refers to lots of different things. In this manual, +we use a rigorous terminology to avoid confusion, and the only thing we +use the simple word ``time'' for is to talk about the abstract concept. + +A @dfn{calendar time} is a point in the time continuum, for example +November 4, 1990, at 18:02.5 UTC. Sometimes this is called ``absolute +time''. +@cindex calendar time + +We don't speak of a ``date'', because that is inherent in a calendar +time. +@cindex date + +An @dfn{interval} is a contiguous part of the time continuum between two +calendar times, for example the hour between 9:00 and 10:00 on July 4, +1980. +@cindex interval + +An @dfn{elapsed time} is the length of an interval, for example, 35 +minutes. People sometimes sloppily use the word ``interval'' to refer +to the elapsed time of some interval. +@cindex elapsed time +@cindex time, elapsed + +An @dfn{amount of time} is a sum of elapsed times, which need not be of +any specific intervals. For example, the amount of time it takes to +read a book might be 9 hours, independently of when and in how many +sittings it is read. + +A @dfn{period} is the elapsed time of an interval between two events, +especially when they are part of a sequence of regularly repeating +events. +@cindex period of time + +@dfn{CPU time} is like calendar time, except that it is based on the +subset of the time continuum when a particular process is actively +using a CPU. CPU time is, therefore, relative to a process. +@cindex CPU time + +@dfn{Processor time} is an amount of time that a CPU is in use. In +fact, it's a basic system resource, since there's a limit to how much +can exist in any given interval (that limit is the elapsed time of the +interval times the number of CPUs in the processor). People often call +this CPU time, but we reserve the latter term in this manual for the +definition above. +@cindex processor time + +@node Elapsed Time +@section Elapsed Time +@cindex elapsed time + +One way to represent an elapsed time is with a simple arithmetic data +type, as with the following function to compute the elapsed time between +two calendar times. This function is declared in @file{time.h}. + +@comment time.h +@comment ISO +@deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The @code{difftime} function returns the number of seconds of elapsed +time between calendar time @var{time1} and calendar time @var{time0}, as +a value of type @code{double}. The difference ignores leap seconds +unless leap second support is enabled. + +In @theglibc{}, you can simply subtract @code{time_t} values. But on +other systems, the @code{time_t} data type might use some other encoding +where subtraction doesn't work directly. +@end deftypefun + +@Theglibc{} provides two data types specifically for representing +an elapsed time. They are used by various @glibcadj{} functions, and +you can use them for your own purposes too. They're exactly the same +except that one has a resolution in microseconds, and the other, newer +one, is in nanoseconds. + +@comment sys/time.h +@comment BSD +@deftp {Data Type} {struct timeval} +@cindex timeval +The @code{struct timeval} structure represents an elapsed time. It is +declared in @file{sys/time.h} and has the following members: + +@table @code +@item time_t tv_sec +This represents the number of whole seconds of elapsed time. + +@item long int tv_usec +This is the rest of the elapsed time (a fraction of a second), +represented as the number of microseconds. It is always less than one +million. + +@end table +@end deftp + +@comment sys/time.h +@comment POSIX.1 +@deftp {Data Type} {struct timespec} +@cindex timespec +The @code{struct timespec} structure represents an elapsed time. It is +declared in @file{time.h} and has the following members: + +@table @code +@item time_t tv_sec +This represents the number of whole seconds of elapsed time. + +@item long int tv_nsec +This is the rest of the elapsed time (a fraction of a second), +represented as the number of nanoseconds. It is always less than one +billion. + +@end table +@end deftp + +It is often necessary to subtract two values of type @w{@code{struct +timeval}} or @w{@code{struct timespec}}. Here is the best way to do +this. It works even on some peculiar operating systems where the +@code{tv_sec} member has an unsigned type. + +@smallexample +@include timeval_subtract.c.texi +@end smallexample + +Common functions that use @code{struct timeval} are @code{gettimeofday} +and @code{settimeofday}. + + +There are no @glibcadj{} functions specifically oriented toward +dealing with elapsed times, but the calendar time, processor time, and +alarm and sleeping functions have a lot to do with them. + + +@node Processor And CPU Time +@section Processor And CPU Time + +If you're trying to optimize your program or measure its efficiency, +it's very useful to know how much processor time it uses. For that, +calendar time and elapsed times are useless because a process may spend +time waiting for I/O or for other processes to use the CPU. However, +you can get the information with the functions in this section. + +CPU time (@pxref{Time Basics}) is represented by the data type +@code{clock_t}, which is a number of @dfn{clock ticks}. It gives the +total amount of time a process has actively used a CPU since some +arbitrary event. On @gnusystems{}, that event is the creation of the +process. While arbitrary in general, the event is always the same event +for any particular process, so you can always measure how much time on +the CPU a particular computation takes by examining the process' CPU +time before and after the computation. +@cindex CPU time +@cindex clock ticks +@cindex ticks, clock + +On @gnulinuxhurdsystems{}, @code{clock_t} is equivalent to @code{long int} and +@code{CLOCKS_PER_SEC} is an integer value. But in other systems, both +@code{clock_t} and the macro @code{CLOCKS_PER_SEC} can be either integer +or floating-point types. Casting CPU time values to @code{double}, as +in the example above, makes sure that operations such as arithmetic and +printing work properly and consistently no matter what the underlying +representation is. + +Note that the clock can wrap around. On a 32bit system with +@code{CLOCKS_PER_SEC} set to one million this function will return the +same value approximately every 72 minutes. + +For additional functions to examine a process' use of processor time, +and to control it, see @ref{Resource Usage And Limitation}. + + +@menu +* CPU Time:: The @code{clock} function. +* Processor Time:: The @code{times} function. +@end menu + +@node CPU Time +@subsection CPU Time Inquiry + +To get a process' CPU time, you can use the @code{clock} function. This +facility is declared in the header file @file{time.h}. +@pindex time.h + +In typical usage, you call the @code{clock} function at the beginning +and end of the interval you want to time, subtract the values, and then +divide by @code{CLOCKS_PER_SEC} (the number of clock ticks per second) +to get processor time, like this: + +@smallexample +@group +#include <time.h> + +clock_t start, end; +double cpu_time_used; + +start = clock(); +@dots{} /* @r{Do the work.} */ +end = clock(); +cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC; +@end group +@end smallexample + +Do not use a single CPU time as an amount of time; it doesn't work that +way. Either do a subtraction as shown above or query processor time +directly. @xref{Processor Time}. + +Different computers and operating systems vary wildly in how they keep +track of CPU time. It's common for the internal processor clock +to have a resolution somewhere between a hundredth and millionth of a +second. + +@comment time.h +@comment ISO +@deftypevr Macro int CLOCKS_PER_SEC +The value of this macro is the number of clock ticks per second measured +by the @code{clock} function. POSIX requires that this value be one +million independent of the actual resolution. +@end deftypevr + +@comment time.h +@comment ISO +@deftp {Data Type} clock_t +This is the type of the value returned by the @code{clock} function. +Values of type @code{clock_t} are numbers of clock ticks. +@end deftp + +@comment time.h +@comment ISO +@deftypefun clock_t clock (void) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On Hurd, this calls task_info twice and adds user and system time +@c from both basic and thread time info structs. On generic posix, +@c calls times and adds utime and stime. On bsd, calls getrusage and +@c safely converts stime and utime to clock. On linux, calls +@c clock_gettime. +This function returns the calling process' current CPU time. If the CPU +time is not available or cannot be represented, @code{clock} returns the +value @code{(clock_t)(-1)}. +@end deftypefun + + +@node Processor Time +@subsection Processor Time Inquiry + +The @code{times} function returns information about a process' +consumption of processor time in a @w{@code{struct tms}} object, in +addition to the process' CPU time. @xref{Time Basics}. You should +include the header file @file{sys/times.h} to use this facility. +@cindex processor time +@cindex CPU time +@pindex sys/times.h + +@comment sys/times.h +@comment POSIX.1 +@deftp {Data Type} {struct tms} +The @code{tms} structure is used to return information about process +times. It contains at least the following members: + +@table @code +@item clock_t tms_utime +This is the total processor time the calling process has used in +executing the instructions of its program. + +@item clock_t tms_stime +This is the processor time the system has used on behalf of the calling +process. + +@item clock_t tms_cutime +This is the sum of the @code{tms_utime} values and the @code{tms_cutime} +values of all terminated child processes of the calling process, whose +status has been reported to the parent process by @code{wait} or +@code{waitpid}; see @ref{Process Completion}. In other words, it +represents the total processor time used in executing the instructions +of all the terminated child processes of the calling process, excluding +child processes which have not yet been reported by @code{wait} or +@code{waitpid}. +@cindex child process + +@item clock_t tms_cstime +This is similar to @code{tms_cutime}, but represents the total processor +time the system has used on behalf of all the terminated child processes +of the calling process. +@end table + +All of the times are given in numbers of clock ticks. Unlike CPU time, +these are the actual amounts of time; not relative to any event. +@xref{Creating a Process}. +@end deftp + +@comment time.h +@comment POSIX.1 +@deftypevr Macro int CLK_TCK +This is an obsolete name for the number of clock ticks per second. Use +@code{sysconf (_SC_CLK_TCK)} instead. +@end deftypevr + +@comment sys/times.h +@comment POSIX.1 +@deftypefun clock_t times (struct tms *@var{buffer}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On HURD, this calls task_info twice, for basic and thread times info, +@c adding user and system times into tms, and then gettimeofday, to +@c compute the real time. On BSD, it calls getclktck, getrusage (twice) +@c and time. On Linux, it's a syscall with special handling to account +@c for clock_t counts that look like error values. +The @code{times} function stores the processor time information for +the calling process in @var{buffer}. + +The return value is the number of clock ticks since an arbitrary point +in the past, e.g. since system start-up. @code{times} returns +@code{(clock_t)(-1)} to indicate failure. +@end deftypefun + +@strong{Portability Note:} The @code{clock} function described in +@ref{CPU Time} is specified by the @w{ISO C} standard. The +@code{times} function is a feature of POSIX.1. On @gnusystems{}, the +CPU time is defined to be equivalent to the sum of the @code{tms_utime} +and @code{tms_stime} fields returned by @code{times}. + +@node Calendar Time +@section Calendar Time + +This section describes facilities for keeping track of calendar time. +@xref{Time Basics}. + +@Theglibc{} represents calendar time three ways: + +@itemize @bullet +@item +@dfn{Simple time} (the @code{time_t} data type) is a compact +representation, typically giving the number of seconds of elapsed time +since some implementation-specific base time. +@cindex simple time + +@item +There is also a "high-resolution time" representation. Like simple +time, this represents a calendar time as an elapsed time since a base +time, but instead of measuring in whole seconds, it uses a @code{struct +timeval} data type, which includes fractions of a second. Use this time +representation instead of simple time when you need greater precision. +@cindex high-resolution time + +@item +@dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data +type) represents a calendar time as a set of components specifying the +year, month, and so on in the Gregorian calendar, for a specific time +zone. This calendar time representation is usually used only to +communicate with people. +@cindex local time +@cindex broken-down time +@cindex Gregorian calendar +@cindex calendar, Gregorian +@end itemize + +@menu +* Simple Calendar Time:: Facilities for manipulating calendar time. +* High-Resolution Calendar:: A time representation with greater precision. +* Broken-down Time:: Facilities for manipulating local time. +* High Accuracy Clock:: Maintaining a high accuracy system clock. +* Formatting Calendar Time:: Converting times to strings. +* Parsing Date and Time:: Convert textual time and date information back + into broken-down time values. +* TZ Variable:: How users specify the time zone. +* Time Zone Functions:: Functions to examine or specify the time zone. +* Time Functions Example:: An example program showing use of some of + the time functions. +@end menu + +@node Simple Calendar Time +@subsection Simple Calendar Time + +This section describes the @code{time_t} data type for representing calendar +time as simple time, and the functions which operate on simple time objects. +These facilities are declared in the header file @file{time.h}. +@pindex time.h + +@cindex epoch +@comment time.h +@comment ISO +@deftp {Data Type} time_t +This is the data type used to represent simple time. Sometimes, it also +represents an elapsed time. When interpreted as a calendar time value, +it represents the number of seconds elapsed since 00:00:00 on January 1, +1970, Coordinated Universal Time. (This calendar time is sometimes +referred to as the @dfn{epoch}.) POSIX requires that this count not +include leap seconds, but on some systems this count includes leap seconds +if you set @code{TZ} to certain values (@pxref{TZ Variable}). + +Note that a simple time has no concept of local time zone. Calendar +Time @var{T} is the same instant in time regardless of where on the +globe the computer is. + +In @theglibc{}, @code{time_t} is equivalent to @code{long int}. +In other systems, @code{time_t} might be either an integer or +floating-point type. +@end deftp + +The function @code{difftime} tells you the elapsed time between two +simple calendar times, which is not always as easy to compute as just +subtracting. @xref{Elapsed Time}. + +@comment time.h +@comment ISO +@deftypefun time_t time (time_t *@var{result}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The @code{time} function returns the current calendar time as a value of +type @code{time_t}. If the argument @var{result} is not a null pointer, +the calendar time value is also stored in @code{*@var{result}}. If the +current calendar time is not available, the value +@w{@code{(time_t)(-1)}} is returned. +@end deftypefun + +@c The GNU C library implements stime() with a call to settimeofday() on +@c Linux. +@comment time.h +@comment SVID, XPG +@deftypefun int stime (const time_t *@var{newtime}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On unix, this is implemented in terms of settimeofday. +@code{stime} sets the system clock, i.e., it tells the system that the +current calendar time is @var{newtime}, where @code{newtime} is +interpreted as described in the above definition of @code{time_t}. + +@code{settimeofday} is a newer function which sets the system clock to +better than one second precision. @code{settimeofday} is generally a +better choice than @code{stime}. @xref{High-Resolution Calendar}. + +Only the superuser can set the system clock. + +If the function succeeds, the return value is zero. Otherwise, it is +@code{-1} and @code{errno} is set accordingly: + +@table @code +@item EPERM +The process is not superuser. +@end table +@end deftypefun + + + +@node High-Resolution Calendar +@subsection High-Resolution Calendar + +The @code{time_t} data type used to represent simple times has a +resolution of only one second. Some applications need more precision. + +So, @theglibc{} also contains functions which are capable of +representing calendar times to a higher resolution than one second. The +functions and the associated data types described in this section are +declared in @file{sys/time.h}. +@pindex sys/time.h + +@comment sys/time.h +@comment BSD +@deftp {Data Type} {struct timezone} +The @code{struct timezone} structure is used to hold minimal information +about the local time zone. It has the following members: + +@table @code +@item int tz_minuteswest +This is the number of minutes west of UTC. + +@item int tz_dsttime +If nonzero, Daylight Saving Time applies during some part of the year. +@end table + +The @code{struct timezone} type is obsolete and should never be used. +Instead, use the facilities described in @ref{Time Zone Functions}. +@end deftp + +@comment sys/time.h +@comment BSD +@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On most GNU/Linux systems this is a direct syscall, but the posix/ +@c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and +@c localtime_r, saving and restoring tzname in an unsafe manner. +@c On some GNU/Linux variants, ifunc resolvers are used in shared libc +@c for vdso resolution. ifunc-vdso-revisit. +The @code{gettimeofday} function returns the current calendar time as +the elapsed time since the epoch in the @code{struct timeval} structure +indicated by @var{tp}. (@pxref{Elapsed Time} for a description of +@code{struct timeval}). Information about the time zone is returned in +the structure pointed to by @var{tzp}. If the @var{tzp} argument is a null +pointer, time zone information is ignored. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error condition is defined for this function: + +@table @code +@item ENOSYS +The operating system does not support getting time zone information, and +@var{tzp} is not a null pointer. @gnusystems{} do not +support using @w{@code{struct timezone}} to represent time zone +information; that is an obsolete feature of 4.3 BSD. +Instead, use the facilities described in @ref{Time Zone Functions}. +@end table +@end deftypefun + +@comment sys/time.h +@comment BSD +@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On HURD, it calls host_set_time with a privileged port. On other +@c unix systems, it's a syscall. +The @code{settimeofday} function sets the current calendar time in the +system clock according to the arguments. As for @code{gettimeofday}, +the calendar time is represented as the elapsed time since the epoch. +As for @code{gettimeofday}, time zone information is ignored if +@var{tzp} is a null pointer. + +You must be a privileged user in order to use @code{settimeofday}. + +Some kernels automatically set the system clock from some source such as +a hardware clock when they start up. Others, including Linux, place the +system clock in an ``invalid'' state (in which attempts to read the clock +fail). A call of @code{stime} removes the system clock from an invalid +state, and system startup scripts typically run a program that calls +@code{stime}. + +@code{settimeofday} causes a sudden jump forwards or backwards, which +can cause a variety of problems in a system. Use @code{adjtime} (below) +to make a smooth transition from one time to another by temporarily +speeding up or slowing down the clock. + +With a Linux kernel, @code{adjtimex} does the same thing and can also +make permanent changes to the speed of the system clock so it doesn't +need to be corrected as often. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error conditions are defined for this function: + +@table @code +@item EPERM +This process cannot set the clock because it is not privileged. + +@item ENOSYS +The operating system does not support setting time zone information, and +@var{tzp} is not a null pointer. +@end table +@end deftypefun + +@c On Linux, GNU libc implements adjtime() as a call to adjtimex(). +@comment sys/time.h +@comment BSD +@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On hurd and mach, call host_adjust_time with a privileged port. On +@c Linux, it's implemented in terms of adjtimex. On other unixen, it's +@c a syscall. +This function speeds up or slows down the system clock in order to make +a gradual adjustment. This ensures that the calendar time reported by +the system clock is always monotonically increasing, which might not +happen if you simply set the clock. + +The @var{delta} argument specifies a relative adjustment to be made to +the clock time. If negative, the system clock is slowed down for a +while until it has lost this much elapsed time. If positive, the system +clock is speeded up for a while. + +If the @var{olddelta} argument is not a null pointer, the @code{adjtime} +function returns information about any previous time adjustment that +has not yet completed. + +This function is typically used to synchronize the clocks of computers +in a local network. You must be a privileged user to use it. + +With a Linux kernel, you can use the @code{adjtimex} function to +permanently change the clock speed. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error condition is defined for this function: + +@table @code +@item EPERM +You do not have privilege to set the time. +@end table +@end deftypefun + +@strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday}, +and @code{adjtime} functions are derived from BSD. + + +Symbols for the following function are declared in @file{sys/timex.h}. + +@comment sys/timex.h +@comment GNU +@deftypefun int adjtimex (struct timex *@var{timex}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c It's a syscall, only available on linux. + +@code{adjtimex} is functionally identical to @code{ntp_adjtime}. +@xref{High Accuracy Clock}. + +This function is present only with a Linux kernel. + +@end deftypefun + +@node Broken-down Time +@subsection Broken-down Time +@cindex broken-down time +@cindex calendar time and broken-down time + +Calendar time is represented by the usual @glibcadj{} functions as an +elapsed time since a fixed base calendar time. This is convenient for +computation, but has no relation to the way people normally think of +calendar time. By contrast, @dfn{broken-down time} is a binary +representation of calendar time separated into year, month, day, and so +on. Broken-down time values are not useful for calculations, but they +are useful for printing human readable time information. + +A broken-down time value is always relative to a choice of time +zone, and it also indicates which time zone that is. + +The symbols in this section are declared in the header file @file{time.h}. + +@comment time.h +@comment ISO +@deftp {Data Type} {struct tm} +This is the data type used to represent a broken-down time. The structure +contains at least the following members, which can appear in any order. + +@table @code +@item int tm_sec +This is the number of full seconds since the top of the minute (normally +in the range @code{0} through @code{59}, but the actual upper limit is +@code{60}, to allow for leap seconds if leap second support is +available). +@cindex leap second + +@item int tm_min +This is the number of full minutes since the top of the hour (in the +range @code{0} through @code{59}). + +@item int tm_hour +This is the number of full hours past midnight (in the range @code{0} through +@code{23}). + +@item int tm_mday +This is the ordinal day of the month (in the range @code{1} through @code{31}). +Watch out for this one! As the only ordinal number in the structure, it is +inconsistent with the rest of the structure. + +@item int tm_mon +This is the number of full calendar months since the beginning of the +year (in the range @code{0} through @code{11}). Watch out for this one! +People usually use ordinal numbers for month-of-year (where January = 1). + +@item int tm_year +This is the number of full calendar years since 1900. + +@item int tm_wday +This is the number of full days since Sunday (in the range @code{0} through +@code{6}). + +@item int tm_yday +This is the number of full days since the beginning of the year (in the +range @code{0} through @code{365}). + +@item int tm_isdst +@cindex Daylight Saving Time +@cindex summer time +This is a flag that indicates whether Daylight Saving Time is (or was, or +will be) in effect at the time described. The value is positive if +Daylight Saving Time is in effect, zero if it is not, and negative if the +information is not available. + +@item long int tm_gmtoff +This field describes the time zone that was used to compute this +broken-down time value, including any adjustment for daylight saving; it +is the number of seconds that you must add to UTC to get local time. +You can also think of this as the number of seconds east of UTC. For +example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}. +The @code{tm_gmtoff} field is derived from BSD and is a GNU library +extension; it is not visible in a strict @w{ISO C} environment. + +@item const char *tm_zone +This field is the name for the time zone that was used to compute this +broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and +GNU extension, and is not visible in a strict @w{ISO C} environment. +@end table +@end deftp + + +@comment time.h +@comment ISO +@deftypefun {struct tm *} localtime (const time_t *@var{time}) +@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c Calls tz_convert with a static buffer. +@c localtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +The @code{localtime} function converts the simple time pointed to by +@var{time} to broken-down time representation, expressed relative to the +user's specified time zone. + +The return value is a pointer to a static broken-down time structure, which +might be overwritten by subsequent calls to @code{ctime}, @code{gmtime}, +or @code{localtime}. (But no other library function overwrites the contents +of this object.) + +The return value is the null pointer if @var{time} cannot be represented +as a broken-down time; typically this is because the year cannot fit into +an @code{int}. + +Calling @code{localtime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. +@end deftypefun + +Using the @code{localtime} function is a big problem in multi-threaded +programs. The result is returned in a static buffer and this is used in +all threads. POSIX.1c introduced a variant of this function. + +@comment time.h +@comment POSIX.1c +@deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c localtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tz_convert(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c tzset_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c always called with tzset_lock held +@c sets static is_initialized before initialization; +@c reads and sets old_tz; sets tz_rules. +@c some of the issues only apply on the first call. +@c subsequent calls only trigger these when called by localtime; +@c otherwise, they're ok. +@c getenv dup @mtsenv +@c strcmp dup ok +@c strdup @ascuheap +@c tzfile_read @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c memcmp dup ok +@c strstr dup ok +@c getenv dup @mtsenv +@c asprintf dup @mtslocale @ascuheap @acsmem +@c stat64 dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fileno dup ok +@c fstat64 dup ok +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c free dup @ascuheap @acsmem +@c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive] +@c fread_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c memcpy dup ok +@c decode ok +@c bswap_32 dup ok +@c fseek dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c ftello dup ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c malloc dup @ascuheap @acsmem +@c decode64 ok +@c bswap_64 dup ok +@c getc_unlocked ok [no @mtasurace:stream @asucorrupt @acucorrupt] +@c tzstring dup @ascuheap @acsmem +@c compute_tzname_max dup ok [guarded by tzset_lock] +@c memset dup ok +@c update_vars ok [guarded by tzset_lock] +@c sets daylight, timezone, tzname and tzname_cur_max; +@c called only with tzset_lock held, unless tzset_parse_tz +@c (internal, but not static) gets called by users; given the its +@c double-underscore-prefixed name, this interface violation could +@c be regarded as undefined behavior. +@c strlen ok +@c tzset_parse_tz @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sscanf dup @mtslocale @ascuheap @acsmem +@c isalnum dup @mtsenv +@c tzstring @ascuheap @acsmem +@c reads and changes tzstring_list without synchronization, but +@c only called with tzset_lock held (save for interface violations) +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c strcpy dup ok +@c isdigit dup @mtslocale +@c compute_offset ok +@c tzfile_default @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sets tzname, timezone, types, zone_names, rule_*off, etc; no guards +@c strlen dup ok +@c tzfile_read dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mempcpy dup ok +@c compute_tzname_max ok [if guarded by tzset_lock] +@c iterates over zone_names; no guards +@c free dup @ascuheap @acsmem +@c strtoul dup @mtslocale +@c update_vars dup ok +@c tzfile_compute(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c sets tzname; no guards. with !use_localtime, as in gmtime, it's ok +@c tzstring dup @acsuheap @acsmem +@c tzset_parse_tz dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c offtime dup ok +@c tz_compute dup ok +@c strcmp dup ok +@c offtime ok +@c isleap dup ok +@c tz_compute ok +@c compute_change ok +@c isleap ok +@c libc_lock_unlock dup @aculock + +The @code{localtime_r} function works just like the @code{localtime} +function. It takes a pointer to a variable containing a simple time +and converts it to the broken-down time format. + +But the result is not placed in a static buffer. Instead it is placed +in the object of type @code{struct tm} to which the parameter +@var{resultp} points. + +If the conversion is successful the function returns a pointer to the +object the result was written into, i.e., it returns @var{resultp}. +@end deftypefun + + +@comment time.h +@comment ISO +@deftypefun {struct tm *} gmtime (const time_t *@var{time}) +@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +This function is similar to @code{localtime}, except that the broken-down +time is expressed as Coordinated Universal Time (UTC) (formerly called +Greenwich Mean Time (GMT)) rather than relative to a local time zone. + +@end deftypefun + +As for the @code{localtime} function we have the problem that the result +is placed in a static variable. POSIX.1c also provides a replacement for +@code{gmtime}. + +@comment time.h +@comment POSIX.1c +@deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c You'd think tz_convert could avoid some safety issues with +@c !use_localtime, but no such luck: tzset_internal will always bring +@c about all possible AS and AC problems when it's first called. +@c Calling any of localtime,gmtime_r once would run the initialization +@c and avoid the heap, mem and fd issues in gmtime* in subsequent calls, +@c but the unsafe locking would remain. +@c gmtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tz_convert(gmtime_r) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +This function is similar to @code{localtime_r}, except that it converts +just like @code{gmtime} the given time as Coordinated Universal Time. + +If the conversion is successful the function returns a pointer to the +object the result was written into, i.e., it returns @var{resultp}. +@end deftypefun + + +@comment time.h +@comment ISO +@deftypefun time_t mktime (struct tm *@var{brokentime}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c mktime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c passes a static localtime_offset to mktime_internal; it is read +@c once, used as an initial guess, and updated at the end, but not +@c used except as a guess for subsequent calls, so it should be safe. +@c Even though a compiler might delay the load and perform it multiple +@c times (bug 16346), there are at least two unconditional uses of the +@c auto variable in which the first load is stored, separated by a +@c call to an external function, and a conditional change of the +@c variable before the external call, so refraining from allocating a +@c local variable at the first load would be a very bad optimization. +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mktime_internal(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c ydhms_diff ok +@c ranged_convert(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c *convert = localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c time_t_avg dup ok +@c guess_time_tm dup ok +@c ydhms_diff dup ok +@c time_t_add_ok ok +@c time_t_avg ok +@c isdst_differ ok +@c time_t_int_add_ok ok +The @code{mktime} function converts a broken-down time structure to a +simple time representation. It also normalizes the contents of the +broken-down time structure, and fills in some components based on the +values of the others. + +The @code{mktime} function ignores the specified contents of the +@code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone} +members of the broken-down time +structure. It uses the values of the other components to determine the +calendar time; it's permissible for these components to have +unnormalized values outside their normal ranges. The last thing that +@code{mktime} does is adjust the components of the @var{brokentime} +structure, including the members that were initially ignored. + +If the specified broken-down time cannot be represented as a simple time, +@code{mktime} returns a value of @code{(time_t)(-1)} and does not modify +the contents of @var{brokentime}. + +Calling @code{mktime} also sets the current time zone as if +@code{tzset} were called; @code{mktime} uses this information instead +of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. +@end deftypefun + +@comment time.h +@comment ??? +@deftypefun time_t timelocal (struct tm *@var{brokentime}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c Alias to mktime. + +@code{timelocal} is functionally identical to @code{mktime}, but more +mnemonically named. Note that it is the inverse of the @code{localtime} +function. + +@strong{Portability note:} @code{mktime} is essentially universally +available. @code{timelocal} is rather rare. + +@end deftypefun + +@comment time.h +@comment ??? +@deftypefun time_t timegm (struct tm *@var{brokentime}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gmtime_offset triggers the same caveats as localtime_offset in mktime. +@c although gmtime_r, as called by mktime, might save some issues, +@c tzset calls tzset_internal with always, which forces +@c reinitialization, so all issues may arise. +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c mktime_internal(gmtime_r) @asulock @aculock +@c ..gmtime_r @asulock @aculock +@c ... dup ok +@c tz_convert(!use_localtime) @asulock @aculock +@c ... dup @asulock @aculock +@c tzfile_compute(!use_localtime) ok + +@code{timegm} is functionally identical to @code{mktime} except it +always takes the input values to be Coordinated Universal Time (UTC) +regardless of any local time zone setting. + +Note that @code{timegm} is the inverse of @code{gmtime}. + +@strong{Portability note:} @code{mktime} is essentially universally +available. @code{timegm} is rather rare. For the most portable +conversion from a UTC broken-down time to a simple time, set +the @code{TZ} environment variable to UTC, call @code{mktime}, then set +@code{TZ} back. + +@end deftypefun + + + +@node High Accuracy Clock +@subsection High Accuracy Clock + +@cindex time, high precision +@cindex clock, high accuracy +@pindex sys/timex.h +@c On Linux, GNU libc implements ntp_gettime() and npt_adjtime() as calls +@c to adjtimex(). +The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an +interface to monitor and manipulate the system clock to maintain high +accuracy time. For example, you can fine tune the speed of the clock +or synchronize it with another time source. + +A typical use of these functions is by a server implementing the Network +Time Protocol to synchronize the clocks of multiple systems and high +precision clocks. + +These functions are declared in @file{sys/timex.h}. + +@tindex struct ntptimeval +@deftp {Data Type} {struct ntptimeval} +This structure is used for information about the system clock. It +contains the following members: +@table @code +@item struct timeval time +This is the current calendar time, expressed as the elapsed time since +the epoch. The @code{struct timeval} data type is described in +@ref{Elapsed Time}. + +@item long int maxerror +This is the maximum error, measured in microseconds. Unless updated +via @code{ntp_adjtime} periodically, this value will reach some +platform-specific maximum value. + +@item long int esterror +This is the estimated error, measured in microseconds. This value can +be set by @code{ntp_adjtime} to indicate the estimated offset of the +system clock from the true calendar time. +@end table +@end deftp + +@comment sys/timex.h +@comment GNU +@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Wrapper for adjtimex. +The @code{ntp_gettime} function sets the structure pointed to by +@var{tptr} to current values. The elements of the structure afterwards +contain the values the timer implementation in the kernel assumes. They +might or might not be correct. If they are not, an @code{ntp_adjtime} +call is necessary. + +The return value is @code{0} on success and other values on failure. The +following @code{errno} error conditions are defined for this function: + +@vtable @code +@item TIME_ERROR +The precision clock model is not properly set up at the moment, thus the +clock must be considered unsynchronized, and the values should be +treated with care. +@end vtable +@end deftypefun + +@tindex struct timex +@deftp {Data Type} {struct timex} +This structure is used to control and monitor the system clock. It +contains the following members: +@table @code +@item unsigned int modes +This variable controls whether and which values are set. Several +symbolic constants have to be combined with @emph{binary or} to specify +the effective mode. These constants start with @code{MOD_}. + +@item long int offset +This value indicates the current offset of the system clock from the true +calendar time. The value is given in microseconds. If bit +@code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other +dependent values) can be set. The offset's absolute value must not +exceed @code{MAXPHASE}. + + +@item long int frequency +This value indicates the difference in frequency between the true +calendar time and the system clock. The value is expressed as scaled +PPM (parts per million, 0.0001%). The scaling is @code{1 << +SHIFT_USEC}. The value can be set with bit @code{MOD_FREQUENCY}, but +the absolute value must not exceed @code{MAXFREQ}. + +@item long int maxerror +This is the maximum error, measured in microseconds. A new value can be +set using bit @code{MOD_MAXERROR}. Unless updated via +@code{ntp_adjtime} periodically, this value will increase steadily +and reach some platform-specific maximum value. + +@item long int esterror +This is the estimated error, measured in microseconds. This value can +be set using bit @code{MOD_ESTERROR}. + +@item int status +This variable reflects the various states of the clock machinery. There +are symbolic constants for the significant bits, starting with +@code{STA_}. Some of these flags can be updated using the +@code{MOD_STATUS} bit. + +@item long int constant +This value represents the bandwidth or stiffness of the PLL (phase +locked loop) implemented in the kernel. The value can be changed using +bit @code{MOD_TIMECONST}. + +@item long int precision +This value represents the accuracy or the maximum error when reading the +system clock. The value is expressed in microseconds. + +@item long int tolerance +This value represents the maximum frequency error of the system clock in +scaled PPM. This value is used to increase the @code{maxerror} every +second. + +@item struct timeval time +The current calendar time. + +@item long int tick +The elapsed time between clock ticks in microseconds. A clock tick is a +periodic timer interrupt on which the system clock is based. + +@item long int ppsfreq +This is the first of a few optional variables that are present only if +the system clock can use a PPS (pulse per second) signal to discipline +the system clock. The value is expressed in scaled PPM and it denotes +the difference in frequency between the system clock and the PPS signal. + +@item long int jitter +This value expresses a median filtered average of the PPS signal's +dispersion in microseconds. + +@item int shift +This value is a binary exponent for the duration of the PPS calibration +interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}. + +@item long int stabil +This value represents the median filtered dispersion of the PPS +frequency in scaled PPM. + +@item long int jitcnt +This counter represents the number of pulses where the jitter exceeded +the allowed maximum @code{MAXTIME}. + +@item long int calcnt +This counter reflects the number of successful calibration intervals. + +@item long int errcnt +This counter represents the number of calibration errors (caused by +large offsets or jitter). + +@item long int stbcnt +This counter denotes the number of calibrations where the stability +exceeded the threshold. +@end table +@end deftp + +@comment sys/timex.h +@comment GNU +@deftypefun int ntp_adjtime (struct timex *@var{tptr}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Alias to adjtimex syscall. +The @code{ntp_adjtime} function sets the structure specified by +@var{tptr} to current values. + +In addition, @code{ntp_adjtime} updates some settings to match what you +pass to it in *@var{tptr}. Use the @code{modes} element of *@var{tptr} +to select what settings to update. You can set @code{offset}, +@code{freq}, @code{maxerror}, @code{esterror}, @code{status}, +@code{constant}, and @code{tick}. + +@code{modes} = zero means set nothing. + +Only the superuser can update settings. + +@c On Linux, ntp_adjtime() also does the adjtime() function if you set +@c modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc implements +@c adjtime()). But this should be considered an internal function because +@c it's so inconsistent with the rest of what ntp_adjtime() does and is +@c forced in an ugly way into the struct timex. So we don't document it +@c and instead document adjtime() as the way to achieve the function. + +The return value is @code{0} on success and other values on failure. The +following @code{errno} error conditions are defined for this function: + +@table @code +@item TIME_ERROR +The high accuracy clock model is not properly set up at the moment, thus the +clock must be considered unsynchronized, and the values should be +treated with care. Another reason could be that the specified new values +are not allowed. + +@item EPERM +The process specified a settings update, but is not superuser. + +@end table + +For more details see RFC1305 (Network Time Protocol, Version 3) and +related documents. + +@strong{Portability note:} Early versions of @theglibc{} did not +have this function but did have the synonymous @code{adjtimex}. + +@end deftypefun + + +@node Formatting Calendar Time +@subsection Formatting Calendar Time + +The functions described in this section format calendar time values as +strings. These functions are declared in the header file @file{time.h}. +@pindex time.h + +@comment time.h +@comment ISO +@deftypefun {char *} asctime (const struct tm *@var{brokentime}) +@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}} +@c asctime @mtasurace:asctime @mtslocale +@c Uses a static buffer. +@c asctime_internal @mtslocale +@c snprintf dup @mtslocale [no @acsuheap @acsmem] +@c ab_day_name @mtslocale +@c ab_month_name @mtslocale +The @code{asctime} function converts the broken-down time value that +@var{brokentime} points to into a string in a standard format: + +@smallexample +"Tue May 21 13:46:22 1991\n" +@end smallexample + +The abbreviations for the days of week are: @samp{Sun}, @samp{Mon}, +@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}. + +The abbreviations for the months are: @samp{Jan}, @samp{Feb}, +@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug}, +@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}. + +The return value points to a statically allocated string, which might be +overwritten by subsequent calls to @code{asctime} or @code{ctime}. +(But no other library function overwrites the contents of this +string.) +@end deftypefun + +@comment time.h +@comment POSIX.1c +@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer}) +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} +@c asctime_r @mtslocale +@c asctime_internal dup @mtslocale +This function is similar to @code{asctime} but instead of placing the +result in a static buffer it writes the string in the buffer pointed to +by the parameter @var{buffer}. This buffer should have room +for at least 26 bytes, including the terminating null. + +If no error occurred the function returns a pointer to the string the +result was written into, i.e., it returns @var{buffer}. Otherwise +it returns @code{NULL}. +@end deftypefun + + +@comment time.h +@comment ISO +@deftypefun {char *} ctime (const time_t *@var{time}) +@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c asctime dup @mtasurace:asctime @mtslocale +The @code{ctime} function is similar to @code{asctime}, except that you +specify the calendar time argument as a @code{time_t} simple time value +rather than in broken-down local time format. It is equivalent to + +@smallexample +asctime (localtime (@var{time})) +@end smallexample + +Calling @code{ctime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. +@end deftypefun + +@comment time.h +@comment POSIX.1c +@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c asctime_r dup @mtslocale +This function is similar to @code{ctime}, but places the result in the +string pointed to by @var{buffer}. It is equivalent to (written using +gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}): + +@smallexample +(@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @}) +@end smallexample + +If no error occurred the function returns a pointer to the string the +result was written into, i.e., it returns @var{buffer}. Otherwise +it returns @code{NULL}. +@end deftypefun + + +@comment time.h +@comment ISO +@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@c strftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c strftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c strftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c add ok +@c memset_zero dup ok +@c memset_space dup ok +@c strlen dup ok +@c mbrlen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps] +@c mbsinit dup ok +@c cpy ok +@c add dup ok +@c memcpy_lowcase ok +@c TOLOWER ok +@c tolower_l ok +@c memcpy_uppcase ok +@c TOUPPER ok +@c toupper_l ok +@c MEMCPY ok +@c memcpy dup ok +@c ISDIGIT ok +@c STRLEN ok +@c strlen dup ok +@c strftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c TOUPPER dup ok +@c nl_get_era_entry @ascuheap @asulock @acsmem @aculock +@c nl_init_era_entries @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c free dup @ascuheap @acsmem +@c realloc dup @ascuheap @acsmem +@c memcpy dup ok +@c strchr dup ok +@c wcschr dup ok +@c libc_rwlock_unlock dup @asulock @aculock +@c ERA_DATE_CMP ok +@c DO_NUMBER ok +@c DO_NUMBER_SPACEPAD ok +@c nl_get_alt_digit @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c strchr dup ok +@c libc_rwlock_unlock dup @aculock +@c memset_space ok +@c memset dup ok +@c memset_zero ok +@c memset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c iso_week_days ok +@c isleap ok +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tm_diff ok +This function is similar to the @code{sprintf} function (@pxref{Formatted +Input}), but the conversion specifications that can appear in the format +template @var{template} are specialized for printing components of the date +and time @var{brokentime} according to the locale currently specified for +time conversion (@pxref{Locales}) and the current time zone +(@pxref{Time Zone Functions}). + +Ordinary characters appearing in the @var{template} are copied to the +output string @var{s}; this can include multibyte character sequences. +Conversion specifiers are introduced by a @samp{%} character, followed +by an optional flag which can be one of the following. These flags +are all GNU extensions. The first three affect only the output of +numbers: + +@table @code +@item _ +The number is padded with spaces. + +@item - +The number is not padded at all. + +@item 0 +The number is padded with zeros even if the format specifies padding +with spaces. + +@item ^ +The output uses uppercase characters, but only if this is possible +(@pxref{Case Conversion}). +@end table + +The default action is to pad the number with zeros to keep it a constant +width. Numbers that do not have a range indicated below are never +padded, since there is no natural width for them. + +Following the flag an optional specification of the width is possible. +This is specified in decimal notation. If the natural size of the +output of the field has less than the specified number of characters, +the result is written right adjusted and space padded to the given +size. + +An optional modifier can follow the optional flag and width +specification. The modifiers, which were first standardized by +POSIX.2-1992 and by @w{ISO C99}, are: + +@table @code +@item E +Use the locale's alternate representation for date and time. This +modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X}, +@code{%y} and @code{%Y} format specifiers. In a Japanese locale, for +example, @code{%Ex} might yield a date format based on the Japanese +Emperors' reigns. + +@item O +Use the locale's alternate numeric symbols for numbers. This modifier +applies only to numeric format specifiers. +@end table + +If the format supports the modifier but no alternate representation +is available, it is ignored. + +The conversion specifier ends with a format specifier taken from the +following list. The whole @samp{%} sequence is replaced in the output +string as follows: + +@table @code +@item %a +The abbreviated weekday name according to the current locale. + +@item %A +The full weekday name according to the current locale. + +@item %b +The abbreviated month name according to the current locale. + +@item %B +The full month name according to the current locale. + +Using @code{%B} together with @code{%d} produces grammatically +incorrect results for some locales. + +@item %c +The preferred calendar time representation for the current locale. + +@item %C +The century of the year. This is equivalent to the greatest integer not +greater than the year divided by 100. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %d +The day of the month as a decimal number (range @code{01} through @code{31}). + +@item %D +The date using the format @code{%m/%d/%y}. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %e +The day of the month like with @code{%d}, but padded with spaces (range +@code{ 1} through @code{31}). + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %F +The date using the format @code{%Y-%m-%d}. This is the form specified +in the @w{ISO 8601} standard and is the preferred form for all uses. + +This format was first standardized by @w{ISO C99} and by POSIX.1-2001. + +@item %g +The year corresponding to the ISO week number, but without the century +(range @code{00} through @code{99}). This has the same format and value +as @code{%y}, except that if the ISO week number (see @code{%V}) belongs +to the previous or next year, that year is used instead. + +This format was first standardized by @w{ISO C99} and by POSIX.1-2001. + +@item %G +The year corresponding to the ISO week number. This has the same format +and value as @code{%Y}, except that if the ISO week number (see +@code{%V}) belongs to the previous or next year, that year is used +instead. + +This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +but was previously available as a GNU extension. + +@item %h +The abbreviated month name according to the current locale. The action +is the same as for @code{%b}. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %H +The hour as a decimal number, using a 24-hour clock (range @code{00} through +@code{23}). + +@item %I +The hour as a decimal number, using a 12-hour clock (range @code{01} through +@code{12}). + +@item %j +The day of the year as a decimal number (range @code{001} through @code{366}). + +@item %k +The hour as a decimal number, using a 24-hour clock like @code{%H}, but +padded with spaces (range @code{ 0} through @code{23}). + +This format is a GNU extension. + +@item %l +The hour as a decimal number, using a 12-hour clock like @code{%I}, but +padded with spaces (range @code{ 1} through @code{12}). + +This format is a GNU extension. + +@item %m +The month as a decimal number (range @code{01} through @code{12}). + +@item %M +The minute as a decimal number (range @code{00} through @code{59}). + +@item %n +A single @samp{\n} (newline) character. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %p +Either @samp{AM} or @samp{PM}, according to the given time value; or the +corresponding strings for the current locale. Noon is treated as +@samp{PM} and midnight as @samp{AM}. In most locales +@samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"} +yields an empty string. + +@ignore +We currently have a problem with makeinfo. Write @samp{AM} and @samp{am} +both results in `am'. I.e., the difference in case is not visible anymore. +@end ignore +@item %P +Either @samp{am} or @samp{pm}, according to the given time value; or the +corresponding strings for the current locale, printed in lowercase +characters. Noon is treated as @samp{pm} and midnight as @samp{am}. In +most locales @samp{AM}/@samp{PM} format is not supported, in such cases +@code{"%P"} yields an empty string. + +This format is a GNU extension. + +@item %r +The complete calendar time using the AM/PM format of the current locale. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. +In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}. + +@item %R +The hour and minute in decimal numbers using the format @code{%H:%M}. + +This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +but was previously available as a GNU extension. + +@item %s +The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. + +This format is a GNU extension. + +@item %S +The seconds as a decimal number (range @code{00} through @code{60}). + +@item %t +A single @samp{\t} (tabulator) character. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %T +The time of day using decimal numbers using the format @code{%H:%M:%S}. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %u +The day of the week as a decimal number (range @code{1} through +@code{7}), Monday being @code{1}. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %U +The week number of the current year as a decimal number (range @code{00} +through @code{53}), starting with the first Sunday as the first day of +the first week. Days preceding the first Sunday in the year are +considered to be in week @code{00}. + +@item %V +The @w{ISO 8601:1988} week number as a decimal number (range @code{01} +through @code{53}). ISO weeks start with Monday and end with Sunday. +Week @code{01} of a year is the first week which has the majority of its +days in that year; this is equivalent to the week containing the year's +first Thursday, and it is also equivalent to the week containing January +4. Week @code{01} of a year can contain days from the previous year. +The week before week @code{01} of a year is the last week (@code{52} or +@code{53}) of the previous year even if it contains days from the new +year. + +This format was first standardized by POSIX.2-1992 and by @w{ISO C99}. + +@item %w +The day of the week as a decimal number (range @code{0} through +@code{6}), Sunday being @code{0}. + +@item %W +The week number of the current year as a decimal number (range @code{00} +through @code{53}), starting with the first Monday as the first day of +the first week. All days preceding the first Monday in the year are +considered to be in week @code{00}. + +@item %x +The preferred date representation for the current locale. + +@item %X +The preferred time of day representation for the current locale. + +@item %y +The year without a century as a decimal number (range @code{00} through +@code{99}). This is equivalent to the year modulo 100. + +@item %Y +The year as a decimal number, using the Gregorian calendar. Years +before the year @code{1} are numbered @code{0}, @code{-1}, and so on. + +@item %z +@w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g., +@code{-0600} or @code{+0100}), or nothing if no time zone is +determinable. + +This format was first standardized by @w{ISO C99} and by POSIX.1-2001 +but was previously available as a GNU extension. + +In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format +@w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent +@w{@samp{"%a, %d %b %Y %T %z"}}). + +@item %Z +The time zone abbreviation (empty if the time zone can't be determined). + +@item %% +A literal @samp{%} character. +@end table + +The @var{size} parameter can be used to specify the maximum number of +characters to be stored in the array @var{s}, including the terminating +null character. If the formatted time requires more than @var{size} +characters, @code{strftime} returns zero and the contents of the array +@var{s} are undefined. Otherwise the return value indicates the +number of characters placed in the array @var{s}, not including the +terminating null character. + +@emph{Warning:} This convention for the return value which is prescribed +in @w{ISO C} can lead to problems in some situations. For certain +format strings and certain locales the output really can be the empty +string and this cannot be discovered by testing the return value only. +E.g., in most locales the AM/PM time format is not supported (most of +the world uses the 24 hour time representation). In such locales +@code{"%p"} will return the empty string, i.e., the return value is +zero. To detect situations like this something similar to the following +code should be used: + +@smallexample +buf[0] = '\1'; +len = strftime (buf, bufsize, format, tp); +if (len == 0 && buf[0] != '\0') + @{ + /* Something went wrong in the strftime call. */ + @dots{} + @} +@end smallexample + +If @var{s} is a null pointer, @code{strftime} does not actually write +anything, but instead returns the number of characters it would have written. + +Calling @code{strftime} also sets the current time zone as if +@code{tzset} were called; @code{strftime} uses this information +instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. + +For an example of @code{strftime}, see @ref{Time Functions Example}. +@end deftypefun + +@comment time.h +@comment ISO/Amend1 +@deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c wcsftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c add ok +@c memset_zero dup ok +@c memset_space dup ok +@c wcslen dup ok +@c cpy ok +@c add dup ok +@c memcpy_lowcase ok +@c TOLOWER ok +@c towlower_l dup ok +@c memcpy_uppcase ok +@c TOUPPER ok +@c towupper_l dup ok +@c MEMCPY ok +@c wmemcpy dup ok +@c widen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c memset dup ok +@c mbsrtowcs_l @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps] +@c ISDIGIT ok +@c STRLEN ok +@c wcslen dup ok +@c wcsftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd +@c TOUPPER dup ok +@c nl_get_era_entry dup @ascuheap @asulock @acsmem @aculock +@c DO_NUMBER ok +@c DO_NUMBER_SPACEPAD ok +@c nl_get_walt_digit dup @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit dup @ascuheap @acsmem +@c malloc dup @ascuheap @acsmem +@c memset dup ok +@c wcschr dup ok +@c libc_rwlock_unlock dup @aculock +@c memset_space ok +@c wmemset dup ok +@c memset_zero ok +@c wmemset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c iso_week_days ok +@c isleap ok +@c tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c tm_diff ok +The @code{wcsftime} function is equivalent to the @code{strftime} +function with the difference that it operates on wide character +strings. The buffer where the result is stored, pointed to by @var{s}, +must be an array of wide characters. The parameter @var{size} which +specifies the size of the output buffer gives the number of wide +characters, not the number of bytes. + +Also the format string @var{template} is a wide character string. Since +all characters needed to specify the format string are in the basic +character set it is portably possible to write format strings in the C +source code using the @code{L"@dots{}"} notation. The parameter +@var{brokentime} has the same meaning as in the @code{strftime} call. + +The @code{wcsftime} function supports the same flags, modifiers, and +format specifiers as the @code{strftime} function. + +The return value of @code{wcsftime} is the number of wide characters +stored in @code{s}. When more characters would have to be written than +can be placed in the buffer @var{s} the return value is zero, with the +same problems indicated in the @code{strftime} documentation. +@end deftypefun + +@node Parsing Date and Time +@subsection Convert textual time and date information back + +The @w{ISO C} standard does not specify any functions which can convert +the output of the @code{strftime} function back into a binary format. +This led to a variety of more-or-less successful implementations with +different interfaces over the years. Then the Unix standard was +extended by the addition of two functions: @code{strptime} and +@code{getdate}. Both have strange interfaces but at least they are +widely available. + +@menu +* Low-Level Time String Parsing:: Interpret string according to given format. +* General Time String Parsing:: User-friendly function to parse data and + time strings. +@end menu + +@node Low-Level Time String Parsing +@subsubsection Interpret string according to given format + +The first function is rather low-level. It is nevertheless frequently +used in software since it is better known. Its interface and +implementation are heavily influenced by the @code{getdate} function, +which is defined and implemented in terms of calls to @code{strptime}. + +@comment time.h +@comment XPG4 +@deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c memset dup ok +@c ISSPACE ok +@c isspace_l dup ok +@c match_char ok +@c match_string ok +@c strlen dup ok +@c strncasecmp_l dup ok +@c strcmp dup ok +@c recursive @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c strptime_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c get_number ok +@c ISSPACE dup ok +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c nl_select_era_entry @ascuheap @asulock @acsmem @aculock +@c nl_init_era_entries dup @ascuheap @asulock @acsmem @aculock +@c get_alt_number dup @ascuheap @asulock @acsmem @aculock +@c nl_parse_alt_digit dup @ascuheap @asulock @acsmem @aculock +@c libc_rwlock_wrlock dup @asulock @aculock +@c nl_init_alt_digit dup @ascuheap @acsmem +@c libc_rwlock_unlock dup @aculock +@c get_number dup ok +@c day_of_the_week ok +@c day_of_the_year ok +The @code{strptime} function parses the input string @var{s} according +to the format string @var{fmt} and stores its results in the +structure @var{tp}. + +The input string could be generated by a @code{strftime} call or +obtained any other way. It does not need to be in a human-recognizable +format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even +though it is ambiguous without context. As long as the format string +@var{fmt} matches the input string the function will succeed. + +The user has to make sure, though, that the input can be parsed in a +unambiguous way. The string @code{"1999112"} can be parsed using the +format @code{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2. It +is necessary to add appropriate separators to reliably get results. + +The format string consists of the same components as the format string +of the @code{strftime} function. The only difference is that the flags +@code{_}, @code{-}, @code{0}, and @code{^} are not allowed. +@comment Is this really the intention? --drepper +Several of the distinct formats of @code{strftime} do the same work in +@code{strptime} since differences like case of the input do not matter. +For reasons of symmetry all formats are supported, though. + +The modifiers @code{E} and @code{O} are also allowed everywhere the +@code{strftime} function allows them. + +The formats are: + +@table @code +@item %a +@itemx %A +The weekday name according to the current locale, in abbreviated form or +the full name. + +@item %b +@itemx %B +@itemx %h +The month name according to the current locale, in abbreviated form or +the full name. + +@item %c +The date and time representation for the current locale. + +@item %Ec +Like @code{%c} but the locale's alternative date and time format is used. + +@item %C +The century of the year. + +It makes sense to use this format only if the format string also +contains the @code{%y} format. + +@item %EC +The locale's representation of the period. + +Unlike @code{%C} it sometimes makes sense to use this format since some +cultures represent years relative to the beginning of eras instead of +using the Gregorian years. + +@item %d +@item %e +The day of the month as a decimal number (range @code{1} through @code{31}). +Leading zeroes are permitted but not required. + +@item %Od +@itemx %Oe +Same as @code{%d} but using the locale's alternative numeric symbols. + +Leading zeroes are permitted but not required. + +@item %D +Equivalent to @code{%m/%d/%y}. + +@item %F +Equivalent to @code{%Y-%m-%d}, which is the @w{ISO 8601} date +format. + +This is a GNU extension following an @w{ISO C99} extension to +@code{strftime}. + +@item %g +The year corresponding to the ISO week number, but without the century +(range @code{00} through @code{99}). + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +This format is a GNU extension following a GNU extension of @code{strftime}. + +@item %G +The year corresponding to the ISO week number. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +This format is a GNU extension following a GNU extension of @code{strftime}. + +@item %H +@itemx %k +The hour as a decimal number, using a 24-hour clock (range @code{00} through +@code{23}). + +@code{%k} is a GNU extension following a GNU extension of @code{strftime}. + +@item %OH +Same as @code{%H} but using the locale's alternative numeric symbols. + +@item %I +@itemx %l +The hour as a decimal number, using a 12-hour clock (range @code{01} through +@code{12}). + +@code{%l} is a GNU extension following a GNU extension of @code{strftime}. + +@item %OI +Same as @code{%I} but using the locale's alternative numeric symbols. + +@item %j +The day of the year as a decimal number (range @code{1} through @code{366}). + +Leading zeroes are permitted but not required. + +@item %m +The month as a decimal number (range @code{1} through @code{12}). + +Leading zeroes are permitted but not required. + +@item %Om +Same as @code{%m} but using the locale's alternative numeric symbols. + +@item %M +The minute as a decimal number (range @code{0} through @code{59}). + +Leading zeroes are permitted but not required. + +@item %OM +Same as @code{%M} but using the locale's alternative numeric symbols. + +@item %n +@itemx %t +Matches any white space. + +@item %p +@item %P +The locale-dependent equivalent to @samp{AM} or @samp{PM}. + +This format is not useful unless @code{%I} or @code{%l} is also used. +Another complication is that the locale might not define these values at +all and therefore the conversion fails. + +@code{%P} is a GNU extension following a GNU extension to @code{strftime}. + +@item %r +The complete time using the AM/PM format of the current locale. + +A complication is that the locale might not define this format at all +and therefore the conversion fails. + +@item %R +The hour and minute in decimal numbers using the format @code{%H:%M}. + +@code{%R} is a GNU extension following a GNU extension to @code{strftime}. + +@item %s +The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. + +@code{%s} is a GNU extension following a GNU extension to @code{strftime}. + +@item %S +The seconds as a decimal number (range @code{0} through @code{60}). + +Leading zeroes are permitted but not required. + +@strong{NB:} The Unix specification says the upper bound on this value +is @code{61}, a result of a decision to allow double leap seconds. You +will not see the value @code{61} because no minute has more than one +leap second, but the myth persists. + +@item %OS +Same as @code{%S} but using the locale's alternative numeric symbols. + +@item %T +Equivalent to the use of @code{%H:%M:%S} in this place. + +@item %u +The day of the week as a decimal number (range @code{1} through +@code{7}), Monday being @code{1}. + +Leading zeroes are permitted but not required. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +@item %U +The week number of the current year as a decimal number (range @code{0} +through @code{53}). + +Leading zeroes are permitted but not required. + +@item %OU +Same as @code{%U} but using the locale's alternative numeric symbols. + +@item %V +The @w{ISO 8601:1988} week number as a decimal number (range @code{1} +through @code{53}). + +Leading zeroes are permitted but not required. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +@item %w +The day of the week as a decimal number (range @code{0} through +@code{6}), Sunday being @code{0}. + +Leading zeroes are permitted but not required. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +@item %Ow +Same as @code{%w} but using the locale's alternative numeric symbols. + +@item %W +The week number of the current year as a decimal number (range @code{0} +through @code{53}). + +Leading zeroes are permitted but not required. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +@item %OW +Same as @code{%W} but using the locale's alternative numeric symbols. + +@item %x +The date using the locale's date format. + +@item %Ex +Like @code{%x} but the locale's alternative data representation is used. + +@item %X +The time using the locale's time format. + +@item %EX +Like @code{%X} but the locale's alternative time representation is used. + +@item %y +The year without a century as a decimal number (range @code{0} through +@code{99}). + +Leading zeroes are permitted but not required. + +Note that it is questionable to use this format without +the @code{%C} format. The @code{strptime} function does regard input +values in the range @math{68} to @math{99} as the years @math{1969} to +@math{1999} and the values @math{0} to @math{68} as the years +@math{2000} to @math{2068}. But maybe this heuristic fails for some +input data. + +Therefore it is best to avoid @code{%y} completely and use @code{%Y} +instead. + +@item %Ey +The offset from @code{%EC} in the locale's alternative representation. + +@item %Oy +The offset of the year (from @code{%C}) using the locale's alternative +numeric symbols. + +@item %Y +The year as a decimal number, using the Gregorian calendar. + +@item %EY +The full alternative year representation. + +@item %z +The offset from GMT in @w{ISO 8601}/RFC822 format. + +@item %Z +The timezone name. + +@emph{Note:} Currently, this is not fully implemented. The format is +recognized, input is consumed but no field in @var{tm} is set. + +@item %% +A literal @samp{%} character. +@end table + +All other characters in the format string must have a matching character +in the input string. Exceptions are white spaces in the input string +which can match zero or more whitespace characters in the format string. + +@strong{Portability Note:} The XPG standard advises applications to use +at least one whitespace character (as specified by @code{isspace}) or +other non-alphanumeric characters between any two conversion +specifications. @Theglibc{} does not have this limitation but +other libraries might have trouble parsing formats like +@code{"%d%m%Y%H%M%S"}. + +The @code{strptime} function processes the input string from right to +left. Each of the three possible input elements (white space, literal, +or format) are handled one after the other. If the input cannot be +matched to the format string the function stops. The remainder of the +format and input strings are not processed. + +The function returns a pointer to the first character it was unable to +process. If the input string contains more characters than required by +the format string the return value points right after the last consumed +input character. If the whole input string is consumed the return value +points to the @code{NULL} byte at the end of the string. If an error +occurs, i.e., @code{strptime} fails to match all of the format string, +the function returns @code{NULL}. +@end deftypefun + +The specification of the function in the XPG standard is rather vague, +leaving out a few important pieces of information. Most importantly, it +does not specify what happens to those elements of @var{tm} which are +not directly initialized by the different formats. The +implementations on different Unix systems vary here. + +The @glibcadj{} implementation does not touch those fields which are not +directly initialized. Exceptions are the @code{tm_wday} and +@code{tm_yday} elements, which are recomputed if any of the year, month, +or date elements changed. This has two implications: + +@itemize @bullet +@item +Before calling the @code{strptime} function for a new input string, you +should prepare the @var{tm} structure you pass. Normally this will mean +initializing all values to zero. Alternatively, you can set all +fields to values like @code{INT_MAX}, allowing you to determine which +elements were set by the function call. Zero does not work here since +it is a valid value for many of the fields. + +Careful initialization is necessary if you want to find out whether a +certain field in @var{tm} was initialized by the function call. + +@item +You can construct a @code{struct tm} value with several consecutive +@code{strptime} calls. A useful application of this is e.g. the parsing +of two separate strings, one containing date information and the other +time information. By parsing one after the other without clearing the +structure in-between, you can construct a complete broken-down time. +@end itemize + +The following example shows a function which parses a string which +contains the date information in either US style or @w{ISO 8601} form: + +@smallexample +const char * +parse_date (const char *input, struct tm *tm) +@{ + const char *cp; + + /* @r{First clear the result structure.} */ + memset (tm, '\0', sizeof (*tm)); + + /* @r{Try the ISO format first.} */ + cp = strptime (input, "%F", tm); + if (cp == NULL) + @{ + /* @r{Does not match. Try the US form.} */ + cp = strptime (input, "%D", tm); + @} + + return cp; +@} +@end smallexample + +@node General Time String Parsing +@subsubsection A More User-friendly Way to Parse Times and Dates + +The Unix standard defines another function for parsing date strings. +The interface is weird, but if the function happens to suit your +application it is just fine. It is problematic to use this function +in multi-threaded programs or libraries, since it returns a pointer to +a static variable, and uses a global variable and global state (an +environment variable). + +@comment time.h +@comment Unix98 +@defvar getdate_err +This variable of type @code{int} contains the error code of the last +unsuccessful call to @code{getdate}. Defined values are: + +@table @math +@item 1 +The environment variable @code{DATEMSK} is not defined or null. +@item 2 +The template file denoted by the @code{DATEMSK} environment variable +cannot be opened. +@item 3 +Information about the template file cannot retrieved. +@item 4 +The template file is not a regular file. +@item 5 +An I/O error occurred while reading the template file. +@item 6 +Not enough memory available to execute the function. +@item 7 +The template file contains no matching template. +@item 8 +The input date is invalid, but would match a template otherwise. This +includes dates like February 31st, and dates which cannot be represented +in a @code{time_t} variable. +@end table +@end defvar + +@comment time.h +@comment Unix98 +@deftypefun {struct tm *} getdate (const char *@var{string}) +@safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +The interface to @code{getdate} is the simplest possible for a function +to parse a string and return the value. @var{string} is the input +string and the result is returned in a statically-allocated variable. + +The details about how the string is processed are hidden from the user. +In fact, they can be outside the control of the program. Which formats +are recognized is controlled by the file named by the environment +variable @code{DATEMSK}. This file should contain +lines of valid format strings which could be passed to @code{strptime}. + +The @code{getdate} function reads these format strings one after the +other and tries to match the input string. The first line which +completely matches the input string is used. + +Elements not initialized through the format string retain the values +present at the time of the @code{getdate} function call. + +The formats recognized by @code{getdate} are the same as for +@code{strptime}. See above for an explanation. There are only a few +extensions to the @code{strptime} behavior: + +@itemize @bullet +@item +If the @code{%Z} format is given the broken-down time is based on the +current time of the timezone matched, not of the current timezone of the +runtime environment. + +@emph{Note}: This is not implemented (currently). The problem is that +timezone names are not unique. If a fixed timezone is assumed for a +given string (say @code{EST} meaning US East Coast time), then uses for +countries other than the USA will fail. So far we have found no good +solution to this. + +@item +If only the weekday is specified the selected day depends on the current +date. If the current weekday is greater than or equal to the @code{tm_wday} +value the current week's day is chosen, otherwise the day next week is chosen. + +@item +A similar heuristic is used when only the month is given and not the +year. If the month is greater than or equal to the current month, then +the current year is used. Otherwise it wraps to next year. The first +day of the month is assumed if one is not explicitly specified. + +@item +The current hour, minute, and second are used if the appropriate value is +not set through the format. + +@item +If no date is given tomorrow's date is used if the time is +smaller than the current time. Otherwise today's date is taken. +@end itemize + +It should be noted that the format in the template file need not only +contain format elements. The following is a list of possible format +strings (taken from the Unix standard): + +@smallexample +%m +%A %B %d, %Y %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p,%B %dnd +%A den %d. %B %Y %H.%M Uhr +@end smallexample + +As you can see, the template list can contain very specific strings like +@code{run job at %I %p,%B %dnd}. Using the above list of templates and +assuming the current time is Mon Sep 22 12:19:47 EDT 1986, we can obtain the +following results for the given input. + +@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} +@item Input @tab Match @tab Result +@item Mon @tab %a @tab Mon Sep 22 12:19:47 EDT 1986 +@item Sun @tab %a @tab Sun Sep 28 12:19:47 EDT 1986 +@item Fri @tab %a @tab Fri Sep 26 12:19:47 EDT 1986 +@item September @tab %B @tab Mon Sep 1 12:19:47 EDT 1986 +@item January @tab %B @tab Thu Jan 1 12:19:47 EST 1987 +@item December @tab %B @tab Mon Dec 1 12:19:47 EST 1986 +@item Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986 +@item Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987 +@item Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986 +@item Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989 +@item Fri 9 @tab %a %H @tab Fri Sep 26 09:00:00 EDT 1986 +@item Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987 +@item 10:30 @tab %H:%M @tab Tue Sep 23 10:30:00 EDT 1986 +@item 13:30 @tab %H:%M @tab Mon Sep 22 13:30:00 EDT 1986 +@end multitable + +The return value of the function is a pointer to a static variable of +type @w{@code{struct tm}}, or a null pointer if an error occurred. The +result is only valid until the next @code{getdate} call, making this +function unusable in multi-threaded applications. + +The @code{errno} variable is @emph{not} changed. Error conditions are +stored in the global variable @code{getdate_err}. See the +description above for a list of the possible error values. + +@emph{Warning:} The @code{getdate} function should @emph{never} be +used in SUID-programs. The reason is obvious: using the +@code{DATEMSK} environment variable you can get the function to open +any arbitrary file and chances are high that with some bogus input +(such as a binary file) the program will crash. +@end deftypefun + +@comment time.h +@comment GNU +@deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp}) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c getenv dup @mtsenv +@c stat64 dup ok +@c access dup ok +@c fopen dup @ascuheap @asulock @acsmem @acsfd @aculock +@c fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive] +@c isspace dup @mtslocale +@c strlen dup ok +@c malloc dup @ascuheap @acsmem +@c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd +@c memcpy dup ok +@c getline dup @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt, exclusive] +@c strptime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c feof_unlocked dup ok +@c free dup @ascuheap @acsmem +@c ferror_unlocked dup dup ok +@c time dup ok +@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c first_wday @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c memset dup ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c check_mday ok +@c mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +The @code{getdate_r} function is the reentrant counterpart of +@code{getdate}. It does not use the global variable @code{getdate_err} +to signal an error, but instead returns an error code. The same error +codes as described in the @code{getdate_err} documentation above are +used, with 0 meaning success. + +Moreover, @code{getdate_r} stores the broken-down time in the variable +of type @code{struct tm} pointed to by the second argument, rather than +in a static variable. + +This function is not defined in the Unix standard. Nevertheless it is +available on some other Unix systems as well. + +The warning against using @code{getdate} in SUID-programs applies to +@code{getdate_r} as well. +@end deftypefun + +@node TZ Variable +@subsection Specifying the Time Zone with @code{TZ} + +In POSIX systems, a user can specify the time zone by means of the +@code{TZ} environment variable. For information about how to set +environment variables, see @ref{Environment Variables}. The functions +for accessing the time zone are declared in @file{time.h}. +@pindex time.h +@cindex time zone + +You should not normally need to set @code{TZ}. If the system is +configured properly, the default time zone will be correct. You might +set @code{TZ} if you are using a computer over a network from a +different time zone, and would like times reported to you in the time +zone local to you, rather than what is local to the computer. + +In POSIX.1 systems the value of the @code{TZ} variable can be in one of +three formats. With @theglibc{}, the most common format is the +last one, which can specify a selection from a large database of time +zone information for many regions of the world. The first two formats +are used to describe the time zone information directly, which is both +more cumbersome and less precise. But the POSIX.1 standard only +specifies the details of the first two formats, so it is good to be +familiar with them in case you come across a POSIX.1 system that doesn't +support a time zone information database. + +The first format is used when there is no Daylight Saving Time (or +summer time) in the local time zone: + +@smallexample +@r{@var{std} @var{offset}} +@end smallexample + +The @var{std} string specifies the name of the time zone. It must be +three or more characters long and must not contain a leading colon, +embedded digits, commas, nor plus and minus signs. There is no space +character separating the time zone name from the @var{offset}, so these +restrictions are necessary to parse the specification correctly. + +The @var{offset} specifies the time value you must add to the local time +to get a Coordinated Universal Time value. It has syntax like +[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This +is positive if the local time zone is west of the Prime Meridian and +negative if it is east. The hour must be between @code{0} and +@code{24}, and the minute and seconds between @code{0} and @code{59}. + +For example, here is how we would specify Eastern Standard Time, but +without any Daylight Saving Time alternative: + +@smallexample +EST+5 +@end smallexample + +The second format is used when there is Daylight Saving Time: + +@smallexample +@r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]} +@end smallexample + +The initial @var{std} and @var{offset} specify the standard time zone, as +described above. The @var{dst} string and @var{offset} specify the name +and offset for the corresponding Daylight Saving Time zone; if the +@var{offset} is omitted, it defaults to one hour ahead of standard time. + +The remainder of the specification describes when Daylight Saving Time is +in effect. The @var{start} field is when Daylight Saving Time goes into +effect and the @var{end} field is when the change is made back to standard +time. The following formats are recognized for these fields: + +@table @code +@item J@var{n} +This specifies the Julian day, with @var{n} between @code{1} and @code{365}. +February 29 is never counted, even in leap years. + +@item @var{n} +This specifies the Julian day, with @var{n} between @code{0} and @code{365}. +February 29 is counted in leap years. + +@item M@var{m}.@var{w}.@var{d} +This specifies day @var{d} of week @var{w} of month @var{m}. The day +@var{d} must be between @code{0} (Sunday) and @code{6}. The week +@var{w} must be between @code{1} and @code{5}; week @code{1} is the +first week in which day @var{d} occurs, and week @code{5} specifies the +@emph{last} @var{d} day in the month. The month @var{m} should be +between @code{1} and @code{12}. +@end table + +The @var{time} fields specify when, in the local time currently in +effect, the change to the other time occurs. If omitted, the default is +@code{02:00:00}. The hours part of the time fields can range from +@minus{}167 through 167; this is an extension to POSIX.1, which allows +only the range 0 through 24. + +Here are some example @code{TZ} values, including the appropriate +Daylight Saving Time and its dates of applicability. In North +American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), +the normal offset from UTC is 5 hours; since this is +west of the prime meridian, the sign is positive. Summer time begins on +March's second Sunday at 2:00am, and ends on November's first Sunday +at 2:00am. + +@smallexample +EST+5EDT,M3.2.0/2,M11.1.0/2 +@end smallexample + +Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours +ahead of the prime meridian in winter, springing forward an hour on +March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or +after March 23), and falling back on October's last Sunday at 02:00. + +@smallexample +IST-2IDT,M3.4.4/26,M10.5.0 +@end smallexample + +Western Argentina Summer Time (WARST) is 3 hours behind the prime +meridian all year. There is a dummy fall-back transition on December +31 at 25:00 daylight saving time (i.e., 24:00 standard time, +equivalent to January 1 at 00:00 standard time), and a simultaneous +spring-forward transition on January 1 at 00:00 standard time, so +daylight saving time is in effect all year and the initial @code{WART} +is a placeholder. + +@smallexample +WART4WARST,J1/0,J365/25 +@end smallexample + +Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) +are 3 hours behind UTC in the winter. Its clocks follow the European +Union rules of springing forward by one hour on March's last Sunday at +01:00 UTC (@minus{}02:00 local time) and falling back on October's +last Sunday at 01:00 UTC (@minus{}01:00 local time). + +@smallexample +WGT3WGST,M3.5.0/-2,M10.5.0/-1 +@end smallexample + +The schedule of Daylight Saving Time in any particular jurisdiction has +changed over the years. To be strictly correct, the conversion of dates +and times in the past should be based on the schedule that was in effect +then. However, this format has no facilities to let you specify how the +schedule has changed from year to year. The most you can do is specify +one particular schedule---usually the present day schedule---and this is +used to convert any date, no matter when. For precise time zone +specifications, it is best to use the time zone information database +(see below). + +The third format looks like this: + +@smallexample +:@var{characters} +@end smallexample + +Each operating system interprets this format differently; in +@theglibc{}, @var{characters} is the name of a file which describes the time +zone. + +@pindex /etc/localtime +@pindex localtime +If the @code{TZ} environment variable does not have a value, the +operation chooses a time zone by default. In @theglibc{}, the +default time zone is like the specification @samp{TZ=:/etc/localtime} +(or @samp{TZ=:/usr/local/etc/localtime}, depending on how @theglibc{} +was configured; @pxref{Installation}). Other C libraries use their own +rule for choosing the default time zone, so there is little we can say +about them. + +@cindex time zone database +@pindex /usr/share/zoneinfo +@pindex zoneinfo +If @var{characters} begins with a slash, it is an absolute file name; +otherwise the library looks for the file +@w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo} +directory contains data files describing local time zones in many +different parts of the world. The names represent major cities, with +subdirectories for geographical areas; for example, +@file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}. +These data files are installed by the system administrator, who also +sets @file{/etc/localtime} to point to the data file for the local time +zone. The files typically come from the @url{http://www.iana.org/time-zones, +Time Zone Database} of time zone and daylight saving time +information for most regions of the world, which is maintained by a +community of volunteers and put in the public domain. + +@node Time Zone Functions +@subsection Functions and Variables for Time Zones + +@comment time.h +@comment POSIX.1 +@deftypevar {char *} tzname [2] +The array @code{tzname} contains two strings, which are the standard +names of the pair of time zones (standard and Daylight +Saving) that the user has selected. @code{tzname[0]} is the name of +the standard time zone (for example, @code{"EST"}), and @code{tzname[1]} +is the name for the time zone when Daylight Saving Time is in use (for +example, @code{"EDT"}). These correspond to the @var{std} and @var{dst} +strings (respectively) from the @code{TZ} environment variable. If +Daylight Saving Time is never used, @code{tzname[1]} is the empty string. + +The @code{tzname} array is initialized from the @code{TZ} environment +variable whenever @code{tzset}, @code{ctime}, @code{strftime}, +@code{mktime}, or @code{localtime} is called. If multiple abbreviations +have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War +Time and Eastern Daylight Time), the array contains the most recent +abbreviation. + +The @code{tzname} array is required for POSIX.1 compatibility, but in +GNU programs it is better to use the @code{tm_zone} member of the +broken-down time structure, since @code{tm_zone} reports the correct +abbreviation even when it is not the latest one. + +Though the strings are declared as @code{char *} the user must refrain +from modifying these strings. Modifying the strings will almost certainly +lead to trouble. + +@end deftypevar + +@comment time.h +@comment POSIX.1 +@deftypefun void tzset (void) +@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}} +@c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_lock dup @asulock @aculock +@c tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd +@c libc_lock_unlock dup @aculock +The @code{tzset} function initializes the @code{tzname} variable from +the value of the @code{TZ} environment variable. It is not usually +necessary for your program to call this function, because it is called +automatically when you use the other time conversion functions that +depend on the time zone. +@end deftypefun + +The following variables are defined for compatibility with System V +Unix. Like @code{tzname}, these variables are set by calling +@code{tzset} or the other time conversion functions. + +@comment time.h +@comment SVID +@deftypevar {long int} timezone +This contains the difference between UTC and the latest local standard +time, in seconds west of UTC. For example, in the U.S. Eastern time +zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member +of the broken-down time structure, this value is not adjusted for +daylight saving, and its sign is reversed. In GNU programs it is better +to use @code{tm_gmtoff}, since it contains the correct offset even when +it is not the latest one. +@end deftypevar + +@comment time.h +@comment SVID +@deftypevar int daylight +This variable has a nonzero value if Daylight Saving Time rules apply. +A nonzero value does not necessarily mean that Daylight Saving Time is +now in effect; it means only that Daylight Saving Time is sometimes in +effect. +@end deftypevar + +@node Time Functions Example +@subsection Time Functions Example + +Here is an example program showing the use of some of the calendar time +functions. + +@smallexample +@include strftim.c.texi +@end smallexample + +It produces output like this: + +@smallexample +Wed Jul 31 13:02:36 1991 +Today is Wednesday, July 31. +The time is 01:02 PM. +@end smallexample + + +@node Setting an Alarm +@section Setting an Alarm + +The @code{alarm} and @code{setitimer} functions provide a mechanism for a +process to interrupt itself in the future. They do this by setting a +timer; when the timer expires, the process receives a signal. + +@cindex setting an alarm +@cindex interval timer, setting +@cindex alarms, setting +@cindex timers, setting +Each process has three independent interval timers available: + +@itemize @bullet +@item +A real-time timer that counts elapsed time. This timer sends a +@code{SIGALRM} signal to the process when it expires. +@cindex real-time timer +@cindex timer, real-time + +@item +A virtual timer that counts processor time used by the process. This timer +sends a @code{SIGVTALRM} signal to the process when it expires. +@cindex virtual timer +@cindex timer, virtual + +@item +A profiling timer that counts both processor time used by the process, +and processor time spent in system calls on behalf of the process. This +timer sends a @code{SIGPROF} signal to the process when it expires. +@cindex profiling timer +@cindex timer, profiling + +This timer is useful for profiling in interpreters. The interval timer +mechanism does not have the fine granularity necessary for profiling +native code. +@c @xref{profil} !!! +@end itemize + +You can only have one timer of each kind set at any given time. If you +set a timer that has not yet expired, that timer is simply reset to the +new value. + +You should establish a handler for the appropriate alarm signal using +@code{signal} or @code{sigaction} before issuing a call to +@code{setitimer} or @code{alarm}. Otherwise, an unusual chain of events +could cause the timer to expire before your program establishes the +handler. In this case it would be terminated, since termination is the +default action for the alarm signals. @xref{Signal Handling}. + +To be able to use the alarm function to interrupt a system call which +might block otherwise indefinitely it is important to @emph{not} set the +@code{SA_RESTART} flag when registering the signal handler using +@code{sigaction}. When not using @code{sigaction} things get even +uglier: the @code{signal} function has fixed semantics with respect +to restarts. The BSD semantics for this function is to set the flag. +Therefore, if @code{sigaction} for whatever reason cannot be used, it is +necessary to use @code{sysv_signal} and not @code{signal}. + +The @code{setitimer} function is the primary means for setting an alarm. +This facility is declared in the header file @file{sys/time.h}. The +@code{alarm} function, declared in @file{unistd.h}, provides a somewhat +simpler interface for setting the real-time timer. +@pindex unistd.h +@pindex sys/time.h + +@comment sys/time.h +@comment BSD +@deftp {Data Type} {struct itimerval} +This structure is used to specify when a timer should expire. It contains +the following members: +@table @code +@item struct timeval it_interval +This is the period between successive timer interrupts. If zero, the +alarm will only be sent once. + +@item struct timeval it_value +This is the period between now and the first timer interrupt. If zero, +the alarm is disabled. +@end table + +The @code{struct timeval} data type is described in @ref{Elapsed Time}. +@end deftp + +@comment sys/time.h +@comment BSD +@deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old}) +@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}} +@c This function is marked with @mtstimer because the same set of timers +@c is shared by all threads of a process, so calling it in one thread +@c may interfere with timers set by another thread. This interference +@c is not regarded as destructive, because the interface specification +@c makes this overriding while returning the previous value the expected +@c behavior, and the kernel will serialize concurrent calls so that the +@c last one prevails, with each call getting the timer information from +@c the timer installed by the previous call in that serialization. +The @code{setitimer} function sets the timer specified by @var{which} +according to @var{new}. The @var{which} argument can have a value of +@code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}. + +If @var{old} is not a null pointer, @code{setitimer} returns information +about any previous unexpired timer of the same kind in the structure it +points to. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error conditions are defined for this function: + +@table @code +@item EINVAL +The timer period is too large. +@end table +@end deftypefun + +@comment sys/time.h +@comment BSD +@deftypefun int getitimer (int @var{which}, struct itimerval *@var{old}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The @code{getitimer} function stores information about the timer specified +by @var{which} in the structure pointed at by @var{old}. + +The return value and error conditions are the same as for @code{setitimer}. +@end deftypefun + +@vtable @code +@comment sys/time.h +@comment BSD +@item ITIMER_REAL +This constant can be used as the @var{which} argument to the +@code{setitimer} and @code{getitimer} functions to specify the real-time +timer. + +@comment sys/time.h +@comment BSD +@item ITIMER_VIRTUAL +This constant can be used as the @var{which} argument to the +@code{setitimer} and @code{getitimer} functions to specify the virtual +timer. + +@comment sys/time.h +@comment BSD +@item ITIMER_PROF +This constant can be used as the @var{which} argument to the +@code{setitimer} and @code{getitimer} functions to specify the profiling +timer. +@end vtable + +@comment unistd.h +@comment POSIX.1 +@deftypefun {unsigned int} alarm (unsigned int @var{seconds}) +@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}} +@c Wrapper for setitimer. +The @code{alarm} function sets the real-time timer to expire in +@var{seconds} seconds. If you want to cancel any existing alarm, you +can do this by calling @code{alarm} with a @var{seconds} argument of +zero. + +The return value indicates how many seconds remain before the previous +alarm would have been sent. If there was no previous alarm, @code{alarm} +returns zero. +@end deftypefun + +The @code{alarm} function could be defined in terms of @code{setitimer} +like this: + +@smallexample +unsigned int +alarm (unsigned int seconds) +@{ + struct itimerval old, new; + new.it_interval.tv_usec = 0; + new.it_interval.tv_sec = 0; + new.it_value.tv_usec = 0; + new.it_value.tv_sec = (long int) seconds; + if (setitimer (ITIMER_REAL, &new, &old) < 0) + return 0; + else + return old.it_value.tv_sec; +@} +@end smallexample + +There is an example showing the use of the @code{alarm} function in +@ref{Handler Returns}. + +If you simply want your process to wait for a given number of seconds, +you should use the @code{sleep} function. @xref{Sleeping}. + +You shouldn't count on the signal arriving precisely when the timer +expires. In a multiprocessing environment there is typically some +amount of delay involved. + +@strong{Portability Note:} The @code{setitimer} and @code{getitimer} +functions are derived from BSD Unix, while the @code{alarm} function is +specified by the POSIX.1 standard. @code{setitimer} is more powerful than +@code{alarm}, but @code{alarm} is more widely used. + +@node Sleeping +@section Sleeping + +The function @code{sleep} gives a simple way to make the program wait +for a short interval. If your program doesn't use signals (except to +terminate), then you can expect @code{sleep} to wait reliably throughout +the specified interval. Otherwise, @code{sleep} can return sooner if a +signal arrives; if you want to wait for a given interval regardless of +signals, use @code{select} (@pxref{Waiting for I/O}) and don't specify +any descriptors to wait for. +@c !!! select can get EINTR; using SA_RESTART makes sleep win too. + +@comment unistd.h +@comment POSIX.1 +@deftypefun {unsigned int} sleep (unsigned int @var{seconds}) +@safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}} +@c On Mach, it uses ports and calls time. On generic posix, it calls +@c nanosleep. On Linux, it temporarily blocks SIGCHLD, which is MT- and +@c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!). +The @code{sleep} function waits for @var{seconds} seconds or until a signal +is delivered, whichever happens first. + +If @code{sleep} returns because the requested interval is over, +it returns a value of zero. If it returns because of delivery of a +signal, its return value is the remaining time in the sleep interval. + +The @code{sleep} function is declared in @file{unistd.h}. +@end deftypefun + +Resist the temptation to implement a sleep for a fixed amount of time by +using the return value of @code{sleep}, when nonzero, to call +@code{sleep} again. This will work with a certain amount of accuracy as +long as signals arrive infrequently. But each signal can cause the +eventual wakeup time to be off by an additional second or so. Suppose a +few signals happen to arrive in rapid succession by bad luck---there is +no limit on how much this could shorten or lengthen the wait. + +Instead, compute the calendar time at which the program should stop +waiting, and keep trying to wait until that calendar time. This won't +be off by more than a second. With just a little more work, you can use +@code{select} and make the waiting period quite accurate. (Of course, +heavy system load can cause additional unavoidable delays---unless the +machine is dedicated to one application, there is no way you can avoid +this.) + +On some systems, @code{sleep} can do strange things if your program uses +@code{SIGALRM} explicitly. Even if @code{SIGALRM} signals are being +ignored or blocked when @code{sleep} is called, @code{sleep} might +return prematurely on delivery of a @code{SIGALRM} signal. If you have +established a handler for @code{SIGALRM} signals and a @code{SIGALRM} +signal is delivered while the process is sleeping, the action taken +might be just to cause @code{sleep} to return instead of invoking your +handler. And, if @code{sleep} is interrupted by delivery of a signal +whose handler requests an alarm or alters the handling of @code{SIGALRM}, +this handler and @code{sleep} will interfere. + +On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in +the same program, because @code{sleep} does not work by means of +@code{SIGALRM}. + +@comment time.h +@comment POSIX.1 +@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c On Linux, it's a syscall. On Mach, it calls gettimeofday and uses +@c ports. +If resolution to seconds is not enough the @code{nanosleep} function can +be used. As the name suggests the sleep interval can be specified in +nanoseconds. The actual elapsed time of the sleep interval might be +longer since the system rounds the elapsed time you request up to the +next integer multiple of the actual resolution the system can deliver. + +*@code{requested_time} is the elapsed time of the interval you want to +sleep. + +The function returns as *@code{remaining} the elapsed time left in the +interval for which you requested to sleep. If the interval completed +without getting interrupted by a signal, this is zero. + +@code{struct timespec} is described in @xref{Elapsed Time}. + +If the function returns because the interval is over the return value is +zero. If the function returns @math{-1} the global variable @var{errno} +is set to the following values: + +@table @code +@item EINTR +The call was interrupted because a signal was delivered to the thread. +If the @var{remaining} parameter is not the null pointer the structure +pointed to by @var{remaining} is updated to contain the remaining +elapsed time. + +@item EINVAL +The nanosecond value in the @var{requested_time} parameter contains an +illegal value. Either the value is negative or greater than or equal to +1000 million. +@end table + +This function is a cancellation point in multi-threaded programs. This +is a problem if the thread allocates some resources (like memory, file +descriptors, semaphores or whatever) at the time @code{nanosleep} is +called. If the thread gets canceled these resources stay allocated +until the program ends. To avoid this calls to @code{nanosleep} should +be protected using cancellation handlers. +@c ref pthread_cleanup_push / pthread_cleanup_pop + +The @code{nanosleep} function is declared in @file{time.h}. +@end deftypefun |