man/man3/ctime.3

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)ctime.3     6.8 (Berkeley) 4/2/87
   6 .\"
   7 .TH CTIME 3  "April 2, 1987"
   8 .UC 4
   9 .SH NAME
  10 ctime, localtime, gmtime, asctime, tzset \-  convert date and time to ASCII
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <sys/types.h>
  15 #include <time.h>
  16
  17 void tzset(void)
  18 char *ctime(const time_t *\fIclock\fP)
  19 char *asctime(const struct tm *\fItm\fP)
  20 struct tm *localtime(const time_t *\fIclock\fP)
  21 struct tm *gmtime(const time_t *\fIclock\fP)
  22 .fi
  23 .SH DESCRIPTION
  24 \fBTzset\fP uses the value of the environment variable \fBTZ\fP to
  25 set up the time conversion information used by \fBlocaltime\fP.
  26 .PP
  27 If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP
  28 file (as defined in \fI<tzfile.h>\fP) is used by \fBlocaltime\fP.  If
  29 this file fails for any reason, the GMT offset as provided by the
  30 kernel is used.  In this case, DST is ignored, resulting in the time
  31 being incorrect by some amount if DST is currently in effect.  If
  32 this fails for any reason, GMT is used.
  33 .PP
  34 If \fBTZ\fP appears in the environment but its value is a null string,
  35 Greenwich Mean Time is used; if \fBTZ\fP appears and begins with a
  36 slash, it is used as the absolute pathname of the \fBtzfile\fP(5)-format
  37 file from which to read the time conversion information; if \fBTZ\fP
  38 appears and begins with a character other than a slash, it's used as
  39 a pathname relative to the system time conversion information directory,
  40 defined as \fBTZDIR\fP in the include file \fBtzfile.h\fP.  If this file
  41 fails for any reason, the GMT offset as provided by the kernel is
  42 used, as described above.  If this fails for any reason, GMT is used.
  43 See
  44 .BR TZ (5)
  45 for a proper description of the
  46 .B TZ
  47 variable.
  48 .PP
  49 \fBCtime\fP converts a time value, pointed to by \fIclock\fP,
  50 such as returned by \fBtime\fP(2) into ASCII and returns a pointer
  51 to a 26-character string in the following form.  All the fields
  52 have constant width.
  53 .PP
  54 .RS
  55 .nf
  56 Sun Sep 16 01:03:52 1973\en\e0
  57 .fi
  58 .RE
  59 .PP
  60 .B Localtime
  61 and
  62 .B gmtime
  63 return pointers to structures containing
  64 the broken-down time.
  65 .B Localtime
  66 corrects for the time zone and possible daylight savings time;
  67 .B gmtime
  68 converts directly to GMT, which is the time UNIX uses.
  69 .B Asctime
  70 converts a broken-down time to ASCII and returns a pointer
  71 to a 26-character string.
  72 .PP
  73 The structure declaration from the include file is:
  74 .PP
  75 .RS
  76 .nf
  77 .nr .0 .8i+\w'int tm_isdst'u
  78 .ta .5i \n(.0u \n(.0u+\w'/* 0-000'u+1n
  79 struct tm {
  80         int tm_sec;     /* 0-59 seconds */
  81         int tm_min;     /* 0-59 minutes */
  82         int tm_hour;    /* 0-23 hour */
  83         int tm_mday;    /* 1-31 day of month */
  84         int tm_mon;     /* 0-11 month */
  85         int tm_year;    /* 0-   year \- 1900 */
  86         int tm_wday;    /* 0-6  day of week (Sunday = 0) */
  87         int tm_yday;    /* 0-365        day of year */
  88         int tm_isdst;   /* flag:        daylight savings time in effect */
  89 };
  90 .fi
  91 .RE
  92 .PP
  93 \fBTm_isdst\fP is non-zero if a time zone adjustment such as Daylight
  94 Savings time is in effect.
  95 .SH FILES
  96 .ta \w'/usr/lib/zoneinfo\0\0'u
  97 /usr/lib/zoneinfo       time zone information directory
  98 .br
  99 /etc/localtime  local time zone file
 100 .SH SEE ALSO
 101 .BR time (2),
 102 .BR getenv (3),
 103 .BR tzfile (5),
 104 .BR TZ (5),
 105 .BR environ (7),
 106 .BR zic (8).
 107 .SH NOTE
 108 The return values point to static data whose content is overwritten by
 109 each call.