mirror/glibc
2
0
Fork 0
mirror of git://sourceware.org/git/glibc.git synced 2024-11-21 01:12:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update.

Browse Source 
1999-08-27  Ulrich Drepper  <drepper@cygnus.com>

	* manual/argp.texi: Fixing language and types.
	* manual/conf.texi: Likewise.
	* manual/contrib.texi: Likewise.
	* manual/filesys.texi: Likewise.
	* manual/install.texi: Likewise.
	* manual/job.texi: Likewise.
	* manual/lang.texi: Likewise.
	* manual/llio.texi: Likewise.
	* manual/math.texi: Likewise.
	* manual/nss.texi: Likewise.
	* manual/pipe.texi: Likewise.
	* manual/signal.texi: Likewise.
	* manual/socket.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/sysinfo.texi: Likewise.
	* manual/users.texi: Likewise.
	Patches by Neil Booth <NeilB@earthling.net>.
This commit is contained in:
Ulrich Drepper 1999-08-27 19:06:58 +00:00
parent 77faa35416
commit 04b9968b39
17 changed files with 1071 additions and 1080 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
ChangeLog
View File

@ -1,3 +1,23 @@
1999-08-27 Ulrich Drepper <drepper@cygnus.com>
* manual/argp.texi: Fixing language and types.
* manual/conf.texi: Likewise.
* manual/contrib.texi: Likewise.
* manual/filesys.texi: Likewise.
* manual/install.texi: Likewise.
* manual/job.texi: Likewise.
* manual/lang.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/math.texi: Likewise.
* manual/nss.texi: Likewise.
* manual/pipe.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/users.texi: Likewise.
Patches by Neil Booth <NeilB@earthling.net>.
1999-08-25 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/i386/fpu/bits/mathinline.h (__finite): Mark constant as

4
manual/argp.texi
View File

@ -112,7 +112,7 @@ flag is used).
@comment GNU
@deftypevar {const char *} argp_program_bug_address
If defined or set by the user program to a non-zero value,
@code{argp_program_bug_address} should point to string that is the
@code{argp_program_bug_address} should point to a string that is the
bug-reporting address for the program. It will be printed at the end of
the standard output for the @samp{--help} option, embedded in a sentence
that says something like @samp{Report bugs to @var{address}.}.
@ -180,7 +180,7 @@ If non-zero, a string describing what non-option arguments are wanted by
this parser; it is only used to print the @samp{Usage:} message. If it
contains newlines, the strings separated by them are considered
alternative usage patterns, and printed on separate lines (lines after
the first are prefix by @samp{ or: } instead of @samp{Usage:}).
the first are prefixed by @samp{ or: } instead of @samp{Usage:}).
@item const char *doc
If non-zero, a string containing extra text to be printed before and

60
manual/conf.texi
View File

@ -446,7 +446,7 @@ Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}.
@comment unistd.h
@comment POSIX.1
@item _SC_SHARED_MEMORY_OBJECTS
Inquire about the parameter corresponding to
Inquire about the parameter corresponding to@*
@code{_POSIX_SHARED_MEMORY_OBJECTS}.
@comment unistd.h
@ -580,7 +580,7 @@ Inquire about the parameter corresponding to @code{_POSIX_THREADS}.
@comment unistd.h
@comment POSIX.1
@item _SC_THREAD_SAFE_FUNCTIONS
Inquire about the parameter corresponding to
Inquire about the parameter corresponding to@*
@code{_POSIX_THREAD_SAFE_FUNCTIONS}.
@comment unistd.h
@ -627,13 +627,13 @@ Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}.
@comment unistd.h
@comment POSIX.1
@item _SC_THREAD_ATTR_STACKADDR
Inquire about the parameter corresponding to
Inquire about the parameter corresponding to@*a
@code{_POSIX_THREAD_ATTR_STACKADDR}.
@comment unistd.h
@comment POSIX.1
@item _SC_THREAD_ATTR_STACKSIZE
Inquire about the parameter corresponding to
Inquire about the parameter corresponding to@*
@code{_POSIX_THREAD_ATTR_STACKSIZE}.
@comment unistd.h
@ -760,27 +760,27 @@ Inquire about the virtual memory page size of the machine.
@comment unistd.h
@comment GNU
@item _SC_NPROCESSORS_CONF
Inquire about number of configured processors.
Inquire about the number of configured processors.
@comment unistd.h
@comment GNU
@item _SC_NPROCESSORS_ONLN
Inquire about number of processors online.
Inquire about the number of processors online.
@comment unistd.h
@comment GNU
@item _SC_PHYS_PAGES
Inquire about number of physical pages in the system.
Inquire about the number of physical pages in the system.
@comment unistd.h
@comment GNU
@item _SC_AVPHYS_PAGES
Inquire about number of available physical pages in the system.
Inquire about the number of available physical pages in the system.
@comment unistd.h
@comment GNU
@item _SC_ATEXIT_MAX
Inquire about number of functions which can be registered as termination
Inquire about the number of functions which can be registered as termination
functions for @code{atexit}; @pxref{Cleanups on Exit}.
@comment unistd.h
@ -831,41 +831,41 @@ Inquire about the parameter corresponding to @code{_XOPEN_XPG4}.
@comment unistd.h
@comment X/Open
@item _SC_CHAR_BIT
Inquire about number of bits in a variable of type @code{char}.
Inquire about the number of bits in a variable of type @code{char}.
@comment unistd.h
@comment X/Open
@item _SC_CHAR_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{char}.
@comment unistd.h
@comment X/Open
@item _SC_CHAR_MIN
Inquire about minimum value which can be stored in a variable of type
Inquire about the minimum value which can be stored in a variable of type
@code{char}.
@comment unistd.h
@comment X/Open
@item _SC_INT_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{int}.
@comment unistd.h
@comment X/Open
@item _SC_INT_MIN
Inquire about minimum value which can be stored in a variable of type
Inquire about the minimum value which can be stored in a variable of type
@code{int}.
@comment unistd.h
@comment X/Open
@item _SC_LONG_BIT
Inquire about number of bits in a variable of type @code{long int}.
Inquire about the number of bits in a variable of type @code{long int}.
@comment unistd.h
@comment X/Open
@item _SC_WORD_BIT
Inquire about number of bits in a variable of a register word.
Inquire about the number of bits in a variable of a register word.
@comment unistd.h
@comment X/Open
@ -876,61 +876,61 @@ character value.
@comment unistd.h
@comment X/Open
@item _SC_NZERO
Inquire value used to internally represent the zero priority level for
Inquire about the value used to internally represent the zero priority level for
the process execution.
@comment unistd.h
@comment X/Open
@item SC_SSIZE_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{ssize_t}.
@comment unistd.h
@comment X/Open
@item _SC_SCHAR_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{signed char}.
@comment unistd.h
@comment X/Open
@item _SC_SCHAR_MIN
Inquire about minimum value which can be stored in a variable of type
Inquire about the minimum value which can be stored in a variable of type
@code{signed char}.
@comment unistd.h
@comment X/Open
@item _SC_SHRT_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{short int}.
@comment unistd.h
@comment X/Open
@item _SC_SHRT_MIN
Inquire about minimum value which can be stored in a variable of type
Inquire about the minimum value which can be stored in a variable of type
@code{short int}.
@comment unistd.h
@comment X/Open
@item _SC_UCHAR_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{unsigned char}.
@comment unistd.h
@comment X/Open
@item _SC_UINT_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{unsigned int}.
@comment unistd.h
@comment X/Open
@item _SC_ULONG_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{unsigned long int}.
@comment unistd.h
@comment X/Open
@item _SC_USHRT_MAX
Inquire about maximum value which can be stored in a variable of type
Inquire about the maximum value which can be stored in a variable of type
@code{unsigned short int}.
@comment unistd.h
@ -956,12 +956,12 @@ Inquire about the parameter corresponding to @code{NL_NMAX}.
@comment unistd.h
@comment X/Open
@item _SC_NL_SETMAX
Inquire about the parameter corresponding to @code{NL_SETMAX}.
Inquire about the parameter corresponding to @code{NL_SETMAX}.
@comment unistd.h
@comment X/Open
@item _SC_NL_TEXTMAX
Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
@end table
@node Examples of Sysconf
@ -1023,7 +1023,7 @@ system you are using can go that far.
The most restrictive limit permitted by POSIX for the maximum number of
I/O operations that can be specified in a list I/O call. The value of
this constant is @code{2}; thus you can add up to two new entries
of the list of outstandard operations.
of the list of outstanding operations.
@comment limits.h
@comment POSIX.1
@ -1191,7 +1191,7 @@ that big! Use dynamic allocation (@pxref{Memory Allocation}) instead.
POSIX defines certain system-specific options in the system calls for
operating on files. Some systems support these options and others do
not. Since these options are provided in the kernel, not in the
library, simply using the GNU C library does not guarantee any of these
library, simply using the GNU C library does not guarantee that any of these
features is supported; it depends on the system you are using. They can
also vary between file systems on a single machine.

2
manual/contrib.texi
View File

@ -8,7 +8,7 @@ contributed or worked on by other people.
@itemize @bullet
@item
The @code{getopt} function and related code were written by
The @code{getopt} function and related code was written by
Richard Stallman, @w{David J.} MacKenzie, and @w{Roland McGrath}.
@item

825
manual/filesys.texi
View File

File diff suppressed because it is too large Load Diff

79
manual/install.texi
View File

