   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Complications in Subexpression Matching
---------------------------------------

   Sometimes a subexpression matches a substring of no characters.  This
happens when `f\(o*\)' matches the string `fum'.  (It really matches
just the `f'.)  In this case, both of the offsets identify the point in
the string where the null substring was found.  In this example, the
offsets are both `1'.

   Sometimes the entire regular expression can match without using some
of its subexpressions at all--for example, when `ba\(na\)*' matches the
string `ba', the parenthetical subexpression is not used.  When this
happens, `regexec' stores `-1' in both fields of the element for that
subexpression.

   Sometimes matching the entire regular expression can match a
particular subexpression more than once--for example, when `ba\(na\)*'
matches the string `bananana', the parenthetical subexpression matches
three times.  When this happens, `regexec' usually stores the offsets
of the last part of the string that matched the subexpression.  In the
case of `bananana', these offsets are `6' and `8'.

   But the last match is not always the one that is chosen.  It's more
accurate to say that the last *opportunity* to match is the one that
takes precedence.  What this means is that when one subexpression
appears within another, then the results reported for the inner
subexpression reflect whatever happened on the last match of the outer
subexpression.  For an example, consider `\(ba\(na\)*s \)*' matching
the string `bananas bas '.  The last time the inner expression actually
matches is near the end of the first word.  But it is *considered*
again in the second word, and fails to match there.  `regexec' reports
nonuse of the "na" subexpression.

   Another place where this rule applies is when the regular expression
`\(ba\(na\)*s \|nefer\(ti\)* \)*' matches `bananas nefertiti'.  The
"na" subexpression does match in the first word, but it doesn't match
in the second word because the other alternative is used there.  Once
again, the second repetition of the outer subexpression overrides the
first, and within that second repetition, the "na" subexpression is not
used.  So `regexec' reports nonuse of the "na" subexpression.

POSIX Regexp Matching Cleanup
-----------------------------

   When you are finished using a compiled regular expression, you can
free the storage it uses by calling `regfree'.

 - Function: void regfree (regex_t *COMPILED)
     Calling `regfree' frees all the storage that `*COMPILED' points
     to.  This includes various internal fields of the `regex_t'
     structure that aren't documented in this manual.

     `regfree' does not free the object `*COMPILED' itself.

   You should always free the space in a `regex_t' structure with
`regfree' before using the structure to compile another regular
expression.

   When `regcomp' or `regexec' reports an error, you can use the
function `regerror' to turn it into an error message string.

 - Function: size_t regerror (int ERRCODE, regex_t *COMPILED, char
          *BUFFER, size_t LENGTH)
     This function produces an error message string for the error code
     ERRCODE, and stores the string in LENGTH bytes of memory starting
     at BUFFER.  For the COMPILED argument, supply the same compiled
     regular expression structure that `regcomp' or `regexec' was
     working with when it got the error.  Alternatively, you can supply
     `NULL' for COMPILED; you will still get a meaningful error
     message, but it might not be as detailed.

     If the error message can't fit in LENGTH bytes (including a
     terminating null character), then `regerror' truncates it.  The
     string that `regerror' stores is always null-terminated even if it
     has been truncated.

     The return value of `regerror' is the minimum length needed to
     store the entire error message.  If this is less than LENGTH, then
     the error message was not truncated, and you can use it.
     Otherwise, you should call `regerror' again with a larger buffer.

     Here is a function which uses `regerror', but always dynamically
     allocates a buffer for the error message:

          char *get_regerror (int errcode, regex_t *compiled)
          {
            size_t length = regerror (errcode, compiled, NULL, 0);
            char *buffer = xmalloc (length);
            (void) regerror (errcode, compiled, buffer, length);
            return buffer;
          }

Shell-Style Word Expansion
==========================

   "Word expansion" means the process of splitting a string into
"words" and substituting for variables, commands, and wildcards just as
the shell does.

   For example, when you write `ls -l foo.c', this string is split into
three separate words--`ls', `-l' and `foo.c'.  This is the most basic
function of word expansion.

   When you write `ls *.c', this can become many words, because the
