[BACK]Return to ctime.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/ctime.3, Revision 1.61

1.61    ! sevan       1: .\" $NetBSD: ctime.3,v 1.60 2018/10/19 23:05:35 christos Exp $
1.39      jruoho      2: .\"
1.44      christos    3: .\" XXX: License missing?
1.39      jruoho      4: .\"
1.61    ! sevan       5: .Dd September 2, 2019
1.23      wiz         6: .Dt CTIME 3
                      7: .Os
                      8: .Sh NAME
                      9: .Nm asctime ,
                     10: .Nm asctime_r ,
                     11: .Nm ctime ,
                     12: .Nm ctime_r ,
1.36      christos   13: .Nm ctime_rz ,
1.23      wiz        14: .Nm difftime ,
                     15: .Nm gmtime ,
                     16: .Nm gmtime_r ,
                     17: .Nm localtime ,
                     18: .Nm localtime_r ,
1.36      christos   19: .Nm localtime_rz ,
                     20: .Nm mktime ,
1.53      abhinav    21: .Nm mktime_z
1.50      christos   22: .Nd convert date and time
1.23      wiz        23: .Sh LIBRARY
                     24: .Lb libc
                     25: .Sh SYNOPSIS
1.27      wiz        26: .In time.h
1.38      njoly      27: .Vt extern char *tzname[2];
1.23      wiz        28: .Ft char *
1.40      jruoho     29: .Fn asctime "const struct tm *tm"
                     30: .Ft char *
1.54      wiz        31: .Fn asctime_r "const struct tm *restrict tm" "char * restrict buf"
1.40      jruoho     32: .Ft char *
1.23      wiz        33: .Fn ctime "const time_t *clock"
                     34: .Ft char *
                     35: .Fn ctime_r "const time_t *clock"  "char *buf"
1.36      christos   36: .Ft char *
1.51      christos   37: .Fn ctime_rz "timezone_t restrict tz" "const time_t *clock"  "char *buf"
1.23      wiz        38: .Ft double
                     39: .Fn difftime "time_t time1" "time_t time0"
1.40      jruoho     40: .Ft struct tm *
                     41: .Fn gmtime "const time_t *clock"
                     42: .Ft struct tm *
                     43: .Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result"
1.23      wiz        44: .Ft struct tm *
                     45: .Fn localtime "const time_t *clock"
                     46: .Ft struct tm *
                     47: .Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result"
                     48: .Ft struct tm *
1.51      christos   49: .Fn localtime_rz "timezone_t restrict tz" "const time_t * restrict clock" "struct tm * restrict result"
1.23      wiz        50: .Ft time_t
                     51: .Fn mktime "struct tm *tm"
1.36      christos   52: .Ft time_t
1.51      christos   53: .Fn mktime_z "timezone_t restrict tz" "struct tm *restrict tm"
1.23      wiz        54: .Sh DESCRIPTION
1.40      jruoho     55: The
                     56: .Nm
                     57: family of functions provide various standard library routines
                     58: to operate with time and conversions related to time.
                     59: .Sh FUNCTIONS
                     60: .Bl -tag -width abcd
                     61: .It Fn asctime "tm"
                     62: The
                     63: .Fn asctime
                     64: function converts a time value contained in the
                     65: .Fa tm
                     66: structure to a string with the following general format:
                     67: .Bd -literal -offset indent
1.52      abhinav    68: Thu Nov 24 18:22:48 1986\en\e0
1.40      jruoho     69: .Ed
                     70: .Pp
                     71: The
                     72: .Fa tm
                     73: structure is described in
                     74: .Xr tm 3 .
                     75: .It Fn asctime_r "tm" "buf"
                     76: The
                     77: .Fn asctime_r
                     78: has the same behavior as
                     79: .Fn asctime ,
1.52      abhinav    80: but the result is stored in
1.40      jruoho     81: .Fa buf ,
                     82: which should have a size of at least 26 bytes.
                     83: .It Fn ctime "clock"
                     84: The
