1: @node Date and Time, Resource Usage And Limitation, Arithmetic, Top
    2: @c %MENU% Functions for getting the date and time and formatting them nicely
    3: @chapter Date and Time
    4: 
    5: This chapter describes functions for manipulating dates and times,
    6: including functions for determining what time it is and conversion
    7: between different time representations.
    8: 
    9: @menu
   10: * Time Basics::                 Concepts and definitions.
   11: * Elapsed Time::                Data types to represent elapsed times
   12: * Processor And CPU Time::      Time a program has spent executing.
   13: * Calendar Time::               Manipulation of ``real'' dates and times.
   14: * Setting an Alarm::            Sending a signal after a specified time.
   15: * Sleeping::                    Waiting for a period of time.
   16: @end menu
   17: 
   18: 
   19: @node Time Basics
   20: @section Time Basics
   21: @cindex time
   22: 
   23: Discussing time in a technical manual can be difficult because the word
   24: ``time'' in English refers to lots of different things.  In this manual,
   25: we use a rigorous terminology to avoid confusion, and the only thing we
   26: use the simple word ``time'' for is to talk about the abstract concept.
   27: 
   28: A @dfn{calendar time} is a point in the time continuum, for example
   29: November 4, 1990 at 18:02.5 UTC.  Sometimes this is called ``absolute
   30: time''.
   31: @cindex calendar time
   32: 
   33: We don't speak of a ``date'', because that is inherent in a calendar
   34: time.
   35: @cindex date
   36: 
   37: An @dfn{interval} is a contiguous part of the time continuum between two
   38: calendar times, for example the hour between 9:00 and 10:00 on July 4,
   39: 1980.
   40: @cindex interval
   41: 
   42: An @dfn{elapsed time} is the length of an interval, for example, 35
   43: minutes.  People sometimes sloppily use the word ``interval'' to refer
   44: to the elapsed time of some interval.
   45: @cindex elapsed time
   46: @cindex time, elapsed
   47: 
   48: An @dfn{amount of time} is a sum of elapsed times, which need not be of
   49: any specific intervals.  For example, the amount of time it takes to
   50: read a book might be 9 hours, independently of when and in how many
   51: sittings it is read.
   52: 
   53: A @dfn{period} is the elapsed time of an interval between two events,
   54: especially when they are part of a sequence of regularly repeating
   55: events.
   56: @cindex period of time
   57: 
   58: @dfn{CPU time} is like calendar time, except that it is based on the
   59: subset of the time continuum when a particular process is actively
   60: using a CPU.  CPU time is, therefore, relative to a process.
   61: @cindex CPU time
   62: 
   63: @dfn{Processor time} is an amount of time that a CPU is in use.  In
   64: fact, it's a basic system resource, since there's a limit to how much
   65: can exist in any given interval (that limit is the elapsed time of the
   66: interval times the number of CPUs in the processor).  People often call
   67: this CPU time, but we reserve the latter term in this manual for the
   68: definition above.
   69: @cindex processor time
   70: 
   71: @node Elapsed Time
   72: @section Elapsed Time
   73: @cindex elapsed time
   74: 
   75: One way to represent an elapsed time is with a simple arithmetic data
   76: type, as with the following function to compute the elapsed time between
   77: two calendar times.  This function is declared in @file{time.h}.
   78: 
   79: @comment time.h
   80: @comment ISO
   81: @deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
   82: The @code{difftime} function returns the number of seconds of elapsed
   83: time between calendar time @var{time1} and calendar time @var{time0}, as
   84: a value of type @code{double}.  The difference ignores leap seconds
   85: unless leap second support is enabled.
   86: 
   87: In the GNU system, you can simply subtract @code{time_t} values.  But on
   88: other systems, the @code{time_t} data type might use some other encoding
   89: where subtraction doesn't work directly.
   90: @end deftypefun
   91: 
   92: The GNU C library provides two data types specifically for representing
   93: an elapsed time.  They are used by various GNU C library functions, and
   94: you can use them for your own purposes too.  They're exactly the same
   95: except that one has a resolution in microseconds, and the other, newer
   96: one, is in nanoseconds.
   97: 
   98: @comment sys/time.h
   99: @comment BSD
  100: @deftp {Data Type} {struct timeval}
  101: @cindex timeval
  102: The @code{struct timeval} structure represents an elapsed time.  It is
  103: declared in @file{sys/time.h} and has the following members:
  104: 
  105: @table @code
  106: @item long int tv_sec
  107: This represents the number of whole seconds of elapsed time.
  108: 
  109: @item long int tv_usec
  110: This is the rest of the elapsed time (a fraction of a second),
  111: represented as the number of microseconds.  It is always less than one
  112: million.
  113: 
  114: @end table
  115: @end deftp
  116: 
  117: @comment sys/time.h
  118: @comment POSIX.1
  119: @deftp {Data Type} {struct timespec}
  120: @cindex timespec
  121: The @code{struct timespec} structure represents an elapsed time.  It is
  122: declared in @file{time.h} and has the following members:
  123: 
  124: @table @code
  125: @item long int tv_sec
  126: This represents the number of whole seconds of elapsed time.
  127: 
  128: @item long int tv_nsec
  129: This is the rest of the elapsed time (a fraction of a second),
  130: represented as the number of nanoseconds.  It is always less than one
  131: billion.
  132: 
  133: @end table
  134: @end deftp
  135: 
  136: It is often necessary to subtract two values of type @w{@code{struct
  137: timeval}} or @w{@code{struct timespec}}.  Here is the best way to do
  138: this.  It works even on some peculiar operating systems where the
  139: @code{tv_sec} member has an unsigned type.
  140: 
  141: @smallexample
  142: /* @r{Subtract the `struct timeval' values X and Y,}
  143:    @r{storing the result in RESULT.}
  144:    @r{Return 1 if the difference is negative, otherwise 0.}  */
  145: 
  146: int
  147: timeval_subtract (result, x, y)
  148:      struct timeval *result, *x, *y;
  149: @{
  150:   /* @r{Perform the carry for the later subtraction by updating @var{y}.} */
  151:   if (x->tv_usec < y->tv_usec) @{
  152:     int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
  153:     y->tv_usec -= 1000000 * nsec;
  154:     y->tv_sec += nsec;
  155:   @}
  156:   if (x->tv_usec - y->tv_usec > 1000000) @{
  157:     int nsec = (x->tv_usec - y->tv_usec) / 1000000;
  158:     y->tv_usec += 1000000 * nsec;
  159:     y->tv_sec -= nsec;
  160:   @}
  161: 
  162:   /* @r{Compute the time remaining to wait.}
  163:      @r{@code{tv_usec} is certainly positive.} */
  164:   result->tv_sec = x->tv_sec - y->tv_sec;
  165:   result->tv_usec = x->tv_usec - y->tv_usec;
  166: 
  167:   /* @r{Return 1 if result is negative.} */
  168:   return x->tv_sec < y->tv_sec;
  169: @}
  170: @end smallexample
  171: 
  172: Common functions that use @code{struct timeval} are @code{gettimeofday}
  173: and @code{settimeofday}.
  174: 
  175: 
  176: There are no GNU C library functions specifically oriented toward
  177: dealing with elapsed times, but the calendar time, processor time, and
  178: alarm and sleeping functions have a lot to do with them.
  179: 
  180: 
  181: @node Processor And CPU Time
  182: @section Processor And CPU Time
  183: 
  184: If you're trying to optimize your program or measure its efficiency,
  185: it's very useful to know how much processor time it uses.  For that,
  186: calendar time and elapsed times are useless because a process may spend
  187: time waiting for I/O or for other processes to use the CPU.  However,
  188: you can get the information with the functions in this section.
  189: 
  190: CPU time (@pxref{Time Basics}) is represented by the data type
  191: @code{clock_t}, which is a number of @dfn{clock ticks}.  It gives the
  192: total amount of time a process has actively used a CPU since some
  193: arbitrary event.  On the GNU system, that event is the creation of the
  194: process.  While arbitrary in general, the event is always the same event
  195: for any particular process, so you can always measure how much time on
  196: the CPU a particular computation takes by examining the process' CPU
  197: time before and after the computation.
  198: @cindex CPU time
  199: @cindex clock ticks
  200: @cindex ticks, clock
  201: 
  202: In the GNU system, @code{clock_t} is equivalent to @code{long int} and
  203: @code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
  204: @code{clock_t} and the macro @code{CLOCKS_PER_SEC} can be either integer
  205: or floating-point types.  Casting CPU time values to @code{double}, as
  206: in the example above, makes sure that operations such as arithmetic and
  207: printing work properly and consistently no matter what the underlying
  208: representation is.
  209: 
  210: Note that the clock can wrap around.  On a 32bit system with
  211: @code{CLOCKS_PER_SEC} set to one million this function will return the
  212: same value approximately every 72 minutes.
  213: 
  214: For additional functions to examine a process' use of processor time,
  215: and to control it, @xref{Resource Usage And Limitation}.
  216: 
  217: 
  218: @menu
  219: * CPU Time::                    The @code{clock} function.
  220: * Processor Time::              The @code{times} function.
  221: @end menu
  222: 
  223: @node CPU Time
  224: @subsection CPU Time Inquiry
  225: 
  226: To get a process' CPU time, you can use the @code{clock} function.  This
  227: facility is declared in the header file @file{time.h}.
  228: @pindex time.h
  229: 
  230: In typical usage, you call the @code{clock} function at the beginning
  231: and end of the interval you want to time, subtract the values, and then
  232: divide by @code{CLOCKS_PER_SEC} (the number of clock ticks per second)
  233: to get processor time, like this:
  234: 
  235: @smallexample
  236: @group
  237: #include <time.h>
  238: 
  239: clock_t start, end;
  240: double cpu_time_used;
  241: 
  242: start = clock();
  243: @dots{} /* @r{Do the work.} */
  244: end = clock();
  245: cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
  246: @end group
  247: @end smallexample
  248: 
  249: Do not use a single CPU time as an amount of time; it doesn't work that
  250: way.  Either do a subtraction as shown above or query processor time
  251: directly.  @xref{Processor Time}.
  252: 
  253: Different computers and operating systems vary wildly in how they keep
  254: track of CPU time.  It's common for the internal processor clock
  255: to have a resolution somewhere between a hundredth and millionth of a
  256: second.
  257: 
  258: @comment time.h
  259: @comment ISO
  260: @deftypevr Macro int CLOCKS_PER_SEC
  261: The value of this macro is the number of clock ticks per second measured
  262: by the @code{clock} function.  POSIX requires that this value be one
  263: million independent of the actual resolution.
  264: @end deftypevr
  265: 
  266: @comment time.h
  267: @comment POSIX.1
  268: @deftypevr Macro int CLK_TCK
  269: This is an obsolete name for @code{CLOCKS_PER_SEC}.
  270: @end deftypevr
  271: 
  272: @comment time.h
  273: @comment ISO
  274: @deftp {Data Type} clock_t
  275: This is the type of the value returned by the @code{clock} function.
  276: Values of type @code{clock_t} are numbers of clock ticks.
  277: @end deftp
  278: 
  279: @comment time.h
  280: @comment ISO
  281: @deftypefun clock_t clock (void)
  282: This function returns the calling process' current CPU time.  If the CPU
  283: time is not available or cannot be represented, @code{clock} returns the
  284: value @code{(clock_t)(-1)}.
  285: @end deftypefun
  286: 
  287: 
  288: @node Processor Time
  289: @subsection Processor Time Inquiry
  290: 
  291: The @code{times} function returns information about a process'
  292: consumption of processor time in a @w{@code{struct tms}} object, in
  293: addition to the process' CPU time.  @xref{Time Basics}.  You should
  294: include the header file @file{sys/times.h} to use this facility.
  295: @cindex processor time
  296: @cindex CPU time
  297: @pindex sys/times.h
  298: 
  299: @comment sys/times.h
  300: @comment POSIX.1
  301: @deftp {Data Type} {struct tms}
  302: The @code{tms} structure is used to return information about process
  303: times.  It contains at least the following members:
  304: 
  305: @table @code
  306: @item clock_t tms_utime
  307: This is the total processor time the calling process has used in
  308: executing the instructions of its program.
  309: 
  310: @item clock_t tms_stime
  311: This is the processor time the system has used on behalf of the calling
  312: process.
  313: 
  314: @item clock_t tms_cutime
  315: This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
  316: values of all terminated child processes of the calling process, whose
  317: status has been reported to the parent process by @code{wait} or
  318: @code{waitpid}; see @ref{Process Completion}.  In other words, it
  319: represents the total processor time used in executing the instructions
  320: of all the terminated child processes of the calling process, excluding
  321: child processes which have not yet been reported by @code{wait} or
  322: @code{waitpid}.
  323: @cindex child process
  324: 
  325: @item clock_t tms_cstime
  326: This is similar to @code{tms_cutime}, but represents the total processor
  327: time system has used on behalf of all the terminated child processes
  328: of the calling process.
  329: @end table
  330: 
  331: All of the times are given in numbers of clock ticks.  Unlike CPU time,
  332: these are the actual amounts of time; not relative to any event.
  333: @xref{Creating a Process}.
  334: @end deftp
  335: 
  336: @comment sys/times.h
  337: @comment POSIX.1
  338: @deftypefun clock_t times (struct tms *@var{buffer})
  339: The @code{times} function stores the processor time information for
  340: the calling process in @var{buffer}.
  341: 
  342: The return value is the calling process' CPU time (the same value you
  343: get from @code{clock()}.  @code{times} returns @code{(clock_t)(-1)} to
  344: indicate failure.
  345: @end deftypefun
  346: 
  347: @strong{Portability Note:} The @code{clock} function described in
  348: @ref{CPU Time} is specified by the @w{ISO C} standard.  The
  349: @code{times} function is a feature of POSIX.1.  In the GNU system, the
  350: CPU time is defined to be equivalent to the sum of the @code{tms_utime}
  351: and @code{tms_stime} fields returned by @code{times}.
  352: 
  353: @node Calendar Time
  354: @section Calendar Time
  355: 
  356: This section describes facilities for keeping track of calendar time.
  357: @xref{Time Basics}.
  358: 
  359: The GNU C library represents calendar time three ways:
  360: 
  361: @itemize @bullet
  362: @item
  363: @dfn{Simple time} (the @code{time_t} data type) is a compact
  364: representation, typically giving the number of seconds of elapsed time
  365: since some implementation-specific base time.
  366: @cindex simple time
  367: 
  368: @item
  369: There is also a "high-resolution time" representation.  Like simple
  370: time, this represents a calendar time as an elapsed time since a base
  371: time, but instead of measuring in whole seconds, it uses a @code{struct
  372: timeval} data type, which includes fractions of a second.  Use this time
  373: representation instead of simple time when you need greater precision.
  374: @cindex high-resolution time
  375: 
  376: @item
  377: @dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data
  378: type) represents a calendar time as a set of components specifying the
  379: year, month, and so on in the Gregorian calendar, for a specific time
  380: zone.  This calendar time representation is usually used only to
  381: communicate with people.
  382: @cindex local time
  383: @cindex broken-down time
  384: @cindex Gregorian calendar
  385: @cindex calendar, Gregorian
  386: @end itemize
  387: 
  388: @menu
  389: * Simple Calendar Time::        Facilities for manipulating calendar time.
  390: * High-Resolution Calendar::    A time representation with greater precision.
  391: * Broken-down Time::            Facilities for manipulating local time.
  392: * High Accuracy Clock::         Maintaining a high accuracy system clock.
  393: * Formatting Calendar Time::    Converting times to strings.
  394: * Parsing Date and Time::       Convert textual time and date information back
  395:                                  into broken-down time values.
  396: * TZ Variable::                 How users specify the time zone.
  397: * Time Zone Functions::         Functions to examine or specify the time zone.
  398: * Time Functions Example::      An example program showing use of some of
  399:                                  the time functions.
  400: @end menu
  401: 
  402: @node Simple Calendar Time
  403: @subsection Simple Calendar Time
  404: 
  405: This section describes the @code{time_t} data type for representing calendar
  406: time as simple time, and the functions which operate on simple time objects.
  407: These facilities are declared in the header file @file{time.h}.
  408: @pindex time.h
  409: 
  410: @cindex epoch
  411: @comment time.h
  412: @comment ISO
  413: @deftp {Data Type} time_t
  414: This is the data type used to represent simple time.  Sometimes, it also
  415: represents an elapsed time.  When interpreted as a calendar time value,
  416: it represents the number of seconds elapsed since 00:00:00 on January 1,
  417: 1970, Coordinated Universal Time.  (This calendar time is sometimes
  418: referred to as the @dfn{epoch}.)  POSIX requires that this count not
  419: include leap seconds, but on some systems this count includes leap seconds
  420: if you set @code{TZ} to certain values (@pxref{TZ Variable}).
  421: 
  422: Note that a simple time has no concept of local time zone.  Calendar
  423: Time @var{T} is the same instant in time regardless of where on the
  424: globe the computer is.
  425: 
  426: In the GNU C library, @code{time_t} is equivalent to @code{long int}.
  427: In other systems, @code{time_t} might be either an integer or
  428: floating-point type.
  429: @end deftp
  430: 
  431: The function @code{difftime} tells you the elapsed time between two
  432: simple calendar times, which is not always as easy to compute as just
  433: subtracting.  @xref{Elapsed Time}.
  434: 
  435: @comment time.h
  436: @comment ISO
  437: @deftypefun time_t time (time_t *@var{result})
  438: The @code{time} function returns the current calendar time as a value of
  439: type @code{time_t}.  If the argument @var{result} is not a null pointer,
  440: the calendar time value is also stored in @code{*@var{result}}.  If the
  441: current calendar time is not available, the value
  442: @w{@code{(time_t)(-1)}} is returned.
  443: @end deftypefun
  444: 
  445: @c The GNU C library implements stime() with a call to settimeofday() on
  446: @c Linux.
  447: @comment time.h
  448: @comment SVID, XPG
  449: @deftypefun int stime (time_t *@var{newtime})
  450: @code{stime} sets the system clock, i.e., it tells the system that the
  451: current calendar time is @var{newtime}, where @code{newtime} is
  452: interpreted as described in the above definition of @code{time_t}.
  453: 
  454: @code{settimeofday} is a newer function which sets the system clock to
  455: better than one second precision.  @code{settimeofday} is generally a
  456: better choice than @code{stime}.  @xref{High-Resolution Calendar}.
  457: 
  458: Only the superuser can set the system clock.
  459: 
  460: If the function succeeds, the return value is zero.  Otherwise, it is
  461: @code{-1} and @code{errno} is set accordingly:
  462: 
  463: @table @code
  464: @item EPERM
  465: The process is not superuser.
  466: @end table
  467: @end deftypefun
  468: 
  469: 
  470: 
  471: @node High-Resolution Calendar
  472: @subsection High-Resolution Calendar
  473: 
  474: The @code{time_t} data type used to represent simple times has a
  475: resolution of only one second.  Some applications need more precision.
  476: 
  477: So, the GNU C library also contains functions which are capable of
  478: representing calendar times to a higher resolution than one second.  The
  479: functions and the associated data types described in this section are
  480: declared in @file{sys/time.h}.
  481: @pindex sys/time.h
  482: 
  483: @comment sys/time.h
  484: @comment BSD
  485: @deftp {Data Type} {struct timezone}
  486: The @code{struct timezone} structure is used to hold minimal information
  487: about the local time zone.  It has the following members:
  488: 
  489: @table @code
  490: @item int tz_minuteswest
  491: This is the number of minutes west of UTC.
  492: 
  493: @item int tz_dsttime
  494: If nonzero, Daylight Saving Time applies during some part of the year.
  495: @end table
  496: 
  497: The @code{struct timezone} type is obsolete and should never be used.
  498: Instead, use the facilities described in @ref{Time Zone Functions}.
  499: @end deftp
  500: 
  501: @comment sys/time.h
  502: @comment BSD
  503: @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
  504: The @code{gettimeofday} function returns the current calendar time as
  505: the elapsed time since the epoch in the @code{struct timeval} structure
  506: indicated by @var{tp}.  (@pxref{Elapsed Time} for a description of
  507: @code{struct timeval}).  Information about the time zone is returned in
  508: the structure pointed at @var{tzp}.  If the @var{tzp} argument is a null
  509: pointer, time zone information is ignored.
  510: 
  511: The return value is @code{0} on success and @code{-1} on failure.  The
  512: following @code{errno} error condition is defined for this function:
  513: 
  514: @table @code
  515: @item ENOSYS
  516: The operating system does not support getting time zone information, and
  517: @var{tzp} is not a null pointer.  The GNU operating system does not
  518: support using @w{@code{struct timezone}} to represent time zone
  519: information; that is an obsolete feature of 4.3 BSD.
  520: Instead, use the facilities described in @ref{Time Zone Functions}.
  521: @end table
  522: @end deftypefun
  523: 
  524: @comment sys/time.h
  525: @comment BSD
  526: @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
  527: The @code{settimeofday} function sets the current calendar time in the
  528: system clock according to the arguments.  As for @code{gettimeofday},
  529: the calendar time is represented as the elapsed time since the epoch.
  530: As for @code{gettimeofday}, time zone information is ignored if
  531: @var{tzp} is a null pointer.
  532: 
  533: You must be a privileged user in order to use @code{settimeofday}.
  534: 
  535: Some kernels automatically set the system clock from some source such as
  536: a hardware clock when they start up.  Others, including Linux, place the
  537: system clock in an ``invalid'' state (in which attempts to read the clock
  538: fail).  A call of @code{stime} removes the system clock from an invalid
  539: state, and system startup scripts typically run a program that calls
  540: @code{stime}.
  541: 
  542: @code{settimeofday} causes a sudden jump forwards or backwards, which
  543: can cause a variety of problems in a system.  Use @code{adjtime} (below)
  544: to make a smooth transition from one time to another by temporarily
  545: speeding up or slowing down the clock.
  546: 
  547: With a Linux kernel, @code{adjtimex} does the same thing and can also
  548: make permanent changes to the speed of the system clock so it doesn't
  549: need to be corrected as often.
  550: 
  551: The return value is @code{0} on success and @code{-1} on failure.  The
  552: following @code{errno} error conditions are defined for this function:
  553: 
  554: @table @code
  555: @item EPERM
  556: This process cannot set the clock because it is not privileged.
  557: 
  558: @item ENOSYS
  559: The operating system does not support setting time zone information, and
  560: @var{tzp} is not a null pointer.
  561: @end table
  562: @end deftypefun
  563: 
  564: @c On Linux, GNU libc implements adjtime() as a call to adjtimex().
  565: @comment sys/time.h
  566: @comment BSD
  567: @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
  568: This function speeds up or slows down the system clock in order to make
  569: a gradual adjustment.  This ensures that the calendar time reported by
  570: the system clock is always monotonically increasing, which might not
  571: happen if you simply set the clock.
  572: 
  573: The @var{delta} argument specifies a relative adjustment to be made to
  574: the clock time.  If negative, the system clock is slowed down for a
  575: while until it has lost this much elapsed time.  If positive, the system
  576: clock is speeded up for a while.
  577: 
  578: If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
  579: function returns information about any previous time adjustment that
  580: has not yet completed.
  581: 
  582: This function is typically used to synchronize the clocks of computers
  583: in a local network.  You must be a privileged user to use it.
  584: 
  585: With a Linux kernel, you can use the @code{adjtimex} function to
  586: permanently change the clock speed.
  587: 
  588: The return value is @code{0} on success and @code{-1} on failure.  The
  589: following @code{errno} error condition is defined for this function:
  590: 
  591: @table @code
  592: @item EPERM
  593: You do not have privilege to set the time.
  594: @end table
  595: @end deftypefun
  596: 
  597: @strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
  598: and @code{adjtime} functions are derived from BSD.
  599: 
  600: 
  601: Symbols for the following function are declared in @file{sys/timex.h}.
  602: 
  603: @comment sys/timex.h
  604: @comment GNU
  605: @deftypefun int adjtimex (struct timex *@var{timex})
  606: 
  607: @code{adjtimex} is functionally identical to @code{ntp_adjtime}.
  608: @xref{High Accuracy Clock}.
  609: 
  610: This function is present only with a Linux kernel.
  611: 
  612: @end deftypefun
  613: 
  614: @node Broken-down Time
  615: @subsection Broken-down Time
  616: @cindex broken-down time
  617: @cindex calendar time and broken-down time
  618: 
  619: Calendar time is represented by the usual GNU C library functions as an
  620: elapsed time since a fixed base calendar time.  This is convenient for
  621: computation, but has no relation to the way people normally think of
  622: calendar time.  By contrast, @dfn{broken-down time} is a binary
  623: representation of calendar time separated into year, month, day, and so
  624: on.  Broken-down time values are not useful for calculations, but they
  625: are useful for printing human readable time information.
  626: 
  627: A broken-down time value is always relative to a choice of time
  628: zone, and it also indicates which time zone that is.
  629: 
  630: The symbols in this section are declared in the header file @file{time.h}.
  631: 
  632: @comment time.h
  633: @comment ISO
  634: @deftp {Data Type} {struct tm}
  635: This is the data type used to represent a broken-down time.  The structure
  636: contains at least the following members, which can appear in any order.
  637: 
  638: @table @code
  639: @item int tm_sec
  640: This is the number of full seconds since the top of the minute (normally
  641: in the range @code{0} through @code{59}, but the actual upper limit is
  642: @code{60}, to allow for leap seconds if leap second support is
  643: available).
  644: @cindex leap second
  645: 
  646: @item int tm_min
  647: This is the number of full minutes since the top of the hour (in the
  648: range @code{0} through @code{59}).
  649: 
  650: @item int tm_hour
  651: This is the number of full hours past midnight (in the range @code{0} through
  652: @code{23}).
  653: 
  654: @item int tm_mday
  655: This is the ordinal day of the month (in the range @code{1} through @code{31}).
  656: Watch out for this one!  As the only ordinal number in the structure, it is
  657: inconsistent with the rest of the structure.
  658: 
  659: @item int tm_mon
  660: This is the number of full calendar months since the beginning of the
  661: year (in the range @code{0} through @code{11}).  Watch out for this one!
  662: People usually use ordinal numbers for month-of-year (where January = 1).
  663: 
  664: @item int tm_year
  665: This is the number of full calendar years since 1900.
  666: 
  667: @item int tm_wday
  668: This is the number of full days since Sunday (in the range @code{0} through
  669: @code{6}).
  670: 
  671: @item int tm_yday
  672: This is the number of full days since the beginning of the year (in the
  673: range @code{0} through @code{365}).
  674: 
  675: @item int tm_isdst
  676: @cindex Daylight Saving Time
  677: @cindex summer time
  678: This is a flag that indicates whether Daylight Saving Time is (or was, or
  679: will be) in effect at the time described.  The value is positive if
  680: Daylight Saving Time is in effect, zero if it is not, and negative if the
  681: information is not available.
  682: 
  683: @item long int tm_gmtoff
  684: This field describes the time zone that was used to compute this
  685: broken-down time value, including any adjustment for daylight saving; it
  686: is the number of seconds that you must add to UTC to get local time.
  687: You can also think of this as the number of seconds east of UTC.  For
  688: example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}.
  689: The @code{tm_gmtoff} field is derived from BSD and is a GNU library
  690: extension; it is not visible in a strict @w{ISO C} environment.
  691: 
  692: @item const char *tm_zone
  693: This field is the name for the time zone that was used to compute this
  694: broken-down time value.  Like @code{tm_gmtoff}, this field is a BSD and
  695: GNU extension, and is not visible in a strict @w{ISO C} environment.
  696: @end table
  697: @end deftp
  698: 
  699: 
  700: @comment time.h
  701: @comment ISO
  702: @deftypefun {struct tm *} localtime (const time_t *@var{time})
  703: The @code{localtime} function converts the simple time pointed to by
  704: @var{time} to broken-down time representation, expressed relative to the
  705: user's specified time zone.
  706: 
  707: The return value is a pointer to a static broken-down time structure, which
  708: might be overwritten by subsequent calls to @code{ctime}, @code{gmtime},
  709: or @code{localtime}.  (But no other library function overwrites the contents
  710: of this object.)
  711: 
  712: The return value is the null pointer if @var{time} cannot be represented
  713: as a broken-down time; typically this is because the year cannot fit into
  714: an @code{int}.
  715: 
  716: Calling @code{localtime} has one other effect: it sets the variable
  717: @code{tzname} with information about the current time zone.  @xref{Time
  718: Zone Functions}.
  719: @end deftypefun
  720: 
  721: Using the @code{localtime} function is a big problem in multi-threaded
  722: programs.  The result is returned in a static buffer and this is used in
  723: all threads.  POSIX.1c introduced a variant of this function.
  724: 
  725: @comment time.h
  726: @comment POSIX.1c
  727: @deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp})
  728: The @code{localtime_r} function works just like the @code{localtime}
  729: function.  It takes a pointer to a variable containing a simple time
  730: and converts it to the broken-down time format.
  731: 
  732: But the result is not placed in a static buffer.  Instead it is placed
  733: in the object of type @code{struct tm} to which the parameter
  734: @var{resultp} points.
  735: 
  736: If the conversion is successful the function returns a pointer to the
  737: object the result was written into, i.e., it returns @var{resultp}.
  738: @end deftypefun
  739: 
  740: 
  741: @comment time.h
  742: @comment ISO
  743: @deftypefun {struct tm *} gmtime (const time_t *@var{time})
  744: This function is similar to @code{localtime}, except that the broken-down
  745: time is expressed as Coordinated Universal Time (UTC) (formerly called
  746: Greenwich Mean Time (GMT)) rather than relative to a local time zone.
  747: 
  748: @end deftypefun
  749: 
  750: As for the @code{localtime} function we have the problem that the result
  751: is placed in a static variable.  POSIX.1c also provides a replacement for
  752: @code{gmtime}.
  753: 
  754: @comment time.h
  755: @comment POSIX.1c
  756: @deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp})
  757: This function is similar to @code{localtime_r}, except that it converts
  758: just like @code{gmtime} the given time as Coordinated Universal Time.
  759: 
  760: If the conversion is successful the function returns a pointer to the
  761: object the result was written into, i.e., it returns @var{resultp}.
  762: @end deftypefun
  763: 
  764: 
  765: @comment time.h
  766: @comment ISO
  767: @deftypefun time_t mktime (struct tm *@var{brokentime})
  768: The @code{mktime} function is used to convert a broken-down time structure
  769: to a simple time representation.  It also ``normalizes'' the contents of
  770: the broken-down time structure, by filling in the day of week and day of