lib/glibc
1
0
Fork 0
mirror of https://sourceware.org/git/glibc.git synced 2025-09-08 13:52:10 +03:00
Code 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
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> 1999-08-25 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/i386/fpu/bits/mathinline.h (__finite): Mark constant as * 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 @comment GNU
@deftypevar {const char *} argp_program_bug_address @deftypevar {const char *} argp_program_bug_address
If defined or set by the user program to a non-zero value, 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 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 the standard output for the @samp{--help} option, embedded in a sentence
that says something like @samp{Report bugs to @var{address}.}. 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 this parser; it is only used to print the @samp{Usage:} message. If it
contains newlines, the strings separated by them are considered contains newlines, the strings separated by them are considered
alternative usage patterns, and printed on separate lines (lines after 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 @item const char *doc
If non-zero, a string containing extra text to be printed before and 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 unistd.h
@comment POSIX.1 @comment POSIX.1
@item _SC_SHARED_MEMORY_OBJECTS @item _SC_SHARED_MEMORY_OBJECTS
Inquire about the parameter corresponding to Inquire about the parameter corresponding to@*
@code{_POSIX_SHARED_MEMORY_OBJECTS}. @code{_POSIX_SHARED_MEMORY_OBJECTS}.
@comment unistd.h @comment unistd.h
@@ -580,7 +580,7 @@ Inquire about the parameter corresponding to @code{_POSIX_THREADS}.
@comment unistd.h @comment unistd.h
@comment POSIX.1 @comment POSIX.1
@item _SC_THREAD_SAFE_FUNCTIONS @item _SC_THREAD_SAFE_FUNCTIONS
Inquire about the parameter corresponding to Inquire about the parameter corresponding to@*
@code{_POSIX_THREAD_SAFE_FUNCTIONS}. @code{_POSIX_THREAD_SAFE_FUNCTIONS}.
@comment unistd.h @comment unistd.h
@@ -627,13 +627,13 @@ Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}.
@comment unistd.h @comment unistd.h
@comment POSIX.1 @comment POSIX.1
@item _SC_THREAD_ATTR_STACKADDR @item _SC_THREAD_ATTR_STACKADDR
Inquire about the parameter corresponding to Inquire about the parameter corresponding to@*a
@code{_POSIX_THREAD_ATTR_STACKADDR}. @code{_POSIX_THREAD_ATTR_STACKADDR}.
@comment unistd.h @comment unistd.h
@comment POSIX.1 @comment POSIX.1
@item _SC_THREAD_ATTR_STACKSIZE @item _SC_THREAD_ATTR_STACKSIZE
Inquire about the parameter corresponding to Inquire about the parameter corresponding to@*
@code{_POSIX_THREAD_ATTR_STACKSIZE}. @code{_POSIX_THREAD_ATTR_STACKSIZE}.
@comment unistd.h @comment unistd.h
@@ -760,27 +760,27 @@ Inquire about the virtual memory page size of the machine.
@comment unistd.h @comment unistd.h
@comment GNU @comment GNU
@item _SC_NPROCESSORS_CONF @item _SC_NPROCESSORS_CONF
Inquire about number of configured processors. Inquire about the number of configured processors.
@comment unistd.h @comment unistd.h
@comment GNU @comment GNU
@item _SC_NPROCESSORS_ONLN @item _SC_NPROCESSORS_ONLN
Inquire about number of processors online. Inquire about the number of processors online.
@comment unistd.h @comment unistd.h
@comment GNU @comment GNU
@item _SC_PHYS_PAGES @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 unistd.h
@comment GNU @comment GNU
@item _SC_AVPHYS_PAGES @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 unistd.h
@comment GNU @comment GNU
@item _SC_ATEXIT_MAX @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}. functions for @code{atexit}; @pxref{Cleanups on Exit}.
@comment unistd.h @comment unistd.h
@@ -831,41 +831,41 @@ Inquire about the parameter corresponding to @code{_XOPEN_XPG4}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_CHAR_BIT @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 unistd.h
@comment X/Open @comment X/Open
@item _SC_CHAR_MAX @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}. @code{char}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_CHAR_MIN @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}. @code{char}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_INT_MAX @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}. @code{int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_INT_MIN @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}. @code{int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_LONG_BIT @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 unistd.h
@comment X/Open @comment X/Open
@item _SC_WORD_BIT @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 unistd.h
@comment X/Open @comment X/Open
@@ -876,61 +876,61 @@ character value.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_NZERO @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. the process execution.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item SC_SSIZE_MAX @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}. @code{ssize_t}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_SCHAR_MAX @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}. @code{signed char}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_SCHAR_MIN @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}. @code{signed char}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_SHRT_MAX @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}. @code{short int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_SHRT_MIN @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}. @code{short int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_UCHAR_MAX @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}. @code{unsigned char}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_UINT_MAX @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}. @code{unsigned int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_ULONG_MAX @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}. @code{unsigned long int}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_USHRT_MAX @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}. @code{unsigned short int}.
@comment unistd.h @comment unistd.h
@@ -956,12 +956,12 @@ Inquire about the parameter corresponding to @code{NL_NMAX}.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@item _SC_NL_SETMAX @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 unistd.h
@comment X/Open @comment X/Open
@item _SC_NL_TEXTMAX @item _SC_NL_TEXTMAX
Inquire about the parameter corresponding to @code{NL_TEXTMAX}. Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
@end table @end table
@node Examples of Sysconf @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 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 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 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 limits.h
@comment POSIX.1 @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 POSIX defines certain system-specific options in the system calls for
operating on files. Some systems support these options and others do operating on files. Some systems support these options and others do
not. Since these options are provided in the kernel, not in the 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 features is supported; it depends on the system you are using. They can
also vary between file systems on a single machine. 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 @itemize @bullet
@item @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}. Richard Stallman, @w{David J.} MacKenzie, and @w{Roland McGrath}.
@item @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 configuring
@cindex compiling @cindex compiling
GNU Libc can be compiled in the source directory but we strongly advise to 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 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 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 @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 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 @end smallexample
Please note that even if you're building in a separate build directory, 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. directory, especially some files in the manual subdirectory.
@noindent @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 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 tells configure to use all the add-on bundles it finds in the source
directory. Since important functionality is provided in add-ons, you 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 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 the environment when running @code{configure}. @var{CC} selects the C
compiler that will be used, and @var{CFLAGS} sets optimization options compiler that will be used, and @var{CFLAGS} sets optimization options
for the compiler. 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 @table @samp
@item --prefix=@var{directory} @item --prefix=@var{directory}
@@ -91,13 +91,13 @@ Install machine-independent data files in subdirectories of
@item --exec-prefix=@var{directory} @item --exec-prefix=@var{directory}
Install the library and other machine-dependent files in subdirectories Install the library and other machine-dependent files in subdirectories
of @file{@var{directory}}. The default is to the @samp{--prefix} 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} @item --with-headers=@var{directory}
Look for kernel header files in @var{directory}, not Look for kernel header files in @var{directory}, not
@file{/usr/include}. Glibc needs information from the kernel's private @file{/usr/include}. Glibc needs information from the kernel's private
header files. It will normally look in @file{/usr/include} for them, 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 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 @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}. @file{/usr/include}.
@item --enable-add-ons[=@var{list}] @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 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 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 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 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 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 the default binutils on your system cannot deal with all the constructs
in the GNU C library. (@code{configure} will detect the problem and in the GNU C library. In that case, @code{configure} will detect the problem and
suppress these constructs, so the library will still be usable, but suppress these constructs, so that the library will still be usable, but
functionality may be lost---for example, you can not build a shared libc functionality may be lost---for example, you can't build a shared libc
with old binutils.) with old binutils.
@item --without-fp @item --without-fp
Use this option if your computer lacks hardware floating-point support 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. @c days, but we recommend you build them in case you need them.
@item --disable-shared @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. shared libraries; you need ELF support and (currently) the GNU linker.
@item --disable-profile @item --disable-profile
@@ -148,7 +148,7 @@ you won't be able to trace bugs through the C library.
@item --disable-versioning @item --disable-versioning
Don't compile the shared libraries with symbol version information. 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. binaries, so it's not recommended.
@item --enable-static-nss @item --enable-static-nss
@@ -159,22 +159,22 @@ reconfigured to use a different name database.
@item --build=@var{build-system} @item --build=@var{build-system}
@itemx --host=@var{host-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} @var{build-system} is different from @var{host-system}, @code{configure}
will prepare to cross-compile glibc from @var{build-system} to be used 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} 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 option too, and you may have to override @var{configure}'s selection of
the compiler and/or binutils. the compiler and/or binutils.
If you give just @samp{--host}, configure will prepare for a native If you only specify @samp{--host}, configure will prepare for a native
compile but use what you say instead of guessing what your system is. 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 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 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 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 just @samp{--host=i386-linux} and add the appropriate compiler flags
(@samp{-mcpu=i386} will do the trick) to @var{CFLAGS}. (@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 @end table
To build the library and related programs, type @code{make}. This will 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 @noindent
You can change the @samp{4} to some other number as appropriate for You can change the @samp{4} to some other number as appropriate for
your system. Instead of changing the @file{Makefile}, you could give 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 @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 directory, you must use the latter approach since in this case no
new @file{Makefile} is generated which you can change. new @file{Makefile} is generated for you to change.
To build and run some test programs which exercise some of the library To build and run test programs which exercise some of the library
facilities, type @code{make check}. This should complete successfully; facilities, type @code{make check}. If it does not complete
if it doesn't, do not use the built library, and report a bug. successfully, do not use the built library, and report a bug after
@xref{Reporting Bugs}, for how to do that. Note that some of the tests verifying that the problem is not already known. @xref{Reporting Bugs},
assume they are not being run by @code{root}. We recommend you compile for instructions on reporting bugs. Note that some of the tests assume
and test glibc as an unprivileged user. 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 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. @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 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, manual, type @code{make install}. This will build things if necessary,
before installing them. Don't rely on that; compile everything first. before installing them. However, you should still compile everything first.
If you are installing glibc as your primary C library, we recommend you 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. shut the system down to single-user mode first, and reboot afterward.
This minimizes the risk of breaking things when the library changes out This minimizes the risk of breaking things when the library changes out
from underneath. from underneath.
@@ -233,8 +234,8 @@ from underneath.
If you are upgrading from a previous installation of glibc 2.0 or 2.1, 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 @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 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 @file{/usr/include} directory before running @samp{make install},
install}, or you will end up with a mixture of header files from both 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 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 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 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 GNU @code{make} 3.75
You need the latest version of GNU @code{make}. Modifying the GNU C 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 you port GNU @code{make} instead. @strong{Really.} We
recommend version GNU @code{make} version 3.75 or 3.77. All earlier 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 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 If you are interested in doing a port, please contact the glibc
maintainers by sending electronic mail to @email{bug-glibc@@gnu.org}. 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}, Valid cases of @samp{i@var{x}86} include @samp{i386}, @samp{i486},
@samp{i586}, or @samp{i686}. All of those configurations produce a @samp{i586}, and @samp{i686}. All of those configurations produce a
library that can run on this processor and newer processors. The GCC 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 compiler by default generates code that's optimized for the machine it's
configured for and will use the instructions available on that machine. 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 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 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 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 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 @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 fixed. If you don't, no one will ever know about them and they will
remain unfixed for all eternity, if not longer. remain unfixed for all eternity, if not longer.
It is a good idea to check first that the problem was not reported It is a good idea to verify that the problem has not already been
before. Bugs are documented in two places: The file @file{BUGS} 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 describes a number of well known bugs and the bug tracking system has a
WWW interface at WWW interface at
@url{http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl}. The WWW @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 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 errors or omissions in this manual, please report them to the Internet
address @email{bug-glibc-manual@@gnu.org}. If you refer to specific address @email{bug-glibc-manual@@gnu.org}. If you refer to specific
sections when reporting on the manual, please include the section names sections of the manual, please include the section names for easier
for easier identification. identification.

4
manual/job.texi
View File

@@ -1298,7 +1298,7 @@ process.
@comment Unix98 @comment Unix98
@deftypefun pid_t tcgetsid (int @var{fildes}) @deftypefun pid_t tcgetsid (int @var{fildes})
This function is used to obtain the process group ID of the session 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 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} return value is @code{(pid_t) -1} and the global variable @var{errno}
is set to the following value: is set to the following value:
@@ -1308,6 +1308,6 @@ The @var{filedes} argument is not a valid file descriptor.
@item ENOTTY @item ENOTTY
The calling process does not have a controlling terminal, or the file 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 table
@end deftypefun @end deftypefun

