1 @node Date and Time, Non-Local Exits, Arithmetic, Top
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.
8 The time functions fall into three main categories:
12 Functions for measuring elapsed CPU time are discussed in @ref{Processor
16 Functions for measuring absolute clock or calendar time are discussed in
20 Functions for setting alarms and timers are discussed in @ref{Setting
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.
35 @section Processor Time
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.
46 @cindex processor time
49 @cindex time, elapsed CPU
52 * Basic CPU Time:: The @code{clock} function.
53 * Detailed CPU Time:: The @code{times} function.
57 @subsection Basic CPU Time Inquiry
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
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:
76 @dots{} /* @r{Do the work.} */
78 elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
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
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.
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.
104 @deftypevr Macro int CLK_TCK
105 This is an obsolete name for @code{CLOCKS_PER_SEC}.
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.
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)}.
125 @node Detailed CPU Time
126 @subsection Detailed Elapsed CPU Time Inquiry
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.
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:
140 @item clock_t tms_utime
141 This is the CPU time used in executing the instructions of the calling
144 @item clock_t tms_stime
145 This is the CPU time used by the system on behalf of the calling process.
147 @item clock_t tms_cutime
148 This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
149 values of all terminated child processes of the calling process, whose
150 status has been reported to the parent process by @code{wait} or
151 @code{waitpid}; see @ref{Process Completion}. In other words, it
152 represents the total CPU time used in executing the instructions of all
153 the terminated child processes of the calling process, excluding child
154 processes which have not yet been reported by @code{wait} or
157 @item clock_t tms_cstime
158 This is similar to @code{tms_cutime}, but represents the total CPU time
159 used by the system on behalf of all the terminated child processes of the
163 All of the times are given in clock ticks. These are absolute values; in a
164 newly created process, they are all zero. @xref{Creating a Process}.
169 @deftypefun clock_t times (struct tms *@var{buffer})
170 The @code{times} function stores the processor time information for
171 the calling process in @var{buffer}.
173 The return value is the same as the value of @code{clock()}: the elapsed
174 real time relative to an arbitrary base. The base is a constant within a
175 particular process, and typically represents the time since system
176 start-up. A value of @code{(clock_t)(-1)} is returned to indicate failure.
179 @strong{Portability Note:} The @code{clock} function described in
180 @ref{Basic CPU Time}, is specified by the @w{ISO C} standard. The
181 @code{times} function is a feature of POSIX.1. In the GNU system, the
182 value returned by the @code{clock} function is equivalent to the sum of
183 the @code{tms_utime} and @code{tms_stime} fields returned by
187 @section Calendar Time
189 This section describes facilities for keeping track of dates and times
190 according to the Gregorian calendar.
191 @cindex Gregorian calendar
192 @cindex time, calendar
193 @cindex date and time
195 There are three representations for date and time information:
199 @dfn{Calendar time} (the @code{time_t} data type) is a compact
200 representation, typically giving the number of seconds elapsed since
201 some implementation-specific base time.
202 @cindex calendar time
205 There is also a @dfn{high-resolution time} representation (the @code{struct
206 timeval} data type) that includes fractions of a second. Use this time
207 representation instead of ordinary calendar time when you need greater
209 @cindex high-resolution time
212 @dfn{Local time} or @dfn{broken-down time} (the @code{struct
213 tm} data type) represents the date and time as a set of components
214 specifying the year, month, and so on, for a specific time zone.
215 This time representation is usually used in conjunction with formatting
216 date and time values.
218 @cindex broken-down time
222 * Simple Calendar Time:: Facilities for manipulating calendar time.
223 * High-Resolution Calendar:: A time representation with greater precision.
224 * Broken-down Time:: Facilities for manipulating local time.
225 * Formatting Date and Time:: Converting times to strings.
226 * TZ Variable:: How users specify the time zone.
227 * Time Zone Functions:: Functions to examine or specify the time zone.
228 * Time Functions Example:: An example program showing use of some of
232 @node Simple Calendar Time
233 @subsection Simple Calendar Time
235 This section describes the @code{time_t} data type for representing
236 calendar time, and the functions which operate on calendar time objects.
237 These facilities are declared in the header file @file{time.h}.
243 @deftp {Data Type} time_t
244 This is the data type used to represent calendar time.
245 When interpreted as an absolute time
246 value, it represents the number of seconds elapsed since 00:00:00 on
247 January 1, 1970, Coordinated Universal Time. (This date is sometimes
248 referred to as the @dfn{epoch}.) POSIX requires that this count
249 ignore leap seconds, but on some hosts this count includes leap seconds
250 if you set @code{TZ} to certain values (@pxref{TZ Variable}).
252 In the GNU C library, @code{time_t} is equivalent to @code{long int}.
253 In other systems, @code{time_t} might be either an integer or
259 @deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
260 The @code{difftime} function returns the number of seconds elapsed
261 between time @var{time1} and time @var{time0}, as a value of type
262 @code{double}. The difference ignores leap seconds unless leap
263 second support is enabled.
265 In the GNU system, you can simply subtract @code{time_t} values. But on
266 other systems, the @code{time_t} data type might use some other encoding
267 where subtraction doesn't work directly.
272 @deftypefun time_t time (time_t *@var{result})
273 The @code{time} function returns the current time as a value of type
274 @code{time_t}. If the argument @var{result} is not a null pointer, the
275 time value is also stored in @code{*@var{result}}. If the calendar
276 time is not available, the value @w{@code{(time_t)(-1)}} is returned.
280 @node High-Resolution Calendar
281 @subsection High-Resolution Calendar
283 The @code{time_t} data type used to represent calendar times has a
284 resolution of only one second. Some applications need more precision.
286 So, the GNU C library also contains functions which are capable of
287 representing calendar times to a higher resolution than one second. The
288 functions and the associated data types described in this section are
289 declared in @file{sys/time.h}.
294 @deftp {Data Type} {struct timeval}
295 The @code{struct timeval} structure represents a calendar time. It
296 has the following members:
299 @item long int tv_sec
300 This represents the number of seconds since the epoch. It is equivalent
301 to a normal @code{time_t} value.
303 @item long int tv_usec
304 This is the fractional second value, represented as the number of
307 Some times struct timeval values are used for time intervals. Then the
308 @code{tv_sec} member is the number of seconds in the interval, and
309 @code{tv_usec} is the number of additional microseconds.
315 @deftp {Data Type} {struct timezone}
316 The @code{struct timezone} structure is used to hold minimal information
317 about the local time zone. It has the following members:
320 @item int tz_minuteswest
321 This is the number of minutes west of UTC.
324 If nonzero, daylight saving time applies during some part of the year.
327 The @code{struct timezone} type is obsolete and should never be used.
328 Instead, use the facilities described in @ref{Time Zone Functions}.
331 It is often necessary to subtract two values of type @w{@code{struct
332 timeval}}. Here is the best way to do this. It works even on some
333 peculiar operating systems where the @code{tv_sec} member has an
337 /* @r{Subtract the `struct timeval' values X and Y,}
338 @r{storing the result in RESULT.}
339 @r{Return 1 if the difference is negative, otherwise 0.} */
342 timeval_subtract (result, x, y)
343 struct timeval *result, *x, *y;
345 /* @r{Perform the carry for the later subtraction by updating @var{y}.} */
346 if (x->tv_usec < y->tv_usec) @{
347 int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
348 y->tv_usec -= 1000000 * nsec;
351 if (x->tv_usec - y->tv_usec > 1000000) @{
352 int nsec = (y->tv_usec - x->tv_usec) / 1000000;
353 y->tv_usec += 1000000 * nsec;
357 /* @r{Compute the time remaining to wait.}
358 @r{@code{tv_usec} is certainly positive.} */
359 result->tv_sec = x->tv_sec - y->tv_sec;
360 result->tv_usec = x->tv_usec - y->tv_usec;
362 /* @r{Return 1 if result is negative.} */
363 return x->tv_sec < y->tv_sec;
369 @deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
370 The @code{gettimeofday} function returns the current date and time in the
371 @code{struct timeval} structure indicated by @var{tp}. Information about the
372 time zone is returned in the structure pointed at @var{tzp}. If the @var{tzp}
373 argument is a null pointer, time zone information is ignored.
375 The return value is @code{0} on success and @code{-1} on failure. The
376 following @code{errno} error condition is defined for this function:
380 The operating system does not support getting time zone information, and
381 @var{tzp} is not a null pointer. The GNU operating system does not
382 support using @w{@code{struct timezone}} to represent time zone
383 information; that is an obsolete feature of 4.3 BSD.
384 Instead, use the facilities described in @ref{Time Zone Functions}.
390 @deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
391 The @code{settimeofday} function sets the current date and time
392 according to the arguments. As for @code{gettimeofday}, time zone
393 information is ignored if @var{tzp} is a null pointer.
395 You must be a privileged user in order to use @code{settimeofday}.
397 The return value is @code{0} on success and @code{-1} on failure. The
398 following @code{errno} error conditions are defined for this function:
402 This process cannot set the time because it is not privileged.
405 The operating system does not support setting time zone information, and
406 @var{tzp} is not a null pointer.
412 @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
413 This function speeds up or slows down the system clock in order to make
414 gradual adjustments in the current time. This ensures that the time
415 reported by the system clock is always monotonically increasing, which
416 might not happen if you simply set the current time.
418 The @var{delta} argument specifies a relative adjustment to be made to
419 the current time. If negative, the system clock is slowed down for a
420 while until it has lost this much time. If positive, the system clock
421 is speeded up for a while.
423 If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
424 function returns information about any previous time adjustment that
425 has not yet completed.
427 This function is typically used to synchronize the clocks of computers
428 in a local network. You must be a privileged user to use it.
429 The return value is @code{0} on success and @code{-1} on failure. The
430 following @code{errno} error condition is defined for this function:
434 You do not have privilege to set the time.
438 @strong{Portability Note:} The @code{gettimeofday}, @code{settimeofday},
439 and @code{adjtime} functions are derived from BSD.
442 @node Broken-down Time
443 @subsection Broken-down Time
444 @cindex broken-down time
445 @cindex calendar time and broken-down time
447 Calendar time is represented as a number of seconds. This is convenient
448 for calculation, but has no resemblance to the way people normally
449 represent dates and times. By contrast, @dfn{broken-down time} is a binary
450 representation separated into year, month, day, and so on. Broken down
451 time values are not useful for calculations, but they are useful for
452 printing human readable time.
454 A broken-down time value is always relative to a choice of local time
455 zone, and it also indicates which time zone was used.
457 The symbols in this section are declared in the header file @file{time.h}.
461 @deftp {Data Type} {struct tm}
462 This is the data type used to represent a broken-down time. The structure
463 contains at least the following members, which can appear in any order:
467 This is the number of seconds after the minute, normally in the range
468 @code{0} through @code{59}. (The actual upper limit is @code{60}, to allow
469 for leap seconds if leap second support is available.)
473 This is the number of minutes after the hour, in the range @code{0} through
477 This is the number of hours past midnight, in the range @code{0} through
481 This is the day of the month, in the range @code{1} through @code{31}.
484 This is the number of months since January, in the range @code{0} through
488 This is the number of years since @code{1900}.
491 This is the number of days since Sunday, in the range @code{0} through
495 This is the number of days since January 1, in the range @code{0} through
499 @cindex Daylight Saving Time
501 This is a flag that indicates whether Daylight Saving Time is (or was, or
502 will be) in effect at the time described. The value is positive if
503 Daylight Saving Time is in effect, zero if it is not, and negative if the
504 information is not available.
506 @item long int tm_gmtoff
507 This field describes the time zone that was used to compute this
508 broken-down time value, including any adjustment for daylight saving; it
509 is the number of seconds that you must add to UTC to get local time.
510 You can also think of this as the number of seconds east of UTC. For
511 example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}.
512 The @code{tm_gmtoff} field is derived from BSD and is a GNU library
513 extension; it is not visible in a strict @w{ISO C} environment.
515 @item const char *tm_zone
516 This field is the name for the time zone that was used to compute this
517 broken-down time value. Like @code{tm_gmtoff}, this field is a BSD and
518 GNU extension, and is not visible in a strict @w{ISO C} environment.
524 @deftypefun {struct tm *} localtime (const time_t *@var{time})
525 The @code{localtime} function converts the calendar time pointed to by
526 @var{time} to broken-down time representation, expressed relative to the
527 user's specified time zone.
529 The return value is a pointer to a static broken-down time structure, which
530 might be overwritten by subsequent calls to @code{ctime}, @code{gmtime},
531 or @code{localtime}. (But no other library function overwrites the contents
534 Calling @code{localtime} has one other effect: it sets the variable
535 @code{tzname} with information about the current time zone. @xref{Time
541 @deftypefun {struct tm *} gmtime (const time_t *@var{time})
542 This function is similar to @code{localtime}, except that the broken-down
543 time is expressed as Coordinated Universal Time (UTC)---that is, as
544 Greenwich Mean Time (GMT)---rather than relative to the local time zone.
546 Recall that calendar times are @emph{always} expressed in coordinated
552 @deftypefun time_t mktime (struct tm *@var{brokentime})
553 The @code{mktime} function is used to convert a broken-down time structure
554 to a calendar time representation. It also ``normalizes'' the contents of
555 the broken-down time structure, by filling in the day of week and day of
556 year based on the other date and time components.
558 The @code{mktime} function ignores the specified contents of the
559 @code{tm_wday} and @code{tm_yday} members of the broken-down time
560 structure. It uses the values of the other components to compute the
561 calendar time; it's permissible for these components to have
562 unnormalized values outside of their normal ranges. The last thing that
563 @code{mktime} does is adjust the components of the @var{brokentime}
564 structure (including the @code{tm_wday} and @code{tm_yday}).
566 If the specified broken-down time cannot be represented as a calendar time,
567 @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
568 the contents of @var{brokentime}.
570 Calling @code{mktime} also sets the variable @code{tzname} with
571 information about the current time zone. @xref{Time Zone Functions}.
574 @node Formatting Date and Time
575 @subsection Formatting Date and Time
577 The functions described in this section format time values as strings.
578 These functions are declared in the header file @file{time.h}.
583 @deftypefun {char *} asctime (const struct tm *@var{brokentime})
584 The @code{asctime} function converts the broken-down time value that
585 @var{brokentime} points to into a string in a standard format:
588 "Tue May 21 13:46:22 1991\n"
591 The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
592 @samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
594 The abbreviations for the months are: @samp{Jan}, @samp{Feb},
595 @samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
596 @samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
598 The return value points to a statically allocated string, which might be
599 overwritten by subsequent calls to @code{asctime} or @code{ctime}.
600 (But no other library function overwrites the contents of this
606 @deftypefun {char *} ctime (const time_t *@var{time})
607 The @code{ctime} function is similar to @code{asctime}, except that the
608 time value is specified as a @code{time_t} calendar time value rather
609 than in broken-down local time format. It is equivalent to
612 asctime (localtime (@var{time}))
615 @code{ctime} sets the variable @code{tzname}, because @code{localtime}
616 does so. @xref{Time Zone Functions}.
622 @deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
623 This function is similar to the @code{sprintf} function (@pxref{Formatted
624 Input}), but the conversion specifications that can appear in the format
625 template @var{template} are specialized for printing components of the date
626 and time @var{brokentime} according to the locale currently specified for
627 time conversion (@pxref{Locales}).
629 Ordinary characters appearing in the @var{template} are copied to the
630 output string @var{s}; this can include multibyte character sequences.
631 Conversion specifiers are introduced by a @samp{%} character, followed
632 by an optional flag which can be one of the following. These flags,
633 which are GNU extensions, affect only the output of numbers:
637 The number is padded with spaces.
640 The number is not padded at all.
643 The number is padded with zeros even if the format spefies padding
647 The default action is to pad the number with zeros to keep it a constant
648 width. Numbers that do not have a range indicated below are never
649 padded, since there is no natural width for them.
651 Following the flag an optional specification of the width is possible.
652 This is specified in decimal notation. If the natural size of the
653 output is of the field has less than the specifed number of character,
654 the result is written right adjusted and space padded to the given
657 An optional modifier can follow the optional flag and width
658 specification. The modifiers, which are POSIX.2 extensions, are:
662 Use the locale's alternate representation for date and time. This
663 modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X},
664 @code{%y} and @code{%Y} format specifiers. In a Japanese locale, for
665 example, @code{%Ex} might yield a date format based on the Japanese
669 Use the locale's alternate numeric symbols for numbers. This modifier
670 applies only to numeric format specifiers.
673 If the format supports the modifier but no alternate representation
674 is available, it is ignored.
676 The conversion specifier ends with a format specifier taken from the
677 following list. The whole @samp{%} sequence is replaced in the output
682 The abbreviated weekday name according to the current locale.
685 The full weekday name according to the current locale.
688 The abbreviated month name according to the current locale.
691 The full month name according to the current locale.
694 The preferred date and time representation for the current locale.
697 The century of the year. This is equivalent to the greatest integer not
698 greater than the year divided by 100.
700 This format is a POSIX.2 extension.
703 The day of the month as a decimal number (range @code{01} through @code{31}).
706 The date using the format @code{%m/%d/%y}.
708 This format is a POSIX.2 extension.
711 The day of the month like with @code{%d}, but padded with blank (range
712 @code{ 1} through @code{31}).
714 This format is a POSIX.2 extension.
717 The year corresponding to the ISO week number, but without the century
718 (range @code{00} through @code{99}). This has the same format and value
719 as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
720 to the previous or next year, that year is used instead.
722 This format is a GNU extension.
725 The year corresponding to the ISO week number. This has the same format
726 and value as @code{%Y}, except that if the ISO week number (see
727 @code{%V}) belongs to the previous or next year, that year is used
730 This format is a GNU extension.
733 The abbreviated month name according to the current locale. The action
734 is the same as for @code{%b}.
736 This format is a POSIX.2 extension.
739 The hour as a decimal number, using a 24-hour clock (range @code{00} through
743 The hour as a decimal number, using a 12-hour clock (range @code{01} through
747 The day of the year as a decimal number (range @code{001} through @code{366}).
750 The hour as a decimal number, using a 24-hour clock like @code{%H}, but
751 padded with blank (range @code{ 0} through @code{23}).
753 This format is a GNU extension.
756 The hour as a decimal number, using a 12-hour clock like @code{%I}, but
757 padded with blank (range @code{ 1} through @code{12}).
759 This format is a GNU extension.
762 The month as a decimal number (range @code{01} through @code{12}).
765 The minute as a decimal number (range @code{00} through @code{59}).
768 A single @samp{\n} (newline) character.
770 This format is a POSIX.2 extension.
773 Either @samp{AM} or @samp{PM}, according to the given time value; or the
774 corresponding strings for the current locale. Noon is treated as
775 @samp{PM} and midnight as @samp{AM}.
778 The complete time using the AM/PM format of the current locale.
780 This format is a POSIX.2 extension.
783 The hour and minute in decimal numbers using the format @code{%H:%M}.
785 This format is a GNU extension.
788 The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
789 Leap seconds are not counted unless leap second support is available.
791 This format is a GNU extension.
794 The second as a decimal number (range @code{00} through @code{60}).
797 A single @samp{\t} (tabulator) character.
799 This format is a POSIX.2 extension.
802 The time using decimal numbers using the format @code{%H:%M:%S}.
804 This format is a POSIX.2 extension.
807 The day of the week as a decimal number (range @code{1} through
808 @code{7}), Monday being @code{1}.
810 This format is a POSIX.2 extension.
813 The week number of the current year as a decimal number (range @code{00}
814 through @code{53}), starting with the first Sunday as the first day of
815 the first week. Days preceding the first Sunday in the year are
816 considered to be in week @code{00}.
819 The @w{ISO 8601:1988} week number as a decimal number (range @code{01}
820 through @code{53}). ISO weeks start with Monday and end with Sunday.
821 Week @code{01} of a year is the first week which has the majority of its
822 days in that year; this is equivalent to the week containing the year's
823 first Thursday, and it is also equivalent to the week containing January
824 4. Week @code{01} of a year can contain days from the previous year.
825 The week before week @code{01} of a year is the last week (@code{52} or
826 @code{53}) of the previous year even if it contains days from the new
829 This format is a POSIX.2 extension.
832 The day of the week as a decimal number (range @code{0} through
833 @code{6}), Sunday being @code{0}.
836 The week number of the current year as a decimal number (range @code{00}
837 through @code{53}), starting with the first Monday as the first day of
838 the first week. All days preceding the first Monday in the year are
839 considered to be in week @code{00}.
842 The preferred date representation for the current locale, but without the
846 The preferred time representation for the current locale, but with no date.
849 The year without a century as a decimal number (range @code{00} through
850 @code{99}). This is equivalent to the year modulo 100.
853 The year as a decimal number, using the Gregorian calendar. Years
854 before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
857 @w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
858 @code{-0600} or @code{+0100}), or nothing if no time zone is
861 This format is a GNU extension.
864 The time zone abbreviation (empty if the time zone can't be determined).
867 A literal @samp{%} character.
870 The @var{size} parameter can be used to specify the maximum number of
871 characters to be stored in the array @var{s}, including the terminating
872 null character. If the formatted time requires more than @var{size}
873 characters, the excess characters are discarded. The return value from
874 @code{strftime} is the number of characters placed in the array @var{s},
875 not including the terminating null character. If the value equals
876 @var{size}, it means that the array @var{s} was too small; you should
877 repeat the call, providing a bigger array.
879 If @var{s} is a null pointer, @code{strftime} does not actually write
880 anything, but instead returns the number of characters it would have written.
882 According to POSIX.1 every call to @code{strftime} implies a call to
883 @code{tzset}. So the contents of the environment variable @code{TZ}
884 is examined before any output is produced.
886 For an example of @code{strftime}, see @ref{Time Functions Example}.
890 @subsection Specifying the Time Zone with @code{TZ}
892 In POSIX systems, a user can specify the time zone by means of the
893 @code{TZ} environment variable. For information about how to set
894 environment variables, see @ref{Environment Variables}. The functions
895 for accessing the time zone are declared in @file{time.h}.
899 You should not normally need to set @code{TZ}. If the system is
900 configured properly, the default time zone will be correct. You might
901 set @code{TZ} if you are using a computer over the network from a
902 different time zone, and would like times reported to you in the time zone
903 that local for you, rather than what is local for the computer.
905 In POSIX.1 systems the value of the @code{TZ} variable can be of one of
906 three formats. With the GNU C library, the most common format is the
907 last one, which can specify a selection from a large database of time
908 zone information for many regions of the world. The first two formats
909 are used to describe the time zone information directly, which is both
910 more cumbersome and less precise. But the POSIX.1 standard only
911 specifies the details of the first two formats, so it is good to be
912 familiar with them in case you come across a POSIX.1 system that doesn't
913 support a time zone information database.
915 The first format is used when there is no Daylight Saving Time (or
916 summer time) in the local time zone:
919 @r{@var{std} @var{offset}}
922 The @var{std} string specifies the name of the time zone. It must be
923 three or more characters long and must not contain a leading colon or
924 embedded digits, commas, or plus or minus signs. There is no space
925 character separating the time zone name from the @var{offset}, so these
926 restrictions are necessary to parse the specification correctly.
928 The @var{offset} specifies the time value one must add to the local time
929 to get a Coordinated Universal Time value. It has syntax like
930 [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This
931 is positive if the local time zone is west of the Prime Meridian and
932 negative if it is east. The hour must be between @code{0} and
933 @code{23}, and the minute and seconds between @code{0} and @code{59}.
935 For example, here is how we would specify Eastern Standard Time, but
936 without any daylight saving time alternative:
942 The second format is used when there is Daylight Saving Time:
945 @r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
948 The initial @var{std} and @var{offset} specify the standard time zone, as
949 described above. The @var{dst} string and @var{offset} specify the name
950 and offset for the corresponding daylight saving time time zone; if the
951 @var{offset} is omitted, it defaults to one hour ahead of standard time.
953 The remainder of the specification describes when daylight saving time is
954 in effect. The @var{start} field is when daylight saving time goes into
955 effect and the @var{end} field is when the change is made back to standard
956 time. The following formats are recognized for these fields:
960 This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
961 February 29 is never counted, even in leap years.
964 This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
965 February 29 is counted in leap years.
967 @item M@var{m}.@var{w}.@var{d}
968 This specifies day @var{d} of week @var{w} of month @var{m}. The day
969 @var{d} must be between @code{0} (Sunday) and @code{6}. The week
970 @var{w} must be between @code{1} and @code{5}; week @code{1} is the
971 first week in which day @var{d} occurs, and week @code{5} specifies the
972 @emph{last} @var{d} day in the month. The month @var{m} should be
973 between @code{1} and @code{12}.
976 The @var{time} fields specify when, in the local time currently in
977 effect, the change to the other time occurs. If omitted, the default is
980 For example, here is how one would specify the Eastern time zone in the
981 United States, including the appropriate daylight saving time and its dates
982 of applicability. The normal offset from UTC is 5 hours; since this is
983 west of the prime meridian, the sign is positive. Summer time begins on
984 the first Sunday in April at 2:00am, and ends on the last Sunday in October
988 EST+5EDT,M4.1.0/2,M10.5.0/2
991 The schedule of daylight saving time in any particular jurisdiction has
992 changed over the years. To be strictly correct, the conversion of dates
993 and times in the past should be based on the schedule that was in effect
994 then. However, this format has no facilities to let you specify how the
995 schedule has changed from year to year. The most you can do is specify
996 one particular schedule---usually the present day schedule---and this is
997 used to convert any date, no matter when. For precise time zone
998 specifications, it is best to use the time zone information database
1001 The third format looks like this:
1007 Each operating system interprets this format differently; in the GNU C
1008 library, @var{characters} is the name of a file which describes the time
1011 @pindex /etc/localtime
1013 If the @code{TZ} environment variable does not have a value, the
1014 operation chooses a time zone by default. In the GNU C library, the
1015 default time zone is like the specification @samp{TZ=:/etc/localtime}
1016 (or @samp{TZ=:/usr/local/etc/localtime}, depending on how GNU C library
1017 was configured; @pxref{Installation}). Other C libraries use their own
1018 rule for choosing the default time zone, so there is little we can say
1021 @cindex time zone database
1022 @pindex /share/lib/zoneinfo
1024 If @var{characters} begins with a slash, it is an absolute file name;
1025 otherwise the library looks for the file
1026 @w{@file{/share/lib/zoneinfo/@var{characters}}}. The @file{zoneinfo}
1027 directory contains data files describing local time zones in many
1028 different parts of the world. The names represent major cities, with
1029 subdirectories for geographical areas; for example,
1030 @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
1031 These data files are installed by the system administrator, who also
1032 sets @file{/etc/localtime} to point to the data file for the local time
1033 zone. The GNU C library comes with a large database of time zone
1034 information for most regions of the world, which is maintained by a
1035 community of volunteers and put in the public domain.
1037 @node Time Zone Functions
1038 @subsection Functions and Variables for Time Zones
1042 @deftypevar {char *} tzname [2]
1043 The array @code{tzname} contains two strings, which are the standard
1044 names of the pair of time zones (standard and daylight
1045 saving) that the user has selected. @code{tzname[0]} is the name of
1046 the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
1047 is the name for the time zone when daylight saving time is in use (for
1048 example, @code{"EDT"}). These correspond to the @var{std} and @var{dst}
1049 strings (respectively) from the @code{TZ} environment variable. If
1050 daylight saving time is never used, @code{tzname[1]} is the empty string.
1052 The @code{tzname} array is initialized from the @code{TZ} environment
1053 variable whenever @code{tzset}, @code{ctime}, @code{strftime},
1054 @code{mktime}, or @code{localtime} is called. If multiple abbreviations
1055 have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War
1056 Time and Eastern Daylight Time), the array contains the most recent
1059 The @code{tzname} array is required for POSIX.1 compatibility, but in
1060 GNU programs it is better to use the @code{tm_zone} member of the
1061 broken-down time structure, since @code{tm_zone} reports the correct
1062 abbreviation even when it is not the latest one.
1068 @deftypefun void tzset (void)
1069 The @code{tzset} function initializes the @code{tzname} variable from
1070 the value of the @code{TZ} environment variable. It is not usually
1071 necessary for your program to call this function, because it is called
1072 automatically when you use the other time conversion functions that
1073 depend on the time zone.
1076 The following variables are defined for compatibility with System V
1077 Unix. Like @code{tzname}, these variables are set by calling
1078 @code{tzset} or the other time conversion functions.
1082 @deftypevar {long int} timezone
1083 This contains the difference between UTC and the latest local standard
1084 time, in seconds west of UTC. For example, in the U.S. Eastern time
1085 zone, the value is @code{5*60*60}. Unlike the @code{tm_gmtoff} member
1086 of the broken-down time structure, this value is not adjusted for
1087 daylight saving, and its sign is reversed. In GNU programs it is better
1088 to use @code{tm_gmtoff}, since it contains the correct offset even when
1089 it is not the latest one.
1094 @deftypevar int daylight
1095 This variable has a nonzero value if daylight savings time rules apply.
1096 A nonzero value does not necessarily mean that daylight savings time is
1097 now in effect; it means only that daylight savings time is sometimes in
1101 @node Time Functions Example
1102 @subsection Time Functions Example
1104 Here is an example program showing the use of some of the local time and
1105 calendar time functions.
1108 @include strftim.c.texi
1111 It produces output like this:
1114 Wed Jul 31 13:02:36 1991
1115 Today is Wednesday, July 31.
1116 The time is 01:02 PM.
1120 @node Setting an Alarm
1121 @section Setting an Alarm
1123 The @code{alarm} and @code{setitimer} functions provide a mechanism for a
1124 process to interrupt itself at some future time. They do this by setting a
1125 timer; when the timer expires, the process receives a signal.
1127 @cindex setting an alarm
1128 @cindex interval timer, setting
1129 @cindex alarms, setting
1130 @cindex timers, setting
1131 Each process has three independent interval timers available:
1135 A real-time timer that counts clock time. This timer sends a
1136 @code{SIGALRM} signal to the process when it expires.
1137 @cindex real-time timer
1138 @cindex timer, real-time
1141 A virtual timer that counts CPU time used by the process. This timer
1142 sends a @code{SIGVTALRM} signal to the process when it expires.
1143 @cindex virtual timer
1144 @cindex timer, virtual
1147 A profiling timer that counts both CPU time used by the process, and CPU
1148 time spent in system calls on behalf of the process. This timer sends a
1149 @code{SIGPROF} signal to the process when it expires.
1150 @cindex profiling timer
1151 @cindex timer, profiling
1153 This timer is useful for profiling in interpreters. The interval timer
1154 mechanism does not have the fine granularity necessary for profiling
1156 @c @xref{profil} !!!
1159 You can only have one timer of each kind set at any given time. If you
1160 set a timer that has not yet expired, that timer is simply reset to the
1163 You should establish a handler for the appropriate alarm signal using
1164 @code{signal} or @code{sigaction} before issuing a call to @code{setitimer}
1165 or @code{alarm}. Otherwise, an unusual chain of events could cause the
1166 timer to expire before your program establishes the handler, and in that
1167 case it would be terminated, since that is the default action for the alarm
1168 signals. @xref{Signal Handling}.
1170 The @code{setitimer} function is the primary means for setting an alarm.
1171 This facility is declared in the header file @file{sys/time.h}. The
1172 @code{alarm} function, declared in @file{unistd.h}, provides a somewhat
1173 simpler interface for setting the real-time timer.
1179 @deftp {Data Type} {struct itimerval}
1180 This structure is used to specify when a timer should expire. It contains
1181 the following members:
1183 @item struct timeval it_interval
1184 This is the interval between successive timer interrupts. If zero, the
1185 alarm will only be sent once.
1187 @item struct timeval it_value
1188 This is the interval to the first timer interrupt. If zero, the alarm is
1192 The @code{struct timeval} data type is described in @ref{High-Resolution
1198 @deftypefun int setitimer (int @var{which}, struct itimerval *@var{new}, struct itimerval *@var{old})
1199 The @code{setitimer} function sets the timer specified by @var{which}
1200 according to @var{new}. The @var{which} argument can have a value of
1201 @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
1203 If @var{old} is not a null pointer, @code{setitimer} returns information
1204 about any previous unexpired timer of the same kind in the structure it
1207 The return value is @code{0} on success and @code{-1} on failure. The
1208 following @code{errno} error conditions are defined for this function:
1212 The timer interval was too large.
1218 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
1219 The @code{getitimer} function stores information about the timer specified
1220 by @var{which} in the structure pointed at by @var{old}.
1222 The return value and error conditions are the same as for @code{setitimer}.
1230 This constant can be used as the @var{which} argument to the
1231 @code{setitimer} and @code{getitimer} functions to specify the real-time
1236 @item ITIMER_VIRTUAL
1237 @findex ITIMER_VIRTUAL
1238 This constant can be used as the @var{which} argument to the
1239 @code{setitimer} and @code{getitimer} functions to specify the virtual
1246 This constant can be used as the @var{which} argument to the
1247 @code{setitimer} and @code{getitimer} functions to specify the profiling
1253 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
1254 The @code{alarm} function sets the real-time timer to expire in
1255 @var{seconds} seconds. If you want to cancel any existing alarm, you
1256 can do this by calling @code{alarm} with a @var{seconds} argument of
1259 The return value indicates how many seconds remain before the previous
1260 alarm would have been sent. If there is no previous alarm, @code{alarm}
1264 The @code{alarm} function could be defined in terms of @code{setitimer}
1269 alarm (unsigned int seconds)
1271 struct itimerval old, new;
1272 new.it_interval.tv_usec = 0;
1273 new.it_interval.tv_sec = 0;
1274 new.it_value.tv_usec = 0;
1275 new.it_value.tv_sec = (long int) seconds;
1276 if (setitimer (ITIMER_REAL, &new, &old) < 0)
1279 return old.it_value.tv_sec;
1283 There is an example showing the use of the @code{alarm} function in
1284 @ref{Handler Returns}.
1286 If you simply want your process to wait for a given number of seconds,
1287 you should use the @code{sleep} function. @xref{Sleeping}.
1289 You shouldn't count on the signal arriving precisely when the timer
1290 expires. In a multiprocessing environment there is typically some
1291 amount of delay involved.
1293 @strong{Portability Note:} The @code{setitimer} and @code{getitimer}
1294 functions are derived from BSD Unix, while the @code{alarm} function is
1295 specified by the POSIX.1 standard. @code{setitimer} is more powerful than
1296 @code{alarm}, but @code{alarm} is more widely used.
1301 The function @code{sleep} gives a simple way to make the program wait
1302 for short periods of time. If your program doesn't use signals (except
1303 to terminate), then you can expect @code{sleep} to wait reliably for
1304 the specified amount of time. Otherwise, @code{sleep} can return sooner
1305 if a signal arrives; if you want to wait for a given period regardless
1306 of signals, use @code{select} (@pxref{Waiting for I/O}) and don't
1307 specify any descriptors to wait for.
1308 @c !!! select can get EINTR; using SA_RESTART makes sleep win too.
1312 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
1313 The @code{sleep} function waits for @var{seconds} or until a signal
1314 is delivered, whichever happens first.
1316 If @code{sleep} function returns because the requested time has
1317 elapsed, it returns a value of zero. If it returns because of delivery
1318 of a signal, its return value is the remaining time in the sleep period.
1320 The @code{sleep} function is declared in @file{unistd.h}.
1323 Resist the temptation to implement a sleep for a fixed amount of time by
1324 using the return value of @code{sleep}, when nonzero, to call
1325 @code{sleep} again. This will work with a certain amount of accuracy as
1326 long as signals arrive infrequently. But each signal can cause the
1327 eventual wakeup time to be off by an additional second or so. Suppose a
1328 few signals happen to arrive in rapid succession by bad luck---there is
1329 no limit on how much this could shorten or lengthen the wait.
1331 Instead, compute the time at which the program should stop waiting, and
1332 keep trying to wait until that time. This won't be off by more than a
1333 second. With just a little more work, you can use @code{select} and
1334 make the waiting period quite accurate. (Of course, heavy system load
1335 can cause unavoidable additional delays---unless the machine is
1336 dedicated to one application, there is no way you can avoid this.)
1338 On some systems, @code{sleep} can do strange things if your program uses
1339 @code{SIGALRM} explicitly. Even if @code{SIGALRM} signals are being
1340 ignored or blocked when @code{sleep} is called, @code{sleep} might
1341 return prematurely on delivery of a @code{SIGALRM} signal. If you have
1342 established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
1343 signal is delivered while the process is sleeping, the action taken
1344 might be just to cause @code{sleep} to return instead of invoking your
1345 handler. And, if @code{sleep} is interrupted by delivery of a signal
1346 whose handler requests an alarm or alters the handling of @code{SIGALRM},
1347 this handler and @code{sleep} will interfere.
1349 On the GNU system, it is safe to use @code{sleep} and @code{SIGALRM} in
1350 the same program, because @code{sleep} does not work by means of
1353 @node Resource Usage
1354 @section Resource Usage
1356 @pindex sys/resource.h
1357 The function @code{getrusage} and the data type @code{struct rusage}
1358 are used for examining the usage figures of a process. They are declared
1359 in @file{sys/resource.h}.
1361 @comment sys/resource.h
1363 @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage})
1364 This function reports the usage totals for processes specified by
1365 @var{processes}, storing the information in @code{*@var{rusage}}.
1367 In most systems, @var{processes} has only two valid values:
1370 @comment sys/resource.h
1373 Just the current process.
1375 @comment sys/resource.h
1377 @item RUSAGE_CHILDREN
1378 All child processes (direct and indirect) that have terminated already.
1381 In the GNU system, you can also inquire about a particular child process
1382 by specifying its process ID.
1384 The return value of @code{getrusage} is zero for success, and @code{-1}
1389 The argument @var{processes} is not valid.
1393 One way of getting usage figures for a particular child process is with
1394 the function @code{wait4}, which returns totals for a child when it
1395 terminates. @xref{BSD Wait Functions}.
1397 @comment sys/resource.h
1399 @deftp {Data Type} {struct rusage}
1400 This data type records a collection usage amounts for various sorts of
1401 resources. It has the following members, and possibly others:
1404 @item struct timeval ru_utime
1405 Time spent executing user instructions.
1407 @item struct timeval ru_stime
1408 Time spent in operating system code on behalf of @var{processes}.
1410 @item long int ru_maxrss
1411 The maximum resident set size used, in kilobytes. That is, the maximum
1412 number of kilobytes that @var{processes} used in real memory simultaneously.
1414 @item long int ru_ixrss
1415 An integral value expressed in kilobytes times ticks of execution, which
1416 indicates the amount of memory used by text that was shared with other
1419 @item long int ru_idrss
1420 An integral value expressed the same way, which is the amount of
1421 unshared memory used in data.
1423 @item long int ru_isrss
1424 An integral value expressed the same way, which is the amount of
1425 unshared memory used in stack space.
1427 @item long int ru_minflt
1428 The number of page faults which were serviced without requiring any I/O.
1430 @item long int ru_majflt
1431 The number of page faults which were serviced by doing I/O.
1433 @item long int ru_nswap
1434 The number of times @var{processes} was swapped entirely out of main memory.
1436 @item long int ru_inblock
1437 The number of times the file system had to read from the disk on behalf
1440 @item long int ru_oublock
1441 The number of times the file system had to write to the disk on behalf
1444 @item long int ru_msgsnd
1445 Number of IPC messages sent.
1447 @item long ru_msgrcv
1448 Number of IPC messages received.
1450 @item long int ru_nsignals
1451 Number of signals received.
1453 @item long int ru_nvcsw
1454 The number of times @var{processes} voluntarily invoked a context switch
1455 (usually to wait for some service).
1457 @item long int ru_nivcsw
1458 The number of times an involuntary context switch took place (because
1459 the time slice expired, or another process of higher priority became
1464 An additional historical function for examining usage figures,
1465 @code{vtimes}, is supported but not documented here. It is declared in
1466 @file{sys/vtimes.h}.
1468 @node Limits on Resources
1469 @section Limiting Resource Usage
1470 @cindex resource limits
1471 @cindex limits on resource usage
1472 @cindex usage limits
1474 You can specify limits for the resource usage of a process. When the
1475 process tries to exceed a limit, it may get a signal, or the system call
1476 by which it tried to do so may fail, depending on the limit. Each
1477 process initially inherits its limit values from its parent, but it can
1478 subsequently change them.
1480 @pindex sys/resource.h
1481 The symbols in this section are defined in @file{sys/resource.h}.
1483 @comment sys/resource.h
1485 @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp})
1486 Read the current value and the maximum value of resource @var{resource}
1487 and store them in @code{*@var{rlp}}.
1489 The return value is @code{0} on success and @code{-1} on failure. The
1490 only possible @code{errno} error condition is @code{EFAULT}.
1493 @comment sys/resource.h
1495 @deftypefun int setrlimit (int @var{resource}, struct rlimit *@var{rlp})
1496 Store the current value and the maximum value of resource @var{resource}
1497 in @code{*@var{rlp}}.
1499 The return value is @code{0} on success and @code{-1} on failure. The
1500 following @code{errno} error condition is possible:
1504 You tried to change the maximum permissible limit value,
1505 but you don't have privileges to do so.
1509 @comment sys/resource.h
1511 @deftp {Data Type} {struct rlimit}
1512 This structure is used with @code{getrlimit} to receive limit values,
1513 and with @code{setrlimit} to specify limit values. It has two fields:
1517 The current value of the limit in question.
1518 This is also called the ``soft limit''.
1522 The maximum permissible value of the limit in question. You cannot set
1523 the current value of the limit to a larger number than this maximum.
1524 Only the super user can change the maximum permissible value.
1525 This is also called the ``hard limit''.
1529 In @code{getrlimit}, the structure is an output; it receives the current
1530 values. In @code{setrlimit}, it specifies the new values.
1533 Here is a list of resources that you can specify a limit for.
1534 Those that are sizes are measured in bytes.
1537 @comment sys/resource.h
1541 The maximum amount of cpu time the process can use. If it runs for
1542 longer than this, it gets a signal: @code{SIGXCPU}. The value is
1543 measured in seconds. @xref{Operation Error Signals}.
1545 @comment sys/resource.h
1548 @vindex RLIMIT_FSIZE
1549 The maximum size of file the process can create. Trying to write a
1550 larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error
1553 @comment sys/resource.h
1557 The maximum size of data memory for the process. If the process tries
1558 to allocate data memory beyond this amount, the allocation function
1561 @comment sys/resource.h
1564 @vindex RLIMIT_STACK
1565 The maximum stack size for the process. If the process tries to extend
1566 its stack past this size, it gets a @code{SIGSEGV} signal.
1567 @xref{Program Error Signals}.
1569 @comment sys/resource.h
1573 The maximum size core file that this process can create. If the process
1574 terminates and would dump a core file larger than this maximum size,
1575 then no core file is created. So setting this limit to zero prevents
1576 core files from ever being created.
1578 @comment sys/resource.h
1582 The maximum amount of physical memory that this process should get.
1583 This parameter is a guide for the system's scheduler and memory
1584 allocator; the system may give the process more memory when there is a
1587 @comment sys/resource.h
1589 @item RLIMIT_MEMLOCK
1590 The maximum amount of memory that can be locked into physical memory (so
1591 it will never be paged out).
1593 @comment sys/resource.h
1596 The maximum number of processes that can be created with the same user ID.
1597 If you have reached the limit for your user ID, @code{fork} will fail
1598 with @code{EAGAIN}. @xref{Creating a Process}.
1600 @comment sys/resource.h
1603 @vindex RLIMIT_NOFILE
1605 @vindex RLIMIT_OFILE
1606 The maximum number of files that the process can open. If it tries to
1607 open more files than this, it gets error code @code{EMFILE}.
1608 @xref{Error Codes}. Not all systems support this limit; GNU does, and
1611 @comment sys/resource.h
1614 @vindex RLIM_NLIMITS
1615 The number of different resource limits. Any valid @var{resource}
1616 operand must be less than @code{RLIM_NLIMITS}.
1619 @comment sys/resource.h
1621 @defvr Constant int RLIM_INFINITY
1622 This constant stands for a value of ``infinity'' when supplied as
1623 the limit value in @code{setrlimit}.
1626 @c ??? Someone want to finish these?
1627 Two historical functions for setting resource limits, @code{ulimit} and
1628 @code{vlimit}, are not documented here. The latter is declared in
1629 @file{sys/vlimit.h} and comes from BSD.
1632 @section Process Priority
1633 @cindex process priority
1634 @cindex priority of a process
1636 @pindex sys/resource.h
1637 When several processes try to run, their respective priorities determine
1638 what share of the CPU each process gets. This section describes how you
1639 can read and set the priority of a process. All these functions and
1640 macros are declared in @file{sys/resource.h}.
1642 The range of valid priority values depends on the operating system, but
1643 typically it runs from @code{-20} to @code{20}. A lower priority value
1644 means the process runs more often. These constants describe the range of
1648 @comment sys/resource.h
1652 The smallest valid priority value.
1654 @comment sys/resource.h
1658 The smallest valid priority value.
1661 @comment sys/resource.h
1663 @deftypefun int getpriority (int @var{class}, int @var{id})
1664 Read the priority of a class of processes; @var{class} and @var{id}
1665 specify which ones (see below). If the processes specified do not all
1666 have the same priority, this returns the smallest value that any of them
1669 The return value is the priority value on success, and @code{-1} on
1670 failure. The following @code{errno} error condition are possible for
1675 The combination of @var{class} and @var{id} does not match any existing
1679 The value of @var{class} is not valid.
1682 When the return value is @code{-1}, it could indicate failure, or it
1683 could be the priority value. The only way to make certain is to set
1684 @code{errno = 0} before calling @code{getpriority}, then use @code{errno
1685 != 0} afterward as the criterion for failure.
1688 @comment sys/resource.h
1690 @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority})
1691 Set the priority of a class of processes to @var{priority}; @var{class}
1692 and @var{id} specify which ones (see below).
1694 The return value is @code{0} on success and @code{-1} on failure. The
1695 following @code{errno} error condition are defined for this function:
1699 The combination of @var{class} and @var{id} does not match any existing
1703 The value of @var{class} is not valid.
1706 You tried to set the priority of some other user's process, and you
1707 don't have privileges for that.
1710 You tried to lower the priority of a process, and you don't have
1711 privileges for that.
1715 The arguments @var{class} and @var{id} together specify a set of
1716 processes you are interested in. These are the possible values for
1720 @comment sys/resource.h
1723 @vindex PRIO_PROCESS
1724 Read or set the priority of one process. The argument @var{id} is a
1727 @comment sys/resource.h
1731 Read or set the priority of one process group. The argument @var{id} is
1734 @comment sys/resource.h
1738 Read or set the priority of one user's processes. The argument @var{id}
1742 If the argument @var{id} is 0, it stands for the current process,
1743 current process group, or the current user, according to @var{class}.
1745 @c ??? I don't know where we should say this comes from.
1748 @deftypefun int nice (int @var{increment})
1749 Increment the priority of the current process by @var{increment}.
1750 The return value is the same as for @code{setpriority}.
1752 Here is an equivalent definition for @code{nice}:
1756 nice (int increment)
1758 int old = getpriority (PRIO_PROCESS, 0);
1759 return setpriority (PRIO_PROCESS, 0, old + increment);