@node Date and Time, Non-Local Exits, Arithmetic, Top
+@c %MENU% Functions for getting the date and time and formatting them nicely
@chapter Date and Time
This chapter describes functions for manipulating dates and times,
@menu
* Processor Time:: Measures processor time used by a program.
* Calendar Time:: Manipulation of ``real'' dates and times.
+* Precision Time:: Manipulation and monitoring of high accuracy
+ time.
* Setting an Alarm:: Sending a signal after a specified time.
* Sleeping:: Waiting for a period of time.
* Resource Usage:: Measuring various resources used.
Different computers and operating systems vary wildly in how they keep
track of processor time. It's common for the internal processor clock
-to have a resolution somewhere between hundredths and millionths of a
+to have a resolution somewhere between hundredth and millionth of a
second.
In the GNU system, @code{clock_t} is equivalent to @code{long int} and
such as arithmetic and printing work properly and consistently no matter
what the underlying representation is.
+Note that the clock can wrap around. On a 32bit system with
+@code{CLOCKS_PER_SEC} set to one million this function will return the
+same value approximately every 72 minutes.
+
@comment time.h
@comment ISO
@deftypevr Macro int CLOCKS_PER_SEC
The value of this macro is the number of clock ticks per second measured
-by the @code{clock} function.
+by the @code{clock} function. POSIX requires that this value is one
+million independent of the actual resolution.
@end deftypevr
@comment time.h
* High-Resolution Calendar:: A time representation with greater precision.
* Broken-down Time:: Facilities for manipulating local time.
* Formatting Date and Time:: Converting times to strings.
+* Parsing Date and Time:: Convert textual time and date information back
+ into broken-down time values.
* TZ Variable:: How users specify the time zone.
* Time Zone Functions:: Functions to examine or specify the time zone.
* Time Functions Example:: An example program showing use of some of
This is the number of minutes west of UTC.
@item int tz_dsttime
-If nonzero, daylight saving time applies during some part of the year.
+If nonzero, Daylight Saving Time applies during some part of the year.
@end table
The @code{struct timezone} type is obsolete and should never be used.
y->tv_sec += nsec;
@}
if (x->tv_usec - y->tv_usec > 1000000) @{
- int nsec = (y->tv_usec - x->tv_usec) / 1000000;
+ int nsec = (x->tv_usec - y->tv_usec) / 1000000;
y->tv_usec += 1000000 * nsec;
y->tv_sec -= nsec;
@}
@cindex calendar time and broken-down time
Calendar time is represented as a number of seconds. This is convenient
-for calculation, but has no resemblance to the way people normally
+for calculation, but has no relation to the way people normally
represent dates and times. By contrast, @dfn{broken-down time} is a binary
-representation separated into year, month, day, and so on. Broken down
+representation separated into year, month, day, and so on. Broken-down
time values are not useful for calculations, but they are useful for
printing human readable time.
or @code{localtime}. (But no other library function overwrites the contents
of this object.)
+The return value is the null pointer if @var{time} cannot be represented
+as a broken-down time; typically this is because the year cannot fit into
+an @code{int}.
+
Calling @code{localtime} has one other effect: it sets the variable
@code{tzname} with information about the current time zone. @xref{Time
Zone Functions}.
Using the @code{localtime} function is a big problem in multi-threaded
programs. The result is returned in a static buffer and this is used in
-all threads. POSIX.1c introduced a varient of this function.
+all threads. POSIX.1c introduced a variant of this function.
@comment time.h
@comment POSIX.1c
@end deftypefun
As for the @code{localtime} function we have the problem that the result
-is placed ina static variable. POSIX.1c also provides a replacement for
+is placed in a static variable. POSIX.1c also provides a replacement for
@code{gmtime}.
@comment time.h
@code{tm_wday} and @code{tm_yday} members of the broken-down time
structure. It uses the values of the other components to compute the
calendar time; it's permissible for these components to have
-unnormalized values outside of their normal ranges. The last thing that
+unnormalized values outside their normal ranges. The last thing that
@code{mktime} does is adjust the components of the @var{brokentime}
structure (including the @code{tm_wday} and @code{tm_yday}).
@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer})
This function is similar to @code{asctime} but instead of placing the
result in a static buffer it writes the string in the buffer pointed to
-by the parameter @var{buffer}. This buffer should have at least room
-for 16 bytes.
+by the parameter @var{buffer}. This buffer should have room
+for at least 26 bytes, including the terminating null.
If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns @var{buffer}. Otherwise
@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer})
This function is similar to @code{ctime}, only that it places the result
in the string pointed to by @var{buffer}. It is equivalent to (written
-using gcc extensions, @xref{Statement Exprs,,,gcc,Porting and Using gcc}.):
+using gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}):
@smallexample
(@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @})
@comment time.h
@comment ISO
-@comment POSIX.2
@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
This function is similar to the @code{sprintf} function (@pxref{Formatted
Input}), but the conversion specifications that can appear in the format
The century of the year. This is equivalent to the greatest integer not
greater than the year divided by 100.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %d
The day of the month as a decimal number (range @code{01} through @code{31}).
@item %D
The date using the format @code{%m/%d/%y}.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %e
The day of the month like with @code{%d}, but padded with blank (range
@code{ 1} through @code{31}).
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
+
+@item %F
+The date using the format @code{%Y-%m-%d}. This is the form specified
+in the @w{ISO 8601} standard and is the preferred form for all uses.
+
+This format is a @w{ISO C99} extension.
@item %g
The year corresponding to the ISO week number, but without the century
as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
to the previous or next year, that year is used instead.
-This format is a GNU extension.
+This format was introduced in @w{ISO C99}.
@item %G
The year corresponding to the ISO week number. This has the same format
@code{%V}) belongs to the previous or next year, that year is used
instead.
-This format is a GNU extension.
+This format was introduced in @w{ISO C99} but was previously available
+as a GNU extension.
@item %h
The abbreviated month name according to the current locale. The action
is the same as for @code{%b}.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %H
The hour as a decimal number, using a 24-hour clock (range @code{00} through
@item %n
A single @samp{\n} (newline) character.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %p
Either @samp{AM} or @samp{PM}, according to the given time value; or the
corresponding strings for the current locale, printed in lowercase
characters. Noon is treated as @samp{pm} and midnight as @samp{am}.
-This format is a GNU extension.
+This format was introduced in @w{ISO C99} but was previously available
+as a GNU extension.
@item %r
The complete time using the AM/PM format of the current locale.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %R
The hour and minute in decimal numbers using the format @code{%H:%M}.
-This format is a GNU extension.
+This format was introduced in @w{ISO C99} but was previously available
+as a GNU extension.
@item %s
The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
This format is a GNU extension.
@item %S
-The second as a decimal number (range @code{00} through @code{60}).
+The seconds as a decimal number (range @code{00} through @code{60}).
@item %t
A single @samp{\t} (tabulator) character.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %T
The time using decimal numbers using the format @code{%H:%M:%S}.
The day of the week as a decimal number (range @code{1} through
@code{7}), Monday being @code{1}.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %U
The week number of the current year as a decimal number (range @code{00}
@code{53}) of the previous year even if it contains days from the new
year.
-This format is a POSIX.2 extension.
+This format is a POSIX.2 extension and also appears in @w{ISO C99}.
@item %w
The day of the week as a decimal number (range @code{0} through
@code{-0600} or @code{+0100}), or nothing if no time zone is
determinable.
-This format is a GNU extension.
+This format was introduced in @w{ISO C99} but was previously available
+as a GNU extension.
+
+A full @w{RFC 822} timestamp is generated by the format
+@w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent
+@w{@samp{"%a, %d %b %Y %T %z"}}).
@item %Z
The time zone abbreviation (empty if the time zone can't be determined).
The @var{size} parameter can be used to specify the maximum number of
characters to be stored in the array @var{s}, including the terminating
null character. If the formatted time requires more than @var{size}
-characters, @code{strftime} returns zero and the content of the array
-@var{s} is indetermined. Otherwise the return value indicates the
+characters, @code{strftime} returns zero and the contents of the array
+@var{s} are undefined. Otherwise the return value indicates the
number of characters placed in the array @var{s}, not including the
terminating null character.
For an example of @code{strftime}, see @ref{Time Functions Example}.
@end deftypefun
+@comment time.h
+@comment ISO/Amend1
+@deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime})
+The @code{wcsftime} function is equivalent to the @code{strftime}
+function with the difference that it operates on wide character
+strings. The buffer where the result is stored, pointed to by @var{s},
+must be an array of wide characters. The parameter @var{size} which
+specifies the size of the output buffer gives the number of wide
+character, not the number of bytes.
+
+Also the format string @var{template} is a wide character string. Since
+all characters needed to specify the format string are in the basic
+character set it is portably possible to write format strings in the C
+source code using the @code{L"..."} notation. The parameter
+@var{brokentime} has the same meaning as in the @code{strftime} call.
+
+The @code{wcsftime} function supports the same flags, modifiers, and
+format specifiers as the @code{strftime} function.
+
+The return value of @code{wcsftime} is the number of wide characters
+stored in @code{s}. When more characters would have to be written than
+can be placed in the buffer @var{s} the return value is zero, with the
+same problems indicated in the @code{strftime} documentation.
+@end deftypefun
+
+@node Parsing Date and Time
+@subsection Convert textual time and date information back
+
+The @w{ISO C} standard does not specify any functions which can convert
+the output of the @code{strftime} function back into a binary format.
+This led to a variety of more-or-less successful implementations with
+different interfaces over the years. Then the Unix standard was
+extended by the addition of two functions: @code{strptime} and
+@code{getdate}. Both have strange interfaces but at least they are
+widely available.
+
+@menu
+* Low-Level Time String Parsing:: Interpret string according to given format.
+* General Time String Parsing:: User-friendly function to parse data and
+ time strings.
+@end menu
+
+@node Low-Level Time String Parsing
+@subsubsection Interpret string according to given format
+
+he first function is rather low-level. It is nevertheless frequently
+used in software since it is better known. Its interface and
+implementation are heavily influenced by the @code{getdate} function,
+which is defined and implemented in terms of calls to @code{strptime}.
+
+@comment time.h
+@comment XPG4
+@deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp})
+The @code{strptime} function parses the input string @var{s} according
+to the format string @var{fmt} and stores its results in the
+structure @var{tp}.
+
+The input string could be generated by a @code{strftime} call or
+obtained any other way. It does not need to be in a human-recognizable
+format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even
+though it is ambiguous without context. As long as the format string
+@var{fmt} matches the input string the function will succeed.
+
+The format string consists of the same components as the format string
+of the @code{strftime} function. The only difference is that the flags
+@code{_}, @code{-}, @code{0}, and @code{^} are not allowed.
+@comment Is this really the intention? --drepper
+Several of the distinct formats of @code{strftime} do the same work in
+@code{strptime} since differences like case of the input do not matter.
+For reasons of symmetry all formats are supported, though.
+
+The modifiers @code{E} and @code{O} are also allowed everywhere the
+@code{strftime} function allows them.
+
+The formats are:
+
+@table @code
+@item %a
+@itemx %A
+The weekday name according to the current locale, in abbreviated form or
+the full name.
+
+@item %b
+@itemx %B
+@itemx %h
+The month name according to the current locale, in abbreviated form or
+the full name.
+
+@item %c
+The date and time representation for the current locale.
+
+@item %Ec
+Like @code{%c} but the locale's alternative date and time format is used.
+
+@item %C
+The century of the year.
+
+It makes sense to use this format only if the format string also
+contains the @code{%y} format.
+
+@item %EC
+The locale's representation of the period.
+
+Unlike @code{%C} it sometimes makes sense to use this format since some
+cultures represent years relative to the beginning of eras instead of
+using the Gregorian years.
+
+@item %d
+@item %e
+The day of the month as a decimal number (range @code{1} through @code{31}).
+Leading zeroes are permitted but not required.
+
+@item %Od
+@itemx %Oe
+Same as @code{%d} but using the locale's alternative numeric symbols.
+
+Leading zeroes are permitted but not required.
+
+@item %D
+Equivalent to @code{%m/%d/%y}.
+
+@item %F
+Equivalent to @code{%Y-%m-%d}, which is the @w{ISO 8601} date
+format.
+
+This is a GNU extension following an @w{ISO C99} extension to
+@code{strftime}.
+
+@item %g
+The year corresponding to the ISO week number, but without the century
+(range @code{00} through @code{99}).
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+This format is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %G
+The year corresponding to the ISO week number.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+This format is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %H
+@itemx %k
+The hour as a decimal number, using a 24-hour clock (range @code{00} through
+@code{23}).
+
+@code{%k} is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %OH
+Same as @code{%H} but using the locale's alternative numeric symbols.
+
+@item %I
+@itemx %l
+The hour as a decimal number, using a 12-hour clock (range @code{01} through
+@code{12}).
+
+@code{%l} is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %OI
+Same as @code{%I} but using the locale's alternative numeric symbols.
+
+@item %j
+The day of the year as a decimal number (range @code{1} through @code{366}).
+
+Leading zeroes are permitted but not required.
+
+@item %m
+The month as a decimal number (range @code{1} through @code{12}).
+
+Leading zeroes are permitted but not required.
+
+@item %Om
+Same as @code{%m} but using the locale's alternative numeric symbols.
+
+@item %M
+The minute as a decimal number (range @code{0} through @code{59}).
+
+Leading zeroes are permitted but not required.
+
+@item %OM
+Same as @code{%M} but using the locale's alternative numeric symbols.
+
+@item %n
+@itemx %t
+Matches any white space.
+
+@item %p
+@item %P
+The locale-dependent equivalent to @samp{AM} or @samp{PM}.
+
+This format is not useful unless @code{%I} or @code{%l} is also used.
+Another complication is that the locale might not define these values at
+all and therefore the conversion fails.
+
+@code{%P} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %r
+The complete time using the AM/PM format of the current locale.
+
+A complication is that the locale might not define this format at all
+and therefore the conversion fails.
+
+@item %R
+The hour and minute in decimal numbers using the format @code{%H:%M}.
+
+@code{%R} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %s
+The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
+Leap seconds are not counted unless leap second support is available.
+
+@code{%s} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %S
+The seconds as a decimal number (range @code{0} through @code{61}).
+
+Leading zeroes are permitted but not required.
+
+Note the nonsense with @code{61}, as given in the Unix specification.
+This is a result of a decision to allow double leap seconds. These do
+not in fact exist but the myth persists.
+
+@item %OS
+Same as @code{%S} but using the locale's alternative numeric symbols.
+
+@item %T
+Equivalent to the use of @code{%H:%M:%S} in this place.
+
+@item %u
+The day of the week as a decimal number (range @code{1} through
+@code{7}), Monday being @code{1}.
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %U
+The week number of the current year as a decimal number (range @code{0}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@item %OU
+Same as @code{%U} but using the locale's alternative numeric symbols.
+
+@item %V
+The @w{ISO 8601:1988} week number as a decimal number (range @code{1}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %w
+The day of the week as a decimal number (range @code{0} through
+@code{6}), Sunday being @code{0}.
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %Ow
+Same as @code{%w} but using the locale's alternative numeric symbols.
+
+@item %W
+The week number of the current year as a decimal number (range @code{0}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %OW
+Same as @code{%W} but using the locale's alternative numeric symbols.
+
+@item %x
+The date using the locale's date format.
+
+@item %Ex
+Like @code{%x} but the locale's alternative data representation is used.
+
+@item %X
+The time using the locale's time format.
+
+@item %EX
+Like @code{%X} but the locale's alternative time representation is used.
+
+@item %y
+The year without a century as a decimal number (range @code{0} through
+@code{99}).
+
+Leading zeroes are permitted but not required.
+
+Note that it is questionable to use this format without
+the @code{%C} format. The @code{strptime} function does regard input
+values in the range @math{68} to @math{99} as the years @math{1969} to
+@math{1999} and the values @math{0} to @math{68} as the years
+@math{2000} to @math{2068}. But maybe this heuristic fails for some
+input data.
+
+Therefore it is best to avoid @code{%y} completely and use @code{%Y}
+instead.
+
+@item %Ey
+The offset from @code{%EC} in the locale's alternative representation.
+
+@item %Oy
+The offset of the year (from @code{%C}) using the locale's alternative
+numeric symbols.
+
+@item %Y
+The year as a decimal number, using the Gregorian calendar.
+
+@item %EY
+The full alternative year representation.
+
+@item %z
+Equivalent to the use of @code{%a, %d %b %Y %H:%M:%S %z} in this place.
+This is the full @w{ISO 8601} date and time format.
+
+@item %Z
+The timezone name.
+
+@emph{Note:} Currently, this is not fully implemented. The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %%
+A literal @samp{%} character.
+@end table
+
+All other characters in the format string must have a matching character
+in the input string. Exceptions are white spaces in the input string
+which can match zero or more white space characters in the format string.
+
+The @code{strptime} function processes the input string from right to
+left. Each of the three possible input elements (white space, literal,
+or format) are handled one after the other. If the input cannot be
+matched to the format string the function stops. The remainder of the
+format and input strings are not processed.
+
+The function returns a pointer to the first character it was unable to
+process. If the input string contains more characters than required by
+the format string the return value points right after the last consumed
+input character. If the whole input string is consumed the return value
+points to the @code{NULL} byte at the end of the string. If an error
+occurs, i.e. @code{strptime} fails to match all of the format string,
+the function returns @code{NULL}.
+@end deftypefun
+
+The specification of the function in the XPG standard is rather vague,
+leaving out a few important pieces of information. Most importantly, it
+does not specify what happens to those elements of @var{tm} which are
+not directly initialized by the different formats. The
+implementations on different Unix systems vary here.
+
+The GNU libc implementation does not touch those fields which are not
+directly initialized. Exceptions are the @code{tm_wday} and
+@code{tm_yday} elements, which are recomputed if any of the year, month,
+or date elements changed. This has two implications:
+
+@itemize @bullet
+@item
+Before calling the @code{strptime} function for a new input string, you
+should prepare the @var{tm} structure you pass. Normally this will mean
+initializing all values are to zero. Alternatively, you can set all
+fields to values like @code{INT_MAX}, allowing you to determine which
+elements were set by the function call. Zero does not work here since
+it is a valid value for many of the fields.
+
+Careful initialization is necessary if you want to find out whether a
+certain field in @var{tm} was initialized by the function call.
+
+@item
+You can construct a @code{struct tm} value with several consecutive
+@code{strptime} calls. A useful application of this is e.g. the parsing
+of two separate strings, one containing date information and the other
+time information. By parsing one after the other without clearing the
+structure in-between, you can construct a complete broken-down time.
+@end itemize
+
+The following example shows a function which parses a string which is
+contains the date information in either US style or @w{ISO 8601} form:
+
+@smallexample
+const char *
+parse_date (const char *input, struct tm *tm)
+@{
+ const char *cp;
+
+ /* @r{First clear the result structure.} */
+ memset (tm, '\0', sizeof (*tm));
+
+ /* @r{Try the ISO format first.} */
+ cp = strptime (input, "%F", tm);
+ if (cp == NULL)
+ @{
+ /* @r{Does not match. Try the US form.} */
+ cp = strptime (input, "%D", tm);
+ @}
+
+ return cp;
+@}
+@end smallexample
+
+@node General Time String Parsing
+@subsubsection A More User-friendly Way to Parse Times and Dates
+
+The Unix standard defines another function for parsing date strings.
+The interface is weird, but if the function happens to suit your
+application it is just fine. It is problematic to use this function
+in multi-threaded programs or libraries, since it returns a pointer to
+a static variable, and uses a global variable and global state (an
+environment variable).
+
+@comment time.h
+@comment Unix98
+@defvar getdate_err
+This variable of type @code{int} contains the error code of the last
+unsuccessful call to @code{getdate}. Defined values are:
+
+@table @math
+@item 1
+The environment variable @code{DATEMSK} is not defined or null.
+@item 2
+The template file denoted by the @code{DATEMSK} environment variable
+cannot be opened.
+@item 3
+Information about the template file cannot retrieved.
+@item 4
+The template file is not a regular file.
+@item 5
+An I/O error occurred while reading the template file.
+@item 6
+Not enough memory available to execute the function.
+@item 7
+The template file contains no matching template.
+@item 8
+The input date is invalid, but would match a template otherwise. This
+includes dates like February 31st, and dates which cannot be represented
+in a @code{time_t} variable.
+@end table
+@end defvar
+
+@comment time.h
+@comment Unix98
+@deftypefun {struct tm *} getdate (const char *@var{string})
+The interface to @code{getdate} is the simplest possible for a function
+to parse a string and return the value. @var{string} is the input
+string and the result is returned in a statically-allocated variable.
+
+The details about how the string is processed are hidden from the user.
+In fact, they can be outside the control of the program. Which formats
+are recognized is controlled by the file named by the environment
+variable @code{DATEMSK}. This file should contain
+lines of valid format strings which could be passed to @code{strptime}.
+
+The @code{getdate} function reads these format strings one after the
+other and tries to match the input string. The first line which
+completely matches the input string is used.
+
+Elements not initialized through the format string retain the values
+present at the time of the @code{getdate} function call.
+
+The formats recognized by @code{getdate} are the same as for
+@code{strptime}. See above for an explanation. There are only a few
+extensions to the @code{strptime} behavior:
+
+@itemize @bullet
+@item
+If the @code{%Z} format is given the broken-down time is based on the
+current time of the timezone matched, not of the current timezone of the
+runtime environment.
+
+@emph{Note}: This is not implemented (currently). The problem is that
+timezone names are not unique. If a fixed timezone is assumed for a
+given string (say @code{EST} meaning US East Coast time), then uses for
+countries other than the USA will fail. So far we have found no good
+solution to this.
+
+@item
+If only the weekday is specified the selected day depends on the current
+date. If the current weekday is greater or equal to the @code{tm_wday}
+value the current week's day is chosen, otherwise the day next week is chosen.
+
+@item
+A similar heuristic is used when only the month is given and not the
+year. If the month is greater than or equal to the current month, then
+the current year is used. Otherwise it wraps to next year. The first
+day of the month is assumed if one is not explicitly specified.
+
+@item
+The current hour, minute, and second are used if the appropriate value is
+not set through the format.
+
+@item
+If no date is given tomorrow's date is used if the time is
+smaller than the current time. Otherwise today's date is taken.
+@end itemize
+
+It should be noted that the format in the template file need not only
+contain format elements. The following is a list of possible format
+strings (taken from the Unix standard):
+
+@smallexample
+%m
+%A %B %d, %Y %H:%M:%S
+%A
+%B
+%m/%d/%y %I %p
+%d,%m,%Y %H:%M
+at %A the %dst of %B in %Y
+run job at %I %p,%B %dnd
+%A den %d. %B %Y %H.%M Uhr
+@end smallexample
+
+As you can see, the template list can contain very specific strings like
+@code{run job at %I %p,%B %dnd}. Using the above list of templates and
+assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the
+following results for the given input.
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item Input @tab Match @tab Result
+@item Mon @tab %a @tab Mon Sep 22 12:19:47 EDT 1986
+@item Sun @tab %a @tab Sun Sep 28 12:19:47 EDT 1986
+@item Fri @tab %a @tab Fri Sep 26 12:19:47 EDT 1986
+@item September @tab %B @tab Mon Sep 1 12:19:47 EDT 1986
+@item January @tab %B @tab Thu Jan 1 12:19:47 EST 1987
+@item December @tab %B @tab Mon Dec 1 12:19:47 EST 1986
+@item Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986
+@item Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987
+@item Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986
+@item Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989
+@item Fri 9 @tab %a %H @tab Fri Sep 26 09:00:00 EDT 1986
+@item Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987
+@item 10:30 @tab %H:%M @tab Tue Sep 23 10:30:00 EDT 1986
+@item 13:30 @tab %H:%M @tab Mon Sep 22 13:30:00 EDT 1986
+@end multitable
+
+The return value of the function is a pointer to a static variable of
+type @w{@code{struct tm}}, or a null pointer if an error occurred. The
+result is only valid until the next @code{getdate} call, making this
+function unusable in multi-threaded applications.
+
+The @code{errno} variable is @emph{not} changed. Error conditions are
+stored in the global variable @code{getdate_err}. See the
+description above for a list of the possible error values.
+
+@emph{Warning:} The @code{getdate} function should @emph{never} be
+used in SUID-programs. The reason is obvious: using the
+@code{DATEMSK} environment variable you can get the function to open
+any arbitrary file and chances are high that with some bogus input
+(such as a binary file) the program will crash.
+@end deftypefun
+
+@comment time.h
+@comment GNU
+@deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp})
+The @code{getdate_r} function is the reentrant counterpart of
+@code{getdate}. It does not use the global variable @code{getdate_err}
+to signal an error, but instead returns an error code. The same error
+codes as described in the @code{getdate_err} documentation above are
+used, with 0 meaning success.
+
+Moreover, @code{getdate_r} stores the broken-down time in the variable
+of type @code{struct tm} pointed to by the second argument, rather than
+in a static variable.
+
+This function is not defined in the Unix standard. Nevertheless it is
+available on some other Unix systems as well.
+
+The warning against using @code{getdate} in SUID-programs applies to
+@code{getdate_r} as well.
+@end deftypefun
+
@node TZ Variable
@subsection Specifying the Time Zone with @code{TZ}
You should not normally need to set @code{TZ}. If the system is
configured properly, the default time zone will be correct. You might
-set @code{TZ} if you are using a computer over the network from a
-different time zone, and would like times reported to you in the time zone
-that local for you, rather than what is local for the computer.
+set @code{TZ} if you are using a computer over a network from a
+different time zone, and would like times reported to you in the time
+zone local to you, rather than what is local to the computer.
-In POSIX.1 systems the value of the @code{TZ} variable can be of one of
+In POSIX.1 systems the value of the @code{TZ} variable can be in one of
three formats. With the GNU C library, the most common format is the
last one, which can specify a selection from a large database of time
zone information for many regions of the world. The first two formats
@end smallexample
The @var{std} string specifies the name of the time zone. It must be
-three or more characters long and must not contain a leading colon or
-embedded digits, commas, or plus or minus signs. There is no space
+three or more characters long and must not contain a leading colon,
+embedded digits, commas, nor plus and minus signs. There is no space
character separating the time zone name from the @var{offset}, so these
restrictions are necessary to parse the specification correctly.
-The @var{offset} specifies the time value one must add to the local time
+The @var{offset} specifies the time value you must add to the local time
to get a Coordinated Universal Time value. It has syntax like
[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This
is positive if the local time zone is west of the Prime Meridian and
@code{23}, and the minute and seconds between @code{0} and @code{59}.
For example, here is how we would specify Eastern Standard Time, but
-without any daylight saving time alternative:
+without any Daylight Saving Time alternative:
@smallexample
EST+5
The initial @var{std} and @var{offset} specify the standard time zone, as
described above. The @var{dst} string and @var{offset} specify the name
-and offset for the corresponding daylight saving time time zone; if the
+and offset for the corresponding Daylight Saving Time zone; if the
@var{offset} is omitted, it defaults to one hour ahead of standard time.
-The remainder of the specification describes when daylight saving time is
-in effect. The @var{start} field is when daylight saving time goes into
+The remainder of the specification describes when Daylight Saving Time is
+in effect. The @var{start} field is when Daylight Saving Time goes into
effect and the @var{end} field is when the change is made back to standard
time. The following formats are recognized for these fields:
effect, the change to the other time occurs. If omitted, the default is
@code{02:00:00}.
-For example, here is how one would specify the Eastern time zone in the
-United States, including the appropriate daylight saving time and its dates
+For example, here is how you would specify the Eastern time zone in the
+United States, including the appropriate Daylight Saving Time and its dates
of applicability. The normal offset from UTC is 5 hours; since this is
west of the prime meridian, the sign is positive. Summer time begins on
the first Sunday in April at 2:00am, and ends on the last Sunday in October
EST+5EDT,M4.1.0/2,M10.5.0/2
@end smallexample
-The schedule of daylight saving time in any particular jurisdiction has
+The schedule of Daylight Saving Time in any particular jurisdiction has
changed over the years. To be strictly correct, the conversion of dates
and times in the past should be based on the schedule that was in effect
then. However, this format has no facilities to let you specify how the
@comment POSIX.1
@deftypevar {char *} tzname [2]
The array @code{tzname} contains two strings, which are the standard
-names of the pair of time zones (standard and daylight
-saving) that the user has selected. @code{tzname[0]} is the name of
+names of the pair of time zones (standard and Daylight
+Saving) that the user has selected. @code{tzname[0]} is the name of
the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
-is the name for the time zone when daylight saving time is in use (for
+is the name for the time zone when Daylight Saving Time is in use (for
example, @code{"EDT"}). These correspond to the @var{std} and @var{dst}
strings (respectively) from the @code{TZ} environment variable. If
-daylight saving time is never used, @code{tzname[1]} is the empty string.
+Daylight Saving Time is never used, @code{tzname[1]} is the empty string.
The @code{tzname} array is initialized from the @code{TZ} environment
variable whenever @code{tzset}, @code{ctime}, @code{strftime},
broken-down time structure, since @code{tm_zone} reports the correct
abbreviation even when it is not the latest one.
-Though the strings are declared as @code{char *} the user must stay away
-from modifying these strings. Modying the strings will almost certainly
+Though the strings are declared as @code{char *} the user must refrain
+from modifying these strings. Modifying the strings will almost certainly
lead to trouble.
@end deftypevar
@comment time.h
@comment SVID
@deftypevar int daylight
-This variable has a nonzero value if daylight savings time rules apply.
-A nonzero value does not necessarily mean that daylight savings time is
-now in effect; it means only that daylight savings time is sometimes in
+This variable has a nonzero value if Daylight Saving Time rules apply.
+A nonzero value does not necessarily mean that Daylight Saving Time is
+now in effect; it means only that Daylight Saving Time is sometimes in
effect.
@end deftypevar
@end smallexample
+@node Precision Time
+@section Precision Time
+
+@cindex time, high precision
+@pindex sys/timex.h
+The @code{net_gettime} and @code{ntp_adjtime} functions provide an
+interface to monitor and manipulate high precision time. These
+functions are declared in @file{sys/timex.h}.
+
+@tindex struct ntptimeval
+@deftp {Data Type} {struct ntptimeval}
+This structure is used to monitor kernel time. It contains the
+following members:
+@table @code
+@item struct timeval time
+This is the current time. The @code{struct timeval} data type is
+described in @ref{High-Resolution Calendar}.
+
+@item long int maxerror
+This is the maximum error, measured in microseconds. Unless updated
+via @code{ntp_adjtime} periodically, this value will reach some
+platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds. This value can
+be set by @code{ntp_adjtime} to indicate the estimated offset of the
+local clock against the true time.
+@end table
+@end deftp
+
+@comment sys/timex,h
+@comment GNU
+@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
+The @code{ntp_gettime} function sets the structure pointed to by
+@var{tptr} to current values. The elements of the structure afterwards
+contain the values the timer implementation in the kernel assumes. They
+might or might not be correct. If they are not a @code{ntp_adjtime}
+call is necessary.
+
+The return value is @code{0} on success and other values on failure. The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item TIME_ERROR
+The precision clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care.
+@end table
+@end deftypefun
+
+@tindex struct timex
+@deftp {Data Type} {struct timex}
+This structure is used to control and monitor kernel time in a greater
+level of detail. It contains the following members:
+@table @code
+@item unsigned int modes
+This variable controls whether and which values are set. Several
+symbolic constants have to be combined with @emph{binary or} to specify
+the effective mode. These constants start with @code{MOD_}.
+
+@item long int offset
+This value indicates the current offset of the local clock from the true
+time. The value is given in microseconds. If bit @code{MOD_OFFSET} is
+set in @code{modes}, the offset (and possibly other dependent values) can
+be set. The offset's absolute value must not exceed @code{MAXPHASE}.
+
+@item long int frequency
+This value indicates the difference in frequency between the true time
+and the local clock. The value is expressed as scaled PPM (parts per
+million, 0.0001%). The scaling is @code{1 << SHIFT_USEC}. The value
+can be set with bit @code{MOD_FREQUENCY}, but the absolute value must
+not exceed @code{MAXFREQ}.
+
+@item long int maxerror
+This is the maximum error, measured in microseconds. A new value can be
+set using bit @code{MOD_MAXERROR}. Unless updated via
+@code{ntp_adjtime} periodically, this value will increase steadily
+and reach some platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds. This value can
+be set using bit @code{MOD_ESTERROR}.
+
+@item int status
+This variable reflects the various states of the clock machinery. There
+are symbolic constants for the significant bits, starting with
+@code{STA_}. Some of these flags can be updated using the
+@code{MOD_STATUS} bit.
+
+@item long int constant
+This value represents the bandwidth or stiffness of the PLL (phase
+locked loop) implemented in the kernel. The value can be changed using
+bit @code{MOD_TIMECONST}.
+
+@item long int precision
+This value represents the accuracy or the maximum error when reading the
+system clock. The value is expressed in microseconds and can't be changed.
+
+@item long int tolerance
+This value represents the maximum frequency error of the system clock in
+scaled PPM. This value is used to increase the @code{maxerror} every
+second.
+
+@item long int ppsfreq
+This is the first of a few optional variables that are present only if
+the system clock can use a PPS (pulse per second) signal to discipline
+the local clock. The value is expressed in scaled PPM and it denotes
+the difference in frequency between the local clock and the PPS signal.
+
+@item long int jitter
+This value expresses a median filtered average of the PPS signal's
+dispersion in microseconds.
+
+@item int int shift
+This value is a binary exponent for the duration of the PPS calibration
+interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}.
+
+@item long int stabil
+This value represents the median filtered dispersion of the PPS
+frequency in scaled PPM.
+
+@item long int jitcnt
+This counter represents the number of pulses where the jitter exceeded
+the allowed maximum @code{MAXTIME}.
+
+@item long int calcnt
+This counter reflects the number of successful calibration intervals.
+
+@item long int errcnt
+This counter represents the number of calibration errors (caused by
+large offsets or jitter).
+
+@item long int stbcnt
+This counter denotes the number of of calibrations where the stability
+exceeded the threshold.
+@end table
+@end deftp
+
+@comment sys/timex.h
+@comment GNU
+@deftypefun int ntp_adjtime (struct timex *@var{tptr})
+The @code{ntp_adjtime} function sets the structure specified by
+@var{tptr} to current values. In addition, values passed in @var{tptr}
+can be used to replace existing settings. To do this the @code{modes}
+element of the @code{struct timex} must be set appropriately. Setting
+it to zero selects reading the current state.
+
+The return value is @code{0} on success and other values on failure. The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item TIME_ERROR
+The precision clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care. Another reason could be that the specified new values
+are not allowed.
+@end table
+
+For more details see RFC1305 (Network Time Protocol, Version 3) and
+related documents.
+@end deftypefun
+
+
@node Setting an Alarm
@section Setting an Alarm
new value.
You should establish a handler for the appropriate alarm signal using
-@code{signal} or @code{sigaction} before issuing a call to @code{setitimer}
-or @code{alarm}. Otherwise, an unusual chain of events could cause the
-timer to expire before your program establishes the handler, and in that
-case it would be terminated, since that is the default action for the alarm
-signals. @xref{Signal Handling}.
+@code{signal} or @code{sigaction} before issuing a call to
+@code{setitimer} or @code{alarm}. Otherwise, an unusual chain of events
+could cause the timer to expire before your program establishes the
+handler. In this case it would be terminated, since termination is the
+default action for the alarm signals. @xref{Signal Handling}.
The @code{setitimer} function is the primary means for setting an alarm.
This facility is declared in the header file @file{sys/time.h}. The
keep trying to wait until that time. This won't be off by more than a
second. With just a little more work, you can use @code{select} and
make the waiting period quite accurate. (Of course, heavy system load
-can cause unavoidable additional delays---unless the machine is
+can cause additional unavoidable delays---unless the machine is
dedicated to one application, there is no way you can avoid this.)
On some systems, @code{sleep} can do strange things if your program uses
@comment time.h
@comment POSIX.1
@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
-If the resolution of seconds is not enough the @code{nanosleep} function
+If resolution to seconds is not enough the @code{nanosleep} function
can be used. As the name suggests the sleeping period can be specified
in nanoseconds. The actual period of waiting time might be longer since
the requested time in the @var{requested_time} parameter is rounded up
to the next integer multiple of the actual resolution of the system.
If the function returns because the time has elapsed the return value is
-zero. If the function return @math{-1} the global variable @var{errno}
+zero. If the function returns @math{-1} the global variable @var{errno}
is set to the following values:
@table @code
1000 million.
@end table
-This function is a cancelation point in multi-threaded programs. This
+This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{nanosleep} is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to @code{nanosleep} should
-be protected using cancelation handlers.
+be protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{nanosleep} function is declared in @file{time.h}.
@section Resource Usage
@pindex sys/resource.h
-The function @code{getrusage} and the data type @code{struct rusage}
-are used for examining the usage figures of a process. They are declared
-in @file{sys/resource.h}.
+The function @code{getrusage} and the data type @code{struct rusage} are
+used to examine the resource usage of a process. They are declared in
+@file{sys/resource.h}.
@comment sys/resource.h
@comment BSD
@deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage})
-This function reports the usage totals for processes specified by
+This function reports resource usage totals for processes specified by
@var{processes}, storing the information in @code{*@var{rusage}}.
In most systems, @var{processes} has only two valid values:
@comment sys/resource.h
@comment BSD
@item RUSAGE_CHILDREN
-All child processes (direct and indirect) that have terminated already.
+All child processes (direct and indirect) that have already terminated.
@end table
In the GNU system, you can also inquire about a particular child process
@end table
@end deftypefun
-One way of getting usage figures for a particular child process is with
+One way of getting resource usage for a particular child process is with
the function @code{wait4}, which returns totals for a child when it
terminates. @xref{BSD Wait Functions}.
@comment sys/resource.h
@comment BSD
@deftp {Data Type} {struct rusage}
-This data type records a collection usage amounts for various sorts of
-resources. It has the following members, and possibly others:
+This data type stores various resource usage statistics. It has the
+following members, and possibly others:
@table @code
@item struct timeval ru_utime
@item long int ru_maxrss
The maximum resident set size used, in kilobytes. That is, the maximum
-number of kilobytes that @var{processes} used in real memory simultaneously.
+number of kilobytes of physical memory that @var{processes} used
+simultaneously.
@item long int ru_ixrss
An integral value expressed in kilobytes times ticks of execution, which
@item long int ru_idrss
An integral value expressed the same way, which is the amount of
-unshared memory used in data.
+unshared memory used for data.
@item long int ru_isrss
An integral value expressed the same way, which is the amount of
-unshared memory used in stack space.
+unshared memory used for stack space.
@item long int ru_minflt
The number of page faults which were serviced without requiring any I/O.
(usually to wait for some service).
@item long int ru_nivcsw
-The number of times an involuntary context switch took place (because
-the time slice expired, or another process of higher priority became
-runnable).
+The number of times an involuntary context switch took place (because a
+time slice expired, or another process of higher priority was
+scheduled).
@end table
@end deftp
-An additional historical function for examining usage figures,
+An additional historical function for examining resource usage,
@code{vtimes}, is supported but not documented here. It is declared in
@file{sys/vtimes.h}.
@cindex usage limits
You can specify limits for the resource usage of a process. When the
-process tries to exceed a limit, it may get a signal, or the system call
-by which it tried to do so may fail, depending on the limit. Each
+process tries to exceed a given limit, it may get a signal, or the system call
+by which it tried to do so may fail, depending on the limit in question. Each
process initially inherits its limit values from its parent, but it can
subsequently change them.
The return value is @code{0} on success and @code{-1} on failure. The
only possible @code{errno} error condition is @code{EFAULT}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system, this function is in fact @code{getrlimit64}. Thus the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp})
+This function is similar to @code{getrlimit}, but its second
+parameter is a pointer to a variable of type @code{struct rlimit64},
+allowing it to read values which wouldn't fit in the member
+of a @code{struct rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit machine, this function is available under the name
+@code{getrlimit} and so transparently replaces the old interface.
@end deftypefun
@comment sys/resource.h
@comment BSD
-@deftypefun int setrlimit (int @var{resource}, struct rlimit *@var{rlp})
+@deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp})
Store the current value and the maximum value of resource @var{resource}
in @code{*@var{rlp}}.
You tried to change the maximum permissible limit value,
but you don't have privileges to do so.
@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{setrlimit64}. Thus the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp})
+This function is similar to @code{setrlimit}, but its second parameter
+is a pointer to a variable of type @code{struct rlimit64}, allowing it
+to set values which wouldn't fit in the member of a @code{struct
+rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit machine, this function is available under the name
+@code{setrlimit} and so transparently replaces the old interface.
@end deftypefun
@comment sys/resource.h
and with @code{setrlimit} to specify limit values. It has two fields:
@table @code
-@item rlim_cur
+@item rlim_t rlim_cur
The current value of the limit in question.
This is also called the ``soft limit''.
@cindex soft limit
-@item rlim_max
+@item rlim_t rlim_max
The maximum permissible value of the limit in question. You cannot set
the current value of the limit to a larger number than this maximum.
-Only the super user can change the maximum permissible value.
+Only the super-user can change the maximum permissible value.
This is also called the ``hard limit''.
@cindex hard limit
@end table
-In @code{getrlimit}, the structure is an output; it receives the current
-values. In @code{setrlimit}, it specifies the new values.
+For @code{getrlimit}, the structure is an output; it receives the current
+value. With @code{setrlimit} it specifies the new value.
+@end deftp
+
+For the LFS functions a similar type is defined in @file{sys/resource.h}.
+
+@comment sys/resource.h
+@comment Unix98
+@deftp {Data Type} {struct rlimit64}
+This structure is used with @code{getrlimit64} to receive limit values,
+and with @code{setrlimit64} to specify limit values. It has two fields:
+
+@table @code
+@item rlim64_t rlim_cur
+The current value of the limit in question.
+This is also called the ``soft limit''.
+
+@item rlim64_t rlim_max
+The maximum permissible value of the limit in question. You cannot set
+the current value of the limit to a larger number than this maximum.
+Only the super-user can change the maximum permissible value.
+This is also called the ``hard limit''.
+@end table
+
+For @code{getrlimit64}, the structure is an output; it receives the current
+value. With @code{setrlimit64} it specifies the new value.
@end deftp
Here is a list of resources that you can specify a limit for.
-Those that are sizes are measured in bytes.
+Memory sizes are measured in bytes.
@table @code
@comment sys/resource.h
@comment BSD
@item RLIMIT_CPU
@vindex RLIMIT_CPU
-The maximum amount of cpu time the process can use. If it runs for
+The maximum amount of CPU time the process can use. If it runs for
longer than this, it gets a signal: @code{SIGXCPU}. The value is
measured in seconds. @xref{Operation Error Signals}.
@item RLIMIT_CORE
@vindex RLIMIT_CORE
The maximum size core file that this process can create. If the process
-terminates and would dump a core file larger than this maximum size,
+terminates and would dump a core file larger than this,
then no core file is created. So setting this limit to zero prevents
core files from ever being created.
@itemx RLIMIT_OFILE
@vindex RLIMIT_OFILE
The maximum number of files that the process can open. If it tries to
-open more files than this, it gets error code @code{EMFILE}.
+open more files than this, it gets the error code @code{EMFILE}.
@xref{Error Codes}. Not all systems support this limit; GNU does, and
4.4 BSD does.
@comment sys/resource.h
+@comment Unix98
+@item RLIMIT_AS
+@vindex RLIMIT_AS
+The maximum size of total memory that this process should get. If the
+process tries to allocate more memory beyond this amount with, for
+example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the
+allocation function fails.
+
+@comment sys/resource.h
@comment BSD
@item RLIM_NLIMITS
@vindex RLIM_NLIMITS
@comment sys/resource.h
@comment BSD
-@defvr Constant int RLIM_INFINITY
+@deftypevr Constant int RLIM_INFINITY
This constant stands for a value of ``infinity'' when supplied as
the limit value in @code{setrlimit}.
-@end defvr
+@end deftypevr
@c ??? Someone want to finish these?
Two historical functions for setting resource limits, @code{ulimit} and
@comment BSD
@item PRIO_MAX
@vindex PRIO_MAX
-The smallest valid priority value.
+The largest valid priority value.
@end table
@comment sys/resource.h
The value of @var{class} is not valid.
@end table
-When the return value is @code{-1}, it could indicate failure, or it
+If the return value is @code{-1}, it could indicate failure, or it
could be the priority value. The only way to make certain is to set
@code{errno = 0} before calling @code{getpriority}, then use @code{errno
!= 0} afterward as the criterion for failure.
@end deftypefun
The arguments @var{class} and @var{id} together specify a set of
-processes you are interested in. These are the possible values for
+processes you are interested in. These are the possible values of
@var{class}:
@table @code
Increment the priority of the current process by @var{increment}.
The return value is the same as for @code{setpriority}.
-Here is an equivalent definition for @code{nice}:
+Here is an equivalent definition of @code{nice}:
@smallexample
int
projects / platform / upstream / glibc.git / blobdiff