Thu Jan 18 00:32:43 1996 Roland McGrath <roland@churchy.gnu.ai.mit.edu>
[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 * Resource Usage::              Measuring various resources used.
30 * Limits on Resources::         Specifying limits on resource usage.
31 * Priority::                    Reading or setting process run priority.
32 @end menu
33
34 @node Processor Time
35 @section Processor Time
36
37 If you're trying to optimize your program or measure its efficiency, it's
38 very useful to be able to know how much @dfn{processor time} or @dfn{CPU
39 time} it has used at any given point.  Processor time is different from
40 actual wall clock time because it doesn't include any time spent waiting
41 for I/O or when some other process is running.  Processor time is
42 represented by the data type @code{clock_t}, and is given as a number of
43 @dfn{clock ticks} relative to an arbitrary base time marking the beginning
44 of a single program invocation.
45 @cindex CPU time
46 @cindex processor time
47 @cindex clock ticks
48 @cindex ticks, clock
49 @cindex time, elapsed CPU
50
51 @menu
52 * Basic CPU Time::              The @code{clock} function.
53 * Detailed CPU Time::           The @code{times} function.
54 @end menu
55
56 @node Basic CPU Time
57 @subsection Basic CPU Time Inquiry
58
59 To get the elapsed CPU time used by a process, you can use the
60 @code{clock} function.  This facility is declared in the header file
61 @file{time.h}.
62 @pindex time.h
63
64 In typical usage, you call the @code{clock} function at the beginning and
65 end of the interval you want to time, subtract the values, and then divide
66 by @code{CLOCKS_PER_SEC} (the number of clock ticks per second), like this:
67
68 @smallexample
69 @group
70 #include <time.h>
71
72 clock_t start, end;
73 double elapsed;
74
75 start = clock();
76 @dots{} /* @r{Do the work.} */
77 end = clock();
78 elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
79 @end group
80 @end smallexample
81
82 Different computers and operating systems vary wildly in how they keep
83 track of processor time.  It's common for the internal processor clock
84 to have a resolution somewhere between hundredths and millionths of a
85 second.
86
87 In the GNU system, @code{clock_t} is equivalent to @code{long int} and
88 @code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
89 @code{clock_t} and the type of the macro @code{CLOCKS_PER_SEC} can be
90 either integer or floating-point types.  Casting processor time values
91 to @code{double}, as in the example above, makes sure that operations
92 such as arithmetic and printing work properly and consistently no matter
93 what the underlying representation is.
94
95 @comment time.h
96 @comment ANSI
97 @deftypevr Macro int CLOCKS_PER_SEC
98 The value of this macro is the number of clock ticks per second measured
99 by the @code{clock} function.
100 @end deftypevr
101
102 @comment time.h
103 @comment POSIX.1
104 @deftypevr Macro int CLK_TCK
105 This is an obsolete name for @code{CLOCKS_PER_SEC}.  
106 @end deftypevr
107
108 @comment time.h
109 @comment ANSI
110 @deftp {Data Type} clock_t
111 This is the type of the value returned by the @code{clock} function.
112 Values of type @code{clock_t} are in units of clock ticks.
113 @end deftp
114
115 @comment time.h
116 @comment ANSI
117 @deftypefun clock_t clock (void)
118 This function returns the elapsed processor time.  The base time is
119 arbitrary but doesn't change within a single process.  If the processor
120 time is not available or cannot be represented, @code{clock} returns the
121 value @code{(clock_t)(-1)}.
122 @end deftypefun
123
124
125 @node Detailed CPU Time
126 @subsection Detailed Elapsed CPU Time Inquiry
127
128 The @code{times} function returns more detailed information about
129 elapsed processor time in a @w{@code{struct tms}} object.  You should
130 include the header file @file{sys/times.h} to use this facility.
131 @pindex sys/times.h
132
133 @comment sys/times.h
134 @comment POSIX.1
135 @deftp {Data Type} {struct tms}
136 The @code{tms} structure is used to return information about process
137 times.  It contains at least the following members:
138
139 @table @code
140 @item clock_t tms_utime
141 This is the CPU time used in executing the instructions of the calling
142 process.
143
144 @item clock_t tms_stime
145 This is the CPU time used by the system on behalf of the calling process.
146
147 @item clock_t tms_cutime
148 This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
149 values of all terminated child processes of the calling process, whose
150 status has been reported to the parent process by @code{wait} or
151 @code{waitpid}; see @ref{Process Completion}.  In other words, it
152 represents the total CPU time used in executing the instructions of all
153 the terminated child processes of the calling process, excluding child
154 processes which have not yet been reported by @code{wait} or
155 @code{waitpid}.
156
157 @item clock_t tms_cstime
158 This is similar to @code{tms_cutime}, but represents the total CPU time
159 used by the system on behalf of all the terminated child processes of the
160 calling process.
161 @end table
162
163 All of the times are given in clock ticks.  These are absolute values; in a
164 newly created process, they are all zero.  @xref{Creating a Process}.
165 @end deftp
166
167 @comment sys/times.h
168 @comment POSIX.1
169 @deftypefun clock_t times (struct tms *@var{buffer})
170 The @code{times} function stores the processor time information for
171 the calling process in @var{buffer}.
172
173 The return value is the same as the value of @code{clock()}: the elapsed
174 real time relative to an arbitrary base.  The base is a constant within a
175 particular process, and typically represents the time since system
176 start-up.  A value of @code{(clock_t)(-1)} is returned to indicate failure.
177 @end deftypefun
178
179 @strong{Portability Note:} The @code{clock} function described in
180 @ref{Basic CPU Time}, is specified by the ANSI C standard.  The
181 @code{times} function is a feature of POSIX.1.  In the GNU system, the
182 value returned by the @code{clock} function is equivalent to the sum of
183 the @code{tms_utime} and @code{tms_stime} fields returned by
184 @code{times}.
185
186 @node Calendar Time
187 @section Calendar Time
188
189 This section describes facilities for keeping track of dates and times
190 according to the Gregorian calendar.
191 @cindex Gregorian calendar
192 @cindex time, calendar
193 @cindex date and time
194
195 There are three representations for date and time information:
196
197 @itemize @bullet
198 @item 
199 @dfn{Calendar time} (the @code{time_t} data type) is a compact 
200 representation, typically giving the number of seconds elapsed since
201 some implementation-specific base time.
202 @cindex calendar time
203
204 @item
205 There is also a @dfn{high-resolution time} representation (the @code{struct
206 timeval} data type) that includes fractions of a second.  Use this time
207 representation instead of ordinary calendar time when you need greater
208 precision.
209 @cindex high-resolution time
210
211 @item
212 @dfn{Local time} or @dfn{broken-down time} (the @code{struct
213 tm} data type) represents the date and time as a set of components
214 specifying the year, month, and so on, for a specific time zone.
215 This time representation is usually used in conjunction with formatting
216 date and time values.
217 @cindex local time
218 @cindex broken-down time
219 @end itemize
220
221 @menu
222 * Simple Calendar Time::        Facilities for manipulating calendar time.
223 * High-Resolution Calendar::    A time representation with greater precision.
224 * Broken-down Time::            Facilities for manipulating local time.
225 * Formatting Date and Time::    Converting times to strings.
226 * TZ Variable::                 How users specify the time zone.
227 * Time Zone Functions::         Functions to examine or specify the time zone. 
228 * Time Functions Example::      An example program showing use of some of
229                                  the time functions.
230 @end menu
231
232 @node Simple Calendar Time
233 @subsection Simple Calendar Time
234
235 This section describes the @code{time_t} data type for representing
236 calendar time, and the functions which operate on calendar time objects.
237 These facilities are declared in the header file @file{time.h}.
238 @pindex time.h
239
240 @cindex epoch
241 @comment time.h
242 @comment ANSI
243 @deftp {Data Type} time_t
244 This is the data type used to represent calendar time.
245 When interpreted as an absolute time
246 value, it represents the number of seconds elapsed since 00:00:00 on
247 January 1, 1970, Coordinated Universal Time.  (This date is sometimes
248 referred to as the @dfn{epoch}.)  POSIX requires that this count
249 ignore leap seconds, but on some hosts this count includes leap seconds
250 if you set @code{TZ} to certain values (@pxref{TZ Variable}).
251
252 In the GNU C library, @code{time_t} is equivalent to @code{long int}.
253 In other systems, @code{time_t} might be either an integer or
254 floating-point type.
255 @end deftp
256
257 @comment time.h
258 @comment ANSI
259 @deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
260 The @code{difftime} function returns the number of seconds elapsed
261 between time @var{time1} and time @var{time0}, as a value of type
262 @code{double}.  The difference ignores leap seconds unless leap
263 second support is enabled.
264
265 In the GNU system, you can simply subtract @code{time_t} values.  But on
266 other systems, the @code{time_t} data type might use some other encoding
267 where subtraction doesn't work directly.
268 @end deftypefun
269
270 @comment time.h
271 @comment ANSI
272 @deftypefun time_t time (time_t *@var{result})
273 The @code{time} function returns the current time as a value of type
274 @code{time_t}.  If the argument @var{result} is not a null pointer, the
275 time value is also stored in @code{*@var{result}}.  If the calendar 
276 time is not available, the value @w{@code{(time_t)(-1)}} is returned.
277 @end deftypefun
278
279
280 @node High-Resolution Calendar
281 @subsection High-Resolution Calendar
282
283 The @code{time_t} data type used to represent calendar times has a 
284 resolution of only one second.  Some applications need more precision.
285
286 So, the GNU C library also contains functions which are capable of
287 representing calendar times to a higher resolution than one second.  The
288 functions and the associated data types described in this section are
289 declared in @file{sys/time.h}.
290 @pindex sys/time.h
291
292 @comment sys/time.h
293 @comment BSD
294 @deftp {Data Type} {struct timeval}
295 The @code{struct timeval} structure represents a calendar time.  It
296 has the following members:
297
298 @table @code
299 @item long int tv_sec
300 This represents the number of seconds since the epoch.  It is equivalent
301 to a normal @code{time_t} value.
302
303 @item long int tv_usec
304 This is the fractional second value, represented as the number of
305 microseconds.
306
307 Some times struct timeval values are used for time intervals.  Then the
308 @code{tv_sec} member is the number of seconds in the interval, and
309 @code{tv_usec} is the number of additional microseconds.
310 @end table
311 @end deftp
312
313 @comment sys/time.h
314 @comment BSD
315 @deftp {Data Type} {struct timezone}
316 The @code{struct timezone} structure is used to hold minimal information
317 about the local time zone.  It has the following members:
318
319 @table @code
320 @item int tz_minuteswest
321 This is the number of minutes west of GMT.
322
323 @item int tz_dsttime
324 If nonzero, daylight savings time applies during some part of the year.
325 @end table
326
327 The @code{struct timezone} type is obsolete and should never be used.
328 Instead, use the facilities described in @ref{Time Zone Functions}.
329 @end deftp
330
331 It is often necessary to subtract two values of type @w{@code{struct
332 timeval}}.  Here is the best way to do this.  It works even on some
333 peculiar operating systems where the @code{tv_sec} member has an
334 unsigned type.
335
336 @smallexample
337 /* @r{Subtract the `struct timeval' values X and Y,}
338    @r{storing the result in RESULT.}
339    @r{Return 1 if the difference is negative, otherwise 0.}  */
340
341 int
342 timeval_subtract (result, x, y)
343      struct timeval *result, *x, *y;
344 @{
345   /* @r{Perform the carry for the later subtraction by updating @var{y}.} */
346   if (x->tv_usec < y->tv_usec) @{
347     int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
348     y->tv_usec -= 1000000 * nsec;
349     y->tv_sec += nsec;
350   @}
351   if (x->tv_usec - y->tv_usec > 1000000) @{
352     int nsec = (y->tv_usec - x->tv_usec) / 1000000;
353     y->tv_usec += 1000000 * nsec;
354     y->tv_sec -= nsec;
355   @}
356
357   /* @r{Compute the time remaining to wait.}
358      @r{@code{tv_usec} is certainly positive.} */
359   result->tv_sec = x->tv_sec - y->tv_sec;
360   result->tv_usec = x->tv_usec - y->tv_usec;
361
362   /* @r{Return 1 if result is negative.} */
363   return x->tv_sec < y->tv_sec;
364 @}
365 @end smallexample
366
367 @comment sys/time.h
368 @comment BSD
369 @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
370 The @code{gettimeofday} function returns the current date and time in the
371 @code{struct timeval} structure indicated by @var{tp}.  Information about the
372 time zone is returned in the structure pointed at @var{tzp}.  If the @var{tzp}
373 argument is a null pointer, time zone information is ignored.
374
375 The return value is @code{0} on success and @code{-1} on failure.  The
376 following @code{errno} error condition is defined for this function:
377
378 @table @code
379 @item ENOSYS
380 The operating system does not support getting time zone information, and
381 @var{tzp} is not a null pointer.  The GNU operating system does not
382 support using @w{@code{struct timezone}} to represent time zone
383 information; that is an obsolete feature of 4.3 BSD.
384 Instead, use the facilities described in @ref{Time Zone Functions}.
385 @end table
386 @end deftypefun
387
388 @comment sys/time.h
389 @comment BSD
390 @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
391 The @code{settimeofday} function sets the current date and time
392 according to the arguments.  As for @code{gettimeofday}, time zone
393 information is ignored if @var{tzp} is a null pointer.
394
395 You must be a privileged user in order to use @code{settimeofday}.
396
397 The return value is @code{0} on success and @code{-1} on failure.  The
398 following @code{errno} error conditions are defined for this function:
399
400 @table @code
401 @item EPERM
402 This process cannot set the time because it is not privileged.
403
404 @item ENOSYS
405 The operating system does not support setting time zone information, and
406 @var{tzp} is not a null pointer.
407 @end table
408 @end deftypefun
409
410 @comment sys/time.h
411 @comment BSD
412 @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
413 This function speeds up or slows down the system clock in order to make
414 gradual adjustments in the current time.  This ensures that the time
415 reported by the system clock is always monotonically increasing, which
416 might not happen if you simply set the current time.
417
418 The @var{delta} argument specifies a relative adjustment to be made to
419 the current time.  If negative, the system clock is slowed down for a
420 while until it has lost this much time.  If positive, the system clock
421 is speeded up for a while.
422
423 If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
424 function returns information about any previous time adjustment that
425 has not yet completed.
426
427 This function is typically used to synchronize the clocks of computers
428 in a local network.  You must be a privileged user to use it.
429 The return value is @code{0} on success and @code{-1} on failure.  The
430 following @code{errno} error condition is defined for this function:
431
432 @table @code
433 @item EPERM
434 You do not have privilege to set the time.
435 @end table
436 @end deftypefun
437
438 @strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
439 and @code{adjtime} functions are derived from BSD.  
440
441
442 @node Broken-down Time
443 @subsection Broken-down Time
444 @cindex broken-down time
445 @cindex calendar time and broken-down time
446
447 Calendar time is represented as a number of seconds.  This is convenient
448 for calculation, but has no resemblance to the way people normally
449 represent dates and times.  By contrast, @dfn{broken-down time} is a binary
450 representation separated into year, month, day, and so on.  Broken down
451 time values are not useful for calculations, but they are useful for
452 printing human readable time.
453
454 A broken-down time value is always relative to a choice of local time
455 zone, and it also indicates which time zone was used.
456
457 The symbols in this section are declared in the header file @file{time.h}.
458
459 @comment time.h
460 @comment ANSI
461 @deftp {Data Type} {struct tm}
462 This is the data type used to represent a broken-down time.  The structure
463 contains at least the following members, which can appear in any order:
464
465 @table @code
466 @item int tm_sec
467 This is the number of seconds after the minute, normally in the range
468 @code{0} to @code{59}.  (The actual upper limit is @code{60}, to allow
469 for leap seconds if leap second support is available.)
470 @cindex leap second
471
472 @item int tm_min
473 This is the number of minutes after the hour, in the range @code{0} to
474 @code{59}.
475
476 @item int tm_hour
477 This is the number of hours past midnight, in the range @code{0} to
478 @code{23}.
479
480 @item int tm_mday
481 This is the day of the month, in the range @code{1} to @code{31}.
482
483 @item int tm_mon
484 This is the number of months since January, in the range @code{0} to
485 @code{11}.
486
487 @item int tm_year
488 This is the number of years since @code{1900}.
489
490 @item int tm_wday
491 This is the number of days since Sunday, in the range @code{0} to @code{6}.
492
493 @item int tm_yday
494 This is the number of days since January 1, in the range @code{0} to
495 @code{365}.
496
497 @item int tm_isdst
498 @cindex Daylight Saving Time
499 @cindex summer time
500 This is a flag that indicates whether Daylight Saving Time is (or was, or
501 will be) in effect at the time described.  The value is positive if
502 Daylight Saving Time is in effect, zero if it is not, and negative if the
503 information is not available.
504
505 @item long int tm_gmtoff
506 This field describes the time zone that was used to compute this
507 broken-down time value; it is the amount you must add to the local time
508 in that zone to get GMT, in units of seconds.  The value is like that of
509 the variable @code{timezone} (@pxref{Time Zone Functions}).  You can
510 also think of this as the ``number of seconds west'' of GMT.  The
511 @code{tm_gmtoff} field is a GNU library extension.
512
513 @item const char *tm_zone
514 This field is the name for the time zone that was used to
515 compute this broken-down time value.  It is a GNU library extension.
516 @end table
517 @end deftp
518
519 @comment time.h
520 @comment ANSI
521 @deftypefun {struct tm *} localtime (const time_t *@var{time})
522 The @code{localtime} function converts the calendar time pointed to by
523 @var{time} to broken-down time representation, expressed relative to the
524 user's specified time zone.
525
526 The return value is a pointer to a static broken-down time structure, which
527 might be overwritten by subsequent calls to @code{ctime}, @code{gmtime},
528 or @code{localtime}.  (But no other library function overwrites the contents
529 of this object.)
530
531 Calling @code{localtime} has one other effect: it sets the variable
532 @code{tzname} with information about the current time zone.  @xref{Time
533 Zone Functions}.
534 @end deftypefun
535
536 @comment time.h
537 @comment ANSI
538 @deftypefun {struct tm *} gmtime (const time_t *@var{time})
539 This function is similar to @code{localtime}, except that the broken-down
540 time is expressed as Coordinated Universal Time (UTC)---that is, as
541 Greenwich Mean Time (GMT) rather than relative to the local time zone.
542
543 Recall that calendar times are @emph{always} expressed in coordinated
544 universal time.
545 @end deftypefun
546
547 @comment time.h
548 @comment ANSI
549 @deftypefun time_t mktime (struct tm *@var{brokentime})
550 The @code{mktime} function is used to convert a broken-down time structure
551 to a calendar time representation.  It also ``normalizes'' the contents of
552 the broken-down time structure, by filling in the day of week and day of
553 year based on the other date and time components.
554
555 The @code{mktime} function ignores the specified contents of the
556 @code{tm_wday} and @code{tm_yday} members of the broken-down time
557 structure.  It uses the values of the other components to compute the
558 calendar time; it's permissible for these components to have
559 unnormalized values outside of their normal ranges.  The last thing that
560 @code{mktime} does is adjust the components of the @var{brokentime}
561 structure (including the @code{tm_wday} and @code{tm_yday}).
562
563 If the specified broken-down time cannot be represented as a calendar time,
564 @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
565 the contents of @var{brokentime}.
566
567 Calling @code{mktime} also sets the variable @code{tzname} with
568 information about the current time zone.  @xref{Time Zone Functions}.
569 @end deftypefun
570
571 @node Formatting Date and Time
572 @subsection Formatting Date and Time
573
574 The functions described in this section format time values as strings.
575 These functions are declared in the header file @file{time.h}.
576 @pindex time.h
577
578 @comment time.h
579 @comment ANSI
580 @deftypefun {char *} asctime (const struct tm *@var{brokentime})
581 The @code{asctime} function converts the broken-down time value that
582 @var{brokentime} points to into a string in a standard format:
583
584 @smallexample
585 "Tue May 21 13:46:22 1991\n"
586 @end smallexample
587
588 The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
589 @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
590
591 The abbreviations for the months are: @samp{Jan}, @samp{Feb},
592 @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
593 @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
594
595 The return value points to a statically allocated string, which might be
596 overwritten by subsequent calls to @code{asctime} or @code{ctime}.
597 (But no other library function overwrites the contents of this
598 string.)
599 @end deftypefun
600
601 @comment time.h
602 @comment ANSI
603 @deftypefun {char *} ctime (const time_t *@var{time})
604 The @code{ctime} function is similar to @code{asctime}, except that the
605 time value is specified as a @code{time_t} calendar time value rather
606 than in broken-down local time format.  It is equivalent to
607
608 @smallexample
609 asctime (localtime (@var{time}))
610 @end smallexample
611
612 @code{ctime} sets the variable @code{tzname}, because @code{localtime}
613 does so.  @xref{Time Zone Functions}.
614 @end deftypefun
615
616 @comment time.h
617 @comment ANSI
618 @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
619 This function is similar to the @code{sprintf} function (@pxref{Formatted
620 Input}), but the conversion specifications that can appear in the format
621 template @var{template} are specialized for printing components of the date
622 and time @var{brokentime} according to the locale currently specified for
623 time conversion (@pxref{Locales}).
624
625 Ordinary characters appearing in the @var{template} are copied to the
626 output string @var{s}; this can include multibyte character sequences.
627 Conversion specifiers are introduced by a @samp{%} character, and are
628 replaced in the output string as follows:
629
630 @table @code
631 @item %a
632 The abbreviated weekday name according to the current locale.
633
634 @item %A
635 The full weekday name according to the current locale.
636
637 @item %b
638 The abbreviated month name according to the current locale.
639
640 @item %B
641 The full month name according to the current locale.
642
643 @item %c
644 The preferred date and time representation for the current locale.
645
646 @item %d
647 The day of the month as a decimal number (range @code{01} to @code{31}).
648
649 @item %H
650 The hour as a decimal number, using a 24-hour clock (range @code{00} to
651 @code{23}).
652
653 @item %I
654 The hour as a decimal number, using a 12-hour clock (range @code{01} to
655 @code{12}).
656
657 @item %j
658 The day of the year as a decimal number (range @code{001} to @code{366}).
659
660 @item %m
661 The month as a decimal number (range @code{01} to @code{12}).
662
663 @item %M
664 The minute as a decimal number.
665
666 @item %p
667 Either @samp{am} or @samp{pm}, according to the given time value; or the
668 corresponding strings for the current locale.
669
670 @item %S
671 The second as a decimal number.
672
673 @item %U
674 The week number of the current year as a decimal number, starting with
675 the first Sunday as the first day of the first week.
676
677 @item %W
678 The week number of the current year as a decimal number, starting with
679 the first Monday as the first day of the first week.
680
681 @item %w
682 The day of the week as a decimal number, Sunday being @code{0}.
683
684 @item %x
685 The preferred date representation for the current locale, but without the
686 time.
687
688 @item %X
689 The preferred time representation for the current locale, but with no date.
690
691 @item %y
692 The year as a decimal number, but without a century (range @code{00} to
693 @code{99}).
694
695 @item %Y
696 The year as a decimal number, including the century.
697
698 @item %Z
699 The time zone or name or abbreviation (empty if the time zone can't be
700 determined).
701
702 @item %%
703 A literal @samp{%} character.
704 @end table
705
706 The @var{size} parameter can be used to specify the maximum number of
707 characters to be stored in the array @var{s}, including the terminating
708 null character.  If the formatted time requires more than @var{size}
709 characters, the excess characters are discarded.  The return value from
710 @code{strftime} is the number of characters placed in the array @var{s},
711 not including the terminating null character.  If the value equals
712 @var{size}, it means that the array @var{s} was too small; you should
713 repeat the call, providing a bigger array.
714
715 If @var{s} is a null pointer, @code{strftime} does not actually write
716 anything, but instead returns the number of characters it would have written.
717
718 For an example of @code{strftime}, see @ref{Time Functions Example}.
719 @end deftypefun
720
721 @node TZ Variable
722 @subsection Specifying the Time Zone with @code{TZ}
723
724 In POSIX systems, a user can specify the time zone by means of the
725 @code{TZ} environment variable.  For information about how to set
726 environment variables, see @ref{Environment Variables}.  The functions
727 for accessing the time zone are declared in @file{time.h}.
728 @pindex time.h
729 @cindex time zone
730
731 You should not normally need to set @code{TZ}.  If the system is
732 configured properly, the default timezone will be correct.  You might
733 set @code{TZ} if you are using a computer over the network from a
734 different timezone, and would like times reported to you in the timezone
735 that local for you, rather than what is local for the computer.
736
737 In POSIX.1 systems the value of the @code{TZ} variable can be of one of
738 three formats.  With the GNU C library, the most common format is the
739 last one, which can specify a selection from a large database of time
740 zone information for many regions of the world.  The first two formats
741 are used to describe the time zone information directly, which is both
742 more cumbersome and less precise.  But the POSIX.1 standard only
743 specifies the details of the first two formats, so it is good to be
744 familiar with them in case you come across a POSIX.1 system that doesn't
745 support a time zone information database.
746
747 The first format is used when there is no Daylight Saving Time (or
748 summer time) in the local time zone:
749
750 @smallexample
751 @r{@var{std} @var{offset}}
752 @end smallexample
753
754 The @var{std} string specifies the name of the time zone.  It must be
755 three or more characters long and must not contain a leading colon or
756 embedded digits, commas, or plus or minus signs.  There is no space
757 character separating the time zone name from the @var{offset}, so these
758 restrictions are necessary to parse the specification correctly.
759
760 The @var{offset} specifies the time value one must add to the local time
761 to get a Coordinated Universal Time value.  It has syntax like
762 [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  This
763 is positive if the local time zone is west of the Prime Meridian and
764 negative if it is east.  The hour must be between @code{0} and
765 @code{24}, and the minute and seconds between @code{0} and @code{59}.
766
767 For example, here is how we would specify Eastern Standard Time, but
768 without any daylight savings time alternative:
769
770 @smallexample
771 EST+5
772 @end smallexample
773
774 The second format is used when there is Daylight Saving Time:
775
776 @smallexample
777 @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
778 @end smallexample
779
780 The initial @var{std} and @var{offset} specify the standard time zone, as
781 described above.  The @var{dst} string and @var{offset} specify the name
782 and offset for the corresponding daylight savings time time zone; if the
783 @var{offset} is omitted, it defaults to one hour ahead of standard time.
784
785 The remainder of the specification describes when daylight savings time is
786 in effect.  The @var{start} field is when daylight savings time goes into
787 effect and the @var{end} field is when the change is made back to standard
788 time.  The following formats are recognized for these fields:
789
790 @table @code
791 @item J@var{n}
792 This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
793 February 29 is never counted, even in leap years.
794
795 @item @var{n}
796 This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
797 February 29 is counted in leap years.
798
799 @item M@var{m}.@var{w}.@var{d}
800 This specifies day @var{d} of week @var{w} of month @var{m}.  The day
801 @var{d} must be between @code{0} (Sunday) and @code{6}.  The week
802 @var{w} must be between @code{1} and @code{5}; week @code{1} is the
803 first week in which day @var{d} occurs, and week @code{5} specifies the
804 @emph{last} @var{d} day in the month.  The month @var{m} should be
805 between @code{1} and @code{12}.
806 @end table
807
808 The @var{time} fields specify when, in the local time currently in
809 effect, the change to the other time occurs.  If omitted, the default is
810 @code{02:00:00}.
811
812 For example, here is how one would specify the Eastern time zone in the
813 United States, including the appropriate daylight saving time and its dates
814 of applicability.  The normal offset from GMT is 5 hours; since this is
815 west of the prime meridian, the sign is positive.  Summer time begins on
816 the first Sunday in April at 2:00am, and ends on the last Sunday in October
817 at 2:00am.
818
819 @smallexample
820 EST+5EDT,M4.1.0/M10.5.0
821 @end smallexample
822
823 The schedule of daylight savings time in any particular jurisdiction has
824 changed over the years.  To be strictly correct, the conversion of dates
825 and times in the past should be based on the schedule that was in effect
826 then.  However, this format has no facilities to let you specify how the
827 schedule has changed from year to year.  The most you can do is specify
828 one particular schedule---usually the present day schedule---and this is
829 used to convert any date, no matter when.  For precise time zone
830 specifications, it is best to use the time zone information database
831 (see below).
832
833 The third format looks like this:
834
835 @smallexample
836 :@var{characters}
837 @end smallexample
838
839 Each operating system interprets this format differently; in the GNU C
840 library, @var{characters} is the name of a file which describes the time
841 zone.
842
843 @pindex /etc/localtime
844 @pindex localtime
845 If the @code{TZ} environment variable does not have a value, the
846 operation chooses a time zone by default.  In the GNU C library, the
847 default time zone is like the specification @samp{TZ=:/etc/localtime}
848 (or @samp{TZ=:/usr/local/etc/localtime}, depending on how GNU C library
849 was configured; @pxref{Installation}).  Other C libraries use their own
850 rule for choosing the default time zone, so there is little we can say
851 about them.
852
853 @cindex time zone database
854 @pindex /share/lib/zoneinfo
855 @pindex zoneinfo
856 If @var{characters} begins with a slash, it is an absolute file name;
857 otherwise the library looks for the file
858 @w{@file{/share/lib/zoneinfo/@var{characters}}}.  The @file{zoneinfo}
859 directory contains data files describing local time zones in many
860 different parts of the world.  The names represent major cities, with
861 subdirectories for geographical areas; for example,
862 @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
863 These data files are installed by the system administrator, who also
864 sets @file{/etc/localtime} to point to the data file for the local time
865 zone.  The GNU C library comes with a large database of time zone
866 information for most regions of the world, which is maintained by a
867 community of volunteers and put in the public domain.
868
869 @node Time Zone Functions
870 @subsection Functions and Variables for Time Zones
871
872 @comment time.h
873 @comment POSIX.1
874 @deftypevar char * tzname [2]
875 The array @code{tzname} contains two strings, which are the standard
876 names of the pair of time zones (standard and daylight
877 savings) that the user has selected.  @code{tzname[0]} is the name of
878 the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
879 is the name for the time zone when daylight savings time is in use (for
880 example, @code{"EDT"}).  These correspond to the @var{std} and @var{dst}
881 strings (respectively) from the @code{TZ} environment variable.
882
883 The @code{tzname} array is initialized from the @code{TZ} environment
884 variable whenever @code{tzset}, @code{ctime}, @code{strftime},
885 @code{mktime}, or @code{localtime} is called.
886 @end deftypevar
887
888 @comment time.h
889 @comment POSIX.1
890 @deftypefun void tzset (void)
891 The @code{tzset} function initializes the @code{tzname} variable from
892 the value of the @code{TZ} environment variable.  It is not usually
893 necessary for your program to call this function, because it is called
894 automatically when you use the other time conversion functions that
895 depend on the time zone.
896 @end deftypefun
897
898 The following variables are defined for compatibility with System V
899 Unix.  These variables are set by calling @code{tzset}.
900
901 @comment time.h
902 @comment SVID
903 @deftypevar {long int} timezone
904 This contains the difference between GMT and local standard time, in
905 seconds.  For example, in the U.S. Eastern time zone, the value is
906 @code{5*60*60}.
907 @end deftypevar
908
909 @comment time.h
910 @comment SVID
911 @deftypevar int daylight
912 This variable has a nonzero value if daylight savings time rules apply.
913 A nonzero value does not necessarily mean that daylight savings time is
914 now in effect; it means only that daylight savings time is sometimes in
915 effect.
916 @end deftypevar
917
918 @node Time Functions Example
919 @subsection Time Functions Example
920
921 Here is an example program showing the use of some of the local time and
922 calendar time functions.
923
924 @smallexample
925 @include strftim.c.texi
926 @end smallexample
927
928 It produces output like this:
929
930 @smallexample
931 Wed Jul 31 13:02:36 1991
932 Today is Wednesday, July 31.
933 The time is 01:02 PM.
934 @end smallexample
935
936
937 @node Setting an Alarm
938 @section Setting an Alarm
939
940 The @code{alarm} and @code{setitimer} functions provide a mechanism for a
941 process to interrupt itself at some future time.  They do this by setting a
942 timer; when the timer expires, the process receives a signal.
943
944 @cindex setting an alarm
945 @cindex interval timer, setting
946 @cindex alarms, setting
947 @cindex timers, setting
948 Each process has three independent interval timers available:
949
950 @itemize @bullet
951 @item 
952 A real-time timer that counts clock time.  This timer sends a
953 @code{SIGALRM} signal to the process when it expires.
954 @cindex real-time timer
955 @cindex timer, real-time
956
957 @item 
958 A virtual timer that counts CPU time used by the process.  This timer
959 sends a @code{SIGVTALRM} signal to the process when it expires.
960 @cindex virtual timer
961 @cindex timer, virtual
962
963 @item 
964 A profiling timer that counts both CPU time used by the process, and CPU
965 time spent in system calls on behalf of the process.  This timer sends a
966 @code{SIGPROF} signal to the process when it expires.
967 @cindex profiling timer
968 @cindex timer, profiling
969
970 This timer is useful for profiling in interpreters.  The interval timer
971 mechanism does not have the fine granularity necessary for profiling
972 native code.
973 @c @xref{profil} !!!
974 @end itemize
975
976 You can only have one timer of each kind set at any given time.  If you
977 set a timer that has not yet expired, that timer is simply reset to the
978 new value.
979
980 You should establish a handler for the appropriate alarm signal using
981 @code{signal} or @code{sigaction} before issuing a call to @code{setitimer}
982 or @code{alarm}.  Otherwise, an unusual chain of events could cause the
983 timer to expire before your program establishes the handler, and in that
984 case it would be terminated, since that is the default action for the alarm
985 signals.  @xref{Signal Handling}.
986
987 The @code{setitimer} function is the primary means for setting an alarm.
988 This facility is declared in the header file @file{sys/time.h}.  The
989 @code{alarm} function, declared in @file{unistd.h}, provides a somewhat
990 simpler interface for setting the real-time timer.
991 @pindex unistd.h
992 @pindex sys/time.h
993
994 @comment sys/time.h
995 @comment BSD
996 @deftp {Data Type} {struct itimerval}
997 This structure is used to specify when a timer should expire.  It contains
998 the following members:
999 @table @code
1000 @item struct timeval it_interval
1001 This is the interval between successive timer interrupts.  If zero, the
1002 alarm will only be sent once.
1003
1004 @item struct timeval it_value
1005 This is the interval to the first timer interrupt.  If zero, the alarm is
1006 disabled.
1007 @end table
1008
1009 The @code{struct timeval} data type is described in @ref{High-Resolution
1010 Calendar}.
1011 @end deftp
1012
1013 @comment sys/time.h
1014 @comment BSD
1015 @deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old})
1016 The @code{setitimer} function sets the timer specified by @var{which} 
1017 according to @var{new}.  The @var{which} argument can have a value of
1018 @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
1019
1020 If @var{old} is not a null pointer, @code{setitimer} returns information
1021 about any previous unexpired timer of the same kind in the structure it
1022 points to.
1023
1024 The return value is @code{0} on success and @code{-1} on failure.  The
1025 following @code{errno} error conditions are defined for this function:
1026
1027 @table @code
1028 @item EINVAL
1029 The timer interval was too large.
1030 @end table
1031 @end deftypefun
1032
1033 @comment sys/time.h
1034 @comment BSD
1035 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
1036 The @code{getitimer} function stores information about the timer specified
1037 by @var{which} in the structure pointed at by @var{old}.
1038
1039 The return value and error conditions are the same as for @code{setitimer}.
1040 @end deftypefun
1041
1042 @comment sys/time.h
1043 @comment BSD
1044 @table @code
1045 @item ITIMER_REAL
1046 @findex ITIMER_REAL
1047 This constant can be used as the @var{which} argument to the
1048 @code{setitimer} and @code{getitimer} functions to specify the real-time
1049 timer.
1050
1051 @comment sys/time.h
1052 @comment BSD
1053 @item ITIMER_VIRTUAL
1054 @findex ITIMER_VIRTUAL
1055 This constant can be used as the @var{which} argument to the
1056 @code{setitimer} and @code{getitimer} functions to specify the virtual
1057 timer.
1058
1059 @comment sys/time.h
1060 @comment BSD
1061 @item ITIMER_PROF
1062 @findex ITIMER_PROF
1063 This constant can be used as the @var{which} argument to the
1064 @code{setitimer} and @code{getitimer} functions to specify the profiling
1065 timer.
1066 @end table
1067
1068 @comment unistd.h
1069 @comment POSIX.1
1070 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
1071 The @code{alarm} function sets the real-time timer to expire in
1072 @var{seconds} seconds.  If you want to cancel any existing alarm, you
1073 can do this by calling @code{alarm} with a @var{seconds} argument of
1074 zero.
1075
1076 The return value indicates how many seconds remain before the previous
1077 alarm would have been sent.  If there is no previous alarm, @code{alarm}
1078 returns zero.
1079 @end deftypefun
1080
1081 The @code{alarm} function could be defined in terms of @code{setitimer}
1082 like this:
1083
1084 @smallexample
1085 unsigned int
1086 alarm (unsigned int seconds)
1087 @{
1088   struct itimerval old, new;
1089   new.it_interval.tv_usec = 0;
1090   new.it_interval.tv_sec = 0;
1091   new.it_value.tv_usec = 0;
1092   new.it_value.tv_sec = (long int) seconds;
1093   if (setitimer (ITIMER_REAL, &new, &old) < 0)
1094     return 0;
1095   else
1096     return old.it_value.tv_sec;
1097 @}
1098 @end smallexample
1099
1100 There is an example showing the use of the @code{alarm} function in
1101 @ref{Handler Returns}.
1102
1103 If you simply want your process to wait for a given number of seconds,
1104 you should use the @code{sleep} function.  @xref{Sleeping}.
1105
1106 You shouldn't count on the signal arriving precisely when the timer
1107 expires.  In a multiprocessing environment there is typically some
1108 amount of delay involved.
1109
1110 @strong{Portability Note:} The @code{setitimer} and @code{getitimer}
1111 functions are derived from BSD Unix, while the @code{alarm} function is
1112 specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
1113 @code{alarm}, but @code{alarm} is more widely used.
1114
1115 @node Sleeping
1116 @section Sleeping
1117
1118 The function @code{sleep} gives a simple way to make the program wait
1119 for short periods of time.  If your program doesn't use signals (except
1120 to terminate), then you can expect @code{sleep} to wait reliably for
1121 the specified amount of time.  Otherwise, @code{sleep} can return sooner
1122 if a signal arrives; if you want to wait for a given period regardless
1123 of signals, use @code{select} (@pxref{Waiting for I/O}) and don't
1124 specify any descriptors to wait for.
1125 @c !!! select can get EINTR; using SA_RESTART makes sleep win too.
1126
1127 @comment unistd.h
1128 @comment POSIX.1
1129 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
1130 The @code{sleep} function waits for @var{seconds} or until a signal
1131 is delivered, whichever happens first.  
1132
1133 If @code{sleep} function returns because the requested time has
1134 elapsed, it returns a value of zero.  If it returns because of delivery
1135 of a signal, its return value is the remaining time in the sleep period.
1136
1137 The @code{sleep} function is declared in @file{unistd.h}.
1138 @end deftypefun
1139
1140 Resist the temptation to implement a sleep for a fixed amount of time by
1141 using the return value of @code{sleep}, when nonzero, to call
1142 @code{sleep} again.  This will work with a certain amount of accuracy as
1143 long as signals arrive infrequently.  But each signal can cause the
1144 eventual wakeup time to be off by an additional second or so.  Suppose a
1145 few signals happen to arrive in rapid succession by bad luck---there is
1146 no limit on how much this could shorten or lengthen the wait.
1147
1148 Instead, compute the time at which the program should stop waiting, and
1149 keep trying to wait until that time.  This won't be off by more than a
1150 second.  With just a little more work, you can use @code{select} and
1151 make the waiting period quite accurate.  (Of course, heavy system load
1152 can cause unavoidable additional delays---unless the machine is 
1153 dedicated to one application, there is no way you can avoid this.)
1154
1155 On some systems, @code{sleep} can do strange things if your program uses
1156 @code{SIGALRM} explicitly.  Even if @code{SIGALRM} signals are being
1157 ignored or blocked when @code{sleep} is called, @code{sleep} might
1158 return prematurely on delivery of a @code{SIGALRM} signal.  If you have
1159 established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
1160 signal is delivered while the process is sleeping, the action taken
1161 might be just to cause @code{sleep} to return instead of invoking your
1162 handler.  And, if @code{sleep} is interrupted by delivery of a signal
1163 whose handler requests an alarm or alters the handling of @code{SIGALRM},
1164 this handler and @code{sleep} will interfere.
1165
1166 On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in
1167 the same program, because @code{sleep} does not work by means of
1168 @code{SIGALRM}.
1169
1170 @node Resource Usage
1171 @section Resource Usage
1172
1173 @pindex sys/resource.h
1174 The function @code{getrusage} and the data type @code{struct rusage}
1175 are used for examining the usage figures of a process.  They are declared
1176 in @file{sys/resource.h}.
1177
1178 @comment sys/resource.h
1179 @comment BSD
1180 @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage})
1181 This function reports the usage totals for processes specified by
1182 @var{processes}, storing the information in @code{*@var{rusage}}.
1183
1184 In most systems, @var{processes} has only two valid values:
1185
1186 @table @code
1187 @comment sys/resource.h
1188 @comment BSD
1189 @item RUSAGE_SELF
1190 Just the current process.
1191
1192 @comment sys/resource.h
1193 @comment BSD
1194 @item RUSAGE_CHILDREN
1195 All child processes (direct and indirect) that have terminated already.
1196 @end table
1197
1198 In the GNU system, you can also inquire about a particular child process
1199 by specifying its process ID.
1200
1201 The return value of @code{getrusage} is zero for success, and @code{-1}
1202 for failure.
1203
1204 @table @code
1205 @item EINVAL
1206 The argument @var{processes} is not valid.
1207 @end table
1208 @end deftypefun
1209
1210 One way of getting usage figures for a particular child process is with
1211 the function @code{wait4}, which returns totals for a child when it
1212 terminates.  @xref{BSD Wait Functions}.
1213
1214 @comment sys/resource.h
1215 @comment BSD
1216 @deftp {Data Type} {struct rusage}
1217 This data type records a collection usage amounts for various sorts of
1218 resources.  It has the following members, and possibly others:
1219
1220 @table @code
1221 @item struct timeval ru_utime
1222 Time spent executing user instructions.
1223
1224 @item struct timeval ru_stime
1225 Time spent in operating system code on behalf of @var{processes}.
1226
1227 @item long int ru_maxrss
1228 The maximum resident set size used, in kilobytes.  That is, the maximum
1229 number of kilobytes that @var{processes} used in real memory simultaneously.
1230
1231 @item long int ru_ixrss
1232 An integral value expressed in kilobytes times ticks of execution, which
1233 indicates the amount of memory used by text that was shared with other
1234 processes.
1235
1236 @item long int ru_idrss
1237 An integral value expressed the same way, which is the amount of
1238 unshared memory used in data.
1239
1240 @item long int ru_isrss
1241 An integral value expressed the same way, which is the amount of
1242 unshared memory used in stack space.
1243
1244 @item long int ru_minflt
1245 The number of page faults which were serviced without requiring any I/O.
1246
1247 @item long int ru_majflt
1248 The number of page faults which were serviced by doing I/O.
1249
1250 @item long int ru_nswap
1251 The number of times @var{processes} was swapped entirely out of main memory.
1252
1253 @item long int ru_inblock
1254 The number of times the file system had to read from the disk on behalf
1255 of @var{processes}.
1256
1257 @item long int ru_oublock
1258 The number of times the file system had to write to the disk on behalf
1259 of @var{processes}.
1260
1261 @item long int ru_msgsnd
1262 Number of IPC messages sent.
1263
1264 @item long ru_msgrcv
1265 Number of IPC messages received.
1266
1267 @item long int ru_nsignals
1268 Number of signals received.
1269
1270 @item long int ru_nvcsw
1271 The number of times @var{processes} voluntarily invoked a context switch
1272 (usually to wait for some service).
1273
1274 @item long int ru_nivcsw
1275 The number of times an involuntary context switch took place (because
1276 the time slice expired, or another process of higher priority became
1277 runnable).
1278 @end table
1279 @end deftp
1280
1281 An additional historical function for examining usage figures,
1282 @code{vtimes}, is supported but not documented here.  It is declared in
1283 @file{sys/vtimes.h}.
1284
1285 @node Limits on Resources
1286 @section Limiting Resource Usage
1287 @cindex resource limits
1288 @cindex limits on resource usage
1289 @cindex usage limits
1290
1291 You can specify limits for the resource usage of a process.  When the
1292 process tries to exceed a limit, it may get a signal, or the system call
1293 by which it tried to do so may fail, depending on the limit.  Each
1294 process initially inherits its limit values from its parent, but it can
1295 subsequently change them.
1296
1297 @pindex sys/resource.h
1298 The symbols in this section are defined in @file{sys/resource.h}.
1299
1300 @comment sys/resource.h
1301 @comment BSD
1302 @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp})
1303 Read the current value and the maximum value of resource @var{resource}
1304 and store them in @code{*@var{rlp}}.
1305
1306 The return value is @code{0} on success and @code{-1} on failure.  The
1307 only possible @code{errno} error condition is @code{EFAULT}.
1308 @end deftypefun
1309
1310 @comment sys/resource.h
1311 @comment BSD
1312 @deftypefun int setrlimit (int @var{resource}, struct rlimit *@var{rlp})
1313 Store the current value and the maximum value of resource @var{resource}
1314 in @code{*@var{rlp}}.
1315
1316 The return value is @code{0} on success and @code{-1} on failure.  The
1317 following @code{errno} error condition is possible:
1318
1319 @table @code
1320 @item EPERM
1321 You tried to change the maximum permissible limit value,
1322 but you don't have privileges to do so.
1323 @end table
1324 @end deftypefun
1325
1326 @comment sys/resource.h
1327 @comment BSD
1328 @deftp {Data Type} {struct rlimit}
1329 This structure is used with @code{getrlimit} to receive limit values,
1330 and with @code{setrlimit} to specify limit values.  It has two fields:
1331
1332 @table @code
1333 @item rlim_cur
1334 The current value of the limit in question.
1335 This is also called the ``soft limit''.
1336 @cindex soft limit
1337
1338 @item rlim_max
1339 The maximum permissible value of the limit in question.  You cannot set
1340 the current value of the limit to a larger number than this maximum.
1341 Only the super user can change the maximum permissible value.
1342 This is also called the ``hard limit''.
1343 @cindex hard limit
1344 @end table
1345
1346 In @code{getrlimit}, the structure is an output; it receives the current
1347 values.  In @code{setrlimit}, it specifies the new values.
1348 @end deftp
1349
1350 Here is a list of resources that you can specify a limit for.
1351 Those that are sizes are measured in bytes.
1352
1353 @table @code
1354 @comment sys/resource.h
1355 @comment BSD
1356 @item RLIMIT_CPU
1357 @vindex RLIMIT_CPU
1358 The maximum amount of cpu time the process can use.  If it runs for
1359 longer than this, it gets a signal: @code{SIGXCPU}.  The value is
1360 measured in seconds.  @xref{Operation Error Signals}.
1361
1362 @comment sys/resource.h
1363 @comment BSD
1364 @item RLIMIT_FSIZE
1365 @vindex RLIMIT_FSIZE
1366 The maximum size of file the process can create.  Trying to write a
1367 larger file causes a signal: @code{SIGXFSZ}.  @xref{Operation Error
1368 Signals}.
1369
1370 @comment sys/resource.h
1371 @comment BSD
1372 @item RLIMIT_DATA
1373 @vindex RLIMIT_DATA
1374 The maximum size of data memory for the process.  If the process tries
1375 to allocate data memory beyond this amount, the allocation function
1376 fails.
1377
1378 @comment sys/resource.h
1379 @comment BSD
1380 @item RLIMIT_STACK
1381 @vindex RLIMIT_STACK
1382 The maximum stack size for the process.  If the process tries to extend
1383 its stack past this size, it gets a @code{SIGSEGV} signal.
1384 @xref{Program Error Signals}.
1385
1386 @comment sys/resource.h
1387 @comment BSD
1388 @item RLIMIT_CORE
1389 @vindex RLIMIT_CORE
1390 The maximum size core file that this process can create.  If the process
1391 terminates and would dump a core file larger than this maximum size,
1392 then no core file is created.  So setting this limit to zero prevents
1393 core files from ever being created.
1394
1395 @comment sys/resource.h
1396 @comment BSD
1397 @item RLIMIT_RSS
1398 @vindex RLIMIT_RSS
1399 The maximum amount of physical memory that this process should get.
1400 This parameter is a guide for the system's scheduler and memory
1401 allocator; the system may give the process more memory when there is a
1402 surplus.
1403
1404 @comment sys/resource.h
1405 @comment BSD
1406 @item RLIMIT_MEMLOCK
1407 The maximum amount of memory that can be locked into physical memory (so
1408 it will never be paged out).
1409
1410 @comment sys/resource.h
1411 @comment BSD
1412 @item RLIMIT_NPROC
1413 The maximum number of processes that can be created with the same user ID.
1414 If you have reached the limit for your user ID, @code{fork} will fail
1415 with @code{EAGAIN}.  @xref{Creating a Process}.
1416
1417 @comment sys/resource.h
1418 @comment BSD
1419 @item RLIMIT_NOFILE
1420 @vindex RLIMIT_NOFILE
1421 @itemx RLIMIT_OFILE
1422 @vindex RLIMIT_OFILE
1423 The maximum number of files that the process can open.  If it tries to
1424 open more files than this, it gets error code @code{EMFILE}.
1425 @xref{Error Codes}.  Not all systems support this limit; GNU does, and
1426 4.4 BSD does.
1427
1428 @comment sys/resource.h
1429 @comment BSD
1430 @item RLIM_NLIMITS
1431 @vindex RLIM_NLIMITS
1432 The number of different resource limits.  Any valid @var{resource}
1433 operand must be less than @code{RLIM_NLIMITS}.
1434 @end table
1435
1436 @comment sys/resource.h
1437 @comment BSD
1438 @defvr Constant int RLIM_INFINITY
1439 This constant stands for a value of ``infinity'' when supplied as
1440 the limit value in @code{setrlimit}.
1441 @end defvr
1442
1443 @c ??? Someone want to finish these?
1444 Two historical functions for setting resource limits, @code{ulimit} and
1445 @code{vlimit}, are not documented here.  The latter is declared in
1446 @file{sys/vlimit.h} and comes from BSD.
1447
1448 @node Priority
1449 @section Process Priority
1450 @cindex process priority
1451 @cindex priority of a process
1452
1453 @pindex sys/resource.h
1454 When several processes try to run, their respective priorities determine
1455 what share of the CPU each process gets.  This section describes how you
1456 can read and set the priority of a process.  All these functions and
1457 macros are declared in @file{sys/resource.h}.
1458
1459 The range of valid priority values depends on the operating system, but
1460 typically it runs from @code{-20} to @code{20}.  A lower priority value
1461 means the process runs more often.  These constants describe the range of
1462 priority values:
1463
1464 @table @code
1465 @comment sys/resource.h
1466 @comment BSD
1467 @item PRIO_MIN
1468 @vindex PRIO_MIN
1469 The smallest valid priority value.
1470
1471 @comment sys/resource.h
1472 @comment BSD
1473 @item PRIO_MAX
1474 @vindex PRIO_MAX
1475 The smallest valid priority value.
1476 @end table
1477
1478 @comment sys/resource.h
1479 @comment BSD
1480 @deftypefun int getpriority (int @var{class}, int @var{id})
1481 Read the priority of a class of processes; @var{class} and @var{id}
1482 specify which ones (see below).  If the processes specified do not all
1483 have the same priority, this returns the smallest value that any of them
1484 has.
1485
1486 The return value is the priority value on success, and @code{-1} on
1487 failure.  The following @code{errno} error condition are possible for
1488 this function:
1489
1490 @table @code
1491 @item ESRCH
1492 The combination of @var{class} and @var{id} does not match any existing
1493 process.
1494
1495 @item EINVAL
1496 The value of @var{class} is not valid.
1497 @end table
1498
1499 When the return value is @code{-1}, it could indicate failure, or it
1500 could be the priority value.  The only way to make certain is to set
1501 @code{errno = 0} before calling @code{getpriority}, then use @code{errno
1502 != 0} afterward as the criterion for failure.
1503 @end deftypefun
1504
1505 @comment sys/resource.h
1506 @comment BSD
1507 @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority})
1508 Set the priority of a class of processes to @var{priority}; @var{class}
1509 and @var{id} specify which ones (see below).
1510
1511 The return value is @code{0} on success and @code{-1} on failure.  The
1512 following @code{errno} error condition are defined for this function:
1513
1514 @table @code
1515 @item ESRCH
1516 The combination of @var{class} and @var{id} does not match any existing
1517 process.
1518
1519 @item EINVAL
1520 The value of @var{class} is not valid.
1521
1522 @item EPERM
1523 You tried to set the priority of some other user's process, and you
1524 don't have privileges for that.
1525
1526 @item EACCES
1527 You tried to lower the priority of a process, and you don't have
1528 privileges for that.
1529 @end table
1530 @end deftypefun
1531
1532 The arguments @var{class} and @var{id} together specify a set of
1533 processes you are interested in.  These are the possible values for
1534 @var{class}:
1535
1536 @table @code
1537 @comment sys/resource.h
1538 @comment BSD
1539 @item PRIO_PROCESS
1540 @vindex PRIO_PROCESS
1541 Read or set the priority of one process.  The argument @var{id} is a
1542 process ID.
1543
1544 @comment sys/resource.h
1545 @comment BSD
1546 @item PRIO_PGRP
1547 @vindex PRIO_PGRP
1548 Read or set the priority of one process group.  The argument @var{id} is
1549 a process group ID.
1550
1551 @comment sys/resource.h
1552 @comment BSD
1553 @item PRIO_USER
1554 @vindex PRIO_USER
1555 Read or set the priority of one user's processes.  The argument @var{id}
1556 is a user ID.
1557 @end table
1558
1559 If the argument @var{id} is 0, it stands for the current process,
1560 current process group, or the current user, according to @var{class}.
1561
1562 @c ??? I don't know where we should say this comes from.
1563 @comment Unix
1564 @comment dunno.h
1565 @deftypefun int nice (int @var{increment})
1566 Increment the priority of the current process by @var{increment}.
1567 The return value is the same as for @code{setpriority}.
1568
1569 Here is an equivalent definition for @code{nice}:
1570
1571 @smallexample
1572 int
1573 nice (int increment)
1574 @{
1575   int old = getpriority (PRIO_PROCESS, 0);
1576   return setpriority (PRIO_PROCESS, 0, old + increment);
1577 @}
1578 @end smallexample
1579 @end deftypefun