unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

CTIME(3V)                                                            CTIME(3V)



NAME
       ctime,  asctime, dysize, gmtime, localtime, strftime, strptime, timegm,
       timelocal, tzset, tzsetwall - convert date and time

SYNOPSIS
       #include <&lt;time.h>&gt;

       char *ctime(clock)
       time_t *clock;

       char *asctime(tm)
       struct tm *tm;

       int dysize(y)
       int y;

       struct tm *gmtime(clock)
       time_t *clock;

       struct tm *localtime(clock)
       time_t *clock;

       int strftime(buf, bufsize, fmt, tm)
       char *buf;
       int bufsize;
       char *fmt;
       struct tm *tm;

       char *strptime(buf, fmt, tm)
       char *buf;
       char *fmt;
       struct tm *tm;

       time_t timegm(tm)
       struct tm *tm;

       time_t timelocal(tm)
       struct tm *tm;

       void tzset()

       void tzsetwall()

SYSTEM V SYNOPSIS
       In addition to the routines above, the following variables  are  avail-
       able:

       extern long timezone;

       extern int daylight;

       extern char *tzname[2];

DESCRIPTION
       ctime() converts a long integer, pointed to by clock, to a 26-character
       string of the form produced by asctime().  It first breaks  down  clock
       to  a  tm structure by calling localtime(), and then calls asctime() to
       convert that tm structure to a string.

       asctime() converts a time value  contained  in  a  tm  structure  to  a
       26-character string of the form:

              Sun Sep 16 01:03:52 1973\n\0

       Each  field  has  a constant width.  asctime() returns a pointer to the
       string.

       dysize() returns the number of days in the argument year, either 365 or
       366.  localtime() and gmtime() return pointers to structures containing
       the time, broken down into various components of that time  represented
       in a particular time zone.  localtime() breaks down a time specified by
       the value pointed to by the clock argument,  correcting  for  the  time
       zone  and  any  time  zone adjustments (such as Daylight Savings Time).
       Before doing so, localtime() calls tzset() (if  tzset()  has  not  been
       called  in the current process).  gmtime() breaks down a time specified
       by the value pointed to by the clock argument into GMT,  which  is  the
       time the system uses.

       strftime()  converts a time value contained in the tm structure pointed
       to by tm to a character string in a format specified by fmt.  The char-
       acter  string  is  placed  into  the  array pointed to by buf, which is
       assumed to contain room for at least buflen characters.  If the  result
       contains  no more than buflen characters, strftime() returns the number
       of characters produced (not including the terminating null  character).
       Otherwise, it returns zero and the contents of the array are indetermi-
       nate.  fmt is a character string that consists of field descriptors and
       text characters, reminiscent of printf(3V).  Each field descriptor con-
       sists of a % character followd by another character that specifies  the
       replacement  for the field descriptor.  All other characters are copied
       from fmt into the result.  The following  field  descriptors  are  sup-
       ported:

              %%     same as %

              %a     day of week, using locale's abbreviated weekday names

              %A     day of week, using locale's full weekday names

              %b
              %h     month, using locale's abbreviated month names

              %B     month, using locale's full month names

              %c     date and time as %x %X

              %C     date and time, in locale's long-format date and time rep-
                     resentation

              %d     day of month (01-31)

              %D     date as %m/%d/%y

              %e     day of month (1-31;  single  digits  are  preceded  by  a
                     blank)

              %H     hour (00-23)

              %I     hour (00-12)

              %j     day number of year (001-366)

              %k     hour (0-23; single digits are preceded by a blank)

              %l     hour (1-12; single digits are preceded by a blank)

              %m     month number (01-12)

              %M     minute (00-59)

              %n     same as \n

              %p     locale's equivalent of AM or PM, whichever is appropriate

              %r     time as %I:%M:%S %p

              %R     time as %H:%M

              %S     seconds (00-59)

              %t     same as \t

              %T     time as %H:%M:%S

              %U     week  number  of year (01-52), Sunday is the first day of
                     the week

              %w     day of week; Sunday is day 0

              %W     week number of year (01-52), Monday is the first  day  of
                     the week

              %x     date, using locale's date format

              %X     time, using locale's time format

              %y     year within century (00-99)

              %Y     year, including century (fore example, 1988)

              %Z     time zone abbreviation

       The  difference  between  %U and %W lies in which day is counted as the
       first day of the week.  Week number 01 is the first week with  four  or
       more January days in it.

       strptime()  converts  the  character string pointed to by buf to a time
       value, which is stored in the tm structure pointed to by tm, using  the
       format specified by fmt.  A pointer to the character following the last
       character in the string pointed to by buf is returned.  fmt is a  char-
       acter  string  that  consists of field descriptors and text characters,
       reminiscent of scanf(3v).  Each field descriptor consists of a %  char-
       acter  followd  by another character that specifies the replacement for
       the field descriptor.  All other characters are copied  from  fmt  into
       the result.  The following field descriptors are supported:

              %%     same as %

              %a
              %A     day  of  week,  using  locale's weekday names; either the
                     abbreviated or full name may be specified

              %b
              %B
              %h     month, using locale's month names; either the abbreviated
                     or full name may be specified

              %c     date and time as %x %X

              %C     date and time, in locale's long-format date and time rep-
                     resentation

              %d
              %e     day of month (1-31; leading zeroes are permitted but  not
                     required)

              %D     date as %m/%d/%y

              %H
              %k     hour   (0-23;   leading  zeroes  are  permitted  but  not
                     required)

              %I
              %l     hour  (0-12;  leading  zeroes  are  permitted   but   not
                     required)

              %j     day number of year (001-366)

              %m     month  number (1-12; leading zeroes are permitted but not
                     required)

              %M     minute  (0-59;  leading  zeroes  are  permitted  but  not
                     required)

              %p     locale's equivalent of AM or PM

              %r     time as %I:%M:%S %p

              %R     time as %H:%M

              %S     seconds  (0-59;  leading  zeroes  are  permitted  but not
                     required)

              %T     time as %H:%M:%S

              %x     date, using locale's date format

              %X     time, using locale's time format

              %y     year within century (0-99; leading zeroes  are  permitted
                     but not required)

              %Y     year, including century (for example, 1988)

       Case  is  ignored  when  matching items such as month or weekday names.
       The %M, %S, %y, and %Y fields are optional; if they would be matched by
       white  space,  the match is suppressed and the appropriate field of the
       tm structure pointed to by tm is left unchanged.  If any of the  format
       items  %d,  %e,  %H, %k, %I, %l, %m, %M, %S, %y, or %Y are matched, but
       the string that matches them is followed by white space, all subsequent
       items  in the format string are skipped up to white space or the end of
       the format.  The net result is that, for example, the  format  %m/%d/%y
       can  be  matched  by the string 12/31; the tm_mon and tm_mday fields of
       the tm structure pointed to by tm will be set to  11  and  31,  respec-
       tively, while the tm_year field will be unchanged.

       timelocal()  and  timegm()  convert  the  time  specified  by the value
       pointed to by the tm argument to a time value that represents that time
       expressed as the number of seconds since Jan. 1, 1970, 00:00, Greenwich
       Mean Time.  timelocal() converts a tm structure that  represents  local
       time,  correcting for the time zone and any time zone adjustments (such
       as Daylight Savings Time).  Before doing so, timelocal() calls  tzset()
       (if tzset() has not been called in the current process).  timegm() con-
       verts a tm structure that represents GMT.

       tzset() uses the value of the environment variable TZ to set time  con-
       version  information  used  by  localtime().   If TZ is absent from the
       environment, the an available approximation to local wall clock time is
       used by localtime().  If TZ appears in the environment but its value is
       a null string, Greenwich Mean Time is used; if TZ  appears  and  begins
       with  a slash, it is used as the absolute pathname of the tzfile-format
       (see tzfile(5)) file from which to read the  time  conversion  informa-
       tion;  if TZ appears and begins with a character other than a slash, it
       is used as a pathname relative to a system time conversion  information
       directory.

       tzsetwall()  sets things up so that localtime() returns the best avail-
       able approximation of local wall clock time.

       Declarations of all the functions and externals, and the tm  structure,
       are  in the <&lt;time.h>&gt; header file.  The structure (of type) tm structure
       includes the following fields:

                   int tm_sec;      /* seconds (0 - 59) */
                   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;    /* 1 if DST in effect */
                   char *tm_zone;   /* abbreviation of timezone name */
                   long tm_gmtoff;  /* offset from GMT in seconds */

       tm_isdst is non-zero if Daylight Savings Time is  in  effect.   tm_zone
       points to a string that is the name used for the local time zone at the
       time being converted.  tm_gmtoff is the offset (in seconds) of the time
       represented  from  GMT,  with positive values indicating East of Green-
       wich.