word `*.c' can be replaced with any number of file names.  This is
called "wildcard expansion", and it is also a part of word expansion.

   When you use `echo $PATH' to print your path, you are taking
advantage of "variable substitution", which is also part of word
expansion.

   Ordinary programs can perform word expansion just like the shell by
calling the library function `wordexp'.

The Stages of Word Expansion
----------------------------

   When word expansion is applied to a sequence of words, it performs
the following transformations in the order shown here:

  1. "Tilde expansion": Replacement of `~foo' with the name of the home
     directory of `foo'.

  2. Next, three different transformations are applied in the same step,
     from left to right:

        * "Variable substitution": Environment variables are
          substituted for references such as `$foo'.

        * "Command substitution": Constructs such as ``cat foo`' and
          the equivalent `$(cat foo)' are replaced with the output from
          the inner command.

        * "Arithmetic expansion": Constructs such as `$(($x-1))' are
          replaced with the result of the arithmetic computation.

  3. "Field splitting": subdivision of the text into "words".

  4. "Wildcard expansion": The replacement of a construct such as `*.c'
     with a list of `.c' file names.  Wildcard expansion applies to an
     entire word at a time, and replaces that word with 0 or more file
     names that are themselves words.

  5. "Quote removal": The deletion of string-quotes, now that they have
     done their job by inhibiting the above transformations when
     appropriate.

   For the details of these transformations, and how to write the
constructs that use them, see `The BASH Manual' (to appear).

Calling `wordexp'
-----------------

   All the functions, constants and data types for word expansion are
declared in the header file `wordexp.h'.

   Word expansion produces a vector of words (strings).  To return this
vector, `wordexp' uses a special data type, `wordexp_t', which is a
structure.  You pass `wordexp' the address of the structure, and it
fills in the structure's fields to tell you about the results.

 - Data Type: wordexp_t
     This data type holds a pointer to a word vector.  More precisely,
     it records both the address of the word vector and its size.

    `we_wordc'
          The number of elements in the vector.

    `we_wordv'
          The address of the vector.  This field has type `char **'.

    `we_offs'
          The offset of the first real element of the vector, from its
          nominal address in the `we_wordv' field.  Unlike the other
          fields, this is always an input to `wordexp', rather than an
          output from it.

          If you use a nonzero offset, then that many elements at the
          beginning of the vector are left empty.  (The `wordexp'
          function fills them with null pointers.)

          The `we_offs' field is meaningful only if you use the
          `WRDE_DOOFFS' flag.  Otherwise, the offset is always zero
          regardless of what is in this field, and the first real
          element comes at the beginning of the vector.

 - Function: int wordexp (const char *WORDS, wordexp_t
          *WORD-VECTOR-PTR, int FLAGS)
     Perform word expansion on the string WORDS, putting the result in
     a newly allocated vector, and store the size and address of this
     vector into `*WORD-VECTOR-PTR'.  The argument FLAGS is a
     combination of bit flags; see Flags for Wordexp, for
     details of the flags.

     You shouldn't use any of the characters `|&;<>' in the string
     WORDS unless they are quoted; likewise for newline.  If you use
     these characters unquoted, you will get the `WRDE_BADCHAR' error
     code.  Don't use parentheses or braces unless they are quoted or
     part of a word expansion construct.  If you use quotation
     characters `'"`', they should come in pairs that balance.

     The results of word expansion are a sequence of words.  The
     function `wordexp' allocates a string for each resulting word, then
     allocates a vector of type `char **' to store the addresses of
     these strings.  The last element of the vector is a null pointer.
     This vector is called the "word vector".

     To return this vector, `wordexp' stores both its address and its
     length (number of elements, not counting the terminating null
     pointer) into `*WORD-VECTOR-PTR'.

     If `wordexp' succeeds, it returns 0.  Otherwise, it returns one of
     these error codes:

    `WRDE_BADCHAR'
          The input string WORDS contains an unquoted invalid character
          such as `|'.

    `WRDE_BADVAL'
          The input string refers to an undefined shell variable, and
          you used the flag `WRDE_UNDEF' to forbid such references.

    `WRDE_CMDSUB'
          The input string uses command substitution, and you used the
          flag `WRDE_NOCMD' to forbid command substitution.

    `WRDE_NOSPACE'
          It was impossible to allocate memory to hold the result.  In
          this case, `wordexp' can store part of the results--as much
          as it could allocate room for.

    `WRDE_SYNTAX'
          There was a syntax error in the input string.  For example,
          an unmatched quoting character is a syntax error.

 - Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
     Free the storage used for the word-strings and vector that
     `*WORD-VECTOR-PTR' points to.  This does not free the structure
     `*WORD-VECTOR-PTR' itself--only the other data it points to.

