Add strfxtime.
[kopensolaris-gnu/glibc.git] / time / time.h
1 /* Copyright (C) 1991, 92, 93, 94, 95, 96, 97 Free Software Foundation, Inc.
2    This file is part of the GNU C Library.
3
4    The GNU C Library is free software; you can redistribute it and/or
5    modify it under the terms of the GNU Library General Public License as
6    published by the Free Software Foundation; either version 2 of the
7    License, or (at your option) any later version.
8
9    The GNU C Library is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    Library General Public License for more details.
13
14    You should have received a copy of the GNU Library General Public
15    License along with the GNU C Library; see the file COPYING.LIB.  If not,
16    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17    Boston, MA 02111-1307, USA.  */
18
19 /*
20  *      ISO C Standard: 4.12 DATE and TIME      <time.h>
21  */
22
23 #ifndef _TIME_H
24
25 #if (! defined __need_time_t && !defined __need_clock_t && \
26      ! defined __need_timespec)
27 # define _TIME_H        1
28 # include <features.h>
29
30 __BEGIN_DECLS
31
32 #endif
33
34 #ifdef  _TIME_H
35 /* Get size_t and NULL from <stddef.h>.  */
36 # define __need_size_t
37 # define __need_NULL
38 # include <stddef.h>
39 #endif /* <time.h> included.  */
40
41
42
43 #ifdef  _TIME_H
44
45 /* This defines CLOCKS_PER_SEC, which is the number of processor clock
46    ticks per second.  */
47 # include <bits/time.h>
48
49 /* This is the obsolete POSIX.1-1988 name for the same constant.  */
50 # ifdef __USE_POSIX
51 #  ifndef CLK_TCK
52 #   define CLK_TCK      CLOCKS_PER_SEC
53 #  endif
54 # endif
55
56 #endif /* <time.h> included.  */
57
58
59 #if !defined __clock_t_defined && (defined _TIME_H || defined __need_clock_t)
60 # define __clock_t_defined      1
61
62 # include <bits/types.h>
63
64 /* Returned by `clock'.  */
65 typedef __clock_t clock_t;
66
67 #endif /* clock_t not defined and <time.h> or need clock_t.  */
68 #undef  __need_clock_t
69
70 #if !defined __time_t_defined && (defined _TIME_H || defined __need_time_t)
71 # define __time_t_defined       1
72
73 # include <bits/types.h>
74
75 /* Returned by `time'.  */
76 typedef __time_t time_t;
77
78 #endif /* time_t not defined and <time.h> or need time_t.  */
79 #undef  __need_time_t
80
81
82 #if !defined __timespec_defined && \
83     ((defined _TIME_H && defined __USE_POSIX) || defined __need_timespec)
84 # define __timespec_defined     1
85
86 /* POSIX.4 structure for a time value.  This is like a `struct timeval' but
87    has nanoseconds instead of microseconds.  */
88 struct timespec
89   {
90     long int tv_sec;            /* Seconds.  */
91     long int tv_nsec;           /* Nanoseconds.  */
92   };
93
94 #endif /* timespec not defined and <time.h> or need timespec.  */
95 #undef  __need_timespec
96
97
98 /* Value used for `tm_' field in `struct tmx' if describing the local
99    time.  */
100 #define _LOCALTIME              (0x7fffffff)
101
102 /* Value used for `tm_leapsecond' field if the number cannot be computed.  */
103 #define _NO_LEAP_SECONDS        (0x7fffffff)
104
105
106 #ifdef  _TIME_H
107 /* Used by other time functions.  */
108 struct tm
109 {
110   int tm_sec;                   /* Seconds.     [0-60] (1 leap second) */
111   int tm_min;                   /* Minutes.     [0-59] */
112   int tm_hour;                  /* Hours.       [0-23] */
113   int tm_mday;                  /* Day.         [1-31] */
114   int tm_mon;                   /* Month.       [0-11] */
115   int tm_year;                  /* Year - 1900.  */
116   int tm_wday;                  /* Day of week. [0-6] */
117   int tm_yday;                  /* Days in year.[0-365] */
118   int tm_isdst;                 /* DST.         [-1/0/1]*/
119
120 # ifdef __USE_BSD
121   long int tm_gmtoff;           /* Seconds east of UTC.  */
122   __const char *tm_zone;        /* Timezone abbreviation.  */
123 # else
124   long int __tm_gmtoff;         /* Seconds east of UTC.  */
125   __const char *__tm_zone;      /* Timezone abbreviation.  */
126 # endif
127 };
128
129 #ifdef __USE_ISOC9X
130 /* Extended form of `struct tm' defined in ISO C 9X.  */
131 struct tmx
132 {
133   int tm_sec;                   /* Seconds.     [0-60] (1 leap second) */
134   int tm_min;                   /* Minutes.     [0-59] */
135   int tm_hour;                  /* Hours.       [0-23] */
136   int tm_mday;                  /* Day.         [1-31] */
137   int tm_mon;                   /* Month.       [0-11] */
138   int tm_year;                  /* Year - 1900.  */
139   int tm_wday;                  /* Day of week. [0-6] */
140   int tm_yday;                  /* Days in year.[0-365] */
141   int tm_isdst;                 /* DST.         [-1/0/1]*/
142
143 # ifdef __USE_BSD
144   long int tm_gmtoff;           /* Seconds east of UTC.  */
145 # else
146   long int __tm_gmtoff;         /* Seconds east of UTC.  */
147 # endif
148   __const char *__tm_zonestr;   /* Timezone abbreviation.  */
149
150   int tm_version;               /* Version number.  */
151   int tm_zone;                  /* Minutes offset from UTC [-1439-1439] */
152   int tm_leapsecs;              /* Number of leap seconds applied.  */
153   void *tm_ext;                 /* Extension block.  */
154   size_t tm_extlen;             /* Size of the extension block.  */
155 };
156 #endif
157
158
159 /* Time used by the program so far (user time + system time).
160    The result / CLOCKS_PER_SECOND is program time in seconds.  */
161 extern clock_t clock __P ((void));
162
163 /* Return the current time and put it in *TIMER if TIMER is not NULL.  */
164 extern time_t time __P ((time_t *__timer));
165
166 /* Return the difference between TIME1 and TIME0.  */
167 extern double difftime __P ((time_t __time1, time_t __time0))
168      __attribute__ ((__const__));
169
170 /* Return the `time_t' representation of TP and normalize TP.  */
171 extern time_t mktime __P ((struct tm *__tp));
172
173 /* Subroutine of `mktime'.  Return the `time_t' representation of TP and
174    normalize TP, given that a `struct tm *' maps to a `time_t' as performed
175    by FUNC.  Keep track of next guess for time_t offset in *OFFSET.  */
176 extern time_t __mktime_internal __P ((struct tm *__tp,
177                                       struct tm *(*__func) (const time_t *,
178                                                             struct tm *),
179                                       time_t *__offset));
180
181 #ifdef __USE_ISOC9X
182 /* Return the `time_t' representation of TP and normalize TP, taking
183    account for the extra members in `struct tmx'.  */
184 extern time_t mkxtime __P ((struct tmx *__tp));
185 #endif
186
187
188 /* Format TP into S according to FORMAT.
189    Write no more than MAXSIZE characters and return the number
190    of characters written, or 0 if it would exceed MAXSIZE.  */
191 extern size_t strftime __P ((char *__restrict __s, size_t __maxsize,
192                              __const char *__restrict __format,
193                              __const struct tm *__restrict __tp));
194
195 #ifdef __USE_ISOC9X
196 /* Format TP into S according to FORMAT.
197    Write no more than MAXSIZE characters and return the number
198    of characters written, or 0 if it would exceed MAXSIZE.  */
199 extern size_t strfxtime __P ((char *__restrict __s, size_t __maxsize,
200                               __const char *__restrict __format,
201                               __const struct tmx *__restrict __tp));
202
203
204 #endif
205
206 # ifdef __USE_XOPEN
207 /* Parse S according to FORMAT and store binary time information in TP.
208    The return value is a pointer to the first unparsed character in S.  */
209 extern char *strptime __P ((__const char *__s, __const char *__fmt,
210                             struct tm *__tp));
211 # endif
212
213
214 /* Return the `struct tm' representation of *TIMER
215    in Universal Coordinated Time (aka Greenwich Mean Time).  */
216 extern struct tm *gmtime __P ((__const time_t *__timer));
217
218 /* Return the `struct tm' representation
219    of *TIMER in the local timezone.  */
220 extern struct tm *localtime __P ((__const time_t *__timer));
221
222 # if defined __USE_POSIX || defined __USE_MISC
223 /* Return the `struct tm' representation of *TIMER in UTC,
224    using *TP to store the result.  */
225 extern struct tm *__gmtime_r __P ((__const time_t *__timer,
226                                    struct tm *__tp));
227 extern struct tm *gmtime_r __P ((__const time_t *__timer,
228                                  struct tm *__tp));
229
230 /* Return the `struct tm' representation of *TIMER in local time,
231    using *TP to store the result.  */
232 extern struct tm *__localtime_r __P ((__const time_t *__timer,
233                                       struct tm *__tp));
234 extern struct tm *localtime_r __P ((__const time_t *__timer,
235                                     struct tm *__tp));
236 # endif /* POSIX or misc */
237
238 /* Compute the `struct tm' representation of *T,
239    offset OFFSET seconds east of UTC,
240    and store year, yday, mon, mday, wday, hour, min, sec into *TP.
241    Return nonzero if successful.  */
242 extern int __offtime __P ((__const time_t *__timer,
243                            long int __offset,
244                            struct tm *__tp));
245
246 /* Return a string of the form "Day Mon dd hh:mm:ss yyyy\n"
247    that is the representation of TP in this format.  */
248 extern char *asctime __P ((__const struct tm *__tp));
249
250 /* Equivalent to `asctime (localtime (timer))'.  */
251 extern char *ctime __P ((__const time_t *__timer));
252
253 # if defined __USE_POSIX || defined __USE_MISC
254 /* Reentrant versions of the above functions.  */
255
256 /* Return in BUF a string of the form "Day Mon dd hh:mm:ss yyyy\n"
257    that is the representation of TP in this format.  */
258 extern char *__asctime_r __P ((__const struct tm *__tp, char *__buf));
259 extern char *asctime_r __P ((__const struct tm *__tp, char *__buf));
260
261 /* Equivalent to `asctime_r (localtime_r (timer, *TMP*), buf)'.  */
262 extern char *ctime_r __P ((__const time_t *__timer, char *__buf));
263 # endif /* POSIX or misc */
264
265
266 /* Defined in localtime.c.  */
267 extern char *__tzname[2];       /* Current timezone names.  */
268 extern int __daylight;          /* If daylight-saving time is ever in use.  */
269 extern long int __timezone;     /* Seconds west of UTC.  */
270
271 /* Set time conversion information from the TZ environment variable.
272    If TZ is not defined, a locale-dependent default is used.  */
273 extern void __tzset __P ((void));
274
275 # ifdef __USE_POSIX
276 /* Same as above.  */
277 extern char *tzname[2];
278
279 /* Return the maximum length of a timezone name.
280    This is what `sysconf (_SC_TZNAME_MAX)' does.  */
281 extern long int __tzname_max __P ((void));
282
283 extern void tzset __P ((void));
284 # endif
285
286 # if defined __USE_SVID || defined __USE_XOPEN
287 extern int daylight;
288 extern long int timezone;
289 # endif
290
291 # ifdef __USE_SVID
292 /* Set the system time to *WHEN.
293    This call is restricted to the superuser.  */
294 extern int stime __P ((__const time_t *__when));
295 # endif
296
297
298 /* Nonzero if YEAR is a leap year (every 4 years,
299    except every 100th isn't, and every 400th is).  */
300 # define __isleap(year) \
301   ((year) % 4 == 0 && ((year) % 100 != 0 || (year) % 400 == 0))
302
303
304 # ifdef __USE_MISC
305 /* Miscellaneous functions many Unices inherited from the public domain
306    localtime package.  These are included only for compatibility.  */
307
308 /* Like `mktime', but for TP represents Universal Time, not local time.  */
309 extern time_t timegm __P ((struct tm *__tp));
310
311 /* Another name for `mktime'.  */
312 extern time_t timelocal __P ((struct tm *__tp));
313
314 /* Return the number of days in YEAR.  */
315 extern int dysize __P ((int __year));
316 # endif
317
318
319 # ifdef __USE_POSIX199309
320 /* Pause execution for a number of nanoseconds.  */
321 extern int __nanosleep __P ((__const struct timespec *__requested_time,
322                              struct timespec *__remaining));
323 extern int nanosleep __P ((__const struct timespec *__requested_time,
324                            struct timespec *__remaining));
325 # endif
326
327
328 # ifdef __USE_XOPEN_EXTENDED
329 /* Set to one of the following values to indicate an error.
330      1  the DATEMSK environment variable is null or undefined,
331      2  the template file cannot be opened for reading,
332      3  failed to get file status information,
333      4  the template file is not a regular file,
334      5  an error is encountered while reading the template file,
335      6  memory allication failed (not enough memory available),
336      7  there is no line in the template that matches the input,
337      8  invalid input specification Example: February 31 or a time is
338         specified that can not be represented in a time_t (representing
339         the time in seconds since 00:00:00 UTC, January 1, 1970) */
340 extern int getdate_err;
341
342 /* Parse the given string as a date specification and return a value
343    representing the value.  The templates from the file identified by
344    the environment variable DATEMSK are used.  In case of an error
345    `getdate_err' is set.  */
346 extern struct tm *getdate __P ((__const char *__string));
347 # endif
348
349 # ifdef __USE_GNU
350 /* Since `getdate' is not reentrant because of the use of `getdate_err'
351    and the static buffer to return the result in, we provide a thread-safe
352    variant.  The functionality is the same.  The result is returned in
353    the buffer pointed to by RESBUFP and in case of an error the return
354    value is != 0 with the same values as given above for `getdate_err'.  */
355 extern int __getdate_r __P ((__const char *__string, struct tm *__resbufp));
356 extern int getdate_r __P ((__const char *__string, struct tm *__resbufp));
357 # endif
358
359
360 __END_DECLS
361
362 #endif /* <time.h> included.  */
363
364 #endif /* <time.h> not already included.  */