1.23      wiz        85: .Fn ctime
1.40      jruoho     86: function converts a
1.38      njoly      87: .Vt time_t ,
1.33      christos   88: pointed to by
1.29      joerg      89: .Fa clock ,
1.40      jruoho     90: and returns a pointer to a string with the format described above.
1.28      mlelstv    91: Years requiring fewer than four characters are padded with leading zeroes.
                     92: For years longer than four characters, the string is of the form
1.40      jruoho     93: .Bd -literal -offset indent
1.52      abhinav    94: Thu Nov 24 18:22:48     81986\en\e0
1.40      jruoho     95: .Ed
                     96: .Pp
1.28      mlelstv    97: with five spaces before the year.
                     98: These unusual formats are designed to make it less likely that older
                     99: software that expects exactly 26 bytes of output will mistakenly output
                    100: misleading values for out-of-range years.
1.48      christos  101: .Pp
                    102: The
                    103: .Fa clock
                    104: time stamp represents the time in seconds since 1970-01-01 00:00:00
                    105: Coordinated Universal Time (UTC).
                    106: The POSIX standard says that time stamps must be nonnegative
                    107: and must ignore leap seconds.
                    108: Many implementations extend POSIX by allowing negative time stamps,
                    109: and can therefore represent time stamps that predate the
                    110: introduction of UTC and are some other flavor of Universal Time (UT).
                    111: Some implementations support leap seconds, in contradiction to POSIX.
1.40      jruoho    112: .It Fn ctime_r "clock" "buf"
                    113: The
1.33      christos  114: .Fn ctime_r
                    115: is similar to
                    116: .Fn ctime ,
1.52      abhinav   117: except it places the result of the conversion in the
1.33      christos  118: .Fa buf
1.40      jruoho    119: argument, which should be 26 or more bytes long,
                    120: instead of using a global static buffer.
                    121: .It Fn ctime_rz "tz" "clock" "buf"
                    122: The
1.36      christos  123: .Fn ctime_rz
1.40      jruoho    124: function is similar to
1.36      christos  125: .Fn ctime_r ,
                    126: but it also takes a
1.51      christos  127: .Ft "timezone_t"
1.40      jruoho    128: argument, as returned by a previous call to
1.47      apb       129: .Fn tzalloc ,
1.51      christos  130: or a
                    131: .Dv NULL
                    132: pointer denoting
1.47      apb       133: Coordinated Universal Time
1.58      wiz       134: .Pq UTC .
1.40      jruoho    135: .It Fn difftime "time1" "time2"
                    136: The
                    137: .Fn difftime
                    138: function returns the difference between two calendar times,
                    139: .Fa ( time1 No - Fa time0 ) ,
                    140: expressed in seconds.
1.51      christos  141: .Pp
                    142: The
                    143: .Fn ctime_r ,
                    144: .Fn localtime_r ,
                    145: .Fn gmtime_r ,
                    146: and
                    147: .Fn asctime_r
                    148: functions
                    149: are like their unsuffixed counterparts, except that they accept an
                    150: additional argument specifying where to store the result if successful.
                    151: .Pp
                    152: The
                    153: .Fn ctime_rz ,
                    154: .Fn localtime_rz ,
                    155: and
                    156: .Fn mktime_z
                    157: functions
                    158: are like their unsuffixed counterparts, except that they accept an
                    159: extra initial
                    160: .Ar zone
1.60      christos  161: argument specifying the timezone to be used for conversion.
1.51      christos  162: If
                    163: .Fa zone
                    164: is
                    165: .Dv NULL ,
1.56      christos  166: UT is used; otherwise,
1.51      christos  167: .Fa zone
1.52      abhinav   168: should have been allocated by
1.51      christos  169: .Fn tzalloc
                    170: and should not be freed until after all uses (e.g., by calls to
                    171: .Fn strftime )
                    172: of the filled-in
                    173: .Fn tm_zone
                    174: fields.
1.40      jruoho    175: .It Fn gmtime "clock"
                    176: The