Flags for Word Expansion
------------------------

   This section describes the flags that you can specify in the FLAGS
argument to `wordexp'.  Choose the flags you want, and combine them
with the C operator `|'.

`WRDE_APPEND'
     Append the words from this expansion to the vector of words
     produced by previous calls to `wordexp'.  This way you can
     effectively expand several words as if they were concatenated with
     spaces between them.

     In order for appending to work, you must not modify the contents
     of the word vector structure between calls to `wordexp'.  And, if
     you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
     set it when you append to the results.

`WRDE_DOOFFS'
     Leave blank slots at the beginning of the vector of words.  The
     `we_offs' field says how many slots to leave.  The blank slots
     contain null pointers.

`WRDE_NOCMD'
     Don't do command substitution; if the input requests command
     substitution, report an error.

`WRDE_REUSE'
     Reuse a word vector made by a previous call to `wordexp'.  Instead
     of allocating a new vector of words, this call to `wordexp' will
     use the vector that already exists (making it larger if necessary).

     Note that the vector may move, so it is not safe to save an old
     pointer and use it again after calling `wordexp'.  You must fetch
     `we_pathv' anew after each call.

`WRDE_SHOWERR'
     Do show any error messages printed by commands run by command
     substitution.  More precisely, allow these commands to inherit the
     standard error output stream of the current process.  By default,
     `wordexp' gives these commands a standard error stream that
     discards all output.

`WRDE_UNDEF'
     If the input refers to a shell variable that is not defined,
     report an error.

`wordexp' Example
-----------------

   Here is an example of using `wordexp' to expand several strings and
use the results to run a shell command.  It also shows the use of
`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
the space allocated by `wordexp'.

     int
     expand_and_execute (const char *program, const char *options)
     {
       wordexp_t result;
       pid_t pid
       int status, i;

       /* Expand the string for the program to run.  */
       switch (wordexp (program, &result, 0))
         {
         case 0:			/* Successful.  */
           break;
         case WRDE_NOSPACE:
           /* If the error was `WRDE_NOSPACE',
              then perhaps part of the result was allocated.  */
           wordfree (&result);
         default:                    /* Some other error.  */
           return -1;
         }

       /* Expand the strings specified for the arguments.  */
       for (i = 0; args[i]; i++)
         {
           if (wordexp (options, &result, WRDE_APPEND))
             {
               wordfree (&result);
               return -1;
             }
         }

       pid = fork ();
       if (pid == 0)
         {
           /* This is the child process.  Execute the command. */
           execv (result.we_wordv[0], result.we_wordv);
           exit (EXIT_FAILURE);
         }
       else if (pid < 0)
         /* The fork failed.  Report failure.  */
         status = -1;
       else
         /* This is the parent process.  Wait for the child to complete.  */
         if (waitpid (pid, &status, 0) != pid)
           status = -1;

       wordfree (&result);
       return status;
     }

   In practice, since `wordexp' is executed by running a subshell, it
would be faster to do this by concatenating the strings with spaces
between them and running that as a shell command using `sh -c'.

Date and Time
*************

   This chapter describes functions for manipulating dates and times,
including functions for determining what the current time is and
conversion between different time representations.

   The time functions fall into three main categories:

   * Functions for measuring elapsed CPU time are discussed in
     Processor Time.

   * Functions for measuring absolute clock or calendar time are
     discussed in Calendar Time.

   * Functions for setting alarms and timers are discussed in
     Setting an Alarm.

Processor Time
==============

   If you're trying to optimize your program or measure its efficiency,