@ -49,8 +49,8 @@ GNU Make, and possibly others. @xref{Tools for Compilation}, below.
@cindex configuring
@cindex compiling
GNU Libc can be compiled in the source directory but we strongly advise to
build in a separate build directory. For example, if you have unpacked
GNU libc can be compiled in the source directory, but we strongly advise to
build it in a separate build directory. For example, if you have unpacked
the glibc sources in @file{/src/gnu/glibc-2.1.0}, create a directory
@file{/src/gnu/glibc-build} to put the object files in. This allows to
remove the whole build directory in case an error occurs which is the
@ -64,7 +64,7 @@ $ ../glibc-2.1.0/configure @var{args...}
@end smallexample
Please note that even if you're building in a separate build directory,
the compiliation needs to modify a few files in the source
the compilation needs to modify a few files in the source
directory, especially some files in the manual subdirectory.
@noindent
@ -74,14 +74,14 @@ only two: @samp{--prefix} and @samp{--enable-add-ons}. The
This defaults to @file{/usr/local}. The @samp{--enable-add-ons} option
tells configure to use all the add-on bundles it finds in the source
directory. Since important functionality is provided in add-ons, you
should always give this option.
should always specify this option.
It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
the environment when running @code{configure}. @var{CC} selects the C
compiler that will be used, and @var{CFLAGS} sets optimization options
for the compiler.
Here are all the useful options known by @code{configure}:
The following list describes all of the available options for @code{configure}:
@table @samp
@item --prefix=@var{directory}
@ -91,13 +91,13 @@ Install machine-independent data files in subdirectories of
@item --exec-prefix=@var{directory}
Install the library and other machine-dependent files in subdirectories
of @file{@var{directory}}. The default is to the @samp{--prefix}
directory if that option is given, or @file{/usr/local} otherwise.
directory if that option is specified, or @file{/usr/local} otherwise.
@item --with-headers=@var{directory}
Look for kernel header files in @var{directory}, not
@file{/usr/include}. Glibc needs information from the kernel's private
header files. It will normally look in @file{/usr/include} for them,
but if you give this option, it will look in @var{DIRECTORY} instead.
but if you specify this option, it will look in @var{DIRECTORY} instead.
This option is primarily of use on a system where the headers in
@file{/usr/include} come from an older version of glibc. Conflicts can
@ -107,7 +107,7 @@ compile glibc with a newer set of kernel headers than the ones found in
@file{/usr/include}.
@item --enable-add-ons[=@var{list}]
Enable add-on packages in your source tree. If this option is given
Enable add-on packages in your source tree. If this option is specified
with no list, it enables all the add-on packages it finds. If you do
not wish to use some add-on package that you have present in your source
tree, give this option a list of the add-ons that you @emph{do} want
@ -117,10 +117,10 @@ used, like this: @samp{--enable-add-ons=crypt,linuxthreads}
Use the binutils (assembler and linker) in @file{@var{directory}}, not
the ones the C compiler would default to. You could use this option if
the default binutils on your system cannot deal with all the constructs
in the GNU C library. (@code{configure} will detect the problem and
suppress these constructs, so the library will still be usable, but
functionality may be lost---for example, you can not build a shared libc
with old binutils.)
in the GNU C library. In that case, @code{configure} will detect the problem and
suppress these constructs, so that the library will still be usable, but
functionality may be lost---for example, you can't build a shared libc
with old binutils.
@item --without-fp
Use this option if your computer lacks hardware floating-point support
@ -132,7 +132,7 @@ and your operating system does not emulate an FPU.
@c days, but we recommend you build them in case you need them.
@item --disable-shared
Don't build shared libraries even if we could. Not all systems support
Don't build shared libraries even if it is possible. Not all systems support
shared libraries; you need ELF support and (currently) the GNU linker.
@item --disable-profile
@ -148,7 +148,7 @@ you won't be able to trace bugs through the C library.
@item --disable-versioning
Don't compile the shared libraries with symbol version information.
Doing this will make the library that's built incompatible with old
Doing this will make the resulting library incompatible with old
binaries, so it's not recommended.
@item --enable-static-nss
@ -159,22 +159,22 @@ reconfigured to use a different name database.
@item --build=@var{build-system}
@itemx --host=@var{host-system}
These options are for cross-compiling. If you give them both and
These options are for cross-compiling. If you specify both options and
@var{build-system} is different from @var{host-system}, @code{configure}
will prepare to cross-compile glibc from @var{build-system} to be used
on @var{host-system}. You'll probably need the @samp{--with-headers}
option too, and you may have to override @var{configure}'s selection of
the compiler and/or binutils.
If you give just @samp{--host}, configure will prepare for a native
compile but use what you say instead of guessing what your system is.
If you only specify @samp{--host}, 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, if
configure guesses your machine as @code{i586-pc-linux-gnu} but you want
to compile a library for 386es, give @samp{--host=i386-pc-linux-gnu} or
just @samp{--host=i386-linux} and add the appropriate compiler flags
(@samp{-mcpu=i386} will do the trick) to @var{CFLAGS}.
If you give just @samp{--build}, configure will get confused.
If you specify just @samp{--build}, configure will get confused.
@end table
To build the library and related programs, type @code{make}. This will
@ -200,17 +200,18 @@ Instead, edit the generated @file{Makefile} and uncomment the line
@noindent
You can change the @samp{4} to some other number as appropriate for
your system. Instead of changing the @file{Makefile}, you could give
this option directly to @code{make} and call it as, e.g.
this option directly to @code{make} and call it as, for example,
@code{make PARALLELMFLAGS=-j4}. If you're building in the source
directory, you've got to use the latter approach since in this case no
new @file{Makefile} is generated which you can change.
directory, you must use the latter approach since in this case no
new @file{Makefile} is generated for you to change.
To build and run some test programs which exercise some of the library
facilities, type @code{make check}. This should complete successfully;
if it doesn't, do not use the built library, and report a bug.
@xref{Reporting Bugs}, for how to do that. Note that some of the tests
assume they are not being run by @code{root}. We recommend you compile
and test glibc as an unprivileged user.
To build and run test programs which exercise some of the library
facilities, type @code{make check}. If it does not complete
successfully, do not use the built library, and report a bug after
verifying that the problem is not already known. @xref{Reporting Bugs},
for instructions on reporting bugs. Note that some of the tests assume
they are not being run by @code{root}. We recommend you compile and
test glibc as an unprivileged user.
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.
@ -224,8 +225,8 @@ info}}, but it shouldn't be necessary.
To install the library and its header files, and the Info files of the
manual, type @code{make install}. This will build things if necessary,
before installing them. Don't rely on that; compile everything first.
If you are installing glibc as your primary C library, we recommend you
before installing them. However, you should still compile everything first.
If you are installing glibc as your primary C library, we recommend that you
shut the system down to single-user mode first, and reboot afterward.
This minimizes the risk of breaking things when the library changes out
from underneath.
@ -233,8 +234,8 @@ from underneath.
If you are upgrading from a previous installation of glibc 2.0 or 2.1,
@samp{make install} will do the entire job. If you're upgrading from
Linux libc5 or some other C library, you need to rename the old
@file{/usr/include} directory out of the way before running @samp{make
install}, or you will end up with a mixture of header files from both
@file{/usr/include} directory before running @samp{make install},
or you will end up with a mixture of header files from both
libraries, and you won't be able to compile anything. You may also need
to reconfigure GCC to work with the new library. The easiest way to do
that is to figure out the compiler switches to make it work again
@ -279,7 +280,7 @@ build the GNU C library:
GNU @code{make} 3.75
You need the latest version of GNU @code{make}. Modifying the GNU C
Library to work with other @code{make} programs would be so hard that we
Library to work with other @code{make} programs would be so difficult that we
recommend you port GNU @code{make} instead. @strong{Really.} We
recommend version GNU @code{make} version 3.75 or 3.77. All earlier
versions have severe bugs or lack features. Version 3.76 is known to
@ -418,8 +419,8 @@ they definitely don't work anymore. Porting the library is not hard.
If you are interested in doing a port, please contact the glibc
maintainers by sending electronic mail to @email{bug-glibc@@gnu.org}.
Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
@samp{i586}, or @samp{i686}. All of those configurations produce a
Valid cases of @samp{i@var{x}86} include @samp{i386}, @samp{i486},
@samp{i586}, and @samp{i686}. All of those configurations produce a
library that can run on this processor and newer processors. The GCC
compiler by default generates code that's optimized for the machine it's
configured for and will use the instructions available on that machine.
@ -436,7 +437,7 @@ switches via @var{CFLAGS}.
If you are installing GNU libc on a Linux system, you need to have
the header files from a 2.2 kernel around for reference. You do not
need to use the 2.2 kernel, just have its headers where glibc can get
need to use the 2.2 kernel, just have its headers where glibc can access
at them. The easiest way to do this is to unpack it in a directory
such as @file{/usr/src/linux-2.2.1}. In that directory, run
@samp{make config} and accept all the defaults. Then run @samp{make
@ -483,8 +484,8 @@ errors and omissions in this manual. If you report them, they will get
fixed. If you don't, no one will ever know about them and they will
remain unfixed for all eternity, if not longer.
It is a good idea to check first that the problem was not reported
before. Bugs are documented in two places: The file @file{BUGS}
It is a good idea to verify that the problem has not already been
reported. Bugs are documented in two places: The file @file{BUGS}
describes a number of well known bugs and the bug tracking system has a
WWW interface at
@url{http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl}. The WWW
@ -525,5 +526,5 @@ function's behavior disagrees with the manual, then either the library
or the manual has a bug, so report the disagreement. If you find any
errors or omissions in this manual, please report them to the Internet
address @email{bug-glibc-manual@@gnu.org}. If you refer to specific
sections when reporting on the manual, please include the section names
for easier identification.
sections of the manual, please include the section names for easier
identification.

4
manual/job.texi
View File

@ -1298,7 +1298,7 @@ process.
@comment Unix98
@deftypefun pid_t tcgetsid (int @var{fildes})
This function is used to obtain the process group ID of the session
for which terminal specified by @var{fildes} is the controlling terminal.
for which the terminal specified by @var{fildes} is the controlling terminal.
If the call is successful the group ID is returned. Otherwise the
return value is @code{(pid_t) -1} and the global variable @var{errno}
is set to the following value:
@ -1308,6 +1308,6 @@ The @var{filedes} argument is not a valid file descriptor.
@item ENOTTY
The calling process does not have a controlling terminal, or the file
ins not the controlling terminal.
is not the controlling terminal.
@end table
@end deftypefun

104
manual/lang.texi
View File

@ -51,8 +51,8 @@ without indicating anything might be wrong.
@comment assert.h
@comment ISO
@deftypefn Macro void assert (int @var{expression})
Verify the programmer's belief that @var{expression} should be nonzero
at this point in the program.
Verify the programmer's belief that @var{expression} is nonzero at
this point in the program.
If @code{NDEBUG} is not defined, @code{assert} tests the value of
@var{expression}. If it is false (zero), @code{assert} aborts the
@ -67,7 +67,7 @@ form:
on the standard error stream @code{stderr} (@pxref{Standard Streams}).
The filename and line number are taken from the C preprocessor macros
@code{__FILE__} and @code{__LINE__} and specify where the call to
@code{assert} was written. When using the GNU C compiler, the name of
@code{assert} was made. When using the GNU C compiler, the name of
the function which calls @code{assert} is taken from the built-in
variable @code{__PRETTY_FUNCTION__}; with older compilers, the function
name and following colon are omitted.
@ -95,7 +95,7 @@ Similar to @code{assert}, but verifies that @var{errnum} is zero.
If @code{NDEBUG} is defined, @code{assert_perror} tests the value of
@var{errnum}. If it is nonzero, @code{assert_perror} aborts the program
after a printing a message of the form:
after printing a message of the form:
@smallexample
@file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
@ -109,7 +109,7 @@ name are as for @code{assert}. The error text is the result of
Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h}
is included, the @code{assert_perror} macro does absolutely nothing. It
does not evaluate the argument, so @var{errnum} should not have any side
effects. It is best for @var{errnum} to be a just simple variable
effects. It is best for @var{errnum} to be just a simple variable
reference; often it will be @code{errno}.
This macro is a GNU extension.
@ -117,20 +117,17 @@ This macro is a GNU extension.
@strong{Usage note:} The @code{assert} facility is designed for
detecting @emph{internal inconsistency}; it is not suitable for
reporting invalid input or improper usage by @emph{the user} of the
reporting invalid input or improper usage by the @emph{user} of the
program.
The information in the diagnostic messages printed by the @code{assert}
macro is intended to help you, the programmer, track down the cause of a
bug, but is not really useful for telling a user of your program why his
or her input was invalid or why a command could not be carried out. So
you can't use @code{assert} or @code{assert_perror} to print the error
messages for these eventualities.
What's more, your program should not abort when given invalid input, as
@code{assert} would do---it should exit with nonzero status (@pxref{Exit
Status}) after printing its error messages, or perhaps read another
command or move on to the next input file.
and @code{assert_perror} macro is intended to help you, the programmer,
track down the cause of a bug, but is not really useful for telling a user
of your program why his or her input was invalid or why a command could not
be carried out. What's more, your program should not abort when given
invalid input, as @code{assert} would do---it should exit with nonzero
status (@pxref{Exit Status}) after printing its error messages, or perhaps
read another command or move on to the next input file.
@xref{Error Messages}, for information on printing error messages for
problems that @emph{do not} represent bugs in the program.
@ -256,10 +253,9 @@ func (const char *a, int b, @dots{})
@end smallexample
@noindent
outlines a definition of a function @code{func} which returns an
@code{int} and takes two required arguments, a @code{const char *} and
an @code{int}. These are followed by any number of anonymous
arguments.
defines a function @code{func} which returns an @code{int} and takes two
required arguments, a @code{const char *} and an @code{int}. These are
followed by any number of anonymous arguments.
@strong{Portability note:} For some C compilers, the last required
argument must not be declared @code{register} in the function
@ -303,10 +299,10 @@ values if you try to access too many arguments.
You indicate that you are finished with the argument pointer variable by
calling @code{va_end}.
(In practice, with most C compilers, calling @code{va_end} does nothing
and you do not really need to call it. This is always true in the GNU C
compiler. But you might as well call @code{va_end} just in case your
program is someday compiled with a peculiar compiler.)
(In practice, with most C compilers, calling @code{va_end} does nothing.
This is always true in the GNU C compiler. But you might as well call
@code{va_end} just in case your program is someday compiled with a peculiar
compiler.)
@end enumerate
@xref{Argument Macros}, for the full definitions of @code{va_start},
@ -317,7 +313,7 @@ optional arguments. However, you can pass the @code{va_list} variable
as an argument to another function and perform all or part of step 2
there.
You can perform the entire sequence of the three steps multiple times
You can perform the entire sequence of three steps multiple times
within a single function invocation. If you want to ignore the optional
arguments, you can do these steps zero times.
@ -342,10 +338,9 @@ regardless.
There is no general way for a function to determine the number and type
of the optional arguments it was called with. So whoever designs the
function typically designs a convention for the caller to tell it how
many arguments it has, and what kind. It is up to you to define an
appropriate calling convention for each variadic function, and write all
calls accordingly.
function typically designs a convention for the caller to specify the number
and type of arguments. It is up to you to define an appropriate calling
convention for each variadic function, and write all calls accordingly.
One kind of calling convention is to pass the number of optional
arguments as one of the fixed arguments. This convention works provided
@ -375,11 +370,10 @@ in just this way; see @ref{Executing a File}.
@cindex calling variadic functions
@cindex declaring variadic functions
You don't have to write anything special when you call a variadic function.
Just write the arguments (required arguments, followed by optional ones)
inside parentheses, separated by commas, as usual. But you should prepare
by declaring the function with a prototype, and you must know how the
argument values are converted.
You don't have to do anything special to call a variadic function.
Just put the arguments (required arguments, followed by optional ones)
inside parentheses, separated by commas, as usual. But you must declare
the function with a prototype and know how the argument values are converted.
In principle, functions that are @emph{defined} to be variadic must also
be @emph{declared} to be variadic using a function prototype whenever
@ -406,7 +400,7 @@ type @code{char} or @w{@code{short int}} (whether signed or not) are
promoted to either @code{int} or @w{@code{unsigned int}}, as
appropriate; and that objects of type @code{float} are promoted to type
@code{double}. So, if the caller passes a @code{char} as an optional
argument, it is promoted to an @code{int}, and the function should get
argument, it is promoted to an @code{int}, and the function can access
it with @code{va_arg (@var{ap}, int)}.
Conversion of the required arguments is controlled by the function
@ -467,16 +461,16 @@ use it except for reasons of portability.
Sometimes it is necessary to parse the list of parameters more than once
or one wants to remember a certain position in the parameter list. To
do this one will have to make a copy of the current value of the
argument. But @code{va_list} is an opaque type and it is not guaranteed
that one can simply assign the value of a variable to another one of
type @code{va_list}
do this, one will have to make a copy of the current value of the
argument. But @code{va_list} is an opaque type and one cannot necessarily
assign the value of one variable of type @code{va_list} to another variable
of the same type.
@comment stdarg.h
@comment GNU
@deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
The @code{__va_copy} macro allows copying of objects of type
@code{va_list} even if this is no integral type. The argument pointer
@code{va_list} even if this is not an integral type. The argument pointer
in @var{dest} is initialized to point to the same argument as the
pointer in @var{src}.
@ -484,10 +478,10 @@ This macro is a GNU extension but it will hopefully also be available in
the next update of the ISO C standard.
@end deftypefn
If you want to use @code{__va_copy} you should always be prepared that
this macro is not available. On architectures where a simple assignment
is invalid it hopefully is and so one should always write something like
this:
If you want to use @code{__va_copy} you should always be prepared for the
possibility that this macro will not be available. On architectures where a
simple assignment is invalid, hopefully @code{__va_copy} @emph{will} be available,
so one should always write something like this:
@smallexample
@{
@ -540,7 +534,7 @@ build (va_alist)
@{
@end smallexample
Secondly, you must give @code{va_start} just one argument, like this:
Secondly, you must give @code{va_start} only one argument, like this:
@smallexample
va_list p;
@ -643,7 +637,7 @@ arguments or variables that hold the size of an object.
In the GNU system @code{size_t} is equivalent to either
@w{@code{unsigned int}} or @w{@code{unsigned long int}}. These types
have identical properties on the GNU system, and for most purposes, you
have identical properties on the GNU system and, for most purposes, you
can use them interchangeably. However, they are distinct as data types,
which makes a difference in certain contexts.
@ -938,7 +932,7 @@ follows.
@item
@cindex mantissa (of floating point number)
@cindex significand (of floating point number)
The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a
The @dfn{mantissa} or @dfn{significand} is an unsigned integer which is a
part of each floating point number.
@item
@ -957,12 +951,12 @@ Again, the GNU library provides no facilities for dealing with such
low-level aspects of the representation.
@end itemize
The mantissa of a floating point number actually represents an implicit
fraction whose denominator is the base raised to the power of the
precision. Since the largest representable mantissa is one less than
this denominator, the value of the fraction is always strictly less than
@code{1}. The mathematical value of a floating point number is then the
product of this fraction, the sign, and the base raised to the exponent.
The mantissa of a floating point number represents an implicit fraction
whose denominator is the base raised to the power of the precision. Since
the largest representable mantissa is one less than this denominator, the
value of the fraction is always strictly less than @code{1}. The
mathematical value of a floating point number is then the product of this
fraction, the sign, and the base raised to the exponent.
@cindex normalized floating point number
We say that the floating point number is @dfn{normalized} if the
@ -1054,7 +1048,7 @@ the IEEE single-precision standard.
@comment float.h
@comment ISO
@item FLT_RADIX
This is the value of the base, or radix, of exponent representation.
This is the value of the base, or radix, of the exponent representation.
This is guaranteed to be a constant expression, unlike the other macros
described in this section. The value is 2 on all machines we know of
except the IBM 360 and derivatives.
@ -1208,7 +1202,7 @@ macro's value is the same as the type it describes.
@comment ISO
@item FLT_EPSILON
This is the minimum positive floating point number of type @code{float}
This is the maximum positive floating point number of type @code{float}
such that @code{1.0 + FLT_EPSILON != 1.0} is true. It's supposed to
be no greater than @code{1E-5}.

299
manual/llio.texi
View File

@ -97,8 +97,8 @@ for this function:
@table @code
@item EACCES
The file exists but is not readable/writable as requested by the @var{flags}
argument, the file does not exist and the directory is unwritable so
The file exists but is not readable/writeable as requested by the @var{flags}
argument, the file does not exist and the directory is unwriteable so
it cannot be created.
@item EEXIST
@ -142,19 +142,19 @@ or @code{O_CREAT} is set and the file does not already exist.
@c !!! umask
If on a 32 bits machine the sources are translated with
If on a 32 bit machine the sources are translated with
@code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
descriptor opened in the large file mode which enables the file handling
functions to use files up to @math{2^63} bytes in size and offset from
@math{-2^63} to @math{2^63}. This happens transparently for the user
since all of the lowlevel file handling functions are equally replaced.
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{open} is
called. If the thread gets canceled these resources stay allocated
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to @code{open} should be
protected using cancelation handlers.
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{open} function is the underlying primitive for the @code{fopen}
@ -166,7 +166,7 @@ and @code{freopen} functions, that create streams.
@deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
This function is similar to @code{open}. It returns a file descriptor
which can be used to access the file named by @var{filename}. The only
the difference is that on 32 bits systems the file is opened in the
difference is that on 32 bit systems the file is opened in the
large file mode. I.e., file length and file offsets can exceed 31 bits.
When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
@ -191,7 +191,7 @@ is equivalent to:
open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
@end smallexample
If on a 32 bits machine the sources are translated with
If on a 32 bit machine the sources are translated with
@code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
descriptor opened in the large file mode which enables the file handling
functions to use files up to @math{2^63} in size and offset from
@ -204,7 +204,7 @@ since all of the lowlevel file handling functions are equally replaced.
@deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
This function is similar to @code{creat}. It returns a file descriptor
which can be used to access the file named by @var{filename}. The only
the difference is that on 32 bits systems the file is opened in the
the difference is that on 32 bit systems the file is opened in the
large file mode. I.e., file length and file offsets can exceed 31 bits.
To use this file descriptor one must not use the normal operations but
@ -234,12 +234,12 @@ When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
@end itemize
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{close} is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to @code{close} should be
protected using cancelation handlers.
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this, calls to @code{close} should be
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The normal return value from @code{close} is @math{0}; a value of @math{-1}
@ -270,7 +270,7 @@ on their meaning.
Please note that there is @emph{no} separate @code{close64} function.
This is not necessary since this function does not determine nor depend
on the mode of the file. The kernel which performs the @code{close}
operation knows for which mode the descriptor is used and can handle
operation knows which mode the descriptor is used for and can handle
this situation.
@end deftypefun
@ -302,8 +302,8 @@ but must be a signed type.
@deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
The @code{read} function reads up to @var{size} bytes from the file
with descriptor @var{filedes}, storing the results in the @var{buffer}.
(This is not necessarily a character string and there is no terminating
null character added.)
(This is not necessarily a character string, and no terminating null
character is added.)
@cindex end-of-file, on a file descriptor
The return value is the number of bytes actually read. This might be
@ -365,7 +365,7 @@ a hardware error.
@code{EIO} also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a @code{SIGTTIN} signal isn't working. This might happen if
signal is being blocked or ignored, or because the process group is
the signal is being blocked or ignored, or because the process group is
orphaned. @xref{Job Control}, for more information about job control,
and @ref{Signal Handling}, for information about signals.
@end table
@ -373,14 +373,14 @@ and @ref{Signal Handling}, for information about signals.
Please note that there is no function named @code{read64}. This is not
necessary since this function does not directly modify or handle the
possibly wide file offset. Since the kernel handles this state
internally the @code{read} function can be used for all cases.
internally, the @code{read} function can be used for all cases.
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{read} is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to @code{read} should be
protected using cancelation handlers.
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this, calls to @code{read} should be
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{read} function is the underlying primitive for all of the
@ -391,23 +391,24 @@ functions that read from streams, such as @code{fgetc}.
@comment Unix98
@deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
The @code{pread} function is similar to the @code{read} function. The
first three arguments are identical and also the return values and error
codes correspond.
first three arguments are identical, and the return values and error
codes also correspond.
The difference is the fourth argument and its handling. The data block
is not read from the current position of the file descriptor
@code{filedes}. Instead the data is read from the file starting at
position @var{offset}. The position of the file descriptor itself is
not effected by the operation. The value is the same as before the call.
not affected by the operation. The value is the same as before the call.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{pread} function is in fact @code{pread64} and the type
@code{off_t} has 64 bits which makes it possible to handle files up to
@code{off_t} has 64 bits, which makes it possible to handle files up to
@math{2^63} bytes in length.
The return value of @code{pread} describes the number of bytes read.
In the error case it returns @math{-1} like @code{read} does and the
error codes are also the same. Only there are a few more error codes:
error codes are also the same, with these additions:
@table @code
@item EINVAL
The value given for @var{offset} is negative and therefore illegal.
@ -426,15 +427,15 @@ version 2.
@deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
This function is similar to the @code{pread} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bits machines to address
@code{off_t} which makes it possible on 32 bit machines to address
files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
32 bits machine this function is actually available under the name
@code{pread} and so transparently replaces the 32 bits interface.
32 bit machine this function is actually available under the name
@code{pread} and so transparently replaces the 32 bit interface.
@end deftypefun
@cindex writing to a file descriptor
@ -470,7 +471,7 @@ In the case of an error, @code{write} returns @math{-1}. The following
@item EAGAIN
Normally, @code{write} blocks until the write operation is complete.
But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
Operations}), it returns immediately without writing any data, and
Operations}), it returns immediately without writing any data and
reports this error. An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
@ -498,7 +499,7 @@ The size of the file would become larger than the implementation can support.
@item EINTR
The @code{write} operation was interrupted by a signal while it was
blocked waiting for completion. A signal will not necessary cause
blocked waiting for completion. A signal will not necessarily cause
@code{write} to return @code{EINTR}; it may instead result in a
successful @code{write} which writes fewer bytes than requested.
@xref{Interrupted Primitives}.
@ -531,12 +532,12 @@ necessary since this function does not directly modify or handle the
possibly wide file offset. Since the kernel handles this state
internally the @code{write} function can be used for all cases.
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{write} is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to @code{write} should be
protected using cancelation handlers.
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this, calls to @code{write} should be
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{write} function is the underlying primitive for all of the
@ -547,29 +548,30 @@ functions that write to streams, such as @code{fputc}.
@comment Unix98
@deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
The @code{pwrite} function is similar to the @code{write} function. The
first three arguments are identical and also the return values and error
codes correspond.
first three arguments are identical, and the return values and error codes
also correspond.
The difference is the fourth argument and its handling. The data block
is not written to the current position of the file descriptor
@code{filedes}. Instead the data is written to the file starting at
position @var{offset}. The position of the file descriptor itself is
not effected by the operation. The value is the same as before the call.
not affected by the operation. The value is the same as before the call.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{pwrite} function is in fact @code{pwrite64} and the type
@code{off_t} has 64 bits which makes it possible to handle files up to
@code{off_t} has 64 bits, which makes it possible to handle files up to
@math{2^63} bytes in length.
The return value of @code{pwrite} describes the number of written bytes.
In the error case it returns @math{-1} like @code{write} does and the
error codes are also the same. Only there are a few more error codes:
error codes are also the same, with these additions:
@table @code
@item EINVAL
The value given for @var{offset} is negative and therefore illegal.
@item ESPIPE
The file descriptor @var{filedes} is associate with a pipe or a FIFO and
The file descriptor @var{filedes} is associated with a pipe or a FIFO and
this device does not allow positioning of the file pointer.
@end table
@ -582,15 +584,15 @@ version 2.
@deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
This function is similar to the @code{pwrite} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bits machines to address
@code{off_t} which makes it possible on 32 bit machines to address
files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode.
When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
32 bits machine this function is actually available under the name
@code{pwrite} and so transparently replaces the 32 bits interface.
32 bit machine this function is actually available under the name
@code{pwrite} and so transparently replaces the 32 bit interface.
@end deftypefun
@ -616,8 +618,8 @@ The @code{lseek} function is used to change the file position of the
file with descriptor @var{filedes}.
The @var{whence} argument specifies how the @var{offset} should be
interpreted in the same way as for the @code{fseek} function, and must be
one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
interpreted, in the same way as for the @code{fseek} function, and it must
be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
@code{SEEK_END}.
@table @code
@ -684,12 +686,12 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
@code{off_t} has 64 bits which makes it possible to handle files up to
@math{2^63} bytes in length.
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{lseek} is
called. If the thread gets canceled these resources stay allocated
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to @code{lseek} should be
protected using cancelation handlers.
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{lseek} function is the underlying primitive for the
@ -703,7 +705,7 @@ descriptors.
@deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
This function is similar to the @code{lseek} function. The difference
is that the @var{offset} parameter is of type @code{off64_t} instead of
@code{off_t} which makes it possible on 32 bits machines to address
@code{off_t} which makes it possible on 32 bit machines to address
files larger than @math{2^31} bytes and up to @math{2^63} bytes. The
file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to
@ -711,7 +713,7 @@ errors with a descriptor in small file mode.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
32 bits machine this function is actually available under the name
@code{lseek} and so transparently replaces the 32 bits interface.
@code{lseek} and so transparently replaces the 32 bit interface.
@end deftypefun
You can have multiple descriptors for the same file if you open the file
@ -775,7 +777,7 @@ is transparently replaced by @code{off64_t}.
@comment Unix98
@deftp {Data Type} off64_t
This type is used similar to @code{off_t}. The difference is that even
on 32 bits machines, where the @code{off_t} type would have 32 bits,
on 32 bit machines, where the @code{off_t} type would have 32 bits,
@code{off64_t} has 64 bits and so is able to address files up to
@math{2^63} bytes in length.
@ -820,7 +822,7 @@ The @var{opentype} argument is interpreted in the same way as for the
@code{fopen} function (@pxref{Opening Streams}), except that
the @samp{b} option is not permitted; this is because GNU makes no
distinction between text and binary files. Also, @code{"w"} and
@code{"w+"} do not cause truncation of the file; these have affect only
@code{"w+"} do not cause truncation of the file; these have an effect only
when opening a file, and in this case the file has already been opened.
You must make sure that the @var{opentype} argument matches the actual
mode of the open file descriptor.
@ -1027,7 +1029,7 @@ Modes}.
@cindex scatter-gather
Some applications may need to read or write data to multiple buffers,
which are seperated in memory. Although this can be done easily enough
which are separated in memory. Although this can be done easily enough
with multiple calls to @code{read} and @code{write}, it is inefficent
because there is overhead associated with each kernel call.
@ -1102,8 +1104,8 @@ On modern operating systems, it is possible to @dfn{mmap} (pronounced
``em-map'') a file to a region of memory. When this is done, the file can
be accessed just like an array in the program.
This is more efficent than @code{read} or @code{write}, as only regions
of the file a program actually accesses are loaded. Accesses to
This is more efficent than @code{read} or @code{write}, as only the regions
of the file that a program actually accesses are loaded. Accesses to
not-yet-loaded parts of the mmapped region are handled in the same way as
swapped out pages.
@ -1245,9 +1247,9 @@ The file is on a filesystem that doesn't support mapping.
@code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
@var{length}). @var{length} should be the length of the mapping.
It is safe to un-map multiple mappings in one command, or include unmapped
It is safe to unmap multiple mappings in one command, or include unmapped
space in the range. It is also possible to unmap only part of an existing
mapping, however only entire pages can be removed. If @var{length} is not
mapping. However, only entire pages can be removed. If @var{length} is not
an even number of pages, it will be rounded up.
It returns @math{0} for success and @math{-1} for an error.
@ -1257,7 +1259,7 @@ One error is possible:
@table @code
@item EINVAL
The memory range given was outside the user mmap range, or wasn't page
The memory range given was outside the user mmap range or wasn't page
aligned.
@end table
@ -1314,8 +1316,7 @@ 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
characteristics will be returned, but a with the length @var{new_length}
instead.
characteristics will be returned with the length @var{new_length}.
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
@ -1324,8 +1325,6 @@ one of the desired length in another location.
The address of the resulting mapping is returned, or @math{-1}. Possible
error codes include:
This function is only available on a few systems. Except for performing
optional optimizations one should not rely on this function.
@table @code
@item EFAULT
@ -1340,7 +1339,7 @@ The region has pages locked, and if extended it would exceed the
process's resource limit for locked pages. @xref{Limits on Resources}.
@item ENOMEM
The region is private writable, and insufficent virtual memory is
The region is private writeable, and insufficent virtual memory is
available to extend it. Also, this error will occur if
@code{MREMAP_MAYMOVE} is not given and the extension would collide with
another mapped region.
@ -1348,6 +1347,9 @@ another mapped region.
@end table
@end deftypefun
This function is only available on a few systems. Except for performing
optional optimizations one should not rely on this function.
Not all file descriptors may be mapped. Sockets, pipes, and most devices
only allow sequential access and do not fit into the mapping abstraction.
In addition, some regular files may not be mmapable, and older kernels may
@ -1533,20 +1535,20 @@ input from multiple sockets in @ref{Server Example}.
@section Synchronizing I/O operations
@cindex synchronizing
In most modern operation systems the normal I/O operations are not
In most modern operating systems the normal I/O operations are not
executed synchronously. I.e., even if a @code{write} system call
returns this does not mean the data is actually written to the media,
e.g., the disk.
In situations where synchronization points are necessary the user can
use special functions which ensure that all operations finished before
In situations where synchronization points are necessary,you can use
special functions which ensure that all operations finish before
they return.
@comment unistd.h
@comment X/Open
@deftypefun int sync (void)
A call to this function will not return as long as there is data which
that is not written to the device. All dirty buffers in the kernel will
has not been written to the device. All dirty buffers in the kernel will
be written and so an overall consistent system can be achieved (if no
other process in parallel writes data).
@ -1555,9 +1557,9 @@ A prototype for @code{sync} can be found in @file{unistd.h}.
The return value is zero to indicate no error.
@end deftypefun
More often it is wanted that not all data in the system is committed.
Programs want to ensure that data written to a given file are all
committed and in this situation @code{sync} is overkill.
Programs more often want to ensure that data written to a given file is
committed, rather than all data in the system. For this, @code{sync} is overkill.
@comment unistd.h
@comment POSIX
@ -1569,12 +1571,12 @@ finished.
A prototype for @code{fsync} can be found in @file{unistd.h}.
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{fsync} is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to @code{fsync} should be
protected using cancelation handlers.
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this, calls to @code{fsync} should be
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The return value of the function is zero if no error occured. Otherwise
@ -1599,9 +1601,9 @@ recovering of the file in case of a problem.
@comment unistd.h
@comment POSIX
@deftypefun int fdatasync (int @var{fildes})
When a call to the @code{fdatasync} function returns it is made sure
When a call to the @code{fdatasync} function returns, it is ensured
that all of the file data is written to the device. For all pending I/O
operations the parts guaranteeing data integrity finished.
operations, the parts guaranteeing data integrity finished.
Not all systems implement the @code{fdatasync} operation. On systems
missing this functionality @code{fdatasync} is emulated by a call to
@ -1627,10 +1629,10 @@ No synchronization is possible since the system does not implement this.
@section Perform I/O Operations in Parallel
The POSIX.1b standard defines a new set of I/O operations which can
reduce the time an application spends waiting at I/O significantly. The
significantly reduce the time an application spends waiting at I/O. The
new functions allow a program to initiate one or more I/O operations and
then immediately resume the normal work while the I/O operations are
executed in parallel. The functionality is available if the
then immediately resume normal work while the I/O operations are
executed in parallel. This functionality is available if the
@file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
These functions are part of the library with realtime functions named
@ -1641,7 +1643,7 @@ userlevel. In the latter case it might be necessary to link applications
with the thread library @file{libpthread} in addition to @file{librt}.
All AIO operations operate on files which were opened previously. There
might be arbitrary many operations for one file running. The
might be arbitrarily many operations running for one file. The
asynchronous I/O operations are controlled using a data structure named
@code{struct aiocb} (@dfn{AIO control block}). It is defined in
@file{aio.h} as follows.
@ -1651,14 +1653,14 @@ asynchronous I/O operations are controlled using a data structure named
@deftp {Data Type} {struct aiocb}
The POSIX.1b standard mandates that the @code{struct aiocb} structure
contains at least the members described in the following table. There
might be more elements which are used by the implementation but
might be more elements which are used by the implementation, but
depending on these elements is not portable and is highly deprecated.
@table @code
@item int aio_fildes
This element specifies the file descriptor which is used for the
operation. It must be a legal descriptor since otherwise the operation
fails for obvious reasons.
fails.
The device on which the file is opened must allow the seek operation.
I.e., it is not possible to use any of the AIO operations on devices
@ -1696,9 +1698,9 @@ is created which starts executing the function pointed to by
@item int aio_lio_opcode
This element is only used by the @code{lio_listio} and
@code{lio_listio64} functions. Since these functions allow to start an
arbitrary number of operations at once and since each operation can be
input or output (or nothing) the information must be stored in the
@code{lio_listio64} functions. Since these functions allow an
arbitrary number of operations to start at once, and each operation can be
input or output (or nothing), the information must be stored in the
control block. The possible values are:
@vtable @code
@ -1720,13 +1722,13 @@ values must not be handled although the whole array is presented to the
@end table
When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
32 bits machine this type is in fact @code{struct aiocb64} since the LFS
32 bit machine this type is in fact @code{struct aiocb64} since the LFS
interface transparently replaces the @code{struct aiocb} definition.
@end deftp
For use with the AIO functions defined in the LFS there is a similar type
defined which replaces the types of the appropriate members with larger
types but otherwise is equivalent to @code{struct aiocb}. Especially
types but otherwise is equivalent to @code{struct aiocb}. Particularly,
all member names are the same.
@comment aio.h
@ -1743,7 +1745,7 @@ I.e., it is not possible to use any of the AIO operations on devices
like terminals where an @code{lseek} call would lead to an error.
@item off64_t aio_offset
This element specified at which offset in the file the operation (input
This element specifies at which offset in the file the operation (input
or output) is performed. Since the operation are carried in arbitrary
order and more than one operation for one file descriptor can be
started, one cannot expect a current read/write position of the file
@ -1758,7 +1760,7 @@ This element specifies the length of the buffer pointed to by @code{aio_buf}.
@item int aio_reqprio
If for the platform @code{_POSIX_PRIORITIZED_IO} and
@code{_POSIX_PRIORITY_SCHEDULING} is defined the AIO requests are
@code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
processed based on the current scheduling priority. The
@code{aio_reqprio} element can then be used to lower the priority of the
AIO operation.
@ -1766,23 +1768,23 @@ AIO operation.
@item struct sigevent aio_sigevent
This element specifies how the calling process is notified once the
operation terminates. If the @code{sigev_notify} element is
@code{SIGEV_NONE} no notification is send. If it is @code{SIGEV_SIGNAL}
the signal determined by @code{sigev_signo} is send. Otherwise
@code{SIGEV_NONE} no notification is sent. If it is @code{SIGEV_SIGNAL}
the signal determined by @code{sigev_signo} is sent. Otherwise
@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
which starts executing the function pointeed to by
which starts executing the function pointed to by
@code{sigev_notify_function}.
@item int aio_lio_opcode
This element is only used by the @code{lio_listio} and
@code{[lio_listio64} functions. Since these functions allow to start an
arbitrary number of operations at once and since each operation can be
input or output (or nothing) the information must be stored in the
@code{[lio_listio64} functions. Since these functions allow an
arbitrary number of operations to start at once, and since each operation can be
input or output (or nothing), the information must be stored in the
control block. See the description of @code{struct aiocb} for a description
of the possible values.
@end table
When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
32 bits machine this type is available under the name @code{struct
32 bit machine this type is available under the name @code{struct
aiocb64} since the LFS replaces transparently the old interface.
@end deftp
@ -1790,7 +1792,7 @@ aiocb64} since the LFS replaces transparently the old interface.
* Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
* Status of AIO Operations:: Getting the Status of AIO Operations.
* Synchronizing AIO Operations:: Getting into a consistent state.
* Cancel AIO Operations:: Cancelation of AIO Operations.
* Cancel AIO Operations:: Cancellation of AIO Operations.
* Configuration of AIO:: How to optimize the AIO implementation.
@end menu
@ -1800,8 +1802,8 @@ aiocb64} since the LFS replaces transparently the old interface.
@comment aio.h
@comment POSIX.1b
@deftypefun int aio_read (struct aiocb *@var{aiocbp})
This function initiates an asynchronous read operation. The function
call immediately returns after the operation was enqueued or when an
This function initiates an asynchronous read operation. It
immediately returns after the operation was enqueued or when an
error was encountered.
The first @code{aiocbp->aio_nbytes} bytes of the file for which
@ -1816,10 +1818,10 @@ the request is actually enqueued.
The calling process is notified about the termination of the read
request according to the @code{aiocbp->aio_sigevent} value.
When @code{aio_read} returns the return value is zero if no error
When @code{aio_read} returns, the return value is zero if no error
occurred that can be found before the process is enqueued. If such an
early error is found the function returns @math{-1} and sets
@code{errno} to one of the following values.
early error is found, the function returns @math{-1} and sets
@code{errno} to one of the following values:
@table @code
@item EAGAIN
@ -1829,7 +1831,7 @@ limitations.
The @code{aio_read} function is not implemented.
@item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid. This condition
needs not be recognized before enqueueing the request and so this error
need not be recognized before enqueueing the request and so this error
might also be signaled asynchronously.
@item EINVAL
The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
@ -1837,22 +1839,21 @@ invalid. This condition need not be recognized before enqueueing the
request and so this error might also be signaled asynchrously.
@end table
In the case @code{aio_read} returns zero the current status of the
request can be queried using @code{aio_error} and @code{aio_return}
functions. As long as the value returned by @code{aio_error} is
@code{EINPROGRESS} the operation has not yet completed. If
@code{aio_error} returns zero the operation successfully terminated,
otherwise the value is to be interpreted as an error code. If the
function terminated the result of the operation can be get using a call
to @code{aio_return}. The returned value is the same as an equivalent
call to @code{read} would have returned. Possible error codes returned
by @code{aio_error} are:
If @code{aio_read} returns zero, the current status of the request
can be queried using @code{aio_error} and @code{aio_return} functions.
As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
the operation has not yet completed. If @code{aio_error} returns zero,
the operation successfully terminated, otherwise the value is to be
interpreted as an error code. If the function terminated, the result of
the operation can be obtained using a call to @code{aio_return}. The
returned value is the same as an equivalent call to @code{read} would
have returned. Possible error codes returned by @code{aio_error} are:
@table @code
@item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid.
@item ECANCELED
The operation was canceled before the operation was finished
The operation was cancelled before the operation was finished
(@pxref{Cancel AIO Operations})
@item EINVAL
The @code{aiocbp->aio_offset} value is invalid.
@ -1867,7 +1868,7 @@ replaces the normal implementation.
@comment Unix98
@deftypefun int aio_read64 (struct aiocb *@var{aiocbp})
This function is similar to the @code{aio_read} function. The only
difference is that on @w{32 bits} machines the file descriptor should
difference is that on @w{32 bit} machines the file descriptor should
be opened in the large file mode. Internally @code{aio_read64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading,
@ -1875,7 +1876,7 @@ as opposed to @code{lseek} functionality used in @code{aio_read}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_read} and so transparently
replaces the interface for small files on 32 bits machines.
replaces the interface for small files on 32 bit machines.
@end deftypefun
To write data asynchronously to a file there exists an equivalent pair
@ -1936,7 +1937,7 @@ by @code{aio_error} are:
@item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid.
@item ECANCELED
The operation was canceled before the operation was finished
The operation was cancelled before the operation was finished
(@pxref{Cancel AIO Operations})
@item EINVAL
The @code{aiocbp->aio_offset} value is invalid.
@ -1951,7 +1952,7 @@ replaces the normal implementation.
@comment Unix98
@deftypefun int aio_write64 (struct aiocb *@var{aiocbp})
This function is similar to the @code{aio_write} function. The only
difference is that on @w{32 bits} machines the file descriptor should
difference is that on @w{32 bit} machines the file descriptor should
be opened in the large file mode. Internally @code{aio_write64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the writing,
@ -1959,7 +1960,7 @@ as opposed to @code{lseek} functionality used in @code{aio_write}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_write} and so transparently
replaces the interface for small files on 32 bits machines.
replaces the interface for small files on 32 bit machines.
@end deftypefun
Beside these functions with the more or less traditional interface
@ -2055,7 +2056,7 @@ transparently replaces the normal implementation.
@comment Unix98
@deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig})
This function is similar to the @code{aio_listio} function. The only
difference is that only @w{32 bits} machines the file descriptor should
difference is that only @w{32 bit} machines the file descriptor should
be opened in the large file mode. Internally @code{lio_listio64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading or
@ -2064,7 +2065,7 @@ writing, as opposed to @code{lseek} functionality used in
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{lio_listio} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@ -2072,12 +2073,12 @@ machines.
@subsection Getting the Status of AIO Operations
As already described in the documentation of the functions in the last
section it must be possible to get information about the status of a I/O
request. When the operation is performed really asynchronous (as with
section, it must be possible to get information about the status of an I/O
request. When the operation is performed truly asynchronously (as with
@code{aio_read} and @code{aio_write} and with @code{aio_listio} when the
mode is @code{LIO_NOWAIT}) one sometimes needs to know whether a
specific request already terminated and if yes, what the result was..
The following two function allow to get this kind of information.
specific request already terminated and if yes, what the result was.
The following two functions allow you to get this kind of information.
@comment aio.h
@comment POSIX.1b
@ -2109,7 +2110,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_error} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@ -2145,7 +2146,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_return} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@ -2156,7 +2157,7 @@ When dealing with asynchronous operations it is sometimes necessary to
get into a consistent state. This would mean for AIO that one wants to
know whether a certain request or a group of request were processed.
This could be done by waiting for the notification sent by the system
after the operation terminated but this sometimes would mean wasting
after the operation terminated, but this sometimes would mean wasting
resources (mainly computation time). Instead POSIX.1b defines two
functions which will help with most kinds of consistency.
@ -2171,12 +2172,12 @@ defined.
Calling this function forces all I/O operations operating queued at the
time of the function call operating on the file descriptor
@code{aiocbp->aio_fildes} into the synchronized I/O completion state
(@pxref{Synchronizing I/O}). The @code{aio_fsync} function return
(@pxref{Synchronizing I/O}). The @code{aio_fsync} function returns
immediately but the notification through the method described in
@code{aiocbp->aio_sigevent} will happen only after all requests for this
file descriptor terminated and the file is synchronized. This also
file descriptor have terminated and the file is synchronized. This also
means that requests for this very same file descriptor which are queued
after the synchronization request are not effected.
after the synchronization request are not affected.
If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
to @code{fdatasync}. Otherwise @var{op} should be @code{O_SYNC} and
@ -2222,7 +2223,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_fsync} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@ -2286,12 +2287,12 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_suspend} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@node Cancel AIO Operations
@subsection Cancelation of AIO Operations
@subsection Cancellation of AIO Operations
When one or more requests are asynchronously processed it might be
useful in some situations to cancel a selected operation, e.g., if it
@ -2300,7 +2301,7 @@ have to be overwritten soon. As an example assume an application, which
writes data in files in a situation where new incoming data would have
to be written in a file which will be updated by an enqueued request.
The POSIX AIO implementation provides such a function but this function
is not capable to force the cancelation of the request. It is up to the
is not capable to force the cancellation of the request. It is up to the
implementation to decide whether it is possible to cancel the operation
or not. Therefore using this function is merely a hint.
@ -2312,26 +2313,26 @@ outstanding requests. If the @var{aiocbp} parameter is @code{NULL} the
function tries to cancel all outstanding requests which would process
the file descriptor @var{fildes} (i.e.,, whose @code{aio_fildes} member
is @var{fildes}). If @var{aiocbp} is not @code{NULL} the very specific
request pointed to by @var{aiocbp} is tried to be canceled.
request pointed to by @var{aiocbp} is tried to be cancelled.
For requests which were successfully canceled the normal notification
For requests which were successfully cancelled the normal notification
about the termination of the request should take place. I.e., depending
on the @code{struct sigevent} object which controls this, nothing
happens, a signal is sent or a thread is started. If the request cannot
be canceled it terminates the usual way after performing te operation.
be cancelled it terminates the usual way after performing te operation.
After a request is successfully canceled a call to @code{aio_error} with
After a request is successfully cancelled a call to @code{aio_error} with
a reference to this request as the parameter will return
@code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
If the request wasn't canceled and is still running the error status is
If the request wasn't cancelled and is still running the error status is
still @code{EINPROGRESS}.
The return value of the function is @code{AIO_CANCELED} if there were
requests which haven't terminated and which successfully were canceled.
If there is one or more request left which couldn't be canceled the
requests which haven't terminated and which successfully were cancelled.
If there is one or more request left which couldn't be cancelled the
return value is @code{AIO_NOTCANCELED}. In this case @code{aio_error}
must be used to find out which of the perhaps multiple requests (in
@var{aiocbp} is @code{NULL}) wasn't successfully canceled. If all
@var{aiocbp} is @code{NULL}) wasn't successfully cancelled. If all
requests already terminated at the time @code{aio_cancel} is called the
return value is @code{AIO_ALLDONE}.
@ -2360,7 +2361,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_cancel} and so
transparently replaces the interface for small files on 32 bits
transparently replaces the interface for small files on 32 bit
machines.
@end deftypefun
@ -2486,12 +2487,12 @@ Set process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.
@end table
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{fcntl} is
called. If the thread gets canceled these resources stay allocated
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to @code{fcntl} should be
protected using cancelation handlers.
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
@end deftypefun