1.23      wiz       177: .Fn gmtime
1.40      jruoho    178: function converts to Coordinated Universal Time
1.58      wiz       179: .Pq UTC
1.40      jruoho    180: and returns a pointer to the
1.23      wiz       181: .Va tm
1.40      jruoho    182: structure described in
                    183: .Xr tm 3 .
                    184: .It Fn gmtime_r "clock" "result"
                    185: The
                    186: .Fn gmtime_r
1.52      abhinav   187: function provides the same functionality as
1.40      jruoho    188: .Fn gmtime ,
                    189: differing in that the caller must supply a buffer area
                    190: .Fa result
1.52      abhinav   191: in which the result is stored.
1.40      jruoho    192: .It Fn localtime "clock"
                    193: Also
                    194: .Fn localtime
                    195: is comparable to
                    196: .Fn gmtime .
                    197: However,
1.23      wiz       198: .Fn localtime
1.60      christos  199: corrects for the timezone and any timezone adjustments
1.1       jtc       200: (such as Daylight Saving Time in the U.S.A.).
1.23      wiz       201: After filling in the
                    202: .Va tm
1.40      jruoho    203: structure, the function sets the
1.23      wiz       204: .Fa tm_isdst Ns 'th
1.1       jtc       205: element of
1.23      wiz       206: .Fa tzname
1.1       jtc       207: to a pointer to an
1.60      christos  208: ASCII string that is the timezone abbreviation to be used with
1.23      wiz       209: .Fn localtime Ns 's
1.1       jtc       210: return value.
1.40      jruoho    211: .It Fn localtime_r "clock" "result"
                    212: As
                    213: .Fn gmtime_r ,
                    214: the
1.23      wiz       215: .Fn localtime_r
1.40      jruoho    216: takes an additional buffer
1.23      wiz       217: .Fa result
1.52      abhinav   218: as a parameter and stores the result in it.
1.40      jruoho    219: Note however that
1.23      wiz       220: .Fn localtime_r
1.19      kleink    221: does not imply initialization of the local time conversion information;
                    222: the application may need to do so by calling
1.23      wiz       223: .Xr tzset 3 .
1.40      jruoho    224: .It Fn localtime_rz "tz" "clock" "result"
                    225: The
1.36      christos  226: .Fn localtime_rz
1.40      jruoho    227: function is similar to
1.36      christos  228: .Fn localtime_r ,
                    229: but it also takes a
1.51      christos  230: .Ft "timezone_t"
1.36      christos  231: argument, returned by a previous call to
1.47      apb       232: .Fn tzalloc ,
1.51      christos  233: or a
                    234: .Dv NULL
                    235: pointer denoting Coordinated Universal Time
1.58      wiz       236: .Pq UTC .
1.40      jruoho    237: .It Fn mktime "tm"
                    238: The
1.29      joerg     239: .Fn mktime
1.40      jruoho    240: function converts the broken-down time,
                    241: expressed as local time in the
                    242: .Xr tm 3
                    243: structure, into a calendar time value with
                    244: the same encoding as that of the values returned by the
