time.h(0p)

1<time.h>(P)                POSIX Programmer's Manual               <time.h>(P)
2
3
4

NAME

6       time.h - time types
7

SYNOPSIS

9       #include <time.h>
10

DESCRIPTION

12       Some  of the functionality described on this reference page extends the
13       ISO C standard. Applications shall define the appropriate feature  test
14       macro  (see  the System Interfaces volume of IEEE Std 1003.1-2001, Sec‐
15       tion 2.2, The Compilation Environment)  to  enable  the  visibility  of
16       these symbols in this header.
17
18       The <time.h> header shall declare the structure tm, which shall include
19       at least the following members:
20
21
22              int    tm_sec   Seconds [0,60].
23              int    tm_min   Minutes [0,59].
24              int    tm_hour  Hour [0,23].
25              int    tm_mday  Day of month [1,31].
26              int    tm_mon   Month of year [0,11].
27              int    tm_year  Years since 1900.
28              int    tm_wday  Day of week [0,6] (Sunday =0).
29              int    tm_yday  Day of year [0,365].
30              int    tm_isdst Daylight Savings flag.
31
32       The value of tm_isdst shall be positive if Daylight Savings Time is  in
33       effect,  0  if  Daylight Savings Time is not in effect, and negative if
34       the information is not available.
35
36       The <time.h> header shall define the following symbolic names:
37
38       NULL   Null pointer constant.
39
40       CLOCKS_PER_SEC
41              A number used to convert the value returned by the clock() func‐
42              tion into seconds.
43
44       CLOCK_PROCESS_CPUTIME_ID
45
46              The identifier of the CPU-time clock associated with the process
47              making a clock() or timer*() function call.
48
49       CLOCK_THREAD_CPUTIME_ID
50
51              The identifier of the CPU-time clock associated with the  thread
52              making a clock() or timer*() function call.
53
54
55       The  <time.h> header shall declare the structure timespec, which has at
56       least the following members:
57
58
59              time_t  tv_sec    Seconds.
60              long    tv_nsec   Nanoseconds.
61
62       The <time.h> header shall also declare the itimerspec structure,  which
63       has at least the following members:
64
65
66              struct timespec  it_interval  Timer period.
67              struct timespec  it_value     Timer expiration.
68
69       The following manifest constants shall be defined:
70
71       CLOCK_REALTIME
72              The identifier of the system-wide realtime clock.
73
74       TIMER_ABSTIME
75              Flag  indicating  time  is  absolute. For functions taking timer
76              objects, this refers to the clock associated with the timer.
77
78       CLOCK_MONOTONIC
79
80              The identifier for the system-wide  monotonic  clock,  which  is
81              defined as a clock whose value cannot be set via clock_settime()
82              and which cannot have backward clock jumps. The maximum possible
83              clock jump shall be implementation-defined.
84
85
86       The  clock_t,  size_t, time_t,   clockid_t, and timer_t  types shall be
87       defined as described in <sys/types.h> .
88
89       Although the value of CLOCKS_PER_SEC is required to be 1 million on all
90       XSI-conformant  systems,  it  may  be variable on other systems, and it
91       should not be assumed that CLOCKS_PER_SEC is a compile-time constant.
92
93       The <time.h> header shall provide a declaration for getdate_err.
94
95       The following shall be declared as functions and may also be defined as
96       macros. Function prototypes shall be provided.
97
98
99              char      *asctime(const struct tm *);
100
101              char      *asctime_r(const struct tm *restrict, char *restrict);
102
103              clock_t    clock(void);
104
105              int        clock_getcpuclockid(pid_t, clockid_t *);
106
107
108              int        clock_getres(clockid_t, struct timespec *);
109              int        clock_gettime(clockid_t, struct timespec *);
110
111
112              int        clock_nanosleep(clockid_t, int, const struct timespec *,
113                             struct timespec *);
114
115
116              int        clock_settime(clockid_t, const struct timespec *);
117
118              char      *ctime(const time_t *);
119
120              char      *ctime_r(const time_t *, char *);
121
122              double     difftime(time_t, time_t);
123
124              struct tm *getdate(const char *);
125
126              struct tm *gmtime(const time_t *);
127
128              struct tm *gmtime_r(const time_t *restrict, struct tm *restrict);
129
130              struct tm *localtime(const time_t *);
131
132              struct tm *localtime_r(const time_t *restrict, struct tm *restrict);
133
134              time_t     mktime(struct tm *);
135
136              int        nanosleep(const struct timespec *, struct timespec *);
137
138              size_t     strftime(char *restrict, size_t, const char *restrict,
139                         const struct tm *restrict);
140
141              char      *strptime(const char *restrict, const char *restrict,
142                             struct tm *restrict);
143
144              time_t     time(time_t *);
145
146              int        timer_create(clockid_t, struct sigevent *restrict,
147                             timer_t *restrict);
148              int        timer_delete(timer_t);
149              int        timer_gettime(timer_t, struct itimerspec *);
150              int        timer_getoverrun(timer_t);
151              int        timer_settime(timer_t, int, const struct itimerspec *restrict,
152                             struct itimerspec *restrict);
153
154
155              void       tzset(void);
156
157
158
159       The following shall be declared as variables:
160
161
162              extern int    daylight;
163              extern long   timezone;
164
165
166              extern char  *tzname[];
167
168
169       Inclusion  of the <time.h> header may make visible all symbols from the
170       <signal.h> header.
171
172       The following sections are informative.
173

APPLICATION USAGE

175       The range [0,60] for tm_sec allows for the occasional leap second.
176
177       tm_year is a signed value; therefore, years before 1900 may  be  repre‐
178       sented.
179
180       To  obtain the number of clock ticks per second returned by the times()
181       function, applications should call sysconf(_SC_CLK_TCK).
182

RATIONALE

184       The range [0,60] seconds allows for positive or negative leap  seconds.
185       The  formal  definition  of UTC does not permit double leap seconds, so
186       all mention of double leap seconds has  been  removed,  and  the  range
187       shortened  from  the former [0,61] seconds seen in previous versions of
188       POSIX.
189

FUTURE DIRECTIONS

191       None.
192

COPYRIGHT

202       Portions  of  this text are reprinted and reproduced in electronic form
203       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
204       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
205       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
206       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
207       event of any discrepancy between this version and the original IEEE and
208       The  Open Group Standard, the original IEEE and The Open Group Standard
209       is the referee document. The original Standard can be  obtained  online
210       at http://www.opengroup.org/unix/online.html .
211
212
213
214IEEE/The Open Group                  2003                          <time.h>(P)