diff options
Diffstat (limited to 'lib/libc/stdtime/ctime.3')
| -rw-r--r-- | lib/libc/stdtime/ctime.3 | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 new file mode 100644 index 0000000..ae5c6a1 --- /dev/null +++ b/lib/libc/stdtime/ctime.3 @@ -0,0 +1,349 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Arthur Olson. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd January 2, 1999 +.Dt CTIME 3 +.Os BSD 4.3 +.Sh NAME +.Nm asctime , +.Nm asctime_r , +.Nm ctime , +.Nm ctime_r , +.Nm difftime , +.Nm gmtime , +.Nm gmtime_r , +.Nm localtime , +.Nm localtime_r , +.Nm mktime , +.Nm timegm +.Nd transform binary date and time values +.Sh SYNOPSIS +.Fd #include <time.h> +.Vt extern char *tzname[2]; +.Ft char * +.Fn ctime "const time_t *clock" +.Ft double +.Fn difftime "time_t time1" "time_t time0" +.Ft char * +.Fn asctime "const struct tm *tm" +.Ft struct tm * +.Fn localtime "const time_t *clock" +.Ft struct tm * +.Fn gmtime "const time_t *clock" +.Ft time_t +.Fn mktime "struct tm *tm" +.Ft time_t +.Fn timegm "struct tm *tm" +.Ft char * +.Fn ctime_r "const time_t *clock" "char *buf" +.Ft struct tm * +.Fn localtime_r "const time_t *clock" "struct tm *result" +.Ft struct tm * +.Fn gmtime_r "const time_t *clock" "struct tm *result" +.Ft char * +.Fn asctime_r "const struct tm *tm" "char *buf" +.Sh DESCRIPTION +The functions +.Fn ctime , +.Fn gmtime +and +.Fn localtime +all take as an argument a time value representing the time in seconds since +the Epoch (00:00:00 +.Tn UTC , +January 1, 1970; see +.Xr time 3 ) . +.Pp +The function +.Fn localtime +converts the time value pointed at by +.Fa clock , +and returns a pointer to a +.Dq Fa struct tm +(described below) which contains +the broken-out time information for the value after adjusting for the current +time zone (and any other factors such as Daylight Saving Time). +Time zone adjustments are performed as specified by the +.Ev TZ +environment variable (see +.Xr tzset 3 ) . +The function +.Fn localtime +uses +.Xr tzset 3 +to initialize time conversion information if +.Xr tzset 3 +has not already been called by the process. +.Pp +After filling in the tm structure, +.Fn localtime +sets the +.Fa tm_isdst Ns 'th +element of +.Fa tzname +to a pointer to an +.Tn ASCII +string that's the time zone abbreviation to be +used with +.Fn localtime Ns 's +return value. +.Pp +The function +.Fn gmtime +similarly converts the time value, but without any time zone adjustment, +and returns a pointer to a tm structure (described below). +.Pp +The +.Fn ctime +function +adjusts the time value for the current time zone in the same manner as +.Fn localtime , +and returns a pointer to a 26-character string of the form: +.Bd -literal -offset indent +Thu Nov 24 18:22:48 1986\en\e0 +.Ed +.Pp +All the fields have constant width. +.Pp +.Fn ctime_r +provides the same functionality as +.Fn ctime +except the caller must provide the output buffer +.Fa buf +to store the result, which must be at least 26 characters long. +.Fn localtime_r +and +.Fn gmtime_r +provide the same functionality as +.Fn localtime +and +.Fn gmtime +respectively, except the caller must provide the output buffer +.Fa result . +.Pp +The +.Fn asctime +function +converts the broken down time in the structure +.Fa tm +pointed at by +.Fa *tm +to the form +shown in the example above. +.Pp +.Fn asctime_r +provides the same functionality as +.Fn asctime +except the caller provide the output buffer +.Fa buf +to store the result, which must be at least 26 characters long. +.Pp +The functions +.Fn mktime +and +.Fn timegm +convert the broken-down time in the structure +pointed to by tm into a time value with the same encoding as that of the +values returned by the +.Xr time 3 +function (that is, seconds from the Epoch, +.Tn UTC ) . +.Fn mktime +interprets the input structure according to the current timezone setting +(see +.Xr tzset 3 ) . +.Fn timegm +interprets the input structure as representing Universal Coordinated Time +.Pq Tn UTC . +.Pp +The original values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are ignored, and the original values of the +other components are not restricted to their normal ranges. +(A positive or zero value for +.Fa tm_isdst +causes +.Fn mktime +to presume initially that summer time (for example, Daylight Saving Time) +is or is not in effect for the specified time, respectively. +A negative value for +.Fa tm_isdst +causes the +.Fn mktime +function to attempt to divine whether summer time is in effect for the +specified time. +The +.Fa tm_isdst +and +.Fa tm_gmtoff +members are forced to zero by +.Fn timegm . ) +.Pp +On successful completion, the values of the +.Fa tm_wday +and +.Fa tm_yday +components of the structure are set appropriately, and the other components +are set to represent the specified calendar time, but with their values +forced to their normal ranges; the final value of +.Fa tm_mday +is not set until +.Fa tm_mon +and +.Fa tm_year +are determined. +.Fn Mktime +returns the specified calendar time; if the calendar time cannot be +represented, it returns \-1; +.Pp +The +.Fn difftime +function +returns the difference between two calendar times, +.Pf ( Fa time1 +- +.Fa time0 ) , +expressed in seconds. +.Pp +External declarations as well as the tm structure definition are in the +.Aq Pa time.h +include file. +The tm structure includes at least the following fields: +.Bd -literal -offset indent +int tm_sec; /\(** seconds (0 - 60) \(**/ +int tm_min; /\(** minutes (0 - 59) \(**/ +int tm_hour; /\(** hours (0 - 23) \(**/ +int tm_mday; /\(** day of month (1 - 31) \(**/ +int tm_mon; /\(** month of year (0 - 11) \(**/ +int tm_year; /\(** year \- 1900 \(**/ +int tm_wday; /\(** day of week (Sunday = 0) \(**/ +int tm_yday; /\(** day of year (0 - 365) \(**/ +int tm_isdst; /\(** is summer time in effect? \(**/ +char \(**tm_zone; /\(** abbreviation of timezone name \(**/ +long tm_gmtoff; /\(** offset from UTC in seconds \(**/ +.Ed +.Pp +The +field +.Fa tm_isdst +is non-zero if summer time is in effect. +.Pp +The field +.Fa tm_gmtoff +is the offset (in seconds) of the time represented from +.Tn UTC , +with positive +values indicating east of the Prime Meridian. +.Sh SEE ALSO +.Xr date 1 , +.Xr gettimeofday 2 , +.Xr getenv 3 , +.Xr time 3 , +.Xr tzset 3 , +.Xr tzfile 5 +.Sh STANDARDS +The +.Fn asctime , +.Fn ctime , +.Fn difftime , +.Fn gmtime , +.Fn localtime , +and +.Fn mktime +functions conform to +.St -isoC , +and conform to +.St -p1003.1 +provided the selected local timezone does not contain a leap-second table +(see +.Xr zic 8 ) . +.Pp +The +.Fn asctime_r , +.Fn ctime_r , +.Fn gmtime_r , +and +.Fn localtime_r +functions are expected to conform to +.St -iso9945-1 +(again provided the selected local timezone does not contain a leap-second +table). +.Pp +The +.Fn timegm +function is not specified by any standard; its function cannot be +completely emulated using the standard functions described above. +.Sh HISTORY +This manual page is derived from +the time package contributed to Berkeley by +.An Arthur Olson +and which appeared in +.Bx 4.3 . +.Sh BUGS +Except for +.Fn difftime , +.Fn mktime , +and the +.Fn \&_r +variants of the other functions, +these functions leaves their result in an internal static object and return +a pointer to that object. Subsequent calls to these +function will modify the same object. +.Pp +The C Standard provides no mechanism for a program to modify its current +local timezone setting, and the +.Tn POSIX Ns No \&-standard +method is not reentrant. (However, thread-safe implementations are provided +in the +.Tn POSIX +threaded environment.) +.Pp +The +.Fa tm_zone +field of a returned tm structure points to a static array of characters, +which will also be overwritten by any subsequent calls (as well as by +subsequent calls to +.Xr tzset 3 +and +.Xr tzsetwall 3 ) . +.Pp +Use of the external variable +.Fa tzname +is discouraged; the +.Fa tm_zone +entry in the tm structure is preferred. |