1.23      wiz       245: .Xr time 3
1.1       jtc       246: function.
1.40      jruoho    247: The following remarks should be taken into account.
1.42      plunky    248: .Bl -bullet
1.40      jruoho    249: .It
1.1       jtc       250: The original values of the
1.23      wiz       251: .Fa tm_wday
1.1       jtc       252: and
1.23      wiz       253: .Fa tm_yday
1.1       jtc       254: components of the structure are ignored,
                    255: and the original values of the other components are not restricted
                    256: to their normal ranges.
                    257: (A positive or zero value for
1.23      wiz       258: .Fa tm_isdst
1.1       jtc       259: causes
1.23      wiz       260: .Fn mktime
1.59      christos  261: to presume initially that daylight saving time
                    262: respectively,
1.26      wiz       263: is or is not in effect for the specified time.
1.40      jruoho    264: .It
1.26      wiz       265: A negative value for
1.23      wiz       266: .Fa tm_isdst
1.1       jtc       267: causes the
1.23      wiz       268: .Fn mktime
1.59      christos  269: function to attempt to divine whether daylight saving time is in effect
1.28      mlelstv   270: for the specified time; in this case it does not use a consistent
                    271: rule and may give a different answer when later
1.40      jruoho    272: presented with the same argument.
                    273: .It
1.1       jtc       274: On successful completion, the values of the
1.23      wiz       275: .Fa tm_wday
1.1       jtc       276: and
1.23      wiz       277: .Fa tm_yday
1.1       jtc       278: components of the structure are set appropriately,
                    279: and the other components are set to represent the specified calendar time,
                    280: but with their values forced to their normal ranges; the final value of
1.23      wiz       281: .Fa tm_mday
1.1       jtc       282: is not set until
1.23      wiz       283: .Fa tm_mon
1.1       jtc       284: and
1.23      wiz       285: .Fa tm_year
1.1       jtc       286: are determined.
1.40      jruoho    287: .El
                    288: .Pp
                    289: The function returns the specified calendar time;
                    290: if the calendar time cannot be represented, it returns
1.30      christos  291: .Va "(time_t)-1" .
1.43      christos  292: This can happen either because the resulting conversion would not fit
                    293: in a
                    294: .Vt time_t
                    295: variable, or because the time specified happens to be in the daylight
                    296: savings gap and
                    297: .Fa tm_isdst
                    298: was set to
                    299: .Dv \-1 .
                    300: Other
                    301: .Fn mktime
                    302: implementations do not return an error in the second case and return
                    303: the appropriate time offset after the daylight savings gap.
                    304: There is code to mimick this behavior, but it is not enabled by default.
1.40      jruoho    305: .It Fn mktime_z "tz" "tm"
                    306: The
1.36      christos  307: .Fn mktime_z
1.40      jruoho    308: function is similar to
1.36      christos  309: .Fn mktime
                    310: but it also takes a
                    311: .Ft "const timezone_t"
                    312: argument, returned by a previous call to
1.47      apb       313: .Fn tzalloc ,
                    314: or a null pointer denoting
                    315: Coordinated Universal Time
1.58      wiz       316: .Pq UTC .
1.40      jruoho    317: .El
1.48      christos  318: .Pp
1.52      abhinav   319: Declarations of all the functions and externals, and the
1.48      christos  320: .Ft tm
                    321: structure, are in the
                    322: .In time.h
                    323: header file.
                    324: The structure (of type)
                    325: .Ft struct tm
                    326: includes the following fields:
                    327: .Bd -literal
                    328:        int tm_sec;      /* seconds (0 - 60) */
                    329:        int tm_min;      /* minutes (0 - 59) */
                    330:        int tm_hour;     /* hours (0 - 23) */
                    331:        int tm_mday;     /* day of month (1 - 31) */
                    332:        int tm_mon;      /* month of year (0 - 11) */
                    333:        int tm_year;     /* year - 1900 */
                    334:        int tm_wday;     /* day of week (Sunday = 0) */
                    335:        int tm_yday;     /* day of year (0 - 365) */
                    336:        int tm_isdst;    /* is summer time in effect? */
1.59      christos  337:        int tm_isdst;   /* is daylight saving time in effect? */
1.55      christos  338:        char *tm_zone;   /* abbreviation of timezone name (optional) */
                    339:        long tm_gmtoff;  /* offset from UT in seconds (optional) */
1.48      christos  340: .Ed
                    341: .Bl -bullet
                    342: .It
                    343: .Va tm_isdst
1.59      christos  344: is non-zero if daylight saving time is in effect.
1.48      christos  345: .It
                    346: .Va tm_gmtoff
                    347: is the offset (in seconds) of the time represented from UT,
                    348: with positive values indicating east of the Prime Meridian.
                    349: The field's name is derived from Greenwich Mean Time, a precursor of UT.
                    350: .El
1.55      christos  351: In
                    352: .Ft struct tm
                    353: the
                    354: .Fa tm_zone
                    355: and
                    356: .Fa tm_gmtoff
                    357: fields exist, and are filled in, only if arrangements to do
                    358: so were made when the library containing these functions  was
                    359: created.
                    360: Similarly, the
                    361: .Va tzname
                    362: variable is optional.
                    363: There is no guarantee that these fields and this variable will
                    364: continue to exist in this form in future releases of this code.
1.30      christos  365: .Sh RETURN VALUES
1.41      njoly     366: .Bl -bullet
1.40      jruoho    367: .It
1.30      christos  368: On success the
1.31      wiz       369: .Fn asctime
1.30      christos  370: and
1.31      wiz       371: .Fn ctime
1.30      christos  372: functions return a pointer to a static character buffer, and the
1.36      christos  373: .Fn asctime_r ,
                    374: .Fn ctime_r ,
1.30      christos  375: and
1.36      christos  376: .Fn ctime_rz
1.30      christos  377: function return a pointer to the user-supplied buffer.
                    378: On failure they all return
                    379: .Dv NULL
                    380: and no errors are defined for them.
1.40      jruoho    381: .It
1.30      christos  382: On success the
1.31      wiz       383: .Fn gmtime ,
1.30      christos  384: and
1.31      wiz       385: .Fn localtime
1.30      christos  386: functions return a pointer to a statically allocated
                    387: .Va "struct tm"
                    388: whereas the
1.36      christos  389: .Fn gmtime_r ,
                    390: .Fn localtime_r ,
1.30      christos  391: and
1.36      christos  392: .Fn localtime_rz ,
1.30      christos  393: functions return a pointer to the user-supplied
                    394: .Va "struct tm" .
                    395: On failure they all return
                    396: .Dv NULL
                    397: and the global variable
                    398: .Va errno
                    399: is set to indicate the error.
1.40      jruoho    400: .It
1.30      christos  401: The
1.31      wiz       402: .Fn mktime
1.36      christos  403: and
                    404: .Fn mktime_z
1.30      christos  405: function returns the specified time since the Epoch as a
1.38      njoly     406: .Vt time_t
1.31      wiz       407: type value.
                    408: If the time cannot be represented, then
                    409: .Fn mktime
1.36      christos  410: and
                    411: .Fn mktime_z
                    412: return
1.30      christos  413: .Va "(time_t)-1"
                    414: setting the global variable
                    415: .Va errno
                    416: to indicate the error.
1.40      jruoho    417: .It
1.36      christos  418: The
                    419: .Fn tzalloc
                    420: function returns a pointer to a
                    421: .Ft timezone_t
                    422: object or
                    423: .Dv NULL
                    424: on failure, setting
                    425: .Va errno
                    426: to indicate the error.
1.47      apb       427: It may also return
                    428: .Dv NULL
                    429: when the
                    430: .Fa name
                    431: argument is
                    432: .Dv NULL ,
                    433: and this is not an error, but a way of referring to
                    434: Coordinated Universal Time
1.58      wiz       435: .Pq UTC .
1.40      jruoho    436: .It
1.36      christos  437: .Fn tzgetzone
                    438: function returns string containing the name of the timezone given in
                    439: .Fa tz .
1.40      jruoho    440: .El
1.23      wiz       441: .Sh FILES
                    442: .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
                    443: .It Pa /etc/localtime
1.60      christos  444: local timezone file
1.23      wiz       445: .It Pa /usr/share/zoneinfo
1.60      christos  446: timezone information directory
                    447: .It Pa usr/share/zoneinfo/localtime
                    448: local timezone file
1.23      wiz       449: .It Pa /usr/share/zoneinfo/posixrules
                    450: used with POSIX-style TZ's
                    451: .It Pa /usr/share/zoneinfo/GMT
                    452: for UTC leap seconds
                    453: .El
                    454: .Pp
1.1       jtc       455: If
1.23      wiz       456: .Pa /usr/share/zoneinfo/GMT
                    457: is absent, UTC leap seconds are loaded from
                    458: .Pa /usr/share/zoneinfo/posixrules .
1.31      wiz       459: .Sh ERRORS
1.40      jruoho    460: The described functions may fail with
1.31      wiz       461: .Bl -tag -width Er
1.37      wiz       462: .It Bq Er EINVAL
1.44      christos  463: The result cannot be represented because a parameter is incorrect, or
                    464: the conversion failed because no such time exists (for example a time
                    465: in the DST gap).
1.31      wiz       466: .It Bq Er EOVERFLOW
1.44      christos  467: The result cannot be represented because the time requested is out of bounds
                    468: and the time calculation resulted in overflow.
1.31      wiz       469: .El
1.36      christos  470: .Pp
1.40      jruoho    471: All functions that return values, except their
1.36      christos  472: .Dq z
                    473: variants, can also return the same errors as
                    474: .Xr open 2
                    475: and
                    476: .Xr malloc 3 .
1.23      wiz       477: .Sh SEE ALSO
                    478: .Xr getenv 3 ,
                    479: .Xr strftime 3 ,
1.24      wiz       480: .Xr time 3 ,
1.39      jruoho    481: .Xr tm 3 ,
1.23      wiz       482: .Xr tzset 3 ,
                    483: .Xr tzfile 5
                    484: .Sh STANDARDS
                    485: The
                    486: .Fn ctime ,
                    487: .Fn difftime ,
                    488: .Fn asctime ,
                    489: .Fn localtime ,
                    490: .Fn gmtime
1.13      kleink    491: and
1.23      wiz       492: .Fn mktime
1.13      kleink    493: functions conform to
1.40      jruoho    494: .St -ansiC .
                    495: Rest of the functions conform to
                    496: .St -p1003.1-2008 .
1.61    ! sevan     497: .Sh HISTORY
        !           498: A
        !           499: .Fn ctime
        !           500: function appeared in
        !           501: .At v1 .
1.40      jruoho    502: .Sh CAVEATS
1.46      christos  503: The functions that do not take an explicit
                    504: .Ft timezone_t
1.52      abhinav   505: argument return values pointing to static data; the data is overwritten by
1.26      wiz       506: each call.
1.46      christos  507: For the above functions the
1.55      christos  508: .Dv tzname
                    509: variable (once set) and the
1.23      wiz       510: .Fa tm_zone
1.1       jtc       511: field of a returned
1.23      wiz       512: .Va "struct tm"
1.57      pgoyette  513: point to an array of characters that
1.55      christos  514: can be freed or overwritten by later calls to the functions
                    515: .Fn localtime ,
                    516: .Fn tzfree ,
1.58      wiz       517: and
                    518: .Fn tzset ,
1.60      christos  519: if these functions affect the timezone information that specifies the
1.55      christos  520: abbreviation in question.
                    521: The remaining functions and data are thread-safe.
1.46      christos  522: The functions that do take an explicit
                    523: .Ft timezone_t
                    524: argument and set the fields of a supplied
                    525: .Va "struct tm"
                    526: should not call
                    527: .Fn tzfree
                    528: since the
                    529: .Fa tm_zone
                    530: field of the
                    531: .Va "struct tm"
                    532: points to data allocated by
                    533: .Fn tzalloc .
1.29      joerg     534: .Pp
1.40      jruoho    535: The
1.51      christos  536: .Fn asctime ,
                    537: .Fn asctime_r ,
                    538: .Fn ctime ,
                    539: .Fn ctime_r ,
1.28      mlelstv   540: and
1.51      christos  541: .Fn ctime_rz ,
1.40      jruoho    542: functions behave strangely for years before 1000 or after 9999.
1.28      mlelstv   543: The 1989 and 1999 editions of the C Standard say
                    544: that years from \-99 through 999 are converted without
                    545: extra spaces, but this conflicts with longstanding
                    546: tradition and with this implementation.
1.51      christos  547: The 2011 edition says that the behavior
                    548: is undefined if the year is before 1000 or after 9999.
1.28      mlelstv   549: Traditional implementations of these two functions are
                    550: restricted to years in the range 1900 through 2099.
                    551: To avoid this portability mess, new programs should use
1.29      joerg     552: .Fn strftime
1.28      mlelstv   553: instead.
                    554: .\" @(#)newctime.3     8.3
                    555: .\" This file is in the public domain, so clarified as of
                    556: .\" 2009-05-17 by Arthur David Olson.

CVSweb <webmaster@jp.NetBSD.org>