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