DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

tmx(3)





NAME

       tm - time conversion support


SYNOPSIS

       #include <tm.h>


DESCRIPTION

       The  tm library supports conversion between string date specifications,
       time_t clock values and struct tm  values.   localtime()  and  gmtime()
       (see ctime(3)) are used to determine local time zone information.

       time_t values are the number of seconds since the epoch, Jan 1 00:00:00
       GMT 1970, with leap seconds omitted.

       The global variable int tm_info.flags contains  flags  that  allow  all
       programs  using  the  library  to be controlled in a consistent manner.
       tm_info.flags is initialized by the tminit() routine  described  below,
       and may be explicitly reset after tminit() is called.  The flags are:

       TM_ADJUST
              Set  by  tminit()  if localtime() and gmtime() do not compensate
              for leap seconds.

       TM_LEAP
              time_t values are interpreted as if they include  leap  seconds.
              Set  by  tminit()  if  the  leap option is set in the TM_OPTIONS
              environment variable.

       TM_UTC Times are relative to UTC  (universal  coordinated  time,  i.e.,
              GMT).  Otherwise times are relative to the local time zone.  Set
              by tminit() if the time zone name matches  one  of  tm_info.for-
              mat[43] through tm_info.format[46] described below.  If the time
              zone name is not determined by localtime() then the  environment
              variables  TZNAME (as described in BSD 4.3) and TZ (as described
              in System V) are checked, in order.  If this fails then the time
              zone name is constructed using the local time zone offset.

       The routines are:

       time_t tmdate(const char* date, char** end, time_t* clock)
              Parses  the  date  specification  date  using the tm_info.format
              string table (described below) and returns the equivalent time_t
              value.   If  non-NULL,  end  is set to the position of the first
              unrecognized character  in  date.   clock  is  used  to  provide
              default values for omitted components in date.  If clock is NULL
              then the current time is used.

       struct tm* tmfix(struct tm* tp)
              Corrects any out of bounds fields in tp and returns  tp  as  its
              value.  The corrections start with tp->tm_sec and propagate down
              to tp->tm_year.  For example, if  tp->tm_sec  were  61  then  it
              would  change to 1 and tp->tm_min would be incremented by 1, and
              so  on.   tp->tm_wday,  tp->tm_yday  and  tp->tm_isdst  are  not
              changed as these can be computed from the other fields.

       char* tmfmt(char* buf, size_t len, const char* format, time_t* clock)
              Formats  the  date  pointed to by clock into the buffer buf with
              size len bytes according to the format specification format.  If
              format  is  NULL  or empty then the string tm_info.format[40] is
              used.  If clock is NULL  then  the  current  time  is  used.   A
              pointer  to  the  end  of  buf  (i.e.,  the terminating '\0') is
              returned.

              format is in the style of printf(3),  where  %field  causes  the
              corresponding  fixed size field to be placed in buf, zero padded
              if necessary, and \c and \nnn sequences are  interpreted  as  in
              the C language.  Otherwise invalid %field specifications and all
              other characters in format are copied into buf  without  change.
              String field values are taken from the tm_info.format string ta-
              ble.  The fields are:

              %      % character.
              a      Abbreviated weekday name.
              A      Full weekday name.
              b      Abbreviated month name.
              c      ctime(3) style date without the trailing newline.
              C      date(1) style date.
              d      Day of month number.
              D      Date as mm/dd/yy.
              e      Blank padded day of month number.
              E      Unpadded day of month number.
              h      Abbreviated month name.
              H      24-hour clock hour.
              i      International date(1) date that includes  the  time  zone
                     type name.
              I      12-hour clock hour.
              j      1-offset Julian date.
              J      0-offset Julian date.
              l      ls(1) -l date that lists recent dates with hh:mm and dis-
                     tant dates with yyyy.
              m      Month number.
              M      Minutes.
              n      newline character.
              p      Meridian (e.g., AM or PM).
              r      12-hour time as hh:mm:ss meridian.
              R      24-hour time as hh:mm.
              S      Seconds.
              t      tab character.
              T      24-hour time as hh:mm:ss.
              U      Week number with Sunday as the first day.
              w      Weekday number.
              W      Week number with Monday as the first day.
              x      Local date style, using tm_info.format[39], that includes
                     the month, day and year.
              X      Local time style, using tm_info.format[38], that includes
                     the hours and minutes.
              y      2-digit year.
              Y      4-digit year.
              z      Time zone type name.
              Z      Time zone name.
              +flag
              -flag  Temporarily (until tmform() returns) sets (+)  or  clears
                     (-) the tm_info.flags flags specified by flag:
                     l      TM_LEAP
                     u      TM_UTC
              #      Number of seconds since the epoch.

       void tminit(Tm_zone_t* zone)
              Implicitly called by the other tm library routines to initialize
              global  data,  including  the  tm_info.format  table   and   the
              tm_info.flags global flags.  Global data should only be modified
              after an explicit call to tminit.  If zone != 0 then  it  speci-
              fies a time zone other that the local time zone.

       void tmset(Tm_zone_t* zone);
              tmset  sets the reference timezoe to zone.  tm_info.local points
              to the local timezone and tm_info.zone  points  to  the  current
              reference timezone.

       time_t tmleap(time_t* clock)
              Returns  a  time_t  value  for the time pointed to by clock with
              leap seconds adjusted for external routines that do  not  handle
              leap  seconds.   If clock is NULL then the current time is used.
              Adjustments are only done  if  the  TM_ADJUST  flag  is  set  in
              tm_info.flags.

       struct tm* tmmake(time_t* clock)
              Returns  a  pointer  to  the tm struct corresponding to the time
              pointed to by clock.  If clock is NULL then the current time  is
              used.

       time_t tmtime(struct tm* tp, int west)
              Returns  the  time_t  value  corresponding  to  tp.   If west is
              TM_LOCALZONE then tm is relative to the local time zone,  other-
              wise  west  is  the  number of minutes west of UTC with daylight
              savings time taken into account.  tp->tm_wday,  tp->tm_yday  and
              tp->tm_isdst are ignored in the conversion.

       The  library  routines use a table of date strings pointed to by char**
       tm_info.format.  The indices in tm_info.format are fixed  by  category.
       tm_info.format  may  be  changed  to point to other tables according to
       local language and date conventions.  The contents  by  index  (showing
       the USA English values) are:

              0-11   3-character abbreviated month names.
              12-23  Full month names.
              24-30  3-character abbreviated weekday names.
              31-37  Full weekday names.
              38     tmform() local time format used by the %X field.
              39     tmform() local date format used by the %x field.
              40     tmform()  format  used  if the format argument is NULL or
                     empty.
              41-42  Meridian names: AM, PM.
              43-46  UTC time zone names: GMT, UTC, UCT, CUT.
              47-50  Daylight savings time suffix names: DST.
              51-54  Suffixes to be ignored when matching strings in tmform().
              55-61  Time  part names: second, hour, minute, day, week, month,
                     year.
              62-65  Hours of the day names: midnight, morning, noon, evening.
              66-68  Relative day names: yesterday, today, tomorrow.
              69-71  Past relative time references: last, ago, past.
              72-75  Current relative time references: this, now, current.
              75-77  Future relative time references: next, hence, coming.
              78-80  Exact relative time references: exactly.
              81-85  Noise words to be ignored: at, in, on.

       Low level support functions and data are described in <tm.h>.


EXAMPLES

              #include <tm.h>
              main() {
                  int       i;
                  time_t    t;
                  char      buf[128];
                  struct {
                      char* date;
                      char* format;
                  }         x[] = {
                      "now",                 "%i",
                      "2 months ago",        "%C",
                      "this Wednesday noon", "%x %I:%M %p",
                      "last December 25",    "%A",
                      0,                     0
                  };
                  for (i = 0; x[i].date; i++) {
                      t = tmdate(x[i].date, (char*)0, (time_t*)0);
                      (void)tmform(buf, x[i].format, &t);
                      puts(buf);
                  }
              }

       produces

              Fri Sep 30 12:10:14 USA EDT 1988
              Fri Jul  1 00:00:00 EDT 1988
              10/05/88 12:00 PM
              Friday


SEE ALSO

       date(1), time(2), ctime(3)


BUGS

       struct  tm  values  may get clobbered by the tm library routines as the
       ctime(3) routines typically return pointers to a single  static  struct
       tm  area.  tmdate() uses an internal international time zone name table
       that will probably always be incomplete.

                                                                         TM(3)

Man(1) output converted with man2html