diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/.cvsignore | 2 | ||||
| -rw-r--r-- | manual/Makefile | 35 | ||||
| -rw-r--r-- | manual/libc-texinfo.sh | 147 | ||||
| -rw-r--r-- | manual/llio.texi | 429 | ||||
| -rw-r--r-- | manual/math.texi | 6 | ||||
| -rw-r--r-- | manual/top-menu.texi | 671 |
6 files changed, 1164 insertions, 126 deletions
diff --git a/manual/.cvsignore b/manual/.cvsignore index 01f89684cf..1d23d99cd2 100644 --- a/manual/.cvsignore +++ b/manual/.cvsignore @@ -8,5 +8,5 @@ glibc-* *.toc *.aux *.log *.tmp *.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs -chapters chapters-incl1 chapters-incl2 summary.texi stamp-* +texis top-menu.texi chapters.texi summary.texi stamp-* distinfo dir-add.texinfo diff --git a/manual/Makefile b/manual/Makefile index 8af1d6c1a2..47656c6c7f 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -48,35 +48,32 @@ endif mkinstalldirs = $(..)scripts/mkinstalldirs chapters = $(addsuffix .texi, \ - intro errno memory ctype string mbyte locale message search \ - pattern io stdio llio filesys pipe socket terminal math \ - arith time setjmp signal startup process job nss users \ - sysinfo conf) -add-chapters = $(wildcard $(patsubst %, ../%.texi, \ - $(join $(add-ons:=/),$(add-ons)))) + intro errno memory ctype string mbyte locale \ + message search pattern io stdio llio filesys \ + pipe socket terminal math arith time setjmp \ + signal startup process job nss users sysinfo conf) +add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi)) appendices = lang.texi header.texi install.texi maint.texi contrib.texi -include texis -texis: $(chapters) $(add-chapters) $(appendices) lgpl.texinfo - $(AWK) -f texis.awk $^ > $@.T +texis: texis.awk $(chapters) $(add-chapters) $(appendices) lgpl.texinfo + $(AWK) -f $^ > $@.T mv -f $@.T $@ -nonexamples = $(filter-out %.c.texi, $(texis)) +nonexamples = $(filter-out $(add-chapters) %.c.texi, $(texis)) examples = $(filter %.c.texi, $(texis)) # Kludge: implicit rule so Make knows the one command does it all. -chapters.% top-menu.%: $(texis) - AWK=$(AWK) $(SHELL) libc-texinfo.sh \ - '$(chapters)' '$(add-chapters)' '$(appendices)' +chapters.% top-menu.%: libc-texinfo.sh $(texis) + AWK=$(AWK) $(SHELL) $< '$(chapters)' '$(add-chapters)' '$(appendices)' libc.dvi libc.info: chapters.texi top-menu.texi libc.dvi: texinfo.tex # Generate the summary from the Texinfo source files for each chapter. summary.texi: stamp-summary ; -stamp-summary: summary.awk $(chapters) $(chapters-incl) - $(AWK) -f $^ \ - | sort -df +1 -2 | tr '\014' '\012' > summary-tmp +stamp-summary: summary.awk $(filter-out summary.texi, $(texis)) + $(AWK) -f $^ | sort -df +1 -2 | tr '\014' '\012' > summary-tmp $(move-if-change) summary-tmp summary.texi touch $@ @@ -106,8 +103,8 @@ dir-add.texinfo: xtract-typefun.awk $(texis) $(TEXI2DVI) $< # Distribution. -minimal-dist = summary.awk texis.awk libc-texinfo.sh libc.texinfo \ - $(filter-out summary.texi, $(nonexamples)) \ +minimal-dist = summary.awk texis.awk libc-texinfo.sh libc.texinfo \ + $(filter-out summary.texi, $(nonexamples)) \ $(patsubst %.c.texi,examples/%.c, $(examples)) doc-only-dist = Makefile COPYING.LIB @@ -170,9 +167,7 @@ install-%: ; $(inst_infodir)/libc.info: libc.info installdirs for file in $<*; do \ - name=`basename $$file`; \ - $(INSTALL_DATA) $$file \ - `echo $@ | sed "s,$<\$$,$$name,"`; \ + $(INSTALL_DATA) $$file $(@D)/$$file; \ done installdirs: diff --git a/manual/libc-texinfo.sh b/manual/libc-texinfo.sh index 88733cb079..7f26f8ec5f 100644 --- a/manual/libc-texinfo.sh +++ b/manual/libc-texinfo.sh @@ -2,98 +2,71 @@ # Create libc.texinfo from the chapter files. -grep '^@node.*Top' $1 | cut -d, -f-2 | - sed 's/, /:/; s/:@node /:/; s/ /_/g; s/:/ /g' >cnodes.$$ - -$AWK '{ file[$2] = $1; nnode[$2] = $3 } -END { for(x in file) - if(file[x] != "") - print file[x] ":" x, file[nnode[x]] ":" nnode[x] }' \ - cnodes.$$ | tsort | sed 's/_/ /g; $d' >corder.$$ - -[ -z "$2" ] || grep '^@node.*Top' `echo $2 /dev/null | tr ' ' '\n' | sort` | - cut -d, -f1 | sed 's/@node //' >xorder.$$ - -grep '^@node.*Top' $3 | cut -d, -f-2 | - sed 's/, /:/; s/:@node /:/; s/ /_/g; s/:/ /g' >anodes.$$ - -$AWK '{ file[$2] = $1; nnode[$2] = $3 } -END { for(x in file) - if(file[x] != "") - print file[x] ":" x, file[nnode[x]] ":" nnode[x] }' \ - anodes.$$ | tsort | sed 's/_/ /g; $d' >aorder.$$ - -IFS=: - ->incl.$$ ->smenu.$$ ->lmenu.$$ - -while read file node; do - echo "@include $file" >>incl.$$ - echo "* $node:: `sed -n 's/^@c %MENU% //p' $file`" >>smenu.$$ - lmenu=`sed -n '/^@menu/,/^@end menu/p; /^@end menu/q' $file | - sed '/^@menu/d; /^@end menu/d'` - [ -z "$lmenu" ] || ( - echo; echo "$node"; echo - echo "$lmenu" - ) >>lmenu.$$ -done <corder.$$ - -if [ -f xorder.$$ ]; then - - (echo; echo 'Add-ons'; echo) >>smenu.$$ - - while read file node; do - echo "@include $file" >>incl.$$ - echo "* $node:: `sed -n 's/^@c %MENU% //p' $file`" >>smenu.$$ - lmenu=`sed -n '/^@menu/,/^@end menu/p; /^@end menu/q' $file | - sed '/^@menu/d; /^@end menu/d'` - [ -z "$lmenu" ] || ( - echo; echo "$node"; echo - echo "$lmenu" - ) >>lmenu.$$ - done <xorder.$$ -fi +trap "rm -f *.$$; exit 1" 1 2 15 + +exec 3>incl.$$ 4>smenu.$$ 5>lmenu.$$ + +build_menu () { + while IFS=: read file node; do + echo "@include $file" >&3 + echo "* $node:: `sed -n 's/^@c %MENU% //p' $file`" >&4 + $AWK 'BEGIN { do_menu = 0 } + /^@node / { sub(/^@node /, ""); sub(/,.*$/, ""); node = $0 } + /^@menu/ { printf "\n%s\n\n", node; do_menu = 1; next } + /^@end menu/ { do_menu = 0 } + do_menu { print }' $file >&5 + done +} -(echo; echo 'Appendices'; echo) >>smenu.$$ - -while read file node; do - echo "@include $file" >>incl.$$ - echo "* $node:: `sed -n 's/^@c %MENU% //p' $file`" >>smenu.$$ - lmenu=`sed -n '/^@menu/,/^@end menu/p; /^@end menu/q' $file | - sed '/^@menu/d; /^@end menu/d'` - [ -z "$lmenu" ] || ( - echo; echo "$node"; echo - echo "$lmenu" - ) >>lmenu.$$ -done <aorder.$$ - -$AWK ' -BEGIN { FS=":" } - -/^\*/ { - printf("%-32s", $1 "::"); - x = split($3, word, " "); - hpos = 34; - for(i = 1; i <= x; i++) { - hpos += length(word[i]) + 1; - if(hpos > 78) { - printf("\n%34s", ""); - hpos = 35 + length(word[i]); - } - printf(" %s", word[i]); - } - print "."; +collect_nodes () { + grep '^@node.*Top' "$@" /dev/null | cut -d, -f-2 | + sed 's/, /:/; s/:@node /:/; s/ /_/g; s/:/ /g' | + $AWK '{ file[$2] = $1; nnode[$2] = $3 } + END { for (x in file) + if (file[x] != "") + print file[x] ":" x, file[nnode[x]] ":" nnode[x] }' | + tsort | sed 's/_/ /g; $d' } -!/^\*/ { print; } -' smenu.$$ >smenux.$$ +collect_nodes $1 | build_menu + +if [ -n "$2" ]; then + + { echo; echo 'Add-ons'; echo; } >&4 + + grep '^@node.*Top' `echo $2 /dev/null | tr ' ' '\n' | sort` | + cut -d, -f1 | sed 's/@node //' | build_menu + +fi + +{ echo; echo 'Appendices'; echo; } >&4 + +collect_nodes $3 | build_menu + +exec 3>&- 4>&- 5>&- mv -f incl.$$ chapters.texi -(echo '@menu' - cat smenux.$$ +{ + echo '@menu' + $AWK -F: ' + /^\*/ { + printf("%-32s", $1 "::"); + x = split($3, word, " "); + hpos = 34; + for (i = 1; i <= x; i++) { + hpos += length(word[i]) + 1; + if (hpos > 78) { + printf("\n%34s", ""); + hpos = 35 + length(word[i]); + } + printf(" %s", word[i]); + } + print "."; + } + + !/^\*/ { print; } + ' smenu.$$ cat <<EOF * Copying:: The GNU Library General Public License says how you can copy and share the GNU C Library. @@ -109,7 +82,7 @@ Indices --- The Detailed Node Listing --- EOF cat lmenu.$$ - echo '@end menu' ) >top-menu.texi.$$ + echo '@end menu'; } >top-menu.texi.$$ mv -f top-menu.texi.$$ top-menu.texi rm -f *.$$ diff --git a/manual/llio.texi b/manual/llio.texi index 459032ee3a..cf3e1a7c89 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -41,6 +41,8 @@ directly.) or vice-versa. * Stream/Descriptor Precautions:: Precautions needed if you use both descriptors and streams. +* Scatter-Gather:: Fast I/O to discontinous buffers. +* Memory-mapped I/O:: Using files like memory. * Waiting for I/O:: How to check for input or output on multiple file descriptors. * Synchronizing I/O:: Making sure all I/O actions completed. @@ -58,6 +60,7 @@ directly.) file locking. * Interrupt Input:: Getting an asynchronous signal when input arrives. +* IOCTLs:: Generic I/O Control operations. @end menu @@ -88,7 +91,7 @@ parameters (using the @samp{|} operator in C). @xref{File Status Flags}, for the parameters available. The normal return value from @code{open} is a non-negative integer file -descriptor. In the case of an error, a value of @code{-1} is returned +descriptor. In the case of an error, a value of @math{-1} is returned instead. In addition to the usual file name errors (@pxref{File Name Errors}), the following @code{errno} error conditions are defined for this function: @@ -240,7 +243,7 @@ until the program ends. To avoid this calls to @code{close} should be protected using cancelation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop -The normal return value from @code{close} is @code{0}; a value of @code{-1} +The normal return value from @code{close} is @math{0}; a value of @math{-1} is returned in case of failure. The following @code{errno} error conditions are defined for this function: @@ -422,7 +425,7 @@ If @code{read} returns at least one character, there is no way you can tell whether end-of-file was reached. But if you did reach the end, the next read will return zero. -In case of an error, @code{read} returns @code{-1}. The following +In case of an error, @code{read} returns @math{-1}. The following @code{errno} error conditions are defined for this function: @table @code @@ -564,7 +567,7 @@ is therefore faster. You can use the @code{O_FSYNC} open mode to make @code{write} always store the data to disk before returning; @pxref{Operating Modes}. -In the case of an error, @code{write} returns @code{-1}. The following +In the case of an error, @code{write} returns @math{-1}. The following @code{errno} error conditions are defined for this function: @table @code @@ -761,7 +764,7 @@ file takes up less space than it appears so; it is then called a @cindex holes in files If the file position cannot be changed, or the operation is in some way -invalid, @code{lseek} returns a value of @code{-1}. The following +invalid, @code{lseek} returns a value of @math{-1}. The following @code{errno} error conditions are defined for this function: @table @code @@ -944,7 +947,7 @@ see @ref{Creating a Pipe}. This function returns the file descriptor associated with the stream @var{stream}. If an error is detected (for example, if the @var{stream} is not valid) or if @var{stream} does not do I/O to a file, -@code{fileno} returns @code{-1}. +@code{fileno} returns @math{-1}. @end deftypefun @cindex standard file descriptors @@ -1122,6 +1125,341 @@ terminal settings that were in effect at the time, flush the output streams for that terminal before setting the modes. @xref{Terminal Modes}. +@node Scatter-Gather +@section Fast Scatter-Gather I/O +@cindex scatter-gather + +Some applications may need to read or write data to multiple buffers, +which are seperated in memory. Although this can be done easily enough +with multiple calls to @code{read} and @code{write}, it is inefficent +because there is overhead associated with each kernel call. + +Instead, many platforms provide special high-speed primitives to perform +these @dfn{scatter-gather} operations in a single kernel call. The GNU C +library will provide an emulation on any system that lacks these +primitives, so they are not a portability threat. They are defined in +@code{sys/uio.h}. + +These functions are controlled with arrays of @code{iovec} structures, +which describe the location and size of each buffer. + +@deftp {Data Type} {struct iovec} + +The @code{iovec} structure describes a buffer. It contains two fields: + +@table @code + +@item void *iov_base +Contains the address of a buffer. + +@item size_t iov_len +Contains the length of the buffer. + +@end table +@end deftp + +@deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) + +The @code{readv} function reads data from @var{filedes} and scatters it +into the buffers described in @var{vector}, which is taken to be +@var{count} structures long. As each buffer is filled, data is sent to the +next. + +Note that @code{readv} is not guaranteed to fill all the buffers. +It may stop at any point, for the same reasons @code{read} would. + +The return value is a count of bytes (@emph{not} buffers) read, @math{0} +indicating end-of-file, or @math{-1} indicating an error. The possible +errors are the same as in @code{read}. + +@end deftypefun + +@deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count}) + +The @code{writev} function gathers data from the buffers described in +@var{vector}, which is taken to be @var{count} structures long, and writes +them to @code{filedes}. As each buffer is written, it moves on to the +next. + +Like @code{readv}, @code{writev} may stop midstream under the same +conditions @code{write} would. + +The return value is a count of bytes written, or @math{-1} indicating an +error. The possible errors are the same as in @code{write}. + +@end deftypefun + +@c Note - I haven't read this anywhere. I surmised it from my knowledge +@c of computer science. Thus, there could be subtleties I'm missing. + +Note that if the buffers are small (under about 1kB), high-level streams +may be easier to use than these functions. However, @code{readv} and +@code{writev} are more efficient when the individual buffers themselves +(as opposed to the total output), are large. In that case, a high-level +stream would not be able to cache the data effectively. + +@node Memory-mapped I/O +@section Memory-mapped I/O + +On modern operating systems, it is possible to @dfn{mmap} (pronounced +``em-map'') a file to a region of memory. When this is done, the file can +be accessed just like an array in the program. + +This is more efficent than @code{read} or @code{write}, as only regions +of the file a program actually accesses are loaded. Accesses to +not-yet-loaded parts of the mmapped region are handled in the same way as +swapped out pages. + +Since mmapped pages can be stored back to their file when physical memory +is low, it is possible to mmap files orders of magnitude larger than both +the physical memory @emph{and} swap space. The only limit is address +space. The theoretical limit is 4GB on a 32-bit machine - however, the +actual limit will be smaller since some areas will be reserved for other +purposes. + +Memory mapping only works on entire pages of memory. Thus, addresses +for mapping must be page-aligned, and length values will be rounded up. +To determine the size of a page the machine uses one should use + +@smallexample +size_t page_size = (size_t) sysconf (_SC_PAGESIZE); +@end smallexample + +These functions are declared in @file{sys/mman.h}. + +@deftypefun {void *} mmap (void *@var{address}, size_t @var{length},int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset}) + +The @code{mmap} function creates a new mapping, connected to bytes +(@var{offset}) to (@var{offset} + @var{length}) in the file open on +@var{filedes}. + +@var{address} gives a preferred starting address for the mapping. +@code{NULL} expresses no preference. Any previous mapping at that +address is automatically removed. The address you give may still be +changed, unless you use the @code{MAP_FIXED} flag. + +@vindex PROT_READ +@vindex PROT_WRITE +@vindex PROT_EXEC +@var{protect} contains flags that control what kind of access is +permitted. They include @code{PROT_READ}, @code{PROT_WRITE}, and +@code{PROT_EXEC}, which permit reading, writing, and execution, +respectively. Inappropriate access will cause a segfault (@pxref{Program +Error Signals}). + +Note that most hardware designs cannot support write permission without +read permission, and many do not distinguish read and execute permission. +Thus, you may recieve wider permissions than you ask for, and mappings of +write-only files may be denied even if you do not use @code{PROT_READ}. + +@var{flags} contains flags that control the nature of the map. +One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified. + +They include: + +@vtable @code +@item MAP_PRIVATE +This specifies that writes to the region should never be written back +to the attached file. Instead, a copy is made for the process, and the +region will be swapped normally if memory runs low. No other process will +see the changes. + +Since private mappings effectively revert to ordinary memory +when written to, you must have enough virtual memory for a copy of +the entire mmapped region if you use this mode with @code{PROT_WRITE}. + +@item MAP_SHARED +This specifies that writes to the region will be written back to the +file. Changes made will be shared immediately with other processes +mmaping the same file. + +Note that actual writing may take place at any time. You need to use +@code{msync}, described below, if it is important that other processes +using conventional I/O get a consistent view of the file. + +@item MAP_FIXED +This forces the system to use the exact mapping address specified in +@var{address} and fail if it can't. + +@c One of these is official - the other is obviously an obsolete synonym +@c Which is which? +@item MAP_ANONYMOUS +@itemx MAP_ANON +This flag tells the system to create an anonymous mapping, not connected +to a file. @var{filedes} and @var{off} are ignored, and the region is +initialized with zeros. + +Anonymous maps are used as the basic primitive to extend the heap on some +systems. They are also useful to share data between multiple tasks +without creating a file. + +On some systems using private anonymous mmaps is more efficent than using +@code{malloc} for large blocks. This is not an issue with the GNU C library, +as the included @code{malloc} automatically uses @code{mmap} where appropriate. + +@c Linux has some other MAP_ options, which I have not discussed here. +@c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to +@c user programs (and I don't understand the last two). MAP_LOCKED does +@c not appear to be implemented. + +@end vtable + +@code{mmap} returns the address of the new mapping, or @math{-1} for an +error. + +Possible errors include: + +@table @code + +@item EINVAL + +Either @var{address} was unusable, or inconsistent @var{flags} were +given. + +@item EACCES + +@var{filedes} was not open for the type of access specified in @var{protect}. + +@item ENOMEM + +Either there is not enough memory for the operation, or the process is +out of address space. + +@item ENODEV + +This file is of a type that doesn't support mapping. + +@item ENOEXEC + +The file is on a filesystem that doesn't support mapping. + +@c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock. +@c However mandatory locks are not discussed in this manual. +@c +@c Similarly, ETXTBSY will occur if the MAP_DENYWRITE flag (not documented +@c here) is used and the file is already open for writing. + +@end table + +@end deftypefun + +@deftypefun int munmap (void *@var{addr}, size_t @var{length}) + +@code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} + +@var{length}). @var{length} should be the length of the mapping. + +It is safe to un-map multiple mappings in one command, or include unmapped +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 +an even number of pages, it will be rounded up. + +It returns @math{0} for success and @math{-1} for an error. + +One error is possible: + +@table @code + +@item EINVAL +The memory range given was outside the user mmap range, or wasn't page +aligned. + +@end table + +@end deftypefun + +@deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags}) + +When using shared mappings, the kernel can write the file at any time +before the mapping is removed. To be certain data has actually been +written to the file and will be accessable to non-memory-mapped I/O, it +is neccessary to use this function. + +It operates on the region @var{address} to (@var{address} + @var{length}). +It may be used on part of a mapping or multiple mappings, however the +region given should not contain any unmapped space. + +@var{flags} can contain some options: + +@vtable @code + +@item MS_SYNC + +This flag makes sure the data is actually written @emph{to disk}. +Normally @code{msync} only makes sure that accesses to a file with +conventional I/O reflect the recent changes. + +@item MS_ASYNC + +This tells @code{msync} to begin the synchronization, but not to wait for +it to complete. + +@c Linux also has MS_INVALIDATE, which I don't understand. + +@end vtable + +@code{msync} returns @math{0} for success and @math{-1} for +error. Errors include: + +@table @code + +@item EINVAL +An invalid region was given, or the @var{flags} were invalid. + +@item EFAULT +There is no existing mapping in at least part of the given region. + +@end table + +@end deftypefun + +@deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag}) + +This function can be used to change the size of an existing memory +area. @var{address} and @var{length} must cover a region entirely mapped +in the same @code{mmap} statement. A new mapping with the same +characteristics will be returned, but a with the length @var{new_length} +instead. + +One option is possible, @code{MREMAP_MAYMOVE}. If it is given in +@var{flags}, the system may remove the existing mapping and create a new +one of the desired length in another location. + +The address of the resulting mapping is returned, or @math{-1}. Possible +error codes include: + +This function is only available on a few systems. Except for performing +optional optimizations one should not rely on this function. +@table @code + +@item EFAULT +There is no existing mapping in at least part of the original region, or +the region covers two or more distinct mappings. + +@item EINVAL +The address given is misaligned or inappropriate. + +@item EAGAIN +The region has pages locked, and if extended it would exceed the +process's resource limit for locked pages. @xref{Limits on Resources}. + +@item ENOMEM +The region is private writable, and insufficent virtual memory is +available to extend it. Also, this error will occur if +@code{MREMAP_MAYMOVE} is not given and the extension would collide with +another mapped region. + +@end table +@end deftypefun + +Not all file descriptors may be mapped. Sockets, pipes, and most devices +only allow sequential access and do not fit into the mapping abstraction. +In addition, some regular files may not be mmapable, and older kernels may +not support mapping at all. Thus, programs using @code{mmap} should +have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU +Coding Standards}. + +@c XXX madvice documentation missing + @node Waiting for I/O @section Waiting for Input or Output @cindex waiting for input or output @@ -2336,7 +2674,7 @@ the file descriptor returned should be the next available one greater than or equal to this value. The return value from @code{fcntl} with this command is normally the value -of the new file descriptor. A return value of @code{-1} indicates an +of the new file descriptor. A return value of @math{-1} indicates an error. The following @code{errno} error conditions are defined for this command: @@ -2420,7 +2758,7 @@ The normal return value from @code{fcntl} with this command is a nonnegative number which can be interpreted as the bitwise OR of the individual flags (except that currently there is only one flag to use). -In case of an error, @code{fcntl} returns @code{-1}. The following +In case of an error, @code{fcntl} returns @math{-1}. The following @code{errno} error conditions are defined for this command: @table @code @@ -2443,7 +2781,7 @@ fcntl (@var{filedes}, F_SETFD, @var{new-flags}) @end smallexample The normal return value from @code{fcntl} with this command is an -unspecified value other than @code{-1}, which indicates an error. +unspecified value other than @math{-1}, which indicates an error. The flags and error conditions are the same as for the @code{F_GETFD} command. @end deftypevr @@ -2848,7 +3186,7 @@ individual flags. Since the file access modes are not single-bit values, you can mask off other bits in the returned flags with @code{O_ACCMODE} to compare them. -In case of an error, @code{fcntl} returns @code{-1}. The following +In case of an error, @code{fcntl} returns @math{-1}. The following @code{errno} error conditions are defined for this command: @table @code @@ -2873,7 +3211,7 @@ You can't change the access mode for the file in this way; that is, whether the file descriptor was opened for reading or writing. The normal return value from @code{fcntl} with this command is an -unspecified value other than @code{-1}, which indicates an error. The +unspecified value other than @math{-1}, which indicates an error. The error conditions are the same as for the @code{F_GETFL} command. @end deftypevr @@ -3012,7 +3350,7 @@ If no lock applies, the only change to the @var{lockp} structure is to update the @code{l_type} to a value of @code{F_UNLCK}. The normal return value from @code{fcntl} with this command is an -unspecified value other than @code{-1}, which is reserved to indicate an +unspecified value other than @math{-1}, which is reserved to indicate an error. The following @code{errno} error conditions are defined for this command: @@ -3043,9 +3381,9 @@ on that part is replaced with the new lock. You can remove a lock by specifying a lock type of @code{F_UNLCK}. If the lock cannot be set, @code{fcntl} returns immediately with a value -of @code{-1}. This function does not block waiting for other processes +of @math{-1}. This function does not block waiting for other processes to release locks. If @code{fcntl} succeeds, it return a value other -than @code{-1}. +than @math{-1}. The following @code{errno} error conditions are defined for this function: @@ -3213,7 +3551,7 @@ fcntl (@var{filedes}, F_SETOWN, @var{pid}) The @var{pid} argument should be a process ID. You can also pass a negative number whose absolute value is a process group ID. -The return value from @code{fcntl} with this command is @code{-1} +The return value from @code{fcntl} with this command is @math{-1} in case of error and some other value if successful. The following @code{errno} error conditions are defined for this command: @@ -3227,3 +3565,64 @@ There is no process or process group corresponding to @var{pid}. @end deftypevr @c ??? This section could use an example program. + +@node IOCTLs +@section Generic I/O Control operations +@cindex generic i/o control operations +@cindex IOCTLs + +The GNU system can handle most input/output operations on many different +devices and objects in terms of a few file primitives - @code{read}, +@code{write} and @code{lseek}. However, most devices also have a few +peculiar operations which do not fit into this model. Such as: + +@itemize @bullet + +@item +Changing the character font used on a terminal. + +@item +Telling a magnetic tape system to rewind or fast forward. (Since they +cannot move in byte increments, @code{lseek} is inapplicable). + +@item +Ejecting a disk from a drive. + +@item +Playing an audio track from a CD-ROM drive. + +@item +Maintaining routing tables for a network. + +@end itemize + +Although some such objects such as sockets and terminals +@footnote{Actually, the terminal-specific functions are implemented with +IOCTLs on many platforms.} have special functions of their own, it would +not be practical to create functions for all these cases. + +Instead these minor operations, known as @dfn{IOCTL}s, are assigned code +numbers and multiplexed through the @code{ioctl} function, defined in +@code{sys/ioctl.h}. The code numbers themselves are defined in many +different headers. + +@deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{}) + +The @code{ioctl} function performs the generic I/O operation +@var{command} on @var{filedes}. + +A third argument is usually present, either a single number or a pointer +to a structure. The meaning of this argument, the returned value, and +any error codes depends upon the command used. Often @math{-1} is +returned for a failure. + +@end deftypefun + +On some systems, IOCTLs used by different devices share the same numbers. +Thus, although use of an inappropriate IOCTL @emph{usually} only produces +an error, you should not attempt to use device-specific IOCTLs on an +unknown device. + +Most IOCTLs are OS-specific and/or only used in special system utilities, +and are thus beyond the scope of this document. For an example of the use +of an IOCTL, @xref{Out-of-Band Data}. diff --git a/manual/math.texi b/manual/math.texi index 10b326287e..4386c2fefc 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -870,9 +870,9 @@ singularity. @comment math.h @comment XPG -@deftypefun double lgamma_r (double @var{x}) -@deftypefunx float lgammaf_r (float @var{x}) -@deftypefunx {long double} lgammal_r (long double @var{x}) +@deftypefun double lgamma_r (double @var{x}, int *@var{signp}) +@deftypefunx float lgammaf_r (float @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 the intermediate result in the variable pointed to by @var{signp} instead of in the @var{signgam} global. diff --git a/manual/top-menu.texi b/manual/top-menu.texi index 2ad64aeec1..6ff8bd64d1 100644 --- a/manual/top-menu.texi +++ b/manual/top-menu.texi @@ -77,6 +77,26 @@ Introduction * Roadmap to the Manual:: Overview of the remaining chapters in this manual. +Standards and Portability + +* ISO C:: The international standard for the C + programming language. +* POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards + for operating systems. +* Berkeley Unix:: BSD and SunOS. +* SVID:: The System V Interface Description. +* XPG:: The X/Open Portability Guide. + +Using the Library + +* Header Files:: How to include the header files in your + programs. +* Macro Definitions:: Some functions in the library may really + be implemented as macros. +* Reserved Names:: The C standard reserves some names for + the library, and some for users. +* Feature Test Macros:: How to control what names are defined. + Error Reporting * Checking for Errors:: How errors are reported by library functions. @@ -99,6 +119,68 @@ Memory Allocation * Relocating Allocator:: Waste less memory, if you can tolerate automatic relocation of the blocks you get. +Unconstrained Allocation + +* Basic Allocation:: Simple use of @code{malloc}. +* Malloc Examples:: Examples of @code{malloc}. @code{xmalloc}. +* Freeing after Malloc:: Use @code{free} to free a block you + got with @code{malloc}. +* Changing Block Size:: Use @code{realloc} to make a block + bigger or smaller. +* Allocating Cleared Space:: Use @code{calloc} to allocate a + block and clear it. +* Efficiency and Malloc:: Efficiency considerations in use of + these functions. +* Aligned Memory Blocks:: Allocating specially aligned memory: + @code{memalign} and @code{valloc}. +* Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation + parameters. +* Heap Consistency Checking:: Automatic checking for errors. +* Hooks for Malloc:: You can use these hooks for debugging + programs that use @code{malloc}. +* Statistics of Malloc:: Getting information about how much + memory your program is using. +* Summary of Malloc:: Summary of @code{malloc} and related functions. + +Allocation Debugging + +* Tracing malloc:: How to install the tracing functionality. +* Using the Memory Debugger:: Example programs excerpts. +* Tips for the Memory Debugger:: Some more or less clever ideas. +* Interpreting the traces:: What do all these lines mean? + +Obstacks + +* Creating Obstacks:: How to declare an obstack in your program. +* Preparing for Obstacks:: Preparations needed before you can + use obstacks. +* Allocation in an Obstack:: Allocating objects in an obstack. +* Freeing Obstack Objects:: Freeing objects in an obstack. +* Obstack Functions:: The obstack functions are both + functions and macros. +* Growing Objects:: Making an object bigger by stages. +* Extra Fast Growing:: Extra-high-efficiency (though more + complicated) growing objects. +* Status of an Obstack:: Inquiries about the status of an obstack. +* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. +* Obstack Chunks:: How obstacks obtain and release chunks; + efficiency considerations. +* Summary of Obstacks:: + +Variable Size Automatic + +* Alloca Example:: Example of using @code{alloca}. +* Advantages of Alloca:: Reasons to use @code{alloca}. +* Disadvantages of Alloca:: Reasons to avoid @code{alloca}. +* GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative + method of allocating dynamically and + freeing automatically. + +Relocating Allocator + +* Relocator Concepts:: How to understand relocating allocation. +* Using Relocator:: Functions for relocating allocation. + Character Handling * Classification of Characters:: Testing whether characters are @@ -123,6 +205,11 @@ String and Array Utilities * Encode Binary Data:: Encoding and Decoding of Binary Data. * Argz and Envz Vectors:: Null-separated string vectors. +Argz and Envz Vectors + +* Argz Functions:: Operations on argz vectors. +* Envz Functions:: Additional operations on environment vectors. + Extended Characters * Extended Char Intro:: Multibyte codes versus wide characters. @@ -150,11 +237,41 @@ Locales * Numeric Formatting:: How to format numbers according to the chosen locale. +Numeric Formatting + +* General Numeric:: Parameters for formatting numbers and + currency amounts. +* Currency Symbol:: How to print the symbol that identifies an + amount of money (e.g. @samp{$}). +* Sign of Money Amount:: How to print the (positive or negative) sign + for a monetary amount, if one exists. + Message Translation * Message catalogs a la X/Open:: The @code{catgets} family of functions. * The Uniforum approach:: The @code{gettext} family of functions. +Message catalogs a la X/Open + +* The catgets Functions:: The @code{catgets} function family. +* The message catalog files:: Format of the message catalog files. +* The gencat program:: How to generate message catalogs files which + can be used by the functions. +* Common Usage:: How to use the @code{catgets} interface. + +The Uniforum approach + +* Message catalogs with gettext:: The @code{gettext} family of functions. +* Helper programs for gettext:: Programs to handle message catalogs + for @code{gettext}. + +Message catalogs with gettext + +* Translation with gettext:: What has to be done to translate a message. +* Locating gettext catalog:: How to determine which catalog to be used. +* Using gettextized software:: The possibilities of the user to influence + the way @code{gettext} works. + Searching and Sorting * Comparison Functions:: Defining how to compare two objects. @@ -176,11 +293,48 @@ Pattern Matching arithmetic, and wildcards. This is what the shell does with shell commands. +Globbing + +* Calling Glob:: Basic use of @code{glob}. +* Flags for Globbing:: Flags that enable various options in @code{glob}. +* More Flags for Globbing:: GNU specific extensions to @code{glob}. + +Regular Expressions + +* POSIX Regexp Compilation:: Using @code{regcomp} to prepare to match. +* Flags for POSIX Regexps:: Syntax variations for @code{regcomp}. +* Matching POSIX Regexps:: Using @code{regexec} to match the compiled + pattern that you get from @code{regcomp}. +* Regexp Subexpressions:: Finding which parts of the string were matched. +* Subexpression Complications:: Find points of which parts were matched. +* Regexp Cleanup:: Freeing storage; reporting errors. + +Word Expansion + +* Expansion Stages:: What word expansion does to a string. +* Calling Wordexp:: How to call @code{wordexp}. +* Flags for Wordexp:: Options you can enable in @code{wordexp}. +* Wordexp Example:: A sample program that does word expansion. + I/O Overview * I/O Concepts:: Some basic information and terminology. * File Names:: How to refer to a file. +I/O Concepts + +* Streams and File Descriptors:: The GNU Library provides two ways + to access the contents of files. +* File Position:: The number of bytes from the + beginning of the file. + +File Names + +* Directories:: Directories contain entries for files. +* File Name Resolution:: A file name specifies how to look up a file. +* File Name Errors:: Error conditions relating to file names. +* File Name Portability:: File name portability and syntax issues. + I/O on Streams * Streams:: About the data type representing a stream. @@ -207,6 +361,83 @@ I/O on Streams to an open file. * Formatted Messages:: Print strictly formatted messages. +Unreading + +* Unreading Idea:: An explanation of unreading with pictures. +* How Unread:: How to call @code{ungetc} to do unreading. + +Formatted Output + +* Formatted Output Basics:: Some examples to get you started. +* Output Conversion Syntax:: General syntax of conversion + specifications. +* Table of Output Conversions:: Summary of output conversions and + what they do. +* Integer Conversions:: Details about formatting of integers. +* Floating-Point Conversions:: Details about formatting of + floating-point numbers. +* Other Output Conversions:: Details about formatting of strings, + characters, pointers, and the like. +* Formatted Output Functions:: Descriptions of the actual functions. +* Dynamic Output:: Functions that allocate memory for the output. +* Variable Arguments Output:: @code{vprintf} and friends. +* Parsing a Template String:: What kinds of args does a given template + call for? +* Example of Parsing:: Sample program using @code{parse_printf_format}. + +Customizing Printf + +* Registering New Conversions:: Using @code{register_printf_function} + to register a new output conversion. +* Conversion Specifier Options:: The handler must be able to get + the options specified in the + template when it is called. +* Defining the Output Handler:: Defining the handler and arginfo + functions that are passed as arguments + to @code{register_printf_function}. +* Printf Extension Example:: How to define a @code{printf} + handler function. +* Predefined Printf Handlers:: Predefined @code{printf} handlers. + +Formatted Input + +* Formatted Input Basics:: Some basics to get you started. +* Input Conversion Syntax:: Syntax of conversion specifications. +* Table of Input Conversions:: Summary of input conversions and what they do. +* Numeric Input Conversions:: Details of conversions for reading numbers. +* String Input Conversions:: Details of conversions for reading strings. +* Dynamic String Input:: String conversions that @code{malloc} the buffer. +* Other Input Conversions:: Details of miscellaneous other conversions. +* Formatted Input Functions:: Descriptions of the actual functions. +* Variable Arguments Input:: @code{vscanf} and friends. + +Stream Buffering + +* Buffering Concepts:: Terminology is defined here. +* Flushing Buffers:: How to ensure that output buffers are flushed. +* Controlling Buffering:: How to specify what kind of buffering to use. + +Other Kinds of Streams + +* String Streams:: Streams that get data from or put data in + a string or memory buffer. +* Obstack Streams:: Streams that store data in an obstack. +* Custom Streams:: Defining your own streams with an arbitrary + input data source and/or output data sink. + +Custom Streams + +* Streams and Cookies:: The @dfn{cookie} records where to fetch or + store data that is read or written. +* Hook Functions:: How you should define the four @dfn{hook + functions} that a custom stream needs. + +Formatted Messages + +* Printing Formatted Messages:: The @code{fmtmsg} function. +* Adding Severity Classes:: Add more severity classes. +* Example:: How to use @code{fmtmsg} and @code{addseverity}. + Low-Level I/O * Opening and Closing Files:: How to open and close file @@ -219,6 +450,8 @@ Low-Level I/O or vice-versa. * Stream/Descriptor Precautions:: Precautions needed if you use both descriptors and streams. +* Scatter-Gather:: Fast I/O to discontinous buffers. +* Memory-mapped I/O:: Using files like memory. * Waiting for I/O:: How to check for input or output on multiple file descriptors. * Synchronizing I/O:: Making sure all I/O actions completed. @@ -236,6 +469,29 @@ Low-Level I/O file locking. * Interrupt Input:: Getting an asynchronous signal when input arrives. +* IOCTLs:: Generic I/O Control operations. + +Stream/Descriptor Precautions + +* Linked Channels:: Dealing with channels sharing a file position. +* Independent Channels:: Dealing with separately opened, unlinked channels. +* Cleaning Streams:: Cleaning a stream makes it safe to use + another channel. + +Asynchronous I/O + +* Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. +* Status of AIO Operations:: Getting the Status of AIO Operations. +* Synchronizing AIO Operations:: Getting into a consistent state. +* Cancel AIO Operations:: Cancelation of AIO Operations. +* Configuration of AIO:: How to optimize the AIO implementation. + +File Status Flags + +* Access Modes:: Whether the descriptor can read or write. +* Open-time Flags:: Details of @code{open}. +* Operating Modes:: Special modes to control I/O operations. +* Getting File Status Flags:: Fetching and changing these flags. File System Interface @@ -254,6 +510,36 @@ File System Interface * Making Special Files:: How to create special files. * Temporary Files:: Naming and creating temporary files. +Accessing Directories + +* Directory Entries:: Format of one directory entry. +* Opening a Directory:: How to open a directory stream. +* Reading/Closing Directory:: How to read directory entries from the stream. +* Simple Directory Lister:: A very simple directory listing program. +* Random Access Directory:: Rereading part of the directory + already read with the same stream. +* Scanning Directory Content:: Get entries for user selected subset of + contents in given directory. +* Simple Directory Lister Mark II:: Revised version of the program. + +File Attributes + +* Attribute Meanings:: The names of the file attributes, + and what their values mean. +* Reading Attributes:: How to read the attributes of a file. +* Testing File Type:: Distinguishing ordinary files, + directories, links... +* File Owner:: How ownership for new files is determined, + and how to change it. +* Permission Bits:: How information about a file's access + mode is stored. +* Access Permission:: How the system decides who can access a file. +* Setting Permissions:: How permissions for new files are assigned, + and how to change them. +* Testing File Access:: How to find out if your process can + access a file. +* File Times:: About the time attributes of a file. + Pipes and FIFOs * Creating a Pipe:: Making a pipe with the @code{pipe} function. @@ -280,6 +566,82 @@ Sockets * Socket Options:: Miscellaneous low-level socket options. * Networks Database:: Accessing the database of network names. +Socket Addresses + +* Address Formats:: About @code{struct sockaddr}. +* Setting Address:: Binding an address to a socket. +* Reading Address:: Reading the address of a socket. + +Local Namespace + +* Concepts: Local Namespace Concepts. What you need to understand. +* Details: Local Namespace Details. Address format, symbolic names, etc. +* Example: Local Socket Example. Example of creating a socket. + +Internet Namespace + +* Internet Address Formats:: How socket addresses are specified in the + Internet namespace. +* Host Addresses:: All about host addresses of internet host. +* Protocols Database:: Referring to protocols by name. +* Ports:: Internet port numbers. +* Services Database:: Ports may have symbolic names. +* Byte Order:: Different hosts may use different byte + ordering conventions; you need to + canonicalize host address and port number. +* Inet Example:: Putting it all together. + +Host Addresses + +* Abstract Host Addresses:: What a host number consists of. +* Data type: Host Address Data Type. Data type for a host number. +* Functions: Host Address Functions. Functions to operate on them. +* Names: Host Names. Translating host names to host numbers. + +Open/Close Sockets + +* Creating a Socket:: How to open a socket. +* Closing a Socket:: How to close a socket. +* Socket Pairs:: These are created like pipes. + +Connections + +* Connecting:: What the client program must do. +* Listening:: How a server program waits for requests. +* Accepting Connections:: What the server does when it gets a request. +* Who is Connected:: Getting the address of the + other side of a connection. +* Transferring Data:: How to send and receive data. +* Byte Stream Example:: An example program: a client for communicating + over a byte stream socket in the Internet namespace. +* Server Example:: A corresponding server program. +* Out-of-Band Data:: This is an advanced feature. + +Transferring Data + +* Sending Data:: Sending data with @code{send}. +* Receiving Data:: Reading data with @code{recv}. +* Socket Data Options:: Using @code{send} and @code{recv}. + +Datagrams + +* Sending Datagrams:: Sending packets on a datagram socket. +* Receiving Datagrams:: Receiving packets on a datagram socket. +* Datagram Example:: An example program: packets sent over a + datagram socket in the local namespace. +* Example Receiver:: Another program, that receives those packets. + +Inetd + +* Inetd Servers:: +* Configuring Inetd:: + +Socket Options + +* Socket Option Functions:: The basic functions for setting and getting + socket options. +* Socket-Level Options:: Details of the options at the socket level. + Low-Level Terminal Interface * Is It a Terminal:: How to determine if a file is a terminal @@ -294,6 +656,40 @@ Low-Level Terminal Interface * Noncanon Example:: How to read single characters without echo. * Pseudo-Terminals:: How to open a pseudo-terminal. +Terminal Modes + +* Mode Data Types:: The data type @code{struct termios} and + related types. +* Mode Functions:: Functions to read and set the terminal + attributes. +* Setting Modes:: The right way to set terminal attributes + reliably. +* Input Modes:: Flags controlling low-level input handling. +* Output Modes:: Flags controlling low-level output handling. +* Control Modes:: Flags controlling serial port behavior. +* Local Modes:: Flags controlling high-level input handling. +* Line Speed:: How to read and set the terminal line speed. +* Special Characters:: Characters that have special effects, + and how to change them. +* Noncanonical Input:: Controlling how long to wait for input. + +Special Characters + +* Editing Characters:: Special characters that terminate lines and + delete text, and other editing functions. +* Signal Characters:: Special characters that send or raise signals + to or for certain classes of processes. +* Start/Stop Characters:: Special characters that suspend or resume + suspended output. +* Other Special:: Other special characters for BSD systems: + they can discard output, and print status. + +Pseudo-Terminals + +* Allocation:: Allocating a pseudo terminal. +* Pseudo-Terminal Pairs:: How to open both sides of a + pseudo-terminal in a single operation. + Mathematics * Mathematical Constants:: Precise numeric values for often-used @@ -307,6 +703,12 @@ Mathematics numbers. * FP Function Optimizations:: Fast code or small code. +Pseudo-Random Numbers + +* ISO Random:: @code{rand} and friends. +* BSD Random:: @code{random} and friends. +* SVID Random:: @code{drand48} and friends. + Arithmetic * Floating Point Numbers:: Basic concepts. IEEE 754. @@ -321,6 +723,29 @@ Arithmetic * Parsing of Numbers:: Converting strings to numbers. * System V Number Conversion:: An archaic way to convert numbers to strings. +Floating Point Errors + +* FP Exceptions:: IEEE 754 math exceptions and how to detect them. +* Infinity and NaN:: Special values returned by calculations. +* Status bit operations:: Checking for exceptions after the fact. +* Math Error Reporting:: How the math functions report errors. + +Arithmetic Functions + +* Absolute Value:: Absolute values of integers and floats. +* Normalization Functions:: Extracting exponents and putting them back. +* Rounding Functions:: Rounding floats to integers. +* Remainder Functions:: Remainders on division, precisely defined. +* FP Bit Twiddling:: Sign bit adjustment. Adding epsilon. +* FP Comparison Functions:: Comparisons without risk of exceptions. +* Misc FP Arithmetic:: Max, min, positive difference, multiply-add. + +Parsing of Numbers + +* Parsing of Integers:: Functions for conversion of integer values. +* Parsing of Floats:: Functions for conversion of floating-point + values. + Date and Time * Processor Time:: Measures processor time used by a program. @@ -331,6 +756,22 @@ Date and Time * Limits on Resources:: Specifying limits on resource usage. * Priority:: Reading or setting process run priority. +Processor Time + +* Basic CPU Time:: The @code{clock} function. +* Detailed CPU Time:: The @code{times} function. + +Calendar Time + +* Simple Calendar Time:: Facilities for manipulating calendar time. +* High-Resolution Calendar:: A time representation with greater precision. +* Broken-down Time:: Facilities for manipulating local time. +* Formatting Date and Time:: Converting times to strings. +* TZ Variable:: How users specify the time zone. +* Time Zone Functions:: Functions to examine or specify the time zone. +* Time Functions Example:: An example program showing use of some of + the time functions. + Non-Local Exits * Intro: Non-Local Intro. When and how to use these facilities. @@ -355,6 +796,91 @@ Signal Handling * BSD Signal Handling:: Additional functions for backward compatibility with BSD. +Concepts of Signals + +* Kinds of Signals:: Some examples of what can cause a signal. +* Signal Generation:: Concepts of why and how signals occur. +* Delivery of Signal:: Concepts of what a signal does to the + process. + +Standard Signals + +* Program Error Signals:: Used to report serious program errors. +* Termination Signals:: Used to interrupt and/or terminate the + program. +* Alarm Signals:: Used to indicate expiration of timers. +* Asynchronous I/O Signals:: Used to indicate input is available. +* Job Control Signals:: Signals used to support job control. +* Operation Error Signals:: Used to report operational system errors. +* Miscellaneous Signals:: Miscellaneous Signals. +* Signal Messages:: Printing a message describing a signal. + +Signal Actions + +* Basic Signal Handling:: The simple @code{signal} function. +* Advanced Signal Handling:: The more powerful @code{sigaction} function. +* Signal and Sigaction:: How those two functions interact. +* Sigaction Function Example:: An example of using the sigaction function. +* Flags for Sigaction:: Specifying options for signal handling. +* Initial Signal Actions:: How programs inherit signal actions. + +Defining Handlers + +* Handler Returns:: Handlers that return normally, and what + this means. +* Termination in Handler:: How handler functions terminate a program. +* Longjmp in Handler:: Nonlocal transfer of control out of a + signal handler. +* Signals in Handler:: What happens when signals arrive while + the handler is already occupied. +* Merged Signals:: When a second signal arrives before the + first is handled. +* Nonreentrancy:: Do not call any functions unless you know they + are reentrant with respect to signals. +* Atomic Data Access:: A single handler can run in the middle of + reading or writing a single object. + +Atomic Data Access + +* Non-atomic Example:: A program illustrating interrupted access. +* Types: Atomic Types. Data types that guarantee no interruption. +* Usage: Atomic Usage. Proving that interruption is harmless. + +Generating Signals + +* Signaling Yourself:: A process can send a signal to itself. +* Signaling Another Process:: Send a signal to another process. +* Permission for kill:: Permission for using @code{kill}. +* Kill Example:: Using @code{kill} for Communication. + +Blocking Signals + +* Why Block:: The purpose of blocking signals. +* Signal Sets:: How to specify which signals to + block. +* Process Signal Mask:: Blocking delivery of signals to your + process during normal execution. +* Testing for Delivery:: Blocking to Test for Delivery of + a Signal. +* Blocking for Handler:: Blocking additional signals while a + handler is being run. +* Checking for Pending Signals:: Checking for Pending Signals +* Remembering a Signal:: How you can get almost the same + effect as blocking a signal, by + handling it and setting a flag + to be tested later. + +Waiting for a Signal + +* Using Pause:: The simple way, using @code{pause}. +* Pause Problems:: Why the simple way is often not very good. +* Sigsuspend:: Reliably waiting for a specific signal. + +BSD Signal Handling + +* BSD Handler:: BSD Function to Establish a Handler. +* Blocking in BSD:: BSD Functions for Blocking Signals. + Process Startup * Program Arguments:: Parsing your program's command-line arguments. @@ -363,6 +889,37 @@ Process Startup * Program Termination:: How to cause a process to terminate and return status information to its parent. +Program Arguments + +* Argument Syntax:: By convention, options start with a hyphen. +* Parsing Program Arguments:: Ways to parse program options and arguments. + +Parsing Program Arguments + +* Getopt:: Parsing program options using @code{getopt}. +* Argp:: Parsing program options using @code{argp_parse}. +* Suboptions:: Some programs need more detailed options. +* Suboptions Example:: This shows how it could be done for @code{mount}. + +Environment Variables + +* Environment Access:: How to get and set the values of + environment variables. +* Standard Environment:: These environment variables have + standard interpretations. + +Program Termination + +* Normal Termination:: If a program calls @code{exit}, a + process terminates normally. +* Exit Status:: The @code{exit status} provides information + about why the process terminated. +* Cleanups on Exit:: A process can run its own cleanup + functions upon normal termination. +* Aborting a Program:: The @code{abort} function causes + abnormal program termination. +* Termination Internals:: What happens when a process terminates. + Processes * Running a Command:: The easy way to run another program. @@ -386,6 +943,24 @@ Job Control * Implementing a Shell:: What a shell must do to implement job control. * Functions for Job Control:: Functions to control process groups. +Implementing a Shell + +* Data Structures:: Introduction to the sample shell. +* Initializing the Shell:: What the shell must do to take + responsibility for job control. +* Launching Jobs:: Creating jobs to execute commands. +* Foreground and Background:: Putting a job in foreground of background. +* Stopped and Terminated Jobs:: Reporting job status. +* Continuing Stopped Jobs:: How to continue a stopped job in + the foreground or background. +* Missing Pieces:: Other parts of the shell. + +Functions for Job Control + +* Identifying the Terminal:: Determining the controlling terminal's name. +* Process Group Functions:: Functions for manipulating process groups. +* Terminal Access Functions:: Functions for controlling terminal access. + Name Service Switch * NSS Basics:: What is this NSS good for. @@ -393,6 +968,26 @@ Name Service Switch * NSS Module Internals:: How does it work internally. * Extending NSS:: What to do to add services or databases. +NSS Configuration File + +* Services in the NSS configuration:: Service names in the NSS configuration. +* Actions in the NSS configuration:: React appropriately to the lookup result. +* Notes on NSS Configuration File:: Things to take care about while + configuring NSS. + +NSS Module Internals + +* NSS Module Names:: Construction of the interface function of + the NSS modules. +* NSS Modules Interface:: Programming interface in the NSS module + functions. + +Extending NSS + +* Adding another Service to NSS:: What is to do to add a new service. +* NSS Module Function Internals:: Guidelines for writing new NSS + service functions. + Users and Groups * User and Group IDs:: Each user has a unique numeric ID; @@ -424,6 +1019,34 @@ Users and Groups inquiry functions. * Netgroup Database:: Functions for accessing the netgroup database. +User Accounting Database + +* Manipulating the Database:: Scanning and modifying the user + accounting database. +* XPG Functions:: A standardized way for doing the same thing. +* Logging In and Out:: Functions from BSD that modify the user + accounting database. + +User Database + +* User Data Structure:: What each user record contains. +* Lookup User:: How to look for a particular user. +* Scanning All Users:: Scanning the list of all users, one by one. +* Writing a User Entry:: How a program can rewrite a user's record. + +Group Database + +* Group Data Structure:: What each group record contains. +* Lookup Group:: How to look for a particular group. +* Scanning All Groups:: Scanning the list of all groups. + +Netgroup Database + +* Netgroup Data:: Data in the Netgroup database and where + it comes from. +* Lookup Netgroup:: How to look for a particular netgroup. +* Netgroup Membership:: How to test for netgroup membership. + System Information * Host Identification:: Determining the name of the machine. @@ -455,6 +1078,13 @@ System Configuration * String Parameters:: Getting the default search path. +Sysconf + +* Sysconf Definition:: Detailed specifications of @code{sysconf}. +* Constants for Sysconf:: The list of parameters @code{sysconf} can read. +* Examples of Sysconf:: How to use @code{sysconf} and the parameter + macros properly together. + POSIX Threads * Basic Thread Operations:: Creating, terminating, and waiting for threads. @@ -481,6 +1111,41 @@ Language Features * Important Data Types:: Data types for object sizes. * Data Type Measurements:: Parameters of data type representations. +Variadic Functions + +* Why Variadic:: Reasons for making functions take + variable arguments. +* How Variadic:: How to define and call variadic functions. +* Variadic Example:: A complete example. + +How Variadic + +* Variadic Prototypes:: How to make a prototype for a function + with variable arguments. +* Receiving Arguments:: Steps you must follow to access the + optional argument values. +* How Many Arguments:: How to decide whether there are more arguments. +* Calling Variadics:: Things you need to know about calling + variable arguments functions. +* Argument Macros:: Detailed specification of the macros + for accessing variable arguments. +* Old Varargs:: The pre-ISO way of defining variadic functions. + +Data Type Measurements + +* Width of Type:: How many bits does an integer type hold? +* Range of Type:: What are the largest and smallest values + that an integer type can hold? +* Floating Type Macros:: Parameters that measure the floating point types. +* Structure Measurement:: Getting measurements on structure types. + +Floating Type Macros + +* Floating Point Concepts:: Definitions of terminology. +* Floating Point Parameters:: Details of specific macros. +* IEEE Floating Point:: The measurements for one common + representation. + Installation * Tools for Installation:: We recommend using these tools to build. @@ -496,4 +1161,10 @@ Maintenance to the GNU C library. * Porting:: How to port the GNU C library to a new machine or operating system. + +Porting + +* Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. +* Porting to Unix:: Porting the library to an average + Unix-like system. @end menu |