DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

/usr/man2/cat.3/tm.3.Z(/usr/man2/cat.3/tm.3.Z)





NAME

       tm - seconds resolution time conversion support


SYNOPSIS

       #include <tm.h>


DESCRIPTION

       The  tm library supports conversion between string date specifications,
       seconds reolution time_t clock values and Tm_t.  Tm_t contains the ele-
       ments of struct tm along with these additions:

       unsigned _ast_int4_t tm_nsec
              The subsecond portion of the time in nanoseconds.

       Tm_zone_t* tm_zone
              The time zone name.

       localtime()  and  gmtime()  (see  ctime(3)) are used to determine local
       time zone and savings time 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.

       Tm_t* tmfix(Tm_t* 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_isdst is not changed -- call tmtime() to deter-
              mine its proper value after the tmfix() adjustments.

       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  printf(3) style, where %field names a fixed size
              field, zero padded if necessary, and \c and \nnn  sequences  are
              as  in C. Invalid %field specifications and all other characters
              are copied without change.  field may be preceded by %- to  turn
              off  padding  or  %_ to pad with space, otherwise numeric fields
              are padded with 0 and  string  fields  are  padded  with  space.
              field may also be preceded by E for alternate era representation
              or O for alternate digit representation  (if  supported  by  the
              current  locale.)   Finally,  an  integral width preceding field
              truncates the field to width characters.  sequences  are  inter-
              preted as in the C language.  String field values are taken from
              the tm_info.format string table.  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.
              f      Locale default override date format.
              F      Locale default date format (tm_info.format[40].)
              h      Abbreviated month name.
              H      24-hour clock hour.
              i      International date(1) date that includes  the  time  zone
                     type name (tm_info.format[107].)
              I      12-hour clock hour.
              j      1-offset Julian date.
              J      0-offset Julian date.
              k      date(1) style date (tm_info.format[106].)
              K      Language  neutral,  all  numeric,  no embedded space date
                     with larger to smaller time units  from  left  to  right,
                     suitable for sorting: '"%Y-%m-%d+%H:%M:%S"'.
              l      ls(1) -l date that lists recent dates with %g and distant
                     dates with %G.
              m      Month number.
              M      Minutes.
              n      newline character.
              N      The time zone type or nation code.
              p      Meridian (e.g., AM or PM.)
              q      The nanosecond part of the time.
              %Q<delim>recent<delim>distant<delim>
                     Recent dates are formatted with recent and distand  dates
                     are  formatted with distant, where <delim> is any charac-
                     ter not appearing in recent or distant.
              r      12-hour time as hh:mm:ss meridian.
              R      24-hour time as hh:mm.
              s      Seconds since the epoch.  .prec preceding s appends  prec
                     nanosecond digits, 9 if prec is omitted.
              S      seconds.subseconds since the epoch.
              t      tab character.
              T      24-hour time as hh:mm:ss.
              u      Weeday number with 1 for Monday, 7 for Sunday.
              U      Week number with Sunday as the first day.
              V      ISO week number (i18n is fun.)
              w      Weekday number with 0 for Sunday, 6 for Saturday.
              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 (you'll be sorry.)
              Y      4-digit year.
              z      Time zone SHHMM west of GMT offset where S is + or -.
              Z      Time zone name.
              =[=]][-+]]flag
                     Set (default or +) or clear (-) flag in tm_info.flags for
                     the remainder of format, or  for  the  remainder  of  the
                     process if == is specified.  flag may be:
                     l      (TM_LEAP) Enable leap second adjustments.
                     s      (TM_SUBSECOND) Append nanosecond .%N to %S.
                     u      (TM_UTC) UTC time zone.
              #      Equivalent to %s.
              ?alternate
                     Use alternate format is a default format override has not
                     been  specified.   e.g.,   ls(1)   uses   %?%l.    Export
                     TM_OPTIONS="format='override'" to override the default.

       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.

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

       time_t tmtime(Tm_t* 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     tmfmt() local time format used by the %X field.
              39     tmfmt() local date format used by the %x field.
              40     tmfmt()  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  tmfmt().
              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-84  Noise words to be ignored: at, in, on.
              85-94  Ordinal suffixes: st, nd, rd, th, th, th, th, th, th, th.
              95-104 Digit names.
              105    The   tmfmt()    format    equivalent    for    ctime(3):
                     '"%a%b%e%T%Y"'.
              106    The tmfmt() date(1) default format: '"%a%b%e%T%Z%Y"'.
              107    The     tmfmt()     date(1)     international     format:
                     '"%a%b%e%T%z%Z%Y"'
              108    The tmfmt() ls(1) recent date format: '"%b%e%H:%M"'.
              109    The tmfmt() ls(1) distant date format: '"%b%e%Y"'.
              110    The tmfmt() date(1) meridian date format: '"%I:%M:%S%p"'.
              111    The ERA name.
              112    ERA alternative for 39.
              113    ERA alternative for 38.
              114    ERA alternative for 40.
              115    The ERA year.
              116-125
                     Ordinal  names:  first, no second!, third, fourth, fifth,
                     sixth, seventh, eighth, ninth, tenth.
              126-128
                     Final time references, as in the last in the list: final,
                     ending, nth.

       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)tmfmt(buf, sizeof(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

       The  C  library static struct tm values may get clobbered by tm library
       routines as the ctime(3) and  localtime(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  incom-
       plete.

                                                                         TM(3)
See also Time::tm(3)
See also tmx(3)

Man(1) output converted with man2html