104
manual/lang.texi
View File

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

299
manual/llio.texi
View File

@@ -97,8 +97,8 @@ for this function:
@table @code @table @code
@item EACCES @item EACCES
The file exists but is not readable/writable as requested by the @var{flags} The file exists but is not readable/writeable as requested by the @var{flags}
argument, the file does not exist and the directory is unwritable so argument, the file does not exist and the directory is unwriteable so
it cannot be created. it cannot be created.
@item EEXIST @item EEXIST
@@ -142,19 +142,19 @@ or @code{O_CREAT} is set and the file does not already exist.
@c !!! umask @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 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
descriptor opened in the large file mode which enables the file handling 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 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 @math{-2^63} to @math{2^63}. This happens transparently for the user
since all of the lowlevel file handling functions are equally replaced. 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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{open} is 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 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 @c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{open} function is the underlying primitive for the @code{fopen} 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}]) @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 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 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. 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 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}) open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
@end smallexample @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 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
descriptor opened in the large file mode which enables the file handling 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 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}) @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 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 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. 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 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. any unread data is discarded.
@end itemize @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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{close} is descriptors, semaphores or whatever) at the time @code{close} 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{close} should be until the program ends. To avoid this, calls to @code{close} should be
protected using cancelation handlers. protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop @c ref pthread_cleanup_push / pthread_cleanup_pop
The normal return value from @code{close} is @math{0}; a value of @math{-1} 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. Please note that there is @emph{no} separate @code{close64} function.
This is not necessary since this function does not determine nor depend 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} 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. this situation.
@end deftypefun @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}) @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 The @code{read} function reads up to @var{size} bytes from the file
with descriptor @var{filedes}, storing the results in the @var{buffer}. with descriptor @var{filedes}, storing the results in the @var{buffer}.
(This is not necessarily a character string and there is no terminating (This is not necessarily a character string, and no terminating null
null character added.) character is added.)
@cindex end-of-file, on a file descriptor @cindex end-of-file, on a file descriptor
The return value is the number of bytes actually read. This might be 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 @code{EIO} also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by controlling terminal, and the normal action of stopping the process by
sending it a @code{SIGTTIN} signal isn't working. This might happen if 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, orphaned. @xref{Job Control}, for more information about job control,
and @ref{Signal Handling}, for information about signals. and @ref{Signal Handling}, for information about signals.
@end table @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 Please note that there is no function named @code{read64}. This is not
necessary since this function does not directly modify or handle the necessary since this function does not directly modify or handle the
possibly wide file offset. Since the kernel handles this state 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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{read} is descriptors, semaphores or whatever) at the time @code{read} 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{read} should be until the program ends. To avoid this, calls to @code{read} should be
protected using cancelation handlers. protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop @c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{read} function is the underlying primitive for all of the 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 @comment Unix98
@deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset}) @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 The @code{pread} function is similar to the @code{read} function. The
first three arguments are identical and also the return values and error first three arguments are identical, and the return values and error
codes correspond. codes also correspond.
The difference is the fourth argument and its handling. The data block The difference is the fourth argument and its handling. The data block
is not read from the current position of the file descriptor is not read from the current position of the file descriptor
@code{filedes}. Instead the data is read from the file starting at @code{filedes}. Instead the data is read from the file starting at
position @var{offset}. The position of the file descriptor itself is 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 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{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. @math{2^63} bytes in length.
The return value of @code{pread} describes the number of bytes read. 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 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 @table @code
@item EINVAL @item EINVAL
The value given for @var{offset} is negative and therefore illegal. 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}) @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 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 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 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 file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode. errors with a descriptor in small file mode.
When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a 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 32 bit machine this function is actually available under the name
@code{pread} and so transparently replaces the 32 bits interface. @code{pread} and so transparently replaces the 32 bit interface.
@end deftypefun @end deftypefun
@cindex writing to a file descriptor @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 @item EAGAIN
Normally, @code{write} blocks until the write operation is complete. Normally, @code{write} blocks until the write operation is complete.
But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control 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 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 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 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 @item EINTR
The @code{write} operation was interrupted by a signal while it was 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 @code{write} to return @code{EINTR}; it may instead result in a
successful @code{write} which writes fewer bytes than requested. successful @code{write} which writes fewer bytes than requested.
@xref{Interrupted Primitives}. @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 possibly wide file offset. Since the kernel handles this state
internally the @code{write} function can be used for all cases. 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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{write} is descriptors, semaphores or whatever) at the time @code{write} 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{write} should be until the program ends. To avoid this, calls to @code{write} should be
protected using cancelation handlers. protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop @c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{write} function is the underlying primitive for all of the 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 @comment Unix98
@deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset}) @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 The @code{pwrite} function is similar to the @code{write} function. The
first three arguments are identical and also the return values and error first three arguments are identical, and the return values and error codes
codes correspond. also correspond.
The difference is the fourth argument and its handling. The data block The difference is the fourth argument and its handling. The data block
is not written to the current position of the file descriptor is not written to the current position of the file descriptor
@code{filedes}. Instead the data is written to the file starting at @code{filedes}. Instead the data is written to the file starting at
position @var{offset}. The position of the file descriptor itself is 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 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{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. @math{2^63} bytes in length.
The return value of @code{pwrite} describes the number of written bytes. 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 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 @table @code
@item EINVAL @item EINVAL
The value given for @var{offset} is negative and therefore illegal. The value given for @var{offset} is negative and therefore illegal.
@item ESPIPE @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. this device does not allow positioning of the file pointer.
@end table @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}) @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 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 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 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 file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to otherwise the large offsets possible with @code{off64_t} will lead to
errors with a descriptor in small file mode. errors with a descriptor in small file mode.
When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a 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 32 bit machine this function is actually available under the name
@code{pwrite} and so transparently replaces the 32 bits interface. @code{pwrite} and so transparently replaces the 32 bit interface.
@end deftypefun @end deftypefun
@@ -616,8 +618,8 @@ The @code{lseek} function is used to change the file position of the
file with descriptor @var{filedes}. file with descriptor @var{filedes}.
The @var{whence} argument specifies how the @var{offset} should be 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 interpreted, in the same way as for the @code{fseek} function, and it must
one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
@code{SEEK_END}. @code{SEEK_END}.
@table @code @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 @code{off_t} has 64 bits which makes it possible to handle files up to
@math{2^63} bytes in length. @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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{lseek} is 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 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 @c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{lseek} function is the underlying primitive for the 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}) @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 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 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 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 file descriptor @code{filedes} must be opened using @code{open64} since
otherwise the large offsets possible with @code{off64_t} will lead to 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 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 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 @end deftypefun
You can have multiple descriptors for the same file if you open the file 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 @comment Unix98
@deftp {Data Type} off64_t @deftp {Data Type} off64_t
This type is used similar to @code{off_t}. The difference is that even 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 @code{off64_t} has 64 bits and so is able to address files up to
@math{2^63} bytes in length. @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 @code{fopen} function (@pxref{Opening Streams}), except that
the @samp{b} option is not permitted; this is because GNU makes no the @samp{b} option is not permitted; this is because GNU makes no
distinction between text and binary files. Also, @code{"w"} and 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. 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 You must make sure that the @var{opentype} argument matches the actual
mode of the open file descriptor. mode of the open file descriptor.
@@ -1027,7 +1029,7 @@ Modes}.
@cindex scatter-gather @cindex scatter-gather
Some applications may need to read or write data to multiple buffers, 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 with multiple calls to @code{read} and @code{write}, it is inefficent
because there is overhead associated with each kernel call. 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 ``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. be accessed just like an array in the program.
This is more efficent than @code{read} or @code{write}, as only regions This is more efficent than @code{read} or @code{write}, as only the regions
of the file a program actually accesses are loaded. Accesses to 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 not-yet-loaded parts of the mmapped region are handled in the same way as
swapped out pages. 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} + @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
@var{length}). @var{length} should be the length of the mapping. @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 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. an even number of pages, it will be rounded up.
It returns @math{0} for success and @math{-1} for an error. It returns @math{0} for success and @math{-1} for an error.
@@ -1257,7 +1259,7 @@ One error is possible:
@table @code @table @code
@item EINVAL @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. aligned.
@end table @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 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 area. @var{address} and @var{length} must cover a region entirely mapped
in the same @code{mmap} statement. A new mapping with the same in the same @code{mmap} statement. A new mapping with the same
characteristics will be returned, but a with the length @var{new_length} characteristics will be returned with the length @var{new_length}.
instead.
One option is possible, @code{MREMAP_MAYMOVE}. If it is given in One option is possible, @code{MREMAP_MAYMOVE}. If it is given in
@var{flags}, the system may remove the existing mapping and create a new @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 The address of the resulting mapping is returned, or @math{-1}. Possible
error codes include: 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 @table @code
@item EFAULT @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}. process's resource limit for locked pages. @xref{Limits on Resources}.
@item ENOMEM @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 available to extend it. Also, this error will occur if
@code{MREMAP_MAYMOVE} is not given and the extension would collide with @code{MREMAP_MAYMOVE} is not given and the extension would collide with
another mapped region. another mapped region.
@@ -1348,6 +1347,9 @@ another mapped region.
@end table @end table
@end deftypefun @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 Not all file descriptors may be mapped. Sockets, pipes, and most devices
only allow sequential access and do not fit into the mapping abstraction. 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 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 @section Synchronizing I/O operations
@cindex synchronizing @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 executed synchronously. I.e., even if a @code{write} system call
returns this does not mean the data is actually written to the media, returns this does not mean the data is actually written to the media,
e.g., the disk. e.g., the disk.
In situations where synchronization points are necessary the user can In situations where synchronization points are necessary,you can use
use special functions which ensure that all operations finished before special functions which ensure that all operations finish before
they return. they return.
@comment unistd.h @comment unistd.h
@comment X/Open @comment X/Open
@deftypefun int sync (void) @deftypefun int sync (void)
A call to this function will not return as long as there is data which 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 be written and so an overall consistent system can be achieved (if no
other process in parallel writes data). 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. The return value is zero to indicate no error.
@end deftypefun @end deftypefun
More often it is wanted that not all data in the system is committed. Programs more often want to ensure that data written to a given file is
Programs want to ensure that data written to a given file are all committed, rather than all data in the system. For this, @code{sync} is overkill.
committed and in this situation @code{sync} is overkill.
@comment unistd.h @comment unistd.h
@comment POSIX @comment POSIX
@@ -1569,12 +1571,12 @@ finished.
A prototype for @code{fsync} can be found in @file{unistd.h}. 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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{fsync} is descriptors, semaphores or whatever) at the time @code{fsync} 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{fsync} should be until the program ends. To avoid this, calls to @code{fsync} should be
protected using cancelation handlers. protected using cancellation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop @c ref pthread_cleanup_push / pthread_cleanup_pop
The return value of the function is zero if no error occured. Otherwise 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 unistd.h
@comment POSIX @comment POSIX
@deftypefun int fdatasync (int @var{fildes}) @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 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 Not all systems implement the @code{fdatasync} operation. On systems
missing this functionality @code{fdatasync} is emulated by a call to 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 @section Perform I/O Operations in Parallel
The POSIX.1b standard defines a new set of I/O operations which can 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 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 then immediately resume normal work while the I/O operations are
executed in parallel. The functionality is available if the executed in parallel. This functionality is available if the
@file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}. @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
These functions are part of the library with realtime functions named 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}. with the thread library @file{libpthread} in addition to @file{librt}.
All AIO operations operate on files which were opened previously. There 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 asynchronous I/O operations are controlled using a data structure named
@code{struct aiocb} (@dfn{AIO control block}). It is defined in @code{struct aiocb} (@dfn{AIO control block}). It is defined in
@file{aio.h} as follows. @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} @deftp {Data Type} {struct aiocb}
The POSIX.1b standard mandates that the @code{struct aiocb} structure The POSIX.1b standard mandates that the @code{struct aiocb} structure
contains at least the members described in the following table. There 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. depending on these elements is not portable and is highly deprecated.
@table @code @table @code
@item int aio_fildes @item int aio_fildes
This element specifies the file descriptor which is used for the This element specifies the file descriptor which is used for the
operation. It must be a legal descriptor since otherwise the operation 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. 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 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 @item int aio_lio_opcode
This element is only used by the @code{lio_listio} and This element is only used by the @code{lio_listio} and
@code{lio_listio64} functions. Since these functions allow to start an @code{lio_listio64} functions. Since these functions allow an
arbitrary number of operations at once and since each operation can be 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 input or output (or nothing), the information must be stored in the
control block. The possible values are: control block. The possible values are:
@vtable @code @vtable @code
@@ -1720,13 +1722,13 @@ values must not be handled although the whole array is presented to the
@end table @end table
When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a 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. interface transparently replaces the @code{struct aiocb} definition.
@end deftp @end deftp
For use with the AIO functions defined in the LFS there is a similar type 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 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. all member names are the same.
@comment aio.h @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. like terminals where an @code{lseek} call would lead to an error.
@item off64_t aio_offset @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 or output) is performed. Since the operation are carried in arbitrary
order and more than one operation for one file descriptor can be order and more than one operation for one file descriptor can be
started, one cannot expect a current read/write position of the file 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 @item int aio_reqprio
If for the platform @code{_POSIX_PRIORITIZED_IO} and 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 processed based on the current scheduling priority. The
@code{aio_reqprio} element can then be used to lower the priority of the @code{aio_reqprio} element can then be used to lower the priority of the
AIO operation. AIO operation.
@@ -1766,23 +1768,23 @@ AIO operation.
@item struct sigevent aio_sigevent @item struct sigevent aio_sigevent
This element specifies how the calling process is notified once the This element specifies how the calling process is notified once the
operation terminates. If the @code{sigev_notify} element is operation terminates. If the @code{sigev_notify} element is
@code{SIGEV_NONE} no notification is send. If it is @code{SIGEV_SIGNAL} @code{SIGEV_NONE} no notification is sent. If it is @code{SIGEV_SIGNAL}
the signal determined by @code{sigev_signo} is send. Otherwise the signal determined by @code{sigev_signo} is sent. Otherwise
@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread @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}. @code{sigev_notify_function}.
@item int aio_lio_opcode @item int aio_lio_opcode
This element is only used by the @code{lio_listio} and This element is only used by the @code{lio_listio} and
@code{[lio_listio64} functions. Since these functions allow to start an @code{[lio_listio64} functions. Since these functions allow an
arbitrary number of operations at once and since each operation can be 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 input or output (or nothing), the information must be stored in the
control block. See the description of @code{struct aiocb} for a description control block. See the description of @code{struct aiocb} for a description
of the possible values. of the possible values.
@end table @end table
When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a 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. aiocb64} since the LFS replaces transparently the old interface.
@end deftp @end deftp
@@ -1790,7 +1792,7 @@ aiocb64} since the LFS replaces transparently the old interface.
* Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
* Status of AIO Operations:: Getting the Status of AIO Operations. * Status of AIO Operations:: Getting the Status of AIO Operations.
* Synchronizing AIO Operations:: Getting into a consistent state. * 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. * Configuration of AIO:: How to optimize the AIO implementation.
@end menu @end menu
@@ -1800,8 +1802,8 @@ aiocb64} since the LFS replaces transparently the old interface.
@comment aio.h @comment aio.h
@comment POSIX.1b @comment POSIX.1b
@deftypefun int aio_read (struct aiocb *@var{aiocbp}) @deftypefun int aio_read (struct aiocb *@var{aiocbp})
This function initiates an asynchronous read operation. The function This function initiates an asynchronous read operation. It
call immediately returns after the operation was enqueued or when an immediately returns after the operation was enqueued or when an
error was encountered. error was encountered.
The first @code{aiocbp->aio_nbytes} bytes of the file for which 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 The calling process is notified about the termination of the read
request according to the @code{aiocbp->aio_sigevent} value. 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 occurred that can be found before the process is enqueued. If such an
early error is found the function returns @math{-1} and sets early error is found, the function returns @math{-1} and sets
@code{errno} to one of the following values. @code{errno} to one of the following values:
@table @code @table @code
@item EAGAIN @item EAGAIN
@@ -1829,7 +1831,7 @@ limitations.
The @code{aio_read} function is not implemented. The @code{aio_read} function is not implemented.
@item EBADF @item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid. This condition 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. might also be signaled asynchronously.
@item EINVAL @item EINVAL
The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is 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. request and so this error might also be signaled asynchrously.
@end table @end table
In the case @code{aio_read} returns zero the current status of the If @code{aio_read} returns zero, the current status of the request
request can be queried using @code{aio_error} and @code{aio_return} can be queried using @code{aio_error} and @code{aio_return} functions.
functions. As long as the value returned by @code{aio_error} is As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
@code{EINPROGRESS} the operation has not yet completed. If the operation has not yet completed. If @code{aio_error} returns zero,
@code{aio_error} returns zero the operation successfully terminated, the operation successfully terminated, otherwise the value is to be
otherwise the value is to be interpreted as an error code. If the interpreted as an error code. If the function terminated, the result of
function terminated the result of the operation can be get using a call the operation can be obtained using a call to @code{aio_return}. The
to @code{aio_return}. The returned value is the same as an equivalent returned value is the same as an equivalent call to @code{read} would
call to @code{read} would have returned. Possible error codes returned have returned. Possible error codes returned by @code{aio_error} are:
by @code{aio_error} are:
@table @code @table @code
@item EBADF @item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid. The @code{aiocbp->aio_fildes} descriptor is not valid.
@item ECANCELED @item ECANCELED
The operation was canceled before the operation was finished The operation was cancelled before the operation was finished
(@pxref{Cancel AIO Operations}) (@pxref{Cancel AIO Operations})
@item EINVAL @item EINVAL
The @code{aiocbp->aio_offset} value is invalid. The @code{aiocbp->aio_offset} value is invalid.
@@ -1867,7 +1868,7 @@ replaces the normal implementation.
@comment Unix98 @comment Unix98
@deftypefun int aio_read64 (struct aiocb *@var{aiocbp}) @deftypefun int aio_read64 (struct aiocb *@var{aiocbp})
This function is similar to the @code{aio_read} function. The only 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 be opened in the large file mode. Internally @code{aio_read64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading, 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 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_read} and so transparently 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 @end deftypefun
To write data asynchronously to a file there exists an equivalent pair To write data asynchronously to a file there exists an equivalent pair
@@ -1936,7 +1937,7 @@ by @code{aio_error} are:
@item EBADF @item EBADF
The @code{aiocbp->aio_fildes} descriptor is not valid. The @code{aiocbp->aio_fildes} descriptor is not valid.
@item ECANCELED @item ECANCELED
The operation was canceled before the operation was finished The operation was cancelled before the operation was finished
(@pxref{Cancel AIO Operations}) (@pxref{Cancel AIO Operations})
@item EINVAL @item EINVAL
The @code{aiocbp->aio_offset} value is invalid. The @code{aiocbp->aio_offset} value is invalid.
@@ -1951,7 +1952,7 @@ replaces the normal implementation.
@comment Unix98 @comment Unix98
@deftypefun int aio_write64 (struct aiocb *@var{aiocbp}) @deftypefun int aio_write64 (struct aiocb *@var{aiocbp})
This function is similar to the @code{aio_write} function. The only 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 be opened in the large file mode. Internally @code{aio_write64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the writing, 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 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_write} and so transparently 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 @end deftypefun
Beside these functions with the more or less traditional interface Beside these functions with the more or less traditional interface
@@ -2055,7 +2056,7 @@ transparently replaces the normal implementation.
@comment Unix98 @comment Unix98
@deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig}) @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 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 be opened in the large file mode. Internally @code{lio_listio64} uses
functionality equivalent to @code{lseek64} (@pxref{File Position functionality equivalent to @code{lseek64} (@pxref{File Position
Primitive}) to position the file descriptor correctly for the reading or 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 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{lio_listio} and so 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. machines.
@end deftypefun @end deftypefun
@@ -2072,12 +2073,12 @@ machines.
@subsection Getting the Status of AIO Operations @subsection Getting the Status of AIO Operations
As already described in the documentation of the functions in the last 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 section, it must be possible to get information about the status of an I/O
request. When the operation is performed really asynchronous (as with request. When the operation is performed truly asynchronously (as with
@code{aio_read} and @code{aio_write} and with @code{aio_listio} when the @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 mode is @code{LIO_NOWAIT}) one sometimes needs to know whether a
specific request already terminated and if yes, what the result was.. specific request already terminated and if yes, what the result was.
The following two function allow to get this kind of information. The following two functions allow you to get this kind of information.
@comment aio.h @comment aio.h
@comment POSIX.1b @comment POSIX.1b
@@ -2109,7 +2110,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_error} and so 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. machines.
@end deftypefun @end deftypefun
@@ -2145,7 +2146,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_return} and so 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. machines.
@end deftypefun @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 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. 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 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 resources (mainly computation time). Instead POSIX.1b defines two
functions which will help with most kinds of consistency. 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 Calling this function forces all I/O operations operating queued at the
time of the function call operating on the file descriptor time of the function call operating on the file descriptor
@code{aiocbp->aio_fildes} into the synchronized I/O completion state @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 immediately but the notification through the method described in
@code{aiocbp->aio_sigevent} will happen only after all requests for this @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 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 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 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 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_fsync} and so 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. machines.
@end deftypefun @end deftypefun
@@ -2286,12 +2287,12 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_suspend} and so 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. machines.
@end deftypefun @end deftypefun
@node Cancel AIO Operations @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 When one or more requests are asynchronously processed it might be
useful in some situations to cancel a selected operation, e.g., if it 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 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. 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 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 implementation to decide whether it is possible to cancel the operation
or not. Therefore using this function is merely a hint. 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 function tries to cancel all outstanding requests which would process
the file descriptor @var{fildes} (i.e.,, whose @code{aio_fildes} member 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 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 about the termination of the request should take place. I.e., depending
on the @code{struct sigevent} object which controls this, nothing on the @code{struct sigevent} object which controls this, nothing
happens, a signal is sent or a thread is started. If the request cannot 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 a reference to this request as the parameter will return
@code{ECANCELED} and a call to @code{aio_return} will return @math{-1}. @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}. still @code{EINPROGRESS}.
The return value of the function is @code{AIO_CANCELED} if there were The return value of the function is @code{AIO_CANCELED} if there were
requests which haven't terminated and which successfully were canceled. requests which haven't terminated and which successfully were cancelled.
If there is one or more request left which couldn't be canceled the 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} 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 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 requests already terminated at the time @code{aio_cancel} is called the
return value is @code{AIO_ALLDONE}. return value is @code{AIO_ALLDONE}.
@@ -2360,7 +2361,7 @@ aiocb64}.
When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
function is available under the name @code{aio_cancel} and so 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. machines.
@end deftypefun @end deftypefun
@@ -2486,12 +2487,12 @@ Set process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}. @xref{Interrupt Input}.
@end table @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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{fcntl} is 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 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 @c ref pthread_cleanup_push / pthread_cleanup_pop
@end deftypefun @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 situation. For most calculations, the @code{float} functions are the
fastest. On the other hand, the @code{long double} functions have the fastest. On the other hand, the @code{long double} functions have the
highest precision. @code{double} is somewhere in between. It is 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 Not all machines have a distinct @code{long double} type; it may be the
same as @code{double}. same as @code{double}.
@@ -87,7 +87,7 @@ The natural logarithm of @code{2}.
@item M_LN10 @item M_LN10
The natural logarithm of @code{10}. The natural logarithm of @code{10}.
@item M_PI @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 @item M_PI_2
Pi divided by two. Pi divided by two.
@item M_PI_4 @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 @end vtable
These constants come from the Unix98 standard and were also available in 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 @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
defined. The default set of features includes these constants. defined. The default set of features includes these constants.
@xref{Feature Test Macros}. @xref{Feature Test Macros}.
@@ -294,7 +294,7 @@ pole.
@cindex inverse trigonometric functions @cindex inverse trigonometric functions
These are the usual arc sine, arc cosine and arc tangent 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. respectively.
@comment math.h @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 floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
to @code{floor (log2 (x))}, except it's probably faster. 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 would have if it were normalized. If @var{x} is infinity (positive or
negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero, negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
@code{logb} returns @math{@infinity{}}. It does not signal. @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}) @deftypefunx {long double} expm1l (long double @var{x})
These functions return a value equivalent to @code{exp (@var{x}) - 1}. 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 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. to subtraction of two numbers that are nearly equal.
@end deftypefun @end deftypefun
@@ -720,7 +720,7 @@ logarithm functions.
@deftypefunx {complex long double} cexpl (complex long double @var{z}) @deftypefunx {complex long double} cexpl (complex long double @var{z})
These functions return @code{e} (the base of natural These functions return @code{e} (the base of natural
logarithms) raised to the power of @var{z}. logarithms) raised to the power of @var{z}.
Mathematically this corresponds to the value Mathematically, this corresponds to the value
@ifinfo @ifinfo
@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))} @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 @comment ISO
@deftypefunx {complex long double} clogl (complex long double @var{z}) @deftypefunx {complex long double} clogl (complex long double @var{z})
These functions return the natural logarithm of @var{z}. These functions return the natural logarithm of @var{z}.
Mathematically this corresponds to the value Mathematically, this corresponds to the value
@ifinfo @ifinfo
@math{log (z) = log (cabs (z)) + I * carg (z)} @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 @comment GNU
@deftypefunx {complex long double} clog10l (complex long double @var{z}) @deftypefunx {complex long double} clog10l (complex long double @var{z})
These functions return the base 10 logarithm of the complex value 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 @ifinfo
@math{log (z) = log10 (cabs (z)) + I * carg (z)} @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 Bessel functions
@cindex gamma function @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. useful. Currently they only have real-valued versions.
@comment math.h @comment math.h
@@ -1052,7 +1052,7 @@ gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
@vindex signgam @vindex signgam
The sign of the gamma function is stored in the global variable 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 @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. negative.
To compute the real gamma function you can use the @code{tgamma} To compute the real gamma function you can use the @code{tgamma}
@@ -1062,7 +1062,7 @@ lgam = lgamma(x);
gam = signgam*exp(lgam); gam = signgam*exp(lgam);
@end smallexample @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 @code{lgamma} will raise the zero divide exception if evaluated at a
singularity. singularity.
@end deftypefun @end deftypefun
@@ -1078,7 +1078,7 @@ singularity.
@deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp}) @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 @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} 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 @end deftypefun
@comment math.h @comment math.h
@@ -1092,7 +1092,7 @@ instead of in the @var{signgam} global.
@deftypefunx {long double} gammal (long double @var{x}) @deftypefunx {long double} gammal (long double @var{x})
These functions exist for compatibility reasons. They are equivalent to These functions exist for compatibility reasons. They are equivalent to
@code{lgamma} etc. It is better to use @code{lgamma} since for one the @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. standardized in @w{ISO C 9x} while @code{gamma} is not.
@end deftypefun @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 different seed each time. For ordinary purposes, basing the seed on the
current time works well. 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 by specifying the same initial seed value for the random number
generator. There is no standard meaning for a particular seed value; generator. There is no standard meaning for a particular seed value;
the same seed, used in different C libraries or on different CPU types, 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. This function returns the next pseudo-random number in the sequence.
The value returned ranges from @code{0} to @code{RAND_MAX}. The value returned ranges from @code{0} to @code{RAND_MAX}.
@strong{Note:} Historically this function returned a @code{long @strong{Note:} Historically this function returned a @code{long int}
int} value. On 64bit systems @code{long int} would have been larger value. On 64-bit systems @code{long int} would have been larger than
than programs expected, so @code{random} is now defined to return programs expected, so @code{random} is now defined to return exactly 32
exactly 32 bits. bits.
@end deftypefun @end deftypefun
@comment stdlib.h @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 choose among a collection of functions which return the random bits
in different forms. 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 the random number generator which is shared among several functions and
by all threads of the process. The second group of functions require by all threads of the process. The second requires the user to handle
the user to handle the state. the state.
All functions have in common that they use the same congruential All functions have in common that they use the same congruential
formula with the same constants. The formula is formula with the same constants. The formula is
@@ -1389,7 +1389,7 @@ Y = (a * X + c) mod m
@noindent @noindent
where @var{X} is the state of the generator at the beginning and 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 @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 @smallexample
a = 0x5DEECE66D = 25214903917 a = 0x5DEECE66D = 25214903917
@@ -1398,7 +1398,7 @@ c = 0xb = 11
@noindent @noindent
but they can also be changed by the user. @code{m} is of course 2^48 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 @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 to @code{1.0} (exclusive). The random bits are determined by the global
state of the random number generator in the C library. 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 mantissa this means 4 bits are not initialized by the random number
generator. These are (of course) chosen to be the least significant generator. These are (of course) chosen to be the least significant
bits and they are initialized to @code{0}. bits and they are initialized to @code{0}.
@@ -1418,20 +1418,20 @@ bits and they are initialized to @code{0}.
@comment SVID @comment SVID
@deftypefun double erand48 (unsigned short int @var{xsubi}[3]) @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
This function returns a @code{double} value in the range of @code{0.0} 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. an array describing the state of the random number generator.
This function can be called subsequently since it updates the array to This function can be called subsequently since it updates the array to
guarantee random numbers. The array should have been initialized before guarantee random numbers. The array should have been initialized before
using to get reproducible results. initial use to obtain reproducible results.
@end deftypefun @end deftypefun
@comment stdlib.h @comment stdlib.h
@comment SVID @comment SVID
@deftypefun {long int} lrand48 (void) @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 @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 The random bits are determined by the global state of the random number
generator in the C library. generator in the C library.
@end deftypefun @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 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. is determined by the array provided as the parameter to the function.
The numbers in the array are afterwards updated so that subsequent calls The numbers in the array are updated afterwards so that subsequent calls
to this function yield to different results (as it is expected by a to this function yield different results (as is expected of a random
random number generator). The array should have been initialized before number generator). The array should have been initialized before the
the first call to get reproducible results. first call to obtain reproducible results.
@end deftypefun @end deftypefun
@comment stdlib.h @comment stdlib.h
@@ -1468,33 +1468,33 @@ requirements are necessary.
@end deftypefun @end deftypefun
The internal state of the random number generator can be initialized in 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. information provided.
@comment stdlib.h @comment stdlib.h
@comment SVID @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 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 significant 32 bits of the @var{seedval} parameter. The lower 16 bits
are initialized to the value @code{0x330E}. Even if the @code{long 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 Owing to this limitation, initialization of the state of this
function of not very useful. But it makes it easy to use a construct function is not very useful. But it makes it easy to use a construct
like @code{srand48 (time (0))}. like @code{srand48 (time (0))}.
A side-effect of this function is that the values @code{a} and @code{c} 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, from the internal state, which are used in the congruential formula,
are reset to the default values given above. This is of importance once 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 @end deftypefun
@comment stdlib.h @comment stdlib.h
@comment SVID @comment SVID
@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
The @code{seed48} function initializes all 48 bits of the state of the 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{seed16v}. Here the lower 16 bits of the first element of
@var{see16v} initialize the least significant 16 bits of the internal @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 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 value returned by @code{seed48} is a pointer to an array containing
the values of the internal state before the change. This might be the values of the internal state before the change. This might be
useful to restart the random number generator at a certain state. 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 As for @code{srand48}, the values @code{a} and @code{c} from the
congruential formula are reset to the default values. congruential formula are reset to the default values.
@end deftypefun @end deftypefun
There is one more function to initialize the random number generator There is one more function to initialize the random number generator
which allows to specify even more information by allowing to change the which enables you to specify even more information by allowing you to
parameters in the congruential formula. change the parameters in the congruential formula.
@comment stdlib.h @comment stdlib.h
@comment SVID @comment SVID
@@ -1527,9 +1527,9 @@ congruential formula.
From the seven elements in the array @var{param} the least significant 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]} 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 @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}. @code{c}.
@end deftypefun @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 state if all threads use the functions which take a pointer to an array
containing the state. The random numbers are computed following the containing the state. The random numbers are computed following the
same loop but if the state in the array is different all threads will 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}. 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 This type should be regarded as opaque and not manipulated directly.
directly.
@comment stdlib.h @comment stdlib.h
@comment GNU @comment GNU
@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
This function is equivalent to the @code{drand48} function with the This function is equivalent to the @code{drand48} function with the
difference it does not modify the global random number generator difference that it does not modify the global random number generator
parameters but instead the parameters is the buffer supplied by the parameters but instead the parameters in the buffer supplied through the
buffer through the pointer @var{buffer}. The random number is return in pointer @var{buffer}. The random number is returned in the variable
the variable pointed to by @var{result}. 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 If the value is less than @code{0} an error occurred and @var{errno} is
set to indicate the problem. set to indicate the problem.
@@ -1570,14 +1569,14 @@ programs.
@comment stdlib.h @comment stdlib.h
@comment GNU @comment GNU
@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) @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 The @code{erand48_r} function works like @code{erand48}, but in addition
an argument @var{buffer} which describes the random number generator. it takes an argument @var{buffer} which describes the random number
The state of the random number generator is taken from the @code{xsubi} generator. The state of the random number generator is taken from the
array, the parameters for the congruential formula from the global @code{xsubi} array, the parameters for the congruential formula from the
random number generator data. The random number is return in the global random number generator data. The random number is returned in
variable pointed to by @var{result}. 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 This function is a GNU extension and should not be used in portable
programs. programs.
@@ -1586,9 +1585,9 @@ programs.
@comment stdlib.h @comment stdlib.h
@comment GNU @comment GNU
@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) @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 This function is similar to @code{lrand48}, but in addition it takes a
buffer describing the state of the random number generator as a pointer to a buffer describing the state of the random number generator
parameter just like @code{drand48}. just like @code{drand48}.
If the return value of the function is non-negative the variable pointed If the return value of the function is non-negative the variable pointed
to by @var{result} contains the result. Otherwise an error occurred. to by @var{result} contains the result. Otherwise an error occurred.
@@ -1601,7 +1600,7 @@ programs.
@comment GNU @comment GNU
@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) @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 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 of using the global parameters for the congruential formula it uses the
information from the buffer pointed to by @var{buffer}. The state is information from the buffer pointed to by @var{buffer}. The state is
described by the values in @var{xsubi}. described by the values in @var{xsubi}.
@@ -1616,8 +1615,8 @@ programs.
@comment stdlib.h @comment stdlib.h
@comment GNU @comment GNU
@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
This function is similar to @code{mrand48} but as the other reentrant This function is similar to @code{mrand48} but like the other reentrant
function it uses the random number generator described by the value in functions it uses the random number generator described by the value in
the buffer pointed to by @var{buffer}. the buffer pointed to by @var{buffer}.
If the return value is non-negative the variable pointed to by If the return value is non-negative the variable pointed to by
@@ -1630,7 +1629,7 @@ programs.
@comment stdlib.h @comment stdlib.h
@comment GNU @comment GNU
@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) @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 other reentrant functions of this function family it uses the
congruential formula parameters from the buffer pointed to by congruential formula parameters from the buffer pointed to by
@var{buffer}. @var{buffer}.
@@ -1642,9 +1641,9 @@ This function is a GNU extension and should not be used in portable
programs. programs.
@end deftypefun @end deftypefun
Before any of the above functions should be used the buffer of type Before any of the above functions are used the buffer of type
@code{struct drand48_data} should initialized. The easiest way is to @code{struct drand48_data} should be initialized. The easiest way to do
fill the whole buffer with null bytes, e.g., using this is to fill the whole buffer with null bytes, e.g. by
@smallexample @smallexample
memset (buffer, '\0', sizeof (struct drand48_data)); 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 automatically initialize the random number generator to the default
values for the state and the parameters of the congruential formula. 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 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 recommended to use these functions since the result might not always be
what you expect. what you expect.
@@ -1665,10 +1664,10 @@ what you expect.
@comment GNU @comment GNU
@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
The description of the random number generator represented by the 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 @code{srand48} does. The state is initialized from the parameter
@var{seedval} and the parameters for the congruential formula are @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. 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 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 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 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 preserve the state for a later re-run s/he can copy the whole buffer
pointed to by @var{buffer}. pointed to by @var{buffer}.
This function is a GNU extension and should not be used in portable This function is a GNU extension and should not be used in portable
@@ -1696,11 +1695,11 @@ programs.
@comment GNU @comment GNU
@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) @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 This function initializes all aspects of the random number generator
described in @var{buffer} by the data in @var{param}. Here it is described in @var{buffer} with the data in @var{param}. Here it is
especially true the function does more than just copying the contents of especially true that the function does more than just copying the
@var{param} of @var{buffer}. Some more actions are required and contents of @var{param} and @var{buffer}. More work is required and
therefore it is important to use this function and not initialized the therefore it is important to use this function rather than initializing
random number generator directly. the random number generator directly.
If the return value is non-negative the function call succeeded. If the return value is non-negative the function call succeeded.
@@ -1712,23 +1711,22 @@ programs.
@section Is Fast Code or Small Code preferred? @section Is Fast Code or Small Code preferred?
@cindex Optimization @cindex Optimization
If an application uses many floating point function it is often the case If an application uses many floating point functions it is often the case
that the costs for the function calls itselfs are not neglectable. that the cost of the function calls themselves is not negligible.
Modern processor implementation often can execute the operation itself Modern processors can often execute the operations themselves
very fast but the call means a disturbance of the control flow. very fast, but the function call disrupts the instruction pipeline.
For this reason the GNU C Library provides optimizations for many of the 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 frequently-used math functions. When GNU CC is used and the user
activates the optimizer several new inline functions and macros get activates the optimizer, several new inline functions and macros are
defined. These new functions and macros have the same names as the 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 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 This means that no calls to the library functions may be necessary, and
are necessary. This increases the speed significantly. But the can increase the speed of generated code significantly. The drawback is
drawback is that the code size increases and this increase is not always that code size will increase, and the increase is not always negligible.
neglectable.
The speed increase has one drawback: the inline functions might not set The speed increase has one drawback: the inline functions might not set
@code{errno} and might not have the same precission as the library @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 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 @code{__NO_MATH_INLINES} should be defined before any system header is
included. This will make sure only library functions are used. Of included. This will ensure that only library functions are used. Of
course it can be determined for each single file in the project whether course, it can be determined for each file in the project whether
giving this option is preferred or not. giving this option is preferable or not.
Not all hardware implements the entire @w{IEEE 754} standard, or if it Not all hardware implements the entire @w{IEEE 754} standard, and even
does, there may be a substantial performance penalty for using some of if it does there may be a substantial performance penalty for using some
its features. For example, enabling traps on some processors forces of its features. For example, enabling traps on some processors forces
the FPU to run unpipelined, which more than doubles calculation time. the FPU to run un-pipelined, which can more than double calculation time.
@c ***Add explanation of -lieee, -mieee. @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 For the @code{hosts} and @code{networks} databases the default value is
@code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for @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 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 The @code{passwd}, @code{group}, and @code{shadow} databases are
traditionally handled in a special way. The appropriate files in the 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 @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
@section NSS Module Internals @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 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 jump table or the like. How this is done is of no interest here; those
interested in this topic should read about Dynamic Linking. interested in this topic should read about Dynamic Linking.
@@ -322,8 +322,8 @@ The name of each function consist of various parts:
@end quotation @end quotation
@var{service} of course corresponds to the name of the module this @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 function is found in.@footnote{Now you might ask why this information is
information. The answer is that we want to keep the possibility to link duplicated. The answer is that we want to make it possible to link
directly with these shared objects.} The @var{function} part is derived directly with these shared objects.} The @var{function} part is derived
from the interface function in the C library itself. If the user calls from the interface function in the C library itself. If the user calls
the function @code{gethostbyname} and the service used is @code{files} 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. only.
The NSS modules in the GNU C Library are prepared to be used as normal The NSS modules in the GNU C Library are prepared to be used as normal
libraries itself. libraries themselves. This is @emph{not} true at the moment, though.
@comment Fix me if necessary. However, the organization of the name space in the modules does not make it
This is @emph{not} true in the moment, though. But the different
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 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 still libraries.@footnote{There is a second explanation: we were too
lazy to change the Makefiles to allow the generation of shared objects 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 @node NSS Modules Interface, , NSS Module Names, NSS Module Internals
@@ -441,7 +439,7 @@ more.
@multitable @columnfractions .3 .2 .50 @multitable @columnfractions .3 .2 .50
@item @item
@code{NSS_STATUS_TRYAGAIN} @tab @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. resources or a service is currently not available.
@item @item
@tab @tab
@@ -481,7 +479,7 @@ signature of the module function:
@item @item
the return value is @code{int}; the return value is @code{int};
@item @item
the name is as explain in @pxref{NSS Module Names}; the name is as explained in @pxref{NSS Module Names};
@item @item
the first arguments are identical to the arguments of the non-reentrant the first arguments are identical to the arguments of the non-reentrant
function; 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 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 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 done by adding the wanted directory to the value of
@code{LD_LIBRARY_PATH}. @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. under IDs which do not belong to the user) ignore this variable.
Therefore the stable version of the module should be placed into a Therefore the stable version of the module should be placed into a
directory which is searched by the dynamic linker. Normally this should 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 @subsection Internals of the NSS Module Functions
Until now we only provided the syntactic interface for the functions in 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 implementation obviously is different for each function. But a few
general rules must be followed by all functions. 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 argument. This depends on the database used; it happens only for
@code{host} and @code{networks}. @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 more entries. When the last entry was read it should return
@code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too @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 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 @cindex filtering i/o through subprocess
A common use of pipes is to send data to or receive data from a program 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{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 @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, 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 subprocess. The subprocess inherits its standard output channel from
the parent process. 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 might happen if the pipe or stream cannot be created, if the subprocess
cannot be forked, or if the program cannot be executed. cannot be forked, or if the program cannot be executed.
@end deftypefun @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 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 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), 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 Reading or writing a larger amount of data may not be atomic; for
example, output data from other processes sharing the descriptor may be 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 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 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: of all the child processes with a chain of structures as follows:
@smallexample @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 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 write a handler that does nothing but set an external variable that the
program checks regularly, and leave all serious work to the program. 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 unpredictable times---perhaps in the middle of a primitive function, or
even between the beginning and the end of a C operator that requires even between the beginning and the end of a C operator that requires
multiple instructions. The data structures being manipulated might 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 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 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 them cause the same problem. Function descriptions in this manual
manual always mentions this behavior. always mention this behavior.
@item @item
If a function uses and modifies an object that you supply, then it is 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 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 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 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 There are three ways you can cope with this problem. You can use data
types that are always accessed atomically; you can carefully arrange 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 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 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 types are atomic; that is very convenient. Both of these assumptions
all of the machines that the GNU C library supports, and on all POSIX are true on all of the machines that the GNU C library supports and on
systems we know of. all POSIX systems we know of.
@c ??? This might fail on a 386 that uses 64-bit pointers. @c ??? This might fail on a 386 that uses 64-bit pointers.
@node Atomic Usage @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 also why we do not check @code{signal_pending} if @code{defer_signal}
is still nonzero. 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 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 middle. But that does not cause any problem. If the signal happens
early enough to see the value from before the increment or decrement, 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 If the signal causes program termination, @code{pause} doesn't return
(obviously). (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 is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time @code{pause} is 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 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 @c ref pthread_cleanup_push / pthread_cleanup_pop
The @code{pause} function is declared in @file{unistd.h}. 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 socket
@cindex interprocess communication, with sockets @cindex interprocess communication, with sockets
A @dfn{socket} is a generalized interprocess communication channel. A @dfn{socket} is a generalized interprocess communication channel.
Like a pipe, a socket is represented as a file descriptor. But, Like a pipe, a socket is represented as a file descriptor. Unlike pipes
unlike pipes, sockets support communication between unrelated sockets support communication between unrelated processes, and even
processes, and even between processes running on different machines between processes running on different machines that communicate over a
that communicate over a network. Sockets are the primary means of network. Sockets are the primary means of communicating with other
communicating with other machines; @code{telnet}, @code{rlogin}, machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
@code{ftp}, @code{talk}, and the other familiar network programs use other familiar network programs use sockets.
sockets.
Not all operating systems support sockets. In the GNU library, the Not all operating systems support sockets. In the GNU library, the
header file @file{sys/socket.h} exists regardless of the operating header file @file{sys/socket.h} exists regardless of the operating
system, and the socket functions always exist, but if the system does 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 @strong{Incomplete:} We do not currently document the facilities for
broadcast messages or for configuring Internet interfaces. The broadcast messages or for configuring Internet interfaces. The
@@ -28,7 +27,7 @@ aren't documented either so far.
@menu @menu
* Socket Concepts:: Basic concepts you need to know about. * 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. * Socket Addresses:: How socket names (``addresses'') work.
* Interface Naming:: Identifying specific network interfaces. * Interface Naming:: Identifying specific network interfaces.
* Local Namespace:: Details about the local namespace. * 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 byte stream
@cindex stream (sockets) @cindex stream (sockets)
@strong{What are the units of data transmission?} Some communication @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 structure; others group the bytes into records (which are known in
this context as @dfn{packets}). this context as @dfn{packets}).
@@ -81,7 +80,7 @@ to retransmit data as needed.
@item @item
@strong{Is communication entirely with one partner?} Some @strong{Is communication entirely with one partner?} Some
communication styles are like a telephone call---you make a 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 freely. Other styles are like mailing letters---you specify a
destination address for each message you send. destination address for each message you send.
@end itemize @end itemize
@@ -112,7 +111,7 @@ start with @samp{PF_}.
The rules of a protocol apply to the data passing between two programs, 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 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: know about protocols is this:
@itemize @bullet @itemize @bullet
@@ -127,30 +126,30 @@ example, the TCP protocol fits only the byte stream style of
communication and the Internet namespace. communication and the Internet namespace.
@item @item
For each combination of style and namespace, there is a @dfn{default For each combination of style and namespace there is a @dfn{default
protocol} which you can request by specifying 0 as the protocol protocol}, which you can request by specifying 0 as the protocol
number. And that's what you should normally do---use the default. number. And that's what you should normally do---use the default.
@end itemize @end itemize
Throughout the following description at various places Throughout the following description at various places
variables/parameters to denote sizes are required. And here the trouble variables/parameters to denote sizes are required. And here the trouble
starts. In the first implementations the type of these variables was 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 simply @code{int}. On most machines at that time an @code{int} was 32
bits wide and so a de-factor standard required 32 bit variables. This bits wide, which created a @emph{de facto} standard requiring 32-bit
is important since references to variables of this type are passed to variables. This is important since references to variables of this type
the kernel. are passed to the kernel.
But then the POSIX people came and unified the interface with the words Then the POSIX people came and unified the interface with the words "all
"all size values are of type @code{size_t}". But on 64 bit machines size values are of type @code{size_t}". On 64-bit machines
@code{size_t} is 64 bits wide, and so variable references are not anymore @code{size_t} is 64 bits wide, so pointers to variables were no longer
possible. possible.
The Unix98 specification provides a solution by introducing a type The Unix98 specification provides a solution by introducing a type
@code{socklen_t}. This type is used in all of the cases that POSIX @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 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 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 which require that references to 32-bit variables be passed can be as
happy as implementations which use 64 bit values. happy as implementations which use 64-bit values.
@node Communication Styles @node Communication Styles
@@ -165,8 +164,8 @@ defined in @file{sys/socket.h}.
@comment sys/socket.h @comment sys/socket.h
@comment BSD @comment BSD
@deftypevr Macro int SOCK_STREAM @deftypevr Macro int SOCK_STREAM
The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}); The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
it operates over a connection with a particular remote socket, and It operates over a connection with a particular remote socket and
transmits data reliably as a stream of bytes. transmits data reliably as a stream of bytes.
Use of this style is covered in detail in @ref{Connections}. 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 @comment BSD
@deftypevr Macro int SOCK_DGRAM @deftypevr Macro int SOCK_DGRAM
The @code{SOCK_DGRAM} style is used for sending 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}. It is the diametrical opposite of @code{SOCK_STREAM}.
Each time you write data to a socket of this kind, that data becomes 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. sixth, and may arrive a second time after the sixth.
The typical use for @code{SOCK_DGRAM} is in situations where it is 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. reasonable amount of time.
@xref{Datagrams}, for detailed information about how to use datagram @xref{Datagrams}, for detailed information about how to use datagram
@@ -203,7 +202,7 @@ sockets.
@comment sys/socket.h @comment sys/socket.h
@comment BSD @comment BSD
@deftypevr Macro int SOCK_SEQPACKET @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. structured into packets.
A program that receives data over a @code{SOCK_SEQPACKET} socket 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. system assigns an address automatically if you have not specified one.
Occasionally a client needs to specify an address because the server 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 protocols look at the client's socket address and only bypass password
checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}). 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 address or construct one; for that, you must use the proper data type
for the socket's namespace. 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 *} namespace-specific type, then cast a pointer to @code{struct sockaddr *}
when you call @code{bind} or @code{getsockname}. when you call @code{bind} or @code{getsockname}.
The one piece of information that you can get from the @code{struct 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. you which data type to use to understand the address fully.
@pindex sys/socket.h @pindex sys/socket.h
@@ -376,8 +375,8 @@ for completeness, but there is no reason to use it in a program.
@end table @end table
@file{sys/socket.h} defines symbols starting with @samp{AF_} for many @file{sys/socket.h} defines symbols starting with @samp{AF_} for many
different kinds of networks, all or most of which are not actually different kinds of networks, most or all of which are not actually
implemented. We will document those that really work, as we receive implemented. We will document those that really work as we receive
information about how to use them. information about how to use them.
@node Setting Address @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 @var{socket}. The @var{addr} and @var{length} arguments specify the
address; the detailed format of the address depends on the namespace. address; the detailed format of the address depends on the namespace.
The first part of the address is always the format designator, which 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. that namespace.
The return value is @code{0} on success and @code{-1} on failure. The 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 @node Local Namespace Concepts
@subsection 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 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 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. these files in the @file{/tmp} directory.
One peculiarity of the local namespace is that the name is only used when One peculiarity of the local namespace is that the name is only used
opening the connection; once that is over with, the address is not when opening the connection; once open the address is not meaningful and
meaningful and may not exist. may not exist.
Another peculiarity is that you cannot connect to such a socket from Another peculiarity is that you cannot connect to such a socket from
another machine--not even if the other machine shares the file system 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 directory listing, but connecting to it never succeeds. Some programs
take advantage of this, such as by asking the client to send its own 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. 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 as we might someday permit connections from other machines that mount
the same file systems. Instead, send each new client an identifying the same file systems. Instead, send each new client an identifying
number if you want it to have one. number if you want it to have one.
@@ -642,7 +641,7 @@ namespace. @xref{Socket Addresses}.
This is the file name to use. This is the file name to use.
@strong{Incomplete:} Why is 108 a magic number? RMS suggests making @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 @code{alloca} to allocate an appropriate amount of storage based on
the length of the filename. the length of the filename.
@end table @end table
@@ -676,15 +675,15 @@ namespace.
This section describes the details of the protocols and socket naming This section describes the details of the protocols and socket naming
conventions used in the Internet namespace. 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 the growing number of hosts on the Internet, a new protocol with a
larger address space was neccessary: IP version 6 (IPv6). IPv6 larger address space was necessary: IP version 6 (IPv6). IPv6
introduces besides 128bit addresses (IPv4 has 32bit addresses) also introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
other features and will eventually replace IPv4. features, and will eventually replace IPv4.
To create a socket in the IPv4 Internet namespace, use the symbolic name 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{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}. macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}.
@pindex sys/socket.h @pindex sys/socket.h
@@ -695,7 +694,9 @@ This designates the IPv4 Internet namespace and associated family of
protocols. protocols.
@end deftypevr @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 This designates the IPv6 Internet namespace and associated family of
protocols. protocols.
@end deftypevr @end deftypevr
@@ -706,7 +707,7 @@ A socket address for the Internet namespace includes the following components:
@item @item
The address of the machine you want to connect to. Internet addresses The address of the machine you want to connect to. Internet addresses
can be specified in several ways; these are discussed in @ref{Internet 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 @item
A port number for that machine. @xref{Ports}. A port number for that machine. @xref{Ports}.
@@ -719,7 +720,7 @@ for information about this.
@menu @menu
* Internet Address Formats:: How socket addresses are specified in the * Internet Address Formats:: How socket addresses are specified in the
Internet namespace. 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. * Protocols Database:: Referring to protocols by name.
* Ports:: Internet port numbers. * Ports:: Internet port numbers.
* Services Database:: Ports may have symbolic names. * Services Database:: Ports may have symbolic names.
@@ -751,7 +752,7 @@ Internet namespace. It has the following members:
@table @code @table @code
@item sa_family_t sin_family @item sa_family_t sin_family
This identifies the address family or format of the socket address. 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}. @xref{Socket Addresses}.
@item struct in_addr sin_addr @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}. of words separated by periods, as in @samp{mescaline.gnu.org}.
Programs that let the user specify a host typically accept both numeric Programs that let the user specify a host typically accept both numeric
addresses and host names. But the program needs a numeric address to addresses and host names. To open a connection a program needs a
open a connection; to use a host name, you must convert it to the numeric address, and so must convert a host name to the numeric address
numeric address it stands for. it stands for.
@menu @menu
* Abstract Host Addresses:: What a host number consists of. * 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. 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 Historically these are divided into two parts, a @dfn{network number} and a
@dfn{local network address number} within that network. In the @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, behaviour. Since some functions implicitly expect the old definitions,
we first describe the class based network and will then describe we first describe the class-based network and will then describe
classless addresses. IPv6 uses only classless adresses and therefore classless addresses. IPv6 uses only classless addresses and therefore
the following paragraphs don't apply. 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. three bytes; the rest of the bytes are the local address.
IPv4 network numbers are registered with the Network Information Center 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 network address numbers of individual machines are registered with the
administrator of the particular network. 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 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 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 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. Internet address specify the address within that network.
The Class A network 0 is reserved for broadcast to all networks. In 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 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. 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 The Class A network 127 is reserved for loopback; you can always use
@@ -902,15 +903,15 @@ radix is assumed.
@subsubheading Classless Addresses @subsubheading Classless Addresses
IPv4 addresses (and IPv6 addresses also) are now considered as IPv4 addresses (and IPv6 addresses also) are now considered classless;
classless. The distinction between classes A, B, and C can be ignored. the distinction between classes A, B and C can be ignored. Instead an
Instead a IPv4 host adddress consists of a 32-bit address and a 32-bit IPv4 host address consists of a 32-bit address and a 32-bit mask. The
mask. The mask contains bits of 1 for the network part and bits of 0 mask contains set bits for the network part and cleared bits for the
for the host part. The 1-bits are contigous from the leftmost bit, the host part. The network part is contiguous from the left, with the
0-bits are contigous from the rightmost bit so that the netmask can also remaining bits representing the host. As a consequence, the netmask can
be written as a prefix length of bits of 1. Classes A, B and C are just simply be specified as the number of set bits. Classes A, B and C are
special cases of this general rule. For example, class A addresses have just special cases of this general rule. For example, class A addresses
a netmask of @samp{255.0.0.0} or a prefix length of 8. 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 Classless IPv4 network addresses are written in numbers-and-dots
notation with the prefix length appended and a slash as separator. For 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 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 address is usually written as eight 16-bit hexadecimal numbers that are
separated by colons. Two colons are used to abbreviate strings of separated by colons. Two colons are used to abbreviate strings of
consecutive zeros. For example the IPv6 loopback address which is consecutive zeros. For example, the IPv6 loopback address
@samp{0:0:0:0:0:0:0:1} can be just written as @samp{::1}. @samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
@node Host Address Data Type @node Host Address Data Type
@subsubsection 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 You will find older code that uses @code{unsigned long int} for
IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct 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 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} 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 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 have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have
32 bits. 32 bits.
@@ -971,7 +972,7 @@ talking to itself.
@comment netinet/in.h @comment netinet/in.h
@comment BSD @comment BSD
@deftypevr Macro {uint32_t} INADDR_ANY @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 binding to an address. @xref{Setting Address}. This is the usual
address to give in the @code{sin_addr} member of @w{@code{struct address to give in the @code{sin_addr} member of @w{@code{struct
sockaddr_in}} when you want to accept Internet connections. 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 @deftypevr Constant {struct in6_addr} in6addr_loopback
This constant is the IPv6 address @samp{::1}, the loopback address. See This constant is the IPv6 address @samp{::1}, the loopback address. See
above for a description of what this means. The macro 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. own variables to this value.
@end deftypevr @end deftypevr
@@ -1011,7 +1012,7 @@ own variables to this value.
@deftypevr Constant {struct in6_addr} in6addr_any @deftypevr Constant {struct in6_addr} in6addr_any
This constant is the IPv6 address @samp{::}, the unspecified address. See This constant is the IPv6 address @samp{::}, the unspecified address. See
above for a description of what this means. The macro 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. own variables to this value.
@end deftypevr @end deftypevr
@@ -1022,7 +1023,7 @@ own variables to this value.
@noindent @noindent
These additional functions for manipulating Internet addresses are These additional functions for manipulating Internet addresses are
declared in the header file @file{arpa/inet.h}. They represent Internet 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 local-address-within-network numbers in host byte order. @xref{Byte
Order}, for an explanation of network and host byte order. 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 This function converts the IPv4 Internet host address @var{name} from the
standard numbers-and-dots notation into binary data. If the input is standard numbers-and-dots notation into binary data. If the input is
not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an 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 is obsolete because @code{INADDR_NONE} is a valid address
(255.255.255.255), and @code{inet_aton} provides a cleaner way to (255.255.255.255), and @code{inet_aton} provides a cleaner way to
indicate error return. indicate error return.
@@ -1170,7 +1171,7 @@ vector of strings.
This is the host address type; in practice, its value is always either 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 @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 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 might find a value in this field other than @code{AF_INET} or
@code{AF_INET6}. @xref{Socket Addresses}. @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}) @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
The @code{gethostbyname2} function is like @code{gethostbyname}, but The @code{gethostbyname2} function is like @code{gethostbyname}, but
allows the caller to specify the desired address family (e.g.@: 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 @end deftypefun
@comment netdb.h @comment netdb.h
@@ -1245,7 +1246,7 @@ Here are the error codes that you may find in @code{h_errno}:
@comment BSD @comment BSD
@item HOST_NOT_FOUND @item HOST_NOT_FOUND
@vindex 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 netdb.h
@comment BSD @comment BSD
@@ -1349,8 +1350,8 @@ too small.
@end deftypefun @end deftypefun
You can also scan the entire hosts database one entry at a time using You can also scan the entire hosts database one entry at a time using
@code{sethostent}, @code{gethostent}, and @code{endhostent}. Be careful @code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful
in using these functions, because they are not reentrant. when using these functions because they are not reentrant.
@comment netdb.h @comment netdb.h
@comment BSD @comment BSD
@@ -1494,8 +1495,8 @@ find such a service, it returns a null pointer.
@noindent @noindent
You can also scan the services database using @code{setservent}, You can also scan the services database using @code{setservent},
@code{getservent}, and @code{endservent}. Be careful in using these @code{getservent} and @code{endservent}. Be careful when using these
functions, because they are not reentrant. functions because they are not reentrant.
@comment netdb.h @comment netdb.h
@comment BSD @comment BSD
@@ -1538,11 +1539,11 @@ order), and others put it last (``little-endian'' order).
So that machines with different byte order conventions can So that machines with different byte order conventions can
communicate, the Internet protocols specify a canonical byte order communicate, the Internet protocols specify a canonical byte order
convention for data transmitted over the network. This is known 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 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 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 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 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 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 If you use @code{getservbyname} and @code{gethostbyname} or
@code{inet_addr} to get the port number and host address, the values are @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. the @code{sockaddr_in} structure.
Otherwise, you have to convert the values explicitly. Use @code{htons} 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 This function converts the @code{uint32_t} integer @var{hostlong} from
host byte order to network byte order. host byte order to network byte order.
This is used for IPv4 internet addresses. This is used for IPv4 Internet addresses.
@end deftypefun @end deftypefun
@comment netinet/in.h @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 This function converts the @code{uint32_t} integer @var{netlong} from
network byte order to host byte order. network byte order to host byte order.
This is used for IPv4 internet addresses. This is used for IPv4 Internet addresses.
@end deftypefun @end deftypefun
@node Protocols Database @node Protocols Database
@@ -1598,7 +1599,7 @@ This is used for IPv4 internet addresses.
@cindex protocols database @cindex protocols database
The communications protocol used with a socket controls low-level 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 things like checksums to detect errors in transmissions, and routing
instructions for messages. Normal user programs have little reason to instructions for messages. Normal user programs have little reason to
mess with these details directly. mess with these details directly.
@@ -1665,8 +1666,8 @@ protocol, it returns a null pointer.
@end deftypefun @end deftypefun
You can also scan the whole protocols database one protocol at a time by You can also scan the whole protocols database one protocol at a time by
using @code{setprotoent}, @code{getprotoent}, and @code{endprotoent}. using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
Be careful in using these functions, because they are not reentrant. Be careful when using these functions because they are not reentrant.
@comment netdb.h @comment netdb.h
@comment BSD @comment BSD
@@ -1729,7 +1730,7 @@ CCITT. @file{socket.h} defines these symbols and others naming protocols
not actually implemented. not actually implemented.
@code{PF_IMPLINK} is used for communicating between hosts and Internet @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 occasionally-used local area routing protocol, see the GNU Hurd Manual
(to appear in the future). (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. The system already has too many file descriptors open.
@item EACCESS @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}. @var{style} or @var{protocol}.
@item ENOBUFS @item ENOBUFS
@@ -1791,7 +1792,7 @@ The system ran out of internal buffer space.
@end table @end table
The file descriptor returned by the @code{socket} function supports both 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. positioning operations.
@end deftypefun @end deftypefun
@@ -1806,7 +1807,7 @@ see @ref{Local Socket Example}, or @ref{Inet Example}.
@cindex shutting down a socket @cindex shutting down a socket
@cindex socket shutdown @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}. file descriptor with @code{close}; see @ref{Opening and Closing Files}.
If there is still data waiting to be transmitted over the connection, If there is still data waiting to be transmitted over the connection,
normally @code{close} tries to complete this transmission. You 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}. specify a timeout period; see @ref{Socket Options}.
@pindex sys/socket.h @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 connection by calling @code{shutdown}, which is declared in
@file{sys/socket.h}. @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 is a full-duplex communications channel, so that both reading and writing
may be performed at either end. 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 interpreted as for the @code{socket} function. @var{style} should be
one of the communication styles listed in @ref{Communication Styles}. one of the communication styles listed in @ref{Communication Styles}.
The @var{namespace} argument specifies the namespace, which must be 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. initiate a connection with a server.
@item @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 server program must do to wait for and act upon connection requests
from clients. from clients.
@item @item
@ref{Transferring Data}, describes how data is transferred through the @ref{Transferring Data}, describes how data are transferred through the
connected socket. connected socket.
@end itemize @end itemize
@end iftex @end iftex
@@ -1959,7 +1960,7 @@ connected socket.
In making a connection, the client makes a connection while the server In making a connection, the client makes a connection while the server
waits for and accepts the connection. Here we discuss what the client 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}. @file{sys/socket.h}.
@comment 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). connection in progress (see @code{EINPROGRESS} above).
@end table @end table
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @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}. connection to it is requested. @xref{Inetd Servers}.
In the Internet namespace, there are no special protection mechanisms 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 can make a connection to your server. If you want to restrict access to
your server, make it examine the addresses associated with connection your server, make it examine the addresses associated with connection
requests or implement some other handshaking or identification 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 A socket that has been established as a server can accept connection
requests from multiple clients. The server's original socket 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. makes a new socket which participates in the connection.
@code{accept} returns the descriptor for this socket. The server's @code{accept} returns the descriptor for this socket. The server's
original socket remains available for listening for further connection 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. The number of pending connection requests on a server socket is finite.
If connection requests arrive from clients faster than the server can If connection requests arrive from clients faster than the server can
act upon them, the queue can fill up and additional requests are refused 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 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 system may also impose its own internal limit on the length of this
queue. queue.
@@ -2158,10 +2159,10 @@ The descriptor @var{socket} does not support this operation.
connections immediately available. connections immediately available.
@end table @end table
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @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{send} functions instead of the more generic @code{read} and
@code{write} functions. The @code{recv} and @code{send} functions take @code{write} functions. The @code{recv} and @code{send} functions take
an additional argument which you can use to specify various flags to 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_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 @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
to control inclusion of routing information on output. 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}. @code{send} fails with @code{EPIPE}.
@end table @end table
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @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 flags @var{flags}. The possible values of @var{flags} are described
in @ref{Socket Data Options}. 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 be read, @code{recv} fails immediately rather than waiting. @xref{File
Status Flags}, for information about nonblocking mode. 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. You never connected this socket.
@end table @end table
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @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 Streams with connections permit @dfn{out-of-band} data that is
delivered with higher priority than ordinary data. Typically the delivered with higher priority than ordinary data. Typically the
reason for sending out-of-band data is to send notice of an 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 @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
Data}). 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 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} available out-of-band data, use @code{recv} with the @code{MSG_OOB}
flag (@pxref{Receiving Data}). Ordinary read operations do not read 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 @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 @code{SIGURG} signal to the owner process or process group of the
socket. You can specify the owner using the @code{F_SETOWN} command socket. You can specify the owner using the @code{F_SETOWN} command
to the @code{fcntl} function; see @ref{Interrupt Input}. You must 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}. for I/O}, for more information about @code{select}.
Notification of out-of-band data (whether with @code{SIGURG} or with 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 may not actually arrive until later. If you try to read the
out-of-band data before it arrives, @code{recv} fails with an out-of-band data before it arrives, @code{recv} fails with an
@code{EWOULDBLOCK} error. @code{EWOULDBLOCK} error.
@@ -2522,7 +2523,7 @@ struct buffer
@r{It may be necessary to read some ordinary data} @r{It may be necessary to read some ordinary data}
@r{in order to make room for the out-of-band 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.} */ @r{found in the `next' field of the value.} */
struct buffer * 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 independent communication. You specify the destination for each
packet individually. 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 with its own destination address, and they may arrive in the wrong
order or not at all. 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 You can call @code{connect} on a datagram socket, but this only
specifies a default destination for further data transmission on the 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 @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
Primitives}) to send a packet there. You can cancel the default Primitives}) to send a packet there. You can cancel the default
destination by calling @code{connect} using an address format of 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 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 @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 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. system on your machine usually does not know this.
It is also possible for one call to @code{sendto} to report an error 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 This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @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. specifies the maximum number of bytes to be read.
If the packet is longer than @var{size} bytes, then you get the first 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 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. 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 The @var{addr} and @var{length-ptr} arguments are used to return the
address where the packet came from. @xref{Socket Addresses}. For a 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 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 Namespace}). You can specify a null pointer as the @var{addr} argument
if you are not interested in this information. 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 (@pxref{Socket Data Options}). The return value and error conditions
are also the same as for @code{recv}. are also the same as for @code{recv}.
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @end deftypefun
You can use plain @code{recv} (@pxref{Receiving Data}) instead of 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 (either because you know where it should come from or because you
treat all possible senders alike). Even @code{read} can be used if treat all possible senders alike). Even @code{read} can be used if
you don't want to specify @var{flags} (@pxref{I/O Primitives}). 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 @comment BSD
@deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) @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 This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is cancel. whatever) are freed even if the thread is cancel.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @end deftypefun
@@ -2730,10 +2731,10 @@ semaphores or whatever) are freed even if the thread is cancel.
@comment BSD @comment BSD
@deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) @deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
This function is defined as a cancelation point in multi-threaded This function is defined as a cancellation point in multi-threaded
programs. So one has to be prepared for this and make sure that programs, so one has to be prepared for this and make sure that
possibly allocated resources (like memory, files descriptors, allocated resources (like memory, files descriptors, semaphores or
semaphores or whatever) are freed even if the thread is canceled. whatever) are freed even if the thread is canceled.
@c @xref{pthread_cleanup_push}, for a method how to do this. @c @xref{pthread_cleanup_push}, for a method how to do this.
@end deftypefun @end deftypefun
@end ignore @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 First, here is the server program. It sits in a loop waiting for
messages to arrive, bouncing each message back to the sender. 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. the general ideas involved.
@smallexample @smallexample
@@ -2774,10 +2775,10 @@ referencing the name of the client.
Keep in mind that datagram socket communications are unreliable. In Keep in mind that datagram socket communications are unreliable. In
this example, the client program waits indefinitely if the message this example, the client program waits indefinitely if the message
never reaches the server or if the server's response never comes 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 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 it if desired. A more automatic solution could be to use
@code{select} (@pxref{Waiting for I/O}) to establish a timeout period @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. shut down the socket and exit.
@node Inetd @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 listening. Such a server must already be running in order for anyone
to connect to it. 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 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 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 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 process starts. The connection already exists at this time; the
socket is available as the standard input descriptor and as the socket is available as the standard input descriptor and as the
standard output descriptor (descriptors 0 and 1) in the server 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; right away. Often the program needs only the ordinary I/O facilities;
in fact, a general-purpose filter program that knows nothing about in fact, a general-purpose filter program that knows nothing about
sockets can work as a byte stream server run by @code{inetd}. sockets can work as a byte stream server run by @code{inetd}.
You can also use @code{inetd} for servers that use connectionless You can also use @code{inetd} for servers that use connectionless
communication styles. For these servers, @code{inetd} does not try to accept 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 server program, which can read the incoming datagram packet from
descriptor 0. The server program can handle one request and then descriptor 0. The server program can handle one request and then
exit, or you can choose to write it to keep reading more requests 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 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 @node Configuring Inetd
@subsection Configuring @code{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}. The @var{wait} field should be either @samp{wait} or @samp{nowait}.
Use @samp{wait} if @var{style} is a connectionless style and the 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 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 or request that comes in. If @var{style} uses connections, then
@var{wait} @strong{must} be @samp{nowait}. @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 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 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 @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 @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}) @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 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 @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 @c Argh. -zw
@iftex @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 protocol modules. The value has type @code{int}; a nonzero value means
``yes''. ``yes''.
@c !!! should say how this is used @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 sys/socket.h
@comment BSD @comment BSD
@@ -3037,7 +3038,7 @@ This structure type has the following members:
@table @code @table @code
@item int l_onoff @item int l_onoff
This field is interpreted as a boolean. If nonzero, @code{close} 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 @item int l_linger
This specifies the timeout period, in seconds. 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 @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 base is useful for routing programs such as @code{route}, but it is not
useful for programs that simply communicate over the network. We 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}. @file{netdb.h}.
@comment netdb.h @comment netdb.h
@@ -3159,8 +3160,8 @@ network.
@end deftypefun @end deftypefun
You can also scan the networks database using @code{setnetent}, You can also scan the networks database using @code{setnetent},
@code{getnetent}, and @code{endnetent}. Be careful in using these @code{getnetent} and @code{endnetent}. Be careful when using these
functions, because they are not reentrant. functions because they are not reentrant.
@comment netdb.h @comment netdb.h
@comment BSD @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 this array describes one argument. This information is encoded using
the various @samp{PA_} macros, listed below. the various @samp{PA_} macros, listed below.
The @var{n} argument specifies the number of elements in the array The argument @var{n} specifies the number of elements in the array
@var{argtypes}. This is the most elements that @var{argtypes}. This is the maximum number of elements that
@code{parse_printf_format} will try to write. @code{parse_printf_format} will try to write.
@code{parse_printf_format} returns the total number of arguments required @code{parse_printf_format} returns the total number of arguments required
by @var{template}. If this number is greater than @var{n}, then the by @var{template}. If this number is greater than @var{n}, then the
information returned describes only the first @var{n} arguments. If you 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. array and call @code{parse_printf_format} again.
@end deftypefun @end deftypefun
@@ -2107,9 +2107,9 @@ about this.
@c but if you are never going to call @code{parse_printf_format}, you do @c but if you are never going to call @code{parse_printf_format}, you do
@c not need to define an arginfo function. @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 @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 Now a call to any of the @code{printf} functions will call this
function when this format specifier appears in the format string. 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 Now let's look at how to define the handler and arginfo functions
which are passed as arguments to @code{register_printf_function}. 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 version 2.0. Previously the third argument was of type
@code{va_list *}. @code{va_list *}.
@@ -2254,7 +2254,7 @@ a description of this data structure.
@c arguments that your handler processes. @xref{Variadic Functions}.) @c arguments that your handler processes. @xref{Variadic Functions}.)
The @var{args} is a vector of pointers to the arguments data. 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. information function provided by the user.
Your handler function should return a value just like @code{printf} 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 Print a given floating point number as for the format @code{%f} except
that there is a postfix character indicating the divisor for the that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors: 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 format character specified while registered this handler. If the
character is of lower case, 1024 is used. For upper case characters, character is of lower case, 1024 is used. For upper case characters,
1000 is used. 1000 is used.
@@ -2378,7 +2378,7 @@ format character as if it were @code{%.3fk} and will yield @code{1.000k}.
@end deftypefun @end deftypefun
Due to the requirements of @code{register_printf_function} we must also 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 printf.h
@comment GNU @comment GNU
@@ -2403,14 +2403,14 @@ register_printf_function ('b', printf_size, printf_size_info);
@end smallexample @end smallexample
@noindent @noindent
we could also print using power of 1024. Please note that all what is we could also print using a power of 1024. Please note that all that is
different in these both lines in the format specifier. The different in these two lines is the format specifier. The
@code{printf_size} function knows about the difference of low and upper @code{printf_size} function knows about the difference between lower and upper
case format specifiers. case format specifiers.
The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is 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 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 @node Formatted Input
@section Formatted Input @section Formatted Input
@@ -2784,7 +2784,7 @@ in. @xref{Dynamic String Input}.
@end itemize @end itemize
The @samp{%c} conversion is the simplest: it matches a fixed number of 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 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 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 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. This section describes the miscellaneous input conversions.
The @samp{%p} conversion is used to read a pointer value. It recognizes 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 @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
number just as the @samp{%x} conversion accepts. The corresponding number just as the @samp{%x} conversion accepts. The corresponding
argument should be of type @code{void **}; that is, the address of a 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. resulting values.
The return value is normally the number of successful assignments. If The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed an end-of-file condition is detected before any matches are performed,
(including matches against whitespace and literal characters in the including matches against whitespace and literal characters in the
template), then @code{EOF} is returned. template, then @code{EOF} is returned.
@end deftypefun @end deftypefun
@comment stdio.h @comment stdio.h
@@ -2987,7 +2987,7 @@ extensions.
@comment stdio.h @comment stdio.h
@comment GNU @comment GNU
@deftypefun int vscanf (const char *@var{template}, va_list @var{ap}) @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 a variable number of arguments directly, it takes an argument list
pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
@end deftypefun @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 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 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. function, and warn you when they do not match the format string.
@xref{Function Attributes, , Declaring Attributes of Functions, For details, @xref{Function Attributes, , Declaring Attributes of Functions,
gcc.info, Using GNU CC}, for details. gcc.info, Using GNU CC}.
@node EOF and Errors @node EOF and Errors
@section End-Of-File 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 stdio.h
@comment Unix98 @comment Unix98
@deftypefun off_t ftello (FILE *@var{stream}) @deftypefun off_t ftello (FILE *@var{stream})
The @code{ftello} function is similar to @code{ftell} only it corrects a The @code{ftello} function is similar to @code{ftell}, except that it
problem which the POSIX type system. In this type system all file returns a value of type @code{off_t}. Systems which support this type
positions are described using values of type @code{off_t} which is not use it to describe all file positions, unlike the POSIX specification
necessarily of the same size as @code{long int}. Therefore using which uses a long int. The two are not necessarily the same size.
@code{ftell} can lead to problems if the implementation is written on Therefore, using ftell can lead to problems if the implementation is
top of a POSIX compliant lowlevel I/O implementation. 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 If this function fails it returns @code{(off_t) -1}. This can happen due
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
to missing support for file positioning or internal errors. Otherwise to missing support for file positioning or internal errors. Otherwise
the return value is the current file position. the return value is the current file position.
@@ -3360,9 +3357,9 @@ the same file position.
@item @item
In a call to @code{fseek} or @code{fseeko} on a text stream, either the 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 @var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
@code{SEEK_SET} and the @var{offset} must be the result of an earlier and the @var{offset} must be the result of an earlier call to @code{ftell}
call to @code{ftell} on the same stream. on the same stream.
@item @item
The value of the file position indicator of a text stream is undefined 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 streams, you need to understand how buffering works when you design the
user interface to your program. Otherwise, you might find that output user interface to your program. Otherwise, you might find that output
(such as progress or prompt messages) doesn't appear when you intended (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 This section deals only with controlling when characters are transmitted
between the stream and the file or device, and @emph{not} with how 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. 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} If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
dynamically allocates (as with @code{malloc}; @pxref{Unconstrained dynamically allocates an array @var{size} bytes long (as with @code{malloc};
Allocation}) an array @var{size} bytes long. This is really only useful @pxref{Unconstrained Allocation}). This is really only useful
if you are going to write things to the buffer and then read them back 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 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 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 in the @var{classification} parameter. The @var{label} parameter
identifies the source of the message. The string should consist of two 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 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 describes the condition of the error, the @var{action} parameter possible
steps to recover from the error and the @var{tag} parameter is a steps to recover from the error and the @var{tag} parameter is a
reference to the online documentation where more information can be 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. ignored.
This function is specified in the X/Open Portability Guide. It is also 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 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}. 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 There are two environment variables which influence the behaviour of
@code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the
output actually happening on standard error (@emph{not} the console 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 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 following in the environment before calling the @code{fmtmsg} function
the first time: the first time:
@@ -4291,17 +4288,17 @@ not print the numeric value but instead the string representation).
@subsection Adding Severity Classes @subsection Adding Severity Classes
@cindex severity class @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 the environment variable @code{SEV_LEVEL}. This simplifies the task of
introducing new classes in a running program. One could use the introducing new classes in a running program. One could use the
@code{setenv} or @code{putenv} function to set the environment variable, @code{setenv} or @code{putenv} function to set the environment variable,
but this is toilsome. but this is toilsome.
@deftypefun int addseverity (int @var{severity}, const char *@var{string}) @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. addressed by the @var{severity} parameter of the @code{fmtmsg} function.
The @var{severity} parameter of @code{addseverity} must match the value 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 is the string printed in the actual messages instead of the numeric
value. value.
@@ -4332,14 +4329,14 @@ functions described in this section.
@include fmtmsgexpl.c.texi @include fmtmsgexpl.c.texi
@end smallexample @end smallexample
The second call to @code{fmtmsg} illustrates a use of this function how The second call to @code{fmtmsg} illustrates a use of this function as
it usually happens on System V systems which heavily use this function. it usually occurs on System V systems, which heavily use this function.
It might be worth a thought to follow the scheme used in System V It seems worthwhile to give a short explanation here of how this system
systems so we give a short explanation here. The value of the works on System V. The value of the
@var{label} field (@code{UX:cat}) says that the error occured in 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 Unix program @code{cat}. The explanation of the error follows and the
value for the @var{action} parameter is @code{"refer to manual"}. One 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} 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 parameter, and additionally a unique ID (@code{001} in this case). For
a GNU environment this string could contain a reference to the 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 (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call
produced no output since the class with the numeric value @code{6} is 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 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. the second call to @code{fmtmsg} produces the above output.
When we change the environment of the program to contain When we change the environment of the program to contain
@@ -4375,11 +4372,11 @@ label:foo: NOTE: text
TO FIX: action tag TO FIX: action tag
@end smallexample @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 the string @code{NOTE} from the environment variable appears in the
message. 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 interested in. If we additionally set the environment variable
@code{MSGVERB} to the value @code{severity:label:action} we get the @code{MSGVERB} to the value @code{severity:label:action} we get the
following output: following output:
@@ -4395,5 +4392,5 @@ TO FIX: action
I.e., the output produced by the @var{text} and the @var{tag} parameters 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 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 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. 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) @deftypefun {long int} gethostid (void)
This function returns the ``host ID'' of the machine the program is This function returns the ``host ID'' of the machine the program is
running on. By convention, this is usually the primary Internet address 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 systems it is a meaningless but unique number which is hard-coded for
each machine. each machine.
@end deftypefun @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. it happens just once, at system boot time.
The return value is @code{0} on success and @code{-1} on failure. 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 @table @code
@item EPERM @item EPERM
@@ -186,10 +186,10 @@ possibility.
@section Which filesystems are mounted and/or available? @section Which filesystems are mounted and/or available?
The Unix concept of @emph{Everything is a file} is based on the 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 filesystem. For some programs it is desirable and necessary to access
the information whether and, if yes, where a certain filesystem is information about whether a certain filesystem is mounted and, if it is,
mounted or simply to get lists of all the available filesystems. The where, or simply to get lists of all the available filesystems. The
GNU libc provides some functions to retrieve this information portably. GNU libc provides some functions to retrieve this information portably.
Traditionally Unix systems have a file named @file{/etc/fstab} which 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{=} consists of a name and an optional value part, introduced by an @code{=}
character. 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}. using the @code{getsubopt} function; see @ref{Suboptions}.
@item const char *fs_type @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 program start or the last call of @code{endfsent}, the file will be
opened. 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 fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent} function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer. 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}, @file{fstab} since program start or the last call of @code{endfsent},
the file will be opened. 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 fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent} function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer. 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}, @file{fstab} since program start or the last call of @code{endfsent},
the file will be opened. 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 fstab}. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred @code{getfsent} function is not thread-safe. If an error occurred @code{getfsent}
returns a @code{NULL} pointer. returns a @code{NULL} pointer.
@@ -387,11 +387,11 @@ filesystem. It corresponds to the @code{fs_file} element in
@item char *mnt_type @item char *mnt_type
@code{mnt_type} describes the filesystem type and is therefore @code{mnt_type} describes the filesystem type and is therefore
equivalent to @code{fs_vfstype} in @code{struct fstab}. @file{mntent.h} 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. defines a few symbolic names for some of the values this string can have.
But since the kernel can support an arbitrary filesystems it does not But since the kernel can support arbitrary filesystems it does not
make much sense to give them symbolic names. If one knows the symbol make much sense to give them symbolic names. If one knows the symbol
name one also knows the filesystem name. Nevertheless here follows the 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 @vtable @code
@item MNTTYPE_IGNORE @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 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 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: to rely on these macros but to be consistent here is the list:
@vtable @code @vtable @code
@@ -539,7 +539,7 @@ end of file reached,
@comment mntent.h @comment mntent.h
@comment BSD @comment BSD
@deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) @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 previously opened with @code{setmntent}. The new entries are always
appended. I.e., even if the position of the file descriptor is not at 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 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 All the @code{get*} functions mentioned before store the information
they return in a static buffer. This can be a problem in multi-threaded 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 return value data in another thread. Therefore the GNU C Library
provides as extensions three more functions which return the data in a provides as extensions three more functions which return the data in a
user-provided buffer. 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. host names is not supported so far.
In Sun Microsystems SunOS appeared a new kind of database, the netgroup In Sun Microsystems SunOS appeared a new kind of database, the netgroup
database. It allows to group hosts, users, and domain freely, giving database. It allows grouping hosts, users, and domains freely, giving
them individual names. More concrete: a netgroup is a list of triples 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 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 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 possibility is that names of other netgroups can also be given in the
list specifying a netgroup. So one can construct arbitrary hierarchies list specifying a netgroup. So one can construct arbitrary hierarchies
without loops. without loops.
Sun's implementation allows netgroups only for the @code{nis} or 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 implementation in the GNU C library has no such restriction. An entry
in either of the input services must have the following form: 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 Any of the fields in the triple can be empty which means anything
matches. While describing the functions we will see that the opposite 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 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. character @code{-} shall be used.
@node Lookup Netgroup @node Lookup Netgroup
@@ -1889,10 +1889,10 @@ These functions are declared in @file{netdb.h}.
@comment BSD @comment BSD
@deftypefun int setnetgrent (const char *@var{netgroup}) @deftypefun int setnetgrent (const char *@var{netgroup})
A call to this function initializes the internal state of the library to 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}. 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 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. netgroup of this name is known or some other error occurred.
@end deftypefun @end deftypefun
@@ -1914,11 +1914,11 @@ the @code{innetgr} function and parts of the implementation of the
@comment BSD @comment BSD
@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp}) @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
This function returns the next unprocessed entry of the currently 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 the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
after a successful call pointers to appropriate strings. If the string after a successful call pointers to appropriate strings. If the string
in the next entry is empty the pointer has the value @code{NULL}. 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. related functions are called.
The return value is @code{1} if the next entry was successfully read. A 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 netdb.h
@comment BSD @comment BSD
@deftypefun void endnetgrent (void) @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 selected netgroup. As a result all string pointers returned by calls
to @code{getnetgrent} are invalid afterwards. to @code{getnetgrent} are invalid afterwards.
@end deftypefun @end deftypefun
@@ -1975,7 +1975,7 @@ to the other @code{set}/@code{get}/@code{endnetgrent} functions.
@end enumerate @end enumerate
Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be 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 also true for the name @code{-} which should not match any other string
otherwise. otherwise.