diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 2 | ||||
| -rw-r--r-- | manual/arith.texi | 28 | ||||
| -rw-r--r-- | manual/creature.texi | 62 | ||||
| -rw-r--r-- | manual/crypt.texi | 10 | ||||
| -rw-r--r-- | manual/freemanuals.texi | 5 | ||||
| -rw-r--r-- | manual/install-plain.texi | 5 | ||||
| -rw-r--r-- | manual/install.texi | 28 | ||||
| -rw-r--r-- | manual/job.texi | 35 | ||||
| -rw-r--r-- | manual/libc.texinfo | 1 | ||||
| -rw-r--r-- | manual/llio.texi | 31 | ||||
| -rw-r--r-- | manual/maint.texi | 8 | ||||
| -rw-r--r-- | manual/math.texi | 80 | ||||
| -rw-r--r-- | manual/memory.texi | 96 | ||||
| -rw-r--r-- | manual/pattern.texi | 7 | ||||
| -rw-r--r-- | manual/probes.texi | 370 | ||||
| -rw-r--r-- | manual/socket.texi | 27 | ||||
| -rw-r--r-- | manual/startup.texi | 3 | ||||
| -rw-r--r-- | manual/string.texi | 10 | ||||
| -rw-r--r-- | manual/texinfo.tex | 154 | ||||
| -rw-r--r-- | manual/threads.texi | 4 | ||||
| -rw-r--r-- | manual/time.texi | 88 |
21 files changed, 817 insertions, 237 deletions
diff --git a/manual/Makefile b/manual/Makefile index 44c0fd4f68..7bb419aea4 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -42,7 +42,7 @@ chapters = $(addsuffix .texi, \ message search pattern io stdio llio filesys \ pipe socket terminal syslog math arith time \ resource setjmp signal startup process job nss \ - users sysinfo conf crypt debug threads) + users sysinfo conf crypt debug threads probes) add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi)) appendices = lang.texi header.texi install.texi maint.texi platform.texi \ contrib.texi diff --git a/manual/arith.texi b/manual/arith.texi index 77056c3ea2..9cd61272d3 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -497,7 +497,8 @@ In the System V math library, the user-defined function @code{matherr} is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in -new programs. +new programs. When this interface is used, exceptions may not be +raised. @noindent The exceptions defined in @w{IEEE 754} are: @@ -806,7 +807,8 @@ an integer. Do not attempt to modify an @code{fexcept_t} variable. Many of the math functions are defined only over a subset of the real or complex numbers. Even if they are mathematically defined, their result may be larger or smaller than the range representable by their return -type. These are known as @dfn{domain errors}, @dfn{overflows}, and +type without loss of accuracy. These are known as @dfn{domain errors}, +@dfn{overflows}, and @dfn{underflows}, respectively. Math functions do several things when one of these errors occurs. In this manual we will refer to the complete response as @dfn{signalling} a domain error, overflow, or @@ -816,11 +818,20 @@ When a math function suffers a domain error, it raises the invalid exception and returns NaN. It also sets @var{errno} to @code{EDOM}; this is for compatibility with old systems that do not support @w{IEEE 754} exception handling. Likewise, when overflow occurs, math -functions raise the overflow exception and return @math{@infinity{}} or -@math{-@infinity{}} as appropriate. They also set @var{errno} to -@code{ERANGE}. When underflow occurs, the underflow exception is -raised, and zero (appropriately signed) is returned. @var{errno} may be -set to @code{ERANGE}, but this is not guaranteed. +functions raise the overflow exception and, in the default rounding +mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate +(in other rounding modes, the largest finite value of the appropriate +sign is returned when appropriate for that rounding mode). They also +set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or +@math{-@infinity{}}; @var{errno} may or may not be set to +@code{ERANGE} when a finite value is returned on overflow. When +underflow occurs, the underflow exception is raised, and zero +(appropriately signed) or a subnormal value, as appropriate for the +mathematical result of the function and the rounding mode, is +returned. @var{errno} may be set to @code{ERANGE}, but this is not +guaranteed; it is intended that @theglibc{} should set it when the +underflow is to an appropriately signed zero, but not necessarily for +other underflows. Some of the math functions are defined mathematically to result in a complex value over parts of their domains. The most familiar example of @@ -2455,7 +2466,8 @@ is provided mostly for compatibility with existing code; using @Theglibc{} also provides @samp{_l} versions of these functions, which take an additional argument, the locale to use in conversion. -@xref{Parsing of Integers}. + +See also @ref{Parsing of Integers}. @node System V Number Conversion @section Old-fashioned System V number-to-string functions diff --git a/manual/creature.texi b/manual/creature.texi index 1bf53147ee..bbf16b7f27 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -77,24 +77,6 @@ edition is made available. @defvr Macro _BSD_SOURCE If you define this macro, functionality derived from 4.3 BSD Unix is included as well as the @w{ISO C}, POSIX.1, and POSIX.2 material. - -Some of the features derived from 4.3 BSD Unix conflict with the -corresponding features specified by the POSIX.1 standard. If this -macro is defined, the 4.3 BSD definitions take precedence over the -POSIX definitions. - -Due to the nature of some of the conflicts between 4.3 BSD and POSIX.1, -you need to use a special @dfn{BSD compatibility library} when linking -programs compiled for BSD compatibility. This is because some functions -must be defined in two different ways, one of them in the normal C -library, and one of them in the compatibility library. If your program -defines @code{_BSD_SOURCE}, you must give the option @samp{-lbsd-compat} -to the compiler or linker when linking the program, to tell it to find -functions in this special compatibility library before looking for them in -the normal C library. -@pindex -lbsd-compat -@pindex bsd-compat -@cindex BSD compatibility library. @end defvr @comment (none) @@ -204,21 +186,21 @@ If you define this macro, everything is included: @w{ISO C89}, @w{ISO C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In the cases where POSIX.1 conflicts with BSD, the POSIX definitions take precedence. +@end defvr -If you want to get the full effect of @code{_GNU_SOURCE} but make the -BSD definitions take precedence over the POSIX definitions, use this -sequence of definitions: - -@smallexample -#define _GNU_SOURCE -#define _BSD_SOURCE -#define _SVID_SOURCE -@end smallexample - -Note that if you do this, you must link your program with the BSD -compatibility library by passing the @samp{-lbsd-compat} option to the -compiler or linker. @strong{NB:} If you forget to do this, you may -get very strange errors at run time. +@comment (none) +@comment GNU +@defvr Macro _DEFAULT_SOURCE +If you define this macro, most features are included apart from +X/Open, LFS and GNU extensions; the effect is similar to defining +@code{_POSIX_C_SOURCE} to @code{200809L} and @code{_POSIX_SOURCE}, +@code{_SVID_SOURCE}, and @code{_BSD_SOURCE} to 1. Defining this +macro, on its own and without using compiler options such as +@option{-ansi} or @option{-std=c99}, has the same effect as not +defining any feature test macros; defining it together with other +feature test macros, or when options such as @option{-ansi} are used, +enables those features even when the other options would otherwise +cause them to be disabled. @end defvr @comment (none) @@ -237,10 +219,10 @@ it must have been specified to compile as thread safe. @end defvr We recommend you use @code{_GNU_SOURCE} in new programs. If you don't -specify the @samp{-ansi} option to GCC and don't define any of these -macros explicitly, the effect is the same as defining -@code{_POSIX_C_SOURCE} to 2 and @code{_POSIX_SOURCE}, -@code{_SVID_SOURCE}, and @code{_BSD_SOURCE} to 1. +specify the @samp{-ansi} option to GCC, or other conformance options +such as @option{-std=c99}, and don't define any of these macros +explicitly, the effect is the same as defining @code{_DEFAULT_SOURCE} +to 1. When you define a feature test macro to request a larger class of features, it is harmless to define in addition a feature test macro for a subset of @@ -248,11 +230,3 @@ those features. For example, if you define @code{_POSIX_C_SOURCE}, then defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or @code{_POSIX_C_SOURCE} or @code{_SVID_SOURCE} as well has no effect. - -Note, however, that the features of @code{_BSD_SOURCE} are not a subset of -any of the other feature test macros supported. This is because it defines -BSD features that take precedence over the POSIX features that are -requested by the other macros. For this reason, defining -@code{_BSD_SOURCE} in addition to the other feature test macros does have -an effect: it causes the BSD features to take priority over the conflicting -POSIX features. diff --git a/manual/crypt.texi b/manual/crypt.texi index ef905904ca..9c65b9535e 100644 --- a/manual/crypt.texi +++ b/manual/crypt.texi @@ -30,8 +30,15 @@ message-digest algorithm that is compatible with modern BSD systems, and the other based on the Data Encryption Standard (DES) that is compatible with Unix systems. +@vindex AUTH_DES +@cindex FIPS 140-2 It also provides support for Secure RPC, and some library functions that -can be used to perform normal DES encryption. +can be used to perform normal DES encryption. The @code{AUTH_DES} +authentication flavor in Secure RPC, as provided by @theglibc{}, +uses DES and does not comply with FIPS 140-2 nor does any other use of DES +within @theglibc{}. It is recommended that Secure RPC should not be used +for systems that need to comply with FIPS 140-2 since all flavors of +encrypted authentication use normal DES. @menu * Legal Problems:: This software can get you locked up, or worse. @@ -203,6 +210,7 @@ header @file{crypt.h}. @node DES Encryption @section DES Encryption +@cindex FIPS 46-3 The Data Encryption Standard is described in the US Government Federal Information Processing Standards (FIPS) 46-3 published by the National Institute of Standards and Technology. The DES has been very thoroughly diff --git a/manual/freemanuals.texi b/manual/freemanuals.texi index a424e8aa3e..9caf22017c 100644 --- a/manual/freemanuals.texi +++ b/manual/freemanuals.texi @@ -1,4 +1,7 @@ -@appendix Free Software Needs Free Documentation +@c freemanuals.texi - blurb for free documentation. +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + @cindex free documentation The biggest deficiency in the free software community today is not in diff --git a/manual/install-plain.texi b/manual/install-plain.texi new file mode 100644 index 0000000000..c5179e780c --- /dev/null +++ b/manual/install-plain.texi @@ -0,0 +1,5 @@ +@c This is for making the `INSTALL' file for the distribution. +@c Makeinfo ignores it when processing the file from the include. +@setfilename INSTALL +@set plain +@include install.texi diff --git a/manual/install.texi b/manual/install.texi index 4575d22319..c0b8d9e134 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -1,10 +1,10 @@ -@c This is for making the `INSTALL' file for the distribution. -@c Makeinfo ignores it when processing the file from the include. -@setfilename INSTALL @include macros.texi @include pkgvers.texi +@ifclear plain @node Installation, Maintenance, Library Summary, Top +@end ifclear + @c %MENU% How to install the GNU C Library @appendix Installing @theglibc{} @@ -21,6 +21,7 @@ to activate them, and they will be compiled into the library. You will need recent versions of several GNU tools: definitely GCC and GNU Make, and possibly others. @xref{Tools for Compilation}, below. +@ifclear plain @menu * Configuring and compiling:: How to compile and test GNU libc. * Running make install:: How to install it once you've got it @@ -29,6 +30,7 @@ GNU Make, and possibly others. @xref{Tools for Compilation}, below. * Linux:: Specific advice for GNU/Linux systems. * Reporting Bugs:: So they'll get fixed. @end menu +@end ifclear @node Configuring and compiling @appendixsec Configuring and compiling @theglibc{} @@ -138,11 +140,6 @@ linker. Don't build libraries with profiling information. You may want to use this option if you don't plan to do profiling. -@item --disable-versioning -Don't compile the shared libraries with symbol version information. -Doing this will make the resulting library incompatible with old -binaries, so it's not recommended. - @item --enable-static-nss Compile static versions of the NSS (Name Service Switch) libraries. This is not recommended because it defeats the purpose of NSS; a program @@ -325,14 +322,11 @@ can dramatically improve performance with NIS+, and may help with DNS as well. One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid -@code{root}. This program is invoked by the @code{grantpt} function; it -sets the permissions on a pseudoterminal so it can be used by the -calling process. This means programs like @code{xterm} and -@code{screen} do not have to be setuid to get a pty. (There may be -other reasons why they need privileges.) If you are using a -Linux kernel with the @code{devptsfs} or @code{devfs} filesystems -providing pty slaves, you don't need this program; otherwise you do. -The source for @file{pt_chown} is in @file{login/programs/pt_chown.c}. +@code{root} if the @samp{--enable-pt_chown} configuration option is used. +This program is invoked by the @code{grantpt} function; it sets the +permissions on a pseudoterminal so it can be used by the calling process. +If you are using a Linux kernel with the @code{devpts} filesystem enabled +and mounted at @file{/dev/pts}, you don't need this program. After installation you might want to configure the timezone and locale installation of your system. @Theglibc{} comes with a locale @@ -421,7 +415,7 @@ should definitely upgrade @code{sed}. @end itemize @noindent -If you change any of the @file{configure.in} files you will also need +If you change any of the @file{configure.ac} files you will also need @itemize @bullet @item diff --git a/manual/job.texi b/manual/job.texi index 4efeed3451..d58dcd8c8f 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1118,39 +1118,18 @@ from the calling process. @end table @end deftypefun -The @code{getpgrp} function has two definitions: one derived from BSD -Unix, and one from the POSIX.1 standard. The feature test macros you -have selected (@pxref{Feature Test Macros}) determine which definition -you get. Specifically, you get the BSD version if you define -@code{_BSD_SOURCE}; otherwise, you get the POSIX version if you define -@code{_POSIX_SOURCE} or @code{_GNU_SOURCE}. Programs written for old -BSD systems will not include @file{unistd.h}, which defines -@code{getpgrp} specially under @code{_BSD_SOURCE}. You must link such -programs with the @code{-lbsd-compat} option to get the BSD definition.@refill -@pindex -lbsd-compat -@pindex bsd-compat -@cindex BSD compatibility library - @comment unistd.h @comment POSIX.1 -@deftypefn {POSIX.1 Function} pid_t getpgrp (void) -The POSIX.1 definition of @code{getpgrp} returns the process group ID of +@deftypefun pid_t getpgrp (void) +The @code{getpgrp} function returns the process group ID of the calling process. -@end deftypefn - -@comment unistd.h -@comment BSD -@deftypefn {BSD Function} pid_t getpgrp (pid_t @var{pid}) -The BSD definition of @code{getpgrp} returns the process group ID of the -process @var{pid}. You can supply a value of @code{0} for the @var{pid} -argument to get information about the calling process. -@end deftypefn +@end deftypefun @comment unistd.h -@comment SVID -@deftypefn {System V Function} int getpgid (pid_t @var{pid}) +@comment POSIX.1 +@deftypefun int getpgid (pid_t @var{pid}) -@code{getpgid} is the same as the BSD function @code{getpgrp}. It +The @code{getpgid} function returns the process group ID of the process @var{pid}. You can supply a value of @code{0} for the @var{pid} argument to get information about the calling process. @@ -1166,7 +1145,7 @@ different sessions, and the implementation doesn't allow to access the process group ID of the process with ID @var{pid} from the calling process. @end table -@end deftypefn +@end deftypefun @comment unistd.h @comment POSIX.1 diff --git a/manual/libc.texinfo b/manual/libc.texinfo index 4505d270b4..96cd380ce3 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -118,6 +118,7 @@ of @theglibc{}. @include chapters.texi @node Free Manuals, Copying, Contributors, Top +@appendix Free Software Needs Free Documentation @include freemanuals.texi @node Copying, Documentation License, Free Manuals, Top diff --git a/manual/llio.texi b/manual/llio.texi index b129cf40bd..b6c926060e 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -1226,8 +1226,8 @@ as the included @code{malloc} automatically uses @code{mmap} where appropriate. @end vtable -@code{mmap} returns the address of the new mapping, or @math{-1} for an -error. +@code{mmap} returns the address of the new mapping, or +@code{MAP_FAILED} for an error. Possible errors include: @@ -1471,6 +1471,33 @@ There is no existing mapping in at least part of the given region. @end table @end deftypefun +@comment sys/mman.h +@comment POSIX +@deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode}) + +This function returns a file descriptor that can be used to allocate shared +memory via mmap. Unrelated processes can use same @var{name} to create or +open existing shared memory objects. + +A @var{name} argument specifies the shared memory object to be opened. +In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting +with an optional slash but containing no other slashes. + +The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}. + +@code{shm_open} returns the file descriptor on success or @math{-1} on error. +On failure @code{errno} is set. +@end deftypefn + +@deftypefn Function int shm_unlink (const char *@var{name}) + +This function is inverse of @code{shm_open} and removes the object with +the given @var{name} previously created by @code{shm_open}. + +@code{shm_unlink} returns @math{0} on success or @math{-1} on error. +On failure @code{errno} is set. +@end deftypefn + @node Waiting for I/O @section Waiting for Input or Output @cindex waiting for input or output diff --git a/manual/maint.texi b/manual/maint.texi index 0f4b959815..659ceae011 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -316,7 +316,7 @@ This file is a shell script fragment to be run at configuration time. The top-level @file{configure} script uses the shell @code{.} command to read the @file{configure} file in each system-dependent directory chosen, in order. The @file{configure} files are often generated from -@file{configure.in} files using Autoconf. +@file{configure.ac} files using Autoconf. A system-dependent @file{configure} script will usually add things to the shell variables @samp{DEFS} and @samp{config_vars}; see the @@ -329,14 +329,14 @@ shell variable @w{@samp{with_@var{package}}} (with any dashes in just @w{@samp{--with-@var{package}}} (no argument), then it sets @w{@samp{with_@var{package}}} to @samp{yes}. -@item configure.in +@item configure.ac This file is an Autoconf input fragment to be processed into the file @file{configure} in this subdirectory. @xref{Introduction,,, autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, for a description of Autoconf. You should write either @file{configure} -or @file{configure.in}, but not both. The first line of -@file{configure.in} should invoke the @code{m4} macro +or @file{configure.ac}, but not both. The first line of +@file{configure.ac} should invoke the @code{m4} macro @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls for Autoconf macros which are used by the top-level @file{configure} script; without this, those macros might be invoked again unnecessarily diff --git a/manual/math.texi b/manual/math.texi index 193d415fba..5e7c90e2e6 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -1227,10 +1227,80 @@ $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$ @noindent where @math{p} is the number of bits in the mantissa of the floating-point number representation. Ideally the error for all -functions is always less than 0.5ulps. Using rounding bits this is also -possible and normally implemented for the basic operations. To achieve -the same for the complex math functions requires a lot more work and -this has not yet been done. +functions is always less than 0.5ulps in round-to-nearest mode. Using +rounding bits this is also +possible and normally implemented for the basic operations. Except +for certain functions such as @code{sqrt}, @code{fma} and @code{rint} +whose results are fully specified by reference to corresponding IEEE +754 floating-point operations, and conversions between strings and +floating point, @theglibc{} does not aim for correctly rounded results +for functions in the math library, and does not aim for correctness in +whether ``inexact'' exceptions are raised. Instead, the goals for +accuracy of functions without fully specified results are as follows; +some functions have bugs meaning they do not meet these goals in all +cases. In future, @theglibc{} may provide some other correctly +rounding functions under the names such as @code{crsin} proposed for +an extension to ISO C. + +@itemize @bullet + +@item +Each function with a floating-point result behaves as if it computes +an infinite-precision result that is within a few ulp (in both real +and complex parts, for functions with complex results) of the +mathematically correct value of the function (interpreted together +with ISO C or POSIX semantics for the function in question) at the +exact value passed as the input. Exceptions are raised appropriately +for this value and in accordance with IEEE 754 / ISO C / POSIX +semantics, and it is then rounded according to the current rounding +direction to the result that is returned to the user. @code{errno} +may also be set (@pxref{Math Error Reporting}). + +@item +For the IBM @code{long double} format, as used on PowerPC GNU/Linux, +the accuracy goal is weaker for input values not exactly representable +in 106 bits of precision; it is as if the input value is some value +within 0.5ulp of the value actually passed, where ``ulp'' is +interpreted in terms of a fixed-precision 106-bit mantissa, but not +necessarily the exact value actually passed with discontiguous +mantissa bits. + +@item +Functions behave as if the infinite-precision result computed is zero, +infinity or NaN if and only if that is the mathematically correct +infinite-precision result. They behave as if the infinite-precision +result computed always has the same sign as the mathematically correct +result. + +@item +If the mathematical result is more than a few ulp above the overflow +threshold for the current rounding direction, the value returned is +the appropriate overflow value for the current rounding direction, +with the overflow exception raised. + +@item +If the mathematical result has magnitude well below half the least +subnormal magnitude, the returned value is either zero or the least +subnormal (in each case, with the correct sign), according to the +current rounding direction and with the underflow exception raised. + +@item +Where the mathematical result underflows and is not exactly +representable as a floating-point value, the underflow exception is +raised (so there may be spurious underflow exceptions in cases where +the underflowing result is exact, but not missing underflow exceptions +in cases where it is inexact). + +@item +@Theglibc{} does not aim for functions to satisfy other properties of +the underlying mathematical function, such as monotonicity, where not +implied by the above goals. + +@item +All the above applies to both real and complex parts, for complex +functions. + +@end itemize Therefore many of the functions in the math library have errors. The table lists the maximum error for each function which is exposed by one @@ -1364,7 +1434,7 @@ The prototypes for these functions are in @file{stdlib.h}. @comment BSD @deftypefun {long int} random (void) This function returns the next pseudo-random number in the sequence. -The value returned ranges from @code{0} to @code{RAND_MAX}. +The value returned ranges from @code{0} to @code{2147483647}. @strong{NB:} Temporarily this function was defined to return a @code{int32_t} value to indicate that the return value always contains diff --git a/manual/memory.texi b/manual/memory.texi index 0c3d39efa8..55a6a50ae6 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -355,7 +355,7 @@ it is: void * xmalloc (size_t size) @{ - register void *value = malloc (size); + void *value = malloc (size); if (value == 0) fatal ("virtual memory exhausted"); return value; @@ -371,7 +371,7 @@ a newly allocated null-terminated string: char * savestring (const char *ptr, size_t len) @{ - register char *value = (char *) xmalloc (len + 1); + char *value = (char *) xmalloc (len + 1); value[len] = '\0'; return (char *) memcpy (value, ptr, len); @} @@ -380,10 +380,10 @@ savestring (const char *ptr, size_t len) The block that @code{malloc} gives you is guaranteed to be aligned so that it can hold any type of data. On @gnusystems{}, the address is -always a multiple of eight on most systems, and a multiple of 16 on +always a multiple of eight on 32-bit systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page -boundary) necessary; for those cases, use @code{memalign}, -@code{posix_memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}). +boundary) necessary; for those cases, use @code{aligned_alloc} or +@code{posix_memalign} (@pxref{Aligned Memory Blocks}). Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another @@ -502,7 +502,7 @@ as @code{xmalloc} does for @code{malloc}: void * xrealloc (void *ptr, size_t size) @{ - register void *value = realloc (ptr, size); + void *value = realloc (ptr, size); if (value == 0) fatal ("Virtual memory exhausted"); return value; @@ -616,14 +616,31 @@ after calling @code{free} wastes memory. The size threshold for The address of a block returned by @code{malloc} or @code{realloc} in @gnusystems{} is always a multiple of eight (or sixteen on 64-bit systems). If you need a block whose address is a multiple of a higher -power of two than that, use @code{memalign}, @code{posix_memalign}, or -@code{valloc}. @code{memalign} is declared in @file{malloc.h} and -@code{posix_memalign} is declared in @file{stdlib.h}. +power of two than that, use @code{aligned_alloc} or @code{posix_memalign}. +@code{aligned_alloc} and @code{posix_memalign} are declared in +@file{stdlib.h}. + +@comment stdlib.h +@deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size}) +The @code{aligned_alloc} function allocates a block of @var{size} bytes whose +address is a multiple of @var{alignment}. The @var{alignment} must be a +power of two and @var{size} must be a multiple of @var{alignment}. -With @theglibc{}, you can use @code{free} to free the blocks that -@code{memalign}, @code{posix_memalign}, and @code{valloc} return. That -does not work in BSD, however---BSD does not provide any way to free -such blocks. +The @code{aligned_alloc} function returns a null pointer on error and sets +@code{errno} to one of the following values: + +@table @code +@item ENOMEM +There was insufficient memory available to satisfy the request. + +@item EINVAL +@var{alignment} is not a power of two. + +This function was introduced in @w{ISO C11} and hence may have better +portability to modern non-POSIX systems than @code{posix_memalign}. +@end table + +@end deftypefun @comment malloc.h @comment BSD @@ -633,6 +650,21 @@ address is a multiple of @var{boundary}. The @var{boundary} must be a power of two! The function @code{memalign} works by allocating a somewhat larger block, and then returning an address within the block that is on the specified boundary. + +The @code{memalign} function returns a null pointer on error and sets +@code{errno} to one of the following values: + +@table @code +@item ENOMEM +There was insufficient memory available to satisfy the request. + +@item EINVAL +@var{alignment} is not a power of two. + +@end table + +The @code{memalign} function is obsolete and @code{aligned_alloc} or +@code{posix_memalign} should be used instead. @end deftypefun @comment stdlib.h @@ -647,8 +679,20 @@ parameter @var{alignment}: the value must be a power of two multiple of If the function succeeds in allocation memory a pointer to the allocated memory is returned in @code{*@var{memptr}} and the return value is zero. Otherwise the function returns an error value indicating the problem. +The possible error values returned are: + +@table @code +@item ENOMEM +There was insufficient memory available to satisfy the request. + +@item EINVAL +@var{alignment} is not a power of two multiple of @code{sizeof (void *)}. -This function was introduced in POSIX 1003.1d. +@end table + +This function was introduced in POSIX 1003.1d. Although this function is +superseded by @code{aligned_alloc}, it is more portable to older POSIX +systems that do not support @w{ISO C11}. @end deftypefun @comment malloc.h stdlib.h @@ -667,6 +711,9 @@ valloc (size_t size) @ref{Query Memory Parameters} for more information about the memory subsystem. + +The @code{valloc} function is obsolete and @code{aligned_alloc} or +@code{posix_memalign} should be used instead. @end deftypefun @node Malloc Tunable Parameters @@ -902,16 +949,18 @@ memory consumption of the program. @comment malloc.h @comment GNU @defvar __memalign_hook -The value of this variable is a pointer to function that @code{memalign} -uses whenever it is called. You should define this function to look -like @code{memalign}; that is, like: +The value of this variable is a pointer to function that @code{aligned_alloc}, +@code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they +are called. You should define this function to look like @code{aligned_alloc}; +that is, like: @smallexample void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller}) @end smallexample The value of @var{caller} is the return address found on the stack when -the @code{memalign} function was called. This value allows you to trace the +the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or +@code{valloc} functions are called. This value allows you to trace the memory consumption of the program. @end defvar @@ -1118,6 +1167,14 @@ Space}. Allocate a block of @var{size} bytes, starting on a page boundary. @xref{Aligned Memory Blocks}. +@item void *aligned_alloc (size_t @var{size}, size_t @var{alignment}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + +@item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + @item void *memalign (size_t @var{size}, size_t @var{boundary}) Allocate a block of @var{size} bytes, starting on an address that is a multiple of @var{boundary}. @xref{Aligned Memory Blocks}. @@ -1140,7 +1197,8 @@ A pointer to a function that @code{realloc} uses whenever it is called. A pointer to a function that @code{free} uses whenever it is called. @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller}) -A pointer to a function that @code{memalign} uses whenever it is called. +A pointer to a function that @code{aligned_alloc}, @code{memalign}, +@code{posix_memalign} and @code{valloc} use whenever they are called. @item struct mallinfo mallinfo (void) Return information about the current dynamic memory usage. diff --git a/manual/pattern.texi b/manual/pattern.texi index 1966f3f148..afd6480926 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -36,11 +36,8 @@ returns the nonzero value @code{FNM_NOMATCH}. The arguments The argument @var{flags} is a combination of flag bits that alter the details of matching. See below for a list of the defined flags. -In @theglibc{}, @code{fnmatch} cannot experience an ``error''---it -always returns an answer for whether the match succeeds. However, other -implementations of @code{fnmatch} might sometimes report ``errors''. -They would do so by returning nonzero values that are not equal to -@code{FNM_NOMATCH}. +In @theglibc{}, @code{fnmatch} might sometimes report ``errors'' by +returning nonzero values that are not equal to @code{FNM_NOMATCH}. @end deftypefun These are the available flags for the @var{flags} argument: diff --git a/manual/probes.texi b/manual/probes.texi new file mode 100644 index 0000000000..25d06e5383 --- /dev/null +++ b/manual/probes.texi @@ -0,0 +1,370 @@ +@node Internal Probes +@c @node Internal Probes, , POSIX Threads, Top +@c %MENU% Probes to monitor libc internal behavior +@chapter Internal probes + +In order to aid in debugging and monitoring internal behavior, +@theglibc{} exposes nearly-zero-overhead SystemTap probes marked with +the @code{libc} provider. + +These probes are not part of the @glibcadj{} stable ABI, and they are +subject to change or removal across releases. Our only promise with +regard to them is that, if we find a need to remove or modify the +arguments of a probe, the modified probe will have a different name, so +that program monitors relying on the old probe will not get unexpected +arguments. + +@menu +* Memory Allocation Probes:: Probes in the memory allocation subsystem +* Mathematical Function Probes:: Probes in mathematical functions +@end menu + +@node Memory Allocation Probes +@section Memory Allocation Probes + +These probes are designed to signal relatively unusual situations within +the virtual memory subsystem of @theglibc{}. + +@deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after the main arena is extended by calling +@code{sbrk}. Argument @var{$arg1} is the additional size requested to +@code{sbrk}, and @var{$arg2} is the pointer that marks the end of the +@code{sbrk} area, returned in response to the request. +@end deftp + +@deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after the size of the main arena is decreased by +calling @code{sbrk}. Argument @var{$arg1} is the size released by +@code{sbrk} (the positive value, rather than the negative value passed +to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of +the @code{sbrk} area, returned in response to the request. +@end deftp + +@deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a new heap is @code{mmap}ed. Argument +@var{$arg1} is a pointer to the base of the memory area, where the +@code{heap_info} data structure is held, and @var{$arg2} is the size of +the heap. +@end deftp + +@deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered @emph{before} (unlike the other sbrk and heap +probes) a heap is completely removed via @code{munmap}. Argument +@var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the +heap. +@end deftp + +@deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a trailing portion of an @code{mmap}ed +heap is extended. Argument @var{$arg1} is a pointer to the heap, and +@var{$arg2} is the new size of the heap. +@end deftp + +@deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered after a trailing portion of an @code{mmap}ed +heap is released. Argument @var{$arg1} is a pointer to the heap, and +@var{$arg2} is the new size of the heap. +@end deftp + +@deftp Probe memory_malloc_retry (size_t @var{$arg1}) +@deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2}) +@deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2}) +@deftpx Probe memory_calloc_retry (size_t @var{$arg1}) +These probes are triggered when the corresponding functions fail to +obtain the requested amount of memory from the arena in use, before they +call @code{arena_get_retry} to select an alternate arena in which to +retry the allocation. Argument @var{$arg1} is the amount of memory +requested by the user; in the @code{calloc} case, that is the total size +computed from both function arguments. In the @code{realloc} case, +@var{$arg2} is the pointer to the memory area being resized. In the +@code{memalign} case, @var{$arg2} is the alignment to be used for the +request, which may be stricter than the value passed to the +@code{memalign} function. A @code{memalign} probe is also used by functions +@code{posix_memalign, valloc} and @code{pvalloc}. + +Note that the argument order does @emph{not} match that of the +corresponding two-argument functions, so that in all of these probes the +user-requested allocation size is in @var{$arg1}. +@end deftp + +@deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2}) +This probe is triggered within @code{arena_get_retry} (the function +called to select the alternate arena in which to retry an allocation +that failed on the first attempt), before the selection of an alternate +arena. This probe is redundant, but much easier to use when it's not +important to determine which of the various memory allocation functions +is failing to allocate on the first try. Argument @var{$arg1} is the +same as in the function-specific probes, except for extra room for +padding introduced by functions that have to ensure stricter alignment. +Argument @var{$arg2} is the arena in which allocation failed. +@end deftp + +@deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2}) +This probe is triggered when @code{malloc} allocates and initializes an +additional arena (not the main arena), but before the arena is assigned +to the running thread or inserted into the internal linked list of +arenas. The arena's @code{malloc_state} internal data structure is +located at @var{$arg1}, within a newly-allocated heap big enough to hold +at least @var{$arg2} bytes. +@end deftp + +@deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2}) +This probe is triggered when @code{malloc} has just selected an existing +arena to reuse, and (temporarily) reserved it for exclusive use. +Argument @var{$arg1} is a pointer to the newly-selected arena, and +@var{$arg2} is a pointer to the arena previously used by that thread. + +This occurs within +@code{reused_arena}, right after the mutex mentioned in probe +@code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will +point to the same arena. In this configuration, this will usually only +occur once per thread. The exception is when a thread first selected +the main arena, but a subsequent allocation from it fails: then, and +only then, may we switch to another arena to retry that allocations, and +for further allocations within that thread. +@end deftp + +@deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3}) +This probe is triggered when @code{malloc} is about to wait for an arena +to become available for reuse. Argument @var{$arg1} holds a pointer to +the mutex the thread is going to wait on, @var{$arg2} is a pointer to a +newly-chosen arena to be reused, and @var{$arg3} is a pointer to the +arena previously used by that thread. + +This occurs within +@code{reused_arena}, when a thread first tries to allocate memory or +needs a retry after a failure to allocate from the main arena, there +isn't any free arena, the maximum number of arenas has been reached, and +an existing arena was chosen for reuse, but its mutex could not be +immediately acquired. The mutex in @var{$arg1} is the mutex of the +selected arena. +@end deftp + +@deftp Probe memory_arena_reuse_free_list (void *@var{$arg1}) +This probe is triggered when @code{malloc} has chosen an arena that is +in the free list for use by a thread, within the @code{get_free_list} +function. The argument @var{$arg1} holds a pointer to the selected arena. +@end deftp + +@deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2}) +This probe is triggered when function @code{mallopt} is called to change +@code{malloc} internal configuration parameters, before any change to +the parameters is made. The arguments @var{$arg1} and @var{$arg2} are +the ones passed to the @code{mallopt} function. +@end deftp + +@deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MXFAST}, and the requested +value is in an acceptable range. Argument @var{$arg1} is the requested +value, and @var{$arg2} is the previous value of this @code{malloc} +parameter. +@end deftp + +@deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggere shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_TRIM_THRESHOLD}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_TOP_PAD}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, @var{$arg2} is the previous value of this @code{malloc} +parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment +was already disabled. +@end deftp + +@deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_MMAP_MAX}. Argument +@var{$arg1} is the requested value, @var{$arg2} is the previous value of +this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic +threshold adjustment was already disabled. +@end deftp + +@deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_CHECK_ACTION}. Argument +@var{$arg1} is the requested value, and @var{$arg2} is the previous +value of this @code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_PERTURB}. Argument +@var{$arg1} is the requested value, and @var{$arg2} is the previous +value of this @code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_ARENA_TEST}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, and @var{$arg2} is the previous value of this +@code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2}) +This probe is triggered shortly after the @code{memory_mallopt} probe, +when the parameter to be changed is @code{M_ARENA_MAX}, and the +requested value is in an acceptable range. Argument @var{$arg1} is the +requested value, and @var{$arg2} is the previous value of this +@code{malloc} parameter. +@end deftp + +@deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2}) +This probe is triggered when function @code{free} decides to adjust the +dynamic brk/mmap thresholds. Argument @var{$arg1} and @var{$arg2} are +the adjusted mmap and trim thresholds, respectively. +@end deftp + +@node Mathematical Function Probes +@section Mathematical Function Probes + +Some mathematical functions fall back to multiple precision arithmetic for +some inputs to get last bit precision for their return values. This multiple +precision fallback is much slower than the default algorithms and may have a +significant impact on application performance. The systemtap probe markers +described in this section may help you determine if your application calls +mathematical functions with inputs that may result in multiple-precision +arithmetic. + +Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of +precision in the mantissa of the multiple precision number. Hence, a precision +level of 32 implies 768 bits of precision in the mantissa. + +@deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{exp} function is called with an input that +results in multiple precision computation with precision 6. Argument +@var{$arg1} is the input value and @var{$arg2} is the computed output. +@end deftp + +@deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{exp} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input value and @var{$arg2} is the computed output. +@end deftp + +@deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is hit when the @code{pow} function is called with inputs that +result in multiple precision computation with precision 10. Arguments +@var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value +computed in the fast phase of the algorithm and @code{$arg4} is the final +accurate value. +@end deftp + +@deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is hit when the @code{pow} function is called with an input that +results in multiple precision computation with precision 32. Arguments +@var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value +computed in the fast phase of the algorithm and @code{$arg4} is the final +accurate value. +@end deftp + +@deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{log} function is called with an input that +results in multiple precision computation. Argument @var{$arg1} is the +precision with which the computation succeeded. Argument @var{$arg2} is the +input and @var{$arg3} is the computed output. +@end deftp + +@deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{log} function is called with an input that +results in multiple precision computation and none of the multiple precision +computations result in an accurate result. Argument @var{$arg1} is the maximum +precision with which computations were performed. Argument @var{$arg2} is the +input and @var{$arg3} is the computed output. +@end deftp + +@deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is hit when the @code{atan2} function is called with an input that +results in multiple precision computation. Argument @var{$arg1} is the +precision with which computation succeeded. Arguments @var{$arg2} and +@var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the +computed result. +@end deftp + +@deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4}) +This probe is hit when the @code{atan} function is called with an input that +results in multiple precision computation and none of the multiple precision +computations result in an accurate result. Argument @var{$arg1} is the maximum +precision with which computations were performed. Arguments @var{$arg2} and +@var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the +computed result. +@end deftp + +@deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{atan} function is called with an input that +results in multiple precision computation. Argument @var{$arg1} is the +precision with which computation succeeded. Argument @var{$arg2} is the +input to the @code{atan} function and @var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{atan} function is called with an input that +results in multiple precision computation and none of the multiple precision +computations result in an accurate result. Argument @var{$arg1} is the maximum +precision with which computations were performed. Argument @var{$arg2} is the +input to the @code{atan} function and @var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowtan (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{tan} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function and @var{$arg2} is the computed +result. +@end deftp + +@deftp Probe slowasin (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{asin} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function and @var{$arg2} is the computed +result. +@end deftp + +@deftp Probe slowacos (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{acos} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function and @var{$arg2} is the computed +result. +@end deftp + +@deftp Probe slowsin (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{sin} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function and @var{$arg2} is the computed +result. +@end deftp + +@deftp Probe slowcos (double @var{$arg1}, double @var{$arg2}) +This probe is hit when the @code{cos} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function and @var{$arg2} is the computed +result. +@end deftp + +@deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{sin} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function, @var{$arg2} is the error bound of +@var{$arg1} and @var{$arg3} is the computed result. +@end deftp + +@deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}) +This probe is hit when the @code{cos} function is called with an input that +results in multiple precision computation with precision 32. Argument +@var{$arg1} is the input to the function, @var{$arg2} is the error bound of +@var{$arg1} and @var{$arg3} is the computed result. +@end deftp diff --git a/manual/socket.texi b/manual/socket.texi index e187402abd..4c7e623b29 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -1290,37 +1290,42 @@ pointer and the size of the buffer in the @var{buf} and @var{buflen} parameters. A pointer to the buffer, in which the result is stored, is available in -@code{*@var{result}} after the function call successfully returned. If -an error occurs or if no entry is found, the pointer @code{*@var{result}} -is a null pointer. Success is signalled by a zero return value. If the -function failed the return value is an error number. In addition to the -errors defined for @code{gethostbyname} it can also be @code{ERANGE}. -In this case the call should be repeated with a larger buffer. -Additional error information is not stored in the global variable -@code{h_errno} but instead in the object pointed to by @var{h_errnop}. +@code{*@var{result}} after the function call successfully returned. The +buffer passed as the @var{buf} parameter can be freed only once the caller +has finished with the result hostent struct, or has copied it including all +the other memory that it points to. If an error occurs or if no entry is +found, the pointer @code{*@var{result}} is a null pointer. Success is +signalled by a zero return value. If the function failed the return value +is an error number. In addition to the errors defined for +@code{gethostbyname} it can also be @code{ERANGE}. In this case the call +should be repeated with a larger buffer. Additional error information is +not stored in the global variable @code{h_errno} but instead in the object +pointed to by @var{h_errnop}. Here's a small example: @smallexample struct hostent * gethostname (char *host) @{ - struct hostent hostbuf, *hp; + struct hostent *hostbuf, *hp; size_t hstbuflen; char *tmphstbuf; int res; int herr; + hostbuf = malloc (sizeof (struct hostent)); hstbuflen = 1024; - /* Allocate buffer, remember to free it to avoid memory leakage. */ tmphstbuf = malloc (hstbuflen); - while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen, + while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, &hp, &herr)) == ERANGE) @{ /* Enlarge the buffer. */ hstbuflen *= 2; tmphstbuf = realloc (tmphstbuf, hstbuflen); @} + + free (tmphstbuf); /* Check for errors. */ if (res || hp == NULL) return NULL; diff --git a/manual/startup.texi b/manual/startup.texi index a2777141c2..edd1de47be 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -625,7 +625,8 @@ basis there may be information that is not available any other way. This function is used to inquire about the entries in the auxiliary vector. The @var{type} argument should be one of the @samp{AT_} symbols defined in @file{elf.h}. If a matching entry is found, the value is -returned; if the entry is not found, zero is returned. +returned; if the entry is not found, zero is returned and @code{errno} is +set to @code{ENOENT}. @end deftypefun For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire diff --git a/manual/string.texi b/manual/string.texi index 2a164a9523..1e45d9ddbc 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -955,8 +955,8 @@ The @code{strncat} function could be implemented like this: char * strncat (char *to, const char *from, size_t size) @{ - to[strlen (to) + size] = '\0'; - strncpy (to + strlen (to), from, size); + memcpy (to + strlen (to), from, strnlen (from, size)); + to[strlen (to) + strnlen (from, size)] = '\0'; return to; @} @end group @@ -982,8 +982,8 @@ wchar_t * wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size) @{ - wto[wcslen (to) + size] = L'\0'; - wcsncpy (wto + wcslen (wto), wfrom, size); + memcpy (wto + wcslen (wto), wfrom, wcsnlen (wfrom, size) * sizeof (wchar_t)); + wto[wcslen (to) + wcsnlen (wfrom, size)] = '\0'; return wto; @} @end group @@ -1370,7 +1370,7 @@ int compare_elements (const void *v1, const void *v2) @{ char * const *p1 = v1; - char * const *p1 = v2; + char * const *p2 = v2; return strcoll (*p1, *p2); @} diff --git a/manual/texinfo.tex b/manual/texinfo.tex index 332943d9e6..a06709bedc 100644 --- a/manual/texinfo.tex +++ b/manual/texinfo.tex @@ -3,7 +3,7 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2013-06-21.17} +\def\texinfoversion{2013-11-26.10} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, @@ -281,9 +281,9 @@ \toks6=\expandafter{\prevsectiondefs}% \toks8=\expandafter{\lastcolordefs}% \mark{% - \the\toks0 \the\toks2 - \noexpand\or \the\toks4 \the\toks6 - \noexpand\else \the\toks8 + \the\toks0 \the\toks2 % 0: top marks (\last...) + \noexpand\or \the\toks4 \the\toks6 % 1: bottom marks (default, \prev...) + \noexpand\else \the\toks8 % 2: color marks }% } % \topmark doesn't work for the very first chapter (after the title @@ -322,10 +322,13 @@ % % Do this outside of the \shipout so @code etc. will be expanded in % the headline as they should be, not taken literally (outputting ''code). + \def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars} + % \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + % \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% % {% % Have to do this stuff outside the \shipout because we want it to @@ -1138,7 +1141,9 @@ output) for that.)} % Color manipulation macros based on pdfcolor.tex, % except using rgb instead of cmyk; the latter is said to render as a % very dark gray on-screen and a very dark halftone in print, instead - % of actual black. + % of actual black. The dark red here is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. We use + % black by default, though. \def\rgbDarkRed{0.50 0.09 0.12} \def\rgbBlack{0 0 0} % @@ -1248,10 +1253,9 @@ output) for that.)} % used to mark target names; must be expandable. \def\pdfmkpgn#1{#1} % - % by default, use a color that is dark enough to print on paper as - % nearly black, but still distinguishable for online viewing. - \def\urlcolor{\rgbDarkRed} - \def\linkcolor{\rgbDarkRed} + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} \def\endlink{\setcolor{\maincolor}\pdfendlink} % % Adding outlines to PDF; macros for calculating structure of outlines @@ -2377,8 +2381,10 @@ end \ifx\next,% \else\ifx\next-% \else\ifx\next.% + \else\ifx\next\.% + \else\ifx\next\comma% \else\ptexslash - \fi\fi\fi + \fi\fi\fi\fi\fi \aftersmartic } @@ -2519,7 +2525,9 @@ end \ifx\codedashprev\codedash \else \discretionary{}{}{}\fi \fi - \global\let\codedashprev=\next + % we need the space after the = for the case when \next itself is a + % space token; it would get swallowed otherwise. As in @code{- a}. + \global\let\codedashprev= \next } } \def\normaldash{-} @@ -2571,33 +2579,17 @@ end % second argument specifying the text to display and an optional third % arg as text to display instead of (rather than in addition to) the url % itself. First (mandatory) arg is the url. -% (This \urefnobreak definition isn't used now, leaving it for a while -% for comparison.) -\def\urefnobreak#1{\dourefnobreak #1,,,\finish} -\def\dourefnobreak#1,#2,#3,#4\finish{\begingroup - \unsepspaces - \pdfurl{#1}% - \setbox0 = \hbox{\ignorespaces #3}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} -% This \urefbreak definition is the active one. +% secret option to allow changing PDF output to show only the second +% arg (if given), and not the url (which is then just the link target). +\newif\ifurefurlonlylink + +% The main macro is \urefbreak, which allows breaking at expected +% places within the url. (There used to be another version, which +% didn't support automatic breaking.) \def\urefbreak{\begingroup \urefcatcodes \dourefbreak} \let\uref=\urefbreak +% \def\dourefbreak#1{\urefbreakfinish #1,,,\finish} \def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example \unsepspaces @@ -2606,12 +2598,19 @@ end \ifdim\wd0 > 0pt \unhbox0 % third arg given, show only that \else - \setbox0 = \hbox{\ignorespaces #2}% + \setbox0 = \hbox{\ignorespaces #2}% look for second arg \ifdim\wd0 > 0pt \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it + \ifurefurlonlylink + % PDF plus option to not display url, show just arg + \unhbox0 + \else + % PDF, normally display both arg and url for consistency, + % visibility, if the pdf is eventually used to print, etc. + \unhbox0\ (\urefcode{#1})% + \fi \else - \unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url + \unhbox0\ (\urefcode{#1})% DVI, always show arg and url \fi \else \urefcode{#1}% only url given, so show it @@ -2887,6 +2886,15 @@ end \def\inlinefmtname{#1}% \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi } +% +% @inlinefmtifelse{FMTNAME,THEN-TEXT,ELSE-TEXT} expands THEN-TEXT if +% FMTNAME is tex, else ELSE-TEXT. +\long\def\inlinefmtifelse#1{\doinlinefmtifelse #1,,,\finish} +\long\def\doinlinefmtifelse#1,#2,#3,#4,\finish{% + \def\inlinefmtname{#1}% + \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\else \ignorespaces #3\fi +} +% % For raw, must switch into @tex before parsing the argument, to avoid % setting catcodes prematurely. Doing it this way means that, for % example, @inlineraw{html, foo{bar} gets a parse error instead of being @@ -2903,6 +2911,23 @@ end \endgroup % close group opened by \tex. } +% @inlineifset{VAR, TEXT} expands TEXT if VAR is @set. +% +\long\def\inlineifset#1{\doinlineifset #1,\finish} +\long\def\doinlineifset#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax + \else\ignorespaces#2\fi +} + +% @inlineifclear{VAR, TEXT} expands TEXT if VAR is not @set. +% +\long\def\inlineifclear#1{\doinlineifclear #1,\finish} +\long\def\doinlineifclear#1,#2,\finish{% + \def\inlinevarname{#1}% + \expandafter\ifx\csname SET\inlinevarname\endcsname\relax \ignorespaces#2\fi +} + \message{glyphs,} % and logos. @@ -3658,7 +3683,7 @@ end \parskip=\smallskipamount \ifdim\parskip=0pt \parskip=2pt \fi % - % Try typesetting the item mark that if the document erroneously says + % Try typesetting the item mark so that if the document erroneously says % something like @itemize @samp (intending @table), there's an error % right away at the @itemize. It's not the best error message in the % world, but it's better than leaving it to the @item. This means if @@ -4198,7 +4223,7 @@ end \def\value{\begingroup\makevalueexpandable\valuexxx} \def\valuexxx#1{\expandablevalue{#1}\endgroup} { - \catcode`\- = \active \catcode`\_ = \active + \catcode`\-=\active \catcode`\_=\active % \gdef\makevalueexpandable{% \let\value = \expandablevalue @@ -4219,6 +4244,11 @@ end % it will fail (although perhaps we could fix that with sufficient work % to do a one-level expansion on the result, instead of complete). % +% Unfortunately, this has the consequence that when _ is in the *value* +% of an @set, it does not print properly in the roman fonts (get the cmr +% dot accent at position 126 instead). No fix comes to mind, and it's +% been this way since 2003 or earlier, so just ignore it. +% \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax {[No value for ``#1'']}% @@ -5905,7 +5935,7 @@ end % % Now the second mark, after the heading break. No break points % between here and the heading. - \let\prevsectiondefs=\lastsectiondefs + \global\let\prevsectiondefs=\lastsectiondefs \domark % % Only insert the space after the number if we have a section number. @@ -6272,8 +6302,8 @@ end \catcode `\|=\other \catcode `\<=\other \catcode `\>=\other - \catcode`\`=\other - \catcode`\'=\other + \catcode `\`=\other + \catcode `\'=\other \escapechar=`\\ % % ' is active in math mode (mathcode"8000). So reset it, and all our @@ -6297,7 +6327,7 @@ end \let\/=\ptexslash \let\*=\ptexstar \let\t=\ptext - \expandafter \let\csname top\endcsname=\ptextop % outer + \expandafter \let\csname top\endcsname=\ptextop % we've made it outer \let\frenchspacing=\plainfrenchspacing % \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% @@ -9940,11 +9970,9 @@ directory should work if nowhere else does.} \catcode`\"=\active \def\activedoublequote{{\tt\char34}} \let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} +\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde \chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} +\catcode`\^=\active \def\activehat{{\tt \hat}} \let^ = \activehat \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} @@ -9954,16 +9982,26 @@ directory should work if nowhere else does.} \catcode`\|=\active \def|{{\tt\char124}} + \chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} +\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless \chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix +\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr +\catcode`\+=\active \def+{{\tt \char 43}} +\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix + +% used for headline/footline in the output routine, in case the page +% breaks in the middle of an @tex block. +\def\texinfochars{% + \let< = \activeless + \let> = \activegtr + \let~ = \activetilde + \let^ = \activehat + \markupsetuplqdefault \markupsetuprqdefault + \let\b = \strong + \let\i = \smartitalic + % in principle, all other definitions in \tex have to be undone too. +} % If a .fmt file is being used, characters that might appear in a file % name cannot be active until we have parsed the command line. diff --git a/manual/threads.texi b/manual/threads.texi index a23ac261ef..9a5ef6a987 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -1,5 +1,5 @@ @node POSIX Threads -@c @node POSIX Threads, , Cryptographic Functions, Top +@c @node POSIX Threads, Internal Probes, Cryptographic Functions, Top @chapter POSIX Threads @c %MENU% POSIX Threads @cindex pthreads @@ -69,7 +69,7 @@ function returns @math{0} on success and a non-zero error code on failure. @end deftypefun -@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) +@deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) Set the default attribute values to match the values in @var{attr}. The function returns @math{0} on success and a non-zero error code on failure. The following error codes are defined for this function: diff --git a/manual/time.texi b/manual/time.texi index ff31e284fd..e7e8647ee2 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -687,9 +687,8 @@ 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}. +Calling @code{localtime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun Using the @code{localtime} function is a big problem in multi-threaded @@ -739,25 +738,28 @@ object the result was written into, i.e., it returns @var{resultp}. @comment time.h @comment ISO @deftypefun time_t mktime (struct tm *@var{brokentime}) -The @code{mktime} function is used to convert a broken-down time structure -to a simple time representation. It also ``normalizes'' the contents of -the broken-down time structure, by filling in the day of week and day of -year based on the other date and time components. +The @code{mktime} function converts a broken-down time structure to a +simple time representation. It also normalizes the contents of the +broken-down time structure, and fills in some components based on the +values of the others. The @code{mktime} function ignores the specified contents of the -@code{tm_wday} and @code{tm_yday} members of the broken-down time +@code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone} +members of the broken-down time structure. It uses the values of the other components to determine the calendar time; it's permissible for these components to have 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}). +structure, including the members that were initally ignored. If the specified broken-down time cannot be represented as a simple time, @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify the contents of @var{brokentime}. -Calling @code{mktime} also sets the variable @code{tzname} with -information about the current time zone. @xref{Time Zone Functions}. +Calling @code{mktime} also sets the current time zone as if +@code{tzset} were called; @code{mktime} uses this information instead +of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. @end deftypefun @comment time.h @@ -1053,8 +1055,8 @@ rather than in broken-down local time format. It is equivalent to asctime (localtime (@var{time})) @end smallexample -@code{ctime} sets the variable @code{tzname}, because @code{localtime} -does so. @xref{Time Zone Functions}. +Calling @code{ctime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun @comment time.h @@ -1081,7 +1083,8 @@ This function is similar to the @code{sprintf} function (@pxref{Formatted Input}), but the conversion specifications that can appear in the format template @var{template} are specialized for printing components of the date and time @var{brokentime} according to the locale currently specified for -time conversion (@pxref{Locales}). +time conversion (@pxref{Locales}) and the current time zone +(@pxref{Time Zone Functions}). Ordinary characters appearing in the @var{template} are copied to the output string @var{s}; this can include multibyte character sequences. @@ -1392,9 +1395,10 @@ if (len == 0 && buf[0] != '\0') If @var{s} is a null pointer, @code{strftime} does not actually write anything, but instead returns the number of characters it would have written. -According to POSIX.1 every call to @code{strftime} implies a call to -@code{tzset}. So the contents of the environment variable @code{TZ} -is examined before any output is produced. +Calling @code{strftime} also sets the current time zone as if +@code{tzset} were called; @code{strftime} uses this information +instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. For an example of @code{strftime}, see @ref{Time Functions Example}. @end deftypefun @@ -2037,7 +2041,7 @@ 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 negative if it is east. The hour must be between @code{0} and -@code{23}, and the minute and seconds between @code{0} and @code{59}. +@code{24}, 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: @@ -2082,17 +2086,51 @@ between @code{1} and @code{12}. The @var{time} fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default is -@code{02:00:00}. - -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 +@code{02:00:00}. The hours part of the time fields can range from +@minus{}167 through 167; this is an extension to POSIX.1, which allows +only the range 0 through 24. + +Here are some example @code{TZ} values, including the appropriate +Daylight Saving Time and its dates of applicability. In North +American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), +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 +March's second Sunday at 2:00am, and ends on November's first Sunday at 2:00am. @smallexample -EST+5EDT,M4.1.0/2,M10.5.0/2 +EST+5EDT,M3.2.0/2,M11.1.0/2 +@end smallexample + +Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours +ahead of the prime meridian in winter, springing forward an hour on +March's fourth Tuesday at 26:00 (i.e., 02:00 on the first Friday on or +after March 23), and falling back on October's last Sunday at 02:00. + +@smallexample +IST-2IDT,M3.4.4/26,M10.5.0 +@end smallexample + +Western Argentina Summer Time (WARST) is 3 hours behind the prime +meridian all year. There is a dummy fall-back transition on December +31 at 25:00 daylight saving time (i.e., 24:00 standard time, +equivalent to January 1 at 00:00 standard time), and a simultaneous +spring-forward transition on January 1 at 00:00 standard time, so +daylight saving time is in effect all year and the initial @code{WART} +is a placeholder. + +@smallexample +WART4WARST,J1/0,J365/25 +@end smallexample + +Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) +are 3 hours behind UTC in the winter. Its clocks follow the European +Union rules of springing forward by one hour on March's last Sunday at +01:00 UTC (@minus{}02:00 local time) and falling back on October's +last Sunday at 01:00 UTC (@minus{}01:00 local time). + +@smallexample +WGT3WGST,M3.5.0/-2,M10.5.0/-1 @end smallexample The schedule of Daylight Saving Time in any particular jurisdiction has |