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