Return to ctime.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/ctime.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1989 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" This code is derived from software contributed to Berkeley by
        !             5: .\" Arthur Olson.
        !             6: .\"
        !             7: .\" Redistribution and use in source and binary forms are permitted provided
        !             8: .\" that: (1) source distributions retain this entire copyright notice and
        !             9: .\" comment, and (2) distributions including binaries display the following
        !            10: .\" acknowledgement:  ``This product includes software developed by the
        !            11: .\" University of California, Berkeley and its contributors'' in the
        !            12: .\" documentation or other materials provided with the distribution and in
        !            13: .\" all advertising materials mentioning features or use of this software.
        !            14: .\" Neither the name of the University nor the names of its contributors may
        !            15: .\" be used to endorse or promote products derived from this software without
        !            16: .\" specific prior written permission.
        !            17: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            18: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            19: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            20: .\"
        !            21: .\"    @(#)ctime.3     6.13 (Berkeley) 6/23/90
        !            22: .\"
        !            23: .TH CTIME 3 "June 23, 1990"
        !            24: .SH NAME
        !            25: asctime, ctime, difftime, gmtime, localtime, mktime, tzset, tzsetwall \- convert date and time to ASCII
        !            26: .SH SYNOPSIS
        !            27: .nf
        !            28: .B extern char *tzname[2];
        !            29: .PP
        !            30: .B void tzset()
        !            31: .PP
        !            32: .B void tzsetwall()
        !            33: .PP
        !            34: .B #include <sys/types.h>
        !            35: .PP
        !            36: .B char *ctime(clock)
        !            37: .B time_t *clock;
        !            38: .PP
        !            39: .B double difftime(time1, time0)
        !            40: .B time_t time1;
        !            41: .B time_t time0;
        !            42: .PP
        !            43: .B #include <time.h>
        !            44: .PP
        !            45: .B char *asctime(tm)
        !            46: .B struct tm *tm;
        !            47: .PP
        !            48: .B struct tm *localtime(clock)
        !            49: .B long *clock;
        !            50: .PP
        !            51: .B struct tm *gmtime(clock)
        !            52: .B long *clock;
        !            53: .PP
        !            54: .B time_t mktime(tm)
        !            55: .B struct tm *tm;
        !            56: .fi
        !            57: .SH DESCRIPTION
        !            58: .I Tzset
        !            59: uses the value of the environment variable
        !            60: .B TZ
        !            61: to set time conversion information used by
        !            62: .IR localtime .
        !            63: If
        !            64: .B TZ
        !            65: does not appear in the environment,
        !            66: the best available approximation to local wall clock time, as specified
        !            67: by the
        !            68: .IR tzfile (5)-format
        !            69: file
        !            70: .B localtime
        !            71: in the system time conversion information directory, is used by
        !            72: .IR localtime .
        !            73: If
        !            74: .B TZ
        !            75: appears in the environment but its value is a null string,
        !            76: Coordinated Universal Time (UTC) is used (without leap second
        !            77: correction).  If
        !            78: .B TZ
        !            79: appears in the environment and its value is not a null string:
        !            80: .IP
        !            81: if the value begins with a colon, it is used as a pathname of a file
        !            82: from which to read the time conversion information;
        !            83: .IP
        !            84: if the value does not begin with a colon, it is first used as the
        !            85: pathname of a file from which to read the time conversion information,
        !            86: and, if that file cannot be read, is used directly as a specification of
        !            87: the time conversion information.
        !            88: .PP
        !            89: When
        !            90: .B TZ
        !            91: is used as a pathname, if it begins with a slash,
        !            92: it is used as an absolute pathname; otherwise,
        !            93: it is used as a pathname relative to a system time conversion information
        !            94: directory.
        !            95: The file must be in the format specified in
        !            96: .IR tzfile (5).
        !            97: .PP
        !            98: When
        !            99: .B TZ
        !           100: is used directly as a specification of the time conversion information,
        !           101: it must have the following syntax (spaces inserted for clarity):
        !           102: .IP
        !           103: \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
        !           104: .PP
        !           105: Where:
        !           106: .RS
        !           107: .TP 15
        !           108: .IR std " and " dst
        !           109: Three or more bytes that are the designation for the standard
        !           110: .RI ( std )
        !           111: or summer
        !           112: .RI ( dst )
        !           113: time zone.  Only
        !           114: .I std
        !           115: is required; if
        !           116: .I dst
        !           117: is missing, then summer time does not apply in this locale.
        !           118: Upper- and lowercase letters are explicitly allowed.  Any characters
        !           119: except a leading colon
        !           120: .RB ( : ),
        !           121: digits, comma
        !           122: .RB ( , ),
        !           123: minus
        !           124: .RB ( \(mi ),
        !           125: plus
        !           126: .RB ( \(pl ),
        !           127: and ASCII NUL are allowed.
        !           128: .TP
        !           129: .I offset
        !           130: Indicates the value one must add to the local time to arrive at
        !           131: Coordinated Universal Time.  The
        !           132: .I offset
        !           133: has the form:
        !           134: .RS
        !           135: .IP
        !           136: \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
        !           137: .RE
        !           138: .IP
        !           139: The minutes
        !           140: .RI ( mm )
        !           141: and seconds
        !           142: .RI ( ss )
        !           143: are optional.  The hour
        !           144: .RI ( hh )
        !           145: is required and may be a single digit.  The
        !           146: .I offset
        !           147: following
        !           148: .I std
        !           149: is required.  If no
        !           150: .I offset
        !           151: follows
        !           152: .IR dst ,
        !           153: summer time is assumed to be one hour ahead of standard time.  One or
        !           154: more digits may be used; the value is always interpreted as a decimal
        !           155: number.  The hour must be between zero and 24, and the minutes (and
        !           156: seconds) \(em if present \(em between zero and 59.  If preceded by a
        !           157: .RB `` \(mi '',
        !           158: the time zone shall be east of the Prime Meridian; otherwise it shall be
        !           159: west (which may be indicated by an optional preceding
        !           160: .RB `` \(pl '').
        !           161: .TP
        !           162: .I rule
        !           163: Indicates when to change to and back from summer time.  The
        !           164: .I rule
        !           165: has the form:
        !           166: .RS
        !           167: .IP
        !           168: \fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
        !           169: .RE
        !           170: .IP
        !           171: where the first
        !           172: .I date
        !           173: describes when the change from standard to summer time occurs and the
        !           174: second
        !           175: .I date
        !           176: describes when the change back happens.  Each
        !           177: .I time
        !           178: field describes when, in current local time, the change to the other
        !           179: time is made.
        !           180: .IP
        !           181: The format of
        !           182: .I date
        !           183: is one of the following:
        !           184: .RS
        !           185: .TP 10
        !           186: .BI J n
        !           187: The Julian day
        !           188: .I n
        !           189: .RI "(1\ \(<=" "\ n\ " "\(<=\ 365).
        !           190: Leap days are not counted; that is, in all years \(em including leap
        !           191: years \(em February 28 is day 59 and March 1 is day 60.  It is
        !           192: impossible to explicitly refer to the occasional February 29.
        !           193: .TP
        !           194: .I n
        !           195: The zero-based Julian day
        !           196: .RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
        !           197: Leap days are counted, and it is possible to refer to February 29.
        !           198: .TP
        !           199: .BI M m . n . d
        !           200: The
        !           201: .IR d' th
        !           202: day
        !           203: .RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
        !           204: of week
        !           205: .I n
        !           206: of month
        !           207: .I m
        !           208: of the year
        !           209: .RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
        !           210: .RI "1\ \(<=" "\ m\ " "\(<=\ 12,
        !           211: where week 5 means ``the last
        !           212: .I d
        !           213: day in month
        !           214: .IR m ''
        !           215: which may occur in either the fourth or the fifth week).  Week 1 is the
        !           216: first week in which the
        !           217: .IR d' th
        !           218: day occurs.  Day zero is Sunday.
        !           219: .RE
        !           220: .IP "" 15
        !           221: The
        !           222: .I time
        !           223: has the same format as
        !           224: .I offset
        !           225: except that no leading sign
        !           226: .RB (`` \(mi ''
        !           227: or
        !           228: .RB `` \(pl '')
        !           229: is allowed.  The default, if
        !           230: .I time
        !           231: is not given, is
        !           232: .BR 02:00:00 .
        !           233: .RE
        !           234: .LP
        !           235: If no
        !           236: .I rule
        !           237: is present in
        !           238: .BR TZ ,
        !           239: the rules specified
        !           240: by the
        !           241: .IR tzfile (5)-format
        !           242: file
        !           243: .B posixrules
        !           244: in the system time conversion information directory are used, with the
        !           245: standard and summer time offsets from UTC replaced by those specified by
        !           246: the
        !           247: .I offset
        !           248: values in
        !           249: .BR TZ .
        !           250: .PP
        !           251: For compatibility with System V Release 3.1, a semicolon
        !           252: .RB ( ; )
        !           253: may be used to separate the
        !           254: .I rule
        !           255: from the rest of the specification.
        !           256: .PP
        !           257: If the
        !           258: .B TZ
        !           259: environment variable does not specify a
        !           260: .IR tzfile (5)-format
        !           261: and cannot be interpreted as a direct specification,
        !           262: UTC is used.
        !           263: .PP
        !           264: .I Tzsetwall
        !           265: sets things up so that
        !           266: .I localtime
        !           267: returns the best available approximation of local wall clock time.
        !           268: .PP
        !           269: .I Ctime\^
        !           270: converts a long integer, pointed to by
        !           271: .IR clock ,
        !           272: representing the time in seconds since
        !           273: 00:00:00 UTC, January 1, 1970,
        !           274: and returns a pointer to a
        !           275: 26-character string
        !           276: of the form
        !           277: .br
        !           278: .ce
        !           279: .eo
        !           280: Thu Nov 24 18:22:48 1986\n\0
        !           281: .ec
        !           282: .br
        !           283: All the fields have constant width.
        !           284: .PP
        !           285: .IR Localtime\^
        !           286: and
        !           287: .I gmtime\^
        !           288: return pointers to ``tm'' structures, described below.
        !           289: .I Localtime\^
        !           290: corrects for the time zone and any time zone adjustments
        !           291: (such as Daylight Saving Time in the U.S.A.).
        !           292: Before doing so,
        !           293: .I localtime\^
        !           294: calls
        !           295: .I tzset\^
        !           296: (if
        !           297: .I tzset\^
        !           298: has not been called in the current process).
        !           299: After filling in the ``tm'' structure,
        !           300: .I localtime
        !           301: sets the
        !           302: .BR tm_isdst 'th
        !           303: element of
        !           304: .B tzname
        !           305: to a pointer to an 
        !           306: ASCII string that's the time zone abbreviation to be used with
        !           307: .IR localtime 's
        !           308: return value.
        !           309: .PP
        !           310: .I Gmtime\^
        !           311: converts to Coordinated Universal Time.
        !           312: .PP
        !           313: .I Asctime\^
        !           314: converts a time value contained in a
        !           315: ``tm'' structure to a 26-character string,
        !           316: as shown in the above example,
        !           317: and returns a pointer
        !           318: to the string.
        !           319: .PP
        !           320: .I Mktime\^
        !           321: converts the broken-down time,
        !           322: expressed as local time,
        !           323: in the structure pointed to by
        !           324: .I tm
        !           325: into a calendar time value with the same encoding as that of the values
        !           326: returned by the
        !           327: .I time
        !           328: function.
        !           329: The original values of the
        !           330: .B tm_wday
        !           331: and
        !           332: .B tm_yday
        !           333: components of the structure are ignored,
        !           334: and the original values of the other components are not restricted
        !           335: to their normal ranges.
        !           336: (A positive or zero value for
        !           337: .B tm_isdst
        !           338: causes
        !           339: .I mktime
        !           340: to presume initially that summer time (for example, Daylight Saving Time 
        !           341: in the U.S.A.)
        !           342: respectively,
        !           343: is or is not in effect for the specified time.
        !           344: A negative value for
        !           345: .B tm_isdst
        !           346: causes the
        !           347: .I mktime
        !           348: function to attempt to divine whether summer time is in effect
        !           349: for the specified time.)
        !           350: On successful completion, the values of the
        !           351: .B tm_wday
        !           352: and
        !           353: .B tm_yday
        !           354: components of the structure are set appropriately,
        !           355: and the other components are set to represent the specified calendar time,
        !           356: but with their values forced to their normal ranges; the final value of
        !           357: .B tm_mday
        !           358: is not set until
        !           359: .B tm_mon
        !           360: and
        !           361: .B tm_year
        !           362: are determined.
        !           363: .I Mktime\^
        !           364: returns the specified calendar time;
        !           365: If the calendar time cannot be represented,
        !           366: it returns
        !           367: .BR -1 .
        !           368: .PP
        !           369: .I Difftime\^
        !           370: returns the difference between two calendar times,
        !           371: .I time1
        !           372: -
        !           373: .IR time0,
        !           374: expressed in seconds.
        !           375: .PP
        !           376: Declarations of all the functions and externals, and the ``tm'' structure,
        !           377: are in the
        !           378: .B <time.h>\^
        !           379: header file.
        !           380: The structure (of type)
        !           381: .B struct tm
        !           382: includes the following fields:
        !           383: .RS
        !           384: .PP
        !           385: .nf
        !           386: .ta .5i +\w'long tm_gmtoff;\0\0'u
        !           387:        int tm_sec;     /\(** seconds (0 - 60) \(**/
        !           388:        int tm_min;     /\(** minutes (0 - 59) \(**/
        !           389:        int tm_hour;    /\(** hours (0 - 23) \(**/
        !           390:        int tm_mday;    /\(** day of month (1 - 31) \(**/
        !           391:        int tm_mon;     /\(** month of year (0 - 11) \(**/
        !           392:        int tm_year;    /\(** year \- 1900 \(**/
        !           393:        int tm_wday;    /\(** day of week (Sunday = 0) \(**/
        !           394:        int tm_yday;    /\(** day of year (0 - 365) \(**/
        !           395:        int tm_isdst;   /\(** is summer time in effect? \(**/
        !           396:        char \(**tm_zone;       /\(** abbreviation of timezone name \(**/
        !           397:        long tm_gmtoff; /\(** offset from UTC in seconds \(**/
        !           398: .fi
        !           399: .RE
        !           400: .PP
        !           401: The
        !           402: .I tm_zone
        !           403: and
        !           404: .I tm_gmtoff
        !           405: fields exist, and are filled in, only if arrangements to do
        !           406: so were made when the library containing these functions was
        !           407: created.
        !           408: There is no guarantee that these fields will continue to exist
        !           409: in this form in future releases of this code.
        !           410: .PP
        !           411: .I Tm_isdst\^
        !           412: is non-zero if summer time is in effect.
        !           413: .PP
        !           414: .I Tm_gmtoff
        !           415: is the offset (in seconds) of the time represented
        !           416: from UTC, with positive values indicating east
        !           417: of the Prime Meridian.
        !           418: .SH FILES
        !           419: .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
        !           420: /usr/share/zoneinfo    time zone information directory
        !           421: .br
        !           422: /usr/share/zoneinfo/localtime  local time zone file
        !           423: .br
        !           424: /usr/share/zoneinfo/posixrules used in converting POSIX-style TZ's
        !           425: .br
        !           426: /usr/share/zoneinfo/GMT        for UTC leap seconds
        !           427: .sp
        !           428: If
        !           429: .I /usr/share/zoneinfo/GMT
        !           430: is absent,
        !           431: UTC leap seconds are loaded from
        !           432: .IR /usr/share/zoneinfo/posixrules .
        !           433: .SH SEE ALSO
        !           434: time(2), getenv(3), tzfile(5)
        !           435: .SH NOTES
        !           436: The return values point to static data
        !           437: whose content is overwritten by each call.
        !           438: The
        !           439: .B tm_zone
        !           440: field of a returned
        !           441: .B "struct tm"
        !           442: points to a static array of characters, which
        !           443: will also be overwritten at the next call
        !           444: (and by calls to
        !           445: .I tzset
        !           446: or
        !           447: .IR tzsetwall ).
        !           448: .PP
        !           449: Avoid using out-of-range values with
        !           450: .I mktime
        !           451: when setting up lunch with promptness sticklers in Riyadh.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.