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