it's very useful to be able to know how much "processor time" or "CPU
time" it has used at any given point.  Processor time is different from
actual wall clock time because it doesn't include any time spent waiting
for I/O or when some other process is running.  Processor time is
represented by the data type `clock_t', and is given as a number of
"clock ticks" relative to an arbitrary base time marking the beginning
of a single program invocation.

Basic CPU Time Inquiry
----------------------

   To get the elapsed CPU time used by a process, you can use the
`clock' function.  This facility is declared in the header file
`time.h'.

   In typical usage, you call the `clock' function at the beginning and
end of the interval you want to time, subtract the values, and then
divide by `CLOCKS_PER_SEC' (the number of clock ticks per second), like
this:

     #include <time.h>

     clock_t start, end;
     double elapsed;

     start = clock();
     ... /* Do the work. */
     end = clock();
     elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;

   Different computers and operating systems vary wildly in how they
keep track of processor time.  It's common for the internal processor
clock to have a resolution somewhere between hundredths and millionths
of a second.

   In the GNU system, `clock_t' is equivalent to `long int' and
`CLOCKS_PER_SEC' is an integer value.  But in other systems, both
`clock_t' and the type of the macro `CLOCKS_PER_SEC' can be either
integer or floating-point types.  Casting processor time values to
`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.

 - Macro: int CLOCKS_PER_SEC
     The value of this macro is the number of clock ticks per second
     measured by the `clock' function.

 - Macro: int CLK_TCK
     This is an obsolete name for `CLOCKS_PER_SEC'.

 - Data Type: clock_t
     This is the type of the value returned by the `clock' function.
     Values of type `clock_t' are in units of clock ticks.

 - Function: clock_t clock (void)
     This function returns the elapsed processor time.  The base time is
     arbitrary but doesn't change within a single process.  If the
     processor time is not available or cannot be represented, `clock'
     returns the value `(clock_t)(-1)'.

Detailed Elapsed CPU Time Inquiry
---------------------------------

   The `times' function returns more detailed information about elapsed
processor time in a `struct tms' object.  You should include the header
file `sys/times.h' to use this facility.

 - Data Type: struct tms
     The `tms' structure is used to return information about process
     times.  It contains at least the following members:

    `clock_t tms_utime'
          This is the CPU time used in executing the instructions of
          the calling process.

    `clock_t tms_stime'
          This is the CPU time used by the system on behalf of the
          calling process.

    `clock_t tms_cutime'
          This is the sum of the `tms_utime' values and the `tms_cutime'
          values of all terminated child processes of the calling
          process, whose status has been reported to the parent process
          by `wait' or `waitpid'; see Process Completion.  In
          other words, it represents the total CPU 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 `wait' or `waitpid'.

    `clock_t tms_cstime'
          This is similar to `tms_cutime', but represents the total CPU
          time used by the system on behalf of all the terminated child
          processes of the calling process.

     All of the times are given in clock ticks.  These are absolute
     values; in a newly created process, they are all zero.  See
     Creating a Process.

 - Function: clock_t times (struct tms *BUFFER)
     The `times' function stores the processor time information for the
     calling process in BUFFER.

     The return value is the same as the value of `clock()': the elapsed
     real time relative to an arbitrary base.  The base is a constant
     within a particular process, and typically represents the time
     since system start-up.  A value of `(clock_t)(-1)' is returned to
     indicate failure.

   *Portability Note:* The `clock' function described in Basic CPU Time,
is specified by the ISO C standard.  The `times' function
is a feature of POSIX.1.  In the GNU system, the value returned by the
`clock' function is equivalent to the sum of the `tms_utime' and
`tms_stime' fields returned by `times'.

Calendar Time
=============

   This section describes facilities for keeping track of dates and
