Clean up sleep/SIGALRM interaction.
[kopensolaris-gnu/glibc.git] / manual / time.texi
1 @node Date and Time, Non-Local Exits, Arithmetic, Top
2 @chapter Date and Time
3
4 This chapter describes functions for manipulating dates and times,
5 including functions for determining what the current time is and
6 conversion between different time representations.
7
8 The time functions fall into three main categories:
9
10 @itemize @bullet
11 @item 
12 Functions for measuring elapsed CPU time are discussed in @ref{Processor
13 Time}.
14
15 @item
16 Functions for measuring absolute clock or calendar time are discussed in
17 @ref{Calendar Time}.
18
19 @item
20 Functions for setting alarms and timers are discussed in @ref{Setting
21 an Alarm}.
22 @end itemize
23
24 @menu
25 * Processor Time::              Measures processor time used by a program.
26 * Calendar Time::               Manipulation of ``real'' dates and times.
27 * Setting an Alarm::            Sending a signal after a specified time.
28 * Sleeping::                    Waiting for a period of time.
29 @end menu
30
31 @node Processor Time, Calendar Time,  , Date and Time
32 @section Processor Time
33
34 If you're trying to optimize your program or measure its efficiency, it's
35 very useful to be able to know how much @dfn{processor time} or @dfn{CPU
36 time} it has used at any given point.  Processor time is different from
37 actual wall clock time because it doesn't include any time spent waiting
38 for I/O or when some other process is running.  Processor time is
39 represented by the data type @code{clock_t}, and is given as a number of
40 @dfn{clock ticks} relative to an arbitrary base time marking the beginning
41 of a single program invocation.
42 @cindex CPU time
43 @cindex processor time
44 @cindex clock ticks
45 @cindex ticks, clock
46 @cindex time, elapsed CPU
47
48 @menu
49 * Basic CPU Time::              The @code{clock} function.
50 * Detailed CPU Time::           The @code{times} function.
51 @end menu
52
53 @node Basic CPU Time, Detailed CPU Time,  , Processor Time
54 @subsection Basic CPU Time Inquiry
55
56 To get the elapsed CPU time used by a process, you can use the
57 @code{clock} function.  This facility is declared in the header file
58 @file{time.h}.
59 @pindex time.h
60
61 In typical usage, you call the @code{clock} function at the beginning and
62 end of the interval you want to time, subtract the values, and then divide
63 by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this:
64
65 @example
66 #include <time.h>
67
68 clock_t start, end;
69 double elapsed;
70
71 start = clock();
72 @dots{} /* @r{Do the work.} */
73 end = clock();
74 elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
75 @end example
76
77 Different computers and operating systems vary wildly in how they keep
78 track of processor time.  It's common for the internal processor clock
79 to have a resolution somewhere between hundredths and millionths of a
80 second.
81
82 In the GNU system, @code{clock_t} is equivalent to @code{long int} and
83 @code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
84 @code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be
85 either integer or floating-point types.  Casting processor time values
86 to @code{double}, as in the example above, makes sure that operations
87 such as arithmetic and printing work properly and consistently no matter
88 what the underlying representation is.
89
90 @comment time.h
91 @comment ANSI
92 @deftypevr Macro int CLOCKS_PER_SEC
93 The value of this macro is the number of clock ticks per second measured
94 by the @code{clock} function.
95 @end deftypevr
96
97 @comment time.h
98 @comment POSIX.1
99 @deftypevr Macro int CLK_TCK
100 This is an obsolete name for @code{CLOCKS_PER_SEC}.  
101 @end deftypevr
102
103 @comment time.h
104 @comment ANSI
105 @deftp {Data Type} clock_t
106 This is the type of the value returned by the @code{clock} function.
107 Values of type @code{clock_t} are in units of clock ticks.
108 @end deftp
109
110 @comment time.h
111 @comment ANSI
112 @deftypefun clock_t clock (void)
113 This function returns the elapsed processor time.  The base time is
114 arbitrary but doesn't change within a single process.  If the processor
115 time is not available or cannot be represented, @code{clock} returns the
116 value @code{(clock_t)(-1)}.
117 @end deftypefun
118
119
120 @node Detailed CPU Time,  , Basic CPU Time, Processor Time
121 @subsection Detailed Elapsed CPU Time Inquiry
122
123 The @code{times} function returns more detailed information about
124 elapsed processor time in a @code{struct tms} object.  You should
125 include the header file @file{sys/times.h} to use this facility.
126 @pindex sys/times.h
127
128 @comment sys/times.h
129 @comment POSIX.1
130 @deftp {Data Type} {struct tms}
131 The @code{tms} structure is used to return information about process
132 times.  It contains at least the following members:
133
134 @table @code
135 @item clock_t tms_utime
136 This is the CPU time used in executing the instructions of the calling
137 process.
138
139 @item clock_t tms_stime
140 This is the CPU time used by the system on behalf of the calling process.
141
142 @item clock_t tms_cutime
143 This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
144 values of all terminated child processes of the calling process, whose
145 status has been reported to the parent process by @code{wait} or
146 @code{waitpid}; see @ref{Process Completion}.  In other words, it represents
147 the total CPU time used in executing the instructions of all the terminated
148 child processes of the calling process.
149
150 @item clock_t tms_cstime
151 This is similar to @code{tms_cutime}, but represents the total CPU time
152 used by the system on behalf of all the terminated child processes of the
153 calling process.
154 @end table
155
156 All of the times are given in clock ticks.  These are absolute values; in a
157 newly created process, they are all zero.  @xref{Creating a Process}.
158 @end deftp
159
160 @comment sys/times.h
161 @comment POSIX.1
162 @deftypefun clock_t times (struct tms *@var{buffer})
163 The @code{times} function stores the processor time information for
164 the calling process in @var{buffer}.
165
166 The return value is the same as the value of @code{clock()}: the elapsed
167 real time relative to an arbitrary base.  The base is a constant within a
168 particular process, and typically represents the time since system
169 start-up.  A value of @code{(clock_t)(-1)} is returned to indicate failure.
170 @end deftypefun
171
172 @strong{Portability Note:} The @code{clock} function described in
173 @ref{Basic CPU Time}, is specified by the ANSI C standard.  The
174 @code{times} function is a feature of POSIX.1.  In the GNU system, the
175 value returned by the @code{clock} function is equivalent to the sum of
176 the @code{tms_utime} and @code{tms_stime} fields returned by
177 @code{times}.
178
179 @node Calendar Time, Setting an Alarm, Processor Time, Date and Time
180 @section Calendar Time
181
182 This section describes facilities for keeping track of dates and times
183 according to the Gregorian calendar.
184 @cindex Gregorian calendar
185 @cindex time, calendar
186 @cindex date and time
187
188 There are three representations for date and time information:
189
190 @itemize @bullet
191 @item 
192 @dfn{Calendar time} (the @code{time_t} data type) is a compact 
193 representation, typically giving the number of seconds elapsed since
194 some implementation-specific base time.
195 @cindex calendar time
196
197 @item
198 There is also a @dfn{high-resolution time} representation (the @code{struct
199 timeval} data type) that includes fractions of a second.  Use this time
200 representation instead of ordinary calendar time when you need greater
201 precision.
202 @cindex high-resolution time
203
204 @item
205 @dfn{Local time} or @dfn{broken-down time} (the @code{struct
206 tm} data type) represents the date and time as a set of components
207 specifying the year, month, and so on, for a specific time zone.
208 This time representation is usually used in conjunction with formatting
209 date and time values.
210 @cindex local time
211 @cindex broken-down time
212 @end itemize
213
214 @menu
215 * Simple Calendar Time::        Facilities for manipulating calendar time.
216 * High-Resolution Calendar::    A time representation with greater precision.
217 * Broken-down Time::            Facilities for manipulating local time.
218 * Formatting Date and Time::    Converting times to strings.
219 * TZ Variable::                 How users specify the time zone.
220 * Time Zone Functions::         Functions to examine or specify the time zone.
221 * Time Functions Example::      An example program showing use of some of
222                                  the time functions.
223 @end menu
224
225 @node Simple Calendar Time, High-Resolution Calendar,  , Calendar Time
226 @subsection Simple Calendar Time
227
228 This section describes the @code{time_t} data type for representing
229 calendar time, and the functions which operate on calendar time objects.
230 These facilities are declared in the header file @file{time.h}.
231 @pindex time.h
232
233 @cindex epoch
234 @comment time.h
235 @comment ANSI
236 @deftp {Data Type} time_t
237 This is the data type used to represent calendar time.  In the GNU C
238 library and other POSIX-compliant implementations, @code{time_t} is
239 equivalent to @code{long int}.  When interpreted as an absolute time
240 value, it represents the number of seconds elapsed since 00:00:00 on
241 January 1, 1970, Coordinated Universal Time.  (This date is sometimes
242 referred to as the @dfn{epoch}.)
243
244 In other systems, @code{time_t} might be either an integer or
245 floating-point type.
246 @end deftp
247
248 @comment time.h
249 @comment ANSI
250 @deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
251 The @code{difftime} function returns the number of seconds elapsed
252 between time @var{time1} and time @var{time0}, as a value of type
253 @code{double}.  
254
255 In the GNU system, you can simply subtract @code{time_t} values.  But on
256 other systems, the @code{time_t} data type might use some other encoding
257 where subtraction doesn't work directly.
258 @end deftypefun
259
260 @comment time.h
261 @comment ANSI
262 @deftypefun time_t time (time_t *@var{result})
263 The @code{time} function returns the current time as a value of type
264 @code{time_t}.  If the argument @var{result} is not a null pointer, the
265 time value is also stored in @code{*@var{result}}.  If the calendar 
266 time is not available, the value @code{(time_t)(-1)} is returned.
267 @end deftypefun
268
269
270 @node High-Resolution Calendar, Broken-down Time, Simple Calendar Time, Calendar Time
271 @subsection High-Resolution Calendar
272
273 The @code{time_t} data type used to represent calendar times has a 
274 resolution of only one second.  Some applications need more precision.
275
276 So, the GNU C library also contains functions which are capable of
277 representing calendar times to a higher resolution than one second.  The
278 functions and the associated data types described in this section are
279 declared in @file{sys/time.h}.
280 @pindex sys/time.h
281
282 @comment sys/time.h
283 @comment BSD
284 @deftp {Data Type} {struct timeval}
285 The @code{struct timeval} structure represents a calendar time.  It
286 has the following members:
287
288 @table @code
289 @item long tv_sec
290 This represents the number of seconds since the epoch.  It is equivalent
291 to a normal @code{time_t} value.
292
293 @item long tv_usec
294 This is the fractional second value, represented as the number of
295 microseconds.
296
297 Some times struct timeval values are user for time intervals.  Then the
298 @code{tv_sec} member is the number of seconds in the interval, and
299 @code{tv_usec} is the number of addictional microseconds.
300 @end table
301 @end deftp
302
303 @comment sys/time.h
304 @comment BSD
305 @deftp {Data Type} {struct timezone}
306 The @code{struct timezone} structure is used to hold minimal information
307 about the local time zone.  It has the following members:
308
309 @table @code
310 @item int tz_minuteswest
311 This is the number of minutes west of GMT.
312
313 @item int tz_dsttime
314 If nonzero, daylight savings time applies during some part of the year.
315 @end table
316 @end deftp
317
318 It is often necessary to subtract two values of type @code{struct
319 timeval}.  Here is the best way to do this.  It works even on some
320 peculiar operating systems where the @code{tv_sec} member has an
321 unsigned type.
322
323 @example
324 /* @r{Subtract the `struct timeval' values X and Y,}
325    @r{storing the result in RESULT.}
326    @r{Return 1 if the difference is negative, otherwise 0.}  */
327
328 int
329 timeval_subtract (result, x, y)
330      struct timeval *result, *x, *y;
331 @{
332   /* @r{Perform the carry for the later subtraction by updating y.} */
333   if (x->tv_usec < y->tv_usec) @{
334     int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
335     y->tv_usec -= 1000000 * nsec;
336     y->tv_sec += nsec;
337   @}
338   if (x->tv_usec - y->tv_usec > 1000000) @{
339     int nsec = (y->tv_usec - x->tv_usec) / 1000000;
340     y->tv_usec += 1000000 * nsec;
341     y->tv_sec -= nsec;
342   @}
343
344   /* @r{Compute the time remaining to wait.}
345      @r{@code{tv_usec} is certainly positive.} */
346   result->tv_sec = x->tv_sec - y->tv_sec;
347   result->tv_usec = x->tv_usec - y->tv_usec;
348
349   /* @r{Return 1 if result is negative.} */
350   return x->tv_sec < y->tv_sec;
351 @}
352 @end example
353
354 @comment sys/time.h
355 @comment BSD
356 @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
357 The @code{gettimeofday} function returns the current date and time in the
358 @code{struct timeval} structure indicated by @var{tp}.  Information about the
359 time zone is returned in the structure pointed at @var{tzp}.  If the @var{tzp}
360 argument is a null pointer, time zone information is ignored.
361
362 The return value is @code{0} on success and @code{-1} on failure.
363 @end deftypefun
364
365 @comment sys/time.h
366 @comment BSD
367 @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
368 The @code{settimeofday} function sets the current date and time
369 according to the arguments.  As for @code{gettimeofday}, time zone
370 information is ignored if @var{tzp} is a null pointer.
371
372 You must be a privileged user in order to use @code{settimeofday}.
373
374 The return value is @code{0} on success and @code{-1} on failure.  The
375 following @code{errno} error condition is defined for this function:
376
377 @table @code
378 @item EPERM
379 You do not have privilege to set the time.
380 @end table
381 @end deftypefun
382
383 @comment sys/time.h
384 @comment BSD
385 @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
386 This function speeds up or slows down the system clock in order to make
387 gradual adjustments in the current time.  This ensures that the time
388 reported by the system clock is always monotonically increasing, which
389 might not happen if you simply set the current time.
390
391 The @var{delta} argument specifies a relative adjustment to be made to
392 the current time.  If negative, the system clock is slowed down for a
393 while until it has lost this much time.  If positive, the system clock
394 is speeded up for a while.
395
396 If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
397 function returns information about any previous time adjustment that
398 has not yet completed.
399
400 This function is typically used to synchronize the clocks of computers
401 in a local network.  You must be a privileged user to use it.
402 The return value is @code{0} on success and @code{-1} on failure.  The
403 following @code{errno} error condition is defined for this function:
404
405 @table @code
406 @item EPERM
407 You do not have privilege to set the time.
408 @end table
409 @end deftypefun
410
411 @strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
412 and @code{adjtime} functions are derived from BSD.  
413
414
415 @node Broken-down Time, Formatting Date and Time, High-Resolution Calendar, Calendar Time
416 @subsection Broken-down Time
417 @cindex broken-down time
418 @cindex calendar time and broken-down time
419
420 Calender time is represented as a number of seconds.  This is convenient
421 for calculation, but has no resemblance to the way people normally
422 represent dates and times.  By contrast, @dfn{broken-down time} is a binary
423 representation separated into year, month, day, and so on.  Broken down
424 time values are not useful for calculations, but they are useful for
425 printing human readable time.
426
427 The symbols in this section are declared in the header file @file{time.h}.
428
429 @comment time.h
430 @comment ANSI
431 @deftp {Data Type} {struct tm}
432 This is the data type used to represent a broken-down time.  The structure
433 contains at least the following members, which can appear in any order:
434
435 @table @code
436 @item int tm_sec
437 This is the number of seconds after the minute, normally in the range
438 @code{0} to @code{59}.  (The actual upper limit is @code{61}, to allow
439 for ``leap seconds''.)
440 @cindex leap second
441
442 @item int tm_min
443 This is the number of minutes after the hour, in the range @code{0} to
444 @code{59}.
445
446 @item int tm_hour
447 This is the number of hours past midnight, in the range @code{0} to
448 @code{23}.
449
450 @item int tm_mday
451 This is the day of the month, in the range @code{1} to @code{31}.
452
453 @item int tm_mon
454 This is the number of months since January, in the range @code{0} to
455 @code{11}.
456
457 @item int tm_year
458 This is the number of years since @code{1900}.
459
460 @item int tm_wday
461 This is the number of days since Sunday, in the range @code{0} to @code{6}.
462
463 @item int tm_yday
464 This is the number of days since January 1, in the range @code{0} to
465 @code{365}.
466
467 @item int tm_isdst
468 This is a flag that indicates whether Daylight Saving Time is (or was, or
469 will be) in effect at the time described.  The value is positive if
470 Daylight Saving Time is in effect, zero if it is not, and negative if the
471 information is not available.
472 @cindex Daylight Saving Time
473 @cindex summer time
474 @end table
475 @end deftp
476
477 @comment time.h
478 @comment ANSI
479 @deftypefun {struct tm *} localtime (const time_t *@var{time})
480 The @code{localtime} function converts the calendar time pointed to by
481 @var{time} to broken-down time representation, expressed relative to the
482 user's specified time zone.
483
484 The return value is a pointer to a static broken-down time structure, which
485 might be overwritten by subsequent calls to any of the date and time
486 functions.  (But no other library function overwrites the contents of this
487 object.)
488
489 Calling @code{localtime} has one other effect: it sets the variable
490 @code{tzname} with information about the current time zone.  @xref{Time
491 Zone Functions}.
492 @end deftypefun
493
494 @comment time.h
495 @comment ANSI
496 @deftypefun {struct tm *} gmtime (const time_t *@var{time})
497 This function is similar to @code{localtime}, except that the broken-down
498 time is expressed as Coordinated Universal Time (UTC)---that is, as
499 Greenwich Mean Time (GMT) rather than relative to the local time zone.
500
501 Recall that calendar times are @emph{always} expressed in coordinated
502 universal time.
503 @c If the implementation can't figure out where the local time zone is
504 @c relative to GMT, this function returns a null pointer.
505 @c ??? This function should not need to use the local time zone. ???
506 @end deftypefun
507
508 @comment time.h
509 @comment ANSI
510 @deftypefun time_t mktime (struct tm *@var{brokentime})
511 The @code{mktime} function is used to convert a broken-down time structure
512 to a calendar time representation.  It also ``normalizes'' the contents of
513 the broken-down time structure, by filling in the day of week and day of
514 year based on the other date and time components.
515
516 The @code{mktime} function ignores the specified contents of the
517 @code{tm_wday} and @code{tm_yday} members of the broken-down time
518 structure.  It uses the values of the other components to compute the
519 calendar time; it's permissible for these components to have
520 unnormalized values outside of their normal ranges.  The last thing that
521 @code{mktime} does is adjust the components of the @var{brokentime}
522 structure (including the @code{tm_wday} and @code{tm_yday}).
523
524 If the specified broken-down time cannot be represented as a calendar time,
525 @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
526 the contents of @var{brokentime}.
527
528 Calling @code{mktime} also sets the variable @code{tzname} with
529 information about the current time zone.  @xref{Time Zone Functions}.
530 @end deftypefun
531
532 @node Formatting Date and Time, TZ Variable, Broken-down Time, Calendar Time
533 @subsection Formatting Date and Time
534
535 The functions described in this section format time values as strings.
536 These functions are declared in the header file @file{time.h}.
537 @pindex time.h
538
539 @comment time.h
540 @comment ANSI
541 @deftypefun {char *} asctime (const struct tm *@var{brokentime})
542 The @code{asctime} function writes the broken-down time value pointed at by
543 @var{brokentime} into a string in a standard format:
544
545 @example
546 "Tue May 21 13:46:22 1991\n"
547 @end example
548
549 The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
550 @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
551
552 The abbreviations for the months are: @samp{Jan}, @samp{Feb},
553 @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
554 @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
555
556 The return value points to a statically allocated string, which might be
557 overwritten by subsequent calls to any of the date and time functions.
558 (But no other library function overwrites the contents of this
559 string.)
560 @end deftypefun
561
562 @comment time.h
563 @comment ANSI
564 @deftypefun {char *} ctime (const time_t *@var{time})
565 The @code{ctime} function is similar to @code{asctime}, except that
566 the time value is specified in calendar time (rather than local time)
567 format.  It is equivalent to
568
569 @example
570 asctime (localtime (@var{time}))
571 @end example
572
573 @code{ctime} sets the variable @code{tzname}, because @code{localtime}
574 does so.  @xref{Time Zone Functions}.
575 @end deftypefun
576
577 @comment time.h
578 @comment ANSI
579 @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
580 This function is similar to the @code{sprintf} function (@pxref{Formatted
581 Input}), but the conversion specifications that can appear in the format
582 template @var{template} are specialized for printing components of the date
583 and time @var{brokentime} according to the locale currently specified for
584 time conversion (@pxref{Locales}).
585
586 Ordinary characters appearing in the @var{template} are copied to the
587 output string @var{s}; this can include multibyte character sequences.
588 Conversion specifiers are introduced by a @samp{%} character, and are
589 replaced in the output string as follows:
590
591 @table @code
592 @item %a
593 The abbreviated weekday name according to the current locale.
594
595 @item %A
596 The full weekday name according to the current locale.
597
598 @item %b
599 The abbreviated month name according to the current locale.
600
601 @item %B
602 The full month name according to the current locale.
603
604 @item %c
605 The preferred date and time representation for the current locale.
606
607 @item %d
608 The day of the month as a decimal number (range @code{01} to @code{31}).
609
610 @item %H
611 The hour as a decimal number, using a 24-hour clock (range @code{00} to
612 @code{23}).
613
614 @item %I
615 The hour as a decimal number, using a 12-hour clock (range @code{01} to
616 @code{12}).
617
618 @item %j
619 The day of the year as a decimal number (range @code{001} to @code{366}).
620
621 @item %m
622 The month as a decimal number (range @code{01} to @code{12}).
623
624 @item %M
625 The minute as a decimal number.
626
627 @item %p
628 Either @samp{am} or @samp{pm}, according to the given time value; or the
629 corresponding strings for the current locale.
630
631 @item %S
632 The second as a decimal number.
633
634 @item %U
635 The week number of the current year as a decimal number, starting with
636 the first Sunday as the first day of the first week.
637
638 @item %w
639 The day of the week as a decimal number, Sunday being @code{0}.
640
641 @item %W
642 The week number of the current year as a decimal number, starting with
643 the first Monday as the first day of the first week.
644
645 @item %x
646 The preferred date representation for the current locale, but without the
647 time.
648
649 @item %X
650 The preferred time representation for the current locale, but with no date.
651
652 @item %y
653 The year as a decimal number, but without a century (range @code{00} to
654 @code{99}).
655
656 @item %Y
657 The year as a decimal number, including the century.
658
659 @item %Z
660 The time zone or name or abbreviation (empty if the time zone can't be
661 determined).
662
663 @item %%
664 A literal @samp{%} character.
665 @end table
666
667 The @var{size} parameter can be used to specify the maximum number of
668 characters to be stored in the array @var{s}, including the terminating
669 null character.  If the formatted time requires more than @var{size}
670 characters, the excess characters are discarded.  The return value from
671 @code{strftime} is the number of characters placed in the array @var{s},
672 not including the terminating null character.  If the value equals
673 @var{size}, it means that the array @var{s} was too small; you should
674 repeat the call, providing a bigger array.
675
676 For an example of @code{strftime}, see @ref{Time Functions Example}.
677 @end deftypefun
678
679 @node TZ Variable, Time Zone Functions, Formatting Date and Time, Calendar Time
680 @subsection Specifying the Time Zone with @code{TZ}
681
682 In the GNU system, a user can specify the time zone by means of the
683 @code{TZ} environment variable.  For information about how to set
684 environment variables, see @ref{Environment Variables}.  The functions for
685 accessing the time zone are declared in @file{time.h}.
686 @pindex time.h
687 @cindex time zone
688
689 The value of the @code{TZ} variable can be of one of three formats.  The
690 first format is used when there is no Daylight Saving Time (or summer
691 time) in the local time zone:
692
693 @example
694 @r{@var{std} @var{offset}}
695 @end example
696
697 The @var{std} string specifies the name of the time zone.  It must be
698 three or more characters long and must not contain a leading colon or
699 embedded digits, commas, or plus or minus signs.  There is no space
700 character separating the time zone name from the @var{offset}, so these
701 restrictions are necessary to parse the specification correctly.
702
703 The @var{offset} specifies the time value one must add to the local time
704 to get a Coordinated Universal Time value.  It has syntax like
705 [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  This
706 is positive if the local time zone is west of the Prime Meridian and
707 negative if it is east.  The hour must be between @code{0} and
708 @code{24}, and the minute and seconds between @code{0} and @code{59}.
709
710 For example, here is how we would specify Eastern Standard Time, but
711 without any daylight savings time alternative:
712
713 @example
714 EST+5
715 @end example
716
717 The second format is used when there is Daylight Saving Time:
718
719 @example
720 @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
721 @end example
722
723 The initial @var{std} and @var{offset} specify the standard time zone, as
724 described above.  The @var{dst} string and @var{offset} specify the name
725 and offset for the corresponding daylight savings time time zone; if the
726 @var{offset} is omitted, it defaults to one hour ahead of standard time.
727
728 The remainder of the specification describes when daylight savings time is
729 in effect.  The @var{start} field is when daylight savings time goes into
730 effect and the @var{end} field is when the change is made back to standard
731 time.  The following formats are recognized for these fields:
732
733 @table @code
734 @item J@var{n}
735 This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
736 February 29 is never counted, even in leap years.
737
738 @item @var{n}
739 This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
740 February 29 is counted in leap years.
741
742 @item M@var{m}.@var{w}.@var{d}
743 This specifies day @var{d} of week @var{w} of month @var{m}.  The day
744 @var{d} must be between @code{0} (Sunday) and @code{6}.  The week
745 @var{w} must be between @code{1} and @code{5}; week @code{1} is the
746 first week in which day @var{d} occurs, and week @code{5} specifies the
747 @emph{last} @var{d} day in the month.  The month @var{m} should be
748 between @code{1} and @code{12}.
749 @end table
750
751 The @var{time} fields specify when, in the local time currently in
752 effect, the change to the other time occurs.  If omitted, the default is
753 @code{02:00:00}.
754
755 For example, here is how one would specify the Eastern time zone in the
756 United States, including the appropriate daylight saving time and its dates
757 of applicability.  The normal offset from GMT is 5 hours; since this is
758 west of the prime meridian, the sign is positive.  Summer time begins on
759 the first Sunday in April at 2:00am, and ends on the last Sunday in October
760 at 2:00am.
761
762 @example
763 EST+5EDT,M4.1.0/M10.5.0
764 @end example
765
766 The schedule of daylight savings time in any particular jurisdiction has
767 changed over the years.  To be strictly correct, the conversion of dates
768 and times in the past should be based on the schedule that was in effect
769 then.  However, the system has no facilities to let you specify how the
770 schedule has changed from year to year.  The most you can do is specify
771 one particular schedule---usually the present day schedule---and this is
772 used to convert any date, no matter when.
773
774 The third format looks like this:
775
776 @example
777 :@var{characters}
778 @end example
779
780 Each operating system interprets this format differently; in the GNU C
781 library, @var{characters} is the name of a file which describes the time
782 zone.
783
784 If the @code{TZ} environment variable does not have a value, the
785 operation chooses a time zone by default.  Each operating system has its
786 own rules for choosing the default time zone, so there is little we can
787 say about them.
788
789 @node Time Zone Functions, Time Functions Example, TZ Variable, Calendar Time
790 @subsection Functions and Variables for Time Zones
791
792 @comment time.h
793 @comment POSIX.1
794 @defvar tzname
795 The array @code{tzname} contains two strings, which are the standard
796 three-letter names of the pair of time zones (standard and daylight
797 savings) that the user has selected.  @code{tzname[0]} is the name of
798 the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
799 is the name for the time zone when daylight savings time is in use (for
800 example, @code{"EDT"}).  These correspond to the @var{std} and @var{dst}
801 strings (respectively) from the @code{TZ} environment variable.
802
803 The data type of @code{tzname} is @code{char *[2]}.
804
805 The @code{tzname} array is initialized from the @code{TZ} environment
806 variable whenever @code{tzset}, @code{ctime}, @code{strftime},
807 @code{mktime}, or @code{localtime} are called.
808 @end defvar
809
810 @comment time.h
811 @comment POSIX.1
812 @deftypefun void tzset (void)
813 The @code{tzset} function initializes the @code{tzname} variable from
814 the value of the @code{TZ} environment variable.  It is not usually
815 necessary for your program to call this function, because it is called
816 automatically when you use the other time conversion functions that
817 depend on the time zone.
818 @end deftypefun
819
820 The following variables are defined for compatibility with System V
821 Unix.
822
823 @comment time.h
824 @comment SVID
825 @deftypevar {long int} timezone
826 This contains the difference between GMT and local standard time, in
827 seconds.  For example, in the U.S. Eastern time zone, the value is
828 @code{5*60*60}.
829 @end deftypevar
830
831 @comment time.h
832 @comment SVID
833 @deftypevar {int} daylight
834 This variable has a nonzero value if the standard U.S. daylight savings
835 time rules apply.
836 @end deftypevar
837
838 @node Time Functions Example,  , Time Zone Functions, Calendar Time
839 @subsection Time Functions Example
840
841 Here is an example program showing the use of some of the local time and
842 calendar time functions.
843
844 @example
845 #include <time.h>
846 #include <stdio.h>
847
848 #define SIZE 256
849
850 void
851 main (void)
852 @{
853   char buffer[SIZE];
854   time_t curtime;
855   struct tm *loctime;
856
857   /* @r{Get the current time.} */
858   curtime = time (NULL);
859
860   /* @r{Convert it to local time representation.} */
861   loctime = localtime (&curtime);
862
863   /* @r{Print out the date and time in the standard format.} */
864   fputs (asctime (loctime), stdout);
865
866   /* @r{Print it out in a nice format.} */
867   strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
868   fputs (buffer, stdout);
869   strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
870   fputs (buffer, stdout);
871 @}
872 @end example
873
874 It produces output like this:
875
876 @example
877 Wed Jul 31 13:02:36 1991
878 Today is Wednesday, July 31.
879 The time is 01:02 PM.
880 @end example
881
882
883 @node Setting an Alarm, Sleeping, Calendar Time, Date and Time
884 @section Setting an Alarm
885
886 The @code{alarm} and @code{setitimer} functions provide a mechanism for a
887 process to interrupt itself at some future time.  They do this by setting a
888 timer; when the timer expires, the process recieves a signal.
889
890 @cindex setting an alarm
891 @cindex interval timer, setting
892 @cindex alarms, setting
893 @cindex timers, setting
894 Each process has three independent interval timers available:
895
896 @itemize @bullet
897 @item 
898 A real-time timer that counts clock time.  This timer sends a
899 @code{SIGALRM} signal to the process when it expires.
900 @cindex real-time timer
901
902 @item 
903 A virtual timer that counts CPU time used by the process.  This timer
904 sends a @code{SIGVTALRM} signal to the process when it expires.
905 @cindex virtual timer
906
907 @item 
908 A profiling timer that counts both CPU time used by the process, and CPU
909 time spent in system calls on behalf of the process.  This timer sends a
910 @code{SIGPROF} signal to the process when it expires.
911 @cindex profiling timer
912 @end itemize
913
914 You can only have one timer of each kind set at any given time.  If you
915 set a timer that has not yet expired, that timer is simply reset to the
916 new value.
917
918 You should establish a handler for the appropriate alarm signal using
919 @code{signal} or @code{sigaction} before issuing a call to @code{setitimer}
920 or @code{alarm}.  Otherwise, an unusual chain of events could cause the
921 timer to expire before your program establishes the handler, and in that
922 case it would be terminated, since that is the default action for the alarm
923 signals.  @xref{Signal Handling}.
924
925 The @code{setitimer} function is the primary means for setting an alarm.
926 This facility is declared in the header file @file{sys/time.h}.  The
927 @code{alarm} function, declared in @file{unistd.h}, provides a somewhat
928 simpler interface for setting the real-time timer.
929 @pindex unistd.h
930 @pindex sys/time.h
931
932 @comment sys/time.h
933 @comment BSD
934 @deftp {Data Type} {struct itimerval}
935 This structure is used to specify when a timer should expire.  It contains
936 the following members:
937 @table @code
938 @item struct timeval it_interval
939 This is the interval between successive timer interrupts.  If zero, the
940 alarm will only be sent once.
941
942 @item struct timeval it_value
943 This is the interval to the first timer interrupt.  If zero, the alarm is
944 disabled.
945 @end table
946
947 The @code{struct timeval} data type is described in @ref{High-Resolution
948 Calendar}.
949 @end deftp
950
951 @comment sys/time.h
952 @comment BSD
953 @deftypefun int setitimer (int @var{which}, struct itimerval *@var{old}, struct itimerval *@var{new})
954 The @code{setitimer} function sets the timer specified by @var{which} 
955 according to @var{new}.  The @var{which} argument can have a value of
956 @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
957
958 If @var{old} is not a null pointer, @code{setitimer} returns information
959 about any previous unexpired timer of the same kind in the structure it
960 points to.
961
962 The return value is @code{0} on success and @code{-1} on failure.  The
963 following @code{errno} error conditions are defined for this function:
964
965 @table @code
966 @item EINVAL
967 The timer interval was too large.
968 @end table
969 @end deftypefun
970
971 @comment sys/time.h
972 @comment BSD
973 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
974 The @code{getitimer} function stores information about the timer specified
975 by @var{which} in the structure pointed at by @var{old}.
976
977 The return value and error conditions are the same as for @code{setitimer}.
978 @end deftypefun
979
980 @comment sys/time.h
981 @comment BSD
982 @table @code
983 @item ITIMER_REAL
984 @findex ITIMER_REAL
985 This constant can be used as the @var{which} argument to the
986 @code{setitimer} and @code{getitimer} functions to specify the real-time
987 timer.
988
989 @comment sys/time.h
990 @comment BSD
991 @item ITIMER_VIRTUAL
992 @findex ITIMER_VIRTUAL
993 This constant can be used as the @var{which} argument to the
994 @code{setitimer} and @code{getitimer} functions to specify the virtual
995 timer.
996
997 @comment sys/time.h
998 @comment BSD
999 @item ITIMER_PROF
1000 @findex ITIMER_PROF
1001 This constant can be used as the @var{which} argument to the
1002 @code{setitimer} and @code{getitimer} functions to specify the profiling
1003 timer.
1004 @end table
1005
1006 @comment unistd.h
1007 @comment POSIX.1
1008 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
1009 The @code{alarm} function sets the real-time timer to expire in
1010 @var{seconds} seconds.  If you want to cancel any existing alarm, you
1011 can do this by calling @code{alarm} with a @var{seconds} argument of
1012 zero.
1013
1014 The return value indicates how many seconds remain before the previous
1015 alarm would have been sent.  If there is no previous alarm, @code{alarm}
1016 returns zero.
1017 @end deftypefun
1018
1019 The @code{alarm} function could be defined in terms of @code{setitimer}
1020 like this:
1021
1022 @example
1023 unsigned int
1024 alarm (unsigned int seconds)
1025 @{
1026   struct itimerval old, new;
1027   new.it_interval.tv_usec = 0;
1028   new.it_interval.tv_sec = 0;
1029   new.it_value.tv_usec = 0;
1030   new.it_value.tv_sec = (long int) seconds;
1031   if (setitimer (ITIMER_REAL, &new, &old) < 0)
1032     return 0;
1033   else
1034     return old.it_value.tv_sec;
1035 @}
1036 @end example
1037
1038 There is an example showing the use of the @code{alarm} function in
1039 @ref{Handler Returns}.
1040
1041 If you simply want your process to wait for a given number of seconds,
1042 you should use the @code{sleep} function.  @xref{Sleeping}.
1043
1044 You shouldn't count on the signal arriving precisely when the timer
1045 expires.  In a multiprocessing environment there is typically some
1046 amount of delay involved.
1047
1048 @strong{Portability Note:} The @code{setitimer} and @code{getitimer}
1049 functions are derived from BSD Unix, while the @code{alarm} function is
1050 specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
1051 @code{alarm}, but @code{alarm} is more widely used.
1052
1053 @node Sleeping,  , Setting an Alarm, Date and Time
1054 @section Sleeping
1055
1056 The function @code{sleep} gives a simple way to make the program wait
1057 for short periods of time.  If your program doesn't use signals (except
1058 to terminate), then you can expect @code{sleep} to wait reliably for
1059 the specified amount of time.  Otherwise, @code{sleep} can return sooner
1060 if the signal arrives; if you want to wait for a given period regardless
1061 of signals, use @code{select} (@pxref{Waiting for I/O}) and don't
1062 specify any descriptors to wait for.
1063
1064 @comment unistd.h
1065 @comment POSIX.1
1066 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
1067 The @code{sleep} function waits for @var{seconds} or until a signal
1068 is delivered, whichever happens first.  
1069
1070 If @code{sleep} function returns because the requested time has
1071 elapsed, it returns a value of zero.  If it returns because of delivery
1072 of a signal, its return value is the remaining time in the sleep period.
1073
1074 The @code{sleep} function is declared in @file{unistd.h}.
1075 @end deftypefun
1076
1077 Resist the temptation to implement a sleep for a fixed amount of time by
1078 using the return value of @code{sleep}, when nonzero, to call
1079 @code{sleep} again.  This will work with a certain amount of accuracy as
1080 long as signals arrive infrequently.  But each signal can cause the
1081 eventual wakeup time to be off by an additional second or so.  Suppose a
1082 few signals happen to arrive in rapid succession by bad luck---there is
1083 no limit on how much this could shorten or lengthen the wait.
1084
1085 Instead, compute the time at which the program should stop waiting, and
1086 keep trying to wait until that time.  This won't be off by more than a
1087 second.  With just a little more work, you can use @code{select} and
1088 make the waiting period quite accurate.  (Of course, heavy system load
1089 can cause unavoidable additional delays---unless the machine is 
1090 dedicated to one application, there is no way you can avoid this.)
1091
1092 On some systems, @code{sleep} can do strange things if your program uses
1093 @code{SIGALRM} explicitly.  Even if @code{SIGALRM} signals are being
1094 ignored or blocked when @code{sleep} is called, @code{sleep} might
1095 return prematurely on delivery of a @code{SIGALRM} signal.  If you have
1096 established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
1097 signal is delivered while the process is sleeping, the action taken
1098 might be just to cause @code{sleep} to return instead of invoking your
1099 handler.  And, if @code{sleep} is interrupted by delivery of a signal
1100 whose handler requests an alarm or alters the handling of @code{SIGALRM},
1101 this handler and @code{sleep} will interfere.
1102
1103 On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in
1104 the same program, because @code{sleep} does not work by means of
1105 @code{SIGALRM}.
1106