202
manual/math.texi
View File

@ -49,7 +49,7 @@ Which of the three versions of a function should be used depends on the
situation. For most calculations, the @code{float} functions are the
fastest. On the other hand, the @code{long double} functions have the
highest precision. @code{double} is somewhere in between. It is
usually wise to pick the narrowest type that can accomodate your data.
usually wise to pick the narrowest type that can accommodate your data.
Not all machines have a distinct @code{long double} type; it may be the
same as @code{double}.
@ -87,7 +87,7 @@ The natural logarithm of @code{2}.
@item M_LN10
The natural logarithm of @code{10}.
@item M_PI
Pi, the ratio of a circle's circumrefence to its diameter.
Pi, the ratio of a circle's circumference to its diameter.
@item M_PI_2
Pi divided by two.
@item M_PI_4
@ -105,7 +105,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{_BSD_SOURCE} or
@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}.
@ -294,7 +294,7 @@ pole.
@cindex inverse trigonometric functions
These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
which are the inverses of the sine, cosine and tangent functions
respectively.
@comment math.h
@ -544,7 +544,7 @@ These functions extract the exponent of @var{x} and return it as a
floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
to @code{floor (log2 (x))}, except it's probably faster.
If @var{x} is denormalized, @code{logb} returns the exponent @var{x}
If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
would have if it were normalized. If @var{x} is infinity (positive or
negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
@code{logb} returns @math{@infinity{}}. It does not signal.
@ -685,7 +685,7 @@ much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
@deftypefunx {long double} expm1l (long double @var{x})
These functions return a value equivalent to @code{exp (@var{x}) - 1}.
They are computed in a way that is accurate even if @var{x} is
near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
to subtraction of two numbers that are nearly equal.
@end deftypefun
@ -720,7 +720,7 @@ logarithm functions.
@deftypefunx {complex long double} cexpl (complex long double @var{z})
These functions return @code{e} (the base of natural
logarithms) raised to the power of @var{z}.
Mathematically this corresponds to the value
Mathematically, this corresponds to the value
@ifinfo
@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
@ -740,7 +740,7 @@ $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
@comment ISO
@deftypefunx {complex long double} clogl (complex long double @var{z})
These functions return the natural logarithm of @var{z}.
Mathematically this corresponds to the value
Mathematically, this corresponds to the value
@ifinfo
@math{log (z) = log (cabs (z)) + I * carg (z)}
@ -766,7 +766,7 @@ or is very close to 0. It is well-defined for all other values of
@comment GNU
@deftypefunx {complex long double} clog10l (complex long double @var{z})
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
@ifinfo
@math{log (z) = log10 (cabs (z)) + I * carg (z)}
@ -992,7 +992,7 @@ the real-valued functions, there are no restrictions on the value of
@cindex Bessel functions
@cindex gamma function
These are some more exotic mathematical functions, which are sometimes
These are some more exotic mathematical functions which are sometimes
useful. Currently they only have real-valued versions.
@comment math.h
@ -1052,7 +1052,7 @@ gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
@vindex signgam
The sign of the gamma function is stored in the global variable
@var{signgam}, which is declared in @file{math.h}. It is @code{1} if
the intermediate result was positive or zero, and, @code{-1} if it was
the intermediate result was positive or zero, or @code{-1} if it was
negative.
To compute the real gamma function you can use the @code{tgamma}
@ -1062,7 +1062,7 @@ lgam = lgamma(x);
gam = signgam*exp(lgam);
@end smallexample
The gamma function has singularities at the nonpositive integers.
The gamma function has singularities at the non-positive integers.
@code{lgamma} will raise the zero divide exception if evaluated at a
singularity.
@end deftypefun
@ -1078,7 +1078,7 @@ singularity.
@deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
@code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
the intermediate result in the variable pointed to by @var{signp}
instead of in the @var{signgam} global.
instead of in the @var{signgam} global. This means it is reentrant.
@end deftypefun
@comment math.h
@ -1092,7 +1092,7 @@ instead of in the @var{signgam} global.
@deftypefunx {long double} gammal (long double @var{x})
These functions exist for compatibility reasons. They are equivalent to
@code{lgamma} etc. It is better to use @code{lgamma} since for one the
name reflects better the actual computation and @code{lgamma} is also
name reflects better the actual computation, moreover @code{lgamma} is
standardized in @w{ISO C 9x} while @code{gamma} is not.
@end deftypefun
@ -1225,7 +1225,7 @@ pseudo-random series each time your program runs, you must specify a
different seed each time. For ordinary purposes, basing the seed on the
current time works well.
You can get repeatable sequences of numbers on a particular machine type
You can obtain repeatable sequences of numbers on a particular machine type
by specifying the same initial seed value for the random number
generator. There is no standard meaning for a particular seed value;
the same seed, used in different C libraries or on different CPU types,
@ -1322,10 +1322,10 @@ The prototypes for these functions are in @file{stdlib.h}.
This function returns the next pseudo-random number in the sequence.
The value returned ranges from @code{0} to @code{RAND_MAX}.
@strong{Note:} Historically this function returned a @code{long
int} value. On 64bit systems @code{long int} would have been larger
than programs expected, so @code{random} is now defined to return
exactly 32 bits.
@strong{Note:} Historically this function returned a @code{long int}
value. On 64-bit systems @code{long int} would have been larger than
programs expected, so @code{random} is now defined to return exactly 32
bits.
@end deftypefun
@comment stdlib.h
@ -1374,10 +1374,10 @@ generator functions. They use a state of 48 bits of data. The user can
choose among a collection of functions which return the random bits
in different forms.
Generally there are two kinds of functions: those which use a state of
Generally there are two kinds of function. The first uses a state of
the random number generator which is shared among several functions and
by all threads of the process. The second group of functions require
the user to handle the state.
by all threads of the process. The second requires the user to handle
the state.
All functions have in common that they use the same congruential
formula with the same constants. The formula is
@ -1389,7 +1389,7 @@ Y = (a * X + c) mod m
@noindent
where @var{X} is the state of the generator at the beginning and
@var{Y} the state at the end. @code{a} and @code{c} are constants
determining the way the generator work. By default they are
determining the way the generator works. By default they are
@smallexample
a = 0x5DEECE66D = 25214903917
@ -1398,7 +1398,7 @@ c = 0xb = 11
@noindent
but they can also be changed by the user. @code{m} is of course 2^48
since the state consists of a 48 bit array.
since the state consists of a 48-bit array.
@comment stdlib.h
@ -1408,7 +1408,7 @@ This function returns a @code{double} value in the range of @code{0.0}
to @code{1.0} (exclusive). The random bits are determined by the global
state of the random number generator in the C library.
Since the @code{double} type according to @w{IEEE 754} has a 52 bit
Since the @code{double} type according to @w{IEEE 754} has a 52-bit
mantissa this means 4 bits are not initialized by the random number
generator. These are (of course) chosen to be the least significant
bits and they are initialized to @code{0}.
@ -1418,20 +1418,20 @@ bits and they are initialized to @code{0}.
@comment SVID
@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
This function returns a @code{double} value in the range of @code{0.0}
to @code{1.0} (exclusive), similar to @code{drand48}. The argument is
to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is
an array describing the state of the random number generator.
This function can be called subsequently since it updates the array to
guarantee random numbers. The array should have been initialized before
using to get reproducible results.
initial use to obtain reproducible results.
@end deftypefun
@comment stdlib.h
@comment SVID
@deftypefun {long int} lrand48 (void)
The @code{lrand48} functions return an integer value in the range of
The @code{lrand48} function returns an integer value in the range of
@code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
int} type can take more than 32 bits no higher numbers are returned.
int} type can take more than 32 bits, no higher numbers are returned.
The random bits are determined by the global state of the random number
generator in the C library.
@end deftypefun
@ -1444,10 +1444,10 @@ returns a number in the range of @code{0} to @code{2^31} (exclusive) but
the state of the random number generator used to produce the random bits
is determined by the array provided as the parameter to the function.
The numbers in the array are afterwards updated so that subsequent calls
to this function yield to different results (as it is expected by a
random number generator). The array should have been initialized before
the first call to get reproducible results.
The numbers in the array are updated afterwards so that subsequent calls
to this function yield different results (as is expected of a random
number generator). The array should have been initialized before the
first call to obtain reproducible results.
@end deftypefun
@comment stdlib.h
@ -1468,33 +1468,33 @@ requirements are necessary.
@end deftypefun
The internal state of the random number generator can be initialized in
several ways. The functions differ in the completeness of the
several ways. The methods differ in the completeness of the
information provided.
@comment stdlib.h
@comment SVID
@deftypefun void srand48 (long int @var{seedval}))
@deftypefun void srand48 (long int @var{seedval})
The @code{srand48} function sets the most significant 32 bits of the
state internal state of the random number generator to the least
internal state of the random number generator to the least
significant 32 bits of the @var{seedval} parameter. The lower 16 bits
are initialized to the value @code{0x330E}. Even if the @code{long
int} type contains more the 32 bits only the lower 32 bits are used.
int} type contains more than 32 bits only the lower 32 bits are used.
Due to this limitation the initialization of the state using this
function of not very useful. But it makes it easy to use a construct
Owing to this limitation, initialization of the state of this
function is not very useful. But it makes it easy to use a construct
like @code{srand48 (time (0))}.
A side-effect of this function is that the values @code{a} and @code{c}
from the internal state, which are used in the congruential formula,
are reset to the default values given above. This is of importance once
the user called the @code{lcong48} function (see below).
the user has called the @code{lcong48} function (see below).
@end deftypefun
@comment stdlib.h
@comment SVID
@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
The @code{seed48} function initializes all 48 bits of the state of the
internal random number generator from the content of the parameter
internal random number generator from the contents of the parameter
@var{seed16v}. Here the lower 16 bits of the first element of
@var{see16v} initialize the least significant 16 bits of the internal
state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
@ -1507,15 +1507,15 @@ of the state.
The value returned by @code{seed48} is a pointer to an array containing
the values of the internal state before the change. This might be
useful to restart the random number generator at a certain state.
Otherwise, the value can simply be ignored.
Otherwise the value can simply be ignored.
As for @code{srand48}, the values @code{a} and @code{c} from the
congruential formula are reset to the default values.
@end deftypefun
There is one more function to initialize the random number generator
which allows to specify even more information by allowing to change the
parameters in the congruential formula.
which enables you to specify even more information by allowing you to
change the parameters in the congruential formula.
@comment stdlib.h
@comment SVID
@ -1527,9 +1527,9 @@ congruential formula.
From the seven elements in the array @var{param} the least significant
16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
determine the initial state, the least 16 bits of
determine the initial state, the least significant 16 bits of
@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
@code{c}.
@end deftypefun
@ -1544,22 +1544,21 @@ Please note that it is no problem if several threads use the global
state if all threads use the functions which take a pointer to an array
containing the state. The random numbers are computed following the
same loop but if the state in the array is different all threads will
get an individual random number generator.
obtain an individual random number generator.
The user supplied buffer must be of type @code{struct drand48_data}.
This type should be regarded as opaque and no member should be used
directly.
The user-supplied buffer must be of type @code{struct drand48_data}.
This type should be regarded as opaque and not manipulated directly.
@comment stdlib.h
@comment GNU
@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
This function is equivalent to the @code{drand48} function with the
difference it does not modify the global random number generator
parameters but instead the parameters is the buffer supplied by the
buffer through the pointer @var{buffer}. The random number is return in
the variable pointed to by @var{result}.
difference that it does not modify the global random number generator
parameters but instead the parameters in the buffer supplied through the
pointer @var{buffer}. The random number is returned in the variable
pointed to by @var{result}.
The return value of the function indicate whether the call succeeded.
The return value of the function indicates whether the call succeeded.
If the value is less than @code{0} an error occurred and @var{errno} is
set to indicate the problem.
@ -1570,14 +1569,14 @@ programs.
@comment stdlib.h
@comment GNU
@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
The @code{erand48_r} function works like the @code{erand48} and it takes
an argument @var{buffer} which describes the random number generator.
The state of the random number generator is taken from the @code{xsubi}
array, the parameters for the congruential formula from the global
random number generator data. The random number is return in the
variable pointed to by @var{result}.
The @code{erand48_r} function works like @code{erand48}, but in addition
it takes an argument @var{buffer} which describes the random number
generator. The state of the random number generator is taken from the
@code{xsubi} array, the parameters for the congruential formula from the
global random number generator data. The random number is returned in
the variable pointed to by @var{result}.
The return value is non-negative is the call succeeded.
The return value is non-negative if the call succeeded.
This function is a GNU extension and should not be used in portable
programs.
@ -1586,9 +1585,9 @@ programs.
@comment stdlib.h
@comment GNU
@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
This function is similar to @code{lrand48} and it takes a pointer to a
buffer describing the state of the random number generator as a
parameter just like @code{drand48}.
This function is similar to @code{lrand48}, but in addition it takes a
pointer to a buffer describing the state of the random number generator
just like @code{drand48}.
If the return value of the function is non-negative the variable pointed
to by @var{result} contains the result. Otherwise an error occurred.
@ -1601,7 +1600,7 @@ programs.
@comment GNU
@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
The @code{nrand48_r} function works like @code{nrand48} in that it
produces a random number in range @code{0} to @code{2^31}. But instead
produces a random number in the range @code{0} to @code{2^31}. But instead
of using the global parameters for the congruential formula it uses the
information from the buffer pointed to by @var{buffer}. The state is
described by the values in @var{xsubi}.
@ -1616,8 +1615,8 @@ programs.
@comment stdlib.h
@comment GNU
@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
This function is similar to @code{mrand48} but as the other reentrant
function it uses the random number generator described by the value in
This function is similar to @code{mrand48} but like the other reentrant
functions it uses the random number generator described by the value in
the buffer pointed to by @var{buffer}.
If the return value is non-negative the variable pointed to by
@ -1630,7 +1629,7 @@ programs.
@comment stdlib.h
@comment GNU
@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
The @code{jrand48_r} function is similar to @code{jrand48}. But as the
The @code{jrand48_r} function is similar to @code{jrand48}. Like the
other reentrant functions of this function family it uses the
congruential formula parameters from the buffer pointed to by
@var{buffer}.
@ -1642,9 +1641,9 @@ This function is a GNU extension and should not be used in portable
programs.
@end deftypefun
Before any of the above functions should be used the buffer of type
@code{struct drand48_data} should initialized. The easiest way is to
fill the whole buffer with null bytes, e.g., using
Before any of the above functions are used the buffer of type
@code{struct drand48_data} should be initialized. The easiest way to do
this is to fill the whole buffer with null bytes, e.g. by
@smallexample
memset (buffer, '\0', sizeof (struct drand48_data));
@ -1655,9 +1654,9 @@ Using any of the reentrant functions of this family now will
automatically initialize the random number generator to the default
values for the state and the parameters of the congruential formula.
The other possibility is too use any of the functions which explicitely
The other possibility is to use any of the functions which explicitly
initialize the buffer. Though it might be obvious how to initialize the
buffer from the data given as parameter from the function it is highly
buffer from looking at the parameter to the function, it is highly
recommended to use these functions since the result might not always be
what you expect.
@ -1665,10 +1664,10 @@ what you expect.
@comment GNU
@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
The description of the random number generator represented by the
information in @var{buffer} is initialized similar to what the function
information in @var{buffer} is initialized similarly to what the function
@code{srand48} does. The state is initialized from the parameter
@var{seedval} and the parameters for the congruential formula are
initialized to the default values.
initialized to their default values.
If the return value is non-negative the function call succeeded.
@ -1684,8 +1683,8 @@ initializes all 48 bits of the state from the parameter @var{seed16v}.
If the return value is non-negative the function call succeeded. It
does not return a pointer to the previous state of the random number
generator like the @code{seed48} function does. if the user wants to
preserve the state for a later rerun s/he can copy the whole buffer
generator like the @code{seed48} function does. If the user wants to
preserve the state for a later re-run s/he can copy the whole buffer
pointed to by @var{buffer}.
This function is a GNU extension and should not be used in portable
@ -1696,11 +1695,11 @@ programs.
@comment GNU
@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
This function initializes all aspects of the random number generator
described in @var{buffer} by the data in @var{param}. Here it is
especially true the function does more than just copying the contents of
@var{param} of @var{buffer}. Some more actions are required and
therefore it is important to use this function and not initialized the
random number generator directly.
described in @var{buffer} with the data in @var{param}. Here it is
especially true that the function does more than just copying the
contents of @var{param} and @var{buffer}. More work is required and
therefore it is important to use this function rather than initializing
the random number generator directly.
If the return value is non-negative the function call succeeded.
@ -1712,23 +1711,22 @@ programs.
@section Is Fast Code or Small Code preferred?
@cindex Optimization
If an application uses many floating point function it is often the case
that the costs for the function calls itselfs are not neglectable.
Modern processor implementation often can execute the operation itself
very fast but the call means a disturbance of the control flow.
If an application uses many floating point functions it is often the case
that the cost of the function calls themselves is not negligible.
Modern processors can often execute the operations themselves
very fast, but the function call disrupts the instruction pipeline.
For this reason the GNU C Library provides optimizations for many of the
frequently used math functions. When the GNU CC is used and the user
activates the optimizer several new inline functions and macros get
frequently-used math functions. When GNU CC is used and the user
activates the optimizer, several new inline functions and macros are
defined. These new functions and macros have the same names as the
library function and so get used instead of the later. In case of
library functions and so are used instead of the latter. In the case of
inline functions the compiler will decide whether it is reasonable to
use the inline function and this decision is usually correct.
use them, and this decision is usually correct.
For the generated code this means that no calls to the library functions
are necessary. This increases the speed significantly. But the
drawback is that the code size increases and this increase is not always
neglectable.
This means that no calls to the library functions may be necessary, and
can increase the speed of generated code significantly. The drawback is
that code size will increase, and the increase is not always negligible.
The speed increase has one drawback: the inline functions might not set
@code{errno} and might not have the same precission as the library
@ -1736,12 +1734,12 @@ functions.
In cases where the inline functions and macros are not wanted the symbol
@code{__NO_MATH_INLINES} should be defined before any system header is
included. This will make sure only library functions are used. Of
course it can be determined for each single file in the project whether
giving this option is preferred or not.
included. This will ensure that only library functions are used. Of
course, it can be determined for each file in the project whether
giving this option is preferable or not.
Not all hardware implements the entire @w{IEEE 754} standard, or if it
does, there may be a substantial performance penalty for using some of
its features. For example, enabling traps on some processors forces
the FPU to run unpipelined, which more than doubles calculation time.
Not all hardware implements the entire @w{IEEE 754} standard, and even
if it does there may be a substantial performance penalty for using some
of its features. For example, enabling traps on some processors forces
the FPU to run un-pipelined, which can more than double calculation time.
@c ***Add explanation of -lieee, -mieee.