times according to the Gregorian calendar.

   There are three representations for date and time information:

   * "Calendar time" (the `time_t' data type) is a compact
     representation, typically giving the number of seconds elapsed
     since some implementation-specific base time.

   * There is also a "high-resolution time" representation (the `struct
     timeval' data type) that includes fractions of a second.  Use this
     time representation instead of ordinary calendar time when you
     need greater precision.

   * "Local time" or "broken-down time" (the `struct tm' data type)
     represents the date and time as a set of components specifying the
     year, month, and so on, for a specific time zone.  This time
     representation is usually used in conjunction with formatting date
     and time values.

Simple Calendar Time
--------------------

   This section describes the `time_t' data type for representing
calendar time, and the functions which operate on calendar time objects.
These facilities are declared in the header file `time.h'.

 - Data Type: time_t
     This is the data type used to represent calendar time.  When
     interpreted as an absolute time value, it represents the number of
     seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
     Universal Time.  (This date is sometimes referred to as the
     "epoch".)  POSIX requires that this count ignore leap seconds, but
     on some hosts this count includes leap seconds if you set `TZ' to
     certain values (see TZ Variable.).

     In the GNU C library, `time_t' is equivalent to `long int'.  In
     other systems, `time_t' might be either an integer or
     floating-point type.

 - Function: double difftime (time_t TIME1, time_t TIME0)
     The `difftime' function returns the number of seconds elapsed
     between time TIME1 and time TIME0, as a value of type `double'.
     The difference ignores leap seconds unless leap second support is
     enabled.

     In the GNU system, you can simply subtract `time_t' values.  But on
     other systems, the `time_t' data type might use some other encoding
     where subtraction doesn't work directly.

 - Function: time_t time (time_t *RESULT)
     The `time' function returns the current time as a value of type
     `time_t'.  If the argument RESULT is not a null pointer, the time
     value is also stored in `*RESULT'.  If the calendar time is not
     available, the value `(time_t)(-1)' is returned.

High-Resolution Calendar
------------------------

   The `time_t' data type used to represent calendar times has a
resolution of only one second.  Some applications need more precision.

   So, the GNU C library 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 `sys/time.h'.

 - Data Type: struct timeval
     The `struct timeval' structure represents a calendar time.  It has
     the following members:

    `long int tv_sec'
          This represents the number of seconds since the epoch.  It is
          equivalent to a normal `time_t' value.

    `long int tv_usec'
          This is the fractional second value, represented as the
          number of microseconds.

          Some times struct timeval values are used for time intervals.
          Then the `tv_sec' member is the number of seconds in the
          interval, and `tv_usec' is the number of additional
          microseconds.

 - Data Type: struct timezone
     The `struct timezone' structure is used to hold minimal information
     about the local time zone.  It has the following members:

    `int tz_minuteswest'
          This is the number of minutes west of UTC.

    `int tz_dsttime'
          If nonzero, daylight saving time applies during some part of
          the year.

     The `struct timezone' type is obsolete and should never be used.
     Instead, use the facilities described in Time Zone Functions.

   It is often necessary to subtract two values of type
`struct timeval'.  Here is the best way to do this.  It works even on
some peculiar operating systems where the `tv_sec' member has an
unsigned type.

     /* Subtract the `struct timeval' values X and Y,
        storing the result in RESULT.
        Return 1 if the difference is negative, otherwise 0.  */

     int
     timeval_subtract (result, x, y)
          struct timeval *result, *x, *y;
     {
       /* Perform the carry for the later subtraction by updating Y. */
       if (x->tv_usec < y->tv_usec) {
         int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
         y->tv_usec -= 1000000 * nsec;
         y->tv_sec += nsec;
       }
       if (x->tv_usec - y->tv_usec > 1000000) {
         int nsec = (y->tv_usec - x->tv_usec) / 1000000;
         y->tv_usec += 1000000 * nsec;
         y->tv_sec -= nsec;
       }

       /* Compute the time remaining to wait.
          `tv_usec' is certainly positive. */
       result->tv_sec = x->tv_sec - y->tv_sec;
       result->tv_usec = x->tv_usec - y->tv_usec;

       /* Return 1 if result is negative. */
       return x->tv_sec < y->tv_sec;
     }

 - Function: int gettimeofday (struct timeval *TP, struct timezone *TZP)
     The `gettimeofday' function returns the current date and time in
     the `struct timeval' structure indicated by TP.  Information about
     the time zone is returned in the structure pointed at TZP.  If the
     TZP argument is a null pointer, time zone information is ignored.

     The return value is `0' on success and `-1' on failure.  The
     following `errno' error condition is defined for this function:

    `ENOSYS'
          The operating system does not support getting time zone
          information, and TZP is not a null pointer.  The GNU
          operating system does not support using `struct timezone' to
          represent time zone information; that is an obsolete feature
          of 4.3 BSD.  Instead, use the facilities described in
          Time Zone Functions.

 - Function: int settimeofday (const struct timeval *TP, const struct
          timezone *TZP)
     The `settimeofday' function sets the current date and time
     according to the arguments.  As for `gettimeofday', time zone
     information is ignored if TZP is a null pointer.

     You must be a privileged user in order to use `settimeofday'.

     The return value is `0' on success and `-1' on failure.  The
     following `errno' error conditions are defined for this function:

    `EPERM'
          This process cannot set the time because it is not privileged.

    `ENOSYS'
          The operating system does not support setting time zone
          information, and TZP is not a null pointer.

 - Function: int adjtime (const struct timeval *DELTA, struct timeval
          *OLDDELTA)
     This function speeds up or slows down the system clock in order to
     make gradual adjustments in the current time.  This ensures that
     the time reported by the system clock is always monotonically
     increasing, which might not happen if you simply set the current
     time.

     The DELTA argument specifies a relative adjustment to be made to
     the current time.  If negative, the system clock is slowed down
     for a while until it has lost this much time.  If positive, the
     system clock is speeded up for a while.

     If the OLDDELTA argument is not a null pointer, the `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.  The return value is `0' on success and `-1' on failure.
     The following `errno' error condition is defined for this function:

    `EPERM'
          You do not have privilege to set the time.

   *Portability Note:*  The `gettimeofday', `settimeofday', and
`adjtime' functions are derived from BSD.

Broken-down Time
----------------

   Calendar time is represented as a number of seconds.  This is
convenient for calculation, but has no resemblance to the way people
normally represent dates and times.  By contrast, "broken-down time" is
a binary representation 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.

   A broken-down time value is always relative to a choice of local time
zone, and it also indicates which time zone was used.

   The symbols in this section are declared in the header file `time.h'.

 - 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:

    `int tm_sec'
          This is the number of seconds after the minute, normally in
          the range `0' through `59'.  (The actual upper limit is `60',
          to allow for leap seconds if leap second support is
          available.)

    `int tm_min'
          This is the number of minutes after the hour, in the range
          `0' through `59'.

    `int tm_hour'
          This is the number of hours past midnight, in the range `0'
          through `23'.

    `int tm_mday'
          This is the day of the month, in the range `1' through `31'.

    `int tm_mon'
          This is the number of months since January, in the range `0'
          through `11'.

    `int tm_year'
          This is the number of years since `1900'.

    `int tm_wday'
          This is the number of days since Sunday, in the range `0'
          through `6'.

    `int tm_yday'
          This is the number of days since January 1, in the range `0'
          through `365'.

    `int tm_isdst'
          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.

    `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 `-5*60*60'.  The
          `tm_gmtoff' field is derived from BSD and is a GNU library
          extension; it is not visible in a strict ISO C environment.

    `const char *tm_zone'
          This field is the name for the time zone that was used to
          compute this broken-down time value.  Like `tm_gmtoff', this
          field is a BSD and GNU extension, and is not visible in a
          strict ISO C environment.

 - Function: struct tm * localtime (const time_t *TIME)
     The `localtime' function converts the calendar time pointed to by
     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
     `ctime', `gmtime', or `localtime'.  (But no other library function
     overwrites the contents of this object.)

     Calling `localtime' has one other effect: it sets the variable
     `tzname' with information about the current time zone.  See Time Zone Functions.

 - Function: struct tm * gmtime (const time_t *TIME)
     This function is similar to `localtime', except that the
     broken-down time is expressed as Coordinated Universal Time
     (UTC)--that is, as Greenwich Mean Time (GMT)--rather than relative
     to the local time zone.

     Recall that calendar times are *always* expressed in coordinated
     universal time.

 - Function: time_t mktime (struct tm *BROKENTIME)
     The `mktime' function is used to convert a broken-down time
     structure to a calendar time representation.  It also "normalizes"
     the contents of the broken-down time structure, by filling in the
     day of week and day of year based on the other date and time
     components.

     The `mktime' function ignores the specified contents of the
     `tm_wday' and `tm_yday' members of the broken-down time structure.
     It uses the values of the other components to compute the
     calendar time; it's permissible for these components to have
     unnormalized values outside of their normal ranges.  The last
     thing that `mktime' does is adjust the components of the BROKENTIME
     structure (including the `tm_wday' and `tm_yday').

     If the specified broken-down time cannot be represented as a
     calendar time, `mktime' returns a value of `(time_t)(-1)' and does
     not modify the contents of BROKENTIME.

     Calling `mktime' also sets the variable `tzname' with information
     about the current time zone.  See Time Zone Functions.

Formatting Date and Time
------------------------

   The functions described in this section format time values as
strings.  These functions are declared in the header file `time.h'.

 - Function: char * asctime (const struct tm *BROKENTIME)
     The `asctime' function converts the broken-down time value that
     BROKENTIME points to into a string in a standard format:

          "Tue May 21 13:46:22 1991\n"

     The abbreviations for the days of week are: `Sun', `Mon', `Tue',
     `Wed', `Thu', `Fri', and `Sat'.

     The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr',
     `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.

     The return value points to a statically allocated string, which
     might be overwritten by subsequent calls to `asctime' or `ctime'.
     (But no other library function overwrites the contents of this
     string.)

 - Function: char * ctime (const time_t *TIME)
     The `ctime' function is similar to `asctime', except that the time
     value is specified as a `time_t' calendar time value rather than
     in broken-down local time format.  It is equivalent to

          asctime (localtime (TIME))

     `ctime' sets the variable `tzname', because `localtime' does so.
     See Time Zone Functions.

 - Function: size_t strftime (char *S, size_t SIZE, const char
          *TEMPLATE, const struct tm *BROKENTIME)
     This function is similar to the `sprintf' function (see
     Formatted Input.), but the conversion specifications that can
     appear in the format template TEMPLATE are specialized for
     printing components of the date and time BROKENTIME according to
     the locale currently specified for time conversion (see
     Locales.).

     Ordinary characters appearing in the TEMPLATE are copied to the
     output string S; this can include multibyte character sequences.
     Conversion specifiers are introduced by a `%' character, followed
     by an optional flag which can be one of the following.  These
     flags, which are GNU extensions, affect only the output of numbers:

    `_'
          The number is padded with spaces.

    `-'
          The number is not padded at all.

     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.

     An optional modifier can follow the optional flag.  The modifiers,
     which are POSIX.2 extensions, are:

    `E'
          Use the locale's alternate representation for date and time.
          This modifier applies to the `%c', `%C', `%x', `%X', `%y' and
          `%Y' format specifiers.  In a Japanese locale, for example,
          `%Ex' might yield a date format based on the Japanese
          Emperors' reigns.

    `O'
          Use the locale's alternate numeric symbols for numbers.  This
          modifier applies only to numeric format specifiers.

     A modifier is ignored if no alternate representation is available.

     The conversion specifier ends with a format specifier taken from
     the following list.  The whole `%' sequence is replaced in the
     output string as follows:

    `%a'
          The abbreviated weekday name according to the current locale.

    `%A'
          The full weekday name according to the current locale.

    `%b'
          The abbreviated month name according to the current locale.

    `%B'
          The full month name according to the current locale.

    `%c'
          The preferred date and time representation for the current
          locale.

    `%C'
          The century of the year.  This is equivalent to the greatest
          integer not greater than the year divided by 100.

          This format is a POSIX.2 extension.

    `%d'
          The day of the month as a decimal number (range `01' through
          `31').

    `%D'
          The date using the format `%m/%d/%y'.

          This format is a POSIX.2 extension.

    `%e'
          The day of the month like with `%d', but padded with blank
          (range ` 1' through `31').

          This format is a POSIX.2 extension.

    `%g'
          The year corresponding to the ISO week number, but without
          the century (range `00' through `99').  This has the same
          format and value as `%y', except that if the ISO week number
          (see `%V') belongs to the previous or next year, that year is
          used instead.

          This format is a GNU extension.

    `%G'
          The year corresponding to the ISO week number.  This has the
          same format and value as `%Y', except that if the ISO week
          number (see `%V') belongs to the previous or next year, that
          year is used instead.

          This format is a GNU extension.

    `%h'
          The abbreviated month name according to the current locale.
          The action is the same as for `%b'.

          This format is a POSIX.2 extension.

    `%H'
          The hour as a decimal number, using a 24-hour clock (range
          `00' through `23').

    `%I'
          The hour as a decimal number, using a 12-hour clock (range
          `01' through `12').

    `%j'
          The day of the year as a decimal number (range `001' through
          `366').

    `%k'
          The hour as a decimal number, using a 24-hour clock like
          `%H', but padded with blank (range ` 0' through `23').

          This format is a GNU extension.

    `%l'
          The hour as a decimal number, using a 12-hour clock like
          `%I', but padded with blank (range ` 1' through `12').

          This format is a GNU extension.

    `%m'
          The month as a decimal number (range `01' through `12').

    `%M'
          The minute as a decimal number (range `00' through `59').

    `%n'
          A single `\n' (newline) character.

          This format is a POSIX.2 extension.

    `%p'
          Either `AM' or `PM', according to the given time value; or the
          corresponding strings for the current locale.  Noon is
          treated as `PM' and midnight as `AM'.

    `%r'
          The complete time using the AM/PM format of the current
          locale.

          This format is a POSIX.2 extension.

    `%R'
          The hour and minute in decimal numbers using the format
          `%H:%M'.

          This format is a GNU extension.

    `%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.

    `%S'
          The second as a decimal number (range `00' through `60').

    `%t'
          A single `\t' (tabulator) character.

          This format is a POSIX.2 extension.

    `%T'
          The time using decimal numbers using the format `%H:%M:%S'.

          This format is a POSIX.2 extension.

    `%u'
          The day of the week as a decimal number (range `1' through
          `7'), Monday being `1'.

          This format is a POSIX.2 extension.

    `%U'
          The week number of the current year as a decimal number
          (range `00' through `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 `00'.

    `%V'
          The ISO 8601:1988 week number as a decimal number (range `01'
          through `53').  ISO weeks start with Monday and end with
          Sunday.  Week `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 `01' of a
          year can contain days from the previous year.  The week
          before week `01' of a year is the last week (`52' or `53') of
          the previous year even if it contains days from the new year.

          This format is a POSIX.2 extension.

    `%w'
          The day of the week as a decimal number (range `0' through
          `6'), Sunday being `0'.

    `%W'
          The week number of the current year as a decimal number
          (range `00' through `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 `00'.

    `%x'
          The preferred date representation for the current locale, but
          without the time.

    `%X'
          The preferred time representation for the current locale, but
          with no date.

    `%y'
          The year without a century as a decimal number (range `00'
          through `99').  This is equivalent to the year modulo 100.

    `%Y'
          The year as a decimal number, using the Gregorian calendar.
          Years before the year `1' are numbered `0', `-1', and so on.

    `%z'
          RFC 822/ISO 8601:1988 style numeric time zone (e.g., `-0600'
          or `+0100'), or nothing if no time zone is determinable.

          This format is a GNU extension.

    `%Z'
          The time zone abbreviation (empty if the time zone can't be
          determined).

    `%%'
          A literal `%' character.

     The SIZE parameter can be used to specify the maximum number of
     characters to be stored in the array S, including the terminating
     null character.  If the formatted time requires more than SIZE
     characters, the excess characters are discarded.  The return value
     from `strftime' is the number of characters placed in the array S,
     not including the terminating null character.  If the value equals
     SIZE, it means that the array S was too small; you should repeat
     the call, providing a bigger array.

     If S is a null pointer, `strftime' does not actually write
     anything, but instead returns the number of characters it would
     have written.

     For an example of `strftime', see Time Functions Example.