diff options
Diffstat (limited to 'manual')
80 files changed, 1258 insertions, 515 deletions
diff --git a/manual/Makefile b/manual/Makefile index 5f98b2abf8..53822082e2 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -1,4 +1,4 @@ -# Copyright (C) 1992-2014 Free Software Foundation, Inc. +# Copyright (C) 1992-2015 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or @@ -19,14 +19,10 @@ subdir := manual -# Allow override -INSTALL_INFO = install-info +include ../Makeconfig .PHONY: dvi pdf info html -# Get glibc's configuration info. -include ../Makeconfig - dvi: $(objpfx)libc.dvi pdf: $(objpfx)libc.pdf @@ -41,8 +37,8 @@ chapters = $(addsuffix .texi, \ intro errno memory ctype string charset locale \ 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 probes) + resource setjmp signal startup process ipc job \ + nss 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 @@ -88,7 +84,7 @@ $(objpfx)libc/index.html: $(addprefix $(objpfx),$(libc-texi-generated)) $(objpfx)summary.texi: $(objpfx)stamp-summary ; $(objpfx)stamp-summary: summary.awk $(filter-out $(objpfx)summary.texi, \ $(texis-path)) - -$(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) + $(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) $(AWK) -f $^ | sort -t' ' -df -k 1,1 | tr '\014' '\012' \ > $(objpfx)summary-tmp $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi @@ -163,14 +159,14 @@ minimal-dist = summary.awk texis.awk tsort.awk libc-texinfo.sh libc.texinfo \ $(patsubst %.c.texi,examples/%.c, $(examples)) indices = cp fn pg tp vr ky -generated-dirs := libc -generated = libc.dvi libc.pdf libc.tmp libc.info* \ - stubs \ - texis summary.texi stamp-summary *.c.texi \ - $(foreach index,$(indices),libc.$(index) libc.$(index)s) \ - libc.log libc.aux libc.toc \ - $(libc-texi-generated) \ - stamp-libm-err stamp-version +generated-dirs += libc +generated += libc.dvi libc.pdf libc.tmp libc.info* \ + stubs \ + texis summary.texi stamp-summary *.c.texi \ + $(foreach index,$(indices),libc.$(index) libc.$(index)s) \ + libc.log libc.aux libc.toc \ + $(libc-texi-generated) \ + stamp-libm-err stamp-version include ../Rules diff --git a/manual/arith.texi b/manual/arith.texi index d1060140ad..72682f0c99 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -1237,7 +1237,7 @@ sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z})) This function should always be used instead of the direct formula because it takes special care to avoid losing precision. It may also -take advantage of hardware support for this operation. See @code{hypot} +take advantage of hardware support for this operation. See @code{hypot} in @ref{Exponents and Logarithms}. @end deftypefun @@ -1369,7 +1369,7 @@ of @w{IEEE 754} conformance. @pindex math.h The functions listed here perform operations such as rounding and -truncation of floating-point values. Some of these functions convert +truncation of floating-point values. Some of these functions convert floating point numbers to integer values. They are all declared in @file{math.h}. @@ -2625,7 +2625,7 @@ All these functions are defined in @file{stdlib.h}. @safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}} The function @code{ecvt} converts the floating-point number @var{value} to a string with at most @var{ndigit} decimal digits. The -returned string contains no decimal point or sign. The first digit of +returned string contains no decimal point or sign. The first digit of the string is non-zero (unless @var{value} is actually zero) and the last digit is rounded to nearest. @code{*@var{decpt}} is set to the index in the string of the first digit after the decimal point. diff --git a/manual/charset.texi b/manual/charset.texi index b2d73abc1e..68aecd3f1e 100644 --- a/manual/charset.texi +++ b/manual/charset.texi @@ -1709,7 +1709,7 @@ implementation has the possibility to perform such a conversion, the function returns a handle. If the wanted conversion is not available, the @code{iconv_open} function -returns @code{(iconv_t) -1}. In this case the global variable +returns @code{(iconv_t) -1}. In this case the global variable @code{errno} can have the following values: @table @code @@ -1838,7 +1838,7 @@ implementation chosen for @theglibc{} as it is described below. Therefore an @code{iconv} call to reset the state should always be performed if some protocol requires this for the output text. -The conversion stops for one of three reasons. The first is that all +The conversion stops for one of three reasons. The first is that all characters from the input buffer are converted. This actually can mean two things: either all bytes from the input buffer are consumed or there are some bytes at the end of the buffer that possibly can form a @@ -2133,7 +2133,7 @@ will succeed, but how to find @math{@cal{B}}? Unfortunately, the answer is: there is no general solution. On some systems guessing might help. On those systems most character sets can -convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text. Beside +convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text. Beside this only some very system-specific methods can help. Since the conversion functions come from loadable modules and these modules must be stored somewhere in the filesystem, one @emph{could} try to find them @@ -2333,7 +2333,7 @@ identical. So far this section has described how modules are located and considered to be used. What remains to be described is the interface of the modules -so that one can write new ones. This section describes the interface as +so that one can write new ones. This section describes the interface as it is in use in January 1999. The interface will change a bit in the future but, with luck, only in an upwardly compatible way. @@ -2918,7 +2918,7 @@ gconv (struct __gconv_step *step, struct __gconv_step_data *data, /* @r{Run the conversion loop. @code{status} is set} @r{appropriately afterwards.} */ - /* @r{If this is the last step, leave the loop. There is} + /* @r{If this is the last step, leave the loop. There is} @r{nothing we can do.} */ if (data->__is_last) @{ diff --git a/manual/check-safety.sh b/manual/check-safety.sh index 701624d3b1..d7c2ca590e 100644 --- a/manual/check-safety.sh +++ b/manual/check-safety.sh @@ -1,6 +1,6 @@ #! /bin/sh -# Copyright 2014 Free Software Foundation, Inc. +# Copyright 2014-2015 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or @@ -30,6 +30,11 @@ success=: # If no arguments are given, take all *.texi files in the current directory. test $# != 0 || set *.texi +# FIXME: check that each @deftypefu?n is followed by a @safety note, +# with nothing but @deftypefu?nx and comment lines in between. (There +# might be more stuff too). + + # Check that all safety remarks have entries for all of MT, AS and AC, # in this order, with an optional prelim note before them. grep -n '^@safety' "$@" | diff --git a/manual/contrib.texi b/manual/contrib.texi index 9c6cb3ed30..930d614e9b 100644 --- a/manual/contrib.texi +++ b/manual/contrib.texi @@ -55,6 +55,9 @@ committee. Thomas Bushnell for his contributions to Hurd. @item +Wilco Dijkstra for various fixes. + +@item Liubov Dmitrieva for optimzed string and math functions on x86-64 and x86. @@ -82,6 +85,10 @@ and wide-character support functions (@file{wctype.h}, @file{wchar.h}, etc.). @end itemize @item +Richard Earnshaw for continued support and fixes to the various ARM +machine files. + +@item Paul Eggert for the @code{mktime} function and for his direction as part of @theglibc{} steering committee. @@ -183,6 +190,9 @@ code. Chris Leonard for various fixes and enhancements to localedata. @item +Stefan Liebler for various fixes. + +@item Hongjiu Lu for providing the support for a Linux 32-bit runtime environment under x86-64 (x32), for porting to Linux on IA64, for improved string functions, a framework for testing IFUNC @@ -276,6 +286,9 @@ libraries and the port to SGI machines running Irix 4 (@code{mips-sgi-irix4}). @item +Torvald Riegel for the implementation of a new semaphore algorithm. + +@item Pravin Satpute for writing sorting rules for some Indian languages. @item diff --git a/manual/creature.texi b/manual/creature.texi index bbf16b7f27..3c686165f1 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -73,20 +73,6 @@ edition is made available. @end defvr @comment (none) -@comment GNU -@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. -@end defvr - -@comment (none) -@comment GNU -@defvr Macro _SVID_SOURCE -If you define this macro, functionality derived from SVID is -included as well as the @w{ISO C}, POSIX.1, POSIX.2, and X/Open material. -@end defvr - -@comment (none) @comment X/Open @defvr Macro _XOPEN_SOURCE @comment (none) @@ -192,9 +178,9 @@ precedence. @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 +X/Open, LFS and GNU extensions: the effect is to enable features from +the 2008 edition of POSIX, as well as certain BSD and SVID features +without a separate feature test macro to control them. 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 @@ -229,4 +215,4 @@ it is harmless to define in addition a feature test macro for a subset of 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. +@code{_POSIX_C_SOURCE} as well has no effect. diff --git a/manual/errno.texi b/manual/errno.texi index 6a691fc963..1068be3a50 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -1317,7 +1317,7 @@ The function @code{strerror} is declared in @file{string.h}. The @code{strerror_r} function works like @code{strerror} but instead of returning the error message in a statically allocated buffer shared by all threads in the process, it returns a private copy for the -thread. This might be either some permanent global data or a message +thread. This might be either some permanent global data or a message string in the user supplied buffer starting at @var{buf} with the length of @var{n} bytes. @@ -1361,9 +1361,6 @@ given error code; the precise text varies from system to system. With messages or embedded newlines. Each error message begins with a capital letter and does not include any terminating punctuation. -@strong{Compatibility Note:} The @code{strerror} function was introduced -in @w{ISO C89}. Many older C systems do not support this function yet. - @cindex program name @cindex name of running program Many programs that don't read input from the terminal are designed to @@ -1380,6 +1377,8 @@ This variable's value is the name that was used to invoke the program running in the current process. It is the same as @code{argv[0]}. Note that this is not necessarily a useful file name; often it contains no directory names. @xref{Program Arguments}. + +This variable is a GNU extension and is declared in @file{errno.h}. @end deftypevar @comment errno.h @@ -1389,17 +1388,19 @@ This variable's value is the name that was used to invoke the program running in the current process, with directory names removed. (That is to say, it is the same as @code{program_invocation_name} minus everything up to the last slash, if any.) + +This variable is a GNU extension and is declared in @file{errno.h}. @end deftypevar The library initialization code sets up both of these variables before calling @code{main}. -@strong{Portability Note:} These two variables are GNU extensions. If -you want your program to work with non-GNU libraries, you must save the -value of @code{argv[0]} in @code{main}, and then strip off the directory -names yourself. We added these extensions to make it possible to write -self-contained error-reporting subroutines that require no explicit -cooperation from @code{main}. +@strong{Portability Note:} If you want your program to work with +non-GNU libraries, you must save the value of @code{argv[0]} in +@code{main}, and then strip off the directory names yourself. We +added these extensions to make it possible to write self-contained +error-reporting subroutines that require no explicit cooperation from +@code{main}. Here is an example showing how to handle failure to open a file correctly. The function @code{open_sesame} tries to open the named file @@ -1413,6 +1414,8 @@ save it in a local variable instead, because those other library functions might overwrite @code{errno} in the meantime. @smallexample +#define _GNU_SOURCE + #include <errno.h> #include <stdio.h> #include <stdlib.h> diff --git a/manual/examples/add.c b/manual/examples/add.c index 99ec53c0e9..e2b025f83e 100644 --- a/manual/examples/add.c +++ b/manual/examples/add.c @@ -1,5 +1,5 @@ /* Example of a Variadic Function - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c index 12c16462f6..968e0cfc7a 100644 --- a/manual/examples/argp-ex1.c +++ b/manual/examples/argp-ex1.c @@ -1,5 +1,5 @@ /* Argp example #1 -- a minimal program using argp - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c index 6f77638e59..39bb719467 100644 --- a/manual/examples/argp-ex2.c +++ b/manual/examples/argp-ex2.c @@ -1,5 +1,5 @@ /* Argp example #2 -- a pretty minimal program using argp - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c index f7764eabfa..a9b30f361d 100644 --- a/manual/examples/argp-ex3.c +++ b/manual/examples/argp-ex3.c @@ -1,5 +1,5 @@ /* Argp example #3 -- a program with options and arguments using argp - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c index bbddc74292..e8034afd6b 100644 --- a/manual/examples/argp-ex4.c +++ b/manual/examples/argp-ex4.c @@ -1,5 +1,5 @@ /* Argp example #4 -- a program with somewhat more complicated options - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/atexit.c b/manual/examples/atexit.c index 857901f259..d8a8f54990 100644 --- a/manual/examples/atexit.c +++ b/manual/examples/atexit.c @@ -1,5 +1,5 @@ /* Cleanups on Exit - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/db.c b/manual/examples/db.c index a8ee9004af..d6ec397fd7 100644 --- a/manual/examples/db.c +++ b/manual/examples/db.c @@ -1,5 +1,5 @@ /* User and Group Database Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/dir.c b/manual/examples/dir.c index 61ce05acd9..4315f45606 100644 --- a/manual/examples/dir.c +++ b/manual/examples/dir.c @@ -1,5 +1,5 @@ /* Simple Program to List a Directory - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/dir2.c b/manual/examples/dir2.c index 22110ac62a..1fe3615aea 100644 --- a/manual/examples/dir2.c +++ b/manual/examples/dir2.c @@ -1,5 +1,5 @@ /* Simple Program to List a Directory, Mark II - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/execinfo.c b/manual/examples/execinfo.c index f728373c04..8272c96e96 100644 --- a/manual/examples/execinfo.c +++ b/manual/examples/execinfo.c @@ -1,5 +1,5 @@ /* Obtain a backtrace and print it. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/filecli.c b/manual/examples/filecli.c index 552a9109bb..6c9dd3c626 100644 --- a/manual/examples/filecli.c +++ b/manual/examples/filecli.c @@ -1,5 +1,5 @@ /* Example of Reading Datagrams - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/filesrv.c b/manual/examples/filesrv.c index 36b59a0f6f..b240e30c39 100644 --- a/manual/examples/filesrv.c +++ b/manual/examples/filesrv.c @@ -1,5 +1,5 @@ /* Datagram Socket Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/fmtmsgexpl.c b/manual/examples/fmtmsgexpl.c index 14e9bcf6fe..43c473b434 100644 --- a/manual/examples/fmtmsgexpl.c +++ b/manual/examples/fmtmsgexpl.c @@ -1,5 +1,5 @@ /* How to use fmtmsg and addseverity. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/genpass.c b/manual/examples/genpass.c index 79f9d0d2c4..57cada012c 100644 --- a/manual/examples/genpass.c +++ b/manual/examples/genpass.c @@ -1,5 +1,5 @@ /* Encrypting Passwords - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/inetcli.c b/manual/examples/inetcli.c index d65b8b58fa..89e51eb14d 100644 --- a/manual/examples/inetcli.c +++ b/manual/examples/inetcli.c @@ -1,5 +1,5 @@ /* Byte Stream Socket Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/inetsrv.c b/manual/examples/inetsrv.c index f6589ec5d2..71aab5a88d 100644 --- a/manual/examples/inetsrv.c +++ b/manual/examples/inetsrv.c @@ -1,5 +1,5 @@ /* Byte Stream Connection Server Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/isockad.c b/manual/examples/isockad.c index 3f447dcf42..863e042fd6 100644 --- a/manual/examples/isockad.c +++ b/manual/examples/isockad.c @@ -1,5 +1,5 @@ /* Internet Socket Example using sockaddr_in. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/longopt.c b/manual/examples/longopt.c index bfd03e3da2..5bc657a8e8 100644 --- a/manual/examples/longopt.c +++ b/manual/examples/longopt.c @@ -1,5 +1,5 @@ /* Example of Parsing Long Options with getopt_long. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/memopen.c b/manual/examples/memopen.c index a17c99cd7f..9fb61cad35 100644 --- a/manual/examples/memopen.c +++ b/manual/examples/memopen.c @@ -1,5 +1,5 @@ /* String Streams - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/memstrm.c b/manual/examples/memstrm.c index 2d19a7e247..66b0061417 100644 --- a/manual/examples/memstrm.c +++ b/manual/examples/memstrm.c @@ -1,5 +1,5 @@ /* open_memstream example. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mkfsock.c b/manual/examples/mkfsock.c index 2a213171ae..b8ecce79cd 100644 --- a/manual/examples/mkfsock.c +++ b/manual/examples/mkfsock.c @@ -1,5 +1,5 @@ /* Example of Local-Namespace Sockets - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mkisock.c b/manual/examples/mkisock.c index 2ed0736658..53e976a54c 100644 --- a/manual/examples/mkisock.c +++ b/manual/examples/mkisock.c @@ -1,5 +1,5 @@ /* Internet Socket Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/mygetpass.c b/manual/examples/mygetpass.c index a78ae080a0..ac4768320f 100644 --- a/manual/examples/mygetpass.c +++ b/manual/examples/mygetpass.c @@ -1,5 +1,5 @@ /* Reading Passwords - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/ofdlocks.c b/manual/examples/ofdlocks.c new file mode 100644 index 0000000000..4ca1ff345d --- /dev/null +++ b/manual/examples/ofdlocks.c @@ -0,0 +1,77 @@ +/* Open File Description Locks Usage Example + Copyright (C) 1991-2015 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <http://www.gnu.org/licenses/>. +*/ + +#define _GNU_SOURCE +#include <stdio.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <unistd.h> +#include <fcntl.h> +#include <pthread.h> + +#define FILENAME "/tmp/foo" +#define NUM_THREADS 3 +#define ITERATIONS 5 + +void * +thread_start (void *arg) +{ + int i, fd, len; + long tid = (long) arg; + char buf[256]; + struct flock lck = { + .l_whence = SEEK_SET, + .l_start = 0, + .l_len = 1, + }; + + fd = open ("/tmp/foo", O_RDWR | O_CREAT, 0666); + + for (i = 0; i < ITERATIONS; i++) + { + lck.l_type = F_WRLCK; + fcntl (fd, F_OFD_SETLKW, &lck); + + len = sprintf (buf, "%d: tid=%ld fd=%d\n", i, tid, fd); + + lseek (fd, 0, SEEK_END); + write (fd, buf, len); + fsync (fd); + + lck.l_type = F_UNLCK; + fcntl (fd, F_OFD_SETLK, &lck); + + /* sleep to ensure lock is yielded to another thread */ + usleep (1); + } + pthread_exit (NULL); +} + +int +main (int argc, char **argv) +{ + long i; + pthread_t threads[NUM_THREADS]; + + truncate (FILENAME, 0); + + for (i = 0; i < NUM_THREADS; i++) + pthread_create (&threads[i], NULL, thread_start, (void *) i); + + pthread_exit (NULL); + return 0; +} diff --git a/manual/examples/pipe.c b/manual/examples/pipe.c index 16c429e825..81db29d503 100644 --- a/manual/examples/pipe.c +++ b/manual/examples/pipe.c @@ -1,5 +1,5 @@ /* Creating a Pipe - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/popen.c b/manual/examples/popen.c index a53c9fd535..5ad3edb9af 100644 --- a/manual/examples/popen.c +++ b/manual/examples/popen.c @@ -1,5 +1,5 @@ /* Pipe to a Subprocess - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/rprintf.c b/manual/examples/rprintf.c index 57503c57d6..89a1ed59f3 100644 --- a/manual/examples/rprintf.c +++ b/manual/examples/rprintf.c @@ -1,5 +1,5 @@ /* Printf Extension Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/search.c b/manual/examples/search.c index 31e9d0a1de..ba48c16458 100644 --- a/manual/examples/search.c +++ b/manual/examples/search.c @@ -1,5 +1,5 @@ /* Searching and Sorting Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/select.c b/manual/examples/select.c index f881424e04..eaa8f6a29a 100644 --- a/manual/examples/select.c +++ b/manual/examples/select.c @@ -1,5 +1,5 @@ /* Waiting for Input or Output - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/setjmp.c b/manual/examples/setjmp.c index 8c3df4ddd3..0efa5ddd30 100644 --- a/manual/examples/setjmp.c +++ b/manual/examples/setjmp.c @@ -1,5 +1,5 @@ /* Introduction to Non-Local Exits - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/sigh1.c b/manual/examples/sigh1.c index 627651a4c3..6814734562 100644 --- a/manual/examples/sigh1.c +++ b/manual/examples/sigh1.c @@ -1,5 +1,5 @@ /* Signal Handlers that Return - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/sigusr.c b/manual/examples/sigusr.c index 5a1a405eb7..fe65160c85 100644 --- a/manual/examples/sigusr.c +++ b/manual/examples/sigusr.c @@ -1,5 +1,5 @@ /* Using kill for Communication - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/stpcpy.c b/manual/examples/stpcpy.c index b9a11e1389..e670d0f62b 100644 --- a/manual/examples/stpcpy.c +++ b/manual/examples/stpcpy.c @@ -1,5 +1,5 @@ /* stpcpy example. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/strdupa.c b/manual/examples/strdupa.c index 26af22179c..ca927b80aa 100644 --- a/manual/examples/strdupa.c +++ b/manual/examples/strdupa.c @@ -1,5 +1,5 @@ /* strdupa example. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/strftim.c b/manual/examples/strftim.c index 5f798401e8..d0c642ff58 100644 --- a/manual/examples/strftim.c +++ b/manual/examples/strftim.c @@ -1,5 +1,5 @@ /* Time Functions Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/strncat.c b/manual/examples/strncat.c index f2983c70af..509be49c97 100644 --- a/manual/examples/strncat.c +++ b/manual/examples/strncat.c @@ -1,5 +1,5 @@ /* strncat example. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/subopt.c b/manual/examples/subopt.c index be6bf98f7b..2c99b73388 100644 --- a/manual/examples/subopt.c +++ b/manual/examples/subopt.c @@ -1,5 +1,5 @@ /* Parsing of Suboptions Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/swapcontext.c b/manual/examples/swapcontext.c index 952987b8f1..1ce25c3459 100644 --- a/manual/examples/swapcontext.c +++ b/manual/examples/swapcontext.c @@ -1,5 +1,5 @@ /* Complete Context Control - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/termios.c b/manual/examples/termios.c index 05636c23cd..2dbc8ba5aa 100644 --- a/manual/examples/termios.c +++ b/manual/examples/termios.c @@ -1,5 +1,5 @@ /* Noncanonical Mode Example - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/testopt.c b/manual/examples/testopt.c index 7c65f510fb..dc35cfb525 100644 --- a/manual/examples/testopt.c +++ b/manual/examples/testopt.c @@ -1,5 +1,5 @@ /* Example of Parsing Arguments with getopt. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/testpass.c b/manual/examples/testpass.c index 2e0bca52e9..c1743dde34 100644 --- a/manual/examples/testpass.c +++ b/manual/examples/testpass.c @@ -1,5 +1,5 @@ /* Verify a password. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/examples/timeval_subtract.c b/manual/examples/timeval_subtract.c index 232d4b199c..8bf8c4c432 100644 --- a/manual/examples/timeval_subtract.c +++ b/manual/examples/timeval_subtract.c @@ -1,5 +1,5 @@ /* struct timeval subtraction. - Copyright (C) 1991-2014 Free Software Foundation, Inc. + Copyright (C) 1991-2015 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License diff --git a/manual/filesys.texi b/manual/filesys.texi index 1c9d7d7707..0f2e3dc3be 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -748,7 +748,7 @@ are very helpful for this purpose. @comment dirent.h @comment BSD/SVID -@deftypefun int alphasort (const void *@var{a}, const void *@var{b}) +@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b}) @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c Calls strcoll. The @code{alphasort} function behaves like the @code{strcoll} function @@ -762,7 +762,7 @@ than zero depending on the order of the two entries @var{a} and @var{b}. @comment dirent.h @comment GNU -@deftypefun int versionsort (const void *@var{a}, const void *@var{b}) +@deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b}) @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c Calls strverscmp, which will accesses the locale object multiple @c times. @@ -797,7 +797,7 @@ argument. Instead we provide the two replacement functions below. @comment dirent.h @comment GNU -@deftypefun int alphasort64 (const void *@var{a}, const void *@var{b}) +@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b}) @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} @c See alphasort. The @code{alphasort64} function behaves like the @code{strcoll} function @@ -811,7 +811,7 @@ than zero depending on the order of the two entries @var{a} and @var{b}. @comment dirent.h @comment GNU -@deftypefun int versionsort64 (const void *@var{a}, const void *@var{b}) +@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b}) @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} @c See versionsort. The @code{versionsort64} function is like @code{alphasort64}, excepted that it @@ -893,7 +893,7 @@ seeing this value in a @code{ftw} callback function means the referenced file does not exist. The situation for @code{nftw} is different. This value is only available if the program is compiled with -@code{_BSD_SOURCE} or @code{_XOPEN_EXTENDED} defined before including +@code{_XOPEN_EXTENDED} defined before including the first header. The original SVID systems do not have symbolic links. @end vtable @@ -1723,6 +1723,7 @@ modify the attributes of a file. access a file. * File Times:: About the time attributes of a file. * File Size:: Manually changing the size of a file. +* Storage Allocation:: Allocate backing storage for files. @end menu @node Attribute Meanings @@ -2553,8 +2554,9 @@ the file's modification time onto disk reliably (the idea being that no-one cares for a swap file). This bit is only available on BSD systems (and those derived from -them). Therefore one has to use the @code{_BSD_SOURCE} feature select -macro to get the definition (@pxref{Feature Test Macros}). +them). Therefore one has to use the @code{_GNU_SOURCE} feature select +macro, or not define any feature test macros, to get the definition +(@pxref{Feature Test Macros}). @end table The actual bit values of the symbols are listed in the table above @@ -3232,6 +3234,99 @@ is a requirement of @code{mmap}. The program has to keep track of the real size, and when it has finished a final @code{ftruncate} call should set the real size of the file. +@node Storage Allocation +@subsection Storage Allocation +@cindex allocating file storage +@cindex file allocation +@cindex storage allocating + +@cindex file fragmentation +@cindex fragmentation of files +@cindex sparse files +@cindex files, sparse +Most file systems support allocating large files in a non-contiguous +fashion: the file is split into @emph{fragments} which are allocated +sequentially, but the fragments themselves can be scattered across the +disk. File systems generally try to avoid such fragmentation because it +decreases performance, but if a file gradually increases in size, there +might be no other option than to fragment it. In addition, many file +systems support @emph{sparse files} with @emph{holes}: regions of null +bytes for which no backing storage has been allocated by the file +system. When the holes are finally overwritten with data, fragmentation +can occur as well. + +Explicit allocation of storage for yet-unwritten parts of the file can +help the system to avoid fragmentation. Additionally, if storage +pre-allocation fails, it is possible to report the out-of-disk error +early, often without filling up the entire disk. However, due to +deduplication, copy-on-write semantics, and file compression, such +pre-allocation may not reliably prevent the out-of-disk-space error from +occurring later. Checking for write errors is still required, and +writes to memory-mapped regions created with @code{mmap} can still +result in @code{SIGBUS}. + +@deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c If the file system does not support allocation, +@c @code{posix_fallocate} has a race with file extension (if +@c @var{length} is zero) or with concurrent writes of non-NUL bytes (if +@c @var{length} is positive). + +Allocate backing store for the region of @var{length} bytes starting at +byte @var{offset} in the file for the descriptor @var{fd}. The file +length is increased to @samp{@var{length} + @var{offset}} if necessary. + +@var{fd} must be a regular file opened for writing, or @code{EBADF} is +returned. If there is insufficient disk space to fulfill the allocation +request, @code{ENOSPC} is returned. + +@strong{Note:} If @code{fallocate} is not available (because the file +system does not support it), @code{posix_fallocate} is emulated, which +has the following drawbacks: + +@itemize @bullet +@item +It is very inefficient because all file system blocks in the requested +range need to be examined (even if they have been allocated before) and +potentially rewritten. In contrast, with proper @code{fallocate} +support (see below), the file system can examine the internal file +allocation data structures and eliminate holes directly, maybe even +using unwritten extents (which are pre-allocated but uninitialized on +disk). + +@item +There is a race condition if another thread or process modifies the +underlying file in the to-be-allocated area. Non-null bytes could be +overwritten with null bytes. + +@item +If @var{fd} has been opened with the @code{O_APPEND} flag, the function +will fail with an @code{errno} value of @code{EBADF}. + +@item +If @var{length} is zero, @code{ftruncate} is used to increase the file +size as requested, without allocating file system blocks. There is a +race condition which means that @code{ftruncate} can accidentally +truncate the file if it has been extended concurrently. +@end itemize + +On Linux, if an application does not benefit from emulation or if the +emulation is harmful due to its inherent race conditions, the +application can use the Linux-specific @code{fallocate} function, with a +zero flag argument. For the @code{fallocate} function, @theglibc{} does +not perform allocation emulation if the file system does not support +allocation. Instead, an @code{EOPNOTSUPP} is returned to the caller. + +@end deftypefun + +@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{length}, off64_t @var{offset}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} + +This function is a variant of @code{posix_fallocate64} which accepts +64-bit file offsets on all platforms. + +@end deftypefun + @node Making Special Files @section Making Special Files @cindex creating special files diff --git a/manual/install.texi b/manual/install.texi index c0b8d9e134..63c41b0b8d 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -174,6 +174,17 @@ setuid and owned by @code{root}. The use of @file{pt_chown} introduces additional security risks to the system and you should enable it only if you understand and accept those risks. +@item --disable-werror +By default, @theglibc{} is built with @option{-Werror}. If you wish +to build without this option (for example, if building with a newer +version of GCC than this version of @theglibc{} was tested with, so +new warnings cause the build with @option{-Werror} to fail), you can +configure with @option{--disable-werror}. + +@item --disable-mathvec +By default for x86_64, @theglibc{} is built with vector math library. +Use this option to disable vector math library. + @item --build=@var{build-system} @itemx --host=@var{host-system} These options are for cross-compiling. If you specify both options and @@ -185,7 +196,7 @@ the compiler and/or binutils. If you only specify @samp{--host}, @code{configure} will prepare for a native compile but use what you specify instead of guessing what your -system is. This is most useful to change the CPU submodel. For example, +system is. This is most useful to change the CPU submodel. For example, if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but you want to compile a library for 586es, give @samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add @@ -235,6 +246,12 @@ The tests (and later installation) use some pre-existing files of the system such as @file{/etc/passwd}, @file{/etc/nsswitch.conf} and others. These files must all contain correct and sensible content. +Normally, @code{make check} will run all the tests before reporting +all problems found and exiting with error status if any problems +occurred. You can specify @samp{stop-on-test-failure=y} when running +@code{make check} to make the test run stop and exit with an error +status immediately when a failure occurs. + To format the @cite{GNU C Library Reference Manual} for printing, type @w{@code{make dvi}}. You need a working @TeX{} installation to do this. The distribution builds the on-line formatted version of the @@ -269,13 +286,20 @@ system and @var{hostname}. In general, when testing @theglibc{}, @samp{test-wrapper} may be set to the name and arguments of any program to run newly built binaries. This program must preserve the arguments to the binary being run, its -working directory, all environment variables set as part of testing -and the standard input, output and error file descriptors. If -@samp{@var{test-wrapper} env} will not work to run a program with -environment variables set, then @samp{test-wrapper-env} must be set to -a program that runs a newly built program with environment variable -assignments in effect, those assignments being specified as -@samp{@var{var}=@var{value}} before the name of the program to be run. +working directory and the standard input, output and error file +descriptors. If @samp{@var{test-wrapper} env} will not work to run a +program with environment variables set, then @samp{test-wrapper-env} +must be set to a program that runs a newly built program with +environment variable assignments in effect, those assignments being +specified as @samp{@var{var}=@var{value}} before the name of the +program to be run. If multiple assignments to the same variable are +specified, the last assignment specified must take precedence. +Similarly, if @samp{@var{test-wrapper} env -i} will not work to run a +program with an environment completely empty of variables except those +directly assigned, then @samp{test-wrapper-env-only} must be set; its +use has the same syntax as @samp{test-wrapper-env}, the only +difference in its semantics being starting with an empty set of +environment variables rather than the ambient set. @node Running make install @@ -283,7 +307,7 @@ assignments in effect, those assignments being specified as @cindex installing To install the library and its header files, and the Info files of the -manual, type @code{env LANGUAGE=C LC_ALL=C make install}. This will +manual, type @code{make install}. This will build things, if necessary, before installing them; however, you should still compile everything first. If you are installing @theglibc{} as your primary C library, we recommend that you shut the system down to @@ -309,12 +333,14 @@ headers, but nothing else. If you do this, you will need to restore any headers from libraries other than @theglibc{} yourself after installing the library. -You can install @theglibc{} somewhere other than where you configured it to go -by setting the @code{install_root} variable on the command line for -@samp{make install}. The value of this variable is prepended to all the -paths for installation. This is useful when setting up a chroot -environment or preparing a binary distribution. The directory should be -specified with an absolute file name. +You can install @theglibc{} somewhere other than where you configured +it to go by setting the @code{DESTDIR} GNU standard make variable on +the command line for @samp{make install}. The value of this variable +is prepended to all the paths for installation. This is useful when +setting up a chroot environment or preparing a binary distribution. +The directory should be specified with an absolute file name. Installing +with the @code{prefix} and @code{exec_prefix} GNU standard make variables +set is not supported. @Theglibc{} includes a daemon called @code{nscd}, which you may or may not want to run. @code{nscd} caches name service lookups; it @@ -364,10 +390,13 @@ recommend GNU @code{make} version 3.79. All earlier versions have severe bugs or lack features. @item -GCC 4.4 or newer, GCC 4.6 recommended +GCC 4.6 or newer -GCC 4.4 or higher is required; as of this writing, GCC 4.6 is the -compiler we advise to use to build @theglibc{}. +GCC 4.6 or higher is required. In general it is recommended to use +the newest version of the compiler that is known to work for building +@theglibc{}, as newer compilers usually produce better code. As of +release time, GCC 4.9.2 is the newest compiler verified to work to build +@theglibc{}. You can use whatever compiler you like to compile programs that use @theglibc{}. @@ -375,19 +404,22 @@ You can use whatever compiler you like to compile programs that use Check the FAQ for any special compiler issues on particular platforms. @item -GNU @code{binutils} 2.20 or later +GNU @code{binutils} 2.22 or later You must use GNU @code{binutils} (as and ld) to build @theglibc{}. No other assembler or linker has the necessary functionality at the -moment. +moment. As of release time, GNU @code{binutils} 2.25 is the newest +verified to work to build @theglibc{}. @item -GNU @code{texinfo} 4.5 or later +GNU @code{texinfo} 4.7 or later To correctly translate and install the Texinfo documentation you need this version of the @code{texinfo} package. Earlier versions do not understand all the tags used in the document, and the installation mechanism for the info files is not present or works differently. +As of release time, @code{texinfo} 5.2 is the newest verified to work +to build @theglibc{}. @item GNU @code{awk} 3.1.2, or higher @@ -419,7 +451,7 @@ If you change any of the @file{configure.ac} files you will also need @itemize @bullet @item -GNU @code{autoconf} 2.53 or higher +GNU @code{autoconf} 2.69 (exactly) @end itemize @noindent @@ -431,6 +463,15 @@ GNU @code{gettext} 0.10.36 or later @end itemize @noindent +If you wish to regenerate the @code{yacc} parser code in the @file{intl} +subdirectory you will need + +@itemize @bullet +@item +GNU @code{bison} 2.7 or later +@end itemize + +@noindent You may also need these packages if you upgrade your source tree using patches, although we try to avoid this. @@ -439,7 +480,7 @@ patches, although we try to avoid this. @cindex kernel header files If you are installing @theglibc{} on @gnulinuxsystems{}, you need to have -the header files from a 2.6.19.1 or newer kernel around for reference. +the header files from a 2.6.32 or newer kernel around for reference. These headers must be installed using @samp{make headers_install}; the headers present in the kernel source directory are not suitable for direct use by @theglibc{}. You do not need to use that kernel, just have diff --git a/manual/intro.texi b/manual/intro.texi index 0f5785990b..d4045f2e06 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -1283,19 +1283,59 @@ The header file @file{termios.h} reserves names prefixed with @samp{c_}, Here is an overview of the contents of the remaining chapters of this manual. +@c The chapter overview ordering is: +@c Error Reporting (2) +@c Virtual Memory Allocation and Paging (3) +@c Character Handling (4) +@c Strings and Array Utilities (5) +@c Character Set Handling (6) +@c Locales and Internationalization (7) +@c Searching and Sorting (9) +@c Pattern Matching (10) +@c Input/Output Overview (11) +@c Input/Output on Streams (12) +@c Low-level Input/Ooutput (13) +@c File System Interface (14) +@c Pipes and FIFOs (15) +@c Sockets (16) +@c Low-Level Terminal Interface (17) +@c Syslog (18) +@c Mathematics (19) +@c Aritmetic Functions (20) +@c Date and Time (21) +@c Non-Local Exist (23) +@c Signal Handling (24) +@c The Basic Program/System Interface (25) +@c Processes (26) +@c Job Control (28) +@c System Databases and Name Service Switch (29) +@c Users and Groups (30) -- References `User Database' and `Group Database' +@c System Management (31) +@c System Configuration Parameters (32) +@c C Language Facilities in the Library (AA) +@c Summary of Library Facilities (AB) +@c Installing (AC) +@c Library Maintenance (AD) + +@c The following chapters need overview text to be added: +@c Message Translation (8) +@c Resource Usage And Limitations (22) +@c Inter-Process Communication (27) +@c DES Encryption and Password Handling (33) +@c Debugging support (34) +@c POSIX Threads (35) +@c Internal Probes (36) +@c Platform-specific facilities (AE) +@c Contributors to (AF) +@c Free Software Needs Free Documentation (AG) +@c GNU Lesser General Public License (AH) +@c GNU Free Documentation License (AI) + @itemize @bullet @item @ref{Error Reporting}, describes how errors detected by the library are reported. -@item -@ref{Language Features}, contains information about library support for -standard parts of the C language, including things like the @code{sizeof} -operator and the symbolic constant @code{NULL}, how to write functions -accepting variable numbers of arguments, and constants describing the -ranges and other properties of the numerical types. There is also a simple -debugging mechanism which allows you to put assertions in your code, and -have diagnostic messages printed if the tests fail. @item @ref{Memory}, describes @theglibc{}'s facilities for managing and @@ -1315,6 +1355,26 @@ manipulating strings (null-terminated character arrays) and general byte arrays, including operations such as copying and comparison. @item +@ref{Character Set Handling}, contains information about manipulating +characters and strings using character sets larger than will fit in +the usual @code{char} data type. + +@item +@ref{Locales}, describes how selecting a particular country +or language affects the behavior of the library. For example, the locale +affects collation sequences for strings and how monetary values are +formatted. + +@item +@ref{Searching and Sorting}, contains information about functions +for searching and sorting arrays. You can use these functions on any +kind of array by providing an appropriate comparison function. + +@item +@ref{Pattern Matching}, presents functions for matching regular expressions +and shell file name patterns, and for expanding words as the shell does. + +@item @ref{I/O Overview}, gives an overall look at the input and output facilities in the library, and contains information about basic concepts such as file names. @@ -1366,30 +1426,10 @@ for simple arithmetic, analysis of floating-point values, and reading numbers from strings. @item -@ref{Searching and Sorting}, contains information about functions -for searching and sorting arrays. You can use these functions on any -kind of array by providing an appropriate comparison function. - -@item -@ref{Pattern Matching}, presents functions for matching regular expressions -and shell file name patterns, and for expanding words as the shell does. - -@item @ref{Date and Time}, describes functions for measuring both calendar time and CPU time, as well as functions for setting alarms and timers. @item -@ref{Character Set Handling}, contains information about manipulating -characters and strings using character sets larger than will fit in -the usual @code{char} data type. - -@item -@ref{Locales}, describes how selecting a particular country -or language affects the behavior of the library. For example, the locale -affects collation sequences for strings and how monetary values are -formatted. - -@item @ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and @code{longjmp} functions. These functions provide a facility for @code{goto}-like jumps which can jump from one function to another. @@ -1435,6 +1475,15 @@ various operating system limits. Most of these parameters are provided for compatibility with POSIX. @item +@ref{Language Features}, contains information about library support for +standard parts of the C language, including things like the @code{sizeof} +operator and the symbolic constant @code{NULL}, how to write functions +accepting variable numbers of arguments, and constants describing the +ranges and other properties of the numerical types. There is also a simple +debugging mechanism which allows you to put assertions in your code, and +have diagnostic messages printed if the tests fail. + +@item @ref{Library Summary}, gives a summary of all the functions, variables, and macros in the library, with complete data types and function prototypes, and says what standard or system each is derived from. diff --git a/manual/ipc.texi b/manual/ipc.texi new file mode 100644 index 0000000000..081b98fe29 --- /dev/null +++ b/manual/ipc.texi @@ -0,0 +1,116 @@ +@node Inter-Process Communication, Job Control, Processes, Top +@c %MENU% All about inter-process communication +@chapter Inter-Process Communication +@cindex ipc + +This chapter describes the @glibcadj{} inter-process communication primitives. + +@menu +* Semaphores:: Support for creating and managing semaphores +@end menu + +@node Semaphores +@section Semaphores + +@Theglibc{} implements the semaphore APIs as defined in POSIX and +System V. Semaphores can be used by multiple processes to coordinate shared +resources. The following is a complete list of the semaphore functions provided +by @theglibc{}. + +@c Need descriptions for all of these functions. + +@subsection System V Semaphores +@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}} +@c syscall(ipc) ok +@c +@c AC-unsafe because we need to translate the new kernel +@c semid_ds buf into the userspace layout. Cancellation +@c at that point results in an inconsistent userspace +@c semid_ds. +@end deftypefun + +@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@subsection POSIX Semaphores + +@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Does not atomically update sem_t therefore AC-unsafe +@c because it can leave sem_t partially initialized. +@end deftypefun + +@deftypefun int sem_destroy (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Function does nothing and is therefore always safe. +@end deftypefun + +@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} +@c pthread_once asuinit +@c +@c We are AC-Unsafe becuase we use pthread_once to initialize +@c a global variable that holds the location of the mounted +@c shmfs on Linux. +@end deftypefun + +@deftypefun int sem_close (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} +@c lll_lock asulock aculock +@c twalk mtsrace{:root} +@c +@c We are AS-unsafe because we take a non-recursive lock. +@c We are AC-unsafe because several internal data structures +@c are not updated atomically. +@end deftypefun + +@deftypefun int sem_unlink (const char *@var{name}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} +@c pthread_once asuinit acucorrupt aculock +@c mempcpy acucorrupt +@end deftypefun + +@deftypefun int sem_wait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c atomic_increment (nwaiters) acucorrupt +@c +@c Given the use atomic operations this function seems +@c to be AS-safe. It is AC-unsafe because there is still +@c a window between atomic_decrement and the pthread_push +@c of the handler that undoes that operation. A cancellation +@c at that point would fail to remove the process from the +@c waiters count. +@end deftypefun + +@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Same safety issues as sem_wait. +@end deftypefun + +@deftypefun int sem_trywait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c All atomic operations are safe in all contexts. +@end deftypefun + +@deftypefun int sem_post (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Same safety as sem_trywait. +@end deftypefun + +@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Atomic write of a value is safe in all contexts. +@end deftypefun diff --git a/manual/job.texi b/manual/job.texi index 4e58f54e9c..095c26d930 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1,4 +1,4 @@ -@node Job Control, Name Service Switch, Processes, Top +@node Job Control, Name Service Switch, Inter-Process Communication, Top @c %MENU% All about process groups and sessions @chapter Job Control @@ -1039,10 +1039,12 @@ The function @code{ctermid} is declared in the header file @comment stdio.h @comment POSIX.1 @deftypefun {char *} ctermid (char *@var{string}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@safety{@prelim{}@mtsafe{@mtsposix{/!string}}@assafe{}@acsafe{}} @c This function is a stub by default; the actual implementation, for -@c posix systems, returns an internal buffer if passed a NULL string, -@c but the internal buffer is always set to /dev/tty. +@c posix systems, returns a pointer to a string literal if passed a NULL +@c string. It's not clear we want to commit to being MT-Safe in the +@c !string case, so maybe add mtasurace{:ctermid/!string} when we take +@c prelim out, to make room for using a static buffer in the future. The @code{ctermid} function returns a string containing the file name of the controlling terminal for the current process. If @var{string} is not a null pointer, it should be an array that can hold at least diff --git a/manual/libc.texinfo b/manual/libc.texinfo index b29e990681..554f8b0a3e 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -46,7 +46,7 @@ This is @value{VERSION} @value{PKGVERSION}. @end ifclear -Copyright @copyright{} 1993--2014 Free Software Foundation, Inc. +Copyright @copyright{} 1993--2015 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version diff --git a/manual/libm-err-tab.pl b/manual/libm-err-tab.pl index 7ac9af2e0e..46ec7c6bb5 100755 --- a/manual/libm-err-tab.pl +++ b/manual/libm-err-tab.pl @@ -1,5 +1,5 @@ #!/usr/bin/perl -w -# Copyright (C) 1999-2014 Free Software Foundation, Inc. +# Copyright (C) 1999-2015 Free Software Foundation, Inc. # This file is part of the GNU C Library. # Contributed by Andreas Jaeger <aj@suse.de>, 1999. @@ -104,7 +104,7 @@ sub find_files { # Parse ulps file sub parse_ulps { my ($file, $platform) = @_; - my ($test, $type, $float, $eps, $kind); + my ($test, $type, $float, $eps); # $type has the following values: # "normal": No complex variable @@ -116,10 +116,6 @@ sub parse_ulps { # ignore comments and empty lines next if /^#/; next if /^\s*$/; - if (/^Test/) { - $kind = 'test'; - next; - } if (/^Function: /) { if (/Real part of/) { s/Real part of //; @@ -131,11 +127,8 @@ sub parse_ulps { $type = 'normal'; } ($test) = ($_ =~ /^Function:\s*\"([a-zA-Z0-9_]+)\"/); - $kind = 'fct'; next; } - # Only handle maximal errors of functions - next if ($kind eq 'test'); if (/^i?(float|double|ldouble):/) { ($float, $eps) = split /\s*:\s*/,$_,2; if ($eps eq 'fail') { diff --git a/manual/llio.texi b/manual/llio.texi index 69b54c2838..4f3fada1e7 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -57,6 +57,10 @@ directly.) flags associated with open files. * File Locks:: Fcntl commands for implementing file locking. +* Open File Description Locks:: Fcntl commands for implementing + open file description locking. +* Open File Description Locks Example:: An example of open file description lock + usage * Interrupt Input:: Getting an asynchronous signal when input arrives. * IOCTLs:: Generic I/O Control operations. @@ -462,6 +466,36 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a @comment POSIX.1 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Some say write is thread-unsafe on Linux without O_APPEND. In the VFS layer +@c the vfs_write() does no locking around the acquisition of a file offset and +@c therefore multiple threads / kernel tasks may race and get the same offset +@c resulting in data loss. +@c +@c See: +@c http://thread.gmane.org/gmane.linux.kernel/397980 +@c http://lwn.net/Articles/180387/ +@c +@c The counter argument is that POSIX only says that the write starts at the +@c file position and that the file position is updated *before* the function +@c returns. What that really means is that any expectation of atomic writes is +@c strictly an invention of the interpretation of the reader. Data loss could +@c happen if two threads start the write at the same time. Only writes that +@c come after the return of another write are guaranteed to follow the other +@c write. +@c +@c The other side of the coin is that POSIX goes on further to say in +@c "2.9.7 Thread Interactions with Regular File Operations" that threads +@c should never see interleaving sets of file operations, but it is insane +@c to do anything like that because it kills performance, so you don't get +@c those guarantees in Linux. +@c +@c So we mark it thread safe, it doesn't blow up, but you might loose +@c data, and we don't strictly meet the POSIX requirements. +@c +@c The fix for file offsets racing was merged in 3.14, the commits were: +@c 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4, and +@c d7a15f8d0777955986a2ab00ab181795cab14b01. Therefore after Linux 3.14 you +@c should get mostly MT-safe writes. The @code{write} function writes up to @var{size} bytes from @var{buffer} to the file with descriptor @var{filedes}. The data in @var{buffer} is not necessarily a character string and a null character is @@ -1083,7 +1117,7 @@ which describe the location and size of each buffer. @comment BSD @deftp {Data Type} {struct iovec} -The @code{iovec} structure describes a buffer. It contains two fields: +The @code{iovec} structure describes a buffer. It contains two fields: @table @code @@ -1141,8 +1175,8 @@ error. The possible errors are the same as in @code{write}. @end deftypefun -@c Note - I haven't read this anywhere. I surmised it from my knowledge -@c of computer science. Thus, there could be subtleties I'm missing. +@c Note - I haven't read this anywhere. I surmised it from my knowledge +@c of computer science. Thus, there could be subtleties I'm missing. Note that if the buffers are small (under about 1kB), high-level streams may be easier to use than these functions. However, @code{readv} and @@ -1195,8 +1229,8 @@ The @code{mmap} function creates a new mapping, connected to bytes is created, which is not removed by closing the file. @var{address} gives a preferred starting address for the mapping. -@code{NULL} expresses no preference. Any previous mapping at that -address is automatically removed. The address you give may still be +@code{NULL} expresses no preference. Any previous mapping at that +address is automatically removed. The address you give may still be changed, unless you use the @code{MAP_FIXED} flag. @vindex PROT_READ @@ -1260,7 +1294,7 @@ as the included @code{malloc} automatically uses @code{mmap} where appropriate. @c Linux has some other MAP_ options, which I have not discussed here. @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to -@c user programs (and I don't understand the last two). MAP_LOCKED does +@c user programs (and I don't understand the last two). MAP_LOCKED does @c not appear to be implemented. @end vtable @@ -1405,14 +1439,14 @@ There is no existing mapping in at least part of the given region. This function can be used to change the size of an existing memory area. @var{address} and @var{length} must cover a region entirely mapped -in the same @code{mmap} statement. A new mapping with the same +in the same @code{mmap} statement. A new mapping with the same characteristics will be returned with the length @var{new_length}. -One option is possible, @code{MREMAP_MAYMOVE}. If it is given in +One option is possible, @code{MREMAP_MAYMOVE}. If it is given in @var{flags}, the system may remove the existing mapping and create a new one of the desired length in another location. -The address of the resulting mapping is returned, or @math{-1}. Possible +The address of the resulting mapping is returned, or @math{-1}. Possible error codes include: @table @code @@ -1464,11 +1498,11 @@ The valid BSD values for @var{advice} are: The region should receive no further special treatment. @item MADV_RANDOM -The region will be accessed via random page references. The kernel +The region will be accessed via random page references. The kernel should page-in the minimal number of pages for each page fault. @item MADV_SEQUENTIAL -The region will be accessed via sequential page references. This +The region will be accessed via sequential page references. This may cause the kernel to aggressively read-ahead, expecting further sequential references after any page fault within this region. @@ -1540,7 +1574,7 @@ There is no existing mapping in at least part of the given region. @c close dup @acsfd 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 +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. @@ -2890,7 +2924,7 @@ Get flags associated with the open file. @xref{File Status Flags}. Set flags associated with the open file. @xref{File Status Flags}. @item F_GETLK -Get a file lock. @xref{File Locks}. +Test a file lock. @xref{File Locks}. @item F_SETLK Set or clear a file lock. @xref{File Locks}. @@ -2898,6 +2932,18 @@ Set or clear a file lock. @xref{File Locks}. @item F_SETLKW Like @code{F_SETLK}, but wait for completion. @xref{File Locks}. +@item F_OFD_GETLK +Test an open file description lock. @xref{Open File Description Locks}. +Specific to Linux. + +@item F_OFD_SETLK +Set or clear an open file description lock. @xref{Open File Description Locks}. +Specific to Linux. + +@item F_OFD_SETLKW +Like @code{F_OFD_SETLK}, but block until lock is acquired. +@xref{Open File Description Locks}. Specific to Linux. + @item F_GETOWN Get process or process group ID to receive @code{SIGIO} signals. @xref{Interrupt Input}. @@ -3576,6 +3622,10 @@ set_nonblock_flag (int desc, int value) @cindex file locks @cindex record locking +This section describes record locks that are associated with the process. +There is also a different type of record lock that is associated with the +open file description instead of the process. @xref{Open File Description Locks}. + The remaining @code{fcntl} commands are used to support @dfn{record locking}, which permits multiple cooperating programs to prevent each other from simultaneously accessing parts of a file in error-prone @@ -3641,7 +3691,10 @@ the file. @item pid_t l_pid This field is the process ID (@pxref{Process Creation Concepts}) of the process holding the lock. It is filled in by calling @code{fcntl} with -the @code{F_GETLK} command, but is ignored when making a lock. +the @code{F_GETLK} command, but is ignored when making a lock. If the +conflicting lock is an open file description lock +(@pxref{Open File Description Locks}), then this field will be set to +@math{-1}. @end table @end deftp @@ -3813,10 +3866,222 @@ that part of the file for writing. @c ??? This section could use an example program. -Remember that file locks are only a @emph{voluntary} protocol for +Remember that file locks are only an @emph{advisory} protocol for controlling access to a file. There is still potential for access to the file by programs that don't use the lock protocol. +@node Open File Description Locks +@section Open File Description Locks + +In contrast to process-associated record locks (@pxref{File Locks}), +open file description record locks are associated with an open file +description rather than a process. + +Using @code{fcntl} to apply an open file description lock on a region that +already has an existing open file description lock that was created via the +same file descriptor will never cause a lock conflict. + +Open file description locks are also inherited by child processes across +@code{fork}, or @code{clone} with @code{CLONE_FILES} set +(@pxref{Creating a Process}), along with the file descriptor. + +It is important to distinguish between the open file @emph{description} (an +instance of an open file, usually created by a call to @code{open}) and +an open file @emph{descriptor}, which is a numeric value that refers to the +open file description. The locks described here are associated with the +open file @emph{description} and not the open file @emph{descriptor}. + +Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file +descriptor does not give you a new open file description, but rather copies a +reference to an existing open file description and assigns it to a new +file descriptor. Thus, open file description locks set on a file +descriptor cloned by @code{dup} will never conflict with open file +description locks set on the original descriptor since they refer to the +same open file description. Depending on the range and type of lock +involved, the original lock may be modified by a @code{F_OFD_SETLK} or +@code{F_OFD_SETLKW} command in this situation however. + +Open file description locks always conflict with process-associated locks, +even if acquired by the same process or on the same open file +descriptor. + +Open file description locks use the same @code{struct flock} as +process-associated locks as an argument (@pxref{File Locks}) and the +macros for the @code{command} values are also declared in the header file +@file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be +defined prior to including any header file. + +In contrast to process-associated locks, any @code{struct flock} used as +an argument to open file description lock commands must have the @code{l_pid} +value set to @math{0}. Also, when returning information about an +open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request, +the @code{l_pid} field in @code{struct flock} will be set to @math{-1} +to indicate that the lock is not associated with a process. + +When the same @code{struct flock} is reused as an argument to a +@code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an +@code{F_OFD_GETLK} request, it is necessary to inspect and reset the +@code{l_pid} field to @math{0}. + +@pindex fcntl.h. + +@deftypevr Macro int F_OFD_GETLK +This macro is used as the @var{command} argument to @code{fcntl}, to +specify that it should get information about a lock. This command +requires a third argument of type @w{@code{struct flock *}} to be passed +to @code{fcntl}, so that the form of the call is: + +@smallexample +fcntl (@var{filedes}, F_OFD_GETLK, @var{lockp}) +@end smallexample + +If there is a lock already in place that would block the lock described +by the @var{lockp} argument, information about that lock is written to +@code{*@var{lockp}}. Existing locks are not reported if they are +compatible with making a new lock as specified. Thus, you should +specify a lock type of @code{F_WRLCK} if you want to find out about both +read and write locks, or @code{F_RDLCK} if you want to find out about +write locks only. + +There might be more than one lock affecting the region specified by the +@var{lockp} argument, but @code{fcntl} only returns information about +one of them. Which lock is returned in this situation is undefined. + +The @code{l_whence} member of the @var{lockp} structure are set to +@code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set +to identify the locked region. + +If no conflicting lock exists, the only change to the @var{lockp} structure +is to update the @code{l_type} field to the value @code{F_UNLCK}. + +The normal return value from @code{fcntl} with this command is either @math{0} +on success or @math{-1}, which indicates an error. The following @code{errno} +error conditions are defined for this command: + +@table @code +@item EBADF +The @var{filedes} argument is invalid. + +@item EINVAL +Either the @var{lockp} argument doesn't specify valid lock information, +the operating system kernel doesn't support open file description locks, or the file +associated with @var{filedes} doesn't support locks. +@end table +@end deftypevr + +@comment fcntl.h +@comment POSIX.1 +@deftypevr Macro int F_OFD_SETLK +This macro is used as the @var{command} argument to @code{fcntl}, to +specify that it should set or clear a lock. This command requires a +third argument of type @w{@code{struct flock *}} to be passed to +@code{fcntl}, so that the form of the call is: + +@smallexample +fcntl (@var{filedes}, F_OFD_SETLK, @var{lockp}) +@end smallexample + +If the open file already has a lock on any part of the +region, the old lock on that part is replaced with the new lock. You +can remove a lock by specifying a lock type of @code{F_UNLCK}. + +If the lock cannot be set, @code{fcntl} returns immediately with a value +of @math{-1}. This command does not wait for other tasks +to release locks. If @code{fcntl} succeeds, it returns @math{0}. + +The following @code{errno} error conditions are defined for this +command: + +@table @code +@item EAGAIN +The lock cannot be set because it is blocked by an existing lock on the +file. + +@item EBADF +Either: the @var{filedes} argument is invalid; you requested a read lock +but the @var{filedes} is not open for read access; or, you requested a +write lock but the @var{filedes} is not open for write access. + +@item EINVAL +Either the @var{lockp} argument doesn't specify valid lock information, +the operating system kernel doesn't support open file description locks, or the +file associated with @var{filedes} doesn't support locks. + +@item ENOLCK +The system has run out of file lock resources; there are already too +many file locks in place. + +Well-designed file systems never report this error, because they have no +limitation on the number of locks. However, you must still take account +of the possibility of this error, as it could result from network access +to a file system on another machine. +@end table +@end deftypevr + +@comment fcntl.h +@comment POSIX.1 +@deftypevr Macro int F_OFD_SETLKW +This macro is used as the @var{command} argument to @code{fcntl}, to +specify that it should set or clear a lock. It is just like the +@code{F_OFD_SETLK} command, but causes the process to wait until the request +can be completed. + +This command requires a third argument of type @code{struct flock *}, as +for the @code{F_OFD_SETLK} command. + +The @code{fcntl} return values and errors are the same as for the +@code{F_OFD_SETLK} command, but these additional @code{errno} error conditions +are defined for this command: + +@table @code +@item EINTR +The function was interrupted by a signal while it was waiting. +@xref{Interrupted Primitives}. + +@end table +@end deftypevr + +Open file description locks are useful in the same sorts of situations as +process-associated locks. They can also be used to synchronize file +access between threads within the same process by having each thread perform +its own @code{open} of the file, to obtain its own open file description. + +Because open file description locks are automatically freed only upon +closing the last file descriptor that refers to the open file +description, this locking mechanism avoids the possibility that locks +are inadvertently released due to a library routine opening and closing +a file without the application being aware. + +As with process-associated locks, open file description locks are advisory. + +@node Open File Description Locks Example +@section Open File Description Locks Example + +Here is an example of using open file description locks in a threaded +program. If this program used process-associated locks, then it would be +subject to data corruption because process-associated locks are shared +by the threads inside a process, and thus cannot be used by one thread +to lock out another thread in the same process. + +Proper error handling has been omitted in the following program for +brevity. + +@smallexample +@include ofdlocks.c.texi +@end smallexample + +This example creates three threads each of which loops five times, +appending to the file. Access to the file is serialized via open file +description locks. If we compile and run the above program, we'll end up +with /tmp/foo that has 15 lines in it. + +If we, however, were to replace the @code{F_OFD_SETLK} and +@code{F_OFD_SETLKW} commands with their process-associated lock +equivalents, the locking essentially becomes a noop since it is all done +within the context of the same process. That leads to data corruption +(typically manifested as missing lines) as some threads race in and +overwrite the data written by others. + @node Interrupt Input @section Interrupt-Driven Input @@ -3899,7 +4164,7 @@ There is no process or process group corresponding to @var{pid}. @gnusystems{} can handle most input/output operations on many different devices and objects in terms of a few file primitives - @code{read}, @code{write} and @code{lseek}. However, most devices also have a few -peculiar operations which do not fit into this model. Such as: +peculiar operations which do not fit into this model. Such as: @itemize @bullet diff --git a/manual/locale.texi b/manual/locale.texi index 8bfd653edb..ee1c3a1201 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -29,6 +29,7 @@ will follow the conventions preferred by the user. * Setting the Locale:: How a program specifies the locale with library functions. * Standard Locales:: Locale names available on all systems. +* Locale Names:: Format of system-specific locale names. * Locale Information:: How to access the information for the locale. * Formatting Numbers:: A dedicated function to format numbers. * Yes-or-No Questions:: Check a Response against the locale. @@ -99,14 +100,16 @@ locale named @samp{espana-castellano} to use the standard conventions of most of Spain. The set of locales supported depends on the operating system you are -using, and so do their names. We can't make any promises about what -locales will exist, except for one standard locale called @samp{C} or -@samp{POSIX}. Later we will describe how to construct locales. -@comment (@pxref{Building Locale Files}). +using, and so do their names, except that the standard locale called +@samp{C} or @samp{POSIX} always exist. @xref{Locale Names}. + +In order to force the system to always use the default locale, the +user can set the @code{LC_ALL} environment variable to @samp{C}. @cindex combining locales -A user also has the option of specifying different locales for different -purposes---in effect, choosing a mixture of multiple locales. +A user also has the option of specifying different locales for +different purposes---in effect, choosing a mixture of multiple +locales. @xref{Locale Categories}. For example, the user might specify the locale @samp{espana-castellano} for most purposes, but specify the locale @samp{usa-english} for @@ -120,7 +123,7 @@ which locales apply. However, the user can choose to use each locale for a particular subset of those purposes. @node Locale Categories, Setting the Locale, Choosing Locale, Locales -@section Categories of Activities that Locales Affect +@section Locale Categories @cindex categories for locales @cindex locale categories @@ -128,7 +131,11 @@ The purposes that locales serve are grouped into @dfn{categories}, so that a user or a program can choose the locale for each category independently. Here is a table of categories; each name is both an environment variable that a user can set, and a macro name that you can -use as an argument to @code{setlocale}. +use as the first argument to @code{setlocale}. + +The contents of the environment variable (or the string in the second +argument to @code{setlocale}) has to be a valid locale name. +@xref{Locale Names}. @vtable @code @comment locale.h @@ -172,7 +179,7 @@ for affirmative and negative responses. @comment locale.h @comment ISO @item LC_ALL -This is not an environment variable; it is only a macro that you can use +This is not a category; it is only a macro that you can use with @code{setlocale} to set a single locale for all purposes. Setting this environment variable overwrites all selections by the other @code{LC_*} variables or @code{LANG}. @@ -355,13 +362,7 @@ The symbols in this section are defined in the header file @file{locale.h}. @c strndup @ascuheap @acsmem @c strcasecmp_l ok (C locale) 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 +@var{category} to @var{locale}. If @var{category} is @code{LC_ALL}, this specifies the locale for all purposes. The other possible values of @var{category} specify an @@ -386,10 +387,9 @@ is passed in as @var{locale} parameter. When you read the current locale for category @code{LC_ALL}, the value encodes the entire combination of selected locales for all categories. -In this case, the value is not just a single locale name. In fact, we -don't make any promises about what it looks like. But if you specify -the same ``locale name'' with @code{LC_ALL} in a subsequent call to -@code{setlocale}, it restores the same combination of locale selections. +If you specify the same ``locale name'' with @code{LC_ALL} in a +subsequent call to @code{setlocale}, it restores the same combination +of locale selections. To be sure you can use the returned string encoding the currently selected locale at a later time, you must make a copy of the string. It is not @@ -405,20 +405,15 @@ for @var{category}. If a nonempty string is given for @var{locale}, then the locale of that name is used if possible. +The effective locale name (either the second argument to +@code{setlocale}, or if the argument is an empty string, the name +obtained from the process environment) must be valid locale name. +@xref{Locale Names}. + If you specify an invalid locale name, @code{setlocale} returns a null pointer and leaves the current locale unchanged. @end deftypefun -The path used for finding locale data can be set using the -@code{LOCPATH} environment variable. The default path for finding -locale data is system specific. It is computed from the value given -as the prefix while configuring the C library. This value normally is -@file{/usr} or @file{/}. For the former the complete path is: - -@smallexample -/usr/lib/locale -@end smallexample - Here is an example showing how you might use @code{setlocale} to temporarily switch to a new locale. @@ -458,7 +453,7 @@ locale categories, and future versions of the library will do so. For portability, assume that any symbol beginning with @samp{LC_} might be defined in @file{locale.h}. -@node Standard Locales, Locale Information, Setting the Locale, Locales +@node Standard Locales, Locale Names, Setting the Locale, Locales @section Standard Locales The only locale names you can count on finding on all operating systems @@ -492,7 +487,94 @@ with the environment, rather than trying to specify some non-standard locale explicitly by name. Remember, different machines might have different sets of locales installed. -@node Locale Information, Formatting Numbers, Standard Locales, Locales +@node Locale Names, Locale Information, Standard Locales, Locales +@section Locale Names + +The following command prints a list of locales supported by the +system: + +@pindex locale +@smallexample + locale -a +@end smallexample + +@strong{Portability Note:} With the notable exception of the standard +locale names @samp{C} and @samp{POSIX}, locale names are +system-specific. + +Most locale names follow XPG syntax and consist of up to four parts: + +@smallexample +@var{language}[_@var{territory}[.@var{codeset}]][@@@var{modifier}] +@end smallexample + +Beside the first part, all of them are allowed to be missing. If the +full specified locale is not found, less specific ones are looked for. +The various parts will be stripped off, in the following order: + +@enumerate +@item +codeset +@item +normalized codeset +@item +territory +@item +modifier +@end enumerate + +For example, the locale name @samp{de_AT.iso885915@@euro} denotes a +German-language locale for use in Austria, using the ISO-8859-15 +(Latin-9) character set, and with the Euro as the currency symbol. + +In addition to locale names which follow XPG syntax, systems may +provide aliases such as @samp{german}. Both categories of names must +not contain the slash character @samp{/}. + +If the locale name starts with a slash @samp{/}, it is treated as a +path relative to the configured locale directories; see @code{LOCPATH} +below. The specified path must not contain a component @samp{..}, or +the name is invalid, and @code{setlocale} will fail. + +@strong{Portability Note:} POSIX suggests that if a locale name starts +with a slash @samp{/}, it is resolved as an absolute path. However, +@theglibc{} treats it as a relative path under the directories listed +in @code{LOCPATH} (or the default locale directory if @code{LOCPATH} +is unset). + +Locale names which are longer than an implementation-defined limit are +invalid and cause @code{setlocale} to fail. + +As a special case, locale names used with @code{LC_ALL} can combine +several locales, reflecting different locale settings for different +categories. For example, you might want to use a U.S. locale with ISO +A4 paper format, so you set @code{LANG} to @samp{en_US.UTF-8}, and +@code{LC_PAPER} to @samp{de_DE.UTF-8}. In this case, the +@code{LC_ALL}-style combined locale name is + +@smallexample +LC_CTYPE=en_US.UTF-8;LC_TIME=en_US.UTF-8;LC_PAPER=de_DE.UTF-8;@dots{} +@end smallexample + +followed by other category settings not shown here. + +@vindex LOCPATH +The path used for finding locale data can be set using the +@code{LOCPATH} environment variable. This variable lists the +directories in which to search for locale definitions, separated by a +colon @samp{:}. + +The default path for finding locale data is system specific. A typical +value for the @code{LOCPATH} default is: + +@smallexample +/usr/share/locale +@end smallexample + +The value of @code{LOCPATH} is ignored by privileged programs for +security reasons, and only the default directory is used. + +@node Locale Information, Formatting Numbers, Locale Names, Locales @section Accessing Locale Information There are several ways to access locale information. The simplest diff --git a/manual/maint.texi b/manual/maint.texi index 659ceae011..862b49d956 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -424,7 +424,7 @@ top level of the @file{sysdeps} directory tree. For example, files specific to those machine architectures, but not specific to any particular operating system. There might be subdirectories for specializations of those architectures, such as -@w{@file{sysdeps/m68k/68020}}. Code which is specific to the +@w{@file{sysdeps/m68k/68020}}. Code which is specific to the floating-point coprocessor used with a particular machine should go in @w{@file{sysdeps/@var{machine}/fpu}}. diff --git a/manual/math.texi b/manual/math.texi index 152744147c..72f3fda0a3 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -106,7 +106,7 @@ The reciprocal of the square root of two (also the square root of 1/2). @end vtable These constants come from the Unix98 standard and were also available in -4.4BSD; therefore they are only defined if @code{_BSD_SOURCE} or +4.4BSD; therefore they are only defined if @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is defined. The default set of features includes these constants. @xref{Feature Test Macros}. @@ -800,7 +800,7 @@ or is very close to 0. It is well-defined for all other values of @deftypefunx {complex long double} clog10l (complex long double @var{z}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} These functions return the base 10 logarithm of the complex value -@var{z}. Mathematically, this corresponds to the value +@var{z}. Mathematically, this corresponds to the value @ifnottex @math{log (z) = log10 (cabs (z)) + I * carg (z)} @@ -1313,7 +1313,9 @@ 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}). +may also be set (@pxref{Math Error Reporting}). (The ``inexact'' +exception may be raised, or not raised, even if this is inconsistent +with the infinite-precision value.) @item For the IBM @code{long double} format, as used on PowerPC GNU/Linux, @@ -1344,11 +1346,16 @@ 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). +Where the mathematical result underflows (before rounding) and is not +exactly representable as a floating-point value, the function does not +behave as if the computed infinite-precision result is an exact value +in the subnormal range. This means that the underflow exception is +raised other than possibly for cases where the mathematical result is +very close to the underflow threshold and the function behaves as if +it computes an infinite-precision result that does not underflow. (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 diff --git a/manual/memory.texi b/manual/memory.texi index 4beb322c96..0729e702db 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -1036,7 +1036,7 @@ There was insufficient memory available to satisfy the request. @end table -This function was introduced in POSIX 1003.1d. Although this function is +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 @@ -1361,7 +1361,7 @@ memory consumption of the program. @defvar __memalign_hook 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}; +are called. You should define this function to look like @code{aligned_alloc}; that is, like: @smallexample @@ -2492,7 +2492,7 @@ add_string (struct obstack *obstack, const char *ptr, int len) int room = obstack_room (obstack); if (room == 0) @{ - /* @r{Not enough room. Add one character slowly,} + /* @r{Not enough room. Add one character slowly,} @r{which may copy to a new chunk and make room.} */ obstack_1grow (obstack, *ptr++); len--; diff --git a/manual/message.texi b/manual/message.texi index 3e324816c6..b03a14a57a 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -1584,7 +1584,7 @@ for the @code{iconv_open} function, or a null pointer. If the @var{codeset} parameter is the null pointer, @code{bind_textdomain_codeset} returns the currently selected codeset -for the domain with the name @var{domainname}. It returns @code{NULL} if +for the domain with the name @var{domainname}. It returns @code{NULL} if no codeset has yet been selected. The @code{bind_textdomain_codeset} function can be used several times. diff --git a/manual/pattern.texi b/manual/pattern.texi index da848c340b..d1b9275cf9 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -2006,7 +2006,8 @@ allocate room for. @comment POSIX.2 @item WRDE_SYNTAX There was a syntax error in the input string. For example, an unmatched -quoting character is a syntax error. +quoting character is a syntax error. This error code is also used to +signal division by zero and overflow in arithmetic expansion. @end table @end deftypefun diff --git a/manual/probes.texi b/manual/probes.texi index 25d06e5383..7dd56d8058 100644 --- a/manual/probes.texi +++ b/manual/probes.texi @@ -17,6 +17,7 @@ arguments. @menu * Memory Allocation Probes:: Probes in the memory allocation subsystem * Mathematical Function Probes:: Probes in mathematical functions +* Non-local Goto Probes:: Probes in setjmp and longjmp @end menu @node Memory Allocation Probes @@ -246,125 +247,170 @@ 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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. +This probe is triggered 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 + +@node Non-local Goto Probes +@section Non-local Goto Probes + +These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp}, +@code{longjmp} or @code{siglongjmp}. + +@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is +called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} +passed as the first argument of @code{setjmp} or @code{sigsetjmp}, +@var{$arg2} is the second argument of @code{sigsetjmp} or zero if this +is a call to @code{setjmp} and @var{$arg3} is a pointer to the return +address that will be stored in the @code{jmp_buf}. +@end deftp + +@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered whenever @code{longjmp} or @code{siglongjmp} +is called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} +passed as the first argument of @code{longjmp} or @code{siglongjmp}, +@var{$arg2} is the return value passed as the second argument of +@code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to +the return address @code{longjmp} or @code{siglongjmp} will return to. + +The @code{longjmp} probe is triggered at a point where the registers +have not yet been restored to the values in the @code{jmp_buf} and +unwinding will show a call stack including the caller of +@code{longjmp} or @code{siglongjmp}. +@end deftp + +@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) +This probe is triggered under the same conditions and with the same +arguments as the @code{longjmp} probe. + +The @code{longjmp_target} probe is triggered at a point where the +registers have been restored to the values in the @code{jmp_buf} and +unwinding will show a call stack including the caller of @code{setjmp} +or @code{sigsetjmp}. @end deftp diff --git a/manual/process.texi b/manual/process.texi index aee65b9738..aa59040cb4 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -1,4 +1,4 @@ -@node Processes, Job Control, Program Basics, Top +@node Processes, Inter-Process Communication, Program Basics, Top @c %MENU% How to create processes and run other programs @chapter Processes diff --git a/manual/resource.texi b/manual/resource.texi index b5f0c24873..e68458b363 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -1644,7 +1644,7 @@ This function is a GNU extension. @comment GNU @deftypefun {long int} get_avphys_pages (void) @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} -The @code{get_phys_pages} function returns the number of available pages of +The @code{get_avphys_pages} function returns the number of available pages of physical the system has. To get the amount of memory this number has to be multiplied by the page size. @@ -1723,7 +1723,7 @@ running. This number is average over different periods of times @c it, closes it, without cancellation point, and calls strtod_l with @c the C locale to convert the strings to doubles. This function gets the 1, 5 and 15 minute load averages of the -system. The values are placed in @var{loadavg}. @code{getloadavg} will +system. The values are placed in @var{loadavg}. @code{getloadavg} will place at most @var{nelem} elements into the array but never more than three elements. The return value is the number of elements written to @var{loadavg}, or -1 on error. diff --git a/manual/search.texi b/manual/search.texi index 509a54313a..662527f813 100644 --- a/manual/search.texi +++ b/manual/search.texi @@ -164,8 +164,8 @@ To sort an array using an arbitrary comparison function, use the @comment ISO @deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare}) @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} -The @var{qsort} function sorts the array @var{array}. The array contains -@var{count} elements, each of which is of size @var{size}. +The @code{qsort} function sorts the array @var{array}. The array +contains @var{count} elements, each of which is of size @var{size}. The @var{compare} function is used to perform the comparison on the array elements. This function is called with two pointer arguments and @@ -180,11 +180,12 @@ This can make a difference when the comparison considers only part of the elements. Two elements with the same sort key may differ in other respects. -If you want the effect of a stable sort, you can get this result by -writing the comparison function so that, lacking other reason -distinguish between two elements, it compares them by their addresses. -Note that doing this may make the sorting algorithm less efficient, so -do it only if necessary. +Although the object addresses passed to the comparison function lie +within the array, they need not correspond with the original locations +of those objects because the sorting algorithm may swap around objects +in the array before making some comparisons. The only way to perform +a stable sort with @code{qsort} is to first augment the objects with a +monotonic counter of some kind. Here is a simple example of sorting an array of doubles in numerical order, using the comparison function defined above (@pxref{Comparison diff --git a/manual/setjmp.texi b/manual/setjmp.texi index b924d582b1..ec79c26bb3 100644 --- a/manual/setjmp.texi +++ b/manual/setjmp.texi @@ -262,7 +262,7 @@ declared respectively in the @file{ucontext.h} header file. @comment SVID @deftp {Data Type} ucontext_t -The @code{ucontext_t} type is defined as a structure with as least the +The @code{ucontext_t} type is defined as a structure with at least the following elements: @table @code @@ -307,17 +307,16 @@ The function returns @code{0} if successful. Otherwise it returns @end deftypefun The @code{getcontext} function is similar to @code{setjmp} but it does -not provide an indication of whether the function returns for the first -time or whether the initialized context was used and the execution is -resumed at just that point. If this is necessary the user has to take -determine this herself. This must be done carefully since the context -contains registers which might contain register variables. This is a -good situation to define variables with @code{volatile}. +not provide an indication of whether @code{getcontext} is returning for +the first time or whether an initialized context has just been restored. +If this is necessary the user has to determine this herself. This must +be done carefully since the context contains registers which might contain +register variables. This is a good situation to define variables with +@code{volatile}. Once the context variable is initialized it can be used as is or it can -be modified. The latter is normally done to implement co-routines or -similar constructs. The @code{makecontext} function is what has to be -used to do that. +be modified using the @code{makecontext} function. The latter is normally +done when implementing co-routines or similar constructs. @comment ucontext.h @comment SVID @@ -325,9 +324,9 @@ used to do that. @safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}} @c Linux-only implementations mostly in assembly, nothing unsafe. -The @var{ucp} parameter passed to the @code{makecontext} shall be +The @var{ucp} parameter passed to @code{makecontext} shall be initialized by a call to @code{getcontext}. The context will be -modified to in a way so that if the context is resumed it will start by +modified in a way such that if the context is resumed it will start by calling the function @code{func} which gets @var{argc} integer arguments passed. The integer arguments which are to be passed should follow the @var{argc} parameter in the call to @code{makecontext}. @@ -347,7 +346,7 @@ information about the exact use. While allocating the memory for the stack one has to be careful. Most modern processors keep track of whether a certain memory region is allowed to contain code which is executed or not. Data segments and -heap memory is normally not tagged to allow this. The result is that +heap memory are normally not tagged to allow this. The result is that programs would fail. Examples for such code include the calling sequences the GNU C compiler generates for calls to nested functions. Safe ways to allocate stacks correctly include using memory on the @@ -363,7 +362,7 @@ the @code{uc_stack} element to point to the base of the memory region allocated for the stack and the size of the memory region is stored in @code{ss_size}. There are implements out there which require @code{ss_sp} to be set to the value the stack pointer will have (which -can depending on the direction the stack grows be different). This +can, depending on the direction the stack grows, be different). This difference makes the @code{makecontext} function hard to use and it requires detection of the platform at compile time. @@ -397,6 +396,9 @@ time of the call. If @code{uc_link} was a null pointer the application terminates normally with an exit status value of @code{EXIT_SUCCESS} (@pxref{Program Termination}). +If the context was created by a call to a signal handler or from any +other source then the behaviour of @code{setcontext} is unspecified. + Since the context contains information about the stack no two threads should use the same context at the same time. The result in most cases would be disastrous. @@ -429,15 +431,15 @@ installed and execution continues as described in this context. If @code{swapcontext} succeeds the function does not return unless the context @var{oucp} is used without prior modification by @code{makecontext}. The return value in this case is @code{0}. If the -function fails it returns @code{-1} and set @var{errno} accordingly. +function fails it returns @code{-1} and sets @var{errno} accordingly. @end deftypefun @heading Example for SVID Context Handling The easiest way to use the context handling functions is as a replacement for @code{setjmp} and @code{longjmp}. The context contains -on most platforms more information which might lead to less surprises -but this also means using these functions is more expensive (beside +on most platforms more information which may lead to fewer surprises +but this also means using these functions is more expensive (besides being less portable). @smallexample @@ -484,11 +486,11 @@ and then resume where execution was stopped. This an example how the context functions can be used to implement co-routines or cooperative multi-threading. All that has to be done is to call every once in a while @code{swapcontext} to continue running a -different context. It is not allowed to do the context switching from -the signal handler directly since neither @code{setcontext} nor -@code{swapcontext} are functions which can be called from a signal -handler. But setting a variable in the signal handler and checking it -in the body of the functions which are executed. Since -@code{swapcontext} is saving the current context it is possible to have -multiple different scheduling points in the code. Execution will always -resume where it was left. +different context. It is not recommended to do the context switching from +the signal handler directly since leaving the signal handler via +@code{setcontext} if the signal was delivered during code that was not +asynchronous signal safe could lead to problems. Setting a variable in +the signal handler and checking it in the body of the functions which +are executed is a safer approach. Since @code{swapcontext} is saving the +current context it is possible to have multiple different scheduling points +in the code. Execution will always resume where it was left. diff --git a/manual/signal.texi b/manual/signal.texi index f0e57ddbe4..77f3d7cfda 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -2139,18 +2139,11 @@ return from that handler will resume a primitive; otherwise, return from that handler will cause @code{EINTR}. @xref{Flags for Sigaction}. Another way to specify the choice is with the @code{siginterrupt} -function. @xref{BSD Handler}. +function. @xref{BSD Signal Handling}. -@c !!! not true now about _BSD_SOURCE When you don't specify with @code{sigaction} or @code{siginterrupt} what a particular handler should do, it uses a default choice. The default -choice in @theglibc{} depends on the feature test macros you have -defined. If you define @code{_BSD_SOURCE} or @code{_GNU_SOURCE} before -calling @code{signal}, the default is to resume primitives; otherwise, -the default is to make them fail with @code{EINTR}. (The library -contains alternate versions of the @code{signal} function, and the -feature test macros determine which one you really call.) @xref{Feature -Test Macros}. +choice in @theglibc{} is to make primitives fail with @code{EINTR}. @cindex EINTR, and restarting interrupted primitives @cindex restarting interrupted primitives @cindex interrupting primitives @@ -2622,7 +2615,7 @@ The prototype for the @code{sigprocmask} function is in @file{signal.h}. Note that you must not use @code{sigprocmask} in multi-threaded processes, because each thread has its own signal mask and there is no single process -signal mask. According to POSIX, the behavior of @code{sigprocmask} in a +signal mask. According to POSIX, the behavior of @code{sigprocmask} in a multi-threaded process is ``unspecified''. Instead, use @code{pthread_sigmask}. @ifset linuxthreads @@ -3313,101 +3306,15 @@ BSD Unix. There are many similarities between the BSD and POSIX signal handling facilities, because the POSIX facilities were inspired by the BSD facilities. Besides having different names for all the functions to -avoid conflicts, the main differences between the two are: - -@itemize @bullet -@item -BSD Unix represents signal masks as an @code{int} bit mask, rather than -as a @code{sigset_t} object. - -@item -The BSD facilities use a different default for whether an interrupted -primitive should fail or resume. The POSIX facilities make system -calls fail unless you specify that they should resume. With the BSD -facility, the default is to make system calls resume unless you say they -should fail. @xref{Interrupted Primitives}. -@end itemize +avoid conflicts, the main difference between the two is that BSD Unix +represents signal masks as an @code{int} bit mask, rather than as a +@code{sigset_t} object. The BSD facilities are declared in @file{signal.h}. @pindex signal.h -@menu -* BSD Handler:: BSD Function to Establish a Handler. -* Blocking in BSD:: BSD Functions for Blocking Signals. -@end menu - -@node BSD Handler -@subsection BSD Function to Establish a Handler - -@comment signal.h -@comment BSD -@deftp {Data Type} {struct sigvec} -This data type is the BSD equivalent of @code{struct sigaction} -(@pxref{Advanced Signal Handling}); it is used to specify signal actions -to the @code{sigvec} function. It contains the following members: - -@table @code -@item sighandler_t sv_handler -This is the handler function. - -@item int sv_mask -This is the mask of additional signals to be blocked while the handler -function is being called. - -@item int sv_flags -This is a bit mask used to specify various flags which affect the -behavior of the signal. You can also refer to this field as -@code{sv_onstack}. -@end table -@end deftp - -These symbolic constants can be used to provide values for the -@code{sv_flags} field of a @code{sigvec} structure. This field is a bit -mask value, so you bitwise-OR the flags of interest to you together. - @comment signal.h -@comment BSD -@deftypevr Macro int SV_ONSTACK -If this bit is set in the @code{sv_flags} field of a @code{sigvec} -structure, it means to use the signal stack when delivering the signal. -@end deftypevr - -@comment signal.h -@comment BSD -@deftypevr Macro int SV_INTERRUPT -If this bit is set in the @code{sv_flags} field of a @code{sigvec} -structure, it means that system calls interrupted by this kind of signal -should not be restarted if the handler returns; instead, the system -calls should return with a @code{EINTR} error status. @xref{Interrupted -Primitives}. -@end deftypevr - -@comment signal.h -@comment Sun -@deftypevr Macro int SV_RESETHAND -If this bit is set in the @code{sv_flags} field of a @code{sigvec} -structure, it means to reset the action for the signal back to -@code{SIG_DFL} when the signal is received. -@end deftypevr - -@comment signal.h -@comment BSD -@deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action}, struct sigvec *@var{old-action}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c This is mostly a safe wrapper for sigaction. The exception are -@c systems that lack SA_RESETHAND, in which a signal handler wrapper is -@c used that calls sigaction to reset the handler before calling the -@c user-supplied handler; it's unlikely that this emulation is used -@c anywhere, for user-supplied flags and mask don't seem to be used -@c the way one would expect. -This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal -Handling}); it installs the action @var{action} for the signal @var{signum}, -returning information about the previous action in effect for that signal -in @var{old-action}. -@end deftypefun - -@comment signal.h -@comment BSD +@comment XPG @deftypefun int siginterrupt (int @var{signum}, int @var{failflag}) @safety{@prelim{}@mtunsafe{@mtasuconst{:@mtssigintr{}}}@asunsafe{}@acunsafe{@acucorrupt{}}} @c This calls sigaction twice, once to get the current sigaction for the @@ -3424,9 +3331,6 @@ true, handling @var{signum} causes these primitives to fail with error code @code{EINTR}. @xref{Interrupted Primitives}. @end deftypefun -@node Blocking in BSD -@subsection BSD Functions for Blocking Signals - @comment signal.h @comment BSD @deftypefn Macro int sigmask (int @var{signum}) diff --git a/manual/socket.texi b/manual/socket.texi index 6ee82010f7..1d9d527488 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -742,7 +742,7 @@ features, and will eventually replace IPv4. To create a socket in the IPv4 Internet namespace, use the symbolic name @code{PF_INET} of this namespace as the @var{namespace} argument to @code{socket} or @code{socketpair}. For IPv6 addresses you need the -macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. +macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. @pindex sys/socket.h @comment sys/socket.h @@ -1110,7 +1110,7 @@ it in the @code{struct in_addr} that @var{addr} points to. This function converts the IPv4 Internet host address @var{name} from the standard numbers-and-dots notation into binary data. If the input is not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an -obsolete interface to @code{inet_aton}, described immediately above. It +obsolete interface to @code{inet_aton}, described immediately above. It is obsolete because @code{INADDR_NONE} is a valid address (255.255.255.255), and @code{inet_aton} provides a cleaner way to indicate error return. @@ -1126,8 +1126,8 @@ indicate error return. @c tolower dup @mtslocale @c isspace dup @mtslocale This function extracts the network number from the address @var{name}, -given in the standard numbers-and-dots notation. The returned address is -in host order. If the input is not valid, @code{inet_network} returns +given in the standard numbers-and-dots notation. The returned address is +in host order. If the input is not valid, @code{inet_network} returns @code{-1}. The function works only with traditional IPv4 class A, B and C network @@ -1419,7 +1419,7 @@ allows the caller to specify the desired address family (e.g.@: The @code{gethostbyaddr} function returns information about the host with Internet address @var{addr}. The parameter @var{addr} is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address +address. The @var{length} argument is the size (in bytes) of the address at @var{addr}. @var{format} specifies the address format; for an IPv4 Internet address, specify a value of @code{AF_INET}; for an IPv6 Internet address, use @code{AF_INET6}. @@ -1550,15 +1550,15 @@ 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. The +@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 +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 +@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}. @@ -1634,7 +1634,7 @@ allows the caller to specify the desired address family (e.g.@: The @code{gethostbyaddr_r} function returns information about the host with Internet address @var{addr}. The parameter @var{addr} is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 -address. The @var{length} argument is the size (in bytes) of the address +address. The @var{length} argument is the size (in bytes) of the address at @var{addr}. @var{format} specifies the address format; for an IPv4 Internet address, specify a value of @code{AF_INET}; for an IPv6 Internet address, use @code{AF_INET6}. diff --git a/manual/startup.texi b/manual/startup.texi index a5d2d2f5e2..9a091a5151 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -379,9 +379,8 @@ reflect automatically in the environment. This also requires that variable is removed from the environment. The same applies of course to dynamically allocated variables which are freed later. -This function is part of the extended Unix interface. Since it was also -available in old SVID libraries you should define either -@var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header. +This function is part of the extended Unix interface. You should define +@var{_XOPEN_SOURCE} before including any header. @end deftypefun diff --git a/manual/stdio.texi b/manual/stdio.texi index 1161a9a90a..e40717034c 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -541,7 +541,7 @@ another thread. @deftypefun void funlockfile (FILE *@var{stream}) @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}} The @code{funlockfile} function releases the internal locking object of -the stream @var{stream}. The stream must have been locked before by a +the stream @var{stream}. The stream must have been locked before by a call to @code{flockfile} or a successful call of @code{ftrylockfile}. The implicit locking performed by the stream operations do not count. The @code{funlockfile} function does not return an error status and the @@ -1298,7 +1298,8 @@ back in @code{*@var{n}}. If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}} to zero, before the call, then @code{getline} allocates the initial -buffer for you by calling @code{malloc}. +buffer for you by calling @code{malloc}. This buffer remains allocated +even if @code{getline} encounters errors and is unable to read any bytes. In either case, when @code{getline} returns, @code{*@var{lineptr}} is a @code{char *} which points to the text of the line. @@ -2547,7 +2548,7 @@ address of a @code{char *} object, and a successful call to location. The return value is the number of characters allocated for the buffer, or -less than zero if an error occurred. Usually this means that the buffer +less than zero if an error occurred. Usually this means that the buffer could not be allocated. Here is how to use @code{asprintf} to get the same result as the @@ -5304,26 +5305,26 @@ otherwise. @comment stdio.h @comment GNU -@deftp {Data Type} cookie_read_function +@deftp {Data Type} cookie_read_function_t This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_write_function +@deftp {Data Type} cookie_write_function_t The data type of the write function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_seek_function +@deftp {Data Type} cookie_seek_function_t The data type of the seek function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_close_function +@deftp {Data Type} cookie_close_function_t The data type of the close function for a custom stream. @end deftp diff --git a/manual/string.texi b/manual/string.texi index 6dcd4aff44..5f8a17ec48 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -1308,7 +1308,7 @@ we find a digit in each string - then we enter a special comparison mode, where each sequence of digits is taken as a whole. If we reach the end of these two parts without noticing a difference, we return to the standard comparison mode. There are two types of numeric parts: -"integral" and "fractional" (those begin with a '0'). The types +"integral" and "fractional" (those begin with a '0'). The types of the numeric parts affect the way we sort them: @itemize @bullet @@ -1572,8 +1572,8 @@ sort_strings_fast (char **array, int nstrings) @} /* @r{Sort @code{temp_array} by comparing transformed strings.} */ - qsort (temp_array, sizeof (struct sorter), - nstrings, compare_elements); + qsort (temp_array, nstrings, + sizeof (struct sorter), compare_elements); /* @r{Put the elements back in the permanent array} @r{in their sorted order.} */ @@ -2258,9 +2258,9 @@ on different systems. @comment libgen.h @comment XPG -@deftypefun {char *} basename (const char *@var{path}) +@deftypefun {char *} basename (char *@var{path}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This is the standard XPG defined @code{basename}. It is similar in +This is the standard XPG defined @code{basename}. It is similar in spirit to the GNU version, but may modify the @var{path} by removing trailing '/' characters. If the @var{path} is made up entirely of '/' characters, then "/" will be returned. Also, if @var{path} is @@ -2788,5 +2788,13 @@ The @code{envz_strip} function removes any null entries from @var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. @end deftypefun +@comment envz.h +@comment GNU +@deftypefun {void} envz_remove (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}) +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +The @code{envz_remove} function removes an entry named @var{name} from +@var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}. +@end deftypefun + @c FIXME this are undocumented: @c strcasecmp_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcasecmp diff --git a/manual/summary.awk b/manual/summary.awk index f13140995e..2d02adec79 100644 --- a/manual/summary.awk +++ b/manual/summary.awk @@ -1,5 +1,5 @@ # awk script to create summary.texinfo from the library texinfo files. -# Copyright (C) 1992-2014 Free Software Foundation, Inc. +# Copyright (C) 1992-2015 Free Software Foundation, Inc. # This file is part of the GNU C Library. # The GNU C Library is free software; you can redistribute it and/or diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index 1c9f51b1b5..e6c44d6366 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -790,7 +790,7 @@ end of file reached, @comment mntent.h @comment BSD @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) -@safety{@prelim{}@mtunsafe{@mtasurace{:stream} @mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +@safety{@prelim{}@mtsafe{@mtsrace{:stream} @mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} @c addmntent @mtasurace:stream @mtslocale @asucorrupt @acucorrupt @c fseek dup @asucorrupt @acucorrupt [no @aculock] @c encode_name ok diff --git a/manual/texinfo.tex b/manual/texinfo.tex index a06709bedc..1dd75b21e2 100644 --- a/manual/texinfo.tex +++ b/manual/texinfo.tex @@ -3,11 +3,11 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2013-11-26.10} +\def\texinfoversion{2014-05-05.10} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. +% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -1138,10 +1138,10 @@ output) for that.)} \ifpdf % - % Color manipulation macros based on pdfcolor.tex, + % Color manipulation macros using ideas from 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. The dark red here is dark enough to print on paper as + % 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} @@ -2146,7 +2146,7 @@ end \let\tenttsl=\secttsl \def\curfontsize{sec}% \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} + \resetmathfonts \setleading{17pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc @@ -2575,12 +2575,12 @@ end \let\file=\code \let\option=\code -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% 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. +% @uref (abbreviation for `urlref') aka @url takes an optional +% (comma-separated) 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. -% secret option to allow changing PDF output to show only the second +% TeX-only 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 @@ -2650,8 +2650,10 @@ end % we put a little stretch before and after the breakable chars, to help % line breaking of long url's. The unequal skips make look better in % cmtt at least, especially for dots. -\def\urefprestretch{\urefprebreak \hskip0pt plus.13em } -\def\urefpoststretch{\urefpostbreak \hskip0pt plus.1em } +\def\urefprestretchamount{.13em} +\def\urefpoststretchamount{.1em} +\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax} +\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax} % \def\urefcodeamp{\urefprestretch \&\urefpoststretch} \def\urefcodedot{\urefprestretch .\urefpoststretch} @@ -3934,18 +3936,22 @@ end % multitable-only commands. % -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. \everycr resets \everytab so we don't have to +% @headitem starts a heading row, which we typeset in bold. Assignments +% have to be global since we are inside the implicit group of an +% alignment entry. \everycr below resets \everytab so we don't have to % undo it ourselves. \def\headitemfont{\b}% for people to use in the template row; not changeable \def\headitem{% \checkenv\multitable \crcr + \gdef\headitemcrhook{\nobreak}% attempt to avoid page break after headings \global\everytab={\bf}% can't use \headitemfont since the parsing differs \the\everytab % for the first item }% % +% default for tables with no headings. +\let\headitemcrhook=\relax +% % A \tab used to include \hskip1sp. But then the space in a template % line is not enough. That is bad. So let's go back to just `&' until % we again encounter the problem the 1sp was intended to solve. @@ -3976,15 +3982,15 @@ end % \everycr = {% \noalign{% - \global\everytab={}% + \global\everytab={}% Reset from possible headitem. \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. + % + % Check for saved footnotes, etc.: \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. + % + % Perhaps a \nobreak, then reset: + \headitemcrhook + \global\let\headitemcrhook=\relax }% }% % @@ -4426,7 +4432,7 @@ end % complicated, when \tex is in effect and \{ is a \delimiter again. % We can't use \lbracecmd and \rbracecmd because texindex assumes % braces and backslashes are used only as delimiters. Perhaps we - % should define @lbrace and @rbrace commands a la @comma. + % should use @lbracechar and @rbracechar? \def\{{{\tt\char123}}% \def\}{{\tt\char125}}% % @@ -4447,8 +4453,7 @@ end % @end macro % ... % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. + % This is not enough to reproduce the bug, but it gives the flavor. % % Sample whatsit resulting: % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} @@ -4649,8 +4654,21 @@ end \definedummyword\verb \definedummyword\w \definedummyword\xref + % + % Consider: + % @macro mkind{arg1,arg2} + % @cindex \arg2\ + % @end macro + % @mkind{foo, bar} + % The space after the comma will end up in the temporary definition + % that we make for arg2 (see \parsemargdef ff.). We want all this to be + % expanded for the sake of the index, so we end up just seeing "bar". + \let\xeatspaces = \eatspaces } +% For testing: output @{ and @} in index sort strings as \{ and \}. +\newif\ifusebracesinindexes + % \indexnofonts is used when outputting the strings to sort the index % by, and when constructing control sequence names. It eliminates all % control sequences and just writes whatever the best ASCII sort string @@ -4679,11 +4697,16 @@ end % Unfortunately, texindex is not prepared to handle braces in the % content at all. So for index sorting, we map @{ and @} to strings % starting with |, since that ASCII character is between ASCII { and }. - \def\{{|a}% - \def\lbracechar{|a}% + \ifusebracesinindexes + \def\lbracechar{\lbracecmd}% + \def\rbracechar{\rbracecmd}% + \else + \def\lbracechar{|a}% + \def\rbracechar{|b}% + \fi + \let\{=\lbracechar + \let\}=\rbracechar % - \def\}{|b}% - \def\rbracechar{|b}% % % Non-English letters. \def\AA{AA}% @@ -6411,8 +6434,6 @@ end % side, and for 6pt waste from % each corner char, and rule thickness \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% % % If this cartouche directly follows a sectioning command, we need the % \parskip glue (backspaced over by default) or the cartouche can @@ -6579,9 +6600,13 @@ end % @raggedright does more-or-less normal line breaking but no right -% justification. From plain.tex. +% justification. From plain.tex. Don't stretch around special +% characters in urls in this environment, since the stretch at the right +% should be enough. \envdef\raggedright{% - \rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax + \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax + \def\urefprestretchamount{0pt}% + \def\urefpoststretchamount{0pt}% } \let\Eraggedright\par @@ -7474,7 +7499,7 @@ end % Parse the optional {params} list. Set up \paramno and \paramlist % so \defmacro knows what to do. Define \macarg.BLAH for each BLAH -% in the params list to some hook where the argument si to be expanded. If +% in the params list to some hook where the argument is to be expanded. If % there are less than 10 arguments that hook is to be replaced by ##N where N % is the position in that list, that is to say the macro arguments are to be % defined `a la TeX in the macro body. @@ -8336,6 +8361,7 @@ end \gdef\footnote{% \let\indent=\ptexindent \let\noindent=\ptexnoindent + % \global\advance\footnoteno by \@ne \edef\thisfootno{$^{\the\footnoteno}$}% % @@ -8359,6 +8385,11 @@ end % \gdef\dofootnote{% \insert\footins\bgroup + % + % Nested footnotes are not supported in TeX, that would take a lot + % more work. (\startsavinginserts does not suffice.) + \let\footnote=\errfootnote + % % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. % So reset some parameters. @@ -8396,13 +8427,19 @@ end } }%end \catcode `\@=11 +\def\errfootnote{% + \errhelp=\EMsimple + \errmessage{Nested footnotes not supported in texinfo.tex, + even though they work in makeinfo; sorry} +} + % In case a @footnote appears in a vbox, save the footnote text and create % the real \insert just after the vbox finished. Otherwise, the insertion % would be lost. % Similarly, if a @footnote appears inside an alignment, save the footnote % text to a box and make the \insert when a row of the table is finished. % And the same can be done for other insert classes. --kasal, 16nov03. - +% % Replace the \insert primitive by a cheating macro. % Deeper inside, just make sure that the saved insertions are not spilled % out prematurely. diff --git a/manual/threads.texi b/manual/threads.texi index e088b26a15..4d080d44cf 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -20,6 +20,8 @@ The @glibcadj{} implements functions to allow users to create and manage data specific to a thread. Such data may be destroyed at thread exit, if a destructor is provided. The following functions are defined: +@comment pthread.h +@comment POSIX @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*)) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_key_create ok @@ -34,6 +36,8 @@ data destructors or even as members of the thread-specific data, since the latter is passed as an argument to the destructor function. @end deftypefun +@comment pthread.h +@comment POSIX @deftypefun int pthread_key_delete (pthread_key_t @var{key}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_key_delete ok @@ -45,6 +49,8 @@ destructor for the thread-specific data is not called during destruction, nor is it called during thread exit. @end deftypefun +@comment pthread.h +@comment POSIX @deftypefun void *pthread_getspecific (pthread_key_t @var{key}) @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} @c pthread_getspecific ok @@ -52,6 +58,8 @@ Return the thread-specific data associated with @var{key} in the calling thread. @end deftypefun +@comment pthread.h +@comment POSIX @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value}) @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} @c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem @@ -84,6 +92,8 @@ the standard. @Theglibc{} provides non-standard API functions to set and get the default attributes used in the creation of threads in a process. +@comment pthread.h +@comment GNU @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} @c Takes lock around read from default_pthread_attr. @@ -92,6 +102,8 @@ function returns @math{0} on success and a non-zero error code on failure. @end deftypefun +@comment pthread.h +@comment GNU @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem diff --git a/manual/time.texi b/manual/time.texi index d46d2c8f4b..f94cbe4887 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -104,7 +104,7 @@ The @code{struct timeval} structure represents an elapsed time. It is declared in @file{sys/time.h} and has the following members: @table @code -@item long int tv_sec +@item time_t tv_sec This represents the number of whole seconds of elapsed time. @item long int tv_usec @@ -123,7 +123,7 @@ The @code{struct timespec} structure represents an elapsed time. It is declared in @file{time.h} and has the following members: @table @code -@item long int tv_sec +@item time_t tv_sec This represents the number of whole seconds of elapsed time. @item long int tv_nsec @@ -1335,7 +1335,7 @@ Ordinary characters appearing in the @var{template} are copied to the output string @var{s}; this can include multibyte character sequences. Conversion specifiers are introduced by a @samp{%} character, followed by an optional flag which can be one of the following. These flags -are all GNU extensions. The first three affect only the output of +are all GNU extensions. The first three affect only the output of numbers: @table @code @@ -2449,7 +2449,7 @@ EST+5EDT,M3.2.0/2,M11.1.0/2 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 +March's fourth Thursday 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 @@ -2509,18 +2509,19 @@ rule for choosing the default time zone, so there is little we can say about them. @cindex time zone database -@pindex /share/lib/zoneinfo +@pindex /usr/share/zoneinfo @pindex zoneinfo If @var{characters} begins with a slash, it is an absolute file name; otherwise the library looks for the file -@w{@file{/share/lib/zoneinfo/@var{characters}}}. The @file{zoneinfo} +@w{@file{/usr/share/zoneinfo/@var{characters}}}. The @file{zoneinfo} directory contains data files describing local time zones in many different parts of the world. The names represent major cities, with subdirectories for geographical areas; for example, @file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}. These data files are installed by the system administrator, who also sets @file{/etc/localtime} to point to the data file for the local time -zone. @Theglibc{} comes with a large database of time zone +zone. The files typically come from the @url{http://www.iana.org/time-zones, +Time Zone Database} of time zone and daylight saving time information for most regions of the world, which is maintained by a community of volunteers and put in the public domain. diff --git a/manual/tsort.awk b/manual/tsort.awk index 16c0a1e302..cae084d713 100644 --- a/manual/tsort.awk +++ b/manual/tsort.awk @@ -1,6 +1,6 @@ #! /usr/bin/awk -f # Generate topologically sorted list of manual chapters. -# Copyright (C) 1998-2014 Free Software Foundation, Inc. +# Copyright (C) 1998-2015 Free Software Foundation, Inc. # Written by Ulrich Drepper <drepper@cygnus.com>, 1998. BEGIN { diff --git a/manual/users.texi b/manual/users.texi index 93b25ebcf4..e8f0f3bdf3 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -71,7 +71,7 @@ in a data base which you can access as described in @ref{User Database}. @cindex group ID Users are classified in @dfn{groups}. Each user name belongs to one @dfn{default group} and may also belong to any number of -@dfn{supplementary groups}. Users who are members of the same group can +@dfn{supplementary groups}. Users who are members of the same group can share resources (such as files) that are not accessible to users who are not a member of that group. Each group has a @dfn{group name} and @dfn{group ID}. @xref{Group Database}, for how to find information @@ -830,7 +830,7 @@ special user. Be cautious about using the @code{exec} functions in combination with changing the effective user ID. Don't let users of your program execute arbitrary programs under a changed user ID. Executing a shell is -especially bad news. Less obviously, the @code{execlp} and @code{execvp} +especially bad news. Less obviously, the @code{execlp} and @code{execvp} functions are a potential risk (since the program they execute depends on the user's @code{PATH} environment variable). @@ -927,8 +927,9 @@ this function or to @code{cuserid}. @comment stdio.h @comment POSIX.1 @deftypefun {char *} cuserid (char *@var{string}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} -@c cuserid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@safety{@prelim{}@mtunsafe{@mtasurace{:cuserid/!string} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} +@c cuserid @mtasurace:cuserid/!string @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem +@c if string is NULL, cuserid will overwrite and return a static buffer @c geteuid dup ok @c getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem @c strncpy dup ok |