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