SYSTEM V DESCRIPTION
       The external long variable timezone contains the  difference,  in  sec-
       onds,  between  GMT  and  local  standard  time  (in  PST,  timezone is
       8*60*60).  If this difference is not a constant, timezone will  contain
       the value of the offset on January 1, 1970 at 00:00 GMT.  Since this is
       not necessarily the same as the value at some particular time, the time
       in question should be converted to a tm structure using localtime() and
       the tm_gmtoff field of that structure should  be  used.   The  external
       variable  daylight  is  non-zero  if  and only if Daylight Savings Time
       would be in effect within the current time zone at some time;  it  does
       not indicate whether Daylight Savings Time is currently in effect.

       The  external  variable tzname is an array of two char * pointers.  The
       first pointer points to a character string that is the name of the cur-
       rent  time zone when Daylight Savings Time is not in effect; the second
       one, if Daylight Savings Time conversion should be applied, points to a
       character  string  that  is the name of the current time zone when Day-
       light Savings Time is in effect.  These strings are updated  by  local-
       time()  whenever  a  time is converted.  If Daylight Savings Time is in
       effect at the time being converted, the second pointer is set to  point
       to  the name of the current time zone at that time, otherwise the first
       pointer is so set.

       timezone, daylight, and tzname  are  retained  for  compatibility  with
       existing programs.

FILES
       /usr/share/lib/zoneinfo       standard   time   conversion  information
                                     directory
       /usr/share/lib/zoneinfo/localtime
                                     local time zone file
SEE ALSO
       gettimeofday(2), getenv(3V), time(3V), environ(5V), tzfile(5)
BUGS
       The return values point to static data, whose contents are  overwritten
       by each call.  The tm_zone field of a returned tm structure points to a
       static array of characters, which will also be overwritten at the  next
       call (and by calls to tzset() or tzsetwall()).



                                5 October 1989                       CTIME(3V)