diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/arith.texi | 157 | ||||
| -rw-r--r-- | manual/conf.texi | 74 | ||||
| -rw-r--r-- | manual/crypt.texi | 52 | ||||
| -rw-r--r-- | manual/llio.texi | 31 | ||||
| -rw-r--r-- | manual/locale.texi | 32 | ||||
| -rw-r--r-- | manual/memory.texi | 4 | ||||
| -rw-r--r-- | manual/nss.texi | 10 | ||||
| -rw-r--r-- | manual/resource.texi | 192 | ||||
| -rw-r--r-- | manual/time.texi | 13 |
9 files changed, 453 insertions, 112 deletions
diff --git a/manual/arith.texi b/manual/arith.texi index 5c73360..630dde5 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -2058,11 +2058,17 @@ one by one. @subsection Parsing of Integers @pindex stdlib.h -These functions are declared in @file{stdlib.h}. +@pindex wchar.h +The @samp{str} functions are declared in @file{stdlib.h} and those +beginning with @samp{wcs} are declared in @file{wchar.h}. One might +wonder about the use of @code{restrict} in the prototypes of the +functions in this section. It is seemingly useless but the @w{ISO C} +standard uses it (for the functions defined there) so we have to do it +as well. @comment stdlib.h @comment ISO -@deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtol} (``string-to-long'') function converts the initial part of @var{string} to a signed integer, which is returned as a value of type @code{long int}. @@ -2123,9 +2129,18 @@ case there was overflow. There is an example at the end of this section. @end deftypefun +@comment wchar.h +@comment ISO +@deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstol} function is equivalent in nearly all aspect to the +@code{strtol} function but it handles wide character string. + +The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}. +@end deftypefun + @comment stdlib.h @comment ISO -@deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtoul} (``string-to-unsigned-long'') function is like @code{strtol} except it converts to an @code{unsigned long int} value. The syntax is the same as described above for @code{strtol}. The value @@ -2141,9 +2156,18 @@ and an input more negative than @code{LONG_MIN} returns range, or @code{ERANGE} on overflow. @end deftypefun +@comment wchar.h +@comment ISO +@deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoul} function is equivalent in nearly all aspect to the +@code{strtoul} function but it handles wide character string. + +The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}. +@end deftypefun + @comment stdlib.h @comment ISO -@deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtoll} function is like @code{strtol} except that it returns a @code{long long int} value, and accepts numbers with a correspondingly larger range. @@ -2157,30 +2181,66 @@ appropriate for the sign of the value. It also sets @code{errno} to The @code{strtoll} function was introduced in @w{ISO C99}. @end deftypefun +@comment wchar.h +@comment ISO +@deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoll} function is equivalent in nearly all aspect to the +@code{strtoll} function but it handles wide character string. + +The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}. +@end deftypefun + @comment stdlib.h @comment BSD -@deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}. @end deftypefun +@comment wchar.h +@comment GNU +@deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoq} function is equivalent in nearly all aspect to the +@code{strtoq} function but it handles wide character string. + +The @code{wcstoq} function is a GNU extension. +@end deftypefun + @comment stdlib.h @comment ISO -@deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtoull} function is related to @code{strtoll} the same way @code{strtoul} is related to @code{strtol}. The @code{strtoull} function was introduced in @w{ISO C99}. @end deftypefun +@comment wchar.h +@comment ISO +@deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoull} function is equivalent in nearly all aspect to the +@code{strtoull} function but it handles wide character string. + +The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}. +@end deftypefun + @comment stdlib.h @comment BSD -@deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) @code{strtouq} is the BSD name for @code{strtoull}. @end deftypefun +@comment wchar.h +@comment GNU +@deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstouq} function is equivalent in nearly all aspect to the +@code{strtouq} function but it handles wide character string. + +The @code{wcstoq} function is a GNU extension. +@end deftypefun + @comment inttypes.h -@comment ??? -@deftypefun {long long int} strtoimax (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@comment ISO +@deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtoimax} function is like @code{strtol} except that it returns a @code{intmax_t} value, and accepts numbers of a corresponding range. @@ -2190,21 +2250,36 @@ representable because of overflow, @code{strtoimax} returns either appropriate for the sign of the value. It also sets @code{errno} to @code{ERANGE} to indicate there was overflow. -The symbols for @code{strtoimax} are declared in @file{inttypes.h}. +See @ref{Integers} for a description of the @code{intmax_t} type. The +@code{strtoimax} function was introduced in @w{ISO C99}. +@end deftypefun -See @ref{Integers} for a description of the @code{intmax_t} type. +@comment wchar.h +@comment ISO +@deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoimax} function is equivalent in nearly all aspect to the +@code{strtoimax} function but it handles wide character string. +The @code{wcstoimax} function was introduced in @w{ISO C99}. @end deftypefun @comment inttypes.h -@comment ??? -@deftypefun uintmax_t strtoumax (const char *@var{string}, char **@var{tailptr}, int @var{base}) +@comment ISO +@deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base}) The @code{strtoumax} function is related to @code{strtoimax} the same way that @code{strtoul} is related to @code{strtol}. -The symbols for @code{strtoimax} are declared in @file{inttypes.h}. +See @ref{Integers} for a description of the @code{intmax_t} type. The +@code{strtoumax} function was introduced in @w{ISO C99}. +@end deftypefun -See @ref{Integers} for a description of the @code{intmax_t} type. +@comment wchar.h +@comment ISO +@deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base}) +The @code{wcstoumax} function is equivalent in nearly all aspect to the +@code{strtoumax} function but it handles wide character string. + +The @code{wcstoumax} function was introduced in @w{ISO C99}. @end deftypefun @comment stdlib.h @@ -2234,25 +2309,12 @@ The @code{atoll} function was introduced in @w{ISO C99}. It too is obsolete (despite having just been added); use @code{strtoll} instead. @end deftypefun -@c !!! please fact check this paragraph -zw -@findex strtol_l -@findex strtoul_l -@findex strtoll_l -@findex strtoull_l -@cindex parsing numbers and locales -@cindex locales, parsing numbers and -Some locales specify a printed syntax for numbers other than the one -that these functions understand. If you need to read numbers formatted -in some other locale, you can use the @code{strtoX_l} functions. Each -of the @code{strtoX} functions has a counterpart with @samp{_l} added to -its name. The @samp{_l} counterparts take an additional argument: a -pointer to an @code{locale_t} structure, which describes how the numbers -to be read are formatted. @xref{Locales}. - -@strong{Portability Note:} These functions are all GNU extensions. You -can also use @code{scanf} or its relatives, which have the @samp{'} flag -for parsing numeric input according to the current locale -(@pxref{Numeric Input Conversions}). This feature is standard. +All the functions mentioned in this section so far do not handle +alternative representations of characters as described in the locale +data. Some locales specify thousands separator and the way they have to +be used which can help to make large numbers more readable. To read +such numbers one has to use the @code{scanf} functions with the @samp{'} +flag. Here is a function which parses a string as a sequence of integers and returns the sum of them: @@ -2294,11 +2356,16 @@ sum_ints_from_string (char *string) @subsection Parsing of Floats @pindex stdlib.h -These functions are declared in @file{stdlib.h}. +The @samp{str} functions are declared in @file{stdlib.h} and those +beginning with @samp{wcs} are declared in @file{wchar.h}. One might +wonder about the use of @code{restrict} in the prototypes of the +functions in this section. It is seemingly useless but the @w{ISO C} +standard uses it (for the functions defined there) so we have to do it +as well. @comment stdlib.h @comment ISO -@deftypefun double strtod (const char *@var{string}, char **@var{tailptr}) +@deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr}) The @code{strtod} (``string-to-double'') function converts the initial part of @var{string} to a floating-point number, which is returned as a value of type @code{double}. @@ -2394,6 +2461,24 @@ double} is a separate type). These functions have been GNU extensions and are new to @w{ISO C99}. @end deftypefun +@comment wchar.h +@comment ISO +@deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}) +@comment stdlib.h +@comment ISO +@deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr}) +@comment stdlib.h +@comment ISO +@deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr}) +The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are +equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and +@code{strtold} functions but it handles wide character string. + +The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO +C90}. The @code{wcstof} and @code{wcstold} functions were introduced in +@w{ISO C99}. +@end deftypefun + @comment stdlib.h @comment ISO @deftypefun double atof (const char *@var{string}) diff --git a/manual/conf.texi b/manual/conf.texi index 31452e0..ef00db6 100644 --- a/manual/conf.texi +++ b/manual/conf.texi @@ -316,7 +316,7 @@ Here are the symbolic constants for use as the @var{parameter} argument to @code{sysconf}. The values are all integer constants (more specifically, enumeration type values). -@table @code +@vtable @code @comment unistd.h @comment POSIX.1 @item _SC_ARG_MAX @@ -752,8 +752,7 @@ support. @comment GNU @item _SC_PAGESIZE Inquire about the virtual memory page size of the machine. -@code{getpagesize} returns the same value. -@c @xref{XXX getpagesize}. !!! ??? +@code{getpagesize} returns the same value (@pxref{Query Memory Parameters}). @comment unistd.h @comment GNU @@ -798,6 +797,21 @@ Inquire about the parameter corresponding to @code{_XOPEN_UNIX}. @comment unistd.h @comment X/Open +@item _SC_XOPEN_REALTIME +Inquire about the parameter corresponding to @code{_XOPEN_REALTIME}. + +@comment unistd.h +@comment X/Open +@item _SC_XOPEN_REALTIME_THREADS +Inquire about the parameter corresponding to @code{_XOPEN_REALTIME_THREADS}. + +@comment unistd.h +@comment X/Open +@item _SC_XOPEN_LEGACY +Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}. + +@comment unistd.h +@comment X/Open @item _SC_XOPEN_CRYPT Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}. @@ -960,7 +974,7 @@ Inquire about the parameter corresponding to @code{NL_SETMAX}. @comment X/Open @item _SC_NL_TEXTMAX Inquire about the parameter corresponding to @code{NL_TEXTMAX}. -@end table +@end vtable @node Examples of Sysconf @subsection Examples of @code{sysconf} @@ -1290,6 +1304,33 @@ bytes in a file name. The value of this constant is @code{256}. The most restrictive limit permitted by POSIX for the maximum number of bytes that can be written atomically to a pipe. The value of this constant is @code{512}. + +@comment limits.h +@comment POSIX.1 +@item SYMLINK_MAX +Maximum number of bytes in a symbolic link. + +@comment limits.h +@comment POSIX.1 +@item POSIX_REC_INCR_XFER_SIZE +Recommended increment for file transfer sizes between the +@code{POSIX_REC_MIN_XFER_SIZE} and @code{POSIX_REC_MAX_XFER_SIZE} +values. + +@comment limits.h +@comment POSIX.1 +@item POSIX_REC_MAX_XFER_SIZE +Maximum recommended file transfer size. + +@comment limits.h +@comment POSIX.1 +@item POSIX_REC_MIN_XFER_SIZE +Minimum recommended file transfer size. + +@comment limits.h +@comment POSIX.1 +@item POSIX_REC_XFER_ALIGN +Recommended file transfer buffer alignment. @end table @node Pathconf @@ -1417,6 +1458,31 @@ Inquire about the value of @code{_POSIX_PRIO_IO}. @comment POSIX.1g @item _PC_SOCK_MAXBUF Inquire about the value of @code{_POSIX_PIPE_BUF}. + +@comment unistd.h +@comment LFS +@item _PC_FILESIZEBITS +Inquire about the availability of large files on the filesystem. + +@comment unistd.h +@comment POSIX.1 +@item _PC_REC_INCR_XFER_SIZE +Inquire about the value of @code{POSIX_REC_INCR_XFER_SIZE}. + +@comment unistd.h +@comment POSIX.1 +@item _PC_REC_MAX_XFER_SIZE +Inquire about the value of @code{POSIX_REC_MAX_XFER_SIZE}. + +@comment unistd.h +@comment POSIX.1 +@item _PC_REC_MIN_XFER_SIZE +Inquire about the value of @code{POSIX_REC_MIN_XFER_SIZE}. + +@comment unistd.h +@comment POSIX.1 +@item _PC_REC_XFER_ALIGN +Inquire about the value of @code{POSIX_REC_XFER_ALIGN}. @end table @node Utility Limits diff --git a/manual/crypt.texi b/manual/crypt.texi index 73f66f6..2e08abe 100644 --- a/manual/crypt.texi +++ b/manual/crypt.texi @@ -23,19 +23,13 @@ through a @dfn{one-way function}, a function which makes it difficult to work out what its input was by looking at its output, before storing in the file. -The GNU C library already provides a one-way function based on MD5. The -@code{crypt} add-on provides additional compatibility with the standard -UNIX one-way function based on the Data Encryption Standard. +The GNU C library already provides a one-way function based on MD5 and +for compatibility with Unix systems the standard one-way function based +on the Data Encryption Standard. It also provides support for Secure RPC, and some library functions that can be used to perform normal DES encryption. -The add-on is not included in the main distribution of the GNU C library -because some governments, most notably those of France, Russia, -and the US, have very restrictive rules governing the distribution and -use of encryption software. The first section below tries to describe some -of those rules. - @menu * Legal Problems:: This software can get you locked up, or worse. * getpass:: Prompting the user for a password. @@ -53,8 +47,8 @@ may help you when you try to find out what the laws of your country are. Some countries require that you have a licence to use, posess, or import cryptography. These countries are believed to include Byelorussia, -Burma, France, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, -and Saudi Arabia. +Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi +Arabia. Some countries restrict the transmission of encrypted messages by radio; some telecommunications carriers restrict the transmission of encrypted @@ -94,7 +88,7 @@ in a convenient way. @comment unistd.h @comment BSD -@deftypefun {char *} getpass (const char * @var{prompt}) +@deftypefun {char *} getpass (const char *@var{prompt}) @code{getpass} outputs @var{prompt}, then reads a string in from the terminal without echoing it. It tries to connect to the real terminal, @@ -129,7 +123,7 @@ The substitute takes the same parameters as @code{getline} @comment crypt.h @comment BSD, SVID -@deftypefun {char *} crypt (const char * @var{key}, const char * @var{salt}) +@deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt}) The @code{crypt} function takes a password, @var{key}, as a string, and a @var{salt} character array which is described below, and returns a @@ -193,7 +187,7 @@ for a password and prints ``Access granted.'' if the user types @comment crypt.h @comment GNU -@deftypefun {char *} crypt_r (const char * @var{key}, const char * @var{salt}, {struct crypt_data *} @var{data}) +@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data}) The @code{crypt_r} function does the same thing as @code{crypt}, but takes an extra parameter which includes space for its result (among @@ -238,7 +232,7 @@ specifies the unused bits. @comment crypt.h @comment BSD, SVID -@deftypefun void setkey (const char * @var{key}) +@deftypefun void setkey (const char *@var{key}) The @code{setkey} function sets an internal data structure to be an expanded form of @var{key}. @var{key} is specified as an array of 64 @@ -249,7 +243,7 @@ parity. @comment crypt.h @comment BSD, SVID -@deftypefun void encrypt (char * @var{block}, int @var{edflag}) +@deftypefun void encrypt (char *@var{block}, int @var{edflag}) The @code{encrypt} function encrypts @var{block} if @var{edflag} is 0, otherwise it decrypts @var{block}, using a key @@ -262,10 +256,10 @@ stored in a @code{char}, but there are no parity bits in @var{block}. @comment crypt.h @comment GNU -@deftypefun void setkey_r (const char * @var{key}, {struct crypt_data *} @var{data}) +@deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data}) @comment crypt.h @comment GNU -@deftypefunx void encrypt_r (char * @var{block}, int @var{edflag}, {struct crypt_data *} @var{data}) +@deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data}) These are reentrant versions of @code{setkey} and @code{encrypt}. The only difference is the extra parameter, which stores the expanded @@ -284,7 +278,7 @@ recommended instead. @comment rpc/des_crypt.h @comment SUNRPC -@deftypefun int ecb_crypt (char * @var{key}, char * @var{blocks}, unsigned @var{len}, unsigned @var{mode}) +@deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}) The function @code{ecb_crypt} encrypts or decrypts one or more blocks using DES. Each block is encrypted independently. @@ -303,25 +297,22 @@ The result of the encryption replaces the input in @var{blocks}. The @var{mode} parameter is the bitwise OR of two of the following: -@table @code +@vtable @code @comment rpc/des_crypt.h @comment SUNRPC @item DES_ENCRYPT -@findex DES_ENCRYPT This constant, used in the @var{mode} parameter, specifies that @var{blocks} is to be encrypted. @comment rpc/des_crypt.h @comment SUNRPC @item DES_DECRYPT -@findex DES_DECRYPT This constant, used in the @var{mode} parameter, specifies that @var{blocks} is to be decrypted. @comment rpc/des_crypt.h @comment SUNRPC @item DES_HW -@findex DES_HW This constant, used in the @var{mode} parameter, asks to use a hardware device. If no hardware device is available, encryption happens anyway, but in software. @@ -329,30 +320,26 @@ but in software. @comment rpc/des_crypt.h @comment SUNRPC @item DES_SW -@findex DES_SW This constant, used in the @var{mode} parameter, specifies that no hardware device is to be used. -@end table +@end vtable The result of the function will be one of these values: -@table @code +@vtable @code @comment rpc/des_crypt.h @comment SUNRPC @item DESERR_NONE -@findex DESERR_NONE The encryption succeeded. @comment rpc/des_crypt.h @comment SUNRPC @item DESERR_NOHWDEVICE -@findex DESERR_NOHWDEVICE The encryption succeeded, but there was no hardware device available. @comment rpc/des_crypt.h @comment SUNRPC @item DESERR_HWERROR -@findex DESERR_HWERROR The encryption failed because of a hardware problem. In the GNU library, this error code is also returned if the @code{crypt} add-on was not used to build the library. @@ -360,10 +347,9 @@ not used to build the library. @comment rpc/des_crypt.h @comment SUNRPC @item DESERR_BADPARAM -@findex DESERR_BADPARAM The encryption failed because of a bad parameter, for instance @var{len} is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}. -@end table +@end vtable @end deftypefun @comment rpc/des_crypt.h @@ -375,7 +361,7 @@ This macro returns 1 if @var{err} is a `success' result code from @comment rpc/des_crypt.h @comment SUNRPC -@deftypefun int cbc_crypt (char * @var{key}, char * @var{blocks}, unsigned @var{len}, unsigned @var{mode}, char * @var{ivec}) +@deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}, char *@var{ivec}) The function @code{cbc_crypt} encrypts or decrypts one or more blocks using DES in Cipher Block Chaining mode. @@ -401,7 +387,7 @@ Otherwise, all the parameters are similar to those for @code{ecb_crypt}. @comment rpc/des_crypt.h @comment SUNRPC -@deftypefun void des_setparity (char * @var{key}) +@deftypefun void des_setparity (char *@var{key}) The function @code{des_setparity} changes the 64-bit @var{key}, stored packed in 8-bit bytes, to have odd parity by altering the low bits of diff --git a/manual/llio.texi b/manual/llio.texi index 4efb552..782e5b1 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1119,21 +1119,26 @@ of the file that a program actually accesses are loaded. Accesses to not-yet-loaded parts of the mmapped region are handled in the same way as swapped out pages. -Since mmapped pages can be stored back to their file when physical memory -is low, it is possible to mmap files orders of magnitude larger than both -the physical memory @emph{and} swap space. The only limit is address -space. The theoretical limit is 4GB on a 32-bit machine - however, the -actual limit will be smaller since some areas will be reserved for other -purposes. +Since mmapped pages can be stored back to their file when physical +memory is low, it is possible to mmap files orders of magnitude larger +than both the physical memory @emph{and} swap space. The only limit is +address space. The theoretical limit is 4GB on a 32-bit machine - +however, the actual limit will be smaller since some areas will be +reserved for other purposes. If the LFS interface is used the file size +on 32-bit systems is not limited to 2GB (offsets are signed which +reduces the addressable area of 4GB by half); the full 64-bit are +available. Memory mapping only works on entire pages of memory. Thus, addresses for mapping must be page-aligned, and length values will be rounded up. To determine the size of a page the machine uses one should use +@vindex _SC_PAGESIZE @smallexample size_t page_size = (size_t) sysconf (_SC_PAGESIZE); @end smallexample +@noindent These functions are declared in @file{sys/mman.h}. @deftypefun {void *} mmap (void *@var{address}, size_t @var{length},int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset}) @@ -1252,6 +1257,20 @@ The file is on a filesystem that doesn't support mapping. @end deftypefun +@deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length},int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset}) +The @code{mmap64} function is equivalent to the @code{mmap} function but +the @var{offset} parameter is of type @code{off64_t}. On 32-bit systems +this allows the file associated with the @var{filedes} descriptor to be +larger than 2GB. @var{filedes} must be a descriptor returned from a +call to @code{open64} or @code{fopen64} and @code{freopen64} where the +descriptor is retrieved with @code{fileno}. + +When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this +function is actually available under the name @code{mmap}. I.e., the +new, extended API using 64 bit file sizes and offsets transparently +replaces the old API. +@end deftypefun + @deftypefun int munmap (void *@var{addr}, size_t @var{length}) @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} + diff --git a/manual/locale.texi b/manual/locale.texi index e540009..680d852 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -225,6 +225,7 @@ The function @code{setlocale} sets the current locale for category @var{category} to @var{locale}. A list of all the locales the system provides can be created by running +@pindex locale @smallexample locale -a @end smallexample @@ -676,11 +677,16 @@ A second advantage is that in addition to the numeric and monetary formatting information, information from the @code{LC_TIME} and @code{LC_MESSAGES} categories is available. +@pindex langinfo.h The type @code{nl_type} is defined in @file{nl_types.h}. The argument @var{item} is a numeric value defined in the header @file{langinfo.h}. The X/Open standard defines the following values: @vtable @code +@item CODESET +@code{nl_langinfo} returns a string with the name of the coded character +set used in the selected locale. + @item ABDAY_1 @itemx ABDAY_2 @itemx ABDAY_3 @@ -832,6 +838,26 @@ The same as the value returned by @code{localeconv} in the @item N_SIGN_POSN The same as the value returned by @code{localeconv} in the @code{n_sign_posn} element of the @code{struct lconv}. + +@item INT_P_CS_PRECEDES +The same as the value returned by @code{localeconv} in the +@code{int_p_cs_precedes} element of the @code{struct lconv}. +@item INT_P_SEP_BY_SPACE +The same as the value returned by @code{localeconv} in the +@code{int_p_sep_by_space} element of the @code{struct lconv}. +@item INT_N_CS_PRECEDES +The same as the value returned by @code{localeconv} in the +@code{int_n_cs_precedes} element of the @code{struct lconv}. +@item INT_N_SEP_BY_SPACE +The same as the value returned by @code{localeconv} in the +@code{int_n_sep_by_space} element of the @code{struct lconv}. +@item INT_P_SIGN_POSN +The same as the value returned by @code{localeconv} in the +@code{int_p_sign_posn} element of the @code{struct lconv}. +@item INT_N_SIGN_POSN +The same as the value returned by @code{localeconv} in the +@code{int_n_sign_posn} element of the @code{struct lconv}. + @item DECIMAL_POINT @itemx RADIXCHAR The same as the value returned by @code{localeconv} in the @@ -862,9 +888,15 @@ to a yes/no question. Using this value is deprecated since it is a very special case of message translation, and is better handled by the message translation functions (@pxref{Message Translation}). + +The use of this symbol is deprecated. Instead message translation +should be used. @item NOSTR The return value is a locale-specific translation of the negative response to a yes/no question. What is said for @code{YESSTR} is also true here. + +The use of this symbol is deprecated. Instead message translation +should be used. @end vtable The file @file{langinfo.h} defines a lot more symbols but none of them diff --git a/manual/memory.texi b/manual/memory.texi index 6d86f55..cca8e81 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -663,7 +663,9 @@ valloc (size_t size) return memalign (getpagesize (), size); @} @end smallexample -@c !!! xref getpagesize + +@ref{Query Memory Parameters} for more information about the memory +subsystem. @end deftypefun @node Malloc Tunable Parameters diff --git a/manual/nss.texi b/manual/nss.texi index 3037645..a3eed74 100644 --- a/manual/nss.texi +++ b/manual/nss.texi @@ -364,7 +364,7 @@ Sun's NSS modules are usable as modules which get indirectly loaded only. The NSS modules in the GNU C Library are prepared to be used as normal -libraries themselves. This is @emph{not} true at the moment, though. +libraries themselves. This is @emph{not} true at the moment, though. However, the organization of the name space in the modules does not make it impossible like it is for Solaris. Now you can see why the modules are still libraries.@footnote{There is a second explanation: we were too @@ -404,11 +404,7 @@ change of the return value and the omission of the @var{result} parameter. While the user-level function returns a pointer to the result the reentrant function return an @code{enum nss_status} value: -@vindex NSS_STATUS_TRYAGAIN -@vindex NSS_STATUS_UNAVAIL -@vindex NSS_STATUS_NOTFOUND -@vindex NSS_STATUS_SUCCESS -@ftable @code +@vtable @code @item NSS_STATUS_TRYAGAIN numeric value @code{-2} @@ -420,7 +416,7 @@ numeric value @code{0} @item NSS_STATUS_SUCCESS numeric value @code{1} -@end ftable +@end vtable @noindent Now you see where the action items of the @file{/etc/nsswitch.conf} file diff --git a/manual/resource.texi b/manual/resource.texi index 5afc843..3aa3f16 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -9,6 +9,8 @@ limits on future usage. * Resource Usage:: Measuring various resources used. * Limits on Resources:: Specifying limits on resource usage. * Priority:: Reading or setting process run priority. +* Memory Resources:: Querying memory available resources. +* Processor Resources:: Learn about the processors available. @end menu @@ -431,8 +433,9 @@ above do. The functions above are better choices. @code{ulimit} and the command symbols are declared in @file{ulimit.h}. @pindex ulimit.h -@comment ulimit.h +@comment ulimit.h +@comment BSD @deftypefun int ulimit (int @var{cmd}, ...) @code{ulimit} gets the current limit or sets the current and maximum @@ -475,10 +478,10 @@ A process tried to increase a maximum limit, but is not superuser. @end deftypefun @code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}. -@comment sys/vlimit.h @pindex sys/vlimit.h -@comment BSD +@comment sys/vlimit.h +@comment BSD @deftypefun int vlimit (int @var{resource}, int @var{limit}) @code{vlimit} sets the current limit for a resource for a process. @@ -666,7 +669,7 @@ most important feature of the absolute priority: its absoluteness. @node Realtime Scheduling @subsection Realtime Scheduling -@comment realtime scheduling +@cindex realtime scheduling Whenever two processes with the same absolute priority are ready to run, the kernel has a decision to make, because only one can run at a time. @@ -1122,19 +1125,17 @@ runs from @code{-20} to @code{20}. A lower nice value corresponds to higher priority for the process. These constants describe the range of priority values: -@table @code +@vtable @code @comment sys/resource.h @comment BSD @item PRIO_MIN -@vindex PRIO_MIN The lowest valid nice value. @comment sys/resource.h @comment BSD @item PRIO_MAX -@vindex PRIO_MAX The highest valid nice value. -@end table +@end vtable @comment sys/resource.h @comment BSD,POSIX @@ -1198,34 +1199,30 @@ The arguments @var{class} and @var{id} together specify a set of processes in which you are interested. These are the possible values of @var{class}: -@table @code +@vtable @code @comment sys/resource.h @comment BSD @item PRIO_PROCESS -@vindex PRIO_PROCESS One particular process. The argument @var{id} is a process ID (pid). @comment sys/resource.h @comment BSD @item PRIO_PGRP -@vindex PRIO_PGRP All the processes in a particular process group. The argument @var{id} is a process group ID (pgid). @comment sys/resource.h @comment BSD @item PRIO_USER -@vindex PRIO_USER All the processes owned by a particular user (i.e. whose real uid indicates the user). The argument @var{id} is a user ID (uid). -@end table +@end vtable If the argument @var{id} is 0, it stands for the calling process, its process group, or its owner (real uid), according to @var{class}. -@c ??? I don't know where we should say this comes from. -@comment Unix -@comment dunno.h +@comment unistd.h +@comment BSD @deftypefun int nice (int @var{increment}) Increment the nice value of the calling process by @var{increment}. The return value is the same as for @code{setpriority}. @@ -1241,3 +1238,166 @@ nice (int increment) @} @end smallexample @end deftypefun + +@node Memory Resources +@section Querying memory available resources + +The amount of memory available in the system and the way it is organized +determines oftentimes the way programs can and have to work. For +functions like @code{mman} it is necessary to know about the size of +individual memory pages and knowing how much memory is available enables +a program to select appropriate sizes for, say, caches. Before we get +into these details a few words about memory subsystems in traditional +Unix systems. + +@menu +* Memory Subsystem:: Overview about traditional Unix memory handling. +* Query Memory Parameters:: How to get information about the memory + subsystem? +@end menu + +@node Memory Subsystem +@subsection Overview about traditional Unix memory handling + +@cindex address space +@cindex physical memory +@cindex physical address +Unix systems normally provide processes virtual address spaces. This +means that the addresses of the memory regions do not have to correspond +directly to the addresses of the actual physical memory which stores the +data. An extra level of indirection is introduced which translates +virtual addresses into physical addresses. This is normally done by the +hardware of the processor. + +@cindex shared memory +Using a virtual address space has several advantage. The most important +is process isolation. The different processes running on the system +cannot interfere directly with each other. No process can write into +the address space of another process (except when shared memory is used +but then it is wanted and controlled). + +Another advantage of virtual memory is that the address space the +processes see can actually be larger than the physical memory available. +The physical memory can be extended by storage on an external media +where the content of currently unused memory regions is stored. The +address translation can then intercept accesses to these memory regions +and make memory content available again by loading the data back into +memory. This concept makes it necessary that programs which have to use +lots of memory know the difference between available virtual address +space and available physical memory. If the working set of virtual +memory of all the processes is larger than the available physical memory +the system will slow down dramatically due to constant swapping of +memory content from the memory to the storage media and back. This is +called ``thrashing''. +@cindex thrashing + +@cindex memory page +@cindex page, memory +A final aspect of virtual memory which is important and follows from +what is said in the last paragraph is the granularity of the virtual +address space handling. When we said that the virtual address handling +stores memory content externally it cannot do this on a byte-by-byte +basis. The administrative overhead does not allow this (leaving alone +the processor hardware). Instead several thousand bytes are handled +together and form a @dfn{page}. The size of each page is always a power +of two byte. The smallest page size in use today is 4096, with 8192, +16384, and 65536 being other popular sizes. + +@node Query Memory Parameters +@subsection How to get information about the memory subsystem? + +The page size of the virtual memory the process sees is essential to +know in several situations. Some programming interface (e.g., +@code{mmap}, @pxref{Memory-mapped I/O}) require the user to provide +information adjusted to the page size. In the case of @code{mmap} is it +necessary to provide a length argument which is a multiple of the page +size. Another place where the knowledge about the page size is useful +is in memory allocation. If one allocates pieces of memory in larger +chunks which are then subdivided by the application code it is useful to +adjust the size of the larger blocks to the page size. If the total +memory requirement for the block is close (but not larger) to a multiple +of the page size the kernel's memory handling can work more effectively +since it only has to allocate memory pages which are fully used. (To do +this optimization it is necessary to know a bit about the memory +allocator which will require a bit of memory itself for each block and +this overhead must not push the total size over the page size multiple. + +The page size traditionally was a compile time constant. But recent +development of processors changed this. Processors now support +different page sizes and they can possibly even vary among different +processes on the same system. Therefore the system should be queried at +runtime about the current page size and no assumptions (except about it +being a power of two) should be made. + +@vindex _SC_PAGESIZE +The correct interface to query about the page size is @code{sysconf} +(@pxref{Sysconf Definition}) with the parameter @code{_SC_PAGESIZE}. +There is a much older interface available, too. + +@comment unistd.h +@comment BSD +@deftypefun int getpagesize (void) +The @code{getpagesize} function returns the page size of the process. +This value is fixed for the runtime of the process but can vary in +different runs of the application. + +The function is declared in @file{unistd.h}. +@end deftypefun + +Widely available on @w{System V} derived systems is a method to get +information about the physical memory the system has. The call + +@vindex _SC_PHYS_PAGES +@cindex sysconf +@smallexample + sysconf (_SC_PHYS_PAGES) +@end smallexample + +@noindent returns the total number of page of physical the system has. +This does not mean all this memory is available. This information can +be found using + +@vindex _SC_AVPHYS_PAGES +@cindex sysconf +@smallexample + sysconf (_SC_AVPHYS_PAGES) +@end smallexample + +These two values help to optimize applications. The value returned for +@code{_SC_AVPHYS_PAGES} is the amount of memory the application can use +without hindering any other process (given that no other process +increases its memory usage). The value returned for +@code{_SC_PHYS_PAGES} is more or less a hard limit for the working set. +If all applications together constantly use more than that amount of +memory the system is in trouble. + +@node Processor Resources +@section Learn about the processors available + +The use of threads or processes with shared memory allows an application +to take advantage of all the processing power a system can provide. If +the task can be parallelized the optimal way to write an application is +to have at any time as many processes running as there are processors. +To determine the number of processors available to the system one can +run + +@vindex _SC_NPROCESSORS_CONF +@cindex sysconf +@smallexample + sysconf (_SC_NPROCESSORS_CONF) +@end smallexample + +@noindent +which returns the number of processors the operating system configured. +But it might be possible for the operating system to disable individual +processors and so the call + +@vindex _SC_NPROCESSORS_ONLN +@cindex sysconf +@smallexample + sysconf (_SC_NPROCESSORS_ONLN) +@end smallexample + +@noindent +returns the number of processors which are currently inline (i.e., +available). diff --git a/manual/time.texi b/manual/time.texi index 154b667..62c7b5f 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -169,7 +169,7 @@ timeval_subtract (result, x, y) @} @end smallexample -Common functions that use @code{struct timeval} are @code{gettimeofday} +Common functions that use @code{struct timeval} are @code{gettimeofday} and @code{settimeofday}. @@ -2341,9 +2341,8 @@ The return value and error conditions are the same as for @code{setitimer}. @comment sys/time.h @comment BSD -@table @code +@vtable @code @item ITIMER_REAL -@findex ITIMER_REAL This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the real-time timer. @@ -2351,7 +2350,6 @@ timer. @comment sys/time.h @comment BSD @item ITIMER_VIRTUAL -@findex ITIMER_VIRTUAL This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the virtual timer. @@ -2359,11 +2357,10 @@ timer. @comment sys/time.h @comment BSD @item ITIMER_PROF -@findex ITIMER_PROF This constant can be used as the @var{which} argument to the @code{setitimer} and @code{getitimer} functions to specify the profiling timer. -@end table +@end vtable @comment unistd.h @comment POSIX.1 @@ -2484,7 +2481,7 @@ The function returns as *@code{remaining} the elapsed time left in the interval for which you requested to sleep. If the interval completed without getting interrupted by a signal, this is zero. -@code{struct timespec} is described in @xref{Elapsed Time}. +@code{struct timespec} is described in @xref{Elapsed Time}. If the function returns because the interval is over the return value is zero. If the function returns @math{-1} the global variable @var{errno} @@ -2513,5 +2510,3 @@ be protected using cancellation handlers. The @code{nanosleep} function is declared in @file{time.h}. @end deftypefun - - |