diff options
Diffstat (limited to 'manual/time.texi')
| -rw-r--r-- | manual/time.texi | 1068 |
1 files changed, 604 insertions, 464 deletions
diff --git a/manual/time.texi b/manual/time.texi index c5f5b94b67..164c150f64 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -8,7 +8,8 @@ between different time representations. @menu * Time Basics:: Concepts and definitions. -* Elapsed Time:: Data types to represent elapsed times +* Time Types:: Data types to represent time. +* Calculating Elapsed Time:: How to calculate the length of an interval. * 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. @@ -55,100 +56,186 @@ 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. +A @dfn{simple calendar time} is a calendar time represented as an +elapsed time since a fixed, implementation-specific calendar time +called the @dfn{epoch}. This representation is convenient for doing +calculations on calendar times, such as finding the elapsed time +between two calendar times. Simple calendar times are independent of +time zone; they represent the same instant in time regardless of where +on the globe the computer is. + +POSIX says that simple calendar times do not include leap seconds, but +some (otherwise POSIX-conformant) systems can be configured to include +leap seconds in simple calendar times. +@cindex leap seconds +@cindex seconds, leap +@cindex simple time +@cindex simple calendar time +@cindex calendar time, simple +@cindex epoch + +A @dfn{broken-down time} is a calendar time represented by its +components in the Gregorian calendar: year, month, day, hour, minute, +and second. A broken-down time value is relative to a specific time +zone, and so it is also sometimes called a @dfn{local time}. +Broken-down times are most useful for input and output, as they are +easier for people to understand, but more difficult to calculate with. +@cindex broken-down time +@cindex local time +@cindex Gregorian calendar +@cindex calendar, Gregorian + +@dfn{CPU time} measures the amount of time that a single process has +actively used a CPU to perform computations. It does not include the +time that process has spent waiting for external events. The system +tracks the CPU time used by each process separately. @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. +@dfn{Processor time} measures the amount of time @emph{any} CPU has +been in use by @emph{any} process. It is a basic system resource, +since there's a limit to how much can exist in any given interval (the +elapsed time of the interval times the number of CPUs in the computer) + +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 +@node Time Types +@section Time Types -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}. +ISO C and POSIX define several data types for representing elapsed +times, simple calendar times, and broken-down times. -@deftypefun double difftime (time_t @var{time1}, time_t @var{time0}) +@deftp {Data Type} clock_t @standards{ISO, time.h} -@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. +@code{clock_t} is used to measure processor and CPU time. +It may be an integer or a floating-point type. +Its values are counts of @dfn{clock ticks} since some arbitrary event +in the past. +The number of clock ticks per second is system-specific. +@xref{Processor And CPU Time}, for further detail. +@cindex clock ticks +@cindex ticks, clock +@end deftp -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 +@deftp {Data Type} time_t +@standards{ISO, time.h} +@code{time_t} is the simplest data type used to represent simple +calendar time. + +In ISO C, @code{time_t} can be either an integer or a floating-point +type, and the meaning of @code{time_t} values is not specified. The +only things a strictly conforming program can do with @code{time_t} +values are: pass them to @code{difftime} to get the elapsed time +between two simple calendar times (@pxref{Calculating Elapsed Time}), +and pass them to the functions that convert them to broken-down time +(@pxref{Broken-down Time}). + +On POSIX-conformant systems, @code{time_t} is an integer type and its +values represent the number of seconds elapsed since the @dfn{epoch}, +which is 00:00:00 on January 1, 1970, Coordinated Universal Time. + +@Theglibc{} additionally guarantees that @code{time_t} is a signed +type, and that all of its functions operate correctly on negative +@code{time_t} values, which are interpreted as times before the epoch. +@cindex epoch +@end deftp + +@deftp {Data Type} {struct timespec} +@standards{POSIX.1, time.h} +@cindex timespec +@code{struct timespec} represents a simple calendar time, or an +elapsed time, with sub-second resolution. It is declared in +@file{time.h} and has the following members: -@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. +@table @code +@item time_t tv_sec +The number of whole seconds elapsed since the epoch (for a simple +calendar time) or since some other starting point (for an elapsed +time). + +@item long int tv_nsec +The number of nanoseconds elapsed since the time given by the +@code{tv_sec} member. + +When @code{struct timespec} values are produced by @glibcadj{} +functions, the value in this field will always be greater than or +equal to zero, and less than 1,000,000,000. +When @code{struct timespec} values are supplied to @glibcadj{} +functions, the value in this field must be in the same range. +@end table +@end deftp @deftp {Data Type} {struct timeval} @standards{BSD, sys/time.h} @cindex timeval -The @code{struct timeval} structure represents an elapsed time. It is -declared in @file{sys/time.h} and has the following members: +@code{struct timeval} is an older type for representing a simple +calendar time, or an elapsed time, with sub-second resolution. It is +almost the same as @code{struct timespec}, but provides only +microsecond resolution. 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. +The number of whole seconds elapsed since the epoch (for a simple +calendar time) or since some other starting point (for an 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. - +The number of microseconds elapsed since the time given by the +@code{tv_sec} member. + +When @code{struct timeval} values are produced by @glibcadj{} +functions, the value in this field will always be greater than or +equal to zero, and less than 1,000,000. +When @code{struct timeval} values are supplied to @glibcadj{} +functions, the value in this field must be in the same range. @end table @end deftp -@deftp {Data Type} {struct timespec} -@standards{POSIX.1, sys/time.h} -@cindex timespec -The @code{struct timespec} structure represents an elapsed time. It is -declared in @file{time.h} and has the following members: +@deftp {Data Type} {struct tm} +@standards{ISO, time.h} +This is the data type used to represent a broken-down time. It has +separate fields for year, month, day, and so on. +@xref{Broken-down Time}, for further details. +@end deftp -@table @code -@item time_t tv_sec -This represents the number of whole seconds of elapsed time. +@node Calculating Elapsed Time +@section Calculating 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. +Often, one wishes to calculate an elapsed time as the difference +between two simple calendar times. @Theglibc{} provides only one +function for this purpose. -@end table -@end deftp +@deftypefun double difftime (time_t @var{end}, time_t @var{begin}) +@standards{ISO, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The @code{difftime} function returns the number of seconds of elapsed +time from calendar time @var{begin} to calendar time @var{end}, as +a value of type @code{double}. + +On POSIX-conformant systems, the advantage of using +@samp{difftime (@var{end}, @var{begin})} over @samp{@var{end} - @var{begin}} +is that it will produce the mathematically correct result even if +@var{end} and @var{begin} are so far apart that a simple subtraction +would overflow. However, if they are so far apart that a @code{double} +cannot exactly represent the difference, the result will be inexact. + +On other systems, @code{time_t} values might be encoded in a way that +prevents subtraction from working directly, and then @code{difftime} +would be the only way to compute their difference. +@end deftypefun -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. +@Theglibc{} does not provide any functions for computing the +difference between two values of type @w{@code{struct timeval}} or +@w{@code{struct timespec}}. Here is the recommended way to do this +calculation by hand. 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 @@ -233,12 +320,6 @@ by the @code{clock} function. POSIX requires that this value be one million independent of the actual resolution. @end deftypevr -@deftp {Data Type} clock_t -@standards{ISO, time.h} -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 - @deftypefun clock_t clock (void) @standards{ISO, time.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @@ -331,43 +412,15 @@ 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 +This section describes the functions for getting, setting, and +manipulating calendar times. @menu -* Simple Calendar Time:: Facilities for manipulating calendar time. -* High-Resolution Calendar:: A time representation with greater precision. +* Getting the Time:: Functions for finding out what time it is. +* Setting and Adjusting the Time:: + Functions for setting and adjusting + the system clock. * 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. @@ -377,175 +430,419 @@ communicate with people. 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 +@node Getting the Time +@subsection Getting the Time -@cindex epoch -@deftp {Data Type} time_t -@standards{ISO, time.h} -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}. +@Theglibc{} provides several functions for getting the current +calendar time, with different levels of resolution. @deftypefun time_t time (time_t *@var{result}) @standards{ISO, time.h} @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. +This is the simplest function for getting the current calendar time. +It returns the calendar time as a value of type @code{time_t}; on +POSIX systems, that means it has a resolution of one second. It +uses the same clock as @w{@samp{clock_gettime (CLOCK_REALTIME_COARSE)}}, +when the clock is available or @w{@samp{clock_gettime (CLOCK_REALTIME)}} +otherwise. + +If the argument @var{result} is not a null pointer, the calendar time +value is also stored in @code{*@var{result}}. + +This function cannot fail. @end deftypefun -@c The GNU C library implements stime() with a call to settimeofday() on -@c Linux. -@deftypefun int stime (const time_t *@var{newtime}) -@standards{SVID, time.h} -@standards{XPG, time.h} -@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}. +Some applications need more precise timekeeping than is possible with +a @code{time_t} alone. Some applications also need more control over +what is meant by ``the current time.'' For these applications, POSIX +provides a function @code{clock_gettime} that can retrieve the time +with up to nanosecond precision, from a variety of different clocks. +Clocks can be system-wide, measuring time the same for all processes; +or they can be per-process or per-thread, measuring CPU time consumed +by a particular process, or some other similar resource. Each clock +has its own resolution and epoch. You can find the resolution of a +clock with the function @code{clock_getres}. There is no function to +get the epoch for a clock; either it is fixed and documented, or the +clock is not meant to be used to measure absolute times. + +@deftp {Data Type} clockid_t +@standards{POSIX.1, time.h} +The type @code{clockid_t} is used for constants that indicate which of +several system clocks one wishes to use. +@end deftp + +All systems that support this family of functions will define at least +this clock constant: + +@deftypevr Macro clockid_t CLOCK_REALTIME +@standards{POSIX.1, time.h} +This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated +Universal Time. It is close to, but not necessarily in lock-step with, the +clocks of @code{time} (above) and of @code{gettimeofday} (below). +@end deftypevr + +@cindex monotonic time +A second clock constant which is not universal, but still very common, +is for a clock measuring @dfn{monotonic time}. Monotonic time is +useful for measuring elapsed times, because it guarantees that those +measurements are not affected by changes to the system clock. + +@deftypevr Macro clockid_t CLOCK_MONOTONIC +@standards{POSIX.1, time.h} +System-wide clock that continuously measures the advancement of +calendar time, ignoring discontinuous changes to the system's +setting for absolute calendar time. + +The epoch for this clock is an unspecified point in the past. +The epoch may change if the system is rebooted or suspended. +Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure +absolute time, only elapsed time. +@end deftypevr -@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}. +Systems may support more than just these two clocks. -Only the superuser can set the system clock. +@deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts}) +@standards{POSIX.1, time.h} +Get the current time accoding to the clock identified by @var{clock}, +storing it as seconds and nanoseconds in @code{*@var{ts}}. +@xref{Time Types}, for a description of @code{struct timespec}. -If the function succeeds, the return value is zero. Otherwise, it is -@code{-1} and @code{errno} is set accordingly: +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 -The process is not superuser. +@item EINVAL +The clock identified by @var{clock} is not supported. @end table @end deftypefun +@code{clock_gettime} reports the time scaled to seconds and +nanoseconds, but the actual resolution of each clock may not be as +fine as one nanosecond, and may not be the same for all clocks. POSIX +also provides a function for finding out the actual resolution of a +clock: +@deftypefun int clock_getres (clockid_t @var{clock}, struct timespec *@var{res}) +@standards{POSIX.1, time.h} +Get the actual resolution of the clock identified by @var{clock}, +storing it in @code{*@var{ts}}. -@node High-Resolution Calendar -@subsection High-Resolution Calendar +For instance, if the clock hardware for @code{CLOCK_REALTIME} +uses a quartz crystal that oscillates at 32.768 kHz, +then its resolution would be 30.518 microseconds, +and @w{@samp{clock_getres (CLOCK_REALTIME, &r)}} would set +@code{r.tv_sec} to 0 and @code{r.tv_nsec} to 30518. -The @code{time_t} data type used to represent simple times has a -resolution of only one second. Some applications need more precision. +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error condition is defined for this function: -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 +@table @code +@item EINVAL +The clock identified by @var{clock} is not supported. +@end table +@end deftypefun + +These functions, and the constants that identify particular clocks, +are declared in @file{time.h}. + +@strong{Portability Note:} On some systems, including systems that use +older versions of @theglibc{}, programs that use @code{clock_gettime} +or @code{clock_setres} must be linked with the @code{-lrt} library. +This has not been necessary with @theglibc{} since version 2.17. -@deftp {Data Type} {struct timezone} +@Theglibc{} also provides an older, but still widely used, function +for getting the current time with a resolution of microseconds. This +function is declared in @file{sys/time.h}. + +@deftypefun int gettimeofday (struct timeval *@var{tp}, void *@var{tzp}) @standards{BSD, sys/time.h} -The @code{struct timezone} structure is used to hold minimal information -about the local time zone. It has the following members: +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +Get the current calendar time, storing it as seconds and microseconds +in @code{*@var{tp}}. @xref{Time Types}, for a description of +@code{struct timeval}. The clock of @code{gettimeofday} is close to, +but not necessarily in lock-step with, the clocks of @code{time} and of +@w{@samp{clock_gettime (CLOCK_REALTIME)}} (see above). + +On some historic systems, if @var{tzp} was not a null pointer, +information about a system-wide time zone would be written to +@code{*@var{tzp}}. This feature is obsolete and not supported on +@gnusystems{}. You should always supply a null pointer for this +argument. Instead, use the facilities described in @ref{Time Zone +Functions} and in @ref{Broken-down Time} for working with time zones. + +This function cannot fail, and its return value is always @code{0}. + +@strong{Portability Note:} As of the 2008 revision of POSIX, this +function is considered obsolete. @Theglibc{} will continue to provide +this function indefinitely, but new programs should use +@code{clock_gettime} instead. +@end deftypefun + +@node Setting and Adjusting the Time +@subsection Setting and Adjusting the Time + +The clock hardware inside a modern computer is quite reliable, but it +can still be wrong. The functions in this section allow one to set +the system's idea of the current calendar time, and to adjust the rate +at which the system counts seconds, so that the calendar time will +both be accurate, and remain accurate. + +The functions in this section require special privileges to use. +@xref{Users and Groups}. + +@deftypefun int clock_settime (clockid_t @var{clock}, const struct timespec *@var{ts}) +@standards{POSIX, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +Change the current calendar time, according to the clock identified by +@var{clock}, to be the simple calendar time in @code{*@var{ts}}. + +Not all of the system's clocks can be changed. For instance, the +@code{CLOCK_REALTIME} clock can be changed (with the appropriate +privileges), but the @code{CLOCK_MONOTONIC} clock cannot. + +Because simple calendar times are independent of time zone, this +function should not be used when the time zone changes (e.g.@: if the +computer is physically moved from one zone to another). Instead, use +the facilities described in @ref{Time Zone Functions}. + +@code{clock_settime} causes the clock to jump forwards or backwards, +which can cause a variety of problems. Changing the +@code{CLOCK_REALTIME} clock with @code{clock_settime} does not affect +when timers expire (@pxref{Setting an Alarm}) or when sleeping +processes wake up (@pxref{Sleeping}), which avoids some of the +problems. Still, for small changes made while the system is running, +it is better to use @code{ntp_adjtime} (below) to make a smooth +transition from one time to another. + +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 int tz_minuteswest -This is the number of minutes west of UTC. +@item EINVAL +The clock identified by @var{clock} is not supported or cannot be set +at all, or the simple calendar time in @code{*@var{ts}} is invalid +(for instance, @code{ts->tv_nsec} is negative or greater than 999,999,999). -@item int tz_dsttime -If nonzero, Daylight Saving Time applies during some part of the year. +@item EPERM +This process does not have the privileges required to set the clock +identified by @var{clock}. @end table -The @code{struct timezone} type is obsolete and should never be used. -Instead, use the facilities described in @ref{Time Zone Functions}. +@strong{Portability Note}: On some systems, including systems that use +older versions of @theglibc{}, programs that use @code{clock_settime} +must be linked with the @code{-lrt} library. This has not been +necessary with @theglibc{} since version 2.17. +@end deftypefun + +@cindex time, high precision +@cindex clock, high accuracy +@cindex clock, disciplining +@pindex sys/timex.h +For systems that remain up and running for long periods, it is not +enough to set the time once; one should also @dfn{discipline} the +clock so that it does not drift away from the true calendar time. + +The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an +interface to monitor and discipline the system clock. For example, +you can fine-tune the rate at which the clock ``ticks,'' and make +small adjustments to the current reported calendar time smoothly, by +temporarily speeding up or slowing down the clock. + +These functions' names begin with @samp{ntp_} because they were +designed for use by programs implementing the Network Time Protocol to +synchronize a system's clock with other systems' clocks and/or with +external high-precision clock hardware. + +These functions, and the constants and structures they use, are +declared in @file{sys/timex.h}. + +@tindex struct ntptimeval +@deftp {Data Type} {struct ntptimeval} +This structure is used to report information about the system clock. +It contains the following members: +@table @code +@item struct timeval time +The current calendar time, as if retrieved by @code{gettimeofday}. +The @code{struct timeval} data type is described in +@ref{Time Types}. + +@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 -@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp}) -@standards{BSD, sys/time.h} +@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr}) +@standards{GNU, sys/timex.h} @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. +@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 @code{-1} on failure. The -following @code{errno} error condition is defined for this 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: + +@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 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}. +@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 deftypefun +@end deftp -@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp}) -@standards{BSD, sys/time.h} +@deftypefun int ntp_adjtime (struct timex *@var{tptr}) +@standards{GNU, sys/timex.h} @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. +@c Alias to adjtimex syscall. +The @code{ntp_adjtime} function sets the structure specified by +@var{tptr} to current values. -The return value is @code{0} on success and @code{-1} on failure. The +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 -This process cannot set the clock because it is not privileged. +The process specified a settings update, but is not superuser. -@item ENOSYS -The operating system does not support setting time zone information, and -@var{tzp} is not a null pointer. @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 + @c On Linux, GNU libc implements adjtime() as a call to adjtimex(). @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta}) @standards{BSD, sys/time.h} @@ -553,10 +850,11 @@ The operating system does not support setting time zone information, and @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. +This simpler version of @code{ntp_adjtime} speeds up or slows down the +system clock for a short time, in order to correct it by a small +amount. This avoids a discontinuous change in the calendar time +reported by the @code{CLOCK_REALTIME} clock, at the price of having to +wait longer for the time to become correct. 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 @@ -567,37 +865,86 @@ 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. +This process does not have the privileges required to adjust the +@code{CLOCK_REALTIME} clock. @end table @end deftypefun -@strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday}, -and @code{adjtime} functions are derived from BSD. +For compatibility, @theglibc{} also provides several older functions +for controlling the system time. New programs should prefer to use +the functions above. + +@deftypefun int stime (const time_t *@var{newtime}) +@standards{SVID, time.h} +@standards{XPG, time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +Change the @code{CLOCK_REALTIME} calendar time to be the simple +calendar time in @code{*@var{newtime}}. Calling this function is +exactly the same as calling @w{@samp{clock_settime (CLOCK_REALTIME)}}, +except that the new time can only be set to a precision of one second. +This function is no longer available on @gnusystems{}, but it may be +the @emph{only} way to set the time on very old Unix systems, so we +continue to document it. If it is available, it is declared in +@file{time.h}. -Symbols for the following function are declared in @file{sys/timex.h}. +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 +This process does not have the privileges required to adjust the +@code{CLOCK_REALTIME} clock. +@end table +@end deftypefun @deftypefun int adjtimex (struct timex *@var{timex}) @standards{GNU, sys/timex.h} @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c It's a syscall, only available on linux. +@code{adjtimex} is an older name for @code{ntp_adjtime}. +This function is only available on @gnulinuxsystems{}. +It is declared in @file{sys/timex.h}. +@end deftypefun + +@deftypefun int settimeofday (const struct timeval *@var{tp}, const void *@var{tzp}) +@standards{BSD, sys/time.h} +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +Change the @code{CLOCK_REALTIME} calendar time to be the simple +calendar time in @code{*@var{newtime}}. This function is declared in +@file{sys/time.h}. + +When @var{tzp} is a null pointer, calling this function is exactly the +same as calling @w{@samp{clock_settime (CLOCK_REALTIME)}}, except that +the new time can only be set to a precision of one microsecond. -@code{adjtimex} is functionally identical to @code{ntp_adjtime}. -@xref{High Accuracy Clock}. +When @var{tzp} is not a null pointer, the data it points to @emph{may} +be used to set a system-wide idea of the current timezone. This +feature is obsolete and not supported on @gnusystems{}. Instead, use +the facilities described in @ref{Time Zone Functions} and in +@ref{Broken-down Time} for working with time zones. + +The return value is @code{0} on success and @code{-1} on failure. The +following @code{errno} error conditions are defined for this function: -This function is present only with a Linux kernel. +@table @code +@item EPERM +This process does not have the privileges required to set the +@code{CLOCK_REALTIME} clock. +@item EINVAL +Neither @var{tp} nor @var{tzp} is a null pointer. (For historical +reasons, it is not possible to set the current time and the current +time zone in the same call.) + +@item ENOSYS +The operating system does not support setting time zone information, and +@var{tzp} is not a null pointer. +@end table @end deftypefun @node Broken-down Time @@ -605,13 +952,13 @@ This function is present only with a Linux kernel. @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. +Simple calendar times represent absolute times as elapsed times since +an epoch. 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. @@ -937,213 +1284,6 @@ the @code{TZ} environment variable to UTC, call @code{mktime}, then set -@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 - -@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr}) -@standards{GNU, sys/timex.h} -@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 - -@deftypefun int ntp_adjtime (struct timex *@var{tptr}) -@standards{GNU, sys/timex.h} -@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 @@ -2700,7 +2840,7 @@ 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}. +The @code{struct timeval} data type is described in @ref{Time Types}. @end deftp @deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old}) @@ -2885,7 +3025,7 @@ 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}. +@code{struct timespec} is described in @ref{Time Types}. If the function returns because the interval is over the return value is zero. If the function returns @math{-1} the global variable @code{errno} |