28
manual/nss.texi
View File

@ -267,7 +267,7 @@ missing.
For the @code{hosts} and @code{networks} databases the default value is
@code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for
the DNS service not to be available but if it is available the answer it
returns is ultimative.
returns is definitive.
The @code{passwd}, @code{group}, and @code{shadow} databases are
traditionally handled in a special way. The appropriate files in the
@ -297,7 +297,7 @@ But one should avoid slow services like this if possible.
@node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
@section NSS Module Internals
Now it is time to described how the modules look like. The functions
Now it is time to describe what the modules look like. The functions
contained in a module are identified by their names. I.e., there is no
jump table or the like. How this is done is of no interest here; those
interested in this topic should read about Dynamic Linking.
@ -322,8 +322,8 @@ The name of each function consist of various parts:
@end quotation
@var{service} of course corresponds to the name of the module this
function is found in.@footnote{Now you might ask why to duplicate this
information. The answer is that we want to keep the possibility to link
function is found in.@footnote{Now you might ask why this information is
duplicated. The answer is that we want to make it possible to link
directly with these shared objects.} The @var{function} part is derived
from the interface function in the C library itself. If the user calls
the function @code{gethostbyname} and the service used is @code{files}
@ -364,14 +364,12 @@ Sun's NSS modules are usable as modules which get indirectly loaded
only.
The NSS modules in the GNU C Library are prepared to be used as normal
libraries itself.
@comment Fix me if necessary.
This is @emph{not} true in the moment, though. But the different
organization of the name space in the modules does not make it
libraries themselves. This is @emph{not} true at the moment, though.
However, the organization of the name space in the modules does not make it
impossible like it is for Solaris. Now you can see why the modules are
still libraries.@footnote{There is a second explanation: we were too
lazy to change the Makefiles to allow the generation of shared objects
not starting with @file{lib} but do not tell this anybody.}
not starting with @file{lib} but don't tell this to anybody.}
@node NSS Modules Interface, , NSS Module Names, NSS Module Internals
@ -441,7 +439,7 @@ more.
@multitable @columnfractions .3 .2 .50
@item
@code{NSS_STATUS_TRYAGAIN} @tab
@code{EAGAIN} @tab One functions used ran temporarily out of
@code{EAGAIN} @tab One of the functions used ran temporarily out of
resources or a service is currently not available.
@item
@tab
@ -481,7 +479,7 @@ signature of the module function:
@item
the return value is @code{int};
@item
the name is as explain in @pxref{NSS Module Names};
the name is as explained in @pxref{NSS Module Names};
@item
the first arguments are identical to the arguments of the non-reentrant
function;
@ -561,11 +559,11 @@ more about this command line.
To use the new module the library must be able to find it. This can be
achieved by using options for the dynamic linker so that it will search
directory where the binary is placed. For an ELF system this could be
the directory where the binary is placed. For an ELF system this could be
done by adding the wanted directory to the value of
@code{LD_LIBRARY_PATH}.
But this is not always possible since some program (those which run
But this is not always possible since some programs (those which run
under IDs which do not belong to the user) ignore this variable.
Therefore the stable version of the module should be placed into a
directory which is searched by the dynamic linker. Normally this should
@ -579,7 +577,7 @@ cause any harm. System administrators should be careful.
@subsection Internals of the NSS Module Functions
Until now we only provided the syntactic interface for the functions in
the NSS module. In fact there is not more much we can tell since the
the NSS module. In fact there is not much more we can say since the
implementation obviously is different for each function. But a few
general rules must be followed by all functions.
@ -635,7 +633,7 @@ As explained above this function could also have an additional last
argument. This depends on the database used; it happens only for
@code{host} and @code{networks}.
The function shall return @code{NSS_STATUS_SUCCESS} as long as their are
The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
more entries. When the last entry was read it should return
@code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too
small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be

6
manual/pipe.texi
View File

@ -95,7 +95,7 @@ read by the child process.
@cindex filtering i/o through subprocess
A common use of pipes is to send data to or receive data from a program
being run as subprocess. One way of doing this is by using a combination of
being run as a subprocess. One way of doing this is by using a combination of
@code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
@code{dup2} (to force the subprocess to use the pipe as its standard input
or output channel), and @code{exec} (to execute the new program). Or,
@ -123,7 +123,7 @@ write to the stream to send data to the standard input channel of the
subprocess. The subprocess inherits its standard output channel from
the parent process.
In the event of an error, @code{popen} returns a null pointer. This
In the event of an error @code{popen} returns a null pointer. This
might happen if the pipe or stream cannot be created, if the subprocess
cannot be forked, or if the program cannot be executed.
@end deftypefun
@ -198,7 +198,7 @@ is not greater than @code{PIPE_BUF}. This means that the data transfer
seems to be an instantaneous unit, in that nothing else in the system
can observe a state in which it is partially complete. Atomic I/O may
not begin right away (it may need to wait for buffer space or for data),
but once it does begin, it finishes immediately.
but once it does begin it finishes immediately.
Reading or writing a larger amount of data may not be atomic; for
example, output data from other processes sharing the descriptor may be

24
manual/signal.texi
View File

@ -1659,7 +1659,7 @@ the past.
Here is an example of a handler for @code{SIGCHLD} that compensates for
the fact that the number of signals received may not equal the number of
child processes generate them. It assumes that the program keeps track
child processes that generate them. It assumes that the program keeps track
of all the child processes with a chain of structures as follows:
@smallexample
@ -1809,7 +1809,7 @@ sig_atomic_t last_process_status_change;
Handler functions usually don't do very much. The best practice is to
write a handler that does nothing but set an external variable that the
program checks regularly, and leave all serious work to the program.
This is best because the handler can be called at asynchronously, at
This is best because the handler can be called asynchronously, at
unpredictable times---perhaps in the middle of a primitive function, or
even between the beginning and the end of a C operator that requires
multiple instructions. The data structures being manipulated might
@ -1856,8 +1856,8 @@ blocks signals around each use, then you are safe.
There are a large number of library functions that return values in a
fixed object, always reusing the same object in this fashion, and all of
them cause the same problem. The description of a function in this
manual always mentions this behavior.
them cause the same problem. Function descriptions in this manual
always mention this behavior.
@item
If a function uses and modifies an object that you supply, then it is
@ -1940,7 +1940,7 @@ Whether the data in your application concerns atoms, or mere text, you
have to be careful about the fact that access to a single datum is not
necessarily @dfn{atomic}. This means that it can take more than one
instruction to read or write a single object. In such cases, a signal
handler might in the middle of reading or writing the object.
handler might be invoked in the middle of reading or writing the object.
There are three ways you can cope with this problem. You can use data
types that are always accessed atomically; you can carefully arrange
@ -2031,9 +2031,9 @@ atomically.
In practice, you can assume that @code{int} and other integer types no
longer than @code{int} are atomic. You can also assume that pointer
types are atomic; that is very convenient. Both of these are true on
all of the machines that the GNU C library supports, and on all POSIX
systems we know of.
types are atomic; that is very convenient. Both of these assumptions
are true on all of the machines that the GNU C library supports and on
all POSIX systems we know of.
@c ??? This might fail on a 386 that uses 64-bit pointers.
@node Atomic Usage
@ -2846,7 +2846,7 @@ not only within @code{update_mumble}, but also within the caller. This
is also why we do not check @code{signal_pending} if @code{defer_signal}
is still nonzero.
The incrementing and decrementing of @code{defer_signal} require more
The incrementing and decrementing of @code{defer_signal} each require more
than one instruction; it is possible for a signal to happen in the
middle. But that does not cause any problem. If the signal happens
early enough to see the value from before the increment or decrement,
@ -2932,12 +2932,12 @@ The function was interrupted by delivery of a signal.
If the signal causes program termination, @code{pause} doesn't return
(obviously).
This function is a cancelation point in multi-threaded programs. This
This function is a cancellation point in multithreaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{pause} is
called. If the thread gets canceled these resources stay allocated
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to @code{pause} should be
protected using cancelation handlers.
protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{pause} function is declared in @file{unistd.h}.

337
manual/socket.texi
View File

@ -8,18 +8,17 @@ communication using sockets.
@cindex socket
@cindex interprocess communication, with sockets
A @dfn{socket} is a generalized interprocess communication channel.
Like a pipe, a socket is represented as a file descriptor. But,
unlike pipes, sockets support communication between unrelated
processes, and even between processes running on different machines
that communicate over a network. Sockets are the primary means of
communicating with other machines; @code{telnet}, @code{rlogin},
@code{ftp}, @code{talk}, and the other familiar network programs use
sockets.
Like a pipe, a socket is represented as a file descriptor. Unlike pipes
sockets support communication between unrelated processes, and even
between processes running on different machines that communicate over a
network. Sockets are the primary means of communicating with other
machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
other familiar network programs use sockets.
Not all operating systems support sockets. In the GNU library, the
header file @file{sys/socket.h} exists regardless of the operating
system, and the socket functions always exist, but if the system does
not really support sockets, these functions always fail.
not really support sockets these functions always fail.
@strong{Incomplete:} We do not currently document the facilities for
broadcast messages or for configuring Internet interfaces. The
@ -28,7 +27,7 @@ aren't documented either so far.
@menu
* Socket Concepts:: Basic concepts you need to know about.
* Communication Styles::Stream communication, datagrams, and other styles.
* Communication Styles::Stream communication, datagrams and other styles.
* Socket Addresses:: How socket names (``addresses'') work.
* Interface Naming:: Identifying specific network interfaces.
* Local Namespace:: Details about the local namespace.
@ -61,7 +60,7 @@ communication style specifies the answers to questions such as these:
@cindex byte stream
@cindex stream (sockets)
@strong{What are the units of data transmission?} Some communication
styles regard the data as a sequence of bytes, with no larger
styles regard the data as a sequence of bytes with no larger
structure; others group the bytes into records (which are known in
this context as @dfn{packets}).
@ -81,7 +80,7 @@ to retransmit data as needed.
@item
@strong{Is communication entirely with one partner?} Some
communication styles are like a telephone call---you make a
@dfn{connection} with one remote socket, and then exchange data
@dfn{connection} with one remote socket and then exchange data
freely. Other styles are like mailing letters---you specify a
destination address for each message you send.
@end itemize
@ -112,7 +111,7 @@ start with @samp{PF_}.
The rules of a protocol apply to the data passing between two programs,
perhaps on different computers; most of these rules are handled by the
operating system, and you need not know about them. What you do need to
operating system and you need not know about them. What you do need to
know about protocols is this:
@itemize @bullet
@ -127,30 +126,30 @@ example, the TCP protocol fits only the byte stream style of
communication and the Internet namespace.
@item
For each combination of style and namespace, there is a @dfn{default
protocol} which you can request by specifying 0 as the protocol
For each combination of style and namespace there is a @dfn{default
protocol}, which you can request by specifying 0 as the protocol
number. And that's what you should normally do---use the default.
@end itemize
Throughout the following description at various places
variables/parameters to denote sizes are required. And here the trouble
starts. In the first implementations the type of these variables was
simply @code{int}. This type was on almost all machines of this time 32
bits wide and so a de-factor standard required 32 bit variables. This
is important since references to variables of this type are passed to
the kernel.
simply @code{int}. On most machines at that time an @code{int} was 32
bits wide, which created a @emph{de facto} standard requiring 32-bit
variables. This is important since references to variables of this type
are passed to the kernel.
But then the POSIX people came and unified the interface with the words
"all size values are of type @code{size_t}". But on 64 bit machines
@code{size_t} is 64 bits wide, and so variable references are not anymore
Then the POSIX people came and unified the interface with the words "all
size values are of type @code{size_t}". On 64-bit machines
@code{size_t} is 64 bits wide, so pointers to variables were no longer
possible.
The Unix98 specification provides a solution by introducing a type
@code{socklen_t}. This type is used in all of the cases that POSIX
changed to use @code{size_t}. The only requirement of this type is that
it be an unsigned type of at least 32 bits. Therefore, implementations
which require that references to 32 bit variables be passed can be as
happy as implementations which use 64 bit values.
which require that references to 32-bit variables be passed can be as
happy as implementations which use 64-bit values.
@node Communication Styles
@ -165,8 +164,8 @@ defined in @file{sys/socket.h}.
@comment sys/socket.h
@comment BSD
@deftypevr Macro int SOCK_STREAM
The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs});
it operates over a connection with a particular remote socket, and
The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
It operates over a connection with a particular remote socket and
transmits data reliably as a stream of bytes.
Use of this style is covered in detail in @ref{Connections}.
@ -176,7 +175,7 @@ Use of this style is covered in detail in @ref{Connections}.
@comment BSD
@deftypevr Macro int SOCK_DGRAM
The @code{SOCK_DGRAM} style is used for sending
individually-addressed packets, unreliably.
individually-addressed packets unreliably.
It is the diametrical opposite of @code{SOCK_STREAM}.
Each time you write data to a socket of this kind, that data becomes
@ -190,7 +189,7 @@ fourth and fifth packets; the seventh packet may arrive before the
sixth, and may arrive a second time after the sixth.
The typical use for @code{SOCK_DGRAM} is in situations where it is
acceptable to simply resend a packet if no response is seen in a
acceptable to simply re-send a packet if no response is seen in a
reasonable amount of time.
@xref{Datagrams}, for detailed information about how to use datagram
@ -203,7 +202,7 @@ sockets.
@comment sys/socket.h
@comment BSD
@deftypevr Macro int SOCK_SEQPACKET
This style is like @code{SOCK_STREAM} except that the data is
This style is like @code{SOCK_STREAM} except that the data are
structured into packets.
A program that receives data over a @code{SOCK_SEQPACKET} socket
@ -262,7 +261,7 @@ you send data from a socket, or use it to initiate a connection, the
system assigns an address automatically if you have not specified one.
Occasionally a client needs to specify an address because the server
discriminates based on addresses; for example, the rsh and rlogin
discriminates based on address; for example, the rsh and rlogin
protocols look at the client's socket address and only bypass password
checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
@ -293,12 +292,12 @@ address. You can't use this data type effectively to interpret an
address or construct one; for that, you must use the proper data type
for the socket's namespace.
Thus, the usual practice is to construct an address in the proper
Thus, the usual practice is to construct an address of the proper
namespace-specific type, then cast a pointer to @code{struct sockaddr *}
when you call @code{bind} or @code{getsockname}.
The one piece of information that you can get from the @code{struct
sockaddr} data type is the @dfn{address format} designator which tells
sockaddr} data type is the @dfn{address format designator}. This tells
you which data type to use to understand the address fully.
@pindex sys/socket.h
@ -376,8 +375,8 @@ for completeness, but there is no reason to use it in a program.
@end table
@file{sys/socket.h} defines symbols starting with @samp{AF_} for many
different kinds of networks, all or most of which are not actually
implemented. We will document those that really work, as we receive
different kinds of networks, most or all of which are not actually
implemented. We will document those that really work as we receive
information about how to use them.
@node Setting Address
@ -395,7 +394,7 @@ The @code{bind} function assigns an address to the socket
@var{socket}. The @var{addr} and @var{length} arguments specify the
address; the detailed format of the address depends on the namespace.
The first part of the address is always the format designator, which
specifies a namespace, and says that the address is in the format for
specifies a namespace, and says that the address is in the format of
that namespace.
The return value is @code{0} on success and @code{-1} on failure. The
@ -566,15 +565,15 @@ as file names.
@node Local Namespace Concepts
@subsection Local Namespace Concepts
In the local namespace, socket addresses are file names. You can specify
In the local namespace socket addresses are file names. You can specify
any file name you want as the address of the socket, but you must have
write permission on the directory containing it. In order to connect to
a socket, you must have read permission for it. It's common to put
a socket you must have read permission for it. It's common to put
these files in the @file{/tmp} directory.
One peculiarity of the local namespace is that the name is only used when
opening the connection; once that is over with, the address is not
meaningful and may not exist.
One peculiarity of the local namespace is that the name is only used
when opening the connection; once open the address is not meaningful and
may not exist.
Another peculiarity is that you cannot connect to such a socket from
another machine--not even if the other machine shares the file system
@ -582,7 +581,7 @@ which contains the name of the socket. You can see the socket in a
directory listing, but connecting to it never succeeds. Some programs
take advantage of this, such as by asking the client to send its own
process ID, and using the process IDs to distinguish between clients.
However, we recommend you not to use this method in protocols you design,
However, we recommend you not use this method in protocols you design,
as we might someday permit connections from other machines that mount
the same file systems. Instead, send each new client an identifying
number if you want it to have one.
@ -642,7 +641,7 @@ namespace. @xref{Socket Addresses}.
This is the file name to use.
@strong{Incomplete:} Why is 108 a magic number? RMS suggests making
this a zero-length array and tweaking the example following to use
this a zero-length array and tweaking the following example to use
@code{alloca} to allocate an appropriate amount of storage based on
the length of the filename.
@end table
@ -676,15 +675,15 @@ namespace.
This section describes the details of the protocols and socket naming
conventions used in the Internet namespace.
Originaly the Internet namespace used only IP version 4 (IPv4). With
Originally the Internet namespace used only IP version 4 (IPv4). With
the growing number of hosts on the Internet, a new protocol with a
larger address space was neccessary: IP version 6 (IPv6). IPv6
introduces besides 128bit addresses (IPv4 has 32bit addresses) also
other features and will eventually replace IPv4.
larger address space was necessary: IP version 6 (IPv6). IPv6
introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
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
@code{socket} or @code{socketpair}. For IPv6 addresses you need the
macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
@pindex sys/socket.h
@ -695,7 +694,9 @@ This designates the IPv4 Internet namespace and associated family of
protocols.
@end deftypevr
@deftypevr Macro int AF_INET6
@comment sys/socket.h
@comment X/Open
@deftypevr Macro int PF_INET6
This designates the IPv6 Internet namespace and associated family of
protocols.
@end deftypevr
@ -706,7 +707,7 @@ A socket address for the Internet namespace includes the following components:
@item
The address of the machine you want to connect to. Internet addresses
can be specified in several ways; these are discussed in @ref{Internet
Address Formats}, @ref{Host Addresses}, and @ref{Host Names}.
Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
@item
A port number for that machine. @xref{Ports}.
@ -719,7 +720,7 @@ for information about this.
@menu
* Internet Address Formats:: How socket addresses are specified in the
Internet namespace.
* Host Addresses:: All about host addresses of internet host.
* Host Addresses:: All about host addresses of Internet host.
* Protocols Database:: Referring to protocols by name.
* Ports:: Internet port numbers.
* Services Database:: Ports may have symbolic names.
@ -751,7 +752,7 @@ Internet namespace. It has the following members:
@table @code
@item sa_family_t sin_family
This identifies the address family or format of the socket address.
You should store the value of @code{AF_INET} in this member.
You should store the value @code{AF_INET} in this member.
@xref{Socket Addresses}.
@item struct in_addr sin_addr
@ -806,9 +807,9 @@ Each computer also has one or more @dfn{host names}, which are strings
of words separated by periods, as in @samp{mescaline.gnu.org}.
Programs that let the user specify a host typically accept both numeric
addresses and host names. But the program needs a numeric address to
open a connection; to use a host name, you must convert it to the
numeric address it stands for.
addresses and host names. To open a connection a program needs a
numeric address, and so must convert a host name to the numeric address
it stands for.
@menu
* Abstract Host Addresses:: What a host number consists of.
@ -832,17 +833,17 @@ numbers which identify that computer among all those on the Internet.
An IPv4 Internet host address is a number containing four bytes of data.
Historically these are divided into two parts, a @dfn{network number} and a
@dfn{local network address number} within that network. In the
mid-1990s classless address were introduced which changed the
mid-1990s classless addresses were introduced which changed this
behaviour. Since some functions implicitly expect the old definitions,
we first describe the class based network and will then describe
classless addresses. IPv6 uses only classless adresses and therefore
we first describe the class-based network and will then describe
classless addresses. IPv6 uses only classless addresses and therefore
the following paragraphs don't apply.
The class based IPv4 network number consists of the first one, two or
The class-based IPv4 network number consists of the first one, two or
three bytes; the rest of the bytes are the local address.
IPv4 network numbers are registered with the Network Information Center
(NIC), and are divided into three classes---A, B, and C. The local
(NIC), and are divided into three classes---A, B and C. The local
network address numbers of individual machines are registered with the
administrator of the particular network.
@ -852,12 +853,12 @@ very large number of hosts. Medium-sized Class B networks have two-byte
network numbers, with the first byte in the range 128 to 191. Class C
networks are the smallest; they have three-byte network numbers, with
the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes
of an Internet address specifies a network. The remaining bytes of the
of an Internet address specify a network. The remaining bytes of the
Internet address specify the address within that network.
The Class A network 0 is reserved for broadcast to all networks. In
addition, the host number 0 within each network is reserved for broadcast
to all hosts in that network. These uses are obsolete now but out of
to all hosts in that network. These uses are obsolete now but for
compatibility reasons you shouldn't use network 0 and host number 0.
The Class A network 127 is reserved for loopback; you can always use
@ -902,15 +903,15 @@ radix is assumed.
@subsubheading Classless Addresses
IPv4 addresses (and IPv6 addresses also) are now considered as
classless. The distinction between classes A, B, and C can be ignored.
Instead a IPv4 host adddress consists of a 32-bit address and a 32-bit
mask. The mask contains bits of 1 for the network part and bits of 0
for the host part. The 1-bits are contigous from the leftmost bit, the
0-bits are contigous from the rightmost bit so that the netmask can also
be written as a prefix length of bits of 1. Classes A, B and C are just
special cases of this general rule. For example, class A addresses have
a netmask of @samp{255.0.0.0} or a prefix length of 8.
IPv4 addresses (and IPv6 addresses also) are now considered classless;
the distinction between classes A, B and C can be ignored. Instead an
IPv4 host address consists of a 32-bit address and a 32-bit mask. The
mask contains set bits for the network part and cleared bits for the
host part. The network part is contiguous from the left, with the
remaining bits representing the host. As a consequence, the netmask can
simply be specified as the number of set bits. Classes A, B and C are
just special cases of this general rule. For example, class A addresses
have a netmask of @samp{255.0.0.0} or a prefix length of 8.
Classless IPv4 network addresses are written in numbers-and-dots
notation with the prefix length appended and a slash as separator. For
@ -921,8 +922,8 @@ example the class A network 10 is written as @samp{10.0.0.0/8}.
IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host
address is usually written as eight 16-bit hexadecimal numbers that are
separated by colons. Two colons are used to abbreviate strings of
consecutive zeros. For example the IPv6 loopback address which is
@samp{0:0:0:0:0:0:0:1} can be just written as @samp{::1}.
consecutive zeros. For example, the IPv6 loopback address
@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
@node Host Address Data Type
@subsubsection Host Address Data Type
@ -935,8 +936,8 @@ the integer from the structure or put the integer into a structure.
You will find older code that uses @code{unsigned long int} for
IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
in_addr}. Historically @code{unsigned long int} was a 32 bit number but
with 64 bit machines this has changed. Using @code{unsigned long int}
in_addr}. Historically @code{unsigned long int} was a 32-bit number but
with 64-bit machines this has changed. Using @code{unsigned long int}
might break the code if it is used on machines where this type doesn't
have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have
32 bits.
@ -971,7 +972,7 @@ talking to itself.
@comment netinet/in.h
@comment BSD
@deftypevr Macro {uint32_t} INADDR_ANY
You can use this constant to stand for ``any incoming address,'' when
You can use this constant to stand for ``any incoming address'' when
binding to an address. @xref{Setting Address}. This is the usual
address to give in the @code{sin_addr} member of @w{@code{struct
sockaddr_in}} when you want to accept Internet connections.
@ -1002,7 +1003,7 @@ data, which can be accessed (via a union) in a variety of ways.
@deftypevr Constant {struct in6_addr} in6addr_loopback
This constant is the IPv6 address @samp{::1}, the loopback address. See
above for a description of what this means. The macro
@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialise your
@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
own variables to this value.
@end deftypevr
@ -1011,7 +1012,7 @@ own variables to this value.
@deftypevr Constant {struct in6_addr} in6addr_any
This constant is the IPv6 address @samp{::}, the unspecified address. See
above for a description of what this means. The macro
@code{IN6ADDR_ANY_INIT} is provided to allow you to initialise your
@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
own variables to this value.
@end deftypevr
@ -1022,7 +1023,7 @@ own variables to this value.
@noindent
These additional functions for manipulating Internet addresses are
declared in the header file @file{arpa/inet.h}. They represent Internet
addresses in network byte order; they represent network numbers and
addresses in network byte order, and network numbers and
local-address-within-network numbers in host byte order. @xref{Byte
Order}, for an explanation of network and host byte order.
@ -1041,7 +1042,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.
@ -1170,7 +1171,7 @@ vector of strings.
This is the host address type; in practice, its value is always either
@code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
hosts. In principle other kinds of addresses could be represented in
the data base as well as Internet addresses; if this were done, you
the database as well as Internet addresses; if this were done, you
might find a value in this field other than @code{AF_INET} or
@code{AF_INET6}. @xref{Socket Addresses}.
@ -1214,7 +1215,7 @@ named @var{name}. If the lookup fails, it returns a null pointer.
@deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
The @code{gethostbyname2} function is like @code{gethostbyname}, but
allows the caller to specify the desired address family (e.g.@:
@code{AF_INET} or @code{AF_INET6}) for the result.
@code{AF_INET} or @code{AF_INET6}) of the result.
@end deftypefun
@comment netdb.h
@ -1245,7 +1246,7 @@ Here are the error codes that you may find in @code{h_errno}:
@comment BSD
@item HOST_NOT_FOUND
@vindex HOST_NOT_FOUND
No such host is known in the data base.
No such host is known in the database.
@comment netdb.h
@comment BSD
@ -1349,8 +1350,8 @@ too small.
@end deftypefun
You can also scan the entire hosts database one entry at a time using
@code{sethostent}, @code{gethostent}, and @code{endhostent}. Be careful
in using these functions, because they are not reentrant.
@code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful
when using these functions because they are not reentrant.
@comment netdb.h
@comment BSD
@ -1494,8 +1495,8 @@ find such a service, it returns a null pointer.
@noindent
You can also scan the services database using @code{setservent},
@code{getservent}, and @code{endservent}. Be careful in using these
functions, because they are not reentrant.
@code{getservent} and @code{endservent}. Be careful when using these
functions because they are not reentrant.
@comment netdb.h
@comment BSD
@ -1538,11 +1539,11 @@ order), and others put it last (``little-endian'' order).
So that machines with different byte order conventions can
communicate, the Internet protocols specify a canonical byte order
convention for data transmitted over the network. This is known
as the @dfn{network byte order}.
as @dfn{network byte order}.
When establishing an Internet socket connection, you must make sure that
the data in the @code{sin_port} and @code{sin_addr} members of the
@code{sockaddr_in} structure are represented in the network byte order.
@code{sockaddr_in} structure are represented in network byte order.
If you are encoding integer data in the messages sent through the
socket, you should convert this to network byte order too. If you don't
do this, your program may fail when running on or talking to other kinds
@ -1550,7 +1551,7 @@ of machines.
If you use @code{getservbyname} and @code{gethostbyname} or
@code{inet_addr} to get the port number and host address, the values are
already in the network byte order, and you can copy them directly into
already in network byte order, and you can copy them directly into
the @code{sockaddr_in} structure.
Otherwise, you have to convert the values explicitly. Use @code{htons}
@ -1581,7 +1582,7 @@ network byte order to host byte order.
This function converts the @code{uint32_t} integer @var{hostlong} from
host byte order to network byte order.
This is used for IPv4 internet addresses.
This is used for IPv4 Internet addresses.
@end deftypefun
@comment netinet/in.h
@ -1590,7 +1591,7 @@ This is used for IPv4 internet addresses.
This function converts the @code{uint32_t} integer @var{netlong} from
network byte order to host byte order.
This is used for IPv4 internet addresses.
This is used for IPv4 Internet addresses.
@end deftypefun
@node Protocols Database
@ -1598,7 +1599,7 @@ This is used for IPv4 internet addresses.
@cindex protocols database
The communications protocol used with a socket controls low-level
details of how data is exchanged. For example, the protocol implements
details of how data are exchanged. For example, the protocol implements
things like checksums to detect errors in transmissions, and routing
instructions for messages. Normal user programs have little reason to
mess with these details directly.
@ -1665,8 +1666,8 @@ protocol, it returns a null pointer.
@end deftypefun
You can also scan the whole protocols database one protocol at a time by
using @code{setprotoent}, @code{getprotoent}, and @code{endprotoent}.
Be careful in using these functions, because they are not reentrant.
using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
Be careful when using these functions because they are not reentrant.
@comment netdb.h
@comment BSD
@ -1729,7 +1730,7 @@ CCITT. @file{socket.h} defines these symbols and others naming protocols
not actually implemented.
@code{PF_IMPLINK} is used for communicating between hosts and Internet
Message Processors. For information on this, and on @code{PF_ROUTE}, an
Message Processors. For information on this and @code{PF_ROUTE}, an
occasionally-used local area routing protocol, see the GNU Hurd Manual
(to appear in the future).
@ -1783,7 +1784,7 @@ The process already has too many file descriptors open.
The system already has too many file descriptors open.
@item EACCESS
The process does not have privilege to create a socket of the specified
The process does not have the privilege to create a socket of the specified
@var{style} or @var{protocol}.
@item ENOBUFS
@ -1791,7 +1792,7 @@ The system ran out of internal buffer space.
@end table
The file descriptor returned by the @code{socket} function supports both
read and write operations. But, like pipes, sockets do not support file
read and write operations. However, like pipes, sockets do not support file
positioning operations.
@end deftypefun
@ -1806,7 +1807,7 @@ see @ref{Local Socket Example}, or @ref{Inet Example}.
@cindex shutting down a socket
@cindex socket shutdown
When you are finished using a socket, you can simply close its
When you have finished using a socket, you can simply close its
file descriptor with @code{close}; see @ref{Opening and Closing Files}.
If there is still data waiting to be transmitted over the connection,
normally @code{close} tries to complete this transmission. You
@ -1814,7 +1815,7 @@ can control this behavior using the @code{SO_LINGER} socket option to
specify a timeout period; see @ref{Socket Options}.
@pindex sys/socket.h
You can also shut down only reception or only transmission on a
You can also shut down only reception or transmission on a
connection by calling @code{shutdown}, which is declared in
@file{sys/socket.h}.
@ -1877,7 +1878,7 @@ This function creates a socket pair, returning the file descriptors in
is a full-duplex communications channel, so that both reading and writing
may be performed at either end.
The @var{namespace}, @var{style}, and @var{protocol} arguments are
The @var{namespace}, @var{style} and @var{protocol} arguments are
interpreted as for the @code{socket} function. @var{style} should be
one of the communication styles listed in @ref{Communication Styles}.
The @var{namespace} argument specifies the namespace, which must be
@ -1927,12 +1928,12 @@ over and over. Making a connection is asymmetric; one side (the
initiate a connection with a server.
@item
@ref{Listening}, and @ref{Accepting Connections}, describe what the
@ref{Listening} and @ref{Accepting Connections} describe what the
server program must do to wait for and act upon connection requests
from clients.
@item
@ref{Transferring Data}, describes how data is transferred through the
@ref{Transferring Data}, describes how data are transferred through the
connected socket.
@end itemize
@end iftex
@ -1959,7 +1960,7 @@ connected socket.
In making a connection, the client makes a connection while the server
waits for and accepts the connection. Here we discuss what the client
program must do, using the @code{connect} function, which is declared in
program must do with the @code{connect} function, which is declared in
@file{sys/socket.h}.
@comment sys/socket.h
@ -2024,10 +2025,10 @@ The socket @var{socket} is non-blocking and already has a pending
connection in progress (see @code{EINPROGRESS} above).
@end table
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2052,7 +2053,7 @@ You can write a network server that does not even start running until a
connection to it is requested. @xref{Inetd Servers}.
In the Internet namespace, there are no special protection mechanisms
for controlling access to connect to a port; any process on any machine
for controlling access to a port; any process on any machine
can make a connection to your server. If you want to restrict access to
your server, make it examine the addresses associated with connection
requests or implement some other handshaking or identification
@ -2099,7 +2100,7 @@ to do this.
A socket that has been established as a server can accept connection
requests from multiple clients. The server's original socket
@emph{does not become part} of the connection; instead, @code{accept}
@emph{does not become part of the connection}; instead, @code{accept}
makes a new socket which participates in the connection.
@code{accept} returns the descriptor for this socket. The server's
original socket remains available for listening for further connection
@ -2108,7 +2109,7 @@ requests.
The number of pending connection requests on a server socket is finite.
If connection requests arrive from clients faster than the server can
act upon them, the queue can fill up and additional requests are refused
with a @code{ECONNREFUSED} error. You can specify the maximum length of
with an @code{ECONNREFUSED} error. You can specify the maximum length of
this queue as an argument to the @code{listen} function, although the
system may also impose its own internal limit on the length of this
queue.
@ -2158,10 +2159,10 @@ The descriptor @var{socket} does not support this operation.
connections immediately available.
@end table
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2217,7 +2218,7 @@ In order to specify these modes, you must use the @code{recv} and
@code{send} functions instead of the more generic @code{read} and
@code{write} functions. The @code{recv} and @code{send} functions take
an additional argument which you can use to specify various flags to
control the special I/O modes. For example, you can specify the
control special I/O modes. For example, you can specify the
@code{MSG_OOB} flag to read or write out-of-band data, the
@code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
to control inclusion of routing information on output.
@ -2290,10 +2291,10 @@ signal is ignored or blocked, or if its handler returns, then
@code{send} fails with @code{EPIPE}.
@end table
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2313,7 +2314,7 @@ The @code{recv} function is like @code{read}, but with the additional
flags @var{flags}. The possible values of @var{flags} are described
in @ref{Socket Data Options}.
If nonblocking mode is set for @var{socket}, and no data is available to
If nonblocking mode is set for @var{socket}, and no data are available to
be read, @code{recv} fails immediately rather than waiting. @xref{File
Status Flags}, for information about nonblocking mode.
@ -2340,10 +2341,10 @@ The operation was interrupted by a signal before any data was read.
You never connected this socket.
@end table
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2424,18 +2425,18 @@ This program uses @code{make_socket} to set up the socket address; see
Streams with connections permit @dfn{out-of-band} data that is
delivered with higher priority than ordinary data. Typically the
reason for sending out-of-band data is to send notice of an
exceptional condition. The way to send out-of-band data is using
exceptional condition. To send out-of-band data use
@code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
Data}).
Out-of-band data is received with higher priority because the
Out-of-band data are received with higher priority because the
receiving process need not read it in sequence; to read the next
available out-of-band data, use @code{recv} with the @code{MSG_OOB}
flag (@pxref{Receiving Data}). Ordinary read operations do not read
out-of-band data; they read only the ordinary data.
out-of-band data; they read only ordinary data.
@cindex urgent socket condition
When a socket finds that out-of-band data is on its way, it sends a
When a socket finds that out-of-band data are on their way, it sends a
@code{SIGURG} signal to the owner process or process group of the
socket. You can specify the owner using the @code{F_SETOWN} command
to the @code{fcntl} function; see @ref{Interrupt Input}. You must
@ -2449,7 +2450,7 @@ can wait for an exceptional condition on the socket. @xref{Waiting
for I/O}, for more information about @code{select}.
Notification of out-of-band data (whether with @code{SIGURG} or with
@code{select}) indicates that out-of-band data is on the way; the data
@code{select}) indicates that out-of-band data are on the way; the data
may not actually arrive until later. If you try to read the
out-of-band data before it arrives, @code{recv} fails with an
@code{EWOULDBLOCK} error.
@ -2522,7 +2523,7 @@ struct buffer
@r{It may be necessary to read some ordinary data}
@r{in order to make room for the out-of-band data.}
@r{If so, the ordinary data is saved as a chain of buffers}
@r{If so, the ordinary data are saved as a chain of buffers}
@r{found in the `next' field of the value.} */
struct buffer *
@ -2599,7 +2600,7 @@ these styles, you group data into packets and each packet is an
independent communication. You specify the destination for each
packet individually.
Datagram packets are like letters: you send each one independently,
Datagram packets are like letters: you send each one independently
with its own destination address, and they may arrive in the wrong
order or not at all.
@ -2626,7 +2627,7 @@ The normal way of sending data on a datagram socket is by using the
You can call @code{connect} on a datagram socket, but this only
specifies a default destination for further data transmission on the
socket. When a socket has a default destination, then you can use
socket. When a socket has a default destination you can use
@code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
Primitives}) to send a packet there. You can cancel the default
destination by calling @code{connect} using an address format of
@ -2647,16 +2648,16 @@ The @var{flags} are interpreted the same way as for @code{send}; see
The return value and error conditions are also the same as for
@code{send}, but you cannot rely on the system to detect errors and
report them; the most common error is that the packet is lost or there
is no one at the specified address to receive it, and the operating
is no-one at the specified address to receive it, and the operating
system on your machine usually does not know this.
It is also possible for one call to @code{sendto} to report an error
due to a problem related to a previous call.
owing to a problem related to a previous call.
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2676,13 +2677,13 @@ The @code{recvfrom} function reads one packet from the socket
specifies the maximum number of bytes to be read.
If the packet is longer than @var{size} bytes, then you get the first
@var{size} bytes of the packet, and the rest of the packet is lost.
@var{size} bytes of the packet and the rest of the packet is lost.
There's no way to read the rest of the packet. Thus, when you use a
packet protocol, you must always know how long a packet to expect.
The @var{addr} and @var{length-ptr} arguments are used to return the
address where the packet came from. @xref{Socket Addresses}. For a
socket in the local domain, the address information won't be meaningful,
socket in the local domain the address information won't be meaningful,
since you can't read the address of such a socket (@pxref{Local
Namespace}). You can specify a null pointer as the @var{addr} argument
if you are not interested in this information.
@ -2691,15 +2692,15 @@ The @var{flags} are interpreted the same way as for @code{recv}
(@pxref{Socket Data Options}). The return value and error conditions
are also the same as for @code{recv}.
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
You can use plain @code{recv} (@pxref{Receiving Data}) instead of
@code{recvfrom} if you know don't need to find out who sent the packet
@code{recvfrom} if you don't need to find out who sent the packet
(either because you know where it should come from or because you
treat all possible senders alike). Even @code{read} can be used if
you don't want to specify @var{flags} (@pxref{I/O Primitives}).
@ -2719,10 +2720,10 @@ you don't want to specify @var{flags} (@pxref{I/O Primitives}).
@comment BSD
@deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is cancel.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is cancel.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@ -2730,10 +2731,10 @@ semaphores or whatever) are freed even if the thread is cancel.
@comment BSD
@deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
This function is defined as a cancelation point in multi-threaded
programs. So one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors,
semaphores or whatever) are freed even if the thread is canceled.
This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun
@end ignore
@ -2748,7 +2749,7 @@ Socket Example}, to create and name their sockets.
First, here is the server program. It sits in a loop waiting for
messages to arrive, bouncing each message back to the sender.
Obviously, this isn't a particularly useful program, but it does show
Obviously this isn't a particularly useful program, but it does show
the general ideas involved.
@smallexample
@ -2774,10 +2775,10 @@ referencing the name of the client.
Keep in mind that datagram socket communications are unreliable. In
this example, the client program waits indefinitely if the message
never reaches the server or if the server's response never comes
back. It's up to the user running the program to kill it and restart
it, if desired. A more automatic solution could be to use
back. It's up to the user running the program to kill and restart
it if desired. A more automatic solution could be to use
@code{select} (@pxref{Waiting for I/O}) to establish a timeout period
for the reply, and in case of timeout either resend the message or
for the reply, and in case of timeout either re-send the message or
shut down the socket and exit.
@node Inetd
@ -2787,7 +2788,7 @@ We've explained above how to write a server program that does its own
listening. Such a server must already be running in order for anyone
to connect to it.
Another way to provide service for an Internet port is to let the daemon
Another way to provide a service on an Internet port is to let the daemon
program @code{inetd} do the listening. @code{inetd} is a program that
runs all the time and waits (using @code{select}) for messages on a
specified set of ports. When it receives a message, it accepts the
@ -2808,19 +2809,19 @@ someone requests a connection to the appropriate port, a new server
process starts. The connection already exists at this time; the
socket is available as the standard input descriptor and as the
standard output descriptor (descriptors 0 and 1) in the server
process. So the server program can begin reading and writing data
process. Thus the server program can begin reading and writing data
right away. Often the program needs only the ordinary I/O facilities;
in fact, a general-purpose filter program that knows nothing about
sockets can work as a byte stream server run by @code{inetd}.
You can also use @code{inetd} for servers that use connectionless
communication styles. For these servers, @code{inetd} does not try to accept
a connection, since no connection is possible. It just starts the
a connection since no connection is possible. It just starts the
server program, which can read the incoming datagram packet from
descriptor 0. The server program can handle one request and then
exit, or you can choose to write it to keep reading more requests
until no more arrive, and then exit. You must specify which of these
two techniques the server uses, when you configure @code{inetd}.
two techniques the server uses when you configure @code{inetd}.
@node Configuring Inetd
@subsection Configuring @code{inetd}
@ -2859,7 +2860,7 @@ byte stream connections and @samp{udp} for unreliable datagrams.
The @var{wait} field should be either @samp{wait} or @samp{nowait}.
Use @samp{wait} if @var{style} is a connectionless style and the
server, once started, handles multiple requests, as many as come in.
server, once started, handles multiple requests as they come in.
Use @samp{nowait} if @code{inetd} should start a new process for each message
or request that comes in. If @var{style} uses connections, then
@var{wait} @strong{must} be @samp{nowait}.
@ -2882,7 +2883,7 @@ program name itself (sans directories).
If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
file and obey its new contents by sending the @code{inetd} process the
@code{SIGHUP} signal. You'll have to use @code{ps} to determine the
process ID of the @code{inetd} process, as it is not fixed.
process ID of the @code{inetd} process as it is not fixed.
@c !!! could document /etc/inetd.sec
@ -2948,7 +2949,7 @@ The @var{optname} doesn't make sense for the given @var{level}.
@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen})
This function is used to set the socket option @var{optname} at level
@var{level} for socket @var{socket}. The value of the option is passed
in the buffer @var{optval}, which has size @var{optlen}.
in the buffer @var{optval} of size @var{optlen}.
@c Argh. -zw
@iftex
@ -2989,7 +2990,7 @@ This option toggles recording of debugging information in the underlying
protocol modules. The value has type @code{int}; a nonzero value means
``yes''.
@c !!! should say how this is used
@c Ok, anyone who knows, please explain.
@c OK, anyone who knows, please explain.
@comment sys/socket.h
@comment BSD
@ -3037,7 +3038,7 @@ This structure type has the following members:
@table @code
@item int l_onoff
This field is interpreted as a boolean. If nonzero, @code{close}
blocks until the data is transmitted or the timeout period has expired.
blocks until the data are transmitted or the timeout period has expired.
@item int l_linger
This specifies the timeout period, in seconds.
@ -3107,7 +3108,7 @@ to the system developer. This is usually kept either in the file
@file{/etc/networks} or in an equivalent from a name server. This data
base is useful for routing programs such as @code{route}, but it is not
useful for programs that simply communicate over the network. We
provide functions to access this data base, which are declared in
provide functions to access this database, which are declared in
@file{netdb.h}.
@comment netdb.h
@ -3159,8 +3160,8 @@ network.
@end deftypefun
You can also scan the networks database using @code{setnetent},
@code{getnetent}, and @code{endnetent}. Be careful in using these
functions, because they are not reentrant.
@code{getnetent} and @code{endnetent}. Be careful when using these
functions because they are not reentrant.
@comment netdb.h
@comment BSD

103
manual/stdio.texi
View File

@ -1847,14 +1847,14 @@ The information is stored in the array @var{argtypes}; each element of
this array describes one argument. This information is encoded using
the various @samp{PA_} macros, listed below.
The @var{n} argument specifies the number of elements in the array
@var{argtypes}. This is the most elements that
The argument @var{n} specifies the number of elements in the array
@var{argtypes}. This is the maximum number of elements that
@code{parse_printf_format} will try to write.
@code{parse_printf_format} returns the total number of arguments required
by @var{template}. If this number is greater than @var{n}, then the
information returned describes only the first @var{n} arguments. If you
want information about more than that many arguments, allocate a bigger
want information about additional arguments, allocate a bigger
array and call @code{parse_printf_format} again.
@end deftypefun
@ -2107,9 +2107,9 @@ about this.
@c but if you are never going to call @code{parse_printf_format}, you do
@c not need to define an arginfo function.
@strong{Attention:} In the GNU C library version before 2.0 the
@strong{Attention:} In the GNU C library versions before 2.0 the
@var{arginfo-function} function did not need to be installed unless
the user uses the @code{parse_printf_format} function. This changed.
the user used the @code{parse_printf_format} function. This has changed.
Now a call to any of the @code{printf} functions will call this
function when this format specifier appears in the format string.
@ -2220,7 +2220,7 @@ width. The value is @code{'0'} if the @samp{0} flag was specified, and
Now let's look at how to define the handler and arginfo functions
which are passed as arguments to @code{register_printf_function}.
@strong{Compatibility Note:} The interface changed in the GNU libc
@strong{Compatibility Note:} The interface changed in GNU libc
version 2.0. Previously the third argument was of type
@code{va_list *}.
@ -2254,7 +2254,7 @@ a description of this data structure.
@c arguments that your handler processes. @xref{Variadic Functions}.)
The @var{args} is a vector of pointers to the arguments data.
The number of arguments were determined by calling the argument
The number of arguments was determined by calling the argument
information function provided by the user.
Your handler function should return a value just like @code{printf}
@ -2328,7 +2328,7 @@ which implement a special way to print floating-point numbers.
Print a given floating point number as for the format @code{%f} except
that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors:
powers of 1024 or powers to 1000. Which one is used depends on the
powers of 1024 or powers of 1000. Which one is used depends on the
format character specified while registered this handler. If the
character is of lower case, 1024 is used. For upper case characters,
1000 is used.
@ -2378,7 +2378,7 @@ format character as if it were @code{%.3fk} and will yield @code{1.000k}.
@end deftypefun
Due to the requirements of @code{register_printf_function} we must also
provide the function which return information about the arguments.
provide the function which returns information about the arguments.
@comment printf.h
@comment GNU
@ -2403,14 +2403,14 @@ register_printf_function ('b', printf_size, printf_size_info);
@end smallexample
@noindent
we could also print using power of 1024. Please note that all what is
different in these both lines in the format specifier. The
@code{printf_size} function knows about the difference of low and upper
we could also print using a power of 1024. Please note that all that is
different in these two lines is the format specifier. The
@code{printf_size} function knows about the difference between lower and upper
case format specifiers.
The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is
the preferred way to use this functionality since it is available on
some other systems also available using the format specifiers.
some other systems which also use format specifiers.
@node Formatted Input
@section Formatted Input
@ -2784,7 +2784,7 @@ in. @xref{Dynamic String Input}.
@end itemize
The @samp{%c} conversion is the simplest: it matches a fixed number of
characters, always. The maximum field with says how many characters to
characters, always. The maximum field width says how many characters to
read; if you don't specify the maximum, the default is 1. This
conversion doesn't append a null character to the end of the text it
reads. It also does not skip over initial whitespace characters. It
@ -2903,7 +2903,7 @@ conversion specification to read a ``variable assignment'' of the form
This section describes the miscellaneous input conversions.
The @samp{%p} conversion is used to read a pointer value. It recognizes
the same syntax as is used by the @samp{%p} output conversion for
the same syntax used by the @samp{%p} output conversion for
@code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
number just as the @samp{%x} conversion accepts. The corresponding
argument should be of type @code{void **}; that is, the address of a
@ -2946,9 +2946,9 @@ The optional arguments are pointers to the places which receive the
resulting values.
The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed
(including matches against whitespace and literal characters in the
template), then @code{EOF} is returned.
an end-of-file condition is detected before any matches are performed,
including matches against whitespace and literal characters in the
template, then @code{EOF} is returned.
@end deftypefun
@comment stdio.h
@ -2987,7 +2987,7 @@ extensions.
@comment stdio.h
@comment GNU
@deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
This function is similar to @code{scanf} except that, instead of taking
This function is similar to @code{scanf}, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@end deftypefun
@ -3010,8 +3010,8 @@ In GNU C, there is a special construct you can use to let the compiler
know that a function uses a @code{scanf}-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
@xref{Function Attributes, , Declaring Attributes of Functions,
gcc.info, Using GNU CC}, for details.
For details, @xref{Function Attributes, , Declaring Attributes of Functions,
gcc.info, Using GNU CC}.
@node EOF and Errors
@section End-Of-File and Errors
@ -3169,18 +3169,15 @@ possibly for other reasons as well. If a failure occurs, a value of
@comment stdio.h
@comment Unix98
@deftypefun off_t ftello (FILE *@var{stream})
The @code{ftello} function is similar to @code{ftell} only it corrects a
problem which the POSIX type system. In this type system all file
positions are described using values of type @code{off_t} which is not
necessarily of the same size as @code{long int}. Therefore using
@code{ftell} can lead to problems if the implementation is written on
top of a POSIX compliant lowlevel I/O implementation.
The @code{ftello} function is similar to @code{ftell}, except that it
returns a value of type @code{off_t}. Systems which support this type
use it to describe all file positions, unlike the POSIX specification
which uses a long int. The two are not necessarily the same size.
Therefore, using ftell can lead to problems if the implementation is
written on top of a POSIX compliant low-level I/O implementation, and using
@code{ftello} is preferable whenever it is available.
Therefore it is a good idea to prefer @code{ftello} whenever it is
available since its functionality is (if different at all) closer the
underlying definition.
If this function fails it return @code{(off_t) -1}. This can happen due
If this function fails it returns @code{(off_t) -1}. This can happen due
to missing support for file positioning or internal errors. Otherwise
the return value is the current file position.
@ -3360,9 +3357,9 @@ the same file position.
@item
In a call to @code{fseek} or @code{fseeko} on a text stream, either the
@var{offset} must either be zero; or @var{whence} must be
@code{SEEK_SET} and the @var{offset} must be the result of an earlier
call to @code{ftell} on the same stream.
@var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
and the @var{offset} must be the result of an earlier call to @code{ftell}
on the same stream.
@item
The value of the file position indicator of a text stream is undefined
@ -3484,7 +3481,7 @@ If you are writing programs that do interactive input and output using
streams, you need to understand how buffering works when you design the
user interface to your program. Otherwise, you might find that output
(such as progress or prompt messages) doesn't appear when you intended
it to, or other unexpected behavior.
it to, or displays some other unexpected behavior.
This section deals only with controlling when characters are transmitted
between the stream and the file or device, and @emph{not} with how
@ -3756,8 +3753,8 @@ This function opens a stream that allows the access specified by the
by the argument @var{buf}. This array must be at least @var{size} bytes long.
If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
dynamically allocates (as with @code{malloc}; @pxref{Unconstrained
Allocation}) an array @var{size} bytes long. This is really only useful
dynamically allocates an array @var{size} bytes long (as with @code{malloc};
@pxref{Unconstrained Allocation}). This is really only useful
if you are going to write things to the buffer and then read them back
in again, because you have no way of actually getting a pointer to the
buffer (for this, try @code{open_memstream}, below). The buffer is
@ -4162,7 +4159,7 @@ Display a message described by its parameters on the device(s) specified
in the @var{classification} parameter. The @var{label} parameter
identifies the source of the message. The string should consist of two
colon separated parts where the first part has not more than 10 and the
second part not more the 14 characters. The @var{text} parameter
second part not more than 14 characters. The @var{text} parameter
describes the condition of the error, the @var{action} parameter possible
steps to recover from the error and the @var{tag} parameter is a
reference to the online documentation where more information can be
@ -4228,7 +4225,7 @@ inserted if necessary, i.e., if the corresponding parameter is not
ignored.
This function is specified in the X/Open Portability Guide. It is also
available on all system derived from System V.
available on all systems derived from System V.
The function returns the value @code{MM_OK} if no error occurred. If
only the printing to standard error failed, it returns @code{MM_NOMSG}.
@ -4241,7 +4238,7 @@ is incorrect.
There are two environment variables which influence the behaviour of
@code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
output actually happening on standard error (@emph{not} the console
output). Each of the five fields can explicitely be enabled. To do
output). Each of the five fields can explicitly be enabled. To do
this the user has to put the @code{MSGVERB} variable with a format like
the following in the environment before calling the @code{fmtmsg} function
the first time:
@ -4291,17 +4288,17 @@ not print the numeric value but instead the string representation).
@subsection Adding Severity Classes
@cindex severity class
There is another possibility to introduce severity classes beside using
There is another possibility to introduce severity classes besides using
the environment variable @code{SEV_LEVEL}. This simplifies the task of
introducing new classes in a running program. One could use the
@code{setenv} or @code{putenv} function to set the environment variable,
but this is toilsome.
@deftypefun int addseverity (int @var{severity}, const char *@var{string})
This function allows to introduce new severity classes which can be
This function allows the introduction of new severity classes which can be
addressed by the @var{severity} parameter of the @code{fmtmsg} function.
The @var{severity} parameter of @code{addseverity} must match the value
for the parameter with the same name of @code{fmtmsg} and @var{string}
for the parameter with the same name of @code{fmtmsg}, and @var{string}
is the string printed in the actual messages instead of the numeric
value.
@ -4332,14 +4329,14 @@ functions described in this section.
@include fmtmsgexpl.c.texi
@end smallexample
The second call to @code{fmtmsg} illustrates a use of this function how
it usually happens on System V systems which heavily use this function.
It might be worth a thought to follow the scheme used in System V
systems so we give a short explanation here. The value of the
The second call to @code{fmtmsg} illustrates a use of this function as
it usually occurs on System V systems, which heavily use this function.
It seems worthwhile to give a short explanation here of how this system
works on System V. The value of the
@var{label} field (@code{UX:cat}) says that the error occured in the
Unix program @code{cat}. The explanation of the error follows and the
value for the @var{action} parameter is @code{"refer to manual"}. One
could me more specific here, if needed. The @var{tag} field contains,
could be more specific here, if necessary. The @var{tag} field contains,
as proposed above, the value of the string given for the @var{label}
parameter, and additionally a unique ID (@code{001} in this case). For
a GNU environment this string could contain a reference to the
@ -4362,7 +4359,7 @@ form. The string must contain two fields, separated by a colon
(@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
produced no output since the class with the numeric value @code{6} is
not defined. Although a class with numeric value @code{5} is also not
defined by default, the call the @code{addseverity} introduces it and
defined by default, the call to @code{addseverity} introduces it and
the second call to @code{fmtmsg} produces the above output.
When we change the environment of the program to contain
@ -4375,11 +4372,11 @@ label:foo: NOTE: text
TO FIX: action tag
@end smallexample
Now the third call the @code{fmtmsg} produced some output and we see how
Now the third call to @code{fmtmsg} produced some output and we see how
the string @code{NOTE} from the environment variable appears in the
message.
Now we can reduce the output by specifying in which fields we are
Now we can reduce the output by specifying which fields we are
interested in. If we additionally set the environment variable
@code{MSGVERB} to the value @code{severity:label:action} we get the
following output:
@ -4395,5 +4392,5 @@ TO FIX: action
I.e., the output produced by the @var{text} and the @var{tag} parameters
to @code{fmtmsg} vanished. Please also note that now there is no colon
after the @code{NOTE} and @code{NOTE2} strings in the output. This is
not necessary since there is no more output on this line since the text
not necessary since there is no more output on this line because the text
is missing.

28
manual/sysinfo.texi
View File

@ -82,7 +82,7 @@ This process cannot set the host name because it is not privileged.
@deftypefun {long int} gethostid (void)
This function returns the ``host ID'' of the machine the program is
running on. By convention, this is usually the primary Internet address
of that machine, converted to a @w{@code{long int}}. However, some
of that machine, converted to a @w{@code{long int}}. However, on some
systems it is a meaningless but unique number which is hard-coded for
each machine.
@end deftypefun
@ -95,7 +95,7 @@ to @var{id}. Only privileged processes are allowed to do this. Usually
it happens just once, at system boot time.
The return value is @code{0} on success and @code{-1} on failure.
The following @code{errno} error condition is defined for this function:
The following @code{errno} error conditions are defined for this function:
@table @code
@item EPERM
@ -186,10 +186,10 @@ possibility.
@section Which filesystems are mounted and/or available?
The Unix concept of @emph{Everything is a file} is based on the
possibility to @dfn{mount} filesystems or other things into the
ability to @dfn{mount} filesystems or other things into the
filesystem. For some programs it is desirable and necessary to access
the information whether and, if yes, where a certain filesystem is
mounted or simply to get lists of all the available filesystems. The
information about whether a certain filesystem is mounted and, if it is,
where, or simply to get lists of all the available filesystems. The
GNU libc provides some functions to retrieve this information portably.
Traditionally Unix systems have a file named @file{/etc/fstab} which
@ -252,7 +252,7 @@ more than one option, separated from the others by a comma. Each option
consists of a name and an optional value part, introduced by an @code{=}
character.
If the value of this element must be processed it should best happen
If the value of this element must be processed it should ideally be done
using the @code{getsubopt} function; see @ref{Suboptions}.
@item const char *fs_type
@ -323,7 +323,7 @@ is the first call to any of the functions handling @file{fstab} since
program start or the last call of @code{endfsent}, the file will be
opened.
The function returns a pointer to an variable of type @code{struct
The function returns a pointer to a variable of type @code{struct
fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer.
@ -340,7 +340,7 @@ argument. If this is the first call to any of the functions handling
@file{fstab} since program start or the last call of @code{endfsent},
the file will be opened.
The function returns a pointer to an variable of type @code{struct
The function returns a pointer to a variable of type @code{struct
fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer.
@ -357,7 +357,7 @@ argument. If this is the first call to any of the functions handling
@file{fstab} since program start or the last call of @code{endfsent},
the file will be opened.
The function returns a pointer to an variable of type @code{struct
The function returns a pointer to a variable of type @code{struct
fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer.
@ -387,11 +387,11 @@ filesystem. It corresponds to the @code{fs_file} element in
@item char *mnt_type
@code{mnt_type} describes the filesystem type and is therefore
equivalent to @code{fs_vfstype} in @code{struct fstab}. @file{mntent.h}
defines a few symbolic names for some of the value this string can have.
But since the kernel can support an arbitrary filesystems it does not
defines a few symbolic names for some of the values this string can have.
But since the kernel can support arbitrary filesystems it does not
make much sense to give them symbolic names. If one knows the symbol
name one also knows the filesystem name. Nevertheless here follows the
list of the symbol provided in @file{mntent.h}.
list of the symbols provided in @file{mntent.h}.
@vtable @code
@item MNTTYPE_IGNORE
@ -414,7 +414,7 @@ the filesystem. As for the equivalent element @code{fs_mntops} of
The @file{mntent.h} file defines a number of macros with string values
which correspond to some of the options understood by the kernel. There
might be many more options which are possible so it makes not much sense
might be many more options which are possible so it doesn't make much sense
to rely on these macros but to be consistent here is the list:
@vtable @code
@ -539,7 +539,7 @@ end of file reached,
@comment mntent.h
@comment BSD
@deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
The @code{addmntent} function allows to add a new entry to the file
The @code{addmntent} function allows adding a new entry to the file
previously opened with @code{setmntent}. The new entries are always
appended. I.e., even if the position of the file descriptor is not at
the end of the file this function does not overwrite an existing entry

26
manual/users.texi
View File

@ -1071,7 +1071,7 @@ the user accounting database.
All the @code{get*} functions mentioned before store the information
they return in a static buffer. This can be a problem in multi-threaded
programs since the data return for the request is overwritten be the
programs since the data returned for the request is overwritten by the
return value data in another thread. Therefore the GNU C Library
provides as extensions three more functions which return the data in a
user-provided buffer.
@ -1853,16 +1853,16 @@ group of users with a certain machine. On the other hand grouping of
host names is not supported so far.
In Sun Microsystems SunOS appeared a new kind of database, the netgroup
database. It allows to group hosts, users, and domain freely, giving
them individual names. More concrete: a netgroup is a list of triples
consisting of a host name, a user name, and a domain name, where any of
the entries can be a wildcard entry, matching all inputs. A last
database. It allows grouping hosts, users, and domains freely, giving
them individual names. To be more concrete, a netgroup is a list of triples
consisting of a host name, a user name, and a domain name where any of
the entries can be a wildcard entry matching all inputs. A last
possibility is that names of other netgroups can also be given in the
list specifying a netgroup. So one can construct arbitrary hierarchies
without loops.
Sun's implementation allows netgroups only for the @code{nis} or
@code{nisplus} service @pxref{Services in the NSS configuration}. The
@code{nisplus} service, @pxref{Services in the NSS configuration}. The
implementation in the GNU C library has no such restriction. An entry
in either of the input services must have the following form:
@ -1873,7 +1873,7 @@ in either of the input services must have the following form:
Any of the fields in the triple can be empty which means anything
matches. While describing the functions we will see that the opposite
case is useful as well. I.e., there may be entries which will not
match any input. For entries like a name consisting of the single
match any input. For entries like this, a name consisting of the single
character @code{-} shall be used.
@node Lookup Netgroup
@ -1889,10 +1889,10 @@ These functions are declared in @file{netdb.h}.
@comment BSD
@deftypefun int setnetgrent (const char *@var{netgroup})
A call to this function initializes the internal state of the library to
allow following calls of the @code{getnetgrent} iterate over all entries
allow following calls of the @code{getnetgrent} to iterate over all entries
in the netgroup with name @var{netgroup}.
When the call is successful (i.e., when a netgroup with this name exist)
When the call is successful (i.e., when a netgroup with this name exists)
the return value is @code{1}. When the return value is @code{0} no
netgroup of this name is known or some other error occurred.
@end deftypefun
@ -1914,11 +1914,11 @@ the @code{innetgr} function and parts of the implementation of the
@comment BSD
@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
This function returns the next unprocessed entry of the currently
selected netgroup. The string pointers, which addresses are passed in
selected netgroup. The string pointers, in which addresses are passed in
the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
after a successful call pointers to appropriate strings. If the string
in the next entry is empty the pointer has the value @code{NULL}.
The returned string pointers are only valid unless no of the netgroup
The returned string pointers are only valid if none of the netgroup
related functions are called.
The return value is @code{1} if the next entry was successfully read. A
@ -1946,7 +1946,7 @@ SunOS libc does not provide this function.
@comment netdb.h
@comment BSD
@deftypefun void endnetgrent (void)
This function free all buffers which were allocated to process the last
This function frees all buffers which were allocated to process the last
selected netgroup. As a result all string pointers returned by calls
to @code{getnetgrent} are invalid afterwards.
@end deftypefun
@ -1975,7 +1975,7 @@ to the other @code{set}/@code{get}/@code{endnetgrent} functions.
@end enumerate
Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
@code{NULL} which means any value is excepted in this position. This is
@code{NULL} which means any value is accepted in this position. This is
also true for the name @code{-} which should not match any other string
otherwise.