diff --git a/ap/libc/glibc/glibc-2.23/manual/Makefile b/ap/libc/glibc/glibc-2.23/manual/Makefile
new file mode 100644
index 0000000..f2f694f
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/Makefile
@@ -0,0 +1,195 @@
+# Copyright (C) 1992-2016 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+
+# The GNU C Library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+
+# The GNU C Library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with the GNU C Library; if not, see
+# <http://www.gnu.org/licenses/>.
+
+# Makefile for the GNU C Library manual.
+
+subdir := manual
+
+include ../Makeconfig
+
+.PHONY: dvi pdf info html
+
+dvi: $(objpfx)libc.dvi
+pdf: $(objpfx)libc.pdf
+
+TEXI2DVI = texi2dvi
+TEXI2PDF = texi2dvi --pdf
+
+ifneq ($(strip $(MAKEINFO)),:)
+info: $(objpfx)libc.info
+endif
+
+chapters = $(addsuffix .texi, \
+		       intro errno memory ctype string charset locale	\
+		       message search pattern io stdio llio filesys	\
+		       pipe socket terminal syslog math arith time	\
+		       resource setjmp signal startup process ipc job	\
+		       nss users sysinfo conf crypt debug threads probes)
+add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
+appendices = lang.texi header.texi install.texi maint.texi platform.texi \
+	     contrib.texi
+licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi
+
+-include $(objpfx)texis
+$(objpfx)texis: texis.awk $(chapters) $(add-chapters) $(appendices) $(licenses)
+	$(make-target-directory)
+	$(AWK) -f $^ > $@.T
+	mv -f $@.T $@
+
+nonexamples = $(filter-out $(add-chapters) %.c.texi, $(texis))
+examples = $(filter-out $(foreach d, $(add-ons), ../$d/%.c.texi), \
+			$(filter %.c.texi, $(texis)))
+
+# Generated files directly included from libc.texinfo.
+libc-texi-generated = chapters.texi top-menu.texi dir-add.texi \
+		      libm-err.texi version.texi pkgvers.texi
+
+# Add path to build dir for generated files
+texis-path := $(filter-out $(libc-texi-generated) summary.texi $(examples), \
+				$(texis)) 				    \
+	 $(addprefix $(objpfx),$(filter $(libc-texi-generated) summary.texi \
+					$(examples), $(texis)))
+
+# Kludge: implicit rule so Make knows the one command does it all.
+chapters.% top-menu.%: libc-texinfo.sh $(texis-path) Makefile
+	AWK=$(AWK) $(SHELL) $< $(objpfx) \
+				'$(chapters)' \
+			       '$(add-chapters)' \
+			       '$(appendices) $(licenses)'
+
+
+$(objpfx)libc.dvi $(objpfx)libc.pdf $(objpfx)libc.info: \
+	$(addprefix $(objpfx),$(libc-texi-generated))
+$(objpfx)libc.dvi $(objpfx)libc.pdf: texinfo.tex
+
+html: $(objpfx)libc/index.html
+$(objpfx)libc/index.html: $(addprefix $(objpfx),$(libc-texi-generated))
+	$(MAKEINFO) -P $(objpfx) -o $(objpfx)libc --html libc.texinfo
+
+# Generate the summary from the Texinfo source files for each chapter.
+$(objpfx)summary.texi: $(objpfx)stamp-summary ;
+$(objpfx)stamp-summary: summary.awk $(filter-out $(objpfx)summary.texi, \
+					$(texis-path))
+	$(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path))
+	$(AWK) -f $^ | sort -t'' -df -k 1,1 | tr '\014' '\012' \
+		> $(objpfx)summary-tmp
+	$(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi
+	touch $@
+
+# Generate a file which can be added to the `dir' content to provide direct
+# access to the documentation of the function, variables, and other
+# definitions.
+$(objpfx)dir-add.texi: xtract-typefun.awk $(texis-path)
+	(echo "@dircategory GNU C library functions and macros";	\
+	 echo "@direntry";						\
+	 $(AWK) -f $^ | sort;						\
+	 echo "@end direntry") > $@.new
+	mv -f $@.new $@
+
+# The table with the math errors is generated.
+$(objpfx)libm-err.texi: $(objpfx)stamp-libm-err
+$(objpfx)stamp-libm-err: libm-err-tab.pl $(wildcard $(foreach dir,$(sysdirs),\
+						     $(dir)/libm-test-ulps))
+	pwd=`pwd`; \
+	$(PERL) $< $$pwd/.. > $(objpfx)libm-err-tmp
+	$(move-if-change) $(objpfx)libm-err-tmp $(objpfx)libm-err.texi
+	touch $@
+
+# Package version and bug reporting URL.
+$(objpfx)pkgvers.texi: $(objpfx)stamp-pkgvers ;
+$(objpfx)stamp-pkgvers: $(common-objpfx)config.make
+	echo "@ifclear PKGVERS" > $(objpfx)pkgvers-tmp
+	echo "@set PKGVERS" >> $(objpfx)pkgvers-tmp
+	echo "@set PKGVERSION $(PKGVERSION_TEXI)" >> $(objpfx)pkgvers-tmp
+	if [ "$(PKGVERSION_TEXI)" = "(GNU libc) " ]; then \
+	  echo "@set PKGVERSION_DEFAULT" >> $(objpfx)pkgvers-tmp; \
+	fi
+	echo "@set REPORT_BUGS_TO $(REPORT_BUGS_TEXI)" >> $(objpfx)pkgvers-tmp
+	echo "@end ifclear" >> $(objpfx)pkgvers-tmp
+	$(move-if-change) $(objpfx)pkgvers-tmp $(objpfx)pkgvers.texi
+	touch $@
+
+# Generate a file with the version number.
+$(objpfx)version.texi: $(objpfx)stamp-version ;
+$(objpfx)stamp-version: $(common-objpfx)config.make
+	echo "@set VERSION $(version)" > $(objpfx)version-tmp
+	$(move-if-change) $(objpfx)version-tmp $(objpfx)version.texi
+	touch $@
+
+# Generate Texinfo files from the C source for the example programs.
+$(objpfx)%.c.texi: examples/%.c
+	sed -e '1,/^\*\/$$/d'				\
+	    -e 's,[{}],@&,g'				\
+	    -e 's,/\*\(@.*\)\*/,\1,g'			\
+	    -e 's,/\*  *,/* @r{,g' -e 's,  *\*/,} */,'	\
+	    -e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/g'\
+	    $< | expand > $@.new
+	mv -f $@.new $@
+
+$(objpfx)%.info: %.texinfo
+	LANGUAGE=C LC_ALL=C $(MAKEINFO) -P $(objpfx) --output=$@ $<
+
+$(objpfx)%.dvi: %.texinfo
+	cd $(objpfx);$(TEXI2DVI) -I $(shell cd $(<D) && pwd) --output=$@ \
+				$(shell cd $(<D) && pwd)/$<
+
+$(objpfx)%.pdf: %.texinfo
+	cd $(objpfx);$(TEXI2PDF) -I $(shell cd $(<D) && pwd) --output=$@ \
+				$(shell cd $(<D) && pwd)/$<
+
+
+# Distribution.
+minimal-dist = summary.awk texis.awk tsort.awk libc-texinfo.sh libc.texinfo \
+	       libm-err.texi stamp-libm-err check-safety.sh		    \
+	       $(filter-out summary.texi, $(nonexamples))		    \
+	       $(patsubst %.c.texi,examples/%.c, $(examples))
+
+indices = cp fn pg tp vr ky
+generated-dirs += libc
+generated += libc.dvi libc.pdf libc.tmp libc.info*			      \
+	     stubs							      \
+	     texis summary.texi stamp-summary *.c.texi			      \
+	     $(foreach index,$(indices),libc.$(index) libc.$(index)s)	      \
+	     libc.log libc.aux libc.toc					      \
+	     $(libc-texi-generated)					      \
+	     stamp-libm-err stamp-version
+
+include ../Rules
+
+.PHONY: install subdir_install install-data
+install-data subdir_install: install
+# libm-err.texi generation requires perl.
+ifneq ($(PERL),no)
+ifneq ($(strip $(MAKEINFO)),:)
+install: $(inst_infodir)/libc.info
+	@if $(SHELL) -c '$(INSTALL_INFO) --version' >/dev/null 2>&1; then \
+	 test -f $(inst_infodir)/dir || $(INSTALL_DATA) dir $(inst_infodir);\
+	 $(INSTALL_INFO) --info-dir=$(inst_infodir) $(inst_infodir)/libc.info;\
+	else : ; fi
+endif
+endif
+# Catchall implicit rule for other installation targets from the parent.
+install-%: ;
+
+$(inst_infodir)/libc.info: $(objpfx)libc.info
+	$(make-target-directory)
+	for file in $<*; do \
+	  $(INSTALL_DATA) $$file $(@D)/; \
+	done
+
+TAGS: $(minimal-dist)
+	$(ETAGS) -o $@ $^
diff --git a/ap/libc/glibc/glibc-2.23/manual/argp.texi b/ap/libc/glibc/glibc-2.23/manual/argp.texi
new file mode 100644
index 0000000..dae6809
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/argp.texi
@@ -0,0 +1,1349 @@
+@node Argp, Suboptions, Getopt, Parsing Program Arguments
+@need 5000
+@section Parsing Program Options with Argp
+@cindex argp (program argument parser)
+@cindex argument parsing with argp
+@cindex option parsing with argp
+
+@dfn{Argp} is an interface for parsing unix-style argument vectors.
+@xref{Program Arguments}.
+
+Argp provides features unavailable in the more commonly used
+@code{getopt} interface.  These features include automatically producing
+output in response to the @samp{--help} and @samp{--version} options, as
+described in the GNU coding standards.  Using argp makes it less likely
+that programmers will neglect to implement these additional options or
+keep them up to date.
+
+Argp also provides the ability to merge several independently defined
+option parsers into one, mediating conflicts between them and making the
+result appear seamless.  A library can export an argp option parser that
+user programs might employ in conjunction with their own option parsers,
+resulting in less work for the user programs.  Some programs may use only
+argument parsers exported by libraries, thereby achieving consistent and
+efficient option-parsing for abstractions implemented by the libraries.
+
+@pindex argp.h
+The header file @file{<argp.h>} should be included to use argp.
+
+@subsection The @code{argp_parse} Function
+
+The main interface to argp is the @code{argp_parse} function.  In many
+cases, calling @code{argp_parse} is the only argument-parsing code
+needed in @code{main}.
+@xref{Program Arguments}.
+
+@comment argp.h
+@comment GNU
+@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Optionally alloca()tes standard help options, initializes the parser,
+@c then parses individual args in a loop, and then finalizes.
+@c  parser_init
+@c   calc_sizes ok
+@c    option_is_end ok
+@c   malloc @ascuheap @acsmem
+@c   parser_convert @mtslocale
+@c    convert_options @mtslocale
+@c     option_is_end ok
+@c     option_is_short ok
+@c      isprint, but locale may change within the loop
+@c     find_long_option ok
+@c   group_parse
+@c    group->parser (from argp->parser)
+@c  parser_parse_next
+@c   getopt_long(_only)_r many issues, same as non_r minus @mtasurace
+@c   parser_parse_arg
+@c    group_parse dup
+@c   parser_parse_opt
+@c    group_parse dup
+@c    argp_error dup @mtasurace:argpbuf @mtsenv @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c    dgettext (bad key error) dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c  parser_finalize
+@c   group_parse
+@c   fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem]
+@c   dgettext dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c   arg_state_help
+@c   free dup @ascuhelp @acsmem
+The @code{argp_parse} function parses the arguments in @var{argv}, of
+length @var{argc}, using the argp parser @var{argp}.  @xref{Argp
+Parsers}.  Passing a null pointer for @var{argp} is the same as using
+a @code{struct argp} containing all zeros.
+
+@var{flags} is a set of flag bits that modify the parsing behavior.
+@xref{Argp Flags}.  @var{input} is passed through to the argp parser
+@var{argp}, and has meaning defined by @var{argp}.  A typical usage is
+to pass a pointer to a structure which is used for specifying
+parameters to the parser and passing back the results.
+
+Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
+in @var{flags}, calling @code{argp_parse} may result in the program
+exiting.  This behavior is true if an error is detected, or when an
+unknown option is encountered.  @xref{Program Termination}.
+
+If @var{arg_index} is non-null, the index of the first unparsed option
+in @var{argv} is returned as a value.
+
+The return value is zero for successful parsing, or an error code
+(@pxref{Error Codes}) if an error is detected.  Different argp parsers
+may return arbitrary error codes, but the standard error codes are:
+@code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if
+an unknown option or option argument is encountered.
+@end deftypefun
+
+@menu
+* Globals: Argp Global Variables.  Global argp parameters.
+* Parsers: Argp Parsers.        Defining parsers for use with @code{argp_parse}.
+* Flags: Argp Flags.            Flags that modify the behavior of @code{argp_parse}.
+* Help: Argp Help.              Printing help messages when not parsing.
+* Examples: Argp Examples.      Simple examples of programs using argp.
+* Customization: Argp User Customization.
+                                Users may control the @samp{--help} output format.
+@end menu
+
+@node Argp Global Variables, Argp Parsers, , Argp
+@subsection Argp Global Variables
+
+These variables make it easy for user programs to implement the
+@samp{--version} option and provide a bug-reporting address in the
+@samp{--help} output.  These are implemented in argp by default.
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_version
+If defined or set by the user program to a non-zero value, then a
+@samp{--version} option is added when parsing with @code{argp_parse},
+which will print the @samp{--version} string followed by a newline and
+exit.  The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
+@end deftypevar
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_bug_address
+If defined or set by the user program to a non-zero value,
+@code{argp_program_bug_address} should point to a string that will be
+printed at the end of the standard output for the @samp{--help} option,
+embedded in a sentence that says @samp{Report bugs to @var{address}.}.
+@end deftypevar
+
+@need 1500
+@comment argp.h
+@comment GNU
+@defvar argp_program_version_hook
+If defined or set by the user program to a non-zero value, a
+@samp{--version} option is added when parsing with @code{arg_parse},
+which prints the program version and exits with a status of zero.  This
+is not the case if the @code{ARGP_NO_HELP} flag is used.  If the
+@code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is
+suppressed or modified, as when the argp parser is going to be used by
+other programs.
+
+It should point to a function with this type of signature:
+
+@smallexample
+void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+@xref{Argp Parsing State}, for an explanation of @var{state}.
+
+This variable takes precedence over @code{argp_program_version}, and is
+useful if a program has version information not easily expressed in a
+simple string.
+@end defvar
+
+@comment argp.h
+@comment GNU
+@deftypevar error_t argp_err_exit_status
+This is the exit status used when argp exits due to a parsing error.  If
+not defined or set by the user program, this defaults to:
+@code{EX_USAGE} from @file{<sysexits.h>}.
+@end deftypevar
+
+@node Argp Parsers, Argp Flags, Argp Global Variables, Argp
+@subsection Specifying Argp Parsers
+
+The first argument to the @code{argp_parse} function is a pointer to a
+@code{struct argp}, which is known as an @dfn{argp parser}:
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp}
+This structure specifies how to parse a given set of options and
+arguments, perhaps in conjunction with other argp parsers.  It has the
+following fields:
+
+@table @code
+@item const struct argp_option *options
+A pointer to a vector of @code{argp_option} structures specifying which
+options this argp parser understands; it may be zero if there are no
+options at all.  @xref{Argp Option Vectors}.
+
+@item argp_parser_t parser
+A pointer to a function that defines actions for this parser; it is
+called for each option parsed, and at other well-defined points in the
+parsing process.  A value of zero is the same as a pointer to a function
+that always returns @code{ARGP_ERR_UNKNOWN}.  @xref{Argp Parser
+Functions}.
+
+@item const char *args_doc
+If non-zero, a string describing what non-option arguments are called by
+this parser.  This is only used to print the @samp{Usage:} message.  If
+it contains newlines, the strings separated by them are considered
+alternative usage patterns and printed on separate lines.  Lines after
+the first are prefixed by @samp{ or: } instead of @samp{Usage:}.
+
+@item const char *doc
+If non-zero, a string containing extra text to be printed before and
+after the options in a long help message, with the two sections
+separated by a vertical tab (@code{'\v'}, @code{'\013'}) character.  By
+convention, the documentation before the options is just a short string
+explaining what the program does.  Documentation printed after the
+options describe behavior in more detail.
+
+@item const struct argp_child *children
+A pointer to a vector of @code{argp_child} structures.  This pointer
+specifies which additional argp parsers should be combined with this
+one.  @xref{Argp Children}.
+
+@item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
+If non-zero, a pointer to a function that filters the output of help
+messages.  @xref{Argp Help Filtering}.
+
+@item const char *argp_domain
+If non-zero, the strings used in the argp library are translated using
+the domain described by this string.  If zero, the current default domain
+is used.
+
+@end table
+@end deftp
+
+Of the above group, @code{options}, @code{parser}, @code{args_doc}, and
+the @code{doc} fields are usually all that are needed.  If an argp
+parser is defined as an initialized C variable, only the fields used
+need be specified in the initializer.  The rest will default to zero due
+to the way C structure initialization works.  This design is exploited in
+most argp structures; the most-used fields are grouped near the
+beginning, the unused fields left unspecified.
+
+@menu
+* Options: Argp Option Vectors.   Specifying options in an argp parser.
+* Argp Parser Functions::         Defining actions for an argp parser.
+* Children: Argp Children.        Combining multiple argp parsers.
+* Help Filtering: Argp Help Filtering.  Customizing help output for an argp parser.
+@end menu
+
+@node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
+@subsection Specifying Options in an Argp Parser
+
+The @code{options} field in a @code{struct argp} points to a vector of
+@code{struct argp_option} structures, each of which specifies an option
+that the argp parser supports.  Multiple entries may be used for a single
+option provided it has multiple names.  This should be terminated by an
+entry with zero in all fields.  Note that when using an initialized C
+array for options, writing @code{@{ 0 @}} is enough to achieve this.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_option}
+This structure specifies a single option that an argp parser
+understands, as well as how to parse and document that option.  It has
+the following fields:
+
+@table @code
+@item const char *name
+The long name for this option, corresponding to the long option
+@samp{--@var{name}}; this field may be zero if this option @emph{only}
+has a short name.  To specify multiple names for an option, additional
+entries may follow this one, with the @code{OPTION_ALIAS} flag
+set.  @xref{Argp Option Flags}.
+
+@item int key
+The integer key provided by the current option to the option parser.  If
+@var{key} has a value that is a printable @sc{ascii} character (i.e.,
+@code{isascii (@var{key})} is true), it @emph{also} specifies a short
+option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character
+with the code @var{key}.
+
+@item const char *arg
+If non-zero, this is the name of an argument associated with this
+option, which must be provided (e.g., with the
+@samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
+syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp
+Option Flags}) is set, in which case it @emph{may} be provided.
+
+@item int flags
+Flags associated with this option, some of which are referred to above.
+@xref{Argp Option Flags}.
+
+@item const char *doc
+A documentation string for this option, for printing in help messages.
+
+If both the @code{name} and @code{key} fields are zero, this string
+will be printed tabbed left from the normal option column, making it
+useful as a group header.  This will be the first thing printed in its
+group.  In this usage, it's conventional to end the string with a
+@samp{:} character.
+
+@item int group
+Group identity for this option.
+
+In a long help message, options are sorted alphabetically within each
+group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
+@minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.
+
+Every entry in an options array with this field 0 will inherit the group
+number of the previous entry, or zero if it's the first one.  If it's a
+group header with @code{name} and @code{key} fields both zero, the
+previous entry + 1 is the default.  Automagic options such as
+@samp{--help} are put into group @minus{}1.
+
+Note that because of C structure initialization rules, this field often
+need not be specified, because 0 is the correct value.
+@end table
+@end deftp
+
+
+@menu
+* Flags: Argp Option Flags.     Flags for options.
+@end menu
+
+@node Argp Option Flags, , , Argp Option Vectors
+@subsubsection Flags for Argp Options
+
+The following flags may be or'd together in the @code{flags} field of a
+@code{struct argp_option}.  These flags control various aspects of how
+that option is parsed or displayed in help messages:
+
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item OPTION_ARG_OPTIONAL
+The argument associated with this option is optional.
+
+@comment argp.h
+@comment GNU
+@item OPTION_HIDDEN
+This option isn't displayed in any help messages.
+
+@comment argp.h
+@comment GNU
+@item OPTION_ALIAS
+This option is an alias for the closest previous non-alias option.  This
+means that it will be displayed in the same help entry, and will inherit
+fields other than @code{name} and @code{key} from the option being
+aliased.
+
+
+@comment argp.h
+@comment GNU
+@item OPTION_DOC
+This option isn't actually an option and should be ignored by the actual
+option parser.  It is an arbitrary section of documentation that should
+be displayed in much the same manner as the options.  This is known as a
+@dfn{documentation option}.
+
+If this flag is set, then the option @code{name} field is displayed
+unmodified (e.g., no @samp{--} prefix is added) at the left-margin where
+a @emph{short} option would normally be displayed, and this
+documentation string is left in it's usual place.  For purposes of
+sorting, any leading whitespace and punctuation is ignored, unless the
+first non-whitespace character is @samp{-}.  This entry is displayed
+after all options, after @code{OPTION_DOC} entries with a leading
+@samp{-}, in the same group.
+
+@comment argp.h
+@comment GNU
+@item OPTION_NO_USAGE
+This option shouldn't be included in `long' usage messages, but should
+still be included in other help messages.  This is intended for options
+that are completely documented in an argp's @code{args_doc}
+field.  @xref{Argp Parsers}.  Including this option in the generic usage
+list would be redundant, and should be avoided.
+
+For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
+@samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
+should probably be marked @code{OPTION_NO_USAGE}.
+@end vtable
+
+@node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
+@subsection Argp Parser Functions
+
+The function pointed to by the @code{parser} field in a @code{struct
+argp} (@pxref{Argp Parsers}) defines what actions take place in response
+to each option or argument parsed.  It is also used as a hook, allowing a
+parser to perform tasks at certain other points during parsing.
+
+@need 2000
+Argp parser functions have the following type signature:
+
+@cindex argp parser functions
+@smallexample
+error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+where the arguments are as follows:
+
+@table @var
+@item key
+For each option that is parsed, @var{parser} is called with a value of
+@var{key} from that option's @code{key} field in the option
+vector.  @xref{Argp Option Vectors}.  @var{parser} is also called at
+other times with special reserved keys, such as @code{ARGP_KEY_ARG} for
+non-option arguments.  @xref{Argp Special Keys}.
+
+@item arg
+If @var{key} is an option, @var{arg} is its given value.  This defaults
+to zero if no value is specified.  Only options that have a non-zero
+@code{arg} field can ever have a value.  These must @emph{always} have a
+value unless the @code{OPTION_ARG_OPTIONAL} flag is specified.  If the
+input being parsed specifies a value for an option that doesn't allow
+one, an error results before @var{parser} ever gets called.
+
+If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option
+argument.  Other special keys always have a zero @var{arg}.
+
+@item state
+@var{state} points to a @code{struct argp_state}, containing useful
+information about the current parsing state for use by
+@var{parser}.  @xref{Argp Parsing State}.
+@end table
+
+When @var{parser} is called, it should perform whatever action is
+appropriate for @var{key}, and return @code{0} for success,
+@code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this
+parser function, or a unix error code if a real error
+occurred.  @xref{Error Codes}.
+
+@comment argp.h
+@comment GNU
+@deftypevr Macro int ARGP_ERR_UNKNOWN
+Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
+@var{key} value they do not recognize, or for non-option arguments
+(@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle.
+@end deftypevr
+
+@need 3000
+A typical parser function uses a switch statement on @var{key}:
+
+@smallexample
+error_t
+parse_opt (int key, char *arg, struct argp_state *state)
+@{
+  switch (key)
+    @{
+    case @var{option_key}:
+      @var{action}
+      break;
+    @dots{}
+    default:
+      return ARGP_ERR_UNKNOWN;
+    @}
+  return 0;
+@}
+@end smallexample
+
+@menu
+* Keys: Argp Special Keys.           Special values for the @var{key} argument.
+* State: Argp Parsing State.         What the @var{state} argument refers to.
+* Functions: Argp Helper Functions.  Functions to help during argp parsing.
+@end menu
+
+@node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
+@subsubsection Special Keys for Argp Parser Functions
+
+In addition to key values corresponding to user options, the @var{key}
+argument to argp parser functions may have a number of other special
+values.  In the following example @var{arg} and @var{state} refer to
+parser function arguments.  @xref{Argp Parser Functions}.
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ARG
+This is not an option at all, but rather a command line argument, whose
+value is pointed to by @var{arg}.
+
+When there are multiple parser functions in play due to argp parsers
+being combined, it's impossible to know which one will handle a specific
+argument.  Each is called until one returns 0 or an error other than
+@code{ARGP_ERR_UNKNOWN}; if an argument is not handled,
+@code{argp_parse} immediately returns success, without parsing any more
+arguments.
+
+Once a parser function returns success for this key, that fact is
+recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be
+used.  @emph{However}, if while processing the argument a parser function
+decrements the @code{next} field of its @var{state} argument, the option
+won't be considered processed; this is to allow you to actually modify
+the argument, perhaps into an option, and have it processed again.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ARGS
+If a parser function returns @code{ARGP_ERR_UNKNOWN} for
+@code{ARGP_KEY_ARG}, it is immediately called again with the key
+@code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
+convenient for consuming all remaining arguments.  @var{arg} is 0, and
+the tail of the argument vector may be found at @code{@var{state}->argv
++ @var{state}->next}.  If success is returned for this key, and
+@code{@var{state}->next} is unchanged, all remaining arguments are
+considered to have been consumed.  Otherwise, the amount by which
+@code{@var{state}->next} has been adjusted indicates how many were used.
+Here's an example that uses both, for different args:
+
+
+@smallexample
+@dots{}
+case ARGP_KEY_ARG:
+  if (@var{state}->arg_num == 0)
+    /* First argument */
+    first_arg = @var{arg};
+  else
+    /* Let the next case parse it.  */
+    return ARGP_KEY_UNKNOWN;
+  break;
+case ARGP_KEY_ARGS:
+  remaining_args = @var{state}->argv + @var{state}->next;
+  num_remaining_args = @var{state}->argc - @var{state}->next;
+  break;
+@end smallexample
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_END
+This indicates that there are no more command line arguments.  Parser
+functions are called in a different order, children first.  This allows
+each parser to clean up its state for the parent.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_NO_ARGS
+Because it's common to do some special processing if there aren't any
+non-option args, parser functions are called with this key if they
+didn't successfully process any non-option arguments.  This is called
+just before @code{ARGP_KEY_END}, where more general validity checks on
+previously parsed arguments take place.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_INIT
+This is passed in before any parsing is done.  Afterwards, the values of
+each element of the @code{child_input} field of @var{state}, if any, are
+copied to each child's state to be the initial value of the @code{input}
+when @emph{their} parsers are called.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_SUCCESS
+Passed in when parsing has successfully been completed, even if
+arguments remain.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ERROR
+Passed in if an error has occurred and parsing is terminated.  In this
+case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_FINI
+The final key ever seen by any parser, even after
+@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}.  Any resources
+allocated by @code{ARGP_KEY_INIT} may be freed here.  At times, certain
+resources allocated are to be returned to the caller after a successful
+parse.  In that case, those particular resources can be freed in the
+@code{ARGP_KEY_ERROR} case.
+@end vtable
+
+In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
+functions, and @code{ARGP_KEY_FINI} the last, unless an error was
+returned by the parser for @code{ARGP_KEY_INIT}.  Other keys can occur
+in one the following orders.  @var{opt} refers to an arbitrary option
+key:
+
+@table @asis
+@item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
+The arguments being parsed did not contain any non-option arguments.
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
+All non-option arguments were successfully handled by a parser
+function.  There may be multiple parser functions if multiple argp
+parsers were combined.
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
+Some non-option argument went unrecognized.
+
+This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
+for an argument, in which case parsing stops at that argument if
+@var{arg_index} is a null pointer.  Otherwise an error occurs.
+@end table
+
+In all cases, if a non-null value for @var{arg_index} gets passed to
+@code{argp_parse}, the index of the first unparsed command-line argument
+is passed back in that value.
+
+If an error occurs and is either detected by argp or because a parser
+function returned an error value, each parser is called with
+@code{ARGP_KEY_ERROR}.  No further calls are made, except the final call
+with @code{ARGP_KEY_FINI}.
+
+@node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
+@subsubsection Argp Parsing State
+
+The third argument to argp parser functions (@pxref{Argp Parser
+Functions}) is a pointer to a @code{struct argp_state}, which contains
+information about the state of the option parsing.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_state}
+This structure has the following fields, which may be modified as noted:
+
+@table @code
+@item const struct argp *const root_argp
+The top level argp parser being parsed.  Note that this is often
+@emph{not} the same @code{struct argp} passed into @code{argp_parse} by
+the invoking program.  @xref{Argp}.  It is an internal argp parser that
+contains options implemented by @code{argp_parse} itself, such as
+@samp{--help}.
+
+@item int argc
+@itemx char **argv
+The argument vector being parsed.  This may be modified.
+
+@item int next
+The index in @code{argv} of the next argument to be parsed.  This may be
+modified.
+
+One way to consume all remaining arguments in the input is to set
+@code{@var{state}->next = @var{state}->argc}, perhaps after recording
+the value of the @code{next} field to find the consumed arguments.  The
+current option can be re-parsed immediately by decrementing this field,
+then modifying @code{@var{state}->argv[@var{state}->next]} to reflect
+the option that should be reexamined.
+
+@item unsigned flags
+The flags supplied to @code{argp_parse}.  These may be modified, although
+some flags may only take effect when @code{argp_parse} is first
+invoked.  @xref{Argp Flags}.
+
+@item unsigned arg_num
+While calling a parsing function with the @var{key} argument
+@code{ARGP_KEY_ARG}, this represents the number of the current arg,
+starting at 0.  It is incremented after each @code{ARGP_KEY_ARG} call
+returns.  At all other times, this is the number of @code{ARGP_KEY_ARG}
+arguments that have been processed.
+
+@item int quoted
+If non-zero, the index in @code{argv} of the first argument following a
+special @samp{--} argument.  This prevents anything that follows from
+being interpreted as an option.  It is only set after argument parsing
+has proceeded past this point.
+
+@item void *input
+An arbitrary pointer passed in from the caller of @code{argp_parse}, in
+the @var{input} argument.
+
+@item void **child_inputs
+These are values that will be passed to child parsers.  This vector will
+be the same length as the number of children in the current parser.  Each
+child parser will be given the value of
+@code{@var{state}->child_inputs[@var{i}]} as @emph{its}
+@code{@var{state}->input} field, where @var{i} is the index of the child
+in the this parser's @code{children} field.  @xref{Argp Children}.
+
+@item void *hook
+For the parser function's use.  Initialized to 0, but otherwise ignored
+by argp.
+
+@item char *name
+The name used when printing messages.  This is initialized to
+@code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is
+unavailable.
+
+@item FILE *err_stream
+@itemx FILE *out_stream
+The stdio streams used when argp prints.  Error messages are printed to
+@code{err_stream}, all other output, such as @samp{--help} output) to
+@code{out_stream}.  These are initialized to @code{stderr} and
+@code{stdout} respectively.  @xref{Standard Streams}.
+
+@item void *pstate
+Private, for use by the argp implementation.
+@end table
+@end deftp
+
+@node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
+@subsubsection Functions For Use in Argp Parsers
+
+Argp provides a number of functions available to the user of argp
+(@pxref{Argp Parser Functions}), mostly for producing error messages.
+These take as their first argument the @var{state} argument to the
+parser function.  @xref{Argp Parsing State}.
+
+
+@cindex usage messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_usage (const struct argp_state *@var{state})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls argp_state_help with stderr and ARGP_HELP_STD_USAGE.
+Outputs the standard usage message for the argp parser referred to by
+@var{state} to @code{@var{state}->err_stream} and terminate the program
+with @code{exit (argp_err_exit_status)}.  @xref{Argp Global Variables}.
+@end deftypefun
+
+@cindex syntax error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Lock stream, vasprintf the formatted message into a buffer, print the
+@c buffer prefixed by the short program name (in libc,
+@c argp_short_program_name is a macro that expands to
+@c program_invocation_short_name), releases the buffer, then call
+@c argp_state_help with stream and ARGP_HELP_STD_ERR, unlocking the
+@c stream at the end.
+Prints the printf format string @var{fmt} and following args, preceded
+by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
+--help}} message, and terminates the program with an exit status of
+@code{argp_err_exit_status}.  @xref{Argp Global Variables}.
+@end deftypefun
+
+@cindex error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c Lock stream, write out the short program name, vasprintf the optional
+@c formatted message to a buffer, print the buffer prefixed by colon and
+@c blank, release the buffer, call strerror_r with an automatic buffer,
+@c print it out after colon and blank, put[w]c a line break, unlock the
+@c stream, then exit unless ARGP_NO_EXIT.
+Similar to the standard gnu error-reporting function @code{error}, this
+prints the program name and @samp{:}, the printf format string
+@var{fmt}, and the appropriate following args.  If it is non-zero, the
+standard unix error text for @var{errnum} is printed.  If @var{status} is
+non-zero, it terminates the program with that value as its exit status.
+
+The difference between @code{argp_failure} and @code{argp_error} is that
+@code{argp_error} is for @emph{parsing errors}, whereas
+@code{argp_failure} is for other problems that occur during parsing but
+don't reflect a syntactic problem with the input, such as illegal values
+for options, bad phase of the moon, etc.
+@end deftypefun
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls _help with the short program name and optionally exit.
+@c The main problems in _help, besides the usual issues with stream I/O
+@c and translation, are the use of a static buffer (uparams, thus
+@c @mtasurace:argpbuf) that makes the whole thing thread-unsafe, reading
+@c from the environment for ARGP_HELP_FMT, accessing the locale object
+@c multiple times.
+
+@c _help @mtsenv @mtasurace:argpbuf @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c  dgettext @ascuintl
+@c  flockfile @aculock
+@c  funlockfile @aculock
+@c  fill_in_uparams @mtsenv @mtasurace:argpbuf @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c   argp_failure dup (status = errnum = 0)
+@c   atoi dup @mtslocale
+@c  argp_hol @ascuheap @acsmem
+@c   make_hol @ascuheap @acsmem
+@c   hol_add_cluster @ascuheap @acsmem
+@c   hol_append @ascuheap @acsmem
+@c  hol_set_group ok
+@c   hol_find_entry ok
+@c  hol_sort @mtslocale @acucorrupt
+@c   qsort dup @acucorrupt
+@c    hol_entry_qcmp @mtslocale
+@c     hol_entry_cmp @mtslocale
+@c      group_cmp ok
+@c      hol_cluster_cmp ok
+@c       group_cmp ok
+@c      hol_entry_first_short @mtslocale
+@c       hol_entry_short_iterate [@mtslocale]
+@c        until_short ok
+@c         oshort ok
+@c          isprint ok
+@c      odoc ok
+@c      hol_entry_first_long ok
+@c      canon_doc_option @mtslocale
+@c      tolower dup
+@c  hol_usage @mtslocale @ascuintl @ascuheap @acsmem
+@c   hol_entry_short_iterate ok
+@c    add_argless_short_opt ok
+@c   argp_fmtstream_printf dup
+@c   hol_entry_short_iterate @mtslocale @ascuintl @ascuheap @acsmem
+@c    usage_argful_short_opt @mtslocale @ascuintl @ascuheap @acsmem
+@c     dgettext dup
+@c     argp_fmtstream_printf dup
+@c   hol_entry_long_iterate @mtslocale @ascuintl @ascuheap @acsmem
+@c    usage_long_opt @mtslocale @ascuintl @ascuheap @acsmem
+@c     dgettext dup
+@c     argp_fmtstream_printf dup
+@c  hol_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c   hol_entry_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_set_lmargin dup
+@c    argp_fmtstream_wmargin dup
+@c    argp_fmtstream_set_wmargin dup
+@c    comma @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_putc dup
+@c     hol_cluster_is_child ok
+@c     argp_fmtstream_wmargin dup
+@c     print_header dup
+@c     argp_fmtstream_set_wmargin dup
+@c     argp_fmtstream_puts dup
+@c     indent_to dup
+@c    argp_fmtstream_putc dup
+@c    arg @mtslocale @ascuheap @acsmem
+@c     argp_fmtstream_printf dup
+@c    odoc dup
+@c    argp_fmtstream_puts dup
+@c    argp_fmtstream_printf dup
+@c    print_header @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c     dgettext dup
+@c     filter_doc dup
+@c     argp_fmtstream_putc dup
+@c     indent_to dup
+@c     argp_fmtstream_set_lmargin dup
+@c     argp_fmtstream_set_wmargin dup
+@c     argp_fmtstream_puts dup
+@c     free dup
+@c    filter_doc dup
+@c    argp_fmtstream_point dup
+@c    indent_to @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_point dup
+@c     argp_fmtstream_putc dup
+@c   dgettext dup
+@c   filter_doc dup
+@c   argp_fmtstream_putc dup
+@c   argp_fmtstream_puts dup
+@c   free dup
+@c  hol_free @ascuheap @acsmem
+@c   free dup
+@c  argp_args_levels ok
+@c  argp_args_usage @mtslocale @ascuintl @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   dgettext dup
+@c   filter_doc ok
+@c    argp_input ok
+@c    argp->help_filter
+@c   space @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_point dup
+@c    argp_fmtstream_rmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c     argp_fmtstream_update dup
+@c    argp_fmtstream_putc dup
+@c   argp_fmtstream_write dup
+@c   free dup
+@c  argp_doc @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c   dgettext @ascuintl
+@c   strndup @ascuheap @acsmem
+@c   argp_input dup
+@c   argp->help_filter
+@c   argp_fmtstream_putc @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_ensure dup
+@c   argp_fmtstream_write dup
+@c   argp_fmtstream_puts dup
+@c   argp_fmtstream_point @mtslocale @asucorrupt @acucorrupt @aculock
+@c    argp_fmtstream_update dup
+@c   argp_fmtstream_lmargin dup
+@c   free dup
+@c  argp_make_fmtstream @ascuheap @acsmem
+@c  argp_fmtstream_free @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   argp_fmtstream_update @mtslocale @asucorrupt @acucorrupt @aculock
+@c    put[w]c_unlocked dup
+@c    isblank in loop @mtslocale
+@c    fxprintf @aculock
+@c   fxprintf @aculock
+@c   free dup
+@c  argp_fmtstream_set_wmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c   argp_fmtstream_update dup
+@c  argp_fmtstream_printf @mtslocale @ascuheap @acsmem
+@c   argp_fmtstream_ensure dup
+@c   vsnprintf dup
+@c  argp_fmtstream_set_lmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c   argp_fmtstream_update dup
+@c  argp_fmtstream_puts @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   argp_fmtstream_write @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_ensure @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_update dup
+@c     fxprintf @aculock
+@c     realloc @ascuheap @acsmem
+Outputs a help message for the argp parser referred to by @var{state},
+to @var{stream}.  The @var{flags} argument determines what sort of help
+message is produced.  @xref{Argp Help Flags}.
+@end deftypefun
+
+Error output is sent to @code{@var{state}->err_stream}, and the program
+name printed is @code{@var{state}->name}.
+
+The output or program termination behavior of these functions may be
+suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are
+passed to @code{argp_parse}.  @xref{Argp Flags}.
+
+This behavior is useful if an argp parser is exported for use by other
+programs (e.g., by a library), and may be used in a context where it is
+not desirable to terminate the program in response to parsing errors.  In
+argp parsers intended for such general use, and for the case where the
+program @emph{doesn't} terminate, calls to any of these functions should
+be followed by code that returns the appropriate error code:
+
+@smallexample
+if (@var{bad argument syntax})
+  @{
+     argp_usage (@var{state});
+     return EINVAL;
+  @}
+@end smallexample
+
+@noindent
+If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT}
+is not set, the return may be omitted.
+
+@node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
+@subsection Combining Multiple Argp Parsers
+
+The @code{children} field in a @code{struct argp} enables other argp
+parsers to be combined with the referencing one for the parsing of a
+single set of arguments.  This field should point to a vector of
+@code{struct argp_child}, which is terminated by an entry having a value
+of zero in the @code{argp} field.
+
+Where conflicts between combined parsers arise, as when two specify an
+option with the same name, the parser conflicts are resolved in favor of
+the parent argp parser(s), or the earlier of the argp parsers in the
+list of children.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_child}
+An entry in the list of subsidiary argp parsers pointed to by the
+@code{children} field in a @code{struct argp}.  The fields are as
+follows:
+
+@table @code
+@item const struct argp *argp
+The child argp parser, or zero to end of the list.
+
+@item int flags
+Flags for this child.
+
+@item const char *header
+If non-zero, this is an optional header to be printed within help output
+before the child options.  As a side-effect, a non-zero value forces the
+child options to be grouped together.  To achieve this effect without
+actually printing a header string, use a value of @code{""}.  As with
+header strings specified in an option entry, the conventional value of
+the last character is @samp{:}.  @xref{Argp Option Vectors}.
+
+@item int group
+This is where the child options are grouped relative to the other
+`consolidated' options in the parent argp parser.  The values are the
+same as the @code{group} field in @code{struct argp_option}.  @xref{Argp
+Option Vectors}.  All child-groupings follow parent options at a
+particular group level.  If both this field and @code{header} are zero,
+then the child's options aren't grouped together, they are merged with
+parent options at the parent option group level.
+
+@end table
+@end deftp
+
+@node Argp Flags, Argp Help, Argp Parsers, Argp
+@subsection Flags for @code{argp_parse}
+
+The default behavior of @code{argp_parse} is designed to be convenient
+for the most common case of parsing program command line argument.  To
+modify these defaults, the following flags may be or'd together in the
+@var{flags} argument to @code{argp_parse}:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_PARSE_ARGV0
+Don't ignore the first element of the @var{argv} argument to
+@code{argp_parse}.  Unless @code{ARGP_NO_ERRS} is set, the first element
+of the argument vector is skipped for option parsing purposes, as it
+corresponds to the program name in a command line.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ERRS
+Don't print error messages for unknown options to @code{stderr}; unless
+this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
+is used as the program name in the error messages.  This flag implies
+@code{ARGP_NO_EXIT}.  This is based on the assumption that silent exiting
+upon errors is bad behavior.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ARGS
+Don't parse any non-option args.  Normally these are parsed by calling
+the parse functions with a key of @code{ARGP_KEY_ARG}, the actual
+argument being the value.  This flag needn't normally be set, as the
+default behavior is to stop parsing as soon as an argument fails to be
+parsed.  @xref{Argp Parser Functions}.
+
+@comment argp.h
+@comment GNU
+@item ARGP_IN_ORDER
+Parse options and arguments in the same order they occur on the command
+line.  Normally they're rearranged so that all options come first.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_HELP
+Don't provide the standard long option @samp{--help}, which ordinarily
+causes usage and option help information to be output to @code{stdout}
+and @code{exit (0)}.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_EXIT
+Don't exit on errors, although they may still result in error messages.
+
+@comment argp.h
+@comment GNU
+@item ARGP_LONG_ONLY
+Use the gnu getopt `long-only' rules for parsing arguments.  This allows
+long-options to be recognized with only a single @samp{-}
+(i.e., @samp{-help}).  This results in a less useful interface, and its
+use is discouraged as it conflicts with the way most GNU programs work
+as well as the GNU coding standards.
+
+@comment argp.h
+@comment GNU
+@item ARGP_SILENT
+Turns off any message-printing/exiting options, specifically
+@code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
+@end vtable
+
+@node Argp Help Filtering, , Argp Children, Argp Parsers
+@need 2000
+@subsection Customizing Argp Help Output
+
+The @code{help_filter} field in a @code{struct argp} is a pointer to a
+function that filters the text of help messages before displaying
+them.  They have a function signature like:
+
+@smallexample
+char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
+@end smallexample
+
+
+@noindent
+Where @var{key} is either a key from an option, in which case @var{text}
+is that option's help text.  @xref{Argp Option Vectors}.  Alternately, one
+of the special keys with names beginning with @samp{ARGP_KEY_HELP_}
+might be used, describing which other help text @var{text} will contain.
+@xref{Argp Help Filter Keys}.
+
+The function should return either @var{text} if it remains as-is, or a
+replacement string allocated using @code{malloc}.  This will be either be
+freed by argp or zero, which prints nothing.  The value of @var{text} is
+supplied @emph{after} any translation has been done, so if any of the
+replacement text needs translation, it will be done by the filter
+function.  @var{input} is either the input supplied to @code{argp_parse}
+or it is zero, if @code{argp_help} was called directly by the user.
+
+@menu
+* Keys: Argp Help Filter Keys.  Special @var{key} values for help filter functions.
+@end menu
+
+@node Argp Help Filter Keys, , , Argp Help Filtering
+@subsubsection Special Keys for Argp Help Filter Functions
+
+The following special values may be passed to an argp help filter
+function as the first argument in addition to key values for user
+options.  They specify which help text the @var{text} argument contains:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_PRE_DOC
+The help text preceding options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_POST_DOC
+The help text following options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_HEADER
+The option header string.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_EXTRA
+This is used after all other documentation; @var{text} is zero for this key.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_DUP_ARGS_NOTE
+The explanatory note printed when duplicate option arguments have been suppressed.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_ARGS_DOC
+The argument doc string; formally the @code{args_doc} field from the argp parser.  @xref{Argp Parsers}.
+@end vtable
+
+@node Argp Help, Argp Examples, Argp Flags, Argp
+@subsection The @code{argp_help} Function
+
+Normally programs using argp need not be written with particular
+printing argument-usage-type help messages in mind as the standard
+@samp{--help} option is handled automatically by argp.  Typical error
+cases can be handled using @code{argp_usage} and
+@code{argp_error}.  @xref{Argp Helper Functions}.  However, if it's
+desirable to print a help message in some context other than parsing the
+program options, argp offers the @code{argp_help} interface.
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls _help.
+This outputs a help message for the argp parser @var{argp} to
+@var{stream}.  The type of messages printed will be determined by
+@var{flags}.
+
+Any options such as @samp{--help} that are implemented automatically by
+argp itself will @emph{not} be present in the help output; for this
+reason it is best to use @code{argp_state_help} if calling from within
+an argp parser function.  @xref{Argp Helper Functions}.
+@end deftypefun
+
+@menu
+* Flags: Argp Help Flags.       Specifying what sort of help message to print.
+@end menu
+
+@node Argp Help Flags, , , Argp Help
+@subsection Flags for the @code{argp_help} Function
+
+When calling @code{argp_help} (@pxref{Argp Help}) or
+@code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output
+is determined by the @var{flags} argument.  This should consist of any of
+the following flags, or'd together:
+
+@vtable @code
+@item ARGP_HELP_USAGE
+A unix @samp{Usage:} message that explicitly lists all options.
+
+@item ARGP_HELP_SHORT_USAGE
+A unix @samp{Usage:} message that displays an appropriate placeholder to
+indicate where the options go; useful for showing the non-option
+argument syntax.
+
+@item ARGP_HELP_SEE
+A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
+program name and @samp{--help}.
+
+@item ARGP_HELP_LONG
+A verbose option help message that gives each option available along
+with its documentation string.
+
+@item ARGP_HELP_PRE_DOC
+The part of the argp parser doc string preceding the verbose option help.
+
+@item ARGP_HELP_POST_DOC
+The part of the argp parser doc string that following the verbose option help.
+
+@item ARGP_HELP_DOC
+@code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
+
+@item ARGP_HELP_BUG_ADDR
+A message that prints where to report bugs for this program, if the
+@code{argp_program_bug_address} variable contains this information.
+
+@item ARGP_HELP_LONG_ONLY
+This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode.
+@end vtable
+
+The following flags are only understood when used with
+@code{argp_state_help}.  They control whether the function returns after
+printing its output, or terminates the program:
+
+@vtable @code
+@item ARGP_HELP_EXIT_ERR
+This will terminate the program with @code{exit (argp_err_exit_status)}.
+
+@item ARGP_HELP_EXIT_OK
+This will terminate the program with @code{exit (0)}.
+@end vtable
+
+The following flags are combinations of the basic flags for printing
+standard messages:
+
+@vtable @code
+@item ARGP_HELP_STD_ERR
+Assuming that an error message for a parsing error has printed, this
+prints a message on how to get help, and terminates the program with an
+error.
+
+@item ARGP_HELP_STD_USAGE
+This prints a standard usage message and terminates the program with an
+error.  This is used when no other specific error messages are
+appropriate or available.
+
+@item ARGP_HELP_STD_HELP
+This prints the standard response for a @samp{--help} option, and
+terminates the program successfully.
+@end vtable
+
+@node Argp Examples, Argp User Customization, Argp Help, Argp
+@subsection Argp Examples
+
+These example programs demonstrate the basic usage of argp.
+
+@menu
+* 1: Argp Example 1.            A minimal program using argp.
+* 2: Argp Example 2.            A program using only default options.
+* 3: Argp Example 3.            A simple program with user options.
+* 4: Argp Example 4.            Combining multiple argp parsers.
+@end menu
+
+@node Argp Example 1, Argp Example 2, , Argp Examples
+@subsubsection A Minimal Program Using Argp
+
+This is perhaps the smallest program possible that uses argp.  It won't
+do much except give an error messages and exit when there are any
+arguments, and prints a rather pointless message for @samp{--help}.
+
+@smallexample
+@include argp-ex1.c.texi
+@end smallexample
+
+@node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
+@subsubsection A Program Using Argp with Only Default Options
+
+This program doesn't use any options or arguments, it uses argp to be
+compliant with the GNU standard command line format.
+
+In addition to giving no arguments and implementing a @samp{--help}
+option, this example has a @samp{--version} option, which will put the
+given documentation string and bug address in the @samp{--help} output,
+as per GNU standards.
+
+The variable @code{argp} contains the argument parser
+specification.  Adding fields to this structure is the way most
+parameters are passed to @code{argp_parse}.  The first three fields are
+normally used, but they are not in this small program.  There are also
+two global variables that argp can use defined here,
+@code{argp_program_version} and @code{argp_program_bug_address}.  They
+are considered global variables because they will almost always be
+constant for a given program, even if they use different argument
+parsers for various tasks.
+
+@smallexample
+@include argp-ex2.c.texi
+@end smallexample
+
+@node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
+@subsubsection A Program Using Argp with User Options
+
+This program uses the same features as example 2, adding user options
+and arguments.
+
+We now use the first four fields in @code{argp} (@pxref{Argp Parsers})
+and specify @code{parse_opt} as the parser function.  @xref{Argp Parser
+Functions}.
+
+Note that in this example, @code{main} uses a structure to communicate
+with the @code{parse_opt} function, a pointer to which it passes in the
+@code{input} argument to @code{argp_parse}.  @xref{Argp}.  It is retrieved
+by @code{parse_opt} through the @code{input} field in its @code{state}
+argument.  @xref{Argp Parsing State}.  Of course, it's also possible to
+use global variables instead, but using a structure like this is
+somewhat more flexible and clean.
+
+@smallexample
+@include argp-ex3.c.texi
+@end smallexample
+
+@node Argp Example 4, , Argp Example 3, Argp Examples
+@subsubsection A Program Using Multiple Combined Argp Parsers
+
+This program uses the same features as example 3, but has more options,
+and presents more structure in the @samp{--help} output.  It also
+illustrates how you can `steal' the remainder of the input arguments
+past a certain point for programs that accept a list of items.  It also
+illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only
+given if no non-option arguments were supplied to the
+program.  @xref{Argp Special Keys}.
+
+For structuring help output, two features are used: @emph{headers} and a
+two part option string.  The @emph{headers} are entries in the options
+vector.  @xref{Argp Option Vectors}.  The first four fields are zero.  The
+two part documentation string are in the variable @code{doc}, which
+allows documentation both before and after the options.  @xref{Argp
+Parsers}, the two parts of @code{doc} are separated by a vertical-tab
+character (@code{'\v'}, or @code{'\013'}).  By convention, the
+documentation before the options is a short string stating what the
+program does, and after any options it is longer, describing the
+behavior in more detail.  All documentation strings are automatically
+filled for output, although newlines may be included to force a line
+break at a particular point.  In addition, documentation strings are
+passed to the @code{gettext} function, for possible translation into the
+current locale.
+
+@smallexample
+@include argp-ex4.c.texi
+@end smallexample
+
+@node Argp User Customization, , Argp Examples, Argp
+@subsection Argp User Customization
+
+@cindex ARGP_HELP_FMT environment variable
+The formatting of argp @samp{--help} output may be controlled to some
+extent by a program's users, by setting the @code{ARGP_HELP_FMT}
+environment variable to a comma-separated list of tokens.  Whitespace is
+ignored:
+
+@table @samp
+@item dup-args
+@itemx no-dup-args
+These turn @dfn{duplicate-argument-mode} on or off.  In duplicate
+argument mode, if an option that accepts an argument has multiple names,
+the argument is shown for each name.  Otherwise, it is only shown for the
+first long option.  A note is subsequently printed so the user knows that
+it applies to other names as well.  The default is @samp{no-dup-args},
+which is less consistent, but prettier.
+
+@item dup-args-note
+@item no-dup-args-note
+These will enable or disable the note informing the user of suppressed
+option argument duplication.  The default is @samp{dup-args-note}.
+
+@item short-opt-col=@var{n}
+This prints the first short option in column @var{n}.  The default is 2.
+
+@item long-opt-col=@var{n}
+This prints the first long option in column @var{n}.  The default is 6.
+
+@item doc-opt-col=@var{n}
+This prints `documentation options' (@pxref{Argp Option Flags}) in
+column @var{n}.  The default is 2.
+
+@item opt-doc-col=@var{n}
+This prints the documentation for options starting in column
+@var{n}.  The default is 29.
+
+@item header-col=@var{n}
+This will indent the group headers that document groups of options to
+column @var{n}.  The default is 1.
+
+@item usage-indent=@var{n}
+This will indent continuation lines in @samp{Usage:} messages to column
+@var{n}.  The default is 12.
+
+@item rmargin=@var{n}
+This will word wrap help output at or before column @var{n}.  The default
+is 79.
+@end table
diff --git a/ap/libc/glibc/glibc-2.23/manual/arith.texi b/ap/libc/glibc/glibc-2.23/manual/arith.texi
new file mode 100644
index 0000000..72682f0
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/arith.texi
@@ -0,0 +1,2769 @@
+@node Arithmetic, Date and Time, Mathematics, Top
+@c %MENU% Low level arithmetic functions
+@chapter Arithmetic Functions
+
+This chapter contains information about functions for doing basic
+arithmetic operations, such as splitting a float into its integer and
+fractional parts or retrieving the imaginary part of a complex value.
+These functions are declared in the header files @file{math.h} and
+@file{complex.h}.
+
+@menu
+* Integers::                    Basic integer types and concepts
+* Integer Division::            Integer division with guaranteed rounding.
+* Floating Point Numbers::      Basic concepts.  IEEE 754.
+* Floating Point Classes::      The five kinds of floating-point number.
+* Floating Point Errors::       When something goes wrong in a calculation.
+* Rounding::                    Controlling how results are rounded.
+* Control Functions::           Saving and restoring the FPU's state.
+* Arithmetic Functions::        Fundamental operations provided by the library.
+* Complex Numbers::             The types.  Writing complex constants.
+* Operations on Complex::       Projection, conjugation, decomposition.
+* Parsing of Numbers::          Converting strings to numbers.
+* System V Number Conversion::  An archaic way to convert numbers to strings.
+@end menu
+
+@node Integers
+@section Integers
+@cindex integer
+
+The C language defines several integer data types: integer, short integer,
+long integer, and character, all in both signed and unsigned varieties.
+The GNU C compiler extends the language to contain long long integers
+as well.
+@cindex signedness
+
+The C integer types were intended to allow code to be portable among
+machines with different inherent data sizes (word sizes), so each type
+may have different ranges on different machines.  The problem with
+this is that a program often needs to be written for a particular range
+of integers, and sometimes must be written for a particular size of
+storage, regardless of what machine the program runs on.
+
+To address this problem, @theglibc{} contains C type definitions
+you can use to declare integers that meet your exact needs.  Because the
+@glibcadj{} header files are customized to a specific machine, your
+program source code doesn't have to be.
+
+These @code{typedef}s are in @file{stdint.h}.
+@pindex stdint.h
+
+If you require that an integer be represented in exactly N bits, use one
+of the following types, with the obvious mapping to bit size and signedness:
+
+@itemize @bullet
+@item int8_t
+@item int16_t
+@item int32_t
+@item int64_t
+@item uint8_t
+@item uint16_t
+@item uint32_t
+@item uint64_t
+@end itemize
+
+If your C compiler and target machine do not allow integers of a certain
+size, the corresponding above type does not exist.
+
+If you don't need a specific storage size, but want the smallest data
+structure with @emph{at least} N bits, use one of these:
+
+@itemize @bullet
+@item int_least8_t
+@item int_least16_t
+@item int_least32_t
+@item int_least64_t
+@item uint_least8_t
+@item uint_least16_t
+@item uint_least32_t
+@item uint_least64_t
+@end itemize
+
+If you don't need a specific storage size, but want the data structure
+that allows the fastest access while having at least N bits (and
+among data structures with the same access speed, the smallest one), use
+one of these:
+
+@itemize @bullet
+@item int_fast8_t
+@item int_fast16_t
+@item int_fast32_t
+@item int_fast64_t
+@item uint_fast8_t
+@item uint_fast16_t
+@item uint_fast32_t
+@item uint_fast64_t
+@end itemize
+
+If you want an integer with the widest range possible on the platform on
+which it is being used, use one of the following.  If you use these,
+you should write code that takes into account the variable size and range
+of the integer.
+
+@itemize @bullet
+@item intmax_t
+@item uintmax_t
+@end itemize
+
+@Theglibc{} also provides macros that tell you the maximum and
+minimum possible values for each integer data type.  The macro names
+follow these examples: @code{INT32_MAX}, @code{UINT8_MAX},
+@code{INT_FAST32_MIN}, @code{INT_LEAST64_MIN}, @code{UINTMAX_MAX},
+@code{INTMAX_MAX}, @code{INTMAX_MIN}.  Note that there are no macros for
+unsigned integer minima.  These are always zero.
+@cindex maximum possible integer
+@cindex minimum possible integer
+
+There are similar macros for use with C's built in integer types which
+should come with your C compiler.  These are described in @ref{Data Type
+Measurements}.
+
+Don't forget you can use the C @code{sizeof} function with any of these
+data types to get the number of bytes of storage each uses.
+
+
+@node Integer Division
+@section Integer Division
+@cindex integer division functions
+
+This section describes functions for performing integer division.  These
+functions are redundant when GNU CC is used, because in GNU C the
+@samp{/} operator always rounds towards zero.  But in other C
+implementations, @samp{/} may round differently with negative arguments.
+@code{div} and @code{ldiv} are useful because they specify how to round
+the quotient: towards zero.  The remainder has the same sign as the
+numerator.
+
+These functions are specified to return a result @var{r} such that the value
+@code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
+@var{numerator}.
+
+@pindex stdlib.h
+To use these facilities, you should include the header file
+@file{stdlib.h} in your program.
+
+@comment stdlib.h
+@comment ISO
+@deftp {Data Type} div_t
+This is a structure type used to hold the result returned by the @code{div}
+function.  It has the following members:
+
+@table @code
+@item int quot
+The quotient from the division.
+
+@item int rem
+The remainder from the division.
+@end table
+@end deftp
+
+@comment stdlib.h
+@comment ISO
+@deftypefun div_t div (int @var{numerator}, int @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Functions in this section are pure, and thus safe.
+This function @code{div} computes the quotient and remainder from
+the division of @var{numerator} by @var{denominator}, returning the
+result in a structure of type @code{div_t}.
+
+If the result cannot be represented (as in a division by zero), the
+behavior is undefined.
+
+Here is an example, albeit not a very useful one.
+
+@smallexample
+div_t result;
+result = div (20, -6);
+@end smallexample
+
+@noindent
+Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftp {Data Type} ldiv_t
+This is a structure type used to hold the result returned by the @code{ldiv}
+function.  It has the following members:
+
+@table @code
+@item long int quot
+The quotient from the division.
+
+@item long int rem
+The remainder from the division.
+@end table
+
+(This is identical to @code{div_t} except that the components are of
+type @code{long int} rather than @code{int}.)
+@end deftp
+
+@comment stdlib.h
+@comment ISO
+@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{ldiv} function is similar to @code{div}, except that the
+arguments are of type @code{long int} and the result is returned as a
+structure of type @code{ldiv_t}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftp {Data Type} lldiv_t
+This is a structure type used to hold the result returned by the @code{lldiv}
+function.  It has the following members:
+
+@table @code
+@item long long int quot
+The quotient from the division.
+
+@item long long int rem
+The remainder from the division.
+@end table
+
+(This is identical to @code{div_t} except that the components are of
+type @code{long long int} rather than @code{int}.)
+@end deftp
+
+@comment stdlib.h
+@comment ISO
+@deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{lldiv} function is like the @code{div} function, but the
+arguments are of type @code{long long int} and the result is returned as
+a structure of type @code{lldiv_t}.
+
+The @code{lldiv} function was added in @w{ISO C99}.
+@end deftypefun
+
+@comment inttypes.h
+@comment ISO
+@deftp {Data Type} imaxdiv_t
+This is a structure type used to hold the result returned by the @code{imaxdiv}
+function.  It has the following members:
+
+@table @code
+@item intmax_t quot
+The quotient from the division.
+
+@item intmax_t rem
+The remainder from the division.
+@end table
+
+(This is identical to @code{div_t} except that the components are of
+type @code{intmax_t} rather than @code{int}.)
+
+See @ref{Integers} for a description of the @code{intmax_t} type.
+
+@end deftp
+
+@comment inttypes.h
+@comment ISO
+@deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{imaxdiv} function is like the @code{div} function, but the
+arguments are of type @code{intmax_t} and the result is returned as
+a structure of type @code{imaxdiv_t}.
+
+See @ref{Integers} for a description of the @code{intmax_t} type.
+
+The @code{imaxdiv} function was added in @w{ISO C99}.
+@end deftypefun
+
+
+@node Floating Point Numbers
+@section Floating Point Numbers
+@cindex floating point
+@cindex IEEE 754
+@cindex IEEE floating point
+
+Most computer hardware has support for two different kinds of numbers:
+integers (@math{@dots{}-3, -2, -1, 0, 1, 2, 3@dots{}}) and
+floating-point numbers.  Floating-point numbers have three parts: the
+@dfn{mantissa}, the @dfn{exponent}, and the @dfn{sign bit}.  The real
+number represented by a floating-point value is given by
+@tex
+$(s \mathrel? -1 \mathrel: 1) \cdot 2^e \cdot M$
+@end tex
+@ifnottex
+@math{(s ? -1 : 1) @mul{} 2^e @mul{} M}
+@end ifnottex
+where @math{s} is the sign bit, @math{e} the exponent, and @math{M}
+the mantissa.  @xref{Floating Point Concepts}, for details.  (It is
+possible to have a different @dfn{base} for the exponent, but all modern
+hardware uses @math{2}.)
+
+Floating-point numbers can represent a finite subset of the real
+numbers.  While this subset is large enough for most purposes, it is
+important to remember that the only reals that can be represented
+exactly are rational numbers that have a terminating binary expansion
+shorter than the width of the mantissa.  Even simple fractions such as
+@math{1/5} can only be approximated by floating point.
+
+Mathematical operations and functions frequently need to produce values
+that are not representable.  Often these values can be approximated
+closely enough for practical purposes, but sometimes they can't.
+Historically there was no way to tell when the results of a calculation
+were inaccurate.  Modern computers implement the @w{IEEE 754} standard
+for numerical computations, which defines a framework for indicating to
+the program when the results of calculation are not trustworthy.  This
+framework consists of a set of @dfn{exceptions} that indicate why a
+result could not be represented, and the special values @dfn{infinity}
+and @dfn{not a number} (NaN).
+
+@node Floating Point Classes
+@section Floating-Point Number Classification Functions
+@cindex floating-point classes
+@cindex classes, floating-point
+@pindex math.h
+
+@w{ISO C99} defines macros that let you determine what sort of
+floating-point number a variable holds.
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is a generic macro which works on all floating-point types and
+which returns a value of type @code{int}.  The possible values are:
+
+@vtable @code
+@item FP_NAN
+The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
+and NaN})
+@item FP_INFINITE
+The value of @var{x} is either plus or minus infinity (@pxref{Infinity
+and NaN})
+@item FP_ZERO
+The value of @var{x} is zero.  In floating-point formats like @w{IEEE
+754}, where zero can be signed, this value is also returned if
+@var{x} is negative zero.
+@item FP_SUBNORMAL
+Numbers whose absolute value is too small to be represented in the
+normal format are represented in an alternate, @dfn{denormalized} format
+(@pxref{Floating Point Concepts}).  This format is less precise but can
+represent values closer to zero.  @code{fpclassify} returns this value
+for values of @var{x} in this alternate format.
+@item FP_NORMAL
+This value is returned for all other values of @var{x}.  It indicates
+that there is nothing special about the number.
+@end vtable
+
+@end deftypefn
+
+@code{fpclassify} is most useful if more than one property of a number
+must be tested.  There are more specific macros which only test one
+property at a time.  Generally these macros execute faster than
+@code{fpclassify}, since there is special hardware support for them.
+You should therefore use the specific macros whenever possible.
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if @var{x} is finite: not plus or
+minus infinity, and not NaN.  It is equivalent to
+
+@smallexample
+(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
+@end smallexample
+
+@code{isfinite} is implemented as a macro which accepts any
+floating-point type.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if @var{x} is finite and normalized.
+It is equivalent to
+
+@smallexample
+(fpclassify (x) == FP_NORMAL)
+@end smallexample
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isnan (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if @var{x} is NaN.  It is equivalent
+to
+
+@smallexample
+(fpclassify (x) == FP_NAN)
+@end smallexample
+@end deftypefn
+
+@comment math.h
+@comment GNU
+@deftypefn {Macro} int issignaling (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if @var{x} is a signaling NaN
+(sNaN).  It is based on draft TS 18661 and currently enabled as a GNU
+extension.
+@end deftypefn
+
+Another set of floating-point classification functions was provided by
+BSD.  @Theglibc{} also supports these functions; however, we
+recommend that you use the ISO C99 macros in new code.  Those are standard
+and will be available more widely.  Also, since they are macros, you do
+not have to worry about the type of their argument.
+
+@comment math.h
+@comment BSD
+@deftypefun int isinf (double @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int isinff (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int isinfl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns @code{-1} if @var{x} represents negative infinity,
+@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun int isnan (double @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int isnanf (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int isnanl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns a nonzero value if @var{x} is a ``not a number''
+value, and zero otherwise.
+
+@strong{NB:} The @code{isnan} macro defined by @w{ISO C99} overrides
+the BSD function.  This is normally not a problem, because the two
+routines behave identically.  However, if you really need to get the BSD
+function for some reason, you can write
+
+@smallexample
+(isnan) (x)
+@end smallexample
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun int finite (double @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int finitef (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx int finitel (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns a nonzero value if @var{x} is finite or a ``not a
+number'' value, and zero otherwise.
+@end deftypefun
+
+@strong{Portability Note:} The functions listed in this section are BSD
+extensions.
+
+
+@node Floating Point Errors
+@section Errors in Floating-Point Calculations
+
+@menu
+* 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.
+@end menu
+
+@node FP Exceptions
+@subsection FP Exceptions
+@cindex exception
+@cindex signal
+@cindex zero divide
+@cindex division by zero
+@cindex inexact exception
+@cindex invalid exception
+@cindex overflow exception
+@cindex underflow exception
+
+The @w{IEEE 754} standard defines five @dfn{exceptions} that can occur
+during a calculation.  Each corresponds to a particular sort of error,
+such as overflow.
+
+When exceptions occur (when exceptions are @dfn{raised}, in the language
+of the standard), one of two things can happen.  By default the
+exception is simply noted in the floating-point @dfn{status word}, and
+the program continues as if nothing had happened.  The operation
+produces a default value, which depends on the exception (see the table
+below).  Your program can check the status word to find out which
+exceptions happened.
+
+Alternatively, you can enable @dfn{traps} for exceptions.  In that case,
+when an exception is raised, your program will receive the @code{SIGFPE}
+signal.  The default action for this signal is to terminate the
+program.  @xref{Signal Handling}, for how you can change the effect of
+the signal.
+
+@findex matherr
+In the System V math library, the user-defined function @code{matherr}
+is called when certain exceptions occur inside math library functions.
+However, the Unix98 standard deprecates this interface.  We support it
+for historical compatibility, but recommend that you do not use it in
+new programs.  When this interface is used, exceptions may not be
+raised.
+
+@noindent
+The exceptions defined in @w{IEEE 754} are:
+
+@table @samp
+@item Invalid Operation
+This exception is raised if the given operands are invalid for the
+operation to be performed.  Examples are
+(see @w{IEEE 754}, @w{section 7}):
+@enumerate
+@item
+Addition or subtraction: @math{@infinity{} - @infinity{}}.  (But
+@math{@infinity{} + @infinity{} = @infinity{}}).
+@item
+Multiplication: @math{0 @mul{} @infinity{}}.
+@item
+Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
+@item
+Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
+infinite.
+@item
+Square root if the operand is less then zero.  More generally, any
+mathematical function evaluated outside its domain produces this
+exception.
+@item
+Conversion of a floating-point number to an integer or decimal
+string, when the number cannot be represented in the target format (due
+to overflow, infinity, or NaN).
+@item
+Conversion of an unrecognizable input string.
+@item
+Comparison via predicates involving @math{<} or @math{>}, when one or
+other of the operands is NaN.  You can prevent this exception by using
+the unordered comparison functions instead; see @ref{FP Comparison Functions}.
+@end enumerate
+
+If the exception does not trap, the result of the operation is NaN.
+
+@item Division by Zero
+This exception is raised when a finite nonzero number is divided
+by zero.  If no trap occurs the result is either @math{+@infinity{}} or
+@math{-@infinity{}}, depending on the signs of the operands.
+
+@item Overflow
+This exception is raised whenever the result cannot be represented
+as a finite value in the precision format of the destination.  If no trap
+occurs the result depends on the sign of the intermediate result and the
+current rounding mode (@w{IEEE 754}, @w{section 7.3}):
+@enumerate
+@item
+Round to nearest carries all overflows to @math{@infinity{}}
+with the sign of the intermediate result.
+@item
+Round toward @math{0} carries all overflows to the largest representable
+finite number with the sign of the intermediate result.
+@item
+Round toward @math{-@infinity{}} carries positive overflows to the
+largest representable finite number and negative overflows to
+@math{-@infinity{}}.
+
+@item
+Round toward @math{@infinity{}} carries negative overflows to the
+most negative representable finite number and positive overflows
+to @math{@infinity{}}.
+@end enumerate
+
+Whenever the overflow exception is raised, the inexact exception is also
+raised.
+
+@item Underflow
+The underflow exception is raised when an intermediate result is too
+small to be calculated accurately, or if the operation's result rounded
+to the destination precision is too small to be normalized.
+
+When no trap is installed for the underflow exception, underflow is
+signaled (via the underflow flag) only when both tininess and loss of
+accuracy have been detected.  If no trap handler is installed the
+operation continues with an imprecise small value, or zero if the
+destination precision cannot hold the small exact result.
+
+@item Inexact
+This exception is signalled if a rounded result is not exact (such as
+when calculating the square root of two) or a result overflows without
+an overflow trap.
+@end table
+
+@node Infinity and NaN
+@subsection Infinity and NaN
+@cindex infinity
+@cindex not a number
+@cindex NaN
+
+@w{IEEE 754} floating point numbers can represent positive or negative
+infinity, and @dfn{NaN} (not a number).  These three values arise from
+calculations whose result is undefined or cannot be represented
+accurately.  You can also deliberately set a floating-point variable to
+any of them, which is sometimes useful.  Some examples of calculations
+that produce infinity or NaN:
+
+@ifnottex
+@smallexample
+@math{1/0 = @infinity{}}
+@math{log (0) = -@infinity{}}
+@math{sqrt (-1) = NaN}
+@end smallexample
+@end ifnottex
+@tex
+$${1\over0} = \infty$$
+$$\log 0 = -\infty$$
+$$\sqrt{-1} = \hbox{NaN}$$
+@end tex
+
+When a calculation produces any of these values, an exception also
+occurs; see @ref{FP Exceptions}.
+
+The basic operations and math functions all accept infinity and NaN and
+produce sensible output.  Infinities propagate through calculations as
+one would expect: for example, @math{2 + @infinity{} = @infinity{}},
+@math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}.  NaN, on
+the other hand, infects any calculation that involves it.  Unless the
+calculation would produce the same result no matter what real value
+replaced NaN, the result is NaN.
+
+In comparison operations, positive infinity is larger than all values
+except itself and NaN, and negative infinity is smaller than all values
+except itself and NaN.  NaN is @dfn{unordered}: it is not equal to,
+greater than, or less than anything, @emph{including itself}. @code{x ==
+x} is false if the value of @code{x} is NaN.  You can use this to test
+whether a value is NaN or not, but the recommended way to test for NaN
+is with the @code{isnan} function (@pxref{Floating Point Classes}).  In
+addition, @code{<}, @code{>}, @code{<=}, and @code{>=} will raise an
+exception when applied to NaNs.
+
+@file{math.h} defines macros that allow you to explicitly set a variable
+to infinity or NaN.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro float INFINITY
+An expression representing positive infinity.  It is equal to the value
+produced  by mathematical operations like @code{1.0 / 0.0}.
+@code{-INFINITY} represents negative infinity.
+
+You can test whether a floating-point value is infinite by comparing it
+to this macro.  However, this is not recommended; you should use the
+@code{isfinite} macro instead.  @xref{Floating Point Classes}.
+
+This macro was introduced in the @w{ISO C99} standard.
+@end deftypevr
+
+@comment math.h
+@comment GNU
+@deftypevr Macro float NAN
+An expression representing a value which is ``not a number''.  This
+macro is a GNU extension, available only on machines that support the
+``not a number'' value---that is to say, on all machines that support
+IEEE floating point.
+
+You can use @samp{#ifdef NAN} to test whether the machine supports
+NaN.  (Of course, you must arrange for GNU extensions to be visible,
+such as by defining @code{_GNU_SOURCE}, and then you must include
+@file{math.h}.)
+@end deftypevr
+
+@w{IEEE 754} also allows for another unusual value: negative zero.  This
+value is produced when you divide a positive number by negative
+infinity, or when a negative result is smaller than the limits of
+representation.
+
+@node Status bit operations
+@subsection Examining the FPU status word
+
+@w{ISO C99} defines functions to query and manipulate the
+floating-point status word.  You can use these functions to check for
+untrapped exceptions when it's convenient, rather than worrying about
+them in the middle of a calculation.
+
+These constants represent the various @w{IEEE 754} exceptions.  Not all
+FPUs report all the different exceptions.  Each constant is defined if
+and only if the FPU you are compiling for supports that exception, so
+you can test for FPU support with @samp{#ifdef}.  They are defined in
+@file{fenv.h}.
+
+@vtable @code
+@comment fenv.h
+@comment ISO
+@item FE_INEXACT
+ The inexact exception.
+@comment fenv.h
+@comment ISO
+@item FE_DIVBYZERO
+ The divide by zero exception.
+@comment fenv.h
+@comment ISO
+@item FE_UNDERFLOW
+ The underflow exception.
+@comment fenv.h
+@comment ISO
+@item FE_OVERFLOW
+ The overflow exception.
+@comment fenv.h
+@comment ISO
+@item FE_INVALID
+ The invalid exception.
+@end vtable
+
+The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
+which are supported by the FP implementation.
+
+These functions allow you to clear exception flags, test for exceptions,
+and save and restore the set of exceptions flagged.
+
+@comment fenv.h
+@comment ISO
+@deftypefun int feclearexcept (int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{@assposix{}}@acsafe{@acsposix{}}}
+@c The other functions in this section that modify FP status register
+@c mostly do so with non-atomic load-modify-store sequences, but since
+@c the register is thread-specific, this should be fine, and safe for
+@c cancellation.  As long as the FP environment is restored before the
+@c signal handler returns control to the interrupted thread (like any
+@c kernel should do), the functions are also safe for use in signal
+@c handlers.
+This function clears all of the supported exception flags indicated by
+@var{excepts}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment ISO
+@deftypefun int feraiseexcept (int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function raises the supported exceptions indicated by
+@var{excepts}.  If more than one exception bit in @var{excepts} is set
+the order in which the exceptions are raised is undefined except that
+overflow (@code{FE_OVERFLOW}) or underflow (@code{FE_UNDERFLOW}) are
+raised before inexact (@code{FE_INEXACT}).  Whether for overflow or
+underflow the inexact exception is also raised is also implementation
+dependent.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fetestexcept (int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Test whether the exception flags indicated by the parameter @var{except}
+are currently set.  If any of them are, a nonzero value is returned
+which specifies which exceptions are set.  Otherwise the result is zero.
+@end deftypefun
+
+To understand these functions, imagine that the status word is an
+integer variable named @var{status}.  @code{feclearexcept} is then
+equivalent to @samp{status &= ~excepts} and @code{fetestexcept} is
+equivalent to @samp{(status & excepts)}.  The actual implementation may
+be very different, of course.
+
+Exception flags are only cleared when the program explicitly requests it,
+by calling @code{feclearexcept}.  If you want to check for exceptions
+from a set of calculations, you should clear all the flags first.  Here
+is a simple example of the way to use @code{fetestexcept}:
+
+@smallexample
+@{
+  double f;
+  int raised;
+  feclearexcept (FE_ALL_EXCEPT);
+  f = compute ();
+  raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
+  if (raised & FE_OVERFLOW) @{ /* @dots{} */ @}
+  if (raised & FE_INVALID) @{ /* @dots{} */ @}
+  /* @dots{} */
+@}
+@end smallexample
+
+You cannot explicitly set bits in the status word.  You can, however,
+save the entire status word and restore it later.  This is done with the
+following functions:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function stores in the variable pointed to by @var{flagp} an
+implementation-defined value representing the current setting of the
+exception flags indicated by @var{excepts}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function restores the flags for the exceptions indicated by
+@var{excepts} to the values stored in the variable pointed to by
+@var{flagp}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+Note that the value stored in @code{fexcept_t} bears no resemblance to
+the bit mask returned by @code{fetestexcept}.  The type may not even be
+an integer.  Do not attempt to modify an @code{fexcept_t} variable.
+
+@node Math Error Reporting
+@subsection Error Reporting by Mathematical Functions
+@cindex errors, mathematical
+@cindex domain error
+@cindex range error
+
+Many of the math functions are defined only over a subset of the real or
+complex numbers.  Even if they are mathematically defined, their result
+may be larger or smaller than the range representable by their return
+type without loss of accuracy.  These are known as @dfn{domain errors},
+@dfn{overflows}, and
+@dfn{underflows}, respectively.  Math functions do several things when
+one of these errors occurs.  In this manual we will refer to the
+complete response as @dfn{signalling} a domain error, overflow, or
+underflow.
+
+When a math function suffers a domain error, it raises the invalid
+exception and returns NaN.  It also sets @var{errno} to @code{EDOM};
+this is for compatibility with old systems that do not support @w{IEEE
+754} exception handling.  Likewise, when overflow occurs, math
+functions raise the overflow exception and, in the default rounding
+mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate
+(in other rounding modes, the largest finite value of the appropriate
+sign is returned when appropriate for that rounding mode).  They also
+set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or
+@math{-@infinity{}}; @var{errno} may or may not be set to
+@code{ERANGE} when a finite value is returned on overflow.  When
+underflow occurs, the underflow exception is raised, and zero
+(appropriately signed) or a subnormal value, as appropriate for the
+mathematical result of the function and the rounding mode, is
+returned.  @var{errno} may be set to @code{ERANGE}, but this is not
+guaranteed; it is intended that @theglibc{} should set it when the
+underflow is to an appropriately signed zero, but not necessarily for
+other underflows.
+
+Some of the math functions are defined mathematically to result in a
+complex value over parts of their domains.  The most familiar example of
+this is taking the square root of a negative number.  The complex math
+functions, such as @code{csqrt}, will return the appropriate complex value
+in this case.  The real-valued functions, such as @code{sqrt}, will
+signal a domain error.
+
+Some older hardware does not support infinities.  On that hardware,
+overflows instead return a particular very large number (usually the
+largest representable number).  @file{math.h} defines macros you can use
+to test for overflow on both old and new hardware.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro double HUGE_VAL
+@comment math.h
+@comment ISO
+@deftypevrx Macro float HUGE_VALF
+@comment math.h
+@comment ISO
+@deftypevrx Macro {long double} HUGE_VALL
+An expression representing a particular very large number.  On machines
+that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity.
+On other machines, it's typically the largest positive number that can
+be represented.
+
+Mathematical functions return the appropriately typed version of
+@code{HUGE_VAL} or @code{@minus{}HUGE_VAL} when the result is too large
+to be represented.
+@end deftypevr
+
+@node Rounding
+@section Rounding Modes
+
+Floating-point calculations are carried out internally with extra
+precision, and then rounded to fit into the destination type.  This
+ensures that results are as precise as the input data.  @w{IEEE 754}
+defines four possible rounding modes:
+
+@table @asis
+@item Round to nearest.
+This is the default mode.  It should be used unless there is a specific
+need for one of the others.  In this mode results are rounded to the
+nearest representable value.  If the result is midway between two
+representable values, the even representable is chosen. @dfn{Even} here
+means the lowest-order bit is zero.  This rounding mode prevents
+statistical bias and guarantees numeric stability: round-off errors in a
+lengthy calculation will remain smaller than half of @code{FLT_EPSILON}.
+
+@c @item Round toward @math{+@infinity{}}
+@item Round toward plus Infinity.
+All results are rounded to the smallest representable value
+which is greater than the result.
+
+@c @item Round toward @math{-@infinity{}}
+@item Round toward minus Infinity.
+All results are rounded to the largest representable value which is less
+than the result.
+
+@item Round toward zero.
+All results are rounded to the largest representable value whose
+magnitude is less than that of the result.  In other words, if the
+result is negative it is rounded up; if it is positive, it is rounded
+down.
+@end table
+
+@noindent
+@file{fenv.h} defines constants which you can use to refer to the
+various rounding modes.  Each one will be defined if and only if the FPU
+supports the corresponding rounding mode.
+
+@table @code
+@comment fenv.h
+@comment ISO
+@vindex FE_TONEAREST
+@item FE_TONEAREST
+Round to nearest.
+
+@comment fenv.h
+@comment ISO
+@vindex FE_UPWARD
+@item FE_UPWARD
+Round toward @math{+@infinity{}}.
+
+@comment fenv.h
+@comment ISO
+@vindex FE_DOWNWARD
+@item FE_DOWNWARD
+Round toward @math{-@infinity{}}.
+
+@comment fenv.h
+@comment ISO
+@vindex FE_TOWARDZERO
+@item FE_TOWARDZERO
+Round toward zero.
+@end table
+
+Underflow is an unusual case.  Normally, @w{IEEE 754} floating point
+numbers are always normalized (@pxref{Floating Point Concepts}).
+Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent,
+@code{FLT_MIN_RADIX-1} for @var{float}) cannot be represented as
+normalized numbers.  Rounding all such numbers to zero or @math{2^r}
+would cause some algorithms to fail at 0.  Therefore, they are left in
+denormalized form.  That produces loss of precision, since some bits of
+the mantissa are stolen to indicate the decimal point.
+
+If a result is too small to be represented as a denormalized number, it
+is rounded to zero.  However, the sign of the result is preserved; if
+the calculation was negative, the result is @dfn{negative zero}.
+Negative zero can also result from some operations on infinity, such as
+@math{4/-@infinity{}}.
+
+At any time one of the above four rounding modes is selected.  You can
+find out which one with this function:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fegetround (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns the currently selected rounding mode, represented by one of the
+values of the defined rounding mode macros.
+@end deftypefun
+
+@noindent
+To change the rounding mode, use this function:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fesetround (int @var{round})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Changes the currently selected rounding mode to @var{round}.  If
+@var{round} does not correspond to one of the supported rounding modes
+nothing is changed.  @code{fesetround} returns zero if it changed the
+rounding mode, a nonzero value if the mode is not supported.
+@end deftypefun
+
+You should avoid changing the rounding mode if possible.  It can be an
+expensive operation; also, some hardware requires you to compile your
+program differently for it to work.  The resulting code may run slower.
+See your compiler documentation for details.
+@c This section used to claim that functions existed to round one number
+@c in a specific fashion.  I can't find any functions in the library
+@c that do that. -zw
+
+@node Control Functions
+@section Floating-Point Control Functions
+
+@w{IEEE 754} floating-point implementations allow the programmer to
+decide whether traps will occur for each of the exceptions, by setting
+bits in the @dfn{control word}.  In C, traps result in the program
+receiving the @code{SIGFPE} signal; see @ref{Signal Handling}.
+
+@strong{NB:} @w{IEEE 754} says that trap handlers are given details of
+the exceptional situation, and can set the result value.  C signals do
+not provide any mechanism to pass this information back and forth.
+Trapping exceptions in C is therefore not very useful.
+
+It is sometimes necessary to save the state of the floating-point unit
+while you perform some calculation.  The library provides functions
+which save and restore the exception flags, the set of exceptions that
+generate traps, and the rounding mode.  This information is known as the
+@dfn{floating-point environment}.
+
+The functions to save and restore the floating-point environment all use
+a variable of type @code{fenv_t} to store information.  This type is
+defined in @file{fenv.h}.  Its size and contents are
+implementation-defined.  You should not attempt to manipulate a variable
+of this type directly.
+
+To save the state of the FPU, use one of these functions:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fegetenv (fenv_t *@var{envp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Store the floating-point environment in the variable pointed to by
+@var{envp}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment ISO
+@deftypefun int feholdexcept (fenv_t *@var{envp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Store the current floating-point environment in the object pointed to by
+@var{envp}.  Then clear all exception flags, and set the FPU to trap no
+exceptions.  Not all FPUs support trapping no exceptions; if
+@code{feholdexcept} cannot set this mode, it returns nonzero value.  If it
+succeeds, it returns zero.
+@end deftypefun
+
+The functions which restore the floating-point environment can take these
+kinds of arguments:
+
+@itemize @bullet
+@item
+Pointers to @code{fenv_t} objects, which were initialized previously by a
+call to @code{fegetenv} or @code{feholdexcept}.
+@item
+@vindex FE_DFL_ENV
+The special macro @code{FE_DFL_ENV} which represents the floating-point
+environment as it was available at program start.
+@item
+Implementation defined macros with names starting with @code{FE_} and
+having type @code{fenv_t *}.
+
+@vindex FE_NOMASK_ENV
+If possible, @theglibc{} defines a macro @code{FE_NOMASK_ENV}
+which represents an environment where every exception raised causes a
+trap to occur.  You can test for this macro using @code{#ifdef}.  It is
+only defined if @code{_GNU_SOURCE} is defined.
+
+Some platforms might define other predefined environments.
+@end itemize
+
+@noindent
+To set the floating-point environment, you can use either of these
+functions:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fesetenv (const fenv_t *@var{envp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the floating-point environment to that described by @var{envp}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment ISO
+@deftypefun int feupdateenv (const fenv_t *@var{envp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Like @code{fesetenv}, this function sets the floating-point environment
+to that described by @var{envp}.  However, if any exceptions were
+flagged in the status word before @code{feupdateenv} was called, they
+remain flagged after the call.  In other words, after @code{feupdateenv}
+is called, the status word is the bitwise OR of the previous status word
+and the one saved in @var{envp}.
+
+The function returns zero in case the operation was successful, a
+non-zero value otherwise.
+@end deftypefun
+
+@noindent
+To control for individual exceptions if raising them causes a trap to
+occur, you can use the following two functions.
+
+@strong{Portability Note:} These functions are all GNU extensions.
+
+@comment fenv.h
+@comment GNU
+@deftypefun int feenableexcept (int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This functions enables traps for each of the exceptions as indicated by
+the parameter @var{except}.  The individual exceptions are described in
+@ref{Status bit operations}.  Only the specified exceptions are
+enabled, the status of the other exceptions is not changed.
+
+The function returns the previous enabled exceptions in case the
+operation was successful, @code{-1} otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment GNU
+@deftypefun int fedisableexcept (int @var{excepts})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This functions disables traps for each of the exceptions as indicated by
+the parameter @var{except}.  The individual exceptions are described in
+@ref{Status bit operations}.  Only the specified exceptions are
+disabled, the status of the other exceptions is not changed.
+
+The function returns the previous enabled exceptions in case the
+operation was successful, @code{-1} otherwise.
+@end deftypefun
+
+@comment fenv.h
+@comment GNU
+@deftypefun int fegetexcept (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function returns a bitmask of all currently enabled exceptions.  It
+returns @code{-1} in case of failure.
+@end deftypefun
+
+@node Arithmetic Functions
+@section Arithmetic Functions
+
+The C library provides functions to do basic operations on
+floating-point numbers.  These include absolute value, maximum and minimum,
+normalization, bit twiddling, rounding, and a few others.
+
+@menu
+* 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.
+@end menu
+
+@node Absolute Value
+@subsection Absolute Value
+@cindex absolute value functions
+
+These functions are provided for obtaining the @dfn{absolute value} (or
+@dfn{magnitude}) of a number.  The absolute value of a real number
+@var{x} is @var{x} if @var{x} is positive, @minus{}@var{x} if @var{x} is
+negative.  For a complex number @var{z}, whose real part is @var{x} and
+whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
+(@var{x}*@var{x} + @var{y}*@var{y})}}.
+
+@pindex math.h
+@pindex stdlib.h
+Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
+@code{imaxabs} is declared in @file{inttypes.h};
+@code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}.
+@code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int abs (int @var{number})
+@comment stdlib.h
+@comment ISO
+@deftypefunx {long int} labs (long int @var{number})
+@comment stdlib.h
+@comment ISO
+@deftypefunx {long long int} llabs (long long int @var{number})
+@comment inttypes.h
+@comment ISO
+@deftypefunx intmax_t imaxabs (intmax_t @var{number})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the absolute value of @var{number}.
+
+Most computers use a two's complement integer representation, in which
+the absolute value of @code{INT_MIN} (the smallest possible @code{int})
+cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
+
+@code{llabs} and @code{imaxdiv} are new to @w{ISO C99}.
+
+See @ref{Integers} for a description of the @code{intmax_t} type.
+
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double fabs (double @var{number})
+@comment math.h
+@comment ISO
+@deftypefunx float fabsf (float @var{number})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fabsl (long double @var{number})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns the absolute value of the floating-point number
+@var{number}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun double cabs (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx float cabsf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {long double} cabsl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the absolute  value of the complex number @var{z}
+(@pxref{Complex Numbers}).  The absolute value of a complex number is:
+
+@smallexample
+sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
+@end smallexample
+
+This function should always be used instead of the direct formula
+because it takes special care to avoid losing precision.  It may also
+take advantage of hardware support for this operation.  See @code{hypot}
+in @ref{Exponents and Logarithms}.
+@end deftypefun
+
+@node Normalization Functions
+@subsection Normalization Functions
+@cindex normalization functions (floating-point)
+
+The functions described in this section are primarily provided as a way
+to efficiently perform certain low-level manipulations on floating point
+numbers that are represented internally using a binary radix;
+see @ref{Floating Point Concepts}.  These functions are required to
+have equivalent behavior even if the representation does not use a radix
+of 2, but of course they are unlikely to be particularly efficient in
+those cases.
+
+@pindex math.h
+All these functions are declared in @file{math.h}.
+
+@comment math.h
+@comment ISO
+@deftypefun double frexp (double @var{value}, int *@var{exponent})
+@comment math.h
+@comment ISO
+@deftypefunx float frexpf (float @var{value}, int *@var{exponent})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are used to split the number @var{value}
+into a normalized fraction and an exponent.
+
+If the argument @var{value} is not zero, the return value is @var{value}
+times a power of two, and its magnitude is always in the range 1/2
+(inclusive) to 1 (exclusive).  The corresponding exponent is stored in
+@code{*@var{exponent}}; the return value multiplied by 2 raised to this
+exponent equals the original number @var{value}.
+
+For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
+stores @code{4} in @code{exponent}.
+
+If @var{value} is zero, then the return value is zero and
+zero is stored in @code{*@var{exponent}}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double ldexp (double @var{value}, int @var{exponent})
+@comment math.h
+@comment ISO
+@deftypefunx float ldexpf (float @var{value}, int @var{exponent})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the result of multiplying the floating-point
+number @var{value} by 2 raised to the power @var{exponent}.  (It can
+be used to reassemble floating-point numbers that were taken apart
+by @code{frexp}.)
+
+For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
+@end deftypefun
+
+The following functions, which come from BSD, provide facilities
+equivalent to those of @code{ldexp} and @code{frexp}.  See also the
+@w{ISO C} function @code{logb} which originally also appeared in BSD.
+
+@comment math.h
+@comment BSD
+@deftypefun double scalb (double @var{value}, double @var{exponent})
+@comment math.h
+@comment BSD
+@deftypefunx float scalbf (float @var{value}, float @var{exponent})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{scalb} function is the BSD name for @code{ldexp}.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun double scalbn (double @var{x}, int @var{n})
+@comment math.h
+@comment BSD
+@deftypefunx float scalbnf (float @var{x}, int @var{n})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} scalbnl (long double @var{x}, int @var{n})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{scalbn} is identical to @code{scalb}, except that the exponent
+@var{n} is an @code{int} instead of a floating-point number.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun double scalbln (double @var{x}, long int @var{n})
+@comment math.h
+@comment BSD
+@deftypefunx float scalblnf (float @var{x}, long int @var{n})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{scalbln} is identical to @code{scalb}, except that the exponent
+@var{n} is a @code{long int} instead of a floating-point number.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun double significand (double @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx float significandf (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} significandl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{significand} returns the mantissa of @var{x} scaled to the range
+@math{[1, 2)}.
+It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}.
+
+This function exists mainly for use in certain standardized tests
+of @w{IEEE 754} conformance.
+@end deftypefun
+
+@node Rounding Functions
+@subsection Rounding Functions
+@cindex converting floats to integers
+
+@pindex math.h
+The functions listed here perform operations such as rounding and
+truncation of floating-point values.  Some of these functions convert
+floating point numbers to integer values.  They are all declared in
+@file{math.h}.
+
+You can also convert floating-point numbers to integers simply by
+casting them to @code{int}.  This discards the fractional part,
+effectively rounding towards zero.  However, this only works if the
+result can actually be represented as an @code{int}---for very large
+numbers, this is impossible.  The functions listed here return the
+result as a @code{double} instead to get around this problem.
+
+@comment math.h
+@comment ISO
+@deftypefun double ceil (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float ceilf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} ceill (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions round @var{x} upwards to the nearest integer,
+returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
+is @code{2.0}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double floor (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float floorf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} floorl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions round @var{x} downwards to the nearest
+integer, returning that value as a @code{double}.  Thus, @code{floor
+(1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double trunc (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float truncf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} truncl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{trunc} functions round @var{x} towards zero to the nearest
+integer (returned in floating-point format).  Thus, @code{trunc (1.5)}
+is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double rint (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float rintf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} rintl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions round @var{x} to an integer value according to the
+current rounding mode.  @xref{Floating Point Parameters}, for
+information about the various rounding modes.  The default
+rounding mode is to round to the nearest integer; some machines
+support other modes, but round-to-nearest is always used unless
+you explicitly select another.
+
+If @var{x} was not initially an integer, these functions raise the
+inexact exception.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double nearbyint (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float nearbyintf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} nearbyintl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the same value as the @code{rint} functions, but
+do not raise the inexact exception if @var{x} is not an integer.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double round (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float roundf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} roundl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are similar to @code{rint}, but they round halfway
+cases away from zero instead of to the nearest integer (or other
+current rounding mode).
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun {long int} lrint (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long int} lrintf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long int} lrintl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are just like @code{rint}, but they return a
+@code{long int} instead of a floating-point number.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun {long long int} llrint (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long long int} llrintf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long long int} llrintl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are just like @code{rint}, but they return a
+@code{long long int} instead of a floating-point number.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun {long int} lround (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long int} lroundf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long int} lroundl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are just like @code{round}, but they return a
+@code{long int} instead of a floating-point number.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun {long long int} llround (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long long int} llroundf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long long int} llroundl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are just like @code{round}, but they return a
+@code{long long int} instead of a floating-point number.
+@end deftypefun
+
+
+@comment math.h
+@comment ISO
+@deftypefun double modf (double @var{value}, double *@var{integer-part})
+@comment math.h
+@comment ISO
+@deftypefunx float modff (float @var{value}, float *@var{integer-part})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions break the argument @var{value} into an integer part and a
+fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
+equals @var{value}.  Each of the parts has the same sign as @var{value},
+and the integer part is always rounded toward zero.
+
+@code{modf} stores the integer part in @code{*@var{integer-part}}, and
+returns the fractional part.  For example, @code{modf (2.5, &intpart)}
+returns @code{0.5} and stores @code{2.0} into @code{intpart}.
+@end deftypefun
+
+@node Remainder Functions
+@subsection Remainder Functions
+
+The functions in this section compute the remainder on division of two
+floating-point numbers.  Each is a little different; pick the one that
+suits your problem.
+
+@comment math.h
+@comment ISO
+@deftypefun double fmod (double @var{numerator}, double @var{denominator})
+@comment math.h
+@comment ISO
+@deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the remainder from the division of
+@var{numerator} by @var{denominator}.  Specifically, the return value is
+@code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
+is the quotient of @var{numerator} divided by @var{denominator}, rounded
+towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
+@code{1.9}, which is @code{6.5} minus @code{4.6}.
+
+The result has the same sign as the @var{numerator} and has magnitude
+less than the magnitude of the @var{denominator}.
+
+If @var{denominator} is zero, @code{fmod} signals a domain error.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun double drem (double @var{numerator}, double @var{denominator})
+@comment math.h
+@comment BSD
+@deftypefunx float dremf (float @var{numerator}, float @var{denominator})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are like @code{fmod} except that they round the
+internal quotient @var{n} to the nearest integer instead of towards zero
+to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
+which is @code{6.5} minus @code{6.9}.
+
+The absolute value of the result is less than or equal to half the
+absolute value of the @var{denominator}.  The difference between
+@code{fmod (@var{numerator}, @var{denominator})} and @code{drem
+(@var{numerator}, @var{denominator})} is always either
+@var{denominator}, minus @var{denominator}, or zero.
+
+If @var{denominator} is zero, @code{drem} signals a domain error.
+@end deftypefun
+
+@comment math.h
+@comment BSD
+@deftypefun double remainder (double @var{numerator}, double @var{denominator})
+@comment math.h
+@comment BSD
+@deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is another name for @code{drem}.
+@end deftypefun
+
+@node FP Bit Twiddling
+@subsection Setting and modifying single bits of FP values
+@cindex FP arithmetic
+
+There are some operations that are too complicated or expensive to
+perform by hand on floating-point numbers.  @w{ISO C99} defines
+functions to do these operations, which mostly involve changing single
+bits.
+
+@comment math.h
+@comment ISO
+@deftypefun double copysign (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float copysignf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return @var{x} but with the sign of @var{y}.  They work
+even if @var{x} or @var{y} are NaN or zero.  Both of these can carry a
+sign (although not all implementations support it) and this is one of
+the few operations that can tell the difference.
+
+@code{copysign} never raises an exception.
+@c except signalling NaNs
+
+This function is defined in @w{IEC 559} (and the appendix with
+recommended functions in @w{IEEE 754}/@w{IEEE 854}).
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int signbit (@emph{float-type} @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{signbit} is a generic macro which can work on all floating-point
+types.  It returns a nonzero value if the value of @var{x} has its sign
+bit set.
+
+This is not the same as @code{x < 0.0}, because @w{IEEE 754} floating
+point allows zero to be signed.  The comparison @code{-0.0 < 0.0} is
+false, but @code{signbit (-0.0)} will return a nonzero value.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double nextafter (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float nextafterf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{nextafter} function returns the next representable neighbor of
+@var{x} in the direction towards @var{y}.  The size of the step between
+@var{x} and the result depends on the type of the result.  If
+@math{@var{x} = @var{y}} the function simply returns @var{y}.  If either
+value is @code{NaN}, @code{NaN} is returned.  Otherwise
+a value corresponding to the value of the least significant bit in the
+mantissa is added or subtracted, depending on the direction.
+@code{nextafter} will signal overflow or underflow if the result goes
+outside of the range of normalized numbers.
+
+This function is defined in @w{IEC 559} (and the appendix with
+recommended functions in @w{IEEE 754}/@w{IEEE 854}).
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double nexttoward (double @var{x}, long double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float nexttowardf (float @var{x}, long double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are identical to the corresponding versions of
+@code{nextafter} except that their second argument is a @code{long
+double}.
+@end deftypefun
+
+@cindex NaN
+@comment math.h
+@comment ISO
+@deftypefun double nan (const char *@var{tagp})
+@comment math.h
+@comment ISO
+@deftypefunx float nanf (const char *@var{tagp})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} nanl (const char *@var{tagp})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c The unsafe-but-ruled-safe locale use comes from strtod.
+The @code{nan} function returns a representation of NaN, provided that
+NaN is supported by the target platform.
+@code{nan ("@var{n-char-sequence}")} is equivalent to
+@code{strtod ("NAN(@var{n-char-sequence})")}.
+
+The argument @var{tagp} is used in an unspecified manner.  On @w{IEEE
+754} systems, there are many representations of NaN, and @var{tagp}
+selects one.  On other systems it may do nothing.
+@end deftypefun
+
+@node FP Comparison Functions
+@subsection Floating-Point Comparison Functions
+@cindex unordered comparison
+
+The standard C comparison operators provoke exceptions when one or other
+of the operands is NaN.  For example,
+
+@smallexample
+int v = a < 1.0;
+@end smallexample
+
+@noindent
+will raise an exception if @var{a} is NaN.  (This does @emph{not}
+happen with @code{==} and @code{!=}; those merely return false and true,
+respectively, when NaN is examined.)  Frequently this exception is
+undesirable.  @w{ISO C99} therefore defines comparison functions that
+do not raise exceptions when NaN is examined.  All of the functions are
+implemented as macros which allow their arguments to be of any
+floating-point type.  The macros are guaranteed to evaluate their
+arguments only once.
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether the argument @var{x} is greater than
+@var{y}.  It is equivalent to @code{(@var{x}) > (@var{y})}, but no
+exception is raised if @var{x} or @var{y} are NaN.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether the argument @var{x} is greater than or
+equal to @var{y}.  It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
+exception is raised if @var{x} or @var{y} are NaN.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether the argument @var{x} is less than @var{y}.
+It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
+raised if @var{x} or @var{y} are NaN.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether the argument @var{x} is less than or equal
+to @var{y}.  It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
+exception is raised if @var{x} or @var{y} are NaN.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether the argument @var{x} is less or greater
+than @var{y}.  It is equivalent to @code{(@var{x}) < (@var{y}) ||
+(@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y}
+once), but no exception is raised if @var{x} or @var{y} are NaN.
+
+This macro is not equivalent to @code{@var{x} != @var{y}}, because that
+expression is true if @var{x} or @var{y} are NaN.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro determines whether its arguments are unordered.  In other
+words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
+@end deftypefn
+
+Not all machines provide hardware support for these operations.  On
+machines that don't, the macros can be very slow.  Therefore, you should
+not use these functions when NaN is not a concern.
+
+@strong{NB:} There are no macros @code{isequal} or @code{isunequal}.
+They are unnecessary, because the @code{==} and @code{!=} operators do
+@emph{not} throw an exception if one or both of the operands are NaN.
+
+@node Misc FP Arithmetic
+@subsection Miscellaneous FP arithmetic functions
+@cindex minimum
+@cindex maximum
+@cindex positive difference
+@cindex multiply-add
+
+The functions in this section perform miscellaneous but common
+operations that are awkward to express with C operators.  On some
+processors these functions can use special machine instructions to
+perform these operations faster than the equivalent C code.
+
+@comment math.h
+@comment ISO
+@deftypefun double fmin (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float fminf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fmin} function returns the lesser of the two values @var{x}
+and @var{y}.  It is similar to the expression
+@smallexample
+((x) < (y) ? (x) : (y))
+@end smallexample
+except that @var{x} and @var{y} are only evaluated once.
+
+If an argument is NaN, the other argument is returned.  If both arguments
+are NaN, NaN is returned.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double fmax (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float fmaxf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fmax} function returns the greater of the two values @var{x}
+and @var{y}.
+
+If an argument is NaN, the other argument is returned.  If both arguments
+are NaN, NaN is returned.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double fdim (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float fdimf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fdim} function returns the positive difference between
+@var{x} and @var{y}.  The positive difference is @math{@var{x} -
+@var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise.
+
+If @var{x}, @var{y}, or both are NaN, NaN is returned.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
+@comment math.h
+@comment ISO
+@deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
+@cindex butterfly
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fma} function performs floating-point multiply-add.  This is
+the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the
+intermediate result is not rounded to the destination type.  This can
+sometimes improve the precision of a calculation.
+
+This function was introduced because some processors have a special
+instruction to perform multiply-add.  The C compiler cannot use it
+directly, because the expression @samp{x*y + z} is defined to round the
+intermediate result.  @code{fma} lets you choose when you want to round
+only once.
+
+@vindex FP_FAST_FMA
+On processors which do not implement multiply-add in hardware,
+@code{fma} can be very slow since it must avoid intermediate rounding.
+@file{math.h} defines the symbols @code{FP_FAST_FMA},
+@code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} when the corresponding
+version of @code{fma} is no slower than the expression @samp{x*y + z}.
+In @theglibc{}, this always means the operation is implemented in
+hardware.
+@end deftypefun
+
+@node Complex Numbers
+@section Complex Numbers
+@pindex complex.h
+@cindex complex numbers
+
+@w{ISO C99} introduces support for complex numbers in C.  This is done
+with a new type qualifier, @code{complex}.  It is a keyword if and only
+if @file{complex.h} has been included.  There are three complex types,
+corresponding to the three real types:  @code{float complex},
+@code{double complex}, and @code{long double complex}.
+
+To construct complex numbers you need a way to indicate the imaginary
+part of a number.  There is no standard notation for an imaginary
+floating point constant.  Instead, @file{complex.h} defines two macros
+that can be used to create complex numbers.
+
+@deftypevr Macro {const float complex} _Complex_I
+This macro is a representation of the complex number ``@math{0+1i}''.
+Multiplying a real floating-point value by @code{_Complex_I} gives a
+complex number whose value is purely imaginary.  You can use this to
+construct complex constants:
+
+@smallexample
+@math{3.0 + 4.0i} = @code{3.0 + 4.0 * _Complex_I}
+@end smallexample
+
+Note that @code{_Complex_I * _Complex_I} has the value @code{-1}, but
+the type of that value is @code{complex}.
+@end deftypevr
+
+@c Put this back in when gcc supports _Imaginary_I.  It's too confusing.
+@ignore
+@noindent
+Without an optimizing compiler this is more expensive than the use of
+@code{_Imaginary_I} but with is better than nothing.  You can avoid all
+the hassles if you use the @code{I} macro below if the name is not
+problem.
+
+@deftypevr Macro {const float imaginary} _Imaginary_I
+This macro is a representation of the value ``@math{1i}''.  I.e., it is
+the value for which
+
+@smallexample
+_Imaginary_I * _Imaginary_I = -1
+@end smallexample
+
+@noindent
+The result is not of type @code{float imaginary} but instead @code{float}.
+One can use it to easily construct complex number like in
+
+@smallexample
+3.0 - _Imaginary_I * 4.0
+@end smallexample
+
+@noindent
+which results in the complex number with a real part of 3.0 and a
+imaginary part -4.0.
+@end deftypevr
+@end ignore
+
+@noindent
+@code{_Complex_I} is a bit of a mouthful.  @file{complex.h} also defines
+a shorter name for the same constant.
+
+@deftypevr Macro {const float complex} I
+This macro has exactly the same value as @code{_Complex_I}.  Most of the
+time it is preferable.  However, it causes problems if you want to use
+the identifier @code{I} for something else.  You can safely write
+
+@smallexample
+#include <complex.h>
+#undef I
+@end smallexample
+
+@noindent
+if you need @code{I} for your own purposes.  (In that case we recommend
+you also define some other short name for @code{_Complex_I}, such as
+@code{J}.)
+
+@ignore
+If the implementation does not support the @code{imaginary} types
+@code{I} is defined as @code{_Complex_I} which is the second best
+solution.  It still can be used in the same way but requires a most
+clever compiler to get the same results.
+@end ignore
+@end deftypevr
+
+@node Operations on Complex
+@section Projections, Conjugates, and Decomposing of Complex Numbers
+@cindex project complex numbers
+@cindex conjugate complex numbers
+@cindex decompose complex numbers
+@pindex complex.h
+
+@w{ISO C99} also defines functions that perform basic operations on
+complex numbers, such as decomposition and conjugation.  The prototypes
+for all these functions are in @file{complex.h}.  All functions are
+available in three variants, one for each of the three complex types.
+
+@comment complex.h
+@comment ISO
+@deftypefun double creal (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx float crealf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {long double} creall (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the real part of the complex number @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun double cimag (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx float cimagf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {long double} cimagl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the imaginary part of the complex number @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} conj (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} conjf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} conjl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the conjugate value of the complex number
+@var{z}.  The conjugate of a complex number has the same real part and a
+negated imaginary part.  In other words, @samp{conj(a + bi) = a + -bi}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun double carg (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx float cargf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {long double} cargl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the argument of the complex number @var{z}.
+The argument of a complex number is the angle in the complex plane
+between the positive real axis and a line passing through zero and the
+number.  This angle is measured in the usual fashion and ranges from
+@math{-@pi{}} to @math{@pi{}}.
+
+@code{carg} has a branch cut along the negative real axis.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cproj (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cprojf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cprojl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the projection of the complex value @var{z} onto
+the Riemann sphere.  Values with an infinite imaginary part are projected
+to positive infinity on the real axis, even if the real part is NaN.  If
+the real part is infinite, the result is equivalent to
+
+@smallexample
+INFINITY + I * copysign (0.0, cimag (z))
+@end smallexample
+@end deftypefun
+
+@node Parsing of Numbers
+@section Parsing of Numbers
+@cindex parsing numbers (in formatted input)
+@cindex converting strings to numbers
+@cindex number syntax, parsing
+@cindex syntax, for reading numbers
+
+This section describes functions for ``reading'' integer and
+floating-point numbers from a string.  It may be more convenient in some
+cases to use @code{sscanf} or one of the related functions; see
+@ref{Formatted Input}.  But often you can make a program more robust by
+finding the tokens in the string by hand, then converting the numbers
+one by one.
+
+@menu
+* Parsing of Integers::         Functions for conversion of integer values.
+* Parsing of Floats::           Functions for conversion of floating-point
+				 values.
+@end menu
+
+@node Parsing of Integers
+@subsection Parsing of Integers
+
+@pindex stdlib.h
+@pindex wchar.h
+The @samp{str} functions are declared in @file{stdlib.h} and those
+beginning with @samp{wcs} are declared in @file{wchar.h}.  One might
+wonder about the use of @code{restrict} in the prototypes of the
+functions in this section.  It is seemingly useless but the @w{ISO C}
+standard uses it (for the functions defined there) so we have to do it
+as well.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c strtol uses the thread-local pointer to the locale in effect, and
+@c strtol_l loads the LC_NUMERIC locale data from it early on and once,
+@c but if the locale is the global locale, and another thread calls
+@c setlocale in a way that modifies the pointer to the LC_CTYPE locale
+@c category, the behavior of e.g. IS*, TOUPPER will vary throughout the
+@c execution of the function, because they re-read the locale data from
+@c the given locale pointer.  We solved this by documenting setlocale as
+@c MT-Unsafe.
+The @code{strtol} (``string-to-long'') function converts the initial
+part of @var{string} to a signed integer, which is returned as a value
+of type @code{long int}.
+
+This function attempts to decompose @var{string} as follows:
+
+@itemize @bullet
+@item
+A (possibly empty) sequence of whitespace characters.  Which characters
+are whitespace is determined by the @code{isspace} function
+(@pxref{Classification of Characters}).  These are discarded.
+
+@item
+An optional plus or minus sign (@samp{+} or @samp{-}).
+
+@item
+A nonempty sequence of digits in the radix specified by @var{base}.
+
+If @var{base} is zero, decimal radix is assumed unless the series of
+digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
+@samp{0X} (specifying hexadecimal radix); in other words, the same
+syntax used for integer constants in C.
+
+Otherwise @var{base} must have a value between @code{2} and @code{36}.
+If @var{base} is @code{16}, the digits may optionally be preceded by
+@samp{0x} or @samp{0X}.  If base has no legal value the value returned
+is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
+
+@item
+Any remaining characters in the string.  If @var{tailptr} is not a null
+pointer, @code{strtol} stores a pointer to this tail in
+@code{*@var{tailptr}}.
+@end itemize
+
+If the string is empty, contains only whitespace, or does not contain an
+initial substring that has the expected syntax for an integer in the
+specified @var{base}, no conversion is performed.  In this case,
+@code{strtol} returns a value of zero and the value stored in
+@code{*@var{tailptr}} is the value of @var{string}.
+
+In a locale other than the standard @code{"C"} locale, this function
+may recognize additional implementation-dependent syntax.
+
+If the string has valid syntax for an integer but the value is not
+representable because of overflow, @code{strtol} returns either
+@code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
+appropriate for the sign of the value.  It also sets @code{errno}
+to @code{ERANGE} to indicate there was overflow.
+
+You should not check for errors by examining the return value of
+@code{strtol}, because the string might be a valid representation of
+@code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}.  Instead, check whether
+@var{tailptr} points to what you expect after the number
+(e.g. @code{'\0'} if the string should end after the number).  You also
+need to clear @var{errno} before the call and check it afterward, in
+case there was overflow.
+
+There is an example at the end of this section.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstol} function is equivalent to the @code{strtol} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{strtoul} (``string-to-unsigned-long'') function is like
+@code{strtol} except it converts to an @code{unsigned long int} value.
+The syntax is the same as described above for @code{strtol}.  The value
+returned on overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
+
+If @var{string} depicts a negative number, @code{strtoul} acts the same
+as @var{strtol} but casts the result to an unsigned integer.  That means
+for example that @code{strtoul} on @code{"-1"} returns @code{ULONG_MAX}
+and an input more negative than @code{LONG_MIN} returns
+(@code{ULONG_MAX} + 1) / 2.
+
+@code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of
+range, or @code{ERANGE} on overflow.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoul} function is equivalent to the @code{strtoul} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{strtoll} function is like @code{strtol} except that it returns
+a @code{long long int} value, and accepts numbers with a correspondingly
+larger range.
+
+If the string has valid syntax for an integer but the value is not
+representable because of overflow, @code{strtoll} returns either
+@code{LLONG_MAX} or @code{LLONG_MIN} (@pxref{Range of Type}), as
+appropriate for the sign of the value.  It also sets @code{errno} to
+@code{ERANGE} to indicate there was overflow.
+
+The @code{strtoll} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoll} function is equivalent to the @code{strtoll} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoq} function is equivalent to the @code{strtoq} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoq} function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{strtoull} function is related to @code{strtoll} the same way
+@code{strtoul} is related to @code{strtol}.
+
+The @code{strtoull} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoull} function is equivalent to the @code{strtoull} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@code{strtouq} is the BSD name for @code{strtoull}.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstouq} function is equivalent to the @code{strtouq} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstouq} function is a GNU extension.
+@end deftypefun
+
+@comment inttypes.h
+@comment ISO
+@deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{strtoimax} function is like @code{strtol} except that it returns
+a @code{intmax_t} value, and accepts numbers of a corresponding range.
+
+If the string has valid syntax for an integer but the value is not
+representable because of overflow, @code{strtoimax} returns either
+@code{INTMAX_MAX} or @code{INTMAX_MIN} (@pxref{Integers}), as
+appropriate for the sign of the value.  It also sets @code{errno} to
+@code{ERANGE} to indicate there was overflow.
+
+See @ref{Integers} for a description of the @code{intmax_t} type.  The
+@code{strtoimax} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoimax} function is equivalent to the @code{strtoimax} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoimax} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment inttypes.h
+@comment ISO
+@deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{strtoumax} function is related to @code{strtoimax}
+the same way that @code{strtoul} is related to @code{strtol}.
+
+See @ref{Integers} for a description of the @code{intmax_t} type.  The
+@code{strtoumax} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstoumax} function is equivalent to the @code{strtoumax} function
+in nearly all aspects but handles wide character strings.
+
+The @code{wcstoumax} function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {long int} atol (const char *@var{string})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is similar to the @code{strtol} function with a @var{base}
+argument of @code{10}, except that it need not detect overflow errors.
+The @code{atol} function is provided mostly for compatibility with
+existing code; using @code{strtol} is more robust.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int atoi (const char *@var{string})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is like @code{atol}, except that it returns an @code{int}.
+The @code{atoi} function is also considered obsolete; use @code{strtol}
+instead.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {long long int} atoll (const char *@var{string})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is similar to @code{atol}, except it returns a @code{long
+long int}.
+
+The @code{atoll} function was introduced in @w{ISO C99}.  It too is
+obsolete (despite having just been added); use @code{strtoll} instead.
+@end deftypefun
+
+All the functions mentioned in this section so far do not handle
+alternative representations of characters as described in the locale
+data.  Some locales specify thousands separator and the way they have to
+be used which can help to make large numbers more readable.  To read
+such numbers one has to use the @code{scanf} functions with the @samp{'}
+flag.
+
+Here is a function which parses a string as a sequence of integers and
+returns the sum of them:
+
+@smallexample
+int
+sum_ints_from_string (char *string)
+@{
+  int sum = 0;
+
+  while (1) @{
+    char *tail;
+    int next;
+
+    /* @r{Skip whitespace by hand, to detect the end.}  */
+    while (isspace (*string)) string++;
+    if (*string == 0)
+      break;
+
+    /* @r{There is more nonwhitespace,}  */
+    /* @r{so it ought to be another number.}  */
+    errno = 0;
+    /* @r{Parse it.}  */
+    next = strtol (string, &tail, 0);
+    /* @r{Add it in, if not overflow.}  */
+    if (errno)
+      printf ("Overflow\n");
+    else
+      sum += next;
+    /* @r{Advance past it.}  */
+    string = tail;
+  @}
+
+  return sum;
+@}
+@end smallexample
+
+@node Parsing of Floats
+@subsection Parsing of Floats
+
+@pindex stdlib.h
+The @samp{str} functions are declared in @file{stdlib.h} and those
+beginning with @samp{wcs} are declared in @file{wchar.h}.  One might
+wonder about the use of @code{restrict} in the prototypes of the
+functions in this section.  It is seemingly useless but the @w{ISO C}
+standard uses it (for the functions defined there) so we have to do it
+as well.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Besides the unsafe-but-ruled-safe locale uses, this uses a lot of
+@c mpn, but it's all safe.
+@c
+@c round_and_return
+@c   get_rounding_mode ok
+@c   mpn_add_1 ok
+@c   mpn_rshift ok
+@c   MPN_ZERO ok
+@c   MPN2FLOAT -> mpn_construct_(float|double|long_double) ok
+@c str_to_mpn
+@c   mpn_mul_1 -> umul_ppmm ok
+@c   mpn_add_1 ok
+@c mpn_lshift_1 -> mpn_lshift ok
+@c STRTOF_INTERNAL
+@c   MPN_VAR ok
+@c   SET_MANTISSA ok
+@c   STRNCASECMP ok, wide and narrow
+@c   round_and_return ok
+@c   mpn_mul ok
+@c     mpn_addmul_1 ok
+@c     ... mpn_sub
+@c   mpn_lshift ok
+@c   udiv_qrnnd ok
+@c   count_leading_zeros ok
+@c   add_ssaaaa ok
+@c   sub_ddmmss ok
+@c   umul_ppmm ok
+@c   mpn_submul_1 ok
+The @code{strtod} (``string-to-double'') function converts the initial
+part of @var{string} to a floating-point number, which is returned as a
+value of type @code{double}.
+
+This function attempts to decompose @var{string} as follows:
+
+@itemize @bullet
+@item
+A (possibly empty) sequence of whitespace characters.  Which characters
+are whitespace is determined by the @code{isspace} function
+(@pxref{Classification of Characters}).  These are discarded.
+
+@item
+An optional plus or minus sign (@samp{+} or @samp{-}).
+
+@item A floating point number in decimal or hexadecimal format.  The
+decimal format is:
+@itemize @minus
+
+@item
+A nonempty sequence of digits optionally containing a decimal-point
+character---normally @samp{.}, but it depends on the locale
+(@pxref{General Numeric}).
+
+@item
+An optional exponent part, consisting of a character @samp{e} or
+@samp{E}, an optional sign, and a sequence of digits.
+
+@end itemize
+
+The hexadecimal format is as follows:
+@itemize @minus
+
+@item
+A 0x or 0X followed by a nonempty sequence of hexadecimal digits
+optionally containing a decimal-point character---normally @samp{.}, but
+it depends on the locale (@pxref{General Numeric}).
+
+@item
+An optional binary-exponent part, consisting of a character @samp{p} or
+@samp{P}, an optional sign, and a sequence of digits.
+
+@end itemize
+
+@item
+Any remaining characters in the string.  If @var{tailptr} is not a null
+pointer, a pointer to this tail of the string is stored in
+@code{*@var{tailptr}}.
+@end itemize
+
+If the string is empty, contains only whitespace, or does not contain an
+initial substring that has the expected syntax for a floating-point
+number, no conversion is performed.  In this case, @code{strtod} returns
+a value of zero and the value returned in @code{*@var{tailptr}} is the
+value of @var{string}.
+
+In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
+this function may recognize additional locale-dependent syntax.
+
+If the string has valid syntax for a floating-point number but the value
+is outside the range of a @code{double}, @code{strtod} will signal
+overflow or underflow as described in @ref{Math Error Reporting}.
+
+@code{strtod} recognizes four special input strings.  The strings
+@code{"inf"} and @code{"infinity"} are converted to @math{@infinity{}},
+or to the largest representable value if the floating-point format
+doesn't support infinities.  You can prepend a @code{"+"} or @code{"-"}
+to specify the sign.  Case is ignored when scanning these strings.
+
+The strings @code{"nan"} and @code{"nan(@var{chars@dots{}})"} are converted
+to NaN.  Again, case is ignored.  If @var{chars@dots{}} are provided, they
+are used in some unspecified fashion to select a particular
+representation of NaN (there can be several).
+
+Since zero is a valid result as well as the value returned on error, you
+should check for errors in the same way as for @code{strtol}, by
+examining @var{errno} and @var{tailptr}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
+@comment stdlib.h
+@comment ISO
+@deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+These functions are analogous to @code{strtod}, but return @code{float}
+and @code{long double} values respectively.  They report errors in the
+same way as @code{strtod}.  @code{strtof} can be substantially faster
+than @code{strtod}, but has less precision; conversely, @code{strtold}
+can be much slower but has more precision (on systems where @code{long
+double} is a separate type).
+
+These functions have been GNU extensions and are new to @w{ISO C99}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
+@comment stdlib.h
+@comment ISO
+@deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@comment stdlib.h
+@comment ISO
+@deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
+equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
+@code{strtold} functions but it handles wide character string.
+
+The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
+C90}.  The @code{wcstof} and @code{wcstold} functions were introduced in
+@w{ISO C99}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun double atof (const char *@var{string})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is similar to the @code{strtod} function, except that it
+need not detect overflow and underflow errors.  The @code{atof} function
+is provided mostly for compatibility with existing code; using
+@code{strtod} is more robust.
+@end deftypefun
+
+@Theglibc{} also provides @samp{_l} versions of these functions,
+which take an additional argument, the locale to use in conversion.
+
+See also @ref{Parsing of Integers}.
+
+@node System V Number Conversion
+@section Old-fashioned System V number-to-string functions
+
+The old @w{System V} C library provided three functions to convert
+numbers to strings, with unusual and hard-to-use semantics.  @Theglibc{}
+also provides these functions and some natural extensions.
+
+These functions are only available in @theglibc{} and on systems descended
+from AT&T Unix.  Therefore, unless these functions do precisely what you
+need, it is better to use @code{sprintf}, which is standard.
+
+All these functions are defined in @file{stdlib.h}.
+
+@comment stdlib.h
+@comment SVID, Unix98
+@deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}}
+The function @code{ecvt} converts the floating-point number @var{value}
+to a string with at most @var{ndigit} decimal digits.  The
+returned string contains no decimal point or sign.  The first digit of
+the string is non-zero (unless @var{value} is actually zero) and the
+last digit is rounded to nearest.  @code{*@var{decpt}} is set to the
+index in the string of the first digit after the decimal point.
+@code{*@var{neg}} is set to a nonzero value if @var{value} is negative,
+zero otherwise.
+
+If @var{ndigit} decimal digits would exceed the precision of a
+@code{double} it is reduced to a system-specific value.
+
+The returned string is statically allocated and overwritten by each call
+to @code{ecvt}.
+
+If @var{value} is zero, it is implementation defined whether
+@code{*@var{decpt}} is @code{0} or @code{1}.
+
+For example: @code{ecvt (12.3, 5, &d, &n)} returns @code{"12300"}
+and sets @var{d} to @code{2} and @var{n} to @code{0}.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, Unix98
+@deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@prelim{}@mtunsafe{@mtasurace{:fcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
+the number of digits after the decimal point.  If @var{ndigit} is less
+than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the
+left of the decimal point.  For example, if @var{ndigit} is @code{-1},
+@var{value} will be rounded to the nearest 10.  If @var{ndigit} is
+negative and larger than the number of digits to the left of the decimal
+point in @var{value}, @var{value} will be rounded to one significant digit.
+
+If @var{ndigit} decimal digits would exceed the precision of a
+@code{double} it is reduced to a system-specific value.
+
+The returned string is statically allocated and overwritten by each call
+to @code{fcvt}.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, Unix98
+@deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s
+@c args_value if it's too large, but gcvt never exercises this path.
+@code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g",
+ndigit, value}.  It is provided only for compatibility's sake.  It
+returns @var{buf}.
+
+If @var{ndigit} decimal digits would exceed the precision of a
+@code{double} it is reduced to a system-specific value.
+@end deftypefun
+
+As extensions, @theglibc{} provides versions of these three
+functions that take @code{long double} arguments.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@prelim{}@mtunsafe{@mtasurace{:qecvt}}@asunsafe{}@acsafe{}}
+This function is equivalent to @code{ecvt} except that it takes a
+@code{long double} for the first parameter and that @var{ndigit} is
+restricted by the precision of a @code{long double}.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
+@safety{@prelim{}@mtunsafe{@mtasurace{:qfcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function is equivalent to @code{fcvt} except that it
+takes a @code{long double} for the first parameter and that @var{ndigit} is
+restricted by the precision of a @code{long double}.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is equivalent to @code{gcvt} except that it takes a
+@code{long double} for the first parameter and that @var{ndigit} is
+restricted by the precision of a @code{long double}.
+@end deftypefun
+
+
+@cindex gcvt_r
+The @code{ecvt} and @code{fcvt} functions, and their @code{long double}
+equivalents, all return a string located in a static buffer which is
+overwritten by the next call to the function.  @Theglibc{}
+provides another set of extended functions which write the converted
+string into a user-supplied buffer.  These have the conventional
+@code{_r} suffix.
+
+@code{gcvt_r} is not necessary, because @code{gcvt} already uses a
+user-supplied buffer.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{ecvt_r} function is the same as @code{ecvt}, except
+that it places its result into the user-specified buffer pointed to by
+@var{buf}, with length @var{len}.  The return value is @code{-1} in
+case of an error and zero otherwise.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, Unix98
+@deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fcvt_r} function is the same as @code{fcvt}, except that it
+places its result into the user-specified buffer pointed to by
+@var{buf}, with length @var{len}.  The return value is @code{-1} in
+case of an error and zero otherwise.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{qecvt_r} function is the same as @code{qecvt}, except
+that it places its result into the user-specified buffer pointed to by
+@var{buf}, with length @var{len}.  The return value is @code{-1} in
+case of an error and zero otherwise.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{qfcvt_r} function is the same as @code{qfcvt}, except
+that it places its result into the user-specified buffer pointed to by
+@var{buf}, with length @var{len}.  The return value is @code{-1} in
+case of an error and zero otherwise.
+
+This function is a GNU extension.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/charset.texi b/ap/libc/glibc/glibc-2.23/manual/charset.texi
new file mode 100644
index 0000000..68aecd3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/charset.texi
@@ -0,0 +1,2989 @@
+@node Character Set Handling, Locales, String and Array Utilities, Top
+@c %MENU% Support for extended character sets
+@chapter Character Set Handling
+
+@ifnottex
+@macro cal{text}
+\text\
+@end macro
+@end ifnottex
+
+Character sets used in the early days of computing had only six, seven,
+or eight bits for each character: there was never a case where more than
+eight bits (one byte) were used to represent a single character.  The
+limitations of this approach became more apparent as more people
+grappled with non-Roman character sets, where not all the characters
+that make up a language's character set can be represented by @math{2^8}
+choices.  This chapter shows the functionality that was added to the C
+library to support multiple character sets.
+
+@menu
+* Extended Char Intro::              Introduction to Extended Characters.
+* Charset Function Overview::        Overview about Character Handling
+                                      Functions.
+* Restartable multibyte conversion:: Restartable multibyte conversion
+                                      Functions.
+* Non-reentrant Conversion::         Non-reentrant Conversion Function.
+* Generic Charset Conversion::       Generic Charset Conversion.
+@end menu
+
+
+@node Extended Char Intro
+@section Introduction to Extended Characters
+
+A variety of solutions is available to overcome the differences between
+character sets with a 1:1 relation between bytes and characters and
+character sets with ratios of 2:1 or 4:1.  The remainder of this
+section gives a few examples to help understand the design decisions
+made while developing the functionality of the @w{C library}.
+
+@cindex internal representation
+A distinction we have to make right away is between internal and
+external representation.  @dfn{Internal representation} means the
+representation used by a program while keeping the text in memory.
+External representations are used when text is stored or transmitted
+through some communication channel.  Examples of external
+representations include files waiting in a directory to be
+read and parsed.
+
+Traditionally there has been no difference between the two representations.
+It was equally comfortable and useful to use the same single-byte
+representation internally and externally.  This comfort level decreases
+with more and larger character sets.
+
+One of the problems to overcome with the internal representation is
+handling text that is externally encoded using different character
+sets.  Assume a program that reads two texts and compares them using
+some metric.  The comparison can be usefully done only if the texts are
+internally kept in a common format.
+
+@cindex wide character
+For such a common format (@math{=} character set) eight bits are certainly
+no longer enough.  So the smallest entity will have to grow: @dfn{wide
+characters} will now be used.  Instead of one byte per character, two or
+four will be used instead.  (Three are not good to address in memory and
+more than four bytes seem not to be necessary).
+
+@cindex Unicode
+@cindex ISO 10646
+As shown in some other part of this manual,
+@c !!! Ahem, wide char string functions are not yet covered -- drepper
+a completely new family has been created of functions that can handle wide
+character texts in memory.  The most commonly used character sets for such
+internal wide character representations are Unicode and @w{ISO 10646}
+(also known as UCS for Universal Character Set).  Unicode was originally
+planned as a 16-bit character set; whereas, @w{ISO 10646} was designed to
+be a 31-bit large code space.  The two standards are practically identical.
+They have the same character repertoire and code table, but Unicode specifies
+added semantics.  At the moment, only characters in the first @code{0x10000}
+code positions (the so-called Basic Multilingual Plane, BMP) have been
+assigned, but the assignment of more specialized characters outside this
+16-bit space is already in progress.  A number of encodings have been
+defined for Unicode and @w{ISO 10646} characters:
+@cindex UCS-2
+@cindex UCS-4
+@cindex UTF-8
+@cindex UTF-16
+UCS-2 is a 16-bit word that can only represent characters
+from the BMP, UCS-4 is a 32-bit word than can represent any Unicode
+and @w{ISO 10646} character, UTF-8 is an ASCII compatible encoding where
+ASCII characters are represented by ASCII bytes and non-ASCII characters
+by sequences of 2-6 non-ASCII bytes, and finally UTF-16 is an extension
+of UCS-2 in which pairs of certain UCS-2 words can be used to encode
+non-BMP characters up to @code{0x10ffff}.
+
+To represent wide characters the @code{char} type is not suitable.  For
+this reason the @w{ISO C} standard introduces a new type that is
+designed to keep one character of a wide character string.  To maintain
+the similarity there is also a type corresponding to @code{int} for
+those functions that take a single wide character.
+
+@comment stddef.h
+@comment ISO
+@deftp {Data type} wchar_t
+This data type is used as the base type for wide character strings.
+In other words, arrays of objects of this type are the equivalent of
+@code{char[]} for multibyte character strings.  The type is defined in
+@file{stddef.h}.
+
+The @w{ISO C90} standard, where @code{wchar_t} was introduced, does not
+say anything specific about the representation.  It only requires that
+this type is capable of storing all elements of the basic character set.
+Therefore it would be legitimate to define @code{wchar_t} as @code{char},
+which might make sense for embedded systems.
+
+But in @theglibc{} @code{wchar_t} is always 32 bits wide and, therefore,
+capable of representing all UCS-4 values and, therefore, covering all of
+@w{ISO 10646}.  Some Unix systems define @code{wchar_t} as a 16-bit type
+and thereby follow Unicode very strictly.  This definition is perfectly
+fine with the standard, but it also means that to represent all
+characters from Unicode and @w{ISO 10646} one has to use UTF-16 surrogate
+characters, which is in fact a multi-wide-character encoding.  But
+resorting to multi-wide-character encoding contradicts the purpose of the
+@code{wchar_t} type.
+@end deftp
+
+@comment wchar.h
+@comment ISO
+@deftp {Data type} wint_t
+@code{wint_t} is a data type used for parameters and variables that
+contain a single wide character.  As the name suggests this type is the
+equivalent of @code{int} when using the normal @code{char} strings.  The
+types @code{wchar_t} and @code{wint_t} often have the same
+representation if their size is 32 bits wide but if @code{wchar_t} is
+defined as @code{char} the type @code{wint_t} must be defined as
+@code{int} due to the parameter promotion.
+
+@pindex wchar.h
+This type is defined in @file{wchar.h} and was introduced in
+@w{Amendment 1} to @w{ISO C90}.
+@end deftp
+
+As there are for the @code{char} data type macros are available for
+specifying the minimum and maximum value representable in an object of
+type @code{wchar_t}.
+
+@comment wchar.h
+@comment ISO
+@deftypevr Macro wint_t WCHAR_MIN
+The macro @code{WCHAR_MIN} evaluates to the minimum value representable
+by an object of type @code{wint_t}.
+
+This macro was introduced in @w{Amendment 1} to @w{ISO C90}.
+@end deftypevr
+
+@comment wchar.h
+@comment ISO
+@deftypevr Macro wint_t WCHAR_MAX
+The macro @code{WCHAR_MAX} evaluates to the maximum value representable
+by an object of type @code{wint_t}.
+
+This macro was introduced in @w{Amendment 1} to @w{ISO C90}.
+@end deftypevr
+
+Another special wide character value is the equivalent to @code{EOF}.
+
+@comment wchar.h
+@comment ISO
+@deftypevr Macro wint_t WEOF
+The macro @code{WEOF} evaluates to a constant expression of type
+@code{wint_t} whose value is different from any member of the extended
+character set.
+
+@code{WEOF} need not be the same value as @code{EOF} and unlike
+@code{EOF} it also need @emph{not} be negative.  In other words, sloppy
+code like
+
+@smallexample
+@{
+  int c;
+  @dots{}
+  while ((c = getc (fp)) < 0)
+    @dots{}
+@}
+@end smallexample
+
+@noindent
+has to be rewritten to use @code{WEOF} explicitly when wide characters
+are used:
+
+@smallexample
+@{
+  wint_t c;
+  @dots{}
+  while ((c = wgetc (fp)) != WEOF)
+    @dots{}
+@}
+@end smallexample
+
+@pindex wchar.h
+This macro was introduced in @w{Amendment 1} to @w{ISO C90} and is
+defined in @file{wchar.h}.
+@end deftypevr
+
+
+These internal representations present problems when it comes to storing
+and transmittal.  Because each single wide character consists of more
+than one byte, they are affected by byte-ordering.  Thus, machines with
+different endianesses would see different values when accessing the same
+data.  This byte ordering concern also applies for communication protocols
+that are all byte-based and therefore require that the sender has to
+decide about splitting the wide character in bytes.  A last (but not least
+important) point is that wide characters often require more storage space
+than a customized byte-oriented character set.
+
+@cindex multibyte character
+@cindex EBCDIC
+For all the above reasons, an external encoding that is different from
+the internal encoding is often used if the latter is UCS-2 or UCS-4.
+The external encoding is byte-based and can be chosen appropriately for
+the environment and for the texts to be handled.  A variety of different
+character sets can be used for this external encoding (information that
+will not be exhaustively presented here--instead, a description of the
+major groups will suffice).  All of the ASCII-based character sets
+fulfill one requirement: they are "filesystem safe."  This means that
+the character @code{'/'} is used in the encoding @emph{only} to
+represent itself.  Things are a bit different for character sets like
+EBCDIC (Extended Binary Coded Decimal Interchange Code, a character set
+family used by IBM), but if the operating system does not understand
+EBCDIC directly the parameters-to-system calls have to be converted
+first anyhow.
+
+@itemize @bullet
+@item
+The simplest character sets are single-byte character sets.  There can
+be only up to 256 characters (for @w{8 bit} character sets), which is
+not sufficient to cover all languages but might be sufficient to handle
+a specific text.  Handling of a @w{8 bit} character sets is simple.  This
+is not true for other kinds presented later, and therefore, the
+application one uses might require the use of @w{8 bit} character sets.
+
+@cindex ISO 2022
+@item
+The @w{ISO 2022} standard defines a mechanism for extended character
+sets where one character @emph{can} be represented by more than one
+byte.  This is achieved by associating a state with the text.
+Characters that can be used to change the state can be embedded in the
+text.  Each byte in the text might have a different interpretation in each
+state.  The state might even influence whether a given byte stands for a
+character on its own or whether it has to be combined with some more
+bytes.
+
+@cindex EUC
+@cindex Shift_JIS
+@cindex SJIS
+In most uses of @w{ISO 2022} the defined character sets do not allow
+state changes that cover more than the next character.  This has the
+big advantage that whenever one can identify the beginning of the byte
+sequence of a character one can interpret a text correctly.  Examples of
+character sets using this policy are the various EUC character sets
+(used by Sun's operating systems, EUC-JP, EUC-KR, EUC-TW, and EUC-CN)
+or Shift_JIS (SJIS, a Japanese encoding).
+
+But there are also character sets using a state that is valid for more
+than one character and has to be changed by another byte sequence.
+Examples for this are ISO-2022-JP, ISO-2022-KR, and ISO-2022-CN.
+
+@item
+@cindex ISO 6937
+Early attempts to fix 8 bit character sets for other languages using the
+Roman alphabet lead to character sets like @w{ISO 6937}.  Here bytes
+representing characters like the acute accent do not produce output
+themselves: one has to combine them with other characters to get the
+desired result.  For example, the byte sequence @code{0xc2 0x61}
+(non-spacing acute accent, followed by lower-case `a') to get the ``small
+a with  acute'' character.  To get the acute accent character on its own,
+one has to write @code{0xc2 0x20} (the non-spacing acute followed by a
+space).
+
+Character sets like @w{ISO 6937} are used in some embedded systems such
+as teletex.
+
+@item
+@cindex UTF-8
+Instead of converting the Unicode or @w{ISO 10646} text used internally,
+it is often also sufficient to simply use an encoding different than
+UCS-2/UCS-4.  The Unicode and @w{ISO 10646} standards even specify such an
+encoding: UTF-8.  This encoding is able to represent all of @w{ISO
+10646} 31 bits in a byte string of length one to six.
+
+@cindex UTF-7
+There were a few other attempts to encode @w{ISO 10646} such as UTF-7,
+but UTF-8 is today the only encoding that should be used.  In fact, with
+any luck UTF-8 will soon be the only external encoding that has to be
+supported.  It proves to be universally usable and its only disadvantage
+is that it favors Roman languages by making the byte string
+representation of other scripts (Cyrillic, Greek, Asian scripts) longer
+than necessary if using a specific character set for these scripts.
+Methods like the Unicode compression scheme can alleviate these
+problems.
+@end itemize
+
+The question remaining is: how to select the character set or encoding
+to use.  The answer: you cannot decide about it yourself, it is decided
+by the developers of the system or the majority of the users.  Since the
+goal is interoperability one has to use whatever the other people one
+works with use.  If there are no constraints, the selection is based on
+the requirements the expected circle of users will have.  In other words,
+if a project is expected to be used in only, say, Russia it is fine to use
+KOI8-R or a similar character set.  But if at the same time people from,
+say, Greece are participating one should use a character set that allows
+all people to collaborate.
+
+The most widely useful solution seems to be: go with the most general
+character set, namely @w{ISO 10646}.  Use UTF-8 as the external encoding
+and problems about users not being able to use their own language
+adequately are a thing of the past.
+
+One final comment about the choice of the wide character representation
+is necessary at this point.  We have said above that the natural choice
+is using Unicode or @w{ISO 10646}.  This is not required, but at least
+encouraged, by the @w{ISO C} standard.  The standard defines at least a
+macro @code{__STDC_ISO_10646__} that is only defined on systems where
+the @code{wchar_t} type encodes @w{ISO 10646} characters.  If this
+symbol is not defined one should avoid making assumptions about the wide
+character representation.  If the programmer uses only the functions
+provided by the C library to handle wide character strings there should
+be no compatibility problems with other systems.
+
+@node Charset Function Overview
+@section Overview about Character Handling Functions
+
+A Unix @w{C library} contains three different sets of functions in two
+families to handle character set conversion.  One of the function families
+(the most commonly used) is specified in the @w{ISO C90} standard and,
+therefore, is portable even beyond the Unix world.  Unfortunately this
+family is the least useful one.  These functions should be avoided
+whenever possible, especially when developing libraries (as opposed to
+applications).
+
+The second family of functions got introduced in the early Unix standards
+(XPG2) and is still part of the latest and greatest Unix standard:
+@w{Unix 98}.  It is also the most powerful and useful set of functions.
+But we will start with the functions defined in @w{Amendment 1} to
+@w{ISO C90}.
+
+@node Restartable multibyte conversion
+@section Restartable Multibyte Conversion Functions
+
+The @w{ISO C} standard defines functions to convert strings from a
+multibyte representation to wide character strings.  There are a number
+of peculiarities:
+
+@itemize @bullet
+@item
+The character set assumed for the multibyte encoding is not specified
+as an argument to the functions.  Instead the character set specified by
+the @code{LC_CTYPE} category of the current locale is used; see
+@ref{Locale Categories}.
+
+@item
+The functions handling more than one character at a time require NUL
+terminated strings as the argument (i.e., converting blocks of text
+does not work unless one can add a NUL byte at an appropriate place).
+@Theglibc{} contains some extensions to the standard that allow
+specifying a size, but basically they also expect terminated strings.
+@end itemize
+
+Despite these limitations the @w{ISO C} functions can be used in many
+contexts.  In graphical user interfaces, for instance, it is not
+uncommon to have functions that require text to be displayed in a wide
+character string if the text is not simple ASCII.  The text itself might
+come from a file with translations and the user should decide about the
+current locale, which determines the translation and therefore also the
+external encoding used.  In such a situation (and many others) the
+functions described here are perfect.  If more freedom while performing
+the conversion is necessary take a look at the @code{iconv} functions
+(@pxref{Generic Charset Conversion}).
+
+@menu
+* Selecting the Conversion::     Selecting the conversion and its properties.
+* Keeping the state::            Representing the state of the conversion.
+* Converting a Character::       Converting Single Characters.
+* Converting Strings::           Converting Multibyte and Wide Character
+                                  Strings.
+* Multibyte Conversion Example:: A Complete Multibyte Conversion Example.
+@end menu
+
+@node Selecting the Conversion
+@subsection Selecting the conversion and its properties
+
+We already said above that the currently selected locale for the
+@code{LC_CTYPE} category decides about the conversion that is performed
+by the functions we are about to describe.  Each locale uses its own
+character set (given as an argument to @code{localedef}) and this is the
+one assumed as the external multibyte encoding.  The wide character
+set is always UCS-4 in @theglibc{}.
+
+A characteristic of each multibyte character set is the maximum number
+of bytes that can be necessary to represent one character.  This
+information is quite important when writing code that uses the
+conversion functions (as shown in the examples below).
+The @w{ISO C} standard defines two macros that provide this information.
+
+
+@comment limits.h
+@comment ISO
+@deftypevr Macro int MB_LEN_MAX
+@code{MB_LEN_MAX} specifies the maximum number of bytes in the multibyte
+sequence for a single character in any of the supported locales.  It is
+a compile-time constant and is defined in @file{limits.h}.
+@pindex limits.h
+@end deftypevr
+
+@comment stdlib.h
+@comment ISO
+@deftypevr Macro int MB_CUR_MAX
+@code{MB_CUR_MAX} expands into a positive integer expression that is the
+maximum number of bytes in a multibyte character in the current locale.
+The value is never greater than @code{MB_LEN_MAX}.  Unlike
+@code{MB_LEN_MAX} this macro need not be a compile-time constant, and in
+@theglibc{} it is not.
+
+@pindex stdlib.h
+@code{MB_CUR_MAX} is defined in @file{stdlib.h}.
+@end deftypevr
+
+Two different macros are necessary since strictly @w{ISO C90} compilers
+do not allow variable length array definitions, but still it is desirable
+to avoid dynamic allocation.  This incomplete piece of code shows the
+problem:
+
+@smallexample
+@{
+  char buf[MB_LEN_MAX];
+  ssize_t len = 0;
+
+  while (! feof (fp))
+    @{
+      fread (&buf[len], 1, MB_CUR_MAX - len, fp);
+      /* @r{@dots{} process} buf */
+      len -= used;
+    @}
+@}
+@end smallexample
+
+The code in the inner loop is expected to have always enough bytes in
+the array @var{buf} to convert one multibyte character.  The array
+@var{buf} has to be sized statically since many compilers do not allow a
+variable size.  The @code{fread} call makes sure that @code{MB_CUR_MAX}
+bytes are always available in @var{buf}.  Note that it isn't
+a problem if @code{MB_CUR_MAX} is not a compile-time constant.
+
+
+@node Keeping the state
+@subsection Representing the state of the conversion
+
+@cindex stateful
+In the introduction of this chapter it was said that certain character
+sets use a @dfn{stateful} encoding.  That is, the encoded values depend
+in some way on the previous bytes in the text.
+
+Since the conversion functions allow converting a text in more than one
+step we must have a way to pass this information from one call of the
+functions to another.
+
+@comment wchar.h
+@comment ISO
+@deftp {Data type} mbstate_t
+@cindex shift state
+A variable of type @code{mbstate_t} can contain all the information
+about the @dfn{shift state} needed from one call to a conversion
+function to another.
+
+@pindex wchar.h
+@code{mbstate_t} is defined in @file{wchar.h}.  It was introduced in
+@w{Amendment 1} to @w{ISO C90}.
+@end deftp
+
+To use objects of type @code{mbstate_t} the programmer has to define such
+objects (normally as local variables on the stack) and pass a pointer to
+the object to the conversion functions.  This way the conversion function
+can update the object if the current multibyte character set is stateful.
+
+There is no specific function or initializer to put the state object in
+any specific state.  The rules are that the object should always
+represent the initial state before the first use, and this is achieved by
+clearing the whole variable with code such as follows:
+
+@smallexample
+@{
+  mbstate_t state;
+  memset (&state, '\0', sizeof (state));
+  /* @r{from now on @var{state} can be used.}  */
+  @dots{}
+@}
+@end smallexample
+
+When using the conversion functions to generate output it is often
+necessary to test whether the current state corresponds to the initial
+state.  This is necessary, for example, to decide whether to emit
+escape sequences to set the state to the initial state at certain
+sequence points.  Communication protocols often require this.
+
+@comment wchar.h
+@comment ISO
+@deftypefun int mbsinit (const mbstate_t *@var{ps})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c ps is dereferenced once, unguarded.  This would call for @mtsrace:ps,
+@c but since a single word-sized field is (atomically) accessed, any
+@c race here would be harmless.  Other functions that take an optional
+@c mbstate_t* argument named ps are marked with @mtasurace:<func>/!ps,
+@c to indicate that the function uses a static buffer if ps is NULL.
+@c These could also have been marked with @mtsrace:ps, but we'll omit
+@c that for brevity, for it's somewhat redundant with the @mtasurace.
+The @code{mbsinit} function determines whether the state object pointed
+to by @var{ps} is in the initial state.  If @var{ps} is a null pointer or
+the object is in the initial state the return value is nonzero.  Otherwise
+it is zero.
+
+@pindex wchar.h
+@code{mbsinit} was introduced in @w{Amendment 1} to @w{ISO C90} and is
+declared in @file{wchar.h}.
+@end deftypefun
+
+Code using @code{mbsinit} often looks similar to this:
+
+@c Fix the example to explicitly say how to generate the escape sequence
+@c to restore the initial state.
+@smallexample
+@{
+  mbstate_t state;
+  memset (&state, '\0', sizeof (state));
+  /* @r{Use @var{state}.}  */
+  @dots{}
+  if (! mbsinit (&state))
+    @{
+      /* @r{Emit code to return to initial state.}  */
+      const wchar_t empty[] = L"";
+      const wchar_t *srcp = empty;
+      wcsrtombs (outbuf, &srcp, outbuflen, &state);
+    @}
+  @dots{}
+@}
+@end smallexample
+
+The code to emit the escape sequence to get back to the initial state is
+interesting.  The @code{wcsrtombs} function can be used to determine the
+necessary output code (@pxref{Converting Strings}).  Please note that with
+@theglibc{} it is not necessary to perform this extra action for the
+conversion from multibyte text to wide character text since the wide
+character encoding is not stateful.  But there is nothing mentioned in
+any standard that prohibits making @code{wchar_t} using a stateful
+encoding.
+
+@node Converting a Character
+@subsection Converting Single Characters
+
+The most fundamental of the conversion functions are those dealing with
+single characters.  Please note that this does not always mean single
+bytes.  But since there is very often a subset of the multibyte
+character set that consists of single byte sequences, there are
+functions to help with converting bytes.  Frequently, ASCII is a subpart
+of the multibyte character set.  In such a scenario, each ASCII character
+stands for itself, and all other characters have at least a first byte
+that is beyond the range @math{0} to @math{127}.
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t btowc (int @var{c})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Calls btowc_fct or __fct; reads from locale, and from the
+@c get_gconv_fcts result multiple times.  get_gconv_fcts calls
+@c __wcsmbs_load_conv to initialize the ctype if it's null.
+@c wcsmbs_load_conv takes a non-recursive wrlock before allocating
+@c memory for the fcts structure, initializing it, and then storing it
+@c in the locale object.  The initialization involves dlopening and a
+@c lot more.
+The @code{btowc} function (``byte to wide character'') converts a valid
+single byte character @var{c} in the initial shift state into the wide
+character equivalent using the conversion rules from the currently
+selected locale of the @code{LC_CTYPE} category.
+
+If @code{(unsigned char) @var{c}} is no valid single byte multibyte
+character or if @var{c} is @code{EOF}, the function returns @code{WEOF}.
+
+Please note the restriction of @var{c} being tested for validity only in
+the initial shift state.  No @code{mbstate_t} object is used from
+which the state information is taken, and the function also does not use
+any static state.
+
+@pindex wchar.h
+The @code{btowc} function was introduced in @w{Amendment 1} to @w{ISO C90}
+and is declared in @file{wchar.h}.
+@end deftypefun
+
+Despite the limitation that the single byte value is always interpreted
+in the initial state, this function is actually useful most of the time.
+Most characters are either entirely single-byte character sets or they
+are extension to ASCII.  But then it is possible to write code like this
+(not that this specific example is very useful):
+
+@smallexample
+wchar_t *
+itow (unsigned long int val)
+@{
+  static wchar_t buf[30];
+  wchar_t *wcp = &buf[29];
+  *wcp = L'\0';
+  while (val != 0)
+    @{
+      *--wcp = btowc ('0' + val % 10);
+      val /= 10;
+    @}
+  if (wcp == &buf[29])
+    *--wcp = L'0';
+  return wcp;
+@}
+@end smallexample
+
+Why is it necessary to use such a complicated implementation and not
+simply cast @code{'0' + val % 10} to a wide character?  The answer is
+that there is no guarantee that one can perform this kind of arithmetic
+on the character of the character set used for @code{wchar_t}
+representation.  In other situations the bytes are not constant at
+compile time and so the compiler cannot do the work.  In situations like
+this, using @code{btowc} is required.
+
+@noindent
+There is also a function for the conversion in the other direction.
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wctob (wint_t @var{c})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{wctob} function (``wide character to byte'') takes as the
+parameter a valid wide character.  If the multibyte representation for
+this character in the initial state is exactly one byte long, the return
+value of this function is this character.  Otherwise the return value is
+@code{EOF}.
+
+@pindex wchar.h
+@code{wctob} was introduced in @w{Amendment 1} to @w{ISO C90} and
+is declared in @file{wchar.h}.
+@end deftypefun
+
+There are more general functions to convert single character from
+multibyte representation to wide characters and vice versa.  These
+functions pose no limit on the length of the multibyte representation
+and they also do not require it to be in the initial state.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t mbrtowc (wchar_t *restrict @var{pwc}, const char *restrict @var{s}, size_t @var{n}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mbrtowc/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@cindex stateful
+The @code{mbrtowc} function (``multibyte restartable to wide
+character'') converts the next multibyte character in the string pointed
+to by @var{s} into a wide character and stores it in the wide character
+string pointed to by @var{pwc}.  The conversion is performed according
+to the locale currently selected for the @code{LC_CTYPE} category.  If
+the conversion for the character set used in the locale requires a state,
+the multibyte string is interpreted in the state represented by the
+object pointed to by @var{ps}.  If @var{ps} is a null pointer, a static,
+internal state variable used only by the @code{mbrtowc} function is
+used.
+
+If the next multibyte character corresponds to the NUL wide character,
+the return value of the function is @math{0} and the state object is
+afterwards in the initial state.  If the next @var{n} or fewer bytes
+form a correct multibyte character, the return value is the number of
+bytes starting from @var{s} that form the multibyte character.  The
+conversion state is updated according to the bytes consumed in the
+conversion.  In both cases the wide character (either the @code{L'\0'}
+or the one found in the conversion) is stored in the string pointed to
+by @var{pwc} if @var{pwc} is not null.
+
+If the first @var{n} bytes of the multibyte string possibly form a valid
+multibyte character but there are more than @var{n} bytes needed to
+complete it, the return value of the function is @code{(size_t) -2} and
+no value is stored.  Please note that this can happen even if @var{n}
+has a value greater than or equal to @code{MB_CUR_MAX} since the input
+might contain redundant shift sequences.
+
+If the first @code{n} bytes of the multibyte string cannot possibly form
+a valid multibyte character, no value is stored, the global variable
+@code{errno} is set to the value @code{EILSEQ}, and the function returns
+@code{(size_t) -1}.  The conversion state is afterwards undefined.
+
+@pindex wchar.h
+@code{mbrtowc} was introduced in @w{Amendment 1} to @w{ISO C90} and
+is declared in @file{wchar.h}.
+@end deftypefun
+
+Use of @code{mbrtowc} is straightforward.  A function that copies a
+multibyte string into a wide character string while at the same time
+converting all lowercase characters into uppercase could look like this
+(this is not the final version, just an example; it has no error
+checking, and sometimes leaks memory):
+
+@smallexample
+wchar_t *
+mbstouwcs (const char *s)
+@{
+  size_t len = strlen (s);
+  wchar_t *result = malloc ((len + 1) * sizeof (wchar_t));
+  wchar_t *wcp = result;
+  wchar_t tmp[1];
+  mbstate_t state;
+  size_t nbytes;
+
+  memset (&state, '\0', sizeof (state));
+  while ((nbytes = mbrtowc (tmp, s, len, &state)) > 0)
+    @{
+      if (nbytes >= (size_t) -2)
+        /* Invalid input string.  */
+        return NULL;
+      *wcp++ = towupper (tmp[0]);
+      len -= nbytes;
+      s += nbytes;
+    @}
+  return result;
+@}
+@end smallexample
+
+The use of @code{mbrtowc} should be clear.  A single wide character is
+stored in @code{@var{tmp}[0]}, and the number of consumed bytes is stored
+in the variable @var{nbytes}.  If the conversion is successful, the
+uppercase variant of the wide character is stored in the @var{result}
+array and the pointer to the input string and the number of available
+bytes is adjusted.
+
+The only non-obvious thing about @code{mbrtowc} might be the way memory
+is allocated for the result.  The above code uses the fact that there
+can never be more wide characters in the converted results than there are
+bytes in the multibyte input string.  This method yields a pessimistic
+guess about the size of the result, and if many wide character strings
+have to be constructed this way or if the strings are long, the extra
+memory required to be allocated because the input string contains
+multibyte characters might be significant.  The allocated memory block can
+be resized to the correct size before returning it, but a better solution
+might be to allocate just the right amount of space for the result right
+away.  Unfortunately there is no function to compute the length of the wide
+character string directly from the multibyte string.  There is, however, a
+function that does part of the work.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t mbrlen (const char *restrict @var{s}, size_t @var{n}, mbstate_t *@var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mbrlen/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{mbrlen} function (``multibyte restartable length'') computes
+the number of at most @var{n} bytes starting at @var{s}, which form the
+next valid and complete multibyte character.
+
+If the next multibyte character corresponds to the NUL wide character,
+the return value is @math{0}.  If the next @var{n} bytes form a valid
+multibyte character, the number of bytes belonging to this multibyte
+character byte sequence is returned.
+
+If the first @var{n} bytes possibly form a valid multibyte
+character but the character is incomplete, the return value is
+@code{(size_t) -2}.  Otherwise the multibyte character sequence is invalid
+and the return value is @code{(size_t) -1}.
+
+The multibyte sequence is interpreted in the state represented by the
+object pointed to by @var{ps}.  If @var{ps} is a null pointer, a state
+object local to @code{mbrlen} is used.
+
+@pindex wchar.h
+@code{mbrlen} was introduced in @w{Amendment 1} to @w{ISO C90} and
+is declared in @file{wchar.h}.
+@end deftypefun
+
+The attentive reader now will note that @code{mbrlen} can be implemented
+as
+
+@smallexample
+mbrtowc (NULL, s, n, ps != NULL ? ps : &internal)
+@end smallexample
+
+This is true and in fact is mentioned in the official specification.
+How can this function be used to determine the length of the wide
+character string created from a multibyte character string?  It is not
+directly usable, but we can define a function @code{mbslen} using it:
+
+@smallexample
+size_t
+mbslen (const char *s)
+@{
+  mbstate_t state;
+  size_t result = 0;
+  size_t nbytes;
+  memset (&state, '\0', sizeof (state));
+  while ((nbytes = mbrlen (s, MB_LEN_MAX, &state)) > 0)
+    @{
+      if (nbytes >= (size_t) -2)
+        /* @r{Something is wrong.}  */
+        return (size_t) -1;
+      s += nbytes;
+      ++result;
+    @}
+  return result;
+@}
+@end smallexample
+
+This function simply calls @code{mbrlen} for each multibyte character
+in the string and counts the number of function calls.  Please note that
+we here use @code{MB_LEN_MAX} as the size argument in the @code{mbrlen}
+call.  This is acceptable since a) this value is larger than the length of
+the longest multibyte character sequence and b) we know that the string
+@var{s} ends with a NUL byte, which cannot be part of any other multibyte
+character sequence but the one representing the NUL wide character.
+Therefore, the @code{mbrlen} function will never read invalid memory.
+
+Now that this function is available (just to make this clear, this
+function is @emph{not} part of @theglibc{}) we can compute the
+number of wide character required to store the converted multibyte
+character string @var{s} using
+
+@smallexample
+wcs_bytes = (mbslen (s) + 1) * sizeof (wchar_t);
+@end smallexample
+
+Please note that the @code{mbslen} function is quite inefficient.  The
+implementation of @code{mbstouwcs} with @code{mbslen} would have to
+perform the conversion of the multibyte character input string twice, and
+this conversion might be quite expensive.  So it is necessary to think
+about the consequences of using the easier but imprecise method before
+doing the work twice.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcrtomb (char *restrict @var{s}, wchar_t @var{wc}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:wcrtomb/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c wcrtomb uses a static, non-thread-local unguarded state variable when
+@c PS is NULL.  When a state is passed in, and it's not used
+@c concurrently in other threads, this function behaves safely as long
+@c as gconv modules don't bring MT safety issues of their own.
+@c Attempting to load gconv modules or to build conversion chains in
+@c signal handlers may encounter gconv databases or caches in a
+@c partially-updated state, and asynchronous cancellation may leave them
+@c in such states, besides leaking the lock that guards them.
+@c get_gconv_fcts ok
+@c    wcsmbs_load_conv ok
+@c      norm_add_slashes ok
+@c      wcsmbs_getfct ok
+@c        gconv_find_transform ok
+@c          gconv_read_conf (libc_once)
+@c          gconv_lookup_cache ok
+@c            find_module_idx ok
+@c            find_module ok
+@c              gconv_find_shlib (ok)
+@c              ->init_fct (assumed ok)
+@c            gconv_get_builtin_trans ok
+@c            gconv_release_step ok
+@c          do_lookup_alias ok
+@c          find_derivation ok
+@c            derivation_lookup ok
+@c            increment_counter ok
+@c              gconv_find_shlib ok
+@c              step->init_fct (assumed ok)
+@c            gen_steps ok
+@c              gconv_find_shlib ok
+@c                dlopen (presumed ok)
+@c                dlsym (presumed ok)
+@c              step->init_fct (assumed ok)
+@c              step->end_fct (assumed ok)
+@c              gconv_get_builtin_trans ok
+@c              gconv_release_step ok
+@c            add_derivation ok
+@c      gconv_close_transform ok
+@c        gconv_release_step ok
+@c          step->end_fct (assumed ok)
+@c          gconv_release_shlib ok
+@c            dlclose (presumed ok)
+@c        gconv_release_cache ok
+@c  ->tomb->__fct (assumed ok)
+The @code{wcrtomb} function (``wide character restartable to
+multibyte'') converts a single wide character into a multibyte string
+corresponding to that wide character.
+
+If @var{s} is a null pointer, the function resets the state stored in
+the objects pointed to by @var{ps} (or the internal @code{mbstate_t}
+object) to the initial state.  This can also be achieved by a call like
+this:
+
+@smallexample
+wcrtombs (temp_buf, L'\0', ps)
+@end smallexample
+
+@noindent
+since, if @var{s} is a null pointer, @code{wcrtomb} performs as if it
+writes into an internal buffer, which is guaranteed to be large enough.
+
+If @var{wc} is the NUL wide character, @code{wcrtomb} emits, if
+necessary, a shift sequence to get the state @var{ps} into the initial
+state followed by a single NUL byte, which is stored in the string
+@var{s}.
+
+Otherwise a byte sequence (possibly including shift sequences) is written
+into the string @var{s}.  This only happens if @var{wc} is a valid wide
+character (i.e., it has a multibyte representation in the character set
+selected by locale of the @code{LC_CTYPE} category).  If @var{wc} is no
+valid wide character, nothing is stored in the strings @var{s},
+@code{errno} is set to @code{EILSEQ}, the conversion state in @var{ps}
+is undefined and the return value is @code{(size_t) -1}.
+
+If no error occurred the function returns the number of bytes stored in
+the string @var{s}.  This includes all bytes representing shift
+sequences.
+
+One word about the interface of the function: there is no parameter
+specifying the length of the array @var{s}.  Instead the function
+assumes that there are at least @code{MB_CUR_MAX} bytes available since
+this is the maximum length of any byte sequence representing a single
+character.  So the caller has to make sure that there is enough space
+available, otherwise buffer overruns can occur.
+
+@pindex wchar.h
+@code{wcrtomb} was introduced in @w{Amendment 1} to @w{ISO C90} and is
+declared in @file{wchar.h}.
+@end deftypefun
+
+Using @code{wcrtomb} is as easy as using @code{mbrtowc}.  The following
+example appends a wide character string to a multibyte character string.
+Again, the code is not really useful (or correct), it is simply here to
+demonstrate the use and some problems.
+
+@smallexample
+char *
+mbscatwcs (char *s, size_t len, const wchar_t *ws)
+@{
+  mbstate_t state;
+  /* @r{Find the end of the existing string.}  */
+  char *wp = strchr (s, '\0');
+  len -= wp - s;
+  memset (&state, '\0', sizeof (state));
+  do
+    @{
+      size_t nbytes;
+      if (len < MB_CUR_LEN)
+        @{
+          /* @r{We cannot guarantee that the next}
+             @r{character fits into the buffer, so}
+             @r{return an error.}  */
+          errno = E2BIG;
+          return NULL;
+        @}
+      nbytes = wcrtomb (wp, *ws, &state);
+      if (nbytes == (size_t) -1)
+        /* @r{Error in the conversion.}  */
+        return NULL;
+      len -= nbytes;
+      wp += nbytes;
+    @}
+  while (*ws++ != L'\0');
+  return s;
+@}
+@end smallexample
+
+First the function has to find the end of the string currently in the
+array @var{s}.  The @code{strchr} call does this very efficiently since a
+requirement for multibyte character representations is that the NUL byte
+is never used except to represent itself (and in this context, the end
+of the string).
+
+After initializing the state object the loop is entered where the first
+task is to make sure there is enough room in the array @var{s}.  We
+abort if there are not at least @code{MB_CUR_LEN} bytes available.  This
+is not always optimal but we have no other choice.  We might have less
+than @code{MB_CUR_LEN} bytes available but the next multibyte character
+might also be only one byte long.  At the time the @code{wcrtomb} call
+returns it is too late to decide whether the buffer was large enough.  If
+this solution is unsuitable, there is a very slow but more accurate
+solution.
+
+@smallexample
+  @dots{}
+  if (len < MB_CUR_LEN)
+    @{
+      mbstate_t temp_state;
+      memcpy (&temp_state, &state, sizeof (state));
+      if (wcrtomb (NULL, *ws, &temp_state) > len)
+        @{
+          /* @r{We cannot guarantee that the next}
+             @r{character fits into the buffer, so}
+             @r{return an error.}  */
+          errno = E2BIG;
+          return NULL;
+        @}
+    @}
+  @dots{}
+@end smallexample
+
+Here we perform the conversion that might overflow the buffer so that
+we are afterwards in the position to make an exact decision about the
+buffer size.  Please note the @code{NULL} argument for the destination
+buffer in the new @code{wcrtomb} call; since we are not interested in the
+converted text at this point, this is a nice way to express this.  The
+most unusual thing about this piece of code certainly is the duplication
+of the conversion state object, but if a change of the state is necessary
+to emit the next multibyte character, we want to have the same shift state
+change performed in the real conversion.  Therefore, we have to preserve
+the initial shift state information.
+
+There are certainly many more and even better solutions to this problem.
+This example is only provided for educational purposes.
+
+@node Converting Strings
+@subsection Converting Multibyte and Wide Character Strings
+
+The functions described in the previous section only convert a single
+character at a time.  Most operations to be performed in real-world
+programs include strings and therefore the @w{ISO C} standard also
+defines conversions on entire strings.  However, the defined set of
+functions is quite limited; therefore, @theglibc{} contains a few
+extensions that can help in some important situations.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t mbsrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mbsrtowcs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{mbsrtowcs} function (``multibyte string restartable to wide
+character string'') converts a NUL-terminated multibyte character
+string at @code{*@var{src}} into an equivalent wide character string,
+including the NUL wide character at the end.  The conversion is started
+using the state information from the object pointed to by @var{ps} or
+from an internal object of @code{mbsrtowcs} if @var{ps} is a null
+pointer.  Before returning, the state object is updated to match the state
+after the last converted character.  The state is the initial state if the
+terminating NUL byte is reached and converted.
+
+If @var{dst} is not a null pointer, the result is stored in the array
+pointed to by @var{dst}; otherwise, the conversion result is not
+available since it is stored in an internal buffer.
+
+If @var{len} wide characters are stored in the array @var{dst} before
+reaching the end of the input string, the conversion stops and @var{len}
+is returned.  If @var{dst} is a null pointer, @var{len} is never checked.
+
+Another reason for a premature return from the function call is if the
+input string contains an invalid multibyte sequence.  In this case the
+global variable @code{errno} is set to @code{EILSEQ} and the function
+returns @code{(size_t) -1}.
+
+@c XXX The ISO C9x draft seems to have a problem here.  It says that PS
+@c is not updated if DST is NULL.  This is not said straightforward and
+@c none of the other functions is described like this.  It would make sense
+@c to define the function this way but I don't think it is meant like this.
+
+In all other cases the function returns the number of wide characters
+converted during this call.  If @var{dst} is not null, @code{mbsrtowcs}
+stores in the pointer pointed to by @var{src} either a null pointer (if
+the NUL byte in the input string was reached) or the address of the byte
+following the last converted multibyte character.
+
+@pindex wchar.h
+@code{mbsrtowcs} was introduced in @w{Amendment 1} to @w{ISO C90} and is
+declared in @file{wchar.h}.
+@end deftypefun
+
+The definition of the @code{mbsrtowcs} function has one important
+limitation.  The requirement that @var{dst} has to be a NUL-terminated
+string provides problems if one wants to convert buffers with text.  A
+buffer is normally no collection of NUL-terminated strings but instead a
+continuous collection of lines, separated by newline characters.  Now
+assume that a function to convert one line from a buffer is needed.  Since
+the line is not NUL-terminated, the source pointer cannot directly point
+into the unmodified text buffer.  This means, either one inserts the NUL
+byte at the appropriate place for the time of the @code{mbsrtowcs}
+function call (which is not doable for a read-only buffer or in a
+multi-threaded application) or one copies the line in an extra buffer
+where it can be terminated by a NUL byte.  Note that it is not in general
+possible to limit the number of characters to convert by setting the
+parameter @var{len} to any specific value.  Since it is not known how
+many bytes each multibyte character sequence is in length, one can only
+guess.
+
+@cindex stateful
+There is still a problem with the method of NUL-terminating a line right
+after the newline character, which could lead to very strange results.
+As said in the description of the @code{mbsrtowcs} function above the
+conversion state is guaranteed to be in the initial shift state after
+processing the NUL byte at the end of the input string.  But this NUL
+byte is not really part of the text (i.e., the conversion state after
+the newline in the original text could be something different than the
+initial shift state and therefore the first character of the next line
+is encoded using this state).  But the state in question is never
+accessible to the user since the conversion stops after the NUL byte
+(which resets the state).  Most stateful character sets in use today
+require that the shift state after a newline be the initial state--but
+this is not a strict guarantee.  Therefore, simply NUL-terminating a
+piece of a running text is not always an adequate solution and,
+therefore, should never be used in generally used code.
+
+The generic conversion interface (@pxref{Generic Charset Conversion})
+does not have this limitation (it simply works on buffers, not
+strings), and @theglibc{} contains a set of functions that take
+additional parameters specifying the maximal number of bytes that are
+consumed from the input string.  This way the problem of
+@code{mbsrtowcs}'s example above could be solved by determining the line
+length and passing this length to the function.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcsrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:wcsrtombs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{wcsrtombs} function (``wide character string restartable to
+multibyte string'') converts the NUL-terminated wide character string at
+@code{*@var{src}} into an equivalent multibyte character string and
+stores the result in the array pointed to by @var{dst}.  The NUL wide
+character is also converted.  The conversion starts in the state
+described in the object pointed to by @var{ps} or by a state object
+locally to @code{wcsrtombs} in case @var{ps} is a null pointer.  If
+@var{dst} is a null pointer, the conversion is performed as usual but the
+result is not available.  If all characters of the input string were
+successfully converted and if @var{dst} is not a null pointer, the
+pointer pointed to by @var{src} gets assigned a null pointer.
+
+If one of the wide characters in the input string has no valid multibyte
+character equivalent, the conversion stops early, sets the global
+variable @code{errno} to @code{EILSEQ}, and returns @code{(size_t) -1}.
+
+Another reason for a premature stop is if @var{dst} is not a null
+pointer and the next converted character would require more than
+@var{len} bytes in total to the array @var{dst}.  In this case (and if
+@var{dest} is not a null pointer) the pointer pointed to by @var{src} is
+assigned a value pointing to the wide character right after the last one
+successfully converted.
+
+Except in the case of an encoding error the return value of the
+@code{wcsrtombs} function is the number of bytes in all the multibyte
+character sequences stored in @var{dst}.  Before returning the state in
+the object pointed to by @var{ps} (or the internal object in case
+@var{ps} is a null pointer) is updated to reflect the state after the
+last conversion.  The state is the initial shift state in case the
+terminating NUL wide character was converted.
+
+@pindex wchar.h
+The @code{wcsrtombs} function was introduced in @w{Amendment 1} to
+@w{ISO C90} and is declared in @file{wchar.h}.
+@end deftypefun
+
+The restriction mentioned above for the @code{mbsrtowcs} function applies
+here also.  There is no possibility of directly controlling the number of
+input characters.  One has to place the NUL wide character at the correct
+place or control the consumed input indirectly via the available output
+array size (the @var{len} parameter).
+
+@comment wchar.h
+@comment GNU
+@deftypefun size_t mbsnrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{nmc}, size_t @var{len}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mbsnrtowcs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{mbsnrtowcs} function is very similar to the @code{mbsrtowcs}
+function.  All the parameters are the same except for @var{nmc}, which is
+new.  The return value is the same as for @code{mbsrtowcs}.
+
+This new parameter specifies how many bytes at most can be used from the
+multibyte character string.  In other words, the multibyte character
+string @code{*@var{src}} need not be NUL-terminated.  But if a NUL byte
+is found within the @var{nmc} first bytes of the string, the conversion
+stops here.
+
+This function is a GNU extension.  It is meant to work around the
+problems mentioned above.  Now it is possible to convert a buffer with
+multibyte character text piece for piece without having to care about
+inserting NUL bytes and the effect of NUL bytes on the conversion state.
+@end deftypefun
+
+A function to convert a multibyte string into a wide character string
+and display it could be written like this (this is not a really useful
+example):
+
+@smallexample
+void
+showmbs (const char *src, FILE *fp)
+@{
+  mbstate_t state;
+  int cnt = 0;
+  memset (&state, '\0', sizeof (state));
+  while (1)
+    @{
+      wchar_t linebuf[100];
+      const char *endp = strchr (src, '\n');
+      size_t n;
+
+      /* @r{Exit if there is no more line.}  */
+      if (endp == NULL)
+        break;
+
+      n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
+      linebuf[n] = L'\0';
+      fprintf (fp, "line %d: \"%S\"\n", linebuf);
+    @}
+@}
+@end smallexample
+
+There is no problem with the state after a call to @code{mbsnrtowcs}.
+Since we don't insert characters in the strings that were not in there
+right from the beginning and we use @var{state} only for the conversion
+of the given buffer, there is no problem with altering the state.
+
+@comment wchar.h
+@comment GNU
+@deftypefun size_t wcsnrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{nwc}, size_t @var{len}, mbstate_t *restrict @var{ps})
+@safety{@prelim{}@mtunsafe{@mtasurace{:wcsnrtombs/!ps}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{wcsnrtombs} function implements the conversion from wide
+character strings to multibyte character strings.  It is similar to
+@code{wcsrtombs} but, just like @code{mbsnrtowcs}, it takes an extra
+parameter, which specifies the length of the input string.
+
+No more than @var{nwc} wide characters from the input string
+@code{*@var{src}} are converted.  If the input string contains a NUL
+wide character in the first @var{nwc} characters, the conversion stops at
+this place.
+
+The @code{wcsnrtombs} function is a GNU extension and just like
+@code{mbsnrtowcs} helps in situations where no NUL-terminated input
+strings are available.
+@end deftypefun
+
+
+@node Multibyte Conversion Example
+@subsection A Complete Multibyte Conversion Example
+
+The example programs given in the last sections are only brief and do
+not contain all the error checking, etc.  Presented here is a complete
+and documented example.  It features the @code{mbrtowc} function but it
+should be easy to derive versions using the other functions.
+
+@smallexample
+int
+file_mbsrtowcs (int input, int output)
+@{
+  /* @r{Note the use of @code{MB_LEN_MAX}.}
+     @r{@code{MB_CUR_MAX} cannot portably be used here.}  */
+  char buffer[BUFSIZ + MB_LEN_MAX];
+  mbstate_t state;
+  int filled = 0;
+  int eof = 0;
+
+  /* @r{Initialize the state.}  */
+  memset (&state, '\0', sizeof (state));
+
+  while (!eof)
+    @{
+      ssize_t nread;
+      ssize_t nwrite;
+      char *inp = buffer;
+      wchar_t outbuf[BUFSIZ];
+      wchar_t *outp = outbuf;
+
+      /* @r{Fill up the buffer from the input file.}  */
+      nread = read (input, buffer + filled, BUFSIZ);
+      if (nread < 0)
+        @{
+          perror ("read");
+          return 0;
+        @}
+      /* @r{If we reach end of file, make a note to read no more.} */
+      if (nread == 0)
+        eof = 1;
+
+      /* @r{@code{filled} is now the number of bytes in @code{buffer}.} */
+      filled += nread;
+
+      /* @r{Convert those bytes to wide characters--as many as we can.} */
+      while (1)
+        @{
+          size_t thislen = mbrtowc (outp, inp, filled, &state);
+          /* @r{Stop converting at invalid character;}
+             @r{this can mean we have read just the first part}
+             @r{of a valid character.}  */
+          if (thislen == (size_t) -1)
+            break;
+          /* @r{We want to handle embedded NUL bytes}
+             @r{but the return value is 0.  Correct this.}  */
+          if (thislen == 0)
+            thislen = 1;
+          /* @r{Advance past this character.} */
+          inp += thislen;
+          filled -= thislen;
+          ++outp;
+        @}
+
+      /* @r{Write the wide characters we just made.}  */
+      nwrite = write (output, outbuf,
+                      (outp - outbuf) * sizeof (wchar_t));
+      if (nwrite < 0)
+        @{
+          perror ("write");
+          return 0;
+        @}
+
+      /* @r{See if we have a @emph{real} invalid character.} */
+      if ((eof && filled > 0) || filled >= MB_CUR_MAX)
+        @{
+          error (0, 0, "invalid multibyte character");
+          return 0;
+        @}
+
+      /* @r{If any characters must be carried forward,}
+         @r{put them at the beginning of @code{buffer}.} */
+      if (filled > 0)
+        memmove (buffer, inp, filled);
+    @}
+
+  return 1;
+@}
+@end smallexample
+
+
+@node Non-reentrant Conversion
+@section Non-reentrant Conversion Function
+
+The functions described in the previous chapter are defined in
+@w{Amendment 1} to @w{ISO C90}, but the original @w{ISO C90} standard
+also contained functions for character set conversion.  The reason that
+these original functions are not described first is that they are almost
+entirely useless.
+
+The problem is that all the conversion functions described in the
+original @w{ISO C90} use a local state.  Using a local state implies that
+multiple conversions at the same time (not only when using threads)
+cannot be done, and that you cannot first convert single characters and
+then strings since you cannot tell the conversion functions which state
+to use.
+
+These original functions are therefore usable only in a very limited set
+of situations.  One must complete converting the entire string before
+starting a new one, and each string/text must be converted with the same
+function (there is no problem with the library itself; it is guaranteed
+that no library function changes the state of any of these functions).
+@strong{For the above reasons it is highly requested that the functions
+described in the previous section be used in place of non-reentrant
+conversion functions.}
+
+@menu
+* Non-reentrant Character Conversion::  Non-reentrant Conversion of Single
+                                         Characters.
+* Non-reentrant String Conversion::     Non-reentrant Conversion of Strings.
+* Shift State::                         States in Non-reentrant Functions.
+@end menu
+
+@node Non-reentrant Character Conversion
+@subsection Non-reentrant Conversion of Single Characters
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int mbtowc (wchar_t *restrict @var{result}, const char *restrict @var{string}, size_t @var{size})
+@safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{mbtowc} (``multibyte to wide character'') function when called
+with non-null @var{string} converts the first multibyte character
+beginning at @var{string} to its corresponding wide character code.  It
+stores the result in @code{*@var{result}}.
+
+@code{mbtowc} never examines more than @var{size} bytes.  (The idea is
+to supply for @var{size} the number of bytes of data you have in hand.)
+
+@code{mbtowc} with non-null @var{string} distinguishes three
+possibilities: the first @var{size} bytes at @var{string} start with
+valid multibyte characters, they start with an invalid byte sequence or
+just part of a character, or @var{string} points to an empty string (a
+null character).
+
+For a valid multibyte character, @code{mbtowc} converts it to a wide
+character and stores that in @code{*@var{result}}, and returns the
+number of bytes in that character (always at least @math{1} and never
+more than @var{size}).
+
+For an invalid byte sequence, @code{mbtowc} returns @math{-1}.  For an
+empty string, it returns @math{0}, also storing @code{'\0'} in
+@code{*@var{result}}.
+
+If the multibyte character code uses shift characters, then
+@code{mbtowc} maintains and updates a shift state as it scans.  If you
+call @code{mbtowc} with a null pointer for @var{string}, that
+initializes the shift state to its standard initial value.  It also
+returns nonzero if the multibyte character code in use actually has a
+shift state.  @xref{Shift State}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar})
+@safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{wctomb} (``wide character to multibyte'') function converts
+the wide character code @var{wchar} to its corresponding multibyte
+character sequence, and stores the result in bytes starting at
+@var{string}.  At most @code{MB_CUR_MAX} characters are stored.
+
+@code{wctomb} with non-null @var{string} distinguishes three
+possibilities for @var{wchar}: a valid wide character code (one that can
+be translated to a multibyte character), an invalid code, and
+@code{L'\0'}.
+
+Given a valid code, @code{wctomb} converts it to a multibyte character,
+storing the bytes starting at @var{string}.  Then it returns the number
+of bytes in that character (always at least @math{1} and never more
+than @code{MB_CUR_MAX}).
+
+If @var{wchar} is an invalid wide character code, @code{wctomb} returns
+@math{-1}.  If @var{wchar} is @code{L'\0'}, it returns @code{0}, also
+storing @code{'\0'} in @code{*@var{string}}.
+
+If the multibyte character code uses shift characters, then
+@code{wctomb} maintains and updates a shift state as it scans.  If you
+call @code{wctomb} with a null pointer for @var{string}, that
+initializes the shift state to its standard initial value.  It also
+returns nonzero if the multibyte character code in use actually has a
+shift state.  @xref{Shift State}.
+
+Calling this function with a @var{wchar} argument of zero when
+@var{string} is not null has the side-effect of reinitializing the
+stored shift state @emph{as well as} storing the multibyte character
+@code{'\0'} and returning @math{0}.
+@end deftypefun
+
+Similar to @code{mbrlen} there is also a non-reentrant function that
+computes the length of a multibyte character.  It can be defined in
+terms of @code{mbtowc}.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int mblen (const char *@var{string}, size_t @var{size})
+@safety{@prelim{}@mtunsafe{@mtasurace{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{mblen} function with a non-null @var{string} argument returns
+the number of bytes that make up the multibyte character beginning at
+@var{string}, never examining more than @var{size} bytes.  (The idea is
+to supply for @var{size} the number of bytes of data you have in hand.)
+
+The return value of @code{mblen} distinguishes three possibilities: the
+first @var{size} bytes at @var{string} start with valid multibyte
+characters, they start with an invalid byte sequence or just part of a
+character, or @var{string} points to an empty string (a null character).
+
+For a valid multibyte character, @code{mblen} returns the number of
+bytes in that character (always at least @code{1} and never more than
+@var{size}).  For an invalid byte sequence, @code{mblen} returns
+@math{-1}.  For an empty string, it returns @math{0}.
+
+If the multibyte character code uses shift characters, then @code{mblen}
+maintains and updates a shift state as it scans.  If you call
+@code{mblen} with a null pointer for @var{string}, that initializes the
+shift state to its standard initial value.  It also returns a nonzero
+value if the multibyte character code in use actually has a shift state.
+@xref{Shift State}.
+
+@pindex stdlib.h
+The function @code{mblen} is declared in @file{stdlib.h}.
+@end deftypefun
+
+
+@node Non-reentrant String Conversion
+@subsection Non-reentrant Conversion of Strings
+
+For convenience the @w{ISO C90} standard also defines functions to
+convert entire strings instead of single characters.  These functions
+suffer from the same problems as their reentrant counterparts from
+@w{Amendment 1} to @w{ISO C90}; see @ref{Converting Strings}.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Odd...  Although this was supposed to be non-reentrant, the internal
+@c state is not a static buffer, but an automatic variable.
+The @code{mbstowcs} (``multibyte string to wide character string'')
+function converts the null-terminated string of multibyte characters
+@var{string} to an array of wide character codes, storing not more than
+@var{size} wide characters into the array beginning at @var{wstring}.
+The terminating null character counts towards the size, so if @var{size}
+is less than the actual number of wide characters resulting from
+@var{string}, no terminating null character is stored.
+
+The conversion of characters from @var{string} begins in the initial
+shift state.
+
+If an invalid multibyte character sequence is found, the @code{mbstowcs}
+function returns a value of @math{-1}.  Otherwise, it returns the number
+of wide characters stored in the array @var{wstring}.  This number does
+not include the terminating null character, which is present if the
+number is less than @var{size}.
+
+Here is an example showing how to convert a string of multibyte
+characters, allocating enough space for the result.
+
+@smallexample
+wchar_t *
+mbstowcs_alloc (const char *string)
+@{
+  size_t size = strlen (string) + 1;
+  wchar_t *buf = xmalloc (size * sizeof (wchar_t));
+
+  size = mbstowcs (buf, string, size);
+  if (size == (size_t) -1)
+    return NULL;
+  buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
+  return buf;
+@}
+@end smallexample
+
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+The @code{wcstombs} (``wide character string to multibyte string'')
+function converts the null-terminated wide character array @var{wstring}
+into a string containing multibyte characters, storing not more than
+@var{size} bytes starting at @var{string}, followed by a terminating
+null character if there is room.  The conversion of characters begins in
+the initial shift state.
+
+The terminating null character counts towards the size, so if @var{size}
+is less than or equal to the number of bytes needed in @var{wstring}, no
+terminating null character is stored.
+
+If a code that does not correspond to a valid multibyte character is
+found, the @code{wcstombs} function returns a value of @math{-1}.
+Otherwise, the return value is the number of bytes stored in the array
+@var{string}.  This number does not include the terminating null character,
+which is present if the number is less than @var{size}.
+@end deftypefun
+
+@node Shift State
+@subsection States in Non-reentrant Functions
+
+In some multibyte character codes, the @emph{meaning} of any particular
+byte sequence is not fixed; it depends on what other sequences have come
+earlier in the same string.  Typically there are just a few sequences that
+can change the meaning of other sequences; these few are called
+@dfn{shift sequences} and we say that they set the @dfn{shift state} for
+other sequences that follow.
+
+To illustrate shift state and shift sequences, suppose we decide that
+the sequence @code{0200} (just one byte) enters Japanese mode, in which
+pairs of bytes in the range from @code{0240} to @code{0377} are single
+characters, while @code{0201} enters Latin-1 mode, in which single bytes
+in the range from @code{0240} to @code{0377} are characters, and
+interpreted according to the ISO Latin-1 character set.  This is a
+multibyte code that has two alternative shift states (``Japanese mode''
+and ``Latin-1 mode''), and two shift sequences that specify particular
+shift states.
+
+When the multibyte character code in use has shift states, then
+@code{mblen}, @code{mbtowc}, and @code{wctomb} must maintain and update
+the current shift state as they scan the string.  To make this work
+properly, you must follow these rules:
+
+@itemize @bullet
+@item
+Before starting to scan a string, call the function with a null pointer
+for the multibyte character address---for example, @code{mblen (NULL,
+0)}.  This initializes the shift state to its standard initial value.
+
+@item
+Scan the string one character at a time, in order.  Do not ``back up''
+and rescan characters already scanned, and do not intersperse the
+processing of different strings.
+@end itemize
+
+Here is an example of using @code{mblen} following these rules:
+
+@smallexample
+void
+scan_string (char *s)
+@{
+  int length = strlen (s);
+
+  /* @r{Initialize shift state.}  */
+  mblen (NULL, 0);
+
+  while (1)
+    @{
+      int thischar = mblen (s, length);
+      /* @r{Deal with end of string and invalid characters.}  */
+      if (thischar == 0)
+        break;
+      if (thischar == -1)
+        @{
+          error ("invalid multibyte character");
+          break;
+        @}
+      /* @r{Advance past this character.}  */
+      s += thischar;
+      length -= thischar;
+    @}
+@}
+@end smallexample
+
+The functions @code{mblen}, @code{mbtowc} and @code{wctomb} are not
+reentrant when using a multibyte code that uses a shift state.  However,
+no other library functions call these functions, so you don't have to
+worry that the shift state will be changed mysteriously.
+
+
+@node Generic Charset Conversion
+@section Generic Charset Conversion
+
+The conversion functions mentioned so far in this chapter all had in
+common that they operate on character sets that are not directly
+specified by the functions.  The multibyte encoding used is specified by
+the currently selected locale for the @code{LC_CTYPE} category.  The
+wide character set is fixed by the implementation (in the case of @theglibc{}
+it is always UCS-4 encoded @w{ISO 10646}.
+
+This has of course several problems when it comes to general character
+conversion:
+
+@itemize @bullet
+@item
+For every conversion where neither the source nor the destination
+character set is the character set of the locale for the @code{LC_CTYPE}
+category, one has to change the @code{LC_CTYPE} locale using
+@code{setlocale}.
+
+Changing the @code{LC_CTYPE} locale introduces major problems for the rest
+of the programs since several more functions (e.g., the character
+classification functions, @pxref{Classification of Characters}) use the
+@code{LC_CTYPE} category.
+
+@item
+Parallel conversions to and from different character sets are not
+possible since the @code{LC_CTYPE} selection is global and shared by all
+threads.
+
+@item
+If neither the source nor the destination character set is the character
+set used for @code{wchar_t} representation, there is at least a two-step
+process necessary to convert a text using the functions above.  One would
+have to select the source character set as the multibyte encoding,
+convert the text into a @code{wchar_t} text, select the destination
+character set as the multibyte encoding, and convert the wide character
+text to the multibyte (@math{=} destination) character set.
+
+Even if this is possible (which is not guaranteed) it is a very tiring
+work.  Plus it suffers from the other two raised points even more due to
+the steady changing of the locale.
+@end itemize
+
+The XPG2 standard defines a completely new set of functions, which has
+none of these limitations.  They are not at all coupled to the selected
+locales, and they have no constraints on the character sets selected for
+source and destination.  Only the set of available conversions limits
+them.  The standard does not specify that any conversion at all must be
+available.  Such availability is a measure of the quality of the
+implementation.
+
+In the following text first the interface to @code{iconv} and then the
+conversion function, will be described.  Comparisons with other
+implementations will show what obstacles stand in the way of portable
+applications.  Finally, the implementation is described in so far as might
+interest the advanced user who wants to extend conversion capabilities.
+
+@menu
+* Generic Conversion Interface::    Generic Character Set Conversion Interface.
+* iconv Examples::                  A complete @code{iconv} example.
+* Other iconv Implementations::     Some Details about other @code{iconv}
+                                     Implementations.
+* glibc iconv Implementation::      The @code{iconv} Implementation in the GNU C
+                                     library.
+@end menu
+
+@node Generic Conversion Interface
+@subsection Generic Character Set Conversion Interface
+
+This set of functions follows the traditional cycle of using a resource:
+open--use--close.  The interface consists of three functions, each of
+which implements one step.
+
+Before the interfaces are described it is necessary to introduce a
+data type.  Just like other open--use--close interfaces the functions
+introduced here work using handles and the @file{iconv.h} header
+defines a special type for the handles used.
+
+@comment iconv.h
+@comment XPG2
+@deftp {Data Type} iconv_t
+This data type is an abstract type defined in @file{iconv.h}.  The user
+must not assume anything about the definition of this type; it must be
+completely opaque.
+
+Objects of this type can get assigned handles for the conversions using
+the @code{iconv} functions.  The objects themselves need not be freed, but
+the conversions for which the handles stand for have to.
+@end deftp
+
+@noindent
+The first step is the function to create a handle.
+
+@comment iconv.h
+@comment XPG2
+@deftypefun iconv_t iconv_open (const char *@var{tocode}, const char *@var{fromcode})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Calls malloc if tocode and/or fromcode are too big for alloca.  Calls
+@c strip and upstr on both, then gconv_open.  strip and upstr call
+@c isalnum_l and toupper_l with the C locale.  gconv_open may MT-safely
+@c tokenize toset, replace unspecified codesets with the current locale
+@c (possibly two different accesses), and finally it calls
+@c gconv_find_transform and initializes the gconv_t result with all the
+@c steps in the conversion sequence, running each one's initializer,
+@c destructing and releasing them all if anything fails.
+
+The @code{iconv_open} function has to be used before starting a
+conversion.  The two parameters this function takes determine the
+source and destination character set for the conversion, and if the
+implementation has the possibility to perform such a conversion, the
+function returns a handle.
+
+If the wanted conversion is not available, the @code{iconv_open} function
+returns @code{(iconv_t) -1}.  In this case the global variable
+@code{errno} can have the following values:
+
+@table @code
+@item EMFILE
+The process already has @code{OPEN_MAX} file descriptors open.
+@item ENFILE
+The system limit of open file is reached.
+@item ENOMEM
+Not enough memory to carry out the operation.
+@item EINVAL
+The conversion from @var{fromcode} to @var{tocode} is not supported.
+@end table
+
+It is not possible to use the same descriptor in different threads to
+perform independent conversions.  The data structures associated
+with the descriptor include information about the conversion state.
+This must not be messed up by using it in different conversions.
+
+An @code{iconv} descriptor is like a file descriptor as for every use a
+new descriptor must be created.  The descriptor does not stand for all
+of the conversions from @var{fromset} to @var{toset}.
+
+The @glibcadj{} implementation of @code{iconv_open} has one
+significant extension to other implementations.  To ease the extension
+of the set of available conversions, the implementation allows storing
+the necessary files with data and code in an arbitrary number of
+directories.  How this extension must be written will be explained below
+(@pxref{glibc iconv Implementation}).  Here it is only important to say
+that all directories mentioned in the @code{GCONV_PATH} environment
+variable are considered only if they contain a file @file{gconv-modules}.
+These directories need not necessarily be created by the system
+administrator.  In fact, this extension is introduced to help users
+writing and using their own, new conversions.  Of course, this does not
+work for security reasons in SUID binaries; in this case only the system
+directory is considered and this normally is
+@file{@var{prefix}/lib/gconv}.  The @code{GCONV_PATH} environment
+variable is examined exactly once at the first call of the
+@code{iconv_open} function.  Later modifications of the variable have no
+effect.
+
+@pindex iconv.h
+The @code{iconv_open} function was introduced early in the X/Open
+Portability Guide, @w{version 2}.  It is supported by all commercial
+Unices as it is required for the Unix branding.  However, the quality and
+completeness of the implementation varies widely.  The @code{iconv_open}
+function is declared in @file{iconv.h}.
+@end deftypefun
+
+The @code{iconv} implementation can associate large data structure with
+the handle returned by @code{iconv_open}.  Therefore, it is crucial to
+free all the resources once all conversions are carried out and the
+conversion is not needed anymore.
+
+@comment iconv.h
+@comment XPG2
+@deftypefun int iconv_close (iconv_t @var{cd})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Calls gconv_close to destruct and release each of the conversion
+@c steps, release the gconv_t object, then call gconv_close_transform.
+@c Access to the gconv_t object is not guarded, but calling iconv_close
+@c concurrently with any other use is undefined.
+
+The @code{iconv_close} function frees all resources associated with the
+handle @var{cd}, which must have been returned by a successful call to
+the @code{iconv_open} function.
+
+If the function call was successful the return value is @math{0}.
+Otherwise it is @math{-1} and @code{errno} is set appropriately.
+Defined error are:
+
+@table @code
+@item EBADF
+The conversion descriptor is invalid.
+@end table
+
+@pindex iconv.h
+The @code{iconv_close} function was introduced together with the rest
+of the @code{iconv} functions in XPG2 and is declared in @file{iconv.h}.
+@end deftypefun
+
+The standard defines only one actual conversion function.  This has,
+therefore, the most general interface: it allows conversion from one
+buffer to another.  Conversion from a file to a buffer, vice versa, or
+even file to file can be implemented on top of it.
+
+@comment iconv.h
+@comment XPG2
+@deftypefun size_t iconv (iconv_t @var{cd}, char **@var{inbuf}, size_t *@var{inbytesleft}, char **@var{outbuf}, size_t *@var{outbytesleft})
+@safety{@prelim{}@mtsafe{@mtsrace{:cd}}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Without guarding access to the iconv_t object pointed to by cd, call
+@c the conversion function to convert inbuf or flush the internal
+@c conversion state.
+@cindex stateful
+The @code{iconv} function converts the text in the input buffer
+according to the rules associated with the descriptor @var{cd} and
+stores the result in the output buffer.  It is possible to call the
+function for the same text several times in a row since for stateful
+character sets the necessary state information is kept in the data
+structures associated with the descriptor.
+
+The input buffer is specified by @code{*@var{inbuf}} and it contains
+@code{*@var{inbytesleft}} bytes.  The extra indirection is necessary for
+communicating the used input back to the caller (see below).  It is
+important to note that the buffer pointer is of type @code{char} and the
+length is measured in bytes even if the input text is encoded in wide
+characters.
+
+The output buffer is specified in a similar way.  @code{*@var{outbuf}}
+points to the beginning of the buffer with at least
+@code{*@var{outbytesleft}} bytes room for the result.  The buffer
+pointer again is of type @code{char} and the length is measured in
+bytes.  If @var{outbuf} or @code{*@var{outbuf}} is a null pointer, the
+conversion is performed but no output is available.
+
+If @var{inbuf} is a null pointer, the @code{iconv} function performs the
+necessary action to put the state of the conversion into the initial
+state.  This is obviously a no-op for non-stateful encodings, but if the
+encoding has a state, such a function call might put some byte sequences
+in the output buffer, which perform the necessary state changes.  The
+next call with @var{inbuf} not being a null pointer then simply goes on
+from the initial state.  It is important that the programmer never makes
+any assumption as to whether the conversion has to deal with states.
+Even if the input and output character sets are not stateful, the
+implementation might still have to keep states.  This is due to the
+implementation chosen for @theglibc{} as it is described below.
+Therefore an @code{iconv} call to reset the state should always be
+performed if some protocol requires this for the output text.
+
+The conversion stops for one of three reasons.  The first is that all
+characters from the input buffer are converted.  This actually can mean
+two things: either all bytes from the input buffer are consumed or
+there are some bytes at the end of the buffer that possibly can form a
+complete character but the input is incomplete.  The second reason for a
+stop is that the output buffer is full.  And the third reason is that
+the input contains invalid characters.
+
+In all of these cases the buffer pointers after the last successful
+conversion, for input and output buffer, are stored in @var{inbuf} and
+@var{outbuf}, and the available room in each buffer is stored in
+@var{inbytesleft} and @var{outbytesleft}.
+
+Since the character sets selected in the @code{iconv_open} call can be
+almost arbitrary, there can be situations where the input buffer contains
+valid characters, which have no identical representation in the output
+character set.  The behavior in this situation is undefined.  The
+@emph{current} behavior of @theglibc{} in this situation is to
+return with an error immediately.  This certainly is not the most
+desirable solution; therefore, future versions will provide better ones,
+but they are not yet finished.
+
+If all input from the input buffer is successfully converted and stored
+in the output buffer, the function returns the number of non-reversible
+conversions performed.  In all other cases the return value is
+@code{(size_t) -1} and @code{errno} is set appropriately.  In such cases
+the value pointed to by @var{inbytesleft} is nonzero.
+
+@table @code
+@item EILSEQ
+The conversion stopped because of an invalid byte sequence in the input.
+After the call, @code{*@var{inbuf}} points at the first byte of the
+invalid byte sequence.
+
+@item E2BIG
+The conversion stopped because it ran out of space in the output buffer.
+
+@item EINVAL
+The conversion stopped because of an incomplete byte sequence at the end
+of the input buffer.
+
+@item EBADF
+The @var{cd} argument is invalid.
+@end table
+
+@pindex iconv.h
+The @code{iconv} function was introduced in the XPG2 standard and is
+declared in the @file{iconv.h} header.
+@end deftypefun
+
+The definition of the @code{iconv} function is quite good overall.  It
+provides quite flexible functionality.  The only problems lie in the
+boundary cases, which are incomplete byte sequences at the end of the
+input buffer and invalid input.  A third problem, which is not really
+a design problem, is the way conversions are selected.  The standard
+does not say anything about the legitimate names, a minimal set of
+available conversions.  We will see how this negatively impacts other
+implementations, as demonstrated below.
+
+@node iconv Examples
+@subsection A complete @code{iconv} example
+
+The example below features a solution for a common problem.  Given that
+one knows the internal encoding used by the system for @code{wchar_t}
+strings, one often is in the position to read text from a file and store
+it in wide character buffers.  One can do this using @code{mbsrtowcs},
+but then we run into the problems discussed above.
+
+@smallexample
+int
+file2wcs (int fd, const char *charset, wchar_t *outbuf, size_t avail)
+@{
+  char inbuf[BUFSIZ];
+  size_t insize = 0;
+  char *wrptr = (char *) outbuf;
+  int result = 0;
+  iconv_t cd;
+
+  cd = iconv_open ("WCHAR_T", charset);
+  if (cd == (iconv_t) -1)
+    @{
+      /* @r{Something went wrong.}  */
+      if (errno == EINVAL)
+        error (0, 0, "conversion from '%s' to wchar_t not available",
+               charset);
+      else
+        perror ("iconv_open");
+
+      /* @r{Terminate the output string.}  */
+      *outbuf = L'\0';
+
+      return -1;
+    @}
+
+  while (avail > 0)
+    @{
+      size_t nread;
+      size_t nconv;
+      char *inptr = inbuf;
+
+      /* @r{Read more input.}  */
+      nread = read (fd, inbuf + insize, sizeof (inbuf) - insize);
+      if (nread == 0)
+        @{
+          /* @r{When we come here the file is completely read.}
+             @r{This still could mean there are some unused}
+             @r{characters in the @code{inbuf}.  Put them back.}  */
+          if (lseek (fd, -insize, SEEK_CUR) == -1)
+            result = -1;
+
+          /* @r{Now write out the byte sequence to get into the}
+             @r{initial state if this is necessary.}  */
+          iconv (cd, NULL, NULL, &wrptr, &avail);
+
+          break;
+        @}
+      insize += nread;
+
+      /* @r{Do the conversion.}  */
+      nconv = iconv (cd, &inptr, &insize, &wrptr, &avail);
+      if (nconv == (size_t) -1)
+        @{
+          /* @r{Not everything went right.  It might only be}
+             @r{an unfinished byte sequence at the end of the}
+             @r{buffer.  Or it is a real problem.}  */
+          if (errno == EINVAL)
+            /* @r{This is harmless.  Simply move the unused}
+               @r{bytes to the beginning of the buffer so that}
+               @r{they can be used in the next round.}  */
+            memmove (inbuf, inptr, insize);
+          else
+            @{
+              /* @r{It is a real problem.  Maybe we ran out of}
+                 @r{space in the output buffer or we have invalid}
+                 @r{input.  In any case back the file pointer to}
+                 @r{the position of the last processed byte.}  */
+              lseek (fd, -insize, SEEK_CUR);
+              result = -1;
+              break;
+            @}
+        @}
+    @}
+
+  /* @r{Terminate the output string.}  */
+  if (avail >= sizeof (wchar_t))
+    *((wchar_t *) wrptr) = L'\0';
+
+  if (iconv_close (cd) != 0)
+    perror ("iconv_close");
+
+  return (wchar_t *) wrptr - outbuf;
+@}
+@end smallexample
+
+@cindex stateful
+This example shows the most important aspects of using the @code{iconv}
+functions.  It shows how successive calls to @code{iconv} can be used to
+convert large amounts of text.  The user does not have to care about
+stateful encodings as the functions take care of everything.
+
+An interesting point is the case where @code{iconv} returns an error and
+@code{errno} is set to @code{EINVAL}.  This is not really an error in the
+transformation.  It can happen whenever the input character set contains
+byte sequences of more than one byte for some character and texts are not
+processed in one piece.  In this case there is a chance that a multibyte
+sequence is cut.  The caller can then simply read the remainder of the
+takes and feed the offending bytes together with new character from the
+input to @code{iconv} and continue the work.  The internal state kept in
+the descriptor is @emph{not} unspecified after such an event as is the
+case with the conversion functions from the @w{ISO C} standard.
+
+The example also shows the problem of using wide character strings with
+@code{iconv}.  As explained in the description of the @code{iconv}
+function above, the function always takes a pointer to a @code{char}
+array and the available space is measured in bytes.  In the example, the
+output buffer is a wide character buffer; therefore, we use a local
+variable @var{wrptr} of type @code{char *}, which is used in the
+@code{iconv} calls.
+
+This looks rather innocent but can lead to problems on platforms that
+have tight restriction on alignment.  Therefore the caller of @code{iconv}
+has to make sure that the pointers passed are suitable for access of
+characters from the appropriate character set.  Since, in the
+above case, the input parameter to the function is a @code{wchar_t}
+pointer, this is the case (unless the user violates alignment when
+computing the parameter).  But in other situations, especially when
+writing generic functions where one does not know what type of character
+set one uses and, therefore, treats text as a sequence of bytes, it might
+become tricky.
+
+@node Other iconv Implementations
+@subsection Some Details about other @code{iconv} Implementations
+
+This is not really the place to discuss the @code{iconv} implementation
+of other systems but it is necessary to know a bit about them to write
+portable programs.  The above mentioned problems with the specification
+of the @code{iconv} functions can lead to portability issues.
+
+The first thing to notice is that, due to the large number of character
+sets in use, it is certainly not practical to encode the conversions
+directly in the C library.  Therefore, the conversion information must
+come from files outside the C library.  This is usually done in one or
+both of the following ways:
+
+@itemize @bullet
+@item
+The C library contains a set of generic conversion functions that can
+read the needed conversion tables and other information from data files.
+These files get loaded when necessary.
+
+This solution is problematic as it requires a great deal of effort to
+apply to all character sets (potentially an infinite set).  The
+differences in the structure of the different character sets is so large
+that many different variants of the table-processing functions must be
+developed.  In addition, the generic nature of these functions make them
+slower than specifically implemented functions.
+
+@item
+The C library only contains a framework that can dynamically load
+object files and execute the conversion functions contained therein.
+
+This solution provides much more flexibility.  The C library itself
+contains only very little code and therefore reduces the general memory
+footprint.  Also, with a documented interface between the C library and
+the loadable modules it is possible for third parties to extend the set
+of available conversion modules.  A drawback of this solution is that
+dynamic loading must be available.
+@end itemize
+
+Some implementations in commercial Unices implement a mixture of these
+possibilities; the majority implement only the second solution.  Using
+loadable modules moves the code out of the library itself and keeps
+the door open for extensions and improvements, but this design is also
+limiting on some platforms since not many platforms support dynamic
+loading in statically linked programs.  On platforms without this
+capability it is therefore not possible to use this interface in
+statically linked programs.  @Theglibc{} has, on ELF platforms, no
+problems with dynamic loading in these situations; therefore, this
+point is moot.  The danger is that one gets acquainted with this
+situation and forgets about the restrictions on other systems.
+
+A second thing to know about other @code{iconv} implementations is that
+the number of available conversions is often very limited.  Some
+implementations provide, in the standard release (not special
+international or developer releases), at most 100 to 200 conversion
+possibilities.  This does not mean 200 different character sets are
+supported; for example, conversions from one character set to a set of 10
+others might count as 10 conversions.  Together with the other direction
+this makes 20 conversion possibilities used up by one character set.  One
+can imagine the thin coverage these platform provide.  Some Unix vendors
+even provide only a handful of conversions, which renders them useless for
+almost all uses.
+
+This directly leads to a third and probably the most problematic point.
+The way the @code{iconv} conversion functions are implemented on all
+known Unix systems and the availability of the conversion functions from
+character set @math{@cal{A}} to @math{@cal{B}} and the conversion from
+@math{@cal{B}} to @math{@cal{C}} does @emph{not} imply that the
+conversion from @math{@cal{A}} to @math{@cal{C}} is available.
+
+This might not seem unreasonable and problematic at first, but it is a
+quite big problem as one will notice shortly after hitting it.  To show
+the problem we assume to write a program that has to convert from
+@math{@cal{A}} to @math{@cal{C}}.  A call like
+
+@smallexample
+cd = iconv_open ("@math{@cal{C}}", "@math{@cal{A}}");
+@end smallexample
+
+@noindent
+fails according to the assumption above.  But what does the program
+do now?  The conversion is necessary; therefore, simply giving up is not
+an option.
+
+This is a nuisance.  The @code{iconv} function should take care of this.
+But how should the program proceed from here on?  If it tries to convert
+to character set @math{@cal{B}}, first the two @code{iconv_open}
+calls
+
+@smallexample
+cd1 = iconv_open ("@math{@cal{B}}", "@math{@cal{A}}");
+@end smallexample
+
+@noindent
+and
+
+@smallexample
+cd2 = iconv_open ("@math{@cal{C}}", "@math{@cal{B}}");
+@end smallexample
+
+@noindent
+will succeed, but how to find @math{@cal{B}}?
+
+Unfortunately, the answer is: there is no general solution.  On some
+systems guessing might help.  On those systems most character sets can
+convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text.  Beside
+this only some very system-specific methods can help.  Since the
+conversion functions come from loadable modules and these modules must
+be stored somewhere in the filesystem, one @emph{could} try to find them
+and determine from the available file which conversions are available
+and whether there is an indirect route from @math{@cal{A}} to
+@math{@cal{C}}.
+
+This example shows one of the design errors of @code{iconv} mentioned
+above.  It should at least be possible to determine the list of available
+conversion programmatically so that if @code{iconv_open} says there is no
+such conversion, one could make sure this also is true for indirect
+routes.
+
+@node glibc iconv Implementation
+@subsection The @code{iconv} Implementation in @theglibc{}
+
+After reading about the problems of @code{iconv} implementations in the
+last section it is certainly good to note that the implementation in
+@theglibc{} has none of the problems mentioned above.  What
+follows is a step-by-step analysis of the points raised above.  The
+evaluation is based on the current state of the development (as of
+January 1999).  The development of the @code{iconv} functions is not
+complete, but basic functionality has solidified.
+
+@Theglibc{}'s @code{iconv} implementation uses shared loadable
+modules to implement the conversions.  A very small number of
+conversions are built into the library itself but these are only rather
+trivial conversions.
+
+All the benefits of loadable modules are available in the @glibcadj{}
+implementation.  This is especially appealing since the interface is
+well documented (see below), and it, therefore, is easy to write new
+conversion modules.  The drawback of using loadable objects is not a
+problem in @theglibc{}, at least on ELF systems.  Since the
+library is able to load shared objects even in statically linked
+binaries, static linking need not be forbidden in case one wants to use
+@code{iconv}.
+
+The second mentioned problem is the number of supported conversions.
+Currently, @theglibc{} supports more than 150 character sets.  The
+way the implementation is designed the number of supported conversions
+is greater than 22350 (@math{150} times @math{149}).  If any conversion
+from or to a character set is missing, it can be added easily.
+
+Particularly impressive as it may be, this high number is due to the
+fact that the @glibcadj{} implementation of @code{iconv} does not have
+the third problem mentioned above (i.e., whenever there is a conversion
+from a character set @math{@cal{A}} to @math{@cal{B}} and from
+@math{@cal{B}} to @math{@cal{C}} it is always possible to convert from
+@math{@cal{A}} to @math{@cal{C}} directly).  If the @code{iconv_open}
+returns an error and sets @code{errno} to @code{EINVAL}, there is no
+known way, directly or indirectly, to perform the wanted conversion.
+
+@cindex triangulation
+Triangulation is achieved by providing for each character set a
+conversion from and to UCS-4 encoded @w{ISO 10646}.  Using @w{ISO 10646}
+as an intermediate representation it is possible to @dfn{triangulate}
+(i.e., convert with an intermediate representation).
+
+There is no inherent requirement to provide a conversion to @w{ISO
+10646} for a new character set, and it is also possible to provide other
+conversions where neither source nor destination character set is @w{ISO
+10646}.  The existing set of conversions is simply meant to cover all
+conversions that might be of interest.
+
+@cindex ISO-2022-JP
+@cindex EUC-JP
+All currently available conversions use the triangulation method above,
+making conversion run unnecessarily slow.  If, for example, somebody
+often needs the conversion from ISO-2022-JP to EUC-JP, a quicker solution
+would involve direct conversion between the two character sets, skipping
+the input to @w{ISO 10646} first.  The two character sets of interest
+are much more similar to each other than to @w{ISO 10646}.
+
+In such a situation one easily can write a new conversion and provide it
+as a better alternative.  The @glibcadj{} @code{iconv} implementation
+would automatically use the module implementing the conversion if it is
+specified to be more efficient.
+
+@subsubsection Format of @file{gconv-modules} files
+
+All information about the available conversions comes from a file named
+@file{gconv-modules}, which can be found in any of the directories along
+the @code{GCONV_PATH}.  The @file{gconv-modules} files are line-oriented
+text files, where each of the lines has one of the following formats:
+
+@itemize @bullet
+@item
+If the first non-whitespace character is a @kbd{#} the line contains only
+comments and is ignored.
+
+@item
+Lines starting with @code{alias} define an alias name for a character
+set.  Two more words are expected on the line.  The first word
+defines the alias name, and the second defines the original name of the
+character set.  The effect is that it is possible to use the alias name
+in the @var{fromset} or @var{toset} parameters of @code{iconv_open} and
+achieve the same result as when using the real character set name.
+
+This is quite important as a character set has often many different
+names.  There is normally an official name but this need not correspond to
+the most popular name.  Beside this many character sets have special
+names that are somehow constructed.  For example, all character sets
+specified by the ISO have an alias of the form @code{ISO-IR-@var{nnn}}
+where @var{nnn} is the registration number.  This allows programs that
+know about the registration number to construct character set names and
+use them in @code{iconv_open} calls.  More on the available names and
+aliases follows below.
+
+@item
+Lines starting with @code{module} introduce an available conversion
+module.  These lines must contain three or four more words.
+
+The first word specifies the source character set, the second word the
+destination character set of conversion implemented in this module, and
+the third word is the name of the loadable module.  The filename is
+constructed by appending the usual shared object suffix (normally
+@file{.so}) and this file is then supposed to be found in the same
+directory the @file{gconv-modules} file is in.  The last word on the line,
+which is optional, is a numeric value representing the cost of the
+conversion.  If this word is missing, a cost of @math{1} is assumed.  The
+numeric value itself does not matter that much; what counts are the
+relative values of the sums of costs for all possible conversion paths.
+Below is a more precise description of the use of the cost value.
+@end itemize
+
+Returning to the example above where one has written a module to directly
+convert from ISO-2022-JP to EUC-JP and back.  All that has to be done is
+to put the new module, let its name be ISO2022JP-EUCJP.so, in a directory
+and add a file @file{gconv-modules} with the following content in the
+same directory:
+
+@smallexample
+module  ISO-2022-JP//   EUC-JP//        ISO2022JP-EUCJP    1
+module  EUC-JP//        ISO-2022-JP//   ISO2022JP-EUCJP    1
+@end smallexample
+
+To see why this is sufficient, it is necessary to understand how the
+conversion used by @code{iconv} (and described in the descriptor) is
+selected.  The approach to this problem is quite simple.
+
+At the first call of the @code{iconv_open} function the program reads
+all available @file{gconv-modules} files and builds up two tables: one
+containing all the known aliases and another that contains the
+information about the conversions and which shared object implements
+them.
+
+@subsubsection Finding the conversion path in @code{iconv}
+
+The set of available conversions form a directed graph with weighted
+edges.  The weights on the edges are the costs specified in the
+@file{gconv-modules} files.  The @code{iconv_open} function uses an
+algorithm suitable for search for the best path in such a graph and so
+constructs a list of conversions that must be performed in succession
+to get the transformation from the source to the destination character
+set.
+
+Explaining why the above @file{gconv-modules} files allows the
+@code{iconv} implementation to resolve the specific ISO-2022-JP to
+EUC-JP conversion module instead of the conversion coming with the
+library itself is straightforward.  Since the latter conversion takes two
+steps (from ISO-2022-JP to @w{ISO 10646} and then from @w{ISO 10646} to
+EUC-JP), the cost is @math{1+1 = 2}.  The above @file{gconv-modules}
+file, however, specifies that the new conversion modules can perform this
+conversion with only the cost of @math{1}.
+
+A mysterious item about the @file{gconv-modules} file above (and also
+the file coming with @theglibc{}) are the names of the character
+sets specified in the @code{module} lines.  Why do almost all the names
+end in @code{//}?  And this is not all: the names can actually be
+regular expressions.  At this point in time this mystery should not be
+revealed, unless you have the relevant spell-casting materials: ashes
+from an original @w{DOS 6.2} boot disk burnt in effigy, a crucifix
+blessed by St.@: Emacs, assorted herbal roots from Central America, sand
+from Cebu, etc.  Sorry!  @strong{The part of the implementation where
+this is used is not yet finished.  For now please simply follow the
+existing examples.  It'll become clearer once it is. --drepper}
+
+A last remark about the @file{gconv-modules} is about the names not
+ending with @code{//}.  A character set named @code{INTERNAL} is often
+mentioned.  From the discussion above and the chosen name it should have
+become clear that this is the name for the representation used in the
+intermediate step of the triangulation.  We have said that this is UCS-4
+but actually that is not quite right.  The UCS-4 specification also
+includes the specification of the byte ordering used.  Since a UCS-4 value
+consists of four bytes, a stored value is affected by byte ordering.  The
+internal representation is @emph{not} the same as UCS-4 in case the byte
+ordering of the processor (or at least the running process) is not the
+same as the one required for UCS-4.  This is done for performance reasons
+as one does not want to perform unnecessary byte-swapping operations if
+one is not interested in actually seeing the result in UCS-4.  To avoid
+trouble with endianness, the internal representation consistently is named
+@code{INTERNAL} even on big-endian systems where the representations are
+identical.
+
+@subsubsection @code{iconv} module data structures
+
+So far this section has described how modules are located and considered
+to be used.  What remains to be described is the interface of the modules
+so that one can write new ones.  This section describes the interface as
+it is in use in January 1999.  The interface will change a bit in the
+future but, with luck, only in an upwardly compatible way.
+
+The definitions necessary to write new modules are publicly available
+in the non-standard header @file{gconv.h}.  The following text,
+therefore, describes the definitions from this header file.  First,
+however, it is necessary to get an overview.
+
+From the perspective of the user of @code{iconv} the interface is quite
+simple: the @code{iconv_open} function returns a handle that can be used
+in calls to @code{iconv}, and finally the handle is freed with a call to
+@code{iconv_close}.  The problem is that the handle has to be able to
+represent the possibly long sequences of conversion steps and also the
+state of each conversion since the handle is all that is passed to the
+@code{iconv} function.  Therefore, the data structures are really the
+elements necessary to understanding the implementation.
+
+We need two different kinds of data structures.  The first describes the
+conversion and the second describes the state etc.  There are really two
+type definitions like this in @file{gconv.h}.
+@pindex gconv.h
+
+@comment gconv.h
+@comment GNU
+@deftp {Data type} {struct __gconv_step}
+This data structure describes one conversion a module can perform.  For
+each function in a loaded module with conversion functions there is
+exactly one object of this type.  This object is shared by all users of
+the conversion (i.e., this object does not contain any information
+corresponding to an actual conversion; it only describes the conversion
+itself).
+
+@table @code
+@item struct __gconv_loaded_object *__shlib_handle
+@itemx const char *__modname
+@itemx int __counter
+All these elements of the structure are used internally in the C library
+to coordinate loading and unloading the shared.  One must not expect any
+of the other elements to be available or initialized.
+
+@item const char *__from_name
+@itemx const char *__to_name
+@code{__from_name} and @code{__to_name} contain the names of the source and
+destination character sets.  They can be used to identify the actual
+conversion to be carried out since one module might implement conversions
+for more than one character set and/or direction.
+
+@item gconv_fct __fct
+@itemx gconv_init_fct __init_fct
+@itemx gconv_end_fct __end_fct
+These elements contain pointers to the functions in the loadable module.
+The interface will be explained below.
+
+@item int __min_needed_from
+@itemx int __max_needed_from
+@itemx int __min_needed_to
+@itemx int __max_needed_to;
+These values have to be supplied in the init function of the module.  The
+@code{__min_needed_from} value specifies how many bytes a character of
+the source character set at least needs.  The @code{__max_needed_from}
+specifies the maximum value that also includes possible shift sequences.
+
+The @code{__min_needed_to} and @code{__max_needed_to} values serve the
+same purpose as @code{__min_needed_from} and @code{__max_needed_from} but
+this time for the destination character set.
+
+It is crucial that these values be accurate since otherwise the
+conversion functions will have problems or not work at all.
+
+@item int __stateful
+This element must also be initialized by the init function.
+@code{int __stateful} is nonzero if the source character set is stateful.
+Otherwise it is zero.
+
+@item void *__data
+This element can be used freely by the conversion functions in the
+module.  @code{void *__data} can be used to communicate extra information
+from one call to another.  @code{void *__data} need not be initialized if
+not needed at all.  If @code{void *__data} element is assigned a pointer
+to dynamically allocated memory (presumably in the init function) it has
+to be made sure that the end function deallocates the memory.  Otherwise
+the application will leak memory.
+
+It is important to be aware that this data structure is shared by all
+users of this specification conversion and therefore the @code{__data}
+element must not contain data specific to one specific use of the
+conversion function.
+@end table
+@end deftp
+
+@comment gconv.h
+@comment GNU
+@deftp {Data type} {struct __gconv_step_data}
+This is the data structure that contains the information specific to
+each use of the conversion functions.
+
+
+@table @code
+@item char *__outbuf
+@itemx char *__outbufend
+These elements specify the output buffer for the conversion step.  The
+@code{__outbuf} element points to the beginning of the buffer, and
+@code{__outbufend} points to the byte following the last byte in the
+buffer.  The conversion function must not assume anything about the size
+of the buffer but it can be safely assumed the there is room for at
+least one complete character in the output buffer.
+
+Once the conversion is finished, if the conversion is the last step, the
+@code{__outbuf} element must be modified to point after the last byte
+written into the buffer to signal how much output is available.  If this
+conversion step is not the last one, the element must not be modified.
+The @code{__outbufend} element must not be modified.
+
+@item int __is_last
+This element is nonzero if this conversion step is the last one.  This
+information is necessary for the recursion.  See the description of the
+conversion function internals below.  This element must never be
+modified.
+
+@item int __invocation_counter
+The conversion function can use this element to see how many calls of
+the conversion function already happened.  Some character sets require a
+certain prolog when generating output, and by comparing this value with
+zero, one can find out whether it is the first call and whether,
+therefore, the prolog should be emitted.  This element must never be
+modified.
+
+@item int __internal_use
+This element is another one rarely used but needed in certain
+situations.  It is assigned a nonzero value in case the conversion
+functions are used to implement @code{mbsrtowcs} et.al.@: (i.e., the
+function is not used directly through the @code{iconv} interface).
+
+This sometimes makes a difference as it is expected that the
+@code{iconv} functions are used to translate entire texts while the
+@code{mbsrtowcs} functions are normally used only to convert single
+strings and might be used multiple times to convert entire texts.
+
+But in this situation we would have problem complying with some rules of
+the character set specification.  Some character sets require a prolog,
+which must appear exactly once for an entire text.  If a number of
+@code{mbsrtowcs} calls are used to convert the text, only the first call
+must add the prolog.  However, because there is no communication between the
+different calls of @code{mbsrtowcs}, the conversion functions have no
+possibility to find this out.  The situation is different for sequences
+of @code{iconv} calls since the handle allows access to the needed
+information.
+
+The @code{int __internal_use} element is mostly used together with
+@code{__invocation_counter} as follows:
+
+@smallexample
+if (!data->__internal_use
+     && data->__invocation_counter == 0)
+  /* @r{Emit prolog.}  */
+  @dots{}
+@end smallexample
+
+This element must never be modified.
+
+@item mbstate_t *__statep
+The @code{__statep} element points to an object of type @code{mbstate_t}
+(@pxref{Keeping the state}).  The conversion of a stateful character
+set must use the object pointed to by @code{__statep} to store
+information about the conversion state.  The @code{__statep} element
+itself must never be modified.
+
+@item mbstate_t __state
+This element must @emph{never} be used directly.  It is only part of
+this structure to have the needed space allocated.
+@end table
+@end deftp
+
+@subsubsection @code{iconv} module interfaces
+
+With the knowledge about the data structures we now can describe the
+conversion function itself.  To understand the interface a bit of
+knowledge is necessary about the functionality in the C library that
+loads the objects with the conversions.
+
+It is often the case that one conversion is used more than once (i.e.,
+there are several @code{iconv_open} calls for the same set of character
+sets during one program run).  The @code{mbsrtowcs} et.al.@: functions in
+@theglibc{} also use the @code{iconv} functionality, which
+increases the number of uses of the same functions even more.
+
+Because of this multiple use of conversions, the modules do not get
+loaded exclusively for one conversion.  Instead a module once loaded can
+be used by an arbitrary number of @code{iconv} or @code{mbsrtowcs} calls
+at the same time.  The splitting of the information between conversion-
+function-specific information and conversion data makes this possible.
+The last section showed the two data structures used to do this.
+
+This is of course also reflected in the interface and semantics of the
+functions that the modules must provide.  There are three functions that
+must have the following names:
+
+@table @code
+@item gconv_init
+The @code{gconv_init} function initializes the conversion function
+specific data structure.  This very same object is shared by all
+conversions that use this conversion and, therefore, no state information
+about the conversion itself must be stored in here.  If a module
+implements more than one conversion, the @code{gconv_init} function will
+be called multiple times.
+
+@item gconv_end
+The @code{gconv_end} function is responsible for freeing all resources
+allocated by the @code{gconv_init} function.  If there is nothing to do,
+this function can be missing.  Special care must be taken if the module
+implements more than one conversion and the @code{gconv_init} function
+does not allocate the same resources for all conversions.
+
+@item gconv
+This is the actual conversion function.  It is called to convert one
+block of text.  It gets passed the conversion step information
+initialized by @code{gconv_init} and the conversion data, specific to
+this use of the conversion functions.
+@end table
+
+There are three data types defined for the three module interface
+functions and these define the interface.
+
+@comment gconv.h
+@comment GNU
+@deftypevr {Data type} int {(*__gconv_init_fct)} (struct __gconv_step *)
+This specifies the interface of the initialization function of the
+module.  It is called exactly once for each conversion the module
+implements.
+
+As explained in the description of the @code{struct __gconv_step} data
+structure above the initialization function has to initialize parts of
+it.
+
+@table @code
+@item __min_needed_from
+@itemx __max_needed_from
+@itemx __min_needed_to
+@itemx __max_needed_to
+These elements must be initialized to the exact numbers of the minimum
+and maximum number of bytes used by one character in the source and
+destination character sets, respectively.  If the characters all have the
+same size, the minimum and maximum values are the same.
+
+@item __stateful
+This element must be initialized to a nonzero value if the source
+character set is stateful.  Otherwise it must be zero.
+@end table
+
+If the initialization function needs to communicate some information
+to the conversion function, this communication can happen using the
+@code{__data} element of the @code{__gconv_step} structure.  But since
+this data is shared by all the conversions, it must not be modified by
+the conversion function.  The example below shows how this can be used.
+
+@smallexample
+#define MIN_NEEDED_FROM         1
+#define MAX_NEEDED_FROM         4
+#define MIN_NEEDED_TO           4
+#define MAX_NEEDED_TO           4
+
+int
+gconv_init (struct __gconv_step *step)
+@{
+  /* @r{Determine which direction.}  */
+  struct iso2022jp_data *new_data;
+  enum direction dir = illegal_dir;
+  enum variant var = illegal_var;
+  int result;
+
+  if (__strcasecmp (step->__from_name, "ISO-2022-JP//") == 0)
+    @{
+      dir = from_iso2022jp;
+      var = iso2022jp;
+    @}
+  else if (__strcasecmp (step->__to_name, "ISO-2022-JP//") == 0)
+    @{
+      dir = to_iso2022jp;
+      var = iso2022jp;
+    @}
+  else if (__strcasecmp (step->__from_name, "ISO-2022-JP-2//") == 0)
+    @{
+      dir = from_iso2022jp;
+      var = iso2022jp2;
+    @}
+  else if (__strcasecmp (step->__to_name, "ISO-2022-JP-2//") == 0)
+    @{
+      dir = to_iso2022jp;
+      var = iso2022jp2;
+    @}
+
+  result = __GCONV_NOCONV;
+  if (dir != illegal_dir)
+    @{
+      new_data = (struct iso2022jp_data *)
+        malloc (sizeof (struct iso2022jp_data));
+
+      result = __GCONV_NOMEM;
+      if (new_data != NULL)
+        @{
+          new_data->dir = dir;
+          new_data->var = var;
+          step->__data = new_data;
+
+          if (dir == from_iso2022jp)
+            @{
+              step->__min_needed_from = MIN_NEEDED_FROM;
+              step->__max_needed_from = MAX_NEEDED_FROM;
+              step->__min_needed_to = MIN_NEEDED_TO;
+              step->__max_needed_to = MAX_NEEDED_TO;
+            @}
+          else
+            @{
+              step->__min_needed_from = MIN_NEEDED_TO;
+              step->__max_needed_from = MAX_NEEDED_TO;
+              step->__min_needed_to = MIN_NEEDED_FROM;
+              step->__max_needed_to = MAX_NEEDED_FROM + 2;
+            @}
+
+          /* @r{Yes, this is a stateful encoding.}  */
+          step->__stateful = 1;
+
+          result = __GCONV_OK;
+        @}
+    @}
+
+  return result;
+@}
+@end smallexample
+
+The function first checks which conversion is wanted.  The module from
+which this function is taken implements four different conversions;
+which one is selected can be determined by comparing the names.  The
+comparison should always be done without paying attention to the case.
+
+Next, a data structure, which contains the necessary information about
+which conversion is selected, is allocated.  The data structure
+@code{struct iso2022jp_data} is locally defined since, outside the
+module, this data is not used at all.  Please note that if all four
+conversions this modules supports are requested there are four data
+blocks.
+
+One interesting thing is the initialization of the @code{__min_} and
+@code{__max_} elements of the step data object.  A single ISO-2022-JP
+character can consist of one to four bytes.  Therefore the
+@code{MIN_NEEDED_FROM} and @code{MAX_NEEDED_FROM} macros are defined
+this way.  The output is always the @code{INTERNAL} character set (aka
+UCS-4) and therefore each character consists of exactly four bytes.  For
+the conversion from @code{INTERNAL} to ISO-2022-JP we have to take into
+account that escape sequences might be necessary to switch the character
+sets.  Therefore the @code{__max_needed_to} element for this direction
+gets assigned @code{MAX_NEEDED_FROM + 2}.  This takes into account the
+two bytes needed for the escape sequences to single the switching.  The
+asymmetry in the maximum values for the two directions can be explained
+easily: when reading ISO-2022-JP text, escape sequences can be handled
+alone (i.e., it is not necessary to process a real character since the
+effect of the escape sequence can be recorded in the state information).
+The situation is different for the other direction.  Since it is in
+general not known which character comes next, one cannot emit escape
+sequences to change the state in advance.  This means the escape
+sequences that have to be emitted together with the next character.
+Therefore one needs more room than only for the character itself.
+
+The possible return values of the initialization function are:
+
+@table @code
+@item __GCONV_OK
+The initialization succeeded
+@item __GCONV_NOCONV
+The requested conversion is not supported in the module.  This can
+happen if the @file{gconv-modules} file has errors.
+@item __GCONV_NOMEM
+Memory required to store additional information could not be allocated.
+@end table
+@end deftypevr
+
+The function called before the module is unloaded is significantly
+easier.  It often has nothing at all to do; in which case it can be left
+out completely.
+
+@comment gconv.h
+@comment GNU
+@deftypevr {Data type} void {(*__gconv_end_fct)} (struct gconv_step *)
+The task of this function is to free all resources allocated in the
+initialization function.  Therefore only the @code{__data} element of
+the object pointed to by the argument is of interest.  Continuing the
+example from the initialization function, the finalization function
+looks like this:
+
+@smallexample
+void
+gconv_end (struct __gconv_step *data)
+@{
+  free (data->__data);
+@}
+@end smallexample
+@end deftypevr
+
+The most important function is the conversion function itself, which can
+get quite complicated for complex character sets.  But since this is not
+of interest here, we will only describe a possible skeleton for the
+conversion function.
+
+@comment gconv.h
+@comment GNU
+@deftypevr {Data type} int {(*__gconv_fct)} (struct __gconv_step *, struct __gconv_step_data *, const char **, const char *, size_t *, int)
+The conversion function can be called for two basic reason: to convert
+text or to reset the state.  From the description of the @code{iconv}
+function it can be seen why the flushing mode is necessary.  What mode
+is selected is determined by the sixth argument, an integer.  This
+argument being nonzero means that flushing is selected.
+
+Common to both modes is where the output buffer can be found.  The
+information about this buffer is stored in the conversion step data.  A
+pointer to this information is passed as the second argument to this
+function.  The description of the @code{struct __gconv_step_data}
+structure has more information on the conversion step data.
+
+@cindex stateful
+What has to be done for flushing depends on the source character set.
+If the source character set is not stateful, nothing has to be done.
+Otherwise the function has to emit a byte sequence to bring the state
+object into the initial state.  Once this all happened the other
+conversion modules in the chain of conversions have to get the same
+chance.  Whether another step follows can be determined from the
+@code{__is_last} element of the step data structure to which the first
+parameter points.
+
+The more interesting mode is when actual text has to be converted.  The
+first step in this case is to convert as much text as possible from the
+input buffer and store the result in the output buffer.  The start of the
+input buffer is determined by the third argument, which is a pointer to a
+pointer variable referencing the beginning of the buffer.  The fourth
+argument is a pointer to the byte right after the last byte in the buffer.
+
+The conversion has to be performed according to the current state if the
+character set is stateful.  The state is stored in an object pointed to
+by the @code{__statep} element of the step data (second argument).  Once
+either the input buffer is empty or the output buffer is full the
+conversion stops.  At this point, the pointer variable referenced by the
+third parameter must point to the byte following the last processed
+byte (i.e., if all of the input is consumed, this pointer and the fourth
+parameter have the same value).
+
+What now happens depends on whether this step is the last one.  If it is
+the last step, the only thing that has to be done is to update the
+@code{__outbuf} element of the step data structure to point after the
+last written byte.  This update gives the caller the information on how
+much text is available in the output buffer.  In addition, the variable
+pointed to by the fifth parameter, which is of type @code{size_t}, must
+be incremented by the number of characters (@emph{not bytes}) that were
+converted in a non-reversible way.  Then, the function can return.
+
+In case the step is not the last one, the later conversion functions have
+to get a chance to do their work.  Therefore, the appropriate conversion
+function has to be called.  The information about the functions is
+stored in the conversion data structures, passed as the first parameter.
+This information and the step data are stored in arrays, so the next
+element in both cases can be found by simple pointer arithmetic:
+
+@smallexample
+int
+gconv (struct __gconv_step *step, struct __gconv_step_data *data,
+       const char **inbuf, const char *inbufend, size_t *written,
+       int do_flush)
+@{
+  struct __gconv_step *next_step = step + 1;
+  struct __gconv_step_data *next_data = data + 1;
+  @dots{}
+@end smallexample
+
+The @code{next_step} pointer references the next step information and
+@code{next_data} the next data record.  The call of the next function
+therefore will look similar to this:
+
+@smallexample
+  next_step->__fct (next_step, next_data, &outerr, outbuf,
+                    written, 0)
+@end smallexample
+
+But this is not yet all.  Once the function call returns the conversion
+function might have some more to do.  If the return value of the function
+is @code{__GCONV_EMPTY_INPUT}, more room is available in the output
+buffer.  Unless the input buffer is empty the conversion, functions start
+all over again and process the rest of the input buffer.  If the return
+value is not @code{__GCONV_EMPTY_INPUT}, something went wrong and we have
+to recover from this.
+
+A requirement for the conversion function is that the input buffer
+pointer (the third argument) always point to the last character that
+was put in converted form into the output buffer.  This is trivially
+true after the conversion performed in the current step, but if the
+conversion functions deeper downstream stop prematurely, not all
+characters from the output buffer are consumed and, therefore, the input
+buffer pointers must be backed off to the right position.
+
+Correcting the input buffers is easy to do if the input and output
+character sets have a fixed width for all characters.  In this situation
+we can compute how many characters are left in the output buffer and,
+therefore, can correct the input buffer pointer appropriately with a
+similar computation.  Things are getting tricky if either character set
+has characters represented with variable length byte sequences, and it
+gets even more complicated if the conversion has to take care of the
+state.  In these cases the conversion has to be performed once again, from
+the known state before the initial conversion (i.e., if necessary the
+state of the conversion has to be reset and the conversion loop has to be
+executed again).  The difference now is that it is known how much input
+must be created, and the conversion can stop before converting the first
+unused character.  Once this is done the input buffer pointers must be
+updated again and the function can return.
+
+One final thing should be mentioned.  If it is necessary for the
+conversion to know whether it is the first invocation (in case a prolog
+has to be emitted), the conversion function should increment the
+@code{__invocation_counter} element of the step data structure just
+before returning to the caller.  See the description of the @code{struct
+__gconv_step_data} structure above for more information on how this can
+be used.
+
+The return value must be one of the following values:
+
+@table @code
+@item __GCONV_EMPTY_INPUT
+All input was consumed and there is room left in the output buffer.
+@item __GCONV_FULL_OUTPUT
+No more room in the output buffer.  In case this is not the last step
+this value is propagated down from the call of the next conversion
+function in the chain.
+@item __GCONV_INCOMPLETE_INPUT
+The input buffer is not entirely empty since it contains an incomplete
+character sequence.
+@end table
+
+The following example provides a framework for a conversion function.
+In case a new conversion has to be written the holes in this
+implementation have to be filled and that is it.
+
+@smallexample
+int
+gconv (struct __gconv_step *step, struct __gconv_step_data *data,
+       const char **inbuf, const char *inbufend, size_t *written,
+       int do_flush)
+@{
+  struct __gconv_step *next_step = step + 1;
+  struct __gconv_step_data *next_data = data + 1;
+  gconv_fct fct = next_step->__fct;
+  int status;
+
+  /* @r{If the function is called with no input this means we have}
+     @r{to reset to the initial state.  The possibly partly}
+     @r{converted input is dropped.}  */
+  if (do_flush)
+    @{
+      status = __GCONV_OK;
+
+      /* @r{Possible emit a byte sequence which put the state object}
+         @r{into the initial state.}  */
+
+      /* @r{Call the steps down the chain if there are any but only}
+         @r{if we successfully emitted the escape sequence.}  */
+      if (status == __GCONV_OK && ! data->__is_last)
+        status = fct (next_step, next_data, NULL, NULL,
+                      written, 1);
+    @}
+  else
+    @{
+      /* @r{We preserve the initial values of the pointer variables.}  */
+      const char *inptr = *inbuf;
+      char *outbuf = data->__outbuf;
+      char *outend = data->__outbufend;
+      char *outptr;
+
+      do
+        @{
+          /* @r{Remember the start value for this round.}  */
+          inptr = *inbuf;
+          /* @r{The outbuf buffer is empty.}  */
+          outptr = outbuf;
+
+          /* @r{For stateful encodings the state must be safe here.}  */
+
+          /* @r{Run the conversion loop.  @code{status} is set}
+             @r{appropriately afterwards.}  */
+
+          /* @r{If this is the last step, leave the loop.  There is}
+             @r{nothing we can do.}  */
+          if (data->__is_last)
+            @{
+              /* @r{Store information about how many bytes are}
+                 @r{available.}  */
+              data->__outbuf = outbuf;
+
+             /* @r{If any non-reversible conversions were performed,}
+                @r{add the number to @code{*written}.}  */
+
+             break;
+           @}
+
+          /* @r{Write out all output that was produced.}  */
+          if (outbuf > outptr)
+            @{
+              const char *outerr = data->__outbuf;
+              int result;
+
+              result = fct (next_step, next_data, &outerr,
+                            outbuf, written, 0);
+
+              if (result != __GCONV_EMPTY_INPUT)
+                @{
+                  if (outerr != outbuf)
+                    @{
+                      /* @r{Reset the input buffer pointer.  We}
+                         @r{document here the complex case.}  */
+                      size_t nstatus;
+
+                      /* @r{Reload the pointers.}  */
+                      *inbuf = inptr;
+                      outbuf = outptr;
+
+                      /* @r{Possibly reset the state.}  */
+
+                      /* @r{Redo the conversion, but this time}
+                         @r{the end of the output buffer is at}
+                         @r{@code{outerr}.}  */
+                    @}
+
+                  /* @r{Change the status.}  */
+                  status = result;
+                @}
+              else
+                /* @r{All the output is consumed, we can make}
+                   @r{ another run if everything was ok.}  */
+                if (status == __GCONV_FULL_OUTPUT)
+                  status = __GCONV_OK;
+           @}
+        @}
+      while (status == __GCONV_OK);
+
+      /* @r{We finished one use of this step.}  */
+      ++data->__invocation_counter;
+    @}
+
+  return status;
+@}
+@end smallexample
+@end deftypevr
+
+This information should be sufficient to write new modules.  Anybody
+doing so should also take a look at the available source code in the
+@glibcadj{} sources.  It contains many examples of working and optimized
+modules.
+
+@c File charset.texi edited October 2001 by Dennis Grace, IBM Corporation
diff --git a/ap/libc/glibc/glibc-2.23/manual/check-safety.sh b/ap/libc/glibc/glibc-2.23/manual/check-safety.sh
new file mode 100644
index 0000000..2eba000
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/check-safety.sh
@@ -0,0 +1,124 @@
+#!/bin/sh
+
+# Copyright 2014-2016 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+
+# The GNU C Library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+
+# The GNU C Library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with the GNU C Library; if not, see
+# <http://www.gnu.org/licenses/>.
+
+
+# Check that the @safety notes are self-consistent, i.e., that they're
+# in proper order (mt then as then ac), that remarks appear within
+# corresponding sections (mt within mt, etc), that unsafety always has
+# an explicit reason and when there's a reason for unsafety it's not
+# safe, and that there aren't duplicates remarks.
+
+
+success=:
+
+# If no arguments are given, take all *.texi files in the current directory.
+test $# != 0 || set *.texi
+
+# FIXME: check that each @deftypefu?n is followed by a @safety note,
+# with nothing but @deftypefu?nx and comment lines in between.  (There
+# might be more stuff too).
+
+
+# Check that all safety remarks have entries for all of MT, AS and AC,
+# in this order, with an optional prelim note before them.
+grep -n '^@safety' "$@" |
+grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\
+'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' &&
+success=false
+
+# Check that @mt-started notes appear within @mtsafe or @mtunsafe,
+# that @as-started notes appear within @assafe or @asunsafe, and that
+# @ac-started notes appear within @acsafe or @acunsafe.  Also check
+# that @mt, @as and @ac are followed by an s (for safe) or u (for
+# unsafe), but let @mt have as, ac or asc before [su], and let @as
+# have a c (for cancel) before [su].  Also make sure blanks separate
+# each of the annotations.
+grep -n '^@safety' "$@" |
+grep -v ':@safety{\(@prelim{}\)\?'\
+'@mt\(un\)\?safe{\(@mt\(asc\?\|ac\)\?[su][^ ]*}\)\?'\
+'\( @mt\(asc\?\|ac\)\?[su][^ ]*}\)*}'\
+'@as\(un\)\?safe{\(@asc\?[su][^ ]*}\)\?'\
+'\( @asc\?[su][^ ]*}\)*}'\
+'@ac\(un\)\?safe{\(@ac[su][^ ]*}\)\?'\
+'\( @ac[su][^ ]*}\)*}}' &&
+success=false
+
+# Make sure safety lines marked as @mtsafe do not contain any
+# MT-Unsafe remark; that would be @mtu, but there could be as, ac or
+# asc between mt and u.
+grep -n '^@safety.*@mtsafe' "$@" |
+grep '@mt\(asc\?\|ac\)?u' "$@" &&
+success=false
+
+# Make sure @mtunsafe lines contain at least one @mtu remark (with
+# optional as, ac or asc between mt and u).
+grep -n '^@safety.*@mtunsafe' "$@" |
+grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' &&
+success=false
+
+# Make sure safety lines marked as @assafe do not contain any AS-Unsafe
+# remark, which could be @asu or @mtasu note (with an optional c
+# between as and u in both cases).
+grep -n '^@safety.*@assafe' "$@" |
+grep '@\(mt\)\?asc\?u' &&
+success=false
+
+# Make sure @asunsafe lines contain at least one @asu remark (which
+# could be @ascu, or @mtasu or even @mtascu).
+grep -n '^@safety.*@asunsafe' "$@" |
+grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' &&
+success=false
+
+# Make sure safety lines marked as @acsafe do not contain any
+# AC-Unsafe remark, which could be @acu, @ascu or even @mtacu or
+# @mtascu.
+grep -n '^@safety.*@acsafe' "$@" |
+grep '@\(mt\)\?as\?cu' &&
+success=false
+
+# Make sure @acunsafe lines contain at least one @acu remark (possibly
+# implied by @ascu, @mtacu or @mtascu).
+grep -n '^@safety.*@acunsafe' "$@" |
+grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' &&
+success=false
+
+# Make sure there aren't duplicate remarks in the same safety note.
+grep -n '^@safety' "$@" |
+grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' &&
+success=false
+
+# Check that comments containing safety remarks do not contain {}s,
+# that all @mt remarks appear before @as remarks, that in turn appear
+# before @ac remarks, all properly blank-separated, and that an
+# optional comment about exclusions is between []s at the end of the
+# line.
+grep -n '^@c \+[^@ ]\+\( dup\)\?'\
+'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
+grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\
+'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' &&
+success=false
+
+# Check that comments containing safety remarks do not contain
+# duplicate remarks.
+grep -n '^@c \+[^@ ]\+\( dup\)\?'\
+'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
+grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' &&
+success=false
+
+$success
diff --git a/ap/libc/glibc/glibc-2.23/manual/conf.texi b/ap/libc/glibc/glibc-2.23/manual/conf.texi
new file mode 100644
index 0000000..82a8766
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/conf.texi
@@ -0,0 +1,1759 @@
+@node System Configuration, Cryptographic Functions, System Management, Top
+@c %MENU% Parameters describing operating system limits
+@chapter System Configuration Parameters
+
+The functions and macros listed in this chapter give information about
+configuration parameters of the operating system---for example, capacity
+limits, presence of optional POSIX features, and the default path for
+executable files (@pxref{String Parameters}).
+
+@menu
+* General Limits::           Constants and functions that describe
+				various process-related limits that have
+				one uniform value for any given machine.
+* System Options::           Optional POSIX features.
+* Version Supported::        Version numbers of POSIX.1 and POSIX.2.
+* Sysconf::                  Getting specific configuration values
+                                of general limits and system options.
+* Minimums::                 Minimum values for general limits.
+
+* Limits for Files::         Size limitations that pertain to individual files.
+                                These can vary between file systems
+                                or even from file to file.
+* Options for Files::        Optional features that some files may support.
+* File Minimums::            Minimum values for file limits.
+* Pathconf::                 Getting the limit values for a particular file.
+
+* Utility Limits::           Capacity limits of some POSIX.2 utility programs.
+* Utility Minimums::         Minimum allowable values of those limits.
+
+* String Parameters::        Getting the default search path.
+@end menu
+
+@node General Limits
+@section General Capacity Limits
+@cindex POSIX capacity limits
+@cindex limits, POSIX
+@cindex capacity limits, POSIX
+
+The POSIX.1 and POSIX.2 standards specify a number of parameters that
+describe capacity limitations of the system.  These limits can be fixed
+constants for a given operating system, or they can vary from machine to
+machine.  For example, some limit values may be configurable by the
+system administrator, either at run time or by rebuilding the kernel,
+and this should not require recompiling application programs.
+
+@pindex limits.h
+Each of the following limit parameters has a macro that is defined in
+@file{limits.h} only if the system has a fixed, uniform limit for the
+parameter in question.  If the system allows different file systems or
+files to have different limits, then the macro is undefined; use
+@code{sysconf} to find out the limit that applies at a particular time
+on a particular machine.  @xref{Sysconf}.
+
+Each of these parameters also has another macro, with a name starting
+with @samp{_POSIX}, which gives the lowest value that the limit is
+allowed to have on @emph{any} POSIX system.  @xref{Minimums}.
+
+@cindex limits, program argument size
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int ARG_MAX
+If defined, the unvarying maximum combined length of the @var{argv} and
+@var{environ} arguments that can be passed to the @code{exec} functions.
+@end deftypevr
+
+@cindex limits, number of processes
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int CHILD_MAX
+If defined, the unvarying maximum number of processes that can exist
+with the same real user ID at any one time.  In BSD and GNU, this is
+controlled by the @code{RLIMIT_NPROC} resource limit; @pxref{Limits on
+Resources}.
+@end deftypevr
+
+@cindex limits, number of open files
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int OPEN_MAX
+If defined, the unvarying maximum number of files that a single process
+can have open simultaneously.  In BSD and GNU, this is controlled
+by the @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int STREAM_MAX
+If defined, the unvarying maximum number of streams that a single
+process can have open simultaneously.  @xref{Opening Streams}.
+@end deftypevr
+
+@cindex limits, time zone name length
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int TZNAME_MAX
+If defined, the unvarying maximum length of a time zone name.
+@xref{Time Zone Functions}.
+@end deftypevr
+
+These limit macros are always defined in @file{limits.h}.
+
+@cindex limits, number of supplementary group IDs
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int NGROUPS_MAX
+The maximum number of supplementary group IDs that one process can have.
+
+The value of this macro is actually a lower bound for the maximum.  That
+is, you can count on being able to have that many supplementary group
+IDs, but a particular machine might let you have even more.  You can use
+@code{sysconf} to see whether a particular machine will let you have
+more (@pxref{Sysconf}).
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro ssize_t SSIZE_MAX
+The largest value that can fit in an object of type @code{ssize_t}.
+Effectively, this is the limit on the number of bytes that can be read
+or written in a single operation.
+
+This macro is defined in all POSIX systems because this limit is never
+configurable.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int RE_DUP_MAX
+The largest number of repetitions you are guaranteed is allowed in the
+construct @samp{\@{@var{min},@var{max}\@}} in a regular expression.
+
+The value of this macro is actually a lower bound for the maximum.  That
+is, you can count on being able to have that many repetitions, but a
+particular machine might let you have even more.  You can use
+@code{sysconf} to see whether a particular machine will let you have
+more (@pxref{Sysconf}).  And even the value that @code{sysconf} tells
+you is just a lower bound---larger values might work.
+
+This macro is defined in all POSIX.2 systems, because POSIX.2 says it
+should always be defined even if there is no specific imposed limit.
+@end deftypevr
+
+@node System Options
+@section Overall System Options
+@cindex POSIX optional features
+@cindex optional POSIX features
+
+POSIX defines certain system-specific options that not all POSIX systems
+support.  Since these options are provided in the kernel, not in the
+library, simply using @theglibc{} does not guarantee any of these
+features is supported; it depends on the system you are using.
+
+@pindex unistd.h
+You can test for the availability of a given option using the macros in
+this section, together with the function @code{sysconf}.  The macros are
+defined only if you include @file{unistd.h}.
+
+For the following macros, if the macro is defined in @file{unistd.h},
+then the option is supported.  Otherwise, the option may or may not be
+supported; use @code{sysconf} to find out.  @xref{Sysconf}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int _POSIX_JOB_CONTROL
+If this symbol is defined, it indicates that the system supports job
+control.  Otherwise, the implementation behaves as if all processes
+within a session belong to a single process group.  @xref{Job Control}.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int _POSIX_SAVED_IDS
+If this symbol is defined, it indicates that the system remembers the
+effective user and group IDs of a process before it executes an
+executable file with the set-user-ID or set-group-ID bits set, and that
+explicitly changing the effective user or group IDs back to these values
+is permitted.  If this option is not defined, then if a nonprivileged
+process changes its effective user or group ID to the real user or group
+ID of the process, it can't change it back again.  @xref{Enable/Disable
+Setuid}.
+@end deftypevr
+
+For the following macros, if the macro is defined in @file{unistd.h},
+then its value indicates whether the option is supported.  A value of
+@code{-1} means no, and any other value means yes.  If the macro is not
+defined, then the option may or may not be supported; use @code{sysconf}
+to find out.  @xref{Sysconf}.
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro int _POSIX2_C_DEV
+If this symbol is defined, it indicates that the system has the POSIX.2
+C compiler command, @code{c89}.  @Theglibc{} always defines this
+as @code{1}, on the assumption that you would not have installed it if
+you didn't have a C compiler.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro int _POSIX2_FORT_DEV
+If this symbol is defined, it indicates that the system has the POSIX.2
+Fortran compiler command, @code{fort77}.  @Theglibc{} never
+defines this, because we don't know what the system has.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro int _POSIX2_FORT_RUN
+If this symbol is defined, it indicates that the system has the POSIX.2
+@code{asa} command to interpret Fortran carriage control.  @Theglibc{}
+never defines this, because we don't know what the system has.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro int _POSIX2_LOCALEDEF
+If this symbol is defined, it indicates that the system has the POSIX.2
+@code{localedef} command.  @Theglibc{} never defines this, because
+we don't know what the system has.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro int _POSIX2_SW_DEV
+If this symbol is defined, it indicates that the system has the POSIX.2
+commands @code{ar}, @code{make}, and @code{strip}.  @Theglibc{}
+always defines this as @code{1}, on the assumption that you had to have
+@code{ar} and @code{make} to install the library, and it's unlikely that
+@code{strip} would be absent when those are present.
+@end deftypevr
+
+@node Version Supported
+@section Which Version of POSIX is Supported
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro {long int} _POSIX_VERSION
+This constant represents the version of the POSIX.1 standard to which
+the implementation conforms.  For an implementation conforming to the
+1995 POSIX.1 standard, the value is the integer @code{199506L}.
+
+@code{_POSIX_VERSION} is always defined (in @file{unistd.h}) in any
+POSIX system.
+
+@strong{Usage Note:} Don't try to test whether the system supports POSIX
+by including @file{unistd.h} and then checking whether
+@code{_POSIX_VERSION} is defined.  On a non-POSIX system, this will
+probably fail because there is no @file{unistd.h}.  We do not know of
+@emph{any} way you can reliably test at compilation time whether your
+target system supports POSIX or whether @file{unistd.h} exists.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevr Macro {long int} _POSIX2_C_VERSION
+This constant represents the version of the POSIX.2 standard which the
+library and system kernel support.  We don't know what value this will
+be for the first version of the POSIX.2 standard, because the value is
+based on the year and month in which the standard is officially adopted.
+
+The value of this symbol says nothing about the utilities installed on
+the system.
+
+@strong{Usage Note:} You can use this macro to tell whether a POSIX.1
+system library supports POSIX.2 as well.  Any POSIX.1 system contains
+@file{unistd.h}, so include that file and then test @code{defined
+(_POSIX2_C_VERSION)}.
+@end deftypevr
+
+@node Sysconf
+@section Using @code{sysconf}
+
+When your system has configurable system limits, you can use the
+@code{sysconf} function to find out the value that applies to any
+particular machine.  The function and the associated @var{parameter}
+constants are declared in the header file @file{unistd.h}.
+
+@menu
+* 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.
+@end menu
+
+@node Sysconf Definition
+@subsection Definition of @code{sysconf}
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {long int} sysconf (int @var{parameter})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c Some parts of the implementation open /proc and /sys files and dirs
+@c to collect system details, using fd and stream I/O depending on the
+@c case.  _SC_TZNAME_MAX calls __tzname_max, that (while holding a lock)
+@c calls tzset_internal, that calls getenv if it's called the first
+@c time; there are free and strdup calls in there too.  The returned max
+@c value may change over time for TZNAME_MAX, depending on selected
+@c timezones; NPROCS, NPROCS_CONF, PHYS_PAGES, AVPHYS_PAGES,
+@c NGROUPS_MAX, SIGQUEUE_MAX, depending on variable values read from
+@c /proc at each call, and from rlimit-obtained values CHILD_MAX,
+@c OPEN_MAX, ARG_MAX, SIGQUEUE_MAX.
+This function is used to inquire about runtime system parameters.  The
+@var{parameter} argument should be one of the @samp{_SC_} symbols listed
+below.
+
+The normal return value from @code{sysconf} is the value you requested.
+A value of @code{-1} is returned both if the implementation does not
+impose a limit, and in case of an error.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The value of the @var{parameter} is invalid.
+@end table
+@end deftypefun
+
+@node Constants for Sysconf
+@subsection Constants for @code{sysconf} Parameters
+
+Here are the symbolic constants for use as the @var{parameter} argument
+to @code{sysconf}.  The values are all integer constants (more
+specifically, enumeration type values).
+
+@vtable @code
+@comment unistd.h
+@comment POSIX.1
+@item _SC_ARG_MAX
+Inquire about the parameter corresponding to @code{ARG_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_CHILD_MAX
+Inquire about the parameter corresponding to @code{CHILD_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_OPEN_MAX
+Inquire about the parameter corresponding to @code{OPEN_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_STREAM_MAX
+Inquire about the parameter corresponding to @code{STREAM_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_TZNAME_MAX
+Inquire about the parameter corresponding to @code{TZNAME_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_NGROUPS_MAX
+Inquire about the parameter corresponding to @code{NGROUPS_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_JOB_CONTROL
+Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SAVED_IDS
+Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_VERSION
+Inquire about the parameter corresponding to @code{_POSIX_VERSION}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_CLK_TCK
+Inquire about the number of clock ticks per second; @pxref{CPU Time}.
+The corresponding parameter @code{CLK_TCK} is obsolete.
+
+@comment unistd.h
+@comment GNU
+@item _SC_CHARCLASS_NAME_MAX
+Inquire about the parameter corresponding to maximal length allowed for
+a character class name in an extended locale specification.  These
+extensions are not yet standardized and so this option is not standardized
+as well.
+
+@comment unistdh.h
+@comment POSIX.1
+@item _SC_REALTIME_SIGNALS
+Inquire about the parameter corresponding to @code{_POSIX_REALTIME_SIGNALS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_PRIORITY_SCHEDULING
+Inquire about the parameter corresponding to @code{_POSIX_PRIORITY_SCHEDULING}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_TIMERS
+Inquire about the parameter corresponding to @code{_POSIX_TIMERS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_ASYNCHRONOUS_IO
+Inquire about the parameter corresponding to @code{_POSIX_ASYNCHRONOUS_IO}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_PRIORITIZED_IO
+Inquire about the parameter corresponding to @code{_POSIX_PRIORITIZED_IO}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SYNCHRONIZED_IO
+Inquire about the parameter corresponding to @code{_POSIX_SYNCHRONIZED_IO}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_FSYNC
+Inquire about the parameter corresponding to @code{_POSIX_FSYNC}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MAPPED_FILES
+Inquire about the parameter corresponding to @code{_POSIX_MAPPED_FILES}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MEMLOCK
+Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MEMLOCK_RANGE
+Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK_RANGE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MEMORY_PROTECTION
+Inquire about the parameter corresponding to @code{_POSIX_MEMORY_PROTECTION}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MESSAGE_PASSING
+Inquire about the parameter corresponding to @code{_POSIX_MESSAGE_PASSING}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SEMAPHORES
+Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SHARED_MEMORY_OBJECTS
+Inquire about the parameter corresponding to@*
+@code{_POSIX_SHARED_MEMORY_OBJECTS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_AIO_LISTIO_MAX
+Inquire about the parameter corresponding to @code{_POSIX_AIO_LISTIO_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_AIO_MAX
+Inquire about the parameter corresponding to @code{_POSIX_AIO_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_AIO_PRIO_DELTA_MAX
+Inquire the value by which a process can decrease its asynchronous I/O
+priority level from its own scheduling priority.  This corresponds to the
+run-time invariant value @code{AIO_PRIO_DELTA_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_DELAYTIMER_MAX
+Inquire about the parameter corresponding to @code{_POSIX_DELAYTIMER_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MQ_OPEN_MAX
+Inquire about the parameter corresponding to @code{_POSIX_MQ_OPEN_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_MQ_PRIO_MAX
+Inquire about the parameter corresponding to @code{_POSIX_MQ_PRIO_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_RTSIG_MAX
+Inquire about the parameter corresponding to @code{_POSIX_RTSIG_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SEM_NSEMS_MAX
+Inquire about the parameter corresponding to @code{_POSIX_SEM_NSEMS_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SEM_VALUE_MAX
+Inquire about the parameter corresponding to @code{_POSIX_SEM_VALUE_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_SIGQUEUE_MAX
+Inquire about the parameter corresponding to @code{_POSIX_SIGQUEUE_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_TIMER_MAX
+Inquire about the parameter corresponding to @code{_POSIX_TIMER_MAX}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII
+Inquire about the parameter corresponding to @code{_POSIX_PII}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_XTI
+Inquire about the parameter corresponding to @code{_POSIX_PII_XTI}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_SOCKET
+Inquire about the parameter corresponding to @code{_POSIX_PII_SOCKET}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_INTERNET
+Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_OSI
+Inquire about the parameter corresponding to @code{_POSIX_PII_OSI}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_SELECT
+Inquire about the parameter corresponding to @code{_POSIX_SELECT}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_UIO_MAXIOV
+Inquire about the parameter corresponding to @code{_POSIX_UIO_MAXIOV}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_INTERNET_STREAM
+Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_STREAM}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_INTERNET_DGRAM
+Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_DGRAM}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_OSI_COTS
+Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_COTS}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_OSI_CLTS
+Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_CLTS}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_PII_OSI_M
+Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_M}.
+
+@comment unistd.h
+@comment POSIX.1g
+@item _SC_T_IOV_MAX
+Inquire the value of the value associated with the @code{T_IOV_MAX}
+variable.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREADS
+Inquire about the parameter corresponding to @code{_POSIX_THREADS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_SAFE_FUNCTIONS
+Inquire about the parameter corresponding to@*
+@code{_POSIX_THREAD_SAFE_FUNCTIONS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_GETGR_R_SIZE_MAX
+Inquire about the parameter corresponding to @code{_POSIX_GETGR_R_SIZE_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_GETPW_R_SIZE_MAX
+Inquire about the parameter corresponding to @code{_POSIX_GETPW_R_SIZE_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_LOGIN_NAME_MAX
+Inquire about the parameter corresponding to @code{_POSIX_LOGIN_NAME_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_TTY_NAME_MAX
+Inquire about the parameter corresponding to @code{_POSIX_TTY_NAME_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_DESTRUCTOR_ITERATIONS
+Inquire about the parameter corresponding to
+@code{_POSIX_THREAD_DESTRUCTOR_ITERATIONS}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_KEYS_MAX
+Inquire about the parameter corresponding to @code{_POSIX_THREAD_KEYS_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_STACK_MIN
+Inquire about the parameter corresponding to @code{_POSIX_THREAD_STACK_MIN}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_THREADS_MAX
+Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_ATTR_STACKADDR
+Inquire about the parameter corresponding to@*a
+@code{_POSIX_THREAD_ATTR_STACKADDR}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_ATTR_STACKSIZE
+Inquire about the parameter corresponding to@*
+@code{_POSIX_THREAD_ATTR_STACKSIZE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_PRIORITY_SCHEDULING
+Inquire about the parameter corresponding to
+@code{_POSIX_THREAD_PRIORITY_SCHEDULING}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_PRIO_INHERIT
+Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_INHERIT}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_PRIO_PROTECT
+Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_PROTECT}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _SC_THREAD_PROCESS_SHARED
+Inquire about the parameter corresponding to
+@code{_POSIX_THREAD_PROCESS_SHARED}.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_C_DEV
+Inquire about whether the system has the POSIX.2 C compiler command,
+@code{c89}.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_FORT_DEV
+Inquire about whether the system has the POSIX.2 Fortran compiler
+command, @code{fort77}.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_FORT_RUN
+Inquire about whether the system has the POSIX.2 @code{asa} command to
+interpret Fortran carriage control.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_LOCALEDEF
+Inquire about whether the system has the POSIX.2 @code{localedef}
+command.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_SW_DEV
+Inquire about whether the system has the POSIX.2 commands @code{ar},
+@code{make}, and @code{strip}.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_BC_BASE_MAX
+Inquire about the maximum value of @code{obase} in the @code{bc}
+utility.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_BC_DIM_MAX
+Inquire about the maximum size of an array in the @code{bc}
+utility.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_BC_SCALE_MAX
+Inquire about the maximum value of @code{scale} in the @code{bc}
+utility.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_BC_STRING_MAX
+Inquire about the maximum size of a string constant in the
+@code{bc} utility.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_COLL_WEIGHTS_MAX
+Inquire about the maximum number of weights that can necessarily
+be used in defining the collating sequence for a locale.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_EXPR_NEST_MAX
+Inquire about the maximum number of expressions nested within
+parentheses when using the @code{expr} utility.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_LINE_MAX
+Inquire about the maximum size of a text line that the POSIX.2 text
+utilities can handle.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_EQUIV_CLASS_MAX
+Inquire about the maximum number of weights that can be assigned to an
+entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale
+definition.  @Theglibc{} does not presently support locale
+definitions.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_VERSION
+Inquire about the version number of POSIX.1 that the library and kernel
+support.
+
+@comment unistd.h
+@comment POSIX.2
+@item _SC_2_VERSION
+Inquire about the version number of POSIX.2 that the system utilities
+support.
+
+@comment unistd.h
+@comment GNU
+@item _SC_PAGESIZE
+Inquire about the virtual memory page size of the machine.
+@code{getpagesize} returns the same value (@pxref{Query Memory Parameters}).
+
+@comment unistd.h
+@comment GNU
+@item _SC_NPROCESSORS_CONF
+Inquire about the number of configured processors.
+
+@comment unistd.h
+@comment GNU
+@item _SC_NPROCESSORS_ONLN
+Inquire about the number of processors online.
+
+@comment unistd.h
+@comment GNU
+@item _SC_PHYS_PAGES
+Inquire about the number of physical pages in the system.
+
+@comment unistd.h
+@comment GNU
+@item _SC_AVPHYS_PAGES
+Inquire about the number of available physical pages in the system.
+
+@comment unistd.h
+@comment GNU
+@item _SC_ATEXIT_MAX
+Inquire about the number of functions which can be registered as termination
+functions for @code{atexit}; @pxref{Cleanups on Exit}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_VERSION
+Inquire about the parameter corresponding to @code{_XOPEN_VERSION}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_XCU_VERSION
+Inquire about the parameter corresponding to @code{_XOPEN_XCU_VERSION}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_UNIX
+Inquire about the parameter corresponding to @code{_XOPEN_UNIX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_REALTIME
+Inquire about the parameter corresponding to @code{_XOPEN_REALTIME}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_REALTIME_THREADS
+Inquire about the parameter corresponding to @code{_XOPEN_REALTIME_THREADS}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_LEGACY
+Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_CRYPT
+Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_ENH_I18N
+Inquire about the parameter corresponding to @code{_XOPEN_ENH_I18N}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_SHM
+Inquire about the parameter corresponding to @code{_XOPEN_SHM}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_XPG2
+Inquire about the parameter corresponding to @code{_XOPEN_XPG2}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_XPG3
+Inquire about the parameter corresponding to @code{_XOPEN_XPG3}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_XOPEN_XPG4
+Inquire about the parameter corresponding to @code{_XOPEN_XPG4}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_CHAR_BIT
+Inquire about the number of bits in a variable of type @code{char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_CHAR_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_CHAR_MIN
+Inquire about the minimum value which can be stored in a variable of type
+@code{char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_INT_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_INT_MIN
+Inquire about the minimum value which can be stored in a variable of type
+@code{int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_LONG_BIT
+Inquire about the number of bits in a variable of type @code{long int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_WORD_BIT
+Inquire about the number of bits in a variable of a register word.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_MB_LEN_MAX
+Inquire the maximum length of a multi-byte representation of a wide
+character value.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NZERO
+Inquire about the value used to internally represent the zero priority level for
+the process execution.
+
+@comment unistd.h
+@comment X/Open
+@item SC_SSIZE_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{ssize_t}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_SCHAR_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{signed char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_SCHAR_MIN
+Inquire about the minimum value which can be stored in a variable of type
+@code{signed char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_SHRT_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{short int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_SHRT_MIN
+Inquire about the minimum value which can be stored in a variable of type
+@code{short int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_UCHAR_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{unsigned char}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_UINT_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{unsigned int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_ULONG_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{unsigned long int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_USHRT_MAX
+Inquire about the maximum value which can be stored in a variable of type
+@code{unsigned short int}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_ARGMAX
+Inquire about the parameter corresponding to @code{NL_ARGMAX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_LANGMAX
+Inquire about the parameter corresponding to @code{NL_LANGMAX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_MSGMAX
+Inquire about the parameter corresponding to @code{NL_MSGMAX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_NMAX
+Inquire about  the parameter corresponding to @code{NL_NMAX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_SETMAX
+Inquire about the parameter corresponding to @code{NL_SETMAX}.
+
+@comment unistd.h
+@comment X/Open
+@item _SC_NL_TEXTMAX
+Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
+@end vtable
+
+@node Examples of Sysconf
+@subsection Examples of @code{sysconf}
+
+We recommend that you first test for a macro definition for the
+parameter you are interested in, and call @code{sysconf} only if the
+macro is not defined.  For example, here is how to test whether job
+control is supported:
+
+@smallexample
+@group
+int
+have_job_control (void)
+@{
+#ifdef _POSIX_JOB_CONTROL
+  return 1;
+#else
+  int value = sysconf (_SC_JOB_CONTROL);
+  if (value < 0)
+    /* @r{If the system is that badly wedged,}
+       @r{there's no use trying to go on.}  */
+    fatal (strerror (errno));
+  return value;
+#endif
+@}
+@end group
+@end smallexample
+
+Here is how to get the value of a numeric limit:
+
+@smallexample
+int
+get_child_max ()
+@{
+#ifdef CHILD_MAX
+  return CHILD_MAX;
+#else
+  int value = sysconf (_SC_CHILD_MAX);
+  if (value < 0)
+    fatal (strerror (errno));
+  return value;
+#endif
+@}
+@end smallexample
+
+@node Minimums
+@section Minimum Values for General Capacity Limits
+
+Here are the names for the POSIX minimum upper bounds for the system
+limit parameters.  The significance of these values is that you can
+safely push to these limits without checking whether the particular
+system you are using can go that far.
+
+@table @code
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_AIO_LISTIO_MAX
+The most restrictive limit permitted by POSIX for the maximum number of
+I/O operations that can be specified in a list I/O call.  The value of
+this constant is @code{2}; thus you can add up to two new entries
+of the list of outstanding operations.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_AIO_MAX
+The most restrictive limit permitted by POSIX for the maximum number of
+outstanding asynchronous I/O operations.  The value of this constant is
+@code{1}.  So you cannot expect that you can issue more than one
+operation and immediately continue with the normal work, receiving the
+notifications asynchronously.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_ARG_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum combined length of the @var{argv} and @var{environ}
+arguments that can be passed to the @code{exec} functions.
+Its value is @code{4096}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_CHILD_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum number of simultaneous processes per real user ID.  Its
+value is @code{6}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_NGROUPS_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum number of supplementary group IDs per process.  Its
+value is @code{0}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_OPEN_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum number of files that a single process can have open
+simultaneously.  Its value is @code{16}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_SSIZE_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum value that can be stored in an object of type
+@code{ssize_t}.  Its value is @code{32767}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_STREAM_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum number of streams that a single process can have open
+simultaneously.  Its value is @code{8}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_TZNAME_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the maximum length of a time zone name.  Its value is @code{3}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_RE_DUP_MAX
+The value of this macro is the most restrictive limit permitted by POSIX
+for the numbers used in the @samp{\@{@var{min},@var{max}\@}} construct
+in a regular expression.  Its value is @code{255}.
+@end table
+
+@node Limits for Files
+@section Limits on File System Capacity
+
+The POSIX.1 standard specifies a number of parameters that describe the
+limitations of the file system.  It's possible for the system to have a
+fixed, uniform limit for a parameter, but this isn't the usual case.  On
+most systems, it's possible for different file systems (and, for some
+parameters, even different files) to have different maximum limits.  For
+example, this is very likely if you use NFS to mount some of the file
+systems from other machines.
+
+@pindex limits.h
+Each of the following macros is defined in @file{limits.h} only if the
+system has a fixed, uniform limit for the parameter in question.  If the
+system allows different file systems or files to have different limits,
+then the macro is undefined; use @code{pathconf} or @code{fpathconf} to
+find out the limit that applies to a particular file.  @xref{Pathconf}.
+
+Each parameter also has another macro, with a name starting with
+@samp{_POSIX}, which gives the lowest value that the limit is allowed to
+have on @emph{any} POSIX system.  @xref{File Minimums}.
+
+@cindex limits, link count of files
+@comment limits.h (optional)
+@comment POSIX.1
+@deftypevr Macro int LINK_MAX
+The uniform system limit (if any) for the number of names for a given
+file.  @xref{Hard Links}.
+@end deftypevr
+
+@cindex limits, terminal input queue
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int MAX_CANON
+The uniform system limit (if any) for the amount of text in a line of
+input when input editing is enabled.  @xref{Canonical or Not}.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int MAX_INPUT
+The uniform system limit (if any) for the total number of characters
+typed ahead as input.  @xref{I/O Queues}.
+@end deftypevr
+
+@cindex limits, file name length
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int NAME_MAX
+The uniform system limit (if any) for the length of a file name component, not
+including the terminating null character.
+
+@strong{Portability Note:} On some systems, @theglibc{} defines
+@code{NAME_MAX}, but does not actually enforce this limit.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int PATH_MAX
+The uniform system limit (if any) for the length of an entire file name (that
+is, the argument given to system calls such as @code{open}), including the
+terminating null character.
+
+@strong{Portability Note:} @Theglibc{} does not enforce this limit
+even if @code{PATH_MAX} is defined.
+@end deftypevr
+
+@cindex limits, pipe buffer size
+@comment limits.h
+@comment POSIX.1
+@deftypevr Macro int PIPE_BUF
+The uniform system limit (if any) for the number of bytes that can be
+written atomically to a pipe.  If multiple processes are writing to the
+same pipe simultaneously, output from different processes might be
+interleaved in chunks of this size.  @xref{Pipes and FIFOs}.
+@end deftypevr
+
+These are alternative macro names for some of the same information.
+
+@comment dirent.h
+@comment BSD
+@deftypevr Macro int MAXNAMLEN
+This is the BSD name for @code{NAME_MAX}.  It is defined in
+@file{dirent.h}.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int FILENAME_MAX
+The value of this macro is an integer constant expression that
+represents the maximum length of a file name string.  It is defined in
+@file{stdio.h}.
+
+Unlike @code{PATH_MAX}, this macro is defined even if there is no actual
+limit imposed.  In such a case, its value is typically a very large
+number.  @strong{This is always the case on @gnuhurdsystems{}.}
+
+@strong{Usage Note:} Don't use @code{FILENAME_MAX} as the size of an
+array in which to store a file name!  You can't possibly make an array
+that big!  Use dynamic allocation (@pxref{Memory Allocation}) instead.
+@end deftypevr
+
+@node Options for Files
+@section Optional Features in File Support
+
+POSIX defines certain system-specific options in the system calls for
+operating on files.  Some systems support these options and others do
+not.  Since these options are provided in the kernel, not in the
+library, simply using @theglibc{} does not guarantee that any of these
+features is supported; it depends on the system you are using.  They can
+also vary between file systems on a single machine.
+
+@pindex unistd.h
+This section describes the macros you can test to determine whether a
+particular option is supported on your machine.  If a given macro is
+defined in @file{unistd.h}, then its value says whether the
+corresponding feature is supported.  (A value of @code{-1} indicates no;
+any other value indicates yes.)  If the macro is undefined, it means
+particular files may or may not support the feature.
+
+Since all the machines that support @theglibc{} also support NFS,
+one can never make a general statement about whether all file systems
+support the @code{_POSIX_CHOWN_RESTRICTED} and @code{_POSIX_NO_TRUNC}
+features.  So these names are never defined as macros in @theglibc{}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int _POSIX_CHOWN_RESTRICTED
+If this option is in effect, the @code{chown} function is restricted so
+that the only changes permitted to nonprivileged processes is to change
+the group owner of a file to either be the effective group ID of the
+process, or one of its supplementary group IDs.  @xref{File Owner}.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int _POSIX_NO_TRUNC
+If this option is in effect, file name components longer than
+@code{NAME_MAX} generate an @code{ENAMETOOLONG} error.  Otherwise, file
+name components that are too long are silently truncated.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro {unsigned char} _POSIX_VDISABLE
+This option is only meaningful for files that are terminal devices.
+If it is enabled, then handling for special control characters can
+be disabled individually.  @xref{Special Characters}.
+@end deftypevr
+
+@pindex unistd.h
+If one of these macros is undefined, that means that the option might be
+in effect for some files and not for others.  To inquire about a
+particular file, call @code{pathconf} or @code{fpathconf}.
+@xref{Pathconf}.
+
+@node File Minimums
+@section Minimum Values for File System Limits
+
+Here are the names for the POSIX minimum upper bounds for some of the
+above parameters.  The significance of these values is that you can
+safely push to these limits without checking whether the particular
+system you are using can go that far.  In most cases @gnusystems{} do not
+have these strict limitations.  The actual limit should be requested if
+necessary.
+
+@table @code
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_LINK_MAX
+The most restrictive limit permitted by POSIX for the maximum value of a
+file's link count.  The value of this constant is @code{8}; thus, you
+can always make up to eight names for a file without running into a
+system limit.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_MAX_CANON
+The most restrictive limit permitted by POSIX for the maximum number of
+bytes in a canonical input line from a terminal device.  The value of
+this constant is @code{255}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_MAX_INPUT
+The most restrictive limit permitted by POSIX for the maximum number of
+bytes in a terminal device input queue (or typeahead buffer).
+@xref{Input Modes}.  The value of this constant is @code{255}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_NAME_MAX
+The most restrictive limit permitted by POSIX for the maximum number of
+bytes in a file name component.  The value of this constant is
+@code{14}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_PATH_MAX
+The most restrictive limit permitted by POSIX for the maximum number of
+bytes in a file name.  The value of this constant is @code{256}.
+
+@comment limits.h
+@comment POSIX.1
+@item _POSIX_PIPE_BUF
+The most restrictive limit permitted by POSIX for the maximum number of
+bytes that can be written atomically to a pipe.  The value of this
+constant is @code{512}.
+
+@comment limits.h
+@comment POSIX.1
+@item SYMLINK_MAX
+Maximum number of bytes in a symbolic link.
+
+@comment limits.h
+@comment POSIX.1
+@item POSIX_REC_INCR_XFER_SIZE
+Recommended increment for file transfer sizes between the
+@code{POSIX_REC_MIN_XFER_SIZE} and @code{POSIX_REC_MAX_XFER_SIZE}
+values.
+
+@comment limits.h
+@comment POSIX.1
+@item POSIX_REC_MAX_XFER_SIZE
+Maximum recommended file transfer size.
+
+@comment limits.h
+@comment POSIX.1
+@item POSIX_REC_MIN_XFER_SIZE
+Minimum recommended file transfer size.
+
+@comment limits.h
+@comment POSIX.1
+@item POSIX_REC_XFER_ALIGN
+Recommended file transfer buffer alignment.
+@end table
+
+@node Pathconf
+@section Using @code{pathconf}
+
+When your machine allows different files to have different values for a
+file system parameter, you can use the functions in this section to find
+out the value that applies to any particular file.
+
+These functions and the associated constants for the @var{parameter}
+argument are declared in the header file @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c When __statfs_link_max finds an ext* filesystem, it may read
+@c /proc/mounts or similar as a mntent stream.
+@c __statfs_chown_restricted may read from
+@c /proc/sys/fs/xfs/restrict_chown as a file descriptor.
+This function is used to inquire about the limits that apply to
+the file named @var{filename}.
+
+The @var{parameter} argument should be one of the @samp{_PC_} constants
+listed below.
+
+The normal return value from @code{pathconf} is the value you requested.
+A value of @code{-1} is returned both if the implementation does not
+impose a limit, and in case of an error.  In the former case,
+@code{errno} is not set, while in the latter case, @code{errno} is set
+to indicate the cause of the problem.  So the only way to use this
+function robustly is to store @code{0} into @code{errno} just before
+calling it.
+
+Besides the usual file name errors (@pxref{File Name Errors}),
+the following error condition is defined for this function:
+
+@table @code
+@item EINVAL
+The value of @var{parameter} is invalid, or the implementation doesn't
+support the @var{parameter} for the specific file.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Same caveats as pathconf.
+This is just like @code{pathconf} except that an open file descriptor
+is used to specify the file for which information is requested, instead
+of a file name.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The value of @var{parameter} is invalid, or the implementation doesn't
+support the @var{parameter} for the specific file.
+@end table
+@end deftypefun
+
+Here are the symbolic constants that you can use as the @var{parameter}
+argument to @code{pathconf} and @code{fpathconf}.  The values are all
+integer constants.
+
+@table @code
+@comment unistd.h
+@comment POSIX.1
+@item _PC_LINK_MAX
+Inquire about the value of @code{LINK_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_MAX_CANON
+Inquire about the value of @code{MAX_CANON}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_MAX_INPUT
+Inquire about the value of @code{MAX_INPUT}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_NAME_MAX
+Inquire about the value of @code{NAME_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_PATH_MAX
+Inquire about the value of @code{PATH_MAX}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_PIPE_BUF
+Inquire about the value of @code{PIPE_BUF}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_CHOWN_RESTRICTED
+Inquire about the value of @code{_POSIX_CHOWN_RESTRICTED}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_NO_TRUNC
+Inquire about the value of @code{_POSIX_NO_TRUNC}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_VDISABLE
+Inquire about the value of @code{_POSIX_VDISABLE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_SYNC_IO
+Inquire about the value of @code{_POSIX_SYNC_IO}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_ASYNC_IO
+Inquire about the value of @code{_POSIX_ASYNC_IO}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_PRIO_IO
+Inquire about the value of @code{_POSIX_PRIO_IO}.
+
+@comment unistd.h
+@comment LFS
+@item _PC_FILESIZEBITS
+Inquire about the availability of large files on the filesystem.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_REC_INCR_XFER_SIZE
+Inquire about the value of @code{POSIX_REC_INCR_XFER_SIZE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_REC_MAX_XFER_SIZE
+Inquire about the value of @code{POSIX_REC_MAX_XFER_SIZE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_REC_MIN_XFER_SIZE
+Inquire about the value of @code{POSIX_REC_MIN_XFER_SIZE}.
+
+@comment unistd.h
+@comment POSIX.1
+@item _PC_REC_XFER_ALIGN
+Inquire about the value of @code{POSIX_REC_XFER_ALIGN}.
+@end table
+
+@strong{Portability Note:} On some systems, @theglibc{} does not
+enforce @code{_PC_NAME_MAX} or @code{_PC_PATH_MAX} limits.
+
+@node Utility Limits
+@section Utility Program Capacity Limits
+
+The POSIX.2 standard specifies certain system limits that you can access
+through @code{sysconf} that apply to utility behavior rather than the
+behavior of the library or the operating system.
+
+@Theglibc{} defines macros for these limits, and @code{sysconf}
+returns values for them if you ask; but these values convey no
+meaningful information.  They are simply the smallest values that
+POSIX.2 permits.
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int BC_BASE_MAX
+The largest value of @code{obase} that the @code{bc} utility is
+guaranteed to support.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int BC_DIM_MAX
+The largest number of elements in one array that the @code{bc} utility
+is guaranteed to support.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int BC_SCALE_MAX
+The largest value of @code{scale} that the @code{bc} utility is
+guaranteed to support.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int BC_STRING_MAX
+The largest number of characters in one string constant that the
+@code{bc} utility is guaranteed to support.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int COLL_WEIGHTS_MAX
+The largest number of weights that can necessarily be used in defining
+the collating sequence for a locale.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int EXPR_NEST_MAX
+The maximum number of expressions that can be nested within parenthesis
+by the @code{expr} utility.
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int LINE_MAX
+The largest text line that the text-oriented POSIX.2 utilities can
+support.  (If you are using the GNU versions of these utilities, then
+there is no actual limit except that imposed by the available virtual
+memory, but there is no way that the library can tell you this.)
+@end deftypevr
+
+@comment limits.h
+@comment POSIX.2
+@deftypevr Macro int EQUIV_CLASS_MAX
+The maximum number of weights that can be assigned to an entry of the
+@code{LC_COLLATE} category @samp{order} keyword in a locale definition.
+@Theglibc{} does not presently support locale definitions.
+@end deftypevr
+
+@node Utility Minimums
+@section Minimum Values for Utility Limits
+
+@table @code
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_BC_BASE_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum value of
+@code{obase} in the @code{bc} utility.  Its value is @code{99}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_BC_DIM_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum size of
+an array in the @code{bc} utility.  Its value is @code{2048}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_BC_SCALE_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum value of
+@code{scale} in the @code{bc} utility.  Its value is @code{99}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_BC_STRING_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum size of
+a string constant in the @code{bc} utility.  Its value is @code{1000}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_COLL_WEIGHTS_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum number
+of weights that can necessarily be used in defining the collating
+sequence for a locale.  Its value is @code{2}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_EXPR_NEST_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum number
+of expressions nested within parenthesis when using the @code{expr} utility.
+Its value is @code{32}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_LINE_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum size of
+a text line that the text utilities can handle.  Its value is
+@code{2048}.
+
+@comment limits.h
+@comment POSIX.2
+@item _POSIX2_EQUIV_CLASS_MAX
+The most restrictive limit permitted by POSIX.2 for the maximum number
+of weights that can be assigned to an entry of the @code{LC_COLLATE}
+category @samp{order} keyword in a locale definition.  Its value is
+@code{2}.  @Theglibc{} does not presently support locale
+definitions.
+@end table
+
+@node String Parameters
+@section String-Valued Parameters
+
+POSIX.2 defines a way to get string-valued parameters from the operating
+system with the function @code{confstr}:
+
+@comment unistd.h
+@comment POSIX.2
+@deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function reads the value of a string-valued system parameter,
+storing the string into @var{len} bytes of memory space starting at
+@var{buf}.  The @var{parameter} argument should be one of the
+@samp{_CS_} symbols listed below.
+
+The normal return value from @code{confstr} is the length of the string
+value that you asked for.  If you supply a null pointer for @var{buf},
+then @code{confstr} does not try to store the string; it just returns
+its length.  A value of @code{0} indicates an error.
+
+If the string you asked for is too long for the buffer (that is, longer
+than @code{@var{len} - 1}), then @code{confstr} stores just that much
+(leaving room for the terminating null character).  You can tell that
+this has happened because @code{confstr} returns a value greater than or
+equal to @var{len}.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The value of the @var{parameter} is invalid.
+@end table
+@end deftypefun
+
+Currently there is just one parameter you can read with @code{confstr}:
+
+@table @code
+@comment unistd.h
+@comment POSIX.2
+@item _CS_PATH
+This parameter's value is the recommended default path for searching for
+executable files.  This is the path that a user has by default just
+after logging in.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS_CFLAGS
+The returned string specifies which additional flags must be given to
+the C compiler if a source is compiled using the
+@code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS_LDFLAGS
+The returned string specifies which additional flags must be given to
+the linker if a source is compiled using the
+@code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS_LIBS
+The returned string specifies which additional libraries must be linked
+to the application if a source is compiled using the
+@code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS_LINTFLAGS
+The returned string specifies which additional flags must be given to
+the lint tool if a source is compiled using the
+@code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS64_CFLAGS
+The returned string specifies which additional flags must be given to
+the C compiler if a source is compiled using the
+@code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS64_LDFLAGS
+The returned string specifies which additional flags must be given to
+the linker if a source is compiled using the
+@code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS64_LIBS
+The returned string specifies which additional libraries must be linked
+to the application if a source is compiled using the
+@code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+
+@comment unistd.h
+@comment Unix98
+@item _CS_LFS64_LINTFLAGS
+The returned string specifies which additional flags must be given to
+the lint tool if a source is compiled using the
+@code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
+@end table
+
+The way to use @code{confstr} without any arbitrary limit on string size
+is to call it twice: first call it to get the length, allocate the
+buffer accordingly, and then call @code{confstr} again to fill the
+buffer, like this:
+
+@smallexample
+@group
+char *
+get_default_path (void)
+@{
+  size_t len = confstr (_CS_PATH, NULL, 0);
+  char *buffer = (char *) xmalloc (len);
+
+  if (confstr (_CS_PATH, buf, len + 1) == 0)
+    @{
+      free (buffer);
+      return NULL;
+    @}
+
+  return buffer;
+@}
+@end group
+@end smallexample
diff --git a/ap/libc/glibc/glibc-2.23/manual/contrib.texi b/ap/libc/glibc/glibc-2.23/manual/contrib.texi
new file mode 100644
index 0000000..930d614
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/contrib.texi
@@ -0,0 +1,411 @@
+@node Contributors, Free Manuals, Platform, Top
+@c %MENU% Who wrote what parts of the GNU C Library
+@appendix Contributors to @theglibc{}
+
+@Theglibc{} project would like to thank its many contributors.
+Without them the project would not have been nearly as successful as
+it has been.  Any omissions in this list are accidental.  Feel free to
+file a bug in bugzilla if you have been left out or some of your
+contributions are not listed.  Please keep this list in alphabetical
+order.
+
+@itemize @bullet
+
+@item
+Ryan S. Arnold for his improvements for Linux on PowerPC and his direction
+as FSF Project Steward for @theglibc{}.
+
+@item
+Miles Bader for writing the @code{argp} argument-parsing package, and the
+@code{argz}/@code{envz} interfaces.
+
+@item
+Jeff Bailey for his maintainership of the HPPA architecture.
+
+@item
+Petr Baudis for bug fixes and testing.
+
+@item
+Stephen R. van den Berg for contributing a highly-optimized
+@code{strstr} function.
+
+@item
+Ondrej Bilka for contributing optimized string routines for x64 and various
+fixes.
+
+@item
+Eric Blake for adding O(n) implementations of @code{memmem},
+@code{strstr} and @code{strcasestr}.
+
+@item
+Philip Blundell for the ports to Linux/ARM
+(@code{arm-@var{ANYTHING}-linuxaout}) and ARM standalone
+(@code{arm-@var{ANYTHING}-none}), as well as for parts of the IPv6
+support code.
+
+@item
+Per Bothner for the implementation of the @code{libio} library which
+is used to implement @code{stdio} functions.
+
+@item
+Mark Brown for his direction as part of @theglibc{} steering
+committee.
+
+@item
+Thomas Bushnell for his contributions to Hurd.
+
+@item
+Wilco Dijkstra for various fixes.
+
+@item
+Liubov Dmitrieva for optimzed string and math functions on x86-64 and
+x86.
+
+@item
+Ulrich Drepper for his many contributions in almost all parts of
+@theglibc{}, including:
+@itemize @bullet
+@item internationalization support, including the @code{locale} and
+@code{localedef} utilities.
+@item Linux i386/ELF support
+@item the @code{hsearch} and @code{drand48} families of functions,
+reentrant @samp{@dots{}@code{_r}} versions of the @code{random}
+family; System V shared memory and IPC support code
+@item several highly-optimized string functions for i@var{x}86
+processors
+@item many math functions
+@item the character conversion functions (@code{iconv})
+@item the @code{ftw} and @code{nftw} functions
+@item the floating-point printing function used by @code{printf} and friends
+and the floating-point reading function used by @code{scanf},
+@code{strtod} and friends
+@item the @code{catgets} support and the entire suite of multi-byte
+and wide-character support functions (@file{wctype.h}, @file{wchar.h}, etc.).
+@item versioning of objects on the symbol level
+@end itemize
+
+@item
+Richard Earnshaw for continued support and fixes to the various ARM
+machine files.
+
+@item
+Paul Eggert for the @code{mktime} function and for his direction as
+part of @theglibc{} steering committee.
+
+@item
+Steve Ellcey for various fixes.
+
+@item
+Tulio Magno Quites Machado Filho for adding a new class of installed
+headers for low-level platform-specific functionality and one such for
+PowerPC.
+
+@item
+Mike Frysinger for his maintaining of the IA64 architecture and for
+testing and bug fixing.
+
+@item
+Michael Glad for the DES encryption function @code{crypt} and related
+functions.
+
+@item
+Wolfram Gloger for contributing the memory allocation functions
+functions @code{malloc}, @code{realloc} and @code{free} and related
+code.
+
+@item
+Torbj@"orn Granlund for fast implementations of many of the string
+functions (@code{memcpy}, @code{strlen}, etc.).
+
+@item
+Michael J. Haertel for writing the merge sort function @code{qsort}
+and malloc checking functions like @code{mcheck}.
+
+@item
+Bruno Haible for his improvements to the @code{iconv} and locale
+implementations.
+
+@item
+Richard Henderson for the port to Linux on Alpha
+(@code{alpha-@var{anything}-linux}).
+
+@item
+David Holsgrove for the port to Linux on MicroBlaze.
+
+@item
+Daniel Jacobowitz for various fixes and enhancements.
+
+@item
+Andreas Jaeger for the port to Linux on x86-64
+(@code{x86_64-@var{anything}-linux} and his work on Linux for MIPS
+(@code{mips-@var{anything}-linux}), implementing the @file{ldconfig}
+program, providing a test suite for the math library and for his
+direction as part of @theglibc{} steering committee.
+
+@item
+Aurelien Jarno for various fixes.
+
+@item
+Jakub Jelinek for implementing a number of checking functions and for
+his direction as part of @theglibc{} steering committee.
+
+@item
+Geoffrey Keating for the port to Linux on PowerPC
+(@code{powerpc-@var{anything}-linux}).
+
+@item
+Brendan Kehoe for contributing the port to the MIPS DECStation running
+Ultrix 4 (@code{mips-dec-ultrix4}) and the port to the DEC Alpha
+running OSF/1 (@code{alpha-dec-osf1}).
+
+@item
+Mark Kettenis for implementing the @code{utmpx} interface and an utmp
+daemon, and for a Hesiod NSS module.
+
+@item
+Andi Kleen for implementing pthreads lock elision with TSX.
+
+@item
+Kazumoto Kojima for the port of the Mach and Hurd code to the MIPS
+architecture (@code{mips-@var{anything}-gnu}) and for his work on the
+SH architecture.
+
+@item
+Andreas Krebbel for his work on Linux for s390 and s390x.
+
+@item
+Thorsten Kukuk for providing an implementation for NIS (YP) and NIS+,
+securelevel 0, 1 and 2 and for the implementation for a caching daemon
+for NSS (@file{nscd}).
+
+@item
+Jeff Law for various fixes.
+
+@item
+Doug Lea for contributing the memory allocation functions
+functions @code{malloc}, @code{realloc} and @code{free} and related
+code.
+
+@item
+Chris Leonard for various fixes and enhancements to localedata.
+
+@item
+Stefan Liebler for various fixes.
+
+@item
+Hongjiu Lu for providing the support for a Linux 32-bit runtime
+environment under x86-64 (x32), for porting to Linux on IA64, for
+improved string functions, a framework for testing IFUNC
+implementations, and many bug fixes.
+
+@item
+Luis Machado for optimized functions on PowerPC.
+
+@item
+David J. MacKenzie for his contribution to the @code{getopt}
+function and writing the @file{tar.h} header.
+
+@item
+Greg McGary for adding runtime support for bounds checking.
+
+@item
+Roland McGrath for writing most of @theglibc{} originally, for his
+work on the Hurd port, his direction as part of @theglibc{} steering
+committee and as FSF Project Steward for @theglibc{}, and for many bug
+fixes and reviewing of contributions.
+
+@item
+Allan McRae for various fixes.
+
+@item
+Jason Merrill for the port to the Sequent Symmetry running Dynix
+version 3 (@code{i386-sequent-bsd}).
+
+@item
+Chris Metcalf for the port to Linux/Tile
+(@code{tilegx-@var{anything}-linux} and
+@code{tilepro-@var{anything}-linux}).
+
+@item
+David Miller for contributing the port to Linux/Sparc
+(@code{sparc*-@var{anything}-linux}).
+
+@item
+Alan Modra for his improvements for Linux on PowerPC.
+
+@item
+David Mosberger-Tang for contributing the port to Linux/Alpha
+(@code{alpha-@var{anything}-linux}).
+
+@item
+Stephen Moshier for implementing some 128-bit long double format math
+functions.
+
+@item
+Stephen Munroe for his port to Linux on PowerPC64
+(@code{powerpc64-@var{anything}-linux}) and for adding optimized
+implementations for PowerPC.
+
+@item
+Joseph S. Myers for numerous bug fixes for the libm functions, for
+his maintainership of the ARM and MIPS architectures, improving
+cross-compilation and cross-testing of @theglibc{}, expanded
+coverage of conformtest, merging the ports/ subdirectory
+into the @glibcadj{} main repository and his direction as FSF Project
+Steward for @theglibc{}.
+
+@item
+Will Newton for contributing some optimized string functions and pointer
+encryption support for ARM and various fixes.
+
+@item
+Carlos O'Donell for his maintainership of the HPPA architecture, for
+maintaining @theglibc{} web pages and wiki, for his direction as FSF
+Project Steward for @theglibc{} and various bug fixes.
+
+@item
+Alexandre Oliva for adding TLS descriptors for LD and GD on x86 and
+x86-64, for the am33 port, for completing the MIPS n64/n32/o32 multilib
+port, for thread-safety, async-signal safety and async-cancellation
+safety documentation in the manual, for his direction as FSF Project
+Maintainer and for various fixes.
+
+@item
+Paul Pluzhnikov for various fixes.
+
+@item
+Marek Polacek for various fixes.
+
+@item
+Siddhesh Poyarekar for various fixes and an implementation of a
+framework for performance benchmarking of functions.
+
+@item
+Tom Quinn for contributing the startup code to support SunOS shared
+libraries and the port to SGI machines running Irix 4
+(@code{mips-sgi-irix4}).
+
+@item
+Torvald Riegel for the implementation of a new semaphore algorithm.
+
+@item
+Pravin Satpute for writing sorting rules for some Indian languages.
+
+@item
+Douglas C. Schmidt for writing the quick sort function used as a
+fallback by @code{qsort}.
+
+@item
+Will Schmidt for optimized string functions on PowerPC.
+
+@item
+Andreas Schwab for the port to Linux/m68k
+(@code{m68k-@var{anything}-linux}) and for his direction as part of
+@theglibc{} steering committee.
+
+@item
+Martin Schwidefsky for porting to Linux on s390
+(@code{s390-@var{anything}-linux}) and s390x
+(@code{s390x-@var{anything}-linux}).
+
+@item
+Thomas Schwinge for his contribution to Hurd and the SH architecture.
+
+@item
+Carlos Eduardo Seo for optimized functions on PowerPC.
+
+@item
+Marcus Shawcroft for contributing the AArch64 port.
+
+@item
+Franz Sirl for various fixes.
+
+@item
+Jes Sorensen for porting to Linux on IA64 (@code{ia64-@var{anything}-linux}).
+
+@item
+Richard Stallman for his contribution to the @code{getopt} function.
+
+@item
+Alfred M. Szmidt for various fixes.
+
+@item
+Ian Lance Taylor for contributing the port to the MIPS DECStation
+running Ultrix 4 (@code{mips-dec-ultrix4}).
+
+@item
+Samuel Thibault for improving the Hurd port.
+
+@item
+Tim Waugh for the implementation of the POSIX.2 @code{wordexp}
+function family.
+
+@item
+Eric Youngdale for implementing versioning of objects on the symbol level.
+
+@item
+Adhemerval Zanella for optimized functions on PowerPC.
+
+@end itemize
+
+Some code in @theglibc{} comes from other projects and might be under
+a different license:
+
+@itemize @bullet
+@item
+The timezone support code is derived from the public-domain timezone
+package by Arthur David Olson and his many contributors.
+
+@item
+Some of the support code for Mach is taken from Mach 3.0 by CMU;
+the file if_ppp.h is also copyright by CMU, but under a different license;
+see the file @file{LICENSES} for the text of the licenses.
+
+@item
+The random number generation functions @code{random}, @code{srandom},
+@code{setstate} and @code{initstate}, which are also the basis for the
+@code{rand} and @code{srand} functions, were written by Earl T. Cohen
+for the University of California at Berkeley and are copyrighted by the
+Regents of the University of California.  They have undergone minor
+changes to fit into @theglibc{} and to fit the @w{ISO C} standard,
+but the functional code is Berkeley's.@refill
+
+@item
+The Internet-related code (most of the @file{inet} subdirectory) and
+several other miscellaneous functions and header files have been
+included from 4.4 BSD with little or no modification.  The copying
+permission notice for this code can be found in the file @file{LICENSES}
+in the source distribution.
+
+@item
+The @code{getaddrinfo} and @code{getnameinfo} functions and supporting
+code were written by Craig Metz; see the file @file{LICENSES} for
+details on their licensing.
+
+@item
+The DNS resolver code is taken directly from BIND 4.9.5, which
+includes copyrighted code from UC Berkeley and from Digital Equipment
+Corporation.  See the file @file{LICENSES} for the text of the DEC license.
+
+@item
+The code to support Sun RPC is taken verbatim from Sun's
+@w{@sc{rpcsrc-4.0}} distribution; see the file @file{LICENSES} for the
+text of the license.
+
+@item
+The math functions are taken from @code{fdlibm-5.1} by Sun
+Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
+Ulrich Drepper, Andreas Schwab, and Roland McGrath.
+
+@item
+Many of the IEEE 64-bit double precision math functions
+(in the @file{sysdeps/ieee754/dbl-64} subdirectory) come
+from the IBM Accurate Mathematical Library, contributed by IBM.
+
+@item
+Many of the IA64 math functions are taken from a collection of
+``Highly Optimized Mathematical Functions for Itanium'' that Intel
+makes available under a free license; see the file @file{LICENSES} for
+details.
+
+@end itemize
diff --git a/ap/libc/glibc/glibc-2.23/manual/creature.texi b/ap/libc/glibc/glibc-2.23/manual/creature.texi
new file mode 100644
index 0000000..3c68616
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/creature.texi
@@ -0,0 +1,218 @@
+@node Feature Test Macros
+@subsection Feature Test Macros
+
+@cindex feature test macros
+The exact set of features available when you compile a source file
+is controlled by which @dfn{feature test macros} you define.
+
+If you compile your programs using @samp{gcc -ansi}, you get only the
+@w{ISO C} library features, unless you explicitly request additional
+features by defining one or more of the feature macros.
+@xref{Invoking GCC,, GNU CC Command Options, gcc.info, The GNU CC Manual},
+for more information about GCC options.@refill
+
+You should define these macros by using @samp{#define} preprocessor
+directives at the top of your source code files.  These directives
+@emph{must} come before any @code{#include} of a system header file.  It
+is best to make them the very first thing in the file, preceded only by
+comments.  You could also use the @samp{-D} option to GCC, but it's
+better if you make the source files indicate their own meaning in a
+self-contained way.
+
+This system exists to allow the library to conform to multiple standards.
+Although the different standards are often described as supersets of each
+other, they are usually incompatible because larger standards require
+functions with names that smaller ones reserve to the user program.  This
+is not mere pedantry --- it has been a problem in practice.  For instance,
+some non-GNU programs define functions named @code{getline} that have
+nothing to do with this library's @code{getline}.  They would not be
+compilable if all features were enabled indiscriminately.
+
+This should not be used to verify that a program conforms to a limited
+standard.  It is insufficient for this purpose, as it will not protect you
+from including header files outside the standard, or relying on semantics
+undefined within the standard.
+
+@comment (none)
+@comment POSIX.1
+@defvr Macro _POSIX_SOURCE
+If you define this macro, then the functionality from the POSIX.1
+standard (IEEE Standard 1003.1) is available, as well as all of the
+@w{ISO C} facilities.
+
+The state of @code{_POSIX_SOURCE} is irrelevant if you define the
+macro @code{_POSIX_C_SOURCE} to a positive integer.
+@end defvr
+
+@comment (none)
+@comment POSIX.2
+@defvr Macro _POSIX_C_SOURCE
+Define this macro to a positive integer to control which POSIX
+functionality is made available.  The greater the value of this macro,
+the more functionality is made available.
+
+If you define this macro to a value greater than or equal to @code{1},
+then the functionality from the 1990 edition of the POSIX.1 standard
+(IEEE Standard 1003.1-1990) is made available.
+
+If you define this macro to a value greater than or equal to @code{2},
+then the functionality from the 1992 edition of the POSIX.2 standard
+(IEEE Standard 1003.2-1992) is made available.
+
+If you define this macro to a value greater than or equal to @code{199309L},
+then the functionality from the 1993 edition of the POSIX.1b standard
+(IEEE Standard 1003.1b-1993) is made available.
+
+Greater values for @code{_POSIX_C_SOURCE} will enable future extensions.
+The POSIX standards process will define these values as necessary, and
+@theglibc{} should support them some time after they become standardized.
+The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that
+if you define @code{_POSIX_C_SOURCE} to a value greater than
+or equal to @code{199506L}, then the functionality from the 1996
+edition is made available.
+@end defvr
+
+@comment (none)
+@comment X/Open
+@defvr Macro _XOPEN_SOURCE
+@comment (none)
+@comment X/Open
+@defvrx Macro _XOPEN_SOURCE_EXTENDED
+If you define this macro, functionality described in the X/Open
+Portability Guide is included.  This is a superset of the POSIX.1 and
+POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and
+@code{_POSIX_C_SOURCE} are automatically defined.
+
+As the unification of all Unices, functionality only available in
+BSD and SVID is also included.
+
+If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more
+functionality is available.  The extra functions will make all functions
+available which are necessary for the X/Open Unix brand.
+
+If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes
+all functionality described so far plus some new definitions from the
+Single Unix Specification, @w{version 2}.
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _LARGEFILE_SOURCE
+If this macro is defined some extra functions are available which
+rectify a few shortcomings in all previous standards.  Specifically,
+the functions @code{fseeko} and @code{ftello} are available.  Without
+these functions the difference between the @w{ISO C} interface
+(@code{fseek}, @code{ftell}) and the low-level POSIX interface
+(@code{lseek}) would lead to problems.
+
+This macro was introduced as part of the Large File Support extension (LFS).
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _LARGEFILE64_SOURCE
+If you define this macro an additional set of functions is made available
+which enables @w{32 bit} systems to use files of sizes beyond
+the usual limit of 2GB.  This interface is not available if the system
+does not support files that large.  On systems where the natural file
+size limit is greater than 2GB (i.e., on @w{64 bit} systems) the new
+functions are identical to the replaced functions.
+
+The new functionality is made available by a new set of types and
+functions which replace the existing ones.  The names of these new objects
+contain @code{64} to indicate the intention, e.g., @code{off_t}
+vs. @code{off64_t} and @code{fseeko} vs. @code{fseeko64}.
+
+This macro was introduced as part of the Large File Support extension
+(LFS).  It is a transition interface for the period when @w{64 bit}
+offsets are not generally used (see @code{_FILE_OFFSET_BITS}).
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _FILE_OFFSET_BITS
+This macro determines which file system interface shall be used, one
+replacing the other.  Whereas @code{_LARGEFILE64_SOURCE} makes the @w{64
+bit} interface available as an additional interface,
+@code{_FILE_OFFSET_BITS} allows the @w{64 bit} interface to
+replace the old interface.
+
+If @code{_FILE_OFFSET_BITS} is undefined, or if it is defined to the
+value @code{32}, nothing changes.  The @w{32 bit} interface is used and
+types like @code{off_t} have a size of @w{32 bits} on @w{32 bit}
+systems.
+
+If the macro is defined to the value @code{64}, the large file interface
+replaces the old interface.  I.e., the functions are not made available
+under different names (as they are with @code{_LARGEFILE64_SOURCE}).
+Instead the old function names now reference the new functions, e.g., a
+call to @code{fseeko} now indeed calls @code{fseeko64}.
+
+This macro should only be selected if the system provides mechanisms for
+handling large files.  On @w{64 bit} systems this macro has no effect
+since the @code{*64} functions are identical to the normal functions.
+
+This macro was introduced as part of the Large File Support extension
+(LFS).
+@end defvr
+
+@comment (none)
+@comment GNU
+@defvr Macro _ISOC99_SOURCE
+Until the revised @w{ISO C} standard is widely adopted the new features
+are not automatically enabled.  @Theglibc{} nevertheless has a complete
+implementation of the new standard and to enable the new features the
+macro @code{_ISOC99_SOURCE} should be defined.
+@end defvr
+
+@comment (none)
+@comment GNU
+@defvr Macro _GNU_SOURCE
+If you define this macro, everything is included: @w{ISO C89}, @w{ISO
+C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions.  In
+the cases where POSIX.1 conflicts with BSD, the POSIX definitions take
+precedence.
+@end defvr
+
+@comment (none)
+@comment GNU
+@defvr Macro _DEFAULT_SOURCE
+If you define this macro, most features are included apart from
+X/Open, LFS and GNU extensions: the effect is to enable features from
+the 2008 edition of POSIX, as well as certain BSD and SVID features
+without a separate feature test macro to control them.  Defining this
+macro, on its own and without using compiler options such as
+@option{-ansi} or @option{-std=c99}, has the same effect as not
+defining any feature test macros; defining it together with other
+feature test macros, or when options such as @option{-ansi} are used,
+enables those features even when the other options would otherwise
+cause them to be disabled.
+@end defvr
+
+@comment (none)
+@comment GNU
+@defvr Macro _REENTRANT
+@defvrx Macro _THREAD_SAFE
+If you define one of these macros, reentrant versions of several functions get
+declared.  Some of the functions are specified in POSIX.1c but many others
+are only available on a few other systems or are unique to @theglibc{}.
+The problem is the delay in the standardization of the thread safe C library
+interface.
+
+Unlike on some other systems, no special version of the C library must be
+used for linking.  There is only one version but while compiling this
+it must have been specified to compile as thread safe.
+@end defvr
+
+We recommend you use @code{_GNU_SOURCE} in new programs.  If you don't
+specify the @samp{-ansi} option to GCC, or other conformance options
+such as @option{-std=c99}, and don't define any of these macros
+explicitly, the effect is the same as defining @code{_DEFAULT_SOURCE}
+to 1.
+
+When you define a feature test macro to request a larger class of features,
+it is harmless to define in addition a feature test macro for a subset of
+those features.  For example, if you define @code{_POSIX_C_SOURCE}, then
+defining @code{_POSIX_SOURCE} as well has no effect.  Likewise, if you
+define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or
+@code{_POSIX_C_SOURCE} as well has no effect.
diff --git a/ap/libc/glibc/glibc-2.23/manual/crypt.texi b/ap/libc/glibc/glibc-2.23/manual/crypt.texi
new file mode 100644
index 0000000..fd007cf
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/crypt.texi
@@ -0,0 +1,430 @@
+@c This node must have no pointers.
+@node Cryptographic Functions
+@c @node Cryptographic Functions, Debugging Support, System Configuration, Top
+@chapter DES Encryption and Password Handling
+@c %MENU% DES encryption and password handling
+
+On many systems, it is unnecessary to have any kind of user
+authentication; for instance, a workstation which is not connected to a
+network probably does not need any user authentication, because to use
+the machine an intruder must have physical access.
+
+Sometimes, however, it is necessary to be sure that a user is authorized
+to use some service a machine provides---for instance, to log in as a
+particular user id (@pxref{Users and Groups}).  One traditional way of
+doing this is for each user to choose a secret @dfn{password}; then, the
+system can ask someone claiming to be a user what the user's password
+is, and if the person gives the correct password then the system can
+grant the appropriate privileges.
+
+If all the passwords are just stored in a file somewhere, then this file
+has to be very carefully protected.  To avoid this, passwords are run
+through a @dfn{one-way function}, a function which makes it difficult to
+work out what its input was by looking at its output, before storing in
+the file.
+
+@Theglibc{} provides a one-way function that is compatible with
+the behavior of the @code{crypt} function introduced in FreeBSD 2.0.
+It supports two one-way algorithms: one based on the MD5
+message-digest algorithm that is compatible with modern BSD systems,
+and the other based on the Data Encryption Standard (DES) that is
+compatible with Unix systems.
+
+@vindex AUTH_DES
+@cindex FIPS 140-2
+It also provides support for Secure RPC, and some library functions that
+can be used to perform normal DES encryption.  The @code{AUTH_DES}
+authentication flavor in Secure RPC, as provided by @theglibc{},
+uses DES and does not comply with FIPS 140-2 nor does any other use of DES
+within @theglibc{}.  It is recommended that Secure RPC should not be used
+for systems that need to comply with FIPS 140-2 since all flavors of
+encrypted authentication use normal DES.
+
+@menu
+* Legal Problems::              This software can get you locked up, or worse.
+* getpass::                     Prompting the user for a password.
+* crypt::                       A one-way function for passwords.
+* DES Encryption::              Routines for DES encryption.
+@end menu
+
+@node Legal Problems
+@section Legal Problems
+
+Because of the continuously changing state of the law, it's not possible
+to provide a definitive survey of the laws affecting cryptography.
+Instead, this section warns you of some of the known trouble spots; this
+may help you when you try to find out what the laws of your country are.
+
+Some countries require that you have a licence to use, possess, or import
+cryptography.  These countries are believed to include Byelorussia,
+Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi
+Arabia.
+
+Some countries restrict the transmission of encrypted messages by radio;
+some telecommunications carriers restrict the transmission of encrypted
+messages over their network.
+
+Many countries have some form of export control for encryption software.
+The Wassenaar Arrangement is a multilateral agreement between 33
+countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada, the
+Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary,
+Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway,
+Poland, Portugal, the Republic of Korea, Romania, the Russian
+Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey,
+Ukraine, the United Kingdom and the United States) which restricts some
+kinds of encryption exports.  Different countries apply the arrangement
+in different ways; some do not allow the exception for certain kinds of
+``public domain'' software (which would include this library), some
+only restrict the export of software in tangible form, and others impose
+significant additional restrictions.
+
+The United States has additional rules.  This software would generally
+be exportable under 15 CFR 740.13(e), which permits exports of
+``encryption source code'' which is ``publicly available'' and which is
+``not subject to an express agreement for the payment of a licensing fee or
+royalty for commercial production or sale of any product developed with
+the source code'' to most countries.
+
+The rules in this area are continuously changing.  If you know of any
+information in this manual that is out-of-date, please report it to
+the bug database.  @xref{Reporting Bugs}.
+
+@node getpass
+@section Reading Passwords
+
+When reading in a password, it is desirable to avoid displaying it on
+the screen, to help keep it secret.  The following function handles this
+in a convenient way.
+
+@comment unistd.h
+@comment BSD
+@deftypefun {char *} getpass (const char *@var{prompt})
+@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
+@c This function will attempt to create a stream for terminal I/O, but
+@c will fallback to stdio/stderr.  It attempts to change the terminal
+@c mode in a thread-unsafe way, write out the prompt, read the password,
+@c then restore the terminal mode.  It has a cleanup to close the stream
+@c in case of (synchronous) cancellation, but not to restore the
+@c terminal mode.
+
+@code{getpass} outputs @var{prompt}, then reads a string in from the
+terminal without echoing it.  It tries to connect to the real terminal,
+@file{/dev/tty}, if possible, to encourage users not to put plaintext
+passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
+@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
+terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
+The terminal is flushed before and after @code{getpass}, so that
+characters of a mistyped password are not accidentally visible.
+
+In other C libraries, @code{getpass} may only return the first
+@code{PASS_MAX} bytes of a password.  @Theglibc{} has no limit, so
+@code{PASS_MAX} is undefined.
+
+The prototype for this function is in @file{unistd.h}.  @code{PASS_MAX}
+would be defined in @file{limits.h}.
+@end deftypefun
+
+This precise set of operations may not suit all possible situations.  In
+this case, it is recommended that users write their own @code{getpass}
+substitute.  For instance, a very simple substitute is as follows:
+
+@smallexample
+@include mygetpass.c.texi
+@end smallexample
+
+The substitute takes the same parameters as @code{getline}
+(@pxref{Line Input}); the user must print any prompt desired.
+
+@node crypt
+@section Encrypting Passwords
+
+@comment crypt.h
+@comment BSD, SVID
+@deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Besides the obvious problem of returning a pointer into static
+@c storage, the DES initializer takes an internal lock with the usual
+@c set of problems for AS- and AC-Safety.  The FIPS mode checker and the
+@c NSS implementations of may leak file descriptors if canceled.  The
+@c The MD5, SHA256 and SHA512 implementations will malloc on long keys,
+@c and NSS relies on dlopening, which brings about another can of worms.
+
+The @code{crypt} function takes a password, @var{key}, as a string, and
+a @var{salt} character array which is described below, and returns a
+printable ASCII string which starts with another salt.  It is believed
+that, given the output of the function, the best way to find a @var{key}
+that will produce that output is to guess values of @var{key} until the
+original value of @var{key} is found.
+
+The @var{salt} parameter does two things.  Firstly, it selects which
+algorithm is used, the MD5-based one or the DES-based one.  Secondly, it
+makes life harder for someone trying to guess passwords against a file
+containing many passwords; without a @var{salt}, an intruder can make a
+guess, run @code{crypt} on it once, and compare the result with all the
+passwords.  With a @var{salt}, the intruder must run @code{crypt} once
+for each different salt.
+
+For the MD5-based algorithm, the @var{salt} should consist of the string
+@code{$1$}, followed by up to 8 characters, terminated by either
+another @code{$} or the end of the string.  The result of @code{crypt}
+will be the @var{salt}, followed by a @code{$} if the salt didn't end
+with one, followed by 22 characters from the alphabet
+@code{./0-9A-Za-z}, up to 34 characters total.  Every character in the
+@var{key} is significant.
+
+For the DES-based algorithm, the @var{salt} should consist of two
+characters from the alphabet @code{./0-9A-Za-z}, and the result of
+@code{crypt} will be those two characters followed by 11 more from the
+same alphabet, 13 in total.  Only the first 8 characters in the
+@var{key} are significant.
+
+The MD5-based algorithm has no limit on the useful length of the
+password used, and is slightly more secure.  It is therefore preferred
+over the DES-based algorithm.
+
+When the user enters their password for the first time, the @var{salt}
+should be set to a new string which is reasonably random.  To verify a
+password against the result of a previous call to @code{crypt}, pass
+the result of the previous call as the @var{salt}.
+@end deftypefun
+
+The following short program is an example of how to use @code{crypt} the
+first time a password is entered.  Note that the @var{salt} generation
+is just barely acceptable; in particular, it is not unique between
+machines, and in many applications it would not be acceptable to let an
+attacker know what time the user's password was last set.
+
+@smallexample
+@include genpass.c.texi
+@end smallexample
+
+The next program shows how to verify a password.  It prompts the user
+for a password and prints ``Access granted.'' if the user types
+@code{GNU libc manual}.
+
+@smallexample
+@include testpass.c.texi
+@end smallexample
+
+@comment crypt.h
+@comment GNU
+@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Compared with crypt, this function fixes the @mtasurace:crypt
+@c problem, but nothing else.
+
+The @code{crypt_r} function does the same thing as @code{crypt}, but
+takes an extra parameter which includes space for its result (among
+other things), so it can be reentrant.  @code{data@w{->}initialized} must be
+cleared to zero before the first time @code{crypt_r} is called.
+
+The @code{crypt_r} function is a GNU extension.
+@end deftypefun
+
+The @code{crypt} and @code{crypt_r} functions are prototyped in the
+header @file{crypt.h}.
+
+@node DES Encryption
+@section DES Encryption
+
+@cindex FIPS 46-3
+The Data Encryption Standard is described in the US Government Federal
+Information Processing Standards (FIPS) 46-3 published by the National
+Institute of Standards and Technology.  The DES has been very thoroughly
+analyzed since it was developed in the late 1970s, and no new
+significant flaws have been found.
+
+However, the DES uses only a 56-bit key (plus 8 parity bits), and a
+machine has been built in 1998 which can search through all possible
+keys in about 6 days, which cost about US$200000; faster searches would
+be possible with more money.  This makes simple DES insecure for most
+purposes, and NIST no longer permits new US government systems
+to use simple DES.
+
+For serious encryption functionality, it is recommended that one of the
+many free encryption libraries be used instead of these routines.
+
+The DES is a reversible operation which takes a 64-bit block and a
+64-bit key, and produces another 64-bit block.  Usually the bits are
+numbered so that the most-significant bit, the first bit, of each block
+is numbered 1.
+
+Under that numbering, every 8th bit of the key (the 8th, 16th, and so
+on) is not used by the encryption algorithm itself.  But the key must
+have odd parity; that is, out of bits 1 through 8, and 9 through 16, and
+so on, there must be an odd number of `1' bits, and this completely
+specifies the unused bits.
+
+@comment crypt.h
+@comment BSD, SVID
+@deftypefun void setkey (const char *@var{key})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+@c The static buffer stores the key, making it fundamentally
+@c thread-unsafe.  The locking issues are only in the initialization
+@c path; cancelling the initialization will leave the lock held, it
+@c would otherwise repeat the initialization on the next call.
+
+The @code{setkey} function sets an internal data structure to be an
+expanded form of @var{key}.  @var{key} is specified as an array of 64
+bits each stored in a @code{char}, the first bit is @code{key[0]} and
+the 64th bit is @code{key[63]}.  The @var{key} should have the correct
+parity.
+@end deftypefun
+
+@comment crypt.h
+@comment BSD, SVID
+@deftypefun void encrypt (char *@var{block}, int @var{edflag})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+@c Same issues as setkey.
+
+The @code{encrypt} function encrypts @var{block} if
+@var{edflag} is 0, otherwise it decrypts @var{block}, using a key
+previously set by @code{setkey}.  The result is
+placed in @var{block}.
+
+Like @code{setkey}, @var{block} is specified as an array of 64 bits each
+stored in a @code{char}, but there are no parity bits in @var{block}.
+@end deftypefun
+
+@comment crypt.h
+@comment GNU
+@deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data})
+@c @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+@comment crypt.h
+@comment GNU
+@deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+
+These are reentrant versions of @code{setkey} and @code{encrypt}.  The
+only difference is the extra parameter, which stores the expanded
+version of @var{key}.  Before calling @code{setkey_r} the first time,
+@code{data->initialized} must be cleared to zero.
+@end deftypefun
+
+The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions.
+@code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are
+defined in @file{crypt.h}.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The function @code{ecb_crypt} encrypts or decrypts one or more blocks
+using DES.  Each block is encrypted independently.
+
+The @var{blocks} and the @var{key} are stored packed in 8-bit bytes, so
+that the first bit of the key is the most-significant bit of
+@code{key[0]} and the 63rd bit of the key is stored as the
+least-significant bit of @code{key[7]}.  The @var{key} should have the
+correct parity.
+
+@var{len} is the number of bytes in @var{blocks}.  It should be a
+multiple of 8 (so that there is a whole number of blocks to encrypt).
+@var{len} is limited to a maximum of @code{DES_MAXDATA} bytes.
+
+The result of the encryption replaces the input in @var{blocks}.
+
+The @var{mode} parameter is the bitwise OR of two of the following:
+
+@vtable @code
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DES_ENCRYPT
+This constant, used in the @var{mode} parameter, specifies that
+@var{blocks} is to be encrypted.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DES_DECRYPT
+This constant, used in the @var{mode} parameter, specifies that
+@var{blocks} is to be decrypted.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DES_HW
+This constant, used in the @var{mode} parameter, asks to use a hardware
+device.  If no hardware device is available, encryption happens anyway,
+but in software.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DES_SW
+This constant, used in the @var{mode} parameter, specifies that no
+hardware device is to be used.
+@end vtable
+
+The result of the function will be one of these values:
+
+@vtable @code
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DESERR_NONE
+The encryption succeeded.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DESERR_NOHWDEVICE
+The encryption succeeded, but there was no hardware device available.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DESERR_HWERROR
+The encryption failed because of a hardware problem.
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@item DESERR_BADPARAM
+The encryption failed because of a bad parameter, for instance @var{len}
+is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}.
+@end vtable
+@end deftypefun
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@deftypefun int DES_FAILED (int @var{err})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns 1 if @var{err} is a `success' result code from
+@code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise.
+@end deftypefun
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}, char *@var{ivec})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The function @code{cbc_crypt} encrypts or decrypts one or more blocks
+using DES in Cipher Block Chaining mode.
+
+For encryption in CBC mode, each block is exclusive-ored with @var{ivec}
+before being encrypted, then @var{ivec} is replaced with the result of
+the encryption, then the next block is processed.  Decryption is the
+reverse of this process.
+
+This has the advantage that blocks which are the same before being
+encrypted are very unlikely to be the same after being encrypted, making
+it much harder to detect patterns in the data.
+
+Usually, @var{ivec} is set to 8 random bytes before encryption starts.
+Then the 8 random bytes are transmitted along with the encrypted data
+(without themselves being encrypted), and passed back in as @var{ivec}
+for decryption.  Another possibility is to set @var{ivec} to 8 zeroes
+initially, and have the first the block encrypted consist of 8 random
+bytes.
+
+Otherwise, all the parameters are similar to those for @code{ecb_crypt}.
+@end deftypefun
+
+@comment rpc/des_crypt.h
+@comment SUNRPC
+@deftypefun void des_setparity (char *@var{key})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The function @code{des_setparity} changes the 64-bit @var{key}, stored
+packed in 8-bit bytes, to have odd parity by altering the low bits of
+each byte.
+@end deftypefun
+
+The @code{ecb_crypt}, @code{cbc_crypt}, and @code{des_setparity}
+functions and their accompanying macros are all defined in the header
+@file{rpc/des_crypt.h}.
diff --git a/ap/libc/glibc/glibc-2.23/manual/ctype.texi b/ap/libc/glibc/glibc-2.23/manual/ctype.texi
new file mode 100644
index 0000000..2d73d4e
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/ctype.texi
@@ -0,0 +1,843 @@
+@node Character Handling, String and Array Utilities, Memory, Top
+@c %MENU% Character testing and conversion functions
+@chapter Character Handling
+
+Programs that work with characters and strings often need to classify a
+character---is it alphabetic, is it a digit, is it whitespace, and so
+on---and perform case conversion operations on characters.  The
+functions in the header file @file{ctype.h} are provided for this
+purpose.
+@pindex ctype.h
+
+Since the choice of locale and character set can alter the
+classifications of particular character codes, all of these functions
+are affected by the current locale.  (More precisely, they are affected
+by the locale currently selected for character classification---the
+@code{LC_CTYPE} category; see @ref{Locale Categories}.)
+
+The @w{ISO C} standard specifies two different sets of functions.  The
+one set works on @code{char} type characters, the other one on
+@code{wchar_t} wide characters (@pxref{Extended Char Intro}).
+
+@menu
+* Classification of Characters::       Testing whether characters are
+			                letters, digits, punctuation, etc.
+
+* Case Conversion::                    Case mapping, and the like.
+* Classification of Wide Characters::  Character class determination for
+                                        wide characters.
+* Using Wide Char Classes::            Notes on using the wide character
+                                        classes.
+* Wide Character Case Conversion::     Mapping of wide characters.
+@end menu
+
+@node Classification of Characters, Case Conversion,  , Character Handling
+@section Classification of Characters
+@cindex character testing
+@cindex classification of characters
+@cindex predicates on characters
+@cindex character predicates
+
+This section explains the library functions for classifying characters.
+For example, @code{isalpha} is the function to test for an alphabetic
+character.  It takes one argument, the character to test, and returns a
+nonzero integer if the character is alphabetic, and zero otherwise.  You
+would use it like this:
+
+@smallexample
+if (isalpha (c))
+  printf ("The character `%c' is alphabetic.\n", c);
+@end smallexample
+
+Each of the functions in this section tests for membership in a
+particular class of characters; each has a name starting with @samp{is}.
+Each of them takes one argument, which is a character to test, and
+returns an @code{int} which is treated as a boolean value.  The
+character argument is passed as an @code{int}, and it may be the
+constant value @code{EOF} instead of a real character.
+
+The attributes of any given character can vary between locales.
+@xref{Locales}, for more information on locales.@refill
+
+These functions are declared in the header file @file{ctype.h}.
+@pindex ctype.h
+
+@cindex lower-case character
+@comment ctype.h
+@comment ISO
+@deftypefun int islower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The is* macros call __ctype_b_loc to get the ctype array from the
+@c current locale, and then index it by c.  __ctype_b_loc reads from
+@c thread-local memory the (indirect) pointer to the ctype array, which
+@c may involve one word access to the global locale object, if that's
+@c the active locale for the thread, and the array, being part of the
+@c locale data, is undeletable, so there's no thread-safety issue.  We
+@c might want to mark these with @mtslocale to flag to callers that
+@c changing locales might affect them, even if not these simpler
+@c functions.
+Returns true if @var{c} is a lower-case letter.  The letter need not be
+from the Latin alphabet, any alphabet representable is valid.
+@end deftypefun
+
+@cindex upper-case character
+@comment ctype.h
+@comment ISO
+@deftypefun int isupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is an upper-case letter.  The letter need not be
+from the Latin alphabet, any alphabet representable is valid.
+@end deftypefun
+
+@cindex alphabetic character
+@comment ctype.h
+@comment ISO
+@deftypefun int isalpha (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is an alphabetic character (a letter).  If
+@code{islower} or @code{isupper} is true of a character, then
+@code{isalpha} is also true.
+
+In some locales, there may be additional characters for which
+@code{isalpha} is true---letters which are neither upper case nor lower
+case.  But in the standard @code{"C"} locale, there are no such
+additional characters.
+@end deftypefun
+
+@cindex digit character
+@cindex decimal digit character
+@comment ctype.h
+@comment ISO
+@deftypefun int isdigit (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
+@end deftypefun
+
+@cindex alphanumeric character
+@comment ctype.h
+@comment ISO
+@deftypefun int isalnum (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is an alphanumeric character (a letter or
+number); in other words, if either @code{isalpha} or @code{isdigit} is
+true of a character, then @code{isalnum} is also true.
+@end deftypefun
+
+@cindex hexadecimal digit character
+@comment ctype.h
+@comment ISO
+@deftypefun int isxdigit (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a hexadecimal digit.
+Hexadecimal digits include the normal decimal digits @samp{0} through
+@samp{9} and the letters @samp{A} through @samp{F} and
+@samp{a} through @samp{f}.
+@end deftypefun
+
+@cindex punctuation character
+@comment ctype.h
+@comment ISO
+@deftypefun int ispunct (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a punctuation character.
+This means any printing character that is not alphanumeric or a space
+character.
+@end deftypefun
+
+@cindex whitespace character
+@comment ctype.h
+@comment ISO
+@deftypefun int isspace (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
+@code{"C"} locale, @code{isspace} returns true for only the standard
+whitespace characters:
+
+@table @code
+@item ' '
+space
+
+@item '\f'
+formfeed
+
+@item '\n'
+newline
+
+@item '\r'
+carriage return
+
+@item '\t'
+horizontal tab
+
+@item '\v'
+vertical tab
+@end table
+@end deftypefun
+
+@cindex blank character
+@comment ctype.h
+@comment ISO
+@deftypefun int isblank (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a blank character; that is, a space or a tab.
+This function was originally a GNU extension, but was added in @w{ISO C99}.
+@end deftypefun
+
+@cindex graphic character
+@comment ctype.h
+@comment ISO
+@deftypefun int isgraph (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a graphic character; that is, a character
+that has a glyph associated with it.  The whitespace characters are not
+considered graphic.
+@end deftypefun
+
+@cindex printing character
+@comment ctype.h
+@comment ISO
+@deftypefun int isprint (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a printing character.  Printing characters
+include all the graphic characters, plus the space (@samp{ }) character.
+@end deftypefun
+
+@cindex control character
+@comment ctype.h
+@comment ISO
+@deftypefun int iscntrl (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a control character (that is, a character that
+is not a printing character).
+@end deftypefun
+
+@cindex ASCII character
+@comment ctype.h
+@comment SVID, BSD
+@deftypefun int isascii (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
+into the US/UK ASCII character set.  This function is a BSD extension
+and is also an SVID extension.
+@end deftypefun
+
+@node Case Conversion, Classification of Wide Characters, Classification of Characters, Character Handling
+@section Case Conversion
+@cindex character case conversion
+@cindex case conversion of characters
+@cindex converting case of characters
+
+This section explains the library functions for performing conversions
+such as case mappings on characters.  For example, @code{toupper}
+converts any character to upper case if possible.  If the character
+can't be converted, @code{toupper} returns it unchanged.
+
+These functions take one argument of type @code{int}, which is the
+character to convert, and return the converted character as an
+@code{int}.  If the conversion is not applicable to the argument given,
+the argument is returned unchanged.
+
+@strong{Compatibility Note:} In pre-@w{ISO C} dialects, instead of
+returning the argument unchanged, these functions may fail when the
+argument is not suitable for the conversion.  Thus for portability, you
+may need to write @code{islower(c) ? toupper(c) : c} rather than just
+@code{toupper(c)}.
+
+These functions are declared in the header file @file{ctype.h}.
+@pindex ctype.h
+
+@comment ctype.h
+@comment ISO
+@deftypefun int tolower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The to* macros/functions call different functions that use different
+@c arrays than those of__ctype_b_loc, but the access patterns and
+@c thus safety guarantees are the same.
+If @var{c} is an upper-case letter, @code{tolower} returns the corresponding
+lower-case letter.  If @var{c} is not an upper-case letter,
+@var{c} is returned unchanged.
+@end deftypefun
+
+@comment ctype.h
+@comment ISO
+@deftypefun int toupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @var{c} is a lower-case letter, @code{toupper} returns the corresponding
+upper-case letter.  Otherwise @var{c} is returned unchanged.
+@end deftypefun
+
+@comment ctype.h
+@comment SVID, BSD
+@deftypefun int toascii (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function converts @var{c} to a 7-bit @code{unsigned char} value
+that fits into the US/UK ASCII character set, by clearing the high-order
+bits.  This function is a BSD extension and is also an SVID extension.
+@end deftypefun
+
+@comment ctype.h
+@comment SVID
+@deftypefun int _tolower (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is identical to @code{tolower}, and is provided for compatibility
+with the SVID.  @xref{SVID}.@refill
+@end deftypefun
+
+@comment ctype.h
+@comment SVID
+@deftypefun int _toupper (int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is identical to @code{toupper}, and is provided for compatibility
+with the SVID.
+@end deftypefun
+
+
+@node Classification of Wide Characters, Using Wide Char Classes, Case Conversion, Character Handling
+@section Character class determination for wide characters
+
+@w{Amendment 1} to @w{ISO C90} defines functions to classify wide
+characters.  Although the original @w{ISO C90} standard already defined
+the type @code{wchar_t}, no functions operating on them were defined.
+
+The general design of the classification functions for wide characters
+is more general.  It allows extensions to the set of available
+classifications, beyond those which are always available.  The POSIX
+standard specifies how extensions can be made, and this is already
+implemented in the @glibcadj{} implementation of the @code{localedef}
+program.
+
+The character class functions are normally implemented with bitsets,
+with a bitset per character.  For a given character, the appropriate
+bitset is read from a table and a test is performed as to whether a
+certain bit is set.  Which bit is tested for is determined by the
+class.
+
+For the wide character classification functions this is made visible.
+There is a type classification type defined, a function to retrieve this
+value for a given class, and a function to test whether a given
+character is in this class, using the classification value.  On top of
+this the normal character classification functions as used for
+@code{char} objects can be defined.
+
+@comment wctype.h
+@comment ISO
+@deftp {Data type} wctype_t
+The @code{wctype_t} can hold a value which represents a character class.
+The only defined way to generate such a value is by using the
+@code{wctype} function.
+
+@pindex wctype.h
+This type is defined in @file{wctype.h}.
+@end deftp
+
+@comment wctype.h
+@comment ISO
+@deftypefun wctype_t wctype (const char *@var{property})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Although the source code of wctype contains multiple references to
+@c the locale, that could each reference different locale_data objects
+@c should the global locale object change while active, the compiler can
+@c and does combine them all into a single dereference that resolves
+@c once to the LCTYPE locale object used throughout the function, so it
+@c is safe in (optimized) practice, if not in theory, even when the
+@c locale changes.  Ideally we'd explicitly save the resolved
+@c locale_data object to make it visibly safe instead of safe only under
+@c compiler optimizations, but given the decision that setlocale is
+@c MT-Unsafe, all this would afford us would be the ability to not mark
+@c this function with @mtslocale.
+The @code{wctype} returns a value representing a class of wide
+characters which is identified by the string @var{property}.  Beside
+some standard properties each locale can define its own ones.  In case
+no property with the given name is known for the current locale
+selected for the @code{LC_CTYPE} category, the function returns zero.
+
+@noindent
+The properties known in every locale are:
+
+@multitable @columnfractions .25 .25 .25 .25
+@item
+@code{"alnum"} @tab @code{"alpha"} @tab @code{"cntrl"} @tab @code{"digit"}
+@item
+@code{"graph"} @tab @code{"lower"} @tab @code{"print"} @tab @code{"punct"}
+@item
+@code{"space"} @tab @code{"upper"} @tab @code{"xdigit"}
+@end multitable
+
+@pindex wctype.h
+This function is declared in @file{wctype.h}.
+@end deftypefun
+
+To test the membership of a character to one of the non-standard classes
+the @w{ISO C} standard defines a completely new function.
+
+@comment wctype.h
+@comment ISO
+@deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The compressed lookup table returned by wctype is read-only.
+This function returns a nonzero value if @var{wc} is in the character
+class specified by @var{desc}.  @var{desc} must previously be returned
+by a successful call to @code{wctype}.
+
+@pindex wctype.h
+This function is declared in @file{wctype.h}.
+@end deftypefun
+
+To make it easier to use the commonly-used classification functions,
+they are defined in the C library.  There is no need to use
+@code{wctype} if the property string is one of the known character
+classes.  In some situations it is desirable to construct the property
+strings, and then it is important that @code{wctype} can also handle the
+standard classes.
+
+@cindex alphanumeric character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswalnum (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c The implicit wctype call in the isw* functions is actually an
+@c optimized version because the category has a known offset, but the
+@c wctype is equally safe when optimized, unsafe with changing locales
+@c if not optimized (thus @mtslocale).  Since it's not a macro, we
+@c always optimize, and the locale can't change in any MT-Safe way, it's
+@c fine.  The test whether wc is ASCII to use the non-wide is*
+@c macro/function doesn't bring any other safety issues: the test does
+@c not depend on the locale, and each path after the decision resolves
+@c the locale object only once.
+This function returns a nonzero value if @var{wc} is an alphanumeric
+character (a letter or number); in other words, if either @code{iswalpha}
+or @code{iswdigit} is true of a character, then @code{iswalnum} is also
+true.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("alnum"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex alphabetic character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswalpha (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is an alphabetic character (a letter).  If
+@code{iswlower} or @code{iswupper} is true of a character, then
+@code{iswalpha} is also true.
+
+In some locales, there may be additional characters for which
+@code{iswalpha} is true---letters which are neither upper case nor lower
+case.  But in the standard @code{"C"} locale, there are no such
+additional characters.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("alpha"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex control character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswcntrl (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a control character (that is, a character that
+is not a printing character).
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("cntrl"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex digit character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswdigit (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
+Please note that this function does not only return a nonzero value for
+@emph{decimal} digits, but for all kinds of digits.  A consequence is
+that code like the following will @strong{not} work unconditionally for
+wide characters:
+
+@smallexample
+n = 0;
+while (iswdigit (*wc))
+  @{
+    n *= 10;
+    n += *wc++ - L'0';
+  @}
+@end smallexample
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("digit"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex graphic character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswgraph (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a graphic character; that is, a character
+that has a glyph associated with it.  The whitespace characters are not
+considered graphic.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("graph"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex lower-case character
+@comment ctype.h
+@comment ISO
+@deftypefun int iswlower (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a lower-case letter.  The letter need not be
+from the Latin alphabet, any alphabet representable is valid.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("lower"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex printing character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswprint (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a printing character.  Printing characters
+include all the graphic characters, plus the space (@samp{ }) character.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("print"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex punctuation character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswpunct (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a punctuation character.
+This means any printing character that is not alphanumeric or a space
+character.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("punct"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex whitespace character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswspace (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a @dfn{whitespace} character.  In the standard
+@code{"C"} locale, @code{iswspace} returns true for only the standard
+whitespace characters:
+
+@table @code
+@item L' '
+space
+
+@item L'\f'
+formfeed
+
+@item L'\n'
+newline
+
+@item L'\r'
+carriage return
+
+@item L'\t'
+horizontal tab
+
+@item L'\v'
+vertical tab
+@end table
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("space"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex upper-case character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswupper (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is an upper-case letter.  The letter need not be
+from the Latin alphabet, any alphabet representable is valid.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("upper"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@cindex hexadecimal digit character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswxdigit (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a hexadecimal digit.
+Hexadecimal digits include the normal decimal digits @samp{0} through
+@samp{9} and the letters @samp{A} through @samp{F} and
+@samp{a} through @samp{f}.
+
+@noindent
+This function can be implemented using
+
+@smallexample
+iswctype (wc, wctype ("xdigit"))
+@end smallexample
+
+@pindex wctype.h
+It is declared in @file{wctype.h}.
+@end deftypefun
+
+@Theglibc{} also provides a function which is not defined in the
+@w{ISO C} standard but which is available as a version for single byte
+characters as well.
+
+@cindex blank character
+@comment wctype.h
+@comment ISO
+@deftypefun int iswblank (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+Returns true if @var{wc} is a blank character; that is, a space or a tab.
+This function was originally a GNU extension, but was added in @w{ISO C99}.
+It is declared in @file{wchar.h}.
+@end deftypefun
+
+@node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
+@section Notes on using the wide character classes
+
+The first note is probably not astonishing but still occasionally a
+cause of problems.  The @code{isw@var{XXX}} functions can be implemented
+using macros and in fact, @theglibc{} does this.  They are still
+available as real functions but when the @file{wctype.h} header is
+included the macros will be used.  This is the same as the
+@code{char} type versions of these functions.
+
+The second note covers something new.  It can be best illustrated by a
+(real-world) example.  The first piece of code is an excerpt from the
+original code.  It is truncated a bit but the intention should be clear.
+
+@smallexample
+int
+is_in_class (int c, const char *class)
+@{
+  if (strcmp (class, "alnum") == 0)
+    return isalnum (c);
+  if (strcmp (class, "alpha") == 0)
+    return isalpha (c);
+  if (strcmp (class, "cntrl") == 0)
+    return iscntrl (c);
+  @dots{}
+  return 0;
+@}
+@end smallexample
+
+Now, with the @code{wctype} and @code{iswctype} you can avoid the
+@code{if} cascades, but rewriting the code as follows is wrong:
+
+@smallexample
+int
+is_in_class (int c, const char *class)
+@{
+  wctype_t desc = wctype (class);
+  return desc ? iswctype ((wint_t) c, desc) : 0;
+@}
+@end smallexample
+
+The problem is that it is not guaranteed that the wide character
+representation of a single-byte character can be found using casting.
+In fact, usually this fails miserably.  The correct solution to this
+problem is to write the code as follows:
+
+@smallexample
+int
+is_in_class (int c, const char *class)
+@{
+  wctype_t desc = wctype (class);
+  return desc ? iswctype (btowc (c), desc) : 0;
+@}
+@end smallexample
+
+@xref{Converting a Character}, for more information on @code{btowc}.
+Note that this change probably does not improve the performance
+of the program a lot since the @code{wctype} function still has to make
+the string comparisons.  It gets really interesting if the
+@code{is_in_class} function is called more than once for the
+same class name.  In this case the variable @var{desc} could be computed
+once and reused for all the calls.  Therefore the above form of the
+function is probably not the final one.
+
+
+@node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
+@section Mapping of wide characters.
+
+The classification functions are also generalized by the @w{ISO C}
+standard.  Instead of just allowing the two standard mappings, a
+locale can contain others.  Again, the @code{localedef} program
+already supports generating such locale data files.
+
+@comment wctype.h
+@comment ISO
+@deftp {Data Type} wctrans_t
+This data type is defined as a scalar type which can hold a value
+representing the locale-dependent character mapping.  There is no way to
+construct such a value apart from using the return value of the
+@code{wctrans} function.
+
+@pindex wctype.h
+@noindent
+This type is defined in @file{wctype.h}.
+@end deftp
+
+@comment wctype.h
+@comment ISO
+@deftypefun wctrans_t wctrans (const char *@var{property})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Similar implementation, same caveats as wctype.
+The @code{wctrans} function has to be used to find out whether a named
+mapping is defined in the current locale selected for the
+@code{LC_CTYPE} category.  If the returned value is non-zero, you can use
+it afterwards in calls to @code{towctrans}.  If the return value is
+zero no such mapping is known in the current locale.
+
+Beside locale-specific mappings there are two mappings which are
+guaranteed to be available in every locale:
+
+@multitable @columnfractions .5 .5
+@item
+@code{"tolower"} @tab @code{"toupper"}
+@end multitable
+
+@pindex wctype.h
+@noindent
+These functions are declared in @file{wctype.h}.
+@end deftypefun
+
+@comment wctype.h
+@comment ISO
+@deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Same caveats as iswctype.
+@code{towctrans} maps the input character @var{wc}
+according to the rules of the mapping for which @var{desc} is a
+descriptor, and returns the value it finds.  @var{desc} must be
+obtained by a successful call to @code{wctrans}.
+
+@pindex wctype.h
+@noindent
+This function is declared in @file{wctype.h}.
+@end deftypefun
+
+For the generally available mappings, the @w{ISO C} standard defines
+convenient shortcuts so that it is not necessary to call @code{wctrans}
+for them.
+
+@comment wctype.h
+@comment ISO
+@deftypefun wint_t towlower (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Same caveats as iswalnum, just using a wctrans rather than a wctype
+@c table.
+If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
+lower-case letter.  If @var{wc} is not an upper-case letter,
+@var{wc} is returned unchanged.
+
+@noindent
+@code{towlower} can be implemented using
+
+@smallexample
+towctrans (wc, wctrans ("tolower"))
+@end smallexample
+
+@pindex wctype.h
+@noindent
+This function is declared in @file{wctype.h}.
+@end deftypefun
+
+@comment wctype.h
+@comment ISO
+@deftypefun wint_t towupper (wint_t @var{wc})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
+upper-case letter.  Otherwise @var{wc} is returned unchanged.
+
+@noindent
+@code{towupper} can be implemented using
+
+@smallexample
+towctrans (wc, wctrans ("toupper"))
+@end smallexample
+
+@pindex wctype.h
+@noindent
+This function is declared in @file{wctype.h}.
+@end deftypefun
+
+The same warnings given in the last section for the use of the wide
+character classification functions apply here.  It is not possible to
+simply cast a @code{char} type value to a @code{wint_t} and use it as an
+argument to @code{towctrans} calls.
diff --git a/ap/libc/glibc/glibc-2.23/manual/debug.texi b/ap/libc/glibc/glibc-2.23/manual/debug.texi
new file mode 100644
index 0000000..25492c3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/debug.texi
@@ -0,0 +1,136 @@
+@node Debugging Support
+@c @node Debugging Support, POSIX Threads, Cryptographic Functions, Top
+@c %MENU% Functions to help debugging applications
+@chapter Debugging support
+
+Applications are usually debugged using dedicated debugger programs.
+But sometimes this is not possible and, in any case, it is useful to
+provide the developer with as much information as possible at the time
+the problems are experienced.  For this reason a few functions are
+provided which a program can use to help the developer more easily
+locate the problem.
+
+
+@menu
+* Backtraces::                Obtaining and printing a back trace of the
+                               current stack.
+@end menu
+
+
+@node Backtraces, , , Debugging Support
+@section Backtraces
+
+@cindex backtrace
+@cindex backtrace_symbols
+@cindex backtrace_fd
+A @dfn{backtrace} is a list of the function calls that are currently
+active in a thread.  The usual way to inspect a backtrace of a program
+is to use an external debugger such as gdb.  However, sometimes it is
+useful to obtain a backtrace programmatically from within a program,
+e.g., for the purposes of logging or diagnostics.
+
+The header file @file{execinfo.h} declares three functions that obtain
+and manipulate backtraces of the current thread.
+@pindex execinfo.h
+
+@comment execinfo.h
+@comment GNU
+@deftypefun int backtrace (void **@var{buffer}, int @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{} @ascuheap{} @ascudlopen{} @ascuplugin{} @asulock{}}@acunsafe{@acuinit{} @acsmem{} @aculock{} @acsfd{}}}
+@c The generic implementation just does pointer chasing within the local
+@c stack, without any guarantees that this will handle signal frames
+@c correctly, so it's AS-Unsafe to begin with.  However, most (all?)
+@c arches defer to libgcc_s's _Unwind_* implementation, dlopening
+@c libgcc_s.so to that end except in a static version of libc.
+@c libgcc_s's implementation may in turn defer to libunwind.  We can't
+@c assume those implementations are AS- or AC-safe, but even if we
+@c could, our own initialization path isn't, and libgcc's implementation
+@c calls malloc and performs internal locking, so...
+The @code{backtrace} function obtains a backtrace for the current
+thread, as a list of pointers, and places the information into
+@var{buffer}.  The argument @var{size} should be the number of
+@w{@code{void *}} elements that will fit into @var{buffer}.  The return
+value is the actual number of entries of @var{buffer} that are obtained,
+and is at most @var{size}.
+
+The pointers placed in @var{buffer} are actually return addresses
+obtained by inspecting the stack, one return address per stack frame.
+
+Note that certain compiler optimizations may interfere with obtaining a
+valid backtrace.  Function inlining causes the inlined function to not
+have a stack frame; tail call optimization replaces one stack frame with
+another; frame pointer elimination will stop @code{backtrace} from
+interpreting the stack contents correctly.
+@end deftypefun
+
+@comment execinfo.h
+@comment GNU
+@deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @aculock{}}}
+@c Collects info returned by _dl_addr in an auto array, allocates memory
+@c for the whole return buffer with malloc then sprintfs into it storing
+@c pointers to the strings into the array entries in the buffer.
+@c _dl_addr takes the recursive dl_load_lock then calls
+@c _dl_find_dso_for_object and determine_info.
+@c _dl_find_dso_for_object calls _dl-addr_inside_object.
+@c All of them are safe as long as the lock is held.
+@c @asucorrupt?  It doesn't look like the dynamic loader's data
+@c structures could be in an inconsistent state that would cause
+@c malfunction here.
+The @code{backtrace_symbols} function translates the information
+obtained from the @code{backtrace} function into an array of strings.
+The argument @var{buffer} should be a pointer to an array of addresses
+obtained via the @code{backtrace} function, and @var{size} is the number
+of entries in that array (the return value of @code{backtrace}).
+
+The return value is a pointer to an array of strings, which has
+@var{size} entries just like the array @var{buffer}.  Each string
+contains a printable representation of the corresponding element of
+@var{buffer}.  It includes the function name (if this can be
+determined), an offset into the function, and the actual return address
+(in hexadecimal).
+
+Currently, the function name and offset only be obtained on systems that
+use the ELF binary format for programs and libraries.  On other systems,
+only the hexadecimal return address will be present.  Also, you may need
+to pass additional flags to the linker to make the function names
+available to the program.  (For example, on systems using GNU ld, you
+must pass (@code{-rdynamic}.)
+
+The return value of @code{backtrace_symbols} is a pointer obtained via
+the @code{malloc} function, and it is the responsibility of the caller
+to @code{free} that pointer.  Note that only the return value need be
+freed, not the individual strings.
+
+The return value is @code{NULL} if sufficient memory for the strings
+cannot be obtained.
+@end deftypefun
+
+@comment execinfo.h
+@comment GNU
+@deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+@c Single loop of _dl_addr over addresses, collecting info into an iovec
+@c written out with a writev call per iteration.  Addresses and offsets
+@c are converted to hex in auto buffers, so the only potential issue
+@c here is leaking the dl lock in case of cancellation.
+The @code{backtrace_symbols_fd} function performs the same translation
+as the function @code{backtrace_symbols} function.  Instead of returning
+the strings to the caller, it writes the strings to the file descriptor
+@var{fd}, one per line.  It does not use the @code{malloc} function, and
+can therefore be used in situations where that function might fail.
+@end deftypefun
+
+The following program illustrates the use of these functions.  Note that
+the array to contain the return addresses returned by @code{backtrace}
+is allocated on the stack.  Therefore code like this can be used in
+situations where the memory handling via @code{malloc} does not work
+anymore (in which case the @code{backtrace_symbols} has to be replaced
+by a @code{backtrace_symbols_fd} call as well).  The number of return
+addresses is normally not very large.  Even complicated programs rather
+seldom have a nesting level of more than, say, 50 and with 200 possible
+entries probably all programs should be covered.
+
+@smallexample
+@include execinfo.c.texi
+@end smallexample
diff --git a/ap/libc/glibc/glibc-2.23/manual/dir b/ap/libc/glibc/glibc-2.23/manual/dir
new file mode 100644
index 0000000..ee98f79
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/dir
@@ -0,0 +1,15 @@
+This is the file .../info/dir, which contains the topmost node of the
+Info hierarchy.  The first time you invoke Info you start off
+looking at that node, which is (dir)Top.
+
+File: dir	Node: Top	This is the top of the INFO tree
+
+  This (the Directory node) gives a menu of major topics. 
+  Typing "q" exits, "?" lists all Info commands, "d" returns here,
+  "h" gives a primer for first-timers,
+  "mEmacs<Return>" visits the Emacs topic, etc.
+
+  In Emacs, you can click mouse button 2 on a menu item or cross reference
+  to select it.
+
+* Menu: 
diff --git a/ap/libc/glibc/glibc-2.23/manual/errno.texi b/ap/libc/glibc/glibc-2.23/manual/errno.texi
new file mode 100644
index 0000000..1068be3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/errno.texi
@@ -0,0 +1,1709 @@
+@node Error Reporting, Memory, Introduction, Top
+@chapter Error Reporting
+@c %MENU% How library functions report errors
+@cindex error reporting
+@cindex reporting errors
+@cindex error codes
+@cindex status codes
+
+Many functions in @theglibc{} detect and report error conditions,
+and sometimes your programs need to check for these error conditions.
+For example, when you open an input file, you should verify that the
+file was actually opened correctly, and print an error message or take
+other appropriate action if the call to the library function failed.
+
+This chapter describes how the error reporting facility works.  Your
+program should include the header file @file{errno.h} to use this
+facility.
+@pindex errno.h
+
+@menu
+* Checking for Errors::         How errors are reported by library functions.
+* Error Codes::                 Error code macros; all of these expand
+                                 into integer constant values.
+* Error Messages::              Mapping error codes onto error messages.
+@end menu
+
+@node Checking for Errors, Error Codes,  , Error Reporting
+@section Checking for Errors
+
+Most library functions return a special value to indicate that they have
+failed.  The special value is typically @code{-1}, a null pointer, or a
+constant such as @code{EOF} that is defined for that purpose.  But this
+return value tells you only that an error has occurred.  To find out
+what kind of error it was, you need to look at the error code stored in the
+variable @code{errno}.  This variable is declared in the header file
+@file{errno.h}.
+@pindex errno.h
+
+@comment errno.h
+@comment ISO
+@deftypevr {Variable} {volatile int} errno
+The variable @code{errno} contains the system error number.  You can
+change the value of @code{errno}.
+
+Since @code{errno} is declared @code{volatile}, it might be changed
+asynchronously by a signal handler; see @ref{Defining Handlers}.
+However, a properly written signal handler saves and restores the value
+of @code{errno}, so you generally do not need to worry about this
+possibility except when writing signal handlers.
+
+The initial value of @code{errno} at program startup is zero.  Many
+library functions are guaranteed to set it to certain nonzero values
+when they encounter certain kinds of errors.  These error conditions are
+listed for each function.  These functions do not change @code{errno}
+when they succeed; thus, the value of @code{errno} after a successful
+call is not necessarily zero, and you should not use @code{errno} to
+determine @emph{whether} a call failed.  The proper way to do that is
+documented for each function.  @emph{If} the call failed, you can
+examine @code{errno}.
+
+Many library functions can set @code{errno} to a nonzero value as a
+result of calling other library functions which might fail.  You should
+assume that any library function might alter @code{errno} when the
+function returns an error.
+
+@strong{Portability Note:} @w{ISO C} specifies @code{errno} as a
+``modifiable lvalue'' rather than as a variable, permitting it to be
+implemented as a macro.  For example, its expansion might involve a
+function call, like @w{@code{*__errno_location ()}}.  In fact, that is
+what it is
+on @gnulinuxhurdsystems{}.  @Theglibc{}, on each system, does
+whatever is right for the particular system.
+
+There are a few library functions, like @code{sqrt} and @code{atan},
+that return a perfectly legitimate value in case of an error, but also
+set @code{errno}.  For these functions, if you want to check to see
+whether an error occurred, the recommended method is to set @code{errno}
+to zero before calling the function, and then check its value afterward.
+@end deftypevr
+
+@pindex errno.h
+All the error codes have symbolic names; they are macros defined in
+@file{errno.h}.  The names start with @samp{E} and an upper-case
+letter or digit; you should consider names of this form to be
+reserved names.  @xref{Reserved Names}.
+
+The error code values are all positive integers and are all distinct,
+with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
+Since the values are distinct, you can use them as labels in a
+@code{switch} statement; just don't use both @code{EWOULDBLOCK} and
+@code{EAGAIN}.  Your program should not make any other assumptions about
+the specific values of these symbolic constants.
+
+The value of @code{errno} doesn't necessarily have to correspond to any
+of these macros, since some library functions might return other error
+codes of their own for other situations.  The only values that are
+guaranteed to be meaningful for a particular library function are the
+ones that this manual lists for that function.
+
+Except on @gnuhurdsystems{}, almost any system call can return @code{EFAULT} if
+it is given an invalid pointer as an argument.  Since this could only
+happen as a result of a bug in your program, and since it will not
+happen on @gnuhurdsystems{}, we have saved space by not mentioning
+@code{EFAULT} in the descriptions of individual functions.
+
+In some Unix systems, many system calls can also return @code{EFAULT} if
+given as an argument a pointer into the stack, and the kernel for some
+obscure reason fails in its attempt to extend the stack.  If this ever
+happens, you should probably try using statically or dynamically
+allocated memory instead of stack memory on that system.
+
+@node Error Codes, Error Messages, Checking for Errors, Error Reporting
+@section Error Codes
+
+@pindex errno.h
+The error code macros are defined in the header file @file{errno.h}.
+All of them expand into integer constant values.  Some of these error
+codes can't occur on @gnusystems{}, but they can occur using @theglibc{}
+on other systems.
+
+@comment errno.h
+@comment POSIX.1: Operation not permitted
+@deftypevr Macro int EPERM
+@comment errno 1 @c DO NOT REMOVE
+Operation not permitted; only the owner of the file (or other resource)
+or processes with special privileges can perform the operation.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No such file or directory
+@deftypevr Macro int ENOENT
+@comment errno 2 @c DO NOT REMOVE
+No such file or directory.  This is a ``file doesn't exist'' error
+for ordinary files that are referenced in contexts where they are
+expected to already exist.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No such process
+@deftypevr Macro int ESRCH
+@comment errno 3 @c DO NOT REMOVE
+No process matches the specified process ID.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Interrupted system call
+@deftypevr Macro int EINTR
+@comment errno 4 @c DO NOT REMOVE
+Interrupted function call; an asynchronous signal occurred and prevented
+completion of the call.  When this happens, you should try the call
+again.
+
+You can choose to have functions resume after a signal that is handled,
+rather than failing with @code{EINTR}; see @ref{Interrupted
+Primitives}.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Input/output error
+@deftypevr Macro int EIO
+@comment errno 5 @c DO NOT REMOVE
+Input/output error; usually used for physical read or write errors.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No such device or address
+@deftypevr Macro int ENXIO
+@comment errno 6 @c DO NOT REMOVE
+No such device or address.  The system tried to use the device
+represented by a file you specified, and it couldn't find the device.
+This can mean that the device file was installed incorrectly, or that
+the physical device is missing or not correctly attached to the
+computer.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Argument list too long
+@deftypevr Macro int E2BIG
+@comment errno 7 @c DO NOT REMOVE
+Argument list too long; used when the arguments passed to a new program
+being executed with one of the @code{exec} functions (@pxref{Executing a
+File}) occupy too much memory space.  This condition never arises on
+@gnuhurdsystems{}.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Exec format error
+@deftypevr Macro int ENOEXEC
+@comment errno 8 @c DO NOT REMOVE
+Invalid executable file format.  This condition is detected by the
+@code{exec} functions; see @ref{Executing a File}.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Bad file descriptor
+@deftypevr Macro int EBADF
+@comment errno 9 @c DO NOT REMOVE
+Bad file descriptor; for example, I/O on a descriptor that has been
+closed or reading from a descriptor open only for writing (or vice
+versa).
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No child processes
+@deftypevr Macro int ECHILD
+@comment errno 10 @c DO NOT REMOVE
+There are no child processes.  This error happens on operations that are
+supposed to manipulate child processes, when there aren't any processes
+to manipulate.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Resource deadlock avoided
+@deftypevr Macro int EDEADLK
+@comment errno 11 @c DO NOT REMOVE
+Deadlock avoided; allocating a system resource would have resulted in a
+deadlock situation.  The system does not guarantee that it will notice
+all such situations.  This error means you got lucky and the system
+noticed; it might just hang.  @xref{File Locks}, for an example.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Cannot allocate memory
+@deftypevr Macro int ENOMEM
+@comment errno 12 @c DO NOT REMOVE
+No memory available.  The system cannot allocate more virtual memory
+because its capacity is full.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Permission denied
+@deftypevr Macro int EACCES
+@comment errno 13 @c DO NOT REMOVE
+Permission denied; the file permissions do not allow the attempted operation.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Bad address
+@deftypevr Macro int EFAULT
+@comment errno 14 @c DO NOT REMOVE
+Bad address; an invalid pointer was detected.
+On @gnuhurdsystems{}, this error never happens; you get a signal instead.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Block device required
+@deftypevr Macro int ENOTBLK
+@comment errno 15 @c DO NOT REMOVE
+A file that isn't a block special file was given in a situation that
+requires one.  For example, trying to mount an ordinary file as a file
+system in Unix gives this error.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Device or resource busy
+@deftypevr Macro int EBUSY
+@comment errno 16 @c DO NOT REMOVE
+Resource busy; a system resource that can't be shared is already in use.
+For example, if you try to delete a file that is the root of a currently
+mounted filesystem, you get this error.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: File exists
+@deftypevr Macro int EEXIST
+@comment errno 17 @c DO NOT REMOVE
+File exists; an existing file was specified in a context where it only
+makes sense to specify a new file.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Invalid cross-device link
+@deftypevr Macro int EXDEV
+@comment errno 18 @c DO NOT REMOVE
+An attempt to make an improper link across file systems was detected.
+This happens not only when you use @code{link} (@pxref{Hard Links}) but
+also when you rename a file with @code{rename} (@pxref{Renaming Files}).
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No such device
+@deftypevr Macro int ENODEV
+@comment errno 19 @c DO NOT REMOVE
+The wrong type of device was given to a function that expects a
+particular sort of device.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Not a directory
+@deftypevr Macro int ENOTDIR
+@comment errno 20 @c DO NOT REMOVE
+A file that isn't a directory was specified when a directory is required.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Is a directory
+@deftypevr Macro int EISDIR
+@comment errno 21 @c DO NOT REMOVE
+File is a directory; you cannot open a directory for writing,
+or create or remove hard links to it.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Invalid argument
+@deftypevr Macro int EINVAL
+@comment errno 22 @c DO NOT REMOVE
+Invalid argument.  This is used to indicate various kinds of problems
+with passing the wrong argument to a library function.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Too many open files
+@deftypevr Macro int EMFILE
+@comment errno 24 @c DO NOT REMOVE
+The current process has too many files open and can't open any more.
+Duplicate descriptors do count toward this limit.
+
+In BSD and GNU, the number of open files is controlled by a resource
+limit that can usually be increased.  If you get this error, you might
+want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited;
+@pxref{Limits on Resources}.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Too many open files in system
+@deftypevr Macro int ENFILE
+@comment errno 23 @c DO NOT REMOVE
+There are too many distinct file openings in the entire system.  Note
+that any number of linked channels count as just one file opening; see
+@ref{Linked Channels}.  This error never occurs on @gnuhurdsystems{}.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Inappropriate ioctl for device
+@deftypevr Macro int ENOTTY
+@comment errno 25 @c DO NOT REMOVE
+Inappropriate I/O control operation, such as trying to set terminal
+modes on an ordinary file.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Text file busy
+@deftypevr Macro int ETXTBSY
+@comment errno 26 @c DO NOT REMOVE
+An attempt to execute a file that is currently open for writing, or
+write to a file that is currently being executed.  Often using a
+debugger to run a program is considered having it open for writing and
+will cause this error.  (The name stands for ``text file busy''.)  This
+is not an error on @gnuhurdsystems{}; the text is copied as necessary.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: File too large
+@deftypevr Macro int EFBIG
+@comment errno 27 @c DO NOT REMOVE
+File too big; the size of a file would be larger than allowed by the system.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No space left on device
+@deftypevr Macro int ENOSPC
+@comment errno 28 @c DO NOT REMOVE
+No space left on device; write operation on a file failed because the
+disk is full.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Illegal seek
+@deftypevr Macro int ESPIPE
+@comment errno 29 @c DO NOT REMOVE
+Invalid seek operation (such as on a pipe).
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Read-only file system
+@deftypevr Macro int EROFS
+@comment errno 30 @c DO NOT REMOVE
+An attempt was made to modify something on a read-only file system.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Too many links
+@deftypevr Macro int EMLINK
+@comment errno 31 @c DO NOT REMOVE
+Too many links; the link count of a single file would become too large.
+@code{rename} can cause this error if the file being renamed already has
+as many links as it can take (@pxref{Renaming Files}).
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Broken pipe
+@deftypevr Macro int EPIPE
+@comment errno 32 @c DO NOT REMOVE
+Broken pipe; there is no process reading from the other end of a pipe.
+Every library function that returns this error code also generates a
+@code{SIGPIPE} signal; this signal terminates the program if not handled
+or blocked.  Thus, your program will never actually see @code{EPIPE}
+unless it has handled or blocked @code{SIGPIPE}.
+@end deftypevr
+
+@comment errno.h
+@comment ISO: Numerical argument out of domain
+@deftypevr Macro int EDOM
+@comment errno 33 @c DO NOT REMOVE
+Domain error; used by mathematical functions when an argument value does
+not fall into the domain over which the function is defined.
+@end deftypevr
+
+@comment errno.h
+@comment ISO: Numerical result out of range
+@deftypevr Macro int ERANGE
+@comment errno 34 @c DO NOT REMOVE
+Range error; used by mathematical functions when the result value is
+not representable because of overflow or underflow.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Resource temporarily unavailable
+@deftypevr Macro int EAGAIN
+@comment errno 35 @c DO NOT REMOVE
+Resource temporarily unavailable; the call might work if you try again
+later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
+they are always the same in @theglibc{}.
+
+This error can happen in a few different situations:
+
+@itemize @bullet
+@item
+An operation that would block was attempted on an object that has
+non-blocking mode selected.  Trying the same operation again will block
+until some external condition makes it possible to read, write, or
+connect (whatever the operation).  You can use @code{select} to find out
+when the operation will be possible; @pxref{Waiting for I/O}.
+
+@strong{Portability Note:} In many older Unix systems, this condition
+was indicated by @code{EWOULDBLOCK}, which was a distinct error code
+different from @code{EAGAIN}.  To make your program portable, you should
+check for both codes and treat them the same.
+
+@item
+A temporary resource shortage made an operation impossible.  @code{fork}
+can return this error.  It indicates that the shortage is expected to
+pass, so your program can try the call again later and it may succeed.
+It is probably a good idea to delay for a few seconds before trying it
+again, to allow time for other processes to release scarce resources.
+Such shortages are usually fairly serious and affect the whole system,
+so usually an interactive program should report the error to the user
+and return to its command loop.
+@end itemize
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Operation would block
+@deftypevr Macro int EWOULDBLOCK
+@comment errno EAGAIN @c DO NOT REMOVE
+In @theglibc{}, this is another name for @code{EAGAIN} (above).
+The values are always the same, on every operating system.
+
+C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
+separate error code.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Operation now in progress
+@deftypevr Macro int EINPROGRESS
+@comment errno 36 @c DO NOT REMOVE
+An operation that cannot complete immediately was initiated on an object
+that has non-blocking mode selected.  Some functions that must always
+block (such as @code{connect}; @pxref{Connecting}) never return
+@code{EAGAIN}.  Instead, they return @code{EINPROGRESS} to indicate that
+the operation has begun and will take some time.  Attempts to manipulate
+the object before the call completes return @code{EALREADY}.  You can
+use the @code{select} function to find out when the pending operation
+has completed; @pxref{Waiting for I/O}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Operation already in progress
+@deftypevr Macro int EALREADY
+@comment errno 37 @c DO NOT REMOVE
+An operation is already in progress on an object that has non-blocking
+mode selected.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Socket operation on non-socket
+@deftypevr Macro int ENOTSOCK
+@comment errno 38 @c DO NOT REMOVE
+A file that isn't a socket was specified when a socket is required.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Message too long
+@deftypevr Macro int EMSGSIZE
+@comment errno 40 @c DO NOT REMOVE
+The size of a message sent on a socket was larger than the supported
+maximum size.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Protocol wrong type for socket
+@deftypevr Macro int EPROTOTYPE
+@comment errno 41 @c DO NOT REMOVE
+The socket type does not support the requested communications protocol.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Protocol not available
+@deftypevr Macro int ENOPROTOOPT
+@comment errno 42 @c DO NOT REMOVE
+You specified a socket option that doesn't make sense for the
+particular protocol being used by the socket.  @xref{Socket Options}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Protocol not supported
+@deftypevr Macro int EPROTONOSUPPORT
+@comment errno 43 @c DO NOT REMOVE
+The socket domain does not support the requested communications protocol
+(perhaps because the requested protocol is completely invalid).
+@xref{Creating a Socket}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Socket type not supported
+@deftypevr Macro int ESOCKTNOSUPPORT
+@comment errno 44 @c DO NOT REMOVE
+The socket type is not supported.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Operation not supported
+@deftypevr Macro int EOPNOTSUPP
+@comment errno 45 @c DO NOT REMOVE
+The operation you requested is not supported.  Some socket functions
+don't make sense for all types of sockets, and others may not be
+implemented for all communications protocols.  On @gnuhurdsystems{}, this
+error can happen for many calls when the object does not support the
+particular operation; it is a generic indication that the server knows
+nothing to do for that call.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Protocol family not supported
+@deftypevr Macro int EPFNOSUPPORT
+@comment errno 46 @c DO NOT REMOVE
+The socket communications protocol family you requested is not supported.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Address family not supported by protocol
+@deftypevr Macro int EAFNOSUPPORT
+@comment errno 47 @c DO NOT REMOVE
+The address family specified for a socket is not supported; it is
+inconsistent with the protocol being used on the socket.  @xref{Sockets}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Address already in use
+@deftypevr Macro int EADDRINUSE
+@comment errno 48 @c DO NOT REMOVE
+The requested socket address is already in use.  @xref{Socket Addresses}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Cannot assign requested address
+@deftypevr Macro int EADDRNOTAVAIL
+@comment errno 49 @c DO NOT REMOVE
+The requested socket address is not available; for example, you tried
+to give a socket a name that doesn't match the local host name.
+@xref{Socket Addresses}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Network is down
+@deftypevr Macro int ENETDOWN
+@comment errno 50 @c DO NOT REMOVE
+A socket operation failed because the network was down.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Network is unreachable
+@deftypevr Macro int ENETUNREACH
+@comment errno 51 @c DO NOT REMOVE
+A socket operation failed because the subnet containing the remote host
+was unreachable.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Network dropped connection on reset
+@deftypevr Macro int ENETRESET
+@comment errno 52 @c DO NOT REMOVE
+A network connection was reset because the remote host crashed.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Software caused connection abort
+@deftypevr Macro int ECONNABORTED
+@comment errno 53 @c DO NOT REMOVE
+A network connection was aborted locally.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Connection reset by peer
+@deftypevr Macro int ECONNRESET
+@comment errno 54 @c DO NOT REMOVE
+A network connection was closed for reasons outside the control of the
+local host, such as by the remote machine rebooting or an unrecoverable
+protocol violation.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: No buffer space available
+@deftypevr Macro int ENOBUFS
+@comment errno 55 @c DO NOT REMOVE
+The kernel's buffers for I/O operations are all in use.  In GNU, this
+error is always synonymous with @code{ENOMEM}; you may get one or the
+other from network operations.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Transport endpoint is already connected
+@deftypevr Macro int EISCONN
+@comment errno 56 @c DO NOT REMOVE
+You tried to connect a socket that is already connected.
+@xref{Connecting}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Transport endpoint is not connected
+@deftypevr Macro int ENOTCONN
+@comment errno 57 @c DO NOT REMOVE
+The socket is not connected to anything.  You get this error when you
+try to transmit data over a socket, without first specifying a
+destination for the data.  For a connectionless socket (for datagram
+protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Destination address required
+@deftypevr Macro int EDESTADDRREQ
+@comment errno 39 @c DO NOT REMOVE
+No default destination address was set for the socket.  You get this
+error when you try to transmit data over a connectionless socket,
+without first specifying a destination for the data with @code{connect}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Cannot send after transport endpoint shutdown
+@deftypevr Macro int ESHUTDOWN
+@comment errno 58 @c DO NOT REMOVE
+The socket has already been shut down.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Too many references: cannot splice
+@deftypevr Macro int ETOOMANYREFS
+@comment errno 59 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Connection timed out
+@deftypevr Macro int ETIMEDOUT
+@comment errno 60 @c DO NOT REMOVE
+A socket operation with a specified timeout received no response during
+the timeout period.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Connection refused
+@deftypevr Macro int ECONNREFUSED
+@comment errno 61 @c DO NOT REMOVE
+A remote host refused to allow the network connection (typically because
+it is not running the requested service).
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Too many levels of symbolic links
+@deftypevr Macro int ELOOP
+@comment errno 62 @c DO NOT REMOVE
+Too many levels of symbolic links were encountered in looking up a file name.
+This often indicates a cycle of symbolic links.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: File name too long
+@deftypevr Macro int ENAMETOOLONG
+@comment errno 63 @c DO NOT REMOVE
+Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
+Files}) or host name too long (in @code{gethostname} or
+@code{sethostname}; @pxref{Host Identification}).
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Host is down
+@deftypevr Macro int EHOSTDOWN
+@comment errno 64 @c DO NOT REMOVE
+The remote host for a requested network connection is down.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: No route to host
+@deftypevr Macro int EHOSTUNREACH
+@comment errno 65 @c DO NOT REMOVE
+The remote host for a requested network connection is not reachable.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Directory not empty
+@deftypevr Macro int ENOTEMPTY
+@comment errno 66 @c DO NOT REMOVE
+Directory not empty, where an empty directory was expected.  Typically,
+this error occurs when you are trying to delete a directory.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Too many processes
+@deftypevr Macro int EPROCLIM
+@comment errno 67 @c DO NOT REMOVE
+This means that the per-user limit on new process would be exceeded by
+an attempted @code{fork}.  @xref{Limits on Resources}, for details on
+the @code{RLIMIT_NPROC} limit.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Too many users
+@deftypevr Macro int EUSERS
+@comment errno 68 @c DO NOT REMOVE
+The file quota system is confused because there are too many users.
+@c This can probably happen in a GNU system when using NFS.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Disk quota exceeded
+@deftypevr Macro int EDQUOT
+@comment errno 69 @c DO NOT REMOVE
+The user's disk quota was exceeded.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Stale file handle
+@deftypevr Macro int ESTALE
+@comment errno 70 @c DO NOT REMOVE
+Stale file handle.  This indicates an internal confusion in the
+file system which is due to file system rearrangements on the server host
+for NFS file systems or corruption in other file systems.
+Repairing this condition usually requires unmounting, possibly repairing
+and remounting the file system.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Object is remote
+@deftypevr Macro int EREMOTE
+@comment errno 71 @c DO NOT REMOVE
+An attempt was made to NFS-mount a remote file system with a file name that
+already specifies an NFS-mounted file.
+(This is an error on some operating systems, but we expect it to work
+properly on @gnuhurdsystems{}, making this error code impossible.)
+@end deftypevr
+
+@comment errno.h
+@comment BSD: RPC struct is bad
+@deftypevr Macro int EBADRPC
+@comment errno 72 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: RPC version wrong
+@deftypevr Macro int ERPCMISMATCH
+@comment errno 73 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: RPC program not available
+@deftypevr Macro int EPROGUNAVAIL
+@comment errno 74 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: RPC program version wrong
+@deftypevr Macro int EPROGMISMATCH
+@comment errno 75 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: RPC bad procedure for program
+@deftypevr Macro int EPROCUNAVAIL
+@comment errno 76 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: No locks available
+@deftypevr Macro int ENOLCK
+@comment errno 77 @c DO NOT REMOVE
+No locks available.  This is used by the file locking facilities; see
+@ref{File Locks}.  This error is never generated by @gnuhurdsystems{}, but
+it can result from an operation to an NFS server running another
+operating system.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Inappropriate file type or format
+@deftypevr Macro int EFTYPE
+@comment errno 79 @c DO NOT REMOVE
+Inappropriate file type or format.  The file was the wrong type for the
+operation, or a data file had the wrong format.
+
+On some systems @code{chmod} returns this error if you try to set the
+sticky bit on a non-directory file; @pxref{Setting Permissions}.
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Authentication error
+@deftypevr Macro int EAUTH
+@comment errno 80 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment BSD: Need authenticator
+@deftypevr Macro int ENEEDAUTH
+@comment errno 81 @c DO NOT REMOVE
+???
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Function not implemented
+@deftypevr Macro int ENOSYS
+@comment errno 78 @c DO NOT REMOVE
+Function not implemented.  This indicates that the function called is
+not implemented at all, either in the C library itself or in the
+operating system.  When you get this error, you can be sure that this
+particular function will always fail with @code{ENOSYS} unless you
+install a new version of the C library or the operating system.
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Not supported
+@deftypevr Macro int ENOTSUP
+@comment errno 118 @c DO NOT REMOVE
+Not supported.  A function returns this error when certain parameter
+values are valid, but the functionality they request is not available.
+This can mean that the function does not implement a particular command
+or option value or flag bit at all.  For functions that operate on some
+object given in a parameter, such as a file descriptor or a port, it
+might instead mean that only @emph{that specific object} (file
+descriptor, port, etc.) is unable to support the other parameters given;
+different file descriptors might support different ranges of parameter
+values.
+
+If the entire function is not available at all in the implementation,
+it returns @code{ENOSYS} instead.
+@end deftypevr
+
+@comment errno.h
+@comment ISO: Invalid or incomplete multibyte or wide character
+@deftypevr Macro int EILSEQ
+@comment errno 106 @c DO NOT REMOVE
+While decoding a multibyte character the function came along an invalid
+or an incomplete sequence of bytes or the given wide character is invalid.
+@end deftypevr
+
+@comment errno.h
+@comment GNU: Inappropriate operation for background process
+@deftypevr Macro int EBACKGROUND
+@comment errno 100 @c DO NOT REMOVE
+On @gnuhurdsystems{}, servers supporting the @code{term} protocol return
+this error for certain operations when the caller is not in the
+foreground process group of the terminal.  Users do not usually see this
+error because functions such as @code{read} and @code{write} translate
+it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
+for information on process groups and these signals.
+@end deftypevr
+
+@comment errno.h
+@comment GNU: Translator died
+@deftypevr Macro int EDIED
+@comment errno 101 @c DO NOT REMOVE
+On @gnuhurdsystems{}, opening a file returns this error when the file is
+translated by a program and the translator program dies while starting
+up, before it has connected to the file.
+@end deftypevr
+
+@comment errno.h
+@comment GNU: ?
+@deftypevr Macro int ED
+@comment errno 102 @c DO NOT REMOVE
+The experienced user will know what is wrong.
+@c This error code is a joke.  Its perror text is part of the joke.
+@c Don't change it.
+@end deftypevr
+
+@comment errno.h
+@comment GNU: You really blew it this time
+@deftypevr Macro int EGREGIOUS
+@comment errno 103 @c DO NOT REMOVE
+You did @strong{what}?
+@end deftypevr
+
+@comment errno.h
+@comment GNU: Computer bought the farm
+@deftypevr Macro int EIEIO
+@comment errno 104 @c DO NOT REMOVE
+Go home and have a glass of warm, dairy-fresh milk.
+@end deftypevr
+
+@comment errno.h
+@comment GNU: Gratuitous error
+@deftypevr Macro int EGRATUITOUS
+@comment errno 105 @c DO NOT REMOVE
+This error code has no purpose.
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Bad message
+@deftypevr Macro int EBADMSG
+@comment errno 107
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Identifier removed
+@deftypevr Macro int EIDRM
+@comment errno 108
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Multihop attempted
+@deftypevr Macro int EMULTIHOP
+@comment errno 109
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: No data available
+@deftypevr Macro int ENODATA
+@comment errno 110
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Link has been severed
+@deftypevr Macro int ENOLINK
+@comment errno 111
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: No message of desired type
+@deftypevr Macro int ENOMSG
+@comment errno 112
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Out of streams resources
+@deftypevr Macro int ENOSR
+@comment errno 113
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Device not a stream
+@deftypevr Macro int ENOSTR
+@comment errno 114
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Value too large for defined data type
+@deftypevr Macro int EOVERFLOW
+@comment errno 115
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Protocol error
+@deftypevr Macro int EPROTO
+@comment errno 116
+@end deftypevr
+
+@comment errno.h
+@comment XOPEN: Timer expired
+@deftypevr Macro int ETIME
+@comment errno 117
+@end deftypevr
+
+@comment errno.h
+@comment POSIX.1: Operation canceled
+@deftypevr Macro int ECANCELED
+@comment errno 119
+Operation canceled; an asynchronous operation was canceled before it
+completed.  @xref{Asynchronous I/O}.  When you call @code{aio_cancel},
+the normal result is for the operations affected to complete with this
+error; @pxref{Cancel AIO Operations}.
+@end deftypevr
+
+
+@emph{The following error codes are defined by the Linux/i386 kernel.
+They are not yet documented.}
+
+@comment errno.h
+@comment Linux???: Interrupted system call should be restarted
+@deftypevr Macro int ERESTART
+@comment errno ???/85
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Channel number out of range
+@deftypevr Macro int ECHRNG
+@comment errno ???/44
+@end deftypevr
+
+@comment errno.h
+@comment Obsolete: Level 2 not synchronized
+@deftypevr Macro int EL2NSYNC
+@comment errno ???/45
+@end deftypevr
+
+@comment errno.h
+@comment Obsolete: Level 3 halted
+@deftypevr Macro int EL3HLT
+@comment errno ???/46
+@end deftypevr
+
+@comment errno.h
+@comment Obsolete: Level 3 reset
+@deftypevr Macro int EL3RST
+@comment errno ???/47
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Link number out of range
+@deftypevr Macro int ELNRNG
+@comment errno ???/48
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Protocol driver not attached
+@deftypevr Macro int EUNATCH
+@comment errno ???/49
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: No CSI structure available
+@deftypevr Macro int ENOCSI
+@comment errno ???/50
+@end deftypevr
+
+@comment errno.h
+@comment Obsolete: Level 2 halted
+@deftypevr Macro int EL2HLT
+@comment errno ???/51
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Invalid exchange
+@deftypevr Macro int EBADE
+@comment errno ???/52
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Invalid request descriptor
+@deftypevr Macro int EBADR
+@comment errno ???/53
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Exchange full
+@deftypevr Macro int EXFULL
+@comment errno ???/54
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: No anode
+@deftypevr Macro int ENOANO
+@comment errno ???/55
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Invalid request code
+@deftypevr Macro int EBADRQC
+@comment errno ???/56
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Invalid slot
+@deftypevr Macro int EBADSLT
+@comment errno ???/57
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: File locking deadlock error
+@deftypevr Macro int EDEADLOCK
+@comment errno ???/58
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Bad font file format
+@deftypevr Macro int EBFONT
+@comment errno ???/59
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Machine is not on the network
+@deftypevr Macro int ENONET
+@comment errno ???/64
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Package not installed
+@deftypevr Macro int ENOPKG
+@comment errno ???/65
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Advertise error
+@deftypevr Macro int EADV
+@comment errno ???/68
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Srmount error
+@deftypevr Macro int ESRMNT
+@comment errno ???/69
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Communication error on send
+@deftypevr Macro int ECOMM
+@comment errno ???/70
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: RFS specific error
+@deftypevr Macro int EDOTDOT
+@comment errno ???/73
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Name not unique on network
+@deftypevr Macro int ENOTUNIQ
+@comment errno ???/76
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: File descriptor in bad state
+@deftypevr Macro int EBADFD
+@comment errno ???/77
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Remote address changed
+@deftypevr Macro int EREMCHG
+@comment errno ???/78
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Can not access a needed shared library
+@deftypevr Macro int ELIBACC
+@comment errno ???/79
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Accessing a corrupted shared library
+@deftypevr Macro int ELIBBAD
+@comment errno ???/80
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: .lib section in a.out corrupted
+@deftypevr Macro int ELIBSCN
+@comment errno ???/81
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Attempting to link in too many shared libraries
+@deftypevr Macro int ELIBMAX
+@comment errno ???/82
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Cannot exec a shared library directly
+@deftypevr Macro int ELIBEXEC
+@comment errno ???/83
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Streams pipe error
+@deftypevr Macro int ESTRPIPE
+@comment errno ???/86
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Structure needs cleaning
+@deftypevr Macro int EUCLEAN
+@comment errno ???/117
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Not a XENIX named type file
+@deftypevr Macro int ENOTNAM
+@comment errno ???/118
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: No XENIX semaphores available
+@deftypevr Macro int ENAVAIL
+@comment errno ???/119
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Is a named type file
+@deftypevr Macro int EISNAM
+@comment errno ???/120
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Remote I/O error
+@deftypevr Macro int EREMOTEIO
+@comment errno ???/121
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: No medium found
+@deftypevr Macro int ENOMEDIUM
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux???: Wrong medium type
+@deftypevr Macro int EMEDIUMTYPE
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Required key not available
+@deftypevr Macro int ENOKEY
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Key has expired
+@deftypevr Macro int EKEYEXPIRED
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Key has been revoked
+@deftypevr Macro int EKEYREVOKED
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Key was rejected by service
+@deftypevr Macro int EKEYREJECTED
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Owner died
+@deftypevr Macro int EOWNERDEAD
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: State not recoverable
+@deftypevr Macro int ENOTRECOVERABLE
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Operation not possible due to RF-kill
+@deftypevr Macro int ERFKILL
+@comment errno ???/???
+@end deftypevr
+
+@comment errno.h
+@comment Linux: Memory page has hardware error
+@deftypevr Macro int EHWPOISON
+@comment errno ???/???
+@end deftypevr
+
+@node Error Messages,  , Error Codes, Error Reporting
+@section Error Messages
+
+The library has functions and variables designed to make it easy for
+your program to report informative error messages in the customary
+format about the failure of a library call.  The functions
+@code{strerror} and @code{perror} give you the standard error message
+for a given error code; the variable
+@w{@code{program_invocation_short_name}} gives you convenient access to the
+name of the program that encountered the error.
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strerror (int @var{errnum})
+@safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}}
+@c Calls strerror_r with a static buffer allocated with malloc on the
+@c first use.
+The @code{strerror} function maps the error code (@pxref{Checking for
+Errors}) specified by the @var{errnum} argument to a descriptive error
+message string.  The return value is a pointer to this string.
+
+The value @var{errnum} normally comes from the variable @code{errno}.
+
+You should not modify the string returned by @code{strerror}.  Also, if
+you make subsequent calls to @code{strerror}, the string might be
+overwritten.  (But it's guaranteed that no library function ever calls
+@code{strerror} behind your back.)
+
+The function @code{strerror} is declared in @file{string.h}.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}}
+The @code{strerror_r} function works like @code{strerror} but instead of
+returning the error message in a statically allocated buffer shared by
+all threads in the process, it returns a private copy for the
+thread.  This might be either some permanent global data or a message
+string in the user supplied buffer starting at @var{buf} with the
+length of @var{n} bytes.
+
+At most @var{n} characters are written (including the NUL byte) so it is
+up to the user to select the buffer large enough.
+
+This function should always be used in multi-threaded programs since
+there is no way to guarantee the string returned by @code{strerror}
+really belongs to the last call of the current thread.
+
+This function @code{strerror_r} is a GNU extension and it is declared in
+@file{string.h}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun void perror (const char *@var{message})
+@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Besides strerror_r's and some of fprintf's issues, if stderr is not
+@c oriented yet, create a new stream with a dup of stderr's fd and write
+@c to that instead of stderr, to avoid orienting it.
+This function prints an error message to the stream @code{stderr};
+see @ref{Standard Streams}.  The orientation of @code{stderr} is not
+changed.
+
+If you call @code{perror} with a @var{message} that is either a null
+pointer or an empty string, @code{perror} just prints the error message
+corresponding to @code{errno}, adding a trailing newline.
+
+If you supply a non-null @var{message} argument, then @code{perror}
+prefixes its output with this string.  It adds a colon and a space
+character to separate the @var{message} from the error string corresponding
+to @code{errno}.
+
+The function @code{perror} is declared in @file{stdio.h}.
+@end deftypefun
+
+@code{strerror} and @code{perror} produce the exact same message for any
+given error code; the precise text varies from system to system.  With
+@theglibc{}, the messages are fairly short; there are no multi-line
+messages or embedded newlines.  Each error message begins with a capital
+letter and does not include any terminating punctuation.
+
+@cindex program name
+@cindex name of running program
+Many programs that don't read input from the terminal are designed to
+exit if any system call fails.  By convention, the error message from
+such a program should start with the program's name, sans directories.
+You can find that name in the variable
+@code{program_invocation_short_name}; the full file name is stored the
+variable @code{program_invocation_name}.
+
+@comment errno.h
+@comment GNU
+@deftypevar {char *} program_invocation_name
+This variable's value is the name that was used to invoke the program
+running in the current process.  It is the same as @code{argv[0]}.  Note
+that this is not necessarily a useful file name; often it contains no
+directory names.  @xref{Program Arguments}.
+
+This variable is a GNU extension and is declared in @file{errno.h}.
+@end deftypevar
+
+@comment errno.h
+@comment GNU
+@deftypevar {char *} program_invocation_short_name
+This variable's value is the name that was used to invoke the program
+running in the current process, with directory names removed.  (That is
+to say, it is the same as @code{program_invocation_name} minus
+everything up to the last slash, if any.)
+
+This variable is a GNU extension and is declared in @file{errno.h}.
+@end deftypevar
+
+The library initialization code sets up both of these variables before
+calling @code{main}.
+
+@strong{Portability Note:} If you want your program to work with
+non-GNU libraries, you must save the value of @code{argv[0]} in
+@code{main}, and then strip off the directory names yourself.  We
+added these extensions to make it possible to write self-contained
+error-reporting subroutines that require no explicit cooperation from
+@code{main}.
+
+Here is an example showing how to handle failure to open a file
+correctly.  The function @code{open_sesame} tries to open the named file
+for reading and returns a stream if successful.  The @code{fopen}
+library function returns a null pointer if it couldn't open the file for
+some reason.  In that situation, @code{open_sesame} constructs an
+appropriate error message using the @code{strerror} function, and
+terminates the program.  If we were going to make some other library
+calls before passing the error code to @code{strerror}, we'd have to
+save it in a local variable instead, because those other library
+functions might overwrite @code{errno} in the meantime.
+
+@smallexample
+#define _GNU_SOURCE
+
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+FILE *
+open_sesame (char *name)
+@{
+  FILE *stream;
+
+  errno = 0;
+  stream = fopen (name, "r");
+  if (stream == NULL)
+    @{
+      fprintf (stderr, "%s: Couldn't open file %s; %s\n",
+               program_invocation_short_name, name, strerror (errno));
+      exit (EXIT_FAILURE);
+    @}
+  else
+    return stream;
+@}
+@end smallexample
+
+Using @code{perror} has the advantage that the function is portable and
+available on all systems implementing @w{ISO C}.  But often the text
+@code{perror} generates is not what is wanted and there is no way to
+extend or change what @code{perror} does.  The GNU coding standard, for
+instance, requires error messages to be preceded by the program name and
+programs which read some input files should provide information
+about the input file name and the line number in case an error is
+encountered while reading the file.  For these occasions there are two
+functions available which are widely used throughout the GNU project.
+These functions are declared in @file{error.h}.
+
+@comment error.h
+@comment GNU
+@deftypefun void error (int @var{status}, int @var{errnum}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acsafe{}}
+@c Cancellation is disabled throughout the execution.  It flushes stdout
+@c and then holds a lock on stderr while printing the program name and
+@c then running error_tail.  The non-wide case just runs vfprintf; the
+@c wide case converts the message to an alloca/malloc-allocated buffer
+@c with mbsrtowcs, then prints it with vfwprintf.  Afterwards,
+@c print_errno_message calls strerror_r and fxprintf.
+The @code{error} function can be used to report general problems during
+program execution.  The @var{format} argument is a format string just
+like those given to the @code{printf} family of functions.  The
+arguments required for the format can follow the @var{format} parameter.
+Just like @code{perror}, @code{error} also can report an error code in
+textual form.  But unlike @code{perror} the error value is explicitly
+passed to the function in the @var{errnum} parameter.  This eliminates
+the problem mentioned above that the error reporting function must be
+called immediately after the function causing the error since otherwise
+@code{errno} might have a different value.
+
+The @code{error} prints first the program name.  If the application
+defined a global variable @code{error_print_progname} and points it to a
+function this function will be called to print the program name.
+Otherwise the string from the global variable @code{program_name} is
+used.  The program name is followed by a colon and a space which in turn
+is followed by the output produced by the format string.  If the
+@var{errnum} parameter is non-zero the format string output is followed
+by a colon and a space, followed by the error message for the error code
+@var{errnum}.  In any case is the output terminated with a newline.
+
+The output is directed to the @code{stderr} stream.  If the
+@code{stderr} wasn't oriented before the call it will be narrow-oriented
+afterwards.
+
+The function will return unless the @var{status} parameter has a
+non-zero value.  In this case the function will call @code{exit} with
+the @var{status} value for its parameter and therefore never return.  If
+@code{error} returns the global variable @code{error_message_count} is
+incremented by one to keep track of the number of errors reported.
+@end deftypefun
+
+@comment error.h
+@comment GNU
+@deftypefun void error_at_line (int @var{status}, int @var{errnum}, const char *@var{fname}, unsigned int @var{lineno}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtunsafe{@mtasurace{:error_at_line/error_one_per_line} @mtslocale{}}@asunsafe{@asucorrupt{} @asuheap{} @asuintl{}}@acunsafe{@acucorrupt{/error_one_per_line}}}
+@c The error_one_per_line variable is accessed (without any form of
+@c synchronization, but since it's an int used once, it should be safe
+@c enough) and, if this mode is enabled, static variables used to hold
+@c the last printed file name and line number are accessed and modified
+@c without synchronization; the update is not atomic and it occurs
+@c before disabling cancellation, so it can be interrupted after only
+@c one of the two variables is modified.  After that, it's very much
+@c like error.
+
+The @code{error_at_line} function is very similar to the @code{error}
+function.  The only difference are the additional parameters @var{fname}
+and @var{lineno}.  The handling of the other parameters is identical to
+that of @code{error} except that between the program name and the string
+generated by the format string additional text is inserted.
+
+Directly following the program name a colon, followed by the file name
+pointer to by @var{fname}, another colon, and a value of @var{lineno} is
+printed.
+
+This additional output of course is meant to be used to locate an error
+in an input file (like a programming language source code file etc).
+
+If the global variable @code{error_one_per_line} is set to a non-zero
+value @code{error_at_line} will avoid printing consecutive messages for
+the same file and line.  Repetition which are not directly following
+each other are not caught.
+
+Just like @code{error} this function only returned if @var{status} is
+zero.  Otherwise @code{exit} is called with the non-zero value.  If
+@code{error} returns the global variable @code{error_message_count} is
+incremented by one to keep track of the number of errors reported.
+@end deftypefun
+
+As mentioned above the @code{error} and @code{error_at_line} functions
+can be customized by defining a variable named
+@code{error_print_progname}.
+
+@comment error.h
+@comment GNU
+@deftypevar {void (*error_print_progname)} (void)
+If the @code{error_print_progname} variable is defined to a non-zero
+value the function pointed to is called by @code{error} or
+@code{error_at_line}.  It is expected to print the program name or do
+something similarly useful.
+
+The function is expected to be print to the @code{stderr} stream and
+must be able to handle whatever orientation the stream has.
+
+The variable is global and shared by all threads.
+@end deftypevar
+
+@comment error.h
+@comment GNU
+@deftypevar {unsigned int} error_message_count
+The @code{error_message_count} variable is incremented whenever one of
+the functions @code{error} or @code{error_at_line} returns.  The
+variable is global and shared by all threads.
+@end deftypevar
+
+@comment error.h
+@comment GNU
+@deftypevar int error_one_per_line
+The @code{error_one_per_line} variable influences only
+@code{error_at_line}.  Normally the @code{error_at_line} function
+creates output for every invocation.  If @code{error_one_per_line} is
+set to a non-zero value @code{error_at_line} keeps track of the last
+file name and line number for which an error was reported and avoid
+directly following messages for the same file and line.  This variable
+is global and shared by all threads.
+@end deftypevar
+
+@noindent
+A program which read some input file and reports errors in it could look
+like this:
+
+@smallexample
+@{
+  char *line = NULL;
+  size_t len = 0;
+  unsigned int lineno = 0;
+
+  error_message_count = 0;
+  while (! feof_unlocked (fp))
+    @{
+      ssize_t n = getline (&line, &len, fp);
+      if (n <= 0)
+        /* @r{End of file or error.}  */
+        break;
+      ++lineno;
+
+      /* @r{Process the line.}  */
+      @dots{}
+
+      if (@r{Detect error in line})
+        error_at_line (0, errval, filename, lineno,
+                       "some error text %s", some_variable);
+    @}
+
+  if (error_message_count != 0)
+    error (EXIT_FAILURE, 0, "%u errors found", error_message_count);
+@}
+@end smallexample
+
+@code{error} and @code{error_at_line} are clearly the functions of
+choice and enable the programmer to write applications which follow the
+GNU coding standard.  @Theglibc{} additionally contains functions which
+are used in BSD for the same purpose.  These functions are declared in
+@file{err.h}.  It is generally advised to not use these functions.  They
+are included only for compatibility.
+
+@comment err.h
+@comment BSD
+@deftypefun void warn (const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Just calls vwarn with the va_list.
+The @code{warn} function is roughly equivalent to a call like
+@smallexample
+  error (0, errno, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void vwarn (const char *@var{format}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c While holding stderr's recursive lock, it prints the programname, the
+@c given message, and the error string with fw?printf's %m.  When the
+@c stream is wide, convert_and_print converts the format string to an
+@c alloca/malloc-created buffer using mbsrtowcs and then calls fwprintf.
+The @code{vwarn} function is just like @code{warn} except that the
+parameters for the handling of the format string @var{format} are passed
+in as a value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void warnx (const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as warn, but without the strerror translation issues.
+The @code{warnx} function is roughly equivalent to a call like
+@smallexample
+  error (0, 0, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used.  The difference to @code{warn} is that no error number
+string is printed.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void vwarnx (const char *@var{format}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as vwarn, but without the strerror translation issues.
+The @code{vwarnx} function is just like @code{warnx} except that the
+parameters for the handling of the format string @var{format} are passed
+in as a value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void err (int @var{status}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as warn followed by exit.
+The @code{err} function is roughly equivalent to a call like
+@smallexample
+  error (status, errno, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used and that the program is exited even if @var{status} is zero.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as vwarn followed by exit.
+The @code{verr} function is just like @code{err} except that the
+parameters for the handling of the format string @var{format} are passed
+in as a value of type @code{va_list}.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void errx (int @var{status}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as warnx followed by exit.
+The @code{errx} function is roughly equivalent to a call like
+@smallexample
+  error (status, 0, format, @r{the parameters})
+@end smallexample
+@noindent
+except that the global variables @code{error} respects and modifies
+are not used and that the program is exited even if @var{status}
+is zero.  The difference to @code{err} is that no error number
+string is printed.
+@end deftypefun
+
+@comment err.h
+@comment BSD
+@deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c Same as vwarnx followed by exit.
+The @code{verrx} function is just like @code{errx} except that the
+parameters for the handling of the format string @var{format} are passed
+in as a value of type @code{va_list}.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/README b/ap/libc/glibc/glibc-2.23/manual/examples/README
new file mode 100644
index 0000000..7d0070f
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/README
@@ -0,0 +1,8 @@
+These are source files for example code that appears in The GNU C
+Library Reference Manual.
+
+While the manual itself is licensed under the terms of the GNU Free
+Documentation License, you can use these source files on their own
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; version 2 of the License, or (at your
+option) any later version.
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/add.c b/ap/libc/glibc/glibc-2.23/manual/examples/add.c
new file mode 100644
index 0000000..327ee5a
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/add.c
@@ -0,0 +1,47 @@
+/* Example of a Variadic Function
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdarg.h>
+#include <stdio.h>
+
+int
+add_em_up (int count,...)
+{
+  va_list ap;
+  int i, sum;
+
+  va_start (ap, count);		/* Initialize the argument list. */
+
+  sum = 0;
+  for (i = 0; i < count; i++)
+    sum += va_arg (ap, int);	/* Get the next argument value. */
+
+  va_end (ap);			/* Clean up. */
+  return sum;
+}
+
+int
+main (void)
+{
+  /* This call prints 16. */
+  printf ("%d\n", add_em_up (3, 5, 5, 6));
+
+  /* This call prints 55. */
+  printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex1.c b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex1.c
new file mode 100644
index 0000000..4a7b811
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex1.c
@@ -0,0 +1,31 @@
+/* Argp example #1 -- a minimal program using argp
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/* This is (probably) the smallest possible program that
+   uses argp.  It won't do much except give an error
+   messages and exit when there are any arguments, and print
+   a (rather pointless) messages for --help.  */
+
+#include <stdlib.h>
+#include <argp.h>
+
+int
+main (int argc, char **argv)
+{
+  argp_parse (0, argc, argv, 0, 0, 0);
+  exit (0);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex2.c b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex2.c
new file mode 100644
index 0000000..f7e6d54
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex2.c
@@ -0,0 +1,61 @@
+/* Argp example #2 -- a pretty minimal program using argp
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/* This program doesn't use any options or arguments, but uses
+   argp to be compliant with the GNU standard command line
+   format.
+
+   In addition to making sure no arguments are given, and
+   implementing a --help option, this example will have a
+   --version option, and will put the given documentation string
+   and bug address in the --help output, as per GNU standards.
+
+   The variable ARGP contains the argument parser specification;
+   adding fields to this structure is the way most parameters are
+   passed to argp_parse (the first three fields are usually used,
+   but not in this small program).  There are also two global
+   variables that argp knows about defined here,
+   ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
+   global variables because they will almost always be constant
+   for a given program, even if it uses different argument
+   parsers for various tasks).  */
+
+#include <stdlib.h>
+#include <argp.h>
+
+const char *argp_program_version =
+  "argp-ex2 1.0";
+const char *argp_program_bug_address =
+  "<bug-gnu-utils@@gnu.org>";
+
+/* Program documentation.  */
+static char doc[] =
+  "Argp example #2 -- a pretty minimal program using argp";
+
+/* Our argument parser.  The @code{options}, @code{parser}, and
+   @code{args_doc} fields are zero because we have neither options or
+   arguments; @code{doc} and @code{argp_program_bug_address} will be
+   used in the output for @samp{--help}, and the @samp{--version}
+   option will print out @code{argp_program_version}.  */
+static struct argp argp = { 0, 0, 0, doc };
+
+int
+main (int argc, char **argv)
+{
+  argp_parse (&argp, argc, argv, 0, 0, 0);
+  exit (0);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex3.c b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex3.c
new file mode 100644
index 0000000..c2cf326
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex3.c
@@ -0,0 +1,169 @@
+/* Argp example #3 -- a program with options and arguments using argp
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/* This program uses the same features as example 2, and uses options and
+   arguments.
+
+   We now use the first four fields in ARGP, so here's a description of them:
+     OPTIONS  -- A pointer to a vector of struct argp_option (see below)
+     PARSER   -- A function to parse a single option, called by argp
+     ARGS_DOC -- A string describing how the non-option arguments should look
+     DOC      -- A descriptive string about this program; if it contains a
+                 vertical tab character (\v), the part after it will be
+                 printed *following* the options
+
+   The function PARSER takes the following arguments:
+     KEY  -- An integer specifying which option this is (taken
+             from the KEY field in each struct argp_option), or
+             a special key specifying something else; the only
+             special keys we use here are ARGP_KEY_ARG, meaning
+             a non-option argument, and ARGP_KEY_END, meaning
+             that all arguments have been parsed
+     ARG  -- For an option KEY, the string value of its
+             argument, or NULL if it has none
+     STATE-- A pointer to a struct argp_state, containing
+             various useful information about the parsing state; used here
+             are the INPUT field, which reflects the INPUT argument to
+             argp_parse, and the ARG_NUM field, which is the number of the
+             current non-option argument being parsed
+   It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
+   given KEY wasn't recognized, or an errno value indicating some other
+   error.
+
+   Note that in this example, main uses a structure to communicate with the
+   parse_opt function, a pointer to which it passes in the INPUT argument to
+   argp_parse.  Of course, it's also possible to use global variables
+   instead, but this is somewhat more flexible.
+
+   The OPTIONS field contains a pointer to a vector of struct argp_option's;
+   that structure has the following fields (if you assign your option
+   structures using array initialization like this example, unspecified
+   fields will be defaulted to 0, and need not be specified):
+     NAME   -- The name of this option's long option (may be zero)
+     KEY    -- The KEY to pass to the PARSER function when parsing this option,
+               *and* the name of this option's short option, if it is a
+               printable ascii character
+     ARG    -- The name of this option's argument, if any
+     FLAGS  -- Flags describing this option; some of them are:
+                 OPTION_ARG_OPTIONAL -- The argument to this option is optional
+                 OPTION_ALIAS        -- This option is an alias for the
+                                        previous option
+                 OPTION_HIDDEN       -- Don't show this option in --help output
+     DOC    -- A documentation string for this option, shown in --help output
+
+   An options vector should be terminated by an option with all fields zero. */
+
+#include <stdlib.h>
+#include <argp.h>
+
+const char *argp_program_version =
+  "argp-ex3 1.0";
+const char *argp_program_bug_address =
+  "<bug-gnu-utils@@gnu.org>";
+
+/* Program documentation.  */
+static char doc[] =
+  "Argp example #3 -- a program with options and arguments using argp";
+
+/* A description of the arguments we accept.  */
+static char args_doc[] = "ARG1 ARG2";
+
+/* The options we understand.  */
+static struct argp_option options[] = {
+  {"verbose",  'v', 0,      0,  "Produce verbose output" },
+  {"quiet",    'q', 0,      0,  "Don't produce any output" },
+  {"silent",   's', 0,      OPTION_ALIAS },
+  {"output",   'o', "FILE", 0,
+   "Output to FILE instead of standard output" },
+  { 0 }
+};
+
+/* Used by @code{main} to communicate with @code{parse_opt}.  */
+struct arguments
+{
+  char *args[2];		/* @var{arg1} & @var{arg2} */
+  int silent, verbose;
+  char *output_file;
+};
+
+/* Parse a single option.  */
+static error_t
+parse_opt (int key, char *arg, struct argp_state *state)
+{
+  /* Get the @var{input} argument from @code{argp_parse}, which we
+     know is a pointer to our arguments structure.  */
+  struct arguments *arguments = state->input;
+
+  switch (key)
+    {
+    case 'q': case 's':
+      arguments->silent = 1;
+      break;
+    case 'v':
+      arguments->verbose = 1;
+      break;
+    case 'o':
+      arguments->output_file = arg;
+      break;
+
+    case ARGP_KEY_ARG:
+      if (state->arg_num >= 2)
+	/* Too many arguments.  */
+	argp_usage (state);
+
+      arguments->args[state->arg_num] = arg;
+
+      break;
+
+    case ARGP_KEY_END:
+      if (state->arg_num < 2)
+	/* Not enough arguments.  */
+	argp_usage (state);
+      break;
+
+    default:
+      return ARGP_ERR_UNKNOWN;
+    }
+  return 0;
+}
+
+/* Our argp parser.  */
+static struct argp argp = { options, parse_opt, args_doc, doc };
+
+int
+main (int argc, char **argv)
+{
+  struct arguments arguments;
+
+  /* Default values.  */
+  arguments.silent = 0;
+  arguments.verbose = 0;
+  arguments.output_file = "-";
+
+  /* Parse our arguments; every option seen by @code{parse_opt} will
+     be reflected in @code{arguments}.  */
+  argp_parse (&argp, argc, argv, 0, 0, &arguments);
+
+  printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
+	  "VERBOSE = %s\nSILENT = %s\n",
+	  arguments.args[0], arguments.args[1],
+	  arguments.output_file,
+	  arguments.verbose ? "yes" : "no",
+	  arguments.silent ? "yes" : "no");
+
+  exit (0);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex4.c b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex4.c
new file mode 100644
index 0000000..a0c1a89
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/argp-ex4.c
@@ -0,0 +1,183 @@
+/* Argp example #4 -- a program with somewhat more complicated options
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/* This program uses the same features as example 3, but has more
+   options, and somewhat more structure in the -help output.  It
+   also shows how you can `steal' the remainder of the input
+   arguments past a certain point, for programs that accept a
+   list of items.  It also shows the special argp KEY value
+   ARGP_KEY_NO_ARGS, which is only given if no non-option
+   arguments were supplied to the program.
+
+   For structuring the help output, two features are used,
+   *headers* which are entries in the options vector with the
+   first four fields being zero, and a two part documentation
+   string (in the variable DOC), which allows documentation both
+   before and after the options; the two parts of DOC are
+   separated by a vertical-tab character ('\v', or '\013').  By
+   convention, the documentation before the options is just a
+   short string saying what the program does, and that afterwards
+   is longer, describing the behavior in more detail.  All
+   documentation strings are automatically filled for output,
+   although newlines may be included to force a line break at a
+   particular point.  All documentation strings are also passed to
+   the `gettext' function, for possible translation into the
+   current locale.  */
+
+#include <stdlib.h>
+#include <error.h>
+#include <argp.h>
+
+const char *argp_program_version =
+  "argp-ex4 1.0";
+const char *argp_program_bug_address =
+  "<bug-gnu-utils@@prep.ai.mit.edu>";
+
+/* Program documentation.  */
+static char doc[] =
+  "Argp example #4 -- a program with somewhat more complicated\
+options\
+\vThis part of the documentation comes *after* the options;\
+ note that the text is automatically filled, but it's possible\
+ to force a line-break, e.g.\n<-- here.";
+
+/* A description of the arguments we accept.  */
+static char args_doc[] = "ARG1 [STRING...]";
+
+/* Keys for options without short-options.  */
+#define OPT_ABORT  1		/* --abort */
+
+/* The options we understand.  */
+static struct argp_option options[] = {
+  {"verbose",  'v', 0,       0, "Produce verbose output" },
+  {"quiet",    'q', 0,       0, "Don't produce any output" },
+  {"silent",   's', 0,       OPTION_ALIAS },
+  {"output",   'o', "FILE",  0,
+   "Output to FILE instead of standard output" },
+
+  {0,0,0,0, "The following options should be grouped together:" },
+  {"repeat",   'r', "COUNT", OPTION_ARG_OPTIONAL,
+   "Repeat the output COUNT (default 10) times"},
+  {"abort",    OPT_ABORT, 0, 0, "Abort before showing any output"},
+
+  { 0 }
+};
+
+/* Used by @code{main} to communicate with @code{parse_opt}.  */
+struct arguments
+{
+  char *arg1;			/* @var{arg1} */
+  char **strings;		/* [@var{string}@dots{}] */
+  int silent, verbose, abort;	/* @samp{-s}, @samp{-v}, @samp{--abort} */
+  char *output_file;		/* @var{file} arg to @samp{--output} */
+  int repeat_count;		/* @var{count} arg to @samp{--repeat} */
+};
+
+/* Parse a single option.  */
+static error_t
+parse_opt (int key, char *arg, struct argp_state *state)
+{
+  /* Get the @code{input} argument from @code{argp_parse}, which we
+     know is a pointer to our arguments structure.  */
+  struct arguments *arguments = state->input;
+
+  switch (key)
+    {
+    case 'q': case 's':
+      arguments->silent = 1;
+      break;
+    case 'v':
+      arguments->verbose = 1;
+      break;
+    case 'o':
+      arguments->output_file = arg;
+      break;
+    case 'r':
+      arguments->repeat_count = arg ? atoi (arg) : 10;
+      break;
+    case OPT_ABORT:
+      arguments->abort = 1;
+      break;
+
+    case ARGP_KEY_NO_ARGS:
+      argp_usage (state);
+
+    case ARGP_KEY_ARG:
+      /* Here we know that @code{state->arg_num == 0}, since we
+	 force argument parsing to end before any more arguments can
+	 get here.  */
+      arguments->arg1 = arg;
+
+      /* Now we consume all the rest of the arguments.
+	 @code{state->next} is the index in @code{state->argv} of the
+	 next argument to be parsed, which is the first @var{string}
+	 we're interested in, so we can just use
+	 @code{&state->argv[state->next]} as the value for
+	 arguments->strings.
+
+	 @emph{In addition}, by setting @code{state->next} to the end
+	 of the arguments, we can force argp to stop parsing here and
+	 return.  */
+      arguments->strings = &state->argv[state->next];
+      state->next = state->argc;
+
+      break;
+
+    default:
+      return ARGP_ERR_UNKNOWN;
+    }
+  return 0;
+}
+
+/* Our argp parser.  */
+static struct argp argp = { options, parse_opt, args_doc, doc };
+
+int
+main (int argc, char **argv)
+{
+  int i, j;
+  struct arguments arguments;
+
+  /* Default values.  */
+  arguments.silent = 0;
+  arguments.verbose = 0;
+  arguments.output_file = "-";
+  arguments.repeat_count = 1;
+  arguments.abort = 0;
+
+  /* Parse our arguments; every option seen by @code{parse_opt} will be
+     reflected in @code{arguments}.  */
+  argp_parse (&argp, argc, argv, 0, 0, &arguments);
+
+  if (arguments.abort)
+    error (10, 0, "ABORTED");
+
+  for (i = 0; i < arguments.repeat_count; i++)
+    {
+      printf ("ARG1 = %s\n", arguments.arg1);
+      printf ("STRINGS = ");
+      for (j = 0; arguments.strings[j]; j++)
+	printf (j == 0 ? "%s" : ", %s", arguments.strings[j]);
+      printf ("\n");
+      printf ("OUTPUT_FILE = %s\nVERBOSE = %s\nSILENT = %s\n",
+	      arguments.output_file,
+	      arguments.verbose ? "yes" : "no",
+	      arguments.silent ? "yes" : "no");
+    }
+
+  exit (0);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/atexit.c b/ap/libc/glibc/glibc-2.23/manual/examples/atexit.c
new file mode 100644
index 0000000..7c09257
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/atexit.c
@@ -0,0 +1,32 @@
+/* Cleanups on Exit
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+
+void
+bye (void)
+{
+  puts ("Goodbye, cruel world....");
+}
+
+int
+main (void)
+{
+  atexit (bye);
+  exit (EXIT_SUCCESS);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/db.c b/ap/libc/glibc/glibc-2.23/manual/examples/db.c
new file mode 100644
index 0000000..a9b06d7
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/db.c
@@ -0,0 +1,69 @@
+/* User and Group Database Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <grp.h>
+#include <pwd.h>
+#include <sys/types.h>
+#include <unistd.h>
+#include <stdlib.h>
+
+int
+main (void)
+{
+  uid_t me;
+  struct passwd *my_passwd;
+  struct group *my_group;
+  char **members;
+
+  /* Get information about the user ID. */
+  me = getuid ();
+  my_passwd = getpwuid (me);
+  if (!my_passwd)
+    {
+      printf ("Couldn't find out about user %d.\n", (int) me);
+      exit (EXIT_FAILURE);
+    }
+
+  /* Print the information. */
+  printf ("I am %s.\n", my_passwd->pw_gecos);
+  printf ("My login name is %s.\n", my_passwd->pw_name);
+  printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
+  printf ("My home directory is %s.\n", my_passwd->pw_dir);
+  printf ("My default shell is %s.\n", my_passwd->pw_shell);
+
+  /* Get information about the default group ID. */
+  my_group = getgrgid (my_passwd->pw_gid);
+  if (!my_group)
+    {
+      printf ("Couldn't find out about group %d.\n",
+	      (int) my_passwd->pw_gid);
+      exit (EXIT_FAILURE);
+    }
+
+  /* Print the information. */
+  printf ("My default group is %s (%d).\n",
+	  my_group->gr_name, (int) (my_passwd->pw_gid));
+  printf ("The members of this group are:\n");
+  members = my_group->gr_mem;
+  while (*members)
+    {
+      printf ("  %s\n", *(members));
+      members++;
+    }
+
+  return EXIT_SUCCESS;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/dir.c b/ap/libc/glibc/glibc-2.23/manual/examples/dir.c
new file mode 100644
index 0000000..dc4a474
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/dir.c
@@ -0,0 +1,41 @@
+/* Simple Program to List a Directory
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*@group*/
+#include <stdio.h>
+#include <sys/types.h>
+#include <dirent.h>
+/*@end group*/
+
+int
+main (void)
+{
+  DIR *dp;
+  struct dirent *ep;
+
+  dp = opendir ("./");
+  if (dp != NULL)
+    {
+      while (ep = readdir (dp))
+	puts (ep->d_name);
+      (void) closedir (dp);
+    }
+  else
+    perror ("Couldn't open the directory");
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/dir2.c b/ap/libc/glibc/glibc-2.23/manual/examples/dir2.c
new file mode 100644
index 0000000..758a84d
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/dir2.c
@@ -0,0 +1,46 @@
+/* Simple Program to List a Directory, Mark II
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*@group*/
+#include <stdio.h>
+#include <dirent.h>
+/*@end group*/
+
+static int
+one (const struct dirent *unused)
+{
+  return 1;
+}
+
+int
+main (void)
+{
+  struct dirent **eps;
+  int n;
+
+  n = scandir ("./", &eps, one, alphasort);
+  if (n >= 0)
+    {
+      int cnt;
+      for (cnt = 0; cnt < n; ++cnt)
+	puts (eps[cnt]->d_name);
+    }
+  else
+    perror ("Couldn't open the directory");
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/execinfo.c b/ap/libc/glibc/glibc-2.23/manual/examples/execinfo.c
new file mode 100644
index 0000000..fd66b9a
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/execinfo.c
@@ -0,0 +1,54 @@
+/* Obtain a backtrace and print it.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <execinfo.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* Obtain a backtrace and print it to @code{stdout}. */
+void
+print_trace (void)
+{
+  void *array[10];
+  size_t size;
+  char **strings;
+  size_t i;
+
+  size = backtrace (array, 10);
+  strings = backtrace_symbols (array, size);
+
+  printf ("Obtained %zd stack frames.\n", size);
+
+  for (i = 0; i < size; i++)
+     printf ("%s\n", strings[i]);
+
+  free (strings);
+}
+
+/* A dummy function to make the backtrace more interesting. */
+void
+dummy_function (void)
+{
+  print_trace ();
+}
+
+int
+main (void)
+{
+  dummy_function ();
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/filecli.c b/ap/libc/glibc/glibc-2.23/manual/examples/filecli.c
new file mode 100644
index 0000000..0e6afa1
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/filecli.c
@@ -0,0 +1,71 @@
+/* Example of Reading Datagrams
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <errno.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+
+#define SERVER	"/tmp/serversocket"
+#define CLIENT	"/tmp/mysocket"
+#define MAXMSG	512
+#define MESSAGE	"Yow!!! Are we having fun yet?!?"
+
+int
+main (void)
+{
+  extern int make_named_socket (const char *name);
+  int sock;
+  char message[MAXMSG];
+  struct sockaddr_un name;
+  size_t size;
+  int nbytes;
+
+  /* Make the socket. */
+  sock = make_named_socket (CLIENT);
+
+  /* Initialize the server socket address. */
+  name.sun_family = AF_LOCAL;
+  strcpy (name.sun_path, SERVER);
+  size = strlen (name.sun_path) + sizeof (name.sun_family);
+
+  /* Send the datagram. */
+  nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
+		   (struct sockaddr *) & name, size);
+  if (nbytes < 0)
+    {
+      perror ("sendto (client)");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Wait for a reply. */
+  nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
+  if (nbytes < 0)
+    {
+      perror ("recfrom (client)");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Print a diagnostic message. */
+  fprintf (stderr, "Client: got message: %s\n", message);
+
+  /* Clean up. */
+  remove (CLIENT);
+  close (sock);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/filesrv.c b/ap/libc/glibc/glibc-2.23/manual/examples/filesrv.c
new file mode 100644
index 0000000..e0f32d7
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/filesrv.c
@@ -0,0 +1,65 @@
+/* Datagram Socket Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+
+#define SERVER	"/tmp/serversocket"
+#define MAXMSG	512
+
+int
+main (void)
+{
+  int sock;
+  char message[MAXMSG];
+  struct sockaddr_un name;
+  size_t size;
+  int nbytes;
+
+  /* Remove the filename first, it's ok if the call fails */
+  unlink (SERVER);
+
+  /* Make the socket, then loop endlessly. */
+  sock = make_named_socket (SERVER);
+  while (1)
+    {
+      /* Wait for a datagram. */
+      size = sizeof (name);
+      nbytes = recvfrom (sock, message, MAXMSG, 0,
+			 (struct sockaddr *) & name, &size);
+      if (nbytes < 0)
+	{
+	  perror ("recfrom (server)");
+	  exit (EXIT_FAILURE);
+	}
+
+      /* Give a diagnostic message. */
+      fprintf (stderr, "Server: got message: %s\n", message);
+
+      /* Bounce the message back to the sender. */
+      nbytes = sendto (sock, message, nbytes, 0,
+		       (struct sockaddr *) & name, size);
+      if (nbytes < 0)
+	{
+	  perror ("sendto (server)");
+	  exit (EXIT_FAILURE);
+	}
+    }
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/fmtmsgexpl.c b/ap/libc/glibc/glibc-2.23/manual/examples/fmtmsgexpl.c
new file mode 100644
index 0000000..f773f61
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/fmtmsgexpl.c
@@ -0,0 +1,29 @@
+/* How to use fmtmsg and addseverity.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <fmtmsg.h>
+
+int
+main (void)
+{
+  addseverity (5, "NOTE2");
+  fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
+  fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
+          "UX:cat:001");
+  fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/genpass.c b/ap/libc/glibc/glibc-2.23/manual/examples/genpass.c
new file mode 100644
index 0000000..ae0e173
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/genpass.c
@@ -0,0 +1,49 @@
+/* Encrypting Passwords
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <time.h>
+#include <unistd.h>
+#include <crypt.h>
+
+int
+main(void)
+{
+  unsigned long seed[2];
+  char salt[] = "$1$........";
+  const char *const seedchars =
+    "./0123456789ABCDEFGHIJKLMNOPQRST"
+    "UVWXYZabcdefghijklmnopqrstuvwxyz";
+  char *password;
+  int i;
+
+  /* Generate a (not very) random seed.
+     You should do it better than this...  */
+  seed[0] = time(NULL);
+  seed[1] = getpid() ^ (seed[0] >> 14 & 0x30000);
+
+  /* Turn it into printable characters from `seedchars'.  */
+  for (i = 0; i < 8; i++)
+    salt[3+i] = seedchars[(seed[i/5] >> (i%5)*6) & 0x3f];
+
+  /* Read in the user's password and encrypt it.  */
+  password = crypt(getpass("Password:"), salt);
+
+  /* Print the results.  */
+  puts(password);
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/inetcli.c b/ap/libc/glibc/glibc-2.23/manual/examples/inetcli.c
new file mode 100644
index 0000000..13a4dae
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/inetcli.c
@@ -0,0 +1,76 @@
+/* Byte Stream Socket Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <netdb.h>
+
+#define PORT		5555
+#define MESSAGE		"Yow!!! Are we having fun yet?!?"
+#define SERVERHOST 	"www.gnu.org"
+
+void
+write_to_server (int filedes)
+{
+  int nbytes;
+
+  nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
+  if (nbytes < 0)
+    {
+      perror ("write");
+      exit (EXIT_FAILURE);
+    }
+}
+
+
+int
+main (void)
+{
+  extern void init_sockaddr (struct sockaddr_in *name,
+			     const char *hostname,
+			     uint16_t port);
+  int sock;
+  struct sockaddr_in servername;
+
+  /* Create the socket.  */
+  sock = socket (PF_INET, SOCK_STREAM, 0);
+  if (sock < 0)
+    {
+      perror ("socket (client)");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Connect to the server.  */
+  init_sockaddr (&servername, SERVERHOST, PORT);
+  if (0 > connect (sock,
+		   (struct sockaddr *) &servername,
+		   sizeof (servername)))
+    {
+      perror ("connect (client)");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Send data to the server.  */
+  write_to_server (sock);
+  close (sock);
+  exit (EXIT_SUCCESS);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/inetsrv.c b/ap/libc/glibc/glibc-2.23/manual/examples/inetsrv.c
new file mode 100644
index 0000000..91dfbc9
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/inetsrv.c
@@ -0,0 +1,120 @@
+/* Byte Stream Connection Server Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <netdb.h>
+
+#define PORT	5555
+#define MAXMSG	512
+
+int
+read_from_client (int filedes)
+{
+  char buffer[MAXMSG];
+  int nbytes;
+
+  nbytes = read (filedes, buffer, MAXMSG);
+  if (nbytes < 0)
+    {
+      /* Read error. */
+      perror ("read");
+      exit (EXIT_FAILURE);
+    }
+  else if (nbytes == 0)
+    /* End-of-file. */
+    return -1;
+  else
+    {
+      /* Data read. */
+      fprintf (stderr, "Server: got message: `%s'\n", buffer);
+      return 0;
+    }
+}
+
+int
+main (void)
+{
+  extern int make_socket (uint16_t port);
+  int sock;
+  fd_set active_fd_set, read_fd_set;
+  int i;
+  struct sockaddr_in clientname;
+  size_t size;
+
+  /* Create the socket and set it up to accept connections. */
+  sock = make_socket (PORT);
+  if (listen (sock, 1) < 0)
+    {
+      perror ("listen");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Initialize the set of active sockets. */
+  FD_ZERO (&active_fd_set);
+  FD_SET (sock, &active_fd_set);
+
+  while (1)
+    {
+      /* Block until input arrives on one or more active sockets. */
+      read_fd_set = active_fd_set;
+      if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
+	{
+	  perror ("select");
+	  exit (EXIT_FAILURE);
+	}
+
+      /* Service all the sockets with input pending. */
+      for (i = 0; i < FD_SETSIZE; ++i)
+	if (FD_ISSET (i, &read_fd_set))
+	  {
+	    if (i == sock)
+	      {
+		/* Connection request on original socket. */
+		int new;
+		size = sizeof (clientname);
+		new = accept (sock,
+			      (struct sockaddr *) &clientname,
+			      &size);
+		if (new < 0)
+		  {
+		    perror ("accept");
+		    exit (EXIT_FAILURE);
+		  }
+		fprintf (stderr,
+			 "Server: connect from host %s, port %hd.\n",
+			 inet_ntoa (clientname.sin_addr),
+			 ntohs (clientname.sin_port));
+		FD_SET (new, &active_fd_set);
+	      }
+	    else
+	      {
+		/* Data arriving on an already-connected socket. */
+		if (read_from_client (i) < 0)
+		  {
+		    close (i);
+		    FD_CLR (i, &active_fd_set);
+		  }
+	      }
+	  }
+    }
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/isockad.c b/ap/libc/glibc/glibc-2.23/manual/examples/isockad.c
new file mode 100644
index 0000000..4eb1060
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/isockad.c
@@ -0,0 +1,40 @@
+/* Internet Socket Example using sockaddr_in.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <netdb.h>
+
+void
+init_sockaddr (struct sockaddr_in *name,
+	       const char *hostname,
+	       uint16_t port)
+{
+  struct hostent *hostinfo;
+
+  name->sin_family = AF_INET;
+  name->sin_port = htons (port);
+  hostinfo = gethostbyname (hostname);
+  if (hostinfo == NULL)
+    {
+      fprintf (stderr, "Unknown host %s.\n", hostname);
+      exit (EXIT_FAILURE);
+    }
+  name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/longopt.c b/ap/libc/glibc/glibc-2.23/manual/examples/longopt.c
new file mode 100644
index 0000000..8731c55
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/longopt.c
@@ -0,0 +1,113 @@
+/* Example of Parsing Long Options with getopt_long.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <getopt.h>
+
+/* Flag set by @samp{--verbose}.  */
+static int verbose_flag;
+
+int
+main (int argc, char **argv)
+{
+  int c;
+
+  while (1)
+    {
+      static struct option long_options[] =
+	{
+	  /* These options set a flag.  */
+	  {"verbose", no_argument,       &verbose_flag, 1},
+	  {"brief",   no_argument,       &verbose_flag, 0},
+	  /* These options don't set a flag.
+	     We distinguish them by their indices.  */
+	  {"add",     no_argument,       0, 'a'},
+	  {"append",  no_argument,       0, 'b'},
+	  {"delete",  required_argument, 0, 'd'},
+	  {"create",  required_argument, 0, 'c'},
+	  {"file",    required_argument, 0, 'f'},
+	  {0, 0, 0, 0}
+	};
+      /* @code{getopt_long} stores the option index here.  */
+      int option_index = 0;
+
+      c = getopt_long (argc, argv, "abc:d:f:",
+		       long_options, &option_index);
+
+      /* Detect the end of the options.  */
+      if (c == -1)
+	break;
+
+      switch (c)
+	{
+	case 0:
+	  /* If this option set a flag, do nothing else now.  */
+	  if (long_options[option_index].flag != 0)
+	    break;
+	  printf ("option %s", long_options[option_index].name);
+	  if (optarg)
+	    printf (" with arg %s", optarg);
+	  printf ("\n");
+	  break;
+
+	case 'a':
+	  puts ("option -a\n");
+	  break;
+
+	case 'b':
+	  puts ("option -b\n");
+	  break;
+
+	case 'c':
+	  printf ("option -c with value `%s'\n", optarg);
+	  break;
+
+	case 'd':
+	  printf ("option -d with value `%s'\n", optarg);
+	  break;
+
+	case 'f':
+	  printf ("option -f with value `%s'\n", optarg);
+	  break;
+
+	case '?':
+	  /* @code{getopt_long} already printed an error message.  */
+	  break;
+
+	default:
+	  abort ();
+	}
+    }
+
+  /* Instead of reporting @samp{--verbose}
+     and @samp{--brief} as they are encountered,
+     we report the final status resulting from them.  */
+  if (verbose_flag)
+    puts ("verbose flag is set");
+
+  /* Print any remaining command line arguments (not options).  */
+  if (optind < argc)
+    {
+      printf ("non-option ARGV-elements: ");
+      while (optind < argc)
+	printf ("%s ", argv[optind++]);
+      putchar ('\n');
+    }
+
+  exit (0);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/memopen.c b/ap/libc/glibc/glibc-2.23/manual/examples/memopen.c
new file mode 100644
index 0000000..96e20a3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/memopen.c
@@ -0,0 +1,34 @@
+/* String Streams
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+
+static char buffer[] = "foobar";
+
+int
+main (void)
+{
+  int ch;
+  FILE *stream;
+
+  stream = fmemopen (buffer, strlen (buffer), "r");
+  while ((ch = fgetc (stream)) != EOF)
+    printf ("Got %c\n", ch);
+  fclose (stream);
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/memstrm.c b/ap/libc/glibc/glibc-2.23/manual/examples/memstrm.c
new file mode 100644
index 0000000..0d443b1
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/memstrm.c
@@ -0,0 +1,36 @@
+/* open_memstream example.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+
+int
+main (void)
+{
+  char *bp;
+  size_t size;
+  FILE *stream;
+
+  stream = open_memstream (&bp, &size);
+  fprintf (stream, "hello");
+  fflush (stream);
+  printf ("buf = `%s', size = %d\n", bp, size);
+  fprintf (stream, ", world");
+  fclose (stream);
+  printf ("buf = `%s', size = %d\n", bp, size);
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/mkfsock.c b/ap/libc/glibc/glibc-2.23/manual/examples/mkfsock.c
new file mode 100644
index 0000000..76ddc97
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/mkfsock.c
@@ -0,0 +1,62 @@
+/* Example of Local-Namespace Sockets
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stddef.h>
+#include <stdio.h>
+#include <errno.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+
+int
+make_named_socket (const char *filename)
+{
+  struct sockaddr_un name;
+  int sock;
+  size_t size;
+
+  /* Create the socket.  */
+  sock = socket (PF_LOCAL, SOCK_DGRAM, 0);
+  if (sock < 0)
+    {
+      perror ("socket");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Bind a name to the socket.  */
+  name.sun_family = AF_LOCAL;
+  strncpy (name.sun_path, filename, sizeof (name.sun_path));
+  name.sun_path[sizeof (name.sun_path) - 1] = '\0';
+
+  /* The size of the address is
+     the offset of the start of the filename,
+     plus its length (not including the terminating null byte).
+     Alternatively you can just do:
+     size = SUN_LEN (&name);
+  */
+  size = (offsetof (struct sockaddr_un, sun_path)
+	  + strlen (name.sun_path));
+
+  if (bind (sock, (struct sockaddr *) &name, size) < 0)
+    {
+      perror ("bind");
+      exit (EXIT_FAILURE);
+    }
+
+  return sock;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/mkisock.c b/ap/libc/glibc/glibc-2.23/manual/examples/mkisock.c
new file mode 100644
index 0000000..b50a5be
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/mkisock.c
@@ -0,0 +1,48 @@
+/* Internet Socket Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+
+int
+make_socket (uint16_t port)
+{
+  int sock;
+  struct sockaddr_in name;
+
+  /* Create the socket. */
+  sock = socket (PF_INET, SOCK_STREAM, 0);
+  if (sock < 0)
+    {
+      perror ("socket");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Give the socket a name. */
+  name.sin_family = AF_INET;
+  name.sin_port = htons (port);
+  name.sin_addr.s_addr = htonl (INADDR_ANY);
+  if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
+    {
+      perror ("bind");
+      exit (EXIT_FAILURE);
+    }
+
+  return sock;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/mygetpass.c b/ap/libc/glibc/glibc-2.23/manual/examples/mygetpass.c
new file mode 100644
index 0000000..5751c2d
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/mygetpass.c
@@ -0,0 +1,42 @@
+/* Reading Passwords
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <termios.h>
+#include <stdio.h>
+
+ssize_t
+my_getpass (char **lineptr, size_t *n, FILE *stream)
+{
+  struct termios old, new;
+  int nread;
+
+  /* Turn echoing off and fail if we can't.  */
+  if (tcgetattr (fileno (stream), &old) != 0)
+    return -1;
+  new = old;
+  new.c_lflag &= ~ECHO;
+  if (tcsetattr (fileno (stream), TCSAFLUSH, &new) != 0)
+    return -1;
+
+  /* Read the password.  */
+  nread = getline (lineptr, n, stream);
+
+  /* Restore terminal.  */
+  (void) tcsetattr (fileno (stream), TCSAFLUSH, &old);
+
+  return nread;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/ofdlocks.c b/ap/libc/glibc/glibc-2.23/manual/examples/ofdlocks.c
new file mode 100644
index 0000000..ba4f0ef
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/ofdlocks.c
@@ -0,0 +1,77 @@
+/* Open File Description Locks Usage Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <pthread.h>
+
+#define FILENAME	"/tmp/foo"
+#define NUM_THREADS	3
+#define ITERATIONS	5
+
+void *
+thread_start (void *arg)
+{
+  int i, fd, len;
+  long tid = (long) arg;
+  char buf[256];
+  struct flock lck = {
+    .l_whence = SEEK_SET,
+    .l_start = 0,
+    .l_len = 1,
+  };
+
+  fd = open ("/tmp/foo", O_RDWR | O_CREAT, 0666);
+
+  for (i = 0; i < ITERATIONS; i++)
+    {
+      lck.l_type = F_WRLCK;
+      fcntl (fd, F_OFD_SETLKW, &lck);
+
+      len = sprintf (buf, "%d: tid=%ld fd=%d\n", i, tid, fd);
+
+      lseek (fd, 0, SEEK_END);
+      write (fd, buf, len);
+      fsync (fd);
+
+      lck.l_type = F_UNLCK;
+      fcntl (fd, F_OFD_SETLK, &lck);
+
+      /* sleep to ensure lock is yielded to another thread */
+      usleep (1);
+    }
+  pthread_exit (NULL);
+}
+
+int
+main (int argc, char **argv)
+{
+  long i;
+  pthread_t threads[NUM_THREADS];
+
+  truncate (FILENAME, 0);
+
+  for (i = 0; i < NUM_THREADS; i++)
+    pthread_create (&threads[i], NULL, thread_start, (void *) i);
+
+  pthread_exit (NULL);
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/pipe.c b/ap/libc/glibc/glibc-2.23/manual/examples/pipe.c
new file mode 100644
index 0000000..c765672
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/pipe.c
@@ -0,0 +1,87 @@
+/* Creating a Pipe
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <sys/types.h>
+#include <unistd.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* Read characters from the pipe and echo them to @code{stdout}.  */
+
+void
+read_from_pipe (int file)
+{
+  FILE *stream;
+  int c;
+  stream = fdopen (file, "r");
+  while ((c = fgetc (stream)) != EOF)
+    putchar (c);
+  fclose (stream);
+}
+
+/* Write some random text to the pipe. */
+
+void
+write_to_pipe (int file)
+{
+  FILE *stream;
+  stream = fdopen (file, "w");
+  fprintf (stream, "hello, world!\n");
+  fprintf (stream, "goodbye, world!\n");
+  fclose (stream);
+}
+
+int
+main (void)
+{
+  pid_t pid;
+  int mypipe[2];
+
+/*@group*/
+  /* Create the pipe.  */
+  if (pipe (mypipe))
+    {
+      fprintf (stderr, "Pipe failed.\n");
+      return EXIT_FAILURE;
+    }
+/*@end group*/
+
+  /* Create the child process.  */
+  pid = fork ();
+  if (pid == (pid_t) 0)
+    {
+      /* This is the child process.
+	 Close other end first.  */
+      close (mypipe[1]);
+      read_from_pipe (mypipe[0]);
+      return EXIT_SUCCESS;
+    }
+  else if (pid < (pid_t) 0)
+    {
+      /* The fork failed.  */
+      fprintf (stderr, "Fork failed.\n");
+      return EXIT_FAILURE;
+    }
+  else
+    {
+      /* This is the parent process.
+	 Close other end first.  */
+      close (mypipe[0]);
+      write_to_pipe (mypipe[1]);
+      return EXIT_SUCCESS;
+    }
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/popen.c b/ap/libc/glibc/glibc-2.23/manual/examples/popen.c
new file mode 100644
index 0000000..cc16135
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/popen.c
@@ -0,0 +1,55 @@
+/* Pipe to a Subprocess
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+
+void
+write_data (FILE * stream)
+{
+  int i;
+  for (i = 0; i < 100; i++)
+    fprintf (stream, "%d\n", i);
+  if (ferror (stream))
+    {
+      fprintf (stderr, "Output to stream failed.\n");
+      exit (EXIT_FAILURE);
+    }
+}
+
+/*@group*/
+int
+main (void)
+{
+  FILE *output;
+
+  output = popen ("more", "w");
+  if (!output)
+    {
+      fprintf (stderr,
+	       "incorrect parameters or too many files.\n");
+      return EXIT_FAILURE;
+    }
+  write_data (output);
+  if (pclose (output) != 0)
+    {
+      fprintf (stderr,
+	       "Could not run more or other error.\n");
+    }
+  return EXIT_SUCCESS;
+}
+/*@end group*/
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/rprintf.c b/ap/libc/glibc/glibc-2.23/manual/examples/rprintf.c
new file mode 100644
index 0000000..4106677
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/rprintf.c
@@ -0,0 +1,84 @@
+/* Printf Extension Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <printf.h>
+
+/*@group*/
+typedef struct
+{
+  char *name;
+}
+Widget;
+/*@end group*/
+
+int
+print_widget (FILE *stream,
+	      const struct printf_info *info,
+	      const void *const *args)
+{
+  const Widget *w;
+  char *buffer;
+  int len;
+
+  /* Format the output into a string. */
+  w = *((const Widget **) (args[0]));
+  len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
+  if (len == -1)
+    return -1;
+
+  /* Pad to the minimum field width and print to the stream. */
+  len = fprintf (stream, "%*s",
+		 (info->left ? -info->width : info->width),
+		 buffer);
+
+  /* Clean up and return. */
+  free (buffer);
+  return len;
+}
+
+
+int
+print_widget_arginfo (const struct printf_info *info, size_t n,
+                      int *argtypes)
+{
+  /* We always take exactly one argument and this is a pointer to the
+     structure..  */
+  if (n > 0)
+    argtypes[0] = PA_POINTER;
+  return 1;
+}
+
+
+int
+main (void)
+{
+  /* Make a widget to print. */
+  Widget mywidget;
+  mywidget.name = "mywidget";
+
+  /* Register the print function for widgets. */
+  register_printf_function ('W', print_widget, print_widget_arginfo);
+
+  /* Now print the widget. */
+  printf ("|%W|\n", &mywidget);
+  printf ("|%35W|\n", &mywidget);
+  printf ("|%-35W|\n", &mywidget);
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/search.c b/ap/libc/glibc/glibc-2.23/manual/examples/search.c
new file mode 100644
index 0000000..4665be0
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/search.c
@@ -0,0 +1,113 @@
+/* Searching and Sorting Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+/* Define an array of critters to sort. */
+
+struct critter
+  {
+    const char *name;
+    const char *species;
+  };
+
+struct critter muppets[] =
+  {
+    {"Kermit", "frog"},
+    {"Piggy", "pig"},
+    {"Gonzo", "whatever"},
+    {"Fozzie", "bear"},
+    {"Sam", "eagle"},
+    {"Robin", "frog"},
+    {"Animal", "animal"},
+    {"Camilla", "chicken"},
+    {"Sweetums", "monster"},
+    {"Dr. Strangepork", "pig"},
+    {"Link Hogthrob", "pig"},
+    {"Zoot", "human"},
+    {"Dr. Bunsen Honeydew", "human"},
+    {"Beaker", "human"},
+    {"Swedish Chef", "human"}
+  };
+
+int count = sizeof (muppets) / sizeof (struct critter);
+
+
+
+/* This is the comparison function used for sorting and searching. */
+
+int
+critter_cmp (const void *v1, const void *v2)
+{
+  const struct critter *c1 = v1;
+  const struct critter *c2 = v2;
+
+  return strcmp (c1->name, c2->name);
+}
+
+
+/* Print information about a critter. */
+
+void
+print_critter (const struct critter *c)
+{
+  printf ("%s, the %s\n", c->name, c->species);
+}
+
+
+/*@group*/
+/* Do the lookup into the sorted array. */
+
+void
+find_critter (const char *name)
+{
+  struct critter target, *result;
+  target.name = name;
+  result = bsearch (&target, muppets, count, sizeof (struct critter),
+		    critter_cmp);
+  if (result)
+    print_critter (result);
+  else
+    printf ("Couldn't find %s.\n", name);
+}
+/*@end group*/
+
+/* Main program. */
+
+int
+main (void)
+{
+  int i;
+
+  for (i = 0; i < count; i++)
+    print_critter (&muppets[i]);
+  printf ("\n");
+
+  qsort (muppets, count, sizeof (struct critter), critter_cmp);
+
+  for (i = 0; i < count; i++)
+    print_critter (&muppets[i]);
+  printf ("\n");
+
+  find_critter ("Kermit");
+  find_critter ("Gonzo");
+  find_critter ("Janice");
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/select.c b/ap/libc/glibc/glibc-2.23/manual/examples/select.c
new file mode 100644
index 0000000..8dde70b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/select.c
@@ -0,0 +1,58 @@
+/* Waiting for Input or Output
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*@group*/
+#include <errno.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <sys/types.h>
+#include <sys/time.h>
+/*@end group*/
+
+/*@group*/
+int
+input_timeout (int filedes, unsigned int seconds)
+{
+  fd_set set;
+  struct timeval timeout;
+/*@end group*/
+
+  /* Initialize the file descriptor set. */
+  FD_ZERO (&set);
+  FD_SET (filedes, &set);
+
+  /* Initialize the timeout data structure. */
+  timeout.tv_sec = seconds;
+  timeout.tv_usec = 0;
+
+/*@group*/
+  /* @code{select} returns 0 if timeout, 1 if input available, -1 if error. */
+  return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
+				     &set, NULL, NULL,
+				     &timeout));
+}
+/*@end group*/
+
+/*@group*/
+int
+main (void)
+{
+  fprintf (stderr, "select returned %d.\n",
+	   input_timeout (STDIN_FILENO, 5));
+  return 0;
+}
+/*@end group*/
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/setjmp.c b/ap/libc/glibc/glibc-2.23/manual/examples/setjmp.c
new file mode 100644
index 0000000..754d8ca
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/setjmp.c
@@ -0,0 +1,49 @@
+/* Introduction to Non-Local Exits
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <setjmp.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+jmp_buf main_loop;
+
+void
+abort_to_main_loop (int status)
+{
+  longjmp (main_loop, status);
+}
+
+int
+main (void)
+{
+  while (1)
+    if (setjmp (main_loop))
+      puts ("Back at main loop....");
+    else
+      do_command ();
+}
+
+
+void
+do_command (void)
+{
+  char buffer[128];
+  if (fgets (buffer, 128, stdin) == NULL)
+    abort_to_main_loop (-1);
+  else
+    exit (EXIT_SUCCESS);
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/sigh1.c b/ap/libc/glibc/glibc-2.23/manual/examples/sigh1.c
new file mode 100644
index 0000000..184cfa8
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/sigh1.c
@@ -0,0 +1,53 @@
+/* Signal Handlers that Return
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* This flag controls termination of the main loop. */
+volatile sig_atomic_t keep_going = 1;
+
+/* The signal handler just clears the flag and re-enables itself. */
+void
+catch_alarm (int sig)
+{
+  keep_going = 0;
+  signal (sig, catch_alarm);
+}
+
+void
+do_stuff (void)
+{
+  puts ("Doing stuff while waiting for alarm....");
+}
+
+int
+main (void)
+{
+  /* Establish a handler for SIGALRM signals. */
+  signal (SIGALRM, catch_alarm);
+
+  /* Set an alarm to go off in a little while. */
+  alarm (2);
+
+  /* Check the flag once in a while to see when to quit. */
+  while (keep_going)
+    do_stuff ();
+
+  return EXIT_SUCCESS;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/sigusr.c b/ap/libc/glibc/glibc-2.23/manual/examples/sigusr.c
new file mode 100644
index 0000000..0befcdb
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/sigusr.c
@@ -0,0 +1,78 @@
+/* Using kill for Communication
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*@group*/
+#include <signal.h>
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+/*@end group*/
+
+/* When a @code{SIGUSR1} signal arrives, set this variable.  */
+volatile sig_atomic_t usr_interrupt = 0;
+
+void
+synch_signal (int sig)
+{
+  usr_interrupt = 1;
+}
+
+/* The child process executes this function. */
+void
+child_function (void)
+{
+  /* Perform initialization. */
+  printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());
+
+  /* Let parent know you're done. */
+  kill (getppid (), SIGUSR1);
+
+  /* Continue with execution. */
+  puts ("Bye, now....");
+  exit (0);
+}
+
+int
+main (void)
+{
+  struct sigaction usr_action;
+  sigset_t block_mask;
+  pid_t child_id;
+
+  /* Establish the signal handler. */
+  sigfillset (&block_mask);
+  usr_action.sa_handler = synch_signal;
+  usr_action.sa_mask = block_mask;
+  usr_action.sa_flags = 0;
+  sigaction (SIGUSR1, &usr_action, NULL);
+
+  /* Create the child process. */
+  child_id = fork ();
+  if (child_id == 0)
+    child_function ();		/* Does not return.  */
+
+/*@group*/
+  /* Busy wait for the child to send a signal. */
+  while (!usr_interrupt)
+    ;
+/*@end group*/
+
+  /* Now continue execution. */
+  puts ("That's all, folks!");
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/stpcpy.c b/ap/libc/glibc/glibc-2.23/manual/examples/stpcpy.c
new file mode 100644
index 0000000..e97c6fe
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/stpcpy.c
@@ -0,0 +1,30 @@
+/* stpcpy example.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <string.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+  char buffer[10];
+  char *to = buffer;
+  to = stpcpy (to, "foo");
+  to = stpcpy (to, "bar");
+  puts (buffer);
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/strdupa.c b/ap/libc/glibc/glibc-2.23/manual/examples/strdupa.c
new file mode 100644
index 0000000..8b1a7c3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/strdupa.c
@@ -0,0 +1,36 @@
+/* strdupa example.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <paths.h>
+#include <string.h>
+#include <stdio.h>
+
+const char path[] = _PATH_STDPATH;
+
+int
+main (void)
+{
+  char *wr_path = strdupa (path);
+  char *cp = strtok (wr_path, ":");
+
+  while (cp != NULL)
+    {
+      puts (cp);
+      cp = strtok (NULL, ":");
+    }
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/strftim.c b/ap/libc/glibc/glibc-2.23/manual/examples/strftim.c
new file mode 100644
index 0000000..9c9c617
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/strftim.c
@@ -0,0 +1,48 @@
+/* Time Functions Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <time.h>
+#include <stdio.h>
+
+#define SIZE 256
+
+int
+main (void)
+{
+  char buffer[SIZE];
+  time_t curtime;
+  struct tm *loctime;
+
+  /* Get the current time. */
+  curtime = time (NULL);
+
+  /* Convert it to local time representation. */
+  loctime = localtime (&curtime);
+
+  /* Print out the date and time in the standard format. */
+  fputs (asctime (loctime), stdout);
+
+/*@group*/
+  /* Print it out in a nice format. */
+  strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
+  fputs (buffer, stdout);
+  strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
+  fputs (buffer, stdout);
+
+  return 0;
+}
+/*@end group*/
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/subopt.c b/ap/libc/glibc/glibc-2.23/manual/examples/subopt.c
new file mode 100644
index 0000000..8ceb5f3
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/subopt.c
@@ -0,0 +1,95 @@
+/* Parsing of Suboptions Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int do_all;
+const char *type;
+int read_size;
+int write_size;
+int read_only;
+
+enum
+{
+  RO_OPTION = 0,
+  RW_OPTION,
+  READ_SIZE_OPTION,
+  WRITE_SIZE_OPTION,
+  THE_END
+};
+
+const char *mount_opts[] =
+{
+  [RO_OPTION] = "ro",
+  [RW_OPTION] = "rw",
+  [READ_SIZE_OPTION] = "rsize",
+  [WRITE_SIZE_OPTION] = "wsize",
+  [THE_END] = NULL
+};
+
+int
+main (int argc, char **argv)
+{
+  char *subopts, *value;
+  int opt;
+
+  while ((opt = getopt (argc, argv, "at:o:")) != -1)
+    switch (opt)
+      {
+      case 'a':
+        do_all = 1;
+        break;
+      case 't':
+        type = optarg;
+        break;
+      case 'o':
+        subopts = optarg;
+        while (*subopts != '\0')
+          switch (getsubopt (&subopts, mount_opts, &value))
+            {
+            case RO_OPTION:
+              read_only = 1;
+              break;
+            case RW_OPTION:
+              read_only = 0;
+              break;
+            case READ_SIZE_OPTION:
+              if (value == NULL)
+                abort ();
+              read_size = atoi (value);
+              break;
+            case WRITE_SIZE_OPTION:
+              if (value == NULL)
+                abort ();
+              write_size = atoi (value);
+              break;
+            default:
+              /* Unknown suboption.  */
+              printf ("Unknown suboption `%s'\n", value);
+              break;
+            }
+        break;
+      default:
+        abort ();
+      }
+
+  /* Do the real work.  */
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/swapcontext.c b/ap/libc/glibc/glibc-2.23/manual/examples/swapcontext.c
new file mode 100644
index 0000000..27011ed
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/swapcontext.c
@@ -0,0 +1,116 @@
+/* Complete Context Control
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <ucontext.h>
+#include <sys/time.h>
+
+/* Set by the signal handler.  */
+static volatile int expired;
+
+/* The contexts.  */
+static ucontext_t uc[3];
+
+/* We do only a certain number of switches.  */
+static int switches;
+
+
+/* This is the function doing the work.  It is just a
+   skeleton, real code has to be filled in.  */
+static void
+f (int n)
+{
+  int m = 0;
+  while (1)
+    {
+      /* This is where the work would be done.  */
+      if (++m % 100 == 0)
+        {
+          putchar ('.');
+          fflush (stdout);
+        }
+
+      /* Regularly the @var{expire} variable must be checked.  */
+      if (expired)
+        {
+          /* We do not want the program to run forever.  */
+          if (++switches == 20)
+            return;
+
+          printf ("\nswitching from %d to %d\n", n, 3 - n);
+          expired = 0;
+          /* Switch to the other context, saving the current one.  */
+          swapcontext (&uc[n], &uc[3 - n]);
+        }
+    }
+}
+
+/* This is the signal handler which simply set the variable.  */
+void
+handler (int signal)
+{
+  expired = 1;
+}
+
+
+int
+main (void)
+{
+  struct sigaction sa;
+  struct itimerval it;
+  char st1[8192];
+  char st2[8192];
+
+  /* Initialize the data structures for the interval timer.  */
+  sa.sa_flags = SA_RESTART;
+  sigfillset (&sa.sa_mask);
+  sa.sa_handler = handler;
+  it.it_interval.tv_sec = 0;
+  it.it_interval.tv_usec = 1;
+  it.it_value = it.it_interval;
+
+  /* Install the timer and get the context we can manipulate.  */
+  if (sigaction (SIGPROF, &sa, NULL) < 0
+      || setitimer (ITIMER_PROF, &it, NULL) < 0
+      || getcontext (&uc[1]) == -1
+      || getcontext (&uc[2]) == -1)
+    abort ();
+
+  /* Create a context with a separate stack which causes the
+     function @code{f} to be call with the parameter @code{1}.
+     Note that the @code{uc_link} points to the main context
+     which will cause the program to terminate once the function
+     return.  */
+  uc[1].uc_link = &uc[0];
+  uc[1].uc_stack.ss_sp = st1;
+  uc[1].uc_stack.ss_size = sizeof st1;
+  makecontext (&uc[1], (void (*) (void)) f, 1, 1);
+
+  /* Similarly, but @code{2} is passed as the parameter to @code{f}.  */
+  uc[2].uc_link = &uc[0];
+  uc[2].uc_stack.ss_sp = st2;
+  uc[2].uc_stack.ss_size = sizeof st2;
+  makecontext (&uc[2], (void (*) (void)) f, 1, 2);
+
+  /* Start running.  */
+  swapcontext (&uc[0], &uc[1]);
+  putchar ('\n');
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/termios.c b/ap/libc/glibc/glibc-2.23/manual/examples/termios.c
new file mode 100644
index 0000000..031667d
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/termios.c
@@ -0,0 +1,77 @@
+/* Noncanonical Mode Example
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <unistd.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <termios.h>
+
+/* Use this variable to remember original terminal attributes. */
+
+struct termios saved_attributes;
+
+void
+reset_input_mode (void)
+{
+  tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
+}
+
+void
+set_input_mode (void)
+{
+  struct termios tattr;
+  char *name;
+
+  /* Make sure stdin is a terminal. */
+  if (!isatty (STDIN_FILENO))
+    {
+      fprintf (stderr, "Not a terminal.\n");
+      exit (EXIT_FAILURE);
+    }
+
+  /* Save the terminal attributes so we can restore them later. */
+  tcgetattr (STDIN_FILENO, &saved_attributes);
+  atexit (reset_input_mode);
+
+/*@group*/
+  /* Set the funny terminal modes. */
+  tcgetattr (STDIN_FILENO, &tattr);
+  tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO.  */
+  tattr.c_cc[VMIN] = 1;
+  tattr.c_cc[VTIME] = 0;
+  tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
+}
+/*@end group*/
+
+int
+main (void)
+{
+  char c;
+
+  set_input_mode ();
+
+  while (1)
+    {
+      read (STDIN_FILENO, &c, 1);
+      if (c == '\004')		/* @kbd{C-d} */
+	break;
+      else
+	putchar (c);
+    }
+
+  return EXIT_SUCCESS;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/testopt.c b/ap/libc/glibc/glibc-2.23/manual/examples/testopt.c
new file mode 100644
index 0000000..7df838a
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/testopt.c
@@ -0,0 +1,72 @@
+/* Example of Parsing Arguments with getopt.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/*@group*/
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int
+main (int argc, char **argv)
+{
+  int aflag = 0;
+  int bflag = 0;
+  char *cvalue = NULL;
+  int index;
+  int c;
+
+  opterr = 0;
+/*@end group*/
+
+/*@group*/
+  while ((c = getopt (argc, argv, "abc:")) != -1)
+    switch (c)
+      {
+      case 'a':
+        aflag = 1;
+        break;
+      case 'b':
+        bflag = 1;
+        break;
+      case 'c':
+        cvalue = optarg;
+        break;
+      case '?':
+        if (optopt == 'c')
+          fprintf (stderr, "Option -%c requires an argument.\n", optopt);
+        else if (isprint (optopt))
+          fprintf (stderr, "Unknown option `-%c'.\n", optopt);
+        else
+          fprintf (stderr,
+                   "Unknown option character `\\x%x'.\n",
+                   optopt);
+        return 1;
+      default:
+        abort ();
+      }
+/*@end group*/
+
+/*@group*/
+  printf ("aflag = %d, bflag = %d, cvalue = %s\n",
+	  aflag, bflag, cvalue);
+
+  for (index = optind; index < argc; index++)
+    printf ("Non-option argument %s\n", argv[index]);
+  return 0;
+}
+/*@end group*/
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/testpass.c b/ap/libc/glibc/glibc-2.23/manual/examples/testpass.c
new file mode 100644
index 0000000..2c8ddbd
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/testpass.c
@@ -0,0 +1,43 @@
+/* Verify a password.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+#include <crypt.h>
+
+int
+main(void)
+{
+  /* Hashed form of "GNU libc manual".  */
+  const char *const pass = "$1$/iSaq7rB$EoUw5jJPPvAPECNaaWzMK/";
+
+  char *result;
+  int ok;
+
+/*@group*/
+  /* Read in the user's password and encrypt it,
+     passing the expected password in as the salt.  */
+  result = crypt(getpass("Password:"), pass);
+/*@end group*/
+
+  /* Test the result.  */
+  ok = strcmp (result, pass) == 0;
+
+  puts(ok ? "Access granted." : "Access denied.");
+  return ok ? 0 : 1;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/examples/timeval_subtract.c b/ap/libc/glibc/glibc-2.23/manual/examples/timeval_subtract.c
new file mode 100644
index 0000000..ffac71c
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/examples/timeval_subtract.c
@@ -0,0 +1,44 @@
+/* struct timeval subtraction.
+   Copyright (C) 1991-2016 Free Software Foundation, Inc.
+
+   This program is free software; you can redistribute it and/or
+   modify it under the terms of the GNU General Public License
+   as published by the Free Software Foundation; either version 2
+   of the License, or (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, if not, see <http://www.gnu.org/licenses/>.
+*/
+
+/* Subtract the `struct timeval' values X and Y,
+   storing the result in RESULT.
+   Return 1 if the difference is negative, otherwise 0.  */
+
+int
+timeval_subtract (struct timeval *result, struct timeval *x, struct timeval *y)
+{
+  /* Perform the carry for the later subtraction by updating @var{y}. */
+  if (x->tv_usec < y->tv_usec) {
+    int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
+    y->tv_usec -= 1000000 * nsec;
+    y->tv_sec += nsec;
+  }
+  if (x->tv_usec - y->tv_usec > 1000000) {
+    int nsec = (x->tv_usec - y->tv_usec) / 1000000;
+    y->tv_usec += 1000000 * nsec;
+    y->tv_sec -= nsec;
+  }
+
+  /* Compute the time remaining to wait.
+     @code{tv_usec} is certainly positive. */
+  result->tv_sec = x->tv_sec - y->tv_sec;
+  result->tv_usec = x->tv_usec - y->tv_usec;
+
+  /* Return 1 if result is negative. */
+  return x->tv_sec < y->tv_sec;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/fdl-1.3.texi b/ap/libc/glibc/glibc-2.23/manual/fdl-1.3.texi
new file mode 100644
index 0000000..cb71f05
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/fdl-1.3.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification.  Examples
+of transparent image formats include PNG, XCF and
+JPG.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.3
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/ap/libc/glibc/glibc-2.23/manual/filesys.texi b/ap/libc/glibc/glibc-2.23/manual/filesys.texi
new file mode 100644
index 0000000..972e106
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/filesys.texi
@@ -0,0 +1,3672 @@
+@node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
+@c %MENU% Functions for manipulating files
+@chapter File System Interface
+
+This chapter describes @theglibc{}'s functions for manipulating
+files.  Unlike the input and output functions (@pxref{I/O on Streams};
+@pxref{Low-Level I/O}), these functions are concerned with operating
+on the files themselves rather than on their contents.
+
+Among the facilities described in this chapter are functions for
+examining or modifying directories, functions for renaming and deleting
+files, and functions for examining and setting file attributes such as
+access permissions and modification times.
+
+@menu
+* Working Directory::           This is used to resolve relative
+				 file names.
+* Accessing Directories::       Finding out what files a directory
+				 contains.
+* Working with Directory Trees:: Apply actions to all files or a selectable
+                                 subset of a directory hierarchy.
+* Hard Links::                  Adding alternate names to a file.
+* Symbolic Links::              A file that ``points to'' a file name.
+* Deleting Files::              How to delete a file, and what that means.
+* Renaming Files::              Changing a file's name.
+* Creating Directories::        A system call just for creating a directory.
+* File Attributes::             Attributes of individual files.
+* Making Special Files::        How to create special files.
+* Temporary Files::             Naming and creating temporary files.
+@end menu
+
+@node Working Directory
+@section Working Directory
+
+@cindex current working directory
+@cindex working directory
+@cindex change working directory
+Each process has associated with it a directory, called its @dfn{current
+working directory} or simply @dfn{working directory}, that is used in
+the resolution of relative file names (@pxref{File Name Resolution}).
+
+When you log in and begin a new session, your working directory is
+initially set to the home directory associated with your login account
+in the system user database.  You can find any user's home directory
+using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
+Database}.
+
+Users can change the working directory using shell commands like
+@code{cd}.  The functions described in this section are the primitives
+used by those commands and by other programs for examining and changing
+the working directory.
+@pindex cd
+
+Prototypes for these functions are declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c If buffer is NULL, this function calls malloc and realloc, and, in
+@c case of error, free.  Linux offers a getcwd syscall that we use on
+@c GNU/Linux systems, but it may fail if the pathname is too long.  As a
+@c fallback, and on other systems, the generic implementation opens each
+@c parent directory with opendir, which allocates memory for the
+@c directory stream with malloc.  If a fstatat64 syscall is not
+@c available, very deep directory trees may also have to malloc to build
+@c longer sequences of ../../../... than those supported by a global
+@c const read-only string.
+
+@c linux/__getcwd
+@c  posix/__getcwd
+@c   malloc/realloc/free if buffer is NULL, or if dir is too deep
+@c   lstat64 -> see its own entry
+@c   fstatat64
+@c     direct syscall if possible, alloca+snprintf+*stat64 otherwise
+@c   openat64_not_cancel_3, close_not_cancel_no_status
+@c   __fdopendir, __opendir, __readdir, rewinddir
+The @code{getcwd} function returns an absolute file name representing
+the current working directory, storing it in the character array
+@var{buffer} that you provide.  The @var{size} argument is how you tell
+the system the allocation size of @var{buffer}.
+
+The @glibcadj{} version of this function also permits you to specify a
+null pointer for the @var{buffer} argument.  Then @code{getcwd}
+allocates a buffer automatically, as with @code{malloc}
+(@pxref{Unconstrained Allocation}).  If the @var{size} is greater than
+zero, then the buffer is that large; otherwise, the buffer is as large
+as necessary to hold the result.
+
+The return value is @var{buffer} on success and a null pointer on failure.
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The @var{size} argument is zero and @var{buffer} is not a null pointer.
+
+@item ERANGE
+The @var{size} argument is less than the length of the working directory
+name.  You need to allocate a bigger array and try again.
+
+@item EACCES
+Permission to read or search a component of the file name was denied.
+@end table
+@end deftypefun
+
+You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}}
+using only the standard behavior of @code{getcwd}:
+
+@smallexample
+char *
+gnu_getcwd ()
+@{
+  size_t size = 100;
+
+  while (1)
+    @{
+      char *buffer = (char *) xmalloc (size);
+      if (getcwd (buffer, size) == buffer)
+        return buffer;
+      free (buffer);
+      if (errno != ERANGE)
+        return 0;
+      size *= 2;
+    @}
+@}
+@end smallexample
+
+@noindent
+@xref{Malloc Examples}, for information about @code{xmalloc}, which is
+not a library function but is a customary name used in most GNU
+software.
+
+@comment unistd.h
+@comment BSD
+@deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides the getcwd safety issues, it calls strerror_r on error, which
+@c brings in all of the i18n issues.
+This is similar to @code{getcwd}, but has no way to specify the size of
+the buffer.  @Theglibc{} provides @code{getwd} only
+for backwards compatibility with BSD.
+
+The @var{buffer} argument should be a pointer to an array at least
+@code{PATH_MAX} bytes long (@pxref{Limits for Files}).  On @gnuhurdsystems{}
+there is no limit to the size of a file name, so this is not
+necessarily enough space to contain the directory name.  That is why
+this function is deprecated.
+@end deftypefn
+
+@comment unistd.h
+@comment GNU
+@deftypefun {char *} get_current_dir_name (void)
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides getcwd, which this function calls as a fallback, it calls
+@c getenv, with the potential thread-safety issues that brings about.
+@vindex PWD
+This @code{get_current_dir_name} function is basically equivalent to
+@w{@code{getcwd (NULL, 0)}}.  The only difference is that the value of
+the @code{PWD} variable is returned if this value is correct.  This is a
+subtle difference which is visible if the path described by the
+@code{PWD} value is using one or more symbol links in which case the
+value returned by @code{getcwd} can resolve the symbol links and
+therefore yield a different result.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int chdir (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is used to set the process's working directory to
+@var{filename}.
+
+The normal, successful return value from @code{chdir} is @code{0}.  A
+value of @code{-1} is returned to indicate an error.  The @code{errno}
+error conditions defined for this function are the usual file name
+syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
+file @var{filename} is not a directory.
+@end deftypefun
+
+@comment unistd.h
+@comment XPG
+@deftypefun int fchdir (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is used to set the process's working directory to
+directory associated with the file descriptor @var{filedes}.
+
+The normal, successful return value from @code{fchdir} is @code{0}.  A
+value of @code{-1} is returned to indicate an error.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+Read permission is denied for the directory named by @code{dirname}.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTDIR
+The file descriptor @var{filedes} is not associated with a directory.
+
+@item EINTR
+The function call was interrupt by a signal.
+
+@item EIO
+An I/O error occurred.
+@end table
+@end deftypefun
+
+
+@node Accessing Directories
+@section Accessing Directories
+@cindex accessing directories
+@cindex reading from a directory
+@cindex directories, accessing
+
+The facilities described in this section let you read the contents of a
+directory file.  This is useful if you want your program to list all the
+files in a directory, perhaps as part of a menu.
+
+@cindex directory stream
+The @code{opendir} function opens a @dfn{directory stream} whose
+elements are directory entries.  Alternatively @code{fdopendir} can be
+used which can have advantages if the program needs to have more
+control over the way the directory is opened for reading.  This
+allows, for instance, to pass the @code{O_NOATIME} flag to
+@code{open}.
+
+You use the @code{readdir} function on the directory stream to
+retrieve these entries, represented as @w{@code{struct dirent}}
+objects.  The name of the file for each entry is stored in the
+@code{d_name} member of this structure.  There are obvious parallels
+here to the stream facilities for ordinary files, described in
+@ref{I/O on Streams}.
+
+@menu
+* 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.
+@end menu
+
+@node Directory Entries
+@subsection Format of a Directory Entry
+
+@pindex dirent.h
+This section describes what you find in a single directory entry, as you
+might obtain it from a directory stream.  All the symbols are declared
+in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftp {Data Type} {struct dirent}
+This is a structure type used to return information about directory
+entries.  It contains the following fields:
+
+@table @code
+@item char d_name[]
+This is the null-terminated file name component.  This is the only
+field you can count on in all POSIX systems.
+
+@item ino_t d_fileno
+This is the file serial number.  For BSD compatibility, you can also
+refer to this member as @code{d_ino}.  On @gnulinuxhurdsystems{} and most POSIX
+systems, for most files this the same as the @code{st_ino} member that
+@code{stat} will return for the file.  @xref{File Attributes}.
+
+@item unsigned char d_namlen
+This is the length of the file name, not including the terminating
+null character.  Its type is @code{unsigned char} because that is the
+integer type of the appropriate size.  This member is a BSD extension.
+The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is
+available.
+
+@item unsigned char d_type
+This is the type of the file, possibly unknown.  The following constants
+are defined for its value:
+
+@vtable @code
+@item DT_UNKNOWN
+The type is unknown.  Only some filesystems have full support to
+return the type of the file, others might always return this value.
+
+@item DT_REG
+A regular file.
+
+@item DT_DIR
+A directory.
+
+@item DT_FIFO
+A named pipe, or FIFO.  @xref{FIFO Special Files}.
+
+@item DT_SOCK
+A local-domain socket.  @c !!! @xref{Local Domain}.
+
+@item DT_CHR
+A character device.
+
+@item DT_BLK
+A block device.
+
+@item DT_LNK
+A symbolic link.
+@end vtable
+
+This member is a BSD extension.  The symbol @code{_DIRENT_HAVE_D_TYPE}
+is defined if this member is available.  On systems where it is used, it
+corresponds to the file type bits in the @code{st_mode} member of
+@code{struct stat}.  If the value cannot be determine the member
+value is DT_UNKNOWN.  These two macros convert between @code{d_type}
+values and @code{st_mode} values:
+
+@comment dirent.h
+@comment BSD
+@deftypefun int IFTODT (mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This returns the @code{d_type} value corresponding to @var{mode}.
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun mode_t DTTOIF (int @var{dtype})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This returns the @code{st_mode} value corresponding to @var{dtype}.
+@end deftypefun
+@end table
+
+This structure may contain additional members in the future.  Their
+availability is always announced in the compilation environment by a
+macro names @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced
+by the name of the new member.  For instance, the member @code{d_reclen}
+available on some systems is announced through the macro
+@code{_DIRENT_HAVE_D_RECLEN}.
+
+When a file has multiple names, each name has its own directory entry.
+The only way you can tell that the directory entries belong to a
+single file is that they have the same value for the @code{d_fileno}
+field.
+
+File attributes such as size, modification times etc., are part of the
+file itself, not of any particular directory entry.  @xref{File
+Attributes}.
+@end deftp
+
+@node Opening a Directory
+@subsection Opening a Directory Stream
+
+@pindex dirent.h
+This section describes how to open a directory stream.  All the symbols
+are declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftp {Data Type} DIR
+The @code{DIR} data type represents a directory stream.
+@end deftp
+
+You shouldn't ever allocate objects of the @code{struct dirent} or
+@code{DIR} data types, since the directory access functions do that for
+you.  Instead, you refer to these objects using the pointers returned by
+the following functions.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun {DIR *} opendir (const char *@var{dirname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Besides the safe syscall, we have to allocate the DIR object with
+@c __alloc_dir, that calls malloc.
+The @code{opendir} function opens and returns a directory stream for
+reading the directory whose file name is @var{dirname}.  The stream has
+type @code{DIR *}.
+
+If unsuccessful, @code{opendir} returns a null pointer.  In addition to
+the usual file name errors (@pxref{File Name Errors}), the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+Read permission is denied for the directory named by @code{dirname}.
+
+@item EMFILE
+The process has too many files open.
+
+@item ENFILE
+The entire system, or perhaps the file system which contains the
+directory, cannot support any additional open files at the moment.
+(This problem cannot happen on @gnuhurdsystems{}.)
+
+@item ENOMEM
+Not enough memory available.
+@end table
+
+The @code{DIR} type is typically implemented using a file descriptor,
+and the @code{opendir} function in terms of the @code{open} function.
+@xref{Low-Level I/O}.  Directory streams and the underlying
+file descriptors are closed on @code{exec} (@pxref{Executing a File}).
+@end deftypefun
+
+The directory which is opened for reading by @code{opendir} is
+identified by the name.  In some situations this is not sufficient.
+Or the way @code{opendir} implicitly creates a file descriptor for the
+directory is not the way a program might want it.  In these cases an
+alternative interface can be used.
+
+@comment dirent.h
+@comment GNU
+@deftypefun {DIR *} fdopendir (int @var{fd})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c The DIR object is allocated with __alloc_dir, that calls malloc.
+The @code{fdopendir} function works just like @code{opendir} but
+instead of taking a file name and opening a file descriptor for the
+directory the caller is required to provide a file descriptor.  This
+file descriptor is then used in subsequent uses of the returned
+directory stream object.
+
+The caller must make sure the file descriptor is associated with a
+directory and it allows reading.
+
+If the @code{fdopendir} call returns successfully the file descriptor
+is now under the control of the system.  It can be used in the same
+way the descriptor implicitly created by @code{opendir} can be used
+but the program must not close the descriptor.
+
+In case the function is unsuccessful it returns a null pointer and the
+file descriptor remains to be usable by the program.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The file descriptor is not valid.
+
+@item ENOTDIR
+The file descriptor is not associated with a directory.
+
+@item EINVAL
+The descriptor does not allow reading the directory content.
+
+@item ENOMEM
+Not enough memory available.
+@end table
+@end deftypefun
+
+In some situations it can be desirable to get hold of the file
+descriptor which is created by the @code{opendir} call.  For instance,
+to switch the current working directory to the directory just read the
+@code{fchdir} function could be used.  Historically the @code{DIR} type
+was exposed and programs could access the fields.  This does not happen
+in @theglibc{}.  Instead a separate function is provided to allow
+access.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int dirfd (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{dirfd} returns the file descriptor associated with
+the directory stream @var{dirstream}.  This descriptor can be used until
+the directory is closed with @code{closedir}.  If the directory stream
+implementation is not using file descriptors the return value is
+@code{-1}.
+@end deftypefun
+
+@node Reading/Closing Directory
+@subsection Reading and Closing a Directory Stream
+
+@pindex dirent.h
+This section describes how to read directory entries from a directory
+stream, and how to close the stream when you are done with it.  All the
+symbols are declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
+@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c This function holds dirstream's non-recursive lock, which brings
+@c about the usual issues with locks and async signals and cancellation,
+@c but the lock taking is not enough to make the returned value safe to
+@c use, since it points to a stream's internal buffer that can be
+@c overwritten by subsequent calls or even released by closedir.
+This function reads the next entry from the directory.  It normally
+returns a pointer to a structure containing information about the
+file.  This structure is associated with the @var{dirstream} handle
+and can be rewritten by a subsequent call.
+
+@strong{Portability Note:} On some systems @code{readdir} may not
+return entries for @file{.} and @file{..}, even though these are always
+valid file names in any directory.  @xref{File Name Resolution}.
+
+If there are no more entries in the directory or an error is detected,
+@code{readdir} returns a null pointer.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{dirstream} argument is not valid.
+@end table
+
+To distinguish between an end-of-directory condition or an error, you
+must set @code{errno} to zero before calling @code{readdir}.  To avoid
+entering an infinite loop, you should stop reading from the directory
+after the first error.
+
+In POSIX.1-2008, @code{readdir} is not thread-safe.  In @theglibc{}
+implementation, it is safe to call @code{readdir} concurrently on
+different @var{dirstream}s, but multiple threads accessing the same
+@var{dirstream} result in undefined behavior.  @code{readdir_r} is a
+fully thread-safe alternative, but suffers from poor portability (see
+below).  It is recommended that you use @code{readdir}, with external
+locking if multiple threads access the same @var{dirstream}.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+This function is a version of @code{readdir} which performs internal
+locking.  Like @code{readdir} it returns the next entry from the
+directory.  To prevent conflicts between simultaneously running
+threads the result is stored inside the @var{entry} object.
+
+@strong{Portability Note:} It is recommended to use @code{readdir}
+instead of @code{readdir_r} for the following reasons:
+
+@itemize @bullet
+@item
+On systems which do not define @code{NAME_MAX}, it may not be possible
+to use @code{readdir_r} safely because the caller does not specify the
+length of the buffer for the directory entry.
+
+@item
+On some systems, @code{readdir_r} cannot read directory entries with
+very long names.  If such a name is encountered, @theglibc{}
+implementation of @code{readdir_r} returns with an error code of
+@code{ENAMETOOLONG} after the final directory entry has been read.  On
+other systems, @code{readdir_r} may return successfully, but the
+@code{d_name} member may not be NUL-terminated or may be truncated.
+
+@item
+POSIX-1.2008 does not guarantee that @code{readdir} is thread-safe,
+even when access to the same @var{dirstream} is serialized.  But in
+current implementations (including @theglibc{}), it is safe to call
+@code{readdir} concurrently on different @var{dirstream}s, so there is
+no need to use @code{readdir_r} in most multi-threaded programs.  In
+the rare case that multiple threads need to read from the same
+@var{dirstream}, it is still better to use @code{readdir} and external
+synchronization.
+
+@item
+It is expected that future versions of POSIX will obsolete
+@code{readdir_r} and mandate the level of thread safety for
+@code{readdir} which is provided by @theglibc{} and other
+implementations today.
+@end itemize
+
+Normally @code{readdir_r} returns zero and sets @code{*@var{result}}
+to @var{entry}.  If there are no more entries in the directory or an
+error is detected, @code{readdir_r} sets @code{*@var{result}} to a
+null pointer and returns a nonzero error code, also stored in
+@code{errno}, as described for @code{readdir}.
+
+It is also important to look at the definition of the @code{struct
+dirent} type.  Simply passing a pointer to an object of this type for
+the second parameter of @code{readdir_r} might not be enough.  Some
+systems don't define the @code{d_name} element sufficiently long.  In
+this case the user has to provide additional space.  There must be room
+for at least @code{NAME_MAX + 1} characters in the @code{d_name} array.
+Code to call @code{readdir_r} could look like this:
+
+@smallexample
+  union
+  @{
+    struct dirent d;
+    char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
+  @} u;
+
+  if (readdir_r (dir, &u.d, &res) == 0)
+    @dots{}
+@end smallexample
+@end deftypefun
+
+To support large filesystems on 32-bit machines there are LFS variants
+of the last two functions.
+
+@comment dirent.h
+@comment LFS
+@deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream})
+@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{readdir64} function is just like the @code{readdir} function
+except that it returns a pointer to a record of type @code{struct
+dirent64}.  Some of the members of this data type (notably @code{d_ino})
+might have a different size to allow large filesystems.
+
+In all other aspects this function is equivalent to @code{readdir}.
+@end deftypefun
+
+@comment dirent.h
+@comment LFS
+@deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{readdir64_r} function is equivalent to the @code{readdir_r}
+function except that it takes parameters of base type @code{struct
+dirent64} instead of @code{struct dirent} in the second and third
+position.  The same precautions mentioned in the documentation of
+@code{readdir_r} also apply here.
+@end deftypefun
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun int closedir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}}
+@c No synchronization in the posix implementation, only in the hurd
+@c one.  This is regarded as safe because it is undefined behavior if
+@c other threads could still be using the dir stream while it's closed.
+This function closes the directory stream @var{dirstream}.  It returns
+@code{0} on success and @code{-1} on failure.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{dirstream} argument is not valid.
+@end table
+@end deftypefun
+
+@node Simple Directory Lister
+@subsection Simple Program to List a Directory
+
+Here's a simple program that prints the names of the files in
+the current working directory:
+
+@smallexample
+@include dir.c.texi
+@end smallexample
+
+The order in which files appear in a directory tends to be fairly
+random.  A more useful program would sort the entries (perhaps by
+alphabetizing them) before printing them; see
+@ref{Scanning Directory Content}, and @ref{Array Sort Function}.
+
+
+@node Random Access Directory
+@subsection Random Access in a Directory Stream
+
+@pindex dirent.h
+This section describes how to reread parts of a directory that you have
+already read from an open directory stream.  All the symbols are
+declared in the header file @file{dirent.h}.
+
+@comment dirent.h
+@comment POSIX.1
+@deftypefun void rewinddir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{rewinddir} function is used to reinitialize the directory
+stream @var{dirstream}, so that if you call @code{readdir} it
+returns information about the first entry in the directory again.  This
+function also notices if files have been added or removed to the
+directory since it was opened with @code{opendir}.  (Entries for these
+files might or might not be returned by @code{readdir} if they were
+added or removed since you last called @code{opendir} or
+@code{rewinddir}.)
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun {long int} telldir (DIR *@var{dirstream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
+@c The implementation is safe on most platforms, but on BSD it uses
+@c cookies, buckets and records, and the global array of pointers to
+@c dynamically allocated records is guarded by a non-recursive lock.
+The @code{telldir} function returns the file position of the directory
+stream @var{dirstream}.  You can use this value with @code{seekdir} to
+restore the directory stream to that position.
+@end deftypefun
+
+@comment dirent.h
+@comment BSD
+@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
+@c The implementation is safe on most platforms, but on BSD it uses
+@c cookies, buckets and records, and the global array of pointers to
+@c dynamically allocated records is guarded by a non-recursive lock.
+The @code{seekdir} function sets the file position of the directory
+stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
+result of a previous call to @code{telldir} on this particular stream;
+closing and reopening the directory can invalidate values returned by
+@code{telldir}.
+@end deftypefun
+
+
+@node Scanning Directory Content
+@subsection Scanning the Content of a Directory
+
+A higher-level interface to the directory handling functions is the
+@code{scandir} function.  With its help one can select a subset of the
+entries in a directory, possibly sort them and get a list of names as
+the result.
+
+@comment dirent.h
+@comment BSD/SVID
+@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **))
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c The scandir function calls __opendirat, __readdir, and __closedir to
+@c go over the named dir; malloc and realloc to allocate the namelist
+@c and copies of each selected dirent, besides the selector, if given,
+@c and qsort and the cmp functions if the latter is given.  In spite of
+@c the cleanup handler that releases memory and the file descriptor in
+@c case of synchronous cancellation, an asynchronous cancellation may
+@c still leak memory and a file descriptor.  Although readdir is unsafe
+@c in general, the use of an internal dir stream for sequential scanning
+@c of the directory with copying of dirents before subsequent calls
+@c makes the use safe, and the fact that the dir stream is private to
+@c each scandir call does away with the lock issues in readdir and
+@c closedir.
+
+The @code{scandir} function scans the contents of the directory selected
+by @var{dir}.  The result in *@var{namelist} is an array of pointers to
+structure of type @code{struct dirent} which describe all selected
+directory entries and which is allocated using @code{malloc}.  Instead
+of always getting all directory entries returned, the user supplied
+function @var{selector} can be used to decide which entries are in the
+result.  Only the entries for which @var{selector} returns a non-zero
+value are selected.
+
+Finally the entries in *@var{namelist} are sorted using the
+user-supplied function @var{cmp}.  The arguments passed to the @var{cmp}
+function are of type @code{struct dirent **}, therefore one cannot
+directly use the @code{strcmp} or @code{strcoll} functions; instead see
+the functions @code{alphasort} and @code{versionsort} below.
+
+The return value of the function is the number of entries placed in
+*@var{namelist}.  If it is @code{-1} an error occurred (either the
+directory could not be opened for reading or the malloc call failed) and
+the global variable @code{errno} contains more information on the error.
+@end deftypefun
+
+As described above the fourth argument to the @code{scandir} function
+must be a pointer to a sorting function.  For the convenience of the
+programmer @theglibc{} contains implementations of functions which
+are very helpful for this purpose.
+
+@comment dirent.h
+@comment BSD/SVID
+@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls strcoll.
+The @code{alphasort} function behaves like the @code{strcoll} function
+(@pxref{String/Array Comparison}).  The difference is that the arguments
+are not string pointers but instead they are of type
+@code{struct dirent **}.
+
+The return value of @code{alphasort} is less than, equal to, or greater
+than zero depending on the order of the two entries @var{a} and @var{b}.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Calls strverscmp, which will accesses the locale object multiple
+@c times.
+The @code{versionsort} function is like @code{alphasort} except that it
+uses the @code{strverscmp} function internally.
+@end deftypefun
+
+If the filesystem supports large files we cannot use the @code{scandir}
+anymore since the @code{dirent} structure might not able to contain all
+the information.  The LFS provides the new type @w{@code{struct
+dirent64}}.  To use this we need a new function.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **))
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c See scandir.
+The @code{scandir64} function works like the @code{scandir} function
+except that the directory entries it returns are described by elements
+of type @w{@code{struct dirent64}}.  The function pointed to by
+@var{selector} is again used to select the desired entries, except that
+@var{selector} now must point to a function which takes a
+@w{@code{struct dirent64 *}} parameter.
+
+Similarly the @var{cmp} function should expect its two arguments to be
+of type @code{struct dirent64 **}.
+@end deftypefun
+
+As @var{cmp} is now a function of a different type, the functions
+@code{alphasort} and @code{versionsort} cannot be supplied for that
+argument.  Instead we provide the two replacement functions below.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c See alphasort.
+The @code{alphasort64} function behaves like the @code{strcoll} function
+(@pxref{String/Array Comparison}).  The difference is that the arguments
+are not string pointers but instead they are of type
+@code{struct dirent64 **}.
+
+Return value of @code{alphasort64} is less than, equal to, or greater
+than zero depending on the order of the two entries @var{a} and @var{b}.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c See versionsort.
+The @code{versionsort64} function is like @code{alphasort64}, excepted that it
+uses the @code{strverscmp} function internally.
+@end deftypefun
+
+It is important not to mix the use of @code{scandir} and the 64-bit
+comparison functions or vice versa.  There are systems on which this
+works but on others it will fail miserably.
+
+@node Simple Directory Lister Mark II
+@subsection Simple Program to List a Directory, Mark II
+
+Here is a revised version of the directory lister found above
+(@pxref{Simple Directory Lister}).  Using the @code{scandir} function we
+can avoid the functions which work directly with the directory contents.
+After the call the returned entries are available for direct use.
+
+@smallexample
+@include dir2.c.texi
+@end smallexample
+
+Note the simple selector function in this example.  Since we want to see
+all directory entries we always return @code{1}.
+
+
+@node Working with Directory Trees
+@section Working with Directory Trees
+@cindex directory hierarchy
+@cindex hierarchy, directory
+@cindex tree, directory
+
+The functions described so far for handling the files in a directory
+have allowed you to either retrieve the information bit by bit, or to
+process all the files as a group (see @code{scandir}).  Sometimes it is
+useful to process whole hierarchies of directories and their contained
+files.  The X/Open specification defines two functions to do this.  The
+simpler form is derived from an early definition in @w{System V} systems
+and therefore this function is available on SVID-derived systems.  The
+prototypes and required definitions can be found in the @file{ftw.h}
+header.
+
+There are four functions in this family: @code{ftw}, @code{nftw} and
+their 64-bit counterparts @code{ftw64} and @code{nftw64}.  These
+functions take as one of their arguments a pointer to a callback
+function of the appropriate type.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __ftw_func_t
+
+@smallexample
+int (*) (const char *, const struct stat *, int)
+@end smallexample
+
+The type of callback functions given to the @code{ftw} function.  The
+first parameter points to the file name, the second parameter to an
+object of type @code{struct stat} which is filled in for the file named
+in the first parameter.
+
+@noindent
+The last parameter is a flag giving more information about the current
+file.  It can have the following values:
+
+@vtable @code
+@item FTW_F
+The item is either a normal file or a file which does not fit into one
+of the following categories.  This could be special files, sockets etc.
+@item FTW_D
+The item is a directory.
+@item FTW_NS
+The @code{stat} call failed and so the information pointed to by the
+second paramater is invalid.
+@item FTW_DNR
+The item is a directory which cannot be read.
+@item FTW_SL
+The item is a symbolic link.  Since symbolic links are normally followed
+seeing this value in a @code{ftw} callback function means the referenced
+file does not exist.  The situation for @code{nftw} is different.
+
+This value is only available if the program is compiled with
+@code{_XOPEN_EXTENDED} defined before including
+the first header.  The original SVID systems do not have symbolic links.
+@end vtable
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__ftw64_func_t} since this mode changes
+@code{struct stat} to be @code{struct stat64}.
+@end deftp
+
+For the LFS interface and for use in the function @code{ftw64}, the
+header @file{ftw.h} defines another function type.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __ftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int)
+@end smallexample
+
+This type is used just like @code{__ftw_func_t} for the callback
+function, but this time is called from @code{ftw64}.  The second
+parameter to the function is a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __nftw_func_t
+
+@smallexample
+int (*) (const char *, const struct stat *, int, struct FTW *)
+@end smallexample
+
+@vindex FTW_DP
+@vindex FTW_SLN
+The first three arguments are the same as for the @code{__ftw_func_t}
+type.  However for the third argument some additional values are defined
+to allow finer differentiation:
+@table @code
+@item FTW_DP
+The current item is a directory and all subdirectories have already been
+visited and reported.  This flag is returned instead of @code{FTW_D} if
+the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below).
+@item FTW_SLN
+The current item is a stale symbolic link.  The file it points to does
+not exist.
+@end table
+
+The last parameter of the callback function is a pointer to a structure
+with some extra information as described below.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+type is in fact @code{__nftw64_func_t} since this mode changes
+@code{struct stat} to be @code{struct stat64}.
+@end deftp
+
+For the LFS interface there is also a variant of this data type
+available which has to be used with the @code{nftw64} function.
+
+@comment ftw.h
+@comment GNU
+@deftp {Data Type} __nftw64_func_t
+
+@smallexample
+int (*) (const char *, const struct stat64 *, int, struct FTW *)
+@end smallexample
+
+This type is used just like @code{__nftw_func_t} for the callback
+function, but this time is called from @code{nftw64}.  The second
+parameter to the function is this time a pointer to a variable of type
+@code{struct stat64} which is able to represent the larger values.
+@end deftp
+
+@comment ftw.h
+@comment XPG4.2
+@deftp {Data Type} {struct FTW}
+The information contained in this structure helps in interpreting the
+name parameter and gives some information about the current state of the
+traversal of the directory hierarchy.
+
+@table @code
+@item int base
+The value is the offset into the string passed in the first parameter to
+the callback function of the beginning of the file name.  The rest of
+the string is the path of the file.  This information is especially
+important if the @code{FTW_CHDIR} flag was set in calling @code{nftw}
+since then the current directory is the one the current item is found
+in.
+@item int level
+Whilst processing, the code tracks how many directories down it has gone
+to find the current file.  This nesting level starts at @math{0} for
+files in the initial directory (or is zero for the initial file if a
+file was passed).
+@end table
+@end deftp
+
+
+@comment ftw.h
+@comment SVID
+@deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c see nftw for safety details
+The @code{ftw} function calls the callback function given in the
+parameter @var{func} for every item which is found in the directory
+specified by @var{filename} and all directories below.  The function
+follows symbolic links if necessary but does not process an item twice.
+If @var{filename} is not a directory then it itself is the only object
+returned to the callback function.
+
+The file name passed to the callback function is constructed by taking
+the @var{filename} parameter and appending the names of all passed
+directories and then the local file name.  So the callback function can
+use this parameter to access the file.  @code{ftw} also calls
+@code{stat} for the file and passes that information on to the callback
+function.  If this @code{stat} call was not successful the failure is
+indicated by setting the third argument of the callback function to
+@code{FTW_NS}.  Otherwise it is set according to the description given
+in the account of @code{__ftw_func_t} above.
+
+The callback function is expected to return @math{0} to indicate that no
+error occurred and that processing should continue.  If an error
+occurred in the callback function or it wants @code{ftw} to return
+immediately, the callback function can return a value other than
+@math{0}.  This is the only correct way to stop the function.  The
+program must not use @code{setjmp} or similar techniques to continue
+from another place.  This would leave resources allocated by the
+@code{ftw} function unfreed.
+
+The @var{descriptors} parameter to @code{ftw} specifies how many file
+descriptors it is allowed to consume.  The function runs faster the more
+descriptors it can use.  For each level in the directory hierarchy at
+most one descriptor is used, but for very deep ones any limit on open
+file descriptors for the process or the system may be exceeded.
+Moreover, file descriptor limits in a multi-threaded program apply to
+all the threads as a group, and therefore it is a good idea to supply a
+reasonable limit to the number of open descriptors.
+
+The return value of the @code{ftw} function is @math{0} if all callback
+function calls returned @math{0} and all actions performed by the
+@code{ftw} succeeded.  If a function call failed (other than calling
+@code{stat} on an item) the function returns @math{-1}.  If a callback
+function returns a value other than @math{0} this value is returned as
+the return value of @code{ftw}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{ftw64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+This function is similar to @code{ftw} but it can work on filesystems
+with large files.  File information is reported using a variable of type
+@code{struct stat64} which is passed by reference to the callback
+function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is available under the name @code{ftw} and
+transparently replaces the old implementation.
+@end deftypefun
+
+@comment ftw.h
+@comment XPG4.2
+@deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag})
+@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
+@c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir
+@c  if FTW_CHDIR, call open, and fchdir, or chdir and getcwd
+@c ftw_dir calls open_dir_stream, readdir64, process_entry, closedir
+@c  if FTW_CHDIR, also calls fchdir
+@c open_dir_stream calls malloc, realloc, readdir64, free, closedir,
+@c  then openat64_not_cancel_3 and fdopendir or opendir, then dirfd.
+@c process_entry may cal realloc, fxstatat/lxstat/xstat, ftw_dir, and
+@c  find_object (tsearch) and add_object (tfind).
+@c Since each invocation of *ftw uses its own private search tree, none
+@c  of the search tree concurrency issues apply.
+The @code{nftw} function works like the @code{ftw} functions.  They call
+the callback function @var{func} for all items found in the directory
+@var{filename} and below.  At most @var{descriptors} file descriptors
+are consumed during the @code{nftw} call.
+
+One difference is that the callback function is of a different type.  It
+is of type @w{@code{struct FTW *}} and provides the callback function
+with the extra information described above.
+
+A second difference is that @code{nftw} takes a fourth argument, which
+is @math{0} or a bitwise-OR combination of any of the following values.
+
+@vtable @code
+@item FTW_PHYS
+While traversing the directory symbolic links are not followed.  Instead
+symbolic links are reported using the @code{FTW_SL} value for the type
+parameter to the callback function.  If the file referenced by a
+symbolic link does not exist @code{FTW_SLN} is returned instead.
+@item FTW_MOUNT
+The callback function is only called for items which are on the same
+mounted filesystem as the directory given by the @var{filename}
+parameter to @code{nftw}.
+@item FTW_CHDIR
+If this flag is given the current working directory is changed to the
+directory of the reported object before the callback function is called.
+When @code{ntfw} finally returns the current directory is restored to
+its original value.
+@item FTW_DEPTH
+If this option is specified then all subdirectories and files within
+them are processed before processing the top directory itself
+(depth-first processing).  This also means the type flag given to the
+callback function is @code{FTW_DP} and not @code{FTW_D}.
+@item FTW_ACTIONRETVAL
+If this option is specified then return values from callbacks
+are handled differently.  If the callback returns @code{FTW_CONTINUE},
+walking continues normally.  @code{FTW_STOP} means walking stops
+and @code{FTW_STOP} is returned to the caller.  If @code{FTW_SKIP_SUBTREE}
+is returned by the callback with @code{FTW_D} argument, the subtree
+is skipped and walking continues with next sibling of the directory.
+If @code{FTW_SKIP_SIBLINGS} is returned by the callback, all siblings
+of the current entry are skipped and walking continues in its parent.
+No other return values should be returned from the callbacks if
+this option is set.  This option is a GNU extension.
+@end vtable
+
+The return value is computed in the same way as for @code{ftw}.
+@code{nftw} returns @math{0} if no failures occurred and all callback
+functions returned @math{0}.  In case of internal errors, such as memory
+problems, the return value is @math{-1} and @var{errno} is set
+accordingly.  If the return value of a callback invocation was non-zero
+then that value is returned.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{nftw64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment ftw.h
+@comment Unix98
+@deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag})
+@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
+This function is similar to @code{nftw} but it can work on filesystems
+with large files.  File information is reported using a variable of type
+@code{struct stat64} which is passed by reference to the callback
+function.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is available under the name @code{nftw} and
+transparently replaces the old implementation.
+@end deftypefun
+
+
+@node Hard Links
+@section Hard Links
+@cindex hard link
+@cindex link, hard
+@cindex multiple names for one file
+@cindex file names, multiple
+
+In POSIX systems, one file can have many names at the same time.  All of
+the names are equally real, and no one of them is preferred to the
+others.
+
+To add a name to a file, use the @code{link} function.  (The new name is
+also called a @dfn{hard link} to the file.)  Creating a new link to a
+file does not copy the contents of the file; it simply makes a new name
+by which the file can be known, in addition to the file's existing name
+or names.
+
+One file can have names in several directories, so the organization
+of the file system is not a strict hierarchy or tree.
+
+In most implementations, it is not possible to have hard links to the
+same file in multiple file systems.  @code{link} reports an error if you
+try to make a hard link to the file from another file system when this
+cannot be done.
+
+The prototype for the @code{link} function is declared in the header
+file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int link (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{link} function makes a new link to the existing file named by
+@var{oldname}, under the new name @var{newname}.
+
+This function returns a value of @code{0} if it is successful and
+@code{-1} on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+You are not allowed to write to the directory in which the new link is
+to be written.
+@ignore
+Some implementations also require that the existing file be accessible
+by the caller, and use this error to report failure for that reason.
+@end ignore
+
+@item EEXIST
+There is already a file named @var{newname}.  If you want to replace
+this link with a new link, you must remove the old link explicitly first.
+
+@item EMLINK
+There are already too many links to the file named by @var{oldname}.
+(The maximum number of links to a file is @w{@code{LINK_MAX}}; see
+@ref{Limits for Files}.)
+
+@item ENOENT
+The file named by @var{oldname} doesn't exist.  You can't make a link to
+a file that doesn't exist.
+
+@item ENOSPC
+The directory or file system that would contain the new link is full
+and cannot be extended.
+
+@item EPERM
+On @gnulinuxhurdsystems{} and some others, you cannot make links to
+directories.
+Many systems allow only privileged users to do so.  This error
+is used to report the problem.
+
+@item EROFS
+The directory containing the new link can't be modified because it's on
+a read-only file system.
+
+@item EXDEV
+The directory specified in @var{newname} is on a different file system
+than the existing file.
+
+@item EIO
+A hardware error occurred while trying to read or write the to filesystem.
+@end table
+@end deftypefun
+
+@node Symbolic Links
+@section Symbolic Links
+@cindex soft link
+@cindex link, soft
+@cindex symbolic link
+@cindex link, symbolic
+
+@gnusystems{} support @dfn{soft links} or @dfn{symbolic links}.  This
+is a kind of ``file'' that is essentially a pointer to another file
+name.  Unlike hard links, symbolic links can be made to directories or
+across file systems with no restrictions.  You can also make a symbolic
+link to a name which is not the name of any file.  (Opening this link
+will fail until a file by that name is created.)  Likewise, if the
+symbolic link points to an existing file which is later deleted, the
+symbolic link continues to point to the same file name even though the
+name no longer names any file.
+
+The reason symbolic links work the way they do is that special things
+happen when you try to open the link.  The @code{open} function realizes
+you have specified the name of a link, reads the file name contained in
+the link, and opens that file name instead.  The @code{stat} function
+likewise operates on the file that the symbolic link points to, instead
+of on the link itself.
+
+By contrast, other operations such as deleting or renaming the file
+operate on the link itself.  The functions @code{readlink} and
+@code{lstat} also refrain from following symbolic links, because their
+purpose is to obtain information about the link.  @code{link}, the
+function that makes a hard link, does too.  It makes a hard link to the
+symbolic link, which one rarely wants.
+
+Some systems have for some functions operating on files have a limit on
+how many symbolic links are followed when resolving a path name.  The
+limit if it exists is published in the @file{sys/param.h} header file.
+
+@comment sys/param.h
+@comment BSD
+@deftypevr Macro int MAXSYMLINKS
+
+The macro @code{MAXSYMLINKS} specifies how many symlinks some function
+will follow before returning @code{ELOOP}.  Not all functions behave the
+same and this value is not the same a that returned for
+@code{_SC_SYMLOOP} by @code{sysconf}.  In fact, the @code{sysconf}
+result can indicate that there is no fixed limit although
+@code{MAXSYMLINKS} exists and has a finite value.
+@end deftypevr
+
+Prototypes for most of the functions listed in this section are in
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment BSD
+@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{symlink} function makes a symbolic link to @var{oldname} named
+@var{newname}.
+
+The normal return value from @code{symlink} is @code{0}.  A return value
+of @code{-1} indicates an error.  In addition to the usual file name
+syntax errors (@pxref{File Name Errors}), the following @code{errno}
+error conditions are defined for this function:
+
+@table @code
+@item EEXIST
+There is already an existing file named @var{newname}.
+
+@item EROFS
+The file @var{newname} would exist on a read-only file system.
+
+@item ENOSPC
+The directory or file system cannot be extended to make the new link.
+
+@item EIO
+A hardware error occurred while reading or writing data on the disk.
+
+@ignore
+@comment not sure about these
+@item ELOOP
+There are too many levels of indirection.  This can be the result of
+circular symbolic links to directories.
+
+@item EDQUOT
+The new link can't be created because the user's disk quota has been
+exceeded.
+@end ignore
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{readlink} function gets the value of the symbolic link
+@var{filename}.  The file name that the link points to is copied into
+@var{buffer}.  This file name string is @emph{not} null-terminated;
+@code{readlink} normally returns the number of characters copied.  The
+@var{size} argument specifies the maximum number of characters to copy,
+usually the allocation size of @var{buffer}.
+
+If the return value equals @var{size}, you cannot tell whether or not
+there was room to return the entire name.  So make a bigger buffer and
+call @code{readlink} again.  Here is an example:
+
+@smallexample
+char *
+readlink_malloc (const char *filename)
+@{
+  int size = 100;
+  char *buffer = NULL;
+
+  while (1)
+    @{
+      buffer = (char *) xrealloc (buffer, size);
+      int nchars = readlink (filename, buffer, size);
+      if (nchars < 0)
+        @{
+          free (buffer);
+          return NULL;
+        @}
+      if (nchars < size)
+        return buffer;
+      size *= 2;
+    @}
+@}
+@end smallexample
+
+@c @group  Invalid outside example.
+A value of @code{-1} is returned in case of error.  In addition to the
+usual file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The named file is not a symbolic link.
+
+@item EIO
+A hardware error occurred while reading or writing data on the disk.
+@end table
+@c @end group
+@end deftypefun
+
+In some situations it is desirable to resolve all the
+symbolic links to get the real
+name of a file where no prefix names a symbolic link which is followed
+and no filename in the path is @code{.} or @code{..}.  This is for
+instance desirable if files have to be compare in which case different
+names can refer to the same inode.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} canonicalize_file_name (const char *@var{name})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Calls realpath.
+
+The @code{canonicalize_file_name} function returns the absolute name of
+the file named by @var{name} which contains no @code{.}, @code{..}
+components nor any repeated path separators (@code{/}) or symlinks.  The
+result is passed back as the return value of the function in a block of
+memory allocated with @code{malloc}.  If the result is not used anymore
+the memory should be freed with a call to @code{free}.
+
+If any of the path components is missing the function returns a NULL
+pointer.  This is also what is returned if the length of the path
+reaches or exceeds @code{PATH_MAX} characters.  In any case
+@code{errno} is set accordingly.
+
+@table @code
+@item ENAMETOOLONG
+The resulting path is too long.  This error only occurs on systems which
+have a limit on the file name length.
+
+@item EACCES
+At least one of the path components is not readable.
+
+@item ENOENT
+The input file name is empty.
+
+@item ENOENT
+At least one of the path components does not exist.
+
+@item ELOOP
+More than @code{MAXSYMLINKS} many symlinks have been followed.
+@end table
+
+This function is a GNU extension and is declared in @file{stdlib.h}.
+@end deftypefun
+
+The Unix standard includes a similar function which differs from
+@code{canonicalize_file_name} in that the user has to provide the buffer
+where the result is placed in.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca.
+
+A call to @code{realpath} where the @var{resolved} parameter is
+@code{NULL} behaves exactly like @code{canonicalize_file_name}.  The
+function allocates a buffer for the file name and returns a pointer to
+it.  If @var{resolved} is not @code{NULL} it points to a buffer into
+which the result is copied.  It is the callers responsibility to
+allocate a buffer which is large enough.  On systems which define
+@code{PATH_MAX} this means the buffer must be large enough for a
+pathname of this size.  For systems without limitations on the pathname
+length the requirement cannot be met and programs should not call
+@code{realpath} with anything but @code{NULL} for the second parameter.
+
+One other difference is that the buffer @var{resolved} (if nonzero) will
+contain the part of the path component which does not exist or is not
+readable if the function returns @code{NULL} and @code{errno} is set to
+@code{EACCES} or @code{ENOENT}.
+
+This function is declared in @file{stdlib.h}.
+@end deftypefun
+
+The advantage of using this function is that it is more widely
+available.  The drawback is that it reports failures for long path on
+systems which have no limits on the file name length.
+
+@node Deleting Files
+@section Deleting Files
+@cindex deleting a file
+@cindex removing a file
+@cindex unlinking a file
+
+You can delete a file with @code{unlink} or @code{remove}.
+
+Deletion actually deletes a file name.  If this is the file's only name,
+then the file is deleted as well.  If the file has other remaining names
+(@pxref{Hard Links}), it remains accessible under those names.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int unlink (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{unlink} function deletes the file name @var{filename}.  If
+this is a file's sole name, the file itself is also deleted.  (Actually,
+if any process has the file open when this happens, deletion is
+postponed until all processes have closed the file.)
+
+@pindex unistd.h
+The function @code{unlink} is declared in the header file @file{unistd.h}.
+
+This function returns @code{0} on successful completion, and @code{-1}
+on error.  In addition to the usual file name errors
+(@pxref{File Name Errors}), the following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EACCES
+Write permission is denied for the directory from which the file is to be
+removed, or the directory has the sticky bit set and you do not own the file.
+
+@item EBUSY
+This error indicates that the file is being used by the system in such a
+way that it can't be unlinked.  For example, you might see this error if
+the file name specifies the root directory or a mount point for a file
+system.
+
+@item ENOENT
+The file name to be deleted doesn't exist.
+
+@item EPERM
+On some systems @code{unlink} cannot be used to delete the name of a
+directory, or at least can only be used this way by a privileged user.
+To avoid such problems, use @code{rmdir} to delete directories.  (On
+@gnulinuxhurdsystems{} @code{unlink} can never delete the name of a directory.)
+
+@item EROFS
+The directory containing the file name to be deleted is on a read-only
+file system and can't be modified.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int rmdir (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@cindex directories, deleting
+@cindex deleting a directory
+The @code{rmdir} function deletes a directory.  The directory must be
+empty before it can be removed; in other words, it can only contain
+entries for @file{.} and @file{..}.
+
+In most other respects, @code{rmdir} behaves like @code{unlink}.  There
+are two additional @code{errno} error conditions defined for
+@code{rmdir}:
+
+@table @code
+@item ENOTEMPTY
+@itemx EEXIST
+The directory to be deleted is not empty.
+@end table
+
+These two error codes are synonymous; some systems use one, and some use
+the other.  @gnulinuxhurdsystems{} always use @code{ENOTEMPTY}.
+
+The prototype for this function is declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int remove (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Calls unlink and rmdir.
+This is the @w{ISO C} function to remove a file.  It works like
+@code{unlink} for files and like @code{rmdir} for directories.
+@code{remove} is declared in @file{stdio.h}.
+@pindex stdio.h
+@end deftypefun
+
+@node Renaming Files
+@section Renaming Files
+
+The @code{rename} function is used to change a file's name.
+
+@cindex renaming a file
+@comment stdio.h
+@comment ISO
+@deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a rename syscall, there's an emulation with link
+@c and unlink, but it's racy, even more so if newname exists and is
+@c unlinked first.
+The @code{rename} function renames the file @var{oldname} to
+@var{newname}.  The file formerly accessible under the name
+@var{oldname} is afterwards accessible as @var{newname} instead.  (If
+the file had any other names aside from @var{oldname}, it continues to
+have those names.)
+
+The directory containing the name @var{newname} must be on the same file
+system as the directory containing the name @var{oldname}.
+
+One special case for @code{rename} is when @var{oldname} and
+@var{newname} are two names for the same file.  The consistent way to
+handle this case is to delete @var{oldname}.  However, in this case
+POSIX requires that @code{rename} do nothing and report success---which
+is inconsistent.  We don't know what your operating system will do.
+
+If @var{oldname} is not a directory, then any existing file named
+@var{newname} is removed during the renaming operation.  However, if
+@var{newname} is the name of a directory, @code{rename} fails in this
+case.
+
+If @var{oldname} is a directory, then either @var{newname} must not
+exist or it must name a directory that is empty.  In the latter case,
+the existing directory named @var{newname} is deleted first.  The name
+@var{newname} must not specify a subdirectory of the directory
+@code{oldname} which is being renamed.
+
+One useful feature of @code{rename} is that the meaning of @var{newname}
+changes ``atomically'' from any previously existing file by that name to
+its new meaning (i.e., the file that was called @var{oldname}).  There is
+no instant at which @var{newname} is non-existent ``in between'' the old
+meaning and the new meaning.  If there is a system crash during the
+operation, it is possible for both names to still exist; but
+@var{newname} will always be intact if it exists at all.
+
+If @code{rename} fails, it returns @code{-1}.  In addition to the usual
+file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+One of the directories containing @var{newname} or @var{oldname}
+refuses write permission; or @var{newname} and @var{oldname} are
+directories and write permission is refused for one of them.
+
+@item EBUSY
+A directory named by @var{oldname} or @var{newname} is being used by
+the system in a way that prevents the renaming from working.  This includes
+directories that are mount points for filesystems, and directories
+that are the current working directories of processes.
+
+@item ENOTEMPTY
+@itemx EEXIST
+The directory @var{newname} isn't empty.  @gnulinuxhurdsystems{} always return
+@code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
+
+@item EINVAL
+@var{oldname} is a directory that contains @var{newname}.
+
+@item EISDIR
+@var{newname} is a directory but the @var{oldname} isn't.
+
+@item EMLINK
+The parent directory of @var{newname} would have too many links
+(entries).
+
+@item ENOENT
+The file @var{oldname} doesn't exist.
+
+@item ENOSPC
+The directory that would contain @var{newname} has no room for another
+entry, and there is no space left in the file system to expand it.
+
+@item EROFS
+The operation would involve writing to a directory on a read-only file
+system.
+
+@item EXDEV
+The two file names @var{newname} and @var{oldname} are on different
+file systems.
+@end table
+@end deftypefun
+
+@node Creating Directories
+@section Creating Directories
+@cindex creating a directory
+@cindex directories, creating
+
+@pindex mkdir
+Directories are created with the @code{mkdir} function.  (There is also
+a shell command @code{mkdir} which does the same thing.)
+@c !!! umask
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{mkdir} function creates a new, empty directory with name
+@var{filename}.
+
+The argument @var{mode} specifies the file permissions for the new
+directory file.  @xref{Permission Bits}, for more information about
+this.
+
+A return value of @code{0} indicates successful completion, and
+@code{-1} indicates failure.  In addition to the usual file name syntax
+errors (@pxref{File Name Errors}), the following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EACCES
+Write permission is denied for the parent directory in which the new
+directory is to be added.
+
+@item EEXIST
+A file named @var{filename} already exists.
+
+@item EMLINK
+The parent directory has too many links (entries).
+
+Well-designed file systems never report this error, because they permit
+more links than your disk could possibly hold.  However, you must still
+take account of the possibility of this error, as it could result from
+network access to a file system on another machine.
+
+@item ENOSPC
+The file system doesn't have enough room to create the new directory.
+
+@item EROFS
+The parent directory of the directory being created is on a read-only
+file system and cannot be modified.
+@end table
+
+To use this function, your program should include the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+@end deftypefun
+
+@node File Attributes
+@section File Attributes
+
+@pindex ls
+When you issue an @samp{ls -l} shell command on a file, it gives you
+information about the size of the file, who owns it, when it was last
+modified, etc.  These are called the @dfn{file attributes}, and are
+associated with the file itself and not a particular one of its names.
+
+This section contains information about how you can inquire about and
+modify the attributes of a file.
+
+@menu
+* 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@dots{}
+* 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.
+* File Size::			Manually changing the size of a file.
+* Storage Allocation::          Allocate backing storage for files.
+@end menu
+
+@node Attribute Meanings
+@subsection The meaning of the File Attributes
+@cindex status of a file
+@cindex attributes of a file
+@cindex file attributes
+
+When you read the attributes of a file, they come back in a structure
+called @code{struct stat}.  This section describes the names of the
+attributes, their data types, and what they mean.  For the functions
+to read the attributes of a file, see @ref{Reading Attributes}.
+
+The header file @file{sys/stat.h} declares all the symbols defined
+in this section.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftp {Data Type} {struct stat}
+The @code{stat} structure type is used to return information about the
+attributes of a file.  It contains at least the following members:
+
+@table @code
+@item mode_t st_mode
+Specifies the mode of the file.  This includes file type information
+(@pxref{Testing File Type}) and the file permission bits
+(@pxref{Permission Bits}).
+
+@item ino_t st_ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+
+@item dev_t st_dev
+Identifies the device containing the file.  The @code{st_ino} and
+@code{st_dev}, taken together, uniquely identify the file.  The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
+
+@item nlink_t st_nlink
+The number of hard links to the file.  This count keeps track of how
+many directories have entries for this file.  If the count is ever
+decremented to zero, then the file itself is discarded as soon as no
+process still holds it open.  Symbolic links are not counted in the
+total.
+
+@item uid_t st_uid
+The user ID of the file's owner.  @xref{File Owner}.
+
+@item gid_t st_gid
+The group ID of the file.  @xref{File Owner}.
+
+@item off_t st_size
+This specifies the size of a regular file in bytes.  For files that are
+really devices this field isn't usually meaningful.  For symbolic links
+this specifies the length of the file name the link refers to.
+
+@item time_t st_atime
+This is the last access time for the file.  @xref{File Times}.
+
+@item unsigned long int st_atime_usec
+This is the fractional part of the last access time for the file.
+@xref{File Times}.
+
+@item time_t st_mtime
+This is the time of the last modification to the contents of the file.
+@xref{File Times}.
+
+@item unsigned long int st_mtime_usec
+This is the fractional part of the time of the last modification to the
+contents of the file.  @xref{File Times}.
+
+@item time_t st_ctime
+This is the time of the last modification to the attributes of the file.
+@xref{File Times}.
+
+@item unsigned long int st_ctime_usec
+This is the fractional part of the time of the last modification to the
+attributes of the file.  @xref{File Times}.
+
+@c !!! st_rdev
+@item blkcnt_t st_blocks
+This is the amount of disk space that the file occupies, measured in
+units of 512-byte blocks.
+
+The number of disk blocks is not strictly proportional to the size of
+the file, for two reasons: the file system may use some blocks for
+internal record keeping; and the file may be sparse---it may have
+``holes'' which contain zeros but do not actually take up space on the
+disk.
+
+You can tell (approximately) whether a file is sparse by comparing this
+value with @code{st_size}, like this:
+
+@smallexample
+(st.st_blocks * 512 < st.st_size)
+@end smallexample
+
+This test is not perfect because a file that is just slightly sparse
+might not be detected as sparse at all.  For practical applications,
+this is not a problem.
+
+@item unsigned int st_blksize
+The optimal block size for reading of writing this file, in bytes.  You
+might use this size for allocating the buffer space for reading of
+writing the file.  (This is unrelated to @code{st_blocks}.)
+@end table
+@end deftp
+
+The extensions for the Large File Support (LFS) require, even on 32-bit
+machines, types which can handle file sizes up to @twoexp{63}.
+Therefore a new definition of @code{struct stat} is necessary.
+
+@comment sys/stat.h
+@comment LFS
+@deftp {Data Type} {struct stat64}
+The members of this type are the same and have the same names as those
+in @code{struct stat}.  The only difference is that the members
+@code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
+type to support larger values.
+
+@table @code
+@item mode_t st_mode
+Specifies the mode of the file.  This includes file type information
+(@pxref{Testing File Type}) and the file permission bits
+(@pxref{Permission Bits}).
+
+@item ino64_t st_ino
+The file serial number, which distinguishes this file from all other
+files on the same device.
+
+@item dev_t st_dev
+Identifies the device containing the file.  The @code{st_ino} and
+@code{st_dev}, taken together, uniquely identify the file.  The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
+
+@item nlink_t st_nlink
+The number of hard links to the file.  This count keeps track of how
+many directories have entries for this file.  If the count is ever
+decremented to zero, then the file itself is discarded as soon as no
+process still holds it open.  Symbolic links are not counted in the
+total.
+
+@item uid_t st_uid
+The user ID of the file's owner.  @xref{File Owner}.
+
+@item gid_t st_gid
+The group ID of the file.  @xref{File Owner}.
+
+@item off64_t st_size
+This specifies the size of a regular file in bytes.  For files that are
+really devices this field isn't usually meaningful.  For symbolic links
+this specifies the length of the file name the link refers to.
+
+@item time_t st_atime
+This is the last access time for the file.  @xref{File Times}.
+
+@item unsigned long int st_atime_usec
+This is the fractional part of the last access time for the file.
+@xref{File Times}.
+
+@item time_t st_mtime
+This is the time of the last modification to the contents of the file.
+@xref{File Times}.
+
+@item unsigned long int st_mtime_usec
+This is the fractional part of the time of the last modification to the
+contents of the file.  @xref{File Times}.
+
+@item time_t st_ctime
+This is the time of the last modification to the attributes of the file.
+@xref{File Times}.
+
+@item unsigned long int st_ctime_usec
+This is the fractional part of the time of the last modification to the
+attributes of the file.  @xref{File Times}.
+
+@c !!! st_rdev
+@item blkcnt64_t st_blocks
+This is the amount of disk space that the file occupies, measured in
+units of 512-byte blocks.
+
+@item unsigned int st_blksize
+The optimal block size for reading of writing this file, in bytes.  You
+might use this size for allocating the buffer space for reading of
+writing the file.  (This is unrelated to @code{st_blocks}.)
+@end table
+@end deftp
+
+Some of the file attributes have special data type names which exist
+specifically for those attributes.  (They are all aliases for well-known
+integer types that you know and love.)  These typedef names are defined
+in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
+Here is a list of them.
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} mode_t
+This is an integer data type used to represent file modes.  In
+@theglibc{}, this is an unsigned type no narrower than @code{unsigned
+int}.
+@end deftp
+
+@cindex inode number
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} ino_t
+This is an unsigned integer type used to represent file serial numbers.
+(In Unix jargon, these are sometimes called @dfn{inode numbers}.)
+In @theglibc{}, this type is no narrower than @code{unsigned int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{ino64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} ino64_t
+This is an unsigned integer type used to represent file serial numbers
+for the use in LFS.  In @theglibc{}, this type is no narrower than
+@code{unsigned int}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{ino_t}.
+@end deftp
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} dev_t
+This is an arithmetic data type used to represent file device numbers.
+In @theglibc{}, this is an integer type no narrower than @code{int}.
+@end deftp
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} nlink_t
+This is an integer type used to represent file link counts.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt_t
+This is a signed integer type used to represent block counts.
+In @theglibc{}, this type is no narrower than @code{int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{blkcnt64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} blkcnt64_t
+This is a signed integer type used to represent block counts for the
+use in LFS.  In @theglibc{}, this type is no narrower than @code{int}.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{blkcnt_t}.
+@end deftp
+
+@node Reading Attributes
+@subsection Reading the Attributes of a File
+
+To examine the attributes of files, use the functions @code{stat},
+@code{fstat} and @code{lstat}.  They return the attribute information in
+a @code{struct stat} object.  All three functions are declared in the
+header file @file{sys/stat.h}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{stat} function returns information about the attributes of the
+file named by @w{@var{filename}} in the structure pointed to by @var{buf}.
+
+If @var{filename} is the name of a symbolic link, the attributes you get
+describe the file that the link points to.  If the link points to a
+nonexistent file name, then @code{stat} fails reporting a nonexistent
+file.
+
+The return value is @code{0} if the operation is successful, or
+@code{-1} on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}, the following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item ENOENT
+The file named by @var{filename} doesn't exist.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{stat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{stat} but it is also able to work on
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{stat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fstat} function is like @code{stat}, except that it takes an
+open file descriptor as an argument instead of a file name.
+@xref{Low-Level I/O}.
+
+Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined for
+@code{fstat}:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{fstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{fstat} but is able to work on large
+files on 32-bit platforms.  For large files the file descriptor
+@var{filedes} should be obtained by @code{open64} or @code{creat64}.
+The @var{buf} pointer points to a variable of type @code{struct stat64}
+which is able to represent the larger values.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{fstat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@c fstatat will call alloca and snprintf if the syscall is not
+@c available.
+@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct system call through lxstat, sometimes with an xstat conv call
+@c afterwards.
+The @code{lstat} function is like @code{stat}, except that it does not
+follow symbolic links.  If @var{filename} is the name of a symbolic
+link, @code{lstat} returns information about the link itself; otherwise
+@code{lstat} works like @code{stat}.  @xref{Symbolic Links}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{lstat64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment sys/stat.h
+@comment Unix98
+@deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct system call through lxstat64, sometimes with an xstat conv
+@c call afterwards.
+This function is similar to @code{lstat} but it is also able to work on
+files larger than @twoexp{31} bytes on 32-bit systems.  To be able to do
+this the result is stored in a variable of type @code{struct stat64} to
+which @var{buf} must point.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{lstat} and so transparently
+replaces the interface for small files on 32-bit machines.
+@end deftypefun
+
+@node Testing File Type
+@subsection Testing the Type of a File
+
+The @dfn{file mode}, stored in the @code{st_mode} field of the file
+attributes, contains two kinds of information: the file type code, and
+the access permission bits.  This section discusses only the type code,
+which you can use to tell whether the file is a directory, socket,
+symbolic link, and so on.  For details about access permissions see
+@ref{Permission Bits}.
+
+There are two ways you can access the file type information in a file
+mode.  Firstly, for each file type there is a @dfn{predicate macro}
+which examines a given file mode and returns whether it is of that type
+or not.  Secondly, you can mask out the rest of the file mode to leave
+just the file type code, and compare this against constants for each of
+the supported file types.
+
+All of the symbols listed in this section are defined in the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+
+The following predicate macros test the type of a file, given the value
+@var{m} which is the @code{st_mode} field returned by @code{stat} on
+that file:
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISDIR (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a directory.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISCHR (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a character special file (a
+device like a terminal).
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISBLK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a block special file (a device
+like a disk).
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISREG (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a regular file.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_ISFIFO (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a FIFO special file, or a
+pipe.  @xref{Pipes and FIFOs}.
+@end deftypefn
+
+@comment sys/stat.h
+@comment GNU
+@deftypefn Macro int S_ISLNK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a symbolic link.
+@xref{Symbolic Links}.
+@end deftypefn
+
+@comment sys/stat.h
+@comment GNU
+@deftypefn Macro int S_ISSOCK (mode_t @var{m})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns non-zero if the file is a socket.  @xref{Sockets}.
+@end deftypefn
+
+An alternate non-POSIX method of testing the file type is supported for
+compatibility with BSD.  The mode can be bitwise AND-ed with
+@code{S_IFMT} to extract the file type code, and compared to the
+appropriate constant.  For example,
+
+@smallexample
+S_ISCHR (@var{mode})
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+((@var{mode} & S_IFMT) == S_IFCHR)
+@end smallexample
+
+@comment sys/stat.h
+@comment BSD
+@deftypevr Macro int S_IFMT
+This is a bit mask used to extract the file type code from a mode value.
+@end deftypevr
+
+These are the symbolic names for the different file type codes:
+
+@table @code
+@comment sys/stat.h
+@comment BSD
+@item S_IFDIR
+@vindex S_IFDIR
+This is the file type constant of a directory file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFCHR
+@vindex S_IFCHR
+This is the file type constant of a character-oriented device file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFBLK
+@vindex S_IFBLK
+This is the file type constant of a block-oriented device file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFREG
+@vindex S_IFREG
+This is the file type constant of a regular file.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFLNK
+@vindex S_IFLNK
+This is the file type constant of a symbolic link.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFSOCK
+@vindex S_IFSOCK
+This is the file type constant of a socket.
+
+@comment sys/stat.h
+@comment BSD
+@item S_IFIFO
+@vindex S_IFIFO
+This is the file type constant of a FIFO or pipe.
+@end table
+
+The POSIX.1b standard introduced a few more objects which possibly can
+be implemented as object in the filesystem.  These are message queues,
+semaphores, and shared memory objects.  To allow differentiating these
+objects from other files the POSIX standard introduces three new test
+macros.  But unlike the other macros it does not take the value of the
+@code{st_mode} field as the parameter.  Instead they expect a pointer to
+the whole @code{struct stat} structure.
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISMQ (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implement POSIX message queues as distinct objects and the
+file is a message queue object, this macro returns a non-zero value.
+In all other cases the result is zero.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISSEM (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implement POSIX semaphores as distinct objects and the
+file is a semaphore object, this macro returns a non-zero value.
+In all other cases the result is zero.
+@end deftypefn
+
+@comment sys/stat.h
+@comment POSIX
+@deftypefn Macro int S_TYPEISSHM (struct stat *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the system implement POSIX shared memory objects as distinct objects
+and the file is a shared memory object, this macro returns a non-zero
+value.  In all other cases the result is zero.
+@end deftypefn
+
+@node File Owner
+@subsection File Owner
+@cindex file owner
+@cindex owner of a file
+@cindex group owner of a file
+
+Every file has an @dfn{owner} which is one of the registered user names
+defined on the system.  Each file also has a @dfn{group} which is one of
+the defined groups.  The file owner can often be useful for showing you
+who edited the file (especially when you edit with GNU Emacs), but its
+main purpose is for access control.
+
+The file owner and group play a role in determining access because the
+file has one set of access permission bits for the owner, another set
+that applies to users who belong to the file's group, and a third set of
+bits that applies to everyone else.  @xref{Access Permission}, for the
+details of how access is decided based on this data.
+
+When a file is created, its owner is set to the effective user ID of the
+process that creates it (@pxref{Process Persona}).  The file's group ID
+may be set to either the effective group ID of the process, or the group
+ID of the directory that contains the file, depending on the system
+where the file is stored.  When you access a remote file system, it
+behaves according to its own rules, not according to the system your
+program is running on.  Thus, your program must be prepared to encounter
+either kind of behavior no matter what kind of system you run it on.
+
+@pindex chown
+@pindex chgrp
+You can change the owner and/or group owner of an existing file using
+the @code{chown} function.  This is the primitive for the @code{chown}
+and @code{chgrp} shell commands.
+
+@pindex unistd.h
+The prototype for this function is declared in @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{chown} function changes the owner of the file @var{filename} to
+@var{owner}, and its group owner to @var{group}.
+
+Changing the owner of the file on certain systems clears the set-user-ID
+and set-group-ID permission bits.  (This is because those bits may not
+be appropriate for the new owner.)  Other file permission bits are not
+changed.
+
+The return value is @code{0} on success and @code{-1} on failure.
+In addition to the usual file name errors (@pxref{File Name Errors}),
+the following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+This process lacks permission to make the requested change.
+
+Only privileged users or the file's owner can change the file's group.
+On most file systems, only privileged users can change the file owner;
+some file systems allow you to change the owner if you are currently the
+owner.  When you access a remote file system, the behavior you encounter
+is determined by the system that actually holds the file, not by the
+system your program is running on.
+
+@xref{Options for Files}, for information about the
+@code{_POSIX_CHOWN_RESTRICTED} macro.
+
+@item EROFS
+The file is on a read-only file system.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{chown}, except that it changes the owner of the open
+file with descriptor @var{filedes}.
+
+The return value from @code{fchown} is @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error codes are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
+file.
+
+@item EPERM
+This process lacks permission to make the requested change.  For details
+see @code{chmod} above.
+
+@item EROFS
+The file resides on a read-only file system.
+@end table
+@end deftypefun
+
+@node Permission Bits
+@subsection The Mode Bits for Access Permission
+
+The @dfn{file mode}, stored in the @code{st_mode} field of the file
+attributes, contains two kinds of information: the file type code, and
+the access permission bits.  This section discusses only the access
+permission bits, which control who can read or write the file.
+@xref{Testing File Type}, for information about the file type code.
+
+All of the symbols listed in this section are defined in the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+
+@cindex file permission bits
+These symbolic constants are defined for the file mode bits that control
+access permission for the file:
+
+@table @code
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRUSR
+@vindex S_IRUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IREAD
+@vindex S_IREAD
+Read permission bit for the owner of the file.  On many systems this bit
+is 0400.  @code{S_IREAD} is an obsolete synonym provided for BSD
+compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWUSR
+@vindex S_IWUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IWRITE
+@vindex S_IWRITE
+Write permission bit for the owner of the file.  Usually 0200.
+@w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXUSR
+@vindex S_IXUSR
+@comment sys/stat.h
+@comment BSD
+@itemx S_IEXEC
+@vindex S_IEXEC
+Execute (for ordinary files) or search (for directories) permission bit
+for the owner of the file.  Usually 0100.  @code{S_IEXEC} is an obsolete
+synonym provided for BSD compatibility.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXU
+@vindex S_IRWXU
+This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRGRP
+@vindex S_IRGRP
+Read permission bit for the group owner of the file.  Usually 040.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWGRP
+@vindex S_IWGRP
+Write permission bit for the group owner of the file.  Usually 020.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXGRP
+@vindex S_IXGRP
+Execute or search permission bit for the group owner of the file.
+Usually 010.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXG
+@vindex S_IRWXG
+This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IROTH
+@vindex S_IROTH
+Read permission bit for other users.  Usually 04.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IWOTH
+@vindex S_IWOTH
+Write permission bit for other users.  Usually 02.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IXOTH
+@vindex S_IXOTH
+Execute or search permission bit for other users.  Usually 01.
+
+@comment sys/stat.h
+@comment POSIX.1
+@item S_IRWXO
+@vindex S_IRWXO
+This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
+
+@comment sys/stat.h
+@comment POSIX
+@item S_ISUID
+@vindex S_ISUID
+This is the set-user-ID on execute bit, usually 04000.
+@xref{How Change Persona}.
+
+@comment sys/stat.h
+@comment POSIX
+@item S_ISGID
+@vindex S_ISGID
+This is the set-group-ID on execute bit, usually 02000.
+@xref{How Change Persona}.
+
+@cindex sticky bit
+@comment sys/stat.h
+@comment BSD
+@item S_ISVTX
+@vindex S_ISVTX
+This is the @dfn{sticky} bit, usually 01000.
+
+For a directory it gives permission to delete a file in that directory
+only if you own that file.  Ordinarily, a user can either delete all the
+files in a directory or cannot delete any of them (based on whether the
+user has write permission for the directory).  The same restriction
+applies---you must have both write permission for the directory and own
+the file you want to delete.  The one exception is that the owner of the
+directory can delete any file in the directory, no matter who owns it
+(provided the owner has given himself write permission for the
+directory).  This is commonly used for the @file{/tmp} directory, where
+anyone may create files but not delete files created by other users.
+
+Originally the sticky bit on an executable file modified the swapping
+policies of the system.  Normally, when a program terminated, its pages
+in core were immediately freed and reused.  If the sticky bit was set on
+the executable file, the system kept the pages in core for a while as if
+the program were still running.  This was advantageous for a program
+likely to be run many times in succession.  This usage is obsolete in
+modern systems.  When a program terminates, its pages always remain in
+core as long as there is no shortage of memory in the system.  When the
+program is next run, its pages will still be in core if no shortage
+arose since the last run.
+
+On some modern systems where the sticky bit has no useful meaning for an
+executable file, you cannot set the bit at all for a non-directory.
+If you try, @code{chmod} fails with @code{EFTYPE};
+@pxref{Setting Permissions}.
+
+Some systems (particularly SunOS) have yet another use for the sticky
+bit.  If the sticky bit is set on a file that is @emph{not} executable,
+it means the opposite: never cache the pages of this file at all.  The
+main use of this is for the files on an NFS server machine which are
+used as the swap area of diskless client machines.  The idea is that the
+pages of the file will be cached in the client's memory, so it is a
+waste of the server's memory to cache them a second time.  With this
+usage the sticky bit also implies that the filesystem may fail to record
+the file's modification time onto disk reliably (the idea being that
+no-one cares for a swap file).
+
+This bit is only available on BSD systems (and those derived from
+them).  Therefore one has to use the @code{_GNU_SOURCE} feature select
+macro, or not define any feature test macros, to get the definition
+(@pxref{Feature Test Macros}).
+@end table
+
+The actual bit values of the symbols are listed in the table above
+so you can decode file mode values when debugging your programs.
+These bit values are correct for most systems, but they are not
+guaranteed.
+
+@strong{Warning:} Writing explicit numbers for file permissions is bad
+practice.  Not only is it not portable, it also requires everyone who
+reads your program to remember what the bits mean.  To make your program
+clean use the symbolic names.
+
+@node Access Permission
+@subsection How Your Access to a File is Decided
+@cindex permission to access a file
+@cindex access permission for a file
+@cindex file access permission
+
+Recall that the operating system normally decides access permission for
+a file based on the effective user and group IDs of the process and its
+supplementary group IDs, together with the file's owner, group and
+permission bits.  These concepts are discussed in detail in @ref{Process
+Persona}.
+
+If the effective user ID of the process matches the owner user ID of the
+file, then permissions for read, write, and execute/search are
+controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
+if any of the effective group ID or supplementary group IDs of the
+process matches the group owner ID of the file, then permissions are
+controlled by the ``group'' bits.  Otherwise, permissions are controlled
+by the ``other'' bits.
+
+Privileged users, like @samp{root}, can access any file regardless of
+its permission bits.  As a special case, for a file to be executable
+even by a privileged user, at least one of its execute bits must be set.
+
+@node Setting Permissions
+@subsection Assigning File Permissions
+
+@cindex file creation mask
+@cindex umask
+The primitive functions for creating files (for example, @code{open} or
+@code{mkdir}) take a @var{mode} argument, which specifies the file
+permissions to give the newly created file.  This mode is modified by
+the process's @dfn{file creation mask}, or @dfn{umask}, before it is
+used.
+
+The bits that are set in the file creation mask identify permissions
+that are always to be disabled for newly created files.  For example, if
+you set all the ``other'' access bits in the mask, then newly created
+files are not accessible at all to processes in the ``other'' category,
+even if the @var{mode} argument passed to the create function would
+permit such access.  In other words, the file creation mask is the
+complement of the ordinary access permissions you want to grant.
+
+Programs that create files typically specify a @var{mode} argument that
+includes all the permissions that make sense for the particular file.
+For an ordinary file, this is typically read and write permission for
+all classes of users.  These permissions are then restricted as
+specified by the individual user's own file creation mask.
+
+@findex chmod
+To change the permission of an existing file given its name, call
+@code{chmod}.  This function uses the specified permission bits and
+ignores the file creation mask.
+
+@pindex umask
+In normal use, the file creation mask is initialized by the user's login
+shell (using the @code{umask} shell command), and inherited by all
+subprocesses.  Application programs normally don't need to worry about
+the file creation mask.  It will automatically do what it is supposed to
+do.
+
+When your program needs to create a file and bypass the umask for its
+access permissions, the easiest way to do this is to use @code{fchmod}
+after opening the file, rather than changing the umask.  In fact,
+changing the umask is usually done only by shells.  They use the
+@code{umask} function.
+
+The functions in this section are declared in @file{sys/stat.h}.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun mode_t umask (mode_t @var{mask})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{umask} function sets the file creation mask of the current
+process to @var{mask}, and returns the previous value of the file
+creation mask.
+
+Here is an example showing how to read the mask with @code{umask}
+without changing it permanently:
+
+@smallexample
+mode_t
+read_umask (void)
+@{
+  mode_t mask = umask (0);
+  umask (mask);
+  return mask;
+@}
+@end smallexample
+
+@noindent
+However, on @gnuhurdsystems{} it is better to use @code{getumask} if
+you just want to read the mask value, because it is reentrant.
+@end deftypefun
+
+@comment sys/stat.h
+@comment GNU
+@deftypefun mode_t getumask (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Return the current value of the file creation mask for the current
+process.  This function is a GNU extension and is only available on
+@gnuhurdsystems{}.
+@end deftypefun
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{chmod} function sets the access permission bits for the file
+named by @var{filename} to @var{mode}.
+
+If @var{filename} is a symbolic link, @code{chmod} changes the
+permissions of the file pointed to by the link, not those of the link
+itself.
+
+This function returns @code{0} if successful and @code{-1} if not.  In
+addition to the usual file name errors (@pxref{File Name
+Errors}), the following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item ENOENT
+The named file doesn't exist.
+
+@item EPERM
+This process does not have permission to change the access permissions
+of this file.  Only the file's owner (as judged by the effective user ID
+of the process) or a privileged user can change them.
+
+@item EROFS
+The file resides on a read-only file system.
+
+@item EFTYPE
+@var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
+and the named file is not a directory.  Some systems do not allow setting the
+sticky bit on non-directory files, and some do (and only some of those
+assign a useful meaning to the bit for non-directory files).
+
+You only get @code{EFTYPE} on systems where the sticky bit has no useful
+meaning for non-directory files, so it is always safe to just clear the
+bit in @var{mode} and call @code{chmod} again.  @xref{Permission Bits},
+for full details on the sticky bit.
+@end table
+@end deftypefun
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int fchmod (int @var{filedes}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{chmod}, except that it changes the permissions of the
+currently open file given by @var{filedes}.
+
+The return value from @code{fchmod} is @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error codes are defined for this
+function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument corresponds to a pipe or socket, or something
+else that doesn't really have access permissions.
+
+@item EPERM
+This process does not have permission to change the access permissions
+of this file.  Only the file's owner (as judged by the effective user ID
+of the process) or a privileged user can change them.
+
+@item EROFS
+The file resides on a read-only file system.
+@end table
+@end deftypefun
+
+@node Testing File Access
+@subsection Testing Permission to Access a File
+@cindex testing access permission
+@cindex access, testing for
+@cindex setuid programs and file access
+
+In some situations it is desirable to allow programs to access files or
+devices even if this is not possible with the permissions granted to the
+user.  One possible solution is to set the setuid-bit of the program
+file.  If such a program is started the @emph{effective} user ID of the
+process is changed to that of the owner of the program file.  So to
+allow write access to files like @file{/etc/passwd}, which normally can
+be written only by the super-user, the modifying program will have to be
+owned by @code{root} and the setuid-bit must be set.
+
+But beside the files the program is intended to change the user should
+not be allowed to access any file to which s/he would not have access
+anyway.  The program therefore must explicitly check whether @emph{the
+user} would have the necessary access to a file, before it reads or
+writes the file.
+
+To do this, use the function @code{access}, which checks for access
+permission based on the process's @emph{real} user ID rather than the
+effective user ID.  (The setuid feature does not alter the real user ID,
+so it reflects the user who actually ran the program.)
+
+There is another way you could check this access, which is easy to
+describe, but very hard to use.  This is to examine the file mode bits
+and mimic the system's own access computation.  This method is
+undesirable because many systems have additional access control
+features; your program cannot portably mimic them, and you would not
+want to try to keep track of the diverse features that different systems
+have.  Using @code{access} is simple and automatically does whatever is
+appropriate for the system you are using.
+
+@code{access} is @emph{only} only appropriate to use in setuid programs.
+A non-setuid program will always use the effective ID rather than the
+real ID.
+
+@pindex unistd.h
+The symbols in this section are declared in @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int access (const char *@var{filename}, int @var{how})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{access} function checks to see whether the file named by
+@var{filename} can be accessed in the way specified by the @var{how}
+argument.  The @var{how} argument either can be the bitwise OR of the
+flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
+@code{F_OK}.
+
+This function uses the @emph{real} user and group IDs of the calling
+process, rather than the @emph{effective} IDs, to check for access
+permission.  As a result, if you use the function from a @code{setuid}
+or @code{setgid} program (@pxref{How Change Persona}), it gives
+information relative to the user who actually ran the program.
+
+The return value is @code{0} if the access is permitted, and @code{-1}
+otherwise.  (In other words, treated as a predicate function,
+@code{access} returns true if the requested access is @emph{denied}.)
+
+In addition to the usual file name errors (@pxref{File Name
+Errors}), the following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item EACCES
+The access specified by @var{how} is denied.
+
+@item ENOENT
+The file doesn't exist.
+
+@item EROFS
+Write permission was requested for a file on a read-only file system.
+@end table
+@end deftypefun
+
+These macros are defined in the header file @file{unistd.h} for use
+as the @var{how} argument to the @code{access} function.  The values
+are integer constants.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int R_OK
+Flag meaning test for read permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int W_OK
+Flag meaning test for write permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int X_OK
+Flag meaning test for execute/search permission.
+@end deftypevr
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevr Macro int F_OK
+Flag meaning test for existence of the file.
+@end deftypevr
+
+@node File Times
+@subsection File Times
+
+@cindex file access time
+@cindex file modification time
+@cindex file attribute modification time
+Each file has three time stamps associated with it:  its access time,
+its modification time, and its attribute modification time.  These
+correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
+members of the @code{stat} structure; see @ref{File Attributes}.
+
+All of these times are represented in calendar time format, as
+@code{time_t} objects.  This data type is defined in @file{time.h}.
+For more information about representation and manipulation of time
+values, see @ref{Calendar Time}.
+@pindex time.h
+
+Reading from a file updates its access time attribute, and writing
+updates its modification time.  When a file is created, all three
+time stamps for that file are set to the current time.  In addition, the
+attribute change time and modification time fields of the directory that
+contains the new entry are updated.
+
+Adding a new name for a file with the @code{link} function updates the
+attribute change time field of the file being linked, and both the
+attribute change time and modification time fields of the directory
+containing the new name.  These same fields are affected if a file name
+is deleted with @code{unlink}, @code{remove} or @code{rmdir}.  Renaming
+a file with @code{rename} affects only the attribute change time and
+modification time fields of the two parent directories involved, and not
+the times for the file being renamed.
+
+Changing the attributes of a file (for example, with @code{chmod})
+updates its attribute change time field.
+
+You can also change some of the time stamps of a file explicitly using
+the @code{utime} function---all except the attribute change time.  You
+need to include the header file @file{utime.h} to use this facility.
+@pindex utime.h
+
+@comment utime.h
+@comment POSIX.1
+@deftp {Data Type} {struct utimbuf}
+The @code{utimbuf} structure is used with the @code{utime} function to
+specify new access and modification times for a file.  It contains the
+following members:
+
+@table @code
+@item time_t actime
+This is the access time for the file.
+
+@item time_t modtime
+This is the modification time for the file.
+@end table
+@end deftp
+
+@comment utime.h
+@comment POSIX.1
+@deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a utime syscall, it non-atomically converts times
+@c to a struct timeval and calls utimes.
+This function is used to modify the file times associated with the file
+named @var{filename}.
+
+If @var{times} is a null pointer, then the access and modification times
+of the file are set to the current time.  Otherwise, they are set to the
+values from the @code{actime} and @code{modtime} members (respectively)
+of the @code{utimbuf} structure pointed to by @var{times}.
+
+The attribute modification time for the file is set to the current time
+in either case (since changing the time stamps is itself a modification
+of the file attributes).
+
+The @code{utime} function returns @code{0} if successful and @code{-1}
+on failure.  In addition to the usual file name errors
+(@pxref{File Name Errors}), the following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item EACCES
+There is a permission problem in the case where a null pointer was
+passed as the @var{times} argument.  In order to update the time stamp on
+the file, you must either be the owner of the file, have write
+permission for the file, or be a privileged user.
+
+@item ENOENT
+The file doesn't exist.
+
+@item EPERM
+If the @var{times} argument is not a null pointer, you must either be
+the owner of the file or be a privileged user.
+
+@item EROFS
+The file lives on a read-only file system.
+@end table
+@end deftypefun
+
+Each of the three time stamps has a corresponding microsecond part,
+which extends its resolution.  These fields are called
+@code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
+each has a value between 0 and 999,999, which indicates the time in
+microseconds.  They correspond to the @code{tv_usec} field of a
+@code{timeval} structure; see @ref{High-Resolution Calendar}.
+
+The @code{utimes} function is like @code{utime}, but also lets you specify
+the fractional part of the file times.  The prototype for this function is
+in the header file @file{sys/time.h}.
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a utimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall, or to
+@c struct utimbuf and calls utime.
+This function sets the file access and modification times of the file
+@var{filename}.  The new file access time is specified by
+@code{@var{tvp}[0]}, and the new modification time by
+@code{@var{tvp}[1]}.  Similar to @code{utime}, if @var{tvp} is a null
+pointer then the access and modification times of the file are set to
+the current time.  This function comes from BSD.
+
+The return values and error conditions are the same as for the @code{utime}
+function.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Since there's no lutimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall.
+This function is like @code{utimes}, except that it does not follow
+symbolic links.  If @var{filename} is the name of a symbolic link,
+@code{lutimes} sets the file access and modification times of the
+symbolic link special file itself (as seen by @code{lstat};
+@pxref{Symbolic Links}) while @code{utimes} sets the file access and
+modification times of the file the symbolic link refers to.  This
+function comes from FreeBSD, and is not available on all platforms (if
+not available, it will fail with @code{ENOSYS}).
+
+The return values and error conditions are the same as for the @code{utime}
+function.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Since there's no futimes syscall, it non-atomically converts tvp
+@c to struct timespec array and issues a utimensat syscall, falling back
+@c to utimes on a /proc/self/fd symlink.
+This function is like @code{utimes}, except that it takes an open file
+descriptor as an argument instead of a file name.  @xref{Low-Level
+I/O}.  This function comes from FreeBSD, and is not available on all
+platforms (if not available, it will fail with @code{ENOSYS}).
+
+Like @code{utimes}, @code{futimes} returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined for
+@code{futimes}:
+
+@table @code
+@item EACCES
+There is a permission problem in the case where a null pointer was
+passed as the @var{times} argument.  In order to update the time stamp on
+the file, you must either be the owner of the file, have write
+permission for the file, or be a privileged user.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EPERM
+If the @var{times} argument is not a null pointer, you must either be
+the owner of the file or be a privileged user.
+
+@item EROFS
+The file lives on a read-only file system.
+@end table
+@end deftypefun
+
+@node File Size
+@subsection File Size
+
+Normally file sizes are maintained automatically.  A file begins with a
+size of @math{0} and is automatically extended when data is written past
+its end.  It is also possible to empty a file completely by an
+@code{open} or @code{fopen} call.
+
+However, sometimes it is necessary to @emph{reduce} the size of a file.
+This can be done with the @code{truncate} and @code{ftruncate} functions.
+They were introduced in BSD Unix.  @code{ftruncate} was later added to
+POSIX.1.
+
+Some systems allow you to extend a file (creating holes) with these
+functions.  This is useful when using memory-mapped I/O
+(@pxref{Memory-mapped I/O}), where files are not automatically extended.
+However, it is not portable but must be implemented if @code{mmap}
+allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined).
+
+Using these functions on anything other than a regular file gives
+@emph{undefined} results.  On many systems, such a call will appear to
+succeed, without actually accomplishing anything.
+
+@comment unistd.h
+@comment X/Open
+@deftypefun int truncate (const char *@var{filename}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a truncate syscall, we use open and ftruncate.
+
+The @code{truncate} function changes the size of @var{filename} to
+@var{length}.  If @var{length} is shorter than the previous length, data
+at the end will be lost.  The file must be writable by the user to
+perform this operation.
+
+If @var{length} is longer, holes will be added to the end.  However, some
+systems do not support this feature and will leave the file unchanged.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{truncate} function is in fact @code{truncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is @math{0} for success, or @math{-1} for an error.  In
+addition to the usual file name errors, the following errors may occur:
+
+@table @code
+
+@item EACCES
+The file is a directory or not writable.
+
+@item EINVAL
+@var{length} is negative.
+
+@item EFBIG
+The operation would extend the file beyond the limits of the operating system.
+
+@item EIO
+A hardware I/O error occurred.
+
+@item EPERM
+The file is "append-only" or "immutable".
+
+@item EINTR
+The operation was interrupted by a signal.
+
+@end table
+
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a syscall, try truncate if length fits.
+This function is similar to the @code{truncate} function.  The
+difference is that the @var{length} argument is 64 bits wide even on 32
+bits machines, which allows the handling of files with sizes up to
+@twoexp{63} bytes.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{truncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This is like @code{truncate}, but it works on a file descriptor @var{fd}
+for an opened file instead of a file name to identify the object.  The
+file must be opened for writing to successfully carry out the operation.
+
+The POSIX standard leaves it implementation defined what happens if the
+specified new @var{length} of the file is bigger than the original size.
+The @code{ftruncate} function might simply leave the file alone and do
+nothing or it can increase the size to the desired size.  In this later
+case the extended area should be zero-filled.  So using @code{ftruncate}
+is no reliable way to increase the file size but if it is possible it is
+probably the fastest way.  The function also operates on POSIX shared
+memory segments if these are implemented by the system.
+
+@code{ftruncate} is especially useful in combination with @code{mmap}.
+Since the mapped region must have a fixed size one cannot enlarge the
+file by writing something beyond the last mapped page.  Instead one has
+to enlarge the file itself and then remap the file with the new size.
+The example below shows how this works.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{ftruncate} function is in fact @code{ftruncate64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is @math{0} for success, or @math{-1} for an error.  The
+following errors may occur:
+
+@table @code
+
+@item EBADF
+@var{fd} does not correspond to an open file.
+
+@item EACCES
+@var{fd} is a directory or not open for writing.
+
+@item EINVAL
+@var{length} is negative.
+
+@item EFBIG
+The operation would extend the file beyond the limits of the operating system.
+@c or the open() call -- with the not-yet-discussed feature of opening
+@c files with extra-large offsets.
+
+@item EIO
+A hardware I/O error occurred.
+
+@item EPERM
+The file is "append-only" or "immutable".
+
+@item EINTR
+The operation was interrupted by a signal.
+
+@c ENOENT is also possible on Linux --- however it only occurs if the file
+@c descriptor has a `file' structure but no `inode' structure.  I'm not
+@c sure how such an fd could be created.  Perhaps it's a bug.
+
+@end table
+
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c In the absence of a syscall, try ftruncate if length fits.
+This function is similar to the @code{ftruncate} function.  The
+difference is that the @var{length} argument is 64 bits wide even on 32
+bits machines which allows the handling of files with sizes up to
+@twoexp{63} bytes.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{ftruncate} and so transparently replaces the 32 bits interface.
+@end deftypefun
+
+As announced here is a little example of how to use @code{ftruncate} in
+combination with @code{mmap}:
+
+@smallexample
+int fd;
+void *start;
+size_t len;
+
+int
+add (off_t at, void *block, size_t size)
+@{
+  if (at + size > len)
+    @{
+      /* Resize the file and remap.  */
+      size_t ps = sysconf (_SC_PAGESIZE);
+      size_t ns = (at + size + ps - 1) & ~(ps - 1);
+      void *np;
+      if (ftruncate (fd, ns) < 0)
+        return -1;
+      np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
+      if (np == MAP_FAILED)
+        return -1;
+      start = np;
+      len = ns;
+    @}
+  memcpy ((char *) start + at, block, size);
+  return 0;
+@}
+@end smallexample
+
+The function @code{add} writes a block of memory at an arbitrary
+position in the file.  If the current size of the file is too small it
+is extended.  Note the it is extended by a round number of pages.  This
+is a requirement of @code{mmap}.  The program has to keep track of the
+real size, and when it has finished a final @code{ftruncate} call should
+set the real size of the file.
+
+@node Storage Allocation
+@subsection Storage Allocation
+@cindex allocating file storage
+@cindex file allocation
+@cindex storage allocating
+
+@cindex file fragmentation
+@cindex fragmentation of files
+@cindex sparse files
+@cindex files, sparse
+Most file systems support allocating large files in a non-contiguous
+fashion: the file is split into @emph{fragments} which are allocated
+sequentially, but the fragments themselves can be scattered across the
+disk.  File systems generally try to avoid such fragmentation because it
+decreases performance, but if a file gradually increases in size, there
+might be no other option than to fragment it.  In addition, many file
+systems support @emph{sparse files} with @emph{holes}: regions of null
+bytes for which no backing storage has been allocated by the file
+system.  When the holes are finally overwritten with data, fragmentation
+can occur as well.
+
+Explicit allocation of storage for yet-unwritten parts of the file can
+help the system to avoid fragmentation.  Additionally, if storage
+pre-allocation fails, it is possible to report the out-of-disk error
+early, often without filling up the entire disk.  However, due to
+deduplication, copy-on-write semantics, and file compression, such
+pre-allocation may not reliably prevent the out-of-disk-space error from
+occurring later.  Checking for write errors is still required, and
+writes to memory-mapped regions created with @code{mmap} can still
+result in @code{SIGBUS}.
+
+@deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c If the file system does not support allocation,
+@c @code{posix_fallocate} has a race with file extension (if
+@c @var{length} is zero) or with concurrent writes of non-NUL bytes (if
+@c @var{length} is positive).
+
+Allocate backing store for the region of @var{length} bytes starting at
+byte @var{offset} in the file for the descriptor @var{fd}.  The file
+length is increased to @samp{@var{length} + @var{offset}} if necessary.
+
+@var{fd} must be a regular file opened for writing, or @code{EBADF} is
+returned.  If there is insufficient disk space to fulfill the allocation
+request, @code{ENOSPC} is returned.
+
+@strong{Note:} If @code{fallocate} is not available (because the file
+system does not support it), @code{posix_fallocate} is emulated, which
+has the following drawbacks:
+
+@itemize @bullet
+@item
+It is very inefficient because all file system blocks in the requested
+range need to be examined (even if they have been allocated before) and
+potentially rewritten.  In contrast, with proper @code{fallocate}
+support (see below), the file system can examine the internal file
+allocation data structures and eliminate holes directly, maybe even
+using unwritten extents (which are pre-allocated but uninitialized on
+disk).
+
+@item
+There is a race condition if another thread or process modifies the
+underlying file in the to-be-allocated area.  Non-null bytes could be
+overwritten with null bytes.
+
+@item
+If @var{fd} has been opened with the @code{O_WRONLY} flag, the function
+will fail with an @code{errno} value of @code{EBADF}.
+
+@item
+If @var{fd} has been opened with the @code{O_APPEND} flag, the function
+will fail with an @code{errno} value of @code{EBADF}.
+
+@item
+If @var{length} is zero, @code{ftruncate} is used to increase the file
+size as requested, without allocating file system blocks.  There is a
+race condition which means that @code{ftruncate} can accidentally
+truncate the file if it has been extended concurrently.
+@end itemize
+
+On Linux, if an application does not benefit from emulation or if the
+emulation is harmful due to its inherent race conditions, the
+application can use the Linux-specific @code{fallocate} function, with a
+zero flag argument.  For the @code{fallocate} function, @theglibc{} does
+not perform allocation emulation if the file system does not support
+allocation.  Instead, an @code{EOPNOTSUPP} is returned to the caller.
+
+@end deftypefun
+
+@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is a variant of @code{posix_fallocate64} which accepts
+64-bit file offsets on all platforms.
+
+@end deftypefun
+
+@node Making Special Files
+@section Making Special Files
+@cindex creating special files
+@cindex special files
+
+The @code{mknod} function is the primitive for making special files,
+such as files that correspond to devices.  @Theglibc{} includes
+this function for compatibility with BSD.
+
+The prototype for @code{mknod} is declared in @file{sys/stat.h}.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment BSD
+@deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Instead of issuing the syscall directly, we go through xmknod.
+@c Although the internal xmknod takes a dev_t*, that could lead to
+@c @mtsrace races, it's passed a pointer to mknod's dev.
+The @code{mknod} function makes a special file with name @var{filename}.
+The @var{mode} specifies the mode of the file, and may include the various
+special file bits, such as @code{S_IFCHR} (for a character special file)
+or @code{S_IFBLK} (for a block special file).  @xref{Testing File Type}.
+
+The @var{dev} argument specifies which device the special file refers to.
+Its exact interpretation depends on the kind of special file being created.
+
+The return value is @code{0} on success and @code{-1} on error.  In addition
+to the usual file name errors (@pxref{File Name Errors}), the
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+The calling process is not privileged.  Only the superuser can create
+special files.
+
+@item ENOSPC
+The directory or file system that would contain the new file is full
+and cannot be extended.
+
+@item EROFS
+The directory containing the new file can't be modified because it's on
+a read-only file system.
+
+@item EEXIST
+There is already a file named @var{filename}.  If you want to replace
+this file, you must remove the old file explicitly first.
+@end table
+@end deftypefun
+
+@node Temporary Files
+@section Temporary Files
+
+If you need to use a temporary file in your program, you can use the
+@code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
+(better: @code{tmpnam_r}) function to provide a name for a temporary
+file and then you can open it in the usual way with @code{fopen}.
+
+The @code{tempnam} function is like @code{tmpnam} but lets you choose
+what directory temporary files will go in, and something about what
+their file names will look like.  Important for multi-threaded programs
+is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it
+returns a pointer to a static buffer.
+
+These facilities are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun {FILE *} tmpfile (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+@c The unsafety issues are those of fdopen, plus @acsfd because of the
+@c open.
+@c __path_search (internal buf, !dir, const pfx, !try_tmpdir) ok
+@c  libc_secure_genenv only if try_tmpdir
+@c  xstat64, strlen, strcmp, sprintf
+@c __gen_tempname (internal tmpl, __GT_FILE) ok
+@c  strlen, memcmp, getpid, open/mkdir/lxstat64 ok
+@c  HP_TIMING_NOW if available ok
+@c  gettimeofday (!tz) first time, or every time if no HP_TIMING_NOW ok
+@c  static value is used and modified without synchronization ok
+@c   but the use is as a source of non-cryptographic randomness
+@c   with retries in case of collision, so it should be safe
+@c unlink, fdopen
+This function creates a temporary binary file for update mode, as if by
+calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
+automatically when it is closed or when the program terminates.  (On
+some other @w{ISO C} systems the file may fail to be deleted if the program
+terminates abnormally).
+
+This function is reentrant.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} tmpfile64 (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+This function is similar to @code{tmpfile}, but the stream it returns a
+pointer to was opened using @code{tmpfile64}.  Therefore this stream can
+be used for files larger than @twoexp{31} bytes on 32-bit machines.
+
+Please note that the return type is still @code{FILE *}.  There is no
+special @code{FILE} type for the LFS interface.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{tmpfile}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun {char *} tmpnam (char *@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}}
+@c The passed-in buffer should not be modified concurrently with the
+@c call.
+@c __path_search (static or passed-in buf, !dir, !pfx, !try_tmpdir) ok
+@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok
+This function constructs and returns a valid file name that does not
+refer to any existing file.  If the @var{result} argument is a null
+pointer, the return value is a pointer to an internal static string,
+which might be modified by subsequent calls and therefore makes this
+function non-reentrant.  Otherwise, the @var{result} argument should be
+a pointer to an array of at least @code{L_tmpnam} characters, and the
+result is written into that array.
+
+It is possible for @code{tmpnam} to fail if you call it too many times
+without removing previously-created files.  This is because the limited
+length of the temporary file names gives room for only a finite number
+of different names.  If @code{tmpnam} fails it returns a null pointer.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{tmpnam}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun {char *} tmpnam_r (char *@var{result})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is nearly identical to the @code{tmpnam} function, except
+that if @var{result} is a null pointer it returns a null pointer.
+
+This guarantees reentrancy because the non-reentrant situation of
+@code{tmpnam} cannot happen here.
+
+@strong{Warning}: This function has the same security problems as
+@code{tmpnam}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int L_tmpnam
+The value of this macro is an integer constant expression that
+represents the minimum size of a string large enough to hold a file name
+generated by the @code{tmpnam} function.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int TMP_MAX
+The macro @code{TMP_MAX} is a lower bound for how many temporary names
+you can create with @code{tmpnam}.  You can rely on being able to call
+@code{tmpnam} at least this many times before it might fail saying you
+have made too many temporary file names.
+
+With @theglibc{}, you can create a very large number of temporary
+file names.  If you actually created the files, you would probably run
+out of disk space before you ran out of names.  Some other systems have
+a fixed, small limit on the number of temporary files.  The limit is
+never less than @code{25}.
+@end deftypevr
+
+@comment stdio.h
+@comment SVID
+@deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c There's no way (short of being setuid) to avoid getenv("TMPDIR"),
+@c even with a non-NULL dir.
+@c
+@c __path_search (internal buf, dir, pfx, try_tmpdir) unsafe getenv
+@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok
+@c strdup
+This function generates a unique temporary file name.  If @var{prefix}
+is not a null pointer, up to five characters of this string are used as
+a prefix for the file name.  The return value is a string newly
+allocated with @code{malloc}, so you should release its storage with
+@code{free} when it is no longer needed.
+
+Because the string is dynamically allocated this function is reentrant.
+
+The directory prefix for the temporary file name is determined by
+testing each of the following in sequence.  The directory must exist and
+be writable.
+
+@itemize @bullet
+@item
+The environment variable @code{TMPDIR}, if it is defined.  For security
+reasons this only happens if the program is not SUID or SGID enabled.
+
+@item
+The @var{dir} argument, if it is not a null pointer.
+
+@item
+The value of the @code{P_tmpdir} macro.
+
+@item
+The directory @file{/tmp}.
+@end itemize
+
+This function is defined for SVID compatibility.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{tempnam}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+@cindex TMPDIR environment variable
+
+@comment stdio.h
+@comment SVID
+@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
+@deftypevr {SVID Macro} {char *} P_tmpdir
+This macro is the name of the default directory for temporary files.
+@end deftypevr
+
+Older Unix systems did not have the functions just described.  Instead
+they used @code{mktemp} and @code{mkstemp}.  Both of these functions
+work by modifying a file name template string you pass.  The last six
+characters of this string must be @samp{XXXXXX}.  These six @samp{X}s
+are replaced with six characters which make the whole string a unique
+file name.  Usually the template string is something like
+@samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
+
+@strong{NB:} Because @code{mktemp} and @code{mkstemp} modify the
+template string, you @emph{must not} pass string constants to them.
+String constants are normally in read-only storage, so your program
+would crash when @code{mktemp} or @code{mkstemp} tried to modify the
+string.  These functions are declared in the header file @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment Unix
+@deftypefun {char *} mktemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c __gen_tempname (caller tmpl, __GT_NOCREATE) ok
+The @code{mktemp} function generates a unique file name by modifying
+@var{template} as described above.  If successful, it returns
+@var{template} as modified.  If @code{mktemp} cannot find a unique file
+name, it makes @var{template} an empty string and returns that.  If
+@var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
+null pointer.
+
+@strong{Warning:} Between the time the pathname is constructed and the
+file is created another process might have created a file with the same
+name using @code{mktemp}, leading to a possible security hole.  The
+implementation generates names which can hardly be predicted, but when
+opening the file you should use the @code{O_EXCL} flag.  Using
+@code{mkstemp} is a safe way to avoid this problem.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int mkstemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c __gen_tempname (caller tmpl, __GT_FILE) ok
+The @code{mkstemp} function generates a unique file name just as
+@code{mktemp} does, but it also opens the file for you with @code{open}
+(@pxref{Opening and Closing Files}).  If successful, it modifies
+@var{template} in place and returns a file descriptor for that file open
+for reading and writing.  If @code{mkstemp} cannot create a
+uniquely-named file, it returns @code{-1}.  If @var{template} does not
+end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not
+modify @var{template}.
+
+The file is opened using mode @code{0600}.  If the file is meant to be
+used by other users this mode must be changed explicitly.
+@end deftypefun
+
+Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
+unique file that cannot possibly clash with any other program trying to
+create a temporary file.  This is because it works by calling
+@code{open} with the @code{O_EXCL} flag, which says you want to create a
+new file and get an error if the file already exists.
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {char *} mkdtemp (char *@var{template})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c __gen_tempname (caller tmpl, __GT_DIR) ok
+The @code{mkdtemp} function creates a directory with a unique name.  If
+it succeeds, it overwrites @var{template} with the name of the
+directory, and returns @var{template}.  As with @code{mktemp} and
+@code{mkstemp}, @var{template} should be a string ending with
+@samp{XXXXXX}.
+
+If @code{mkdtemp} cannot create an uniquely named directory, it returns
+@code{NULL} and sets @var{errno} appropriately.  If @var{template} does
+not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does
+not modify @var{template}.  @var{errno} will be set to @code{EINVAL} in
+this case.
+
+The directory is created using mode @code{0700}.
+@end deftypefun
+
+The directory created by @code{mkdtemp} cannot clash with temporary
+files or directories created by other users.  This is because directory
+creation always works like @code{open} with @code{O_EXCL}.
+@xref{Creating Directories}.
+
+The @code{mkdtemp} function comes from OpenBSD.
+
+@c FIXME these are undocumented:
+@c faccessat
+@c fchmodat
+@c fchownat
+@c futimesat
+@c fstatat (there's a commented-out safety assessment for this one)
+@c linkat
+@c mkdirat
+@c mkfifoat
+@c name_to_handle_at
+@c openat
+@c open_by_handle_at
+@c readlinkat
+@c renameat
+@c scandirat
+@c symlinkat
+@c unlinkat
+@c utimensat
+@c mknodat
diff --git a/ap/libc/glibc/glibc-2.23/manual/freemanuals.texi b/ap/libc/glibc/glibc-2.23/manual/freemanuals.texi
new file mode 100644
index 0000000..9caf220
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/freemanuals.texi
@@ -0,0 +1,93 @@
+@c freemanuals.texi - blurb for free documentation.
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@cindex free documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software.  Many of our most important
+programs do not come with free reference manuals and free introductory
+texts.  Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap.  We have many such
+gaps today.
+
+Consider Perl, for instance.  The tutorial manuals that people
+normally use are non-free.  How did this come about?  Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last.  Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price.  The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine.  (The Free
+Software Foundation sells printed copies of manuals, too.)  The
+problem is the restrictions on the use of the manual.  Free manuals
+are available in source code form, and give you permission to copy and
+modify.  Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software.  Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program.  A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable.  For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok.  It is also no problem to require modified versions
+to include notice that they were modified.  Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one).  These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels.  Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue.  Our community continues to
+lose manuals to proprietary publishing.  If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license.  Remember that this decision requires your approval---you
+don't have to let the publisher decide.  Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want.  If the publisher you are dealing with refuses, please
+try other publishers.  If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements.  Meanwhile, try to avoid buying non-free documentation
+at all.  Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+@url{http://www.fsf.org/doc/other-free-books.html}.
diff --git a/ap/libc/glibc/glibc-2.23/manual/getopt.texi b/ap/libc/glibc/glibc-2.23/manual/getopt.texi
new file mode 100644
index 0000000..aa4134b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/getopt.texi
@@ -0,0 +1,333 @@
+@node Getopt, Argp, , Parsing Program Arguments
+@section Parsing program options using @code{getopt}
+
+The @code{getopt} and @code{getopt_long} functions automate some of the
+chore involved in parsing typical unix command line options.
+
+@menu
+* Using Getopt::                Using the @code{getopt} function.
+* Example of Getopt::           An example of parsing options with @code{getopt}.
+* Getopt Long Options::         GNU suggests utilities accept long-named
+                                 options; here is one way to do.
+* Getopt Long Option Example::  An example of using @code{getopt_long}.
+@end menu
+
+@node Using Getopt, Example of Getopt, , Getopt
+@subsection Using the @code{getopt} function
+
+Here are the details about how to call the @code{getopt} function.  To
+use this facility, your program must include the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int opterr
+If the value of this variable is nonzero, then @code{getopt} prints an
+error message to the standard error stream if it encounters an unknown
+option character or an option with a missing required argument.  This is
+the default behavior.  If you set this variable to zero, @code{getopt}
+does not print any messages, but it still returns the character @code{?}
+to indicate an error.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optopt
+When @code{getopt} encounters an unknown option character or an option
+with a missing required argument, it stores that option character in
+this variable.  You can use this for providing your own diagnostic
+messages.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optind
+This variable is set by @code{getopt} to the index of the next element
+of the @var{argv} array to be processed.  Once @code{getopt} has found
+all of the option arguments, you can use this variable to determine
+where the remaining non-option arguments begin.  The initial value of
+this variable is @code{1}.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar {char *} optarg
+This variable is set by @code{getopt} to point at the value of the
+option argument, for those options that accept arguments.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options})
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Swapping elements of passed-in argv may be partial in case of
+@c cancellation.  Gettext brings about a whole lot of AS and AC safety
+@c issues.  The getopt API involves returning values in the
+@c non-thread-specific optarg variable, which adds another thread-safety
+@c issue.  Given print_errors, it may output errors to stderr, which may
+@c self-deadlock, leak locks, or encounter (in a signal handler) or
+@c leave (in case of cancellation) stderr in an inconsistent state.
+@c Various implicit, indirect uses of malloc, in uses of memstream and
+@c asprintf for error-printing, bring about the usual malloc issues.
+@c (The explicit use of malloc in a conditional situation in
+@c _getopt_initialize is never exercised in glibc.)
+@c
+@c _getopt_internal
+@c  _getopt_internal_r
+@c   gettext
+@c   _getopt_initialize
+@c    getenv
+@c    malloc if USE_NONOPTION_FLAGS, never defined in libc
+@c   open_memstream
+@c   lockfile, unlockfile, __fxprintf -> stderr
+@c   asprintf
+The @code{getopt} function gets the next option argument from the
+argument list specified by the @var{argv} and @var{argc} arguments.
+Normally these values come directly from the arguments received by
+@code{main}.
+
+The @var{options} argument is a string that specifies the option
+characters that are valid for this program.  An option character in this
+string can be followed by a colon (@samp{:}) to indicate that it takes a
+required argument.  If an option character is followed by two colons
+(@samp{::}), its argument is optional; this is a GNU extension.
+
+@code{getopt} has three ways to deal with options that follow
+non-options @var{argv} elements.  The special argument @samp{--} forces
+in all cases the end of option scanning.
+
+@itemize @bullet
+@item
+The default is to permute the contents of @var{argv} while scanning it
+so that eventually all the non-options are at the end.  This allows
+options to be given in any order, even with programs that were not
+written to expect this.
+
+@item
+If the @var{options} argument string begins with a hyphen (@samp{-}), this
+is treated specially.  It permits arguments that are not options to be
+returned as if they were associated with option character @samp{\1}.
+
+@item
+POSIX demands the following behavior: The first non-option stops option
+processing.  This mode is selected by either setting the environment
+variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument
+string with a plus sign (@samp{+}).
+@end itemize
+
+The @code{getopt} function returns the option character for the next
+command line option.  When no more option arguments are available, it
+returns @code{-1}.  There may still be more non-option arguments; you
+must compare the external variable @code{optind} against the @var{argc}
+parameter to check this.
+
+If the option has an argument, @code{getopt} returns the argument by
+storing it in the variable @var{optarg}.  You don't ordinarily need to
+copy the @code{optarg} string, since it is a pointer into the original
+@var{argv} array, not into a static area that might be overwritten.
+
+If @code{getopt} finds an option character in @var{argv} that was not
+included in @var{options}, or a missing option argument, it returns
+@samp{?} and sets the external variable @code{optopt} to the actual
+option character.  If the first character of @var{options} is a colon
+(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
+indicate a missing option argument.  In addition, if the external
+variable @code{opterr} is nonzero (which is the default), @code{getopt}
+prints an error message.
+@end deftypefun
+
+@node Example of Getopt
+@subsection Example of Parsing Arguments with @code{getopt}
+
+Here is an example showing how @code{getopt} is typically used.  The
+key points to notice are:
+
+@itemize @bullet
+@item
+Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
+@code{-1}, indicating no more options are present, the loop terminates.
+
+@item
+A @code{switch} statement is used to dispatch on the return value from
+@code{getopt}.  In typical use, each case just sets a variable that
+is used later in the program.
+
+@item
+A second loop is used to process the remaining non-option arguments.
+@end itemize
+
+@smallexample
+@include testopt.c.texi
+@end smallexample
+
+Here are some examples showing what this program prints with different
+combinations of arguments:
+
+@smallexample
+% testopt
+aflag = 0, bflag = 0, cvalue = (null)
+
+% testopt -a -b
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -ab
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -c foo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt -cfoo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt arg1
+aflag = 0, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -a arg1
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -c foo arg1
+aflag = 0, bflag = 0, cvalue = foo
+Non-option argument arg1
+
+% testopt -a -- -b
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -b
+
+% testopt -a -
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -
+@end smallexample
+
+@node Getopt Long Options
+@subsection Parsing Long Options with @code{getopt_long}
+
+To accept GNU-style long options as well as single-character options,
+use @code{getopt_long} instead of @code{getopt}.  This function is
+declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
+program accept long options if it uses any options, for this takes
+little extra work and helps beginners remember how to use the program.
+
+@comment getopt.h
+@comment GNU
+@deftp {Data Type} {struct option}
+This structure describes a single long option name for the sake of
+@code{getopt_long}.  The argument @var{longopts} must be an array of
+these structures, one for each long option.  Terminate the array with an
+element containing all zeros.
+
+The @code{struct option} structure has these fields:
+
+@table @code
+@item const char *name
+This field is the name of the option.  It is a string.
+
+@item int has_arg
+This field says whether the option takes an argument.  It is an integer,
+and there are three legitimate values: @w{@code{no_argument}},
+@code{required_argument} and @code{optional_argument}.
+
+@item int *flag
+@itemx int val
+These fields control how to report or act on the option when it occurs.
+
+If @code{flag} is a null pointer, then the @code{val} is a value which
+identifies this option.  Often these values are chosen to uniquely
+identify particular long options.
+
+If @code{flag} is not a null pointer, it should be the address of an
+@code{int} variable which is the flag for this option.  The value in
+@code{val} is the value to store in the flag to indicate that the option
+was seen.
+@end table
+@end deftp
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Same issues as getopt.
+Decode options from the vector @var{argv} (whose length is @var{argc}).
+The argument @var{shortopts} describes the short options to accept, just as
+it does in @code{getopt}.  The argument @var{longopts} describes the long
+options to accept (see above).
+
+When @code{getopt_long} encounters a short option, it does the same
+thing that @code{getopt} would do: it returns the character code for the
+option, and stores the options argument (if it has one) in @code{optarg}.
+
+When @code{getopt_long} encounters a long option, it takes actions based
+on the @code{flag} and @code{val} fields of the definition of that
+option.
+
+If @code{flag} is a null pointer, then @code{getopt_long} returns the
+contents of @code{val} to indicate which option it found.  You should
+arrange distinct values in the @code{val} field for options with
+different meanings, so you can decode these values after
+@code{getopt_long} returns.  If the long option is equivalent to a short
+option, you can use the short option's character code in @code{val}.
+
+If @code{flag} is not a null pointer, that means this option should just
+set a flag in the program.  The flag is a variable of type @code{int}
+that you define.  Put the address of the flag in the @code{flag} field.
+Put in the @code{val} field the value you would like this option to
+store in the flag.  In this case, @code{getopt_long} returns @code{0}.
+
+For any long option, @code{getopt_long} tells you the index in the array
+@var{longopts} of the options definition, by storing it into
+@code{*@var{indexptr}}.  You can get the name of the option with
+@code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
+long options either by the values in their @code{val} fields or by their
+indices.  You can also distinguish in this way among long options that
+set flags.
+
+When a long option has an argument, @code{getopt_long} puts the argument
+value in the variable @code{optarg} before returning.  When the option
+has no argument, the value in @code{optarg} is a null pointer.  This is
+how you can tell whether an optional argument was supplied.
+
+When @code{getopt_long} has no more options to handle, it returns
+@code{-1}, and leaves in the variable @code{optind} the index in
+@var{argv} of the next remaining argument.
+@end deftypefun
+
+Since long option names were used before the @code{getopt_long}
+options was invented there are program interfaces which require programs
+to recognize options like @w{@samp{-option value}} instead of
+@w{@samp{--option value}}.  To enable these programs to use the GNU
+getopt functionality there is one more function available.
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
+@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Same issues as getopt.
+
+The @code{getopt_long_only} function is equivalent to the
+@code{getopt_long} function but it allows to specify the user of the
+application to pass long options with only @samp{-} instead of
+@samp{--}.  The @samp{--} prefix is still recognized but instead of
+looking through the short options if a @samp{-} is seen it is first
+tried whether this parameter names a long option.  If not, it is parsed
+as a short option.
+
+Assuming @code{getopt_long_only} is used starting an application with
+
+@smallexample
+  app -foo
+@end smallexample
+
+@noindent
+the @code{getopt_long_only} will first look for a long option named
+@samp{foo}.  If this is not found, the short options @samp{f}, @samp{o},
+and again @samp{o} are recognized.
+@end deftypefun
+
+@node Getopt Long Option Example
+@subsection Example of Parsing Long Options with @code{getopt_long}
+
+@smallexample
+@include longopt.c.texi
+@end smallexample
diff --git a/ap/libc/glibc/glibc-2.23/manual/header.texi b/ap/libc/glibc/glibc-2.23/manual/header.texi
new file mode 100644
index 0000000..2a551cd
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/header.texi
@@ -0,0 +1,22 @@
+@node Library Summary, Installation, Language Features, Top
+@c %MENU% A summary showing the syntax, header file, and derivation of each library feature
+@appendix Summary of Library Facilities
+
+This appendix is a complete list of the facilities declared within the
+header files supplied with @theglibc{}.  Each entry also lists the
+standard or other source from which each facility is derived, and tells
+you where in the manual you can find more information about how to use
+it.
+
+@c This table runs wide.  Shrink fonts.
+@iftex
+@smallfonts @rm
+@end iftex
+@table @code
+@comment summary.texi is generated from the other Texinfo files.
+@comment See the Makefile and summary.awk for the details.
+@include summary.texi
+@end table
+@iftex
+@textfonts @rm
+@end iftex
diff --git a/ap/libc/glibc/glibc-2.23/manual/install-plain.texi b/ap/libc/glibc/glibc-2.23/manual/install-plain.texi
new file mode 100644
index 0000000..c5179e7
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/install-plain.texi
@@ -0,0 +1,5 @@
+@c This is for making the `INSTALL' file for the distribution.
+@c Makeinfo ignores it when processing the file from the include.
+@setfilename INSTALL
+@set plain
+@include install.texi
diff --git a/ap/libc/glibc/glibc-2.23/manual/install.texi b/ap/libc/glibc/glibc-2.23/manual/install.texi
new file mode 100644
index 0000000..b329950
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/install.texi
@@ -0,0 +1,577 @@
+@include macros.texi
+@include pkgvers.texi
+
+@ifclear plain
+@node Installation, Maintenance, Library Summary, Top
+@end ifclear
+
+@c %MENU% How to install the GNU C Library
+@appendix Installing @theglibc{}
+
+Before you do anything else, you should read the FAQ at
+@url{http://sourceware.org/glibc/wiki/FAQ}.  It answers common
+questions and describes problems you may experience with compilation
+and installation.
+
+Features can be added to @theglibc{} via @dfn{add-on} bundles.  These are
+separate tar files, which you unpack into the top level of the source
+tree.  Then you give @code{configure} the @samp{--enable-add-ons} option
+to activate them, and they will be compiled into the library.
+
+You will need recent versions of several GNU tools: definitely GCC and
+GNU Make, and possibly others.  @xref{Tools for Compilation}, below.
+
+@ifclear plain
+@menu
+* Configuring and compiling::   How to compile and test GNU libc.
+* Running make install::        How to install it once you've got it
+ compiled.
+* Tools for Compilation::       You'll need these first.
+* Linux::                       Specific advice for GNU/Linux systems.
+* Reporting Bugs::              So they'll get fixed.
+@end menu
+@end ifclear
+
+@node Configuring and compiling
+@appendixsec Configuring and compiling @theglibc{}
+@cindex configuring
+@cindex compiling
+
+@Theglibc{} cannot be compiled in the source directory.  You must build
+it in a separate build directory.  For example, if you have unpacked
+the @glibcadj{} sources in @file{/src/gnu/glibc-@var{version}},
+create a directory
+@file{/src/gnu/glibc-build} to put the object files in.  This allows
+removing the whole build directory in case an error occurs, which is
+the safest way to get a fresh start and should always be done.
+
+From your object directory, run the shell script @file{configure} located
+at the top level of the source tree.  In the scenario above, you'd type
+
+@smallexample
+$ ../glibc-@var{version}/configure @var{args@dots{}}
+@end smallexample
+
+Please note that even though you're building in a separate build
+directory, the compilation may need to create or modify files and
+directories in the source directory.
+
+@noindent
+@code{configure} takes many options, but the only one that is usually
+mandatory is @samp{--prefix}.  This option tells @code{configure}
+where you want @theglibc{} installed.  This defaults to @file{/usr/local},
+but the normal setting to install as the standard system library is
+@samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
+empty prefix) for @gnuhurdsystems{}.
+
+It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
+the environment when running @code{configure}.  @var{CC} selects the C
+compiler that will be used, and @var{CFLAGS} sets optimization options
+for the compiler.
+
+The following list describes all of the available options for
+ @code{configure}:
+
+@table @samp
+@item --prefix=@var{directory}
+Install machine-independent data files in subdirectories of
+@file{@var{directory}}.  The default is to install in @file{/usr/local}.
+
+@item --exec-prefix=@var{directory}
+Install the library and other machine-dependent files in subdirectories
+of @file{@var{directory}}.  The default is to the @samp{--prefix}
+directory if that option is specified, or @file{/usr/local} otherwise.
+
+@item --with-headers=@var{directory}
+Look for kernel header files in @var{directory}, not
+@file{/usr/include}.  @Theglibc{} needs information from the kernel's header
+files describing the interface to the kernel.  @Theglibc{} will normally
+look in @file{/usr/include} for them,
+but if you specify this option, it will look in @var{DIRECTORY} instead.
+
+This option is primarily of use on a system where the headers in
+@file{/usr/include} come from an older version of @theglibc{}.  Conflicts can
+occasionally happen in this case.  You can also use this option if you want to
+compile @theglibc{} with a newer set of kernel headers than the ones found in
+@file{/usr/include}.
+
+@item --enable-add-ons[=@var{list}]
+Specify add-on packages to include in the build.  If this option is
+specified with no list, it enables all the add-on packages it finds in
+the main source directory; this is the default behavior.  You may
+specify an explicit list of add-ons to use in @var{list}, separated by
+spaces or commas (if you use spaces, remember to quote them from the
+shell).  Each add-on in @var{list} can be an absolute directory name
+or can be a directory name relative to the main source directory, or
+relative to the build directory (that is, the current working directory).
+For example, @samp{--enable-add-ons=nptl,../glibc-libidn-@var{version}}.
+
+@item --enable-kernel=@var{version}
+This option is currently only useful on @gnulinuxsystems{}.  The
+@var{version} parameter should have the form X.Y.Z and describes the
+smallest version of the Linux kernel the generated library is expected
+to support.  The higher the @var{version} number is, the less
+compatibility code is added, and the faster the code gets.
+
+@item --with-binutils=@var{directory}
+Use the binutils (assembler and linker) in @file{@var{directory}}, not
+the ones the C compiler would default to.  You can use this option if
+the default binutils on your system cannot deal with all the constructs
+in @theglibc{}.  In that case, @code{configure} will detect the
+problem and suppress these constructs, so that the library will still be
+usable, but functionality may be lost---for example, you can't build a
+shared libc with old binutils.
+
+@item --without-fp
+Use this option if your computer lacks hardware floating-point support
+and your operating system does not emulate an FPU.
+
+@c disable static doesn't work currently
+@c @item --disable-static
+@c Don't build static libraries.  Static libraries aren't that useful these
+@c days, but we recommend you build them in case you need them.
+
+@item --disable-shared
+Don't build shared libraries even if it is possible.  Not all systems
+support shared libraries; you need ELF support and (currently) the GNU
+linker.
+
+@item --disable-profile
+Don't build libraries with profiling information.  You may want to use
+this option if you don't plan to do profiling.
+
+@item --enable-static-nss
+Compile static versions of the NSS (Name Service Switch) libraries.
+This is not recommended because it defeats the purpose of NSS; a program
+linked statically with the NSS libraries cannot be dynamically
+reconfigured to use a different name database.
+
+@item --without-tls
+By default the C library is built with support for thread-local storage
+if the used tools support it.  By using @samp{--without-tls} this can be
+prevented though there generally is no reason since it creates
+compatibility problems.
+
+@item --enable-hardcoded-path-in-tests
+By default, dynamic tests are linked to run with the installed C library.
+This option hardcodes the newly built C library path in dynamic tests
+so that they can be invoked directly.
+
+@item --disable-timezone-tools
+By default, timezone related utilities (@command{zic}, @command{zdump},
+and @command{tzselect}) are installed with @theglibc{}.  If you are building
+these independently (e.g. by using the @samp{tzcode} package), then this
+option will allow disabling the install of these.
+
+Note that you need to make sure the external tools are kept in sync with
+the versions that @theglibc{} expects as the data formats may change over
+time.  Consult the @file{timezone} subdirectory for more details.
+
+@item --enable-lock-elision=yes
+Enable lock elision for pthread mutexes by default.
+
+@pindex pt_chown
+@findex grantpt
+@item --enable-pt_chown
+The file @file{pt_chown} is a helper binary for @code{grantpt}
+(@pxref{Allocation, Pseudo-Terminals}) that is installed setuid root to
+fix up pseudo-terminal ownership.  It is not built by default because
+systems using the Linux kernel are commonly built with the @code{devpts}
+filesystem enabled and mounted at @file{/dev/pts}, which manages
+pseudo-terminal ownership automatically.  By using
+@samp{--enable-pt_chown}, you may build @file{pt_chown} and install it
+setuid and owned by @code{root}.  The use of @file{pt_chown} introduces
+additional security risks to the system and you should enable it only if
+you understand and accept those risks.
+
+@item --disable-werror
+By default, @theglibc{} is built with @option{-Werror}.  If you wish
+to build without this option (for example, if building with a newer
+version of GCC than this version of @theglibc{} was tested with, so
+new warnings cause the build with @option{-Werror} to fail), you can
+configure with @option{--disable-werror}.
+
+@item --disable-mathvec
+By default for x86_64, @theglibc{} is built with vector math library.
+Use this option to disable vector math library.
+
+@item --build=@var{build-system}
+@itemx --host=@var{host-system}
+These options are for cross-compiling.  If you specify both options and
+@var{build-system} is different from @var{host-system}, @code{configure}
+will prepare to cross-compile @theglibc{} from @var{build-system} to be used
+on @var{host-system}.  You'll probably need the @samp{--with-headers}
+option too, and you may have to override @var{configure}'s selection of
+the compiler and/or binutils.
+
+If you only specify @samp{--host}, @code{configure} will prepare for a
+native compile but use what you specify instead of guessing what your
+system is.  This is most useful to change the CPU submodel.  For example,
+if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but
+you want to compile a library for 586es, give
+@samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add
+the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to
+@var{CFLAGS}.
+
+If you specify just @samp{--build}, @code{configure} will get confused.
+
+@item --with-pkgversion=@var{version}
+Specify a description, possibly including a build number or build
+date, of the binaries being built, to be included in
+@option{--version} output from programs installed with @theglibc{}.
+For example, @option{--with-pkgversion='FooBar GNU/Linux glibc build
+123'}.  The default value is @samp{GNU libc}.
+
+@item --with-bugurl=@var{url}
+Specify the URL that users should visit if they wish to report a bug,
+to be included in @option{--help} output from programs installed with
+@theglibc{}.  The default value refers to the main bug-reporting
+information for @theglibc{}.
+@end table
+
+To build the library and related programs, type @code{make}.  This will
+produce a lot of output, some of which may look like errors from
+@code{make} but isn't.  Look for error messages from @code{make}
+containing @samp{***}.  Those indicate that something is seriously wrong.
+
+The compilation process can take a long time, depending on the
+configuration and the speed of your machine.  Some complex modules may
+take a very long time to compile, as much as several minutes on slower
+machines.  Do not panic if the compiler appears to hang.
+
+If you want to run a parallel make, simply pass the @samp{-j} option
+with an appropriate numeric parameter to @code{make}.  You need a recent
+GNU @code{make} version, though.
+
+To build and run test programs which exercise some of the library
+facilities, type @code{make check}.  If it does not complete
+successfully, do not use the built library, and report a bug after
+verifying that the problem is not already known.  @xref{Reporting Bugs},
+for instructions on reporting bugs.  Note that some of the tests assume
+they are not being run by @code{root}.  We recommend you compile and
+test @theglibc{} as an unprivileged user.
+
+Before reporting bugs make sure there is no problem with your system.
+The tests (and later installation) use some pre-existing files of the
+system such as @file{/etc/passwd}, @file{/etc/nsswitch.conf} and others.
+These files must all contain correct and sensible content.
+
+Normally, @code{make check} will run all the tests before reporting
+all problems found and exiting with error status if any problems
+occurred.  You can specify @samp{stop-on-test-failure=y} when running
+@code{make check} to make the test run stop and exit with an error
+status immediately when a failure occurs.
+
+To format the @cite{GNU C Library Reference Manual} for printing, type
+@w{@code{make dvi}}.  You need a working @TeX{} installation to do
+this.  The distribution builds the on-line formatted version of the
+manual, as Info files, as part of the build process.  You can build
+them manually with @w{@code{make info}}.
+
+The library has a number of special-purpose configuration parameters
+which you can find in @file{Makeconfig}.  These can be overwritten with
+the file @file{configparms}.  To change them, create a
+@file{configparms} in your build directory and add values as appropriate
+for your system.  The file is included and parsed by @code{make} and has
+to follow the conventions for makefiles.
+
+It is easy to configure @theglibc{} for cross-compilation by
+setting a few variables in @file{configparms}.  Set @code{CC} to the
+cross-compiler for the target you configured the library for; it is
+important to use this same @code{CC} value when running
+@code{configure}, like this: @samp{CC=@var{target}-gcc configure
+@var{target}}.  Set @code{BUILD_CC} to the compiler to use for programs
+run on the build system as part of compiling the library.  You may need to
+set @code{AR} to cross-compiling versions of @code{ar}
+if the native tools are not configured to work with
+object files for the target you configured for.  When cross-compiling
+@theglibc{}, it may be tested using @samp{make check
+test-wrapper="@var{srcdir}/scripts/cross-test-ssh.sh @var{hostname}"},
+where @var{srcdir} is the absolute directory name for the main source
+directory and @var{hostname} is the host name of a system that can run
+the newly built binaries of @theglibc{}.  The source and build
+directories must be visible at the same locations on both the build
+system and @var{hostname}.
+
+In general, when testing @theglibc{}, @samp{test-wrapper} may be set
+to the name and arguments of any program to run newly built binaries.
+This program must preserve the arguments to the binary being run, its
+working directory and the standard input, output and error file
+descriptors.  If @samp{@var{test-wrapper} env} will not work to run a
+program with environment variables set, then @samp{test-wrapper-env}
+must be set to a program that runs a newly built program with
+environment variable assignments in effect, those assignments being
+specified as @samp{@var{var}=@var{value}} before the name of the
+program to be run.  If multiple assignments to the same variable are
+specified, the last assignment specified must take precedence.
+Similarly, if @samp{@var{test-wrapper} env -i} will not work to run a
+program with an environment completely empty of variables except those
+directly assigned, then @samp{test-wrapper-env-only} must be set; its
+use has the same syntax as @samp{test-wrapper-env}, the only
+difference in its semantics being starting with an empty set of
+environment variables rather than the ambient set.
+
+
+@node Running make install
+@appendixsec Installing the C Library
+@cindex installing
+
+To install the library and its header files, and the Info files of the
+manual, type @code{make install}.  This will
+build things, if necessary, before installing them; however, you should
+still compile everything first.  If you are installing @theglibc{} as your
+primary C library, we recommend that you shut the system down to
+single-user mode first, and reboot afterward.  This minimizes the risk
+of breaking things when the library changes out from underneath.
+
+@samp{make install} will do the entire job of upgrading from a
+previous installation of @theglibc{} version 2.x.  There may sometimes
+be headers
+left behind from the previous installation, but those are generally
+harmless.  If you want to avoid leaving headers behind you can do
+things in the following order.
+
+You must first build the library (@samp{make}), optionally check it
+(@samp{make check}), switch the include directories and then install
+(@samp{make install}).  The steps must be done in this order.  Not moving
+the directory before install will result in an unusable mixture of header
+files from both libraries, but configuring, building, and checking the
+library requires the ability to compile and run programs against the old
+library.  The new @file{/usr/include}, after switching the include
+directories and before installing the library should contain the Linux
+headers, but nothing else.  If you do this, you will need to restore
+any headers from libraries other than @theglibc{} yourself after installing the
+library.
+
+You can install @theglibc{} somewhere other than where you configured
+it to go by setting the @code{DESTDIR} GNU standard make variable on
+the command line for @samp{make install}.  The value of this variable
+is prepended to all the paths for installation.  This is useful when
+setting up a chroot environment or preparing a binary distribution.
+The directory should be specified with an absolute file name. Installing
+with the @code{prefix} and @code{exec_prefix} GNU standard make variables
+set is not supported.
+
+@Theglibc{} includes a daemon called @code{nscd}, which you
+may or may not want to run.  @code{nscd} caches name service lookups; it
+can dramatically improve performance with NIS+, and may help with DNS as
+well.
+
+One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid
+@code{root} if the @samp{--enable-pt_chown} configuration option is used.
+This program is invoked by the @code{grantpt} function; it sets the
+permissions on a pseudoterminal so it can be used by the calling process.
+If you are using a Linux kernel with the @code{devpts} filesystem enabled
+and mounted at @file{/dev/pts}, you don't need this program.
+
+After installation you might want to configure the timezone and locale
+installation of your system.  @Theglibc{} comes with a locale
+database which gets configured with @code{localedef}.  For example, to
+set up a German locale with name @code{de_DE}, simply issue the command
+@samp{localedef -i de_DE -f ISO-8859-1 de_DE}.  To configure all locales
+that are supported by @theglibc{}, you can issue from your build directory the
+command @samp{make localedata/install-locales}.
+
+To configure the locally used timezone, set the @code{TZ} environment
+variable.  The script @code{tzselect} helps you to select the right value.
+As an example, for Germany, @code{tzselect} would tell you to use
+@samp{TZ='Europe/Berlin'}.  For a system wide installation (the given
+paths are for an installation with @samp{--prefix=/usr}), link the
+timezone file which is in @file{/usr/share/zoneinfo} to the file
+@file{/etc/localtime}.  For Germany, you might execute @samp{ln -s
+/usr/share/zoneinfo/Europe/Berlin /etc/localtime}.
+
+@node Tools for Compilation
+@appendixsec Recommended Tools for Compilation
+@cindex installation tools
+@cindex tools, for installing library
+
+We recommend installing the following GNU tools before attempting to
+build @theglibc{}:
+
+@itemize @bullet
+@item
+GNU @code{make} 3.79 or newer
+
+You need the latest version of GNU @code{make}.  Modifying @theglibc{}
+to work with other @code{make} programs would be so difficult that
+we recommend you port GNU @code{make} instead.  @strong{Really.}  We
+recommend GNU @code{make} version 3.79.  All earlier versions have severe
+bugs or lack features.
+
+@item
+GCC 4.7 or newer
+
+GCC 4.7 or higher is required.  In general it is recommended to use
+the newest version of the compiler that is known to work for building
+@theglibc{}, as newer compilers usually produce better code.  As of
+release time, GCC 5.3 is the newest compiler verified to work to build
+@theglibc{}.
+
+You can use whatever compiler you like to compile programs that use
+@theglibc{}.
+
+Check the FAQ for any special compiler issues on particular platforms.
+
+@item
+GNU @code{binutils} 2.22 or later
+
+You must use GNU @code{binutils} (as and ld) to build @theglibc{}.
+No other assembler or linker has the necessary functionality at the
+moment. As of release time, GNU @code{binutils} 2.25 is the newest
+verified to work to build @theglibc{}.
+
+@item
+GNU @code{texinfo} 4.7 or later
+
+To correctly translate and install the Texinfo documentation you need
+this version of the @code{texinfo} package.  Earlier versions do not
+understand all the tags used in the document, and the installation
+mechanism for the info files is not present or works differently.
+As of release time, @code{texinfo} 6.0 is the newest verified to work
+to build @theglibc{}.
+
+@item
+GNU @code{awk} 3.1.2, or higher
+
+@code{awk} is used in several places to generate files.
+Some @code{gawk} extensions are used, including the @code{asorti}
+function, which was introduced in version 3.1.2 of @code{gawk}.
+As of release time, @code{gawk} version 4.1.3 is the newest verified
+to work to build @theglibc{}.
+
+@item
+Perl 5
+
+Perl is not required, but it is used if present to test the
+installation.  We may decide to use it elsewhere in the future.
+
+@item
+GNU @code{sed} 3.02 or newer
+
+@code{Sed} is used in several places to generate files.  Most scripts work
+with any version of @code{sed}.  As of release time, @code{sed} version
+4.2.2 is the newest verified to work to build @theglibc{}.
+
+@end itemize
+
+@noindent
+If you change any of the @file{configure.ac} files you will also need
+
+@itemize @bullet
+@item
+GNU @code{autoconf} 2.69 (exactly)
+@end itemize
+
+@noindent
+and if you change any of the message translation files you will need
+
+@itemize @bullet
+@item
+GNU @code{gettext} 0.10.36 or later
+@end itemize
+
+@noindent
+If you wish to regenerate the @code{yacc} parser code in the @file{intl}
+subdirectory you will need
+
+@itemize @bullet
+@item
+GNU @code{bison} 2.7 or later
+@end itemize
+
+@noindent
+You may also need these packages if you upgrade your source tree using
+patches, although we try to avoid this.
+
+@node Linux
+@appendixsec Specific advice for @gnulinuxsystems{}
+@cindex kernel header files
+
+If you are installing @theglibc{} on @gnulinuxsystems{}, you need to have
+the header files from a 2.6.32 or newer kernel around for reference.
+These headers must be installed using @samp{make headers_install}; the
+headers present in the kernel source directory are not suitable for
+direct use by @theglibc{}.  You do not need to use that kernel, just have
+its headers installed where @theglibc{} can access them, referred to here as
+@var{install-directory}.  The easiest way to do this is to unpack it
+in a directory such as @file{/usr/src/linux-@var{version}}.  In that
+directory, run @samp{make headers_install
+INSTALL_HDR_PATH=@var{install-directory}}.  Finally, configure @theglibc{}
+with the option @samp{--with-headers=@var{install-directory}/include}.
+Use the most recent kernel you can get your hands on.  (If you are
+cross-compiling @theglibc{}, you need to specify
+@samp{ARCH=@var{architecture}} in the @samp{make headers_install}
+command, where @var{architecture} is the architecture name used by the
+Linux kernel, such as @samp{x86} or @samp{powerpc}.)
+
+After installing @theglibc{}, you may need to remove or rename
+directories such as @file{/usr/include/linux} and
+@file{/usr/include/asm}, and replace them with copies of directories
+such as @file{linux} and @file{asm} from
+@file{@var{install-directory}/include}.  All directories present in
+@file{@var{install-directory}/include} should be copied, except that
+@theglibc{} provides its own version of @file{/usr/include/scsi}; the
+files provided by the kernel should be copied without replacing those
+provided by @theglibc{}.  The @file{linux}, @file{asm} and
+@file{asm-generic} directories are required to compile programs using
+@theglibc{}; the other directories describe interfaces to the kernel but
+are not required if not compiling programs using those interfaces.
+You do not need to copy kernel headers if you did not specify an
+alternate kernel header source using @samp{--with-headers}.
+
+The Filesystem Hierarchy Standard for @gnulinuxsystems{} expects some
+components of the @glibcadj{} installation to be in
+@file{/lib} and some in @file{/usr/lib}.  This is handled automatically
+if you configure @theglibc{} with @samp{--prefix=/usr}.  If you set some other
+prefix or allow it to default to @file{/usr/local}, then all the
+components are installed there.
+
+@node Reporting Bugs
+@appendixsec Reporting Bugs
+@cindex reporting bugs
+@cindex bugs, reporting
+
+There are probably bugs in @theglibc{}.  There are certainly
+errors and omissions in this manual.  If you report them, they will get
+fixed.  If you don't, no one will ever know about them and they will
+remain unfixed for all eternity, if not longer.
+
+It is a good idea to verify that the problem has not already been
+reported.  Bugs are documented in two places: The file @file{BUGS}
+describes a number of well known bugs and the central @glibcadj{}
+bug tracking system has a
+WWW interface at
+@url{http://sourceware.org/bugzilla/}.  The WWW
+interface gives you access to open and closed reports.  A closed report
+normally includes a patch or a hint on solving the problem.
+
+To report a bug, first you must find it.  With any luck, this will be the
+hard part.  Once you've found a bug, make sure it's really a bug.  A
+good way to do this is to see if @theglibc{} behaves the same way
+some other C library does.  If so, probably you are wrong and the
+libraries are right (but not necessarily).  If not, one of the libraries
+is probably wrong.  It might not be @theglibc{}.  Many historical
+Unix C libraries permit things that we don't, such as closing a file
+twice.
+
+If you think you have found some way in which @theglibc{} does not
+conform to the ISO and POSIX standards (@pxref{Standards and
+Portability}), that is definitely a bug.  Report it!
+
+Once you're sure you've found a bug, try to narrow it down to the
+smallest test case that reproduces the problem.  In the case of a C
+library, you really only need to narrow it down to one library
+function call, if possible.  This should not be too difficult.
+
+The final step when you have a simple test case is to report the bug.
+Do this at @value{REPORT_BUGS_TO}.
+
+If you are not sure how a function should behave, and this manual
+doesn't tell you, that's a bug in the manual.  Report that too!  If the
+function's behavior disagrees with the manual, then either the library
+or the manual has a bug, so report the disagreement.  If you find any
+errors or omissions in this manual, please report them to the
+bug database.  If you refer to specific
+sections of the manual, please include the section names for easier
+identification.
diff --git a/ap/libc/glibc/glibc-2.23/manual/intro.texi b/ap/libc/glibc/glibc-2.23/manual/intro.texi
new file mode 100644
index 0000000..d4045f2
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/intro.texi
@@ -0,0 +1,1506 @@
+@node Introduction, Error Reporting, Top, Top
+@chapter Introduction
+@c %MENU% Purpose of the GNU C Library
+
+The C language provides no built-in facilities for performing such
+common operations as input/output, memory management, string
+manipulation, and the like.  Instead, these facilities are defined
+in a standard @dfn{library}, which you compile and link with your
+programs.
+@cindex library
+
+@Theglibc{}, described in this document, defines all of the
+library functions that are specified by the @w{ISO C} standard, as well as
+additional features specific to POSIX and other derivatives of the Unix
+operating system, and extensions specific to @gnusystems{}.
+
+The purpose of this manual is to tell you how to use the facilities
+of @theglibc{}.  We have mentioned which features belong to which
+standards to help you identify things that are potentially non-portable
+to other systems.  But the emphasis in this manual is not on strict
+portability.
+
+@menu
+* Getting Started::             What this manual is for and how to use it.
+* Standards and Portability::   Standards and sources upon which the GNU
+                                 C library is based.
+* Using the Library::           Some practical uses for the library.
+* Roadmap to the Manual::       Overview of the remaining chapters in
+                                 this manual.
+@end menu
+
+@node Getting Started, Standards and Portability,  , Introduction
+@section Getting Started
+
+This manual is written with the assumption that you are at least
+somewhat familiar with the C programming language and basic programming
+concepts.  Specifically, familiarity with ISO standard C
+(@pxref{ISO C}), rather than ``traditional'' pre-ISO C dialects, is
+assumed.
+
+@Theglibc{} includes several @dfn{header files}, each of which
+provides definitions and declarations for a group of related facilities;
+this information is used by the C compiler when processing your program.
+For example, the header file @file{stdio.h} declares facilities for
+performing input and output, and the header file @file{string.h}
+declares string processing utilities.  The organization of this manual
+generally follows the same division as the header files.
+
+If you are reading this manual for the first time, you should read all
+of the introductory material and skim the remaining chapters.  There are
+a @emph{lot} of functions in @theglibc{} and it's not realistic to
+expect that you will be able to remember exactly @emph{how} to use each
+and every one of them.  It's more important to become generally familiar
+with the kinds of facilities that the library provides, so that when you
+are writing your programs you can recognize @emph{when} to make use of
+library functions, and @emph{where} in this manual you can find more
+specific information about them.
+
+
+@node Standards and Portability, Using the Library, Getting Started, Introduction
+@section Standards and Portability
+@cindex standards
+
+This section discusses the various standards and other sources that @theglibc{}
+is based upon.  These sources include the @w{ISO C} and
+POSIX standards, and the System V and Berkeley Unix implementations.
+
+The primary focus of this manual is to tell you how to make effective
+use of the @glibcadj{} facilities.  But if you are concerned about
+making your programs compatible with these standards, or portable to
+operating systems other than GNU, this can affect how you use the
+library.  This section gives you an overview of these standards, so that
+you will know what they are when they are mentioned in other parts of
+the manual.
+
+@xref{Library Summary}, for an alphabetical list of the functions and
+other symbols provided by the library.  This list also states which
+standards each function or symbol comes from.
+
+@menu
+* 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.
+@end menu
+
+@node ISO C, POSIX,  , Standards and Portability
+@subsection ISO C
+@cindex ISO C
+
+@Theglibc{} is compatible with the C standard adopted by the
+American National Standards Institute (ANSI):
+@cite{American National Standard X3.159-1989---``ANSI C''} and later
+by the International Standardization Organization (ISO):
+@cite{ISO/IEC 9899:1990, ``Programming languages---C''}.
+We here refer to the standard as @w{ISO C} since this is the more
+general standard in respect of ratification.
+The header files and library facilities that make up @theglibc{} are
+a superset of those specified by the @w{ISO C} standard.@refill
+
+@pindex gcc
+If you are concerned about strict adherence to the @w{ISO C} standard, you
+should use the @samp{-ansi} option when you compile your programs with
+the GNU C compiler.  This tells the compiler to define @emph{only} ISO
+standard features from the library header files, unless you explicitly
+ask for additional features.  @xref{Feature Test Macros}, for
+information on how to do this.
+
+Being able to restrict the library to include only @w{ISO C} features is
+important because @w{ISO C} puts limitations on what names can be defined
+by the library implementation, and the GNU extensions don't fit these
+limitations.  @xref{Reserved Names}, for more information about these
+restrictions.
+
+This manual does not attempt to give you complete details on the
+differences between @w{ISO C} and older dialects.  It gives advice on how
+to write programs to work portably under multiple C dialects, but does
+not aim for completeness.
+
+
+@node POSIX, Berkeley Unix, ISO C, Standards and Portability
+@subsection POSIX (The Portable Operating System Interface)
+@cindex POSIX
+@cindex POSIX.1
+@cindex IEEE Std 1003.1
+@cindex ISO/IEC 9945-1
+@cindex POSIX.2
+@cindex IEEE Std 1003.2
+@cindex ISO/IEC 9945-2
+
+@Theglibc{} is also compatible with the ISO @dfn{POSIX} family of
+standards, known more formally as the @dfn{Portable Operating System
+Interface for Computer Environments} (ISO/IEC 9945).  They were also
+published as ANSI/IEEE Std 1003.  POSIX is derived mostly from various
+versions of the Unix operating system.
+
+The library facilities specified by the POSIX standards are a superset
+of those required by @w{ISO C}; POSIX specifies additional features for
+@w{ISO C} functions, as well as specifying new additional functions.  In
+general, the additional requirements and functionality defined by the
+POSIX standards are aimed at providing lower-level support for a
+particular kind of operating system environment, rather than general
+programming language support which can run in many diverse operating
+system environments.@refill
+
+@Theglibc{} implements all of the functions specified in
+@cite{ISO/IEC 9945-1:1996, the POSIX System Application Program
+Interface}, commonly referred to as POSIX.1.  The primary extensions to
+the @w{ISO C} facilities specified by this standard include file system
+interface primitives (@pxref{File System Interface}), device-specific
+terminal control functions (@pxref{Low-Level Terminal Interface}), and
+process control functions (@pxref{Processes}).
+
+Some facilities from @cite{ISO/IEC 9945-2:1993, the POSIX Shell and
+Utilities standard} (POSIX.2) are also implemented in @theglibc{}.
+These include utilities for dealing with regular expressions and other
+pattern matching facilities (@pxref{Pattern Matching}).
+
+@menu
+* POSIX Safety Concepts::       Safety concepts from POSIX.
+* Unsafe Features::             Features that make functions unsafe.
+* Conditionally Safe Features:: Features that make functions unsafe
+                                 in the absence of workarounds.
+* Other Safety Remarks::        Additional safety features and remarks.
+@end menu
+
+@comment Roland sez:
+@comment The GNU C library as it stands conforms to 1003.2 draft 11, which
+@comment specifies:
+@comment
+@comment Several new macros in <limits.h>.
+@comment popen, pclose
+@comment <regex.h> (which is not yet fully implemented--wait on this)
+@comment fnmatch
+@comment getopt
+@comment <glob.h>
+@comment <wordexp.h> (not yet implemented)
+@comment confstr
+
+@node POSIX Safety Concepts, Unsafe Features, , POSIX
+@subsubsection POSIX Safety Concepts
+@cindex POSIX Safety Concepts
+
+This manual documents various safety properties of @glibcadj{}
+functions, in lines that follow their prototypes and look like:
+
+@sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The properties are assessed according to the criteria set forth in the
+POSIX standard for such safety contexts as Thread-, Async-Signal- and
+Async-Cancel- -Safety.  Intuitive definitions of these properties,
+attempting to capture the meaning of the standard definitions, follow.
+
+@itemize @bullet
+
+@item
+@cindex MT-Safe
+@cindex Thread-Safe
+@code{MT-Safe} or Thread-Safe functions are safe to call in the presence
+of other threads.  MT, in MT-Safe, stands for Multi Thread.
+
+Being MT-Safe does not imply a function is atomic, nor that it uses any
+of the memory synchronization mechanisms POSIX exposes to users.  It is
+even possible that calling MT-Safe functions in sequence does not yield
+an MT-Safe combination.  For example, having a thread call two MT-Safe
+functions one right after the other does not guarantee behavior
+equivalent to atomic execution of a combination of both functions, since
+concurrent calls in other threads may interfere in a destructive way.
+
+Whole-program optimizations that could inline functions across library
+interfaces may expose unsafe reordering, and so performing inlining
+across the @glibcadj{} interface is not recommended.  The documented
+MT-Safety status is not guaranteed under whole-program optimization.
+However, functions defined in user-visible headers are designed to be
+safe for inlining.
+
+
+@item
+@cindex AS-Safe
+@cindex Async-Signal-Safe
+@code{AS-Safe} or Async-Signal-Safe functions are safe to call from
+asynchronous signal handlers.  AS, in AS-Safe, stands for Asynchronous
+Signal.
+
+Many functions that are AS-Safe may set @code{errno}, or modify the
+floating-point environment, because their doing so does not make them
+unsuitable for use in signal handlers.  However, programs could
+misbehave should asynchronous signal handlers modify this thread-local
+state, and the signal handling machinery cannot be counted on to
+preserve it.  Therefore, signal handlers that call functions that may
+set @code{errno} or modify the floating-point environment @emph{must}
+save their original values, and restore them before returning.
+
+
+@item
+@cindex AC-Safe
+@cindex Async-Cancel-Safe
+@code{AC-Safe} or Async-Cancel-Safe functions are safe to call when
+asynchronous cancellation is enabled.  AC in AC-Safe stands for
+Asynchronous Cancellation.
+
+The POSIX standard defines only three functions to be AC-Safe, namely
+@code{pthread_cancel}, @code{pthread_setcancelstate}, and
+@code{pthread_setcanceltype}.  At present @theglibc{} provides no
+guarantees beyond these three functions, but does document which
+functions are presently AC-Safe.  This documentation is provided for use
+by @theglibc{} developers.
+
+Just like signal handlers, cancellation cleanup routines must configure
+the floating point environment they require.  The routines cannot assume
+a floating point environment, particularly when asynchronous
+cancellation is enabled.  If the configuration of the floating point
+environment cannot be performed atomically then it is also possible that
+the environment encountered is internally inconsistent.
+
+
+@item
+@cindex MT-Unsafe
+@cindex Thread-Unsafe
+@cindex AS-Unsafe
+@cindex Async-Signal-Unsafe
+@cindex AC-Unsafe
+@cindex Async-Cancel-Unsafe
+@code{MT-Unsafe}, @code{AS-Unsafe}, @code{AC-Unsafe} functions are not
+safe to call within the safety contexts described above.  Calling them
+within such contexts invokes undefined behavior.
+
+Functions not explicitly documented as safe in a safety context should
+be regarded as Unsafe.
+
+
+@item
+@cindex Preliminary
+@code{Preliminary} safety properties are documented, indicating these
+properties may @emph{not} be counted on in future releases of
+@theglibc{}.
+
+Such preliminary properties are the result of an assessment of the
+properties of our current implementation, rather than of what is
+mandated and permitted by current and future standards.
+
+Although we strive to abide by the standards, in some cases our
+implementation is safe even when the standard does not demand safety,
+and in other cases our implementation does not meet the standard safety
+requirements.  The latter are most likely bugs; the former, when marked
+as @code{Preliminary}, should not be counted on: future standards may
+require changes that are not compatible with the additional safety
+properties afforded by the current implementation.
+
+Furthermore, the POSIX standard does not offer a detailed definition of
+safety.  We assume that, by ``safe to call'', POSIX means that, as long
+as the program does not invoke undefined behavior, the ``safe to call''
+function behaves as specified, and does not cause other functions to
+deviate from their specified behavior.  We have chosen to use its loose
+definitions of safety, not because they are the best definitions to use,
+but because choosing them harmonizes this manual with POSIX.
+
+Please keep in mind that these are preliminary definitions and
+annotations, and certain aspects of the definitions are still under
+discussion and might be subject to clarification or change.
+
+Over time, we envision evolving the preliminary safety notes into stable
+commitments, as stable as those of our interfaces.  As we do, we will
+remove the @code{Preliminary} keyword from safety notes.  As long as the
+keyword remains, however, they are not to be regarded as a promise of
+future behavior.
+
+
+@end itemize
+
+Other keywords that appear in safety notes are defined in subsequent
+sections.
+
+
+@node Unsafe Features, Conditionally Safe Features, POSIX Safety Concepts, POSIX
+@subsubsection Unsafe Features
+@cindex Unsafe Features
+
+Functions that are unsafe to call in certain contexts are annotated with
+keywords that document their features that make them unsafe to call.
+AS-Unsafe features in this section indicate the functions are never safe
+to call when asynchronous signals are enabled.  AC-Unsafe features
+indicate they are never safe to call when asynchronous cancellation is
+enabled.  There are no MT-Unsafe marks in this section.
+
+@itemize @bullet
+
+@item @code{lock}
+@cindex lock
+
+Functions marked with @code{lock} as an AS-Unsafe feature may be
+interrupted by a signal while holding a non-recursive lock.  If the
+signal handler calls another such function that takes the same lock, the
+result is a deadlock.
+
+Functions annotated with @code{lock} as an AC-Unsafe feature may, if
+cancelled asynchronously, fail to release a lock that would have been
+released if their execution had not been interrupted by asynchronous
+thread cancellation.  Once a lock is left taken, attempts to take that
+lock will block indefinitely.
+
+
+@item @code{corrupt}
+@cindex corrupt
+
+Functions marked with @code{corrupt} as an AS-Unsafe feature may corrupt
+data structures and misbehave when they interrupt, or are interrupted
+by, another such function.  Unlike functions marked with @code{lock},
+these take recursive locks to avoid MT-Safety problems, but this is not
+enough to stop a signal handler from observing a partially-updated data
+structure.  Further corruption may arise from the interrupted function's
+failure to notice updates made by signal handlers.
+
+Functions marked with @code{corrupt} as an AC-Unsafe feature may leave
+data structures in a corrupt, partially updated state.  Subsequent uses
+of the data structure may misbehave.
+
+@c A special case, probably not worth documenting separately, involves
+@c reallocing, or even freeing pointers.  Any case involving free could
+@c be easily turned into an ac-safe leak by resetting the pointer before
+@c releasing it; I don't think we have any case that calls for this sort
+@c of fixing.  Fixing the realloc cases would require a new interface:
+@c instead of @code{ptr=realloc(ptr,size)} we'd have to introduce
+@c @code{acsafe_realloc(&ptr,size)} that would modify ptr before
+@c releasing the old memory.  The ac-unsafe realloc could be implemented
+@c in terms of an internal interface with this semantics (say
+@c __acsafe_realloc), but since realloc can be overridden, the function
+@c we call to implement realloc should not be this internal interface,
+@c but another internal interface that calls __acsafe_realloc if realloc
+@c was not overridden, and calls the overridden realloc with async
+@c cancel disabled.  --lxoliva
+
+
+@item @code{heap}
+@cindex heap
+
+Functions marked with @code{heap} may call heap memory management
+functions from the @code{malloc}/@code{free} family of functions and are
+only as safe as those functions.  This note is thus equivalent to:
+
+@sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+
+
+@c Check for cases that should have used plugin instead of or in
+@c addition to this.  Then, after rechecking gettext, adjust i18n if
+@c needed.
+@item @code{dlopen}
+@cindex dlopen
+
+Functions marked with @code{dlopen} use the dynamic loader to load
+shared libraries into the current execution image.  This involves
+opening files, mapping them into memory, allocating additional memory,
+resolving symbols, applying relocations and more, all of this while
+holding internal dynamic loader locks.
+
+The locks are enough for these functions to be AS- and AC-Unsafe, but
+other issues may arise.  At present this is a placeholder for all
+potential safety issues raised by @code{dlopen}.
+
+@c dlopen runs init and fini sections of the module; does this mean
+@c dlopen always implies plugin?
+
+
+@item @code{plugin}
+@cindex plugin
+
+Functions annotated with @code{plugin} may run code from plugins that
+may be external to @theglibc{}.  Such plugin functions are assumed to be
+MT-Safe, AS-Unsafe and AC-Unsafe.  Examples of such plugins are stack
+@cindex NSS
+unwinding libraries, name service switch (NSS) and character set
+@cindex iconv
+conversion (iconv) back-ends.
+
+Although the plugins mentioned as examples are all brought in by means
+of dlopen, the @code{plugin} keyword does not imply any direct
+involvement of the dynamic loader or the @code{libdl} interfaces, those
+are covered by @code{dlopen}.  For example, if one function loads a
+module and finds the addresses of some of its functions, while another
+just calls those already-resolved functions, the former will be marked
+with @code{dlopen}, whereas the latter will get the @code{plugin}.  When
+a single function takes all of these actions, then it gets both marks.
+
+
+@item @code{i18n}
+@cindex i18n
+
+Functions marked with @code{i18n} may call internationalization
+functions of the @code{gettext} family and will be only as safe as those
+functions.  This note is thus equivalent to:
+
+@sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}}
+
+
+@item @code{timer}
+@cindex timer
+
+Functions marked with @code{timer} use the @code{alarm} function or
+similar to set a time-out for a system call or a long-running operation.
+In a multi-threaded program, there is a risk that the time-out signal
+will be delivered to a different thread, thus failing to interrupt the
+intended thread.  Besides being MT-Unsafe, such functions are always
+AS-Unsafe, because calling them in signal handlers may interfere with
+timers set in the interrupted code, and AC-Unsafe, because there is no
+safe way to guarantee an earlier timer will be reset in case of
+asynchronous cancellation.
+
+@end itemize
+
+
+@node Conditionally Safe Features, Other Safety Remarks, Unsafe Features, POSIX
+@subsubsection Conditionally Safe Features
+@cindex Conditionally Safe Features
+
+For some features that make functions unsafe to call in certain
+contexts, there are known ways to avoid the safety problem other than
+refraining from calling the function altogether.  The keywords that
+follow refer to such features, and each of their definitions indicate
+how the whole program needs to be constrained in order to remove the
+safety problem indicated by the keyword.  Only when all the reasons that
+make a function unsafe are observed and addressed, by applying the
+documented constraints, does the function become safe to call in a
+context.
+
+@itemize @bullet
+
+@item @code{init}
+@cindex init
+
+Functions marked with @code{init} as an MT-Unsafe feature perform
+MT-Unsafe initialization when they are first called.
+
+Calling such a function at least once in single-threaded mode removes
+this specific cause for the function to be regarded as MT-Unsafe.  If no
+other cause for that remains, the function can then be safely called
+after other threads are started.
+
+Functions marked with @code{init} as an AS- or AC-Unsafe feature use the
+internal @code{libc_once} machinery or similar to initialize internal
+data structures.
+
+If a signal handler interrupts such an initializer, and calls any
+function that also performs @code{libc_once} initialization, it will
+deadlock if the thread library has been loaded.
+
+Furthermore, if an initializer is partially complete before it is
+canceled or interrupted by a signal whose handler requires the same
+initialization, some or all of the initialization may be performed more
+than once, leaking resources or even resulting in corrupt internal data.
+
+Applications that need to call functions marked with @code{init} as an
+AS- or AC-Unsafe feature should ensure the initialization is performed
+before configuring signal handlers or enabling cancellation, so that the
+AS- and AC-Safety issues related with @code{libc_once} do not arise.
+
+@c We may have to extend the annotations to cover conditions in which
+@c initialization may or may not occur, since an initial call in a safe
+@c context is no use if the initialization doesn't take place at that
+@c time: it doesn't remove the risk for later calls.
+
+
+@item @code{race}
+@cindex race
+
+Functions annotated with @code{race} as an MT-Safety issue operate on
+objects in ways that may cause data races or similar forms of
+destructive interference out of concurrent execution.  In some cases,
+the objects are passed to the functions by users; in others, they are
+used by the functions to return values to users; in others, they are not
+even exposed to users.
+
+We consider access to objects passed as (indirect) arguments to
+functions to be data race free.  The assurance of data race free objects
+is the caller's responsibility.  We will not mark a function as
+MT-Unsafe or AS-Unsafe if it misbehaves when users fail to take the
+measures required by POSIX to avoid data races when dealing with such
+objects.  As a general rule, if a function is documented as reading from
+an object passed (by reference) to it, or modifying it, users ought to
+use memory synchronization primitives to avoid data races just as they
+would should they perform the accesses themselves rather than by calling
+the library function.  @code{FILE} streams are the exception to the
+general rule, in that POSIX mandates the library to guard against data
+races in many functions that manipulate objects of this specific opaque
+type.  We regard this as a convenience provided to users, rather than as
+a general requirement whose expectations should extend to other types.
+
+In order to remind users that guarding certain arguments is their
+responsibility, we will annotate functions that take objects of certain
+types as arguments.  We draw the line for objects passed by users as
+follows: objects whose types are exposed to users, and that users are
+expected to access directly, such as memory buffers, strings, and
+various user-visible @code{struct} types, do @emph{not} give reason for
+functions to be annotated with @code{race}.  It would be noisy and
+redundant with the general requirement, and not many would be surprised
+by the library's lack of internal guards when accessing objects that can
+be accessed directly by users.
+
+As for objects that are opaque or opaque-like, in that they are to be
+manipulated only by passing them to library functions (e.g.,
+@code{FILE}, @code{DIR}, @code{obstack}, @code{iconv_t}), there might be
+additional expectations as to internal coordination of access by the
+library.  We will annotate, with @code{race} followed by a colon and the
+argument name, functions that take such objects but that do not take
+care of synchronizing access to them by default.  For example,
+@code{FILE} stream @code{unlocked} functions will be annotated, but
+those that perform implicit locking on @code{FILE} streams by default
+will not, even though the implicit locking may be disabled on a
+per-stream basis.
+
+In either case, we will not regard as MT-Unsafe functions that may
+access user-supplied objects in unsafe ways should users fail to ensure
+the accesses are well defined.  The notion prevails that users are
+expected to safeguard against data races any user-supplied objects that
+the library accesses on their behalf.
+
+@c The above describes @mtsrace; @mtasurace is described below.
+
+This user responsibility does not apply, however, to objects controlled
+by the library itself, such as internal objects and static buffers used
+to return values from certain calls.  When the library doesn't guard
+them against concurrent uses, these cases are regarded as MT-Unsafe and
+AS-Unsafe (although the @code{race} mark under AS-Unsafe will be omitted
+as redundant with the one under MT-Unsafe).  As in the case of
+user-exposed objects, the mark may be followed by a colon and an
+identifier.  The identifier groups all functions that operate on a
+certain unguarded object; users may avoid the MT-Safety issues related
+with unguarded concurrent access to such internal objects by creating a
+non-recursive mutex related with the identifier, and always holding the
+mutex when calling any function marked as racy on that identifier, as
+they would have to should the identifier be an object under user
+control.  The non-recursive mutex avoids the MT-Safety issue, but it
+trades one AS-Safety issue for another, so use in asynchronous signals
+remains undefined.
+
+When the identifier relates to a static buffer used to hold return
+values, the mutex must be held for as long as the buffer remains in use
+by the caller.  Many functions that return pointers to static buffers
+offer reentrant variants that store return values in caller-supplied
+buffers instead.  In some cases, such as @code{tmpname}, the variant is
+chosen not by calling an alternate entry point, but by passing a
+non-@code{NULL} pointer to the buffer in which the returned values are
+to be stored.  These variants are generally preferable in multi-threaded
+programs, although some of them are not MT-Safe because of other
+internal buffers, also documented with @code{race} notes.
+
+
+@item @code{const}
+@cindex const
+
+Functions marked with @code{const} as an MT-Safety issue non-atomically
+modify internal objects that are better regarded as constant, because a
+substantial portion of @theglibc{} accesses them without
+synchronization.  Unlike @code{race}, that causes both readers and
+writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe,
+this mark is applied to writers only.  Writers remain equally MT- and
+AS-Unsafe to call, but the then-mandatory constness of objects they
+modify enables readers to be regarded as MT-Safe and AS-Safe (as long as
+no other reasons for them to be unsafe remain), since the lack of
+synchronization is not a problem when the objects are effectively
+constant.
+
+The identifier that follows the @code{const} mark will appear by itself
+as a safety note in readers.  Programs that wish to work around this
+safety issue, so as to call writers, may use a non-recursve
+@code{rwlock} associated with the identifier, and guard @emph{all} calls
+to functions marked with @code{const} followed by the identifier with a
+write lock, and @emph{all} calls to functions marked with the identifier
+by itself with a read lock.  The non-recursive locking removes the
+MT-Safety problem, but it trades one AS-Safety problem for another, so
+use in asynchronous signals remains undefined.
+
+@c But what if, instead of marking modifiers with const:id and readers
+@c with just id, we marked writers with race:id and readers with ro:id?
+@c Instead of having to define each instance of “id”, we'd have a
+@c general pattern governing all such “id”s, wherein race:id would
+@c suggest the need for an exclusive/write lock to make the function
+@c safe, whereas ro:id would indicate “id” is expected to be read-only,
+@c but if any modifiers are called (while holding an exclusive lock),
+@c then ro:id-marked functions ought to be guarded with a read lock for
+@c safe operation.  ro:env or ro:locale, for example, seems to convey
+@c more clearly the expectations and the meaning, than just env or
+@c locale.
+
+
+@item @code{sig}
+@cindex sig
+
+Functions marked with @code{sig} as a MT-Safety issue (that implies an
+identical AS-Safety issue, omitted for brevity) may temporarily install
+a signal handler for internal purposes, which may interfere with other
+uses of the signal, identified after a colon.
+
+This safety problem can be worked around by ensuring that no other uses
+of the signal will take place for the duration of the call.  Holding a
+non-recursive mutex while calling all functions that use the same
+temporary signal; blocking that signal before the call and resetting its
+handler afterwards is recommended.
+
+There is no safe way to guarantee the original signal handler is
+restored in case of asynchronous cancellation, therefore so-marked
+functions are also AC-Unsafe.
+
+@c fixme: at least deferred cancellation should get it right, and would
+@c obviate the restoring bit below, and the qualifier above.
+
+Besides the measures recommended to work around the MT- and AS-Safety
+problem, in order to avert the cancellation problem, disabling
+asynchronous cancellation @emph{and} installing a cleanup handler to
+restore the signal to the desired state and to release the mutex are
+recommended.
+
+
+@item @code{term}
+@cindex term
+
+Functions marked with @code{term} as an MT-Safety issue may change the
+terminal settings in the recommended way, namely: call @code{tcgetattr},
+modify some flags, and then call @code{tcsetattr}; this creates a window
+in which changes made by other threads are lost.  Thus, functions marked
+with @code{term} are MT-Unsafe.  The same window enables changes made by
+asynchronous signals to be lost.  These functions are also AS-Unsafe,
+but the corresponding mark is omitted as redundant.
+
+It is thus advisable for applications using the terminal to avoid
+concurrent and reentrant interactions with it, by not using it in signal
+handlers or blocking signals that might use it, and holding a lock while
+calling these functions and interacting with the terminal.  This lock
+should also be used for mutual exclusion with functions marked with
+@code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for
+the controlling terminal.  The caller may use a single mutex for
+simplicity, or use one mutex per terminal, even if referenced by
+different file descriptors.
+
+Functions marked with @code{term} as an AC-Safety issue are supposed to
+restore terminal settings to their original state, after temporarily
+changing them, but they may fail to do so if cancelled.
+
+@c fixme: at least deferred cancellation should get it right, and would
+@c obviate the restoring bit below, and the qualifier above.
+
+Besides the measures recommended to work around the MT- and AS-Safety
+problem, in order to avert the cancellation problem, disabling
+asynchronous cancellation @emph{and} installing a cleanup handler to
+restore the terminal settings to the original state and to release the
+mutex are recommended.
+
+
+@end itemize
+
+
+@node Other Safety Remarks, , Conditionally Safe Features, POSIX
+@subsubsection Other Safety Remarks
+@cindex Other Safety Remarks
+
+Additional keywords may be attached to functions, indicating features
+that do not make a function unsafe to call, but that may need to be
+taken into account in certain classes of programs:
+
+@itemize @bullet
+
+@item @code{locale}
+@cindex locale
+
+Functions annotated with @code{locale} as an MT-Safety issue read from
+the locale object without any form of synchronization.  Functions
+annotated with @code{locale} called concurrently with locale changes may
+behave in ways that do not correspond to any of the locales active
+during their execution, but an unpredictable mix thereof.
+
+We do not mark these functions as MT- or AS-Unsafe, however, because
+functions that modify the locale object are marked with
+@code{const:locale} and regarded as unsafe.  Being unsafe, the latter
+are not to be called when multiple threads are running or asynchronous
+signals are enabled, and so the locale can be considered effectively
+constant in these contexts, which makes the former safe.
+
+@c Should the locking strategy suggested under @code{const} be used,
+@c failure to guard locale uses is not as fatal as data races in
+@c general: unguarded uses will @emph{not} follow dangling pointers or
+@c access uninitialized, unmapped or recycled memory.  Each access will
+@c read from a consistent locale object that is or was active at some
+@c point during its execution.  Without synchronization, however, it
+@c cannot even be assumed that, after a change in locale, earlier
+@c locales will no longer be used, even after the newly-chosen one is
+@c used in the thread.  Nevertheless, even though unguarded reads from
+@c the locale will not violate type safety, functions that access the
+@c locale multiple times may invoke all sorts of undefined behavior
+@c because of the unexpected locale changes.
+
+
+@item @code{env}
+@cindex env
+
+Functions marked with @code{env} as an MT-Safety issue access the
+environment with @code{getenv} or similar, without any guards to ensure
+safety in the presence of concurrent modifications.
+
+We do not mark these functions as MT- or AS-Unsafe, however, because
+functions that modify the environment are all marked with
+@code{const:env} and regarded as unsafe.  Being unsafe, the latter are
+not to be called when multiple threads are running or asynchronous
+signals are enabled, and so the environment can be considered
+effectively constant in these contexts, which makes the former safe.
+
+
+@item @code{hostid}
+@cindex hostid
+
+The function marked with @code{hostid} as an MT-Safety issue reads from
+the system-wide data structures that hold the ``host ID'' of the
+machine.  These data structures cannot generally be modified atomically.
+Since it is expected that the ``host ID'' will not normally change, the
+function that reads from it (@code{gethostid}) is regarded as safe,
+whereas the function that modifies it (@code{sethostid}) is marked with
+@code{@mtasuconst{:@mtshostid{}}}, indicating it may require special
+care if it is to be called.  In this specific case, the special care
+amounts to system-wide (not merely intra-process) coordination.
+
+
+@item @code{sigintr}
+@cindex sigintr
+
+Functions marked with @code{sigintr} as an MT-Safety issue access the
+@code{_sigintr} internal data structure without any guards to ensure
+safety in the presence of concurrent modifications.
+
+We do not mark these functions as MT- or AS-Unsafe, however, because
+functions that modify the this data structure are all marked with
+@code{const:sigintr} and regarded as unsafe.  Being unsafe, the latter
+are not to be called when multiple threads are running or asynchronous
+signals are enabled, and so the data structure can be considered
+effectively constant in these contexts, which makes the former safe.
+
+
+@item @code{fd}
+@cindex fd
+
+Functions annotated with @code{fd} as an AC-Safety issue may leak file
+descriptors if asynchronous thread cancellation interrupts their
+execution.
+
+Functions that allocate or deallocate file descriptors will generally be
+marked as such.  Even if they attempted to protect the file descriptor
+allocation and deallocation with cleanup regions, allocating a new
+descriptor and storing its number where the cleanup region could release
+it cannot be performed as a single atomic operation.  Similarly,
+releasing the descriptor and taking it out of the data structure
+normally responsible for releasing it cannot be performed atomically.
+There will always be a window in which the descriptor cannot be released
+because it was not stored in the cleanup handler argument yet, or it was
+already taken out before releasing it.  It cannot be taken out after
+release: an open descriptor could mean either that the descriptor still
+has to be closed, or that it already did so but the descriptor was
+reallocated by another thread or signal handler.
+
+Such leaks could be internally avoided, with some performance penalty,
+by temporarily disabling asynchronous thread cancellation.  However,
+since callers of allocation or deallocation functions would have to do
+this themselves, to avoid the same sort of leak in their own layer, it
+makes more sense for the library to assume they are taking care of it
+than to impose a performance penalty that is redundant when the problem
+is solved in upper layers, and insufficient when it is not.
+
+This remark by itself does not cause a function to be regarded as
+AC-Unsafe.  However, cumulative effects of such leaks may pose a
+problem for some programs.  If this is the case, suspending asynchronous
+cancellation for the duration of calls to such functions is recommended.
+
+
+@item @code{mem}
+@cindex mem
+
+Functions annotated with @code{mem} as an AC-Safety issue may leak
+memory if asynchronous thread cancellation interrupts their execution.
+
+The problem is similar to that of file descriptors: there is no atomic
+interface to allocate memory and store its address in the argument to a
+cleanup handler, or to release it and remove its address from that
+argument, without at least temporarily disabling asynchronous
+cancellation, which these functions do not do.
+
+This remark does not by itself cause a function to be regarded as
+generally AC-Unsafe.  However, cumulative effects of such leaks may be
+severe enough for some programs that disabling asynchronous cancellation
+for the duration of calls to such functions may be required.
+
+
+@item @code{cwd}
+@cindex cwd
+
+Functions marked with @code{cwd} as an MT-Safety issue may temporarily
+change the current working directory during their execution, which may
+cause relative pathnames to be resolved in unexpected ways in other
+threads or within asynchronous signal or cancellation handlers.
+
+This is not enough of a reason to mark so-marked functions as MT- or
+AS-Unsafe, but when this behavior is optional (e.g., @code{nftw} with
+@code{FTW_CHDIR}), avoiding the option may be a good alternative to
+using full pathnames or file descriptor-relative (e.g. @code{openat})
+system calls.
+
+
+@item @code{!posix}
+@cindex !posix
+
+This remark, as an MT-, AS- or AC-Safety note to a function, indicates
+the safety status of the function is known to differ from the specified
+status in the POSIX standard.  For example, POSIX does not require a
+function to be Safe, but our implementation is, or vice-versa.
+
+For the time being, the absence of this remark does not imply the safety
+properties we documented are identical to those mandated by POSIX for
+the corresponding functions.
+
+
+@item @code{:identifier}
+@cindex :identifier
+
+Annotations may sometimes be followed by identifiers, intended to group
+several functions that e.g. access the data structures in an unsafe way,
+as in @code{race} and @code{const}, or to provide more specific
+information, such as naming a signal in a function marked with
+@code{sig}.  It is envisioned that it may be applied to @code{lock} and
+@code{corrupt} as well in the future.
+
+In most cases, the identifier will name a set of functions, but it may
+name global objects or function arguments, or identifiable properties or
+logical components associated with them, with a notation such as
+e.g. @code{:buf(arg)} to denote a buffer associated with the argument
+@var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a
+file descriptor @var{fd}.
+
+The most common use for identifiers is to provide logical groups of
+functions and arguments that need to be protected by the same
+synchronization primitive in order to ensure safe operation in a given
+context.
+
+
+@item @code{/condition}
+@cindex /condition
+
+Some safety annotations may be conditional, in that they only apply if a
+boolean expression involving arguments, global variables or even the
+underlying kernel evaluates evaluates to true.  Such conditions as
+@code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only
+applies when the underlying kernel is the HURD, or when it is neither
+Linux nor a BSD kernel, respectively.  @code{/!ps} and
+@code{/one_per_line} indicate the preceding marker only applies when
+argument @var{ps} is NULL, or global variable @var{one_per_line} is
+nonzero.
+
+When all marks that render a function unsafe are adorned with such
+conditions, and none of the named conditions hold, then the function can
+be regarded as safe.
+
+
+@end itemize
+
+
+@node Berkeley Unix, SVID, POSIX, Standards and Portability
+@subsection Berkeley Unix
+@cindex BSD Unix
+@cindex 4.@var{n} BSD Unix
+@cindex Berkeley Unix
+@cindex SunOS
+@cindex Unix, Berkeley
+
+@Theglibc{} defines facilities from some versions of Unix which
+are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
+and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from
+@dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System
+V functionality).  These systems support most of the @w{ISO C} and POSIX
+facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.
+
+The BSD facilities include symbolic links (@pxref{Symbolic Links}), the
+@code{select} function (@pxref{Waiting for I/O}), the BSD signal
+functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}).
+
+@node SVID, XPG, Berkeley Unix, Standards and Portability
+@subsection SVID (The System V Interface Description)
+@cindex SVID
+@cindex System V Unix
+@cindex Unix, System V
+
+The @dfn{System V Interface Description} (SVID) is a document describing
+the AT&T Unix System V operating system.  It is to some extent a
+superset of the POSIX standard (@pxref{POSIX}).
+
+@Theglibc{} defines most of the facilities required by the SVID
+that are not also required by the @w{ISO C} or POSIX standards, for
+compatibility with  System V Unix and other Unix systems (such as
+SunOS) which include these facilities.  However, many of the more
+obscure and less generally useful facilities required by the SVID are
+not included.  (In fact, Unix System V itself does not provide them all.)
+
+The supported facilities from System V include the methods for
+inter-process communication and shared memory, the @code{hsearch} and
+@code{drand48} families of functions, @code{fmtmsg} and several of the
+mathematical functions.
+
+@node XPG, , SVID, Standards and Portability
+@subsection XPG (The X/Open Portability Guide)
+
+The X/Open Portability Guide, published by the X/Open Company, Ltd., is
+a more general standard than POSIX.  X/Open owns the Unix copyright and
+the XPG specifies the requirements for systems which are intended to be
+a Unix system.
+
+@Theglibc{} complies to the X/Open Portability Guide, Issue 4.2,
+with all extensions common to XSI (X/Open System Interface)
+compliant systems and also all X/Open UNIX extensions.
+
+The additions on top of POSIX are mainly derived from functionality
+available in @w{System V} and BSD systems.  Some of the really bad
+mistakes in @w{System V} systems were corrected, though.  Since
+fulfilling the XPG standard with the Unix extensions is a
+precondition for getting the Unix brand chances are good that the
+functionality is available on commercial systems.
+
+
+@node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
+@section Using the Library
+
+This section describes some of the practical issues involved in using
+@theglibc{}.
+
+@menu
+* 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.
+@end menu
+
+@node Header Files, Macro Definitions,  , Using the Library
+@subsection Header Files
+@cindex header files
+
+Libraries for use by C programs really consist of two parts: @dfn{header
+files} that define types and macros and declare variables and
+functions; and the actual library or @dfn{archive} that contains the
+definitions of the variables and functions.
+
+(Recall that in C, a @dfn{declaration} merely provides information that
+a function or variable exists and gives its type.  For a function
+declaration, information about the types of its arguments might be
+provided as well.  The purpose of declarations is to allow the compiler
+to correctly process references to the declared variables and functions.
+A @dfn{definition}, on the other hand, actually allocates storage for a
+variable or says what a function does.)
+@cindex definition (compared to declaration)
+@cindex declaration (compared to definition)
+
+In order to use the facilities in @theglibc{}, you should be sure
+that your program source files include the appropriate header files.
+This is so that the compiler has declarations of these facilities
+available and can correctly process references to them.  Once your
+program has been compiled, the linker resolves these references to
+the actual definitions provided in the archive file.
+
+Header files are included into a program source file by the
+@samp{#include} preprocessor directive.  The C language supports two
+forms of this directive; the first,
+
+@smallexample
+#include "@var{header}"
+@end smallexample
+
+@noindent
+is typically used to include a header file @var{header} that you write
+yourself; this would contain definitions and declarations describing the
+interfaces between the different parts of your particular application.
+By contrast,
+
+@smallexample
+#include <file.h>
+@end smallexample
+
+@noindent
+is typically used to include a header file @file{file.h} that contains
+definitions and declarations for a standard library.  This file would
+normally be installed in a standard place by your system administrator.
+You should use this second form for the C library header files.
+
+Typically, @samp{#include} directives are placed at the top of the C
+source file, before any other code.  If you begin your source files with
+some comments explaining what the code in the file does (a good idea),
+put the @samp{#include} directives immediately afterwards, following the
+feature test macro definition (@pxref{Feature Test Macros}).
+
+For more information about the use of header files and @samp{#include}
+directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor
+Manual}.@refill
+
+@Theglibc{} provides several header files, each of which contains
+the type and macro definitions and variable and function declarations
+for a group of related facilities.  This means that your programs may
+need to include several header files, depending on exactly which
+facilities you are using.
+
+Some library header files include other library header files
+automatically.  However, as a matter of programming style, you should
+not rely on this; it is better to explicitly include all the header
+files required for the library facilities you are using.  The @glibcadj{}
+header files have been written in such a way that it doesn't
+matter if a header file is accidentally included more than once;
+including a header file a second time has no effect.  Likewise, if your
+program needs to include multiple header files, the order in which they
+are included doesn't matter.
+
+@strong{Compatibility Note:} Inclusion of standard header files in any
+order and any number of times works in any @w{ISO C} implementation.
+However, this has traditionally not been the case in many older C
+implementations.
+
+Strictly speaking, you don't @emph{have to} include a header file to use
+a function it declares; you could declare the function explicitly
+yourself, according to the specifications in this manual.  But it is
+usually better to include the header file because it may define types
+and macros that are not otherwise available and because it may define
+more efficient macro replacements for some functions.  It is also a sure
+way to have the correct declaration.
+
+@node Macro Definitions, Reserved Names, Header Files, Using the Library
+@subsection Macro Definitions of Functions
+@cindex shadowing functions with macros
+@cindex removing macros that shadow functions
+@cindex undefining macros that shadow functions
+
+If we describe something as a function in this manual, it may have a
+macro definition as well.  This normally has no effect on how your
+program runs---the macro definition does the same thing as the function
+would.  In particular, macro equivalents for library functions evaluate
+arguments exactly once, in the same way that a function call would.  The
+main reason for these macro definitions is that sometimes they can
+produce an inline expansion that is considerably faster than an actual
+function call.
+
+Taking the address of a library function works even if it is also
+defined as a macro.  This is because, in this context, the name of the
+function isn't followed by the left parenthesis that is syntactically
+necessary to recognize a macro call.
+
+You might occasionally want to avoid using the macro definition of a
+function---perhaps to make your program easier to debug.  There are
+two ways you can do this:
+
+@itemize @bullet
+@item
+You can avoid a macro definition in a specific use by enclosing the name
+of the function in parentheses.  This works because the name of the
+function doesn't appear in a syntactic context where it is recognizable
+as a macro call.
+
+@item
+You can suppress any macro definition for a whole source file by using
+the @samp{#undef} preprocessor directive, unless otherwise stated
+explicitly in the description of that facility.
+@end itemize
+
+For example, suppose the header file @file{stdlib.h} declares a function
+named @code{abs} with
+
+@smallexample
+extern int abs (int);
+@end smallexample
+
+@noindent
+and also provides a macro definition for @code{abs}.  Then, in:
+
+@smallexample
+#include <stdlib.h>
+int f (int *i) @{ return abs (++*i); @}
+@end smallexample
+
+@noindent
+the reference to @code{abs} might refer to either a macro or a function.
+On the other hand, in each of the following examples the reference is
+to a function and not a macro.
+
+@smallexample
+#include <stdlib.h>
+int g (int *i) @{ return (abs) (++*i); @}
+
+#undef abs
+int h (int *i) @{ return abs (++*i); @}
+@end smallexample
+
+Since macro definitions that double for a function behave in
+exactly the same way as the actual function version, there is usually no
+need for any of these methods.  In fact, removing macro definitions usually
+just makes your program slower.
+
+
+@node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library
+@subsection Reserved Names
+@cindex reserved names
+@cindex name space
+
+The names of all library types, macros, variables and functions that
+come from the @w{ISO C} standard are reserved unconditionally; your program
+@strong{may not} redefine these names.  All other library names are
+reserved if your program explicitly includes the header file that
+defines or declares them.  There are several reasons for these
+restrictions:
+
+@itemize @bullet
+@item
+Other people reading your code could get very confused if you were using
+a function named @code{exit} to do something completely different from
+what the standard @code{exit} function does, for example.  Preventing
+this situation helps to make your programs easier to understand and
+contributes to modularity and maintainability.
+
+@item
+It avoids the possibility of a user accidentally redefining a library
+function that is called by other library functions.  If redefinition
+were allowed, those other functions would not work properly.
+
+@item
+It allows the compiler to do whatever special optimizations it pleases
+on calls to these functions, without the possibility that they may have
+been redefined by the user.  Some library facilities, such as those for
+dealing with variadic arguments (@pxref{Variadic Functions})
+and non-local exits (@pxref{Non-Local Exits}), actually require a
+considerable amount of cooperation on the part of the C compiler, and
+with respect to the implementation, it might be easier for the compiler
+to treat these as built-in parts of the language.
+@end itemize
+
+In addition to the names documented in this manual, reserved names
+include all external identifiers (global functions and variables) that
+begin with an underscore (@samp{_}) and all identifiers regardless of
+use that begin with either two underscores or an underscore followed by
+a capital letter are reserved names.  This is so that the library and
+header files can define functions, variables, and macros for internal
+purposes without risk of conflict with names in user programs.
+
+Some additional classes of identifier names are reserved for future
+extensions to the C language or the POSIX.1 environment.  While using these
+names for your own purposes right now might not cause a problem, they do
+raise the possibility of conflict with future versions of the C
+or POSIX standards, so you should avoid these names.
+
+@itemize @bullet
+@item
+Names beginning with a capital @samp{E} followed a digit or uppercase
+letter may be used for additional error code names.  @xref{Error
+Reporting}.
+
+@item
+Names that begin with either @samp{is} or @samp{to} followed by a
+lowercase letter may be used for additional character testing and
+conversion functions.  @xref{Character Handling}.
+
+@item
+Names that begin with @samp{LC_} followed by an uppercase letter may be
+used for additional macros specifying locale attributes.
+@xref{Locales}.
+
+@item
+Names of all existing mathematics functions (@pxref{Mathematics})
+suffixed with @samp{f} or @samp{l} are reserved for corresponding
+functions that operate on @code{float} and @code{long double} arguments,
+respectively.
+
+@item
+Names that begin with @samp{SIG} followed by an uppercase letter are
+reserved for additional signal names.  @xref{Standard Signals}.
+
+@item
+Names that begin with @samp{SIG_} followed by an uppercase letter are
+reserved for additional signal actions.  @xref{Basic Signal Handling}.
+
+@item
+Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a
+lowercase letter are reserved for additional string and array functions.
+@xref{String and Array Utilities}.
+
+@item
+Names that end with @samp{_t} are reserved for additional type names.
+@end itemize
+
+In addition, some individual header files reserve names beyond
+those that they actually define.  You only need to worry about these
+restrictions if your program includes that particular header file.
+
+@itemize @bullet
+@item
+The header file @file{dirent.h} reserves names prefixed with
+@samp{d_}.
+@pindex dirent.h
+
+@item
+The header file @file{fcntl.h} reserves names prefixed with
+@samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}.
+@pindex fcntl.h
+
+@item
+The header file @file{grp.h} reserves names prefixed with @samp{gr_}.
+@pindex grp.h
+
+@item
+The header file @file{limits.h} reserves names suffixed with @samp{_MAX}.
+@pindex limits.h
+
+@item
+The header file @file{pwd.h} reserves names prefixed with @samp{pw_}.
+@pindex pwd.h
+
+@item
+The header file @file{signal.h} reserves names prefixed with @samp{sa_}
+and @samp{SA_}.
+@pindex signal.h
+
+@item
+The header file @file{sys/stat.h} reserves names prefixed with @samp{st_}
+and @samp{S_}.
+@pindex sys/stat.h
+
+@item
+The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}.
+@pindex sys/times.h
+
+@item
+The header file @file{termios.h} reserves names prefixed with @samp{c_},
+@samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with
+@samp{B} followed by a digit.
+@pindex termios.h
+@end itemize
+
+@comment Include the section on Creature Nest Macros.
+@include creature.texi
+
+@node Roadmap to the Manual,  , Using the Library, Introduction
+@section Roadmap to the Manual
+
+Here is an overview of the contents of the remaining chapters of
+this manual.
+
+@c The chapter overview ordering is:
+@c Error Reporting (2)
+@c Virtual Memory Allocation and Paging (3)
+@c Character Handling (4)
+@c Strings and Array Utilities (5)
+@c Character Set Handling (6)
+@c Locales and Internationalization (7)
+@c Searching and Sorting (9)
+@c Pattern Matching (10)
+@c Input/Output Overview (11)
+@c Input/Output on Streams (12)
+@c Low-level Input/Ooutput (13)
+@c File System Interface (14)
+@c Pipes and FIFOs (15)
+@c Sockets (16)
+@c Low-Level Terminal Interface (17)
+@c Syslog (18)
+@c Mathematics (19)
+@c Aritmetic Functions (20)
+@c Date and Time (21)
+@c Non-Local Exist (23)
+@c Signal Handling (24)
+@c The Basic Program/System Interface (25)
+@c Processes (26)
+@c Job Control (28)
+@c System Databases and Name Service Switch (29)
+@c Users and Groups (30) -- References `User Database' and `Group Database'
+@c System Management (31)
+@c System Configuration Parameters (32)
+@c C Language Facilities in the Library (AA)
+@c Summary of Library Facilities (AB)
+@c Installing (AC)
+@c Library Maintenance (AD)
+
+@c The following chapters need overview text to be added:
+@c Message Translation (8)
+@c Resource Usage And Limitations (22)
+@c Inter-Process Communication (27)
+@c DES Encryption and Password Handling (33)
+@c Debugging support (34)
+@c POSIX Threads (35)
+@c Internal Probes (36)
+@c Platform-specific facilities (AE)
+@c Contributors to (AF)
+@c Free Software Needs Free Documentation (AG)
+@c GNU Lesser General Public License (AH)
+@c GNU Free Documentation License (AI)
+
+@itemize @bullet
+@item
+@ref{Error Reporting}, describes how errors detected by the library
+are reported.
+
+
+@item
+@ref{Memory}, describes @theglibc{}'s facilities for managing and
+using virtual and real memory, including dynamic allocation of virtual
+memory.  If you do not know in advance how much memory your program
+needs, you can allocate it dynamically instead, and manipulate it via
+pointers.
+
+@item
+@ref{Character Handling}, contains information about character
+classification functions (such as @code{isspace}) and functions for
+performing case conversion.
+
+@item
+@ref{String and Array Utilities}, has descriptions of functions for
+manipulating strings (null-terminated character arrays) and general
+byte arrays, including operations such as copying and comparison.
+
+@item
+@ref{Character Set Handling}, contains information about manipulating
+characters and strings using character sets larger than will fit in
+the usual @code{char} data type.
+
+@item
+@ref{Locales}, describes how selecting a particular country
+or language affects the behavior of the library.  For example, the locale
+affects collation sequences for strings and how monetary values are
+formatted.
+
+@item
+@ref{Searching and Sorting}, contains information about functions
+for searching and sorting arrays.  You can use these functions on any
+kind of array by providing an appropriate comparison function.
+
+@item
+@ref{Pattern Matching}, presents functions for matching regular expressions
+and shell file name patterns, and for expanding words as the shell does.
+
+@item
+@ref{I/O Overview}, gives an overall look at the input and output
+facilities in the library, and contains information about basic concepts
+such as file names.
+
+@item
+@ref{I/O on Streams}, describes I/O operations involving streams (or
+@w{@code{FILE *}} objects).  These are the normal C library functions
+from @file{stdio.h}.
+
+@item
+@ref{Low-Level I/O}, contains information about I/O operations
+on file descriptors.  File descriptors are a lower-level mechanism
+specific to the Unix family of operating systems.
+
+@item
+@ref{File System Interface}, has descriptions of operations on entire
+files, such as functions for deleting and renaming them and for creating
+new directories.  This chapter also contains information about how you
+can access the attributes of a file, such as its owner and file protection
+modes.
+
+@item
+@ref{Pipes and FIFOs}, contains information about simple interprocess
+communication mechanisms.  Pipes allow communication between two related
+processes (such as between a parent and child), while FIFOs allow
+communication between processes sharing a common file system on the same
+machine.
+
+@item
+@ref{Sockets}, describes a more complicated interprocess communication
+mechanism that allows processes running on different machines to
+communicate over a network.  This chapter also contains information about
+Internet host addressing and how to use the system network databases.
+
+@item
+@ref{Low-Level Terminal Interface}, describes how you can change the
+attributes of a terminal device.  If you want to disable echo of
+characters typed by the user, for example, read this chapter.
+
+@item
+@ref{Mathematics}, contains information about the math library
+functions.  These include things like random-number generators and
+remainder functions on integers as well as the usual trigonometric and
+exponential functions on floating-point numbers.
+
+@item
+@ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions
+for simple arithmetic, analysis of floating-point values, and reading
+numbers from strings.
+
+@item
+@ref{Date and Time}, describes functions for measuring both calendar time
+and CPU time, as well as functions for setting alarms and timers.
+
+@item
+@ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and
+@code{longjmp} functions.  These functions provide a facility for
+@code{goto}-like jumps which can jump from one function to another.
+
+@item
+@ref{Signal Handling}, tells you all about signals---what they are,
+how to establish a handler that is called when a particular kind of
+signal is delivered, and how to prevent signals from arriving during
+critical sections of your program.
+
+@item
+@ref{Program Basics}, tells how your programs can access their
+command-line arguments and environment variables.
+
+@item
+@ref{Processes}, contains information about how to start new processes
+and run programs.
+
+@item
+@ref{Job Control}, describes functions for manipulating process groups
+and the controlling terminal.  This material is probably only of
+interest if you are writing a shell or other program which handles job
+control specially.
+
+@item
+@ref{Name Service Switch}, describes the services which are available
+for looking up names in the system databases, how to determine which
+service is used for which database, and how these services are
+implemented so that contributors can design their own services.
+
+@item
+@ref{User Database}, and @ref{Group Database}, tell you how to access
+the system user and group databases.
+
+@item
+@ref{System Management}, describes functions for controlling and getting
+information about the hardware and software configuration your program
+is executing under.
+
+@item
+@ref{System Configuration}, tells you how you can get information about
+various operating system limits.  Most of these parameters are provided for
+compatibility with POSIX.
+
+@item
+@ref{Language Features}, contains information about library support for
+standard parts of the C language, including things like the @code{sizeof}
+operator and the symbolic constant @code{NULL}, how to write functions
+accepting variable numbers of arguments, and constants describing the
+ranges and other properties of the numerical types.  There is also a simple
+debugging mechanism which allows you to put assertions in your code, and
+have diagnostic messages printed if the tests fail.
+
+@item
+@ref{Library Summary}, gives a summary of all the functions, variables, and
+macros in the library, with complete data types and function prototypes,
+and says what standard or system each is derived from.
+
+@item
+@ref{Installation}, explains how to build and install @theglibc{} on
+your system, and how to report any bugs you might find.
+
+@item
+@ref{Maintenance}, explains how to add new functions or port the
+library to a new system.
+@end itemize
+
+If you already know the name of the facility you are interested in, you
+can look it up in @ref{Library Summary}.  This gives you a summary of
+its syntax and a pointer to where you can find a more detailed
+description.  This appendix is particularly useful if you just want to
+verify the order and type of arguments to a function, for example.  It
+also tells you what standard or system each function, variable, or macro
+is derived from.
diff --git a/ap/libc/glibc/glibc-2.23/manual/io.texi b/ap/libc/glibc/glibc-2.23/manual/io.texi
new file mode 100644
index 0000000..bd82f76
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/io.texi
@@ -0,0 +1,395 @@
+@node I/O Overview, I/O on Streams, Pattern Matching, Top
+@c %MENU% Introduction to the I/O facilities
+@chapter Input/Output Overview
+
+Most programs need to do either input (reading data) or output (writing
+data), or most frequently both, in order to do anything useful.  @Theglibc{}
+provides such a large selection of input and output functions
+that the hardest part is often deciding which function is most
+appropriate!
+
+This chapter introduces concepts and terminology relating to input
+and output.  Other chapters relating to the GNU I/O facilities are:
+
+@itemize @bullet
+@item
+@ref{I/O on Streams}, which covers the high-level functions
+that operate on streams, including formatted input and output.
+
+@item
+@ref{Low-Level I/O}, which covers the basic I/O and control
+functions on file descriptors.
+
+@item
+@ref{File System Interface}, which covers functions for operating on
+directories and for manipulating file attributes such as access modes
+and ownership.
+
+@item
+@ref{Pipes and FIFOs}, which includes information on the basic interprocess
+communication facilities.
+
+@item
+@ref{Sockets}, which covers a more complicated interprocess communication
+facility with support for networking.
+
+@item
+@ref{Low-Level Terminal Interface}, which covers functions for changing
+how input and output to terminals or other serial devices are processed.
+@end itemize
+
+
+@menu
+* I/O Concepts::       Some basic information and terminology.
+* File Names::         How to refer to a file.
+@end menu
+
+@node I/O Concepts, File Names,  , I/O Overview
+@section Input/Output Concepts
+
+Before you can read or write the contents of a file, you must establish
+a connection or communications channel to the file.  This process is
+called @dfn{opening} the file.  You can open a file for reading, writing,
+or both.
+@cindex opening a file
+
+The connection to an open file is represented either as a stream or as a
+file descriptor.  You pass this as an argument to the functions that do
+the actual read or write operations, to tell them which file to operate
+on.  Certain functions expect streams, and others are designed to
+operate on file descriptors.
+
+When you have finished reading to or writing from the file, you can
+terminate the connection by @dfn{closing} the file.  Once you have
+closed a stream or file descriptor, you cannot do any more input or
+output operations on it.
+
+@menu
+* Streams and File Descriptors::    The GNU C Library provides two ways
+			             to access the contents of files.
+* File Position::                   The number of bytes from the
+                                     beginning of the file.
+@end menu
+
+@node Streams and File Descriptors, File Position,  , I/O Concepts
+@subsection Streams and File Descriptors
+
+When you want to do input or output to a file, you have a choice of two
+basic mechanisms for representing the connection between your program
+and the file: file descriptors and streams.  File descriptors are
+represented as objects of type @code{int}, while streams are represented
+as @code{FILE *} objects.
+
+File descriptors provide a primitive, low-level interface to input and
+output operations.  Both file descriptors and streams can represent a
+connection to a device (such as a terminal), or a pipe or socket for
+communicating with another process, as well as a normal file.  But, if
+you want to do control operations that are specific to a particular kind
+of device, you must use a file descriptor; there are no facilities to
+use streams in this way.  You must also use file descriptors if your
+program needs to do input or output in special modes, such as
+nonblocking (or polled) input (@pxref{File Status Flags}).
+
+Streams provide a higher-level interface, layered on top of the
+primitive file descriptor facilities.  The stream interface treats all
+kinds of files pretty much alike---the sole exception being the three
+styles of buffering that you can choose (@pxref{Stream Buffering}).
+
+The main advantage of using the stream interface is that the set of
+functions for performing actual input and output operations (as opposed
+to control operations) on streams is much richer and more powerful than
+the corresponding facilities for file descriptors.  The file descriptor
+interface provides only simple functions for transferring blocks of
+characters, but the stream interface also provides powerful formatted
+input and output functions (@code{printf} and @code{scanf}) as well as
+functions for character- and line-oriented input and output.
+@c !!! glibc has dprintf, which lets you do printf on an fd.
+
+Since streams are implemented in terms of file descriptors, you can
+extract the file descriptor from a stream and perform low-level
+operations directly on the file descriptor.  You can also initially open
+a connection as a file descriptor and then make a stream associated with
+that file descriptor.
+
+In general, you should stick with using streams rather than file
+descriptors, unless there is some specific operation you want to do that
+can only be done on a file descriptor.  If you are a beginning
+programmer and aren't sure what functions to use, we suggest that you
+concentrate on the formatted input functions (@pxref{Formatted Input})
+and formatted output functions (@pxref{Formatted Output}).
+
+If you are concerned about portability of your programs to systems other
+than GNU, you should also be aware that file descriptors are not as
+portable as streams.  You can expect any system running @w{ISO C} to
+support streams, but @nongnusystems{} may not support file descriptors at
+all, or may only implement a subset of the GNU functions that operate on
+file descriptors.  Most of the file descriptor functions in @theglibc{}
+are included in the POSIX.1 standard, however.
+
+@node File Position,  , Streams and File Descriptors, I/O Concepts
+@subsection File Position
+
+One of the attributes of an open file is its @dfn{file position} that
+keeps track of where in the file the next character is to be read or
+written.  On @gnusystems{}, and all POSIX.1 systems, the file position
+is simply an integer representing the number of bytes from the beginning
+of the file.
+
+The file position is normally set to the beginning of the file when it
+is opened, and each time a character is read or written, the file
+position is incremented.  In other words, access to the file is normally
+@dfn{sequential}.
+@cindex file position
+@cindex sequential-access files
+
+Ordinary files permit read or write operations at any position within
+the file.  Some other kinds of files may also permit this.  Files which
+do permit this are sometimes referred to as @dfn{random-access} files.
+You can change the file position using the @code{fseek} function on a
+stream (@pxref{File Positioning}) or the @code{lseek} function on a file
+descriptor (@pxref{I/O Primitives}).  If you try to change the file
+position on a file that doesn't support random access, you get the
+@code{ESPIPE} error.
+@cindex random-access files
+
+Streams and descriptors that are opened for @dfn{append access} are
+treated specially for output: output to such files is @emph{always}
+appended sequentially to the @emph{end} of the file, regardless of the
+file position.  However, the file position is still used to control where in
+the file reading is done.
+@cindex append-access files
+
+If you think about it, you'll realize that several programs can read a
+given file at the same time.  In order for each program to be able to
+read the file at its own pace, each program must have its own file
+pointer, which is not affected by anything the other programs do.
+
+In fact, each opening of a file creates a separate file position.
+Thus, if you open a file twice even in the same program, you get two
+streams or descriptors with independent file positions.
+
+By contrast, if you open a descriptor and then duplicate it to get
+another descriptor, these two descriptors share the same file position:
+changing the file position of one descriptor will affect the other.
+
+@node File Names,  , I/O Concepts, I/O Overview
+@section File Names
+
+In order to open a connection to a file, or to perform other operations
+such as deleting a file, you need some way to refer to the file.  Nearly
+all files have names that are strings---even files which are actually
+devices such as tape drives or terminals.  These strings are called
+@dfn{file names}.  You specify the file name to say which file you want
+to open or operate on.
+
+This section describes the conventions for file names and how the
+operating system works with them.
+@cindex file name
+
+@menu
+* 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.
+@end menu
+
+
+@node Directories, File Name Resolution,  , File Names
+@subsection Directories
+
+In order to understand the syntax of file names, you need to understand
+how the file system is organized into a hierarchy of directories.
+
+@cindex directory
+@cindex link
+@cindex directory entry
+A @dfn{directory} is a file that contains information to associate other
+files with names; these associations are called @dfn{links} or
+@dfn{directory entries}.  Sometimes, people speak of ``files in a
+directory'', but in reality, a directory only contains pointers to
+files, not the files themselves.
+
+@cindex file name component
+The name of a file contained in a directory entry is called a @dfn{file
+name component}.  In general, a file name consists of a sequence of one
+or more such components, separated by the slash character (@samp{/}).  A
+file name which is just one component names a file with respect to its
+directory.  A file name with multiple components names a directory, and
+then a file in that directory, and so on.
+
+Some other documents, such as the POSIX standard, use the term
+@dfn{pathname} for what we call a file name, and either @dfn{filename}
+or @dfn{pathname component} for what this manual calls a file name
+component.  We don't use this terminology because a ``path'' is
+something completely different (a list of directories to search), and we
+think that ``pathname'' used for something else will confuse users.  We
+always use ``file name'' and ``file name component'' (or sometimes just
+``component'', where the context is obvious) in GNU documentation.  Some
+macros use the POSIX terminology in their names, such as
+@code{PATH_MAX}.  These macros are defined by the POSIX standard, so we
+cannot change their names.
+
+You can find more detailed information about operations on directories
+in @ref{File System Interface}.
+
+@node File Name Resolution, File Name Errors, Directories, File Names
+@subsection File Name Resolution
+
+A file name consists of file name components separated by slash
+(@samp{/}) characters.  On the systems that @theglibc{} supports,
+multiple successive @samp{/} characters are equivalent to a single
+@samp{/} character.
+
+@cindex file name resolution
+The process of determining what file a file name refers to is called
+@dfn{file name resolution}.  This is performed by examining the
+components that make up a file name in left-to-right order, and locating
+each successive component in the directory named by the previous
+component.  Of course, each of the files that are referenced as
+directories must actually exist, be directories instead of regular
+files, and have the appropriate permissions to be accessible by the
+process; otherwise the file name resolution fails.
+
+@cindex root directory
+@cindex absolute file name
+If a file name begins with a @samp{/}, the first component in the file
+name is located in the @dfn{root directory} of the process (usually all
+processes on the system have the same root directory).  Such a file name
+is called an @dfn{absolute file name}.
+@c !!! xref here to chroot, if we ever document chroot. -rm
+
+@cindex relative file name
+Otherwise, the first component in the file name is located in the
+current working directory (@pxref{Working Directory}).  This kind of
+file name is called a @dfn{relative file name}.
+
+@cindex parent directory
+The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')
+have special meanings.  Every directory has entries for these file name
+components.  The file name component @file{.} refers to the directory
+itself, while the file name component @file{..} refers to its
+@dfn{parent directory} (the directory that contains the link for the
+directory in question).  As a special case, @file{..} in the root
+directory refers to the root directory itself, since it has no parent;
+thus @file{/..} is the same as @file{/}.
+
+Here are some examples of file names:
+
+@table @file
+@item /a
+The file named @file{a}, in the root directory.
+
+@item /a/b
+The file named @file{b}, in the directory named @file{a} in the root directory.
+
+@item a
+The file named @file{a}, in the current working directory.
+
+@item /a/./b
+This is the same as @file{/a/b}.
+
+@item ./a
+The file named @file{a}, in the current working directory.
+
+@item ../a
+The file named @file{a}, in the parent directory of the current working
+directory.
+@end table
+
+@c An empty string may ``work'', but I think it's confusing to
+@c try to describe it.  It's not a useful thing for users to use--rms.
+A file name that names a directory may optionally end in a @samp{/}.
+You can specify a file name of @file{/} to refer to the root directory,
+but the empty string is not a meaningful file name.  If you want to
+refer to the current working directory, use a file name of @file{.} or
+@file{./}.
+
+Unlike some other operating systems, @gnusystems{} don't have any
+built-in support for file types (or extensions) or file versions as part
+of its file name syntax.  Many programs and utilities use conventions
+for file names---for example, files containing C source code usually
+have names suffixed with @samp{.c}---but there is nothing in the file
+system itself that enforces this kind of convention.
+
+@node File Name Errors, File Name Portability, File Name Resolution, File Names
+@subsection File Name Errors
+
+@cindex file name errors
+@cindex usual file name errors
+
+Functions that accept file name arguments usually detect these
+@code{errno} error conditions relating to the file name syntax or
+trouble finding the named file.  These errors are referred to throughout
+this manual as the @dfn{usual file name errors}.
+
+@table @code
+@item EACCES
+The process does not have search permission for a directory component
+of the file name.
+
+@item ENAMETOOLONG
+This error is used when either the total length of a file name is
+greater than @code{PATH_MAX}, or when an individual file name component
+has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.
+
+On @gnuhurdsystems{}, there is no imposed limit on overall file name
+length, but some file systems may place limits on the length of a
+component.
+
+@item ENOENT
+This error is reported when a file referenced as a directory component
+in the file name doesn't exist, or when a component is a symbolic link
+whose target file does not exist.  @xref{Symbolic Links}.
+
+@item ENOTDIR
+A file that is referenced as a directory component in the file name
+exists, but it isn't a directory.
+
+@item ELOOP
+Too many symbolic links were resolved while trying to look up the file
+name.  The system has an arbitrary limit on the number of symbolic links
+that may be resolved in looking up a single file name, as a primitive
+way to detect loops.  @xref{Symbolic Links}.
+@end table
+
+
+@node File Name Portability,  , File Name Errors, File Names
+@subsection Portability of File Names
+
+The rules for the syntax of file names discussed in @ref{File Names},
+are the rules normally used by @gnusystems{} and by other POSIX
+systems.  However, other operating systems may use other conventions.
+
+There are two reasons why it can be important for you to be aware of
+file name portability issues:
+
+@itemize @bullet
+@item
+If your program makes assumptions about file name syntax, or contains
+embedded literal file name strings, it is more difficult to get it to
+run under other operating systems that use different syntax conventions.
+
+@item
+Even if you are not concerned about running your program on machines
+that run other operating systems, it may still be possible to access
+files that use different naming conventions.  For example, you may be
+able to access file systems on another computer running a different
+operating system over a network, or read and write disks in formats used
+by other operating systems.
+@end itemize
+
+The @w{ISO C} standard says very little about file name syntax, only that
+file names are strings.  In addition to varying restrictions on the
+length of file names and what characters can validly appear in a file
+name, different operating systems use different conventions and syntax
+for concepts such as structured directories and file types or
+extensions.  Some concepts such as file versions might be supported in
+some operating systems and not by others.
+
+The POSIX.1 standard allows implementations to put additional
+restrictions on file name syntax, concerning what characters are
+permitted in file names and on the length of file name and file name
+component strings.  However, on @gnusystems{}, any character except
+the null character is permitted in a file name string, and
+on @gnuhurdsystems{} there are no limits on the length of file name
+strings.
diff --git a/ap/libc/glibc/glibc-2.23/manual/ipc.texi b/ap/libc/glibc/glibc-2.23/manual/ipc.texi
new file mode 100644
index 0000000..081b98f
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/ipc.texi
@@ -0,0 +1,116 @@
+@node Inter-Process Communication, Job Control, Processes, Top
+@c %MENU% All about inter-process communication
+@chapter Inter-Process Communication
+@cindex ipc
+
+This chapter describes the @glibcadj{} inter-process communication primitives.
+
+@menu
+* Semaphores::	Support for creating and managing semaphores
+@end menu
+
+@node Semaphores
+@section Semaphores
+
+@Theglibc{} implements the semaphore APIs as defined in POSIX and
+System V.  Semaphores can be used by multiple processes to coordinate shared
+resources.  The following is a complete list of the semaphore functions provided
+by @theglibc{}.
+
+@c Need descriptions for all of these functions.
+
+@subsection System V Semaphores
+@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}}
+@c syscall(ipc) ok
+@c
+@c AC-unsafe because we need to translate the new kernel
+@c semid_ds buf into the userspace layout.  Cancellation
+@c at that point results in an inconsistent userspace
+@c semid_ds.
+@end deftypefun
+
+@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@subsection POSIX Semaphores
+
+@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Does not atomically update sem_t therefore AC-unsafe
+@c because it can leave sem_t partially initialized.
+@end deftypefun
+
+@deftypefun int sem_destroy (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Function does nothing and is therefore always safe.
+@end deftypefun
+
+@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...);
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
+@c pthread_once asuinit
+@c
+@c We are AC-Unsafe becuase we use pthread_once to initialize
+@c a global variable that holds the location of the mounted
+@c shmfs on Linux.
+@end deftypefun
+
+@deftypefun int sem_close (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c lll_lock asulock aculock
+@c twalk mtsrace{:root}
+@c
+@c We are AS-unsafe because we take a non-recursive lock.
+@c We are AC-unsafe because several internal data structures
+@c are not updated atomically.
+@end deftypefun
+
+@deftypefun int sem_unlink (const char *@var{name});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
+@c pthread_once asuinit acucorrupt aculock
+@c mempcpy acucorrupt
+@end deftypefun
+
+@deftypefun int sem_wait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c atomic_increment (nwaiters) acucorrupt
+@c
+@c Given the use atomic operations this function seems
+@c to be AS-safe.  It is AC-unsafe because there is still
+@c a window between atomic_decrement and the pthread_push
+@c of the handler that undoes that operation.  A cancellation
+@c at that point would fail to remove the process from the
+@c waiters count.
+@end deftypefun
+
+@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Same safety issues as sem_wait.
+@end deftypefun
+
+@deftypefun int sem_trywait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c All atomic operations are safe in all contexts.
+@end deftypefun
+
+@deftypefun int sem_post (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Same safety as sem_trywait.
+@end deftypefun
+
+@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Atomic write of a value is safe in all contexts.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/job.texi b/ap/libc/glibc/glibc-2.23/manual/job.texi
new file mode 100644
index 0000000..095c26d
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/job.texi
@@ -0,0 +1,1319 @@
+@node Job Control, Name Service Switch, Inter-Process Communication, Top
+@c %MENU% All about process groups and sessions
+@chapter Job Control
+
+@cindex process groups
+@cindex job control
+@cindex job
+@cindex session
+@dfn{Job control} refers to the protocol for allowing a user to move
+between multiple @dfn{process groups} (or @dfn{jobs}) within a single
+@dfn{login session}.  The job control facilities are set up so that
+appropriate behavior for most programs happens automatically and they
+need not do anything special about job control.  So you can probably
+ignore the material in this chapter unless you are writing a shell or
+login program.
+
+You need to be familiar with concepts relating to process creation
+(@pxref{Process Creation Concepts}) and signal handling (@pxref{Signal
+Handling}) in order to understand this material presented in this
+chapter.
+
+@menu
+* Concepts of Job Control::     Jobs can be controlled by a shell.
+* Job Control is Optional::     Not all POSIX systems support job control.
+* Controlling Terminal::        How a process gets its controlling terminal.
+* Access to the Terminal::      How processes share the controlling terminal.
+* Orphaned Process Groups::     Jobs left after the user logs out.
+* Implementing a Shell::        What a shell must do to implement job control.
+* Functions for Job Control::   Functions to control process groups.
+@end menu
+
+@node Concepts of Job Control, Job Control is Optional,  , Job Control
+@section Concepts of Job Control
+
+@cindex shell
+The fundamental purpose of an interactive shell is to read
+commands from the user's terminal and create processes to execute the
+programs specified by those commands.  It can do this using the
+@code{fork} (@pxref{Creating a Process}) and @code{exec}
+(@pxref{Executing a File}) functions.
+
+A single command may run just one process---but often one command uses
+several processes.  If you use the @samp{|} operator in a shell command,
+you explicitly request several programs in their own processes.  But
+even if you run just one program, it can use multiple processes
+internally.  For example, a single compilation command such as @samp{cc
+-c foo.c} typically uses four processes (though normally only two at any
+given time).  If you run @code{make}, its job is to run other programs
+in separate processes.
+
+The processes belonging to a single command are called a @dfn{process
+group} or @dfn{job}.  This is so that you can operate on all of them at
+once.  For example, typing @kbd{C-c} sends the signal @code{SIGINT} to
+terminate all the processes in the foreground process group.
+
+@cindex session
+A @dfn{session} is a larger group of processes.  Normally all the
+processes that stem from a single login belong to the same session.
+
+Every process belongs to a process group.  When a process is created, it
+becomes a member of the same process group and session as its parent
+process.  You can put it in another process group using the
+@code{setpgid} function, provided the process group belongs to the same
+session.
+
+@cindex session leader
+The only way to put a process in a different session is to make it the
+initial process of a new session, or a @dfn{session leader}, using the
+@code{setsid} function.  This also puts the session leader into a new
+process group, and you can't move it out of that process group again.
+
+Usually, new sessions are created by the system login program, and the
+session leader is the process running the user's login shell.
+
+@cindex controlling terminal
+A shell that supports job control must arrange to control which job can
+use the terminal at any time.  Otherwise there might be multiple jobs
+trying to read from the terminal at once, and confusion about which
+process should receive the input typed by the user.  To prevent this,
+the shell must cooperate with the terminal driver using the protocol
+described in this chapter.
+
+@cindex foreground job
+@cindex background job
+The shell can give unlimited access to the controlling terminal to only
+one process group at a time.  This is called the @dfn{foreground job} on
+that controlling terminal.  Other process groups managed by the shell
+that are executing without such access to the terminal are called
+@dfn{background jobs}.
+
+@cindex stopped job
+If a background job needs to read from its controlling
+terminal, it is @dfn{stopped} by the terminal driver; if the
+@code{TOSTOP} mode is set, likewise for writing.  The user can stop
+a foreground job by typing the SUSP character (@pxref{Special
+Characters}) and a program can stop any job by sending it a
+@code{SIGSTOP} signal.  It's the responsibility of the shell to notice
+when jobs stop, to notify the user about them, and to provide mechanisms
+for allowing the user to interactively continue stopped jobs and switch
+jobs between foreground and background.
+
+@xref{Access to the Terminal}, for more information about I/O to the
+controlling terminal,
+
+@node Job Control is Optional, Controlling Terminal, Concepts of Job Control , Job Control
+@section Job Control is Optional
+@cindex job control is optional
+
+Not all operating systems support job control.  @gnusystems{} do
+support job control, but if you are using @theglibc{} on some other
+system, that system may not support job control itself.
+
+You can use the @code{_POSIX_JOB_CONTROL} macro to test at compile-time
+whether the system supports job control.  @xref{System Options}.
+
+If job control is not supported, then there can be only one process
+group per session, which behaves as if it were always in the foreground.
+The functions for creating additional process groups simply fail with
+the error code @code{ENOSYS}.
+
+The macros naming the various job control signals (@pxref{Job Control
+Signals}) are defined even if job control is not supported.  However,
+the system never generates these signals, and attempts to send a job
+control signal or examine or specify their actions report errors or do
+nothing.
+
+
+@node Controlling Terminal, Access to the Terminal, Job Control is Optional, Job Control
+@section Controlling Terminal of a Process
+
+One of the attributes of a process is its controlling terminal.  Child
+processes created with @code{fork} inherit the controlling terminal from
+their parent process.  In this way, all the processes in a session
+inherit the controlling terminal from the session leader.  A session
+leader that has control of a terminal is called the @dfn{controlling
+process} of that terminal.
+
+@cindex controlling process
+You generally do not need to worry about the exact mechanism used to
+allocate a controlling terminal to a session, since it is done for you
+by the system when you log in.
+@c ??? How does GNU system let a process get a ctl terminal.
+
+An individual process disconnects from its controlling terminal when it
+calls @code{setsid} to become the leader of a new session.
+@xref{Process Group Functions}.
+
+@c !!! explain how it gets a new one (by opening any terminal)
+@c ??? How you get a controlling terminal is system-dependent.
+@c We should document how this will work in the GNU system when it is decided.
+@c What Unix does is not clean and I don't think GNU should use that.
+
+@node Access to the Terminal, Orphaned Process Groups, Controlling Terminal, Job Control
+@section Access to the Controlling Terminal
+@cindex controlling terminal, access to
+
+Processes in the foreground job of a controlling terminal have
+unrestricted access to that terminal; background processes do not.  This
+section describes in more detail what happens when a process in a
+background job tries to access its controlling terminal.
+
+@cindex @code{SIGTTIN}, from background job
+When a process in a background job tries to read from its controlling
+terminal, the process group is usually sent a @code{SIGTTIN} signal.
+This normally causes all of the processes in that group to stop (unless
+they handle the signal and don't stop themselves).  However, if the
+reading process is ignoring or blocking this signal, then @code{read}
+fails with an @code{EIO} error instead.
+
+@cindex @code{SIGTTOU}, from background job
+Similarly, when a process in a background job tries to write to its
+controlling terminal, the default behavior is to send a @code{SIGTTOU}
+signal to the process group.  However, the behavior is modified by the
+@code{TOSTOP} bit of the local modes flags (@pxref{Local Modes}).  If
+this bit is not set (which is the default), then writing to the
+controlling terminal is always permitted without sending a signal.
+Writing is also permitted if the @code{SIGTTOU} signal is being ignored
+or blocked by the writing process.
+
+Most other terminal operations that a program can do are treated as
+reading or as writing.  (The description of each operation should say
+which.)
+
+For more information about the primitive @code{read} and @code{write}
+functions, see @ref{I/O Primitives}.
+
+
+@node Orphaned Process Groups, Implementing a Shell, Access to the Terminal, Job Control
+@section Orphaned Process Groups
+@cindex orphaned process group
+
+When a controlling process terminates, its terminal becomes free and a
+new session can be established on it.  (In fact, another user could log
+in on the terminal.)  This could cause a problem if any processes from
+the old session are still trying to use that terminal.
+
+To prevent problems, process groups that continue running even after the
+session leader has terminated are marked as @dfn{orphaned process
+groups}.
+
+When a process group becomes an orphan, its processes are sent a
+@code{SIGHUP} signal.  Ordinarily, this causes the processes to
+terminate.  However, if a program ignores this signal or establishes a
+handler for it (@pxref{Signal Handling}), it can continue running as in
+the orphan process group even after its controlling process terminates;
+but it still cannot access the terminal any more.
+
+@node Implementing a Shell, Functions for Job Control, Orphaned Process Groups, Job Control
+@section Implementing a Job Control Shell
+
+This section describes what a shell must do to implement job control, by
+presenting an extensive sample program to illustrate the concepts
+involved.
+
+@iftex
+@itemize @bullet
+@item
+@ref{Data Structures}, introduces the example and presents
+its primary data structures.
+
+@item
+@ref{Initializing the Shell}, discusses actions which the shell must
+perform to prepare for job control.
+
+@item
+@ref{Launching Jobs}, includes information about how to create jobs
+to execute commands.
+
+@item
+@ref{Foreground and Background}, discusses what the shell should
+do differently when launching a job in the foreground as opposed to
+a background job.
+
+@item
+@ref{Stopped and Terminated Jobs}, discusses reporting of job status
+back to the shell.
+
+@item
+@ref{Continuing Stopped Jobs}, tells you how to continue jobs that
+have been stopped.
+
+@item
+@ref{Missing Pieces}, discusses other parts of the shell.
+@end itemize
+@end iftex
+
+@menu
+* 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.
+@end menu
+
+@node Data Structures, Initializing the Shell,  , Implementing a Shell
+@subsection Data Structures for the Shell
+
+All of the program examples included in this chapter are part of
+a simple shell program.  This section presents data structures
+and utility functions which are used throughout the example.
+
+The sample shell deals mainly with two data structures.  The
+@code{job} type contains information about a job, which is a
+set of subprocesses linked together with pipes.  The @code{process} type
+holds information about a single subprocess.  Here are the relevant
+data structure declarations:
+
+@smallexample
+@group
+/* @r{A process is a single process.}  */
+typedef struct process
+@{
+  struct process *next;       /* @r{next process in pipeline} */
+  char **argv;                /* @r{for exec} */
+  pid_t pid;                  /* @r{process ID} */
+  char completed;             /* @r{true if process has completed} */
+  char stopped;               /* @r{true if process has stopped} */
+  int status;                 /* @r{reported status value} */
+@} process;
+@end group
+
+@group
+/* @r{A job is a pipeline of processes.}  */
+typedef struct job
+@{
+  struct job *next;           /* @r{next active job} */
+  char *command;              /* @r{command line, used for messages} */
+  process *first_process;     /* @r{list of processes in this job} */
+  pid_t pgid;                 /* @r{process group ID} */
+  char notified;              /* @r{true if user told about stopped job} */
+  struct termios tmodes;      /* @r{saved terminal modes} */
+  int stdin, stdout, stderr;  /* @r{standard i/o channels} */
+@} job;
+
+/* @r{The active jobs are linked into a list.  This is its head.}   */
+job *first_job = NULL;
+@end group
+@end smallexample
+
+Here are some utility functions that are used for operating on @code{job}
+objects.
+
+@smallexample
+@group
+/* @r{Find the active job with the indicated @var{pgid}.}  */
+job *
+find_job (pid_t pgid)
+@{
+  job *j;
+
+  for (j = first_job; j; j = j->next)
+    if (j->pgid == pgid)
+      return j;
+  return NULL;
+@}
+@end group
+
+@group
+/* @r{Return true if all processes in the job have stopped or completed.}  */
+int
+job_is_stopped (job *j)
+@{
+  process *p;
+
+  for (p = j->first_process; p; p = p->next)
+    if (!p->completed && !p->stopped)
+      return 0;
+  return 1;
+@}
+@end group
+
+@group
+/* @r{Return true if all processes in the job have completed.}  */
+int
+job_is_completed (job *j)
+@{
+  process *p;
+
+  for (p = j->first_process; p; p = p->next)
+    if (!p->completed)
+      return 0;
+  return 1;
+@}
+@end group
+@end smallexample
+
+
+@node Initializing the Shell, Launching Jobs, Data Structures, Implementing a Shell
+@subsection Initializing the Shell
+@cindex job control, enabling
+@cindex subshell
+
+When a shell program that normally performs job control is started, it
+has to be careful in case it has been invoked from another shell that is
+already doing its own job control.
+
+A subshell that runs interactively has to ensure that it has been placed
+in the foreground by its parent shell before it can enable job control
+itself.  It does this by getting its initial process group ID with the
+@code{getpgrp} function, and comparing it to the process group ID of the
+current foreground job associated with its controlling terminal (which
+can be retrieved using the @code{tcgetpgrp} function).
+
+If the subshell is not running as a foreground job, it must stop itself
+by sending a @code{SIGTTIN} signal to its own process group.  It may not
+arbitrarily put itself into the foreground; it must wait for the user to
+tell the parent shell to do this.  If the subshell is continued again,
+it should repeat the check and stop itself again if it is still not in
+the foreground.
+
+@cindex job control, enabling
+Once the subshell has been placed into the foreground by its parent
+shell, it can enable its own job control.  It does this by calling
+@code{setpgid} to put itself into its own process group, and then
+calling @code{tcsetpgrp} to place this process group into the
+foreground.
+
+When a shell enables job control, it should set itself to ignore all the
+job control stop signals so that it doesn't accidentally stop itself.
+You can do this by setting the action for all the stop signals to
+@code{SIG_IGN}.
+
+A subshell that runs non-interactively cannot and should not support job
+control.  It must leave all processes it creates in the same process
+group as the shell itself; this allows the non-interactive shell and its
+child processes to be treated as a single job by the parent shell.  This
+is easy to do---just don't use any of the job control primitives---but
+you must remember to make the shell do it.
+
+
+Here is the initialization code for the sample shell that shows how to
+do all of this.
+
+@smallexample
+/* @r{Keep track of attributes of the shell.}  */
+
+#include <sys/types.h>
+#include <termios.h>
+#include <unistd.h>
+
+pid_t shell_pgid;
+struct termios shell_tmodes;
+int shell_terminal;
+int shell_is_interactive;
+
+
+/* @r{Make sure the shell is running interactively as the foreground job}
+   @r{before proceeding.} */
+
+void
+init_shell ()
+@{
+
+  /* @r{See if we are running interactively.}  */
+  shell_terminal = STDIN_FILENO;
+  shell_is_interactive = isatty (shell_terminal);
+
+  if (shell_is_interactive)
+    @{
+      /* @r{Loop until we are in the foreground.}  */
+      while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
+        kill (- shell_pgid, SIGTTIN);
+
+      /* @r{Ignore interactive and job-control signals.}  */
+      signal (SIGINT, SIG_IGN);
+      signal (SIGQUIT, SIG_IGN);
+      signal (SIGTSTP, SIG_IGN);
+      signal (SIGTTIN, SIG_IGN);
+      signal (SIGTTOU, SIG_IGN);
+      signal (SIGCHLD, SIG_IGN);
+
+      /* @r{Put ourselves in our own process group.}  */
+      shell_pgid = getpid ();
+      if (setpgid (shell_pgid, shell_pgid) < 0)
+        @{
+          perror ("Couldn't put the shell in its own process group");
+          exit (1);
+        @}
+
+      /* @r{Grab control of the terminal.}  */
+      tcsetpgrp (shell_terminal, shell_pgid);
+
+      /* @r{Save default terminal attributes for shell.}  */
+      tcgetattr (shell_terminal, &shell_tmodes);
+    @}
+@}
+@end smallexample
+
+
+@node Launching Jobs, Foreground and Background, Initializing the Shell, Implementing a Shell
+@subsection Launching Jobs
+@cindex launching jobs
+
+Once the shell has taken responsibility for performing job control on
+its controlling terminal, it can launch jobs in response to commands
+typed by the user.
+
+To create the processes in a process group, you use the same @code{fork}
+and @code{exec} functions described in @ref{Process Creation Concepts}.
+Since there are multiple child processes involved, though, things are a
+little more complicated and you must be careful to do things in the
+right order.  Otherwise, nasty race conditions can result.
+
+You have two choices for how to structure the tree of parent-child
+relationships among the processes.  You can either make all the
+processes in the process group be children of the shell process, or you
+can make one process in group be the ancestor of all the other processes
+in that group.  The sample shell program presented in this chapter uses
+the first approach because it makes bookkeeping somewhat simpler.
+
+@cindex process group leader
+@cindex process group ID
+As each process is forked, it should put itself in the new process group
+by calling @code{setpgid}; see @ref{Process Group Functions}.  The first
+process in the new group becomes its @dfn{process group leader}, and its
+process ID becomes the @dfn{process group ID} for the group.
+
+@cindex race conditions, relating to job control
+The shell should also call @code{setpgid} to put each of its child
+processes into the new process group.  This is because there is a
+potential timing problem: each child process must be put in the process
+group before it begins executing a new program, and the shell depends on
+having all the child processes in the group before it continues
+executing.  If both the child processes and the shell call
+@code{setpgid}, this ensures that the right things happen no matter which
+process gets to it first.
+
+If the job is being launched as a foreground job, the new process group
+also needs to be put into the foreground on the controlling terminal
+using @code{tcsetpgrp}.  Again, this should be done by the shell as well
+as by each of its child processes, to avoid race conditions.
+
+The next thing each child process should do is to reset its signal
+actions.
+
+During initialization, the shell process set itself to ignore job
+control signals; see @ref{Initializing the Shell}.  As a result, any child
+processes it creates also ignore these signals by inheritance.  This is
+definitely undesirable, so each child process should explicitly set the
+actions for these signals back to @code{SIG_DFL} just after it is forked.
+
+Since shells follow this convention, applications can assume that they
+inherit the correct handling of these signals from the parent process.
+But every application has a responsibility not to mess up the handling
+of stop signals.  Applications that disable the normal interpretation of
+the SUSP character should provide some other mechanism for the user to
+stop the job.  When the user invokes this mechanism, the program should
+send a @code{SIGTSTP} signal to the process group of the process, not
+just to the process itself.  @xref{Signaling Another Process}.
+
+Finally, each child process should call @code{exec} in the normal way.
+This is also the point at which redirection of the standard input and
+output channels should be handled.  @xref{Duplicating Descriptors},
+for an explanation of how to do this.
+
+Here is the function from the sample shell program that is responsible
+for launching a program.  The function is executed by each child process
+immediately after it has been forked by the shell, and never returns.
+
+@smallexample
+void
+launch_process (process *p, pid_t pgid,
+                int infile, int outfile, int errfile,
+                int foreground)
+@{
+  pid_t pid;
+
+  if (shell_is_interactive)
+    @{
+      /* @r{Put the process into the process group and give the process group}
+         @r{the terminal, if appropriate.}
+         @r{This has to be done both by the shell and in the individual}
+         @r{child processes because of potential race conditions.}  */
+      pid = getpid ();
+      if (pgid == 0) pgid = pid;
+      setpgid (pid, pgid);
+      if (foreground)
+        tcsetpgrp (shell_terminal, pgid);
+
+      /* @r{Set the handling for job control signals back to the default.}  */
+      signal (SIGINT, SIG_DFL);
+      signal (SIGQUIT, SIG_DFL);
+      signal (SIGTSTP, SIG_DFL);
+      signal (SIGTTIN, SIG_DFL);
+      signal (SIGTTOU, SIG_DFL);
+      signal (SIGCHLD, SIG_DFL);
+    @}
+
+  /* @r{Set the standard input/output channels of the new process.}  */
+  if (infile != STDIN_FILENO)
+    @{
+      dup2 (infile, STDIN_FILENO);
+      close (infile);
+    @}
+  if (outfile != STDOUT_FILENO)
+    @{
+      dup2 (outfile, STDOUT_FILENO);
+      close (outfile);
+    @}
+  if (errfile != STDERR_FILENO)
+    @{
+      dup2 (errfile, STDERR_FILENO);
+      close (errfile);
+    @}
+
+  /* @r{Exec the new process.  Make sure we exit.}  */
+  execvp (p->argv[0], p->argv);
+  perror ("execvp");
+  exit (1);
+@}
+@end smallexample
+
+If the shell is not running interactively, this function does not do
+anything with process groups or signals.  Remember that a shell not
+performing job control must keep all of its subprocesses in the same
+process group as the shell itself.
+
+Next, here is the function that actually launches a complete job.
+After creating the child processes, this function calls some other
+functions to put the newly created job into the foreground or background;
+these are discussed in @ref{Foreground and Background}.
+
+@smallexample
+void
+launch_job (job *j, int foreground)
+@{
+  process *p;
+  pid_t pid;
+  int mypipe[2], infile, outfile;
+
+  infile = j->stdin;
+  for (p = j->first_process; p; p = p->next)
+    @{
+      /* @r{Set up pipes, if necessary.}  */
+      if (p->next)
+        @{
+          if (pipe (mypipe) < 0)
+            @{
+              perror ("pipe");
+              exit (1);
+            @}
+          outfile = mypipe[1];
+        @}
+      else
+        outfile = j->stdout;
+
+      /* @r{Fork the child processes.}  */
+      pid = fork ();
+      if (pid == 0)
+        /* @r{This is the child process.}  */
+        launch_process (p, j->pgid, infile,
+                        outfile, j->stderr, foreground);
+      else if (pid < 0)
+        @{
+          /* @r{The fork failed.}  */
+          perror ("fork");
+          exit (1);
+        @}
+      else
+        @{
+          /* @r{This is the parent process.}  */
+          p->pid = pid;
+          if (shell_is_interactive)
+            @{
+              if (!j->pgid)
+                j->pgid = pid;
+              setpgid (pid, j->pgid);
+            @}
+        @}
+
+      /* @r{Clean up after pipes.}  */
+      if (infile != j->stdin)
+        close (infile);
+      if (outfile != j->stdout)
+        close (outfile);
+      infile = mypipe[0];
+    @}
+
+  format_job_info (j, "launched");
+
+  if (!shell_is_interactive)
+    wait_for_job (j);
+  else if (foreground)
+    put_job_in_foreground (j, 0);
+  else
+    put_job_in_background (j, 0);
+@}
+@end smallexample
+
+
+@node Foreground and Background, Stopped and Terminated Jobs, Launching Jobs, Implementing a Shell
+@subsection Foreground and Background
+
+Now let's consider what actions must be taken by the shell when it
+launches a job into the foreground, and how this differs from what
+must be done when a background job is launched.
+
+@cindex foreground job, launching
+When a foreground job is launched, the shell must first give it access
+to the controlling terminal by calling @code{tcsetpgrp}.  Then, the
+shell should wait for processes in that process group to terminate or
+stop.  This is discussed in more detail in @ref{Stopped and Terminated
+Jobs}.
+
+When all of the processes in the group have either completed or stopped,
+the shell should regain control of the terminal for its own process
+group by calling @code{tcsetpgrp} again.  Since stop signals caused by
+I/O from a background process or a SUSP character typed by the user
+are sent to the process group, normally all the processes in the job
+stop together.
+
+The foreground job may have left the terminal in a strange state, so the
+shell should restore its own saved terminal modes before continuing.  In
+case the job is merely stopped, the shell should first save the current
+terminal modes so that it can restore them later if the job is
+continued.  The functions for dealing with terminal modes are
+@code{tcgetattr} and @code{tcsetattr}; these are described in
+@ref{Terminal Modes}.
+
+Here is the sample shell's function for doing all of this.
+
+@smallexample
+@group
+/* @r{Put job @var{j} in the foreground.  If @var{cont} is nonzero,}
+   @r{restore the saved terminal modes and send the process group a}
+   @r{@code{SIGCONT} signal to wake it up before we block.}  */
+
+void
+put_job_in_foreground (job *j, int cont)
+@{
+  /* @r{Put the job into the foreground.}  */
+  tcsetpgrp (shell_terminal, j->pgid);
+@end group
+
+@group
+  /* @r{Send the job a continue signal, if necessary.}  */
+  if (cont)
+    @{
+      tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
+      if (kill (- j->pgid, SIGCONT) < 0)
+        perror ("kill (SIGCONT)");
+    @}
+@end group
+
+  /* @r{Wait for it to report.}  */
+  wait_for_job (j);
+
+  /* @r{Put the shell back in the foreground.}  */
+  tcsetpgrp (shell_terminal, shell_pgid);
+
+@group
+  /* @r{Restore the shell's terminal modes.}  */
+  tcgetattr (shell_terminal, &j->tmodes);
+  tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
+@}
+@end group
+@end smallexample
+
+@cindex background job, launching
+If the process group is launched as a background job, the shell should
+remain in the foreground itself and continue to read commands from
+the terminal.
+
+In the sample shell, there is not much that needs to be done to put
+a job into the background.  Here is the function it uses:
+
+@smallexample
+/* @r{Put a job in the background.  If the cont argument is true, send}
+   @r{the process group a @code{SIGCONT} signal to wake it up.}  */
+
+void
+put_job_in_background (job *j, int cont)
+@{
+  /* @r{Send the job a continue signal, if necessary.}  */
+  if (cont)
+    if (kill (-j->pgid, SIGCONT) < 0)
+      perror ("kill (SIGCONT)");
+@}
+@end smallexample
+
+
+@node Stopped and Terminated Jobs, Continuing Stopped Jobs, Foreground and Background, Implementing a Shell
+@subsection Stopped and Terminated Jobs
+
+@cindex stopped jobs, detecting
+@cindex terminated jobs, detecting
+When a foreground process is launched, the shell must block until all of
+the processes in that job have either terminated or stopped.  It can do
+this by calling the @code{waitpid} function; see @ref{Process
+Completion}.  Use the @code{WUNTRACED} option so that status is reported
+for processes that stop as well as processes that terminate.
+
+The shell must also check on the status of background jobs so that it
+can report terminated and stopped jobs to the user; this can be done by
+calling @code{waitpid} with the @code{WNOHANG} option.  A good place to
+put a such a check for terminated and stopped jobs is just before
+prompting for a new command.
+
+@cindex @code{SIGCHLD}, handling of
+The shell can also receive asynchronous notification that there is
+status information available for a child process by establishing a
+handler for @code{SIGCHLD} signals.  @xref{Signal Handling}.
+
+In the sample shell program, the @code{SIGCHLD} signal is normally
+ignored.  This is to avoid reentrancy problems involving the global data
+structures the shell manipulates.  But at specific times when the shell
+is not using these data structures---such as when it is waiting for
+input on the terminal---it makes sense to enable a handler for
+@code{SIGCHLD}.  The same function that is used to do the synchronous
+status checks (@code{do_job_notification}, in this case) can also be
+called from within this handler.
+
+Here are the parts of the sample shell program that deal with checking
+the status of jobs and reporting the information to the user.
+
+@smallexample
+@group
+/* @r{Store the status of the process @var{pid} that was returned by waitpid.}
+   @r{Return 0 if all went well, nonzero otherwise.}  */
+
+int
+mark_process_status (pid_t pid, int status)
+@{
+  job *j;
+  process *p;
+@end group
+
+@group
+  if (pid > 0)
+    @{
+      /* @r{Update the record for the process.}  */
+      for (j = first_job; j; j = j->next)
+        for (p = j->first_process; p; p = p->next)
+          if (p->pid == pid)
+            @{
+              p->status = status;
+              if (WIFSTOPPED (status))
+                p->stopped = 1;
+              else
+                @{
+                  p->completed = 1;
+                  if (WIFSIGNALED (status))
+                    fprintf (stderr, "%d: Terminated by signal %d.\n",
+                             (int) pid, WTERMSIG (p->status));
+                @}
+              return 0;
+             @}
+      fprintf (stderr, "No child process %d.\n", pid);
+      return -1;
+    @}
+@end group
+@group
+  else if (pid == 0 || errno == ECHILD)
+    /* @r{No processes ready to report.}  */
+    return -1;
+  else @{
+    /* @r{Other weird errors.}  */
+    perror ("waitpid");
+    return -1;
+  @}
+@}
+@end group
+
+@group
+/* @r{Check for processes that have status information available,}
+   @r{without blocking.}  */
+
+void
+update_status (void)
+@{
+  int status;
+  pid_t pid;
+
+  do
+    pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
+  while (!mark_process_status (pid, status));
+@}
+@end group
+
+@group
+/* @r{Check for processes that have status information available,}
+   @r{blocking until all processes in the given job have reported.}  */
+
+void
+wait_for_job (job *j)
+@{
+  int status;
+  pid_t pid;
+
+  do
+    pid = waitpid (WAIT_ANY, &status, WUNTRACED);
+  while (!mark_process_status (pid, status)
+         && !job_is_stopped (j)
+         && !job_is_completed (j));
+@}
+@end group
+
+@group
+/* @r{Format information about job status for the user to look at.}  */
+
+void
+format_job_info (job *j, const char *status)
+@{
+  fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
+@}
+@end group
+
+@group
+/* @r{Notify the user about stopped or terminated jobs.}
+   @r{Delete terminated jobs from the active job list.}  */
+
+void
+do_job_notification (void)
+@{
+  job *j, *jlast, *jnext;
+  process *p;
+
+  /* @r{Update status information for child processes.}  */
+  update_status ();
+
+  jlast = NULL;
+  for (j = first_job; j; j = jnext)
+    @{
+      jnext = j->next;
+
+      /* @r{If all processes have completed, tell the user the job has}
+         @r{completed and delete it from the list of active jobs.}  */
+      if (job_is_completed (j)) @{
+        format_job_info (j, "completed");
+        if (jlast)
+          jlast->next = jnext;
+        else
+          first_job = jnext;
+        free_job (j);
+      @}
+
+      /* @r{Notify the user about stopped jobs,}
+         @r{marking them so that we won't do this more than once.}  */
+      else if (job_is_stopped (j) && !j->notified) @{
+        format_job_info (j, "stopped");
+        j->notified = 1;
+        jlast = j;
+      @}
+
+      /* @r{Don't say anything about jobs that are still running.}  */
+      else
+        jlast = j;
+    @}
+@}
+@end group
+@end smallexample
+
+@node Continuing Stopped Jobs, Missing Pieces, Stopped and Terminated Jobs, Implementing a Shell
+@subsection Continuing Stopped Jobs
+
+@cindex stopped jobs, continuing
+The shell can continue a stopped job by sending a @code{SIGCONT} signal
+to its process group.  If the job is being continued in the foreground,
+the shell should first invoke @code{tcsetpgrp} to give the job access to
+the terminal, and restore the saved terminal settings.  After continuing
+a job in the foreground, the shell should wait for the job to stop or
+complete, as if the job had just been launched in the foreground.
+
+The sample shell program handles both newly created and continued jobs
+with the same pair of functions, @w{@code{put_job_in_foreground}} and
+@w{@code{put_job_in_background}}.  The definitions of these functions
+were given in @ref{Foreground and Background}.  When continuing a
+stopped job, a nonzero value is passed as the @var{cont} argument to
+ensure that the @code{SIGCONT} signal is sent and the terminal modes
+reset, as appropriate.
+
+This leaves only a function for updating the shell's internal bookkeeping
+about the job being continued:
+
+@smallexample
+@group
+/* @r{Mark a stopped job J as being running again.}  */
+
+void
+mark_job_as_running (job *j)
+@{
+  Process *p;
+
+  for (p = j->first_process; p; p = p->next)
+    p->stopped = 0;
+  j->notified = 0;
+@}
+@end group
+
+@group
+/* @r{Continue the job J.}  */
+
+void
+continue_job (job *j, int foreground)
+@{
+  mark_job_as_running (j);
+  if (foreground)
+    put_job_in_foreground (j, 1);
+  else
+    put_job_in_background (j, 1);
+@}
+@end group
+@end smallexample
+
+@node Missing Pieces,  , Continuing Stopped Jobs, Implementing a Shell
+@subsection The Missing Pieces
+
+The code extracts for the sample shell included in this chapter are only
+a part of the entire shell program.  In particular, nothing at all has
+been said about how @code{job} and @code{program} data structures are
+allocated and initialized.
+
+Most real shells provide a complex user interface that has support for
+a command language; variables; abbreviations, substitutions, and pattern
+matching on file names; and the like.  All of this is far too complicated
+to explain here!  Instead, we have concentrated on showing how to
+implement the core process creation and job control functions that can
+be called from such a shell.
+
+Here is a table summarizing the major entry points we have presented:
+
+@table @code
+@item void init_shell (void)
+Initialize the shell's internal state.  @xref{Initializing the
+Shell}.
+
+@item void launch_job (job *@var{j}, int @var{foreground})
+Launch the job @var{j} as either a foreground or background job.
+@xref{Launching Jobs}.
+
+@item void do_job_notification (void)
+Check for and report any jobs that have terminated or stopped.  Can be
+called synchronously or within a handler for @code{SIGCHLD} signals.
+@xref{Stopped and Terminated Jobs}.
+
+@item void continue_job (job *@var{j}, int @var{foreground})
+Continue the job @var{j}.  @xref{Continuing Stopped Jobs}.
+@end table
+
+Of course, a real shell would also want to provide other functions for
+managing jobs.  For example, it would be useful to have commands to list
+all active jobs or to send a signal (such as @code{SIGKILL}) to a job.
+
+
+@node Functions for Job Control,  , Implementing a Shell, Job Control
+@section Functions for Job Control
+@cindex process group functions
+@cindex job control functions
+
+This section contains detailed descriptions of the functions relating
+to job control.
+
+@menu
+* 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.
+@end menu
+
+
+@node Identifying the Terminal, Process Group Functions,  , Functions for Job Control
+@subsection Identifying the Controlling Terminal
+@cindex controlling terminal, determining
+
+You can use the @code{ctermid} function to get a file name that you can
+use to open the controlling terminal.  In @theglibc{}, it returns
+the same string all the time: @code{"/dev/tty"}.  That is a special
+``magic'' file name that refers to the controlling terminal of the
+current process (if it has one).  To find the name of the specific
+terminal device, use @code{ttyname}; @pxref{Is It a Terminal}.
+
+The function @code{ctermid} is declared in the header file
+@file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment POSIX.1
+@deftypefun {char *} ctermid (char *@var{string})
+@safety{@prelim{}@mtsafe{@mtsposix{/!string}}@assafe{}@acsafe{}}
+@c This function is a stub by default; the actual implementation, for
+@c posix systems, returns a pointer to a string literal if passed a NULL
+@c string.  It's not clear we want to commit to being MT-Safe in the
+@c !string case, so maybe add mtasurace{:ctermid/!string} when we take
+@c prelim out, to make room for using a static buffer in the future.
+The @code{ctermid} function returns a string containing the file name of
+the controlling terminal for the current process.  If @var{string} is
+not a null pointer, it should be an array that can hold at least
+@code{L_ctermid} characters; the string is returned in this array.
+Otherwise, a pointer to a string in a static area is returned, which
+might get overwritten on subsequent calls to this function.
+
+An empty string is returned if the file name cannot be determined for
+any reason.  Even if a file name is returned, access to the file it
+represents is not guaranteed.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX.1
+@deftypevr Macro int L_ctermid
+The value of this macro is an integer constant expression that
+represents the size of a string large enough to hold the file name
+returned by @code{ctermid}.
+@end deftypevr
+
+See also the @code{isatty} and @code{ttyname} functions, in
+@ref{Is It a Terminal}.
+
+
+@node Process Group Functions, Terminal Access Functions, Identifying the Terminal, Functions for Job Control
+@subsection Process Group Functions
+
+Here are descriptions of the functions for manipulating process groups.
+Your program should include the header files @file{sys/types.h} and
+@file{unistd.h} to use these functions.
+@pindex unistd.h
+@pindex sys/types.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t setsid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is usually a direct syscall, but if a syscall is not available,
+@c we use a stub, or Hurd- and BSD-specific implementations.  The former
+@c uses a mutex and a hurd critical section, and the latter issues a few
+@c syscalls, so both seem safe, the locking on Hurd is safe because of
+@c the critical section.
+The @code{setsid} function creates a new session.  The calling process
+becomes the session leader, and is put in a new process group whose
+process group ID is the same as the process ID of that process.  There
+are initially no other processes in the new process group, and no other
+process groups in the new session.
+
+This function also makes the calling process have no controlling terminal.
+
+The @code{setsid} function returns the new process group ID of the
+calling process if successful.  A return value of @code{-1} indicates an
+error.  The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EPERM
+The calling process is already a process group leader, or there is
+already another process group around that has the same process group ID.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment SVID
+@deftypefun pid_t getsid (pid_t @var{pid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Stub or direct syscall, except on hurd, where it is equally safe.
+
+The @code{getsid} function returns the process group ID of the session
+leader of the specified process.  If a @var{pid} is @code{0}, the
+process group ID of the session leader of the current process is
+returned.
+
+In case of error @code{-1} is returned and @code{errno} is set.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item ESRCH
+There is no process with the given process ID @var{pid}.
+@item EPERM
+The calling process and the process specified by @var{pid} are in
+different sessions, and the implementation doesn't allow to access the
+process group ID of the session leader of the process with ID @var{pid}
+from the calling process.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t getpgrp (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getpgrp} function returns the process group ID of
+the calling process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int getpgid (pid_t @var{pid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Stub or direct syscall, except on hurd, where it is equally safe.
+
+The @code{getpgid} function
+returns the process group ID of the process @var{pid}.  You can supply a
+value of @code{0} for the @var{pid} argument to get information about
+the calling process.
+
+In case of error @code{-1} is returned and @code{errno} is set.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item ESRCH
+There is no process with the given process ID @var{pid}.
+The calling process and the process specified by @var{pid} are in
+different sessions, and the implementation doesn't allow to access the
+process group ID of the process with ID @var{pid} from the calling
+process.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Stub or direct syscall, except on hurd, where it is equally safe.
+The @code{setpgid} function puts the process @var{pid} into the process
+group @var{pgid}.  As a special case, either @var{pid} or @var{pgid} can
+be zero to indicate the process ID of the calling process.
+
+This function fails on a system that does not support job control.
+@xref{Job Control is Optional}, for more information.
+
+If the operation is successful, @code{setpgid} returns zero.  Otherwise
+it returns @code{-1}.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EACCES
+The child process named by @var{pid} has executed an @code{exec}
+function since it was forked.
+
+@item EINVAL
+The value of the @var{pgid} is not valid.
+
+@item ENOSYS
+The system doesn't support job control.
+
+@item EPERM
+The process indicated by the @var{pid} argument is a session leader,
+or is not in the same session as the calling process, or the value of
+the @var{pgid} argument doesn't match a process group ID in the same
+session as the calling process.
+
+@item ESRCH
+The process indicated by the @var{pid} argument is not the calling
+process or a child of the calling process.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall or setpgid wrapper.
+This is the BSD Unix name for @code{setpgid}.  Both functions do exactly
+the same thing.
+@end deftypefun
+
+
+@node Terminal Access Functions,  , Process Group Functions, Functions for Job Control
+@subsection Functions for Controlling Terminal Access
+
+These are the functions for reading or setting the foreground
+process group of a terminal.  You should include the header files
+@file{sys/types.h} and @file{unistd.h} in your application to use
+these functions.
+@pindex unistd.h
+@pindex sys/types.h
+
+Although these functions take a file descriptor argument to specify
+the terminal device, the foreground job is associated with the terminal
+file itself and not a particular open file descriptor.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t tcgetpgrp (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Stub, or ioctl on BSD and GNU/Linux.
+This function returns the process group ID of the foreground process
+group associated with the terminal open on descriptor @var{filedes}.
+
+If there is no foreground process group, the return value is a number
+greater than @code{1} that does not match the process group ID of any
+existing process group.  This can happen if all of the processes in the
+job that was formerly the foreground job have terminated, and no other
+job has yet been moved into the foreground.
+
+In case of an error, a value of @code{-1} is returned.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOSYS
+The system doesn't support job control.
+
+@item ENOTTY
+The terminal file associated with the @var{filedes} argument isn't the
+controlling terminal of the calling process.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Stub, or ioctl on BSD and GNU/Linux.
+This function is used to set a terminal's foreground process group ID.
+The argument @var{filedes} is a descriptor which specifies the terminal;
+@var{pgid} specifies the process group.  The calling process must be a
+member of the same session as @var{pgid} and must have the same
+controlling terminal.
+
+For terminal access purposes, this function is treated as output.  If it
+is called from a background process on its controlling terminal,
+normally all processes in the process group are sent a @code{SIGTTOU}
+signal.  The exception is if the calling process itself is ignoring or
+blocking @code{SIGTTOU} signals, in which case the operation is
+performed and no signal is sent.
+
+If successful, @code{tcsetpgrp} returns @code{0}.  A return value of
+@code{-1} indicates an error.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{pgid} argument is not valid.
+
+@item ENOSYS
+The system doesn't support job control.
+
+@item ENOTTY
+The @var{filedes} isn't the controlling terminal of the calling process.
+
+@item EPERM
+The @var{pgid} isn't a process group in the same session as the calling
+process.
+@end table
+@end deftypefun
+
+@comment termios.h
+@comment Unix98
+@deftypefun pid_t tcgetsid (int @var{fildes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Ioctl call, if available, or tcgetpgrp followed by getsid.
+This function is used to obtain the process group ID of the session
+for which the terminal specified by @var{fildes} is the controlling terminal.
+If the call is successful the group ID is returned.  Otherwise the
+return value is @code{(pid_t) -1} and the global variable @var{errno}
+is set to the following value:
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTTY
+The calling process does not have a controlling terminal, or the file
+is not the controlling terminal.
+@end table
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/lang.texi b/ap/libc/glibc/glibc-2.23/manual/lang.texi
new file mode 100644
index 0000000..7f8a368
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/lang.texi
@@ -0,0 +1,1239 @@
+@c This node must have no pointers.
+@node Language Features
+@c @node Language Features, Library Summary, , Top
+@c %MENU% C language features provided by the library
+@appendix C Language Facilities in the Library
+
+Some of the facilities implemented by the C library really should be
+thought of as parts of the C language itself.  These facilities ought to
+be documented in the C Language Manual, not in the library manual; but
+since we don't have the language manual yet, and documentation for these
+features has been written, we are publishing it here.
+
+@menu
+* Consistency Checking::        Using @code{assert} to abort if
+				 something ``impossible'' happens.
+* Variadic Functions::          Defining functions with varying numbers
+                                 of args.
+* Null Pointer Constant::       The macro @code{NULL}.
+* Important Data Types::        Data types for object sizes.
+* Data Type Measurements::      Parameters of data type representations.
+@end menu
+
+@node Consistency Checking
+@section Explicitly Checking Internal Consistency
+@cindex consistency checking
+@cindex impossible events
+@cindex assertions
+
+When you're writing a program, it's often a good idea to put in checks
+at strategic places for ``impossible'' errors or violations of basic
+assumptions.  These kinds of checks are helpful in debugging problems
+with the interfaces between different parts of the program, for example.
+
+@pindex assert.h
+The @code{assert} macro, defined in the header file @file{assert.h},
+provides a convenient way to abort the program while printing a message
+about where in the program the error was detected.
+
+@vindex NDEBUG
+Once you think your program is debugged, you can disable the error
+checks performed by the @code{assert} macro by recompiling with the
+macro @code{NDEBUG} defined.  This means you don't actually have to
+change the program source code to disable these checks.
+
+But disabling these consistency checks is undesirable unless they make
+the program significantly slower.  All else being equal, more error
+checking is good no matter who is running the program.  A wise user
+would rather have a program crash, visibly, than have it return nonsense
+without indicating anything might be wrong.
+
+@comment assert.h
+@comment ISO
+@deftypefn Macro void assert (int @var{expression})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c assert_fail_base calls asprintf, and fflushes stderr.
+Verify the programmer's belief that @var{expression} is nonzero at
+this point in the program.
+
+If @code{NDEBUG} is not defined, @code{assert} tests the value of
+@var{expression}.  If it is false (zero), @code{assert} aborts the
+program (@pxref{Aborting a Program}) after printing a message of the
+form:
+
+@smallexample
+@file{@var{file}}:@var{linenum}: @var{function}: Assertion `@var{expression}' failed.
+@end smallexample
+
+@noindent
+on the standard error stream @code{stderr} (@pxref{Standard Streams}).
+The filename and line number are taken from the C preprocessor macros
+@code{__FILE__} and @code{__LINE__} and specify where the call to
+@code{assert} was made.  When using the GNU C compiler, the name of
+the function which calls @code{assert} is taken from the built-in
+variable @code{__PRETTY_FUNCTION__}; with older compilers, the function
+name and following colon are omitted.
+
+If the preprocessor macro @code{NDEBUG} is defined before
+@file{assert.h} is included, the @code{assert} macro is defined to do
+absolutely nothing.
+
+@strong{Warning:} Even the argument expression @var{expression} is not
+evaluated if @code{NDEBUG} is in effect.  So never use @code{assert}
+with arguments that involve side effects.  For example, @code{assert
+(++i > 0);} is a bad idea, because @code{i} will not be incremented if
+@code{NDEBUG} is defined.
+@end deftypefn
+
+Sometimes the ``impossible'' condition you want to check for is an error
+return from an operating system function.  Then it is useful to display
+not only where the program crashes, but also what error was returned.
+The @code{assert_perror} macro makes this easy.
+
+@comment assert.h
+@comment GNU
+@deftypefn Macro void assert_perror (int @var{errnum})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c assert_fail_base calls asprintf, and fflushes stderr.
+Similar to @code{assert}, but verifies that @var{errnum} is zero.
+
+If @code{NDEBUG} is not defined, @code{assert_perror} tests the value of
+@var{errnum}.  If it is nonzero, @code{assert_perror} aborts the program
+after printing a message of the form:
+
+@smallexample
+@file{@var{file}}:@var{linenum}: @var{function}: @var{error text}
+@end smallexample
+
+@noindent
+on the standard error stream.  The file name, line number, and function
+name are as for @code{assert}.  The error text is the result of
+@w{@code{strerror (@var{errnum})}}.  @xref{Error Messages}.
+
+Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h}
+is included, the @code{assert_perror} macro does absolutely nothing.  It
+does not evaluate the argument, so @var{errnum} should not have any side
+effects.  It is best for @var{errnum} to be just a simple variable
+reference; often it will be @code{errno}.
+
+This macro is a GNU extension.
+@end deftypefn
+
+@strong{Usage note:} The @code{assert} facility is designed for
+detecting @emph{internal inconsistency}; it is not suitable for
+reporting invalid input or improper usage by the @emph{user} of the
+program.
+
+The information in the diagnostic messages printed by the @code{assert}
+and @code{assert_perror} macro is intended to help you, the programmer,
+track down the cause of a bug, but is not really useful for telling a user
+of your program why his or her input was invalid or why a command could not
+be carried out.  What's more, your program should not abort when given
+invalid input, as @code{assert} would do---it should exit with nonzero
+status (@pxref{Exit Status}) after printing its error messages, or perhaps
+read another command or move on to the next input file.
+
+@xref{Error Messages}, for information on printing error messages for
+problems that @emph{do not} represent bugs in the program.
+
+
+@node Variadic Functions
+@section Variadic Functions
+@cindex variable number of arguments
+@cindex variadic functions
+@cindex optional arguments
+
+@w{ISO C} defines a syntax for declaring a function to take a variable
+number or type of arguments.  (Such functions are referred to as
+@dfn{varargs functions} or @dfn{variadic functions}.)  However, the
+language itself provides no mechanism for such functions to access their
+non-required arguments; instead, you use the variable arguments macros
+defined in @file{stdarg.h}.
+
+This section describes how to declare variadic functions, how to write
+them, and how to call them properly.
+
+@strong{Compatibility Note:} Many older C dialects provide a similar,
+but incompatible, mechanism for defining functions with variable numbers
+of arguments, using @file{varargs.h}.
+
+@menu
+* Why Variadic::                Reasons for making functions take
+                                 variable arguments.
+* How Variadic::                How to define and call variadic functions.
+* Variadic Example::            A complete example.
+@end menu
+
+@node Why Variadic
+@subsection Why Variadic Functions are Used
+
+Ordinary C functions take a fixed number of arguments.  When you define
+a function, you specify the data type for each argument.  Every call to
+the function should supply the expected number of arguments, with types
+that can be converted to the specified ones.  Thus, if the function
+@samp{foo} is declared with @code{int foo (int, char *);} then you must
+call it with two arguments, a number (any kind will do) and a string
+pointer.
+
+But some functions perform operations that can meaningfully accept an
+unlimited number of arguments.
+
+In some cases a function can handle any number of values by operating on
+all of them as a block.  For example, consider a function that allocates
+a one-dimensional array with @code{malloc} to hold a specified set of
+values.  This operation makes sense for any number of values, as long as
+the length of the array corresponds to that number.  Without facilities
+for variable arguments, you would have to define a separate function for
+each possible array size.
+
+The library function @code{printf} (@pxref{Formatted Output}) is an
+example of another class of function where variable arguments are
+useful.  This function prints its arguments (which can vary in type as
+well as number) under the control of a format template string.
+
+These are good reasons to define a @dfn{variadic} function which can
+handle as many arguments as the caller chooses to pass.
+
+Some functions such as @code{open} take a fixed set of arguments, but
+occasionally ignore the last few.  Strict adherence to @w{ISO C} requires
+these functions to be defined as variadic; in practice, however, the GNU
+C compiler and most other C compilers let you define such a function to
+take a fixed set of arguments---the most it can ever use---and then only
+@emph{declare} the function as variadic (or not declare its arguments
+at all!).
+
+@node How Variadic
+@subsection How Variadic Functions are Defined and Used
+
+Defining and using a variadic function involves three steps:
+
+@itemize @bullet
+@item
+@emph{Define} the function as variadic, using an ellipsis
+(@samp{@dots{}}) in the argument list, and using special macros to
+access the variable arguments.  @xref{Receiving Arguments}.
+
+@item
+@emph{Declare} the function as variadic, using a prototype with an
+ellipsis (@samp{@dots{}}), in all the files which call it.
+@xref{Variadic Prototypes}.
+
+@item
+@emph{Call} the function by writing the fixed arguments followed by the
+additional variable arguments.  @xref{Calling Variadics}.
+@end itemize
+
+@menu
+* 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.
+@end menu
+
+@node Variadic Prototypes
+@subsubsection Syntax for Variable Arguments
+@cindex function prototypes (variadic)
+@cindex prototypes for variadic functions
+@cindex variadic function prototypes
+
+A function that accepts a variable number of arguments must be declared
+with a prototype that says so.   You write the fixed arguments as usual,
+and then tack on @samp{@dots{}} to indicate the possibility of
+additional arguments.  The syntax of @w{ISO C} requires at least one fixed
+argument before the @samp{@dots{}}.  For example,
+
+@smallexample
+int
+func (const char *a, int b, @dots{})
+@{
+  @dots{}
+@}
+@end smallexample
+
+@noindent
+defines a function @code{func} which returns an @code{int} and takes two
+required arguments, a @code{const char *} and an @code{int}.  These are
+followed by any number of anonymous arguments.
+
+@strong{Portability note:} For some C compilers, the last required
+argument must not be declared @code{register} in the function
+definition.  Furthermore, this argument's type must be
+@dfn{self-promoting}: that is, the default promotions must not change
+its type.  This rules out array and function types, as well as
+@code{float}, @code{char} (whether signed or not) and @w{@code{short int}}
+(whether signed or not).  This is actually an @w{ISO C} requirement.
+
+@node Receiving Arguments
+@subsubsection Receiving the Argument Values
+@cindex variadic function argument access
+@cindex arguments (variadic functions)
+
+Ordinary fixed arguments have individual names, and you can use these
+names to access their values.  But optional arguments have no
+names---nothing but @samp{@dots{}}.  How can you access them?
+
+@pindex stdarg.h
+The only way to access them is sequentially, in the order they were
+written, and you must use special macros from @file{stdarg.h} in the
+following three step process:
+
+@enumerate
+@item
+You initialize an argument pointer variable of type @code{va_list} using
+@code{va_start}.  The argument pointer when initialized points to the
+first optional argument.
+
+@item
+You access the optional arguments by successive calls to @code{va_arg}.
+The first call to @code{va_arg} gives you the first optional argument,
+the next call gives you the second, and so on.
+
+You can stop at any time if you wish to ignore any remaining optional
+arguments.  It is perfectly all right for a function to access fewer
+arguments than were supplied in the call, but you will get garbage
+values if you try to access too many arguments.
+
+@item
+You indicate that you are finished with the argument pointer variable by
+calling @code{va_end}.
+
+(In practice, with most C compilers, calling @code{va_end} does nothing.
+This is always true in the GNU C compiler.  But you might as well call
+@code{va_end} just in case your program is someday compiled with a peculiar
+compiler.)
+@end enumerate
+
+@xref{Argument Macros}, for the full definitions of @code{va_start},
+@code{va_arg} and @code{va_end}.
+
+Steps 1 and 3 must be performed in the function that accepts the
+optional arguments.  However, you can pass the @code{va_list} variable
+as an argument to another function and perform all or part of step 2
+there.
+
+You can perform the entire sequence of three steps multiple times
+within a single function invocation.  If you want to ignore the optional
+arguments, you can do these steps zero times.
+
+You can have more than one argument pointer variable if you like.  You
+can initialize each variable with @code{va_start} when you wish, and
+then you can fetch arguments with each argument pointer as you wish.
+Each argument pointer variable will sequence through the same set of
+argument values, but at its own pace.
+
+@strong{Portability note:} With some compilers, once you pass an
+argument pointer value to a subroutine, you must not keep using the same
+argument pointer value after that subroutine returns.  For full
+portability, you should just pass it to @code{va_end}.  This is actually
+an @w{ISO C} requirement, but most ANSI C compilers work happily
+regardless.
+
+@node How Many Arguments
+@subsubsection How Many Arguments Were Supplied
+@cindex number of arguments passed
+@cindex how many arguments
+@cindex arguments, how many
+
+There is no general way for a function to determine the number and type
+of the optional arguments it was called with.  So whoever designs the
+function typically designs a convention for the caller to specify the number
+and type of arguments.  It is up to you to define an appropriate calling
+convention for each variadic function, and write all calls accordingly.
+
+One kind of calling convention is to pass the number of optional
+arguments as one of the fixed arguments.  This convention works provided
+all of the optional arguments are of the same type.
+
+A similar alternative is to have one of the required arguments be a bit
+mask, with a bit for each possible purpose for which an optional
+argument might be supplied.  You would test the bits in a predefined
+sequence; if the bit is set, fetch the value of the next argument,
+otherwise use a default value.
+
+A required argument can be used as a pattern to specify both the number
+and types of the optional arguments.  The format string argument to
+@code{printf} is one example of this (@pxref{Formatted Output Functions}).
+
+Another possibility is to pass an ``end marker'' value as the last
+optional argument.  For example, for a function that manipulates an
+arbitrary number of pointer arguments, a null pointer might indicate the
+end of the argument list.  (This assumes that a null pointer isn't
+otherwise meaningful to the function.)  The @code{execl} function works
+in just this way; see @ref{Executing a File}.
+
+
+@node Calling Variadics
+@subsubsection Calling Variadic Functions
+@cindex variadic functions, calling
+@cindex calling variadic functions
+@cindex declaring variadic functions
+
+You don't have to do anything special to call a variadic function.
+Just put the arguments (required arguments, followed by optional ones)
+inside parentheses, separated by commas, as usual.  But you must declare
+the function with a prototype and know how the argument values are converted.
+
+In principle, functions that are @emph{defined} to be variadic must also
+be @emph{declared} to be variadic using a function prototype whenever
+you call them.  (@xref{Variadic Prototypes}, for how.)  This is because
+some C compilers use a different calling convention to pass the same set
+of argument values to a function depending on whether that function
+takes variable arguments or fixed arguments.
+
+In practice, the GNU C compiler always passes a given set of argument
+types in the same way regardless of whether they are optional or
+required.  So, as long as the argument types are self-promoting, you can
+safely omit declaring them.  Usually it is a good idea to declare the
+argument types for variadic functions, and indeed for all functions.
+But there are a few functions which it is extremely convenient not to
+have to declare as variadic---for example, @code{open} and
+@code{printf}.
+
+@cindex default argument promotions
+@cindex argument promotion
+Since the prototype doesn't specify types for optional arguments, in a
+call to a variadic function the @dfn{default argument promotions} are
+performed on the optional argument values.  This means the objects of
+type @code{char} or @w{@code{short int}} (whether signed or not) are
+promoted to either @code{int} or @w{@code{unsigned int}}, as
+appropriate; and that objects of type @code{float} are promoted to type
+@code{double}.  So, if the caller passes a @code{char} as an optional
+argument, it is promoted to an @code{int}, and the function can access
+it with @code{va_arg (@var{ap}, int)}.
+
+Conversion of the required arguments is controlled by the function
+prototype in the usual way: the argument expression is converted to the
+declared argument type as if it were being assigned to a variable of
+that type.
+
+@node Argument Macros
+@subsubsection Argument Access Macros
+
+Here are descriptions of the macros used to retrieve variable arguments.
+These macros are defined in the header file @file{stdarg.h}.
+@pindex stdarg.h
+
+@comment stdarg.h
+@comment ISO
+@deftp {Data Type} va_list
+The type @code{va_list} is used for argument pointer variables.
+@end deftp
+
+@comment stdarg.h
+@comment ISO
+@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last-required})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
+This macro initializes the argument pointer variable @var{ap} to point
+to the first of the optional arguments of the current function;
+@var{last-required} must be the last required argument to the function.
+@end deftypefn
+
+@comment stdarg.h
+@comment ISO
+@deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
+@safety{@prelim{}@mtsafe{@mtsrace{:ap}}@assafe{}@acunsafe{@acucorrupt{}}}
+@c This is no longer provided by glibc, but rather by the compiler.
+@c Unlike the other va_ macros, that either start/end the lifetime of
+@c the va_list object or don't modify it, this one modifies ap, and it
+@c may leave it in a partially updated state.
+The @code{va_arg} macro returns the value of the next optional argument,
+and modifies the value of @var{ap} to point to the subsequent argument.
+Thus, successive uses of @code{va_arg} return successive optional
+arguments.
+
+The type of the value returned by @code{va_arg} is @var{type} as
+specified in the call.  @var{type} must be a self-promoting type (not
+@code{char} or @code{short int} or @code{float}) that matches the type
+of the actual argument.
+@end deftypefn
+
+@comment stdarg.h
+@comment ISO
+@deftypefn {Macro} void va_end (va_list @var{ap})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
+This ends the use of @var{ap}.  After a @code{va_end} call, further
+@code{va_arg} calls with the same @var{ap} may not work.  You should invoke
+@code{va_end} before returning from the function in which @code{va_start}
+was invoked with the same @var{ap} argument.
+
+In @theglibc{}, @code{va_end} does nothing, and you need not ever
+use it except for reasons of portability.
+@refill
+@end deftypefn
+
+Sometimes it is necessary to parse the list of parameters more than once
+or one wants to remember a certain position in the parameter list.  To
+do this, one will have to make a copy of the current value of the
+argument.  But @code{va_list} is an opaque type and one cannot necessarily
+assign the value of one variable of type @code{va_list} to another variable
+of the same type.
+
+@comment stdarg.h
+@comment ISO
+@deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
+@deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
+The @code{va_copy} macro allows copying of objects of type
+@code{va_list} even if this is not an integral type.  The argument pointer
+in @var{dest} is initialized to point to the same argument as the
+pointer in @var{src}.
+
+This macro was added in ISO C99.  When building for strict conformance
+to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
+@code{__va_copy} is available as a GNU extension in any standards
+mode; before GCC 3.0, it was the only macro for this functionality.
+@end deftypefn
+
+If you want to use @code{va_copy} and be portable to pre-C99 systems,
+you should always be prepared for the
+possibility that this macro will not be available.  On architectures where a
+simple assignment is invalid, hopefully @code{va_copy} @emph{will} be available,
+so one should always write something like this if concerned about
+pre-C99 portability:
+
+@smallexample
+@{
+  va_list ap, save;
+  @dots{}
+#ifdef va_copy
+  va_copy (save, ap);
+#else
+  save = ap;
+#endif
+  @dots{}
+@}
+@end smallexample
+
+
+@node Variadic Example
+@subsection Example of a Variadic Function
+
+Here is a complete sample function that accepts a variable number of
+arguments.  The first argument to the function is the count of remaining
+arguments, which are added up and the result returned.  While trivial,
+this function is sufficient to illustrate how to use the variable
+arguments facility.
+
+@comment Yes, this example has been tested.
+@smallexample
+@include add.c.texi
+@end smallexample
+
+@node Null Pointer Constant
+@section Null Pointer Constant
+@cindex null pointer constant
+
+The null pointer constant is guaranteed not to point to any real object.
+You can assign it to any pointer variable since it has type @code{void
+*}.  The preferred way to write a null pointer constant is with
+@code{NULL}.
+
+@comment stddef.h
+@comment ISO
+@deftypevr Macro {void *} NULL
+This is a null pointer constant.
+@end deftypevr
+
+You can also use @code{0} or @code{(void *)0} as a null pointer
+constant, but using @code{NULL} is cleaner because it makes the purpose
+of the constant more evident.
+
+If you use the null pointer constant as a function argument, then for
+complete portability you should make sure that the function has a
+prototype declaration.  Otherwise, if the target machine has two
+different pointer representations, the compiler won't know which
+representation to use for that argument.  You can avoid the problem by
+explicitly casting the constant to the proper pointer type, but we
+recommend instead adding a prototype for the function you are calling.
+
+@node Important Data Types
+@section Important Data Types
+
+The result of subtracting two pointers in C is always an integer, but the
+precise data type varies from C compiler to C compiler.  Likewise, the
+data type of the result of @code{sizeof} also varies between compilers.
+ISO defines standard aliases for these two types, so you can refer to
+them in a portable fashion.  They are defined in the header file
+@file{stddef.h}.
+@pindex stddef.h
+
+@comment stddef.h
+@comment ISO
+@deftp {Data Type} ptrdiff_t
+This is the signed integer type of the result of subtracting two
+pointers.  For example, with the declaration @code{char *p1, *p2;}, the
+expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
+probably be one of the standard signed integer types (@w{@code{short
+int}}, @code{int} or @w{@code{long int}}), but might be a nonstandard
+type that exists only for this purpose.
+@end deftp
+
+@comment stddef.h
+@comment ISO
+@deftp {Data Type} size_t
+This is an unsigned integer type used to represent the sizes of objects.
+The result of the @code{sizeof} operator is of this type, and functions
+such as @code{malloc} (@pxref{Unconstrained Allocation}) and
+@code{memcpy} (@pxref{Copying Strings and Arrays}) accept arguments of
+this type to specify object sizes.  On systems using @theglibc{}, this
+will be @w{@code{unsigned int}} or @w{@code{unsigned long int}}.
+
+@strong{Usage Note:} @code{size_t} is the preferred way to declare any
+arguments or variables that hold the size of an object.
+@end deftp
+
+@strong{Compatibility Note:} Implementations of C before the advent of
+@w{ISO C} generally used @code{unsigned int} for representing object sizes
+and @code{int} for pointer subtraction results.  They did not
+necessarily define either @code{size_t} or @code{ptrdiff_t}.  Unix
+systems did define @code{size_t}, in @file{sys/types.h}, but the
+definition was usually a signed type.
+
+@node Data Type Measurements
+@section Data Type Measurements
+
+Most of the time, if you choose the proper C data type for each object
+in your program, you need not be concerned with just how it is
+represented or how many bits it uses.  When you do need such
+information, the C language itself does not provide a way to get it.
+The header files @file{limits.h} and @file{float.h} contain macros
+which give you this information in full detail.
+
+@menu
+* 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.
+@end menu
+
+@node Width of Type
+@subsection Computing the Width of an Integer Data Type
+@cindex integer type width
+@cindex width of integer type
+@cindex type measurements, integer
+
+The most common reason that a program needs to know how many bits are in
+an integer type is for using an array of @code{long int} as a bit vector.
+You can access the bit at index @var{n} with
+
+@smallexample
+vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
+@end smallexample
+
+@noindent
+provided you define @code{LONGBITS} as the number of bits in a
+@code{long int}.
+
+@pindex limits.h
+There is no operator in the C language that can give you the number of
+bits in an integer data type.  But you can compute it from the macro
+@code{CHAR_BIT}, defined in the header file @file{limits.h}.
+
+@table @code
+@comment limits.h
+@comment ISO
+@item CHAR_BIT
+This is the number of bits in a @code{char}---eight, on most systems.
+The value has type @code{int}.
+
+You can compute the number of bits in any data type @var{type} like
+this:
+
+@smallexample
+sizeof (@var{type}) * CHAR_BIT
+@end smallexample
+@end table
+
+@node Range of Type
+@subsection Range of an Integer Type
+@cindex integer type range
+@cindex range of integer type
+@cindex limits, integer types
+
+Suppose you need to store an integer value which can range from zero to
+one million.  Which is the smallest type you can use?  There is no
+general rule; it depends on the C compiler and target machine.  You can
+use the @samp{MIN} and @samp{MAX} macros in @file{limits.h} to determine
+which type will work.
+
+Each signed integer type has a pair of macros which give the smallest
+and largest values that it can hold.  Each unsigned integer type has one
+such macro, for the maximum value; the minimum value is, of course,
+zero.
+
+The values of these macros are all integer constant expressions.  The
+@samp{MAX} and @samp{MIN} macros for @code{char} and @w{@code{short
+int}} types have values of type @code{int}.  The @samp{MAX} and
+@samp{MIN} macros for the other types have values of the same type
+described by the macro---thus, @code{ULONG_MAX} has type
+@w{@code{unsigned long int}}.
+
+@comment Extra blank lines make it look better.
+@vtable @code
+@comment limits.h
+@comment ISO
+@item SCHAR_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed char}}.
+
+@comment limits.h
+@comment ISO
+@item SCHAR_MAX
+@comment limits.h
+@comment ISO
+@itemx UCHAR_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed char}} and @w{@code{unsigned char}}, respectively.
+
+@comment limits.h
+@comment ISO
+@item CHAR_MIN
+
+This is the minimum value that can be represented by a @code{char}.
+It's equal to @code{SCHAR_MIN} if @code{char} is signed, or zero
+otherwise.
+
+@comment limits.h
+@comment ISO
+@item CHAR_MAX
+
+This is the maximum value that can be represented by a @code{char}.
+It's equal to @code{SCHAR_MAX} if @code{char} is signed, or
+@code{UCHAR_MAX} otherwise.
+
+@comment limits.h
+@comment ISO
+@item SHRT_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+short int}}.  On most machines that @theglibc{} runs on,
+@code{short} integers are 16-bit quantities.
+
+@comment limits.h
+@comment ISO
+@item SHRT_MAX
+@comment limits.h
+@comment ISO
+@itemx USHRT_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed short int}} and @w{@code{unsigned short int}},
+respectively.
+
+@comment limits.h
+@comment ISO
+@item INT_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+int}}.  On most machines that @theglibc{} runs on, an @code{int} is
+a 32-bit quantity.
+
+@comment limits.h
+@comment ISO
+@item INT_MAX
+@comment limits.h
+@comment ISO
+@itemx UINT_MAX
+
+These are the maximum values that can be represented by, respectively,
+the type @w{@code{signed int}} and the type @w{@code{unsigned int}}.
+
+@comment limits.h
+@comment ISO
+@item LONG_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+long int}}.  On most machines that @theglibc{} runs on, @code{long}
+integers are 32-bit quantities, the same size as @code{int}.
+
+@comment limits.h
+@comment ISO
+@item LONG_MAX
+@comment limits.h
+@comment ISO
+@itemx ULONG_MAX
+
+These are the maximum values that can be represented by a
+@w{@code{signed long int}} and @code{unsigned long int}, respectively.
+
+@comment limits.h
+@comment ISO
+@item LLONG_MIN
+
+This is the minimum value that can be represented by a @w{@code{signed
+long long int}}.  On most machines that @theglibc{} runs on,
+@w{@code{long long}} integers are 64-bit quantities.
+
+@comment limits.h
+@comment ISO
+@item LLONG_MAX
+@comment limits.h
+@comment ISO
+@itemx ULLONG_MAX
+
+These are the maximum values that can be represented by a @code{signed
+long long int} and @code{unsigned long long int}, respectively.
+
+@comment limits.h
+@comment GNU
+@item LONG_LONG_MIN
+@comment limits.h
+@comment GNU
+@itemx LONG_LONG_MAX
+@comment limits.h
+@comment GNU
+@itemx ULONG_LONG_MAX
+These are obsolete names for @code{LLONG_MIN}, @code{LLONG_MAX}, and
+@code{ULLONG_MAX}.  They are only available if @code{_GNU_SOURCE} is
+defined (@pxref{Feature Test Macros}).  In GCC versions prior to 3.0,
+these were the only names available.
+
+@comment limits.h
+@comment GNU
+@item WCHAR_MAX
+
+This is the maximum value that can be represented by a @code{wchar_t}.
+@xref{Extended Char Intro}.
+@end vtable
+
+The header file @file{limits.h} also defines some additional constants
+that parameterize various operating system and file system limits.  These
+constants are described in @ref{System Configuration}.
+
+@node Floating Type Macros
+@subsection Floating Type Macros
+@cindex floating type measurements
+@cindex measurements of floating types
+@cindex type measurements, floating
+@cindex limits, floating types
+
+The specific representation of floating point numbers varies from
+machine to machine.  Because floating point numbers are represented
+internally as approximate quantities, algorithms for manipulating
+floating point data often need to take account of the precise details of
+the machine's floating point representation.
+
+Some of the functions in the C library itself need this information; for
+example, the algorithms for printing and reading floating point numbers
+(@pxref{I/O on Streams}) and for calculating trigonometric and
+irrational functions (@pxref{Mathematics}) use it to avoid round-off
+error and loss of accuracy.  User programs that implement numerical
+analysis techniques also often need this information in order to
+minimize or compute error bounds.
+
+The header file @file{float.h} describes the format used by your
+machine.
+
+@menu
+* Floating Point Concepts::     Definitions of terminology.
+* Floating Point Parameters::   Details of specific macros.
+* IEEE Floating Point::         The measurements for one common
+                                 representation.
+@end menu
+
+@node Floating Point Concepts
+@subsubsection Floating Point Representation Concepts
+
+This section introduces the terminology for describing floating point
+representations.
+
+You are probably already familiar with most of these concepts in terms
+of scientific or exponential notation for floating point numbers.  For
+example, the number @code{123456.0} could be expressed in exponential
+notation as @code{1.23456e+05}, a shorthand notation indicating that the
+mantissa @code{1.23456} is multiplied by the base @code{10} raised to
+power @code{5}.
+
+More formally, the internal representation of a floating point number
+can be characterized in terms of the following parameters:
+
+@itemize @bullet
+@item
+@cindex sign (of floating point number)
+The @dfn{sign} is either @code{-1} or @code{1}.
+
+@item
+@cindex base (of floating point number)
+@cindex radix (of floating point number)
+The @dfn{base} or @dfn{radix} for exponentiation, an integer greater
+than @code{1}.  This is a constant for a particular representation.
+
+@item
+@cindex exponent (of floating point number)
+The @dfn{exponent} to which the base is raised.  The upper and lower
+bounds of the exponent value are constants for a particular
+representation.
+
+@cindex bias (of floating point number exponent)
+Sometimes, in the actual bits representing the floating point number,
+the exponent is @dfn{biased} by adding a constant to it, to make it
+always be represented as an unsigned quantity.  This is only important
+if you have some reason to pick apart the bit fields making up the
+floating point number by hand, which is something for which @theglibc{}
+provides no support.  So this is ignored in the discussion that
+follows.
+
+@item
+@cindex mantissa (of floating point number)
+@cindex significand (of floating point number)
+The @dfn{mantissa} or @dfn{significand} is an unsigned integer which is a
+part of each floating point number.
+
+@item
+@cindex precision (of floating point number)
+The @dfn{precision} of the mantissa.  If the base of the representation
+is @var{b}, then the precision is the number of base-@var{b} digits in
+the mantissa.  This is a constant for a particular representation.
+
+@cindex hidden bit (of floating point number mantissa)
+Many floating point representations have an implicit @dfn{hidden bit} in
+the mantissa.  This is a bit which is present virtually in the mantissa,
+but not stored in memory because its value is always 1 in a normalized
+number.  The precision figure (see above) includes any hidden bits.
+
+Again, @theglibc{} provides no facilities for dealing with such
+low-level aspects of the representation.
+@end itemize
+
+The mantissa of a floating point number represents an implicit fraction
+whose denominator is the base raised to the power of the precision.  Since
+the largest representable mantissa is one less than this denominator, the
+value of the fraction is always strictly less than @code{1}.  The
+mathematical value of a floating point number is then the product of this
+fraction, the sign, and the base raised to the exponent.
+
+@cindex normalized floating point number
+We say that the floating point number is @dfn{normalized} if the
+fraction is at least @code{1/@var{b}}, where @var{b} is the base.  In
+other words, the mantissa would be too large to fit if it were
+multiplied by the base.  Non-normalized numbers are sometimes called
+@dfn{denormal}; they contain less precision than the representation
+normally can hold.
+
+If the number is not normalized, then you can subtract @code{1} from the
+exponent while multiplying the mantissa by the base, and get another
+floating point number with the same value.  @dfn{Normalization} consists
+of doing this repeatedly until the number is normalized.  Two distinct
+normalized floating point numbers cannot be equal in value.
+
+(There is an exception to this rule: if the mantissa is zero, it is
+considered normalized.  Another exception happens on certain machines
+where the exponent is as small as the representation can hold.  Then
+it is impossible to subtract @code{1} from the exponent, so a number
+may be normalized even if its fraction is less than @code{1/@var{b}}.)
+
+@node Floating Point Parameters
+@subsubsection Floating Point Parameters
+
+@pindex float.h
+These macro definitions can be accessed by including the header file
+@file{float.h} in your program.
+
+Macro names starting with @samp{FLT_} refer to the @code{float} type,
+while names beginning with @samp{DBL_} refer to the @code{double} type
+and names beginning with @samp{LDBL_} refer to the @code{long double}
+type.  (If GCC does not support @code{long double} as a distinct data
+type on a target machine then the values for the @samp{LDBL_} constants
+are equal to the corresponding constants for the @code{double} type.)
+
+Of these macros, only @code{FLT_RADIX} is guaranteed to be a constant
+expression.  The other macros listed here cannot be reliably used in
+places that require constant expressions, such as @samp{#if}
+preprocessing directives or in the dimensions of static arrays.
+
+Although the @w{ISO C} standard specifies minimum and maximum values for
+most of these parameters, the GNU C implementation uses whatever values
+describe the floating point representation of the target machine.  So in
+principle GNU C actually satisfies the @w{ISO C} requirements only if the
+target machine is suitable.  In practice, all the machines currently
+supported are suitable.
+
+@vtable @code
+@comment float.h
+@comment ISO
+@item FLT_ROUNDS
+This value characterizes the rounding mode for floating point addition.
+The following values indicate standard rounding modes:
+
+@need 750
+
+@table @code
+@item -1
+The mode is indeterminable.
+@item 0
+Rounding is towards zero.
+@item 1
+Rounding is to the nearest number.
+@item 2
+Rounding is towards positive infinity.
+@item 3
+Rounding is towards negative infinity.
+@end table
+
+@noindent
+Any other value represents a machine-dependent nonstandard rounding
+mode.
+
+On most machines, the value is @code{1}, in accordance with the IEEE
+standard for floating point.
+
+Here is a table showing how certain values round for each possible value
+of @code{FLT_ROUNDS}, if the other aspects of the representation match
+the IEEE single-precision standard.
+
+@smallexample
+                0      1             2             3
+ 1.00000003    1.0    1.0           1.00000012    1.0
+ 1.00000007    1.0    1.00000012    1.00000012    1.0
+-1.00000003   -1.0   -1.0          -1.0          -1.00000012
+-1.00000007   -1.0   -1.00000012   -1.0          -1.00000012
+@end smallexample
+
+@comment float.h
+@comment ISO
+@item FLT_RADIX
+This is the value of the base, or radix, of the exponent representation.
+This is guaranteed to be a constant expression, unlike the other macros
+described in this section.  The value is 2 on all machines we know of
+except the IBM 360 and derivatives.
+
+@comment float.h
+@comment ISO
+@item FLT_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating point
+mantissa for the @code{float} data type.  The following expression
+yields @code{1.0} (even though mathematically it should not) due to the
+limited number of mantissa digits:
+
+@smallexample
+float radix = FLT_RADIX;
+
+1.0f + 1.0f / radix / radix / @dots{} / radix
+@end smallexample
+
+@noindent
+where @code{radix} appears @code{FLT_MANT_DIG} times.
+
+@comment float.h
+@comment ISO
+@item DBL_MANT_DIG
+@itemx LDBL_MANT_DIG
+This is the number of base-@code{FLT_RADIX} digits in the floating point
+mantissa for the data types @code{double} and @code{long double},
+respectively.
+
+@comment Extra blank lines make it look better.
+@comment float.h
+@comment ISO
+@item FLT_DIG
+
+This is the number of decimal digits of precision for the @code{float}
+data type.  Technically, if @var{p} and @var{b} are the precision and
+base (respectively) for the representation, then the decimal precision
+@var{q} is the maximum number of decimal digits such that any floating
+point number with @var{q} base 10 digits can be rounded to a floating
+point number with @var{p} base @var{b} digits and back again, without
+change to the @var{q} decimal digits.
+
+The value of this macro is supposed to be at least @code{6}, to satisfy
+@w{ISO C}.
+
+@comment float.h
+@comment ISO
+@item DBL_DIG
+@itemx LDBL_DIG
+
+These are similar to @code{FLT_DIG}, but for the data types
+@code{double} and @code{long double}, respectively.  The values of these
+macros are supposed to be at least @code{10}.
+
+@comment float.h
+@comment ISO
+@item FLT_MIN_EXP
+This is the smallest possible exponent value for type @code{float}.
+More precisely, is the minimum negative integer such that the value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+normalized floating point number of type @code{float}.
+
+@comment float.h
+@comment ISO
+@item DBL_MIN_EXP
+@itemx LDBL_MIN_EXP
+
+These are similar to @code{FLT_MIN_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ISO
+@item FLT_MIN_10_EXP
+This is the minimum negative integer such that @code{10} raised to this
+power minus 1 can be represented as a normalized floating point number
+of type @code{float}.  This is supposed to be @code{-37} or even less.
+
+@comment float.h
+@comment ISO
+@item DBL_MIN_10_EXP
+@itemx LDBL_MIN_10_EXP
+These are similar to @code{FLT_MIN_10_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ISO
+@item FLT_MAX_EXP
+This is the largest possible exponent value for type @code{float}.  More
+precisely, this is the maximum positive integer such that value
+@code{FLT_RADIX} raised to this power minus 1 can be represented as a
+floating point number of type @code{float}.
+
+@comment float.h
+@comment ISO
+@item DBL_MAX_EXP
+@itemx LDBL_MAX_EXP
+These are similar to @code{FLT_MAX_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ISO
+@item FLT_MAX_10_EXP
+This is the maximum positive integer such that @code{10} raised to this
+power minus 1 can be represented as a normalized floating point number
+of type @code{float}.  This is supposed to be at least @code{37}.
+
+@comment float.h
+@comment ISO
+@item DBL_MAX_10_EXP
+@itemx LDBL_MAX_10_EXP
+These are similar to @code{FLT_MAX_10_EXP}, but for the data types
+@code{double} and @code{long double}, respectively.
+
+@comment float.h
+@comment ISO
+@item FLT_MAX
+
+The value of this macro is the maximum number representable in type
+@code{float}.  It is supposed to be at least @code{1E+37}.  The value
+has type @code{float}.
+
+The smallest representable number is @code{- FLT_MAX}.
+
+@comment float.h
+@comment ISO
+@item DBL_MAX
+@itemx LDBL_MAX
+
+These are similar to @code{FLT_MAX}, but for the data types
+@code{double} and @code{long double}, respectively.  The type of the
+macro's value is the same as the type it describes.
+
+@comment float.h
+@comment ISO
+@item FLT_MIN
+
+The value of this macro is the minimum normalized positive floating
+point number that is representable in type @code{float}.  It is supposed
+to be no more than @code{1E-37}.
+
+@comment float.h
+@comment ISO
+@item DBL_MIN
+@itemx LDBL_MIN
+
+These are similar to @code{FLT_MIN}, but for the data types
+@code{double} and @code{long double}, respectively.  The type of the
+macro's value is the same as the type it describes.
+
+@comment float.h
+@comment ISO
+@item FLT_EPSILON
+
+This is the difference between 1 and the smallest floating point
+number of type @code{float} that is greater than 1.  It's supposed to
+be no greater than @code{1E-5}.
+
+@comment float.h
+@comment ISO
+@item DBL_EPSILON
+@itemx LDBL_EPSILON
+
+These are similar to @code{FLT_EPSILON}, but for the data types
+@code{double} and @code{long double}, respectively.  The type of the
+macro's value is the same as the type it describes.  The values are not
+supposed to be greater than @code{1E-9}.
+@end vtable
+
+@node IEEE Floating Point
+@subsubsection IEEE Floating Point
+@cindex IEEE floating point representation
+@cindex floating point, IEEE
+
+Here is an example showing how the floating type measurements come out
+for the most common floating point representation, specified by the
+@cite{IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
+754-1985)}.  Nearly all computers designed since the 1980s use this
+format.
+
+The IEEE single-precision float representation uses a base of 2.  There
+is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
+precision is 24 base-2 digits), and an 8-bit exponent that can represent
+values in the range -125 to 128, inclusive.
+
+So, for an implementation that uses this representation for the
+@code{float} data type, appropriate values for the corresponding
+parameters are:
+
+@smallexample
+FLT_RADIX                             2
+FLT_MANT_DIG                         24
+FLT_DIG                               6
+FLT_MIN_EXP                        -125
+FLT_MIN_10_EXP                      -37
+FLT_MAX_EXP                         128
+FLT_MAX_10_EXP                      +38
+FLT_MIN                 1.17549435E-38F
+FLT_MAX                 3.40282347E+38F
+FLT_EPSILON             1.19209290E-07F
+@end smallexample
+
+Here are the values for the @code{double} data type:
+
+@smallexample
+DBL_MANT_DIG                         53
+DBL_DIG                              15
+DBL_MIN_EXP                       -1021
+DBL_MIN_10_EXP                     -307
+DBL_MAX_EXP                        1024
+DBL_MAX_10_EXP                      308
+DBL_MAX         1.7976931348623157E+308
+DBL_MIN         2.2250738585072014E-308
+DBL_EPSILON     2.2204460492503131E-016
+@end smallexample
+
+@node Structure Measurement
+@subsection Structure Field Offset Measurement
+
+You can use @code{offsetof} to measure the location within a structure
+type of a particular structure member.
+
+@comment stddef.h
+@comment ISO
+@deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is no longer provided by glibc, but rather by the compiler.
+This expands to an integer constant expression that is the offset of the
+structure member named @var{member} in the structure type @var{type}.
+For example, @code{offsetof (struct s, elem)} is the offset, in bytes,
+of the member @code{elem} in a @code{struct s}.
+
+This macro won't work if @var{member} is a bit field; you get an error
+from the C compiler in that case.
+@end deftypefn
diff --git a/ap/libc/glibc/glibc-2.23/manual/lgpl-2.1.texi b/ap/libc/glibc/glibc-2.23/manual/lgpl-2.1.texi
new file mode 100644
index 0000000..ab03d6c
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/lgpl-2.1.texi
@@ -0,0 +1,549 @@
+@c The GNU Lesser General Public License.
+@center Version 2.1, February 1999
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+as the successor of the GNU Library Public License, version 2, hence the
+version number 2.1.]
+@end display
+
+@subheading Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software---to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software---typically libraries---of the Free
+Software Foundation and other authors who decide to use it.  You can use
+it too, but we suggest you first think carefully about whether this
+license or the ordinary General Public License is the better strategy to
+use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of it
+in new free programs; and that you are informed that you can do these
+things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the @dfn{Lesser} General Public License because it
+does @emph{Less} to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+``work based on the library'' and a ``work that uses the library''.  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+@subheading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+@enumerate 0
+@item
+This License Agreement applies to any software library or other program
+which contains a notice placed by the copyright holder or other
+authorized party saying it may be distributed under the terms of this
+Lesser General Public License (also called ``this License'').  Each
+licensee is addressed as ``you''.
+
+  A ``library'' means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The ``Library'', below, refers to any such software library or work
+which has been distributed under these terms.  A ``work based on the
+Library'' means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term ``modification''.)
+
+  ``Source code'' for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+@item
+You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+@item
+You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+The modified work must itself be a software library.
+
+@item
+You must cause the files modified to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause the whole of the work to be licensed at no
+charge to all third parties under the terms of this License.
+
+@item
+If a facility in the modified Library refers to a function or a
+table of data to be supplied by an application program that uses
+the facility, other than as an argument passed when the facility
+is invoked, then you must make a good faith effort to ensure that,
+in the event an application does not supply such function or
+table, the facility still operates, and performs whatever part of
+its purpose remains meaningful.
+
+(For example, a function in a library to compute square roots has
+a purpose that is entirely well-defined independent of the
+application.  Therefore, Subsection 2d requires that any
+application-supplied function or table used by this function must
+be optional: if the application does not supply it, the square
+root function must still compute square roots.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+@item
+You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a ``work that uses the Library''.  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a ``work that uses the Library'' with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a ``work that uses the
+library''.  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a ``work that uses the Library'' uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+@item
+As an exception to the Sections above, you may also combine or
+link a ``work that uses the Library'' with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+@enumerate a
+@item
+Accompany the work with the complete corresponding
+machine-readable source code for the Library including whatever
+changes were used in the work (which must be distributed under
+Sections 1 and 2 above); and, if the work is an executable linked
+with the Library, with the complete machine-readable ``work that
+uses the Library'', as object code and/or source code, so that the
+user can modify the Library and then relink to produce a modified
+executable containing the modified Library.  (It is understood
+that the user who changes the contents of definitions files in the
+Library will not necessarily be able to recompile the application
+to use the modified definitions.)
+
+@item
+Use a suitable shared library mechanism for linking with the Library.  A
+suitable mechanism is one that (1) uses at run time a copy of the
+library already present on the user's computer system, rather than
+copying library functions into the executable, and (2) will operate
+properly with a modified version of the library, if the user installs
+one, as long as the modified version is interface-compatible with the
+version that the work was made with.
+
+@item
+Accompany the work with a written offer, valid for at
+least three years, to give the same user the materials
+specified in Subsection 6a, above, for a charge no more
+than the cost of performing this distribution.
+
+@item
+If distribution of the work is made by offering access to copy
+from a designated place, offer equivalent access to copy the above
+specified materials from the same place.
+
+@item
+Verify that the user has already received a copy of these
+materials or that you have already sent this user a copy.
+@end enumerate
+
+  For an executable, the required form of the ``work that uses the
+Library'' must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies the
+executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+@item
+You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+@enumerate a
+@item
+Accompany the combined library with a copy of the same work
+based on the Library, uncombined with any other library
+facilities.  This must be distributed under the terms of the
+Sections above.
+
+@item
+Give prominent notice with the combined library of the fact
+that part of it is a work based on the Library, and explaining
+where to find the accompanying uncombined form of the same work.
+@end enumerate
+
+@item
+You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+@item
+Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+``any later version'', you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+@item
+If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+@center @b{NO WARRANTY}
+
+@item
+BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+@end enumerate
+
+@subheading END OF TERMS AND CONDITIONS
+
+@page
+@subheading How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the library's name and an idea of what it does.}
+Copyright (C) @var{year}  @var{name of author}
+
+This library is free software; you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 2.1 of the License, or (at
+your option) any later version.
+
+This library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the library, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+`Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+@var{signature of Ty Coon}, 1 April 1990
+Ty Coon, President of Vice
+@end smallexample
+
+That's all there is to it!
diff --git a/ap/libc/glibc/glibc-2.23/manual/libc-texinfo.sh b/ap/libc/glibc/glibc-2.23/manual/libc-texinfo.sh
new file mode 100644
index 0000000..4d0a522
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/libc-texinfo.sh
@@ -0,0 +1,102 @@
+#!/bin/sh
+
+OUTDIR=$1
+shift
+
+# Create libc.texinfo from the chapter files.
+
+trap "rm -f ${OUTDIR}*.$$; exit 1" 1 2 15
+
+exec 3>${OUTDIR}incl.$$ 4>${OUTDIR}smenu.$$ 5>${OUTDIR}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
+}
+
+collect_nodes () {
+  egrep '^(@c )?@node.*Top' "$@" /dev/null | cut -d, -f-2 |
+  sed 's/@c //; 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] }' |
+  $AWK -f tsort.awk | sed 's/_/ /g'
+}
+
+# Emit "@set ADD-ON" for each add-on contributing a manual chapter.
+for addon in $2; do
+  addon=`basename $addon .texi`
+  echo >&3 "@set $addon"
+done
+
+collect_nodes $1 | build_menu
+
+if [ -n "$2" ]; then
+
+  { echo; echo 'Add-ons'; echo; } >&4
+
+  egrep '^(@c )?@node.*Top' `echo $2 /dev/null | tr ' ' '\n' | sort` |
+  cut -d, -f1 | sed 's/@c //;s/@node //' | build_menu
+
+fi
+
+{ echo; echo 'Appendices'; echo; } >&4
+
+collect_nodes $3 | build_menu
+
+exec 3>&- 4>&- 5>&-
+
+mv -f ${OUTDIR}incl.$$ ${OUTDIR}chapters.texi
+
+{
+ 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; }
+ ' ${OUTDIR}smenu.$$
+ cat <<EOF
+* Free Manuals::		 Free Software Needs Free Documentation.
+* Copying::                      The GNU Lesser General Public License says
+                                  how you can copy and share the GNU C Library.
+* Documentation License::        This manual is under the GNU Free
+                                  Documentation License.
+
+Indices
+
+* Concept Index::                Index of concepts and names.
+* Type Index::                   Index of types and type qualifiers.
+* Function Index::               Index of functions and function-like macros.
+* Variable Index::               Index of variables and variable-like macros.
+* File Index::                   Index of programs and files.
+
+ @detailmenu
+ --- The Detailed Node Listing ---
+EOF
+ cat ${OUTDIR}lmenu.$$
+ echo '@end detailmenu'
+ echo '@end menu'; } >${OUTDIR}top-menu.texi.$$
+mv -f ${OUTDIR}top-menu.texi.$$ ${OUTDIR}top-menu.texi
+
+rm -f ${OUTDIR}*.$$
diff --git a/ap/libc/glibc/glibc-2.23/manual/libc.texinfo b/ap/libc/glibc/glibc-2.23/manual/libc.texinfo
new file mode 100644
index 0000000..c4138db
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/libc.texinfo
@@ -0,0 +1,166 @@
+\input texinfo                  @c -*- Texinfo -*-
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename libc.info
+@settitle The GNU C Library
+@documentencoding UTF-8
+@c '@codequotebacktick on' and '@codequoteundirected on' require
+@c Texinfo 5.0 or later, so use the older equivalent @set variables
+@c supported in Texinfo 4.11 and later.
+@set txicodequoteundirected
+@set txicodequotebacktick
+
+@c setchapternewpage odd
+
+@include macros.texi
+
+@comment Tell install-info what to do.
+@dircategory Software libraries
+@direntry
+* Libc: (libc).                 C library.
+@end direntry
+@include dir-add.texi
+
+@include pkgvers.texi
+
+@c This tells texinfo.tex to use the real section titles in xrefs in
+@c place of the node name, when no section title is explicitly given.
+@set xref-automatic-section-title
+@c @smallbook
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@c Everything related to printed editions is disabled until we have
+@c resolved how to keep them in sync with the master sources of the
+@c manual.
+@c sold 0.06/1.09, print run out 21may96
+@c @set EDITION 0.13
+@c @set ISBN 1-882114-55-8
+
+@include version.texi
+
+@set FDL_VERSION 1.3
+
+@copying
+This file documents @theglibc{}.
+
+This is
+@c Disabled (printed editions, see above).
+@c Edition @value{EDITION} of
+@cite{The GNU C Library Reference Manual}, for version
+@ifset PKGVERSION_DEFAULT
+@value{VERSION}.
+@end ifset
+@ifclear PKGVERSION_DEFAULT
+@value{VERSION} @value{PKGVERSION}.
+@end ifclear
+
+Copyright @copyright{} 1993--2016 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version
+@value{FDL_VERSION} or any later version published by the Free
+Software Foundation; with the Invariant Sections being ``Free Software
+Needs Free Documentation'' and ``GNU Lesser General Public License'',
+the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover
+Texts as in (a) below.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.  Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
+@end copying
+
+@iftex
+@shorttitlepage The GNU C Library Reference Manual
+@end iftex
+@titlepage
+@center @titlefont{The GNU C Library}
+@sp 1
+@center @titlefont{Reference Manual}
+@sp 2
+@center Sandra Loosemore
+@center with
+@center Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper
+@sp 3
+@c Disabled (printed editions, see above).
+@c @center Edition @value{EDITION}
+@c @sp 1
+@center for version @value{VERSION}
+@ifclear PKGVERSION_DEFAULT
+@sp 1
+@center @value{PKGVERSION}
+@end ifclear
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@c Disabled (printed editions, see above).
+@c @sp 2
+@c Published by the @uref{http://www.fsf.org/, Free Software Foundation} @*
+@c ISBN @value{ISBN} @*
+
+@c Disabled (printed editions, see above).
+@c @sp 2
+@c Cover art for the Free Software Foundation's printed edition
+@c by Etienne Suvasa.
+
+@end titlepage
+
+@shortcontents
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Main Menu
+This is
+@c Disabled (printed editions, see above).
+@c Edition @value{EDITION} of
+@cite{The GNU C Library Reference Manual}, for Version @value{VERSION}
+@ifclear PKGVERSION_DEFAULT
+@value{PKGVERSION}
+@end ifclear
+of @theglibc{}.
+@end ifnottex
+
+@include top-menu.texi
+@include chapters.texi
+
+@node Free Manuals, Copying, Contributors, Top
+@appendix Free Software Needs Free Documentation
+@include freemanuals.texi
+
+@node Copying, Documentation License, Free Manuals, Top
+@appendix GNU Lesser General Public License
+@include lgpl-2.1.texi
+
+@node Documentation License, Concept Index, Copying, Top
+@appendix GNU Free Documentation License
+@cindex FDL, GNU Free Documentation License
+@include fdl-@value{FDL_VERSION}.texi
+
+@node Concept Index, Type Index, Documentation License, Top
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Type Index, Function Index, Concept Index, Top
+@unnumbered Type Index
+
+@printindex tp
+
+@node Function Index, Variable Index, Type Index, Top
+@unnumbered Function and Macro Index
+
+@printindex fn
+
+@node Variable Index, File Index, Function Index, Top
+@unnumbered Variable and Constant Macro Index
+
+@printindex vr
+
+@node File Index, , Variable Index, Top
+@unnumbered Program and File Index
+
+@printindex pg
+
+
+@bye
diff --git a/ap/libc/glibc/glibc-2.23/manual/libcbook.texi b/ap/libc/glibc/glibc-2.23/manual/libcbook.texi
new file mode 100644
index 0000000..b248304
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/libcbook.texi
@@ -0,0 +1,3 @@
+\input texinfo
+@finalout
+@include libc.texinfo
diff --git a/ap/libc/glibc/glibc-2.23/manual/libdl.texi b/ap/libc/glibc/glibc-2.23/manual/libdl.texi
new file mode 100644
index 0000000..e3fe045
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/libdl.texi
@@ -0,0 +1,10 @@
+@c FIXME these are undocumented:
+@c dladdr
+@c dladdr1
+@c dlclose
+@c dlerror
+@c dlinfo
+@c dlmopen
+@c dlopen
+@c dlsym
+@c dlvsym
diff --git a/ap/libc/glibc/glibc-2.23/manual/libm-err-tab.pl b/ap/libc/glibc/glibc-2.23/manual/libm-err-tab.pl
new file mode 100755
index 0000000..3846afc
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/libm-err-tab.pl
@@ -0,0 +1,233 @@
+#!/usr/bin/perl -w
+# Copyright (C) 1999-2016 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+# Contributed by Andreas Jaeger <aj@suse.de>, 1999.
+
+# The GNU C Library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+
+# The GNU C Library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with the GNU C Library; if not, see
+# <http://www.gnu.org/licenses/>.
+
+# Information about tests are stored in: %results
+# $results{$test}{"type"} is the result type, e.g. normal or complex.
+# In the following description $platform, $type and $float are:
+# - $platform is the used platform
+# - $type is either "normal", "real" (for the real part of a complex number)
+#   or "imag" (for the imaginary part # of a complex number).
+# - $float is either of float, ifloat, double, idouble, ldouble, ildouble;
+#   It represents the underlying floating point type (float, double or long
+#   double) and if inline functions (the leading i stands for inline)
+#   are used.
+# $results{$test}{$platform}{$type}{$float} is defined and has a delta
+# or 'fail' as value.
+
+use File::Find;
+
+use strict;
+
+use vars qw ($sources @platforms %pplatforms);
+use vars qw (%results @all_floats %suffices @all_functions);
+
+
+# all_floats is in output order and contains all recognised float types that
+# we're going to output
+@all_floats = ('float', 'double', 'ldouble');
+%suffices =
+  ( 'float' => 'f',
+    'double' => '',
+    'ldouble' => 'l'
+  );
+
+# Pretty description of platform
+%pplatforms =
+  ( "i386/fpu" => "ix86",
+    "generic" => "Generic",
+    "alpha/fpu" => "Alpha",
+    "ia64/fpu" => "IA64",
+    "m68k/fpu" => "M68k",
+    "mips/fpu" => "MIPS",
+    "powerpc/fpu" => "PowerPC",
+    "sparc/sparc32/fpu" => "Sparc 32-bit",
+    "sparc/sparc64/fpu" => "Sparc 64-bit",
+    "sh/sh4/fpu" => "SH4",
+    "s390/fpu" => "S/390",
+    "arm" => "ARM"
+  );
+
+@all_functions =
+  ( "acos", "acosh", "asin", "asinh", "atan", "atanh",
+    "atan2", "cabs", "cacos", "cacosh", "carg", "casin", "casinh",
+    "catan", "catanh", "cbrt", "ccos", "ccosh", "ceil", "cexp", "cimag",
+    "clog", "clog10", "conj", "copysign", "cos", "cosh", "cpow", "cproj",
+    "creal", "csin", "csinh", "csqrt", "ctan", "ctanh", "erf", "erfc",
+    "exp", "exp10", "exp2", "expm1", "fabs", "fdim", "floor", "fma",
+    "fmax", "fmin", "fmod", "frexp", "gamma", "hypot",
+    "ilogb", "j0", "j1", "jn", "lgamma", "lrint",
+    "llrint", "log", "log10", "log1p", "log2", "logb", "lround",
+    "llround", "modf", "nearbyint", "nextafter", "nexttoward", "pow",
+    "remainder", "remquo", "rint", "round", "scalb", "scalbn", "scalbln",
+    "sin", "sincos", "sinh", "sqrt", "tan", "tanh", "tgamma",
+    "trunc", "y0", "y1", "yn" );
+# fpclassify, isnormal, isfinite, isinf, isnan, issignaling, signbit,
+# isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered
+# are not tabulated.
+
+if ($#ARGV == 0) {
+  $sources = $ARGV[0];
+} else {
+  $sources = '/usr/src/cvs/libc';
+}
+
+find (\&find_files, $sources);
+
+@platforms = sort by_platforms @platforms;
+
+&print_all;
+
+sub find_files {
+  if ($_ eq 'libm-test-ulps') {
+    # print "Parsing $File::Find::name\n";
+    push @platforms, $File::Find::dir;
+    &parse_ulps ($File::Find::name, $File::Find::dir);
+  }
+}
+
+# Parse ulps file
+sub parse_ulps {
+  my ($file, $platform) = @_;
+  my ($test, $type, $float, $eps);
+
+  # $type has the following values:
+  # "normal": No complex variable
+  # "real": Real part of complex result
+  # "imag": Imaginary part of complex result
+  open ULP, $file  or die ("Can't open $file: $!");
+  while (<ULP>) {
+    chop;
+    # ignore comments and empty lines
+    next if /^#/;
+    next if /^\s*$/;
+    if (/^Function: /) {
+      if (/Real part of/) {
+	s/Real part of //;
+	$type = 'real';
+      } elsif (/Imaginary part of/) {
+	s/Imaginary part of //;
+	$type = 'imag';
+      } else {
+	$type = 'normal';
+      }
+      ($test) = ($_ =~ /^Function:\s*\"([a-zA-Z0-9_]+)\"/);
+      next;
+    }
+    if (/^i?(float|double|ldouble):/) {
+      ($float, $eps) = split /\s*:\s*/,$_,2;
+      if ($eps eq 'fail') {
+	$results{$test}{$platform}{$type}{$float} = 'fail';
+      } elsif ($eps eq "0") {
+	# ignore
+	next;
+      } elsif (!exists $results{$test}{$platform}{$type}{$float}
+	    || $results{$test}{$platform}{$type}{$float} ne 'fail') {
+	$results{$test}{$platform}{$type}{$float} = $eps;
+      }
+      if ($type =~ /^real|imag$/) {
+	$results{$test}{'type'} = 'complex';
+      } elsif ($type eq 'normal') {
+	$results{$test}{'type'} = 'normal';
+      }
+      next;
+    }
+    print "Skipping unknown entry: `$_'\n";
+  }
+  close ULP;
+}
+
+sub get_value {
+  my ($fct, $platform, $type, $float) = @_;
+
+  return (exists $results{$fct}{$platform}{$type}{$float}
+	  ? $results{$fct}{$platform}{$type}{$float} : "0");
+}
+
+sub canonicalize_platform {
+  my ($platform) = @_;
+
+  $platform =~ s|^(.*/sysdeps/)||;
+
+
+  return exists $pplatforms{$platform} ? $pplatforms{$platform} : $platform;
+}
+
+sub print_platforms {
+  my (@p) = @_;
+  my ($fct, $platform, $float, $first, $i, $platform_no, $platform_total);
+
+  print '@multitable {nexttowardf} ';
+  foreach (@p) {
+    print ' {1000 + i 1000}';
+  }
+  print "\n";
+
+  print '@item Function ';
+  foreach (@p) {
+    print ' @tab ';
+    print &canonicalize_platform ($_);
+  }
+  print "\n";
+
+
+  foreach $fct (@all_functions) {
+    foreach $float (@all_floats) {
+      print "\@item $fct$suffices{$float} ";
+      foreach $platform (@p) {
+	print ' @tab ';
+	if (exists $results{$fct}{$platform}{'normal'}{$float}
+	    || exists $results{$fct}{$platform}{'real'}{$float}
+	    || exists $results{$fct}{$platform}{'imag'}{$float}) {
+	  if ($results{$fct}{'type'} eq 'complex') {
+	    print &get_value ($fct, $platform, 'real', $float),
+	    ' + i ', &get_value ($fct, $platform, 'imag', $float);
+	  } else {
+	    print $results{$fct}{$platform}{'normal'}{$float};
+	  }
+	} else {
+	  print '-';
+	}
+      }
+      print "\n";
+    }
+  }
+
+  print "\@end multitable\n";
+}
+
+sub print_all {
+  my ($i, $max);
+
+  my ($columns) = 5;
+
+  # Print only 5 platforms at a time.
+  for ($i=0; $i < $#platforms; $i+=$columns) {
+    $max = $i+$columns-1 > $#platforms ? $#platforms : $i+$columns-1;
+    print_platforms (@platforms[$i .. $max]);
+  }
+}
+
+sub by_platforms {
+  my ($pa, $pb);
+
+  $pa = $pplatforms{$a} ? $pplatforms{$a} : $a;
+  $pb = $pplatforms{$b} ? $pplatforms{$b} : $b;
+
+  return $pa cmp $pb;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/llio.texi b/ap/libc/glibc/glibc-2.23/manual/llio.texi
new file mode 100644
index 0000000..019dea2
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/llio.texi
@@ -0,0 +1,4224 @@
+@node Low-Level I/O, File System Interface, I/O on Streams, Top
+@c %MENU% Low-level, less portable I/O
+@chapter Low-Level Input/Output
+
+This chapter describes functions for performing low-level input/output
+operations on file descriptors.  These functions include the primitives
+for the higher-level I/O functions described in @ref{I/O on Streams}, as
+well as functions for performing low-level control operations for which
+there are no equivalents on streams.
+
+Stream-level I/O is more flexible and usually more convenient;
+therefore, programmers generally use the descriptor-level functions only
+when necessary.  These are some of the usual reasons:
+
+@itemize @bullet
+@item
+For reading binary files in large chunks.
+
+@item
+For reading an entire file into core before parsing it.
+
+@item
+To perform operations other than data transfer, which can only be done
+with a descriptor.  (You can use @code{fileno} to get the descriptor
+corresponding to a stream.)
+
+@item
+To pass descriptors to a child process.  (The child can create its own
+stream to use a descriptor that it inherits, but cannot inherit a stream
+directly.)
+@end itemize
+
+@menu
+* Opening and Closing Files::           How to open and close file
+                                         descriptors.
+* I/O Primitives::                      Reading and writing data.
+* File Position Primitive::             Setting a descriptor's file
+                                         position.
+* Descriptors and Streams::             Converting descriptor to stream
+                                         or vice-versa.
+* Stream/Descriptor Precautions::       Precautions needed if you use both
+                                         descriptors and streams.
+* Scatter-Gather::                      Fast I/O to discontinuous 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.
+* Asynchronous I/O::                    Perform I/O in parallel.
+* Control Operations::                  Various other operations on file
+					 descriptors.
+* Duplicating Descriptors::             Fcntl commands for duplicating
+                                         file descriptors.
+* Descriptor Flags::                    Fcntl commands for manipulating
+                                         flags associated with file
+                                         descriptors.
+* File Status Flags::                   Fcntl commands for manipulating
+                                         flags associated with open files.
+* File Locks::                          Fcntl commands for implementing
+                                         file locking.
+* Open File Description Locks::         Fcntl commands for implementing
+                                         open file description locking.
+* Open File Description Locks Example:: An example of open file description lock
+                                         usage
+* Interrupt Input::                     Getting an asynchronous signal when
+                                         input arrives.
+* IOCTLs::                              Generic I/O Control operations.
+@end menu
+
+
+@node Opening and Closing Files
+@section Opening and Closing Files
+
+@cindex opening a file descriptor
+@cindex closing a file descriptor
+This section describes the primitives for opening and closing files
+using file descriptors.  The @code{open} and @code{creat} functions are
+declared in the header file @file{fcntl.h}, while @code{close} is
+declared in @file{unistd.h}.
+@pindex unistd.h
+@pindex fcntl.h
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+The @code{open} function creates and returns a new file descriptor for
+the file named by @var{filename}.  Initially, the file position
+indicator for the file is at the beginning of the file.  The argument
+@var{mode} (@pxref{Permission Bits}) is used only when a file is
+created, but it doesn't hurt to supply the argument in any case.
+
+The @var{flags} argument controls how the file is to be opened.  This is
+a bit mask; you create the value by the bitwise OR of the appropriate
+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 @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:
+
+@table @code
+@item EACCES
+The file exists but is not readable/writable as requested by the @var{flags}
+argument, the file does not exist and the directory is unwritable so
+it cannot be created.
+
+@item EEXIST
+Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
+exists.
+
+@item EINTR
+The @code{open} operation was interrupted by a signal.
+@xref{Interrupted Primitives}.
+
+@item EISDIR
+The @var{flags} argument specified write access, and the file is a directory.
+
+@item EMFILE
+The process has too many files open.
+The maximum number of file descriptors is controlled by the
+@code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
+
+@item ENFILE
+The entire system, or perhaps the file system which contains the
+directory, cannot support any additional open files at the moment.
+(This problem cannot happen on @gnuhurdsystems{}.)
+
+@item ENOENT
+The named file does not exist, and @code{O_CREAT} is not specified.
+
+@item ENOSPC
+The directory or file system that would contain the new file cannot be
+extended, because there is no disk space left.
+
+@item ENXIO
+@code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
+argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
+FIFOs}), and no process has the file open for reading.
+
+@item EROFS
+The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
+@code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
+or @code{O_CREAT} is set and the file does not already exist.
+@end table
+
+@c !!! umask
+
+If on a 32 bit machine the sources are translated with
+@code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
+descriptor opened in the large file mode which enables the file handling
+functions to use files up to @twoexp{63} bytes in size and offset from
+@minus{}@twoexp{63} to @twoexp{63}.  This happens transparently for the user
+since all of the lowlevel file handling functions are equally replaced.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{open} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{open} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{open} function is the underlying primitive for the @code{fopen}
+and @code{freopen} functions, that create streams.
+@end deftypefun
+
+@comment fcntl.h
+@comment Unix98
+@deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+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
+difference is that on 32 bit systems the file is opened in the
+large file mode.  I.e., file length and file offsets can exceed 31 bits.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{open}.  I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+replaces the old API.
+@end deftypefun
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+This function is obsolete.  The call:
+
+@smallexample
+creat (@var{filename}, @var{mode})
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
+@end smallexample
+
+If on a 32 bit machine the sources are translated with
+@code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
+descriptor opened in the large file mode which enables the file handling
+functions to use files up to @twoexp{63} in size and offset from
+@minus{}@twoexp{63} to @twoexp{63}.  This happens transparently for the user
+since all of the lowlevel file handling functions are equally replaced.
+@end deftypefn
+
+@comment fcntl.h
+@comment Unix98
+@deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+This function is similar to @code{creat}.  It returns a file descriptor
+which can be used to access the file named by @var{filename}.  The only
+the difference is that on 32 bit systems the file is opened in the
+large file mode.  I.e., file length and file offsets can exceed 31 bits.
+
+To use this file descriptor one must not use the normal operations but
+instead the counterparts named @code{*64}, e.g., @code{read64}.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{open}.  I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+replaces the old API.
+@end deftypefn
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int close (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+The function @code{close} closes the file descriptor @var{filedes}.
+Closing a file has the following consequences:
+
+@itemize @bullet
+@item
+The file descriptor is deallocated.
+
+@item
+Any record locks owned by the process on the file are unlocked.
+
+@item
+When all file descriptors associated with a pipe or FIFO have been closed,
+any unread data is discarded.
+@end itemize
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{close} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this, calls to @code{close} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The normal return value from @code{close} is @math{0}; a value of @math{-1}
+is returned in case of failure.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINTR
+The @code{close} call was interrupted by a signal.
+@xref{Interrupted Primitives}.
+Here is an example of how to handle @code{EINTR} properly:
+
+@smallexample
+TEMP_FAILURE_RETRY (close (desc));
+@end smallexample
+
+@item ENOSPC
+@itemx EIO
+@itemx EDQUOT
+When the file is accessed by NFS, these errors from @code{write} can sometimes
+not be detected until @code{close}.  @xref{I/O Primitives}, for details
+on their meaning.
+@end table
+
+Please note that there is @emph{no} separate @code{close64} function.
+This is not necessary since this function does not determine nor depend
+on the mode of the file.  The kernel which performs the @code{close}
+operation knows which mode the descriptor is used for and can handle
+this situation.
+@end deftypefun
+
+To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
+of trying to close its underlying file descriptor with @code{close}.
+This flushes any buffered output and updates the stream object to
+indicate that it is closed.
+
+@node I/O Primitives
+@section Input and Output Primitives
+
+This section describes the functions for performing primitive input and
+output operations on file descriptors: @code{read}, @code{write}, and
+@code{lseek}.  These functions are declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftp {Data Type} ssize_t
+This data type is used to represent the sizes of blocks that can be
+read or written in a single operation.  It is similar to @code{size_t},
+but must be a signed type.
+@end deftp
+
+@cindex reading from a file descriptor
+@comment unistd.h
+@comment POSIX.1
+@deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{read} function reads up to @var{size} bytes from the file
+with descriptor @var{filedes}, storing the results in the @var{buffer}.
+(This is not necessarily a character string, and no terminating null
+character is added.)
+
+@cindex end-of-file, on a file descriptor
+The return value is the number of bytes actually read.  This might be
+less than @var{size}; for example, if there aren't that many bytes left
+in the file or if there aren't that many bytes immediately available.
+The exact behavior depends on what kind of file it is.  Note that
+reading less than @var{size} bytes is not an error.
+
+A value of zero indicates end-of-file (except if the value of the
+@var{size} argument is also zero).  This is not considered an error.
+If you keep calling @code{read} while at end-of-file, it will keep
+returning zero and doing nothing else.
+
+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 @math{-1}.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EAGAIN
+Normally, when no input is immediately available, @code{read} waits for
+some input.  But if the @code{O_NONBLOCK} flag is set for the file
+(@pxref{File Status Flags}), @code{read} returns immediately without
+reading any data, and reports this error.
+
+@strong{Compatibility Note:} Most versions of BSD Unix use a different
+error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
+@code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
+which name you use.
+
+On some systems, reading a large amount of data from a character special
+file can also fail with @code{EAGAIN} if the kernel cannot find enough
+physical memory to lock down the user's pages.  This is limited to
+devices that transfer with direct memory access into the user's memory,
+which means it does not include terminals, since they always use
+separate buffers inside the kernel.  This problem never happens on
+@gnuhurdsystems{}.
+
+Any condition that could result in @code{EAGAIN} can instead result in a
+successful @code{read} which returns fewer bytes than requested.
+Calling @code{read} again immediately would result in @code{EAGAIN}.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor,
+or is not open for reading.
+
+@item EINTR
+@code{read} was interrupted by a signal while it was waiting for input.
+@xref{Interrupted Primitives}.  A signal will not necessary cause
+@code{read} to return @code{EINTR}; it may instead result in a
+successful @code{read} which returns fewer bytes than requested.
+
+@item EIO
+For many devices, and for disk files, this error code indicates
+a hardware error.
+
+@code{EIO} also occurs when a background process tries to read from the
+controlling terminal, and the normal action of stopping the process by
+sending it a @code{SIGTTIN} signal isn't working.  This might happen if
+the signal is being blocked or ignored, or because the process group is
+orphaned.  @xref{Job Control}, for more information about job control,
+and @ref{Signal Handling}, for information about signals.
+
+@item EINVAL
+In some systems, when reading from a character or block device, position
+and size offsets must be aligned to a particular block size.  This error
+indicates that the offsets were not properly aligned.
+@end table
+
+Please note that there is no function named @code{read64}.  This is not
+necessary since this function does not directly modify or handle the
+possibly wide file offset.  Since the kernel handles this state
+internally, the @code{read} function can be used for all cases.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{read} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this, calls to @code{read} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{read} function is the underlying primitive for all of the
+functions that read from streams, such as @code{fgetc}.
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is usually a safe syscall.  The sysdeps/posix fallback emulation
+@c is not MT-Safe because it uses lseek, read and lseek back, but is it
+@c used anywhere?
+The @code{pread} function is similar to the @code{read} function.  The
+first three arguments are identical, and the return values and error
+codes also correspond.
+
+The difference is the fourth argument and its handling.  The data block
+is not read from the current position of the file descriptor
+@code{filedes}.  Instead the data is read from the file starting at
+position @var{offset}.  The position of the file descriptor itself is
+not affected by the operation.  The value is the same as before the call.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pread} function is in fact @code{pread64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value of @code{pread} describes the number of bytes read.
+In the error case it returns @math{-1} like @code{read} does and the
+error codes are also the same, with these additions:
+
+@table @code
+@item EINVAL
+The value given for @var{offset} is negative and therefore illegal.
+
+@item ESPIPE
+The file descriptor @var{filedes} is associate with a pipe or a FIFO and
+this device does not allow positioning of the file pointer.
+@end table
+
+The function is an extension defined in the Unix Single Specification
+version 2.
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is usually a safe syscall.  The sysdeps/posix fallback emulation
+@c is not MT-Safe because it uses lseek64, read and lseek64 back, but is
+@c it used anywhere?
+This function is similar to the @code{pread} function.  The difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t} which makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{pread} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+@cindex writing to a file descriptor
+@comment unistd.h
+@comment POSIX.1
+@deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Some say write is thread-unsafe on Linux without O_APPEND.  In the VFS layer
+@c the vfs_write() does no locking around the acquisition of a file offset and
+@c therefore multiple threads / kernel tasks may race and get the same offset
+@c resulting in data loss.
+@c
+@c See:
+@c http://thread.gmane.org/gmane.linux.kernel/397980
+@c http://lwn.net/Articles/180387/
+@c
+@c The counter argument is that POSIX only says that the write starts at the
+@c file position and that the file position is updated *before* the function
+@c returns.  What that really means is that any expectation of atomic writes is
+@c strictly an invention of the interpretation of the reader.  Data loss could
+@c happen if two threads start the write at the same time.  Only writes that
+@c come after the return of another write are guaranteed to follow the other
+@c write.
+@c
+@c The other side of the coin is that POSIX goes on further to say in
+@c "2.9.7 Thread Interactions with Regular File Operations" that threads
+@c should never see interleaving sets of file operations, but it is insane
+@c to do anything like that because it kills performance, so you don't get
+@c those guarantees in Linux.
+@c
+@c So we mark it thread safe, it doesn't blow up, but you might loose
+@c data, and we don't strictly meet the POSIX requirements.
+@c
+@c The fix for file offsets racing was merged in 3.14, the commits were:
+@c 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4, and
+@c d7a15f8d0777955986a2ab00ab181795cab14b01.  Therefore after Linux 3.14 you
+@c should get mostly MT-safe writes.
+The @code{write} function writes up to @var{size} bytes from
+@var{buffer} to the file with descriptor @var{filedes}.  The data in
+@var{buffer} is not necessarily a character string and a null character is
+output like any other character.
+
+The return value is the number of bytes actually written.  This may be
+@var{size}, but can always be smaller.  Your program should always call
+@code{write} in a loop, iterating until all the data is written.
+
+Once @code{write} returns, the data is enqueued to be written and can be
+read back right away, but it is not necessarily written out to permanent
+storage immediately.  You can use @code{fsync} when you need to be sure
+your data has been permanently stored before continuing.  (It is more
+efficient for the system to batch up consecutive writes and do them all
+at once when convenient.  Normally they will always be written to disk
+within a minute or less.)  Modern systems provide another function
+@code{fdatasync} which guarantees integrity only for the file data and
+is therefore faster.
+@c !!! xref fsync, fdatasync
+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 @math{-1}.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EAGAIN
+Normally, @code{write} blocks until the write operation is complete.
+But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
+Operations}), it returns immediately without writing any data and
+reports this error.  An example of a situation that might cause the
+process to block on output is writing to a terminal device that supports
+flow control, where output has been suspended by receipt of a STOP
+character.
+
+@strong{Compatibility Note:} Most versions of BSD Unix use a different
+error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
+@code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
+which name you use.
+
+On some systems, writing a large amount of data from a character special
+file can also fail with @code{EAGAIN} if the kernel cannot find enough
+physical memory to lock down the user's pages.  This is limited to
+devices that transfer with direct memory access into the user's memory,
+which means it does not include terminals, since they always use
+separate buffers inside the kernel.  This problem does not arise on
+@gnuhurdsystems{}.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor,
+or is not open for writing.
+
+@item EFBIG
+The size of the file would become larger than the implementation can support.
+
+@item EINTR
+The @code{write} operation was interrupted by a signal while it was
+blocked waiting for completion.  A signal will not necessarily cause
+@code{write} to return @code{EINTR}; it may instead result in a
+successful @code{write} which writes fewer bytes than requested.
+@xref{Interrupted Primitives}.
+
+@item EIO
+For many devices, and for disk files, this error code indicates
+a hardware error.
+
+@item ENOSPC
+The device containing the file is full.
+
+@item EPIPE
+This error is returned when you try to write to a pipe or FIFO that
+isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
+signal is also sent to the process; see @ref{Signal Handling}.
+
+@item EINVAL
+In some systems, when writing to a character or block device, position
+and size offsets must be aligned to a particular block size.  This error
+indicates that the offsets were not properly aligned.
+@end table
+
+Unless you have arranged to prevent @code{EINTR} failures, you should
+check @code{errno} after each failing call to @code{write}, and if the
+error was @code{EINTR}, you should simply repeat the call.
+@xref{Interrupted Primitives}.  The easy way to do this is with the
+macro @code{TEMP_FAILURE_RETRY}, as follows:
+
+@smallexample
+nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
+@end smallexample
+
+Please note that there is no function named @code{write64}.  This is not
+necessary since this function does not directly modify or handle the
+possibly wide file offset.  Since the kernel handles this state
+internally the @code{write} function can be used for all cases.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{write} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this, calls to @code{write} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{write} function is the underlying primitive for all of the
+functions that write to streams, such as @code{fputc}.
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is usually a safe syscall.  The sysdeps/posix fallback emulation
+@c is not MT-Safe because it uses lseek, write and lseek back, but is it
+@c used anywhere?
+The @code{pwrite} function is similar to the @code{write} function.  The
+first three arguments are identical, and the return values and error codes
+also correspond.
+
+The difference is the fourth argument and its handling.  The data block
+is not written to the current position of the file descriptor
+@code{filedes}.  Instead the data is written to the file starting at
+position @var{offset}.  The position of the file descriptor itself is
+not affected by the operation.  The value is the same as before the call.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pwrite} function is in fact @code{pwrite64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value of @code{pwrite} describes the number of written bytes.
+In the error case it returns @math{-1} like @code{write} does and the
+error codes are also the same, with these additions:
+
+@table @code
+@item EINVAL
+The value given for @var{offset} is negative and therefore illegal.
+
+@item ESPIPE
+The file descriptor @var{filedes} is associated with a pipe or a FIFO and
+this device does not allow positioning of the file pointer.
+@end table
+
+The function is an extension defined in the Unix Single Specification
+version 2.
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is usually a safe syscall.  The sysdeps/posix fallback emulation
+@c is not MT-Safe because it uses lseek64, write and lseek64 back, but
+@c is it used anywhere?
+This function is similar to the @code{pwrite} function.  The difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t} which makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{pwrite} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+
+@node File Position Primitive
+@section Setting the File Position of a Descriptor
+
+Just as you can set the file position of a stream with @code{fseek}, you
+can set the file position of a descriptor with @code{lseek}.  This
+specifies the position in the file for the next @code{read} or
+@code{write} operation.  @xref{File Positioning}, for more information
+on the file position and what it means.
+
+To read the current file position value from a descriptor, use
+@code{lseek (@var{desc}, 0, SEEK_CUR)}.
+
+@cindex file positioning on a file descriptor
+@cindex positioning a file descriptor
+@cindex seeking on a file descriptor
+@comment unistd.h
+@comment POSIX.1
+@deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{lseek} function is used to change the file position of the
+file with descriptor @var{filedes}.
+
+The @var{whence} argument specifies how the @var{offset} should be
+interpreted, in the same way as for the @code{fseek} function, and it must
+be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
+@code{SEEK_END}.
+
+@table @code
+@item SEEK_SET
+Specifies that @var{offset} is a count of characters from the beginning
+of the file.
+
+@item SEEK_CUR
+Specifies that @var{offset} is a count of characters from the current
+file position.  This count may be positive or negative.
+
+@item SEEK_END
+Specifies that @var{offset} is a count of characters from the end of
+the file.  A negative count specifies a position within the current
+extent of the file; a positive count specifies a position past the
+current end.  If you set the position past the current end, and
+actually write data, you will extend the file with zeros up to that
+position.
+@end table
+
+The return value from @code{lseek} is normally the resulting file
+position, measured in bytes from the beginning of the file.
+You can use this feature together with @code{SEEK_CUR} to read the
+current file position.
+
+If you want to append to the file, setting the file position to the
+current end of file with @code{SEEK_END} is not sufficient.  Another
+process may write more data after you seek but before you write,
+extending the file so the position you write onto clobbers their data.
+Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
+
+You can set the file position past the current end of the file.  This
+does not by itself make the file longer; @code{lseek} never changes the
+file.  But subsequent output at that position will extend the file.
+Characters between the previous end of file and the new position are
+filled with zeros.  Extending the file in this way can create a
+``hole'': the blocks of zeros are not actually allocated on disk, so the
+file takes up less space than it appears to; it is then called a
+``sparse file''.
+@cindex sparse files
+@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 @math{-1}.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} is not a valid file descriptor.
+
+@item EINVAL
+The @var{whence} argument value is not valid, or the resulting
+file offset is not valid.  A file offset is invalid.
+
+@item ESPIPE
+The @var{filedes} corresponds to an object that cannot be positioned,
+such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
+only for pipes and FIFOs, but on @gnusystems{}, you always get
+@code{ESPIPE} if the object is not seekable.)
+@end table
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{lseek} function is in fact @code{lseek64} and the type
+@code{off_t} has 64 bits which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{lseek} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{lseek} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{lseek} function is the underlying primitive for the
+@code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
+@code{rewind} functions, which operate on streams instead of file
+descriptors.
+@end deftypefun
+
+@comment unistd.h
+@comment Unix98
+@deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to the @code{lseek} function.  The difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t} which makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bits machine this function is actually available under the name
+@code{lseek} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+You can have multiple descriptors for the same file if you open the file
+more than once, or if you duplicate a descriptor with @code{dup}.
+Descriptors that come from separate calls to @code{open} have independent
+file positions; using @code{lseek} on one descriptor has no effect on the
+other.  For example,
+
+@smallexample
+@group
+@{
+  int d1, d2;
+  char buf[4];
+  d1 = open ("foo", O_RDONLY);
+  d2 = open ("foo", O_RDONLY);
+  lseek (d1, 1024, SEEK_SET);
+  read (d2, buf, 4);
+@}
+@end group
+@end smallexample
+
+@noindent
+will read the first four characters of the file @file{foo}.  (The
+error-checking code necessary for a real program has been omitted here
+for brevity.)
+
+By contrast, descriptors made by duplication share a common file
+position with the original descriptor that was duplicated.  Anything
+which alters the file position of one of the duplicates, including
+reading or writing data, affects all of them alike.  Thus, for example,
+
+@smallexample
+@{
+  int d1, d2, d3;
+  char buf1[4], buf2[4];
+  d1 = open ("foo", O_RDONLY);
+  d2 = dup (d1);
+  d3 = dup (d2);
+  lseek (d3, 1024, SEEK_SET);
+  read (d1, buf1, 4);
+  read (d2, buf2, 4);
+@}
+@end smallexample
+
+@noindent
+will read four characters starting with the 1024'th character of
+@file{foo}, and then four more characters starting with the 1028'th
+character.
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} off_t
+This is a signed integer type used to represent file sizes.  In
+@theglibc{}, this type is no narrower than @code{int}.
+
+If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
+is transparently replaced by @code{off64_t}.
+@end deftp
+
+@comment sys/types.h
+@comment Unix98
+@deftp {Data Type} off64_t
+This type is used similar to @code{off_t}.  The difference is that even
+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
+@twoexp{63} bytes in length.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
+available under the name @code{off_t}.
+@end deftp
+
+These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
+of compatibility with older BSD systems.  They are defined in two
+different header files: @file{fcntl.h} and @file{sys/file.h}.
+
+@table @code
+@item L_SET
+An alias for @code{SEEK_SET}.
+
+@item L_INCR
+An alias for @code{SEEK_CUR}.
+
+@item L_XTND
+An alias for @code{SEEK_END}.
+@end table
+
+@node Descriptors and Streams
+@section Descriptors and Streams
+@cindex streams, and file descriptors
+@cindex converting file descriptor to stream
+@cindex extracting file descriptor from stream
+
+Given an open file descriptor, you can create a stream for it with the
+@code{fdopen} function.  You can get the underlying file descriptor for
+an existing stream with the @code{fileno} function.  These functions are
+declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment POSIX.1
+@deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+The @code{fdopen} function returns a new stream for the file descriptor
+@var{filedes}.
+
+The @var{opentype} argument is interpreted in the same way as for the
+@code{fopen} function (@pxref{Opening Streams}), except that
+the @samp{b} option is not permitted; this is because @gnusystems{} make no
+distinction between text and binary files.  Also, @code{"w"} and
+@code{"w+"} do not cause truncation of the file; these have an effect only
+when opening a file, and in this case the file has already been opened.
+You must make sure that the @var{opentype} argument matches the actual
+mode of the open file descriptor.
+
+The return value is the new stream.  If the stream cannot be created
+(for example, if the modes for the file indicated by the file descriptor
+do not permit the access specified by the @var{opentype} argument), a
+null pointer is returned instead.
+
+In some other systems, @code{fdopen} may fail to detect that the modes
+for file descriptor do not permit the access specified by
+@code{opentype}.  @Theglibc{} always checks for this.
+@end deftypefun
+
+For an example showing the use of the @code{fdopen} function,
+see @ref{Creating a Pipe}.
+
+@comment stdio.h
+@comment POSIX.1
+@deftypefun int fileno (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+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 @math{-1}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int fileno_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fileno_unlocked} function is equivalent to the @code{fileno}
+function except that it does not implicitly lock the stream if the state
+is @code{FSETLOCKING_INTERNAL}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@cindex standard file descriptors
+@cindex file descriptors, standard
+There are also symbolic constants defined in @file{unistd.h} for the
+file descriptors belonging to the standard streams @code{stdin},
+@code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@table @code
+@item STDIN_FILENO
+@vindex STDIN_FILENO
+This macro has value @code{0}, which is the file descriptor for
+standard input.
+@cindex standard input file descriptor
+
+@comment unistd.h
+@comment POSIX.1
+@item STDOUT_FILENO
+@vindex STDOUT_FILENO
+This macro has value @code{1}, which is the file descriptor for
+standard output.
+@cindex standard output file descriptor
+
+@comment unistd.h
+@comment POSIX.1
+@item STDERR_FILENO
+@vindex STDERR_FILENO
+This macro has value @code{2}, which is the file descriptor for
+standard error output.
+@end table
+@cindex standard error file descriptor
+
+@node Stream/Descriptor Precautions
+@section Dangers of Mixing Streams and Descriptors
+@cindex channels
+@cindex streams and descriptors
+@cindex descriptors and streams
+@cindex mixing descriptors and streams
+
+You can have multiple file descriptors and streams (let's call both
+streams and descriptors ``channels'' for short) connected to the same
+file, but you must take care to avoid confusion between channels.  There
+are two cases to consider: @dfn{linked} channels that share a single
+file position value, and @dfn{independent} channels that have their own
+file positions.
+
+It's best to use just one channel in your program for actual data
+transfer to any given file, except when all the access is for input.
+For example, if you open a pipe (something you can only do at the file
+descriptor level), either do all I/O with the descriptor, or construct a
+stream from the descriptor with @code{fdopen} and then do all I/O with
+the stream.
+
+@menu
+* 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.
+@end menu
+
+@node Linked Channels
+@subsection Linked Channels
+@cindex linked channels
+
+Channels that come from a single opening share the same file position;
+we call them @dfn{linked} channels.  Linked channels result when you
+make a stream from a descriptor using @code{fdopen}, when you get a
+descriptor from a stream with @code{fileno}, when you copy a descriptor
+with @code{dup} or @code{dup2}, and when descriptors are inherited
+during @code{fork}.  For files that don't support random access, such as
+terminals and pipes, @emph{all} channels are effectively linked.  On
+random-access files, all append-type output streams are effectively
+linked to each other.
+
+@cindex cleaning up a stream
+If you have been using a stream for I/O (or have just opened the stream),
+and you want to do I/O using
+another channel (either a stream or a descriptor) that is linked to it,
+you must first @dfn{clean up} the stream that you have been using.
+@xref{Cleaning Streams}.
+
+Terminating a process, or executing a new program in the process,
+destroys all the streams in the process.  If descriptors linked to these
+streams persist in other processes, their file positions become
+undefined as a result.  To prevent this, you must clean up the streams
+before destroying them.
+
+@node Independent Channels
+@subsection Independent Channels
+@cindex independent channels
+
+When you open channels (streams or descriptors) separately on a seekable
+file, each channel has its own file position.  These are called
+@dfn{independent channels}.
+
+The system handles each channel independently.  Most of the time, this
+is quite predictable and natural (especially for input): each channel
+can read or write sequentially at its own place in the file.  However,
+if some of the channels are streams, you must take these precautions:
+
+@itemize @bullet
+@item
+You should clean an output stream after use, before doing anything else
+that might read or write from the same part of the file.
+
+@item
+You should clean an input stream before reading data that may have been
+modified using an independent channel.  Otherwise, you might read
+obsolete data that had been in the stream's buffer.
+@end itemize
+
+If you do output to one channel at the end of the file, this will
+certainly leave the other independent channels positioned somewhere
+before the new end.  You cannot reliably set their file positions to the
+new end of file before writing, because the file can always be extended
+by another process between when you set the file position and when you
+write the data.  Instead, use an append-type descriptor or stream; they
+always output at the current end of the file.  In order to make the
+end-of-file position accurate, you must clean the output channel you
+were using, if it is a stream.
+
+It's impossible for two channels to have separate file pointers for a
+file that doesn't support random access.  Thus, channels for reading or
+writing such files are always linked, never independent.  Append-type
+channels are also always linked.  For these channels, follow the rules
+for linked channels; see @ref{Linked Channels}.
+
+@node Cleaning Streams
+@subsection Cleaning Streams
+
+You can use @code{fflush} to clean a stream in most
+cases.
+
+You can skip the @code{fflush} if you know the stream
+is already clean.  A stream is clean whenever its buffer is empty.  For
+example, an unbuffered stream is always clean.  An input stream that is
+at end-of-file is clean.  A line-buffered stream is clean when the last
+character output was a newline.  However, a just-opened input stream
+might not be clean, as its input buffer might not be empty.
+
+There is one case in which cleaning a stream is impossible on most
+systems.  This is when the stream is doing input from a file that is not
+random-access.  Such streams typically read ahead, and when the file is
+not random access, there is no way to give back the excess data already
+read.  When an input stream reads from a random-access file,
+@code{fflush} does clean the stream, but leaves the file pointer at an
+unpredictable place; you must set the file pointer before doing any
+further I/O.
+
+Closing an output-only stream also does @code{fflush}, so this is a
+valid way of cleaning an output stream.
+
+You need not clean a stream before using its descriptor for control
+operations such as setting terminal modes; these operations don't affect
+the file position and are not affected by it.  You can use any
+descriptor for these operations, and all channels are affected
+simultaneously.  However, text already ``output'' to a stream but still
+buffered by the stream will be subject to the new terminal modes when
+subsequently flushed.  To make sure ``past'' output is covered by the
+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 separated in memory.  Although this can be done easily enough
+with multiple calls to @code{read} and @code{write}, it is inefficient
+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.  @Theglibc{}
+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.
+
+@comment sys/uio.h
+@comment BSD
+@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
+
+@comment sys/uio.h
+@comment BSD
+@deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c The fallback sysdeps/posix implementation, used even on GNU/Linux
+@c with old kernels that lack a full readv/writev implementation, may
+@c malloc the buffer into which data is read, if the total read size is
+@c too large for alloca.
+
+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
+
+@comment sys/uio.h
+@comment BSD
+@deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c The fallback sysdeps/posix implementation, used even on GNU/Linux
+@c with old kernels that lack a full readv/writev implementation, may
+@c malloc the buffer from which data is written, if the total write size
+@c is too large for alloca.
+
+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 efficient than @code{read} or @code{write}, as only the regions
+of the file that a program actually accesses are loaded.  Accesses to
+not-yet-loaded parts of the mmapped region are handled in the same way as
+swapped out pages.
+
+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.  If the LFS interface is used the file size
+on 32-bit systems is not limited to 2GB (offsets are signed which
+reduces the addressable area of 4GB by half); the full 64-bit are
+available.
+
+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
+
+@vindex _SC_PAGESIZE
+@smallexample
+size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
+@end smallexample
+
+@noindent
+These functions are declared in @file{sys/mman.h}.
+
+@comment sys/mman.h
+@comment POSIX
+@deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The @code{mmap} function creates a new mapping, connected to bytes
+(@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on
+@var{filedes}.  A new reference for the file specified by @var{filedes}
+is created, which is not removed by closing the file.
+
+@var{address} gives a preferred starting address for the mapping.
+@code{NULL} expresses no preference.  Any previous mapping at that
+address is automatically removed.  The address you give may still be
+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 receive 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 efficient than using
+@code{malloc} for large blocks.  This is not an issue with @theglibc{},
+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
+@code{MAP_FAILED} 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
+
+@comment sys/mman.h
+@comment LFS
+@deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never
+@c is) would be thread-unsafe.
+The @code{mmap64} function is equivalent to the @code{mmap} function but
+the @var{offset} parameter is of type @code{off64_t}.  On 32-bit systems
+this allows the file associated with the @var{filedes} descriptor to be
+larger than 2GB.  @var{filedes} must be a descriptor returned from a
+call to @code{open64} or @code{fopen64} and @code{freopen64} where the
+descriptor is retrieved with @code{fileno}.
+
+When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
+function is actually available under the name @code{mmap}.  I.e., the
+new, extended API using 64 bit file sizes and offsets transparently
+replaces the old API.
+@end deftypefun
+
+@comment sys/mman.h
+@comment POSIX
+@deftypefun int munmap (void *@var{addr}, size_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@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 unmap multiple mappings in one command, or include unmapped
+space in the range.  It is also possible to unmap only part of an existing
+mapping.  However, only entire pages can be removed.  If @var{length} is not
+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
+
+@comment sys/mman.h
+@comment POSIX
+@deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+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 accessible to non-memory-mapped I/O, it
+is necessary 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
+
+@comment sys/mman.h
+@comment GNU
+@deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+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 with the length @var{new_length}.
+
+One option is possible, @code{MREMAP_MAYMOVE}.  If it is given in
+@var{flags}, the system may remove the existing mapping and create a new
+one of the desired length in another location.
+
+The address of the resulting mapping is returned, or @math{-1}.  Possible
+error codes include:
+
+@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 insufficient 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
+
+This function is only available on a few systems.  Except for performing
+optional optimizations one should not rely on this function.
+
+Not all file descriptors may be mapped.  Sockets, pipes, and most devices
+only allow sequential access and do not fit into the mapping abstraction.
+In addition, some regular files may not be mmapable, and older kernels may
+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}.
+
+@comment sys/mman.h
+@comment POSIX
+@deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function can be used to provide the system with @var{advice} about
+the intended usage patterns of the memory region starting at @var{addr}
+and extending @var{length} bytes.
+
+The valid BSD values for @var{advice} are:
+
+@table @code
+
+@item MADV_NORMAL
+The region should receive no further special treatment.
+
+@item MADV_RANDOM
+The region will be accessed via random page references.  The kernel
+should page-in the minimal number of pages for each page fault.
+
+@item MADV_SEQUENTIAL
+The region will be accessed via sequential page references.  This
+may cause the kernel to aggressively read-ahead, expecting further
+sequential references after any page fault within this region.
+
+@item MADV_WILLNEED
+The region will be needed.  The pages within this region may
+be pre-faulted in by the kernel.
+
+@item MADV_DONTNEED
+The region is no longer needed.  The kernel may free these pages,
+causing any changes to the pages to be lost, as well as swapped
+out pages to be discarded.
+
+@end table
+
+The POSIX names are slightly different, but with the same meanings:
+
+@table @code
+
+@item POSIX_MADV_NORMAL
+This corresponds with BSD's @code{MADV_NORMAL}.
+
+@item POSIX_MADV_RANDOM
+This corresponds with BSD's @code{MADV_RANDOM}.
+
+@item POSIX_MADV_SEQUENTIAL
+This corresponds with BSD's @code{MADV_SEQUENTIAL}.
+
+@item POSIX_MADV_WILLNEED
+This corresponds with BSD's @code{MADV_WILLNEED}.
+
+@item POSIX_MADV_DONTNEED
+This corresponds with BSD's @code{MADV_DONTNEED}.
+
+@end table
+
+@code{madvise} returns @math{0} for success and @math{-1} for
+error.  Errors include:
+@table @code
+
+@item EINVAL
+An invalid region was given, or the @var{advice} was invalid.
+
+@item EFAULT
+There is no existing mapping in at least part of the given region.
+
+@end table
+@end deftypefun
+
+@comment sys/mman.h
+@comment POSIX
+@deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
+@c   where_is_shmfs @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    statfs dup ok
+@c    setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c    getmntent_r dup @mtslocale @ascuheap @aculock @acsmem [no @asucorrupt @acucorrupt; exclusive stream]
+@c    strcmp dup ok
+@c    strlen dup ok
+@c    malloc dup @ascuheap @acsmem
+@c    mempcpy dup ok
+@c    endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  strlen dup ok
+@c  strchr dup ok
+@c  mempcpy dup ok
+@c  open dup @acsfd
+@c  fcntl dup ok
+@c  close dup @acsfd
+
+This function returns a file descriptor that can be used to allocate shared
+memory via mmap.  Unrelated processes can use same @var{name} to create or
+open existing shared memory objects.
+
+A @var{name} argument specifies the shared memory object to be opened.
+In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting
+with an optional slash but containing no other slashes.
+
+The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}.
+
+@code{shm_open} returns the file descriptor on success or @math{-1} on error.
+On failure @code{errno} is set.
+@end deftypefn
+
+@deftypefn Function int shm_unlink (const char *@var{name})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c shm_unlink @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_once(where_is_shmfs) dup @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
+@c  strlen dup ok
+@c  strchr dup ok
+@c  mempcpy dup ok
+@c  unlink dup ok
+
+This function is inverse of @code{shm_open} and removes the object with
+the given @var{name} previously created by @code{shm_open}.
+
+@code{shm_unlink} returns @math{0} on success or @math{-1} on error.
+On failure @code{errno} is set.
+@end deftypefn
+
+@node Waiting for I/O
+@section Waiting for Input or Output
+@cindex waiting for input or output
+@cindex multiplexing input
+@cindex input from multiple files
+
+Sometimes a program needs to accept input on multiple input channels
+whenever input arrives.  For example, some workstations may have devices
+such as a digitizing tablet, function button box, or dial box that are
+connected via normal asynchronous serial interfaces; good user interface
+style requires responding immediately to input on any device.  Another
+example is a program that acts as a server to several other processes
+via pipes or sockets.
+
+You cannot normally use @code{read} for this purpose, because this
+blocks the program until input is available on one particular file
+descriptor; input on other channels won't wake it up.  You could set
+nonblocking mode and poll each file descriptor in turn, but this is very
+inefficient.
+
+A better solution is to use the @code{select} function.  This blocks the
+program until input or output is ready on a specified set of file
+descriptors, or until a timer expires, whichever comes first.  This
+facility is declared in the header file @file{sys/types.h}.
+@pindex sys/types.h
+
+In the case of a server socket (@pxref{Listening}), we say that
+``input'' is available when there are pending connections that could be
+accepted (@pxref{Accepting Connections}).  @code{accept} for server
+sockets blocks and interacts with @code{select} just as @code{read} does
+for normal input.
+
+@cindex file descriptor sets, for @code{select}
+The file descriptor sets for the @code{select} function are specified
+as @code{fd_set} objects.  Here is the description of the data type
+and some macros for manipulating these objects.
+
+@comment sys/types.h
+@comment BSD
+@deftp {Data Type} fd_set
+The @code{fd_set} data type represents file descriptor sets for the
+@code{select} function.  It is actually a bit array.
+@end deftp
+
+@comment sys/types.h
+@comment BSD
+@deftypevr Macro int FD_SETSIZE
+The value of this macro is the maximum number of file descriptors that a
+@code{fd_set} object can hold information about.  On systems with a
+fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
+some systems, including GNU, there is no absolute limit on the number of
+descriptors open, but this macro still has a constant value which
+controls the number of bits in an @code{fd_set}; if you get a file
+descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
+that descriptor into an @code{fd_set}.
+@end deftypevr
+
+@comment sys/types.h
+@comment BSD
+@deftypefn Macro void FD_ZERO (fd_set *@var{set})
+@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
+This macro initializes the file descriptor set @var{set} to be the
+empty set.
+@end deftypefn
+
+@comment sys/types.h
+@comment BSD
+@deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
+@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
+@c Setting a bit isn't necessarily atomic, so there's a potential race
+@c here if set is not used exclusively.
+This macro adds @var{filedes} to the file descriptor set @var{set}.
+
+The @var{filedes} parameter must not have side effects since it is
+evaluated more than once.
+@end deftypefn
+
+@comment sys/types.h
+@comment BSD
+@deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
+@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
+@c Setting a bit isn't necessarily atomic, so there's a potential race
+@c here if set is not used exclusively.
+This macro removes @var{filedes} from the file descriptor set @var{set}.
+
+The @var{filedes} parameter must not have side effects since it is
+evaluated more than once.
+@end deftypefn
+
+@comment sys/types.h
+@comment BSD
+@deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set})
+@safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
+This macro returns a nonzero value (true) if @var{filedes} is a member
+of the file descriptor set @var{set}, and zero (false) otherwise.
+
+The @var{filedes} parameter must not have side effects since it is
+evaluated more than once.
+@end deftypefn
+
+Next, here is the description of the @code{select} function itself.
+
+@comment sys/types.h
+@comment BSD
+@deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout})
+@safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}}
+@c The select syscall is preferred, but pselect6 may be used instead,
+@c which requires converting timeout to a timespec and back.  The
+@c conversions are not atomic.
+The @code{select} function blocks the calling process until there is
+activity on any of the specified sets of file descriptors, or until the
+timeout period has expired.
+
+The file descriptors specified by the @var{read-fds} argument are
+checked to see if they are ready for reading; the @var{write-fds} file
+descriptors are checked to see if they are ready for writing; and the
+@var{except-fds} file descriptors are checked for exceptional
+conditions.  You can pass a null pointer for any of these arguments if
+you are not interested in checking for that kind of condition.
+
+A file descriptor is considered ready for reading if a @code{read}
+call will not block.  This usually includes the read offset being at
+the end of the file or there is an error to report.  A server socket
+is considered ready for reading if there is a pending connection which
+can be accepted with @code{accept}; @pxref{Accepting Connections}.  A
+client socket is ready for writing when its connection is fully
+established; @pxref{Connecting}.
+
+``Exceptional conditions'' does not mean errors---errors are reported
+immediately when an erroneous system call is executed, and do not
+constitute a state of the descriptor.  Rather, they include conditions
+such as the presence of an urgent message on a socket.  (@xref{Sockets},
+for information on urgent messages.)
+
+The @code{select} function checks only the first @var{nfds} file
+descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
+of this argument.
+
+The @var{timeout} specifies the maximum time to wait.  If you pass a
+null pointer for this argument, it means to block indefinitely until one
+of the file descriptors is ready.  Otherwise, you should provide the
+time in @code{struct timeval} format; see @ref{High-Resolution
+Calendar}.  Specify zero as the time (a @code{struct timeval} containing
+all zeros) if you want to find out which descriptors are ready without
+waiting if none are ready.
+
+The normal return value from @code{select} is the total number of ready file
+descriptors in all of the sets.  Each of the argument sets is overwritten
+with information about the descriptors that are ready for the corresponding
+operation.  Thus, to see if a particular descriptor @var{desc} has input,
+use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
+
+If @code{select} returns because the timeout period expires, it returns
+a value of zero.
+
+Any signal will cause @code{select} to return immediately.  So if your
+program uses signals, you can't rely on @code{select} to keep waiting
+for the full time specified.  If you want to be sure of waiting for a
+particular amount of time, you must check for @code{EINTR} and repeat
+the @code{select} with a newly calculated timeout based on the current
+time.  See the example below.  See also @ref{Interrupted Primitives}.
+
+If an error occurs, @code{select} returns @code{-1} and does not modify
+the argument file descriptor sets.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+One of the file descriptor sets specified an invalid file descriptor.
+
+@item EINTR
+The operation was interrupted by a signal.  @xref{Interrupted Primitives}.
+
+@item EINVAL
+The @var{timeout} argument is invalid; one of the components is negative
+or too large.
+@end table
+@end deftypefun
+
+@strong{Portability Note:}  The @code{select} function is a BSD Unix
+feature.
+
+Here is an example showing how you can use @code{select} to establish a
+timeout period for reading from a file descriptor.  The @code{input_timeout}
+function blocks the calling process until input is available on the
+file descriptor, or until the timeout period expires.
+
+@smallexample
+@include select.c.texi
+@end smallexample
+
+There is another example showing the use of @code{select} to multiplex
+input from multiple sockets in @ref{Server Example}.
+
+
+@node Synchronizing I/O
+@section Synchronizing I/O operations
+
+@cindex synchronizing
+In most modern operating systems, the normal I/O operations are not
+executed synchronously.  I.e., even if a @code{write} system call
+returns, this does not mean the data is actually written to the media,
+e.g., the disk.
+
+In situations where synchronization points are necessary, you can use
+special functions which ensure that all operations finish before
+they return.
+
+@comment unistd.h
+@comment X/Open
+@deftypefun void sync (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+A call to this function will not return as long as there is data which
+has not been written to the device.  All dirty buffers in the kernel will
+be written and so an overall consistent system can be achieved (if no
+other process in parallel writes data).
+
+A prototype for @code{sync} can be found in @file{unistd.h}.
+@end deftypefun
+
+Programs more often want to ensure that data written to a given file is
+committed, rather than all data in the system.  For this, @code{sync} is overkill.
+
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int fsync (int @var{fildes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fsync} function can be used to make sure all data associated with
+the open file @var{fildes} is written to the device associated with the
+descriptor.  The function call does not return unless all actions have
+finished.
+
+A prototype for @code{fsync} can be found in @file{unistd.h}.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{fsync} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this, calls to @code{fsync} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The return value of the function is zero if no error occurred.  Otherwise
+it is @math{-1} and the global variable @var{errno} is set to the
+following values:
+@table @code
+@item EBADF
+The descriptor @var{fildes} is not valid.
+
+@item EINVAL
+No synchronization is possible since the system does not implement this.
+@end table
+@end deftypefun
+
+Sometimes it is not even necessary to write all data associated with a
+file descriptor.  E.g., in database files which do not change in size it
+is enough to write all the file content data to the device.
+Meta-information, like the modification time etc., are not that important
+and leaving such information uncommitted does not prevent a successful
+recovering of the file in case of a problem.
+
+@comment unistd.h
+@comment POSIX
+@deftypefun int fdatasync (int @var{fildes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+When a call to the @code{fdatasync} function returns, it is ensured
+that all of the file data is written to the device.  For all pending I/O
+operations, the parts guaranteeing data integrity finished.
+
+Not all systems implement the @code{fdatasync} operation.  On systems
+missing this functionality @code{fdatasync} is emulated by a call to
+@code{fsync} since the performed actions are a superset of those
+required by @code{fdatasync}.
+
+The prototype for @code{fdatasync} is in @file{unistd.h}.
+
+The return value of the function is zero if no error occurred.  Otherwise
+it is @math{-1} and the global variable @var{errno} is set to the
+following values:
+@table @code
+@item EBADF
+The descriptor @var{fildes} is not valid.
+
+@item EINVAL
+No synchronization is possible since the system does not implement this.
+@end table
+@end deftypefun
+
+
+@node Asynchronous I/O
+@section Perform I/O Operations in Parallel
+
+The POSIX.1b standard defines a new set of I/O operations which can
+significantly reduce the time an application spends waiting at I/O.  The
+new functions allow a program to initiate one or more I/O operations and
+then immediately resume normal work while the I/O operations are
+executed in parallel.  This functionality is available if the
+@file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
+
+These functions are part of the library with realtime functions named
+@file{librt}.  They are not actually part of the @file{libc} binary.
+The implementation of these functions can be done using support in the
+kernel (if available) or using an implementation based on threads at
+userlevel.  In the latter case it might be necessary to link applications
+with the thread library @file{libpthread} in addition to @file{librt}.
+
+All AIO operations operate on files which were opened previously.  There
+might be arbitrarily many operations running for one file.  The
+asynchronous I/O operations are controlled using a data structure named
+@code{struct aiocb} (@dfn{AIO control block}).  It is defined in
+@file{aio.h} as follows.
+
+@comment aio.h
+@comment POSIX.1b
+@deftp {Data Type} {struct aiocb}
+The POSIX.1b standard mandates that the @code{struct aiocb} structure
+contains at least the members described in the following table.  There
+might be more elements which are used by the implementation, but
+depending upon these elements is not portable and is highly deprecated.
+
+@table @code
+@item int aio_fildes
+This element specifies the file descriptor to be used for the
+operation.  It must be a legal descriptor, otherwise the operation will
+fail.
+
+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
+like terminals where an @code{lseek} call would lead to an error.
+
+@item off_t aio_offset
+This element specifies the offset in the file at which the operation (input
+or output) is performed.  Since the operations are carried out in arbitrary
+order and more than one operation for one file descriptor can be
+started, one cannot expect a current read/write position of the file
+descriptor.
+
+@item volatile void *aio_buf
+This is a pointer to the buffer with the data to be written or the place
+where the read data is stored.
+
+@item size_t aio_nbytes
+This element specifies the length of the buffer pointed to by @code{aio_buf}.
+
+@item int aio_reqprio
+If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
+@code{_POSIX_PRIORITY_SCHEDULING}, the AIO requests are
+processed based on the current scheduling priority.  The
+@code{aio_reqprio} element can then be used to lower the priority of the
+AIO operation.
+
+@item struct sigevent aio_sigevent
+This element specifies how the calling process is notified once the
+operation terminates.  If the @code{sigev_notify} element is
+@code{SIGEV_NONE}, no notification is sent.  If it is @code{SIGEV_SIGNAL},
+the signal determined by @code{sigev_signo} is sent.  Otherwise,
+@code{sigev_notify} must be @code{SIGEV_THREAD}.  In this case, a thread
+is created which starts executing the function pointed to by
+@code{sigev_notify_function}.
+
+@item int aio_lio_opcode
+This element is only used by the @code{lio_listio} and
+@code{lio_listio64} functions.  Since these functions allow an
+arbitrary number of operations to start at once, and each operation can be
+input or output (or nothing), the information must be stored in the
+control block.  The possible values are:
+
+@vtable @code
+@item LIO_READ
+Start a read operation.  Read from the file at position
+@code{aio_offset} and store the next @code{aio_nbytes} bytes in the
+buffer pointed to by @code{aio_buf}.
+
+@item LIO_WRITE
+Start a write operation.  Write @code{aio_nbytes} bytes starting at
+@code{aio_buf} into the file starting at position @code{aio_offset}.
+
+@item LIO_NOP
+Do nothing for this control block.  This value is useful sometimes when
+an array of @code{struct aiocb} values contains holes, i.e., some of the
+values must not be handled although the whole array is presented to the
+@code{lio_listio} function.
+@end vtable
+@end table
+
+When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine, this type is in fact @code{struct aiocb64}, since the LFS
+interface transparently replaces the @code{struct aiocb} definition.
+@end deftp
+
+For use with the AIO functions defined in the LFS, there is a similar type
+defined which replaces the types of the appropriate members with larger
+types but otherwise is equivalent to @code{struct aiocb}.  Particularly,
+all member names are the same.
+
+@comment aio.h
+@comment POSIX.1b
+@deftp {Data Type} {struct aiocb64}
+@table @code
+@item int aio_fildes
+This element specifies the file descriptor which is used for the
+operation.  It must be a legal descriptor since otherwise the operation
+fails for obvious reasons.
+
+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
+like terminals where an @code{lseek} call would lead to an error.
+
+@item off64_t aio_offset
+This element specifies at which offset in the file the operation (input
+or output) is performed.  Since the operation are carried in arbitrary
+order and more than one operation for one file descriptor can be
+started, one cannot expect a current read/write position of the file
+descriptor.
+
+@item volatile void *aio_buf
+This is a pointer to the buffer with the data to be written or the place
+where the read data is stored.
+
+@item size_t aio_nbytes
+This element specifies the length of the buffer pointed to by @code{aio_buf}.
+
+@item int aio_reqprio
+If for the platform @code{_POSIX_PRIORITIZED_IO} and
+@code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
+processed based on the current scheduling priority.  The
+@code{aio_reqprio} element can then be used to lower the priority of the
+AIO operation.
+
+@item struct sigevent aio_sigevent
+This element specifies how the calling process is notified once the
+operation terminates.  If the @code{sigev_notify}, element is
+@code{SIGEV_NONE} no notification is sent.  If it is @code{SIGEV_SIGNAL},
+the signal determined by @code{sigev_signo} is sent.  Otherwise,
+@code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
+which starts executing the function pointed to by
+@code{sigev_notify_function}.
+
+@item int aio_lio_opcode
+This element is only used by the @code{lio_listio} and
+@code{[lio_listio64} functions.  Since these functions allow an
+arbitrary number of operations to start at once, and since each operation can be
+input or output (or nothing), the information must be stored in the
+control block.  See the description of @code{struct aiocb} for a description
+of the possible values.
+@end table
+
+When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine, this type is available under the name @code{struct
+aiocb64}, since the LFS transparently replaces the old interface.
+@end deftp
+
+@menu
+* 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::        Cancellation of AIO Operations.
+* Configuration of AIO::         How to optimize the AIO implementation.
+@end menu
+
+@node Asynchronous Reads/Writes
+@subsection Asynchronous Read and Write Operations
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_read (struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Calls aio_enqueue_request.
+@c aio_enqueue_request @asulock @ascuheap @aculock @acsmem
+@c  pthread_self ok
+@c  pthread_getschedparam @asulock @aculock
+@c   lll_lock (pthread descriptor's lock) @asulock @aculock
+@c   sched_getparam ok
+@c   sched_getscheduler ok
+@c   lll_unlock @aculock
+@c  pthread_mutex_lock (aio_requests_mutex) @asulock @aculock
+@c  get_elem @ascuheap @acsmem [@asucorrupt @acucorrupt]
+@c   realloc @ascuheap @acsmem
+@c   calloc @ascuheap @acsmem
+@c  aio_create_helper_thread @asulock @ascuheap @aculock @acsmem
+@c   pthread_attr_init ok
+@c   pthread_attr_setdetachstate ok
+@c   pthread_get_minstack ok
+@c   pthread_attr_setstacksize ok
+@c   sigfillset ok
+@c    memset ok
+@c    sigdelset ok
+@c   SYSCALL rt_sigprocmask ok
+@c   pthread_create @asulock @ascuheap @aculock @acsmem
+@c    lll_lock (default_pthread_attr_lock) @asulock @aculock
+@c    alloca/malloc @ascuheap @acsmem
+@c    lll_unlock @aculock
+@c    allocate_stack @asulock @ascuheap @aculock @acsmem
+@c     getpagesize dup
+@c     lll_lock (default_pthread_attr_lock) @asulock @aculock
+@c     lll_unlock @aculock
+@c     _dl_allocate_tls @ascuheap @acsmem
+@c      _dl_allocate_tls_storage @ascuheap @acsmem
+@c       memalign @ascuheap @acsmem
+@c       memset ok
+@c       allocate_dtv dup
+@c       free @ascuheap @acsmem
+@c      allocate_dtv @ascuheap @acsmem
+@c       calloc @ascuheap @acsmem
+@c       INSTALL_DTV ok
+@c     list_add dup
+@c     get_cached_stack
+@c      lll_lock (stack_cache_lock) @asulock @aculock
+@c      list_for_each ok
+@c      list_entry dup
+@c      FREE_P dup
+@c      stack_list_del dup
+@c      stack_list_add dup
+@c      lll_unlock @aculock
+@c      _dl_allocate_tls_init ok
+@c       GET_DTV ok
+@c     mmap ok
+@c     atomic_increment_val ok
+@c     munmap ok
+@c     change_stack_perm ok
+@c      mprotect ok
+@c     mprotect ok
+@c     stack_list_del dup
+@c     _dl_deallocate_tls dup
+@c     munmap ok
+@c    THREAD_COPY_STACK_GUARD ok
+@c    THREAD_COPY_POINTER_GUARD ok
+@c    atomic_exchange_acq ok
+@c    lll_futex_wake ok
+@c    deallocate_stack @asulock @ascuheap @aculock @acsmem
+@c     lll_lock (state_cache_lock) @asulock @aculock
+@c     stack_list_del ok
+@c      atomic_write_barrier ok
+@c      list_del ok
+@c      atomic_write_barrier ok
+@c     queue_stack @ascuheap @acsmem
+@c      stack_list_add ok
+@c       atomic_write_barrier ok
+@c       list_add ok
+@c       atomic_write_barrier ok
+@c      free_stacks @ascuheap @acsmem
+@c       list_for_each_prev_safe ok
+@c       list_entry ok
+@c       FREE_P ok
+@c       stack_list_del dup
+@c       _dl_deallocate_tls dup
+@c       munmap ok
+@c     _dl_deallocate_tls @ascuheap @acsmem
+@c      free @ascuheap @acsmem
+@c     lll_unlock @aculock
+@c    create_thread @asulock @ascuheap @aculock @acsmem
+@c     td_eventword
+@c     td_eventmask
+@c     do_clone @asulock @ascuheap @aculock @acsmem
+@c      PREPARE_CREATE ok
+@c      lll_lock (pd->lock) @asulock @aculock
+@c      atomic_increment ok
+@c      clone ok
+@c      atomic_decrement ok
+@c      atomic_exchange_acq ok
+@c      lll_futex_wake ok
+@c      deallocate_stack dup
+@c      sched_setaffinity ok
+@c      tgkill ok
+@c      sched_setscheduler ok
+@c     atomic_compare_and_exchange_bool_acq ok
+@c     nptl_create_event ok
+@c     lll_unlock (pd->lock) @aculock
+@c    free @ascuheap @acsmem
+@c   pthread_attr_destroy ok (cpuset won't be set, so free isn't called)
+@c  add_request_to_runlist ok
+@c  pthread_cond_signal ok
+@c  aio_free_request ok
+@c  pthread_mutex_unlock @aculock
+
+@c (in the new thread, initiated with clone)
+@c    start_thread ok
+@c     HP_TIMING_NOW ok
+@c     ctype_init @mtslocale
+@c     atomic_exchange_acq ok
+@c     lll_futex_wake ok
+@c     sigemptyset ok
+@c     sigaddset ok
+@c     setjmp ok
+@c     CANCEL_ASYNC -> pthread_enable_asynccancel ok
+@c      do_cancel ok
+@c       pthread_unwind ok
+@c        Unwind_ForcedUnwind or longjmp ok [@ascuheap @acsmem?]
+@c     lll_lock @asulock @aculock
+@c     lll_unlock @asulock @aculock
+@c     CANCEL_RESET -> pthread_disable_asynccancel ok
+@c      lll_futex_wait ok
+@c     ->start_routine ok -----
+@c     call_tls_dtors @asulock @ascuheap @aculock @acsmem
+@c      user-supplied dtor
+@c      rtld_lock_lock_recursive (dl_load_lock) @asulock @aculock
+@c      rtld_lock_unlock_recursive @aculock
+@c      free @ascuheap @acsmem
+@c     nptl_deallocate_tsd @ascuheap @acsmem
+@c      tsd user-supplied dtors ok
+@c      free @ascuheap @acsmem
+@c     libc_thread_freeres
+@c      libc_thread_subfreeres ok
+@c     atomic_decrement_and_test ok
+@c     td_eventword ok
+@c     td_eventmask ok
+@c     atomic_compare_exchange_bool_acq ok
+@c     nptl_death_event ok
+@c     lll_robust_dead ok
+@c     getpagesize ok
+@c     madvise ok
+@c     free_tcb @asulock @ascuheap @aculock @acsmem
+@c      free @ascuheap @acsmem
+@c      deallocate_stack @asulock @ascuheap @aculock @acsmem
+@c     lll_futex_wait ok
+@c     exit_thread_inline ok
+@c      syscall(exit) ok
+
+This function initiates an asynchronous read operation.  It
+immediately returns after the operation was enqueued or when an
+error was encountered.
+
+The first @code{aiocbp->aio_nbytes} bytes of the file for which
+@code{aiocbp->aio_fildes} is a descriptor are written to the buffer
+starting at @code{aiocbp->aio_buf}.  Reading starts at the absolute
+position @code{aiocbp->aio_offset} in the file.
+
+If prioritized I/O is supported by the platform the
+@code{aiocbp->aio_reqprio} value is used to adjust the priority before
+the request is actually enqueued.
+
+The calling process is notified about the termination of the read
+request according to the @code{aiocbp->aio_sigevent} value.
+
+When @code{aio_read} returns, the return value is zero if no error
+occurred that can be found before the process is enqueued.  If such an
+early error is found, the function returns @math{-1} and sets
+@code{errno} to one of the following values:
+
+@table @code
+@item EAGAIN
+The request was not enqueued due to (temporarily) exceeded resource
+limitations.
+@item ENOSYS
+The @code{aio_read} function is not implemented.
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
+need not be recognized before enqueueing the request and so this error
+might also be signaled asynchronously.
+@item EINVAL
+The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
+invalid.  This condition need not be recognized before enqueueing the
+request and so this error might also be signaled asynchronously.
+@end table
+
+If @code{aio_read} returns zero, the current status of the request
+can be queried using @code{aio_error} and @code{aio_return} functions.
+As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
+the operation has not yet completed.  If @code{aio_error} returns zero,
+the operation successfully terminated, otherwise the value is to be
+interpreted as an error code.  If the function terminated, the result of
+the operation can be obtained using a call to @code{aio_return}.  The
+returned value is the same as an equivalent call to @code{read} would
+have returned.  Possible error codes returned by @code{aio_error} are:
+
+@table @code
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid.
+@item ECANCELED
+The operation was canceled before the operation was finished
+(@pxref{Cancel AIO Operations})
+@item EINVAL
+The @code{aiocbp->aio_offset} value is invalid.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_read64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function is similar to the @code{aio_read} function.  The only
+difference is that on @w{32 bit} machines, the file descriptor should
+be opened in the large file mode.  Internally, @code{aio_read64} uses
+functionality equivalent to @code{lseek64} (@pxref{File Position
+Primitive}) to position the file descriptor correctly for the reading,
+as opposed to @code{lseek} functionality used in @code{aio_read}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is available under the name @code{aio_read} and so transparently
+replaces the interface for small files on 32 bit machines.
+@end deftypefun
+
+To write data asynchronously to a file, there exists an equivalent pair
+of functions with a very similar interface.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_write (struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function initiates an asynchronous write operation.  The function
+call immediately returns after the operation was enqueued or if before
+this happens an error was encountered.
+
+The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
+@code{aiocbp->aio_buf} are written to the file for which
+@code{aiocbp->aio_fildes} is a descriptor, starting at the absolute
+position @code{aiocbp->aio_offset} in the file.
+
+If prioritized I/O is supported by the platform, the
+@code{aiocbp->aio_reqprio} value is used to adjust the priority before
+the request is actually enqueued.
+
+The calling process is notified about the termination of the read
+request according to the @code{aiocbp->aio_sigevent} value.
+
+When @code{aio_write} returns, the return value is zero if no error
+occurred that can be found before the process is enqueued.  If such an
+early error is found the function returns @math{-1} and sets
+@code{errno} to one of the following values.
+
+@table @code
+@item EAGAIN
+The request was not enqueued due to (temporarily) exceeded resource
+limitations.
+@item ENOSYS
+The @code{aio_write} function is not implemented.
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
+may not be recognized before enqueueing the request, and so this error
+might also be signaled asynchronously.
+@item EINVAL
+The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqprio} value is
+invalid.  This condition may not be recognized before enqueueing the
+request and so this error might also be signaled asynchronously.
+@end table
+
+In the case @code{aio_write} returns zero, the current status of the
+request can be queried using @code{aio_error} and @code{aio_return}
+functions.  As long as the value returned by @code{aio_error} is
+@code{EINPROGRESS} the operation has not yet completed.  If
+@code{aio_error} returns zero, the operation successfully terminated,
+otherwise the value is to be interpreted as an error code.  If the
+function terminated, the result of the operation can be get using a call
+to @code{aio_return}.  The returned value is the same as an equivalent
+call to @code{read} would have returned.  Possible error codes returned
+by @code{aio_error} are:
+
+@table @code
+@item EBADF
+The @code{aiocbp->aio_fildes} descriptor is not valid.
+@item ECANCELED
+The operation was canceled before the operation was finished.
+(@pxref{Cancel AIO Operations})
+@item EINVAL
+The @code{aiocbp->aio_offset} value is invalid.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is in fact @code{aio_write64} since the LFS interface transparently
+replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function is similar to the @code{aio_write} function.  The only
+difference is that on @w{32 bit} machines the file descriptor should
+be opened in the large file mode.  Internally @code{aio_write64} uses
+functionality equivalent to @code{lseek64} (@pxref{File Position
+Primitive}) to position the file descriptor correctly for the writing,
+as opposed to @code{lseek} functionality used in @code{aio_write}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is available under the name @code{aio_write} and so transparently
+replaces the interface for small files on 32 bit machines.
+@end deftypefun
+
+Besides these functions with the more or less traditional interface,
+POSIX.1b also defines a function which can initiate more than one
+operation at a time, and which can handle freely mixed read and write
+operations.  It is therefore similar to a combination of @code{readv} and
+@code{writev}.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Call lio_listio_internal, that takes the aio_requests_mutex lock and
+@c enqueues each request.  Then, it waits for notification or prepares
+@c for it before releasing the lock.  Even though it performs memory
+@c allocation and locking of its own, it doesn't add any classes of
+@c safety issues that aren't already covered by aio_enqueue_request.
+The @code{lio_listio} function can be used to enqueue an arbitrary
+number of read and write requests at one time.  The requests can all be
+meant for the same file, all for different files or every solution in
+between.
+
+@code{lio_listio} gets the @var{nent} requests from the array pointed to
+by @var{list}.  The operation to be performed is determined by the
+@code{aio_lio_opcode} member in each element of @var{list}.  If this
+field is @code{LIO_READ} a read operation is enqueued, similar to a call
+of @code{aio_read} for this element of the array (except that the way
+the termination is signalled is different, as we will see below).  If
+the @code{aio_lio_opcode} member is @code{LIO_WRITE} a write operation
+is enqueued.  Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
+in which case this element of @var{list} is simply ignored.  This
+``operation'' is useful in situations where one has a fixed array of
+@code{struct aiocb} elements from which only a few need to be handled at
+a time.  Another situation is where the @code{lio_listio} call was
+canceled before all requests are processed (@pxref{Cancel AIO
+Operations}) and the remaining requests have to be reissued.
+
+The other members of each element of the array pointed to by
+@code{list} must have values suitable for the operation as described in
+the documentation for @code{aio_read} and @code{aio_write} above.
+
+The @var{mode} argument determines how @code{lio_listio} behaves after
+having enqueued all the requests.  If @var{mode} is @code{LIO_WAIT} it
+waits until all requests terminated.  Otherwise @var{mode} must be
+@code{LIO_NOWAIT} and in this case the function returns immediately after
+having enqueued all the requests.  In this case the caller gets a
+notification of the termination of all requests according to the
+@var{sig} parameter.  If @var{sig} is @code{NULL} no notification is
+send.  Otherwise a signal is sent or a thread is started, just as
+described in the description for @code{aio_read} or @code{aio_write}.
+
+If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
+is @math{0} when all requests completed successfully.  Otherwise the
+function return @math{-1} and @code{errno} is set accordingly.  To find
+out which request or requests failed one has to use the @code{aio_error}
+function on all the elements of the array @var{list}.
+
+In case @var{mode} is @code{LIO_NOWAIT}, the function returns @math{0} if
+all requests were enqueued correctly.  The current state of the requests
+can be found using @code{aio_error} and @code{aio_return} as described
+above.  If @code{lio_listio} returns @math{-1} in this mode, the
+global variable @code{errno} is set accordingly.  If a request did not
+yet terminate, a call to @code{aio_error} returns @code{EINPROGRESS}.  If
+the value is different, the request is finished and the error value (or
+@math{0}) is returned and the result of the operation can be retrieved
+using @code{aio_return}.
+
+Possible values for @code{errno} are:
+
+@table @code
+@item EAGAIN
+The resources necessary to queue all the requests are not available at
+the moment.  The error status for each element of @var{list} must be
+checked to determine which request failed.
+
+Another reason could be that the system wide limit of AIO requests is
+exceeded.  This cannot be the case for the implementation on @gnusystems{}
+since no arbitrary limits exist.
+@item EINVAL
+The @var{mode} parameter is invalid or @var{nent} is larger than
+@code{AIO_LISTIO_MAX}.
+@item EIO
+One or more of the request's I/O operations failed.  The error status of
+each request should be checked to determine which one failed.
+@item ENOSYS
+The @code{lio_listio} function is not supported.
+@end table
+
+If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
+a request, the error status for this request returned by
+@code{aio_error} is @code{ECANCELED}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is in fact @code{lio_listio64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function is similar to the @code{lio_listio} function.  The only
+difference is that on @w{32 bit} machines, the file descriptor should
+be opened in the large file mode.  Internally, @code{lio_listio64} uses
+functionality equivalent to @code{lseek64} (@pxref{File Position
+Primitive}) to position the file descriptor correctly for the reading or
+writing, as opposed to @code{lseek} functionality used in
+@code{lio_listio}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is available under the name @code{lio_listio} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+@node Status of AIO Operations
+@subsection Getting the Status of AIO Operations
+
+As already described in the documentation of the functions in the last
+section, it must be possible to get information about the status of an I/O
+request.  When the operation is performed truly asynchronously (as with
+@code{aio_read} and @code{aio_write} and with @code{lio_listio} when the
+mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a
+specific request already terminated and if so, what the result was.
+The following two functions allow you to get this kind of information.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_error (const struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function determines the error state of the request described by the
+@code{struct aiocb} variable pointed to by @var{aiocbp}.  If the
+request has not yet terminated the value returned is always
+@code{EINPROGRESS}.  Once the request has terminated the value
+@code{aio_error} returns is either @math{0} if the request completed
+successfully or it returns the value which would be stored in the
+@code{errno} variable if the request would have been done using
+@code{read}, @code{write}, or @code{fsync}.
+
+The function can return @code{ENOSYS} if it is not implemented.  It
+could also return @code{EINVAL} if the @var{aiocbp} parameter does not
+refer to an asynchronous operation whose return status is not yet known.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_error64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{aio_error} with the only difference
+that the argument is a reference to a variable of type @code{struct
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_error} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function can be used to retrieve the return status of the operation
+carried out by the request described in the variable pointed to by
+@var{aiocbp}.  As long as the error status of this request as returned
+by @code{aio_error} is @code{EINPROGRESS} the return of this function is
+undefined.
+
+Once the request is finished this function can be used exactly once to
+retrieve the return value.  Following calls might lead to undefined
+behavior.  The return value itself is the value which would have been
+returned by the @code{read}, @code{write}, or @code{fsync} call.
+
+The function can return @code{ENOSYS} if it is not implemented.  It
+could also return @code{EINVAL} if the @var{aiocbp} parameter does not
+refer to an asynchronous operation whose return status is not yet known.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_return64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{aio_return} with the only difference
+that the argument is a reference to a variable of type @code{struct
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_return} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+@node Synchronizing AIO Operations
+@subsection Getting into a Consistent State
+
+When dealing with asynchronous operations it is sometimes necessary to
+get into a consistent state.  This would mean for AIO that one wants to
+know whether a certain request or a group of request were processed.
+This could be done by waiting for the notification sent by the system
+after the operation terminated, but this sometimes would mean wasting
+resources (mainly computation time).  Instead POSIX.1b defines two
+functions which will help with most kinds of consistency.
+
+The @code{aio_fsync} and @code{aio_fsync64} functions are only available
+if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
+
+@cindex synchronizing
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c After fcntl to check that the FD is open, it calls
+@c aio_enqueue_request.
+Calling this function forces all I/O operations operating queued at the
+time of the function call operating on the file descriptor
+@code{aiocbp->aio_fildes} into the synchronized I/O completion state
+(@pxref{Synchronizing I/O}).  The @code{aio_fsync} function returns
+immediately but the notification through the method described in
+@code{aiocbp->aio_sigevent} will happen only after all requests for this
+file descriptor have terminated and the file is synchronized.  This also
+means that requests for this very same file descriptor which are queued
+after the synchronization request are not affected.
+
+If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
+to @code{fdatasync}.  Otherwise @var{op} should be @code{O_SYNC} and
+the synchronization happens as with @code{fsync}.
+
+As long as the synchronization has not happened, a call to
+@code{aio_error} with the reference to the object pointed to by
+@var{aiocbp} returns @code{EINPROGRESS}.  Once the synchronization is
+done @code{aio_error} return @math{0} if the synchronization was not
+successful.  Otherwise the value returned is the value to which the
+@code{fsync} or @code{fdatasync} function would have set the
+@code{errno} variable.  In this case nothing can be assumed about the
+consistency for the data written to this file descriptor.
+
+The return value of this function is @math{0} if the request was
+successfully enqueued.  Otherwise the return value is @math{-1} and
+@code{errno} is set to one of the following values:
+
+@table @code
+@item EAGAIN
+The request could not be enqueued due to temporary lack of resources.
+@item EBADF
+The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid.
+@item EINVAL
+The implementation does not support I/O synchronization or the @var{op}
+parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
+@item ENOSYS
+This function is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_fsync64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function is similar to @code{aio_fsync} with the only difference
+that the argument is a reference to a variable of type @code{struct
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_fsync} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+Another method of synchronization is to wait until one or more requests of a
+specific set terminated.  This could be achieved by the @code{aio_*}
+functions to notify the initiating process about the termination but in
+some situations this is not the ideal solution.  In a program which
+constantly updates clients somehow connected to the server it is not
+always the best solution to go round robin since some connections might
+be slow.  On the other hand letting the @code{aio_*} function notify the
+caller might also be not the best solution since whenever the process
+works on preparing data for on client it makes no sense to be
+interrupted by a notification since the new client will not be handled
+before the current client is served.  For situations like this
+@code{aio_suspend} should be used.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Take aio_requests_mutex, set up waitlist and requestlist, wait
+@c for completion or timeout, and release the mutex.
+When calling this function, the calling thread is suspended until at
+least one of the requests pointed to by the @var{nent} elements of the
+array @var{list} has completed.  If any of the requests has already
+completed at the time @code{aio_suspend} is called, the function returns
+immediately.  Whether a request has terminated or not is determined by
+comparing the error status of the request with @code{EINPROGRESS}.  If
+an element of @var{list} is @code{NULL}, the entry is simply ignored.
+
+If no request has finished, the calling process is suspended.  If
+@var{timeout} is @code{NULL}, the process is not woken until a request
+has finished.  If @var{timeout} is not @code{NULL}, the process remains
+suspended at least as long as specified in @var{timeout}.  In this case,
+@code{aio_suspend} returns with an error.
+
+The return value of the function is @math{0} if one or more requests
+from the @var{list} have terminated.  Otherwise the function returns
+@math{-1} and @code{errno} is set to one of the following values:
+
+@table @code
+@item EAGAIN
+None of the requests from the @var{list} completed in the time specified
+by @var{timeout}.
+@item EINTR
+A signal interrupted the @code{aio_suspend} function.  This signal might
+also be sent by the AIO implementation while signalling the termination
+of one of the requests.
+@item ENOSYS
+The @code{aio_suspend} function is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is in fact @code{aio_suspend64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+This function is similar to @code{aio_suspend} with the only difference
+that the argument is a reference to a variable of type @code{struct
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
+function is available under the name @code{aio_suspend} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+@node Cancel AIO Operations
+@subsection Cancellation of AIO Operations
+
+When one or more requests are asynchronously processed, it might be
+useful in some situations to cancel a selected operation, e.g., if it
+becomes obvious that the written data is no longer accurate and would
+have to be overwritten soon.  As an example, assume an application, which
+writes data in files in a situation where new incoming data would have
+to be written in a file which will be updated by an enqueued request.
+The POSIX AIO implementation provides such a function, but this function
+is not capable of forcing the cancellation of the request.  It is up to the
+implementation to decide whether it is possible to cancel the operation
+or not.  Therefore using this function is merely a hint.
+
+@comment aio.h
+@comment POSIX.1b
+@deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c After fcntl to check the fd is open, hold aio_requests_mutex, call
+@c aio_find_req_fd, aio_remove_request, then aio_notify and
+@c aio_free_request each request before releasing the lock.
+@c aio_notify calls aio_notify_only and free, besides cond signal or
+@c similar.  aio_notify_only calls pthread_attr_init,
+@c pthread_attr_setdetachstate, malloc, pthread_create,
+@c notify_func_wrapper, aio_sigqueue, getpid, raise.
+@c notify_func_wraper calls aio_start_notify_thread, free and then the
+@c notifier function.
+The @code{aio_cancel} function can be used to cancel one or more
+outstanding requests.  If the @var{aiocbp} parameter is @code{NULL}, the
+function tries to cancel all of the outstanding requests which would process
+the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
+is @var{fildes}).  If @var{aiocbp} is not @code{NULL}, @code{aio_cancel}
+attempts to cancel the specific request pointed to by @var{aiocbp}.
+
+For requests which were successfully canceled, the normal notification
+about the termination of the request should take place.  I.e., depending
+on the @code{struct sigevent} object which controls this, nothing
+happens, a signal is sent or a thread is started.  If the request cannot
+be canceled, it terminates the usual way after performing the operation.
+
+After a request is successfully canceled, a call to @code{aio_error} with
+a reference to this request as the parameter will return
+@code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
+If the request wasn't canceled and is still running the error status is
+still @code{EINPROGRESS}.
+
+The return value of the function is @code{AIO_CANCELED} if there were
+requests which haven't terminated and which were successfully canceled.
+If there is one or more requests left which couldn't be canceled, the
+return value is @code{AIO_NOTCANCELED}.  In this case @code{aio_error}
+must be used to find out which of the, perhaps multiple, requests (in
+@var{aiocbp} is @code{NULL}) weren't successfully canceled.  If all
+requests already terminated at the time @code{aio_cancel} is called the
+return value is @code{AIO_ALLDONE}.
+
+If an error occurred during the execution of @code{aio_cancel} the
+function returns @math{-1} and sets @code{errno} to one of the following
+values.
+
+@table @code
+@item EBADF
+The file descriptor @var{fildes} is not valid.
+@item ENOSYS
+@code{aio_cancel} is not implemented.
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is in fact @code{aio_cancel64} since the LFS interface
+transparently replaces the normal implementation.
+@end deftypefun
+
+@comment aio.h
+@comment Unix98
+@deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+This function is similar to @code{aio_cancel} with the only difference
+that the argument is a reference to a variable of type @code{struct
+aiocb64}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
+function is available under the name @code{aio_cancel} and so
+transparently replaces the interface for small files on 32 bit
+machines.
+@end deftypefun
+
+@node Configuration of AIO
+@subsection How to optimize the AIO implementation
+
+The POSIX standard does not specify how the AIO functions are
+implemented.  They could be system calls, but it is also possible to
+emulate them at userlevel.
+
+At the point of this writing, the available implementation is a userlevel
+implementation which uses threads for handling the enqueued requests.
+While this implementation requires making some decisions about
+limitations, hard limitations are something which is best avoided
+in @theglibc{}.  Therefore, @theglibc{} provides a means
+for tuning the AIO implementation according to the individual use.
+
+@comment aio.h
+@comment GNU
+@deftp {Data Type} {struct aioinit}
+This data type is used to pass the configuration or tunable parameters
+to the implementation.  The program has to initialize the members of
+this struct and pass it to the implementation using the @code{aio_init}
+function.
+
+@table @code
+@item int aio_threads
+This member specifies the maximal number of threads which may be used
+at any one time.
+@item int aio_num
+This number provides an estimate on the maximal number of simultaneously
+enqueued requests.
+@item int aio_locks
+Unused.
+@item int aio_usedba
+Unused.
+@item int aio_debug
+Unused.
+@item int aio_numusers
+Unused.
+@item int aio_reserved[2]
+Unused.
+@end table
+@end deftp
+
+@comment aio.h
+@comment GNU
+@deftypefun void aio_init (const struct aioinit *@var{init})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c All changes to global objects are guarded by aio_requests_mutex.
+This function must be called before any other AIO function.  Calling it
+is completely voluntary, as it is only meant to help the AIO
+implementation perform better.
+
+Before calling the @code{aio_init}, function the members of a variable of
+type @code{struct aioinit} must be initialized.  Then a reference to
+this variable is passed as the parameter to @code{aio_init} which itself
+may or may not pay attention to the hints.
+
+The function has no return value and no error cases are defined.  It is
+a extension which follows a proposal from the SGI implementation in
+@w{Irix 6}.  It is not covered by POSIX.1b or Unix98.
+@end deftypefun
+
+@node Control Operations
+@section Control Operations on Files
+
+@cindex control operations on files
+@cindex @code{fcntl} function
+This section describes how you can perform various other operations on
+file descriptors, such as inquiring about or setting flags describing
+the status of the file descriptor, manipulating record locks, and the
+like.  All of these operations are performed by the function @code{fcntl}.
+
+The second argument to the @code{fcntl} function is a command that
+specifies which operation to perform.  The function and macros that name
+various flags that are used with it are declared in the header file
+@file{fcntl.h}.  Many of these flags are also used by the @code{open}
+function; see @ref{Opening and Closing Files}.
+@pindex fcntl.h
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{fcntl} function performs the operation specified by
+@var{command} on the file descriptor @var{filedes}.  Some commands
+require additional arguments to be supplied.  These additional arguments
+and the return value and error conditions are given in the detailed
+descriptions of the individual commands.
+
+Briefly, here is a list of what the various commands are.
+
+@table @code
+@item F_DUPFD
+Duplicate the file descriptor (return another file descriptor pointing
+to the same open file).  @xref{Duplicating Descriptors}.
+
+@item F_GETFD
+Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
+
+@item F_SETFD
+Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
+
+@item F_GETFL
+Get flags associated with the open file.  @xref{File Status Flags}.
+
+@item F_SETFL
+Set flags associated with the open file.  @xref{File Status Flags}.
+
+@item F_GETLK
+Test a file lock.  @xref{File Locks}.
+
+@item F_SETLK
+Set or clear a file lock.  @xref{File Locks}.
+
+@item F_SETLKW
+Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
+
+@item F_OFD_GETLK
+Test an open file description lock.  @xref{Open File Description Locks}.
+Specific to Linux.
+
+@item F_OFD_SETLK
+Set or clear an open file description lock.  @xref{Open File Description Locks}.
+Specific to Linux.
+
+@item F_OFD_SETLKW
+Like @code{F_OFD_SETLK}, but block until lock is acquired.
+@xref{Open File Description Locks}.  Specific to Linux.
+
+@item F_GETOWN
+Get process or process group ID to receive @code{SIGIO} signals.
+@xref{Interrupt Input}.
+
+@item F_SETOWN
+Set process or process group ID to receive @code{SIGIO} signals.
+@xref{Interrupt Input}.
+@end table
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{fcntl} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{fcntl} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+@end deftypefun
+
+
+@node Duplicating Descriptors
+@section Duplicating Descriptors
+
+@cindex duplicating file descriptors
+@cindex redirecting input and output
+
+You can @dfn{duplicate} a file descriptor, or allocate another file
+descriptor that refers to the same open file as the original.  Duplicate
+descriptors share one file position and one set of file status flags
+(@pxref{File Status Flags}), but each has its own set of file descriptor
+flags (@pxref{Descriptor Flags}).
+
+The major use of duplicating a file descriptor is to implement
+@dfn{redirection} of input or output:  that is, to change the
+file or pipe that a particular file descriptor corresponds to.
+
+You can perform this operation using the @code{fcntl} function with the
+@code{F_DUPFD} command, but there are also convenient functions
+@code{dup} and @code{dup2} for duplicating descriptors.
+
+@pindex unistd.h
+@pindex fcntl.h
+The @code{fcntl} function and flags are declared in @file{fcntl.h},
+while prototypes for @code{dup} and @code{dup2} are in the header file
+@file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int dup (int @var{old})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function copies descriptor @var{old} to the first available
+descriptor number (the first number not currently open).  It is
+equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int dup2 (int @var{old}, int @var{new})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function copies the descriptor @var{old} to descriptor number
+@var{new}.
+
+If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
+does not close @var{new}.  Otherwise, the new duplicate of @var{old}
+replaces any previous meaning of descriptor @var{new}, as if @var{new}
+were closed first.
+
+If @var{old} and @var{new} are different numbers, and @var{old} is a
+valid descriptor number, then @code{dup2} is equivalent to:
+
+@smallexample
+close (@var{new});
+fcntl (@var{old}, F_DUPFD, @var{new})
+@end smallexample
+
+However, @code{dup2} does this atomically; there is no instant in the
+middle of calling @code{dup2} at which @var{new} is closed and not yet a
+duplicate of @var{old}.
+@end deftypefun
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_DUPFD
+This macro is used as the @var{command} argument to @code{fcntl}, to
+copy the file descriptor given as the first argument.
+
+The form of the call in this case is:
+
+@smallexample
+fcntl (@var{old}, F_DUPFD, @var{next-filedes})
+@end smallexample
+
+The @var{next-filedes} argument is of type @code{int} and specifies that
+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 @math{-1} indicates an
+error.  The following @code{errno} error conditions are defined for
+this command:
+
+@table @code
+@item EBADF
+The @var{old} argument is invalid.
+
+@item EINVAL
+The @var{next-filedes} argument is invalid.
+
+@item EMFILE
+There are no more file descriptors available---your program is already
+using the maximum.  In BSD and GNU, the maximum is controlled by a
+resource limit that can be changed; @pxref{Limits on Resources}, for
+more information about the @code{RLIMIT_NOFILE} limit.
+@end table
+
+@code{ENFILE} is not a possible error code for @code{dup2} because
+@code{dup2} does not create a new opening of a file; duplicate
+descriptors do not count toward the limit which @code{ENFILE}
+indicates.  @code{EMFILE} is possible because it refers to the limit on
+distinct descriptor numbers in use in one process.
+@end deftypevr
+
+Here is an example showing how to use @code{dup2} to do redirection.
+Typically, redirection of the standard streams (like @code{stdin}) is
+done by a shell or shell-like program before calling one of the
+@code{exec} functions (@pxref{Executing a File}) to execute a new
+program in a child process.  When the new program is executed, it
+creates and initializes the standard streams to point to the
+corresponding file descriptors, before its @code{main} function is
+invoked.
+
+So, to redirect standard input to a file, the shell could do something
+like:
+
+@smallexample
+pid = fork ();
+if (pid == 0)
+  @{
+    char *filename;
+    char *program;
+    int file;
+    @dots{}
+    file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
+    dup2 (file, STDIN_FILENO);
+    TEMP_FAILURE_RETRY (close (file));
+    execv (program, NULL);
+  @}
+@end smallexample
+
+There is also a more detailed example showing how to implement redirection
+in the context of a pipeline of processes in @ref{Launching Jobs}.
+
+
+@node Descriptor Flags
+@section File Descriptor Flags
+@cindex file descriptor flags
+
+@dfn{File descriptor flags} are miscellaneous attributes of a file
+descriptor.  These flags are associated with particular file
+descriptors, so that if you have created duplicate file descriptors
+from a single opening of a file, each descriptor has its own set of flags.
+
+Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
+which causes the descriptor to be closed if you use any of the
+@code{exec@dots{}} functions (@pxref{Executing a File}).
+
+The symbols in this section are defined in the header file
+@file{fcntl.h}.
+@pindex fcntl.h
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_GETFD
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should return the file descriptor flags associated
+with the @var{filedes} argument.
+
+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 @math{-1}.  The following
+@code{errno} error conditions are defined for this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+@end table
+@end deftypevr
+
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETFD
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set the file descriptor flags associated with the
+@var{filedes} argument.  This requires a third @code{int} argument to
+specify the new flags, so the form of the call is:
+
+@smallexample
+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 @math{-1}, which indicates an error.
+The flags and error conditions are the same as for the @code{F_GETFD}
+command.
+@end deftypevr
+
+The following macro is defined for use as a file descriptor flag with
+the @code{fcntl} function.  The value is an integer constant usable
+as a bit mask value.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int FD_CLOEXEC
+@cindex close-on-exec (file descriptor flag)
+This flag specifies that the file descriptor should be closed when
+an @code{exec} function is invoked; see @ref{Executing a File}.  When
+a file descriptor is allocated (as with @code{open} or @code{dup}),
+this bit is initially cleared on the new file descriptor, meaning that
+descriptor will survive into the new program after @code{exec}.
+@end deftypevr
+
+If you want to modify the file descriptor flags, you should get the
+current flags with @code{F_GETFD} and modify the value.  Don't assume
+that the flags listed here are the only ones that are implemented; your
+program may be run years from now and more flags may exist then.  For
+example, here is a function to set or clear the flag @code{FD_CLOEXEC}
+without altering any other flags:
+
+@smallexample
+/* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
+   @r{or clear the flag if @var{value} is 0.}
+   @r{Return 0 on success, or -1 on error with @code{errno} set.} */
+
+int
+set_cloexec_flag (int desc, int value)
+@{
+  int oldflags = fcntl (desc, F_GETFD, 0);
+  /* @r{If reading the flags failed, return error indication now.} */
+  if (oldflags < 0)
+    return oldflags;
+  /* @r{Set just the flag we want to set.} */
+  if (value != 0)
+    oldflags |= FD_CLOEXEC;
+  else
+    oldflags &= ~FD_CLOEXEC;
+  /* @r{Store modified flag word in the descriptor.} */
+  return fcntl (desc, F_SETFD, oldflags);
+@}
+@end smallexample
+
+@node File Status Flags
+@section File Status Flags
+@cindex file status flags
+
+@dfn{File status flags} are used to specify attributes of the opening of a
+file.  Unlike the file descriptor flags discussed in @ref{Descriptor
+Flags}, the file status flags are shared by duplicated file descriptors
+resulting from a single opening of the file.  The file status flags are
+specified with the @var{flags} argument to @code{open};
+@pxref{Opening and Closing Files}.
+
+File status flags fall into three categories, which are described in the
+following sections.
+
+@itemize @bullet
+@item
+@ref{Access Modes}, specify what type of access is allowed to the
+file: reading, writing, or both.  They are set by @code{open} and are
+returned by @code{fcntl}, but cannot be changed.
+
+@item
+@ref{Open-time Flags}, control details of what @code{open} will do.
+These flags are not preserved after the @code{open} call.
+
+@item
+@ref{Operating Modes}, affect how operations such as @code{read} and
+@code{write} are done.  They are set by @code{open}, and can be fetched or
+changed with @code{fcntl}.
+@end itemize
+
+The symbols in this section are defined in the header file
+@file{fcntl.h}.
+@pindex fcntl.h
+
+@menu
+* 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.
+@end menu
+
+@node Access Modes
+@subsection File Access Modes
+
+The file access modes allow a file descriptor to be used for reading,
+writing, or both.  (On @gnuhurdsystems{}, they can also allow none of these,
+and allow execution of the file as a program.)  The access modes are chosen
+when the file is opened, and never change.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_RDONLY
+Open the file for read access.
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_WRONLY
+Open the file for write access.
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_RDWR
+Open the file for both reading and writing.
+@end deftypevr
+
+On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
+@code{O_WRONLY} are independent bits that can be bitwise-ORed together,
+and it is valid for either bit to be set or clear.  This means that
+@code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
+mode of zero is permissible; it allows no operations that do input or
+output to the file, but does allow other operations such as
+@code{fchmod}.  On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
+is a misnomer, @file{fcntl.h} defines additional names for the file
+access modes.  These names are preferred when writing GNU-specific code.
+But most programs will want to be portable to other POSIX.1 systems and
+should use the POSIX.1 names above instead.
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_READ
+Open the file for reading.  Same as @code{O_RDONLY}; only defined on GNU.
+@end deftypevr
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_WRITE
+Open the file for writing.  Same as @code{O_WRONLY}; only defined on GNU.
+@end deftypevr
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_EXEC
+Open the file for executing.  Only defined on GNU.
+@end deftypevr
+
+To determine the file access mode with @code{fcntl}, you must extract
+the access mode bits from the retrieved file status flags.  On
+@gnuhurdsystems{},
+you can just test the @code{O_READ} and @code{O_WRITE} bits in
+the flags word.  But in other POSIX.1 systems, reading and writing
+access modes are not stored as distinct bit flags.  The portable way to
+extract the file access mode bits is with @code{O_ACCMODE}.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_ACCMODE
+This macro stands for a mask that can be bitwise-ANDed with the file
+status flag value to produce a value representing the file access mode.
+The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
+(On @gnuhurdsystems{} it could also be zero, and it never includes the
+@code{O_EXEC} bit.)
+@end deftypevr
+
+@node Open-time Flags
+@subsection Open-time Flags
+
+The open-time flags specify options affecting how @code{open} will behave.
+These options are not preserved once the file is open.  The exception to
+this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
+@emph{is} saved.  @xref{Opening and Closing Files}, for how to call
+@code{open}.
+
+There are two sorts of options specified by open-time flags.
+
+@itemize @bullet
+@item
+@dfn{File name translation flags} affect how @code{open} looks up the
+file name to locate the file, and whether the file can be created.
+@cindex file name translation flags
+@cindex flags, file name translation
+
+@item
+@dfn{Open-time action flags} specify extra operations that @code{open} will
+perform on the file once it is open.
+@cindex open-time action flags
+@cindex flags, open-time action
+@end itemize
+
+Here are the file name translation flags.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_CREAT
+If set, the file will be created if it doesn't already exist.
+@c !!! mode arg, umask
+@cindex create on open (file status flag)
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_EXCL
+If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
+if the specified file already exists.  This is guaranteed to never
+clobber an existing file.
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_NONBLOCK
+@cindex non-blocking open
+This prevents @code{open} from blocking for a ``long time'' to open the
+file.  This is only meaningful for some kinds of files, usually devices
+such as serial ports; when it is not meaningful, it is harmless and
+ignored.  Often opening a port to a modem blocks until the modem reports
+carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
+return immediately without a carrier.
+
+Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
+mode and a file name translation flag.  This means that specifying
+@code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
+@pxref{Operating Modes}.  To open the file without blocking but do normal
+I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
+then call @code{fcntl} to turn the bit off.
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_NOCTTY
+If the named file is a terminal device, don't make it the controlling
+terminal for the process.  @xref{Job Control}, for information about
+what it means to be the controlling terminal.
+
+On @gnuhurdsystems{} and 4.4 BSD, opening a file never makes it the
+controlling terminal and @code{O_NOCTTY} is zero.  However, @gnulinuxsystems{}
+and some other systems use a nonzero value for @code{O_NOCTTY} and set the
+controlling terminal when you open a file that is a terminal device; so
+to be portable, use @code{O_NOCTTY} when it is important to avoid this.
+@cindex controlling terminal, setting
+@end deftypevr
+
+The following three file name translation flags exist only on
+@gnuhurdsystems{}.
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_IGNORE_CTTY
+Do not recognize the named file as the controlling terminal, even if it
+refers to the process's existing controlling terminal device.  Operations
+on the new file descriptor will never induce job control signals.
+@xref{Job Control}.
+@end deftypevr
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_NOLINK
+If the named file is a symbolic link, open the link itself instead of
+the file it refers to.  (@code{fstat} on the new file descriptor will
+return the information returned by @code{lstat} on the link's name.)
+@cindex symbolic link, opening
+@end deftypevr
+
+@comment fcntl.h (optional)
+@comment GNU
+@deftypevr Macro int O_NOTRANS
+If the named file is specially translated, do not invoke the translator.
+Open the bare file the translator itself sees.
+@end deftypevr
+
+
+The open-time action flags tell @code{open} to do additional operations
+which are not really related to opening the file.  The reason to do them
+as part of @code{open} instead of in separate calls is that @code{open}
+can do them @i{atomically}.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_TRUNC
+Truncate the file to zero length.  This option is only useful for
+regular files, not special files such as directories or FIFOs.  POSIX.1
+requires that you open the file for writing to use @code{O_TRUNC}.  In
+BSD and GNU you must have permission to write the file to truncate it,
+but you need not open for write access.
+
+This is the only open-time action flag specified by POSIX.1.  There is
+no good reason for truncation to be done by @code{open}, instead of by
+calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
+Unix before @code{ftruncate} was invented, and is retained for backward
+compatibility.
+@end deftypevr
+
+The remaining operating modes are BSD extensions.  They exist only
+on some systems.  On other systems, these macros are not defined.
+
+@comment fcntl.h (optional)
+@comment BSD
+@deftypevr Macro int O_SHLOCK
+Acquire a shared lock on the file, as with @code{flock}.
+@xref{File Locks}.
+
+If @code{O_CREAT} is specified, the locking is done atomically when
+creating the file.  You are guaranteed that no other process will get
+the lock on the new file first.
+@end deftypevr
+
+@comment fcntl.h (optional)
+@comment BSD
+@deftypevr Macro int O_EXLOCK
+Acquire an exclusive lock on the file, as with @code{flock}.
+@xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
+@end deftypevr
+
+@node Operating Modes
+@subsection I/O Operating Modes
+
+The operating modes affect how input and output operations using a file
+descriptor work.  These flags are set by @code{open} and can be fetched
+and changed with @code{fcntl}.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_APPEND
+The bit that enables append mode for the file.  If set, then all
+@code{write} operations write the data at the end of the file, extending
+it, regardless of the current file position.  This is the only reliable
+way to append to a file.  In append mode, you are guaranteed that the
+data you write will always go to the current end of the file, regardless
+of other processes writing to the file.  Conversely, if you simply set
+the file position to the end of file and write, then another process can
+extend the file after you set the file position but before you write,
+resulting in your data appearing someplace before the real end of file.
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int O_NONBLOCK
+The bit that enables nonblocking mode for the file.  If this bit is set,
+@code{read} requests on the file can return immediately with a failure
+status if there is no input immediately available, instead of blocking.
+Likewise, @code{write} requests can also return immediately with a
+failure status if the output can't be written immediately.
+
+Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
+operating mode and a file name translation flag; @pxref{Open-time Flags}.
+@end deftypevr
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int O_NDELAY
+This is an obsolete name for @code{O_NONBLOCK}, provided for
+compatibility with BSD.  It is not defined by the POSIX.1 standard.
+@end deftypevr
+
+The remaining operating modes are BSD and GNU extensions.  They exist only
+on some systems.  On other systems, these macros are not defined.
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int O_ASYNC
+The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
+signals will be generated when input is available.  @xref{Interrupt Input}.
+
+Asynchronous input mode is a BSD feature.
+@end deftypevr
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int O_FSYNC
+The bit that enables synchronous writing for the file.  If set, each
+@code{write} call will make sure the data is reliably stored on disk before
+returning. @c !!! xref fsync
+
+Synchronous writing is a BSD feature.
+@end deftypevr
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int O_SYNC
+This is another name for @code{O_FSYNC}.  They have the same value.
+@end deftypevr
+
+@comment fcntl.h
+@comment GNU
+@deftypevr Macro int O_NOATIME
+If this bit is set, @code{read} will not update the access time of the
+file.  @xref{File Times}.  This is used by programs that do backups, so
+that backing a file up does not count as reading it.
+Only the owner of the file or the superuser may use this bit.
+
+This is a GNU extension.
+@end deftypevr
+
+@node Getting File Status Flags
+@subsection Getting and Setting File Status Flags
+
+The @code{fcntl} function can fetch or change file status flags.
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_GETFL
+This macro is used as the @var{command} argument to @code{fcntl}, to
+read the file status flags for the open file with descriptor
+@var{filedes}.
+
+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.  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 @math{-1}.  The following
+@code{errno} error conditions are defined for this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETFL
+This macro is used as the @var{command} argument to @code{fcntl}, to set
+the file status flags for the open file corresponding to the
+@var{filedes} argument.  This command requires a third @code{int}
+argument to specify the new flags, so the call looks like this:
+
+@smallexample
+fcntl (@var{filedes}, F_SETFL, @var{new-flags})
+@end smallexample
+
+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 @math{-1}, which indicates an error.  The
+error conditions are the same as for the @code{F_GETFL} command.
+@end deftypevr
+
+If you want to modify the file status flags, you should get the current
+flags with @code{F_GETFL} and modify the value.  Don't assume that the
+flags listed here are the only ones that are implemented; your program
+may be run years from now and more flags may exist then.  For example,
+here is a function to set or clear the flag @code{O_NONBLOCK} without
+altering any other flags:
+
+@smallexample
+@group
+/* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
+   @r{or clear the flag if @var{value} is 0.}
+   @r{Return 0 on success, or -1 on error with @code{errno} set.} */
+
+int
+set_nonblock_flag (int desc, int value)
+@{
+  int oldflags = fcntl (desc, F_GETFL, 0);
+  /* @r{If reading the flags failed, return error indication now.} */
+  if (oldflags == -1)
+    return -1;
+  /* @r{Set just the flag we want to set.} */
+  if (value != 0)
+    oldflags |= O_NONBLOCK;
+  else
+    oldflags &= ~O_NONBLOCK;
+  /* @r{Store modified flag word in the descriptor.} */
+  return fcntl (desc, F_SETFL, oldflags);
+@}
+@end group
+@end smallexample
+
+@node File Locks
+@section File Locks
+
+@cindex file locks
+@cindex record locking
+This section describes record locks that are associated with the process.
+There is also a different type of record lock that is associated with the
+open file description instead of the process.  @xref{Open File Description Locks}.
+
+The remaining @code{fcntl} commands are used to support @dfn{record
+locking}, which permits multiple cooperating programs to prevent each
+other from simultaneously accessing parts of a file in error-prone
+ways.
+
+@cindex exclusive lock
+@cindex write lock
+An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
+for writing to the specified part of the file.  While a write lock is in
+place, no other process can lock that part of the file.
+
+@cindex shared lock
+@cindex read lock
+A @dfn{shared} or @dfn{read} lock prohibits any other process from
+requesting a write lock on the specified part of the file.  However,
+other processes can request read locks.
+
+The @code{read} and @code{write} functions do not actually check to see
+whether there are any locks in place.  If you want to implement a
+locking protocol for a file shared by multiple processes, your application
+must do explicit @code{fcntl} calls to request and clear locks at the
+appropriate points.
+
+Locks are associated with processes.  A process can only have one kind
+of lock set for each byte of a given file.  When any file descriptor for
+that file is closed by the process, all of the locks that process holds
+on that file are released, even if the locks were made using other
+descriptors that remain open.  Likewise, locks are released when a
+process exits, and are not inherited by child processes created using
+@code{fork} (@pxref{Creating a Process}).
+
+When making a lock, use a @code{struct flock} to specify what kind of
+lock and where.  This data type and the associated macros for the
+@code{fcntl} function are declared in the header file @file{fcntl.h}.
+@pindex fcntl.h
+
+@comment fcntl.h
+@comment POSIX.1
+@deftp {Data Type} {struct flock}
+This structure is used with the @code{fcntl} function to describe a file
+lock.  It has these members:
+
+@table @code
+@item short int l_type
+Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
+@code{F_UNLCK}.
+
+@item short int l_whence
+This corresponds to the @var{whence} argument to @code{fseek} or
+@code{lseek}, and specifies what the offset is relative to.  Its value
+can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
+
+@item off_t l_start
+This specifies the offset of the start of the region to which the lock
+applies, and is given in bytes relative to the point specified by
+@code{l_whence} member.
+
+@item off_t l_len
+This specifies the length of the region to be locked.  A value of
+@code{0} is treated specially; it means the region extends to the end of
+the file.
+
+@item pid_t l_pid
+This field is the process ID (@pxref{Process Creation Concepts}) of the
+process holding the lock.  It is filled in by calling @code{fcntl} with
+the @code{F_GETLK} command, but is ignored when making a lock.  If the
+conflicting lock is an open file description lock
+(@pxref{Open File Description Locks}), then this field will be set to
+@math{-1}.
+@end table
+@end deftp
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_GETLK
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should get information about a lock.  This command
+requires a third argument of type @w{@code{struct flock *}} to be passed
+to @code{fcntl}, so that the form of the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_GETLK, @var{lockp})
+@end smallexample
+
+If there is a lock already in place that would block the lock described
+by the @var{lockp} argument, information about that lock overwrites
+@code{*@var{lockp}}.  Existing locks are not reported if they are
+compatible with making a new lock as specified.  Thus, you should
+specify a lock type of @code{F_WRLCK} if you want to find out about both
+read and write locks, or @code{F_RDLCK} if you want to find out about
+write locks only.
+
+There might be more than one lock affecting the region specified by the
+@var{lockp} argument, but @code{fcntl} only returns information about
+one of them.  The @code{l_whence} member of the @var{lockp} structure is
+set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
+set to identify the locked region.
+
+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 @math{-1}, which is reserved to indicate an
+error.  The following @code{errno} error conditions are defined for
+this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+or the file associated with @var{filedes} doesn't support locks.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETLK
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock.  This command requires a
+third argument of type @w{@code{struct flock *}} to be passed to
+@code{fcntl}, so that the form of the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_SETLK, @var{lockp})
+@end smallexample
+
+If the process already has a lock on any part of the region, the old lock
+on that part is replaced with the new lock.  You can remove a lock
+by specifying a lock type of @code{F_UNLCK}.
+
+If the lock cannot be set, @code{fcntl} returns immediately with a value
+of @math{-1}.  This function does not block waiting for other processes
+to release locks.  If @code{fcntl} succeeds, it return a value other
+than @math{-1}.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EAGAIN
+@itemx EACCES
+The lock cannot be set because it is blocked by an existing lock on the
+file.  Some systems use @code{EAGAIN} in this case, and other systems
+use @code{EACCES}; your program should treat them alike, after
+@code{F_SETLK}.  (@gnulinuxhurdsystems{} always use @code{EAGAIN}.)
+
+@item EBADF
+Either: the @var{filedes} argument is invalid; you requested a read lock
+but the @var{filedes} is not open for read access; or, you requested a
+write lock but the @var{filedes} is not open for write access.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+or the file associated with @var{filedes} doesn't support locks.
+
+@item ENOLCK
+The system has run out of file lock resources; there are already too
+many file locks in place.
+
+Well-designed file systems never report this error, because they have no
+limitation on the number of locks.  However, you must still take account
+of the possibility of this error, as it could result from network access
+to a file system on another machine.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETLKW
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock.  It is just like the
+@code{F_SETLK} command, but causes the process to block (or wait)
+until the request can be specified.
+
+This command requires a third argument of type @code{struct flock *}, as
+for the @code{F_SETLK} command.
+
+The @code{fcntl} return values and errors are the same as for the
+@code{F_SETLK} command, but these additional @code{errno} error conditions
+are defined for this command:
+
+@table @code
+@item EINTR
+The function was interrupted by a signal while it was waiting.
+@xref{Interrupted Primitives}.
+
+@item EDEADLK
+The specified region is being locked by another process.  But that
+process is waiting to lock a region which the current process has
+locked, so waiting for the lock would result in deadlock.  The system
+does not guarantee that it will detect all such conditions, but it lets
+you know if it notices one.
+@end table
+@end deftypevr
+
+
+The following macros are defined for use as values for the @code{l_type}
+member of the @code{flock} structure.  The values are integer constants.
+
+@table @code
+@comment fcntl.h
+@comment POSIX.1
+@vindex F_RDLCK
+@item F_RDLCK
+This macro is used to specify a read (or shared) lock.
+
+@comment fcntl.h
+@comment POSIX.1
+@vindex F_WRLCK
+@item F_WRLCK
+This macro is used to specify a write (or exclusive) lock.
+
+@comment fcntl.h
+@comment POSIX.1
+@vindex F_UNLCK
+@item F_UNLCK
+This macro is used to specify that the region is unlocked.
+@end table
+
+As an example of a situation where file locking is useful, consider a
+program that can be run simultaneously by several different users, that
+logs status information to a common file.  One example of such a program
+might be a game that uses a file to keep track of high scores.  Another
+example might be a program that records usage or accounting information
+for billing purposes.
+
+Having multiple copies of the program simultaneously writing to the
+file could cause the contents of the file to become mixed up.  But
+you can prevent this kind of problem by setting a write lock on the
+file before actually writing to the file.
+
+If the program also needs to read the file and wants to make sure that
+the contents of the file are in a consistent state, then it can also use
+a read lock.  While the read lock is set, no other process can lock
+that part of the file for writing.
+
+@c ??? This section could use an example program.
+
+Remember that file locks are only an @emph{advisory} protocol for
+controlling access to a file.  There is still potential for access to
+the file by programs that don't use the lock protocol.
+
+@node Open File Description Locks
+@section Open File Description Locks
+
+In contrast to process-associated record locks (@pxref{File Locks}),
+open file description record locks are associated with an open file
+description rather than a process.
+
+Using @code{fcntl} to apply an open file description lock on a region that
+already has an existing open file description lock that was created via the
+same file descriptor will never cause a lock conflict.
+
+Open file description locks are also inherited by child processes across
+@code{fork}, or @code{clone} with @code{CLONE_FILES} set
+(@pxref{Creating a Process}), along with the file descriptor.
+
+It is important to distinguish between the open file @emph{description} (an
+instance of an open file, usually created by a call to @code{open}) and
+an open file @emph{descriptor}, which is a numeric value that refers to the
+open file description.  The locks described here are associated with the
+open file @emph{description} and not the open file @emph{descriptor}.
+
+Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
+descriptor does not give you a new open file description, but rather copies a
+reference to an existing open file description and assigns it to a new
+file descriptor.  Thus, open file description locks set on a file
+descriptor cloned by @code{dup} will never conflict with open file
+description locks set on the original descriptor since they refer to the
+same open file description.  Depending on the range and type of lock
+involved, the original lock may be modified by a @code{F_OFD_SETLK} or
+@code{F_OFD_SETLKW} command in this situation however.
+
+Open file description locks always conflict with process-associated locks,
+even if acquired by the same process or on the same open file
+descriptor.
+
+Open file description locks use the same @code{struct flock} as
+process-associated locks as an argument (@pxref{File Locks}) and the
+macros for the @code{command} values are also declared in the header file
+@file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be
+defined prior to including any header file.
+
+In contrast to process-associated locks, any @code{struct flock} used as
+an argument to open file description lock commands must have the @code{l_pid}
+value set to @math{0}.  Also, when returning information about an
+open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request,
+the @code{l_pid} field in @code{struct flock} will be set to @math{-1}
+to indicate that the lock is not associated with a process.
+
+When the same @code{struct flock} is reused as an argument to a
+@code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an
+@code{F_OFD_GETLK} request, it is necessary to inspect and reset the
+@code{l_pid} field to @math{0}.
+
+@pindex fcntl.h.
+
+@deftypevr Macro int F_OFD_GETLK
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should get information about a lock.  This command
+requires a third argument of type @w{@code{struct flock *}} to be passed
+to @code{fcntl}, so that the form of the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_OFD_GETLK, @var{lockp})
+@end smallexample
+
+If there is a lock already in place that would block the lock described
+by the @var{lockp} argument, information about that lock is written to
+@code{*@var{lockp}}.  Existing locks are not reported if they are
+compatible with making a new lock as specified.  Thus, you should
+specify a lock type of @code{F_WRLCK} if you want to find out about both
+read and write locks, or @code{F_RDLCK} if you want to find out about
+write locks only.
+
+There might be more than one lock affecting the region specified by the
+@var{lockp} argument, but @code{fcntl} only returns information about
+one of them. Which lock is returned in this situation is undefined.
+
+The @code{l_whence} member of the @var{lockp} structure are set to
+@code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set
+to identify the locked region.
+
+If no conflicting lock exists, the only change to the @var{lockp} structure
+is to update the @code{l_type} field to the value @code{F_UNLCK}.
+
+The normal return value from @code{fcntl} with this command is either @math{0}
+on success or @math{-1}, which indicates an error. The following @code{errno}
+error conditions are defined for this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+the operating system kernel doesn't support open file description locks, or the file
+associated with @var{filedes} doesn't support locks.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_OFD_SETLK
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock.  This command requires a
+third argument of type @w{@code{struct flock *}} to be passed to
+@code{fcntl}, so that the form of the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_OFD_SETLK, @var{lockp})
+@end smallexample
+
+If the open file already has a lock on any part of the
+region, the old lock on that part is replaced with the new lock.  You
+can remove a lock by specifying a lock type of @code{F_UNLCK}.
+
+If the lock cannot be set, @code{fcntl} returns immediately with a value
+of @math{-1}.  This command does not wait for other tasks
+to release locks.  If @code{fcntl} succeeds, it returns @math{0}.
+
+The following @code{errno} error conditions are defined for this
+command:
+
+@table @code
+@item EAGAIN
+The lock cannot be set because it is blocked by an existing lock on the
+file.
+
+@item EBADF
+Either: the @var{filedes} argument is invalid; you requested a read lock
+but the @var{filedes} is not open for read access; or, you requested a
+write lock but the @var{filedes} is not open for write access.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+the operating system kernel doesn't support open file description locks, or the
+file associated with @var{filedes} doesn't support locks.
+
+@item ENOLCK
+The system has run out of file lock resources; there are already too
+many file locks in place.
+
+Well-designed file systems never report this error, because they have no
+limitation on the number of locks.  However, you must still take account
+of the possibility of this error, as it could result from network access
+to a file system on another machine.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_OFD_SETLKW
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock.  It is just like the
+@code{F_OFD_SETLK} command, but causes the process to wait until the request
+can be completed.
+
+This command requires a third argument of type @code{struct flock *}, as
+for the @code{F_OFD_SETLK} command.
+
+The @code{fcntl} return values and errors are the same as for the
+@code{F_OFD_SETLK} command, but these additional @code{errno} error conditions
+are defined for this command:
+
+@table @code
+@item EINTR
+The function was interrupted by a signal while it was waiting.
+@xref{Interrupted Primitives}.
+
+@end table
+@end deftypevr
+
+Open file description locks are useful in the same sorts of situations as
+process-associated locks. They can also be used to synchronize file
+access between threads within the same process by having each thread perform
+its own @code{open} of the file, to obtain its own open file description.
+
+Because open file description locks are automatically freed only upon
+closing the last file descriptor that refers to the open file
+description, this locking mechanism avoids the possibility that locks
+are inadvertently released due to a library routine opening and closing
+a file without the application being aware.
+
+As with process-associated locks, open file description locks are advisory.
+
+@node Open File Description Locks Example
+@section Open File Description Locks Example
+
+Here is an example of using open file description locks in a threaded
+program. If this program used process-associated locks, then it would be
+subject to data corruption because process-associated locks are shared
+by the threads inside a process, and thus cannot be used by one thread
+to lock out another thread in the same process.
+
+Proper error handling has been omitted in the following program for
+brevity.
+
+@smallexample
+@include ofdlocks.c.texi
+@end smallexample
+
+This example creates three threads each of which loops five times,
+appending to the file.  Access to the file is serialized via open file
+description locks. If we compile and run the above program, we'll end up
+with /tmp/foo that has 15 lines in it.
+
+If we, however, were to replace the @code{F_OFD_SETLK} and
+@code{F_OFD_SETLKW} commands with their process-associated lock
+equivalents, the locking essentially becomes a noop since it is all done
+within the context of the same process. That leads to data corruption
+(typically manifested as missing lines) as some threads race in and
+overwrite the data written by others.
+
+@node Interrupt Input
+@section Interrupt-Driven Input
+
+@cindex interrupt-driven input
+If you set the @code{O_ASYNC} status flag on a file descriptor
+(@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
+input or output becomes possible on that file descriptor.  The process
+or process group to receive the signal can be selected by using the
+@code{F_SETOWN} command to the @code{fcntl} function.  If the file
+descriptor is a socket, this also selects the recipient of @code{SIGURG}
+signals that are delivered when out-of-band data arrives on that socket;
+see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
+where @code{select} would report the socket as having an ``exceptional
+condition''.  @xref{Waiting for I/O}.)
+
+If the file descriptor corresponds to a terminal device, then @code{SIGIO}
+signals are sent to the foreground process group of the terminal.
+@xref{Job Control}.
+
+@pindex fcntl.h
+The symbols in this section are defined in the header file
+@file{fcntl.h}.
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int F_GETOWN
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should get information about the process or process
+group to which @code{SIGIO} signals are sent.  (For a terminal, this is
+actually the foreground process group ID, which you can get using
+@code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
+
+The return value is interpreted as a process ID; if negative, its
+absolute value is the process group ID.
+
+The following @code{errno} error condition is defined for this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment BSD
+@deftypevr Macro int F_SETOWN
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set the process or process group to which
+@code{SIGIO} signals are sent.  This command requires a third argument
+of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
+the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_SETOWN, @var{pid})
+@end smallexample
+
+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 @math{-1}
+in case of error and some other value if successful.  The following
+@code{errno} error conditions are defined for this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+
+@item ESRCH
+There is no process or process group corresponding to @var{pid}.
+@end table
+@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
+
+@gnusystems{} can handle most input/output operations on many different
+devices and objects in terms of a few file primitives - @code{read},
+@code{write} and @code{lseek}.  However, most devices also have a few
+peculiar operations which do not fit into this model.  Such as:
+
+@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.
+
+@comment sys/ioctl.h
+@comment BSD
+@deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+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, see @ref{Out-of-Band Data}.
+
+@c FIXME this is undocumented:
+@c dup3
diff --git a/ap/libc/glibc/glibc-2.23/manual/locale.texi b/ap/libc/glibc/glibc-2.23/manual/locale.texi
new file mode 100644
index 0000000..1828500
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/locale.texi
@@ -0,0 +1,1468 @@
+@node Locales, Message Translation, Character Set Handling, Top
+@c %MENU% The country and language can affect the behavior of library functions
+@chapter Locales and Internationalization
+
+Different countries and cultures have varying conventions for how to
+communicate.  These conventions range from very simple ones, such as the
+format for representing dates and times, to very complex ones, such as
+the language spoken.
+
+@cindex internationalization
+@cindex locales
+@dfn{Internationalization} of software means programming it to be able
+to adapt to the user's favorite conventions.  In @w{ISO C},
+internationalization works by means of @dfn{locales}.  Each locale
+specifies a collection of conventions, one convention for each purpose.
+The user chooses a set of conventions by specifying a locale (via
+environment variables).
+
+All programs inherit the chosen locale as part of their environment.
+Provided the programs are written to obey the choice of locale, they
+will follow the conventions preferred by the user.
+
+@menu
+* Effects of Locale::           Actions affected by the choice of
+                                 locale.
+* Choosing Locale::             How the user specifies a locale.
+* Locale Categories::           Different purposes for which you can
+                                 select a locale.
+* Setting the Locale::          How a program specifies the locale
+                                 with library functions.
+* Standard Locales::            Locale names available on all systems.
+* Locale Names::                Format of system-specific locale names.
+* Locale Information::          How to access the information for the locale.
+* Formatting Numbers::          A dedicated function to format numbers.
+* Yes-or-No Questions::         Check a Response against the locale.
+@end menu
+
+@node Effects of Locale, Choosing Locale,  , Locales
+@section What Effects a Locale Has
+
+Each locale specifies conventions for several purposes, including the
+following:
+
+@itemize @bullet
+@item
+What multibyte character sequences are valid, and how they are
+interpreted (@pxref{Character Set Handling}).
+
+@item
+Classification of which characters in the local character set are
+considered alphabetic, and upper- and lower-case conversion conventions
+(@pxref{Character Handling}).
+
+@item
+The collating sequence for the local language and character set
+(@pxref{Collation Functions}).
+
+@item
+Formatting of numbers and currency amounts (@pxref{General Numeric}).
+
+@item
+Formatting of dates and times (@pxref{Formatting Calendar Time}).
+
+@item
+What language to use for output, including error messages
+(@pxref{Message Translation}).
+
+@item
+What language to use for user answers to yes-or-no questions
+(@pxref{Yes-or-No Questions}).
+
+@item
+What language to use for more complex user input.
+(The C library doesn't yet help you implement this.)
+@end itemize
+
+Some aspects of adapting to the specified locale are handled
+automatically by the library subroutines.  For example, all your program
+needs to do in order to use the collating sequence of the chosen locale
+is to use @code{strcoll} or @code{strxfrm} to compare strings.
+
+Other aspects of locales are beyond the comprehension of the library.
+For example, the library can't automatically translate your program's
+output messages into other languages.  The only way you can support
+output in the user's favorite language is to program this more or less
+by hand.  The C library provides functions to handle translations for
+multiple languages easily.
+
+This chapter discusses the mechanism by which you can modify the current
+locale.  The effects of the current locale on specific library functions
+are discussed in more detail in the descriptions of those functions.
+
+@node Choosing Locale, Locale Categories, Effects of Locale, Locales
+@section Choosing a Locale
+
+The simplest way for the user to choose a locale is to set the
+environment variable @code{LANG}.  This specifies a single locale to use
+for all purposes.  For example, a user could specify a hypothetical
+locale named @samp{espana-castellano} to use the standard conventions of
+most of Spain.
+
+The set of locales supported depends on the operating system you are
+using, and so do their names, except that the standard locale called
+@samp{C} or @samp{POSIX} always exist.  @xref{Locale Names}.
+
+In order to force the system to always use the default locale, the
+user can set the @code{LC_ALL} environment variable to @samp{C}.
+
+@cindex combining locales
+A user also has the option of specifying different locales for
+different purposes---in effect, choosing a mixture of multiple
+locales.  @xref{Locale Categories}.
+
+For example, the user might specify the locale @samp{espana-castellano}
+for most purposes, but specify the locale @samp{usa-english} for
+currency formatting.  This might make sense if the user is a
+Spanish-speaking American, working in Spanish, but representing monetary
+amounts in US dollars.
+
+Note that both locales @samp{espana-castellano} and @samp{usa-english},
+like all locales, would include conventions for all of the purposes to
+which locales apply.  However, the user can choose to use each locale
+for a particular subset of those purposes.
+
+@node Locale Categories, Setting the Locale, Choosing Locale, Locales
+@section Locale Categories
+@cindex categories for locales
+@cindex locale categories
+
+The purposes that locales serve are grouped into @dfn{categories}, so
+that a user or a program can choose the locale for each category
+independently.  Here is a table of categories; each name is both an
+environment variable that a user can set, and a macro name that you can
+use as the first argument to @code{setlocale}.
+
+The contents of the environment variable (or the string in the second
+argument to @code{setlocale}) has to be a valid locale name.
+@xref{Locale Names}.
+
+@vtable @code
+@comment locale.h
+@comment ISO
+@item LC_COLLATE
+This category applies to collation of strings (functions @code{strcoll}
+and @code{strxfrm}); see @ref{Collation Functions}.
+
+@comment locale.h
+@comment ISO
+@item LC_CTYPE
+This category applies to classification and conversion of characters,
+and to multibyte and wide characters;
+see @ref{Character Handling}, and @ref{Character Set Handling}.
+
+@comment locale.h
+@comment ISO
+@item LC_MONETARY
+This category applies to formatting monetary values; see @ref{General Numeric}.
+
+@comment locale.h
+@comment ISO
+@item LC_NUMERIC
+This category applies to formatting numeric values that are not
+monetary; see @ref{General Numeric}.
+
+@comment locale.h
+@comment ISO
+@item LC_TIME
+This category applies to formatting date and time values; see
+@ref{Formatting Calendar Time}.
+
+@comment locale.h
+@comment XOPEN
+@item LC_MESSAGES
+This category applies to selecting the language used in the user
+interface for message translation (@pxref{The Uniforum approach};
+@pxref{Message catalogs a la X/Open})  and contains regular expressions
+for affirmative and negative responses.
+
+@comment locale.h
+@comment ISO
+@item LC_ALL
+This is not a category; it is only a macro that you can use
+with @code{setlocale} to set a single locale for all purposes.  Setting
+this environment variable overwrites all selections by the other
+@code{LC_*} variables or @code{LANG}.
+
+@comment locale.h
+@comment ISO
+@item LANG
+If this environment variable is defined, its value specifies the locale
+to use for all purposes except as overridden by the variables above.
+@end vtable
+
+@vindex LANGUAGE
+When developing the message translation functions it was felt that the
+functionality provided by the variables above is not sufficient.  For
+example, it should be possible to specify more than one locale name.
+Take a Swedish user who better speaks German than English, and a program
+whose messages are output in English by default.  It should be possible
+to specify that the first choice of language is Swedish, the second
+German, and if this also fails to use English.  This is
+possible with the variable @code{LANGUAGE}.  For further description of
+this GNU extension see @ref{Using gettextized software}.
+
+@node Setting the Locale, Standard Locales, Locale Categories, Locales
+@section How Programs Set the Locale
+
+A C program inherits its locale environment variables when it starts up.
+This happens automatically.  However, these variables do not
+automatically control the locale used by the library functions, because
+@w{ISO C} says that all programs start by default in the standard @samp{C}
+locale.  To use the locales specified by the environment, you must call
+@code{setlocale}.  Call it as follows:
+
+@smallexample
+setlocale (LC_ALL, "");
+@end smallexample
+
+@noindent
+to select a locale based on the user choice of the appropriate
+environment variables.
+
+@cindex changing the locale
+@cindex locale, changing
+You can also use @code{setlocale} to specify a particular locale, for
+general use or for a specific category.
+
+@pindex locale.h
+The symbols in this section are defined in the header file @file{locale.h}.
+
+@comment locale.h
+@comment ISO
+@deftypefun {char *} setlocale (int @var{category}, const char *@var{locale})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtslocale{}} @mtsenv{}}@asunsafe{@asuinit{} @asulock{} @ascuheap{} @asucorrupt{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Uses of the global locale object are unguarded in functions that
+@c ought to be MT-Safe, so we're ruling out the use of this function
+@c once threads are started.  It takes a write lock itself, but it may
+@c return a pointer loaded from the global locale object after releasing
+@c the lock, or before taking it.
+@c setlocale @mtasuconst:@mtslocale @mtsenv @asuinit @ascuheap @asulock @asucorrupt @acucorrupt @acsmem @acsfd @aculock
+@c  libc_rwlock_wrlock @asulock @aculock
+@c  libc_rwlock_unlock @aculock
+@c  getenv LOCPATH @mtsenv
+@c  malloc @ascuheap @acsmem
+@c  free @ascuheap @acsmem
+@c  new_composite_name ok
+@c  setdata ok
+@c  setname ok
+@c  _nl_find_locale @mtsenv @asuinit @ascuheap @asulock @asucorrupt @acucorrupt @acsmem @acsfd @aculock
+@c   getenv LC_ALL and LANG @mtsenv
+@c   _nl_load_locale_from_archive @ascuheap @acucorrupt @acsmem @acsfd
+@c    sysconf _SC_PAGE_SIZE ok
+@c    _nl_normalize_codeset @ascuheap @acsmem
+@c     isalnum_l ok (C locale)
+@c     isdigit_l ok (C locale)
+@c     malloc @ascuheap @acsmem
+@c     tolower_l ok (C locale)
+@c    open_not_cancel_2 @acsfd
+@c    fxstat64 ok
+@c    close_not_cancel_no_status ok
+@c    __mmap64 @acsmem
+@c    calculate_head_size ok
+@c    __munmap ok
+@c    compute_hashval ok
+@c    qsort dup @acucorrupt
+@c     rangecmp ok
+@c    malloc @ascuheap @acsmem
+@c    strdup @ascuheap @acsmem
+@c    _nl_intern_locale_data @ascuheap @acsmem
+@c     malloc @ascuheap @acsmem
+@c     free @ascuheap @acsmem
+@c   _nl_expand_alias @ascuheap @asulock @acsmem @acsfd @aculock
+@c    libc_lock_lock @asulock @aculock
+@c    bsearch ok
+@c     alias_compare ok
+@c      strcasecmp ok
+@c    read_alias_file @ascuheap @asulock @acsmem @acsfd @aculock
+@c     fopen @ascuheap @asulock @acsmem @acsfd @aculock
+@c     fsetlocking ok
+@c     feof_unlocked ok
+@c     fgets_unlocked ok
+@c     isspace ok (locale mutex is locked)
+@c     extend_alias_table @ascuheap @acsmem
+@c      realloc @ascuheap @acsmem
+@c     realloc @ascuheap @acsmem
+@c     fclose @ascuheap @asulock @acsmem @acsfd @aculock
+@c     qsort @ascuheap @acsmem
+@c      alias_compare dup
+@c    libc_lock_unlock @aculock
+@c   _nl_explode_name @ascuheap @acsmem
+@c    _nl_find_language ok
+@c    _nl_normalize_codeset dup @ascuheap @acsmem
+@c   _nl_make_l10nflist @ascuheap @acsmem
+@c    malloc @ascuheap @acsmem
+@c    free @ascuheap @acsmem
+@c    __argz_stringify ok
+@c    __argz_count ok
+@c    __argz_next ok
+@c   _nl_load_locale @ascuheap @acsmem @acsfd
+@c    open_not_cancel_2 @acsfd
+@c    __fxstat64 ok
+@c    close_not_cancel_no_status ok
+@c    mmap @acsmem
+@c    malloc @ascuheap @acsmem
+@c    read_not_cancel ok
+@c    free @ascuheap @acsmem
+@c    _nl_intern_locale_data dup @ascuheap @acsmem
+@c    munmap ok
+@c   __gconv_compare_alias @asuinit @ascuheap @asucorrupt @asulock @acsmem@acucorrupt @acsfd @aculock
+@c    __gconv_read_conf @asuinit @ascuheap @asucorrupt @asulock @acsmem@acucorrupt @acsfd @aculock
+@c     (libc_once-initializes gconv_cache and gconv_path_envvar; they're
+@c      never modified afterwards)
+@c     __gconv_load_cache @ascuheap @acsmem @acsfd
+@c      getenv GCONV_PATH @mtsenv
+@c      open_not_cancel @acsfd
+@c      __fxstat64 ok
+@c      close_not_cancel_no_status ok
+@c      mmap @acsmem
+@c      malloc @ascuheap @acsmem
+@c      __read ok
+@c      free @ascuheap @acsmem
+@c      munmap ok
+@c     __gconv_get_path @asulock @ascuheap @aculock @acsmem @acsfd
+@c      getcwd @ascuheap @acsmem @acsfd
+@c      libc_lock_lock @asulock @aculock
+@c      malloc @ascuheap @acsmem
+@c      strtok_r ok
+@c      libc_lock_unlock @aculock
+@c     read_conf_file @ascuheap @asucorrupt @asulock @acsmem @acucorrupt @acsfd @aculock
+@c      fopen @ascuheap @asulock @acsmem @acsfd @aculock
+@c      fsetlocking ok
+@c      feof_unlocked ok
+@c      getdelim @ascuheap @asucorrupt @acsmem @acucorrupt
+@c      isspace_l ok (C locale)
+@c      add_alias
+@c       isspace_l ok (C locale)
+@c       toupper_l ok (C locale)
+@c       add_alias2 dup @ascuheap @acucorrupt @acsmem
+@c      add_module @ascuheap @acsmem
+@c       isspace_l ok (C locale)
+@c       toupper_l ok (C locale)
+@c       strtol ok (@mtslocale but we hold the locale lock)
+@c       tfind __gconv_alias_db ok
+@c        __gconv_alias_compare dup ok
+@c       calloc @ascuheap @acsmem
+@c       insert_module dup @ascuheap
+@c     __tfind ok (because the tree is read only by then)
+@c      __gconv_alias_compare dup ok
+@c     insert_module @ascuheap
+@c      free @ascuheap
+@c     add_alias2 @ascuheap @acucorrupt @acsmem
+@c      detect_conflict ok, reads __gconv_modules_db
+@c      malloc @ascuheap @acsmem
+@c      tsearch __gconv_alias_db @ascuheap @acucorrupt @acsmem [exclusive tree, no @mtsrace]
+@c       __gconv_alias_compare ok
+@c      free @ascuheap
+@c    __gconv_compare_alias_cache ok
+@c     find_module_idx ok
+@c    do_lookup_alias ok
+@c     __tfind ok (because the tree is read only by then)
+@c      __gconv_alias_compare ok
+@c   strndup @ascuheap @acsmem
+@c   strcasecmp_l ok (C locale)
+The function @code{setlocale} sets the current locale for category
+@var{category} to @var{locale}.
+
+If @var{category} is @code{LC_ALL}, this specifies the locale for all
+purposes.  The other possible values of @var{category} specify an
+single purpose (@pxref{Locale Categories}).
+
+You can also use this function to find out the current locale by passing
+a null pointer as the @var{locale} argument.  In this case,
+@code{setlocale} returns a string that is the name of the locale
+currently selected for category @var{category}.
+
+The string returned by @code{setlocale} can be overwritten by subsequent
+calls, so you should make a copy of the string (@pxref{Copying Strings
+and Arrays}) if you want to save it past any further calls to
+@code{setlocale}.  (The standard library is guaranteed never to call
+@code{setlocale} itself.)
+
+You should not modify the string returned by @code{setlocale}.  It might
+be the same string that was passed as an argument in a previous call to
+@code{setlocale}.  One requirement is that the @var{category} must be
+the same in the call the string was returned and the one when the string
+is passed in as @var{locale} parameter.
+
+When you read the current locale for category @code{LC_ALL}, the value
+encodes the entire combination of selected locales for all categories.
+If you specify the same ``locale name'' with @code{LC_ALL} in a
+subsequent call to @code{setlocale}, it restores the same combination
+of locale selections.
+
+To be sure you can use the returned string encoding the currently selected
+locale at a later time, you must make a copy of the string.  It is not
+guaranteed that the returned pointer remains valid over time.
+
+When the @var{locale} argument is not a null pointer, the string returned
+by @code{setlocale} reflects the newly-modified locale.
+
+If you specify an empty string for @var{locale}, this means to read the
+appropriate environment variable and use its value to select the locale
+for @var{category}.
+
+If a nonempty string is given for @var{locale}, then the locale of that
+name is used if possible.
+
+The effective locale name (either the second argument to
+@code{setlocale}, or if the argument is an empty string, the name
+obtained from the process environment) must be valid locale name.
+@xref{Locale Names}.
+
+If you specify an invalid locale name, @code{setlocale} returns a null
+pointer and leaves the current locale unchanged.
+@end deftypefun
+
+Here is an example showing how you might use @code{setlocale} to
+temporarily switch to a new locale.
+
+@smallexample
+#include <stddef.h>
+#include <locale.h>
+#include <stdlib.h>
+#include <string.h>
+
+void
+with_other_locale (char *new_locale,
+                   void (*subroutine) (int),
+                   int argument)
+@{
+  char *old_locale, *saved_locale;
+
+  /* @r{Get the name of the current locale.}  */
+  old_locale = setlocale (LC_ALL, NULL);
+
+  /* @r{Copy the name so it won't be clobbered by @code{setlocale}.} */
+  saved_locale = strdup (old_locale);
+  if (saved_locale == NULL)
+    fatal ("Out of memory");
+
+  /* @r{Now change the locale and do some stuff with it.} */
+  setlocale (LC_ALL, new_locale);
+  (*subroutine) (argument);
+
+  /* @r{Restore the original locale.} */
+  setlocale (LC_ALL, saved_locale);
+  free (saved_locale);
+@}
+@end smallexample
+
+@strong{Portability Note:} Some @w{ISO C} systems may define additional
+locale categories, and future versions of the library will do so.  For
+portability, assume that any symbol beginning with @samp{LC_} might be
+defined in @file{locale.h}.
+
+@node Standard Locales, Locale Names, Setting the Locale, Locales
+@section Standard Locales
+
+The only locale names you can count on finding on all operating systems
+are these three standard ones:
+
+@table @code
+@item "C"
+This is the standard C locale.  The attributes and behavior it provides
+are specified in the @w{ISO C} standard.  When your program starts up, it
+initially uses this locale by default.
+
+@item "POSIX"
+This is the standard POSIX locale.  Currently, it is an alias for the
+standard C locale.
+
+@item ""
+The empty name says to select a locale based on environment variables.
+@xref{Locale Categories}.
+@end table
+
+Defining and installing named locales is normally a responsibility of
+the system administrator at your site (or the person who installed
+@theglibc{}).  It is also possible for the user to create private
+locales.  All this will be discussed later when describing the tool to
+do so.
+@comment (@pxref{Building Locale Files}).
+
+If your program needs to use something other than the @samp{C} locale,
+it will be more portable if you use whatever locale the user specifies
+with the environment, rather than trying to specify some non-standard
+locale explicitly by name.  Remember, different machines might have
+different sets of locales installed.
+
+@node Locale Names, Locale Information, Standard Locales, Locales
+@section Locale Names
+
+The following command prints a list of locales supported by the
+system:
+
+@pindex locale
+@smallexample
+  locale -a
+@end smallexample
+
+@strong{Portability Note:} With the notable exception of the standard
+locale names @samp{C} and @samp{POSIX}, locale names are
+system-specific.
+
+Most locale names follow XPG syntax and consist of up to four parts:
+
+@smallexample
+@var{language}[_@var{territory}[.@var{codeset}]][@@@var{modifier}]
+@end smallexample
+
+Beside the first part, all of them are allowed to be missing.  If the
+full specified locale is not found, less specific ones are looked for.
+The various parts will be stripped off, in the following order:
+
+@enumerate
+@item
+codeset
+@item
+normalized codeset
+@item
+territory
+@item
+modifier
+@end enumerate
+
+For example, the locale name @samp{de_AT.iso885915@@euro} denotes a
+German-language locale for use in Austria, using the ISO-8859-15
+(Latin-9) character set, and with the Euro as the currency symbol.
+
+In addition to locale names which follow XPG syntax, systems may
+provide aliases such as @samp{german}.  Both categories of names must
+not contain the slash character @samp{/}.
+
+If the locale name starts with a slash @samp{/}, it is treated as a
+path relative to the configured locale directories; see @code{LOCPATH}
+below.  The specified path must not contain a component @samp{..}, or
+the name is invalid, and @code{setlocale} will fail.
+
+@strong{Portability Note:} POSIX suggests that if a locale name starts
+with a slash @samp{/}, it is resolved as an absolute path.  However,
+@theglibc{} treats it as a relative path under the directories listed
+in @code{LOCPATH} (or the default locale directory if @code{LOCPATH}
+is unset).
+
+Locale names which are longer than an implementation-defined limit are
+invalid and cause @code{setlocale} to fail.
+
+As a special case, locale names used with @code{LC_ALL} can combine
+several locales, reflecting different locale settings for different
+categories.  For example, you might want to use a U.S. locale with ISO
+A4 paper format, so you set @code{LANG} to @samp{en_US.UTF-8}, and
+@code{LC_PAPER} to @samp{de_DE.UTF-8}.  In this case, the
+@code{LC_ALL}-style combined locale name is
+
+@smallexample
+LC_CTYPE=en_US.UTF-8;LC_TIME=en_US.UTF-8;LC_PAPER=de_DE.UTF-8;@dots{}
+@end smallexample
+
+followed by other category settings not shown here.
+
+@vindex LOCPATH
+The path used for finding locale data can be set using the
+@code{LOCPATH} environment variable.  This variable lists the
+directories in which to search for locale definitions, separated by a
+colon @samp{:}.
+
+The default path for finding locale data is system specific.  A typical
+value for the @code{LOCPATH} default is:
+
+@smallexample
+/usr/share/locale
+@end smallexample
+
+The value of @code{LOCPATH} is ignored by privileged programs for
+security reasons, and only the default directory is used.
+
+@node Locale Information, Formatting Numbers, Locale Names, Locales
+@section Accessing Locale Information
+
+There are several ways to access locale information.  The simplest
+way is to let the C library itself do the work.  Several of the
+functions in this library implicitly access the locale data, and use
+what information is provided by the currently selected locale.  This is
+how the locale model is meant to work normally.
+
+As an example take the @code{strftime} function, which is meant to nicely
+format date and time information (@pxref{Formatting Calendar Time}).
+Part of the standard information contained in the @code{LC_TIME}
+category is the names of the months.  Instead of requiring the
+programmer to take care of providing the translations the
+@code{strftime} function does this all by itself.  @code{%A}
+in the format string is replaced by the appropriate weekday
+name of the locale currently selected by @code{LC_TIME}.  This is an
+easy example, and wherever possible functions do things automatically
+in this way.
+
+But there are quite often situations when there is simply no function
+to perform the task, or it is simply not possible to do the work
+automatically.  For these cases it is necessary to access the
+information in the locale directly.  To do this the C library provides
+two functions: @code{localeconv} and @code{nl_langinfo}.  The former is
+part of @w{ISO C} and therefore portable, but has a brain-damaged
+interface.  The second is part of the Unix interface and is portable in
+as far as the system follows the Unix standards.
+
+@menu
+* The Lame Way to Locale Data::   ISO C's @code{localeconv}.
+* The Elegant and Fast Way::      X/Open's @code{nl_langinfo}.
+@end menu
+
+@node The Lame Way to Locale Data, The Elegant and Fast Way, ,Locale Information
+@subsection @code{localeconv}: It is portable but @dots{}
+
+Together with the @code{setlocale} function the @w{ISO C} people
+invented the @code{localeconv} function.  It is a masterpiece of poor
+design.  It is expensive to use, not extendable, and not generally
+usable as it provides access to only @code{LC_MONETARY} and
+@code{LC_NUMERIC} related information.  Nevertheless, if it is
+applicable to a given situation it should be used since it is very
+portable.  The function @code{strfmon} formats monetary amounts
+according to the selected locale using this information.
+@pindex locale.h
+@cindex monetary value formatting
+@cindex numeric value formatting
+
+@comment locale.h
+@comment ISO
+@deftypefun {struct lconv *} localeconv (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:localeconv} @mtslocale{}}@asunsafe{}@acsafe{}}
+@c This function reads from multiple components of the locale object,
+@c without synchronization, while writing to the static buffer it uses
+@c as the return value.
+The @code{localeconv} function returns a pointer to a structure whose
+components contain information about how numeric and monetary values
+should be formatted in the current locale.
+
+You should not modify the structure or its contents.  The structure might
+be overwritten by subsequent calls to @code{localeconv}, or by calls to
+@code{setlocale}, but no other function in the library overwrites this
+value.
+@end deftypefun
+
+@comment locale.h
+@comment ISO
+@deftp {Data Type} {struct lconv}
+@code{localeconv}'s return value is of this data type.  Its elements are
+described in the following subsections.
+@end deftp
+
+If a member of the structure @code{struct lconv} has type @code{char},
+and the value is @code{CHAR_MAX}, it means that the current locale has
+no value for that parameter.
+
+@menu
+* 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.
+@end menu
+
+@node General Numeric, Currency Symbol, , The Lame Way to Locale Data
+@subsubsection Generic Numeric Formatting Parameters
+
+These are the standard members of @code{struct lconv}; there may be
+others.
+
+@table @code
+@item char *decimal_point
+@itemx char *mon_decimal_point
+These are the decimal-point separators used in formatting non-monetary
+and monetary quantities, respectively.  In the @samp{C} locale, the
+value of @code{decimal_point} is @code{"."}, and the value of
+@code{mon_decimal_point} is @code{""}.
+@cindex decimal-point separator
+
+@item char *thousands_sep
+@itemx char *mon_thousands_sep
+These are the separators used to delimit groups of digits to the left of
+the decimal point in formatting non-monetary and monetary quantities,
+respectively.  In the @samp{C} locale, both members have a value of
+@code{""} (the empty string).
+
+@item char *grouping
+@itemx char *mon_grouping
+These are strings that specify how to group the digits to the left of
+the decimal point.  @code{grouping} applies to non-monetary quantities
+and @code{mon_grouping} applies to monetary quantities.  Use either
+@code{thousands_sep} or @code{mon_thousands_sep} to separate the digit
+groups.
+@cindex grouping of digits
+
+Each member of these strings is to be interpreted as an integer value of
+type @code{char}.  Successive numbers (from left to right) give the
+sizes of successive groups (from right to left, starting at the decimal
+point.)  The last member is either @code{0}, in which case the previous
+member is used over and over again for all the remaining groups, or
+@code{CHAR_MAX}, in which case there is no more grouping---or, put
+another way, any remaining digits form one large group without
+separators.
+
+For example, if @code{grouping} is @code{"\04\03\02"}, the correct
+grouping for the number @code{123456787654321} is @samp{12}, @samp{34},
+@samp{56}, @samp{78}, @samp{765}, @samp{4321}.  This uses a group of 4
+digits at the end, preceded by a group of 3 digits, preceded by groups
+of 2 digits (as many as needed).  With a separator of @samp{,}, the
+number would be printed as @samp{12,34,56,78,765,4321}.
+
+A value of @code{"\03"} indicates repeated groups of three digits, as
+normally used in the U.S.
+
+In the standard @samp{C} locale, both @code{grouping} and
+@code{mon_grouping} have a value of @code{""}.  This value specifies no
+grouping at all.
+
+@item char int_frac_digits
+@itemx char frac_digits
+These are small integers indicating how many fractional digits (to the
+right of the decimal point) should be displayed in a monetary value in
+international and local formats, respectively.  (Most often, both
+members have the same value.)
+
+In the standard @samp{C} locale, both of these members have the value
+@code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
+what to do when you find this value; we recommend printing no
+fractional digits.  (This locale also specifies the empty string for
+@code{mon_decimal_point}, so printing any fractional digits would be
+confusing!)
+@end table
+
+@node Currency Symbol, Sign of Money Amount, General Numeric, The Lame Way to Locale Data
+@subsubsection Printing the Currency Symbol
+@cindex currency symbols
+
+These members of the @code{struct lconv} structure specify how to print
+the symbol to identify a monetary value---the international analog of
+@samp{$} for US dollars.
+
+Each country has two standard currency symbols.  The @dfn{local currency
+symbol} is used commonly within the country, while the
+@dfn{international currency symbol} is used internationally to refer to
+that country's currency when it is necessary to indicate the country
+unambiguously.
+
+For example, many countries use the dollar as their monetary unit, and
+when dealing with international currencies it's important to specify
+that one is dealing with (say) Canadian dollars instead of U.S. dollars
+or Australian dollars.  But when the context is known to be Canada,
+there is no need to make this explicit---dollar amounts are implicitly
+assumed to be in Canadian dollars.
+
+@table @code
+@item char *currency_symbol
+The local currency symbol for the selected locale.
+
+In the standard @samp{C} locale, this member has a value of @code{""}
+(the empty string), meaning ``unspecified''.  The ISO standard doesn't
+say what to do when you find this value; we recommend you simply print
+the empty string as you would print any other string pointed to by this
+variable.
+
+@item char *int_curr_symbol
+The international currency symbol for the selected locale.
+
+The value of @code{int_curr_symbol} should normally consist of a
+three-letter abbreviation determined by the international standard
+@cite{ISO 4217 Codes for the Representation of Currency and Funds},
+followed by a one-character separator (often a space).
+
+In the standard @samp{C} locale, this member has a value of @code{""}
+(the empty string), meaning ``unspecified''.  We recommend you simply print
+the empty string as you would print any other string pointed to by this
+variable.
+
+@item char p_cs_precedes
+@itemx char n_cs_precedes
+@itemx char int_p_cs_precedes
+@itemx char int_n_cs_precedes
+These members are @code{1} if the @code{currency_symbol} or
+@code{int_curr_symbol} strings should precede the value of a monetary
+amount, or @code{0} if the strings should follow the value.  The
+@code{p_cs_precedes} and @code{int_p_cs_precedes} members apply to
+positive amounts (or zero), and the @code{n_cs_precedes} and
+@code{int_n_cs_precedes} members apply to negative amounts.
+
+In the standard @samp{C} locale, all of these members have a value of
+@code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
+what to do when you find this value.  We recommend printing the
+currency symbol before the amount, which is right for most countries.
+In other words, treat all nonzero values alike in these members.
+
+The members with the @code{int_} prefix apply to the
+@code{int_curr_symbol} while the other two apply to
+@code{currency_symbol}.
+
+@item char p_sep_by_space
+@itemx char n_sep_by_space
+@itemx char int_p_sep_by_space
+@itemx char int_n_sep_by_space
+These members are @code{1} if a space should appear between the
+@code{currency_symbol} or @code{int_curr_symbol} strings and the
+amount, or @code{0} if no space should appear.  The
+@code{p_sep_by_space} and @code{int_p_sep_by_space} members apply to
+positive amounts (or zero), and the @code{n_sep_by_space} and
+@code{int_n_sep_by_space} members apply to negative amounts.
+
+In the standard @samp{C} locale, all of these members have a value of
+@code{CHAR_MAX}, meaning ``unspecified''.  The ISO standard doesn't say
+what you should do when you find this value; we suggest you treat it as
+1 (print a space).  In other words, treat all nonzero values alike in
+these members.
+
+The members with the @code{int_} prefix apply to the
+@code{int_curr_symbol} while the other two apply to
+@code{currency_symbol}.  There is one specialty with the
+@code{int_curr_symbol}, though.  Since all legal values contain a space
+at the end the string one either printf this space (if the currency
+symbol must appear in front and must be separated) or one has to avoid
+printing this character at all (especially when at the end of the
+string).
+@end table
+
+@node Sign of Money Amount, , Currency Symbol, The Lame Way to Locale Data
+@subsubsection Printing the Sign of a Monetary Amount
+
+These members of the @code{struct lconv} structure specify how to print
+the sign (if any) of a monetary value.
+
+@table @code
+@item char *positive_sign
+@itemx char *negative_sign
+These are strings used to indicate positive (or zero) and negative
+monetary quantities, respectively.
+
+In the standard @samp{C} locale, both of these members have a value of
+@code{""} (the empty string), meaning ``unspecified''.
+
+The ISO standard doesn't say what to do when you find this value; we
+recommend printing @code{positive_sign} as you find it, even if it is
+empty.  For a negative value, print @code{negative_sign} as you find it
+unless both it and @code{positive_sign} are empty, in which case print
+@samp{-} instead.  (Failing to indicate the sign at all seems rather
+unreasonable.)
+
+@item char p_sign_posn
+@itemx char n_sign_posn
+@itemx char int_p_sign_posn
+@itemx char int_n_sign_posn
+These members are small integers that indicate how to
+position the sign for nonnegative and negative monetary quantities,
+respectively.  (The string used by the sign is what was specified with
+@code{positive_sign} or @code{negative_sign}.)  The possible values are
+as follows:
+
+@table @code
+@item 0
+The currency symbol and quantity should be surrounded by parentheses.
+
+@item 1
+Print the sign string before the quantity and currency symbol.
+
+@item 2
+Print the sign string after the quantity and currency symbol.
+
+@item 3
+Print the sign string right before the currency symbol.
+
+@item 4
+Print the sign string right after the currency symbol.
+
+@item CHAR_MAX
+``Unspecified''.  Both members have this value in the standard
+@samp{C} locale.
+@end table
+
+The ISO standard doesn't say what you should do when the value is
+@code{CHAR_MAX}.  We recommend you print the sign after the currency
+symbol.
+
+The members with the @code{int_} prefix apply to the
+@code{int_curr_symbol} while the other two apply to
+@code{currency_symbol}.
+@end table
+
+@node The Elegant and Fast Way, , The Lame Way to Locale Data, Locale Information
+@subsection Pinpoint Access to Locale Data
+
+When writing the X/Open Portability Guide the authors realized that the
+@code{localeconv} function is not enough to provide reasonable access to
+locale information.  The information which was meant to be available
+in the locale (as later specified in the POSIX.1 standard) requires more
+ways to access it.  Therefore the @code{nl_langinfo} function
+was introduced.
+
+@comment langinfo.h
+@comment XOPEN
+@deftypefun {char *} nl_langinfo (nl_item @var{item})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c It calls _nl_langinfo_l with the current locale, which returns a
+@c pointer into constant strings defined in locale data structures.
+The @code{nl_langinfo} function can be used to access individual
+elements of the locale categories.  Unlike the @code{localeconv}
+function, which returns all the information, @code{nl_langinfo}
+lets the caller select what information it requires.  This is very
+fast and it is not a problem to call this function multiple times.
+
+A second advantage is that in addition to the numeric and monetary
+formatting information, information from the
+@code{LC_TIME} and @code{LC_MESSAGES} categories is available.
+
+@pindex langinfo.h
+The type @code{nl_type} is defined in @file{nl_types.h}.  The argument
+@var{item} is a numeric value defined in the header @file{langinfo.h}.
+The X/Open standard defines the following values:
+
+@vtable @code
+@item CODESET
+@code{nl_langinfo} returns a string with the name of the coded character
+set used in the selected locale.
+
+@item ABDAY_1
+@itemx ABDAY_2
+@itemx ABDAY_3
+@itemx ABDAY_4
+@itemx ABDAY_5
+@itemx ABDAY_6
+@itemx ABDAY_7
+@code{nl_langinfo} returns the abbreviated weekday name.  @code{ABDAY_1}
+corresponds to Sunday.
+@item DAY_1
+@itemx DAY_2
+@itemx DAY_3
+@itemx DAY_4
+@itemx DAY_5
+@itemx DAY_6
+@itemx DAY_7
+Similar to @code{ABDAY_1} etc., but here the return value is the
+unabbreviated weekday name.
+@item ABMON_1
+@itemx ABMON_2
+@itemx ABMON_3
+@itemx ABMON_4
+@itemx ABMON_5
+@itemx ABMON_6
+@itemx ABMON_7
+@itemx ABMON_8
+@itemx ABMON_9
+@itemx ABMON_10
+@itemx ABMON_11
+@itemx ABMON_12
+The return value is abbreviated name of the month.  @code{ABMON_1}
+corresponds to January.
+@item MON_1
+@itemx MON_2
+@itemx MON_3
+@itemx MON_4
+@itemx MON_5
+@itemx MON_6
+@itemx MON_7
+@itemx MON_8
+@itemx MON_9
+@itemx MON_10
+@itemx MON_11
+@itemx MON_12
+Similar to @code{ABMON_1} etc., but here the month names are not abbreviated.
+Here the first value @code{MON_1} also corresponds to January.
+@item AM_STR
+@itemx PM_STR
+The return values are strings which can be used in the representation of time
+as an hour from 1 to 12 plus an am/pm specifier.
+
+Note that in locales which do not use this time representation
+these strings might be empty, in which case the am/pm format
+cannot be used at all.
+@item D_T_FMT
+The return value can be used as a format string for @code{strftime} to
+represent time and date in a locale-specific way.
+@item D_FMT
+The return value can be used as a format string for @code{strftime} to
+represent a date in a locale-specific way.
+@item T_FMT
+The return value can be used as a format string for @code{strftime} to
+represent time in a locale-specific way.
+@item T_FMT_AMPM
+The return value can be used as a format string for @code{strftime} to
+represent time in the am/pm format.
+
+Note that if the am/pm format does not make any sense for the
+selected locale, the return value might be the same as the one for
+@code{T_FMT}.
+@item ERA
+The return value represents the era used in the current locale.
+
+Most locales do not define this value.  An example of a locale which
+does define this value is the Japanese one.  In Japan, the traditional
+representation of dates includes the name of the era corresponding to
+the then-emperor's reign.
+
+Normally it should not be necessary to use this value directly.
+Specifying the @code{E} modifier in their format strings causes the
+@code{strftime} functions to use this information.  The format of the
+returned string is not specified, and therefore you should not assume
+knowledge of it on different systems.
+@item ERA_YEAR
+The return value gives the year in the relevant era of the locale.
+As for @code{ERA} it should not be necessary to use this value directly.
+@item ERA_D_T_FMT
+This return value can be used as a format string for @code{strftime} to
+represent dates and times in a locale-specific era-based way.
+@item ERA_D_FMT
+This return value can be used as a format string for @code{strftime} to
+represent a date in a locale-specific era-based way.
+@item ERA_T_FMT
+This return value can be used as a format string for @code{strftime} to
+represent time in a locale-specific era-based way.
+@item ALT_DIGITS
+The return value is a representation of up to @math{100} values used to
+represent the values @math{0} to @math{99}.  As for @code{ERA} this
+value is not intended to be used directly, but instead indirectly
+through the @code{strftime} function.  When the modifier @code{O} is
+used in a format which would otherwise use numerals to represent hours,
+minutes, seconds, weekdays, months, or weeks, the appropriate value for
+the locale is used instead.
+@item INT_CURR_SYMBOL
+The same as the value returned by @code{localeconv} in the
+@code{int_curr_symbol} element of the @code{struct lconv}.
+@item CURRENCY_SYMBOL
+@itemx CRNCYSTR
+The same as the value returned by @code{localeconv} in the
+@code{currency_symbol} element of the @code{struct lconv}.
+
+@code{CRNCYSTR} is a deprecated alias still required by Unix98.
+@item MON_DECIMAL_POINT
+The same as the value returned by @code{localeconv} in the
+@code{mon_decimal_point} element of the @code{struct lconv}.
+@item MON_THOUSANDS_SEP
+The same as the value returned by @code{localeconv} in the
+@code{mon_thousands_sep} element of the @code{struct lconv}.
+@item MON_GROUPING
+The same as the value returned by @code{localeconv} in the
+@code{mon_grouping} element of the @code{struct lconv}.
+@item POSITIVE_SIGN
+The same as the value returned by @code{localeconv} in the
+@code{positive_sign} element of the @code{struct lconv}.
+@item NEGATIVE_SIGN
+The same as the value returned by @code{localeconv} in the
+@code{negative_sign} element of the @code{struct lconv}.
+@item INT_FRAC_DIGITS
+The same as the value returned by @code{localeconv} in the
+@code{int_frac_digits} element of the @code{struct lconv}.
+@item FRAC_DIGITS
+The same as the value returned by @code{localeconv} in the
+@code{frac_digits} element of the @code{struct lconv}.
+@item P_CS_PRECEDES
+The same as the value returned by @code{localeconv} in the
+@code{p_cs_precedes} element of the @code{struct lconv}.
+@item P_SEP_BY_SPACE
+The same as the value returned by @code{localeconv} in the
+@code{p_sep_by_space} element of the @code{struct lconv}.
+@item N_CS_PRECEDES
+The same as the value returned by @code{localeconv} in the
+@code{n_cs_precedes} element of the @code{struct lconv}.
+@item N_SEP_BY_SPACE
+The same as the value returned by @code{localeconv} in the
+@code{n_sep_by_space} element of the @code{struct lconv}.
+@item P_SIGN_POSN
+The same as the value returned by @code{localeconv} in the
+@code{p_sign_posn} element of the @code{struct lconv}.
+@item N_SIGN_POSN
+The same as the value returned by @code{localeconv} in the
+@code{n_sign_posn} element of the @code{struct lconv}.
+
+@item INT_P_CS_PRECEDES
+The same as the value returned by @code{localeconv} in the
+@code{int_p_cs_precedes} element of the @code{struct lconv}.
+@item INT_P_SEP_BY_SPACE
+The same as the value returned by @code{localeconv} in the
+@code{int_p_sep_by_space} element of the @code{struct lconv}.
+@item INT_N_CS_PRECEDES
+The same as the value returned by @code{localeconv} in the
+@code{int_n_cs_precedes} element of the @code{struct lconv}.
+@item INT_N_SEP_BY_SPACE
+The same as the value returned by @code{localeconv} in the
+@code{int_n_sep_by_space} element of the @code{struct lconv}.
+@item INT_P_SIGN_POSN
+The same as the value returned by @code{localeconv} in the
+@code{int_p_sign_posn} element of the @code{struct lconv}.
+@item INT_N_SIGN_POSN
+The same as the value returned by @code{localeconv} in the
+@code{int_n_sign_posn} element of the @code{struct lconv}.
+
+@item DECIMAL_POINT
+@itemx RADIXCHAR
+The same as the value returned by @code{localeconv} in the
+@code{decimal_point} element of the @code{struct lconv}.
+
+The name @code{RADIXCHAR} is a deprecated alias still used in Unix98.
+@item THOUSANDS_SEP
+@itemx THOUSEP
+The same as the value returned by @code{localeconv} in the
+@code{thousands_sep} element of the @code{struct lconv}.
+
+The name @code{THOUSEP} is a deprecated alias still used in Unix98.
+@item GROUPING
+The same as the value returned by @code{localeconv} in the
+@code{grouping} element of the @code{struct lconv}.
+@item YESEXPR
+The return value is a regular expression which can be used with the
+@code{regex} function to recognize a positive response to a yes/no
+question.  @Theglibc{} provides the @code{rpmatch} function for
+easier handling in applications.
+@item NOEXPR
+The return value is a regular expression which can be used with the
+@code{regex} function to recognize a negative response to a yes/no
+question.
+@item YESSTR
+The return value is a locale-specific translation of the positive response
+to a yes/no question.
+
+Using this value is deprecated since it is a very special case of
+message translation, and is better handled by the message
+translation functions (@pxref{Message Translation}).
+
+The use of this symbol is deprecated.  Instead message translation
+should be used.
+@item NOSTR
+The return value is a locale-specific translation of the negative response
+to a yes/no question.  What is said for @code{YESSTR} is also true here.
+
+The use of this symbol is deprecated.  Instead message translation
+should be used.
+@end vtable
+
+The file @file{langinfo.h} defines a lot more symbols but none of them
+is official.  Using them is not portable, and the format of the
+return values might change.  Therefore we recommended you not use
+them.
+
+Note that the return value for any valid argument can be used for
+in all situations (with the possible exception of the am/pm time formatting
+codes).  If the user has not selected any locale for the
+appropriate category, @code{nl_langinfo} returns the information from the
+@code{"C"} locale.  It is therefore possible to use this function as
+shown in the example below.
+
+If the argument @var{item} is not valid, a pointer to an empty string is
+returned.
+@end deftypefun
+
+An example of @code{nl_langinfo} usage is a function which has to
+print a given date and time in a locale-specific way.  At first one
+might think that, since @code{strftime} internally uses the locale
+information, writing something like the following is enough:
+
+@smallexample
+size_t
+i18n_time_n_data (char *s, size_t len, const struct tm *tp)
+@{
+  return strftime (s, len, "%X %D", tp);
+@}
+@end smallexample
+
+The format contains no weekday or month names and therefore is
+internationally usable.  Wrong!  The output produced is something like
+@code{"hh:mm:ss MM/DD/YY"}.  This format is only recognizable in the
+USA.  Other countries use different formats.  Therefore the function
+should be rewritten like this:
+
+@smallexample
+size_t
+i18n_time_n_data (char *s, size_t len, const struct tm *tp)
+@{
+  return strftime (s, len, nl_langinfo (D_T_FMT), tp);
+@}
+@end smallexample
+
+Now it uses the date and time format of the locale
+selected when the program runs.  If the user selects the locale
+correctly there should never be a misunderstanding over the time and
+date format.
+
+@node Formatting Numbers, Yes-or-No Questions, Locale Information, Locales
+@section A dedicated function to format numbers
+
+We have seen that the structure returned by @code{localeconv} as well as
+the values given to @code{nl_langinfo} allow you to retrieve the various
+pieces of locale-specific information to format numbers and monetary
+amounts.  We have also seen that the underlying rules are quite complex.
+
+Therefore the X/Open standards introduce a function which uses such
+locale information, making it easier for the user to format
+numbers according to these rules.
+
+@deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c It (and strfmon_l) both call vstrfmon_l, which, besides accessing the
+@c locale object passed to it, accesses the active locale through
+@c isdigit (but to_digit assumes ASCII digits only).  It may call
+@c __printf_fp (@mtslocale @ascuheap @acsmem) and guess_grouping (safe).
+The @code{strfmon} function is similar to the @code{strftime} function
+in that it takes a buffer, its size, a format string,
+and values to write into the buffer as text in a form specified
+by the format string.  Like @code{strftime}, the function
+also returns the number of bytes written into the buffer.
+
+There are two differences: @code{strfmon} can take more than one
+argument, and, of course, the format specification is different.  Like
+@code{strftime}, the format string consists of normal text, which is
+output as is, and format specifiers, which are indicated by a @samp{%}.
+Immediately after the @samp{%}, you can optionally specify various flags
+and formatting information before the main formatting character, in a
+similar way to @code{printf}:
+
+@itemize @bullet
+@item
+Immediately following the @samp{%} there can be one or more of the
+following flags:
+@table @asis
+@item @samp{=@var{f}}
+The single byte character @var{f} is used for this field as the numeric
+fill character.  By default this character is a space character.
+Filling with this character is only performed if a left precision
+is specified.  It is not just to fill to the given field width.
+@item @samp{^}
+The number is printed without grouping the digits according to the rules
+of the current locale.  By default grouping is enabled.
+@item @samp{+}, @samp{(}
+At most one of these flags can be used.  They select which format to
+represent the sign of a currency amount.  By default, and if
+@samp{+} is given, the locale equivalent of @math{+}/@math{-} is used.  If
+@samp{(} is given, negative amounts are enclosed in parentheses.  The
+exact format is determined by the values of the @code{LC_MONETARY}
+category of the locale selected at program runtime.
+@item @samp{!}
+The output will not contain the currency symbol.
+@item @samp{-}
+The output will be formatted left-justified instead of right-justified if
+it does not fill the entire field width.
+@end table
+@end itemize
+
+The next part of a specification is an optional field width.  If no
+width is specified @math{0} is taken.  During output, the function first
+determines how much space is required.  If it requires at least as many
+characters as given by the field width, it is output using as much space
+as necessary.  Otherwise, it is extended to use the full width by
+filling with the space character.  The presence or absence of the
+@samp{-} flag determines the side at which such padding occurs.  If
+present, the spaces are added at the right making the output
+left-justified, and vice versa.
+
+So far the format looks familiar, being similar to the @code{printf} and
+@code{strftime} formats.  However, the next two optional fields
+introduce something new.  The first one is a @samp{#} character followed
+by a decimal digit string.  The value of the digit string specifies the
+number of @emph{digit} positions to the left of the decimal point (or
+equivalent).  This does @emph{not} include the grouping character when
+the @samp{^} flag is not given.  If the space needed to print the number
+does not fill the whole width, the field is padded at the left side with
+the fill character, which can be selected using the @samp{=} flag and by
+default is a space.  For example, if the field width is selected as 6
+and the number is @math{123}, the fill character is @samp{*} the result
+will be @samp{***123}.
+
+The second optional field starts with a @samp{.} (period) and consists
+of another decimal digit string.  Its value describes the number of
+characters printed after the decimal point.  The default is selected
+from the current locale (@code{frac_digits}, @code{int_frac_digits}, see
+@pxref{General Numeric}).  If the exact representation needs more digits
+than given by the field width, the displayed value is rounded.  If the
+number of fractional digits is selected to be zero, no decimal point is
+printed.
+
+As a GNU extension, the @code{strfmon} implementation in @theglibc{}
+allows an optional @samp{L} next as a format modifier.  If this modifier
+is given, the argument is expected to be a @code{long double} instead of
+a @code{double} value.
+
+Finally, the last component is a format specifier.  There are three
+specifiers defined:
+
+@table @asis
+@item @samp{i}
+Use the locale's rules for formatting an international currency value.
+@item @samp{n}
+Use the locale's rules for formatting a national currency value.
+@item @samp{%}
+Place a @samp{%} in the output.  There must be no flag, width
+specifier or modifier given, only @samp{%%} is allowed.
+@end table
+
+As for @code{printf}, the function reads the format string
+from left to right and uses the values passed to the function following
+the format string.  The values are expected to be either of type
+@code{double} or @code{long double}, depending on the presence of the
+modifier @samp{L}.  The result is stored in the buffer pointed to by
+@var{s}.  At most @var{maxsize} characters are stored.
+
+The return value of the function is the number of characters stored in
+@var{s}, including the terminating @code{NULL} byte.  If the number of
+characters stored would exceed @var{maxsize}, the function returns
+@math{-1} and the content of the buffer @var{s} is unspecified.  In this
+case @code{errno} is set to @code{E2BIG}.
+@end deftypefun
+
+A few examples should make clear how the function works.  It is
+assumed that all the following pieces of code are executed in a program
+which uses the USA locale (@code{en_US}).  The simplest
+form of the format is this:
+
+@smallexample
+strfmon (buf, 100, "@@%n@@%n@@%n@@", 123.45, -567.89, 12345.678);
+@end smallexample
+
+@noindent
+The output produced is
+@smallexample
+"@@$123.45@@-$567.89@@$12,345.68@@"
+@end smallexample
+
+We can notice several things here.  First, the widths of the output
+numbers are different.  We have not specified a width in the format
+string, and so this is no wonder.  Second, the third number is printed
+using thousands separators.  The thousands separator for the
+@code{en_US} locale is a comma.  The number is also rounded.
+@math{.678} is rounded to @math{.68} since the format does not specify a
+precision and the default value in the locale is @math{2}.  Finally,
+note that the national currency symbol is printed since @samp{%n} was
+used, not @samp{i}.  The next example shows how we can align the output.
+
+@smallexample
+strfmon (buf, 100, "@@%=*11n@@%=*11n@@%=*11n@@", 123.45, -567.89, 12345.678);
+@end smallexample
+
+@noindent
+The output this time is:
+
+@smallexample
+"@@    $123.45@@   -$567.89@@ $12,345.68@@"
+@end smallexample
+
+Two things stand out.  Firstly, all fields have the same width (eleven
+characters) since this is the width given in the format and since no
+number required more characters to be printed.  The second important
+point is that the fill character is not used.  This is correct since the
+white space was not used to achieve a precision given by a @samp{#}
+modifier, but instead to fill to the given width.  The difference
+becomes obvious if we now add a width specification.
+
+@smallexample
+strfmon (buf, 100, "@@%=*11#5n@@%=*11#5n@@%=*11#5n@@",
+         123.45, -567.89, 12345.678);
+@end smallexample
+
+@noindent
+The output is
+
+@smallexample
+"@@ $***123.45@@-$***567.89@@ $12,456.68@@"
+@end smallexample
+
+Here we can see that all the currency symbols are now aligned, and that
+the space between the currency sign and the number is filled with the
+selected fill character.  Note that although the width is selected to be
+@math{5} and @math{123.45} has three digits left of the decimal point,
+the space is filled with three asterisks.  This is correct since, as
+explained above, the width does not include the positions used to store
+thousands separators.  One last example should explain the remaining
+functionality.
+
+@smallexample
+strfmon (buf, 100, "@@%=0(16#5.3i@@%=0(16#5.3i@@%=0(16#5.3i@@",
+         123.45, -567.89, 12345.678);
+@end smallexample
+
+@noindent
+This rather complex format string produces the following output:
+
+@smallexample
+"@@ USD 000123,450 @@(USD 000567.890)@@ USD 12,345.678 @@"
+@end smallexample
+
+The most noticeable change is the alternative way of representing
+negative numbers.  In financial circles this is often done using
+parentheses, and this is what the @samp{(} flag selected.  The fill
+character is now @samp{0}.  Note that this @samp{0} character is not
+regarded as a numeric zero, and therefore the first and second numbers
+are not printed using a thousands separator.  Since we used the format
+specifier @samp{i} instead of @samp{n}, the international form of the
+currency symbol is used.  This is a four letter string, in this case
+@code{"USD "}.  The last point is that since the precision right of the
+decimal point is selected to be three, the first and second numbers are
+printed with an extra zero at the end and the third number is printed
+without rounding.
+
+@node Yes-or-No Questions,  , Formatting Numbers , Locales
+@section Yes-or-No Questions
+
+Some non GUI programs ask a yes-or-no question.  If the messages
+(especially the questions) are translated into foreign languages, be
+sure that you localize the answers too.  It would be very bad habit to
+ask a question in one language and request the answer in another, often
+English.
+
+@Theglibc{} contains @code{rpmatch} to give applications easy
+access to the corresponding locale definitions.
+
+@comment GNU
+@comment stdlib.h
+@deftypefun int rpmatch (const char *@var{response})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c Calls nl_langinfo with YESEXPR and NOEXPR, triggering @mtslocale but
+@c it's regcomp and regexec that bring in all of the safety issues.
+@c regfree is also called, but it doesn't introduce any further issues.
+The function @code{rpmatch} checks the string in @var{response} whether
+or not it is a correct yes-or-no answer and if yes, which one.  The
+check uses the @code{YESEXPR} and @code{NOEXPR} data in the
+@code{LC_MESSAGES} category of the currently selected locale.  The
+return value is as follows:
+
+@table @code
+@item 1
+The user entered an affirmative answer.
+
+@item 0
+The user entered a negative answer.
+
+@item -1
+The answer matched neither the @code{YESEXPR} nor the @code{NOEXPR}
+regular expression.
+@end table
+
+This function is not standardized but available beside in @theglibc{} at
+least also in the IBM AIX library.
+@end deftypefun
+
+@noindent
+This function would normally be used like this:
+
+@smallexample
+  @dots{}
+  /* @r{Use a safe default.}  */
+  _Bool doit = false;
+
+  fputs (gettext ("Do you really want to do this? "), stdout);
+  fflush (stdout);
+  /* @r{Prepare the @code{getline} call.}  */
+  line = NULL;
+  len = 0;
+  while (getline (&line, &len, stdin) >= 0)
+    @{
+      /* @r{Check the response.}  */
+      int res = rpmatch (line);
+      if (res >= 0)
+        @{
+          /* @r{We got a definitive answer.}  */
+          if (res > 0)
+            doit = true;
+          break;
+        @}
+    @}
+  /* @r{Free what @code{getline} allocated.}  */
+  free (line);
+@end smallexample
+
+Note that the loop continues until a read error is detected or until a
+definitive (positive or negative) answer is read.
diff --git a/ap/libc/glibc/glibc-2.23/manual/macros.texi b/ap/libc/glibc/glibc-2.23/manual/macros.texi
new file mode 100644
index 0000000..9cf8031
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/macros.texi
@@ -0,0 +1,270 @@
+@c Define common macros used to keep phrasing consistent in the manual.
+
+@ifclear MACROS
+@set MACROS
+
+@c Names used to refer to the library, as noun phrases at the start or
+@c not at the start of a sentence.
+@macro Theglibc
+The GNU C Library
+@end macro
+@macro theglibc
+the GNU C Library
+@end macro
+
+@c Name used to refer to the library as an adjective.
+@macro glibcadj
+GNU C Library
+@end macro
+
+@c Description applying to all GNU systems; that is, used in
+@c describing a property of a system such that no system without that
+@c property would be considered a variant of the GNU system.
+@macro gnusystems
+GNU systems
+@end macro
+
+@c Systems that are not GNU systems.
+@macro nongnusystems
+non-GNU systems
+@end macro
+
+@c Description applying to GNU/Linux and GNU/Hurd systems, but not
+@c necessarily to other variants of the GNU system.
+@macro gnulinuxhurdsystems
+GNU/Linux and GNU/Hurd systems
+@end macro
+
+@c Description applying to GNU/Hurd systems; that is, systems using the
+@c GNU Hurd with the GNU C Library.
+@macro gnuhurdsystems
+GNU/Hurd systems
+@end macro
+
+@c Description applying to GNU/Linux systems; that is, systems using
+@c the Linux kernel with the GNU C Library.
+@macro gnulinuxsystems
+GNU/Linux systems
+@end macro
+
+@c Document the safety functions as preliminary.  It does NOT expand its
+@c comments.
+@macro prelim {comments}
+Preliminary:
+
+@end macro
+@c Document a function as thread safe.
+@macro mtsafe {comments}
+| MT-Safe \comments\
+
+@end macro
+@c Document a function as thread unsafe.
+@macro mtunsafe {comments}
+| MT-Unsafe \comments\
+
+@end macro
+@c Document a function as safe for use in asynchronous signal handlers.
+@macro assafe {comments}
+| AS-Safe \comments\
+
+@end macro
+@c Document a function as unsafe for use in asynchronous signal
+@c handlers.  This distinguishes unmarked functions, for which this
+@c property has not been assessed, from those that have been analyzed.
+@macro asunsafe {comments}
+| AS-Unsafe \comments\
+
+@end macro
+@c Document a function as safe for use when asynchronous cancellation is
+@c enabled.
+@macro acsafe {comments}
+| AC-Safe \comments\
+
+@end macro
+@c Document a function as unsafe for use when asynchronous cancellation
+@c is enabled.  This distinguishes unmarked functions, for which this
+@c property has not been assessed, from those that have been analyzed.
+@macro acunsafe {comments}
+| AC-Unsafe \comments\
+
+@end macro
+@c Format safety properties without referencing the section of the
+@c definitions.  To be used in the definitions of the properties
+@c themselves.
+@macro sampsafety {notes}
+@noindent
+\notes\|
+
+
+@end macro
+@c Format the safety properties of a function.
+@macro safety {notes}
+\notes\| @xref{POSIX Safety Concepts}.
+
+
+@end macro
+@c Function is MT- and AS-Unsafe due to an internal race.
+@macro mtasurace {comments}
+race\comments\
+@end macro
+@c Function is AS-Unsafe due to an internal race.
+@macro asurace {comments}
+race\comments\
+@end macro
+@c Function is MT-Safe, but with potential race on user-supplied object
+@c of opaque type.
+@macro mtsrace {comments}
+race\comments\
+@end macro
+@c Function is MT- and AS-Unsafe for modifying an object that is decreed
+@c MT-constant due to MT-Unsafe accesses elsewhere.
+@macro mtasuconst {comments}
+const\comments\
+@end macro
+@c Function accesses the assumed-constant locale object.
+@macro mtslocale {comments}
+locale\comments\
+@end macro
+@c Function accesses the assumed-constant environment.
+@macro mtsenv {comments}
+env\comments\
+@end macro
+@c Function accesses the assumed-constant hostid.
+@macro mtshostid {comments}
+hostid\comments\
+@end macro
+@c Function accesses the assumed-constant _sigintr variable.
+@macro mtssigintr {comments}
+sigintr\comments\
+@end macro
+@c Function performs MT-Unsafe initialization at the first call.
+@macro mtuinit {comments}
+init\comments\
+@end macro
+@c Function performs libc_once AS-Unsafe initialization.
+@macro asuinit {comments}
+init\comments\
+@end macro
+@c Function performs libc_once AC-Unsafe initialization.
+@macro acuinit {comments}
+init\comments\
+@end macro
+@c Function is AS-Unsafe because it takes a non-recursive mutex that may
+@c already be held by the function interrupted by the signal.
+@macro asulock {comments}
+lock\comments\
+@end macro
+@c Function is AC-Unsafe because it may fail to release a mutex.
+@macro aculock {comments}
+lock\comments\
+@end macro
+@c Function is AS-Unsafe because some data structure may be inconsistent
+@c due to an ongoing updated interrupted by a signal.
+@macro asucorrupt {comments}
+corrupt\comments\
+@end macro
+@c Function is AC-Unsafe because some data structure may be left
+@c inconsistent when cancelled.
+@macro acucorrupt {comments}
+corrupt\comments\
+@end macro
+@c Function is AS- and AC-Unsafe because of malloc/free.
+@macro ascuheap {comments}
+heap\comments\
+@end macro
+@c Function is AS-Unsafe because of malloc/free.
+@macro asuheap {comments}
+heap\comments\
+@end macro
+@c Function is AS- and AC-Unsafe because of dlopen/dlclose.
+@macro ascudlopen {comments}
+dlopen\comments\
+@end macro
+@c Function is AS- and AC-Unsafe because of unknown plugins.
+@macro ascuplugin {comments}
+plugin\comments\
+@end macro
+@c Function is AS- and AC-Unsafe because of i18n.
+@macro ascuintl {comments}
+i18n\comments\
+@end macro
+@c Function is AS--Unsafe because of i18n.
+@macro asuintl {comments}
+i18n\comments\
+@end macro
+@c Function may leak file descriptors if async-cancelled.
+@macro acsfd {comments}
+fd\comments\
+@end macro
+@c Function may leak memory if async-cancelled.
+@macro acsmem {comments}
+mem\comments\
+@end macro
+@c Function is unsafe due to temporary overriding a signal handler.
+@macro mtascusig {comments}
+sig\comments\
+@end macro
+@c Function is MT- and AS-Unsafe due to temporarily changing attributes
+@c of the controlling terminal.
+@macro mtasuterm {comments}
+term\comments\
+@end macro
+@c Function is AC-Unsafe for failing to restore attributes of the
+@c controlling terminal.
+@macro acuterm {comments}
+term\comments\
+@end macro
+@c Function sets timers atomically.
+@macro mtstimer {comments}
+timer\comments\
+@end macro
+@c Function sets and restores timers.
+@macro mtascutimer {comments}
+timer\comments\
+@end macro
+@c Function temporarily changes the current working directory.
+@macro mtasscwd {comments}
+cwd\comments\
+@end macro
+@c Function may fail to restore to the original current working
+@c directory after temporarily changing it.
+@macro acscwd {comments}
+cwd\comments\
+@end macro
+@c Function is MT-Safe while POSIX says it needn't be MT-Safe.
+@macro mtsposix {comments}
+!posix\comments\
+@end macro
+@c Function is MT-Unsafe while POSIX says it should be MT-Safe.
+@macro mtuposix {comments}
+!posix\comments\
+@end macro
+@c Function is AS-Safe while POSIX says it needn't be AS-Safe.
+@macro assposix {comments}
+!posix\comments\
+@end macro
+@c Function is AS-Unsafe while POSIX says it should be AS-Safe.
+@macro asuposix {comments}
+!posix\comments\
+@end macro
+@c Function is AC-Safe while POSIX says it needn't be AC-Safe.
+@macro acsposix {comments}
+!posix\comments\
+@end macro
+@c Function is AC-Unsafe while POSIX says it should be AC-Safe.
+@macro acuposix {comments}
+!posix\comments\
+@end macro
+
+@iftex
+@macro twoexp{exp}
+@math{2^{{\exp\}}}
+@end macro
+@end iftex
+@ifnottex
+@macro twoexp{exp}
+2^\exp\
+@end macro
+@end ifnottex
+
+@end ifclear
diff --git a/ap/libc/glibc/glibc-2.23/manual/maint.texi b/ap/libc/glibc/glibc-2.23/manual/maint.texi
new file mode 100644
index 0000000..862b49d
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/maint.texi
@@ -0,0 +1,539 @@
+@node Maintenance, Platform, Installation, Top
+@c %MENU% How to enhance and port the GNU C Library
+@appendix Library Maintenance
+
+@menu
+* Source Layout::         How to add new functions or header files
+                             to the GNU C Library.
+* Porting::               How to port the GNU C Library to
+                             a new machine or operating system.
+@end menu
+
+@node Source Layout
+@appendixsec Adding New Functions
+
+The process of building the library is driven by the makefiles, which
+make heavy use of special features of GNU @code{make}.  The makefiles
+are very complex, and you probably don't want to try to understand them.
+But what they do is fairly straightforward, and only requires that you
+define a few variables in the right places.
+
+The library sources are divided into subdirectories, grouped by topic.
+
+The @file{string} subdirectory has all the string-manipulation
+functions, @file{math} has all the mathematical functions, etc.
+
+Each subdirectory contains a simple makefile, called @file{Makefile},
+which defines a few @code{make} variables and then includes the global
+makefile @file{Rules} with a line like:
+
+@smallexample
+include ../Rules
+@end smallexample
+
+@noindent
+The basic variables that a subdirectory makefile defines are:
+
+@table @code
+@item subdir
+The name of the subdirectory, for example @file{stdio}.
+This variable @strong{must} be defined.
+
+@item headers
+The names of the header files in this section of the library,
+such as @file{stdio.h}.
+
+@item routines
+@itemx aux
+The names of the modules (source files) in this section of the library.
+These should be simple names, such as @samp{strlen} (rather than
+complete file names, such as @file{strlen.c}).  Use @code{routines} for
+modules that define functions in the library, and @code{aux} for
+auxiliary modules containing things like data definitions.  But the
+values of @code{routines} and @code{aux} are just concatenated, so there
+really is no practical difference.@refill
+
+@item tests
+The names of test programs for this section of the library.  These
+should be simple names, such as @samp{tester} (rather than complete file
+names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
+run all the test programs.  If a test program needs input, put the test
+data in a file called @file{@var{test-program}.input}; it will be given to
+the test program on its standard input.  If a test program wants to be
+run with arguments, put the arguments (all on a single line) in a file
+called @file{@var{test-program}.args}.  Test programs should exit with
+zero status when the test passes, and nonzero status when the test
+indicates a bug in the library or error in building.
+
+@item others
+The names of ``other'' programs associated with this section of the
+library.  These are programs which are not tests per se, but are other
+small programs included with the library.  They are built by
+@w{@samp{make others}}.@refill
+
+@item install-lib
+@itemx install-data
+@itemx install
+Files to be installed by @w{@samp{make install}}.  Files listed in
+@samp{install-lib} are installed in the directory specified by
+@samp{libdir} in @file{configparms} or @file{Makeconfig}
+(@pxref{Installation}).  Files listed in @code{install-data} are
+installed in the directory specified by @samp{datadir} in
+@file{configparms} or @file{Makeconfig}.  Files listed in @code{install}
+are installed in the directory specified by @samp{bindir} in
+@file{configparms} or @file{Makeconfig}.@refill
+
+@item distribute
+Other files from this subdirectory which should be put into a
+distribution tar file.  You need not list here the makefile itself or
+the source and header files listed in the other standard variables.
+Only define @code{distribute} if there are files used in an unusual way
+that should go into the distribution.
+
+@item generated
+Files which are generated by @file{Makefile} in this subdirectory.
+These files will be removed by @w{@samp{make clean}}, and they will
+never go into a distribution.
+
+@item extra-objs
+Extra object files which are built by @file{Makefile} in this
+subdirectory.  This should be a list of file names like @file{foo.o};
+the files will actually be found in whatever directory object files are
+being built in.  These files will be removed by @w{@samp{make clean}}.
+This variable is used for secondary object files needed to build
+@code{others} or @code{tests}.
+@end table
+
+@menu
+* Platform: Adding Platform-specific.             Adding platform-specific
+                                         features.
+@end menu
+
+@node Adding Platform-specific
+@appendixsubsec Platform-specific types, macros and functions
+
+It's sometimes necessary to provide nonstandard, platform-specific
+features to developers.  The C library is traditionally the
+lowest library layer, so it makes sense for it to provide these
+low-level features.  However, including these features in the C
+library may be a disadvantage if another package provides them
+as well as there will be two conflicting versions of them.  Also,
+the features won't be available to projects that do not use
+@theglibc{} but use other GNU tools, like GCC.
+
+The current guidelines are:
+@itemize @bullet
+@item
+If the header file provides features that only make sense on a particular
+machine architecture and have nothing to do with an operating system, then
+the features should ultimately be provided as GCC built-in functions.  Until
+then, @theglibc{} may provide them in the header file.  When the GCC built-in
+functions become available, those provided in the header file should be made
+conditionally available prior to the GCC version in which the built-in
+function was made available.
+
+@item
+If the header file provides features that are specific to an operating system,
+both GCC and @theglibc{} could provide it, but @theglibc{} is preferred
+as it already has a lot of information about the operating system.
+
+@item
+If the header file provides features that are specific to an operating system
+but used by @theglibc{}, then @theglibc{} should provide them.
+@end itemize
+
+The general solution for providing low-level features is to export them as
+follows:
+
+@itemize @bullet
+@item
+A nonstandard, low-level header file that defines macros and inline
+functions should be called @file{sys/platform/@var{name}.h}.
+
+@item
+Each header file's name should include the platform name, to avoid
+users thinking there is anything in common between different the
+header files for different platforms.  For example, a
+@file{sys/platform/@var{arch}.h} name such as
+@file{sys/platform/ppc.h} is better than @file{sys/platform.h}.
+
+@item
+A platform-specific header file provided by @theglibc{} should coordinate
+with GCC such that compiler built-in versions of the functions and macros are
+preferred if available.  This means that user programs will only ever need to
+include @file{sys/platform/@var{arch}.h}, keeping the same names of types,
+macros, and functions for convenience and portability.
+
+@item
+Each included symbol must have the prefix @code{__@var{arch}_}, such as
+@code{__ppc_get_timebase}.
+@end itemize
+
+
+The easiest way to provide a header file is to add it to the
+@code{sysdep_headers} variable.  For example, the combination of
+Linux-specific header files on PowerPC could be provided like this:
+
+@smallexample
+sysdep_headers += sys/platform/ppc.h
+@end smallexample
+
+Then ensure that you have added a @file{sys/platform/ppc.h}
+header file in the machine-specific directory, e.g.,
+@file{sysdeps/powerpc/sys/platform/ppc.h}.
+
+
+@node Porting
+@appendixsec Porting @theglibc{}
+
+@Theglibc{} is written to be easily portable to a variety of
+machines and operating systems.  Machine- and operating system-dependent
+functions are well separated to make it easy to add implementations for
+new machines or operating systems.  This section describes the layout of
+the library source tree and explains the mechanisms used to select
+machine-dependent code to use.
+
+All the machine-dependent and operating system-dependent files in the
+library are in the subdirectory @file{sysdeps} under the top-level
+library source directory.  This directory contains a hierarchy of
+subdirectories (@pxref{Hierarchy Conventions}).
+
+Each subdirectory of @file{sysdeps} contains source files for a
+particular machine or operating system, or for a class of machine or
+operating system (for example, systems by a particular vendor, or all
+machines that use IEEE 754 floating-point format).  A configuration
+specifies an ordered list of these subdirectories.  Each subdirectory
+implicitly appends its parent directory to the list.  For example,
+specifying the list @file{unix/bsd/vax} is equivalent to specifying the
+list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
+that it implies other subdirectories which are not directly above it in
+the directory hierarchy.  If the file @file{Implies} exists in a
+subdirectory, it lists other subdirectories of @file{sysdeps} which are
+appended to the list, appearing after the subdirectory containing the
+@file{Implies} file.  Lines in an @file{Implies} file that begin with a
+@samp{#} character are ignored as comments.  For example,
+@file{unix/bsd/Implies} contains:@refill
+@smallexample
+# BSD has Internet-related things.
+unix/inet
+@end smallexample
+@noindent
+and @file{unix/Implies} contains:
+@need 300
+@smallexample
+posix
+@end smallexample
+
+@noindent
+So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
+
+@file{sysdeps} has a ``special'' subdirectory called @file{generic}.  It
+is always implicitly appended to the list of subdirectories, so you
+needn't put it in an @file{Implies} file, and you should not create any
+subdirectories under it intended to be new specific categories.
+@file{generic} serves two purposes.  First, the makefiles do not bother
+to look for a system-dependent version of a file that's not in
+@file{generic}.  This means that any system-dependent source file must
+have an analogue in @file{generic}, even if the routines defined by that
+file are not implemented on other platforms.  Second, the @file{generic}
+version of a system-dependent file is used if the makefiles do not find
+a version specific to the system you're compiling for.
+
+If it is possible to implement the routines in a @file{generic} file in
+machine-independent C, using only other machine-independent functions in
+the C library, then you should do so.  Otherwise, make them stubs.  A
+@dfn{stub} function is a function which cannot be implemented on a
+particular machine or operating system.  Stub functions always return an
+error, and set @code{errno} to @code{ENOSYS} (Function not implemented).
+@xref{Error Reporting}.  If you define a stub function, you must place
+the statement @code{stub_warning(@var{function})}, where @var{function}
+is the name of your function, after its definition.  This causes the
+function to be listed in the installed @code{<gnu/stubs.h>}, and
+makes GNU ld warn when the function is used.
+
+Some rare functions are only useful on specific systems and aren't
+defined at all on others; these do not appear anywhere in the
+system-independent source code or makefiles (including the
+@file{generic} directory), only in the system-dependent @file{Makefile}
+in the specific system's subdirectory.
+
+If you come across a file that is in one of the main source directories
+(@file{string}, @file{stdio}, etc.), and you want to write a machine- or
+operating system-dependent version of it, move the file into
+@file{sysdeps/generic} and write your new implementation in the
+appropriate system-specific subdirectory.  Note that if a file is to be
+system-dependent, it @strong{must not} appear in one of the main source
+directories.@refill
+
+There are a few special files that may exist in each subdirectory of
+@file{sysdeps}:
+
+@comment Blank lines after items make the table look better.
+@table @file
+@item Makefile
+
+A makefile for this machine or operating system, or class of machine or
+operating system.  This file is included by the library makefile
+@file{Makerules}, which is used by the top-level makefile and the
+subdirectory makefiles.  It can change the variables set in the
+including makefile or add new rules.  It can use GNU @code{make}
+conditional directives based on the variable @samp{subdir} (see above) to
+select different sets of variables and rules for different sections of
+the library.  It can also set the @code{make} variable
+@samp{sysdep-routines}, to specify extra modules to be included in the
+library.  You should use @samp{sysdep-routines} rather than adding
+modules to @samp{routines} because the latter is used in determining
+what to distribute for each subdirectory of the main source tree.@refill
+
+Each makefile in a subdirectory in the ordered list of subdirectories to
+be searched is included in order.  Since several system-dependent
+makefiles may be included, each should append to @samp{sysdep-routines}
+rather than simply setting it:
+
+@smallexample
+sysdep-routines := $(sysdep-routines) foo bar
+@end smallexample
+
+@need 1000
+@item Subdirs
+
+This file contains the names of new whole subdirectories under the
+top-level library source tree that should be included for this system.
+These subdirectories are treated just like the system-independent
+subdirectories in the library source tree, such as @file{stdio} and
+@file{math}.
+
+Use this when there are completely new sets of functions and header
+files that should go into the library for the system this subdirectory
+of @file{sysdeps} implements.  For example,
+@file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
+directory contains various network-oriented operations which only make
+sense to put in the library on systems that support the Internet.@refill
+
+@item configure
+
+This file is a shell script fragment to be run at configuration time.
+The top-level @file{configure} script uses the shell @code{.} command to
+read the @file{configure} file in each system-dependent directory
+chosen, in order.  The @file{configure} files are often generated from
+@file{configure.ac} files using Autoconf.
+
+A system-dependent @file{configure} script will usually add things to
+the shell variables @samp{DEFS} and @samp{config_vars}; see the
+top-level @file{configure} script for details.  The script can check for
+@w{@samp{--with-@var{package}}} options that were passed to the
+top-level @file{configure}.  For an option
+@w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
+shell variable @w{@samp{with_@var{package}}} (with any dashes in
+@var{package} converted to underscores) to @var{value}; if the option is
+just @w{@samp{--with-@var{package}}} (no argument), then it sets
+@w{@samp{with_@var{package}}} to @samp{yes}.
+
+@item configure.ac
+
+This file is an Autoconf input fragment to be processed into the file
+@file{configure} in this subdirectory.  @xref{Introduction,,,
+autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
+for a description of Autoconf.  You should write either @file{configure}
+or @file{configure.ac}, but not both.  The first line of
+@file{configure.ac} should invoke the @code{m4} macro
+@samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
+for Autoconf macros which are used by the top-level @file{configure}
+script; without this, those macros might be invoked again unnecessarily
+by Autoconf.
+@end table
+
+That is the general system for how system-dependencies are isolated.
+@iftex
+The next section explains how to decide what directories in
+@file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
+the library to Unix variants.
+@end iftex
+
+@menu
+* Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
+* Porting to Unix::             Porting the library to an average
+                                   Unix-like system.
+@end menu
+
+@node Hierarchy Conventions
+@appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
+
+A GNU configuration name has three parts: the CPU type, the
+manufacturer's name, and the operating system.  @file{configure} uses
+these to pick the list of system-dependent directories to look for.  If
+the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
+directory @file{@var{machine}/fpu} is also used.  The operating system
+often has a @dfn{base operating system}; for example, if the operating
+system is @samp{Linux}, the base operating system is @samp{unix/sysv}.
+The algorithm used to pick the list of directories is simple:
+@file{configure} makes a list of the base operating system,
+manufacturer, CPU type, and operating system, in that order.  It then
+concatenates all these together with slashes in between, to produce a
+directory name; for example, the configuration @w{@samp{i686-linux-gnu}}
+results in @file{unix/sysv/linux/i386/i686}.  @file{configure} then
+tries removing each element of the list in turn, so
+@file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others.
+Since the precise version number of the operating system is often not
+important, and it would be very inconvenient, for example, to have
+identical @file{irix6.2} and @file{irix6.3} directories,
+@file{configure} tries successively less specific operating system names
+by removing trailing suffixes starting with a period.
+
+As an example, here is the complete list of directories that would be
+tried for the configuration @w{@samp{i686-linux-gnu}} (with the
+@file{crypt} and @file{linuxthreads} add-on):
+
+@smallexample
+sysdeps/i386/elf
+crypt/sysdeps/unix
+linuxthreads/sysdeps/unix/sysv/linux
+linuxthreads/sysdeps/pthread
+linuxthreads/sysdeps/unix/sysv
+linuxthreads/sysdeps/unix
+linuxthreads/sysdeps/i386/i686
+linuxthreads/sysdeps/i386
+linuxthreads/sysdeps/pthread/no-cmpxchg
+sysdeps/unix/sysv/linux/i386
+sysdeps/unix/sysv/linux
+sysdeps/gnu
+sysdeps/unix/common
+sysdeps/unix/mman
+sysdeps/unix/inet
+sysdeps/unix/sysv/i386/i686
+sysdeps/unix/sysv/i386
+sysdeps/unix/sysv
+sysdeps/unix/i386
+sysdeps/unix
+sysdeps/posix
+sysdeps/i386/i686
+sysdeps/i386/i486
+sysdeps/libm-i387/i686
+sysdeps/i386/fpu
+sysdeps/libm-i387
+sysdeps/i386
+sysdeps/wordsize-32
+sysdeps/ieee754
+sysdeps/libm-ieee754
+sysdeps/generic
+@end smallexample
+
+Different machine architectures are conventionally subdirectories at the
+top level of the @file{sysdeps} directory tree.  For example,
+@w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
+files specific to those machine architectures, but not specific to any
+particular operating system.  There might be subdirectories for
+specializations of those architectures, such as
+@w{@file{sysdeps/m68k/68020}}.  Code which is specific to the
+floating-point coprocessor used with a particular machine should go in
+@w{@file{sysdeps/@var{machine}/fpu}}.
+
+There are a few directories at the top level of the @file{sysdeps}
+hierarchy that are not for particular machine architectures.
+
+@table @file
+@item generic
+As described above (@pxref{Porting}), this is the subdirectory
+that every configuration implicitly uses after all others.
+
+@item ieee754
+This directory is for code using the IEEE 754 floating-point format,
+where the C type @code{float} is IEEE 754 single-precision format, and
+@code{double} is IEEE 754 double-precision format.  Usually this
+directory is referred to in the @file{Implies} file in a machine
+architecture-specific directory, such as @file{m68k/Implies}.
+
+@item libm-ieee754
+This directory contains an implementation of a mathematical library
+usable on platforms which use @w{IEEE 754} conformant floating-point
+arithmetic.
+
+@item libm-i387
+This is a special case.  Ideally the code should be in
+@file{sysdeps/i386/fpu} but for various reasons it is kept aside.
+
+@item posix
+This directory contains implementations of things in the library in
+terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
+functions themselves.  Of course, @sc{POSIX.1} cannot be completely
+implemented in terms of itself, so a configuration using just
+@file{posix} cannot be complete.
+
+@item unix
+This is the directory for Unix-like things.  @xref{Porting to Unix}.
+@file{unix} implies @file{posix}.  There are some special-purpose
+subdirectories of @file{unix}:
+
+@table @file
+@item unix/common
+This directory is for things common to both BSD and System V release 4.
+Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
+
+@item unix/inet
+This directory is for @code{socket} and related functions on Unix systems.
+@file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory.
+@file{unix/common} implies @file{unix/inet}.
+@end table
+
+@item mach
+This is the directory for things based on the Mach microkernel from CMU
+(including @gnuhurdsystems{}).  Other basic operating systems
+(VMS, for example) would have their own directories at the top level of
+the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
+@end table
+
+@node Porting to Unix
+@appendixsubsec Porting @theglibc{} to Unix Systems
+
+Most Unix systems are fundamentally very similar.  There are variations
+between different machines, and variations in what facilities are
+provided by the kernel.  But the interface to the operating system
+facilities is, for the most part, pretty uniform and simple.
+
+The code for Unix systems is in the directory @file{unix}, at the top
+level of the @file{sysdeps} hierarchy.  This directory contains
+subdirectories (and subdirectory trees) for various Unix variants.
+
+The functions which are system calls in most Unix systems are
+implemented in assembly code, which is generated automatically from
+specifications in files named @file{syscalls.list}.  There are several
+such files, one in @file{sysdeps/unix} and others in its subdirectories.
+Some special system calls are implemented in files that are named with a
+suffix of @samp{.S}; for example, @file{_exit.S}.  Files ending in
+@samp{.S} are run through the C preprocessor before being fed to the
+assembler.
+
+These files all use a set of macros that should be defined in
+@file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
+partially defines them; a @file{sysdep.h} file in another directory must
+finish defining them for the particular machine and operating system
+variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
+@file{sysdep.h} implementations to see what these macros are and what
+they should do.@refill
+
+The system-specific makefile for the @file{unix} directory
+(@file{sysdeps/unix/Makefile}) gives rules to generate several files
+from the Unix system you are building the library on (which is assumed
+to be the target system you are building the library @emph{for}).  All
+the generated files are put in the directory where the object files are
+kept; they should not affect the source tree itself.  The files
+generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
+@file{errlist.c} (for the @file{stdio} section of the library).
+
+@ignore
+@c This section might be a good idea if it is finished,
+@c but there's no point including it as it stands. --rms
+@c @appendixsec Compatibility with Traditional C
+
+@c ??? This section is really short now.  Want to keep it? --roland
+
+@c It's not anymore true.  glibc 2.1 cannot be used with K&R compilers.
+@c --drepper
+
+Although @theglibc{} implements the @w{ISO C} library facilities, you
+@emph{can} use @theglibc{} with traditional, ``pre-ISO'' C
+compilers.  However, you need to be careful because the content and
+organization of the @glibcadj{} header files differs from that of
+traditional C implementations.  This means you may need to make changes
+to your program in order to get it to compile.
+@end ignore
diff --git a/ap/libc/glibc/glibc-2.23/manual/math.texi b/ap/libc/glibc/glibc-2.23/manual/math.texi
new file mode 100644
index 0000000..72f3fda
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/math.texi
@@ -0,0 +1,2035 @@
+@c We need some definitions here.
+@ifclear mult
+@ifhtml
+@set mult &middot;
+@set infty &infin;
+@set pie &pi;
+@end ifhtml
+@iftex
+@set mult @cdot
+@set infty @infty
+@end iftex
+@ifclear mult
+@set mult *
+@set infty oo
+@set pie pi
+@end ifclear
+@macro mul
+@value{mult}
+@end macro
+@macro infinity
+@value{infty}
+@end macro
+@ifnottex
+@macro pi
+@value{pie}
+@end macro
+@end ifnottex
+@end ifclear
+
+@node Mathematics, Arithmetic, Syslog, Top
+@c %MENU% Math functions, useful constants, random numbers
+@chapter Mathematics
+
+This chapter contains information about functions for performing
+mathematical computations, such as trigonometric functions.  Most of
+these functions have prototypes declared in the header file
+@file{math.h}.  The complex-valued functions are defined in
+@file{complex.h}.
+@pindex math.h
+@pindex complex.h
+
+All mathematical functions which take a floating-point argument
+have three variants, one each for @code{double}, @code{float}, and
+@code{long double} arguments.  The @code{double} versions are mostly
+defined in @w{ISO C89}.  The @code{float} and @code{long double}
+versions are from the numeric extensions to C included in @w{ISO C99}.
+
+Which of the three versions of a function should be used depends on the
+situation.  For most calculations, the @code{float} functions are the
+fastest.  On the other hand, the @code{long double} functions have the
+highest precision.  @code{double} is somewhere in between.  It is
+usually wise to pick the narrowest type that can accommodate your data.
+Not all machines have a distinct @code{long double} type; it may be the
+same as @code{double}.
+
+@menu
+* Mathematical Constants::      Precise numeric values for often-used
+                                 constants.
+* Trig Functions::              Sine, cosine, tangent, and friends.
+* Inverse Trig Functions::      Arcsine, arccosine, etc.
+* Exponents and Logarithms::    Also pow and sqrt.
+* Hyperbolic Functions::        sinh, cosh, tanh, etc.
+* Special Functions::           Bessel, gamma, erf.
+* Errors in Math Functions::    Known Maximum Errors in Math Functions.
+* Pseudo-Random Numbers::       Functions for generating pseudo-random
+				 numbers.
+* FP Function Optimizations::   Fast code or small code.
+@end menu
+
+@node Mathematical Constants
+@section Predefined Mathematical Constants
+@cindex constants
+@cindex mathematical constants
+
+The header @file{math.h} defines several useful mathematical constants.
+All values are defined as preprocessor macros starting with @code{M_}.
+The values provided are:
+
+@vtable @code
+@item M_E
+The base of natural logarithms.
+@item M_LOG2E
+The logarithm to base @code{2} of @code{M_E}.
+@item M_LOG10E
+The logarithm to base @code{10} of @code{M_E}.
+@item M_LN2
+The natural logarithm of @code{2}.
+@item M_LN10
+The natural logarithm of @code{10}.
+@item M_PI
+Pi, the ratio of a circle's circumference to its diameter.
+@item M_PI_2
+Pi divided by two.
+@item M_PI_4
+Pi divided by four.
+@item M_1_PI
+The reciprocal of pi (1/pi)
+@item M_2_PI
+Two times the reciprocal of pi.
+@item M_2_SQRTPI
+Two times the reciprocal of the square root of pi.
+@item M_SQRT2
+The square root of two.
+@item M_SQRT1_2
+The reciprocal of the square root of two (also the square root of 1/2).
+@end vtable
+
+These constants come from the Unix98 standard and were also available in
+4.4BSD; therefore they are only defined if
+@code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
+defined.  The default set of features includes these constants.
+@xref{Feature Test Macros}.
+
+All values are of type @code{double}.  As an extension, @theglibc{}
+also defines these constants with type @code{long double}.  The
+@code{long double} macros have a lowercase @samp{l} appended to their
+names: @code{M_El}, @code{M_PIl}, and so forth.  These are only
+available if @code{_GNU_SOURCE} is defined.
+
+@vindex PI
+@emph{Note:} Some programs use a constant named @code{PI} which has the
+same value as @code{M_PI}.  This constant is not standard; it may have
+appeared in some old AT&T headers, and is mentioned in Stroustrup's book
+on C++.  It infringes on the user's name space, so @theglibc{}
+does not define it.  Fixing programs written to expect it is simple:
+replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
+on the compiler command line.
+
+@node Trig Functions
+@section Trigonometric Functions
+@cindex trigonometric functions
+
+These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
+The arguments to all of these functions are in units of radians; recall
+that pi radians equals 180 degrees.
+
+@cindex pi (trigonometric constant)
+The math library normally defines @code{M_PI} to a @code{double}
+approximation of pi.  If strict ISO and/or POSIX compliance
+are requested this constant is not defined, but you can easily define it
+yourself:
+
+@smallexample
+#define M_PI 3.14159265358979323846264338327
+@end smallexample
+
+@noindent
+You can also compute the value of pi with the expression @code{acos
+(-1.0)}.
+
+@comment math.h
+@comment ISO
+@deftypefun double sin (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float sinf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sinl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the sine of @var{x}, where @var{x} is given in
+radians.  The return value is in the range @code{-1} to @code{1}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double cos (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float cosf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} cosl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the cosine of @var{x}, where @var{x} is given in
+radians.  The return value is in the range @code{-1} to @code{1}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double tan (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float tanf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} tanl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the tangent of @var{x}, where @var{x} is given in
+radians.
+
+Mathematically, the tangent function has singularities at odd multiples
+of pi/2.  If the argument @var{x} is too close to one of these
+singularities, @code{tan} will signal overflow.
+@end deftypefun
+
+In many applications where @code{sin} and @code{cos} are used, the sine
+and cosine of the same angle are needed at the same time.  It is more
+efficient to compute them simultaneously, so the library provides a
+function to do that.
+
+@comment math.h
+@comment GNU
+@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the sine of @var{x} in @code{*@var{sinx}} and the
+cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
+radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
+the range of @code{-1} to @code{1}.
+
+This function is a GNU extension.  Portable programs should be prepared
+to cope with its absence.
+@end deftypefun
+
+@cindex complex trigonometric functions
+
+@w{ISO C99} defines variants of the trig functions which work on
+complex numbers.  @Theglibc{} provides these functions, but they
+are only useful if your compiler supports the new complex types defined
+by the standard.
+@c XXX Change this when gcc is fixed. -zw
+(As of this writing GCC supports complex numbers, but there are bugs in
+the implementation.)
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csinl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c There are calls to nan* that could trigger @mtslocale if they didn't get
+@c empty strings.
+These functions return the complex sine of @var{z}.
+The mathematical definition of the complex sine is
+
+@ifnottex
+@math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
+@end ifnottex
+@tex
+$$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
+@end tex
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ccosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ccosl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex cosine of @var{z}.
+The mathematical definition of the complex cosine is
+
+@ifnottex
+@math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
+@end ifnottex
+@tex
+$$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
+@end tex
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctan (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ctanf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ctanl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex tangent of @var{z}.
+The mathematical definition of the complex tangent is
+
+@ifnottex
+@math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
+@end ifnottex
+@tex
+$$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
+@end tex
+
+@noindent
+The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
+integer.  @code{ctan} may signal overflow if @var{z} is too close to a
+pole.
+@end deftypefun
+
+
+@node Inverse Trig Functions
+@section Inverse Trigonometric Functions
+@cindex inverse trigonometric functions
+
+These are the usual arc sine, arc cosine and arc tangent functions,
+which are the inverses of the sine, cosine and tangent functions
+respectively.
+
+@comment math.h
+@comment ISO
+@deftypefun double asin (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float asinf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} asinl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the arc sine of @var{x}---that is, the value whose
+sine is @var{x}.  The value is in units of radians.  Mathematically,
+there are infinitely many such values; the one actually returned is the
+one between @code{-pi/2} and @code{pi/2} (inclusive).
+
+The arc sine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{asin} signals a domain error.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double acos (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float acosf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} acosl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the arc cosine of @var{x}---that is, the value
+whose cosine is @var{x}.  The value is in units of radians.
+Mathematically, there are infinitely many such values; the one actually
+returned is the one between @code{0} and @code{pi} (inclusive).
+
+The arc cosine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{acos} signals a domain error.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double atan (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float atanf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atanl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the arc tangent of @var{x}---that is, the value
+whose tangent is @var{x}.  The value is in units of radians.
+Mathematically, there are infinitely many such values; the one actually
+returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double atan2 (double @var{y}, double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float atan2f (float @var{y}, float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function computes the arc tangent of @var{y}/@var{x}, but the signs
+of both arguments are used to determine the quadrant of the result, and
+@var{x} is permitted to be zero.  The return value is given in radians
+and is in the range @code{-pi} to @code{pi}, inclusive.
+
+If @var{x} and @var{y} are coordinates of a point in the plane,
+@code{atan2} returns the signed angle between the line from the origin
+to that point and the x-axis.  Thus, @code{atan2} is useful for
+converting Cartesian coordinates to polar coordinates.  (To compute the
+radial coordinate, use @code{hypot}; see @ref{Exponents and
+Logarithms}.)
+
+@c This is experimentally true.  Should it be so? -zw
+If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
+@end deftypefun
+
+@cindex inverse complex trigonometric functions
+@w{ISO C99} defines complex versions of the inverse trig functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} casinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} casinl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the complex arc sine of @var{z}---that is, the
+value whose sine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{casin} is defined for all
+values of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacosl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the complex arc cosine of @var{z}---that is, the
+value whose cosine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{cacos} is defined for all
+values of @var{z}.
+@end deftypefun
+
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catan (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} catanf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} catanl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the complex arc tangent of @var{z}---that is,
+the value whose tangent is @var{z}.  The value is in units of radians.
+@end deftypefun
+
+
+@node Exponents and Logarithms
+@section Exponentiation and Logarithms
+@cindex exponentiation functions
+@cindex power functions
+@cindex logarithm functions
+
+@comment math.h
+@comment ISO
+@deftypefun double exp (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float expf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} expl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute @code{e} (the base of natural logarithms) raised
+to the power @var{x}.
+
+If the magnitude of the result is too large to be representable,
+@code{exp} signals overflow.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double exp2 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float exp2f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} exp2l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute @code{2} raised to the power @var{x}.
+Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun double exp10 (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float exp10f (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} exp10l (long double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx double pow10 (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float pow10f (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} pow10l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute @code{10} raised to the power @var{x}.
+Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
+
+These functions are GNU extensions.  The name @code{exp10} is
+preferred, since it is analogous to @code{exp} and @code{exp2}.
+@end deftypefun
+
+
+@comment math.h
+@comment ISO
+@deftypefun double log (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float logf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} logl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions compute the natural logarithm of @var{x}.  @code{exp (log
+(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
+C.
+
+If @var{x} is negative, @code{log} signals a domain error.  If @var{x}
+is zero, it returns negative infinity; if @var{x} is too close to zero,
+it may signal overflow.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double log10 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log10f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log10l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the base-10 logarithm of @var{x}.
+@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
+
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double log2 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log2f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log2l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the base-2 logarithm of @var{x}.
+@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double logb (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float logbf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} logbl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions extract the exponent of @var{x} and return it as a
+floating-point value.  If @code{FLT_RADIX} is two, @code{logb} is equal
+to @code{floor (log2 (x))}, except it's probably faster.
+
+If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
+would have if it were normalized.  If @var{x} is infinity (positive or
+negative), @code{logb} returns @math{@infinity{}}.  If @var{x} is zero,
+@code{logb} returns @math{@infinity{}}.  It does not signal.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int ilogb (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx int ilogbf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx int ilogbl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions are equivalent to the corresponding @code{logb}
+functions except that they return signed integer values.
+@end deftypefun
+
+@noindent
+Since integers cannot represent infinity and NaN, @code{ilogb} instead
+returns an integer that can't be the exponent of a normal floating-point
+number.  @file{math.h} defines constants so you can check for this.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGB0
+@code{ilogb} returns this value if its argument is @code{0}.  The
+numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGBNAN
+@code{ilogb} returns this value if its argument is @code{NaN}.  The
+numeric value is either @code{INT_MIN} or @code{INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr
+
+These values are system specific.  They might even be the same.  The
+proper way to test the result of @code{ilogb} is as follows:
+
+@smallexample
+i = ilogb (f);
+if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
+  @{
+    if (isnan (f))
+      @{
+        /* @r{Handle NaN.}  */
+      @}
+    else if (f  == 0.0)
+      @{
+        /* @r{Handle 0.0.}  */
+      @}
+    else
+      @{
+        /* @r{Some other value with large exponent,}
+           @r{perhaps +Inf.}  */
+      @}
+  @}
+@end smallexample
+
+@comment math.h
+@comment ISO
+@deftypefun double pow (double @var{base}, double @var{power})
+@comment math.h
+@comment ISO
+@deftypefunx float powf (float @var{base}, float @var{power})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} powl (long double @var{base}, long double @var{power})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These are general exponentiation functions, returning @var{base} raised
+to @var{power}.
+
+Mathematically, @code{pow} would return a complex number when @var{base}
+is negative and @var{power} is not an integral value.  @code{pow} can't
+do that, so instead it signals a domain error. @code{pow} may also
+underflow or overflow the destination type.
+@end deftypefun
+
+@cindex square root function
+@comment math.h
+@comment ISO
+@deftypefun double sqrt (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float sqrtf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sqrtl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the nonnegative square root of @var{x}.
+
+If @var{x} is negative, @code{sqrt} signals a domain error.
+Mathematically, it should return a complex number.
+@end deftypefun
+
+@cindex cube root function
+@comment math.h
+@comment BSD
+@deftypefun double cbrt (double @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx float cbrtf (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} cbrtl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the cube root of @var{x}.  They cannot
+fail; every representable real value has a representable real cube root.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double hypot (double @var{x}, double @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx float hypotf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return @code{sqrt (@var{x}*@var{x} +
+@var{y}*@var{y})}.  This is the length of the hypotenuse of a right
+triangle with sides of length @var{x} and @var{y}, or the distance
+of the point (@var{x}, @var{y}) from the origin.  Using this function
+instead of the direct formula is wise, since the error is
+much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double expm1 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float expm1f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} expm1l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return a value equivalent to @code{exp (@var{x}) - 1}.
+They are computed in a way that is accurate even if @var{x} is
+near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
+to subtraction of two numbers that are nearly equal.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double log1p (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log1pf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log1pl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
+They are computed in a way that is accurate even if @var{x} is
+near zero.
+@end deftypefun
+
+@cindex complex exponentiation functions
+@cindex complex logarithm functions
+
+@w{ISO C99} defines complex variants of some of the exponentiation and
+logarithm functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cexp (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cexpf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cexpl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return @code{e} (the base of natural
+logarithms) raised to the power of @var{z}.
+Mathematically, this corresponds to the value
+
+@ifnottex
+@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
+@end ifnottex
+@tex
+$$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
+@end tex
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} clog (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} clogf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} clogl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the natural logarithm of @var{z}.
+Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log(z) = \log |z| + i \arg z$$
+@end tex
+
+@noindent
+@code{clog} has a pole at 0, and will signal overflow if @var{z} equals
+or is very close to 0.  It is well-defined for all other values of
+@var{z}.
+@end deftypefun
+
+
+@comment complex.h
+@comment GNU
+@deftypefun {complex double} clog10 (complex double @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex float} clog10f (complex float @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex long double} clog10l (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the base 10 logarithm of the complex value
+@var{z}.  Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log10 (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log_{10}(z) = \log_{10}|z| + i \arg z$$
+@end tex
+
+These functions are GNU extensions.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csqrt (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csqrtf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csqrtl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex square root of the argument @var{z}.  Unlike
+the real-valued functions, they are defined for all values of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return @var{base} raised to the power of
+@var{power}.  This is equivalent to @w{@code{cexp (y * clog (x))}}
+@end deftypefun
+
+@node Hyperbolic Functions
+@section Hyperbolic Functions
+@cindex hyperbolic functions
+
+The functions in this section are related to the exponential functions;
+see @ref{Exponents and Logarithms}.
+
+@comment math.h
+@comment ISO
+@deftypefun double sinh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float sinhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sinhl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the hyperbolic sine of @var{x}, defined
+mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  They
+may signal overflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double cosh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float coshf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} coshl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These function return the hyperbolic cosine of @var{x},
+defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
+They may signal overflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double tanh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float tanhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} tanhl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the hyperbolic tangent of @var{x},
+defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
+They may signal overflow if @var{x} is too large.
+@end deftypefun
+
+@cindex hyperbolic functions
+
+There are counterparts for the hyperbolic functions which take
+complex arguments.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csinh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csinhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csinhl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex hyperbolic sine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccosh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ccoshf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ccoshl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex hyperbolic cosine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctanh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ctanhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ctanhl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the complex hyperbolic tangent of @var{z},
+defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
+@end deftypefun
+
+
+@cindex inverse hyperbolic functions
+
+@comment math.h
+@comment ISO
+@deftypefun double asinh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float asinhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} asinhl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse hyperbolic sine of @var{x}---the
+value whose hyperbolic sine is @var{x}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double acosh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float acoshf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} acoshl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse hyperbolic cosine of @var{x}---the
+value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
+@code{1}, @code{acosh} signals a domain error.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double atanh (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float atanhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atanhl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse hyperbolic tangent of @var{x}---the
+value whose hyperbolic tangent is @var{x}.  If the absolute value of
+@var{x} is greater than @code{1}, @code{atanh} signals a domain error;
+if it is equal to 1, @code{atanh} returns infinity.
+@end deftypefun
+
+@cindex inverse complex hyperbolic functions
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casinh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} casinhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} casinhl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse complex hyperbolic sine of
+@var{z}---the value whose complex hyperbolic sine is @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacosh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacoshf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacoshl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse complex hyperbolic cosine of
+@var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catanh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} catanhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} catanhl (complex long double @var{z})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+These functions return the inverse complex hyperbolic tangent of
+@var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of
+@var{z}.
+@end deftypefun
+
+@node Special Functions
+@section Special Functions
+@cindex special functions
+@cindex Bessel functions
+@cindex gamma function
+
+These are some more exotic mathematical functions which are sometimes
+useful.  Currently they only have real-valued versions.
+
+@comment math.h
+@comment SVID
+@deftypefun double erf (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float erff (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} erfl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{erf} returns the error function of @var{x}.  The error
+function is defined as
+@tex
+$$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
+@end smallexample
+@end ifnottex
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double erfc (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float erfcf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} erfcl (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
+fashion that avoids round-off error when @var{x} is large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double lgamma (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float lgammaf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} lgammal (long double @var{x})
+@safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
+@code{lgamma} returns the natural logarithm of the absolute value of
+the gamma function of @var{x}.  The gamma function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+@vindex signgam
+The sign of the gamma function is stored in the global variable
+@var{signgam}, which is declared in @file{math.h}.  It is @code{1} if
+the intermediate result was positive or zero, or @code{-1} if it was
+negative.
+
+To compute the real gamma function you can use the @code{tgamma}
+function or you can compute the values as follows:
+@smallexample
+lgam = lgamma(x);
+gam  = signgam*exp(lgam);
+@end smallexample
+
+The gamma function has singularities at the non-positive integers.
+@code{lgamma} will raise the zero divide exception if evaluated at a
+singularity.
+@end deftypefun
+
+@comment math.h
+@comment XPG
+@deftypefun double lgamma_r (double @var{x}, int *@var{signp})
+@comment math.h
+@comment XPG
+@deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
+@comment math.h
+@comment XPG
+@deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@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.  This means it is reentrant.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double gamma (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float gammaf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} gammal (long double @var{x})
+@safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
+These functions exist for compatibility reasons.  They are equivalent to
+@code{lgamma} etc.  It is better to use @code{lgamma} since for one the
+name reflects better the actual computation, moreover @code{lgamma} is
+standardized in @w{ISO C99} while @code{gamma} is not.
+@end deftypefun
+
+@comment math.h
+@comment XPG, ISO
+@deftypefun double tgamma (double @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx float tgammaf (float @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx {long double} tgammal (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{tgamma} applies the gamma function to @var{x}.  The gamma
+function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+This function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double j0 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float j0f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} j0l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{j0} returns the Bessel function of the first kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double j1 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float j1f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} j1l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{j1} returns the Bessel function of the first kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double jn (int @var{n}, double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float jnf (int @var{n}, float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} jnl (int @var{n}, long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{jn} returns the Bessel function of the first kind of order
+@var{n} of @var{x}.  It may signal underflow if @var{x} is too large.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double y0 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float y0f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} y0l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{y0} returns the Bessel function of the second kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y0} signals a domain error; if it is zero,
+@code{y0} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double y1 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float y1f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} y1l (long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{y1} returns the Bessel function of the second kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y1} signals a domain error; if it is zero,
+@code{y1} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@comment math.h
+@comment SVID
+@deftypefun double yn (int @var{n}, double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float ynf (int @var{n}, float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} ynl (int @var{n}, long double @var{x})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{yn} returns the Bessel function of the second kind of order @var{n} of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{yn} signals a domain error; if it is zero,
+@code{yn} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@node Errors in Math Functions
+@section Known Maximum Errors in Math Functions
+@cindex math errors
+@cindex ulps
+
+This section lists the known errors of the functions in the math
+library.  Errors are measured in ``units of the last place''.  This is a
+measure for the relative error.  For a number @math{z} with the
+representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
+floating-point numbers with base 2) the ULP is represented by
+
+@tex
+$${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
+@end tex
+@ifnottex
+@smallexample
+|d.d...d - (z / 2^e)| / 2^(p - 1)
+@end smallexample
+@end ifnottex
+
+@noindent
+where @math{p} is the number of bits in the mantissa of the
+floating-point number representation.  Ideally the error for all
+functions is always less than 0.5ulps in round-to-nearest mode.  Using
+rounding bits this is also
+possible and normally implemented for the basic operations.  Except
+for certain functions such as @code{sqrt}, @code{fma} and @code{rint}
+whose results are fully specified by reference to corresponding IEEE
+754 floating-point operations, and conversions between strings and
+floating point, @theglibc{} does not aim for correctly rounded results
+for functions in the math library, and does not aim for correctness in
+whether ``inexact'' exceptions are raised.  Instead, the goals for
+accuracy of functions without fully specified results are as follows;
+some functions have bugs meaning they do not meet these goals in all
+cases.  In future, @theglibc{} may provide some other correctly
+rounding functions under the names such as @code{crsin} proposed for
+an extension to ISO C.
+
+@itemize @bullet
+
+@item
+Each function with a floating-point result behaves as if it computes
+an infinite-precision result that is within a few ulp (in both real
+and complex parts, for functions with complex results) of the
+mathematically correct value of the function (interpreted together
+with ISO C or POSIX semantics for the function in question) at the
+exact value passed as the input.  Exceptions are raised appropriately
+for this value and in accordance with IEEE 754 / ISO C / POSIX
+semantics, and it is then rounded according to the current rounding
+direction to the result that is returned to the user.  @code{errno}
+may also be set (@pxref{Math Error Reporting}).  (The ``inexact''
+exception may be raised, or not raised, even if this is inconsistent
+with the infinite-precision value.)
+
+@item
+For the IBM @code{long double} format, as used on PowerPC GNU/Linux,
+the accuracy goal is weaker for input values not exactly representable
+in 106 bits of precision; it is as if the input value is some value
+within 0.5ulp of the value actually passed, where ``ulp'' is
+interpreted in terms of a fixed-precision 106-bit mantissa, but not
+necessarily the exact value actually passed with discontiguous
+mantissa bits.
+
+@item
+Functions behave as if the infinite-precision result computed is zero,
+infinity or NaN if and only if that is the mathematically correct
+infinite-precision result.  They behave as if the infinite-precision
+result computed always has the same sign as the mathematically correct
+result.
+
+@item
+If the mathematical result is more than a few ulp above the overflow
+threshold for the current rounding direction, the value returned is
+the appropriate overflow value for the current rounding direction,
+with the overflow exception raised.
+
+@item
+If the mathematical result has magnitude well below half the least
+subnormal magnitude, the returned value is either zero or the least
+subnormal (in each case, with the correct sign), according to the
+current rounding direction and with the underflow exception raised.
+
+@item
+Where the mathematical result underflows (before rounding) and is not
+exactly representable as a floating-point value, the function does not
+behave as if the computed infinite-precision result is an exact value
+in the subnormal range.  This means that the underflow exception is
+raised other than possibly for cases where the mathematical result is
+very close to the underflow threshold and the function behaves as if
+it computes an infinite-precision result that does not underflow.  (So
+there may be spurious underflow exceptions in cases where the
+underflowing result is exact, but not missing underflow exceptions in
+cases where it is inexact.)
+
+@item
+@Theglibc{} does not aim for functions to satisfy other properties of
+the underlying mathematical function, such as monotonicity, where not
+implied by the above goals.
+
+@item
+All the above applies to both real and complex parts, for complex
+functions.
+
+@end itemize
+
+Therefore many of the functions in the math library have errors.  The
+table lists the maximum error for each function which is exposed by one
+of the existing tests in the test suite.  The table tries to cover as much
+as possible and list the actual maximum error (or at least a ballpark
+figure) but this is often not achieved due to the large search space.
+
+The table lists the ULP values for different architectures.  Different
+architectures have different results since their hardware support for
+floating-point operations varies and also the existing hardware support
+is different.
+
+@page
+@c This multitable does not fit on a single page
+@include libm-err.texi
+
+@node Pseudo-Random Numbers
+@section Pseudo-Random Numbers
+@cindex random numbers
+@cindex pseudo-random numbers
+@cindex seed (for random numbers)
+
+This section describes the GNU facilities for generating a series of
+pseudo-random numbers.  The numbers generated are not truly random;
+typically, they form a sequence that repeats periodically, with a period
+so large that you can ignore it for ordinary purposes.  The random
+number generator works by remembering a @dfn{seed} value which it uses
+to compute the next random number and also to compute a new seed.
+
+Although the generated numbers look unpredictable within one run of a
+program, the sequence of numbers is @emph{exactly the same} from one run
+to the next.  This is because the initial seed is always the same.  This
+is convenient when you are debugging a program, but it is unhelpful if
+you want the program to behave unpredictably.  If you want a different
+pseudo-random series each time your program runs, you must specify a
+different seed each time.  For ordinary purposes, basing the seed on the
+current time works well.
+
+You can obtain repeatable sequences of numbers on a particular machine type
+by specifying the same initial seed value for the random number
+generator.  There is no standard meaning for a particular seed value;
+the same seed, used in different C libraries or on different CPU types,
+will give you different random numbers.
+
+@Theglibc{} supports the standard @w{ISO C} random number functions
+plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
+functions provide identical, somewhat limited functionality.  If only a
+small number of random bits are required, we recommend you use the
+@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
+provide a more flexible interface, which allows better random number
+generator algorithms, provides more random bits (up to 48) per call, and
+can provide random floating-point numbers.  These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.
+
+@menu
+* ISO Random::                  @code{rand} and friends.
+* BSD Random::                  @code{random} and friends.
+* SVID Random::                 @code{drand48} and friends.
+@end menu
+
+@node ISO Random
+@subsection ISO C Random Number Functions
+
+This section describes the random number functions that are part of
+the @w{ISO C} standard.
+
+To use these facilities, you should include the header file
+@file{stdlib.h} in your program.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ISO
+@deftypevr Macro int RAND_MAX
+The value of this macro is an integer constant representing the largest
+value the @code{rand} function can return.  In @theglibc{}, it is
+@code{2147483647}, which is the largest signed integer representable in
+32 bits.  In other libraries, it may be as low as @code{32767}.
+@end deftypevr
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int rand (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Just calls random.
+The @code{rand} function returns the next pseudo-random number in the
+series.  The value ranges from @code{0} to @code{RAND_MAX}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun void srand (unsigned int @var{seed})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Alias to srandom.
+This function establishes @var{seed} as the seed for a new series of
+pseudo-random numbers.  If you call @code{rand} before a seed has been
+established with @code{srand}, it uses the value @code{1} as a default
+seed.
+
+To produce a different pseudo-random series each time your program is
+run, do @code{srand (time (0))}.
+@end deftypefun
+
+POSIX.1 extended the C standard functions to support reproducible random
+numbers in multi-threaded programs.  However, the extension is badly
+designed and unsuitable for serious work.
+
+@comment stdlib.h
+@comment POSIX.1
+@deftypefun int rand_r (unsigned int *@var{seed})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns a random number in the range 0 to @code{RAND_MAX}
+just as @code{rand} does.  However, all its state is stored in the
+@var{seed} argument.  This means the RNG's state can only have as many
+bits as the type @code{unsigned int} has.  This is far too few to
+provide a good RNG.
+
+If your program requires a reentrant RNG, we recommend you use the
+reentrant GNU extensions to the SVID random number generator.  The
+POSIX.1 interface should only be used when the GNU extensions are not
+available.
+@end deftypefun
+
+
+@node BSD Random
+@subsection BSD Random Number Functions
+
+This section describes a set of random number generation functions that
+are derived from BSD.  There is no advantage to using these functions
+with @theglibc{}; we support them for BSD compatibility only.
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {long int} random (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Takes a lock and calls random_r with an automatic variable and the
+@c global state, while holding a lock.
+This function returns the next pseudo-random number in the sequence.
+The value returned ranges from @code{0} to @code{2147483647}.
+
+@strong{NB:} Temporarily this function was defined to return a
+@code{int32_t} value to indicate that the return value always contains
+32 bits even if @code{long int} is wider.  The standard demands it
+differently.  Users must always be aware of the 32-bit limitation,
+though.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun void srandom (unsigned int @var{seed})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Takes a lock and calls srandom_r with an automatic variable and a
+@c static buffer.  There's no MT-safety issue because the static buffer
+@c is internally protected by a lock, although other threads may modify
+@c the set state before it is used.
+The @code{srandom} function sets the state of the random number
+generator based on the integer @var{seed}.  If you supply a @var{seed} value
+of @code{1}, this will cause @code{random} to reproduce the default set
+of random numbers.
+
+To produce a different set of pseudo-random numbers each time your
+program runs, do @code{srandom (time (0))}.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{initstate} function is used to initialize the random number
+generator state.  The argument @var{state} is an array of @var{size}
+bytes, used to hold the state information.  It is initialized based on
+@var{seed}.  The size must be between 8 and 256 bytes, and should be a
+power of two.  The bigger the @var{state} array, the better.
+
+The return value is the previous value of the state information array.
+You can use this value later as an argument to @code{setstate} to
+restore that state.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun {char *} setstate (char *@var{state})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+The @code{setstate} function restores the random number state
+information @var{state}.  The argument must have been the result of
+a previous call to @var{initstate} or @var{setstate}.
+
+The return value is the previous value of the state information array.
+You can use this value later as an argument to @code{setstate} to
+restore that state.
+
+If the function fails the return value is @code{NULL}.
+@end deftypefun
+
+The four functions described so far in this section all work on a state
+which is shared by all threads.  The state is not directly accessible to
+the user and can only be modified by these functions.  This makes it
+hard to deal with situations where each thread should have its own
+pseudo-random number generator.
+
+@Theglibc{} contains four additional functions which contain the
+state as an explicit parameter and therefore make it possible to handle
+thread-local PRNGs.  Beside this there is no difference.  In fact, the
+four functions already discussed are implemented internally using the
+following interfaces.
+
+The @file{stdlib.h} header contains a definition of the following type:
+
+@comment stdlib.h
+@comment GNU
+@deftp {Data Type} {struct random_data}
+
+Objects of type @code{struct random_data} contain the information
+necessary to represent the state of the PRNG.  Although a complete
+definition of the type is present the type should be treated as opaque.
+@end deftp
+
+The functions modifying the state follow exactly the already described
+functions.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{random_r} function behaves exactly like the @code{random}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{srandom_r} function behaves exactly like the @code{srandom}
+function except that it uses and modifies the state in the object
+pointed to by the second parameter instead of the global state.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{initstate_r} function behaves exactly like the @code{initstate}
+function except that it uses and modifies the state in the object
+pointed to by the fourth parameter instead of the global state.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
+@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{setstate_r} function behaves exactly like the @code{setstate}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
+@end deftypefun
+
+@node SVID Random
+@subsection SVID Random Number Function
+
+The C library on SVID systems contains yet another kind of random number
+generator functions.  They use a state of 48 bits of data.  The user can
+choose among a collection of functions which return the random bits
+in different forms.
+
+Generally there are two kinds of function.  The first uses a state of
+the random number generator which is shared among several functions and
+by all threads of the process.  The second requires the user to handle
+the state.
+
+All functions have in common that they use the same congruential
+formula with the same constants.  The formula is
+
+@smallexample
+Y = (a * X + c) mod m
+@end smallexample
+
+@noindent
+where @var{X} is the state of the generator at the beginning and
+@var{Y} the state at the end.  @code{a} and @code{c} are constants
+determining the way the generator works.  By default they are
+
+@smallexample
+a = 0x5DEECE66D = 25214903917
+c = 0xb = 11
+@end smallexample
+
+@noindent
+but they can also be changed by the user.  @code{m} is of course 2^48
+since the state consists of a 48-bit array.
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+
+@comment stdlib.h
+@comment SVID
+@deftypefun double drand48 (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+@c Uses of the static state buffer are not guarded by a lock (thus
+@c @mtasurace:drand48), so they may be found or left at a
+@c partially-updated state in case of calls from within signal handlers
+@c or cancellation.  None of this will break safety rules or invoke
+@c undefined behavior, but it may affect randomness.
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive).  The random bits are determined by the global
+state of the random number generator in the C library.
+
+Since the @code{double} type according to @w{IEEE 754} has a 52-bit
+mantissa this means 4 bits are not initialized by the random number
+generator.  These are (of course) chosen to be the least significant
+bits and they are initialized to @code{0}.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+@c The static buffer is just initialized with default parameters, which
+@c are later read to advance the state held in xsubi.
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
+an array describing the state of the random number generator.
+
+This function can be called subsequently since it updates the array to
+guarantee random numbers.  The array should have been initialized before
+initial use to obtain reproducible results.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} lrand48 (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{lrand48} function returns an integer value in the range of
+@code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
+int} type can take more than 32 bits, no higher numbers are returned.
+The random bits are determined by the global state of the random number
+generator in the C library.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to the @code{lrand48} function in that it
+returns a number in the range of @code{0} to @code{2^31} (exclusive) but
+the state of the random number generator used to produce the random bits
+is determined by the array provided as the parameter to the function.
+
+The numbers in the array are updated afterwards so that subsequent calls
+to this function yield different results (as is expected of a random
+number generator).  The array should have been initialized before the
+first call to obtain reproducible results.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} mrand48 (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{mrand48} function is similar to @code{lrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{jrand48} function is similar to @code{nrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).  For the @code{xsubi} parameter the same
+requirements are necessary.
+@end deftypefun
+
+The internal state of the random number generator can be initialized in
+several ways.  The methods differ in the completeness of the
+information provided.
+
+@comment stdlib.h
+@comment SVID
+@deftypefun void srand48 (long int @var{seedval})
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{srand48} function sets the most significant 32 bits of the
+internal state of the random number generator to the least
+significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
+are initialized to the value @code{0x330E}.  Even if the @code{long
+int} type contains more than 32 bits only the lower 32 bits are used.
+
+Owing to this limitation, initialization of the state of this
+function is not very useful.  But it makes it easy to use a construct
+like @code{srand48 (time (0))}.
+
+A side-effect of this function is that the values @code{a} and @code{c}
+from the internal state, which are used in the congruential formula,
+are reset to the default values given above.  This is of importance once
+the user has called the @code{lcong48} function (see below).
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{seed48} function initializes all 48 bits of the state of the
+internal random number generator from the contents of the parameter
+@var{seed16v}.  Here the lower 16 bits of the first element of
+@var{see16v} initialize the least significant 16 bits of the internal
+state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
+16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
+initialize the most significant 16 bits of the state.
+
+Unlike @code{srand48} this function lets the user initialize all 48 bits
+of the state.
+
+The value returned by @code{seed48} is a pointer to an array containing
+the values of the internal state before the change.  This might be
+useful to restart the random number generator at a certain state.
+Otherwise the value can simply be ignored.
+
+As for @code{srand48}, the values @code{a} and @code{c} from the
+congruential formula are reset to the default values.
+@end deftypefun
+
+There is one more function to initialize the random number generator
+which enables you to specify even more information by allowing you to
+change the parameters in the congruential formula.
+
+@comment stdlib.h
+@comment SVID
+@deftypefun void lcong48 (unsigned short int @var{param}[7])
+@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+The @code{lcong48} function allows the user to change the complete state
+of the random number generator.  Unlike @code{srand48} and
+@code{seed48}, this function also changes the constants in the
+congruential formula.
+
+From the seven elements in the array @var{param} the least significant
+16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
+determine the initial state, the least significant 16 bits of
+@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
+constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
+@code{c}.
+@end deftypefun
+
+All the above functions have in common that they use the global
+parameters for the congruential formula.  In multi-threaded programs it
+might sometimes be useful to have different parameters in different
+threads.  For this reason all the above functions have a counterpart
+which works on a description of the random number generator in the
+user-supplied buffer instead of the global state.
+
+Please note that it is no problem if several threads use the global
+state if all threads use the functions which take a pointer to an array
+containing the state.  The random numbers are computed following the
+same loop but if the state in the array is different all threads will
+obtain an individual random number generator.
+
+The user-supplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and not manipulated directly.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is equivalent to the @code{drand48} function with the
+difference that it does not modify the global random number generator
+parameters but instead the parameters in the buffer supplied through the
+pointer @var{buffer}.  The random number is returned in the variable
+pointed to by @var{result}.
+
+The return value of the function indicates whether the call succeeded.
+If the value is less than @code{0} an error occurred and @var{errno} is
+set to indicate the problem.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{erand48_r} function works like @code{erand48}, but in addition
+it takes an argument @var{buffer} which describes the random number
+generator.  The state of the random number generator is taken from the
+@code{xsubi} array, the parameters for the congruential formula from the
+global random number generator data.  The random number is returned in
+the variable pointed to by @var{result}.
+
+The return value is non-negative if the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{lrand48}, but in addition it takes a
+pointer to a buffer describing the state of the random number generator
+just like @code{drand48}.
+
+If the return value of the function is non-negative the variable pointed
+to by @var{result} contains the result.  Otherwise an error occurred.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{nrand48_r} function works like @code{nrand48} in that it
+produces a random number in the range @code{0} to @code{2^31}.  But instead
+of using the global parameters for the congruential formula it uses the
+information from the buffer pointed to by @var{buffer}.  The state is
+described by the values in @var{xsubi}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{mrand48} but like the other reentrant
+functions it uses the random number generator described by the value in
+the buffer pointed to by @var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
+other reentrant functions of this function family it uses the
+congruential formula parameters from the buffer pointed to by
+@var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+Before any of the above functions are used the buffer of type
+@code{struct drand48_data} should be initialized.  The easiest way to do
+this is to fill the whole buffer with null bytes, e.g. by
+
+@smallexample
+memset (buffer, '\0', sizeof (struct drand48_data));
+@end smallexample
+
+@noindent
+Using any of the reentrant functions of this family now will
+automatically initialize the random number generator to the default
+values for the state and the parameters of the congruential formula.
+
+The other possibility is to use any of the functions which explicitly
+initialize the buffer.  Though it might be obvious how to initialize the
+buffer from looking at the parameter to the function, it is highly
+recommended to use these functions since the result might not always be
+what you expect.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+The description of the random number generator represented by the
+information in @var{buffer} is initialized similarly to what the function
+@code{srand48} does.  The state is initialized from the parameter
+@var{seedval} and the parameters for the congruential formula are
+initialized to their default values.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function is similar to @code{srand48_r} but like @code{seed48} it
+initializes all 48 bits of the state from the parameter @var{seed16v}.
+
+If the return value is non-negative the function call succeeded.  It
+does not return a pointer to the previous state of the random number
+generator like the @code{seed48} function does.  If the user wants to
+preserve the state for a later re-run s/he can copy the whole buffer
+pointed to by @var{buffer}.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
+@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
+This function initializes all aspects of the random number generator
+described in @var{buffer} with the data in @var{param}.  Here it is
+especially true that the function does more than just copying the
+contents of @var{param} and @var{buffer}.  More work is required and
+therefore it is important to use this function rather than initializing
+the random number generator directly.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@node FP Function Optimizations
+@section Is Fast Code or Small Code preferred?
+@cindex Optimization
+
+If an application uses many floating point functions it is often the case
+that the cost of the function calls themselves is not negligible.
+Modern processors can often execute the operations themselves
+very fast, but the function call disrupts the instruction pipeline.
+
+For this reason @theglibc{} provides optimizations for many of the
+frequently-used math functions.  When GNU CC is used and the user
+activates the optimizer, several new inline functions and macros are
+defined.  These new functions and macros have the same names as the
+library functions and so are used instead of the latter.  In the case of
+inline functions the compiler will decide whether it is reasonable to
+use them, and this decision is usually correct.
+
+This means that no calls to the library functions may be necessary, and
+can increase the speed of generated code significantly.  The drawback is
+that code size will increase, and the increase is not always negligible.
+
+There are two kind of inline functions: Those that give the same result
+as the library functions and others that might not set @code{errno} and
+might have a reduced precision and/or argument range in comparison with
+the library functions.  The latter inline functions are only available
+if the flag @code{-ffast-math} is given to GNU CC.
+
+In cases where the inline functions and macros are not wanted the symbol
+@code{__NO_MATH_INLINES} should be defined before any system header is
+included.  This will ensure that only library functions are used.  Of
+course, it can be determined for each file in the project whether
+giving this option is preferable or not.
+
+Not all hardware implements the entire @w{IEEE 754} standard, and even
+if it does there may be a substantial performance penalty for using some
+of its features.  For example, enabling traps on some processors forces
+the FPU to run un-pipelined, which can more than double calculation time.
+@c ***Add explanation of -lieee, -mieee.
diff --git a/ap/libc/glibc/glibc-2.23/manual/memory.texi b/ap/libc/glibc/glibc-2.23/manual/memory.texi
new file mode 100644
index 0000000..700555e
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/memory.texi
@@ -0,0 +1,3411 @@
+@node Memory, Character Handling, Error Reporting, Top
+@chapter Virtual Memory Allocation And Paging
+@c %MENU% Allocating virtual memory and controlling paging
+@cindex memory allocation
+@cindex storage allocation
+
+This chapter describes how processes manage and use memory in a system
+that uses @theglibc{}.
+
+@Theglibc{} has several functions for dynamically allocating
+virtual memory in various ways.  They vary in generality and in
+efficiency.  The library also provides functions for controlling paging
+and allocation of real memory.
+
+
+@menu
+* Memory Concepts::             An introduction to concepts and terminology.
+* Memory Allocation::           Allocating storage for your program data
+* Resizing the Data Segment::   @code{brk}, @code{sbrk}
+* Locking Pages::               Preventing page faults
+@end menu
+
+Memory mapped I/O is not discussed in this chapter.  @xref{Memory-mapped I/O}.
+
+
+
+@node Memory Concepts
+@section Process Memory Concepts
+
+One of the most basic resources a process has available to it is memory.
+There are a lot of different ways systems organize memory, but in a
+typical one, each process has one linear virtual address space, with
+addresses running from zero to some huge maximum.  It need not be
+contiguous; i.e., not all of these addresses actually can be used to
+store data.
+
+The virtual memory is divided into pages (4 kilobytes is typical).
+Backing each page of virtual memory is a page of real memory (called a
+@dfn{frame}) or some secondary storage, usually disk space.  The disk
+space might be swap space or just some ordinary disk file.  Actually, a
+page of all zeroes sometimes has nothing at all backing it -- there's
+just a flag saying it is all zeroes.
+@cindex page frame
+@cindex frame, real memory
+@cindex swap space
+@cindex page, virtual memory
+
+The same frame of real memory or backing store can back multiple virtual
+pages belonging to multiple processes.  This is normally the case, for
+example, with virtual memory occupied by @glibcadj{} code.  The same
+real memory frame containing the @code{printf} function backs a virtual
+memory page in each of the existing processes that has a @code{printf}
+call in its program.
+
+In order for a program to access any part of a virtual page, the page
+must at that moment be backed by (``connected to'') a real frame.  But
+because there is usually a lot more virtual memory than real memory, the
+pages must move back and forth between real memory and backing store
+regularly, coming into real memory when a process needs to access them
+and then retreating to backing store when not needed anymore.  This
+movement is called @dfn{paging}.
+
+When a program attempts to access a page which is not at that moment
+backed by real memory, this is known as a @dfn{page fault}.  When a page
+fault occurs, the kernel suspends the process, places the page into a
+real page frame (this is called ``paging in'' or ``faulting in''), then
+resumes the process so that from the process' point of view, the page
+was in real memory all along.  In fact, to the process, all pages always
+seem to be in real memory.  Except for one thing: the elapsed execution
+time of an instruction that would normally be a few nanoseconds is
+suddenly much, much, longer (because the kernel normally has to do I/O
+to complete the page-in).  For programs sensitive to that, the functions
+described in @ref{Locking Pages} can control it.
+@cindex page fault
+@cindex paging
+
+Within each virtual address space, a process has to keep track of what
+is at which addresses, and that process is called memory allocation.
+Allocation usually brings to mind meting out scarce resources, but in
+the case of virtual memory, that's not a major goal, because there is
+generally much more of it than anyone needs.  Memory allocation within a
+process is mainly just a matter of making sure that the same byte of
+memory isn't used to store two different things.
+
+Processes allocate memory in two major ways: by exec and
+programmatically.  Actually, forking is a third way, but it's not very
+interesting.  @xref{Creating a Process}.
+
+Exec is the operation of creating a virtual address space for a process,
+loading its basic program into it, and executing the program.  It is
+done by the ``exec'' family of functions (e.g. @code{execl}).  The
+operation takes a program file (an executable), it allocates space to
+load all the data in the executable, loads it, and transfers control to
+it.  That data is most notably the instructions of the program (the
+@dfn{text}), but also literals and constants in the program and even
+some variables: C variables with the static storage class (@pxref{Memory
+Allocation and C}).
+@cindex executable
+@cindex literals
+@cindex constants
+
+Once that program begins to execute, it uses programmatic allocation to
+gain additional memory.  In a C program with @theglibc{}, there
+are two kinds of programmatic allocation: automatic and dynamic.
+@xref{Memory Allocation and C}.
+
+Memory-mapped I/O is another form of dynamic virtual memory allocation.
+Mapping memory to a file means declaring that the contents of certain
+range of a process' addresses shall be identical to the contents of a
+specified regular file.  The system makes the virtual memory initially
+contain the contents of the file, and if you modify the memory, the
+system writes the same modification to the file.  Note that due to the
+magic of virtual memory and page faults, there is no reason for the
+system to do I/O to read the file, or allocate real memory for its
+contents, until the program accesses the virtual memory.
+@xref{Memory-mapped I/O}.
+@cindex memory mapped I/O
+@cindex memory mapped file
+@cindex files, accessing
+
+Just as it programmatically allocates memory, the program can
+programmatically deallocate (@dfn{free}) it.  You can't free the memory
+that was allocated by exec.  When the program exits or execs, you might
+say that all its memory gets freed, but since in both cases the address
+space ceases to exist, the point is really moot.  @xref{Program
+Termination}.
+@cindex execing a program
+@cindex freeing memory
+@cindex exiting a program
+
+A process' virtual address space is divided into segments.  A segment is
+a contiguous range of virtual addresses.  Three important segments are:
+
+@itemize @bullet
+
+@item
+
+The @dfn{text segment} contains a program's instructions and literals and
+static constants.  It is allocated by exec and stays the same size for
+the life of the virtual address space.
+
+@item
+The @dfn{data segment} is working storage for the program.  It can be
+preallocated and preloaded by exec and the process can extend or shrink
+it by calling functions as described in @xref{Resizing the Data
+Segment}.  Its lower end is fixed.
+
+@item
+The @dfn{stack segment} contains a program stack.  It grows as the stack
+grows, but doesn't shrink when the stack shrinks.
+
+@end itemize
+
+
+
+@node Memory Allocation
+@section Allocating Storage For Program Data
+
+This section covers how ordinary programs manage storage for their data,
+including the famous @code{malloc} function and some fancier facilities
+special @theglibc{} and GNU Compiler.
+
+@menu
+* Memory Allocation and C::     How to get different kinds of allocation in C.
+* Unconstrained Allocation::    The @code{malloc} facility allows fully general
+		 		 dynamic allocation.
+* Allocation Debugging::        Finding memory leaks and not freed memory.
+* Obstacks::                    Obstacks are less general than malloc
+				 but more efficient and convenient.
+* Variable Size Automatic::     Allocation of variable-sized blocks
+				 of automatic storage that are freed when the
+				 calling function returns.
+@end menu
+
+
+@node Memory Allocation and C
+@subsection Memory Allocation in C Programs
+
+The C language supports two kinds of memory allocation through the
+variables in C programs:
+
+@itemize @bullet
+@item
+@dfn{Static allocation} is what happens when you declare a static or
+global variable.  Each static or global variable defines one block of
+space, of a fixed size.  The space is allocated once, when your program
+is started (part of the exec operation), and is never freed.
+@cindex static memory allocation
+@cindex static storage class
+
+@item
+@dfn{Automatic allocation} happens when you declare an automatic
+variable, such as a function argument or a local variable.  The space
+for an automatic variable is allocated when the compound statement
+containing the declaration is entered, and is freed when that
+compound statement is exited.
+@cindex automatic memory allocation
+@cindex automatic storage class
+
+In GNU C, the size of the automatic storage can be an expression
+that varies.  In other C implementations, it must be a constant.
+@end itemize
+
+A third important kind of memory allocation, @dfn{dynamic allocation},
+is not supported by C variables but is available via @glibcadj{}
+functions.
+@cindex dynamic memory allocation
+
+@subsubsection Dynamic Memory Allocation
+@cindex dynamic memory allocation
+
+@dfn{Dynamic memory allocation} is a technique in which programs
+determine as they are running where to store some information.  You need
+dynamic allocation when the amount of memory you need, or how long you
+continue to need it, depends on factors that are not known before the
+program runs.
+
+For example, you may need a block to store a line read from an input
+file; since there is no limit to how long a line can be, you must
+allocate the memory dynamically and make it dynamically larger as you
+read more of the line.
+
+Or, you may need a block for each record or each definition in the input
+data; since you can't know in advance how many there will be, you must
+allocate a new block for each record or definition as you read it.
+
+When you use dynamic allocation, the allocation of a block of memory is
+an action that the program requests explicitly.  You call a function or
+macro when you want to allocate space, and specify the size with an
+argument.  If you want to free the space, you do so by calling another
+function or macro.  You can do these things whenever you want, as often
+as you want.
+
+Dynamic allocation is not supported by C variables; there is no storage
+class ``dynamic'', and there can never be a C variable whose value is
+stored in dynamically allocated space.  The only way to get dynamically
+allocated memory is via a system call (which is generally via a @glibcadj{}
+function call), and the only way to refer to dynamically
+allocated space is through a pointer.  Because it is less convenient,
+and because the actual process of dynamic allocation requires more
+computation time, programmers generally use dynamic allocation only when
+neither static nor automatic allocation will serve.
+
+For example, if you want to allocate dynamically some space to hold a
+@code{struct foobar}, you cannot declare a variable of type @code{struct
+foobar} whose contents are the dynamically allocated space.  But you can
+declare a variable of pointer type @code{struct foobar *} and assign it the
+address of the space.  Then you can use the operators @samp{*} and
+@samp{->} on this pointer variable to refer to the contents of the space:
+
+@smallexample
+@{
+  struct foobar *ptr
+     = (struct foobar *) malloc (sizeof (struct foobar));
+  ptr->name = x;
+  ptr->next = current_foobar;
+  current_foobar = ptr;
+@}
+@end smallexample
+
+@node Unconstrained Allocation
+@subsection Unconstrained Allocation
+@cindex unconstrained memory allocation
+@cindex @code{malloc} function
+@cindex heap, dynamic allocation from
+
+The most general dynamic allocation facility is @code{malloc}.  It
+allows you to allocate blocks of memory of any size at any time, make
+them bigger or smaller at any time, and free the blocks individually at
+any time (or never).
+
+@menu
+* 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.
+* 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.
+@end menu
+
+@node Basic Allocation
+@subsubsection Basic Memory Allocation
+@cindex allocation of memory with @code{malloc}
+
+To allocate a block of memory, call @code{malloc}.  The prototype for
+this function is in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment malloc.h stdlib.h
+@comment ISO
+@deftypefun {void *} malloc (size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Malloc hooks and __morecore pointers, as well as such parameters as
+@c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they
+@c could pose a thread safety issue; in order to not declare malloc
+@c MT-unsafe, it's modifying the hooks and parameters while multiple
+@c threads are active that is regarded as unsafe.  An arena's next field
+@c is initialized and never changed again, except for main_arena's,
+@c that's protected by list_lock; next_free is only modified while
+@c list_lock is held too.  All other data members of an arena, as well
+@c as the metadata of the memory areas assigned to it, are only modified
+@c while holding the arena's mutex (fastbin pointers use catomic ops
+@c because they may be modified by free without taking the arena's
+@c lock).  Some reassurance was needed for fastbins, for it wasn't clear
+@c how they were initialized.  It turns out they are always
+@c zero-initialized: main_arena's, for being static data, and other
+@c arena's, for being just-mmapped memory.
+
+@c Leaking file descriptors and memory in case of cancellation is
+@c unavoidable without disabling cancellation, but the lock situation is
+@c a bit more complicated: we don't have fallback arenas for malloc to
+@c be safe to call from within signal handlers.  Error-checking mutexes
+@c or trylock could enable us to try and use alternate arenas, even with
+@c -DPER_THREAD (enabled by default), but supporting interruption
+@c (cancellation or signal handling) while holding the arena list mutex
+@c would require more work; maybe blocking signals and disabling async
+@c cancellation while manipulating the arena lists?
+
+@c __libc_malloc @asulock @aculock @acsfd @acsmem
+@c  force_reg ok
+@c  *malloc_hook unguarded
+@c  arena_lock @asulock @aculock @acsfd @acsmem
+@c   mutex_lock @asulock @aculock
+@c   arena_get2 @asulock @aculock @acsfd @acsmem
+@c    get_free_list @asulock @aculock
+@c     mutex_lock (list_lock) dup @asulock @aculock
+@c     mutex_unlock (list_lock) dup @aculock
+@c     mutex_lock (arena lock) dup @asulock @aculock [returns locked]
+@c    __get_nprocs ext ok @acsfd
+@c    NARENAS_FROM_NCORES ok
+@c    catomic_compare_and_exchange_bool_acq ok
+@c    _int_new_arena ok @asulock @aculock @acsmem
+@c     new_heap ok @acsmem
+@c      mmap ok @acsmem
+@c      munmap ok @acsmem
+@c      mprotect ok
+@c     chunk2mem ok
+@c     set_head ok
+@c     tsd_setspecific dup ok
+@c     mutex_init ok
+@c     mutex_lock (just-created mutex) ok, returns locked
+@c     mutex_lock (list_lock) dup @asulock @aculock
+@c     atomic_write_barrier ok
+@c     mutex_unlock (list_lock) @aculock
+@c    catomic_decrement ok
+@c    reused_arena @asulock @aculock
+@c      reads&writes next_to_use and iterates over arena next without guards
+@c      those are harmless as long as we don't drop arenas from the
+@c      NEXT list, and we never do; when a thread terminates,
+@c      arena_thread_freeres prepends the arena to the free_list
+@c      NEXT_FREE list, but NEXT is never modified, so it's safe!
+@c     mutex_trylock (arena lock) @asulock @aculock
+@c     mutex_lock (arena lock) dup @asulock @aculock
+@c     tsd_setspecific dup ok
+@c  _int_malloc @acsfd @acsmem
+@c   checked_request2size ok
+@c    REQUEST_OUT_OF_RANGE ok
+@c    request2size ok
+@c   get_max_fast ok
+@c   fastbin_index ok
+@c   fastbin ok
+@c   catomic_compare_and_exhange_val_acq ok
+@c   malloc_printerr dup @mtsenv
+@c     if we get to it, we're toast already, undefined behavior must have
+@c     been invoked before
+@c    libc_message @mtsenv [no leaks with cancellation disabled]
+@c     FATAL_PREPARE ok
+@c      pthread_setcancelstate disable ok
+@c     libc_secure_getenv @mtsenv
+@c      getenv @mtsenv
+@c     open_not_cancel_2 dup @acsfd
+@c     strchrnul ok
+@c     WRITEV_FOR_FATAL ok
+@c      writev ok
+@c     mmap ok @acsmem
+@c     munmap ok @acsmem
+@c     BEFORE_ABORT @acsfd
+@c      backtrace ok
+@c      write_not_cancel dup ok
+@c      backtrace_symbols_fd @aculock
+@c      open_not_cancel_2 dup @acsfd
+@c      read_not_cancel dup ok
+@c      close_not_cancel_no_status dup @acsfd
+@c     abort ok
+@c    itoa_word ok
+@c    abort ok
+@c   check_remalloced_chunk ok/disabled
+@c   chunk2mem dup ok
+@c   alloc_perturb ok
+@c   in_smallbin_range ok
+@c   smallbin_index ok
+@c   bin_at ok
+@c   last ok
+@c   malloc_consolidate ok
+@c    get_max_fast dup ok
+@c    clear_fastchunks ok
+@c    unsorted_chunks dup ok
+@c    fastbin dup ok
+@c    atomic_exchange_acq ok
+@c    check_inuse_chunk dup ok/disabled
+@c    chunk_at_offset dup ok
+@c    chunksize dup ok
+@c    inuse_bit_at_offset dup ok
+@c    unlink dup ok
+@c    clear_inuse_bit_at_offset dup ok
+@c    in_smallbin_range dup ok
+@c    set_head dup ok
+@c    malloc_init_state ok
+@c     bin_at dup ok
+@c     set_noncontiguous dup ok
+@c     set_max_fast dup ok
+@c     initial_top ok
+@c      unsorted_chunks dup ok
+@c    check_malloc_state ok/disabled
+@c   set_inuse_bit_at_offset ok
+@c   check_malloced_chunk ok/disabled
+@c   largebin_index ok
+@c   have_fastchunks ok
+@c   unsorted_chunks ok
+@c    bin_at ok
+@c   chunksize ok
+@c   chunk_at_offset ok
+@c   set_head ok
+@c   set_foot ok
+@c   mark_bin ok
+@c    idx2bit ok
+@c   first ok
+@c   unlink ok
+@c    malloc_printerr dup ok
+@c    in_smallbin_range dup ok
+@c   idx2block ok
+@c   idx2bit dup ok
+@c   next_bin ok
+@c   sysmalloc @acsfd @acsmem
+@c    MMAP @acsmem
+@c    set_head dup ok
+@c    check_chunk ok/disabled
+@c    chunk2mem dup ok
+@c    chunksize dup ok
+@c    chunk_at_offset dup ok
+@c    heap_for_ptr ok
+@c    grow_heap ok
+@c     mprotect ok
+@c    set_head dup ok
+@c    new_heap @acsmem
+@c     MMAP dup @acsmem
+@c     munmap @acsmem
+@c    top ok
+@c    set_foot dup ok
+@c    contiguous ok
+@c    MORECORE ok
+@c     *__morecore ok unguarded
+@c      __default_morecore
+@c       sbrk ok
+@c    force_reg dup ok
+@c    *__after_morecore_hook unguarded
+@c    set_noncontiguous ok
+@c    malloc_printerr dup ok
+@c    _int_free (have_lock) @acsfd @acsmem [@asulock @aculock]
+@c     chunksize dup ok
+@c     mutex_unlock dup @aculock/!have_lock
+@c     malloc_printerr dup ok
+@c     check_inuse_chunk ok/disabled
+@c     chunk_at_offset dup ok
+@c     mutex_lock dup @asulock @aculock/@have_lock
+@c     chunk2mem dup ok
+@c     free_perturb ok
+@c     set_fastchunks ok
+@c      catomic_and ok
+@c     fastbin_index dup ok
+@c     fastbin dup ok
+@c     catomic_compare_and_exchange_val_rel ok
+@c     chunk_is_mmapped ok
+@c     contiguous dup ok
+@c     prev_inuse ok
+@c     unlink dup ok
+@c     inuse_bit_at_offset dup ok
+@c     clear_inuse_bit_at_offset ok
+@c     unsorted_chunks dup ok
+@c     in_smallbin_range dup ok
+@c     set_head dup ok
+@c     set_foot dup ok
+@c     check_free_chunk ok/disabled
+@c     check_chunk dup ok/disabled
+@c     have_fastchunks dup ok
+@c     malloc_consolidate dup ok
+@c     systrim ok
+@c      MORECORE dup ok
+@c      *__after_morecore_hook dup unguarded
+@c      set_head dup ok
+@c      check_malloc_state ok/disabled
+@c     top dup ok
+@c     heap_for_ptr dup ok
+@c     heap_trim @acsfd @acsmem
+@c      top dup ok
+@c      chunk_at_offset dup ok
+@c      prev_chunk ok
+@c      chunksize dup ok
+@c      prev_inuse dup ok
+@c      delete_heap @acsmem
+@c       munmap dup @acsmem
+@c      unlink dup ok
+@c      set_head dup ok
+@c      shrink_heap @acsfd
+@c       check_may_shrink_heap @acsfd
+@c        open_not_cancel_2 @acsfd
+@c        read_not_cancel ok
+@c        close_not_cancel_no_status @acsfd
+@c       MMAP dup ok
+@c       madvise ok
+@c     munmap_chunk @acsmem
+@c      chunksize dup ok
+@c      chunk_is_mmapped dup ok
+@c      chunk2mem dup ok
+@c      malloc_printerr dup ok
+@c      munmap dup @acsmem
+@c    check_malloc_state ok/disabled
+@c  arena_get_retry @asulock @aculock @acsfd @acsmem
+@c   mutex_unlock dup @aculock
+@c   mutex_lock dup @asulock @aculock
+@c   arena_get2 dup @asulock @aculock @acsfd @acsmem
+@c  mutex_unlock @aculock
+@c  mem2chunk ok
+@c  chunk_is_mmapped ok
+@c  arena_for_chunk ok
+@c   chunk_non_main_arena ok
+@c   heap_for_ptr ok
+This function returns a pointer to a newly allocated block @var{size}
+bytes long, or a null pointer if the block could not be allocated.
+@end deftypefun
+
+The contents of the block are undefined; you must initialize it yourself
+(or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
+Normally you would cast the value as a pointer to the kind of object
+that you want to store in the block.  Here we show an example of doing
+so, and of initializing the space with zeros using the library function
+@code{memset} (@pxref{Copying Strings and Arrays}):
+
+@smallexample
+struct foo *ptr;
+@dots{}
+ptr = (struct foo *) malloc (sizeof (struct foo));
+if (ptr == 0) abort ();
+memset (ptr, 0, sizeof (struct foo));
+@end smallexample
+
+You can store the result of @code{malloc} into any pointer variable
+without a cast, because @w{ISO C} automatically converts the type
+@code{void *} to another type of pointer when necessary.  But the cast
+is necessary in contexts other than assignment operators or if you might
+want your code to run in traditional C.
+
+Remember that when allocating space for a string, the argument to
+@code{malloc} must be one plus the length of the string.  This is
+because a string is terminated with a null character that doesn't count
+in the ``length'' of the string but does need space.  For example:
+
+@smallexample
+char *ptr;
+@dots{}
+ptr = (char *) malloc (length + 1);
+@end smallexample
+
+@noindent
+@xref{Representation of Strings}, for more information about this.
+
+@node Malloc Examples
+@subsubsection Examples of @code{malloc}
+
+If no more space is available, @code{malloc} returns a null pointer.
+You should check the value of @emph{every} call to @code{malloc}.  It is
+useful to write a subroutine that calls @code{malloc} and reports an
+error if the value is a null pointer, returning only if the value is
+nonzero.  This function is conventionally called @code{xmalloc}.  Here
+it is:
+
+@smallexample
+void *
+xmalloc (size_t size)
+@{
+  void *value = malloc (size);
+  if (value == 0)
+    fatal ("virtual memory exhausted");
+  return value;
+@}
+@end smallexample
+
+Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
+The function @code{savestring} will copy a sequence of characters into
+a newly allocated null-terminated string:
+
+@smallexample
+@group
+char *
+savestring (const char *ptr, size_t len)
+@{
+  char *value = (char *) xmalloc (len + 1);
+  value[len] = '\0';
+  return (char *) memcpy (value, ptr, len);
+@}
+@end group
+@end smallexample
+
+The block that @code{malloc} gives you is guaranteed to be aligned so
+that it can hold any type of data.  On @gnusystems{}, the address is
+always a multiple of eight on 32-bit systems, and a multiple of 16 on
+64-bit systems.  Only rarely is any higher boundary (such as a page
+boundary) necessary; for those cases, use @code{aligned_alloc} or
+@code{posix_memalign} (@pxref{Aligned Memory Blocks}).
+
+Note that the memory located after the end of the block is likely to be
+in use for something else; perhaps a block already allocated by another
+call to @code{malloc}.  If you attempt to treat the block as longer than
+you asked for it to be, you are liable to destroy the data that
+@code{malloc} uses to keep track of its blocks, or you may destroy the
+contents of another block.  If you have already allocated a block and
+discover you want it to be bigger, use @code{realloc} (@pxref{Changing
+Block Size}).
+
+@node Freeing after Malloc
+@subsubsection Freeing Memory Allocated with @code{malloc}
+@cindex freeing memory allocated with @code{malloc}
+@cindex heap, freeing memory from
+
+When you no longer need a block that you got with @code{malloc}, use the
+function @code{free} to make the block available to be allocated again.
+The prototype for this function is in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment malloc.h stdlib.h
+@comment ISO
+@deftypefun void free (void *@var{ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c __libc_free @asulock @aculock @acsfd @acsmem
+@c   releasing memory into fastbins modifies the arena without taking
+@c   its mutex, but catomic operations ensure safety.  If two (or more)
+@c   threads are running malloc and have their own arenas locked when
+@c   each gets a signal whose handler free()s large (non-fastbin-able)
+@c   blocks from each other's arena, we deadlock; this is a more general
+@c   case of @asulock.
+@c  *__free_hook unguarded
+@c  mem2chunk ok
+@c  chunk_is_mmapped ok, chunk bits not modified after allocation
+@c  chunksize ok
+@c  munmap_chunk dup @acsmem
+@c  arena_for_chunk dup ok
+@c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
+The @code{free} function deallocates the block of memory pointed at
+by @var{ptr}.
+@end deftypefun
+
+@comment stdlib.h
+@comment Sun
+@deftypefun void cfree (void *@var{ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c alias to free
+This function does the same thing as @code{free}.  It's provided for
+backward compatibility with SunOS; you should use @code{free} instead.
+@end deftypefun
+
+Freeing a block alters the contents of the block.  @strong{Do not expect to
+find any data (such as a pointer to the next block in a chain of blocks) in
+the block after freeing it.}  Copy whatever you need out of the block before
+freeing it!  Here is an example of the proper way to free all the blocks in
+a chain, and the strings that they point to:
+
+@smallexample
+struct chain
+  @{
+    struct chain *next;
+    char *name;
+  @}
+
+void
+free_chain (struct chain *chain)
+@{
+  while (chain != 0)
+    @{
+      struct chain *next = chain->next;
+      free (chain->name);
+      free (chain);
+      chain = next;
+    @}
+@}
+@end smallexample
+
+Occasionally, @code{free} can actually return memory to the operating
+system and make the process smaller.  Usually, all it can do is allow a
+later call to @code{malloc} to reuse the space.  In the meantime, the
+space remains in your program as part of a free-list used internally by
+@code{malloc}.
+
+There is no point in freeing blocks at the end of a program, because all
+of the program's space is given back to the system when the process
+terminates.
+
+@node Changing Block Size
+@subsubsection Changing the Size of a Block
+@cindex changing the size of a block (@code{malloc})
+
+Often you do not know for certain how big a block you will ultimately need
+at the time you must begin to use the block.  For example, the block might
+be a buffer that you use to hold a line being read from a file; no matter
+how long you make the buffer initially, you may encounter a line that is
+longer.
+
+You can make the block longer by calling @code{realloc}.  This function
+is declared in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment malloc.h stdlib.h
+@comment ISO
+@deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c It may call the implementations of malloc and free, so all of their
+@c issues arise, plus the realloc hook, also accessed without guards.
+
+@c __libc_realloc @asulock @aculock @acsfd @acsmem
+@c  *__realloc_hook unguarded
+@c  __libc_free dup @asulock @aculock @acsfd @acsmem
+@c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
+@c  mem2chunk dup ok
+@c  chunksize dup ok
+@c  malloc_printerr dup ok
+@c  checked_request2size dup ok
+@c  chunk_is_mmapped dup ok
+@c  mremap_chunk
+@c   chunksize dup ok
+@c   __mremap ok
+@c   set_head dup ok
+@c  MALLOC_COPY ok
+@c   memcpy ok
+@c  munmap_chunk dup @acsmem
+@c  arena_for_chunk dup ok
+@c  mutex_lock (arena mutex) dup @asulock @aculock
+@c  _int_realloc @acsfd @acsmem
+@c   malloc_printerr dup ok
+@c   check_inuse_chunk dup ok/disabled
+@c   chunk_at_offset dup ok
+@c   chunksize dup ok
+@c   set_head_size dup ok
+@c   chunk_at_offset dup ok
+@c   set_head dup ok
+@c   chunk2mem dup ok
+@c   inuse dup ok
+@c   unlink dup ok
+@c   _int_malloc dup @acsfd @acsmem
+@c   mem2chunk dup ok
+@c   MALLOC_COPY dup ok
+@c   _int_free (have_lock) dup @acsfd @acsmem
+@c   set_inuse_bit_at_offset dup ok
+@c   set_head dup ok
+@c  mutex_unlock (arena mutex) dup @aculock
+@c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
+
+The @code{realloc} function changes the size of the block whose address is
+@var{ptr} to be @var{newsize}.
+
+Since the space after the end of the block may be in use, @code{realloc}
+may find it necessary to copy the block to a new address where more free
+space is available.  The value of @code{realloc} is the new address of the
+block.  If the block needs to be moved, @code{realloc} copies the old
+contents.
+
+If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
+like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
+that older implementations (before @w{ISO C}) may not support this
+behavior, and will probably crash when @code{realloc} is passed a null
+pointer.
+@end deftypefun
+
+Like @code{malloc}, @code{realloc} may return a null pointer if no
+memory space is available to make the block bigger.  When this happens,
+the original block is untouched; it has not been modified or relocated.
+
+In most cases it makes no difference what happens to the original block
+when @code{realloc} fails, because the application program cannot continue
+when it is out of memory, and the only thing to do is to give a fatal error
+message.  Often it is convenient to write and use a subroutine,
+conventionally called @code{xrealloc}, that takes care of the error message
+as @code{xmalloc} does for @code{malloc}:
+
+@smallexample
+void *
+xrealloc (void *ptr, size_t size)
+@{
+  void *value = realloc (ptr, size);
+  if (value == 0)
+    fatal ("Virtual memory exhausted");
+  return value;
+@}
+@end smallexample
+
+You can also use @code{realloc} to make a block smaller.  The reason you
+would do this is to avoid tying up a lot of memory space when only a little
+is needed.
+@comment The following is no longer true with the new malloc.
+@comment But it seems wise to keep the warning for other implementations.
+In several allocation implementations, making a block smaller sometimes
+necessitates copying it, so it can fail if no other space is available.
+
+If the new size you specify is the same as the old size, @code{realloc}
+is guaranteed to change nothing and return the same address that you gave.
+
+@node Allocating Cleared Space
+@subsubsection Allocating Cleared Space
+
+The function @code{calloc} allocates memory and clears it to zero.  It
+is declared in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment malloc.h stdlib.h
+@comment ISO
+@deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Same caveats as malloc.
+
+@c __libc_calloc @asulock @aculock @acsfd @acsmem
+@c  *__malloc_hook dup unguarded
+@c  memset dup ok
+@c  arena_get @asulock @aculock @acsfd @acsmem
+@c   arena_lock dup @asulock @aculock @acsfd @acsmem
+@c  top dup ok
+@c  chunksize dup ok
+@c  heap_for_ptr dup ok
+@c  _int_malloc dup @acsfd @acsmem
+@c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
+@c  mutex_unlock dup @aculock
+@c  mem2chunk dup ok
+@c  chunk_is_mmapped dup ok
+@c  MALLOC_ZERO ok
+@c   memset dup ok
+This function allocates a block long enough to contain a vector of
+@var{count} elements, each of size @var{eltsize}.  Its contents are
+cleared to zero before @code{calloc} returns.
+@end deftypefun
+
+You could define @code{calloc} as follows:
+
+@smallexample
+void *
+calloc (size_t count, size_t eltsize)
+@{
+  size_t size = count * eltsize;
+  void *value = malloc (size);
+  if (value != 0)
+    memset (value, 0, size);
+  return value;
+@}
+@end smallexample
+
+But in general, it is not guaranteed that @code{calloc} calls
+@code{malloc} internally.  Therefore, if an application provides its own
+@code{malloc}/@code{realloc}/@code{free} outside the C library, it
+should always define @code{calloc}, too.
+
+@node Efficiency and Malloc
+@subsubsection Efficiency Considerations for @code{malloc}
+@cindex efficiency and @code{malloc}
+
+
+
+
+@ignore
+
+@c No longer true, see below instead.
+To make the best use of @code{malloc}, it helps to know that the GNU
+version of @code{malloc} always dispenses small amounts of memory in
+blocks whose sizes are powers of two.  It keeps separate pools for each
+power of two.  This holds for sizes up to a page size.  Therefore, if
+you are free to choose the size of a small block in order to make
+@code{malloc} more efficient, make it a power of two.
+@c !!! xref getpagesize
+
+Once a page is split up for a particular block size, it can't be reused
+for another size unless all the blocks in it are freed.  In many
+programs, this is unlikely to happen.  Thus, you can sometimes make a
+program use memory more efficiently by using blocks of the same size for
+many different purposes.
+
+When you ask for memory blocks of a page or larger, @code{malloc} uses a
+different strategy; it rounds the size up to a multiple of a page, and
+it can coalesce and split blocks as needed.
+
+The reason for the two strategies is that it is important to allocate
+and free small blocks as fast as possible, but speed is less important
+for a large block since the program normally spends a fair amount of
+time using it.  Also, large blocks are normally fewer in number.
+Therefore, for large blocks, it makes sense to use a method which takes
+more time to minimize the wasted space.
+
+@end ignore
+
+As opposed to other versions, the @code{malloc} in @theglibc{}
+does not round up block sizes to powers of two, neither for large nor
+for small sizes.  Neighboring chunks can be coalesced on a @code{free}
+no matter what their size is.  This makes the implementation suitable
+for all kinds of allocation patterns without generally incurring high
+memory waste through fragmentation.
+
+Very large blocks (much larger than a page) are allocated with
+@code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
+This has the great advantage that these chunks are returned to the
+system immediately when they are freed.  Therefore, it cannot happen
+that a large chunk becomes ``locked'' in between smaller ones and even
+after calling @code{free} wastes memory.  The size threshold for
+@code{mmap} to be used can be adjusted with @code{mallopt}.  The use of
+@code{mmap} can also be disabled completely.
+
+@node Aligned Memory Blocks
+@subsubsection Allocating Aligned Memory Blocks
+
+@cindex page boundary
+@cindex alignment (with @code{malloc})
+@pindex stdlib.h
+The address of a block returned by @code{malloc} or @code{realloc} in
+@gnusystems{} is always a multiple of eight (or sixteen on 64-bit
+systems).  If you need a block whose address is a multiple of a higher
+power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
+@code{aligned_alloc} and @code{posix_memalign} are declared in
+@file{stdlib.h}.
+
+@comment stdlib.h
+@deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Alias to memalign.
+The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
+address is a multiple of @var{alignment}.  The @var{alignment} must be a
+power of two and @var{size} must be a multiple of @var{alignment}.
+
+The @code{aligned_alloc} function returns a null pointer on error and sets
+@code{errno} to one of the following values:
+
+@table @code
+@item ENOMEM
+There was insufficient memory available to satisfy the request.
+
+@item EINVAL
+@var{alignment} is not a power of two.
+
+This function was introduced in @w{ISO C11} and hence may have better
+portability to modern non-POSIX systems than @code{posix_memalign}.
+@end table
+
+@end deftypefun
+
+@comment malloc.h
+@comment BSD
+@deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Same issues as malloc.  The padding bytes are safely freed in
+@c _int_memalign, with the arena still locked.
+
+@c __libc_memalign @asulock @aculock @acsfd @acsmem
+@c  *__memalign_hook dup unguarded
+@c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
+@c  arena_get dup @asulock @aculock @acsfd @acsmem
+@c  _int_memalign @acsfd @acsmem
+@c   _int_malloc dup @acsfd @acsmem
+@c   checked_request2size dup ok
+@c   mem2chunk dup ok
+@c   chunksize dup ok
+@c   chunk_is_mmapped dup ok
+@c   set_head dup ok
+@c   chunk2mem dup ok
+@c   set_inuse_bit_at_offset dup ok
+@c   set_head_size dup ok
+@c   _int_free (have_lock) dup @acsfd @acsmem
+@c   chunk_at_offset dup ok
+@c   check_inuse_chunk dup ok
+@c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
+@c  mutex_unlock dup @aculock
+The @code{memalign} function allocates a block of @var{size} bytes whose
+address is a multiple of @var{boundary}.  The @var{boundary} must be a
+power of two!  The function @code{memalign} works by allocating a
+somewhat larger block, and then returning an address within the block
+that is on the specified boundary.
+
+The @code{memalign} function returns a null pointer on error and sets
+@code{errno} to one of the following values:
+
+@table @code
+@item ENOMEM
+There was insufficient memory available to satisfy the request.
+
+@item EINVAL
+@var{alignment} is not a power of two.
+
+@end table
+
+The @code{memalign} function is obsolete and @code{aligned_alloc} or
+@code{posix_memalign} should be used instead.
+@end deftypefun
+
+@comment stdlib.h
+@comment POSIX
+@deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c Calls memalign unless the requirements are not met (powerof2 macro is
+@c safe given an automatic variable as an argument) or there's a
+@c memalign hook (accessed unguarded, but safely).
+The @code{posix_memalign} function is similar to the @code{memalign}
+function in that it returns a buffer of @var{size} bytes aligned to a
+multiple of @var{alignment}.  But it adds one requirement to the
+parameter @var{alignment}: the value must be a power of two multiple of
+@code{sizeof (void *)}.
+
+If the function succeeds in allocation memory a pointer to the allocated
+memory is returned in @code{*@var{memptr}} and the return value is zero.
+Otherwise the function returns an error value indicating the problem.
+The possible error values returned are:
+
+@table @code
+@item ENOMEM
+There was insufficient memory available to satisfy the request.
+
+@item EINVAL
+@var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
+
+@end table
+
+This function was introduced in POSIX 1003.1d.  Although this function is
+superseded by @code{aligned_alloc}, it is more portable to older POSIX
+systems that do not support @w{ISO C11}.
+@end deftypefun
+
+@comment malloc.h stdlib.h
+@comment BSD
+@deftypefun {void *} valloc (size_t @var{size})
+@safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{} @acsfd{} @acsmem{}}}
+@c __libc_valloc @mtuinit @asuinit @asulock @aculock @acsfd @acsmem
+@c  ptmalloc_init (once) @mtsenv @asulock @aculock @acsfd @acsmem
+@c   _dl_addr @asucorrupt? @aculock
+@c    __rtld_lock_lock_recursive (dl_load_lock) @asucorrupt? @aculock
+@c    _dl_find_dso_for_object ok, iterates over dl_ns and its _ns_loaded objs
+@c      the ok above assumes no partial updates on dl_ns and _ns_loaded
+@c      that could confuse a _dl_addr call in a signal handler
+@c     _dl_addr_inside_object ok
+@c    determine_info ok
+@c    __rtld_lock_unlock_recursive (dl_load_lock) @aculock
+@c   thread_atfork @asulock @aculock @acsfd @acsmem
+@c    __register_atfork @asulock @aculock @acsfd @acsmem
+@c     lll_lock (__fork_lock) @asulock @aculock
+@c     fork_handler_alloc @asulock @aculock @acsfd @acsmem
+@c      calloc dup @asulock @aculock @acsfd @acsmem
+@c     __linkin_atfork ok
+@c      catomic_compare_and_exchange_bool_acq ok
+@c     lll_unlock (__fork_lock) @aculock
+@c   *_environ @mtsenv
+@c   next_env_entry ok
+@c   strcspn dup ok
+@c   __libc_mallopt dup @mtasuconst:mallopt [setting mp_]
+@c   __malloc_check_init @mtasuconst:malloc_hooks [setting hooks]
+@c   *__malloc_initialize_hook unguarded, ok
+@c  *__memalign_hook dup ok, unguarded
+@c  arena_get dup @asulock @aculock @acsfd @acsmem
+@c  _int_valloc @acsfd @acsmem
+@c   malloc_consolidate dup ok
+@c   _int_memalign dup @acsfd @acsmem
+@c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
+@c  _int_memalign dup @acsfd @acsmem
+@c  mutex_unlock dup @aculock
+Using @code{valloc} is like using @code{memalign} and passing the page size
+as the value of the second argument.  It is implemented like this:
+
+@smallexample
+void *
+valloc (size_t size)
+@{
+  return memalign (getpagesize (), size);
+@}
+@end smallexample
+
+@ref{Query Memory Parameters} for more information about the memory
+subsystem.
+
+The @code{valloc} function is obsolete and @code{aligned_alloc} or
+@code{posix_memalign} should be used instead.
+@end deftypefun
+
+@node Malloc Tunable Parameters
+@subsubsection Malloc Tunable Parameters
+
+You can adjust some parameters for dynamic memory allocation with the
+@code{mallopt} function.  This function is the general SVID/XPG
+interface, defined in @file{malloc.h}.
+@pindex malloc.h
+
+@deftypefun int mallopt (int @var{param}, int @var{value})
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
+@c __libc_mallopt @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
+@c  ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
+@c  mutex_lock (main_arena->mutex) @asulock @aculock
+@c  malloc_consolidate dup ok
+@c  set_max_fast ok
+@c  mutex_unlock dup @aculock
+
+When calling @code{mallopt}, the @var{param} argument specifies the
+parameter to be set, and @var{value} the new value to be set.  Possible
+choices for @var{param}, as defined in @file{malloc.h}, are:
+
+@table @code
+@comment TODO: @item M_ARENA_MAX
+@comment       - Document ARENA_MAX env var.
+@comment TODO: @item M_ARENA_TEST
+@comment       - Document ARENA_TEST env var.
+@comment TODO: @item M_CHECK_ACTION
+@item M_MMAP_MAX
+The maximum number of chunks to allocate with @code{mmap}.  Setting this
+to zero disables all use of @code{mmap}.
+@item M_MMAP_THRESHOLD
+All chunks larger than this value are allocated outside the normal
+heap, using the @code{mmap} system call.  This way it is guaranteed
+that the memory for these chunks can be returned to the system on
+@code{free}.  Note that requests smaller than this threshold might still
+be allocated via @code{mmap}.
+@comment TODO: @item M_MXFAST
+@item M_PERTURB
+If non-zero, memory blocks are filled with values depending on some
+low order bits of this parameter when they are allocated (except when
+allocated by @code{calloc}) and freed.  This can be used to debug the
+use of uninitialized or freed heap memory.  Note that this option does not
+guarantee that the freed block will have any specific values.  It only
+guarantees that the content the block had before it was freed will be
+overwritten.
+@item M_TOP_PAD
+This parameter determines the amount of extra memory to obtain from the
+system when a call to @code{sbrk} is required.  It also specifies the
+number of bytes to retain when shrinking the heap by calling @code{sbrk}
+with a negative argument.  This provides the necessary hysteresis in
+heap size such that excessive amounts of system calls can be avoided.
+@item M_TRIM_THRESHOLD
+This is the minimum size (in bytes) of the top-most, releasable chunk
+that will cause @code{sbrk} to be called with a negative argument in
+order to return memory to the system.
+@end table
+
+@end deftypefun
+
+@node Heap Consistency Checking
+@subsubsection Heap Consistency Checking
+
+@cindex heap consistency checking
+@cindex consistency checking, of heap
+
+You can ask @code{malloc} to check the consistency of dynamic memory by
+using the @code{mcheck} function.  This function is a GNU extension,
+declared in @file{mcheck.h}.
+@pindex mcheck.h
+
+@comment mcheck.h
+@comment GNU
+@deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
+@safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c The hooks must be set up before malloc is first used, which sort of
+@c implies @mtuinit/@asuinit but since the function is a no-op if malloc
+@c was already used, that doesn't pose any safety issues.  The actual
+@c problem is with the hooks, designed for single-threaded
+@c fully-synchronous operation: they manage an unguarded linked list of
+@c allocated blocks, and get temporarily overwritten before calling the
+@c allocation functions recursively while holding the old hooks.  There
+@c are no guards for thread safety, and inconsistent hooks may be found
+@c within signal handlers or left behind in case of cancellation.
+
+Calling @code{mcheck} tells @code{malloc} to perform occasional
+consistency checks.  These will catch things such as writing
+past the end of a block that was allocated with @code{malloc}.
+
+The @var{abortfn} argument is the function to call when an inconsistency
+is found.  If you supply a null pointer, then @code{mcheck} uses a
+default function which prints a message and calls @code{abort}
+(@pxref{Aborting a Program}).  The function you supply is called with
+one argument, which says what sort of inconsistency was detected; its
+type is described below.
+
+It is too late to begin allocation checking once you have allocated
+anything with @code{malloc}.  So @code{mcheck} does nothing in that
+case.  The function returns @code{-1} if you call it too late, and
+@code{0} otherwise (when it is successful).
+
+The easiest way to arrange to call @code{mcheck} early enough is to use
+the option @samp{-lmcheck} when you link your program; then you don't
+need to modify your program source at all.  Alternatively you might use
+a debugger to insert a call to @code{mcheck} whenever the program is
+started, for example these gdb commands will automatically call @code{mcheck}
+whenever the program starts:
+
+@smallexample
+(gdb) break main
+Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
+(gdb) command 1
+Type commands for when breakpoint 1 is hit, one per line.
+End with a line saying just "end".
+>call mcheck(0)
+>continue
+>end
+(gdb) @dots{}
+@end smallexample
+
+This will however only work if no initialization function of any object
+involved calls any of the @code{malloc} functions since @code{mcheck}
+must be called before the first such function.
+
+@end deftypefun
+
+@deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c The linked list of headers may be modified concurrently by other
+@c threads, and it may find a partial update if called from a signal
+@c handler.  It's mostly read only, so cancelling it might be safe, but
+@c it will modify global state that, if cancellation hits at just the
+@c right spot, may be left behind inconsistent.  This path is only taken
+@c if checkhdr finds an inconsistency.  If the inconsistency could only
+@c occur because of earlier undefined behavior, that wouldn't be an
+@c additional safety issue problem, but because of the other concurrency
+@c issues in the mcheck hooks, the apparent inconsistency could be the
+@c result of mcheck's own internal data race.  So, AC-Unsafe it is.
+
+The @code{mprobe} function lets you explicitly check for inconsistencies
+in a particular allocated block.  You must have already called
+@code{mcheck} at the beginning of the program, to do its occasional
+checks; calling @code{mprobe} requests an additional consistency check
+to be done at the time of the call.
+
+The argument @var{pointer} must be a pointer returned by @code{malloc}
+or @code{realloc}.  @code{mprobe} returns a value that says what
+inconsistency, if any, was found.  The values are described below.
+@end deftypefun
+
+@deftp {Data Type} {enum mcheck_status}
+This enumerated type describes what kind of inconsistency was detected
+in an allocated block, if any.  Here are the possible values:
+
+@table @code
+@item MCHECK_DISABLED
+@code{mcheck} was not called before the first allocation.
+No consistency checking can be done.
+@item MCHECK_OK
+No inconsistency detected.
+@item MCHECK_HEAD
+The data immediately before the block was modified.
+This commonly happens when an array index or pointer
+is decremented too far.
+@item MCHECK_TAIL
+The data immediately after the block was modified.
+This commonly happens when an array index or pointer
+is incremented too far.
+@item MCHECK_FREE
+The block was already freed.
+@end table
+@end deftp
+
+Another possibility to check for and guard against bugs in the use of
+@code{malloc}, @code{realloc} and @code{free} is to set the environment
+variable @code{MALLOC_CHECK_}.  When @code{MALLOC_CHECK_} is set, a
+special (less efficient) implementation is used which is designed to be
+tolerant against simple errors, such as double calls of @code{free} with
+the same argument, or overruns of a single byte (off-by-one bugs).  Not
+all such errors can be protected against, however, and memory leaks can
+result.  If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
+corruption is silently ignored; if set to @code{1}, a diagnostic is
+printed on @code{stderr}; if set to @code{2}, @code{abort} is called
+immediately.  This can be useful because otherwise a crash may happen
+much later, and the true cause for the problem is then very hard to
+track down.
+
+There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
+it could possibly be exploited since diverging from the normal programs
+behavior it now writes something to the standard error descriptor.
+Therefore the use of @code{MALLOC_CHECK_} is disabled by default for
+SUID and SGID binaries.  It can be enabled again by the system
+administrator by adding a file @file{/etc/suid-debug} (the content is
+not important it could be empty).
+
+So, what's the difference between using @code{MALLOC_CHECK_} and linking
+with @samp{-lmcheck}?  @code{MALLOC_CHECK_} is orthogonal with respect to
+@samp{-lmcheck}.  @samp{-lmcheck} has been added for backward
+compatibility.  Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
+uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
+recompile your application.
+
+@node Hooks for Malloc
+@subsubsection Memory Allocation Hooks
+@cindex allocation hooks, for @code{malloc}
+
+@Theglibc{} lets you modify the behavior of @code{malloc},
+@code{realloc}, and @code{free} by specifying appropriate hook
+functions.  You can use these hooks to help you debug programs that use
+dynamic memory allocation, for example.
+
+The hook variables are declared in @file{malloc.h}.
+@pindex malloc.h
+
+@comment malloc.h
+@comment GNU
+@defvar __malloc_hook
+The value of this variable is a pointer to the function that
+@code{malloc} uses whenever it is called.  You should define this
+function to look like @code{malloc}; that is, like:
+
+@smallexample
+void *@var{function} (size_t @var{size}, const void *@var{caller})
+@end smallexample
+
+The value of @var{caller} is the return address found on the stack when
+the @code{malloc} function was called.  This value allows you to trace
+the memory consumption of the program.
+@end defvar
+
+@comment malloc.h
+@comment GNU
+@defvar __realloc_hook
+The value of this variable is a pointer to function that @code{realloc}
+uses whenever it is called.  You should define this function to look
+like @code{realloc}; that is, like:
+
+@smallexample
+void *@var{function} (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
+@end smallexample
+
+The value of @var{caller} is the return address found on the stack when
+the @code{realloc} function was called.  This value allows you to trace the
+memory consumption of the program.
+@end defvar
+
+@comment malloc.h
+@comment GNU
+@defvar __free_hook
+The value of this variable is a pointer to function that @code{free}
+uses whenever it is called.  You should define this function to look
+like @code{free}; that is, like:
+
+@smallexample
+void @var{function} (void *@var{ptr}, const void *@var{caller})
+@end smallexample
+
+The value of @var{caller} is the return address found on the stack when
+the @code{free} function was called.  This value allows you to trace the
+memory consumption of the program.
+@end defvar
+
+@comment malloc.h
+@comment GNU
+@defvar __memalign_hook
+The value of this variable is a pointer to function that @code{aligned_alloc},
+@code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
+are called.  You should define this function to look like @code{aligned_alloc};
+that is, like:
+
+@smallexample
+void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
+@end smallexample
+
+The value of @var{caller} is the return address found on the stack when
+the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or
+@code{valloc} functions are called.  This value allows you to trace the
+memory consumption of the program.
+@end defvar
+
+You must make sure that the function you install as a hook for one of
+these functions does not call that function recursively without restoring
+the old value of the hook first!  Otherwise, your program will get stuck
+in an infinite recursion.  Before calling the function recursively, one
+should make sure to restore all the hooks to their previous value.  When
+coming back from the recursive call, all the hooks should be resaved
+since a hook might modify itself.
+
+@comment malloc.h
+@comment GNU
+@defvar __malloc_initialize_hook
+The value of this variable is a pointer to a function that is called
+once when the malloc implementation is initialized.  This is a weak
+variable, so it can be overridden in the application with a definition
+like the following:
+
+@smallexample
+void (*@var{__malloc_initialize_hook}) (void) = my_init_hook;
+@end smallexample
+@end defvar
+
+An issue to look out for is the time at which the malloc hook functions
+can be safely installed.  If the hook functions call the malloc-related
+functions recursively, it is necessary that malloc has already properly
+initialized itself at the time when @code{__malloc_hook} etc. is
+assigned to.  On the other hand, if the hook functions provide a
+complete malloc implementation of their own, it is vital that the hooks
+are assigned to @emph{before} the very first @code{malloc} call has
+completed, because otherwise a chunk obtained from the ordinary,
+un-hooked malloc may later be handed to @code{__free_hook}, for example.
+
+In both cases, the problem can be solved by setting up the hooks from
+within a user-defined function pointed to by
+@code{__malloc_initialize_hook}---then the hooks will be set up safely
+at the right time.
+
+Here is an example showing how to use @code{__malloc_hook} and
+@code{__free_hook} properly.  It installs a function that prints out
+information every time @code{malloc} or @code{free} is called.  We just
+assume here that @code{realloc} and @code{memalign} are not used in our
+program.
+
+@smallexample
+/* Prototypes for __malloc_hook, __free_hook */
+#include <malloc.h>
+
+/* Prototypes for our hooks.  */
+static void my_init_hook (void);
+static void *my_malloc_hook (size_t, const void *);
+static void my_free_hook (void*, const void *);
+
+/* Override initializing hook from the C library. */
+void (*__malloc_initialize_hook) (void) = my_init_hook;
+
+static void
+my_init_hook (void)
+@{
+  old_malloc_hook = __malloc_hook;
+  old_free_hook = __free_hook;
+  __malloc_hook = my_malloc_hook;
+  __free_hook = my_free_hook;
+@}
+
+static void *
+my_malloc_hook (size_t size, const void *caller)
+@{
+  void *result;
+  /* Restore all old hooks */
+  __malloc_hook = old_malloc_hook;
+  __free_hook = old_free_hook;
+  /* Call recursively */
+  result = malloc (size);
+  /* Save underlying hooks */
+  old_malloc_hook = __malloc_hook;
+  old_free_hook = __free_hook;
+  /* @r{@code{printf} might call @code{malloc}, so protect it too.} */
+  printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
+  /* Restore our own hooks */
+  __malloc_hook = my_malloc_hook;
+  __free_hook = my_free_hook;
+  return result;
+@}
+
+static void
+my_free_hook (void *ptr, const void *caller)
+@{
+  /* Restore all old hooks */
+  __malloc_hook = old_malloc_hook;
+  __free_hook = old_free_hook;
+  /* Call recursively */
+  free (ptr);
+  /* Save underlying hooks */
+  old_malloc_hook = __malloc_hook;
+  old_free_hook = __free_hook;
+  /* @r{@code{printf} might call @code{free}, so protect it too.} */
+  printf ("freed pointer %p\n", ptr);
+  /* Restore our own hooks */
+  __malloc_hook = my_malloc_hook;
+  __free_hook = my_free_hook;
+@}
+
+main ()
+@{
+  @dots{}
+@}
+@end smallexample
+
+The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
+installing such hooks.
+
+@c __morecore, __after_morecore_hook are undocumented
+@c It's not clear whether to document them.
+
+@node Statistics of Malloc
+@subsubsection Statistics for Memory Allocation with @code{malloc}
+
+@cindex allocation statistics
+You can get information about dynamic memory allocation by calling the
+@code{mallinfo} function.  This function and its associated data type
+are declared in @file{malloc.h}; they are an extension of the standard
+SVID/XPG version.
+@pindex malloc.h
+
+@comment malloc.h
+@comment GNU
+@deftp {Data Type} {struct mallinfo}
+This structure type is used to return information about the dynamic
+memory allocator.  It contains the following members:
+
+@table @code
+@item int arena
+This is the total size of memory allocated with @code{sbrk} by
+@code{malloc}, in bytes.
+
+@item int ordblks
+This is the number of chunks not in use.  (The memory allocator
+internally gets chunks of memory from the operating system, and then
+carves them up to satisfy individual @code{malloc} requests; see
+@ref{Efficiency and Malloc}.)
+
+@item int smblks
+This field is unused.
+
+@item int hblks
+This is the total number of chunks allocated with @code{mmap}.
+
+@item int hblkhd
+This is the total size of memory allocated with @code{mmap}, in bytes.
+
+@item int usmblks
+This field is unused.
+
+@item int fsmblks
+This field is unused.
+
+@item int uordblks
+This is the total size of memory occupied by chunks handed out by
+@code{malloc}.
+
+@item int fordblks
+This is the total size of memory occupied by free (not in use) chunks.
+
+@item int keepcost
+This is the size of the top-most releasable chunk that normally
+borders the end of the heap (i.e., the high end of the virtual address
+space's data segment).
+
+@end table
+@end deftp
+
+@comment malloc.h
+@comment SVID
+@deftypefun {struct mallinfo} mallinfo (void)
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
+@c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics
+@c but non-atomically elsewhere, may get us inconsistent results.  We
+@c mark the statistics as unsafe, rather than the fast-path functions
+@c that collect the possibly inconsistent data.
+
+@c __libc_mallinfo @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
+@c  ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
+@c  mutex_lock dup @asulock @aculock
+@c  int_mallinfo @mtasuconst:mallopt [mp_ access on main_arena]
+@c   malloc_consolidate dup ok
+@c   check_malloc_state dup ok/disabled
+@c   chunksize dup ok
+@c   fastbin dupo ok
+@c   bin_at dup ok
+@c   last dup ok
+@c  mutex_unlock @aculock
+
+This function returns information about the current dynamic memory usage
+in a structure of type @code{struct mallinfo}.
+@end deftypefun
+
+@node Summary of Malloc
+@subsubsection Summary of @code{malloc}-Related Functions
+
+Here is a summary of the functions that work with @code{malloc}:
+
+@table @code
+@item void *malloc (size_t @var{size})
+Allocate a block of @var{size} bytes.  @xref{Basic Allocation}.
+
+@item void free (void *@var{addr})
+Free a block previously allocated by @code{malloc}.  @xref{Freeing after
+Malloc}.
+
+@item void *realloc (void *@var{addr}, size_t @var{size})
+Make a block previously allocated by @code{malloc} larger or smaller,
+possibly by copying it to a new location.  @xref{Changing Block Size}.
+
+@item void *calloc (size_t @var{count}, size_t @var{eltsize})
+Allocate a block of @var{count} * @var{eltsize} bytes using
+@code{malloc}, and set its contents to zero.  @xref{Allocating Cleared
+Space}.
+
+@item void *valloc (size_t @var{size})
+Allocate a block of @var{size} bytes, starting on a page boundary.
+@xref{Aligned Memory Blocks}.
+
+@item void *aligned_alloc (size_t @var{size}, size_t @var{alignment})
+Allocate a block of @var{size} bytes, starting on an address that is a
+multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
+
+@item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
+Allocate a block of @var{size} bytes, starting on an address that is a
+multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
+
+@item void *memalign (size_t @var{size}, size_t @var{boundary})
+Allocate a block of @var{size} bytes, starting on an address that is a
+multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
+
+@item int mallopt (int @var{param}, int @var{value})
+Adjust a tunable parameter.  @xref{Malloc Tunable Parameters}.
+
+@item int mcheck (void (*@var{abortfn}) (void))
+Tell @code{malloc} to perform occasional consistency checks on
+dynamically allocated memory, and to call @var{abortfn} when an
+inconsistency is found.  @xref{Heap Consistency Checking}.
+
+@item void *(*__malloc_hook) (size_t @var{size}, const void *@var{caller})
+A pointer to a function that @code{malloc} uses whenever it is called.
+
+@item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
+A pointer to a function that @code{realloc} uses whenever it is called.
+
+@item void (*__free_hook) (void *@var{ptr}, const void *@var{caller})
+A pointer to a function that @code{free} uses whenever it is called.
+
+@item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
+A pointer to a function that @code{aligned_alloc}, @code{memalign},
+@code{posix_memalign} and @code{valloc} use whenever they are called.
+
+@item struct mallinfo mallinfo (void)
+Return information about the current dynamic memory usage.
+@xref{Statistics of Malloc}.
+@end table
+
+@node Allocation Debugging
+@subsection Allocation Debugging
+@cindex allocation debugging
+@cindex malloc debugger
+
+A complicated task when programming with languages which do not use
+garbage collected dynamic memory allocation is to find memory leaks.
+Long running programs must assure that dynamically allocated objects are
+freed at the end of their lifetime.  If this does not happen the system
+runs out of memory, sooner or later.
+
+The @code{malloc} implementation in @theglibc{} provides some
+simple means to detect such leaks and obtain some information to find
+the location.  To do this the application must be started in a special
+mode which is enabled by an environment variable.  There are no speed
+penalties for the program if the debugging mode is not enabled.
+
+@menu
+* 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?
+@end menu
+
+@node Tracing malloc
+@subsubsection How to install the tracing functionality
+
+@comment mcheck.h
+@comment GNU
+@deftypefun void mtrace (void)
+@safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Like the mcheck hooks, these are not designed with thread safety in
+@c mind, because the hook pointers are temporarily modified without
+@c regard to other threads, signals or cancellation.
+
+@c mtrace @mtuinit @mtasurace:mtrace @mtsenv @asuinit @ascuheap @asucorrupt @acuinit @acucorrupt @aculock @acsfd @acsmem
+@c  __libc_secure_getenv dup @mtsenv
+@c  malloc dup @ascuheap @acsmem
+@c  fopen dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  fcntl dup ok
+@c  setvbuf dup @aculock
+@c  fprintf dup (on newly-created stream) @aculock
+@c  __cxa_atexit (once) dup @asulock @aculock @acsmem
+@c  free dup @ascuheap @acsmem
+When the @code{mtrace} function is called it looks for an environment
+variable named @code{MALLOC_TRACE}.  This variable is supposed to
+contain a valid file name.  The user must have write access.  If the
+file already exists it is truncated.  If the environment variable is not
+set or it does not name a valid file which can be opened for writing
+nothing is done.  The behavior of @code{malloc} etc. is not changed.
+For obvious reasons this also happens if the application is installed
+with the SUID or SGID bit set.
+
+If the named file is successfully opened, @code{mtrace} installs special
+handlers for the functions @code{malloc}, @code{realloc}, and
+@code{free} (@pxref{Hooks for Malloc}).  From then on, all uses of these
+functions are traced and protocolled into the file.  There is now of
+course a speed penalty for all calls to the traced functions so tracing
+should not be enabled during normal use.
+
+This function is a GNU extension and generally not available on other
+systems.  The prototype can be found in @file{mcheck.h}.
+@end deftypefun
+
+@comment mcheck.h
+@comment GNU
+@deftypefun void muntrace (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}}
+
+@c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd
+@c  fprintf (fputs) dup @mtslocale @asucorrupt @ascuheap @acsmem @aculock @acucorrupt
+@c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+The @code{muntrace} function can be called after @code{mtrace} was used
+to enable tracing the @code{malloc} calls.  If no (successful) call of
+@code{mtrace} was made @code{muntrace} does nothing.
+
+Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
+and @code{free} and then closes the protocol file.  No calls are
+protocolled anymore and the program runs again at full speed.
+
+This function is a GNU extension and generally not available on other
+systems.  The prototype can be found in @file{mcheck.h}.
+@end deftypefun
+
+@node Using the Memory Debugger
+@subsubsection Example program excerpts
+
+Even though the tracing functionality does not influence the runtime
+behavior of the program it is not a good idea to call @code{mtrace} in
+all programs.  Just imagine that you debug a program using @code{mtrace}
+and all other programs used in the debugging session also trace their
+@code{malloc} calls.  The output file would be the same for all programs
+and thus is unusable.  Therefore one should call @code{mtrace} only if
+compiled for debugging.  A program could therefore start like this:
+
+@example
+#include <mcheck.h>
+
+int
+main (int argc, char *argv[])
+@{
+#ifdef DEBUGGING
+  mtrace ();
+#endif
+  @dots{}
+@}
+@end example
+
+This is all what is needed if you want to trace the calls during the
+whole runtime of the program.  Alternatively you can stop the tracing at
+any time with a call to @code{muntrace}.  It is even possible to restart
+the tracing again with a new call to @code{mtrace}.  But this can cause
+unreliable results since there may be calls of the functions which are
+not called.  Please note that not only the application uses the traced
+functions, also libraries (including the C library itself) use these
+functions.
+
+This last point is also why it is no good idea to call @code{muntrace}
+before the program terminated.  The libraries are informed about the
+termination of the program only after the program returns from
+@code{main} or calls @code{exit} and so cannot free the memory they use
+before this time.
+
+So the best thing one can do is to call @code{mtrace} as the very first
+function in the program and never call @code{muntrace}.  So the program
+traces almost all uses of the @code{malloc} functions (except those
+calls which are executed by constructors of the program or used
+libraries).
+
+@node Tips for the Memory Debugger
+@subsubsection Some more or less clever ideas
+
+You know the situation.  The program is prepared for debugging and in
+all debugging sessions it runs well.  But once it is started without
+debugging the error shows up.  A typical example is a memory leak that
+becomes visible only when we turn off the debugging.  If you foresee
+such situations you can still win.  Simply use something equivalent to
+the following little program:
+
+@example
+#include <mcheck.h>
+#include <signal.h>
+
+static void
+enable (int sig)
+@{
+  mtrace ();
+  signal (SIGUSR1, enable);
+@}
+
+static void
+disable (int sig)
+@{
+  muntrace ();
+  signal (SIGUSR2, disable);
+@}
+
+int
+main (int argc, char *argv[])
+@{
+  @dots{}
+
+  signal (SIGUSR1, enable);
+  signal (SIGUSR2, disable);
+
+  @dots{}
+@}
+@end example
+
+I.e., the user can start the memory debugger any time s/he wants if the
+program was started with @code{MALLOC_TRACE} set in the environment.
+The output will of course not show the allocations which happened before
+the first signal but if there is a memory leak this will show up
+nevertheless.
+
+@node Interpreting the traces
+@subsubsection Interpreting the traces
+
+If you take a look at the output it will look similar to this:
+
+@example
+= Start
+@ [0x8048209] - 0x8064cc8
+@ [0x8048209] - 0x8064ce0
+@ [0x8048209] - 0x8064cf8
+@ [0x80481eb] + 0x8064c48 0x14
+@ [0x80481eb] + 0x8064c60 0x14
+@ [0x80481eb] + 0x8064c78 0x14
+@ [0x80481eb] + 0x8064c90 0x14
+= End
+@end example
+
+What this all means is not really important since the trace file is not
+meant to be read by a human.  Therefore no attention is given to
+readability.  Instead there is a program which comes with @theglibc{}
+which interprets the traces and outputs a summary in an
+user-friendly way.  The program is called @code{mtrace} (it is in fact a
+Perl script) and it takes one or two arguments.  In any case the name of
+the file with the trace output must be specified.  If an optional
+argument precedes the name of the trace file this must be the name of
+the program which generated the trace.
+
+@example
+drepper$ mtrace tst-mtrace log
+No memory leaks.
+@end example
+
+In this case the program @code{tst-mtrace} was run and it produced a
+trace file @file{log}.  The message printed by @code{mtrace} shows there
+are no problems with the code, all allocated memory was freed
+afterwards.
+
+If we call @code{mtrace} on the example trace given above we would get a
+different outout:
+
+@example
+drepper$ mtrace errlog
+- 0x08064cc8 Free 2 was never alloc'd 0x8048209
+- 0x08064ce0 Free 3 was never alloc'd 0x8048209
+- 0x08064cf8 Free 4 was never alloc'd 0x8048209
+
+Memory not freed:
+-----------------
+   Address     Size     Caller
+0x08064c48     0x14  at 0x80481eb
+0x08064c60     0x14  at 0x80481eb
+0x08064c78     0x14  at 0x80481eb
+0x08064c90     0x14  at 0x80481eb
+@end example
+
+We have called @code{mtrace} with only one argument and so the script
+has no chance to find out what is meant with the addresses given in the
+trace.  We can do better:
+
+@example
+drepper$ mtrace tst errlog
+- 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
+- 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
+- 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
+
+Memory not freed:
+-----------------
+   Address     Size     Caller
+0x08064c48     0x14  at /home/drepper/tst.c:33
+0x08064c60     0x14  at /home/drepper/tst.c:33
+0x08064c78     0x14  at /home/drepper/tst.c:33
+0x08064c90     0x14  at /home/drepper/tst.c:33
+@end example
+
+Suddenly the output makes much more sense and the user can see
+immediately where the function calls causing the trouble can be found.
+
+Interpreting this output is not complicated.  There are at most two
+different situations being detected.  First, @code{free} was called for
+pointers which were never returned by one of the allocation functions.
+This is usually a very bad problem and what this looks like is shown in
+the first three lines of the output.  Situations like this are quite
+rare and if they appear they show up very drastically: the program
+normally crashes.
+
+The other situation which is much harder to detect are memory leaks.  As
+you can see in the output the @code{mtrace} function collects all this
+information and so can say that the program calls an allocation function
+from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
+times without freeing this memory before the program terminates.
+Whether this is a real problem remains to be investigated.
+
+@node Obstacks
+@subsection Obstacks
+@cindex obstacks
+
+An @dfn{obstack} is a pool of memory containing a stack of objects.  You
+can create any number of separate obstacks, and then allocate objects in
+specified obstacks.  Within each obstack, the last object allocated must
+always be the first one freed, but distinct obstacks are independent of
+each other.
+
+Aside from this one constraint of order of freeing, obstacks are totally
+general: an obstack can contain any number of objects of any size.  They
+are implemented with macros, so allocation is usually very fast as long as
+the objects are usually small.  And the only space overhead per object is
+the padding needed to start each object on a suitable boundary.
+
+@menu
+* 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::
+@end menu
+
+@node Creating Obstacks
+@subsubsection Creating Obstacks
+
+The utilities for manipulating obstacks are declared in the header
+file @file{obstack.h}.
+@pindex obstack.h
+
+@comment obstack.h
+@comment GNU
+@deftp {Data Type} {struct obstack}
+An obstack is represented by a data structure of type @code{struct
+obstack}.  This structure has a small fixed size; it records the status
+of the obstack and how to find the space in which objects are allocated.
+It does not contain any of the objects themselves.  You should not try
+to access the contents of the structure directly; use only the functions
+described in this chapter.
+@end deftp
+
+You can declare variables of type @code{struct obstack} and use them as
+obstacks, or you can allocate obstacks dynamically like any other kind
+of object.  Dynamic allocation of obstacks allows your program to have a
+variable number of different stacks.  (You can even allocate an
+obstack structure in another obstack, but this is rarely useful.)
+
+All the functions that work with obstacks require you to specify which
+obstack to use.  You do this with a pointer of type @code{struct obstack
+*}.  In the following, we often say ``an obstack'' when strictly
+speaking the object at hand is such a pointer.
+
+The objects in the obstack are packed into large blocks called
+@dfn{chunks}.  The @code{struct obstack} structure points to a chain of
+the chunks currently in use.
+
+The obstack library obtains a new chunk whenever you allocate an object
+that won't fit in the previous chunk.  Since the obstack library manages
+chunks automatically, you don't need to pay much attention to them, but
+you do need to supply a function which the obstack library should use to
+get a chunk.  Usually you supply a function which uses @code{malloc}
+directly or indirectly.  You must also supply a function to free a chunk.
+These matters are described in the following section.
+
+@node Preparing for Obstacks
+@subsubsection Preparing for Using Obstacks
+
+Each source file in which you plan to use the obstack functions
+must include the header file @file{obstack.h}, like this:
+
+@smallexample
+#include <obstack.h>
+@end smallexample
+
+@findex obstack_chunk_alloc
+@findex obstack_chunk_free
+Also, if the source file uses the macro @code{obstack_init}, it must
+declare or define two functions or macros that will be called by the
+obstack library.  One, @code{obstack_chunk_alloc}, is used to allocate
+the chunks of memory into which objects are packed.  The other,
+@code{obstack_chunk_free}, is used to return chunks when the objects in
+them are freed.  These macros should appear before any use of obstacks
+in the source file.
+
+Usually these are defined to use @code{malloc} via the intermediary
+@code{xmalloc} (@pxref{Unconstrained Allocation}).  This is done with
+the following pair of macro definitions:
+
+@smallexample
+#define obstack_chunk_alloc xmalloc
+#define obstack_chunk_free free
+@end smallexample
+
+@noindent
+Though the memory you get using obstacks really comes from @code{malloc},
+using obstacks is faster because @code{malloc} is called less often, for
+larger blocks of memory.  @xref{Obstack Chunks}, for full details.
+
+At run time, before the program can use a @code{struct obstack} object
+as an obstack, it must initialize the obstack by calling
+@code{obstack_init}.
+
+@comment obstack.h
+@comment GNU
+@deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}}
+@c obstack_init @mtsrace:obstack-ptr @acsmem
+@c  _obstack_begin @acsmem
+@c    chunkfun = obstack_chunk_alloc (suggested malloc)
+@c    freefun = obstack_chunk_free (suggested free)
+@c   *chunkfun @acsmem
+@c    obstack_chunk_alloc user-supplied
+@c   *obstack_alloc_failed_handler user-supplied
+@c    -> print_and_abort (default)
+@c
+@c print_and_abort
+@c  _ dup @ascuintl
+@c  fxprintf dup @asucorrupt @aculock @acucorrupt
+@c  exit @acucorrupt?
+Initialize obstack @var{obstack-ptr} for allocation of objects.  This
+function calls the obstack's @code{obstack_chunk_alloc} function.  If
+allocation of memory fails, the function pointed to by
+@code{obstack_alloc_failed_handler} is called.  The @code{obstack_init}
+function always returns 1 (Compatibility notice: Former versions of
+obstack returned 0 if allocation failed).
+@end deftypefun
+
+Here are two examples of how to allocate the space for an obstack and
+initialize it.  First, an obstack that is a static variable:
+
+@smallexample
+static struct obstack myobstack;
+@dots{}
+obstack_init (&myobstack);
+@end smallexample
+
+@noindent
+Second, an obstack that is itself dynamically allocated:
+
+@smallexample
+struct obstack *myobstack_ptr
+  = (struct obstack *) xmalloc (sizeof (struct obstack));
+
+obstack_init (myobstack_ptr);
+@end smallexample
+
+@comment obstack.h
+@comment GNU
+@defvar obstack_alloc_failed_handler
+The value of this variable is a pointer to a function that
+@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
+memory.  The default action is to print a message and abort.
+You should supply a function that either calls @code{exit}
+(@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
+Exits}) and doesn't return.
+
+@smallexample
+void my_obstack_alloc_failed (void)
+@dots{}
+obstack_alloc_failed_handler = &my_obstack_alloc_failed;
+@end smallexample
+
+@end defvar
+
+@node Allocation in an Obstack
+@subsubsection Allocation in an Obstack
+@cindex allocation (obstacks)
+
+The most direct way to allocate an object in an obstack is with
+@code{obstack_alloc}, which is invoked almost like @code{malloc}.
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
+This allocates an uninitialized block of @var{size} bytes in an obstack
+and returns its address.  Here @var{obstack-ptr} specifies which obstack
+to allocate the block in; it is the address of the @code{struct obstack}
+object which represents the obstack.  Each obstack function or macro
+requires you to specify an @var{obstack-ptr} as the first argument.
+
+This function calls the obstack's @code{obstack_chunk_alloc} function if
+it needs to allocate a new chunk of memory; it calls
+@code{obstack_alloc_failed_handler} if allocation of memory by
+@code{obstack_chunk_alloc} failed.
+@end deftypefun
+
+For example, here is a function that allocates a copy of a string @var{str}
+in a specific obstack, which is in the variable @code{string_obstack}:
+
+@smallexample
+struct obstack string_obstack;
+
+char *
+copystring (char *string)
+@{
+  size_t len = strlen (string) + 1;
+  char *s = (char *) obstack_alloc (&string_obstack, len);
+  memcpy (s, string, len);
+  return s;
+@}
+@end smallexample
+
+To allocate a block with specified contents, use the function
+@code{obstack_copy}, declared like this:
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
+This allocates a block and initializes it by copying @var{size}
+bytes of data starting at @var{address}.  It calls
+@code{obstack_alloc_failed_handler} if allocation of memory by
+@code{obstack_chunk_alloc} failed.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
+Like @code{obstack_copy}, but appends an extra byte containing a null
+character.  This extra byte is not counted in the argument @var{size}.
+@end deftypefun
+
+The @code{obstack_copy0} function is convenient for copying a sequence
+of characters into an obstack as a null-terminated string.  Here is an
+example of its use:
+
+@smallexample
+char *
+obstack_savestring (char *addr, int size)
+@{
+  return obstack_copy0 (&myobstack, addr, size);
+@}
+@end smallexample
+
+@noindent
+Contrast this with the previous example of @code{savestring} using
+@code{malloc} (@pxref{Basic Allocation}).
+
+@node Freeing Obstack Objects
+@subsubsection Freeing Objects in an Obstack
+@cindex freeing (obstacks)
+
+To free an object allocated in an obstack, use the function
+@code{obstack_free}.  Since the obstack is a stack of objects, freeing
+one object automatically frees all other objects allocated more recently
+in the same obstack.
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
+@c obstack_free @mtsrace:obstack-ptr @acucorrupt
+@c  (obstack_free) @mtsrace:obstack-ptr @acucorrupt
+@c   *freefun dup user-supplied
+If @var{object} is a null pointer, everything allocated in the obstack
+is freed.  Otherwise, @var{object} must be the address of an object
+allocated in the obstack.  Then @var{object} is freed, along with
+everything allocated in @var{obstack} since @var{object}.
+@end deftypefun
+
+Note that if @var{object} is a null pointer, the result is an
+uninitialized obstack.  To free all memory in an obstack but leave it
+valid for further allocation, call @code{obstack_free} with the address
+of the first object allocated on the obstack:
+
+@smallexample
+obstack_free (obstack_ptr, first_object_allocated_ptr);
+@end smallexample
+
+Recall that the objects in an obstack are grouped into chunks.  When all
+the objects in a chunk become free, the obstack library automatically
+frees the chunk (@pxref{Preparing for Obstacks}).  Then other
+obstacks, or non-obstack allocation, can reuse the space of the chunk.
+
+@node Obstack Functions
+@subsubsection Obstack Functions and Macros
+@cindex macros
+
+The interfaces for using obstacks may be defined either as functions or
+as macros, depending on the compiler.  The obstack facility works with
+all C compilers, including both @w{ISO C} and traditional C, but there are
+precautions you must take if you plan to use compilers other than GNU C.
+
+If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
+``functions'' are actually defined only as macros.  You can call these
+macros like functions, but you cannot use them in any other way (for
+example, you cannot take their address).
+
+Calling the macros requires a special precaution: namely, the first
+operand (the obstack pointer) may not contain any side effects, because
+it may be computed more than once.  For example, if you write this:
+
+@smallexample
+obstack_alloc (get_obstack (), 4);
+@end smallexample
+
+@noindent
+you will find that @code{get_obstack} may be called several times.
+If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
+you will get very strange results since the incrementation may occur
+several times.
+
+In @w{ISO C}, each function has both a macro definition and a function
+definition.  The function definition is used if you take the address of the
+function without calling it.  An ordinary call uses the macro definition by
+default, but you can request the function definition instead by writing the
+function name in parentheses, as shown here:
+
+@smallexample
+char *x;
+void *(*funcp) ();
+/* @r{Use the macro}.  */
+x = (char *) obstack_alloc (obptr, size);
+/* @r{Call the function}.  */
+x = (char *) (obstack_alloc) (obptr, size);
+/* @r{Take the address of the function}.  */
+funcp = obstack_alloc;
+@end smallexample
+
+@noindent
+This is the same situation that exists in @w{ISO C} for the standard library
+functions.  @xref{Macro Definitions}.
+
+@strong{Warning:} When you do use the macros, you must observe the
+precaution of avoiding side effects in the first operand, even in @w{ISO C}.
+
+If you use the GNU C compiler, this precaution is not necessary, because
+various language extensions in GNU C permit defining the macros so as to
+compute each argument only once.
+
+@node Growing Objects
+@subsubsection Growing Objects
+@cindex growing objects (in obstacks)
+@cindex changing the size of a block (obstacks)
+
+Because memory in obstack chunks is used sequentially, it is possible to
+build up an object step by step, adding one or more bytes at a time to the
+end of the object.  With this technique, you do not need to know how much
+data you will put in the object until you come to the end of it.  We call
+this the technique of @dfn{growing objects}.  The special functions
+for adding data to the growing object are described in this section.
+
+You don't need to do anything special when you start to grow an object.
+Using one of the functions to add data to the object automatically
+starts it.  However, it is necessary to say explicitly when the object is
+finished.  This is done with the function @code{obstack_finish}.
+
+The actual address of the object thus built up is not known until the
+object is finished.  Until then, it always remains possible that you will
+add so much data that the object must be copied into a new chunk.
+
+While the obstack is in use for a growing object, you cannot use it for
+ordinary allocation of another object.  If you try to do so, the space
+already added to the growing object will become part of the other object.
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c   *chunkfun dup @acsmem
+@c   *obstack_alloc_failed_handler dup user-supplied
+@c   *freefun
+@c  obstack_blank_fast dup @mtsrace:obstack-ptr
+The most basic function for adding to a growing object is
+@code{obstack_blank}, which adds space without initializing it.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  memcpy ok
+To add a block of initialized space, use @code{obstack_grow}, which is
+the growing-object analogue of @code{obstack_copy}.  It adds @var{size}
+bytes of data to the growing object, copying the contents from
+@var{data}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c   (no sequence point between storing NUL and incrementing next_free)
+@c   (multiple changes to next_free => @acucorrupt)
+@c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  memcpy ok
+This is the growing-object analogue of @code{obstack_copy0}.  It adds
+@var{size} bytes copied from @var{data}, followed by an additional null
+character.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_1grow_fast dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+To add one character at a time, use the function @code{obstack_1grow}.
+It adds a single byte containing @var{c} to the growing object.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_ptr_grow_fast dup @mtsrace:obstack-ptr
+Adding the value of a pointer one can use the function
+@code{obstack_ptr_grow}.  It adds @code{sizeof (void *)} bytes
+containing the value of @var{data}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c  obstack_int_grow_fast dup @mtsrace:obstack-ptr
+A single value of type @code{int} can be added by using the
+@code{obstack_int_grow} function.  It adds @code{sizeof (int)} bytes to
+the growing object and initializes them with the value of @var{data}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
+@c obstack_finish @mtsrace:obstack-ptr @acucorrupt
+When you are finished growing the object, use the function
+@code{obstack_finish} to close it off and return its final address.
+
+Once you have finished the object, the obstack is available for ordinary
+allocation or for growing another object.
+
+This function can return a null pointer under the same conditions as
+@code{obstack_alloc} (@pxref{Allocation in an Obstack}).
+@end deftypefun
+
+When you build an object by growing it, you will probably need to know
+afterward how long it became.  You need not keep track of this as you grow
+the object, because you can find out the length from the obstack just
+before finishing the object with the function @code{obstack_object_size},
+declared as follows:
+
+@comment obstack.h
+@comment GNU
+@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+This function returns the current size of the growing object, in bytes.
+Remember to call this function @emph{before} finishing the object.
+After it is finished, @code{obstack_object_size} will return zero.
+@end deftypefun
+
+If you have started growing an object and wish to cancel it, you should
+finish it and then free it, like this:
+
+@smallexample
+obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
+@end smallexample
+
+@noindent
+This has no effect if no object was growing.
+
+@cindex shrinking objects
+You can use @code{obstack_blank} with a negative size argument to make
+the current object smaller.  Just don't try to shrink it beyond zero
+length---there's no telling what will happen if you do that.
+
+@node Extra Fast Growing
+@subsubsection Extra Fast Growing Objects
+@cindex efficiency and obstacks
+
+The usual functions for growing objects incur overhead for checking
+whether there is room for the new growth in the current chunk.  If you
+are frequently constructing objects in small steps of growth, this
+overhead can be significant.
+
+You can reduce the overhead by using special ``fast growth''
+functions that grow the object without checking.  In order to have a
+robust program, you must do the checking yourself.  If you do this checking
+in the simplest way each time you are about to add data to the object, you
+have not saved anything, because that is what the ordinary growth
+functions do.  But if you can arrange to check less often, or check
+more efficiently, then you make the program faster.
+
+The function @code{obstack_room} returns the amount of room available
+in the current chunk.  It is declared as follows:
+
+@comment obstack.h
+@comment GNU
+@deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+This returns the number of bytes that can be added safely to the current
+growing object (or to an object about to be started) in obstack
+@var{obstack} using the fast growth functions.
+@end deftypefun
+
+While you know there is room, you can use these fast growth functions
+for adding data to a growing object:
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem
+@c   (no sequence point between copying c and incrementing next_free)
+The function @code{obstack_1grow_fast} adds one byte containing the
+character @var{c} to the growing object in obstack @var{obstack-ptr}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+@c obstack_ptr_grow_fast @mtsrace:obstack-ptr
+The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
+bytes containing the value of @var{data} to the growing object in
+obstack @var{obstack-ptr}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+@c obstack_int_grow_fast @mtsrace:obstack-ptr
+The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
+containing the value of @var{data} to the growing object in obstack
+@var{obstack-ptr}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+@c obstack_blank_fast @mtsrace:obstack-ptr
+The function @code{obstack_blank_fast} adds @var{size} bytes to the
+growing object in obstack @var{obstack-ptr} without initializing them.
+@end deftypefun
+
+When you check for space using @code{obstack_room} and there is not
+enough room for what you want to add, the fast growth functions
+are not safe.  In this case, simply use the corresponding ordinary
+growth function instead.  Very soon this will copy the object to a
+new chunk; then there will be lots of room available again.
+
+So, each time you use an ordinary growth function, check afterward for
+sufficient space using @code{obstack_room}.  Once the object is copied
+to a new chunk, there will be plenty of space again, so the program will
+start using the fast growth functions again.
+
+Here is an example:
+
+@smallexample
+@group
+void
+add_string (struct obstack *obstack, const char *ptr, int len)
+@{
+  while (len > 0)
+    @{
+      int room = obstack_room (obstack);
+      if (room == 0)
+        @{
+          /* @r{Not enough room.  Add one character slowly,}
+             @r{which may copy to a new chunk and make room.}  */
+          obstack_1grow (obstack, *ptr++);
+          len--;
+        @}
+      else
+        @{
+          if (room > len)
+            room = len;
+          /* @r{Add fast as much as we have room for.} */
+          len -= room;
+          while (room-- > 0)
+            obstack_1grow_fast (obstack, *ptr++);
+        @}
+    @}
+@}
+@end group
+@end smallexample
+
+@node Status of an Obstack
+@subsubsection Status of an Obstack
+@cindex obstack status
+@cindex status of obstack
+
+Here are functions that provide information on the current status of
+allocation in an obstack.  You can use them to learn about an object while
+still growing it.
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function returns the tentative address of the beginning of the
+currently growing object in @var{obstack-ptr}.  If you finish the object
+immediately, it will have that address.  If you make it larger first, it
+may outgrow the current chunk---then its address will change!
+
+If no object is growing, this value says where the next object you
+allocate will start (once again assuming it fits in the current
+chunk).
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
+This function returns the address of the first free byte in the current
+chunk of obstack @var{obstack-ptr}.  This is the end of the currently
+growing object.  If no object is growing, @code{obstack_next_free}
+returns the same value as @code{obstack_base}.
+@end deftypefun
+
+@comment obstack.h
+@comment GNU
+@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
+@c dup
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
+This function returns the size in bytes of the currently growing object.
+This is equivalent to
+
+@smallexample
+obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
+@end smallexample
+@end deftypefun
+
+@node Obstacks Data Alignment
+@subsubsection Alignment of Data in Obstacks
+@cindex alignment (in obstacks)
+
+Each obstack has an @dfn{alignment boundary}; each object allocated in
+the obstack automatically starts on an address that is a multiple of the
+specified boundary.  By default, this boundary is aligned so that
+the object can hold any type of data.
+
+To access an obstack's alignment boundary, use the macro
+@code{obstack_alignment_mask}, whose function prototype looks like
+this:
+
+@comment obstack.h
+@comment GNU
+@deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The value is a bit mask; a bit that is 1 indicates that the corresponding
+bit in the address of an object should be 0.  The mask value should be one
+less than a power of 2; the effect is that all object addresses are
+multiples of that power of 2.  The default value of the mask is a value
+that allows aligned objects to hold any type of data: for example, if
+its value is 3, any type of data can be stored at locations whose
+addresses are multiples of 4.  A mask value of 0 means an object can start
+on any multiple of 1 (that is, no alignment is required).
+
+The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
+so you can alter the mask by assignment.  For example, this statement:
+
+@smallexample
+obstack_alignment_mask (obstack_ptr) = 0;
+@end smallexample
+
+@noindent
+has the effect of turning off alignment processing in the specified obstack.
+@end deftypefn
+
+Note that a change in alignment mask does not take effect until
+@emph{after} the next time an object is allocated or finished in the
+obstack.  If you are not growing an object, you can make the new
+alignment mask take effect immediately by calling @code{obstack_finish}.
+This will finish a zero-length object and then do proper alignment for
+the next object.
+
+@node Obstack Chunks
+@subsubsection Obstack Chunks
+@cindex efficiency of chunks
+@cindex chunks
+
+Obstacks work by allocating space for themselves in large chunks, and
+then parceling out space in the chunks to satisfy your requests.  Chunks
+are normally 4096 bytes long unless you specify a different chunk size.
+The chunk size includes 8 bytes of overhead that are not actually used
+for storing objects.  Regardless of the specified size, longer chunks
+will be allocated when necessary for long objects.
+
+The obstack library allocates chunks by calling the function
+@code{obstack_chunk_alloc}, which you must define.  When a chunk is no
+longer needed because you have freed all the objects in it, the obstack
+library frees the chunk by calling @code{obstack_chunk_free}, which you
+must also define.
+
+These two must be defined (as macros) or declared (as functions) in each
+source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
+Most often they are defined as macros like this:
+
+@smallexample
+#define obstack_chunk_alloc malloc
+#define obstack_chunk_free free
+@end smallexample
+
+Note that these are simple macros (no arguments).  Macro definitions with
+arguments will not work!  It is necessary that @code{obstack_chunk_alloc}
+or @code{obstack_chunk_free}, alone, expand into a function name if it is
+not itself a function name.
+
+If you allocate chunks with @code{malloc}, the chunk size should be a
+power of 2.  The default chunk size, 4096, was chosen because it is long
+enough to satisfy many typical requests on the obstack yet short enough
+not to waste too much memory in the portion of the last chunk not yet used.
+
+@comment obstack.h
+@comment GNU
+@deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This returns the chunk size of the given obstack.
+@end deftypefn
+
+Since this macro expands to an lvalue, you can specify a new chunk size by
+assigning it a new value.  Doing so does not affect the chunks already
+allocated, but will change the size of chunks allocated for that particular
+obstack in the future.  It is unlikely to be useful to make the chunk size
+smaller, but making it larger might improve efficiency if you are
+allocating many objects whose size is comparable to the chunk size.  Here
+is how to do so cleanly:
+
+@smallexample
+if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
+  obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
+@end smallexample
+
+@node Summary of Obstacks
+@subsubsection Summary of Obstack Functions
+
+Here is a summary of all the functions associated with obstacks.  Each
+takes the address of an obstack (@code{struct obstack *}) as its first
+argument.
+
+@table @code
+@item void obstack_init (struct obstack *@var{obstack-ptr})
+Initialize use of an obstack.  @xref{Creating Obstacks}.
+
+@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
+Allocate an object of @var{size} uninitialized bytes.
+@xref{Allocation in an Obstack}.
+
+@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+Allocate an object of @var{size} bytes, with contents copied from
+@var{address}.  @xref{Allocation in an Obstack}.
+
+@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
+from @var{address}, followed by a null character at the end.
+@xref{Allocation in an Obstack}.
+
+@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
+Free @var{object} (and everything allocated in the specified obstack
+more recently than @var{object}).  @xref{Freeing Obstack Objects}.
+
+@item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
+Add @var{size} uninitialized bytes to a growing object.
+@xref{Growing Objects}.
+
+@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+Add @var{size} bytes, copied from @var{address}, to a growing object.
+@xref{Growing Objects}.
+
+@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
+Add @var{size} bytes, copied from @var{address}, to a growing object,
+and then add another byte containing a null character.  @xref{Growing
+Objects}.
+
+@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
+Add one byte containing @var{data-char} to a growing object.
+@xref{Growing Objects}.
+
+@item void *obstack_finish (struct obstack *@var{obstack-ptr})
+Finalize the object that is growing and return its permanent address.
+@xref{Growing Objects}.
+
+@item int obstack_object_size (struct obstack *@var{obstack-ptr})
+Get the current size of the currently growing object.  @xref{Growing
+Objects}.
+
+@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
+Add @var{size} uninitialized bytes to a growing object without checking
+that there is enough room.  @xref{Extra Fast Growing}.
+
+@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
+Add one byte containing @var{data-char} to a growing object without
+checking that there is enough room.  @xref{Extra Fast Growing}.
+
+@item int obstack_room (struct obstack *@var{obstack-ptr})
+Get the amount of room now available for growing the current object.
+@xref{Extra Fast Growing}.
+
+@item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
+The mask used for aligning the beginning of an object.  This is an
+lvalue.  @xref{Obstacks Data Alignment}.
+
+@item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
+The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.
+
+@item void *obstack_base (struct obstack *@var{obstack-ptr})
+Tentative starting address of the currently growing object.
+@xref{Status of an Obstack}.
+
+@item void *obstack_next_free (struct obstack *@var{obstack-ptr})
+Address just after the end of the currently growing object.
+@xref{Status of an Obstack}.
+@end table
+
+@node Variable Size Automatic
+@subsection Automatic Storage with Variable Size
+@cindex automatic freeing
+@cindex @code{alloca} function
+@cindex automatic storage with variable size
+
+The function @code{alloca} supports a kind of half-dynamic allocation in
+which blocks are allocated dynamically but freed automatically.
+
+Allocating a block with @code{alloca} is an explicit action; you can
+allocate as many blocks as you wish, and compute the size at run time.  But
+all the blocks are freed when you exit the function that @code{alloca} was
+called from, just as if they were automatic variables declared in that
+function.  There is no way to free the space explicitly.
+
+The prototype for @code{alloca} is in @file{stdlib.h}.  This function is
+a BSD extension.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment GNU, BSD
+@deftypefun {void *} alloca (size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The return value of @code{alloca} is the address of a block of @var{size}
+bytes of memory, allocated in the stack frame of the calling function.
+@end deftypefun
+
+Do not use @code{alloca} inside the arguments of a function call---you
+will get unpredictable results, because the stack space for the
+@code{alloca} would appear on the stack in the middle of the space for
+the function arguments.  An example of what to avoid is @code{foo (x,
+alloca (4), y)}.
+@c This might get fixed in future versions of GCC, but that won't make
+@c it safe with compilers generally.
+
+@menu
+* 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.
+@end menu
+
+@node Alloca Example
+@subsubsection @code{alloca} Example
+
+As an example of the use of @code{alloca}, here is a function that opens
+a file name made from concatenating two argument strings, and returns a
+file descriptor or minus one signifying failure:
+
+@smallexample
+int
+open2 (char *str1, char *str2, int flags, int mode)
+@{
+  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
+  stpcpy (stpcpy (name, str1), str2);
+  return open (name, flags, mode);
+@}
+@end smallexample
+
+@noindent
+Here is how you would get the same results with @code{malloc} and
+@code{free}:
+
+@smallexample
+int
+open2 (char *str1, char *str2, int flags, int mode)
+@{
+  char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
+  int desc;
+  if (name == 0)
+    fatal ("virtual memory exceeded");
+  stpcpy (stpcpy (name, str1), str2);
+  desc = open (name, flags, mode);
+  free (name);
+  return desc;
+@}
+@end smallexample
+
+As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
+other, more important advantages, and some disadvantages.
+
+@node Advantages of Alloca
+@subsubsection Advantages of @code{alloca}
+
+Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
+
+@itemize @bullet
+@item
+Using @code{alloca} wastes very little space and is very fast.  (It is
+open-coded by the GNU C compiler.)
+
+@item
+Since @code{alloca} does not have separate pools for different sizes of
+block, space used for any size block can be reused for any other size.
+@code{alloca} does not cause memory fragmentation.
+
+@item
+@cindex longjmp
+Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
+automatically free the space allocated with @code{alloca} when they exit
+through the function that called @code{alloca}.  This is the most
+important reason to use @code{alloca}.
+
+To illustrate this, suppose you have a function
+@code{open_or_report_error} which returns a descriptor, like
+@code{open}, if it succeeds, but does not return to its caller if it
+fails.  If the file cannot be opened, it prints an error message and
+jumps out to the command level of your program using @code{longjmp}.
+Let's change @code{open2} (@pxref{Alloca Example}) to use this
+subroutine:@refill
+
+@smallexample
+int
+open2 (char *str1, char *str2, int flags, int mode)
+@{
+  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
+  stpcpy (stpcpy (name, str1), str2);
+  return open_or_report_error (name, flags, mode);
+@}
+@end smallexample
+
+@noindent
+Because of the way @code{alloca} works, the memory it allocates is
+freed even when an error occurs, with no special effort required.
+
+By contrast, the previous definition of @code{open2} (which uses
+@code{malloc} and @code{free}) would develop a memory leak if it were
+changed in this way.  Even if you are willing to make more changes to
+fix it, there is no easy way to do so.
+@end itemize
+
+@node Disadvantages of Alloca
+@subsubsection Disadvantages of @code{alloca}
+
+@cindex @code{alloca} disadvantages
+@cindex disadvantages of @code{alloca}
+These are the disadvantages of @code{alloca} in comparison with
+@code{malloc}:
+
+@itemize @bullet
+@item
+If you try to allocate more memory than the machine can provide, you
+don't get a clean error message.  Instead you get a fatal signal like
+the one you would get from an infinite recursion; probably a
+segmentation violation (@pxref{Program Error Signals}).
+
+@item
+Some @nongnusystems{} fail to support @code{alloca}, so it is less
+portable.  However, a slower emulation of @code{alloca} written in C
+is available for use on systems with this deficiency.
+@end itemize
+
+@node GNU C Variable-Size Arrays
+@subsubsection GNU C Variable-Size Arrays
+@cindex variable-sized arrays
+
+In GNU C, you can replace most uses of @code{alloca} with an array of
+variable size.  Here is how @code{open2} would look then:
+
+@smallexample
+int open2 (char *str1, char *str2, int flags, int mode)
+@{
+  char name[strlen (str1) + strlen (str2) + 1];
+  stpcpy (stpcpy (name, str1), str2);
+  return open (name, flags, mode);
+@}
+@end smallexample
+
+But @code{alloca} is not always equivalent to a variable-sized array, for
+several reasons:
+
+@itemize @bullet
+@item
+A variable size array's space is freed at the end of the scope of the
+name of the array.  The space allocated with @code{alloca}
+remains until the end of the function.
+
+@item
+It is possible to use @code{alloca} within a loop, allocating an
+additional block on each iteration.  This is impossible with
+variable-sized arrays.
+@end itemize
+
+@strong{NB:} If you mix use of @code{alloca} and variable-sized arrays
+within one function, exiting a scope in which a variable-sized array was
+declared frees all blocks allocated with @code{alloca} during the
+execution of that scope.
+
+
+@node Resizing the Data Segment
+@section Resizing the Data Segment
+
+The symbols in this section are declared in @file{unistd.h}.
+
+You will not normally use the functions in this section, because the
+functions described in @ref{Memory Allocation} are easier to use.  Those
+are interfaces to a @glibcadj{} memory allocator that uses the
+functions below itself.  The functions below are simple interfaces to
+system calls.
+
+@comment unistd.h
+@comment BSD
+@deftypefun int brk (void *@var{addr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{brk} sets the high end of the calling process' data segment to
+@var{addr}.
+
+The address of the end of a segment is defined to be the address of the
+last byte in the segment plus 1.
+
+The function has no effect if @var{addr} is lower than the low end of
+the data segment.  (This is considered success, by the way).
+
+The function fails if it would cause the data segment to overlap another
+segment or exceed the process' data storage limit (@pxref{Limits on
+Resources}).
+
+The function is named for a common historical case where data storage
+and the stack are in the same segment.  Data storage allocation grows
+upward from the bottom of the segment while the stack grows downward
+toward it from the top of the segment and the curtain between them is
+called the @dfn{break}.
+
+The return value is zero on success.  On failure, the return value is
+@code{-1} and @code{errno} is set accordingly.  The following @code{errno}
+values are specific to this function:
+
+@table @code
+@item ENOMEM
+The request would cause the data segment to overlap another segment or
+exceed the process' data storage limit.
+@end table
+
+@c The Brk system call in Linux (as opposed to the GNU C Library function)
+@c is considerably different.  It always returns the new end of the data
+@c segment, whether it succeeds or fails.  The GNU C library Brk determines
+@c it's a failure if and only if the system call returns an address less
+@c than the address requested.
+
+@end deftypefun
+
+
+@comment unistd.h
+@comment BSD
+@deftypefun void *sbrk (ptrdiff_t @var{delta})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is the same as @code{brk} except that you specify the new
+end of the data segment as an offset @var{delta} from the current end
+and on success the return value is the address of the resulting end of
+the data segment instead of zero.
+
+This means you can use @samp{sbrk(0)} to find out what the current end
+of the data segment is.
+
+@end deftypefun
+
+
+
+@node Locking Pages
+@section Locking Pages
+@cindex locking pages
+@cindex memory lock
+@cindex paging
+
+You can tell the system to associate a particular virtual memory page
+with a real page frame and keep it that way --- i.e., cause the page to
+be paged in if it isn't already and mark it so it will never be paged
+out and consequently will never cause a page fault.  This is called
+@dfn{locking} a page.
+
+The functions in this chapter lock and unlock the calling process'
+pages.
+
+@menu
+* Why Lock Pages::                Reasons to read this section.
+* Locked Memory Details::         Everything you need to know locked
+                                    memory
+* Page Lock Functions::           Here's how to do it.
+@end menu
+
+@node Why Lock Pages
+@subsection Why Lock Pages
+
+Because page faults cause paged out pages to be paged in transparently,
+a process rarely needs to be concerned about locking pages.  However,
+there are two reasons people sometimes are:
+
+@itemize @bullet
+
+@item
+Speed.  A page fault is transparent only insofar as the process is not
+sensitive to how long it takes to do a simple memory access.  Time-critical
+processes, especially realtime processes, may not be able to wait or
+may not be able to tolerate variance in execution speed.
+@cindex realtime processing
+@cindex speed of execution
+
+A process that needs to lock pages for this reason probably also needs
+priority among other processes for use of the CPU.  @xref{Priority}.
+
+In some cases, the programmer knows better than the system's demand
+paging allocator which pages should remain in real memory to optimize
+system performance.  In this case, locking pages can help.
+
+@item
+Privacy.  If you keep secrets in virtual memory and that virtual memory
+gets paged out, that increases the chance that the secrets will get out.
+If a password gets written out to disk swap space, for example, it might
+still be there long after virtual and real memory have been wiped clean.
+
+@end itemize
+
+Be aware that when you lock a page, that's one fewer page frame that can
+be used to back other virtual memory (by the same or other processes),
+which can mean more page faults, which means the system runs more
+slowly.  In fact, if you lock enough memory, some programs may not be
+able to run at all for lack of real memory.
+
+@node Locked Memory Details
+@subsection Locked Memory Details
+
+A memory lock is associated with a virtual page, not a real frame.  The
+paging rule is: If a frame backs at least one locked page, don't page it
+out.
+
+Memory locks do not stack.  I.e., you can't lock a particular page twice
+so that it has to be unlocked twice before it is truly unlocked.  It is
+either locked or it isn't.
+
+A memory lock persists until the process that owns the memory explicitly
+unlocks it.  (But process termination and exec cause the virtual memory
+to cease to exist, which you might say means it isn't locked any more).
+
+Memory locks are not inherited by child processes.  (But note that on a
+modern Unix system, immediately after a fork, the parent's and the
+child's virtual address space are backed by the same real page frames,
+so the child enjoys the parent's locks).  @xref{Creating a Process}.
+
+Because of its ability to impact other processes, only the superuser can
+lock a page.  Any process can unlock its own page.
+
+The system sets limits on the amount of memory a process can have locked
+and the amount of real memory it can have dedicated to it.  @xref{Limits
+on Resources}.
+
+In Linux, locked pages aren't as locked as you might think.
+Two virtual pages that are not shared memory can nonetheless be backed
+by the same real frame.  The kernel does this in the name of efficiency
+when it knows both virtual pages contain identical data, and does it
+even if one or both of the virtual pages are locked.
+
+But when a process modifies one of those pages, the kernel must get it a
+separate frame and fill it with the page's data.  This is known as a
+@dfn{copy-on-write page fault}.  It takes a small amount of time and in
+a pathological case, getting that frame may require I/O.
+@cindex copy-on-write page fault
+@cindex page fault, copy-on-write
+
+To make sure this doesn't happen to your program, don't just lock the
+pages.  Write to them as well, unless you know you won't write to them
+ever.  And to make sure you have pre-allocated frames for your stack,
+enter a scope that declares a C automatic variable larger than the
+maximum stack size you will need, set it to something, then return from
+its scope.
+
+@node Page Lock Functions
+@subsection Functions To Lock And Unlock Pages
+
+The symbols in this section are declared in @file{sys/mman.h}.  These
+functions are defined by POSIX.1b, but their availability depends on
+your kernel.  If your kernel doesn't allow these functions, they exist
+but always fail.  They @emph{are} available with a Linux kernel.
+
+@strong{Portability Note:} POSIX.1b requires that when the @code{mlock}
+and @code{munlock} functions are available, the file @file{unistd.h}
+define the macro @code{_POSIX_MEMLOCK_RANGE} and the file
+@code{limits.h} define the macro @code{PAGESIZE} to be the size of a
+memory page in bytes.  It requires that when the @code{mlockall} and
+@code{munlockall} functions are available, the @file{unistd.h} file
+define the macro @code{_POSIX_MEMLOCK}.  @Theglibc{} conforms to
+this requirement.
+
+@comment sys/mman.h
+@comment POSIX.1b
+@deftypefun int mlock (const void *@var{addr}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{mlock} locks a range of the calling process' virtual pages.
+
+The range of memory starts at address @var{addr} and is @var{len} bytes
+long.  Actually, since you must lock whole pages, it is the range of
+pages that include any part of the specified range.
+
+When the function returns successfully, each of those pages is backed by
+(connected to) a real frame (is resident) and is marked to stay that
+way.  This means the function may cause page-ins and have to wait for
+them.
+
+When the function fails, it does not affect the lock status of any
+pages.
+
+The return value is zero if the function succeeds.  Otherwise, it is
+@code{-1} and @code{errno} is set accordingly.  @code{errno} values
+specific to this function are:
+
+@table @code
+@item ENOMEM
+@itemize @bullet
+@item
+At least some of the specified address range does not exist in the
+calling process' virtual address space.
+@item
+The locking would cause the process to exceed its locked page limit.
+@end itemize
+
+@item EPERM
+The calling process is not superuser.
+
+@item EINVAL
+@var{len} is not positive.
+
+@item ENOSYS
+The kernel does not provide @code{mlock} capability.
+
+@end table
+
+You can lock @emph{all} a process' memory with @code{mlockall}.  You
+unlock memory with @code{munlock} or @code{munlockall}.
+
+To avoid all page faults in a C program, you have to use
+@code{mlockall}, because some of the memory a program uses is hidden
+from the C code, e.g. the stack and automatic variables, and you
+wouldn't know what address to tell @code{mlock}.
+
+@end deftypefun
+
+@comment sys/mman.h
+@comment POSIX.1b
+@deftypefun int munlock (const void *@var{addr}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{munlock} unlocks a range of the calling process' virtual pages.
+
+@code{munlock} is the inverse of @code{mlock} and functions completely
+analogously to @code{mlock}, except that there is no @code{EPERM}
+failure.
+
+@end deftypefun
+
+@comment sys/mman.h
+@comment POSIX.1b
+@deftypefun int mlockall (int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{mlockall} locks all the pages in a process' virtual memory address
+space, and/or any that are added to it in the future.  This includes the
+pages of the code, data and stack segment, as well as shared libraries,
+user space kernel data, shared memory, and memory mapped files.
+
+@var{flags} is a string of single bit flags represented by the following
+macros.  They tell @code{mlockall} which of its functions you want.  All
+other bits must be zero.
+
+@table @code
+
+@item MCL_CURRENT
+Lock all pages which currently exist in the calling process' virtual
+address space.
+
+@item MCL_FUTURE
+Set a mode such that any pages added to the process' virtual address
+space in the future will be locked from birth.  This mode does not
+affect future address spaces owned by the same process so exec, which
+replaces a process' address space, wipes out @code{MCL_FUTURE}.
+@xref{Executing a File}.
+
+@end table
+
+When the function returns successfully, and you specified
+@code{MCL_CURRENT}, all of the process' pages are backed by (connected
+to) real frames (they are resident) and are marked to stay that way.
+This means the function may cause page-ins and have to wait for them.
+
+When the process is in @code{MCL_FUTURE} mode because it successfully
+executed this function and specified @code{MCL_CURRENT}, any system call
+by the process that requires space be added to its virtual address space
+fails with @code{errno} = @code{ENOMEM} if locking the additional space
+would cause the process to exceed its locked page limit.  In the case
+that the address space addition that can't be accommodated is stack
+expansion, the stack expansion fails and the kernel sends a
+@code{SIGSEGV} signal to the process.
+
+When the function fails, it does not affect the lock status of any pages
+or the future locking mode.
+
+The return value is zero if the function succeeds.  Otherwise, it is
+@code{-1} and @code{errno} is set accordingly.  @code{errno} values
+specific to this function are:
+
+@table @code
+@item ENOMEM
+@itemize @bullet
+@item
+At least some of the specified address range does not exist in the
+calling process' virtual address space.
+@item
+The locking would cause the process to exceed its locked page limit.
+@end itemize
+
+@item EPERM
+The calling process is not superuser.
+
+@item EINVAL
+Undefined bits in @var{flags} are not zero.
+
+@item ENOSYS
+The kernel does not provide @code{mlockall} capability.
+
+@end table
+
+You can lock just specific pages with @code{mlock}.  You unlock pages
+with @code{munlockall} and @code{munlock}.
+
+@end deftypefun
+
+
+@comment sys/mman.h
+@comment POSIX.1b
+@deftypefun int munlockall (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{munlockall} unlocks every page in the calling process' virtual
+address space and turn off @code{MCL_FUTURE} future locking mode.
+
+The return value is zero if the function succeeds.  Otherwise, it is
+@code{-1} and @code{errno} is set accordingly.  The only way this
+function can fail is for generic reasons that all functions and system
+calls can fail, so there are no specific @code{errno} values.
+
+@end deftypefun
+
+
+
+
+@ignore
+@c This was never actually implemented.  -zw
+@node Relocating Allocator
+@section Relocating Allocator
+
+@cindex relocating memory allocator
+Any system of dynamic memory allocation has overhead: the amount of
+space it uses is more than the amount the program asks for.  The
+@dfn{relocating memory allocator} achieves very low overhead by moving
+blocks in memory as necessary, on its own initiative.
+
+@c @menu
+@c * Relocator Concepts::		How to understand relocating allocation.
+@c * Using Relocator::		Functions for relocating allocation.
+@c @end menu
+
+@node Relocator Concepts
+@subsection Concepts of Relocating Allocation
+
+@ifinfo
+The @dfn{relocating memory allocator} achieves very low overhead by
+moving blocks in memory as necessary, on its own initiative.
+@end ifinfo
+
+When you allocate a block with @code{malloc}, the address of the block
+never changes unless you use @code{realloc} to change its size.  Thus,
+you can safely store the address in various places, temporarily or
+permanently, as you like.  This is not safe when you use the relocating
+memory allocator, because any and all relocatable blocks can move
+whenever you allocate memory in any fashion.  Even calling @code{malloc}
+or @code{realloc} can move the relocatable blocks.
+
+@cindex handle
+For each relocatable block, you must make a @dfn{handle}---a pointer
+object in memory, designated to store the address of that block.  The
+relocating allocator knows where each block's handle is, and updates the
+address stored there whenever it moves the block, so that the handle
+always points to the block.  Each time you access the contents of the
+block, you should fetch its address anew from the handle.
+
+To call any of the relocating allocator functions from a signal handler
+is almost certainly incorrect, because the signal could happen at any
+time and relocate all the blocks.  The only way to make this safe is to
+block the signal around any access to the contents of any relocatable
+block---not a convenient mode of operation.  @xref{Nonreentrancy}.
+
+@node Using Relocator
+@subsection Allocating and Freeing Relocatable Blocks
+
+@pindex malloc.h
+In the descriptions below, @var{handleptr} designates the address of the
+handle.  All the functions are declared in @file{malloc.h}; all are GNU
+extensions.
+
+@comment malloc.h
+@comment GNU
+@c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
+This function allocates a relocatable block of size @var{size}.  It
+stores the block's address in @code{*@var{handleptr}} and returns
+a non-null pointer to indicate success.
+
+If @code{r_alloc} can't get the space needed, it stores a null pointer
+in @code{*@var{handleptr}}, and returns a null pointer.
+@end deftypefun
+
+@comment malloc.h
+@comment GNU
+@c @deftypefun void r_alloc_free (void **@var{handleptr})
+This function is the way to free a relocatable block.  It frees the
+block that @code{*@var{handleptr}} points to, and stores a null pointer
+in @code{*@var{handleptr}} to show it doesn't point to an allocated
+block any more.
+@end deftypefun
+
+@comment malloc.h
+@comment GNU
+@c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
+The function @code{r_re_alloc} adjusts the size of the block that
+@code{*@var{handleptr}} points to, making it @var{size} bytes long.  It
+stores the address of the resized block in @code{*@var{handleptr}} and
+returns a non-null pointer to indicate success.
+
+If enough memory is not available, this function returns a null pointer
+and does not modify @code{*@var{handleptr}}.
+@end deftypefun
+@end ignore
+
+
+
+
+@ignore
+@comment No longer available...
+
+@comment @node Memory Warnings
+@comment @section Memory Usage Warnings
+@comment @cindex memory usage warnings
+@comment @cindex warnings of memory almost full
+
+@pindex malloc.c
+You can ask for warnings as the program approaches running out of memory
+space, by calling @code{memory_warnings}.  This tells @code{malloc} to
+check memory usage every time it asks for more memory from the operating
+system.  This is a GNU extension declared in @file{malloc.h}.
+
+@comment malloc.h
+@comment GNU
+@comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
+Call this function to request warnings for nearing exhaustion of virtual
+memory.
+
+The argument @var{start} says where data space begins, in memory.  The
+allocator compares this against the last address used and against the
+limit of data space, to determine the fraction of available memory in
+use.  If you supply zero for @var{start}, then a default value is used
+which is right in most circumstances.
+
+For @var{warn-func}, supply a function that @code{malloc} can call to
+warn you.  It is called with a string (a warning message) as argument.
+Normally it ought to display the string for the user to read.
+@end deftypefun
+
+The warnings come when memory becomes 75% full, when it becomes 85%
+full, and when it becomes 95% full.  Above 95% you get another warning
+each time memory usage increases.
+
+@end ignore
diff --git a/ap/libc/glibc/glibc-2.23/manual/message.texi b/ap/libc/glibc/glibc-2.23/manual/message.texi
new file mode 100644
index 0000000..b03a14a
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/message.texi
@@ -0,0 +1,1970 @@
+@node Message Translation, Searching and Sorting, Locales, Top
+@c %MENU% How to make the program speak the user's language
+@chapter Message Translation
+
+The program's interface with the user should be designed to ease the user's
+task.  One way to ease the user's task is to use messages in whatever
+language the user prefers.
+
+Printing messages in different languages can be implemented in different
+ways.  One could add all the different languages in the source code and
+choose among the variants every time a message has to be printed.  This is
+certainly not a good solution since extending the set of languages is
+cumbersome (the code must be changed) and the code itself can become
+really big with dozens of message sets.
+
+A better solution is to keep the message sets for each language
+in separate files which are loaded at runtime depending on the language
+selection of the user.
+
+@Theglibc{} provides two different sets of functions to support
+message translation.  The problem is that neither of the interfaces is
+officially defined by the POSIX standard.  The @code{catgets} family of
+functions is defined in the X/Open standard but this is derived from
+industry decisions and therefore not necessarily based on reasonable
+decisions.
+
+As mentioned above the message catalog handling provides easy
+extendibility by using external data files which contain the message
+translations.  I.e., these files contain for each of the messages used
+in the program a translation for the appropriate language.  So the tasks
+of the message handling functions are
+
+@itemize @bullet
+@item
+locate the external data file with the appropriate translations
+@item
+load the data and make it possible to address the messages
+@item
+map a given key to the translated message
+@end itemize
+
+The two approaches mainly differ in the implementation of this last
+step.  Decisions made in the last step influence the rest of the design.
+
+@menu
+* Message catalogs a la X/Open::  The @code{catgets} family of functions.
+* The Uniforum approach::         The @code{gettext} family of functions.
+@end menu
+
+
+@node Message catalogs a la X/Open
+@section X/Open Message Catalog Handling
+
+The @code{catgets} functions are based on the simple scheme:
+
+@quotation
+Associate every message to translate in the source code with a unique
+identifier.  To retrieve a message from a catalog file solely the
+identifier is used.
+@end quotation
+
+This means for the author of the program that s/he will have to make
+sure the meaning of the identifier in the program code and in the
+message catalogs are always the same.
+
+Before a message can be translated the catalog file must be located.
+The user of the program must be able to guide the responsible function
+to find whatever catalog the user wants.  This is separated from what
+the programmer had in mind.
+
+All the types, constants and functions for the @code{catgets} functions
+are defined/declared in the @file{nl_types.h} header file.
+
+@menu
+* 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.
+@end menu
+
+
+@node The catgets Functions
+@subsection The @code{catgets} function family
+
+@comment nl_types.h
+@comment X/Open
+@deftypefun nl_catd catopen (const char *@var{cat_name}, int @var{flag})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c catopen @mtsenv @ascuheap @acsmem
+@c  strchr ok
+@c  setlocale(,NULL) ok
+@c  getenv @mtsenv
+@c  strlen ok
+@c  alloca ok
+@c  stpcpy ok
+@c  malloc @ascuheap @acsmem
+@c  __open_catalog @ascuheap @acsmem
+@c   strchr ok
+@c   open_not_cancel_2 @acsfd
+@c   strlen ok
+@c   ENOUGH ok
+@c    alloca ok
+@c    memcpy ok
+@c   fxstat64 ok
+@c   __set_errno ok
+@c   mmap @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   read_not_cancel ok
+@c   free dup @ascuheap @acsmem
+@c   munmap ok
+@c   close_not_cancel_no_status ok
+@c  free @ascuheap @acsmem
+The @code{catopen} function tries to locate the message data file names
+@var{cat_name} and loads it when found.  The return value is of an
+opaque type and can be used in calls to the other functions to refer to
+this loaded catalog.
+
+The return value is @code{(nl_catd) -1} in case the function failed and
+no catalog was loaded.  The global variable @var{errno} contains a code
+for the error causing the failure.  But even if the function call
+succeeded this does not mean that all messages can be translated.
+
+Locating the catalog file must happen in a way which lets the user of
+the program influence the decision.  It is up to the user to decide
+about the language to use and sometimes it is useful to use alternate
+catalog files.  All this can be specified by the user by setting some
+environment variables.
+
+The first problem is to find out where all the message catalogs are
+stored.  Every program could have its own place to keep all the
+different files but usually the catalog files are grouped by languages
+and the catalogs for all programs are kept in the same place.
+
+@cindex NLSPATH environment variable
+To tell the @code{catopen} function where the catalog for the program
+can be found the user can set the environment variable @code{NLSPATH} to
+a value which describes her/his choice.  Since this value must be usable
+for different languages and locales it cannot be a simple string.
+Instead it is a format string (similar to @code{printf}'s).  An example
+is
+
+@smallexample
+/usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N
+@end smallexample
+
+First one can see that more than one directory can be specified (with
+the usual syntax of separating them by colons).  The next things to
+observe are the format string, @code{%L} and @code{%N} in this case.
+The @code{catopen} function knows about several of them and the
+replacement for all of them is of course different.
+
+@table @code
+@item %N
+This format element is substituted with the name of the catalog file.
+This is the value of the @var{cat_name} argument given to
+@code{catgets}.
+
+@item %L
+This format element is substituted with the name of the currently
+selected locale for translating messages.  How this is determined is
+explained below.
+
+@item %l
+(This is the lowercase ell.) This format element is substituted with the
+language element of the locale name.  The string describing the selected
+locale is expected to have the form
+@code{@var{lang}[_@var{terr}[.@var{codeset}]]} and this format uses the
+first part @var{lang}.
+
+@item %t
+This format element is substituted by the territory part @var{terr} of
+the name of the currently selected locale.  See the explanation of the
+format above.
+
+@item %c
+This format element is substituted by the codeset part @var{codeset} of
+the name of the currently selected locale.  See the explanation of the
+format above.
+
+@item %%
+Since @code{%} is used in a meta character there must be a way to
+express the @code{%} character in the result itself.  Using @code{%%}
+does this just like it works for @code{printf}.
+@end table
+
+
+Using @code{NLSPATH} allows arbitrary directories to be searched for
+message catalogs while still allowing different languages to be used.
+If the @code{NLSPATH} environment variable is not set, the default value
+is
+
+@smallexample
+@var{prefix}/share/locale/%L/%N:@var{prefix}/share/locale/%L/LC_MESSAGES/%N
+@end smallexample
+
+@noindent
+where @var{prefix} is given to @code{configure} while installing @theglibc{}
+(this value is in many cases @code{/usr} or the empty string).
+
+The remaining problem is to decide which must be used.  The value
+decides about the substitution of the format elements mentioned above.
+First of all the user can specify a path in the message catalog name
+(i.e., the name contains a slash character).  In this situation the
+@code{NLSPATH} environment variable is not used.  The catalog must exist
+as specified in the program, perhaps relative to the current working
+directory.  This situation in not desirable and catalogs names never
+should be written this way.  Beside this, this behavior is not portable
+to all other platforms providing the @code{catgets} interface.
+
+@cindex LC_ALL environment variable
+@cindex LC_MESSAGES environment variable
+@cindex LANG environment variable
+Otherwise the values of environment variables from the standard
+environment are examined (@pxref{Standard Environment}).  Which
+variables are examined is decided by the @var{flag} parameter of
+@code{catopen}.  If the value is @code{NL_CAT_LOCALE} (which is defined
+in @file{nl_types.h}) then the @code{catopen} function use the name of
+the locale currently selected for the @code{LC_MESSAGES} category.
+
+If @var{flag} is zero the @code{LANG} environment variable is examined.
+This is a left-over from the early days where the concept of the locales
+had not even reached the level of POSIX locales.
+
+The environment variable and the locale name should have a value of the
+form @code{@var{lang}[_@var{terr}[.@var{codeset}]]} as explained above.
+If no environment variable is set the @code{"C"} locale is used which
+prevents any translation.
+
+The return value of the function is in any case a valid string.  Either
+it is a translation from a message catalog or it is the same as the
+@var{string} parameter.  So a piece of code to decide whether a
+translation actually happened must look like this:
+
+@smallexample
+@{
+  char *trans = catgets (desc, set, msg, input_string);
+  if (trans == input_string)
+    @{
+      /* Something went wrong.  */
+    @}
+@}
+@end smallexample
+
+@noindent
+When an error occurred the global variable @var{errno} is set to
+
+@table @var
+@item EBADF
+The catalog does not exist.
+@item ENOMSG
+The set/message tuple does not name an existing element in the
+message catalog.
+@end table
+
+While it sometimes can be useful to test for errors programs normally
+will avoid any test.  If the translation is not available it is no big
+problem if the original, untranslated message is printed.  Either the
+user understands this as well or s/he will look for the reason why the
+messages are not translated.
+@end deftypefun
+
+Please note that the currently selected locale does not depend on a call
+to the @code{setlocale} function.  It is not necessary that the locale
+data files for this locale exist and calling @code{setlocale} succeeds.
+The @code{catopen} function directly reads the values of the environment
+variables.
+
+
+@deftypefun {char *} catgets (nl_catd @var{catalog_desc}, int @var{set}, int @var{message}, const char *@var{string})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{catgets} has to be used to access the massage catalog
+previously opened using the @code{catopen} function.  The
+@var{catalog_desc} parameter must be a value previously returned by
+@code{catopen}.
+
+The next two parameters, @var{set} and @var{message}, reflect the
+internal organization of the message catalog files.  This will be
+explained in detail below.  For now it is interesting to know that a
+catalog can consists of several set and the messages in each thread are
+individually numbered using numbers.  Neither the set number nor the
+message number must be consecutive.  They can be arbitrarily chosen.
+But each message (unless equal to another one) must have its own unique
+pair of set and message number.
+
+Since it is not guaranteed that the message catalog for the language
+selected by the user exists the last parameter @var{string} helps to
+handle this case gracefully.  If no matching string can be found
+@var{string} is returned.  This means for the programmer that
+
+@itemize @bullet
+@item
+the @var{string} parameters should contain reasonable text (this also
+helps to understand the program seems otherwise there would be no hint
+on the string which is expected to be returned.
+@item
+all @var{string} arguments should be written in the same language.
+@end itemize
+@end deftypefun
+
+It is somewhat uncomfortable to write a program using the @code{catgets}
+functions if no supporting functionality is available.  Since each
+set/message number tuple must be unique the programmer must keep lists
+of the messages at the same time the code is written.  And the work
+between several people working on the same project must be coordinated.
+We will see some how these problems can be relaxed a bit (@pxref{Common
+Usage}).
+
+@deftypefun int catclose (nl_catd @var{catalog_desc})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c catclose @ascuheap @acucorrupt @acsmem
+@c  __set_errno ok
+@c  munmap ok
+@c  free @ascuheap @acsmem
+The @code{catclose} function can be used to free the resources
+associated with a message catalog which previously was opened by a call
+to @code{catopen}.  If the resources can be successfully freed the
+function returns @code{0}.  Otherwise it return @code{@minus{}1} and the
+global variable @var{errno} is set.  Errors can occur if the catalog
+descriptor @var{catalog_desc} is not valid in which case @var{errno} is
+set to @code{EBADF}.
+@end deftypefun
+
+
+@node The message catalog files
+@subsection  Format of the message catalog files
+
+The only reasonable way the translate all the messages of a function and
+store the result in a message catalog file which can be read by the
+@code{catopen} function is to write all the message text to the
+translator and let her/him translate them all.  I.e., we must have a
+file with entries which associate the set/message tuple with a specific
+translation.  This file format is specified in the X/Open standard and
+is as follows:
+
+@itemize @bullet
+@item
+Lines containing only whitespace characters or empty lines are ignored.
+
+@item
+Lines which contain as the first non-whitespace character a @code{$}
+followed by a whitespace character are comment and are also ignored.
+
+@item
+If a line contains as the first non-whitespace characters the sequence
+@code{$set} followed by a whitespace character an additional argument
+is required to follow.  This argument can either be:
+
+@itemize @minus
+@item
+a number.  In this case the value of this number determines the set
+to which the following messages are added.
+
+@item
+an identifier consisting of alphanumeric characters plus the underscore
+character.  In this case the set get automatically a number assigned.
+This value is one added to the largest set number which so far appeared.
+
+How to use the symbolic names is explained in section @ref{Common Usage}.
+
+It is an error if a symbol name appears more than once.  All following
+messages are placed in a set with this number.
+@end itemize
+
+@item
+If a line contains as the first non-whitespace characters the sequence
+@code{$delset} followed by a whitespace character an additional argument
+is required to follow.  This argument can either be:
+
+@itemize @minus
+@item
+a number.  In this case the value of this number determines the set
+which will be deleted.
+
+@item
+an identifier consisting of alphanumeric characters plus the underscore
+character.  This symbolic identifier must match a name for a set which
+previously was defined.  It is an error if the name is unknown.
+@end itemize
+
+In both cases all messages in the specified set will be removed.  They
+will not appear in the output.  But if this set is later again selected
+with a @code{$set} command again messages could be added and these
+messages will appear in the output.
+
+@item
+If a line contains after leading whitespaces the sequence
+@code{$quote}, the quoting character used for this input file is
+changed to the first non-whitespace character following the
+@code{$quote}.  If no non-whitespace character is present before the
+line ends quoting is disable.
+
+By default no quoting character is used.  In this mode strings are
+terminated with the first unescaped line break.  If there is a
+@code{$quote} sequence present newline need not be escaped.  Instead a
+string is terminated with the first unescaped appearance of the quote
+character.
+
+A common usage of this feature would be to set the quote character to
+@code{"}.  Then any appearance of the @code{"} in the strings must
+be escaped using the backslash (i.e., @code{\"} must be written).
+
+@item
+Any other line must start with a number or an alphanumeric identifier
+(with the underscore character included).  The following characters
+(starting after the first whitespace character) will form the string
+which gets associated with the currently selected set and the message
+number represented by the number and identifier respectively.
+
+If the start of the line is a number the message number is obvious.  It
+is an error if the same message number already appeared for this set.
+
+If the leading token was an identifier the message number gets
+automatically assigned.  The value is the current maximum messages
+number for this set plus one.  It is an error if the identifier was
+already used for a message in this set.  It is OK to reuse the
+identifier for a message in another thread.  How to use the symbolic
+identifiers will be explained below (@pxref{Common Usage}).  There is
+one limitation with the identifier: it must not be @code{Set}.  The
+reason will be explained below.
+
+The text of the messages can contain escape characters.  The usual bunch
+of characters known from the @w{ISO C} language are recognized
+(@code{\n}, @code{\t}, @code{\v}, @code{\b}, @code{\r}, @code{\f},
+@code{\\}, and @code{\@var{nnn}}, where @var{nnn} is the octal coding of
+a character code).
+@end itemize
+
+@strong{Important:} The handling of identifiers instead of numbers for
+the set and messages is a GNU extension.  Systems strictly following the
+X/Open specification do not have this feature.  An example for a message
+catalog file is this:
+
+@smallexample
+$ This is a leading comment.
+$quote "
+
+$set SetOne
+1 Message with ID 1.
+two "   Message with ID \"two\", which gets the value 2 assigned"
+
+$set SetTwo
+$ Since the last set got the number 1 assigned this set has number 2.
+4000 "The numbers can be arbitrary, they need not start at one."
+@end smallexample
+
+This small example shows various aspects:
+@itemize @bullet
+@item
+Lines 1 and 9 are comments since they start with @code{$} followed by
+a whitespace.
+@item
+The quoting character is set to @code{"}.  Otherwise the quotes in the
+message definition would have to be left away and in this case the
+message with the identifier @code{two} would loose its leading whitespace.
+@item
+Mixing numbered messages with message having symbolic names is no
+problem and the numbering happens automatically.
+@end itemize
+
+
+While this file format is pretty easy it is not the best possible for
+use in a running program.  The @code{catopen} function would have to
+parser the file and handle syntactic errors gracefully.  This is not so
+easy and the whole process is pretty slow.  Therefore the @code{catgets}
+functions expect the data in another more compact and ready-to-use file
+format.  There is a special program @code{gencat} which is explained in
+detail in the next section.
+
+Files in this other format are not human readable.  To be easy to use by
+programs it is a binary file.  But the format is byte order independent
+so translation files can be shared by systems of arbitrary architecture
+(as long as they use @theglibc{}).
+
+Details about the binary file format are not important to know since
+these files are always created by the @code{gencat} program.  The
+sources of @theglibc{} also provide the sources for the
+@code{gencat} program and so the interested reader can look through
+these source files to learn about the file format.
+
+
+@node The gencat program
+@subsection Generate Message Catalogs files
+
+@cindex gencat
+The @code{gencat} program is specified in the X/Open standard and the
+GNU implementation follows this specification and so processes
+all correctly formed input files.  Additionally some extension are
+implemented which help to work in a more reasonable way with the
+@code{catgets} functions.
+
+The @code{gencat} program can be invoked in two ways:
+
+@example
+`gencat [@var{Option}]@dots{} [@var{Output-File} [@var{Input-File}]@dots{}]`
+@end example
+
+This is the interface defined in the X/Open standard.  If no
+@var{Input-File} parameter is given input will be read from standard
+input.  Multiple input files will be read as if they are concatenated.
+If @var{Output-File} is also missing, the output will be written to
+standard output.  To provide the interface one is used to from other
+programs a second interface is provided.
+
+@smallexample
+`gencat [@var{Option}]@dots{} -o @var{Output-File} [@var{Input-File}]@dots{}`
+@end smallexample
+
+The option @samp{-o} is used to specify the output file and all file
+arguments are used as input files.
+
+Beside this one can use @file{-} or @file{/dev/stdin} for
+@var{Input-File} to denote the standard input.  Corresponding one can
+use @file{-} and @file{/dev/stdout} for @var{Output-File} to denote
+standard output.  Using @file{-} as a file name is allowed in X/Open
+while using the device names is a GNU extension.
+
+The @code{gencat} program works by concatenating all input files and
+then @strong{merge} the resulting collection of message sets with a
+possibly existing output file.  This is done by removing all messages
+with set/message number tuples matching any of the generated messages
+from the output file and then adding all the new messages.  To
+regenerate a catalog file while ignoring the old contents therefore
+requires to remove the output file if it exists.  If the output is
+written to standard output no merging takes place.
+
+@noindent
+The following table shows the options understood by the @code{gencat}
+program.  The X/Open standard does not specify any option for the
+program so all of these are GNU extensions.
+
+@table @samp
+@item -V
+@itemx --version
+Print the version information and exit.
+@item -h
+@itemx --help
+Print a usage message listing all available options, then exit successfully.
+@item --new
+Do never merge the new messages from the input files with the old content
+of the output files.  The old content of the output file is discarded.
+@item -H
+@itemx --header=name
+This option is used to emit the symbolic names given to sets and
+messages in the input files for use in the program.  Details about how
+to use this are given in the next section.  The @var{name} parameter to
+this option specifies the name of the output file.  It will contain a
+number of C preprocessor @code{#define}s to associate a name with a
+number.
+
+Please note that the generated file only contains the symbols from the
+input files.  If the output is merged with the previous content of the
+output file the possibly existing symbols from the file(s) which
+generated the old output files are not in the generated header file.
+@end table
+
+
+@node Common Usage
+@subsection How to use the @code{catgets} interface
+
+The @code{catgets} functions can be used in two different ways.  By
+following slavishly the X/Open specs and not relying on the extension
+and by using the GNU extensions.  We will take a look at the former
+method first to understand the benefits of extensions.
+
+@subsubsection Not using symbolic names
+
+Since the X/Open format of the message catalog files does not allow
+symbol names we have to work with numbers all the time.  When we start
+writing a program we have to replace all appearances of translatable
+strings with something like
+
+@smallexample
+catgets (catdesc, set, msg, "string")
+@end smallexample
+
+@noindent
+@var{catgets} is retrieved from a call to @code{catopen} which is
+normally done once at the program start.  The @code{"string"} is the
+string we want to translate.  The problems start with the set and
+message numbers.
+
+In a bigger program several programmers usually work at the same time on
+the program and so coordinating the number allocation is crucial.
+Though no two different strings must be indexed by the same tuple of
+numbers it is highly desirable to reuse the numbers for equal strings
+with equal translations (please note that there might be strings which
+are equal in one language but have different translations due to
+difference contexts).
+
+The allocation process can be relaxed a bit by different set numbers for
+different parts of the program.  So the number of developers who have to
+coordinate the allocation can be reduced.  But still lists must be keep
+track of the allocation and errors can easily happen.  These errors
+cannot be discovered by the compiler or the @code{catgets} functions.
+Only the user of the program might see wrong messages printed.  In the
+worst cases the messages are so irritating that they cannot be
+recognized as wrong.  Think about the translations for @code{"true"} and
+@code{"false"} being exchanged.  This could result in a disaster.
+
+
+@subsubsection Using symbolic names
+
+The problems mentioned in the last section derive from the fact that:
+
+@enumerate
+@item
+the numbers are allocated once and due to the possibly frequent use of
+them it is difficult to change a number later.
+@item
+the numbers do not allow to guess anything about the string and
+therefore collisions can easily happen.
+@end enumerate
+
+By constantly using symbolic names and by providing a method which maps
+the string content to a symbolic name (however this will happen) one can
+prevent both problems above.  The cost of this is that the programmer
+has to write a complete message catalog file while s/he is writing the
+program itself.
+
+This is necessary since the symbolic names must be mapped to numbers
+before the program sources can be compiled.  In the last section it was
+described how to generate a header containing the mapping of the names.
+E.g., for the example message file given in the last section we could
+call the @code{gencat} program as follow (assume @file{ex.msg} contains
+the sources).
+
+@smallexample
+gencat -H ex.h -o ex.cat ex.msg
+@end smallexample
+
+@noindent
+This generates a header file with the following content:
+
+@smallexample
+#define SetTwoSet 0x2   /* ex.msg:8 */
+
+#define SetOneSet 0x1   /* ex.msg:4 */
+#define SetOnetwo 0x2   /* ex.msg:6 */
+@end smallexample
+
+As can be seen the various symbols given in the source file are mangled
+to generate unique identifiers and these identifiers get numbers
+assigned.  Reading the source file and knowing about the rules will
+allow to predict the content of the header file (it is deterministic)
+but this is not necessary.  The @code{gencat} program can take care for
+everything.  All the programmer has to do is to put the generated header
+file in the dependency list of the source files of her/his project and
+to add a rules to regenerate the header of any of the input files
+change.
+
+One word about the symbol mangling.  Every symbol consists of two parts:
+the name of the message set plus the name of the message or the special
+string @code{Set}.  So @code{SetOnetwo} means this macro can be used to
+access the translation with identifier @code{two} in the message set
+@code{SetOne}.
+
+The other names denote the names of the message sets.  The special
+string @code{Set} is used in the place of the message identifier.
+
+If in the code the second string of the set @code{SetOne} is used the C
+code should look like this:
+
+@smallexample
+catgets (catdesc, SetOneSet, SetOnetwo,
+         "   Message with ID \"two\", which gets the value 2 assigned")
+@end smallexample
+
+Writing the function this way will allow to change the message number
+and even the set number without requiring any change in the C source
+code.  (The text of the string is normally not the same; this is only
+for this example.)
+
+
+@subsubsection How does to this allow to develop
+
+To illustrate the usual way to work with the symbolic version numbers
+here is a little example.  Assume we want to write the very complex and
+famous greeting program.  We start by writing the code as usual:
+
+@smallexample
+#include <stdio.h>
+int
+main (void)
+@{
+  printf ("Hello, world!\n");
+  return 0;
+@}
+@end smallexample
+
+Now we want to internationalize the message and therefore replace the
+message with whatever the user wants.
+
+@smallexample
+#include <nl_types.h>
+#include <stdio.h>
+#include "msgnrs.h"
+int
+main (void)
+@{
+  nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);
+  printf (catgets (catdesc, SetMainSet, SetMainHello,
+                   "Hello, world!\n"));
+  catclose (catdesc);
+  return 0;
+@}
+@end smallexample
+
+We see how the catalog object is opened and the returned descriptor used
+in the other function calls.  It is not really necessary to check for
+failure of any of the functions since even in these situations the
+functions will behave reasonable.  They simply will be return a
+translation.
+
+What remains unspecified here are the constants @code{SetMainSet} and
+@code{SetMainHello}.  These are the symbolic names describing the
+message.  To get the actual definitions which match the information in
+the catalog file we have to create the message catalog source file and
+process it using the @code{gencat} program.
+
+@smallexample
+$ Messages for the famous greeting program.
+$quote "
+
+$set Main
+Hello "Hallo, Welt!\n"
+@end smallexample
+
+Now we can start building the program (assume the message catalog source
+file is named @file{hello.msg} and the program source file @file{hello.c}):
+
+@smallexample
+% gencat -H msgnrs.h -o hello.cat hello.msg
+% cat msgnrs.h
+#define MainSet 0x1     /* hello.msg:4 */
+#define MainHello 0x1   /* hello.msg:5 */
+% gcc -o hello hello.c -I.
+% cp hello.cat /usr/share/locale/de/LC_MESSAGES
+% echo $LC_ALL
+de
+% ./hello
+Hallo, Welt!
+%
+@end smallexample
+
+The call of the @code{gencat} program creates the missing header file
+@file{msgnrs.h} as well as the message catalog binary.  The former is
+used in the compilation of @file{hello.c} while the later is placed in a
+directory in which the @code{catopen} function will try to locate it.
+Please check the @code{LC_ALL} environment variable and the default path
+for @code{catopen} presented in the description above.
+
+
+@node The Uniforum approach
+@section The Uniforum approach to Message Translation
+
+Sun Microsystems tried to standardize a different approach to message
+translation in the Uniforum group.  There never was a real standard
+defined but still the interface was used in Sun's operating systems.
+Since this approach fits better in the development process of free
+software it is also used throughout the GNU project and the GNU
+@file{gettext} package provides support for this outside @theglibc{}.
+
+The code of the @file{libintl} from GNU @file{gettext} is the same as
+the code in @theglibc{}.  So the documentation in the GNU
+@file{gettext} manual is also valid for the functionality here.  The
+following text will describe the library functions in detail.  But the
+numerous helper programs are not described in this manual.  Instead
+people should read the GNU @file{gettext} manual
+(@pxref{Top,,GNU gettext utilities,gettext,Native Language Support Library and Tools}).
+We will only give a short overview.
+
+Though the @code{catgets} functions are available by default on more
+systems the @code{gettext} interface is at least as portable as the
+former.  The GNU @file{gettext} package can be used wherever the
+functions are not available.
+
+
+@menu
+* Message catalogs with gettext::  The @code{gettext} family of functions.
+* Helper programs for gettext::    Programs to handle message catalogs
+                                    for @code{gettext}.
+@end menu
+
+
+@node Message catalogs with gettext
+@subsection The @code{gettext} family of functions
+
+The paradigms underlying the @code{gettext} approach to message
+translations is different from that of the @code{catgets} functions the
+basic functionally is equivalent.  There are functions of the following
+categories:
+
+@menu
+* Translation with gettext::       What has to be done to translate a message.
+* Locating gettext catalog::       How to determine which catalog to be used.
+* Advanced gettext functions::     Additional functions for more complicated
+                                    situations.
+* Charset conversion in gettext::  How to specify the output character set
+                                    @code{gettext} uses.
+* GUI program problems::           How to use @code{gettext} in GUI programs.
+* Using gettextized software::     The possibilities of the user to influence
+                                    the way @code{gettext} works.
+@end menu
+
+@node Translation with gettext
+@subsubsection What has to be done to translate a message?
+
+The @code{gettext} functions have a very simple interface.  The most
+basic function just takes the string which shall be translated as the
+argument and it returns the translation.  This is fundamentally
+different from the @code{catgets} approach where an extra key is
+necessary and the original string is only used for the error case.
+
+If the string which has to be translated is the only argument this of
+course means the string itself is the key.  I.e., the translation will
+be selected based on the original string.  The message catalogs must
+therefore contain the original strings plus one translation for any such
+string.  The task of the @code{gettext} function is it to compare the
+argument string with the available strings in the catalog and return the
+appropriate translation.  Of course this process is optimized so that
+this process is not more expensive than an access using an atomic key
+like in @code{catgets}.
+
+The @code{gettext} approach has some advantages but also some
+disadvantages.  Please see the GNU @file{gettext} manual for a detailed
+discussion of the pros and cons.
+
+All the definitions and declarations for @code{gettext} can be found in
+the @file{libintl.h} header file.  On systems where these functions are
+not part of the C library they can be found in a separate library named
+@file{libintl.a} (or accordingly different for shared libraries).
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} gettext (const char *@var{msgid})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Wrapper for dcgettext.
+The @code{gettext} function searches the currently selected message
+catalogs for a string which is equal to @var{msgid}.  If there is such a
+string available it is returned.  Otherwise the argument string
+@var{msgid} is returned.
+
+Please note that although the return value is @code{char *} the
+returned string must not be changed.  This broken type results from the
+history of the function and does not reflect the way the function should
+be used.
+
+Please note that above we wrote ``message catalogs'' (plural).  This is
+a specialty of the GNU implementation of these functions and we will
+say more about this when we talk about the ways message catalogs are
+selected (@pxref{Locating gettext catalog}).
+
+The @code{gettext} function does not modify the value of the global
+@var{errno} variable.  This is necessary to make it possible to write
+something like
+
+@smallexample
+  printf (gettext ("Operation failed: %m\n"));
+@end smallexample
+
+Here the @var{errno} value is used in the @code{printf} function while
+processing the @code{%m} format element and if the @code{gettext}
+function would change this value (it is called before @code{printf} is
+called) we would get a wrong message.
+
+So there is no easy way to detect a missing message catalog beside
+comparing the argument string with the result.  But it is normally the
+task of the user to react on missing catalogs.  The program cannot guess
+when a message catalog is really necessary since for a user who speaks
+the language the program was developed in does not need any translation.
+@end deftypefun
+
+The remaining two functions to access the message catalog add some
+functionality to select a message catalog which is not the default one.
+This is important if parts of the program are developed independently.
+Every part can have its own message catalog and all of them can be used
+at the same time.  The C library itself is an example: internally it
+uses the @code{gettext} functions but since it must not depend on a
+currently selected default message catalog it must specify all ambiguous
+information.
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} dgettext (const char *@var{domainname}, const char *@var{msgid})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Wrapper for dcgettext.
+The @code{dgettext} functions acts just like the @code{gettext}
+function.  It only takes an additional first argument @var{domainname}
+which guides the selection of the message catalogs which are searched
+for the translation.  If the @var{domainname} parameter is the null
+pointer the @code{dgettext} function is exactly equivalent to
+@code{gettext} since the default value for the domain name is used.
+
+As for @code{gettext} the return value type is @code{char *} which is an
+anachronism.  The returned string must never be modified.
+@end deftypefun
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} dcgettext (const char *@var{domainname}, const char *@var{msgid}, int @var{category})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c dcgettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c  dcigettext @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c   libc_rwlock_rdlock @asulock @aculock
+@c   current_locale_name ok [protected from @mtslocale]
+@c   tfind ok
+@c   libc_rwlock_unlock ok
+@c   plural_lookup ok
+@c    plural_eval ok
+@c    rawmemchr ok
+@c   DETERMINE_SECURE ok, nothing
+@c   strcmp ok
+@c   strlen ok
+@c   getcwd @ascuheap @acsmem @acsfd
+@c   strchr ok
+@c   stpcpy ok
+@c   category_to_name ok
+@c   guess_category_value @mtsenv
+@c    getenv @mtsenv
+@c    current_locale_name dup ok [protected from @mtslocale by dcigettext]
+@c    strcmp ok
+@c   ENABLE_SECURE ok
+@c   _nl_find_domain @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c    libc_rwlock_rdlock dup @asulock @aculock
+@c    _nl_make_l10nflist dup @ascuheap @acsmem
+@c    libc_rwlock_unlock dup ok
+@c    _nl_load_domain @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c     libc_lock_lock_recursive @aculock
+@c     libc_lock_unlock_recursive @aculock
+@c     open->open_not_cancel_2 @acsfd
+@c     fstat ok
+@c     mmap dup @acsmem
+@c     close->close_not_cancel_no_status @acsfd
+@c     malloc dup @ascuheap @acsmem
+@c     read->read_not_cancel ok
+@c     munmap dup @acsmem
+@c     W dup ok
+@c     strlen dup ok
+@c     get_sysdep_segment_value ok
+@c     memcpy dup ok
+@c     hash_string dup ok
+@c     free dup @ascuheap @acsmem
+@c     libc_rwlock_init ok
+@c     _nl_find_msg dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c     libc_rwlock_fini ok
+@c     EXTRACT_PLURAL_EXPRESSION @ascuheap @acsmem
+@c      strstr dup ok
+@c      isspace ok
+@c      strtoul ok
+@c      PLURAL_PARSE @ascuheap @acsmem
+@c       malloc dup @ascuheap @acsmem
+@c       free dup @ascuheap @acsmem
+@c      INIT_GERMANIC_PLURAL ok, nothing
+@c        the pre-C99 variant is @acucorrupt [protected from @mtuinit by dcigettext]
+@c    _nl_expand_alias dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c    _nl_explode_name dup @ascuheap @acsmem
+@c    libc_rwlock_wrlock dup @asulock @aculock
+@c    free dup @asulock @aculock @acsfd @acsmem
+@c   _nl_find_msg @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c    _nl_load_domain dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c    strlen ok
+@c    hash_string ok
+@c    W ok
+@c     SWAP ok
+@c      bswap_32 ok
+@c    strcmp ok
+@c    get_output_charset @mtsenv @ascuheap @acsmem
+@c     getenv dup @mtsenv
+@c     strlen dup ok
+@c     malloc dup @ascuheap @acsmem
+@c     memcpy dup ok
+@c    libc_rwlock_rdlock dup @asulock @aculock
+@c    libc_rwlock_unlock dup ok
+@c    libc_rwlock_wrlock dup @asulock @aculock
+@c    realloc @ascuheap @acsmem
+@c    strdup @ascuheap @acsmem
+@c    strstr ok
+@c    strcspn ok
+@c    mempcpy dup ok
+@c    norm_add_slashes dup ok
+@c    gconv_open @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     [protected from @mtslocale by dcigettext locale lock]
+@c    free dup @ascuheap @acsmem
+@c    libc_lock_lock @asulock @aculock
+@c    calloc @ascuheap @acsmem
+@c    gconv dup @acucorrupt [protected from @mtsrace and @asucorrupt by lock]
+@c    libc_lock_unlock ok
+@c   malloc @ascuheap @acsmem
+@c   mempcpy ok
+@c   memcpy ok
+@c   strcpy ok
+@c   libc_rwlock_wrlock @asulock @aculock
+@c   tsearch @ascuheap @acucorrupt @acsmem [protected from @mtsrace and @asucorrupt]
+@c    transcmp ok
+@c     strmp dup ok
+@c   free @ascuheap @acsmem
+The @code{dcgettext} adds another argument to those which
+@code{dgettext} takes.  This argument @var{category} specifies the last
+piece of information needed to localize the message catalog.  I.e., the
+domain name and the locale category exactly specify which message
+catalog has to be used (relative to a given directory, see below).
+
+The @code{dgettext} function can be expressed in terms of
+@code{dcgettext} by using
+
+@smallexample
+dcgettext (domain, string, LC_MESSAGES)
+@end smallexample
+
+@noindent
+instead of
+
+@smallexample
+dgettext (domain, string)
+@end smallexample
+
+This also shows which values are expected for the third parameter.  One
+has to use the available selectors for the categories available in
+@file{locale.h}.  Normally the available values are @code{LC_CTYPE},
+@code{LC_COLLATE}, @code{LC_MESSAGES}, @code{LC_MONETARY},
+@code{LC_NUMERIC}, and @code{LC_TIME}.  Please note that @code{LC_ALL}
+must not be used and even though the names might suggest this, there is
+no relation to the environments variables of this name.
+
+The @code{dcgettext} function is only implemented for compatibility with
+other systems which have @code{gettext} functions.  There is not really
+any situation where it is necessary (or useful) to use a different value
+but @code{LC_MESSAGES} in for the @var{category} parameter.  We are
+dealing with messages here and any other choice can only be irritating.
+
+As for @code{gettext} the return value type is @code{char *} which is an
+anachronism.  The returned string must never be modified.
+@end deftypefun
+
+When using the three functions above in a program it is a frequent case
+that the @var{msgid} argument is a constant string.  So it is worth to
+optimize this case.  Thinking shortly about this one will realize that
+as long as no new message catalog is loaded the translation of a message
+will not change.  This optimization is actually implemented by the
+@code{gettext}, @code{dgettext} and @code{dcgettext} functions.
+
+
+@node Locating gettext catalog
+@subsubsection How to determine which catalog to be used
+
+The functions to retrieve the translations for a given message have a
+remarkable simple interface.  But to provide the user of the program
+still the opportunity to select exactly the translation s/he wants and
+also to provide the programmer the possibility to influence the way to
+locate the search for catalogs files there is a quite complicated
+underlying mechanism which controls all this.  The code is complicated
+the use is easy.
+
+Basically we have two different tasks to perform which can also be
+performed by the @code{catgets} functions:
+
+@enumerate
+@item
+Locate the set of message catalogs.  There are a number of files for
+different languages and which all belong to the package.  Usually they
+are all stored in the filesystem below a certain directory.
+
+There can be arbitrary many packages installed and they can follow
+different guidelines for the placement of their files.
+
+@item
+Relative to the location specified by the package the actual translation
+files must be searched, based on the wishes of the user.  I.e., for each
+language the user selects the program should be able to locate the
+appropriate file.
+@end enumerate
+
+This is the functionality required by the specifications for
+@code{gettext} and this is also what the @code{catgets} functions are
+able to do.  But there are some problems unresolved:
+
+@itemize @bullet
+@item
+The language to be used can be specified in several different ways.
+There is no generally accepted standard for this and the user always
+expects the program understand what s/he means.  E.g., to select the
+German translation one could write @code{de}, @code{german}, or
+@code{deutsch} and the program should always react the same.
+
+@item
+Sometimes the specification of the user is too detailed.  If s/he, e.g.,
+specifies @code{de_DE.ISO-8859-1} which means German, spoken in Germany,
+coded using the @w{ISO 8859-1} character set there is the possibility
+that a message catalog matching this exactly is not available.  But
+there could be a catalog matching @code{de} and if the character set
+used on the machine is always @w{ISO 8859-1} there is no reason why this
+later message catalog should not be used.  (We call this @dfn{message
+inheritance}.)
+
+@item
+If a catalog for a wanted language is not available it is not always the
+second best choice to fall back on the language of the developer and
+simply not translate any message.  Instead a user might be better able
+to read the messages in another language and so the user of the program
+should be able to define a precedence order of languages.
+@end itemize
+
+We can divide the configuration actions in two parts: the one is
+performed by the programmer, the other by the user.  We will start with
+the functions the programmer can use since the user configuration will
+be based on this.
+
+As the functions described in the last sections already mention separate
+sets of messages can be selected by a @dfn{domain name}.  This is a
+simple string which should be unique for each program part with uses a
+separate domain.  It is possible to use in one program arbitrary many
+domains at the same time.  E.g., @theglibc{} itself uses a domain
+named @code{libc} while the program using the C Library could use a
+domain named @code{foo}.  The important point is that at any time
+exactly one domain is active.  This is controlled with the following
+function.
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} textdomain (const char *@var{domainname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c textdomain @asulock @ascuheap @aculock @acsmem
+@c  libc_rwlock_wrlock @asulock @aculock
+@c  strcmp ok
+@c  strdup @ascuheap @acsmem
+@c  free @ascuheap @acsmem
+@c  libc_rwlock_unlock ok
+The @code{textdomain} function sets the default domain, which is used in
+all future @code{gettext} calls, to @var{domainname}.  Please note that
+@code{dgettext} and @code{dcgettext} calls are not influenced if the
+@var{domainname} parameter of these functions is not the null pointer.
+
+Before the first call to @code{textdomain} the default domain is
+@code{messages}.  This is the name specified in the specification of
+the @code{gettext} API.  This name is as good as any other name.  No
+program should ever really use a domain with this name since this can
+only lead to problems.
+
+The function returns the value which is from now on taken as the default
+domain.  If the system went out of memory the returned value is
+@code{NULL} and the global variable @var{errno} is set to @code{ENOMEM}.
+Despite the return value type being @code{char *} the return string must
+not be changed.  It is allocated internally by the @code{textdomain}
+function.
+
+If the @var{domainname} parameter is the null pointer no new default
+domain is set.  Instead the currently selected default domain is
+returned.
+
+If the @var{domainname} parameter is the empty string the default domain
+is reset to its initial value, the domain with the name @code{messages}.
+This possibility is questionable to use since the domain @code{messages}
+really never should be used.
+@end deftypefun
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} bindtextdomain (const char *@var{domainname}, const char *@var{dirname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c bindtextdomain @ascuheap @acsmem
+@c  set_binding_values @ascuheap @acsmem
+@c   libc_rwlock_wrlock dup @asulock @aculock
+@c   strcmp dup ok
+@c   strdup dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c   malloc dup @ascuheap @acsmem
+The @code{bindtextdomain} function can be used to specify the directory
+which contains the message catalogs for domain @var{domainname} for the
+different languages.  To be correct, this is the directory where the
+hierarchy of directories is expected.  Details are explained below.
+
+For the programmer it is important to note that the translations which
+come with the program have be placed in a directory hierarchy starting
+at, say, @file{/foo/bar}.  Then the program should make a
+@code{bindtextdomain} call to bind the domain for the current program to
+this directory.  So it is made sure the catalogs are found.  A correctly
+running program does not depend on the user setting an environment
+variable.
+
+The @code{bindtextdomain} function can be used several times and if the
+@var{domainname} argument is different the previously bound domains
+will not be overwritten.
+
+If the program which wish to use @code{bindtextdomain} at some point of
+time use the @code{chdir} function to change the current working
+directory it is important that the @var{dirname} strings ought to be an
+absolute pathname.  Otherwise the addressed directory might vary with
+the time.
+
+If the @var{dirname} parameter is the null pointer @code{bindtextdomain}
+returns the currently selected directory for the domain with the name
+@var{domainname}.
+
+The @code{bindtextdomain} function returns a pointer to a string
+containing the name of the selected directory name.  The string is
+allocated internally in the function and must not be changed by the
+user.  If the system went out of core during the execution of
+@code{bindtextdomain} the return value is @code{NULL} and the global
+variable @var{errno} is set accordingly.
+@end deftypefun
+
+
+@node Advanced gettext functions
+@subsubsection Additional functions for more complicated situations
+
+The functions of the @code{gettext} family described so far (and all the
+@code{catgets} functions as well) have one problem in the real world
+which have been neglected completely in all existing approaches.  What
+is meant here is the handling of plural forms.
+
+Looking through Unix source code before the time anybody thought about
+internationalization (and, sadly, even afterwards) one can often find
+code similar to the following:
+
+@smallexample
+   printf ("%d file%s deleted", n, n == 1 ? "" : "s");
+@end smallexample
+
+@noindent
+After the first complaints from people internationalizing the code people
+either completely avoided formulations like this or used strings like
+@code{"file(s)"}.  Both look unnatural and should be avoided.  First
+tries to solve the problem correctly looked like this:
+
+@smallexample
+   if (n == 1)
+     printf ("%d file deleted", n);
+   else
+     printf ("%d files deleted", n);
+@end smallexample
+
+But this does not solve the problem.  It helps languages where the
+plural form of a noun is not simply constructed by adding an `s' but
+that is all.  Once again people fell into the trap of believing the
+rules their language is using are universal.  But the handling of plural
+forms differs widely between the language families.  There are two
+things we can differ between (and even inside language families);
+
+@itemize @bullet
+@item
+The form how plural forms are build differs.  This is a problem with
+language which have many irregularities.  German, for instance, is a
+drastic case.  Though English and German are part of the same language
+family (Germanic), the almost regular forming of plural noun forms
+(appending an `s') is hardly found in German.
+
+@item
+The number of plural forms differ.  This is somewhat surprising for
+those who only have experiences with Romanic and Germanic languages
+since here the number is the same (there are two).
+
+But other language families have only one form or many forms.  More
+information on this in an extra section.
+@end itemize
+
+The consequence of this is that application writers should not try to
+solve the problem in their code.  This would be localization since it is
+only usable for certain, hardcoded language environments.  Instead the
+extended @code{gettext} interface should be used.
+
+These extra functions are taking instead of the one key string two
+strings and a numerical argument.  The idea behind this is that using
+the numerical argument and the first string as a key, the implementation
+can select using rules specified by the translator the right plural
+form.  The two string arguments then will be used to provide a return
+value in case no message catalog is found (similar to the normal
+@code{gettext} behavior).  In this case the rules for Germanic language
+is used and it is assumed that the first string argument is the singular
+form, the second the plural form.
+
+This has the consequence that programs without language catalogs can
+display the correct strings only if the program itself is written using
+a Germanic language.  This is a limitation but since @theglibc{}
+(as well as the GNU @code{gettext} package) are written as part of the
+GNU package and the coding standards for the GNU project require program
+being written in English, this solution nevertheless fulfills its
+purpose.
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Wrapper for dcngettext.
+The @code{ngettext} function is similar to the @code{gettext} function
+as it finds the message catalogs in the same way.  But it takes two
+extra arguments.  The @var{msgid1} parameter must contain the singular
+form of the string to be converted.  It is also used as the key for the
+search in the catalog.  The @var{msgid2} parameter is the plural form.
+The parameter @var{n} is used to determine the plural form.  If no
+message catalog is found @var{msgid1} is returned if @code{n == 1},
+otherwise @code{msgid2}.
+
+An example for the us of this function is:
+
+@smallexample
+  printf (ngettext ("%d file removed", "%d files removed", n), n);
+@end smallexample
+
+Please note that the numeric value @var{n} has to be passed to the
+@code{printf} function as well.  It is not sufficient to pass it only to
+@code{ngettext}.
+@end deftypefun
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} dngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Wrapper for dcngettext.
+The @code{dngettext} is similar to the @code{dgettext} function in the
+way the message catalog is selected.  The difference is that it takes
+two extra parameter to provide the correct plural form.  These two
+parameters are handled in the same way @code{ngettext} handles them.
+@end deftypefun
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} dcngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}, int @var{category})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Wrapper for dcigettext.
+The @code{dcngettext} is similar to the @code{dcgettext} function in the
+way the message catalog is selected.  The difference is that it takes
+two extra parameter to provide the correct plural form.  These two
+parameters are handled in the same way @code{ngettext} handles them.
+@end deftypefun
+
+@subsubheading The problem of plural forms
+
+A description of the problem can be found at the beginning of the last
+section.  Now there is the question how to solve it.  Without the input
+of linguists (which was not available) it was not possible to determine
+whether there are only a few different forms in which plural forms are
+formed or whether the number can increase with every new supported
+language.
+
+Therefore the solution implemented is to allow the translator to specify
+the rules of how to select the plural form.  Since the formula varies
+with every language this is the only viable solution except for
+hardcoding the information in the code (which still would require the
+possibility of extensions to not prevent the use of new languages).  The
+details are explained in the GNU @code{gettext} manual.  Here only a
+bit of information is provided.
+
+The information about the plural form selection has to be stored in the
+header entry (the one with the empty (@code{msgid} string).  It looks
+like this:
+
+@smallexample
+Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
+@end smallexample
+
+The @code{nplurals} value must be a decimal number which specifies how
+many different plural forms exist for this language.  The string
+following @code{plural} is an expression which is using the C language
+syntax.  Exceptions are that no negative number are allowed, numbers
+must be decimal, and the only variable allowed is @code{n}.  This
+expression will be evaluated whenever one of the functions
+@code{ngettext}, @code{dngettext}, or @code{dcngettext} is called.  The
+numeric value passed to these functions is then substituted for all uses
+of the variable @code{n} in the expression.  The resulting value then
+must be greater or equal to zero and smaller than the value given as the
+value of @code{nplurals}.
+
+@noindent
+The following rules are known at this point.  The language with families
+are listed.  But this does not necessarily mean the information can be
+generalized for the whole family (as can be easily seen in the table
+below).@footnote{Additions are welcome.  Send appropriate information to
+@email{bug-glibc-manual@@gnu.org}.}
+
+@table @asis
+@item Only one form:
+Some languages only require one single form.  There is no distinction
+between the singular and plural form.  An appropriate header entry
+would look like this:
+
+@smallexample
+Plural-Forms: nplurals=1; plural=0;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Finno-Ugric family
+Hungarian
+@item Asian family
+Japanese, Korean
+@item Turkic/Altaic family
+Turkish
+@end table
+
+@item Two forms, singular used for one only
+This is the form used in most existing programs since it is what English
+is using.  A header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=2; plural=n != 1;
+@end smallexample
+
+(Note: this uses the feature of C expressions that boolean expressions
+have to value zero or one.)
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Germanic family
+Danish, Dutch, English, German, Norwegian, Swedish
+@item Finno-Ugric family
+Estonian, Finnish
+@item Latin/Greek family
+Greek
+@item Semitic family
+Hebrew
+@item Romance family
+Italian, Portuguese, Spanish
+@item Artificial
+Esperanto
+@end table
+
+@item Two forms, singular used for zero and one
+Exceptional case in the language family.  The header entry would be:
+
+@smallexample
+Plural-Forms: nplurals=2; plural=n>1;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Romanic family
+French, Brazilian Portuguese
+@end table
+
+@item Three forms, special case for zero
+The header entry would be:
+
+@smallexample
+Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Baltic family
+Latvian
+@end table
+
+@item Three forms, special cases for one and two
+The header entry would be:
+
+@smallexample
+Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Celtic
+Gaeilge (Irish)
+@end table
+
+@item Three forms, special case for numbers ending in 1[2-9]
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=3; \
+    plural=n%10==1 && n%100!=11 ? 0 : \
+           n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Baltic family
+Lithuanian
+@end table
+
+@item Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=3; \
+    plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Slavic family
+Croatian, Czech, Russian, Ukrainian
+@end table
+
+@item Three forms, special cases for 1 and 2, 3, 4
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=3; \
+    plural=(n==1) ? 1 : (n>=2 && n<=4) ? 2 : 0;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Slavic family
+Slovak
+@end table
+
+@item Three forms, special case for one and some numbers ending in 2, 3, or 4
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=3; \
+    plural=n==1 ? 0 : \
+           n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Slavic family
+Polish
+@end table
+
+@item Four forms, special case for one and all numbers ending in 02, 03, or 04
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=4; \
+    plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Slavic family
+Slovenian
+@end table
+@end table
+
+
+@node Charset conversion in gettext
+@subsubsection How to specify the output character set @code{gettext} uses
+
+@code{gettext} not only looks up a translation in a message catalog.  It
+also converts the translation on the fly to the desired output character
+set.  This is useful if the user is working in a different character set
+than the translator who created the message catalog, because it avoids
+distributing variants of message catalogs which differ only in the
+character set.
+
+The output character set is, by default, the value of @code{nl_langinfo
+(CODESET)}, which depends on the @code{LC_CTYPE} part of the current
+locale.  But programs which store strings in a locale independent way
+(e.g. UTF-8) can request that @code{gettext} and related functions
+return the translations in that encoding, by use of the
+@code{bind_textdomain_codeset} function.
+
+Note that the @var{msgid} argument to @code{gettext} is not subject to
+character set conversion.  Also, when @code{gettext} does not find a
+translation for @var{msgid}, it returns @var{msgid} unchanged --
+independently of the current output character set.  It is therefore
+recommended that all @var{msgid}s be US-ASCII strings.
+
+@comment libintl.h
+@comment GNU
+@deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c bind_textdomain_codeset @ascuheap @acsmem
+@c  set_binding_values dup @ascuheap @acsmem
+The @code{bind_textdomain_codeset} function can be used to specify the
+output character set for message catalogs for domain @var{domainname}.
+The @var{codeset} argument must be a valid codeset name which can be used
+for the @code{iconv_open} function, or a null pointer.
+
+If the @var{codeset} parameter is the null pointer,
+@code{bind_textdomain_codeset} returns the currently selected codeset
+for the domain with the name @var{domainname}.  It returns @code{NULL} if
+no codeset has yet been selected.
+
+The @code{bind_textdomain_codeset} function can be used several times.
+If used multiple times with the same @var{domainname} argument, the
+later call overrides the settings made by the earlier one.
+
+The @code{bind_textdomain_codeset} function returns a pointer to a
+string containing the name of the selected codeset.  The string is
+allocated internally in the function and must not be changed by the
+user.  If the system went out of core during the execution of
+@code{bind_textdomain_codeset}, the return value is @code{NULL} and the
+global variable @var{errno} is set accordingly.
+@end deftypefun
+
+
+@node GUI program problems
+@subsubsection How to use @code{gettext} in GUI programs
+
+One place where the @code{gettext} functions, if used normally, have big
+problems is within programs with graphical user interfaces (GUIs).  The
+problem is that many of the strings which have to be translated are very
+short.  They have to appear in pull-down menus which restricts the
+length.  But strings which are not containing entire sentences or at
+least large fragments of a sentence may appear in more than one
+situation in the program but might have different translations.  This is
+especially true for the one-word strings which are frequently used in
+GUI programs.
+
+As a consequence many people say that the @code{gettext} approach is
+wrong and instead @code{catgets} should be used which indeed does not
+have this problem.  But there is a very simple and powerful method to
+handle these kind of problems with the @code{gettext} functions.
+
+@noindent
+As an example consider the following fictional situation.  A GUI program
+has a menu bar with the following entries:
+
+@smallexample
++------------+------------+--------------------------------------+
+| File       | Printer    |                                      |
++------------+------------+--------------------------------------+
+| Open     | | Select   |
+| New      | | Open     |
++----------+ | Connect  |
+             +----------+
+@end smallexample
+
+To have the strings @code{File}, @code{Printer}, @code{Open},
+@code{New}, @code{Select}, and @code{Connect} translated there has to be
+at some point in the code a call to a function of the @code{gettext}
+family.  But in two places the string passed into the function would be
+@code{Open}.  The translations might not be the same and therefore we
+are in the dilemma described above.
+
+One solution to this problem is to artificially enlengthen the strings
+to make them unambiguous.  But what would the program do if no
+translation is available?  The enlengthened string is not what should be
+printed.  So we should use a little bit modified version of the functions.
+
+To enlengthen the strings a uniform method should be used.  E.g., in the
+example above the strings could be chosen as
+
+@smallexample
+Menu|File
+Menu|Printer
+Menu|File|Open
+Menu|File|New
+Menu|Printer|Select
+Menu|Printer|Open
+Menu|Printer|Connect
+@end smallexample
+
+Now all the strings are different and if now instead of @code{gettext}
+the following little wrapper function is used, everything works just
+fine:
+
+@cindex sgettext
+@smallexample
+  char *
+  sgettext (const char *msgid)
+  @{
+    char *msgval = gettext (msgid);
+    if (msgval == msgid)
+      msgval = strrchr (msgid, '|') + 1;
+    return msgval;
+  @}
+@end smallexample
+
+What this little function does is to recognize the case when no
+translation is available.  This can be done very efficiently by a
+pointer comparison since the return value is the input value.  If there
+is no translation we know that the input string is in the format we used
+for the Menu entries and therefore contains a @code{|} character.  We
+simply search for the last occurrence of this character and return a
+pointer to the character following it.  That's it!
+
+If one now consistently uses the enlengthened string form and replaces
+the @code{gettext} calls with calls to @code{sgettext} (this is normally
+limited to very few places in the GUI implementation) then it is
+possible to produce a program which can be internationalized.
+
+With advanced compilers (such as GNU C) one can write the
+@code{sgettext} functions as an inline function or as a macro like this:
+
+@cindex sgettext
+@smallexample
+#define sgettext(msgid) \
+  (@{ const char *__msgid = (msgid);            \
+     char *__msgstr = gettext (__msgid);       \
+     if (__msgval == __msgid)                  \
+       __msgval = strrchr (__msgid, '|') + 1;  \
+     __msgval; @})
+@end smallexample
+
+The other @code{gettext} functions (@code{dgettext}, @code{dcgettext}
+and the @code{ngettext} equivalents) can and should have corresponding
+functions as well which look almost identical, except for the parameters
+and the call to the underlying function.
+
+Now there is of course the question why such functions do not exist in
+@theglibc{}?  There are two parts of the answer to this question.
+
+@itemize @bullet
+@item
+They are easy to write and therefore can be provided by the project they
+are used in.  This is not an answer by itself and must be seen together
+with the second part which is:
+
+@item
+There is no way the C library can contain a version which can work
+everywhere.  The problem is the selection of the character to separate
+the prefix from the actual string in the enlenghtened string.  The
+examples above used @code{|} which is a quite good choice because it
+resembles a notation frequently used in this context and it also is a
+character not often used in message strings.
+
+But what if the character is used in message strings.  Or if the chose
+character is not available in the character set on the machine one
+compiles (e.g., @code{|} is not required to exist for @w{ISO C}; this is
+why the @file{iso646.h} file exists in @w{ISO C} programming environments).
+@end itemize
+
+There is only one more comment to make left.  The wrapper function above
+require that the translations strings are not enlengthened themselves.
+This is only logical.  There is no need to disambiguate the strings
+(since they are never used as keys for a search) and one also saves
+quite some memory and disk space by doing this.
+
+
+@node Using gettextized software
+@subsubsection User influence on @code{gettext}
+
+The last sections described what the programmer can do to
+internationalize the messages of the program.  But it is finally up to
+the user to select the message s/he wants to see.  S/He must understand
+them.
+
+The POSIX locale model uses the environment variables @code{LC_COLLATE},
+@code{LC_CTYPE}, @code{LC_MESSAGES}, @code{LC_MONETARY}, @code{LC_NUMERIC},
+and @code{LC_TIME} to select the locale which is to be used.  This way
+the user can influence lots of functions.  As we mentioned above the
+@code{gettext} functions also take advantage of this.
+
+To understand how this happens it is necessary to take a look at the
+various components of the filename which gets computed to locate a
+message catalog.  It is composed as follows:
+
+@smallexample
+@var{dir_name}/@var{locale}/LC_@var{category}/@var{domain_name}.mo
+@end smallexample
+
+The default value for @var{dir_name} is system specific.  It is computed
+from the value given as the prefix while configuring the C library.
+This value normally is @file{/usr} or @file{/}.  For the former the
+complete @var{dir_name} is:
+
+@smallexample
+/usr/share/locale
+@end smallexample
+
+We can use @file{/usr/share} since the @file{.mo} files containing the
+message catalogs are system independent, so all systems can use the same
+files.  If the program executed the @code{bindtextdomain} function for
+the message domain that is currently handled, the @code{dir_name}
+component is exactly the value which was given to the function as
+the second parameter.  I.e., @code{bindtextdomain} allows overwriting
+the only system dependent and fixed value to make it possible to
+address files anywhere in the filesystem.
+
+The @var{category} is the name of the locale category which was selected
+in the program code.  For @code{gettext} and @code{dgettext} this is
+always @code{LC_MESSAGES}, for @code{dcgettext} this is selected by the
+value of the third parameter.  As said above it should be avoided to
+ever use a category other than @code{LC_MESSAGES}.
+
+The @var{locale} component is computed based on the category used.  Just
+like for the @code{setlocale} function here comes the user selection
+into the play.  Some environment variables are examined in a fixed order
+and the first environment variable set determines the return value of
+the lookup process.  In detail, for the category @code{LC_xxx} the
+following variables in this order are examined:
+
+@table @code
+@item LANGUAGE
+@item LC_ALL
+@item LC_xxx
+@item LANG
+@end table
+
+This looks very familiar.  With the exception of the @code{LANGUAGE}
+environment variable this is exactly the lookup order the
+@code{setlocale} function uses.  But why introducing the @code{LANGUAGE}
+variable?
+
+The reason is that the syntax of the values these variables can have is
+different to what is expected by the @code{setlocale} function.  If we
+would set @code{LC_ALL} to a value following the extended syntax that
+would mean the @code{setlocale} function will never be able to use the
+value of this variable as well.  An additional variable removes this
+problem plus we can select the language independently of the locale
+setting which sometimes is useful.
+
+While for the @code{LC_xxx} variables the value should consist of
+exactly one specification of a locale the @code{LANGUAGE} variable's
+value can consist of a colon separated list of locale names.  The
+attentive reader will realize that this is the way we manage to
+implement one of our additional demands above: we want to be able to
+specify an ordered list of language.
+
+Back to the constructed filename we have only one component missing.
+The @var{domain_name} part is the name which was either registered using
+the @code{textdomain} function or which was given to @code{dgettext} or
+@code{dcgettext} as the first parameter.  Now it becomes obvious that a
+good choice for the domain name in the program code is a string which is
+closely related to the program/package name.  E.g., for @theglibc{}
+the domain name is @code{libc}.
+
+@noindent
+A limit piece of example code should show how the programmer is supposed
+to work:
+
+@smallexample
+@{
+  setlocale (LC_ALL, "");
+  textdomain ("test-package");
+  bindtextdomain ("test-package", "/usr/local/share/locale");
+  puts (gettext ("Hello, world!"));
+@}
+@end smallexample
+
+At the program start the default domain is @code{messages}, and the
+default locale is "C".  The @code{setlocale} call sets the locale
+according to the user's environment variables; remember that correct
+functioning of @code{gettext} relies on the correct setting of the
+@code{LC_MESSAGES} locale (for looking up the message catalog) and
+of the @code{LC_CTYPE} locale (for the character set conversion).
+The @code{textdomain} call changes the default domain to
+@code{test-package}.  The @code{bindtextdomain} call specifies that
+the message catalogs for the domain @code{test-package} can be found
+below the directory @file{/usr/local/share/locale}.
+
+If now the user set in her/his environment the variable @code{LANGUAGE}
+to @code{de} the @code{gettext} function will try to use the
+translations from the file
+
+@smallexample
+/usr/local/share/locale/de/LC_MESSAGES/test-package.mo
+@end smallexample
+
+From the above descriptions it should be clear which component of this
+filename is determined by which source.
+
+In the above example we assumed that the @code{LANGUAGE} environment
+variable to @code{de}.  This might be an appropriate selection but what
+happens if the user wants to use @code{LC_ALL} because of the wider
+usability and here the required value is @code{de_DE.ISO-8859-1}?  We
+already mentioned above that a situation like this is not infrequent.
+E.g., a person might prefer reading a dialect and if this is not
+available fall back on the standard language.
+
+The @code{gettext} functions know about situations like this and can
+handle them gracefully.  The functions recognize the format of the value
+of the environment variable.  It can split the value is different pieces
+and by leaving out the only or the other part it can construct new
+values.  This happens of course in a predictable way.  To understand
+this one must know the format of the environment variable value.  There
+is one more or less standardized form, originally from the X/Open
+specification:
+
+@code{language[_territory[.codeset]][@@modifier]}
+
+Less specific locale names will be stripped of in the order of the
+following list:
+
+@enumerate
+@item
+@code{codeset}
+@item
+@code{normalized codeset}
+@item
+@code{territory}
+@item
+@code{modifier}
+@end enumerate
+
+The @code{language} field will never be dropped for obvious reasons.
+
+The only new thing is the @code{normalized codeset} entry.  This is
+another goodie which is introduced to help reducing the chaos which
+derives from the inability of the people to standardize the names of
+character sets.  Instead of @w{ISO-8859-1} one can often see @w{8859-1},
+@w{88591}, @w{iso8859-1}, or @w{iso_8859-1}.  The @code{normalized
+codeset} value is generated from the user-provided character set name by
+applying the following rules:
+
+@enumerate
+@item
+Remove all characters beside numbers and letters.
+@item
+Fold letters to lowercase.
+@item
+If the same only contains digits prepend the string @code{"iso"}.
+@end enumerate
+
+@noindent
+So all of the above name will be normalized to @code{iso88591}.  This
+allows the program user much more freely choosing the locale name.
+
+Even this extended functionality still does not help to solve the
+problem that completely different names can be used to denote the same
+locale (e.g., @code{de} and @code{german}).  To be of help in this
+situation the locale implementation and also the @code{gettext}
+functions know about aliases.
+
+The file @file{/usr/share/locale/locale.alias} (replace @file{/usr} with
+whatever prefix you used for configuring the C library) contains a
+mapping of alternative names to more regular names.  The system manager
+is free to add new entries to fill her/his own needs.  The selected
+locale from the environment is compared with the entries in the first
+column of this file ignoring the case.  If they match the value of the
+second column is used instead for the further handling.
+
+In the description of the format of the environment variables we already
+mentioned the character set as a factor in the selection of the message
+catalog.  In fact, only catalogs which contain text written using the
+character set of the system/program can be used (directly; there will
+come a solution for this some day).  This means for the user that s/he
+will always have to take care for this.  If in the collection of the
+message catalogs there are files for the same language but coded using
+different character sets the user has to be careful.
+
+
+@node Helper programs for gettext
+@subsection Programs to handle message catalogs for @code{gettext}
+
+@Theglibc{} does not contain the source code for the programs to
+handle message catalogs for the @code{gettext} functions.  As part of
+the GNU project the GNU gettext package contains everything the
+developer needs.  The functionality provided by the tools in this
+package by far exceeds the abilities of the @code{gencat} program
+described above for the @code{catgets} functions.
+
+There is a program @code{msgfmt} which is the equivalent program to the
+@code{gencat} program.  It generates from the human-readable and
+-editable form of the message catalog a binary file which can be used by
+the @code{gettext} functions.  But there are several more programs
+available.
+
+The @code{xgettext} program can be used to automatically extract the
+translatable messages from a source file.  I.e., the programmer need not
+take care of the translations and the list of messages which have to be
+translated.  S/He will simply wrap the translatable string in calls to
+@code{gettext} et.al and the rest will be done by @code{xgettext}.  This
+program has a lot of options which help to customize the output or
+help to understand the input better.
+
+Other programs help to manage the development cycle when new messages appear
+in the source files or when a new translation of the messages appears.
+Here it should only be noted that using all the tools in GNU gettext it
+is possible to @emph{completely} automate the handling of message
+catalogs.  Beside marking the translatable strings in the source code and
+generating the translations the developers do not have anything to do
+themselves.
diff --git a/ap/libc/glibc/glibc-2.23/manual/nss.texi b/ap/libc/glibc/glibc-2.23/manual/nss.texi
new file mode 100644
index 0000000..66dccef
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/nss.texi
@@ -0,0 +1,675 @@
+@node Name Service Switch, Users and Groups, Job Control, Top
+@chapter System Databases and Name Service Switch
+@c %MENU% Accessing system databases
+@cindex Name Service Switch
+@cindex NSS
+@cindex databases
+
+Various functions in the C Library need to be configured to work
+correctly in the local environment.  Traditionally, this was done by
+using files (e.g., @file{/etc/passwd}), but other nameservices (like the
+Network Information Service (NIS) and the Domain Name Service (DNS))
+became popular, and were hacked into the C library, usually with a fixed
+search order.
+
+@Theglibc{} contains a cleaner solution of this problem.  It is
+designed after a method used by Sun Microsystems in the C library of
+@w{Solaris 2}.  @Theglibc{} follows their name and calls this
+scheme @dfn{Name Service Switch} (NSS).
+
+Though the interface might be similar to Sun's version there is no
+common code.  We never saw any source code of Sun's implementation and
+so the internal interface is incompatible.  This also manifests in the
+file names we use as we will see later.
+
+
+@menu
+* NSS Basics::                  What is this NSS good for.
+* NSS Configuration File::      Configuring NSS.
+* NSS Module Internals::        How does it work internally.
+* Extending NSS::               What to do to add services or databases.
+@end menu
+
+@node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
+@section NSS Basics
+
+The basic idea is to put the implementation of the different services
+offered to access the databases in separate modules.  This has some
+advantages:
+
+@enumerate
+@item
+Contributors can add new services without adding them to @theglibc{}.
+@item
+The modules can be updated separately.
+@item
+The C library image is smaller.
+@end enumerate
+
+To fulfill the first goal above the ABI of the modules will be described
+below.  For getting the implementation of a new service right it is
+important to understand how the functions in the modules get called.
+They are in no way designed to be used by the programmer directly.
+Instead the programmer should only use the documented and standardized
+functions to access the databases.
+
+@noindent
+The databases available in the NSS are
+
+@cindex ethers
+@cindex group
+@cindex hosts
+@cindex netgroup
+@cindex networks
+@cindex protocols
+@cindex passwd
+@cindex rpc
+@cindex services
+@cindex shadow
+@vtable @code
+@item aliases
+Mail aliases
+@comment @pxref{Mail Aliases}.
+@item ethers
+Ethernet numbers,
+@comment @pxref{Ethernet Numbers}.
+@item group
+Groups of users, @pxref{Group Database}.
+@item hosts
+Host names and numbers, @pxref{Host Names}.
+@item netgroup
+Network wide list of host and users, @pxref{Netgroup Database}.
+@item networks
+Network names and numbers, @pxref{Networks Database}.
+@item protocols
+Network protocols, @pxref{Protocols Database}.
+@item passwd
+User passwords, @pxref{User Database}.
+@item rpc
+Remote procedure call names and numbers,
+@comment @pxref{RPC Database}.
+@item services
+Network services, @pxref{Services Database}.
+@item shadow
+Shadow user passwords,
+@comment @pxref{Shadow Password Database}.
+@end vtable
+
+@noindent
+There will be some more added later (@code{automount}, @code{bootparams},
+@code{netmasks}, and @code{publickey}).
+
+@node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
+@section The NSS Configuration File
+
+@cindex @file{/etc/nsswitch.conf}
+@cindex @file{nsswitch.conf}
+Somehow the NSS code must be told about the wishes of the user.  For
+this reason there is the file @file{/etc/nsswitch.conf}.  For each
+database this file contain a specification how the lookup process should
+work.  The file could look like this:
+
+@example
+@include nsswitch.texi
+@end example
+
+The first column is the database as you can guess from the table above.
+The rest of the line specifies how the lookup process works.  Please
+note that you specify the way it works for each database individually.
+This cannot be done with the old way of a monolithic implementation.
+
+The configuration specification for each database can contain two
+different items:
+
+@itemize @bullet
+@item
+the service specification like @code{files}, @code{db}, or @code{nis}.
+@item
+the reaction on lookup result like @code{[NOTFOUND=return]}.
+@end itemize
+
+@menu
+* 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.
+@end menu
+
+@node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File
+@subsection Services in the NSS configuration File
+
+The above example file mentions five different services: @code{files},
+@code{db}, @code{dns}, @code{nis}, and @code{nisplus}.  This does not
+mean these
+services are available on all sites and it does also not mean these are
+all the services which will ever be available.
+
+In fact, these names are simply strings which the NSS code uses to find
+the implicitly addressed functions.  The internal interface will be
+described later.  Visible to the user are the modules which implement an
+individual service.
+
+Assume the service @var{name} shall be used for a lookup.  The code for
+this service is implemented in a module called @file{libnss_@var{name}}.
+On a system supporting shared libraries this is in fact a shared library
+with the name (for example) @file{libnss_@var{name}.so.2}.  The number
+at the end is the currently used version of the interface which will not
+change frequently.  Normally the user should not have to be cognizant of
+these files since they should be placed in a directory where they are
+found automatically.  Only the names of all available services are
+important.
+
+@node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
+@subsection Actions in the NSS configuration
+
+The second item in the specification gives the user much finer control
+on the lookup process.  Action items are placed between two service
+names and are written within brackets.  The general form is
+
+@display
+@code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
+@end display
+
+@noindent
+where
+
+@smallexample
+@var{status} @result{} success | notfound | unavail | tryagain
+@var{action} @result{} return | continue
+@end smallexample
+
+The case of the keywords is insignificant.  The @var{status}
+values are the results of a call to a lookup function of a specific
+service.  They mean
+
+@ftable @samp
+@item success
+No error occurred and the wanted entry is returned.  The default action
+for this is @code{return}.
+
+@item notfound
+The lookup process works ok but the needed value was not found.  The
+default action is @code{continue}.
+
+@item unavail
+@cindex DNS server unavailable
+The service is permanently unavailable.  This can either mean the needed
+file is not available, or, for DNS, the server is not available or does
+not allow queries.  The default action is @code{continue}.
+
+@item tryagain
+The service is temporarily unavailable.  This could mean a file is
+locked or a server currently cannot accept more connections.  The
+default action is @code{continue}.
+@end ftable
+
+@noindent
+If we have a line like
+
+@smallexample
+ethers: nisplus [NOTFOUND=return] db files
+@end smallexample
+
+@noindent
+this is equivalent to
+
+@smallexample
+ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
+                 TRYAGAIN=continue]
+        db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
+                 TRYAGAIN=continue]
+        files
+@end smallexample
+
+@noindent
+(except that it would have to be written on one line).  The default
+value for the actions are normally what you want, and only need to be
+changed in exceptional cases.
+
+If the optional @code{!} is placed before the @var{status} this means
+the following action is used for all statuses but @var{status} itself.
+I.e., @code{!} is negation as in the C language (and others).
+
+Before we explain the exception which makes this action item necessary
+one more remark: obviously it makes no sense to add another action
+item after the @code{files} service.  Since there is no other service
+following the action @emph{always} is @code{return}.
+
+@cindex nisplus, and completeness
+Now, why is this @code{[NOTFOUND=return]} action useful?  To understand
+this we should know that the @code{nisplus} service is often
+complete; i.e., if an entry is not available in the NIS+ tables it is
+not available anywhere else.  This is what is expressed by this action
+item: it is useless to examine further services since they will not give
+us a result.
+
+@cindex nisplus, and booting
+@cindex bootstrapping, and services
+The situation would be different if the NIS+ service is not available
+because the machine is booting.  In this case the return value of the
+lookup function is not @code{notfound} but instead @code{unavail}.  And
+as you can see in the complete form above: in this situation the
+@code{db} and @code{files} services are used.  Neat, isn't it?  The
+system administrator need not pay special care for the time the system
+is not completely ready to work (while booting or shutdown or
+network problems).
+
+
+@node Notes on NSS Configuration File,  , Actions in the NSS configuration, NSS Configuration File
+@subsection Notes on the NSS Configuration File
+
+Finally a few more hints.  The NSS implementation is not completely
+helpless if @file{/etc/nsswitch.conf} does not exist.  For
+all supported databases there is a default value so it should normally
+be possible to get the system running even if the file is corrupted or
+missing.
+
+@cindex default value, and NSS
+For the @code{hosts} and @code{networks} databases the default value is
+@code{dns [!UNAVAIL=return] files}.  I.e., the system is prepared for
+the DNS service not to be available but if it is available the answer it
+returns is definitive.
+
+The @code{passwd}, @code{group}, and @code{shadow} databases are
+traditionally handled in a special way.  The appropriate files in the
+@file{/etc} directory are read but if an entry with a name starting
+with a @code{+} character is found NIS is used.  This kind of lookup
+remains possible by using the special lookup service @code{compat}
+and the default value for the three databases above is
+@code{compat [NOTFOUND=return] files}.
+
+For all other databases the default value is
+@code{nis [NOTFOUND=return] files}.  This solution give the best
+chance to be correct since NIS and file based lookup is used.
+
+@cindex optimizing NSS
+A second point is that the user should try to optimize the lookup
+process.  The different service have different response times.
+A simple file look up on a local file could be fast, but if the file
+is long and the needed entry is near the end of the file this may take
+quite some time.  In this case it might be better to use the @code{db}
+service which allows fast local access to large data sets.
+
+Often the situation is that some global information like NIS must be
+used.  So it is unavoidable to use service entries like @code{nis} etc.
+But one should avoid slow services like this if possible.
+
+
+@node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
+@section NSS Module Internals
+
+Now it is time to describe what the modules look like.  The functions
+contained in a module are identified by their names.  I.e., there is no
+jump table or the like.  How this is done is of no interest here; those
+interested in this topic should read about Dynamic Linking.
+@comment @ref{Dynamic Linking}.
+
+
+@menu
+* NSS Module Names::            Construction of the interface function of
+                                the NSS modules.
+* NSS Modules Interface::       Programming interface in the NSS module
+                                functions.
+@end menu
+
+@node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
+@subsection The Naming Scheme of the NSS Modules
+
+@noindent
+The name of each function consist of various parts:
+
+@quotation
+       _nss_@var{service}_@var{function}
+@end quotation
+
+@var{service} of course corresponds to the name of the module this
+function is found in.@footnote{Now you might ask why this information is
+duplicated.  The answer is that we want to make it possible to link
+directly with these shared objects.}  The @var{function} part is derived
+from the interface function in the C library itself.  If the user calls
+the function @code{gethostbyname} and the service used is @code{files}
+the function
+
+@smallexample
+       _nss_files_gethostbyname_r
+@end smallexample
+
+@noindent
+in the module
+
+@smallexample
+       libnss_files.so.2
+@end smallexample
+
+@noindent
+@cindex reentrant NSS functions
+is used.  You see, what is explained above in not the whole truth.  In
+fact the NSS modules only contain reentrant versions of the lookup
+functions.  I.e., if the user would call the @code{gethostbyname_r}
+function this also would end in the above function.  For all user
+interface functions the C library maps this call to a call to the
+reentrant function.  For reentrant functions this is trivial since the
+interface is (nearly) the same.  For the non-reentrant version The
+library keeps internal buffers which are used to replace the user
+supplied buffer.
+
+I.e., the reentrant functions @emph{can} have counterparts.  No service
+module is forced to have functions for all databases and all kinds to
+access them.  If a function is not available it is simply treated as if
+the function would return @code{unavail}
+(@pxref{Actions in the NSS configuration}).
+
+The file name @file{libnss_files.so.2} would be on a @w{Solaris 2}
+system @file{nss_files.so.2}.  This is the difference mentioned above.
+Sun's NSS modules are usable as modules which get indirectly loaded
+only.
+
+The NSS modules in @theglibc{} are prepared to be used as normal
+libraries themselves.  This is @emph{not} true at the moment, though.
+However,  the organization of the name space in the modules does not make it
+impossible like it is for Solaris.  Now you can see why the modules are
+still libraries.@footnote{There is a second explanation: we were too
+lazy to change the Makefiles to allow the generation of shared objects
+not starting with @file{lib} but don't tell this to anybody.}
+
+
+@node NSS Modules Interface,  , NSS Module Names, NSS Module Internals
+@subsection The Interface of the Function in NSS Modules
+
+Now we know about the functions contained in the modules.  It is now
+time to describe the types.  When we mentioned the reentrant versions of
+the functions above, this means there are some additional arguments
+(compared with the standard, non-reentrant version).  The prototypes for
+the non-reentrant and reentrant versions of our function above are:
+
+@smallexample
+struct hostent *gethostbyname (const char *name)
+
+int gethostbyname_r (const char *name, struct hostent *result_buf,
+                     char *buf, size_t buflen, struct hostent **result,
+                     int *h_errnop)
+@end smallexample
+
+@noindent
+The actual prototype of the function in the NSS modules in this case is
+
+@smallexample
+enum nss_status _nss_files_gethostbyname_r (const char *name,
+                                            struct hostent *result_buf,
+                                            char *buf, size_t buflen,
+                                            int *errnop, int *h_errnop)
+@end smallexample
+
+I.e., the interface function is in fact the reentrant function with the
+change of the return value and the omission of the @var{result}
+parameter.  While the user-level function returns a pointer to the
+result the reentrant function return an @code{enum nss_status} value:
+
+@vtable @code
+@item NSS_STATUS_TRYAGAIN
+numeric value @code{-2}
+
+@item NSS_STATUS_UNAVAIL
+numeric value @code{-1}
+
+@item NSS_STATUS_NOTFOUND
+numeric value @code{0}
+
+@item NSS_STATUS_SUCCESS
+numeric value @code{1}
+@end vtable
+
+@noindent
+Now you see where the action items of the @file{/etc/nsswitch.conf} file
+are used.
+
+If you study the source code you will find there is a fifth value:
+@code{NSS_STATUS_RETURN}.  This is an internal use only value, used by a
+few functions in places where none of the above value can be used.  If
+necessary the source code should be examined to learn about the details.
+
+In case the interface function has to return an error it is important
+that the correct error code is stored in @code{*@var{errnop}}.  Some
+return status value have only one associated error code, others have
+more.
+
+@multitable @columnfractions .3 .2 .50
+@item
+@code{NSS_STATUS_TRYAGAIN} @tab
+        @code{EAGAIN} @tab One of the functions used ran temporarily out of
+resources or a service is currently not available.
+@item
+@tab
+        @code{ERANGE} @tab The provided buffer is not large enough.
+The function should be called again with a larger buffer.
+@item
+@code{NSS_STATUS_UNAVAIL} @tab
+        @code{ENOENT} @tab A necessary input file cannot be found.
+@item
+@code{NSS_STATUS_NOTFOUND} @tab
+        @code{ENOENT} @tab The requested entry is not available.
+
+@item
+@code{NSS_STATUS_NOTFOUND} @tab
+	@code{SUCCESS} @tab There are no entries.
+Use this to avoid returning errors for inactive services which may
+be enabled at a later time. This is not the same as the service
+being temporarily unavailable.
+@end multitable
+
+These are proposed values.  There can be other error codes and the
+described error codes can have different meaning.  @strong{With one
+exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code
+@code{ERANGE} @emph{must} mean that the user provided buffer is too
+small.  Everything is non-critical.
+
+The above function has something special which is missing for almost all
+the other module functions.  There is an argument @var{h_errnop}.  This
+points to a variable which will be filled with the error code in case
+the execution of the function fails for some reason.  The reentrant
+function cannot use the global variable @var{h_errno};
+@code{gethostbyname} calls @code{gethostbyname_r} with the last argument
+set to @code{&h_errno}.
+
+The @code{get@var{XXX}by@var{YYY}} functions are the most important
+functions in the NSS modules.  But there are others which implement
+the other ways to access system databases (say for the
+password database, there are @code{setpwent}, @code{getpwent}, and
+@code{endpwent}).  These will be described in more detail later.
+Here we give a general way to determine the
+signature of the module function:
+
+@itemize @bullet
+@item
+the return value is @code{int};
+@item
+the name is as explained in @pxref{NSS Module Names};
+@item
+the first arguments are identical to the arguments of the non-reentrant
+function;
+@item
+the next three arguments are:
+
+@table @code
+@item STRUCT_TYPE *result_buf
+pointer to buffer where the result is stored.  @code{STRUCT_TYPE} is
+normally a struct which corresponds to the database.
+@item char *buffer
+pointer to a buffer where the function can store additional data for
+the result etc.
+@item size_t buflen
+length of the buffer pointed to by @var{buffer}.
+@end table
+
+@item
+possibly a last argument @var{h_errnop}, for the host name and network
+name lookup functions.
+@end itemize
+
+@noindent
+This table is correct for all functions but the @code{set@dots{}ent}
+and @code{end@dots{}ent} functions.
+
+
+@node Extending NSS,  , NSS Module Internals, Name Service Switch
+@section Extending NSS
+
+One of the advantages of NSS mentioned above is that it can be extended
+quite easily.  There are two ways in which the extension can happen:
+adding another database or adding another service.  The former is
+normally done only by the C library developers.  It is
+here only important to remember that adding another database is
+independent from adding another service because a service need not
+support all databases or lookup functions.
+
+A designer/implementor of a new service is therefore free to choose the
+databases s/he is interested in and leave the rest for later (or
+completely aside).
+
+@menu
+* 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.
+@end menu
+
+@node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
+@subsection Adding another Service to NSS
+
+The sources for a new service need not (and should not) be part of @theglibc{}
+itself.  The developer retains complete control over the
+sources and its development.  The links between the C library and the
+new service module consists solely of the interface functions.
+
+Each module is designed following a specific interface specification.
+For now the version is 2 (the interface in version 1 was not adequate)
+and this manifests in the version number of the shared library object of
+the NSS modules: they have the extension @code{.2}.  If the interface
+changes again in an incompatible way, this number will be increased.
+Modules using the old interface will still be usable.
+
+Developers of a new service will have to make sure that their module is
+created using the correct interface number.  This means the file itself
+must have the correct name and on ELF systems the @dfn{soname} (Shared
+Object Name) must also have this number.  Building a module from a bunch
+of object files on an ELF system using GNU CC could be done like this:
+
+@smallexample
+gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
+@end smallexample
+
+@noindent
+@ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
+more about this command line.
+
+To use the new module the library must be able to find it.  This can be
+achieved by using options for the dynamic linker so that it will search
+the directory where the binary is placed.  For an ELF system this could be
+done by adding the wanted directory to the value of
+@code{LD_LIBRARY_PATH}.
+
+But this is not always possible since some programs (those which run
+under IDs which do not belong to the user) ignore this variable.
+Therefore the stable version of the module should be placed into a
+directory which is searched by the dynamic linker.  Normally this should
+be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
+the value given to configure using the @code{--prefix} option.  But be
+careful: this should only be done if it is clear the module does not
+cause any harm.  System administrators should be careful.
+
+
+@node NSS Module Function Internals,  , Adding another Service to NSS, Extending NSS
+@subsection Internals of the NSS Module Functions
+
+Until now we only provided the syntactic interface for the functions in
+the NSS module.  In fact there is not much more we can say since the
+implementation obviously is different for each function.  But a few
+general rules must be followed by all functions.
+
+In fact there are four kinds of different functions which may appear in
+the interface.  All derive from the traditional ones for system databases.
+@var{db} in the following table is normally an abbreviation for the
+database (e.g., it is @code{pw} for the password database).
+
+@table @code
+@item enum nss_status _nss_@var{database}_set@var{db}ent (void)
+This function prepares the service for following operations.  For a
+simple file based lookup this means files could be opened, for other
+services this function simply is a noop.
+
+One special case for this function is that it takes an additional
+argument for some @var{database}s (i.e., the interface is
+@code{int set@var{db}ent (int)}).  @ref{Host Names}, which describes the
+@code{sethostent} function.
+
+The return value should be @var{NSS_STATUS_SUCCESS} or according to the
+table above in case of an error (@pxref{NSS Modules Interface}).
+
+@item enum nss_status _nss_@var{database}_end@var{db}ent (void)
+This function simply closes all files which are still open or removes
+buffer caches.  If there are no files or buffers to remove this is again
+a simple noop.
+
+There normally is no return value different to @var{NSS_STATUS_SUCCESS}.
+
+@item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
+Since this function will be called several times in a row to retrieve
+one entry after the other it must keep some kind of state.  But this
+also means the functions are not really reentrant.  They are reentrant
+only in that simultaneous calls to this function will not try to
+write the retrieved data in the same place (as it would be the case for
+the non-reentrant functions); instead, it writes to the structure
+pointed to by the @var{result} parameter.  But the calls share a common
+state and in the case of a file access this means they return neighboring
+entries in the file.
+
+The buffer of length @var{buflen} pointed to by @var{buffer} can be used
+for storing some additional data for the result.  It is @emph{not}
+guaranteed that the same buffer will be passed for the next call of this
+function.  Therefore one must not misuse this buffer to save some state
+information from one call to another.
+
+Before the function returns the implementation should store the value of
+the local @var{errno} variable in the variable pointed to be
+@var{errnop}.  This is important to guarantee the module working in
+statically linked programs.
+
+As explained above this function could also have an additional last
+argument.  This depends on the database used; it happens only for
+@code{host} and @code{networks}.
+
+The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
+more entries.  When the last entry was read it should return
+@code{NSS_STATUS_NOTFOUND}.  When the buffer given as an argument is too
+small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
+returned.  When the service was not formerly initialized by a call to
+@code{_nss_@var{DATABASE}_set@var{db}ent} all return value allowed for
+this function can also be returned here.
+
+@item enum nss_status _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
+This function shall return the entry from the database which is
+addressed by the @var{PARAMS}.  The type and number of these arguments
+vary.  It must be individually determined by looking to the user-level
+interface functions.  All arguments given to the non-reentrant version
+are here described by @var{PARAMS}.
+
+The result must be stored in the structure pointed to by @var{result}.
+If there is additional data to return (say strings, where the
+@var{result} structure only contains pointers) the function must use the
+@var{buffer} or length @var{buflen}.  There must not be any references
+to non-constant global data.
+
+The implementation of this function should honor the @var{stayopen}
+flag set by the @code{set@var{DB}ent} function whenever this makes sense.
+
+Before the function returns the implementation should store the value of
+the local @var{errno} variable in the variable pointed to be
+@var{errnop}.  This is important to guarantee the module working in
+statically linked programs.
+
+Again, this function takes an additional last argument for the
+@code{host} and @code{networks} database.
+
+The return value should as always follow the rules given above
+(@pxref{NSS Modules Interface}).
+
+@end table
diff --git a/ap/libc/glibc/glibc-2.23/manual/nsswitch.texi b/ap/libc/glibc/glibc-2.23/manual/nsswitch.texi
new file mode 100644
index 0000000..62e7f60
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/nsswitch.texi
@@ -0,0 +1,16 @@
+# /etc/nsswitch.conf
+#
+# Name Service Switch configuration file.
+#
+
+passwd:     db files nis
+shadow:     files
+group:      db files nis
+
+hosts:      files nisplus nis dns
+networks:   nisplus [NOTFOUND=return] files
+
+ethers:     nisplus [NOTFOUND=return] db files
+protocols:  nisplus [NOTFOUND=return] db files
+rpc:        nisplus [NOTFOUND=return] db files
+services:   nisplus [NOTFOUND=return] db files
diff --git a/ap/libc/glibc/glibc-2.23/manual/pattern.texi b/ap/libc/glibc/glibc-2.23/manual/pattern.texi
new file mode 100644
index 0000000..d1b9275
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/pattern.texi
@@ -0,0 +1,2274 @@
+@node Pattern Matching, I/O Overview, Searching and Sorting, Top
+@c %MENU% Matching shell ``globs'' and regular expressions
+@chapter Pattern Matching
+
+@Theglibc{} provides pattern matching facilities for two kinds of
+patterns: regular expressions and file-name wildcards.  The library also
+provides a facility for expanding variable and command references and
+parsing text into words in the way the shell does.
+
+@menu
+* Wildcard Matching::    Matching a wildcard pattern against a single string.
+* Globbing::             Finding the files that match a wildcard pattern.
+* Regular Expressions::  Matching regular expressions against strings.
+* Word Expansion::       Expanding shell variables, nested commands,
+			    arithmetic, and wildcards.
+			    This is what the shell does with shell commands.
+@end menu
+
+@node Wildcard Matching
+@section Wildcard Matching
+
+@pindex fnmatch.h
+This section describes how to match a wildcard pattern against a
+particular string.  The result is a yes or no answer: does the
+string fit the pattern or not.  The symbols described here are all
+declared in @file{fnmatch.h}.
+
+@comment fnmatch.h
+@comment POSIX.2
+@deftypefun int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c fnmatch @mtsenv @mtslocale @ascuheap @acsmem
+@c  strnlen dup ok
+@c  mbsrtowcs
+@c  memset dup ok
+@c  malloc dup @ascuheap @acsmem
+@c  mbsinit dup ok
+@c  free dup @ascuheap @acsmem
+@c  FCT = internal_fnwmatch @mtsenv @mtslocale @ascuheap @acsmem
+@c   FOLD @mtslocale
+@c    towlower @mtslocale
+@c   EXT @mtsenv @mtslocale @ascuheap @acsmem
+@c    STRLEN = wcslen dup ok
+@c    getenv @mtsenv
+@c    malloc dup @ascuheap @acsmem
+@c    MEMPCPY = wmempcpy dup ok
+@c    FCT dup @mtsenv @mtslocale @ascuheap @acsmem
+@c    STRCAT = wcscat dup ok
+@c    free dup @ascuheap @acsmem
+@c   END @mtsenv
+@c    getenv @mtsenv
+@c   MEMCHR = wmemchr dup ok
+@c   getenv @mtsenv
+@c   IS_CHAR_CLASS = is_char_class @mtslocale
+@c    wctype @mtslocale
+@c   BTOWC ok
+@c   ISWCTYPE ok
+@c   auto findidx dup ok
+@c   elem_hash dup ok
+@c   memcmp dup ok
+@c   collseq_table_lookup dup ok
+@c   NO_LEADING_PERIOD ok
+This function tests whether the string @var{string} matches the pattern
+@var{pattern}.  It returns @code{0} if they do match; otherwise, it
+returns the nonzero value @code{FNM_NOMATCH}.  The arguments
+@var{pattern} and @var{string} are both strings.
+
+The argument @var{flags} is a combination of flag bits that alter the
+details of matching.  See below for a list of the defined flags.
+
+In @theglibc{}, @code{fnmatch} might sometimes report ``errors'' by
+returning nonzero values that are not equal to @code{FNM_NOMATCH}.
+@end deftypefun
+
+These are the available flags for the @var{flags} argument:
+
+@table @code
+@comment fnmatch.h
+@comment GNU
+@item FNM_FILE_NAME
+Treat the @samp{/} character specially, for matching file names.  If
+this flag is set, wildcard constructs in @var{pattern} cannot match
+@samp{/} in @var{string}.  Thus, the only way to match @samp{/} is with
+an explicit @samp{/} in @var{pattern}.
+
+@comment fnmatch.h
+@comment POSIX.2
+@item FNM_PATHNAME
+This is an alias for @code{FNM_FILE_NAME}; it comes from POSIX.2.  We
+don't recommend this name because we don't use the term ``pathname'' for
+file names.
+
+@comment fnmatch.h
+@comment POSIX.2
+@item FNM_PERIOD
+Treat the @samp{.} character specially if it appears at the beginning of
+@var{string}.  If this flag is set, wildcard constructs in @var{pattern}
+cannot match @samp{.} as the first character of @var{string}.
+
+If you set both @code{FNM_PERIOD} and @code{FNM_FILE_NAME}, then the
+special treatment applies to @samp{.} following @samp{/} as well as to
+@samp{.} at the beginning of @var{string}.  (The shell uses the
+@code{FNM_PERIOD} and @code{FNM_FILE_NAME} flags together for matching
+file names.)
+
+@comment fnmatch.h
+@comment POSIX.2
+@item FNM_NOESCAPE
+Don't treat the @samp{\} character specially in patterns.  Normally,
+@samp{\} quotes the following character, turning off its special meaning
+(if any) so that it matches only itself.  When quoting is enabled, the
+pattern @samp{\?} matches only the string @samp{?}, because the question
+mark in the pattern acts like an ordinary character.
+
+If you use @code{FNM_NOESCAPE}, then @samp{\} is an ordinary character.
+
+@comment fnmatch.h
+@comment GNU
+@item FNM_LEADING_DIR
+Ignore a trailing sequence of characters starting with a @samp{/} in
+@var{string}; that is to say, test whether @var{string} starts with a
+directory name that @var{pattern} matches.
+
+If this flag is set, either @samp{foo*} or @samp{foobar} as a pattern
+would match the string @samp{foobar/frobozz}.
+
+@comment fnmatch.h
+@comment GNU
+@item FNM_CASEFOLD
+Ignore case in comparing @var{string} to @var{pattern}.
+
+@comment fnmatch.h
+@comment GNU
+@item FNM_EXTMATCH
+@cindex Korn Shell
+@pindex ksh
+Recognize beside the normal patterns also the extended patterns
+introduced in @file{ksh}.  The patterns are written in the form
+explained in the following table where @var{pattern-list} is a @code{|}
+separated list of patterns.
+
+@table @code
+@item ?(@var{pattern-list})
+The pattern matches if zero or one occurrences of any of the patterns
+in the @var{pattern-list} allow matching the input string.
+
+@item *(@var{pattern-list})
+The pattern matches if zero or more occurrences of any of the patterns
+in the @var{pattern-list} allow matching the input string.
+
+@item +(@var{pattern-list})
+The pattern matches if one or more occurrences of any of the patterns
+in the @var{pattern-list} allow matching the input string.
+
+@item @@(@var{pattern-list})
+The pattern matches if exactly one occurrence of any of the patterns in
+the @var{pattern-list} allows matching the input string.
+
+@item !(@var{pattern-list})
+The pattern matches if the input string cannot be matched with any of
+the patterns in the @var{pattern-list}.
+@end table
+@end table
+
+@node Globbing
+@section Globbing
+
+@cindex globbing
+The archetypal use of wildcards is for matching against the files in a
+directory, and making a list of all the matches.  This is called
+@dfn{globbing}.
+
+You could do this using @code{fnmatch}, by reading the directory entries
+one by one and testing each one with @code{fnmatch}.  But that would be
+slow (and complex, since you would have to handle subdirectories by
+hand).
+
+The library provides a function @code{glob} to make this particular use
+of wildcards convenient.  @code{glob} and the other symbols in this
+section are declared in @file{glob.h}.
+
+@menu
+* 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}.
+@end menu
+
+@node Calling Glob
+@subsection Calling @code{glob}
+
+The result of globbing is a vector of file names (strings).  To return
+this vector, @code{glob} uses a special data type, @code{glob_t}, which
+is a structure.  You pass @code{glob} the address of the structure, and
+it fills in the structure's fields to tell you about the results.
+
+@comment glob.h
+@comment POSIX.2
+@deftp {Data Type} glob_t
+This data type holds a pointer to a word vector.  More precisely, it
+records both the address of the word vector and its size.  The GNU
+implementation contains some more fields which are non-standard
+extensions.
+
+@table @code
+@item gl_pathc
+The number of elements in the vector, excluding the initial null entries
+if the GLOB_DOOFFS flag is used (see gl_offs below).
+
+@item gl_pathv
+The address of the vector.  This field has type @w{@code{char **}}.
+
+@item gl_offs
+The offset of the first real element of the vector, from its nominal
+address in the @code{gl_pathv} field.  Unlike the other fields, this
+is always an input to @code{glob}, rather than an output from it.
+
+If you use a nonzero offset, then that many elements at the beginning of
+the vector are left empty.  (The @code{glob} function fills them with
+null pointers.)
+
+The @code{gl_offs} field is meaningful only if you use the
+@code{GLOB_DOOFFS} flag.  Otherwise, the offset is always zero
+regardless of what is in this field, and the first real element comes at
+the beginning of the vector.
+
+@item gl_closedir
+The address of an alternative implementation of the @code{closedir}
+function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
+the flag parameter.  The type of this field is
+@w{@code{void (*) (void *)}}.
+
+This is a GNU extension.
+
+@item gl_readdir
+The address of an alternative implementation of the @code{readdir}
+function used to read the contents of a directory.  It is used if the
+@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
+this field is @w{@code{struct dirent *(*) (void *)}}.
+
+This is a GNU extension.
+
+@item gl_opendir
+The address of an alternative implementation of the @code{opendir}
+function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
+the flag parameter.  The type of this field is
+@w{@code{void *(*) (const char *)}}.
+
+This is a GNU extension.
+
+@item gl_stat
+The address of an alternative implementation of the @code{stat} function
+to get information about an object in the filesystem.  It is used if the
+@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
+this field is @w{@code{int (*) (const char *, struct stat *)}}.
+
+This is a GNU extension.
+
+@item gl_lstat
+The address of an alternative implementation of the @code{lstat}
+function to get information about an object in the filesystems, not
+following symbolic links.  It is used if the @code{GLOB_ALTDIRFUNC} bit
+is set in the flag parameter.  The type of this field is @code{@w{int
+(*) (const char *,} @w{struct stat *)}}.
+
+This is a GNU extension.
+
+@item gl_flags
+The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}
+might be set.  See @ref{Flags for Globbing} for more details.
+
+This is a GNU extension.
+@end table
+@end deftp
+
+For use in the @code{glob64} function @file{glob.h} contains another
+definition for a very similar type.  @code{glob64_t} differs from
+@code{glob_t} only in the types of the members @code{gl_readdir},
+@code{gl_stat}, and @code{gl_lstat}.
+
+@comment glob.h
+@comment GNU
+@deftp {Data Type} glob64_t
+This data type holds a pointer to a word vector.  More precisely, it
+records both the address of the word vector and its size.  The GNU
+implementation contains some more fields which are non-standard
+extensions.
+
+@table @code
+@item gl_pathc
+The number of elements in the vector, excluding the initial null entries
+if the GLOB_DOOFFS flag is used (see gl_offs below).
+
+@item gl_pathv
+The address of the vector.  This field has type @w{@code{char **}}.
+
+@item gl_offs
+The offset of the first real element of the vector, from its nominal
+address in the @code{gl_pathv} field.  Unlike the other fields, this
+is always an input to @code{glob}, rather than an output from it.
+
+If you use a nonzero offset, then that many elements at the beginning of
+the vector are left empty.  (The @code{glob} function fills them with
+null pointers.)
+
+The @code{gl_offs} field is meaningful only if you use the
+@code{GLOB_DOOFFS} flag.  Otherwise, the offset is always zero
+regardless of what is in this field, and the first real element comes at
+the beginning of the vector.
+
+@item gl_closedir
+The address of an alternative implementation of the @code{closedir}
+function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
+the flag parameter.  The type of this field is
+@w{@code{void (*) (void *)}}.
+
+This is a GNU extension.
+
+@item gl_readdir
+The address of an alternative implementation of the @code{readdir64}
+function used to read the contents of a directory.  It is used if the
+@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
+this field is @w{@code{struct dirent64 *(*) (void *)}}.
+
+This is a GNU extension.
+
+@item gl_opendir
+The address of an alternative implementation of the @code{opendir}
+function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
+the flag parameter.  The type of this field is
+@w{@code{void *(*) (const char *)}}.
+
+This is a GNU extension.
+
+@item gl_stat
+The address of an alternative implementation of the @code{stat64} function
+to get information about an object in the filesystem.  It is used if the
+@code{GLOB_ALTDIRFUNC} bit is set in the flag parameter.  The type of
+this field is @w{@code{int (*) (const char *, struct stat64 *)}}.
+
+This is a GNU extension.
+
+@item gl_lstat
+The address of an alternative implementation of the @code{lstat64}
+function to get information about an object in the filesystems, not
+following symbolic links.  It is used if the @code{GLOB_ALTDIRFUNC} bit
+is set in the flag parameter.  The type of this field is @code{@w{int
+(*) (const char *,} @w{struct stat64 *)}}.
+
+This is a GNU extension.
+
+@item gl_flags
+The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}
+might be set.  See @ref{Flags for Globbing} for more details.
+
+This is a GNU extension.
+@end table
+@end deftp
+
+@comment glob.h
+@comment POSIX.2
+@deftypefun int glob (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob_t *@var{vector-ptr})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c glob @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  strlen dup ok
+@c  strchr dup ok
+@c  malloc dup @ascuheap @acsmem
+@c  mempcpy dup ok
+@c  next_brace_sub ok
+@c  free dup @ascuheap @acsmem
+@c  globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  glob_pattern_p ok
+@c   glob_pattern_type dup ok
+@c  getenv dup @mtsenv
+@c  GET_LOGIN_NAME_MAX ok
+@c  getlogin_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  GETPW_R_SIZE_MAX ok
+@c  getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  memcpy dup ok
+@c  memchr dup ok
+@c  *pglob->gl_stat user-supplied
+@c  stat64 dup ok
+@c  S_ISDIR dup ok
+@c  strdup dup @ascuheap @acsmem
+@c  glob_pattern_type ok
+@c  glob_in_dir @mtsenv @mtslocale @asucorrupt @ascuheap @acucorrupt @acsfd @acsmem
+@c   strlen dup ok
+@c   glob_pattern_type dup ok
+@c   malloc dup @ascuheap @acsmem
+@c   mempcpy dup ok
+@c   *pglob->gl_stat user-supplied
+@c   stat64 dup ok
+@c   free dup @ascuheap @acsmem
+@c   *pglob->gl_opendir user-supplied
+@c   opendir dup @ascuheap @acsmem @acsfd
+@c   dirfd dup ok
+@c   *pglob->gl_readdir user-supplied
+@c   CONVERT_DIRENT_DIRENT64 ok
+@c   readdir64 ok [protected by exclusive use of the stream]
+@c   REAL_DIR_ENTRY ok
+@c   DIRENT_MIGHT_BE_DIR ok
+@c   fnmatch dup @mtsenv @mtslocale @ascuheap @acsmem
+@c   DIRENT_MIGHT_BE_SYMLINK ok
+@c   link_exists_p ok
+@c    link_exists2_p ok
+@c     strlen dup ok
+@c     mempcpy dup ok
+@c     *pglob->gl_stat user-supplied
+@c    fxstatat64 dup ok
+@c   realloc dup @ascuheap @acsmem
+@c   pglob->gl_closedir user-supplied
+@c   closedir @ascuheap @acsmem @acsfd
+@c  prefix_array dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c   strlen dup ok
+@c   malloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c   mempcpy dup ok
+@c  strcpy dup ok
+The function @code{glob} does globbing using the pattern @var{pattern}
+in the current directory.  It puts the result in a newly allocated
+vector, and stores the size and address of this vector into
+@code{*@var{vector-ptr}}.  The argument @var{flags} is a combination of
+bit flags; see @ref{Flags for Globbing}, for details of the flags.
+
+The result of globbing is a sequence of file names.  The function
+@code{glob} allocates a string for each resulting word, then
+allocates a vector of type @code{char **} to store the addresses of
+these strings.  The last element of the vector is a null pointer.
+This vector is called the @dfn{word vector}.
+
+To return this vector, @code{glob} stores both its address and its
+length (number of elements, not counting the terminating null pointer)
+into @code{*@var{vector-ptr}}.
+
+Normally, @code{glob} sorts the file names alphabetically before
+returning them.  You can turn this off with the flag @code{GLOB_NOSORT}
+if you want to get the information as fast as possible.  Usually it's
+a good idea to let @code{glob} sort them---if you process the files in
+alphabetical order, the users will have a feel for the rate of progress
+that your application is making.
+
+If @code{glob} succeeds, it returns 0.  Otherwise, it returns one
+of these error codes:
+
+@vtable @code
+@comment glob.h
+@comment POSIX.2
+@item GLOB_ABORTED
+There was an error opening a directory, and you used the flag
+@code{GLOB_ERR} or your specified @var{errfunc} returned a nonzero
+value.
+@iftex
+See below
+@end iftex
+@ifinfo
+@xref{Flags for Globbing},
+@end ifinfo
+for an explanation of the @code{GLOB_ERR} flag and @var{errfunc}.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_NOMATCH
+The pattern didn't match any existing files.  If you use the
+@code{GLOB_NOCHECK} flag, then you never get this error code, because
+that flag tells @code{glob} to @emph{pretend} that the pattern matched
+at least one file.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_NOSPACE
+It was impossible to allocate memory to hold the result.
+@end vtable
+
+In the event of an error, @code{glob} stores information in
+@code{*@var{vector-ptr}} about all the matches it has found so far.
+
+It is important to notice that the @code{glob} function will not fail if
+it encounters directories or files which cannot be handled without the
+LFS interfaces.  The implementation of @code{glob} is supposed to use
+these functions internally.  This at least is the assumptions made by
+the Unix standard.  The GNU extension of allowing the user to provide
+own directory handling and @code{stat} functions complicates things a
+bit.  If these callback functions are used and a large file or directory
+is encountered @code{glob} @emph{can} fail.
+@end deftypefun
+
+@comment glob.h
+@comment GNU
+@deftypefun int glob64 (const char *@var{pattern}, int @var{flags}, int (*@var{errfunc}) (const char *@var{filename}, int @var{error-code}), glob64_t *@var{vector-ptr})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Same code as glob, but with glob64_t #defined as glob_t.
+The @code{glob64} function was added as part of the Large File Summit
+extensions but is not part of the original LFS proposal.  The reason for
+this is simple: it is not necessary.  The necessity for a @code{glob64}
+function is added by the extensions of the GNU @code{glob}
+implementation which allows the user to provide own directory handling
+and @code{stat} functions.  The @code{readdir} and @code{stat} functions
+do depend on the choice of @code{_FILE_OFFSET_BITS} since the definition
+of the types @code{struct dirent} and @code{struct stat} will change
+depending on the choice.
+
+Beside this difference the @code{glob64} works just like @code{glob} in
+all aspects.
+
+This function is a GNU extension.
+@end deftypefun
+
+@node Flags for Globbing
+@subsection Flags for Globbing
+
+This section describes the standard flags that you can specify in the
+@var{flags} argument to @code{glob}.  Choose the flags you want,
+and combine them with the C bitwise OR operator @code{|}.
+
+Note that there are @ref{More Flags for Globbing} available as GNU extensions.
+
+@vtable @code
+@comment glob.h
+@comment POSIX.2
+@item GLOB_APPEND
+Append the words from this expansion to the vector of words produced by
+previous calls to @code{glob}.  This way you can effectively expand
+several words as if they were concatenated with spaces between them.
+
+In order for appending to work, you must not modify the contents of the
+word vector structure between calls to @code{glob}.  And, if you set
+@code{GLOB_DOOFFS} in the first call to @code{glob}, you must also
+set it when you append to the results.
+
+Note that the pointer stored in @code{gl_pathv} may no longer be valid
+after you call @code{glob} the second time, because @code{glob} might
+have relocated the vector.  So always fetch @code{gl_pathv} from the
+@code{glob_t} structure after each @code{glob} call; @strong{never} save
+the pointer across calls.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_DOOFFS
+Leave blank slots at the beginning of the vector of words.
+The @code{gl_offs} field says how many slots to leave.
+The blank slots contain null pointers.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_ERR
+Give up right away and report an error if there is any difficulty
+reading the directories that must be read in order to expand @var{pattern}
+fully.  Such difficulties might include a directory in which you don't
+have the requisite access.  Normally, @code{glob} tries its best to keep
+on going despite any errors, reading whatever directories it can.
+
+You can exercise even more control than this by specifying an
+error-handler function @var{errfunc} when you call @code{glob}.  If
+@var{errfunc} is not a null pointer, then @code{glob} doesn't give up
+right away when it can't read a directory; instead, it calls
+@var{errfunc} with two arguments, like this:
+
+@smallexample
+(*@var{errfunc}) (@var{filename}, @var{error-code})
+@end smallexample
+
+@noindent
+The argument @var{filename} is the name of the directory that
+@code{glob} couldn't open or couldn't read, and @var{error-code} is the
+@code{errno} value that was reported to @code{glob}.
+
+If the error handler function returns nonzero, then @code{glob} gives up
+right away.  Otherwise, it continues.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_MARK
+If the pattern matches the name of a directory, append @samp{/} to the
+directory's name when returning it.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_NOCHECK
+If the pattern doesn't match any file names, return the pattern itself
+as if it were a file name that had been matched.  (Normally, when the
+pattern doesn't match anything, @code{glob} returns that there were no
+matches.)
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_NOESCAPE
+Don't treat the @samp{\} character specially in patterns.  Normally,
+@samp{\} quotes the following character, turning off its special meaning
+(if any) so that it matches only itself.  When quoting is enabled, the
+pattern @samp{\?} matches only the string @samp{?}, because the question
+mark in the pattern acts like an ordinary character.
+
+If you use @code{GLOB_NOESCAPE}, then @samp{\} is an ordinary character.
+
+@code{glob} does its work by calling the function @code{fnmatch}
+repeatedly.  It handles the flag @code{GLOB_NOESCAPE} by turning on the
+@code{FNM_NOESCAPE} flag in calls to @code{fnmatch}.
+
+@comment glob.h
+@comment POSIX.2
+@item GLOB_NOSORT
+Don't sort the file names; return them in no particular order.
+(In practice, the order will depend on the order of the entries in
+the directory.)  The only reason @emph{not} to sort is to save time.
+@end vtable
+
+@node More Flags for Globbing
+@subsection More Flags for Globbing
+
+Beside the flags described in the last section, the GNU implementation of
+@code{glob} allows a few more flags which are also defined in the
+@file{glob.h} file.  Some of the extensions implement functionality
+which is available in modern shell implementations.
+
+@vtable @code
+@comment glob.h
+@comment GNU
+@item GLOB_PERIOD
+The @code{.} character (period) is treated special.  It cannot be
+matched by wildcards.  @xref{Wildcard Matching}, @code{FNM_PERIOD}.
+
+@comment glob.h
+@comment GNU
+@item GLOB_MAGCHAR
+The @code{GLOB_MAGCHAR} value is not to be given to @code{glob} in the
+@var{flags} parameter.  Instead, @code{glob} sets this bit in the
+@var{gl_flags} element of the @var{glob_t} structure provided as the
+result if the pattern used for matching contains any wildcard character.
+
+@comment glob.h
+@comment GNU
+@item GLOB_ALTDIRFUNC
+Instead of the using the using the normal functions for accessing the
+filesystem the @code{glob} implementation uses the user-supplied
+functions specified in the structure pointed to by @var{pglob}
+parameter.  For more information about the functions refer to the
+sections about directory handling see @ref{Accessing Directories}, and
+@ref{Reading Attributes}.
+
+@comment glob.h
+@comment GNU
+@item GLOB_BRACE
+If this flag is given the handling of braces in the pattern is changed.
+It is now required that braces appear correctly grouped.  I.e., for each
+opening brace there must be a closing one.  Braces can be used
+recursively.  So it is possible to define one brace expression in
+another one.  It is important to note that the range of each brace
+expression is completely contained in the outer brace expression (if
+there is one).
+
+The string between the matching braces is separated into single
+expressions by splitting at @code{,} (comma) characters.  The commas
+themselves are discarded.  Please note what we said above about recursive
+brace expressions.  The commas used to separate the subexpressions must
+be at the same level.  Commas in brace subexpressions are not matched.
+They are used during expansion of the brace expression of the deeper
+level.  The example below shows this
+
+@smallexample
+glob ("@{foo/@{,bar,biz@},baz@}", GLOB_BRACE, NULL, &result)
+@end smallexample
+
+@noindent
+is equivalent to the sequence
+
+@smallexample
+glob ("foo/", GLOB_BRACE, NULL, &result)
+glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
+glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
+glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
+@end smallexample
+
+@noindent
+if we leave aside error handling.
+
+@comment glob.h
+@comment GNU
+@item GLOB_NOMAGIC
+If the pattern contains no wildcard constructs (it is a literal file name),
+return it as the sole ``matching'' word, even if no file exists by that name.
+
+@comment glob.h
+@comment GNU
+@item GLOB_TILDE
+If this flag is used the character @code{~} (tilde) is handled special
+if it appears at the beginning of the pattern.  Instead of being taken
+verbatim it is used to represent the home directory of a known user.
+
+If @code{~} is the only character in pattern or it is followed by a
+@code{/} (slash), the home directory of the process owner is
+substituted.  Using @code{getlogin} and @code{getpwnam} the information
+is read from the system databases.  As an example take user @code{bart}
+with his home directory at @file{/home/bart}.  For him a call like
+
+@smallexample
+glob ("~/bin/*", GLOB_TILDE, NULL, &result)
+@end smallexample
+
+@noindent
+would return the contents of the directory @file{/home/bart/bin}.
+Instead of referring to the own home directory it is also possible to
+name the home directory of other users.  To do so one has to append the
+user name after the tilde character.  So the contents of user
+@code{homer}'s @file{bin} directory can be retrieved by
+
+@smallexample
+glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
+@end smallexample
+
+If the user name is not valid or the home directory cannot be determined
+for some reason the pattern is left untouched and itself used as the
+result.  I.e., if in the last example @code{home} is not available the
+tilde expansion yields to @code{"~homer/bin/*"} and @code{glob} is not
+looking for a directory named @code{~homer}.
+
+This functionality is equivalent to what is available in C-shells if the
+@code{nonomatch} flag is set.
+
+@comment glob.h
+@comment GNU
+@item GLOB_TILDE_CHECK
+If this flag is used @code{glob} behaves like as if @code{GLOB_TILDE} is
+given.  The only difference is that if the user name is not available or
+the home directory cannot be determined for other reasons this leads to
+an error.  @code{glob} will return @code{GLOB_NOMATCH} instead of using
+the pattern itself as the name.
+
+This functionality is equivalent to what is available in C-shells if
+@code{nonomatch} flag is not set.
+
+@comment glob.h
+@comment GNU
+@item GLOB_ONLYDIR
+If this flag is used the globbing function takes this as a
+@strong{hint} that the caller is only interested in directories
+matching the pattern.  If the information about the type of the file
+is easily available non-directories will be rejected but no extra
+work will be done to determine the information for each file.  I.e.,
+the caller must still be able to filter directories out.
+
+This functionality is only available with the GNU @code{glob}
+implementation.  It is mainly used internally to increase the
+performance but might be useful for a user as well and therefore is
+documented here.
+@end vtable
+
+Calling @code{glob} will in most cases allocate resources which are used
+to represent the result of the function call.  If the same object of
+type @code{glob_t} is used in multiple call to @code{glob} the resources
+are freed or reused so that no leaks appear.  But this does not include
+the time when all @code{glob} calls are done.
+
+@comment glob.h
+@comment POSIX.2
+@deftypefun void globfree (glob_t *@var{pglob})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c globfree dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  free dup @ascuheap @acsmem
+The @code{globfree} function frees all resources allocated by previous
+calls to @code{glob} associated with the object pointed to by
+@var{pglob}.  This function should be called whenever the currently used
+@code{glob_t} typed object isn't used anymore.
+@end deftypefun
+
+@comment glob.h
+@comment GNU
+@deftypefun void globfree64 (glob64_t *@var{pglob})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+This function is equivalent to @code{globfree} but it frees records of
+type @code{glob64_t} which were allocated by @code{glob64}.
+@end deftypefun
+
+
+@node Regular Expressions
+@section Regular Expression Matching
+
+@Theglibc{} supports two interfaces for matching regular
+expressions.  One is the standard POSIX.2 interface, and the other is
+what @theglibc{} has had for many years.
+
+Both interfaces are declared in the header file @file{regex.h}.
+If you define @w{@code{_POSIX_C_SOURCE}}, then only the POSIX.2
+functions, structures, and constants are declared.
+@c !!! we only document the POSIX.2 interface here!!
+
+@menu
+* 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.
+@end menu
+
+@node POSIX Regexp Compilation
+@subsection POSIX Regular Expression Compilation
+
+Before you can actually match a regular expression, you must
+@dfn{compile} it.  This is not true compilation---it produces a special
+data structure, not machine instructions.  But it is like ordinary
+compilation in that its purpose is to enable you to ``execute'' the
+pattern fast.  (@xref{Matching POSIX Regexps}, for how to use the
+compiled regular expression for matching.)
+
+There is a special data type for compiled regular expressions:
+
+@comment regex.h
+@comment POSIX.2
+@deftp {Data Type} regex_t
+This type of object holds a compiled regular expression.
+It is actually a structure.  It has just one field that your programs
+should look at:
+
+@table @code
+@item re_nsub
+This field holds the number of parenthetical subexpressions in the
+regular expression that was compiled.
+@end table
+
+There are several other fields, but we don't describe them here, because
+only the functions in the library should use them.
+@end deftp
+
+After you create a @code{regex_t} object, you can compile a regular
+expression into it by calling @code{regcomp}.
+
+@comment regex.h
+@comment POSIX.2
+@deftypefun int regcomp (regex_t *restrict @var{compiled}, const char *restrict @var{pattern}, int @var{cflags})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c All of the issues have to do with memory allocation and multi-byte
+@c character handling present in the input string, or implied by ranges
+@c or inverted character classes.
+@c (re_)malloc @ascuheap @acsmem
+@c re_compile_internal @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  (re_)realloc @ascuheap @acsmem [no @asucorrupt @acucorrupt for we zero the buffer]
+@c  init_dfa @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   (re_)malloc @ascuheap @acsmem
+@c   calloc @ascuheap @acsmem
+@c   _NL_CURRENT ok
+@c   _NL_CURRENT_WORD ok
+@c   btowc @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  libc_lock_init ok
+@c  re_string_construct @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   re_string_construct_common ok
+@c   re_string_realloc_buffers @ascuheap @acsmem
+@c    (re_)realloc dup @ascuheap @acsmem
+@c   build_wcs_upper_buffer @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    isascii ok
+@c    mbsinit ok
+@c    toupper ok
+@c    mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    iswlower @mtslocale
+@c    towupper @mtslocale
+@c    wcrtomb dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    (re_)malloc dup @ascuheap @acsmem
+@c   build_upper_buffer ok (@mtslocale but optimized)
+@c    islower ok
+@c    toupper ok
+@c   build_wcs_buffer @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   re_string_translate_buffer ok
+@c  parse @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   fetch_token @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    peek_token @mtslocale
+@c     re_string_eoi ok
+@c     re_string_peek_byte ok
+@c     re_string_cur_idx ok
+@c     re_string_length ok
+@c     re_string_peek_byte_case @mtslocale
+@c      re_string_peek_byte dup ok
+@c      re_string_is_single_byte_char ok
+@c      isascii ok
+@c      re_string_peek_byte dup ok
+@c     re_string_wchar_at ok
+@c     re_string_skip_bytes ok
+@c    re_string_skip_bytes dup ok
+@c   parse_reg_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    parse_branch @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     parse_expression @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c      create_token_tree dup @ascuheap @acsmem
+@c      re_string_eoi dup ok
+@c      re_string_first_byte ok
+@c      fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c      create_tree dup @ascuheap @acsmem
+@c      parse_sub_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       parse_reg_exp dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       postorder() @ascuheap @acsmem
+@c        free_tree @ascuheap @acsmem
+@c         free_token dup @ascuheap @acsmem
+@c       create_tree dup @ascuheap @acsmem
+@c      parse_bracket_exp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       _NL_CURRENT dup ok
+@c       _NL_CURRENT_WORD dup ok
+@c       calloc dup @ascuheap @acsmem
+@c       (re_)free dup @ascuheap @acsmem
+@c       peek_token_bracket ok
+@c        re_string_eoi dup ok
+@c        re_string_peek_byte dup ok
+@c        re_string_first_byte dup ok
+@c        re_string_cur_idx dup ok
+@c        re_string_length dup ok
+@c        re_string_skip_bytes dup ok
+@c       bitset_set ok
+@c       re_string_skip_bytes ok
+@c       parse_bracket_element @mtslocale
+@c        re_string_char_size_at ok
+@c        re_string_wchar_at dup ok
+@c        re_string_skip_bytes dup ok
+@c        parse_bracket_symbol @mtslocale
+@c         re_string_eoi dup ok
+@c         re_string_fetch_byte_case @mtslocale
+@c          re_string_fetch_byte ok
+@c          re_string_first_byte dup ok
+@c          isascii ok
+@c          re_string_char_size_at dup ok
+@c          re_string_skip_bytes dup ok
+@c         re_string_fetch_byte dup ok
+@c         re_string_peek_byte dup ok
+@c         re_string_skip_bytes dup ok
+@c        peek_token_bracket dup ok
+@c       auto build_range_exp @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c        auto lookup_collation_sequence_value @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c         btowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c         collseq_table_lookup ok
+@c         auto seek_collating_symbol_entry dup ok
+@c        (re_)realloc dup @ascuheap @acsmem
+@c        collseq_table_lookup dup ok
+@c       bitset_set dup ok
+@c       (re_)realloc dup @ascuheap @acsmem
+@c       build_equiv_class @mtslocale @ascuheap @acsmem
+@c        _NL_CURRENT ok
+@c        auto findidx ok
+@c        bitset_set dup ok
+@c        (re_)realloc dup @ascuheap @acsmem
+@c       auto build_collating_symbol @ascuheap @acsmem
+@c        auto seek_collating_symbol_entry ok
+@c        bitset_set dup ok
+@c        (re_)realloc dup @ascuheap @acsmem
+@c       build_charclass @mtslocale @ascuheap @acsmem
+@c        (re_)realloc dup @ascuheap @acsmem
+@c        bitset_set dup ok
+@c        isalnum ok
+@c        iscntrl ok
+@c        isspace ok
+@c        isalpha ok
+@c        isdigit ok
+@c        isprint ok
+@c        isupper ok
+@c        isblank ok
+@c        isgraph ok
+@c        ispunct ok
+@c        isxdigit ok
+@c       bitset_not ok
+@c       bitset_mask ok
+@c       create_token_tree dup @ascuheap @acsmem
+@c       create_tree dup @ascuheap @acsmem
+@c       free_charset dup @ascuheap @acsmem
+@c      init_word_char @mtslocale
+@c       isalnum ok
+@c      build_charclass_op @mtslocale @ascuheap @acsmem
+@c       calloc dup @ascuheap @acsmem
+@c       build_charclass dup @mtslocale @ascuheap @acsmem
+@c       (re_)free dup @ascuheap @acsmem
+@c       free_charset dup @ascuheap @acsmem
+@c       bitset_set dup ok
+@c       bitset_not dup ok
+@c       bitset_mask dup ok
+@c       create_token_tree dup @ascuheap @acsmem
+@c       create_tree dup @ascuheap @acsmem
+@c      parse_dup_op @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       re_string_cur_idx dup ok
+@c       fetch_number @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c        fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       re_string_set_index ok
+@c       postorder() @ascuheap @acsmem
+@c        free_tree dup @ascuheap @acsmem
+@c        mark_opt_subexp ok
+@c       duplicate_tree @ascuheap @acsmem
+@c        create_token_tree dup @ascuheap @acsmem
+@c       create_tree dup @ascuheap @acsmem
+@c     postorder() @ascuheap @acsmem
+@c      free_tree dup @ascuheap @acsmem
+@c    fetch_token dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    parse_branch dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    create_tree dup @ascuheap @acsmem
+@c   create_tree @ascuheap @acsmem
+@c    create_token_tree @ascuheap @acsmem
+@c     (re_)malloc dup @ascuheap @acsmem
+@c  analyze @ascuheap @acsmem
+@c   (re_)malloc dup @ascuheap @acsmem
+@c   preorder() @ascuheap @acsmem
+@c    optimize_subexps ok
+@c    calc_next ok
+@c    link_nfa_nodes @ascuheap @acsmem
+@c     re_node_set_init_1 @ascuheap @acsmem
+@c      (re_)malloc dup @ascuheap @acsmem
+@c     re_node_set_init_2 @ascuheap @acsmem
+@c      (re_)malloc dup @ascuheap @acsmem
+@c   postorder() @ascuheap @acsmem
+@c    lower_subexps @ascuheap @acsmem
+@c     lower_subexp @ascuheap @acsmem
+@c      create_tree dup @ascuheap @acsmem
+@c    calc_first @ascuheap @acsmem
+@c     re_dfa_add_node @ascuheap @acsmem
+@c      (re_)realloc dup @ascuheap @acsmem
+@c      re_node_set_init_empty ok
+@c   calc_eclosure @ascuheap @acsmem
+@c    calc_eclosure_iter @ascuheap @acsmem
+@c     re_node_set_alloc @ascuheap @acsmem
+@c      (re_)malloc dup @ascuheap @acsmem
+@c     duplicate_node_closure @ascuheap @acsmem
+@c      re_node_set_empty ok
+@c      duplicate_node @ascuheap @acsmem
+@c       re_dfa_add_node dup @ascuheap @acsmem
+@c      re_node_set_insert @ascuheap @acsmem
+@c       (re_)realloc dup @ascuheap @acsmem
+@c      search_duplicated_node ok
+@c     re_node_set_merge @ascuheap @acsmem
+@c      (re_)realloc dup @ascuheap @acsmem
+@c     re_node_set_free @ascuheap @acsmem
+@c      (re_)free dup @ascuheap @acsmem
+@c     re_node_set_insert dup @ascuheap @acsmem
+@c    re_node_set_free dup @ascuheap @acsmem
+@c   calc_inveclosure @ascuheap @acsmem
+@c    re_node_set_init_empty dup ok
+@c    re_node_set_insert_last @ascuheap @acsmem
+@c     (re_)realloc dup @ascuheap @acsmem
+@c  optimize_utf8 ok
+@c  create_initial_state @ascuheap @acsmem
+@c   re_node_set_init_copy @ascuheap @acsmem
+@c    (re_)malloc dup @ascuheap @acsmem
+@c    re_node_set_init_empty dup ok
+@c   re_node_set_contains ok
+@c   re_node_set_merge dup @ascuheap @acsmem
+@c   re_acquire_state_context @ascuheap @acsmem
+@c    calc_state_hash ok
+@c    re_node_set_compare ok
+@c    create_cd_newstate @ascuheap @acsmem
+@c     calloc dup @ascuheap @acsmem
+@c     re_node_set_init_copy dup @ascuheap @acsmem
+@c     (re_)free dup @ascuheap @acsmem
+@c     free_state @ascuheap @acsmem
+@c      re_node_set_free dup @ascuheap @acsmem
+@c      (re_)free dup @ascuheap @acsmem
+@c     NOT_SATISFY_PREV_CONSTRAINT ok
+@c     re_node_set_remove_at ok
+@c     register_state @ascuheap @acsmem
+@c      re_node_set_alloc dup @ascuheap @acsmem
+@c      re_node_set_insert_last dup @ascuheap @acsmem
+@c      (re_)realloc dup @ascuheap @acsmem
+@c   re_node_set_free dup @ascuheap @acsmem
+@c  free_workarea_compile @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c  re_string_destruct @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c  free_dfa_content @ascuheap @acsmem
+@c   free_token @ascuheap @acsmem
+@c    free_charset @ascuheap @acsmem
+@c     (re_)free dup @ascuheap @acsmem
+@c    (re_)free dup @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c   re_node_set_free dup @ascuheap @acsmem
+@c re_compile_fastmap @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  re_compile_fastmap_iter @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   re_set_fastmap ok
+@c    tolower ok
+@c   mbrtowc dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   wcrtomb dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   towlower @mtslocale
+@c   _NL_CURRENT ok
+@c (re_)free @ascuheap @acsmem
+The function @code{regcomp} ``compiles'' a regular expression into a
+data structure that you can use with @code{regexec} to match against a
+string.  The compiled regular expression format is designed for
+efficient matching.  @code{regcomp} stores it into @code{*@var{compiled}}.
+
+It's up to you to allocate an object of type @code{regex_t} and pass its
+address to @code{regcomp}.
+
+The argument @var{cflags} lets you specify various options that control
+the syntax and semantics of regular expressions.  @xref{Flags for POSIX
+Regexps}.
+
+If you use the flag @code{REG_NOSUB}, then @code{regcomp} omits from
+the compiled regular expression the information necessary to record
+how subexpressions actually match.  In this case, you might as well
+pass @code{0} for the @var{matchptr} and @var{nmatch} arguments when
+you call @code{regexec}.
+
+If you don't use @code{REG_NOSUB}, then the compiled regular expression
+does have the capacity to record how subexpressions match.  Also,
+@code{regcomp} tells you how many subexpressions @var{pattern} has, by
+storing the number in @code{@var{compiled}->re_nsub}.  You can use that
+value to decide how long an array to allocate to hold information about
+subexpression matches.
+
+@code{regcomp} returns @code{0} if it succeeds in compiling the regular
+expression; otherwise, it returns a nonzero error code (see the table
+below).  You can use @code{regerror} to produce an error message string
+describing the reason for a nonzero value; see @ref{Regexp Cleanup}.
+
+@end deftypefun
+
+Here are the possible nonzero values that @code{regcomp} can return:
+
+@table @code
+@comment regex.h
+@comment POSIX.2
+@item REG_BADBR
+There was an invalid @samp{\@{@dots{}\@}} construct in the regular
+expression.  A valid @samp{\@{@dots{}\@}} construct must contain either
+a single number, or two numbers in increasing order separated by a
+comma.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_BADPAT
+There was a syntax error in the regular expression.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_BADRPT
+A repetition operator such as @samp{?} or @samp{*} appeared in a bad
+position (with no preceding subexpression to act on).
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ECOLLATE
+The regular expression referred to an invalid collating element (one not
+defined in the current locale for string collation).  @xref{Locale
+Categories}.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ECTYPE
+The regular expression referred to an invalid character class name.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_EESCAPE
+The regular expression ended with @samp{\}.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ESUBREG
+There was an invalid number in the @samp{\@var{digit}} construct.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_EBRACK
+There were unbalanced square brackets in the regular expression.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_EPAREN
+An extended regular expression had unbalanced parentheses,
+or a basic regular expression had unbalanced @samp{\(} and @samp{\)}.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_EBRACE
+The regular expression had unbalanced @samp{\@{} and @samp{\@}}.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ERANGE
+One of the endpoints in a range expression was invalid.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ESPACE
+@code{regcomp} ran out of memory.
+@end table
+
+@node Flags for POSIX Regexps
+@subsection Flags for POSIX Regular Expressions
+
+These are the bit flags that you can use in the @var{cflags} operand when
+compiling a regular expression with @code{regcomp}.
+
+@table @code
+@comment regex.h
+@comment POSIX.2
+@item REG_EXTENDED
+Treat the pattern as an extended regular expression, rather than as a
+basic regular expression.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ICASE
+Ignore case when matching letters.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_NOSUB
+Don't bother storing the contents of the @var{matches-ptr} array.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_NEWLINE
+Treat a newline in @var{string} as dividing @var{string} into multiple
+lines, so that @samp{$} can match before the newline and @samp{^} can
+match after.  Also, don't permit @samp{.} to match a newline, and don't
+permit @samp{[^@dots{}]} to match a newline.
+
+Otherwise, newline acts like any other ordinary character.
+@end table
+
+@node Matching POSIX Regexps
+@subsection Matching a Compiled POSIX Regular Expression
+
+Once you have compiled a regular expression, as described in @ref{POSIX
+Regexp Compilation}, you can match it against strings using
+@code{regexec}.  A match anywhere inside the string counts as success,
+unless the regular expression contains anchor characters (@samp{^} or
+@samp{$}).
+
+@comment regex.h
+@comment POSIX.2
+@deftypefun int regexec (const regex_t *restrict @var{compiled}, const char *restrict @var{string}, size_t @var{nmatch}, regmatch_t @var{matchptr}[restrict], int @var{eflags})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c libc_lock_lock @asulock @aculock
+@c re_search_internal @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  re_string_allocate @ascuheap @acsmem
+@c   re_string_construct_common dup ok
+@c   re_string_realloc_buffers dup @ascuheap @acsmem
+@c  match_ctx_init @ascuheap @acsmem
+@c   (re_)malloc dup @ascuheap @acsmem
+@c  re_string_byte_at ok
+@c  re_string_first_byte dup ok
+@c  check_matching @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   re_string_cur_idx dup ok
+@c   acquire_init_state_context dup @ascuheap @acsmem
+@c    re_string_context_at ok
+@c     re_string_byte_at dup ok
+@c     bitset_contain ok
+@c    re_acquire_state_context dup @ascuheap @acsmem
+@c   check_subexp_matching_top @ascuheap @acsmem
+@c    match_ctx_add_subtop @ascuheap @acsmem
+@c     (re_)realloc dup @ascuheap @acsmem
+@c     calloc dup @ascuheap @acsmem
+@c   transit_state_bkref @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    re_string_cur_idx dup ok
+@c    re_string_context_at dup ok
+@c    NOT_SATISFY_NEXT_CONSTRAINT ok
+@c    get_subexp @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     re_string_get_buffer ok
+@c     search_cur_bkref_entry ok
+@c     clean_state_log_if_needed @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c      extend_buffers @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       re_string_realloc_buffers dup @ascuheap @acsmem
+@c       (re_)realloc dup @ascuheap @acsmem
+@c       build_wcs_upper_buffer dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       build_upper_buffer dup ok (@mtslocale but optimized)
+@c       build_wcs_buffer dup @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       re_string_translate_buffer dup ok
+@c     get_subexp_sub @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c      check_arrival @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c       (re_)realloc dup @ascuheap @acsmem
+@c       re_string_context_at dup ok
+@c       re_node_set_init_1 dup @ascuheap @acsmem
+@c       check_arrival_expand_ecl @ascuheap @acsmem
+@c        re_node_set_alloc dup @ascuheap @acsmem
+@c        find_subexp_node ok
+@c        re_node_set_merge dup @ascuheap @acsmem
+@c        re_node_set_free dup @ascuheap @acsmem
+@c        check_arrival_expand_ecl_sub @ascuheap @acsmem
+@c         re_node_set_contains dup ok
+@c         re_node_set_insert dup @ascuheap @acsmem
+@c       re_node_set_free dup @ascuheap @acsmem
+@c       re_node_set_init_copy dup @ascuheap @acsmem
+@c       re_node_set_init_empty dup ok
+@c       expand_bkref_cache @ascuheap @acsmem
+@c        search_cur_bkref_entry dup ok
+@c        re_node_set_contains dup ok
+@c        re_node_set_init_1 dup @ascuheap @acsmem
+@c        check_arrival_expand_ecl dup @ascuheap @acsmem
+@c        re_node_set_merge dup @ascuheap @acsmem
+@c        re_node_set_init_copy dup @ascuheap @acsmem
+@c        re_node_set_insert dup @ascuheap @acsmem
+@c        re_node_set_free dup @ascuheap @acsmem
+@c        re_acquire_state @ascuheap @acsmem
+@c         calc_state_hash dup ok
+@c         re_node_set_compare dup ok
+@c         create_ci_newstate @ascuheap @acsmem
+@c          calloc dup @ascuheap @acsmem
+@c          re_node_set_init_copy dup @ascuheap @acsmem
+@c          (re_)free dup @ascuheap @acsmem
+@c          register_state dup @ascuheap @acsmem
+@c          free_state dup @ascuheap @acsmem
+@c       re_acquire_state_context dup @ascuheap @acsmem
+@c       re_node_set_merge dup @ascuheap @acsmem
+@c       check_arrival_add_next_nodes @mtslocale @ascuheap @acsmem
+@c        re_node_set_init_empty dup ok
+@c        check_node_accept_bytes @mtslocale @ascuheap @acsmem
+@c         re_string_byte_at dup ok
+@c         re_string_char_size_at dup ok
+@c         re_string_elem_size_at @mtslocale
+@c          _NL_CURRENT_WORD dup ok
+@c          _NL_CURRENT dup ok
+@c          auto findidx dup ok
+@c         _NL_CURRENT_WORD dup ok
+@c         _NL_CURRENT dup ok
+@c         collseq_table_lookup dup ok
+@c         find_collation_sequence_value @mtslocale
+@c          _NL_CURRENT_WORD dup ok
+@c          _NL_CURRENT dup ok
+@c         auto findidx dup ok
+@c         wcscoll @mtslocale @ascuheap @acsmem
+@c        re_node_set_empty dup ok
+@c        re_node_set_merge dup @ascuheap @acsmem
+@c        re_node_set_free dup @ascuheap @acsmem
+@c        re_node_set_insert dup @ascuheap @acsmem
+@c        re_acquire_state dup @ascuheap @acsmem
+@c        check_node_accept ok
+@c         re_string_byte_at dup ok
+@c         bitset_contain dup ok
+@c         re_string_context_at dup ok
+@c         NOT_SATISFY_NEXT_CONSTRAINT dup ok
+@c      match_ctx_add_entry @ascuheap @acsmem
+@c       (re_)realloc dup @ascuheap @acsmem
+@c       (re_)free dup @ascuheap @acsmem
+@c      clean_state_log_if_needed dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     extend_buffers dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     find_subexp_node dup ok
+@c     calloc dup @ascuheap @acsmem
+@c     check_arrival dup ***
+@c     match_ctx_add_sublast @ascuheap @acsmem
+@c      (re_)realloc dup @ascuheap @acsmem
+@c    re_acquire_state_context dup @ascuheap @acsmem
+@c    re_node_set_init_union @ascuheap @acsmem
+@c     (re_)malloc dup @ascuheap @acsmem
+@c     re_node_set_init_copy dup @ascuheap @acsmem
+@c     re_node_set_init_empty dup ok
+@c    re_node_set_free dup @ascuheap @acsmem
+@c    check_subexp_matching_top dup @ascuheap @acsmem
+@c   check_halt_state_context ok
+@c    re_string_context_at dup ok
+@c    check_halt_node_context ok
+@c     NOT_SATISFY_NEXT_CONSTRAINT dup ok
+@c   re_string_eoi dup ok
+@c   extend_buffers dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   transit_state @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    transit_state_mb @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     re_string_context_at dup ok
+@c     NOT_SATISFY_NEXT_CONSTRAINT dup ok
+@c     check_node_accept_bytes dup @mtslocale @ascuheap @acsmem
+@c     re_string_cur_idx dup ok
+@c     clean_state_log_if_needed @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     re_node_set_init_union dup @ascuheap @acsmem
+@c     re_acquire_state_context dup @ascuheap @acsmem
+@c    re_string_fetch_byte dup ok
+@c    re_string_context_at dup ok
+@c    build_trtable @ascuheap @acsmem
+@c     (re_)malloc dup @ascuheap @acsmem
+@c     group_nodes_into_DFAstates @ascuheap @acsmem
+@c      bitset_empty dup ok
+@c      bitset_set dup ok
+@c      bitset_merge dup ok
+@c      bitset_set_all ok
+@c      bitset_clear ok
+@c      bitset_contain dup ok
+@c      bitset_copy ok
+@c      re_node_set_init_copy dup @ascuheap @acsmem
+@c      re_node_set_insert dup @ascuheap @acsmem
+@c      re_node_set_init_1 dup @ascuheap @acsmem
+@c      re_node_set_free dup @ascuheap @acsmem
+@c     re_node_set_alloc dup @ascuheap @acsmem
+@c     malloc dup @ascuheap @acsmem
+@c     free dup @ascuheap @acsmem
+@c     re_node_set_free dup @ascuheap @acsmem
+@c     bitset_empty ok
+@c     re_node_set_empty dup ok
+@c     re_node_set_merge dup @ascuheap @acsmem
+@c     re_acquire_state_context dup @ascuheap @acsmem
+@c     bitset_merge ok
+@c     calloc dup @ascuheap @acsmem
+@c     bitset_contain dup ok
+@c   merge_state_with_log @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    re_string_cur_idx dup ok
+@c    re_node_set_init_union dup @ascuheap @acsmem
+@c    re_string_context_at dup ok
+@c    re_node_set_free dup @ascuheap @acsmem
+@c    check_subexp_matching_top @ascuheap @acsmem
+@c     match_ctx_add_subtop dup @ascuheap @acsmem
+@c    transit_state_bkref dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   find_recover_state
+@c    re_string_cur_idx dup ok
+@c    re_string_skip_bytes dup ok
+@c    merge_state_with_log dup @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  check_halt_state_context dup ok
+@c  prune_impossible_nodes @mtslocale @ascuheap @acsmem
+@c   (re_)malloc dup @ascuheap @acsmem
+@c   sift_ctx_init ok
+@c    re_node_set_init_empty dup ok
+@c   sift_states_backward @mtslocale @ascuheap @acsmem
+@c    re_node_set_init_1 dup @ascuheap @acsmem
+@c    update_cur_sifted_state @mtslocale @ascuheap @acsmem
+@c     add_epsilon_src_nodes @ascuheap @acsmem
+@c      re_acquire_state dup @ascuheap @acsmem
+@c      re_node_set_alloc dup @ascuheap @acsmem
+@c      re_node_set_merge dup @ascuheap @acsmem
+@c      re_node_set_add_intersect @ascuheap @acsmem
+@c       (re_)realloc dup @ascuheap @acsmem
+@c     check_subexp_limits @ascuheap @acsmem
+@c      sub_epsilon_src_nodes @ascuheap @acsmem
+@c       re_node_set_init_empty dup ok
+@c       re_node_set_contains dup ok
+@c       re_node_set_add_intersect dup @ascuheap @acsmem
+@c       re_node_set_free dup @ascuheap @acsmem
+@c       re_node_set_remove_at dup ok
+@c      re_node_set_contains dup ok
+@c     re_acquire_state dup @ascuheap @acsmem
+@c     sift_states_bkref @mtslocale @ascuheap @acsmem
+@c      search_cur_bkref_entry dup ok
+@c      check_dst_limits ok
+@c       search_cur_bkref_entry dup ok
+@c       check_dst_limits_calc_pos ok
+@c        check_dst_limits_calc_pos_1 ok
+@c      re_node_set_init_copy dup @ascuheap @acsmem
+@c      re_node_set_insert dup @ascuheap @acsmem
+@c      sift_states_backward dup @mtslocale @ascuheap @acsmem
+@c      merge_state_array dup @ascuheap @acsmem
+@c      re_node_set_remove ok
+@c       re_node_set_contains dup ok
+@c       re_node_set_remove_at dup ok
+@c      re_node_set_free dup @ascuheap @acsmem
+@c    re_node_set_free dup @ascuheap @acsmem
+@c    re_node_set_empty dup ok
+@c    build_sifted_states @mtslocale @ascuheap @acsmem
+@c     sift_states_iter_mb @mtslocale @ascuheap @acsmem
+@c      check_node_accept_bytes dup @mtslocale @ascuheap @acsmem
+@c     check_node_accept dup ok
+@c     check_dst_limits dup ok
+@c     re_node_set_insert dup @ascuheap @acsmem
+@c   re_node_set_free dup @ascuheap @acsmem
+@c   check_halt_state_context dup ok
+@c   merge_state_array @ascuheap @acsmem
+@c    re_node_set_init_union dup @ascuheap @acsmem
+@c    re_acquire_state dup @ascuheap @acsmem
+@c    re_node_set_free dup @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c  set_regs @ascuheap @acsmem
+@c   (re_)malloc dup @ascuheap @acsmem
+@c   re_node_set_init_empty dup ok
+@c   free_fail_stack_return @ascuheap @acsmem
+@c    re_node_set_free dup @ascuheap @acsmem
+@c    (re_)free dup @ascuheap @acsmem
+@c   update_regs ok
+@c   re_node_set_free dup @ascuheap @acsmem
+@c   pop_fail_stack @ascuheap @acsmem
+@c    re_node_set_free dup @ascuheap @acsmem
+@c    (re_)free dup @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c  (re_)free dup @ascuheap @acsmem
+@c  match_ctx_free @ascuheap @acsmem
+@c   match_ctx_clean @ascuheap @acsmem
+@c    (re_)free dup @ascuheap @acsmem
+@c   (re_)free dup @ascuheap @acsmem
+@c  re_string_destruct dup @ascuheap @acsmem
+@c libc_lock_unlock @aculock
+This function tries to match the compiled regular expression
+@code{*@var{compiled}} against @var{string}.
+
+@code{regexec} returns @code{0} if the regular expression matches;
+otherwise, it returns a nonzero value.  See the table below for
+what nonzero values mean.  You can use @code{regerror} to produce an
+error message string describing the reason for a nonzero value;
+see @ref{Regexp Cleanup}.
+
+The argument @var{eflags} is a word of bit flags that enable various
+options.
+
+If you want to get information about what part of @var{string} actually
+matched the regular expression or its subexpressions, use the arguments
+@var{matchptr} and @var{nmatch}.  Otherwise, pass @code{0} for
+@var{nmatch}, and @code{NULL} for @var{matchptr}.  @xref{Regexp
+Subexpressions}.
+@end deftypefun
+
+You must match the regular expression with the same set of current
+locales that were in effect when you compiled the regular expression.
+
+The function @code{regexec} accepts the following flags in the
+@var{eflags} argument:
+
+@table @code
+@comment regex.h
+@comment POSIX.2
+@item REG_NOTBOL
+Do not regard the beginning of the specified string as the beginning of
+a line; more generally, don't make any assumptions about what text might
+precede it.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_NOTEOL
+Do not regard the end of the specified string as the end of a line; more
+generally, don't make any assumptions about what text might follow it.
+@end table
+
+Here are the possible nonzero values that @code{regexec} can return:
+
+@table @code
+@comment regex.h
+@comment POSIX.2
+@item REG_NOMATCH
+The pattern didn't match the string.  This isn't really an error.
+
+@comment regex.h
+@comment POSIX.2
+@item REG_ESPACE
+@code{regexec} ran out of memory.
+@end table
+
+@node Regexp Subexpressions
+@subsection Match Results with Subexpressions
+
+When @code{regexec} matches parenthetical subexpressions of
+@var{pattern}, it records which parts of @var{string} they match.  It
+returns that information by storing the offsets into an array whose
+elements are structures of type @code{regmatch_t}.  The first element of
+the array (index @code{0}) records the part of the string that matched
+the entire regular expression.  Each other element of the array records
+the beginning and end of the part that matched a single parenthetical
+subexpression.
+
+@comment regex.h
+@comment POSIX.2
+@deftp {Data Type} regmatch_t
+This is the data type of the @var{matcharray} array that you pass to
+@code{regexec}.  It contains two structure fields, as follows:
+
+@table @code
+@item rm_so
+The offset in @var{string} of the beginning of a substring.  Add this
+value to @var{string} to get the address of that part.
+
+@item rm_eo
+The offset in @var{string} of the end of the substring.
+@end table
+@end deftp
+
+@comment regex.h
+@comment POSIX.2
+@deftp {Data Type} regoff_t
+@code{regoff_t} is an alias for another signed integer type.
+The fields of @code{regmatch_t} have type @code{regoff_t}.
+@end deftp
+
+The @code{regmatch_t} elements correspond to subexpressions
+positionally; the first element (index @code{1}) records where the first
+subexpression matched, the second element records the second
+subexpression, and so on.  The order of the subexpressions is the order
+in which they begin.
+
+When you call @code{regexec}, you specify how long the @var{matchptr}
+array is, with the @var{nmatch} argument.  This tells @code{regexec} how
+many elements to store.  If the actual regular expression has more than
+@var{nmatch} subexpressions, then you won't get offset information about
+the rest of them.  But this doesn't alter whether the pattern matches a
+particular string or not.
+
+If you don't want @code{regexec} to return any information about where
+the subexpressions matched, you can either supply @code{0} for
+@var{nmatch}, or use the flag @code{REG_NOSUB} when you compile the
+pattern with @code{regcomp}.
+
+@node Subexpression Complications
+@subsection Complications in Subexpression Matching
+
+Sometimes a subexpression matches a substring of no characters.  This
+happens when @samp{f\(o*\)} matches the string @samp{fum}.  (It really
+matches just the @samp{f}.)  In this case, both of the offsets identify
+the point in the string where the null substring was found.  In this
+example, the offsets are both @code{1}.
+
+Sometimes the entire regular expression can match without using some of
+its subexpressions at all---for example, when @samp{ba\(na\)*} matches the
+string @samp{ba}, the parenthetical subexpression is not used.  When
+this happens, @code{regexec} stores @code{-1} in both fields of the
+element for that subexpression.
+
+Sometimes matching the entire regular expression can match a particular
+subexpression more than once---for example, when @samp{ba\(na\)*}
+matches the string @samp{bananana}, the parenthetical subexpression
+matches three times.  When this happens, @code{regexec} usually stores
+the offsets of the last part of the string that matched the
+subexpression.  In the case of @samp{bananana}, these offsets are
+@code{6} and @code{8}.
+
+But the last match is not always the one that is chosen.  It's more
+accurate to say that the last @emph{opportunity} to match is the one
+that takes precedence.  What this means is that when one subexpression
+appears within another, then the results reported for the inner
+subexpression reflect whatever happened on the last match of the outer
+subexpression.  For an example, consider @samp{\(ba\(na\)*s \)*} matching
+the string @samp{bananas bas }.  The last time the inner expression
+actually matches is near the end of the first word.  But it is
+@emph{considered} again in the second word, and fails to match there.
+@code{regexec} reports nonuse of the ``na'' subexpression.
+
+Another place where this rule applies is when the regular expression
+@smallexample
+\(ba\(na\)*s \|nefer\(ti\)* \)*
+@end smallexample
+@noindent
+matches @samp{bananas nefertiti}.  The ``na'' subexpression does match
+in the first word, but it doesn't match in the second word because the
+other alternative is used there.  Once again, the second repetition of
+the outer subexpression overrides the first, and within that second
+repetition, the ``na'' subexpression is not used.  So @code{regexec}
+reports nonuse of the ``na'' subexpression.
+
+@node Regexp Cleanup
+@subsection POSIX Regexp Matching Cleanup
+
+When you are finished using a compiled regular expression, you can
+free the storage it uses by calling @code{regfree}.
+
+@comment regex.h
+@comment POSIX.2
+@deftypefun void regfree (regex_t *@var{compiled})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c (re_)free dup @ascuheap @acsmem
+@c free_dfa_content dup @ascuheap @acsmem
+Calling @code{regfree} frees all the storage that @code{*@var{compiled}}
+points to.  This includes various internal fields of the @code{regex_t}
+structure that aren't documented in this manual.
+
+@code{regfree} does not free the object @code{*@var{compiled}} itself.
+@end deftypefun
+
+You should always free the space in a @code{regex_t} structure with
+@code{regfree} before using the structure to compile another regular
+expression.
+
+When @code{regcomp} or @code{regexec} reports an error, you can use
+the function @code{regerror} to turn it into an error message string.
+
+@comment regex.h
+@comment POSIX.2
+@deftypefun size_t regerror (int @var{errcode}, const regex_t *restrict @var{compiled}, char *restrict @var{buffer}, size_t @var{length})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c regerror calls gettext, strcmp and mempcpy or memcpy.
+This function produces an error message string for the error code
+@var{errcode}, and stores the string in @var{length} bytes of memory
+starting at @var{buffer}.  For the @var{compiled} argument, supply the
+same compiled regular expression structure that @code{regcomp} or
+@code{regexec} was working with when it got the error.  Alternatively,
+you can supply @code{NULL} for @var{compiled}; you will still get a
+meaningful error message, but it might not be as detailed.
+
+If the error message can't fit in @var{length} bytes (including a
+terminating null character), then @code{regerror} truncates it.
+The string that @code{regerror} stores is always null-terminated
+even if it has been truncated.
+
+The return value of @code{regerror} is the minimum length needed to
+store the entire error message.  If this is less than @var{length}, then
+the error message was not truncated, and you can use it.  Otherwise, you
+should call @code{regerror} again with a larger buffer.
+
+Here is a function which uses @code{regerror}, but always dynamically
+allocates a buffer for the error message:
+
+@smallexample
+char *get_regerror (int errcode, regex_t *compiled)
+@{
+  size_t length = regerror (errcode, compiled, NULL, 0);
+  char *buffer = xmalloc (length);
+  (void) regerror (errcode, compiled, buffer, length);
+  return buffer;
+@}
+@end smallexample
+@end deftypefun
+
+@node Word Expansion
+@section Shell-Style Word Expansion
+@cindex word expansion
+@cindex expansion of shell words
+
+@dfn{Word expansion} means the process of splitting a string into
+@dfn{words} and substituting for variables, commands, and wildcards
+just as the shell does.
+
+For example, when you write @samp{ls -l foo.c}, this string is split
+into three separate words---@samp{ls}, @samp{-l} and @samp{foo.c}.
+This is the most basic function of word expansion.
+
+When you write @samp{ls *.c}, this can become many words, because
+the word @samp{*.c} can be replaced with any number of file names.
+This is called @dfn{wildcard expansion}, and it is also a part of
+word expansion.
+
+When you use @samp{echo $PATH} to print your path, you are taking
+advantage of @dfn{variable substitution}, which is also part of word
+expansion.
+
+Ordinary programs can perform word expansion just like the shell by
+calling the library function @code{wordexp}.
+
+@menu
+* 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.
+* Tilde Expansion::             Details of how tilde expansion works.
+* Variable Substitution::       Different types of variable substitution.
+@end menu
+
+@node Expansion Stages
+@subsection The Stages of Word Expansion
+
+When word expansion is applied to a sequence of words, it performs the
+following transformations in the order shown here:
+
+@enumerate
+@item
+@cindex tilde expansion
+@dfn{Tilde expansion}: Replacement of @samp{~foo} with the name of
+the home directory of @samp{foo}.
+
+@item
+Next, three different transformations are applied in the same step,
+from left to right:
+
+@itemize @bullet
+@item
+@cindex variable substitution
+@cindex substitution of variables and commands
+@dfn{Variable substitution}: Environment variables are substituted for
+references such as @samp{$foo}.
+
+@item
+@cindex command substitution
+@dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} and
+the equivalent @w{@samp{$(cat foo)}} are replaced with the output from
+the inner command.
+
+@item
+@cindex arithmetic expansion
+@dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} are
+replaced with the result of the arithmetic computation.
+@end itemize
+
+@item
+@cindex field splitting
+@dfn{Field splitting}: subdivision of the text into @dfn{words}.
+
+@item
+@cindex wildcard expansion
+@dfn{Wildcard expansion}: The replacement of a construct such as @samp{*.c}
+with a list of @samp{.c} file names.  Wildcard expansion applies to an
+entire word at a time, and replaces that word with 0 or more file names
+that are themselves words.
+
+@item
+@cindex quote removal
+@cindex removal of quotes
+@dfn{Quote removal}: The deletion of string-quotes, now that they have
+done their job by inhibiting the above transformations when appropriate.
+@end enumerate
+
+For the details of these transformations, and how to write the constructs
+that use them, see @w{@cite{The BASH Manual}} (to appear).
+
+@node Calling Wordexp
+@subsection Calling @code{wordexp}
+
+All the functions, constants and data types for word expansion are
+declared in the header file @file{wordexp.h}.
+
+Word expansion produces a vector of words (strings).  To return this
+vector, @code{wordexp} uses a special data type, @code{wordexp_t}, which
+is a structure.  You pass @code{wordexp} the address of the structure,
+and it fills in the structure's fields to tell you about the results.
+
+@comment wordexp.h
+@comment POSIX.2
+@deftp {Data Type} {wordexp_t}
+This data type holds a pointer to a word vector.  More precisely, it
+records both the address of the word vector and its size.
+
+@table @code
+@item we_wordc
+The number of elements in the vector.
+
+@item we_wordv
+The address of the vector.  This field has type @w{@code{char **}}.
+
+@item we_offs
+The offset of the first real element of the vector, from its nominal
+address in the @code{we_wordv} field.  Unlike the other fields, this
+is always an input to @code{wordexp}, rather than an output from it.
+
+If you use a nonzero offset, then that many elements at the beginning of
+the vector are left empty.  (The @code{wordexp} function fills them with
+null pointers.)
+
+The @code{we_offs} field is meaningful only if you use the
+@code{WRDE_DOOFFS} flag.  Otherwise, the offset is always zero
+regardless of what is in this field, and the first real element comes at
+the beginning of the vector.
+@end table
+@end deftp
+
+@comment wordexp.h
+@comment POSIX.2
+@deftypefun int wordexp (const char *@var{words}, wordexp_t *@var{word-vector-ptr}, int @var{flags})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtasuconst{:@mtsenv{}} @mtsenv{} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuintl{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c wordexp @mtasurace:utent @mtasuconst:@mtsenv @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuintl @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  w_newword ok
+@c  wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  calloc dup @ascuheap @acsmem
+@c  getenv dup @mtsenv
+@c  strcpy dup ok
+@c  parse_backslash @ascuheap @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c  parse_dollars @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c   parse_arith @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    w_newword dup ok
+@c    parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    parse_backtick dup @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c    parse_qtd_backslash dup @ascuheap @acsmem
+@c    eval_expr @mtslocale
+@c     eval_expr_multidiv @mtslocale
+@c      eval_expr_val @mtslocale
+@c       isspace dup @mtslocale
+@c       eval_expr dup @mtslocale
+@c      isspace dup @mtslocale
+@c     isspace dup @mtslocale
+@c    free dup @ascuheap @acsmem
+@c    w_addchar dup @ascuheap @acsmem
+@c    w_addstr dup @ascuheap @acsmem
+@c    itoa_word dup ok
+@c   parse_comm @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c    w_newword dup ok
+@c    pthread_setcancelstate @ascuplugin @ascuheap @acsmem
+@c      (disable cancellation around exec_comm; it may do_cancel the
+@c       second time, if async cancel is enabled)
+@c     THREAD_ATOMIC_CMPXCHG_VAL dup ok
+@c     CANCEL_ENABLED_AND_CANCELED_AND_ASYNCHRONOUS dup ok
+@c     do_cancel @ascuplugin @ascuheap @acsmem
+@c      THREAD_ATOMIC_BIT_SET dup ok
+@c      pthread_unwind @ascuplugin @ascuheap @acsmem
+@c       Unwind_ForcedUnwind if available @ascuplugin @ascuheap @acsmem
+@c       libc_unwind_longjmp otherwise
+@c       cleanups
+@c    exec_comm @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c     pipe2 dup ok
+@c     pipe dup ok
+@c     fork dup @ascuplugin @aculock
+@c     close dup @acsfd
+@c     on child: exec_comm_child -> exec or abort
+@c     waitpid dup ok
+@c     read dup ok
+@c     w_addmem dup @ascuheap @acsmem
+@c     strchr dup ok
+@c     w_addword dup @ascuheap @acsmem
+@c     w_newword dup ok
+@c     w_addchar dup @ascuheap @acsmem
+@c     free dup @ascuheap @acsmem
+@c     kill dup ok
+@c    free dup @ascuheap @acsmem
+@c   parse_param @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     reads from __libc_argc and __libc_argv without guards
+@c    w_newword dup ok
+@c    isalpha dup @mtslocale^^
+@c    w_addchar dup @ascuheap @acsmem
+@c    isalnum dup @mtslocale^^
+@c    isdigit dup @mtslocale^^
+@c    strchr dup ok
+@c    itoa_word dup ok
+@c    atoi dup @mtslocale
+@c    getpid dup ok
+@c    w_addstr dup @ascuheap @acsmem
+@c    free dup @ascuheap @acsmem
+@c    strlen dup ok
+@c    malloc dup @ascuheap @acsmem
+@c    stpcpy dup ok
+@c    w_addword dup @ascuheap @acsmem
+@c    strdup dup @ascuheap @acsmem
+@c    getenv dup @mtsenv
+@c    parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    parse_tilde dup @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    fnmatch dup @mtsenv @mtslocale @ascuheap @acsmem
+@c    mempcpy dup ok
+@c    _ dup @ascuintl
+@c    fxprintf dup @aculock
+@c    setenv dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c    strspn dup ok
+@c    strcspn dup ok
+@c  parse_backtick @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c   w_newword dup ok
+@c   exec_comm dup @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c   free dup @ascuheap @acsmem
+@c   parse_qtd_backslash dup @ascuheap @acsmem
+@c   parse_backslash dup @ascuheap @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c  parse_dquote @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   parse_backtick dup @ascuplugin @ascuheap @aculock @acsfd @acsmem
+@c   parse_qtd_backslash dup @ascuheap @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c  w_addword dup @ascuheap @acsmem
+@c   strdup dup @ascuheap @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  parse_squote dup @ascuheap @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c  parse_tilde @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   strchr dup ok
+@c   w_addchar dup @ascuheap @acsmem
+@c   getenv dup @mtsenv
+@c   w_addstr dup @ascuheap @acsmem
+@c    strlen dup ok
+@c    w_addmem dup @ascuheap @acsmem
+@c     realloc dup @ascuheap @acsmem
+@c     free dup @ascuheap @acsmem
+@c     mempcpy dup ok
+@c   getuid dup ok
+@c   getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  parse_glob @mtasurace:utent @mtasuconst:@mtsenv @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   strchr dup ok
+@c   parse_dollars dup @mtasuconst:@mtsenv @mtslocale @mtsenv @ascudlopen @ascuplugin @ascuintl @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   parse_qtd_backslash @ascuheap @acsmem
+@c    w_addchar dup @ascuheap @acsmem
+@c   parse_backslash dup @ascuheap @acsmem
+@c   w_addchar dup @ascuheap @acsmem
+@c   w_addword dup @ascuheap @acsmem
+@c   w_newword dup ok
+@c   do_parse_glob @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem
+@c    glob dup @mtasurace:utent @mtsenv @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem [auto glob_t avoids @asucorrupt @acucorrupt]
+@c    w_addstr dup @ascuheap @acsmem
+@c    w_addchar dup @ascuheap @acsmem
+@c    globfree dup @ascuheap @acsmem [auto glob_t avoids @asucorrupt @acucorrupt]
+@c    free dup @ascuheap @acsmem
+@c    w_newword dup ok
+@c    strdup dup @ascuheap @acsmem
+@c    w_addword dup @ascuheap @acsmem
+@c   wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  strchr dup ok
+@c  w_addchar dup @ascuheap @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+Perform word expansion on the string @var{words}, putting the result in
+a newly allocated vector, and store the size and address of this vector
+into @code{*@var{word-vector-ptr}}.  The argument @var{flags} is a
+combination of bit flags; see @ref{Flags for Wordexp}, for details of
+the flags.
+
+You shouldn't use any of the characters @samp{|&;<>} in the string
+@var{words} unless they are quoted; likewise for newline.  If you use
+these characters unquoted, you will get the @code{WRDE_BADCHAR} error
+code.  Don't use parentheses or braces unless they are quoted or part of
+a word expansion construct.  If you use quotation characters @samp{'"`},
+they should come in pairs that balance.
+
+The results of word expansion are a sequence of words.  The function
+@code{wordexp} allocates a string for each resulting word, then
+allocates a vector of type @code{char **} to store the addresses of
+these strings.  The last element of the vector is a null pointer.
+This vector is called the @dfn{word vector}.
+
+To return this vector, @code{wordexp} stores both its address and its
+length (number of elements, not counting the terminating null pointer)
+into @code{*@var{word-vector-ptr}}.
+
+If @code{wordexp} succeeds, it returns 0.  Otherwise, it returns one
+of these error codes:
+
+@table @code
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_BADCHAR
+The input string @var{words} contains an unquoted invalid character such
+as @samp{|}.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_BADVAL
+The input string refers to an undefined shell variable, and you used the flag
+@code{WRDE_UNDEF} to forbid such references.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_CMDSUB
+The input string uses command substitution, and you used the flag
+@code{WRDE_NOCMD} to forbid command substitution.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_NOSPACE
+It was impossible to allocate memory to hold the result.  In this case,
+@code{wordexp} can store part of the results---as much as it could
+allocate room for.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_SYNTAX
+There was a syntax error in the input string.  For example, an unmatched
+quoting character is a syntax error.  This error code is also used to
+signal division by zero and overflow in arithmetic expansion.
+@end table
+@end deftypefun
+
+@comment wordexp.h
+@comment POSIX.2
+@deftypefun void wordfree (wordexp_t *@var{word-vector-ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c wordfree dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  free dup @ascuheap @acsmem
+Free the storage used for the word-strings and vector that
+@code{*@var{word-vector-ptr}} points to.  This does not free the
+structure @code{*@var{word-vector-ptr}} itself---only the other
+data it points to.
+@end deftypefun
+
+@node Flags for Wordexp
+@subsection Flags for Word Expansion
+
+This section describes the flags that you can specify in the
+@var{flags} argument to @code{wordexp}.  Choose the flags you want,
+and combine them with the C operator @code{|}.
+
+@table @code
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_APPEND
+Append the words from this expansion to the vector of words produced by
+previous calls to @code{wordexp}.  This way you can effectively expand
+several words as if they were concatenated with spaces between them.
+
+In order for appending to work, you must not modify the contents of the
+word vector structure between calls to @code{wordexp}.  And, if you set
+@code{WRDE_DOOFFS} in the first call to @code{wordexp}, you must also
+set it when you append to the results.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_DOOFFS
+Leave blank slots at the beginning of the vector of words.
+The @code{we_offs} field says how many slots to leave.
+The blank slots contain null pointers.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_NOCMD
+Don't do command substitution; if the input requests command substitution,
+report an error.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_REUSE
+Reuse a word vector made by a previous call to @code{wordexp}.
+Instead of allocating a new vector of words, this call to @code{wordexp}
+will use the vector that already exists (making it larger if necessary).
+
+Note that the vector may move, so it is not safe to save an old pointer
+and use it again after calling @code{wordexp}.  You must fetch
+@code{we_pathv} anew after each call.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_SHOWERR
+Do show any error messages printed by commands run by command substitution.
+More precisely, allow these commands to inherit the standard error output
+stream of the current process.  By default, @code{wordexp} gives these
+commands a standard error stream that discards all output.
+
+@comment wordexp.h
+@comment POSIX.2
+@item WRDE_UNDEF
+If the input refers to a shell variable that is not defined, report an
+error.
+@end table
+
+@node Wordexp Example
+@subsection @code{wordexp} Example
+
+Here is an example of using @code{wordexp} to expand several strings
+and use the results to run a shell command.  It also shows the use of
+@code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
+to free the space allocated by @code{wordexp}.
+
+@smallexample
+int
+expand_and_execute (const char *program, const char **options)
+@{
+  wordexp_t result;
+  pid_t pid
+  int status, i;
+
+  /* @r{Expand the string for the program to run.}  */
+  switch (wordexp (program, &result, 0))
+    @{
+    case 0:			/* @r{Successful}.  */
+      break;
+    case WRDE_NOSPACE:
+      /* @r{If the error was @code{WRDE_NOSPACE},}
+         @r{then perhaps part of the result was allocated.}  */
+      wordfree (&result);
+    default:                    /* @r{Some other error.}  */
+      return -1;
+    @}
+
+  /* @r{Expand the strings specified for the arguments.}  */
+  for (i = 0; options[i] != NULL; i++)
+    @{
+      if (wordexp (options[i], &result, WRDE_APPEND))
+        @{
+          wordfree (&result);
+          return -1;
+        @}
+    @}
+
+  pid = fork ();
+  if (pid == 0)
+    @{
+      /* @r{This is the child process.  Execute the command.} */
+      execv (result.we_wordv[0], result.we_wordv);
+      exit (EXIT_FAILURE);
+    @}
+  else if (pid < 0)
+    /* @r{The fork failed.  Report failure.}  */
+    status = -1;
+  else
+    /* @r{This is the parent process.  Wait for the child to complete.}  */
+    if (waitpid (pid, &status, 0) != pid)
+      status = -1;
+
+  wordfree (&result);
+  return status;
+@}
+@end smallexample
+
+@node Tilde Expansion
+@subsection Details of Tilde Expansion
+
+It's a standard part of shell syntax that you can use @samp{~} at the
+beginning of a file name to stand for your own home directory.  You
+can use @samp{~@var{user}} to stand for @var{user}'s home directory.
+
+@dfn{Tilde expansion} is the process of converting these abbreviations
+to the directory names that they stand for.
+
+Tilde expansion applies to the @samp{~} plus all following characters up
+to whitespace or a slash.  It takes place only at the beginning of a
+word, and only if none of the characters to be transformed is quoted in
+any way.
+
+Plain @samp{~} uses the value of the environment variable @code{HOME}
+as the proper home directory name.  @samp{~} followed by a user name
+uses @code{getpwname} to look up that user in the user database, and
+uses whatever directory is recorded there.  Thus, @samp{~} followed
+by your own name can give different results from plain @samp{~}, if
+the value of @code{HOME} is not really your home directory.
+
+@node Variable Substitution
+@subsection Details of Variable Substitution
+
+Part of ordinary shell syntax is the use of @samp{$@var{variable}} to
+substitute the value of a shell variable into a command.  This is called
+@dfn{variable substitution}, and it is one part of doing word expansion.
+
+There are two basic ways you can write a variable reference for
+substitution:
+
+@table @code
+@item $@{@var{variable}@}
+If you write braces around the variable name, then it is completely
+unambiguous where the variable name ends.  You can concatenate
+additional letters onto the end of the variable value by writing them
+immediately after the close brace.  For example, @samp{$@{foo@}s}
+expands into @samp{tractors}.
+
+@item $@var{variable}
+If you do not put braces around the variable name, then the variable
+name consists of all the alphanumeric characters and underscores that
+follow the @samp{$}.  The next punctuation character ends the variable
+name.  Thus, @samp{$foo-bar} refers to the variable @code{foo} and expands
+into @samp{tractor-bar}.
+@end table
+
+When you use braces, you can also use various constructs to modify the
+value that is substituted, or test it in various ways.
+
+@table @code
+@item $@{@var{variable}:-@var{default}@}
+Substitute the value of @var{variable}, but if that is empty or
+undefined, use @var{default} instead.
+
+@item $@{@var{variable}:=@var{default}@}
+Substitute the value of @var{variable}, but if that is empty or
+undefined, use @var{default} instead and set the variable to
+@var{default}.
+
+@item $@{@var{variable}:?@var{message}@}
+If @var{variable} is defined and not empty, substitute its value.
+
+Otherwise, print @var{message} as an error message on the standard error
+stream, and consider word expansion a failure.
+
+@c ??? How does wordexp report such an error?
+@c WRDE_BADVAL is returned.
+
+@item $@{@var{variable}:+@var{replacement}@}
+Substitute @var{replacement}, but only if @var{variable} is defined and
+nonempty.  Otherwise, substitute nothing for this construct.
+@end table
+
+@table @code
+@item $@{#@var{variable}@}
+Substitute a numeral which expresses in base ten the number of
+characters in the value of @var{variable}.  @samp{$@{#foo@}} stands for
+@samp{7}, because @samp{tractor} is seven characters.
+@end table
+
+These variants of variable substitution let you remove part of the
+variable's value before substituting it.  The @var{prefix} and
+@var{suffix} are not mere strings; they are wildcard patterns, just
+like the patterns that you use to match multiple file names.  But
+in this context, they match against parts of the variable value
+rather than against file names.
+
+@table @code
+@item $@{@var{variable}%%@var{suffix}@}
+Substitute the value of @var{variable}, but first discard from that
+variable any portion at the end that matches the pattern @var{suffix}.
+
+If there is more than one alternative for how to match against
+@var{suffix}, this construct uses the longest possible match.
+
+Thus, @samp{$@{foo%%r*@}} substitutes @samp{t}, because the largest
+match for @samp{r*} at the end of @samp{tractor} is @samp{ractor}.
+
+@item $@{@var{variable}%@var{suffix}@}
+Substitute the value of @var{variable}, but first discard from that
+variable any portion at the end that matches the pattern @var{suffix}.
+
+If there is more than one alternative for how to match against
+@var{suffix}, this construct uses the shortest possible alternative.
+
+Thus, @samp{$@{foo%r*@}} substitutes @samp{tracto}, because the shortest
+match for @samp{r*} at the end of @samp{tractor} is just @samp{r}.
+
+@item $@{@var{variable}##@var{prefix}@}
+Substitute the value of @var{variable}, but first discard from that
+variable any portion at the beginning that matches the pattern @var{prefix}.
+
+If there is more than one alternative for how to match against
+@var{prefix}, this construct uses the longest possible match.
+
+Thus, @samp{$@{foo##*t@}} substitutes @samp{or}, because the largest
+match for @samp{*t} at the beginning of @samp{tractor} is @samp{tract}.
+
+@item $@{@var{variable}#@var{prefix}@}
+Substitute the value of @var{variable}, but first discard from that
+variable any portion at the beginning that matches the pattern @var{prefix}.
+
+If there is more than one alternative for how to match against
+@var{prefix}, this construct uses the shortest possible alternative.
+
+Thus, @samp{$@{foo#*t@}} substitutes @samp{ractor}, because the shortest
+match for @samp{*t} at the beginning of @samp{tractor} is just @samp{t}.
+
+@end table
diff --git a/ap/libc/glibc/glibc-2.23/manual/pipe.texi b/ap/libc/glibc/glibc-2.23/manual/pipe.texi
new file mode 100644
index 0000000..2d7e30e
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/pipe.texi
@@ -0,0 +1,319 @@
+@node Pipes and FIFOs, Sockets, File System Interface, Top
+@c %MENU% A simple interprocess communication mechanism
+@chapter Pipes and FIFOs
+
+@cindex pipe
+A @dfn{pipe} is a mechanism for interprocess communication; data written
+to the pipe by one process can be read by another process.  The data is
+handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
+is created for one use and both ends must be inherited from the single
+process which created the pipe.
+
+@cindex FIFO special file
+A @dfn{FIFO special file} is similar to a pipe, but instead of being an
+anonymous, temporary connection, a FIFO has a name or names like any
+other file.  Processes open the FIFO by name in order to communicate
+through it.
+
+A pipe or FIFO has to be open at both ends simultaneously.  If you read
+from a pipe or FIFO file that doesn't have any processes writing to it
+(perhaps because they have all closed the file, or exited), the read
+returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
+reading process is treated as an error condition; it generates a
+@code{SIGPIPE} signal, and fails with error code @code{EPIPE} if the
+signal is handled or blocked.
+
+Neither pipes nor FIFO special files allow file positioning.  Both
+reading and writing operations happen sequentially; reading from the
+beginning of the file and writing at the end.
+
+@menu
+* Creating a Pipe::             Making a pipe with the @code{pipe} function.
+* Pipe to a Subprocess::        Using a pipe to communicate with a
+				 child process.
+* FIFO Special Files::          Making a FIFO special file.
+* Pipe Atomicity::		When pipe (or FIFO) I/O is atomic.
+@end menu
+
+@node Creating a Pipe
+@section Creating a Pipe
+@cindex creating a pipe
+@cindex opening a pipe
+@cindex interprocess communication, with pipes
+
+The primitive for creating a pipe is the @code{pipe} function.  This
+creates both the reading and writing ends of the pipe.  It is not very
+useful for a single process to use a pipe to talk to itself.  In typical
+use, a process creates a pipe just before it forks one or more child
+processes (@pxref{Creating a Process}).  The pipe is then used for
+communication either between the parent or child processes, or between
+two sibling processes.
+
+The @code{pipe} function is declared in the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int pipe (int @var{filedes}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c On Linux, syscall pipe2.  On HURD, call socketpair.
+The @code{pipe} function creates a pipe and puts the file descriptors
+for the reading and writing ends of the pipe (respectively) into
+@code{@var{filedes}[0]} and @code{@var{filedes}[1]}.
+
+An easy way to remember that the input end comes first is that file
+descriptor @code{0} is standard input, and file descriptor @code{1} is
+standard output.
+
+If successful, @code{pipe} returns a value of @code{0}.  On failure,
+@code{-1} is returned.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EMFILE
+The process has too many files open.
+
+@item ENFILE
+There are too many open files in the entire system.  @xref{Error Codes},
+for more information about @code{ENFILE}.  This error never occurs on
+@gnuhurdsystems{}.
+@end table
+@end deftypefun
+
+Here is an example of a simple program that creates a pipe.  This program
+uses the @code{fork} function (@pxref{Creating a Process}) to create
+a child process.  The parent process writes data to the pipe, which is
+read by the child process.
+
+@smallexample
+@include pipe.c.texi
+@end smallexample
+
+@node Pipe to a Subprocess
+@section Pipe to a Subprocess
+@cindex creating a pipe to a subprocess
+@cindex pipe to a subprocess
+@cindex filtering i/o through subprocess
+
+A common use of pipes is to send data to or receive data from a program
+being run as a subprocess.  One way of doing this is by using a combination of
+@code{pipe} (to create the pipe), @code{fork} (to create the subprocess),
+@code{dup2} (to force the subprocess to use the pipe as its standard input
+or output channel), and @code{exec} (to execute the new program).  Or,
+you can use @code{popen} and @code{pclose}.
+
+The advantage of using @code{popen} and @code{pclose} is that the
+interface is much simpler and easier to use.  But it doesn't offer as
+much flexibility as using the low-level functions directly.
+
+@comment stdio.h
+@comment POSIX.2, SVID, BSD
+@deftypefun {FILE *} popen (const char *@var{command}, const char *@var{mode})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c popen @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
+@c  malloc dup @ascuheap @acsmem
+@c  _IO_init ok
+@c   _IO_no_init ok
+@c    _IO_old_init ok
+@c     _IO_lock_init ok
+@c  _IO_new_file_init @asucorrupt @acucorrupt @aculock @acsfd
+@c   _IO_link_in @asucorrupt @acucorrupt @aculock @acsfd
+@c     the linked list is guarded by a recursive lock;
+@c     it may get corrupted with async signals and cancellation
+@c    _IO_lock_lock dup @aculock
+@c    _IO_flockfile dup @aculock
+@c    _IO_funlockfile dup @aculock
+@c    _IO_lock_unlock dup @aculock
+@c  _IO_new_proc_open @asucorrupt @acucorrupt @aculock @acsfd
+@c    the linked list is guarded by a recursive lock;
+ @c   it may get corrupted with async signals and cancellation
+@c   _IO_file_is_open ok
+@c   pipe2 dup @acsfd
+@c   pipe dup @acsfd
+@c   _IO_fork=fork @aculock
+@c   _IO_close=close_not_cancel dup @acsfd
+@c   fcntl dup ok
+@c   _IO_lock_lock @aculock
+@c   _IO_lock_unlock @aculock
+@c   _IO_mask_flags ok [no @mtasurace:stream, nearly but sufficiently exclusive access]
+@c  _IO_un_link @asucorrupt @acucorrupt @aculock @acsfd
+@c    the linked list is guarded by a recursive lock;
+@c    it may get corrupted with async signals and cancellation
+@c   _IO_lock_lock dup @aculock
+@c   _IO_flockfile dup @aculock
+@c   _IO_funlockfile dup @aculock
+@c   _IO_lock_unlock dup @aculock
+@c  free dup @ascuheap @acsmem
+The @code{popen} function is closely related to the @code{system}
+function; see @ref{Running a Command}.  It executes the shell command
+@var{command} as a subprocess.  However, instead of waiting for the
+command to complete, it creates a pipe to the subprocess and returns a
+stream that corresponds to that pipe.
+
+If you specify a @var{mode} argument of @code{"r"}, you can read from the
+stream to retrieve data from the standard output channel of the subprocess.
+The subprocess inherits its standard input channel from the parent process.
+
+Similarly, if you specify a @var{mode} argument of @code{"w"}, you can
+write to the stream to send data to the standard input channel of the
+subprocess.  The subprocess inherits its standard output channel from
+the parent process.
+
+In the event of an error @code{popen} returns a null pointer.  This
+might happen if the pipe or stream cannot be created, if the subprocess
+cannot be forked, or if the program cannot be executed.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX.2, SVID, BSD
+@deftypefun int pclose (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuplugin{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c Although the stream cannot be used after the call, even in case of
+@c async cancellation, because the stream must not be used after pclose
+@c is called, other stdio linked lists and their locks may be left in
+@c corrupt states; that's where the corrupt and lock annotations come
+@c from.
+@c
+@c pclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  _IO_new_fclose @ascuheap @ascuplugin @asucorrupt @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
+@c   _IO_acquire_lock dup @aculock
+@c    _IO_flockfile dup @aculock
+@c   _IO_file_close_it @ascuheap @ascuplugin @asucorrupt @aculock @acucorrupt @acsfd @acsmem
+@c    _IO_file_is_open dup ok
+@c    _IO_do_flush @asucorrupt @ascuplugin @acucorrupt
+@c     _IO_do_write @asucorrupt @acucorrupt
+@c      new_do_write @asucorrupt @acucorrupt
+@c       _IO_SYSSEEK ok
+@c        lseek64 dup ok
+@c       _IO_SYSWRITE ok
+@c        write_not_cancel dup ok
+@c        write dup ok
+@c       _IO_adjust_column ok
+@c       _IO_setg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c     _IO_wdo_write @asucorrupt @ascuplugin @acucorrupt
+@c      _IO_new_do_write=_IO_do_write dup @asucorrupt @acucorrupt
+@c      *cc->__codecvt_do_out @ascuplugin
+@c      _IO_wsetg dup @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_unsave_markers @ascuheap @asucorrupt @acucorrupt @acsmem
+@c     _IO_have_backup dup ok
+@c     _IO_free_backup_area dup @ascuheap @asucorrupt @acucorrupt @acsmem
+@c    _IO_SYSCLOSE @aculock @acucorrupt @acsfd
+@c     _IO_lock_lock dup @aculock
+@c     _IO_close=close_not_cancel dup @acsfd
+@c     _IO_lock_unlock dup @aculock
+@c     _IO_waitpid=waitpid_not_cancel dup ok
+@c    _IO_have_wbackup ok
+@c    _IO_free_wbackup_area @ascuheap @asucorrupt @acucorrupt @acsmem
+@c     _IO_in_backup dup ok
+@c     _IO_switch_to_main_wget_area @asucorrupt @acucorrupt
+@c     free dup @ascuheap @acsmem
+@c    _IO_wsetb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_wsetg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_wsetp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_setb @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_setg @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_setp @asucorrupt @acucorrupt [no @mtasurace:stream, locked]
+@c    _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
+@c   _IO_release_lock dup @aculock
+@c    _IO_funlockfile dup @aculock
+@c   _IO_FINISH @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
+@c    _IO_new_file_finish @ascuheap @ascuplugin @asucorrupt @acucorrupt @aculock @acsfd @acsmem
+@c     _IO_file_is_open dup ok
+@c     _IO_do_flush dup @ascuplugin @asucorrupt @acucorrupt
+@c     _IO_SYSCLOSE dup @aculock @acucorrupt @acsfd
+@c     _IO_default_finish @ascuheap @asucorrupt @acucorrupt @aculock @acsfd @acsmem
+@c      FREE_BUF @acsmem
+@c       munmap dup @acsmem
+@c      free dup @ascuheap @acsmem
+@c      _IO_un_link dup @asucorrupt @acucorrupt @aculock @acsfd
+@c      _IO_lock_fini ok
+@c       libc_lock_fini_recursive ok
+@c   libc_lock_lock dup @asulock @aculock
+@c   gconv_release_step ok
+@c   libc_lock_unlock dup @asulock @aculock
+@c   _IO_have_backup ok
+@c   _IO_free_backup_area @ascuheap @asucorrupt @acucorrupt @acsmem
+@c    _IO_in_backup ok
+@c    _IO_switch_to_main_get_area @asucorrupt @acucorrupt
+@c    free dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+The @code{pclose} function is used to close a stream created by @code{popen}.
+It waits for the child process to terminate and returns its status value,
+as for the @code{system} function.
+@end deftypefun
+
+Here is an example showing how to use @code{popen} and @code{pclose} to
+filter output through another program, in this case the paging program
+@code{more}.
+
+@smallexample
+@include popen.c.texi
+@end smallexample
+
+@node FIFO Special Files
+@section FIFO Special Files
+@cindex creating a FIFO special file
+@cindex interprocess communication, with FIFO
+
+A FIFO special file is similar to a pipe, except that it is created in a
+different way.  Instead of being an anonymous communications channel, a
+FIFO special file is entered into the file system by calling
+@code{mkfifo}.
+
+Once you have created a FIFO special file in this way, any process can
+open it for reading or writing, in the same way as an ordinary file.
+However, it has to be open at both ends simultaneously before you can
+proceed to do any input or output operations on it.  Opening a FIFO for
+reading normally blocks until some other process opens the same FIFO for
+writing, and vice versa.
+
+The @code{mkfifo} function is declared in the header file
+@file{sys/stat.h}.
+@pindex sys/stat.h
+
+@comment sys/stat.h
+@comment POSIX.1
+@deftypefun int mkfifo (const char *@var{filename}, mode_t @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On generic Posix, calls xmknod.
+The @code{mkfifo} function makes a FIFO special file with name
+@var{filename}.  The @var{mode} argument is used to set the file's
+permissions; see @ref{Setting Permissions}.
+
+The normal, successful return value from @code{mkfifo} is @code{0}.  In
+the case of an error, @code{-1} is returned.  In addition to the usual
+file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EEXIST
+The named file already exists.
+
+@item ENOSPC
+The directory or file system cannot be extended.
+
+@item EROFS
+The directory that would contain the file resides on a read-only file
+system.
+@end table
+@end deftypefun
+
+@node Pipe Atomicity
+@section Atomicity of Pipe I/O
+
+Reading or writing pipe data is @dfn{atomic} if the size of data written
+is not greater than @code{PIPE_BUF}.  This means that the data transfer
+seems to be an instantaneous unit, in that nothing else in the system
+can observe a state in which it is partially complete.  Atomic I/O may
+not begin right away (it may need to wait for buffer space or for data),
+but once it does begin it finishes immediately.
+
+Reading or writing a larger amount of data may not be atomic; for
+example, output data from other processes sharing the descriptor may be
+interspersed.  Also, once @code{PIPE_BUF} characters have been written,
+further writes will block until some characters are read.
+
+@xref{Limits for Files}, for information about the @code{PIPE_BUF}
+parameter.
diff --git a/ap/libc/glibc/glibc-2.23/manual/platform.texi b/ap/libc/glibc/glibc-2.23/manual/platform.texi
new file mode 100644
index 0000000..cb16664
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/platform.texi
@@ -0,0 +1,117 @@
+@node Platform, Contributors, Maintenance, Top
+@c %MENU% Describe all platform-specific facilities provided
+@appendix Platform-specific facilities
+
+@Theglibc{} can provide machine-specific functionality.
+
+@menu
+* PowerPC::           Facilities Specific to the PowerPC Architecture
+@end menu
+
+@node PowerPC
+@appendixsec PowerPC-specific Facilities
+
+Facilities specific to PowerPC that are not specific to a particular
+operating system are declared in @file{sys/platform/ppc.h}.
+
+@deftypefun {uint64_t} __ppc_get_timebase (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Read the current value of the Time Base Register.
+
+The @dfn{Time Base Register} is a 64-bit register that stores a monotonically
+incremented value updated at a system-dependent frequency that may be
+different from the processor frequency.  More information is available in
+@cite{Power ISA 2.06b - Book II - Section 5.2}.
+
+@code{__ppc_get_timebase} uses the processor's time base facility directly
+without requiring assistance from the operating system, so it is very
+efficient.
+@end deftypefun
+
+@deftypefun {uint64_t} __ppc_get_timebase_freq (void)
+@safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asucorrupt{:init}}@acunsafe{@acucorrupt{:init}}}
+@c __ppc_get_timebase_freq=__get_timebase_freq @mtuinit @acsfd
+@c  __get_clockfreq @mtuinit @asucorrupt:init @acucorrupt:init @acsfd
+@c    the initialization of the static timebase_freq is not exactly
+@c    safe, because hp_timing_t cannot be atomically set up.
+@c   syscall:get_tbfreq ok
+@c   open dup @acsfd
+@c   read dup ok
+@c   memcpy dup ok
+@c   memmem dup ok
+@c   close dup @acsfd
+Read the current frequency at which the Time Base Register is updated.
+
+This frequency is not related to the processor clock or the bus clock.
+It is also possible that this frequency is not constant.  More information is
+available in @cite{Power ISA 2.06b - Book II - Section 5.2}.
+@end deftypefun
+
+The following functions provide hints about the usage of resources that are
+shared with other processors.  They can be used, for example, if a program
+waiting on a lock intends to divert the shared resources to be used by other
+processors.  More information is available in @cite{Power ISA 2.06b - Book II -
+Section 3.2}.
+
+@deftypefun {void} __ppc_yield (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Provide a hint that performance will probably be improved if shared resources
+dedicated to the executing processor are released for use by other processors.
+@end deftypefun
+
+@deftypefun {void} __ppc_mdoio (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Provide a hint that performance will probably be improved if shared resources
+dedicated to the executing processor are released until all outstanding storage
+accesses to caching-inhibited storage have been completed.
+@end deftypefun
+
+@deftypefun {void} __ppc_mdoom (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Provide a hint that performance will probably be improved if shared resources
+dedicated to the executing processor are released until all outstanding storage
+accesses to cacheable storage for which the data is not in the cache have been
+completed.
+@end deftypefun
+
+@deftypefun {void} __ppc_set_ppr_med (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the Program Priority Register to medium value (default).
+
+The @dfn{Program Priority Register} (PPR) is a 64-bit register that controls
+the program's priority.  By adjusting the PPR value the programmer may
+improve system throughput by causing the system resources to be used
+more efficiently, especially in contention situations.
+The three unprivileged states available are covered by the functions
+@code{__ppc_set_ppr_med} (medium -- default), @code{__ppc_set_ppc_low} (low)
+and @code{__ppc_set_ppc_med_low} (medium low).  More information
+available in @cite{Power ISA 2.06b - Book II - Section 3.1}.
+@end deftypefun
+
+@deftypefun {void} __ppc_set_ppr_low (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the Program Priority Register to low value.
+@end deftypefun
+
+@deftypefun {void} __ppc_set_ppr_med_low (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the Program Priority Register to medium low value.
+@end deftypefun
+
+Power ISA 2.07 extends the priorities that can be set to the Program Priority
+Register (PPR).  The following functions implement the new priority levels:
+very low and medium high.
+
+@deftypefun {void} __ppc_set_ppr_very_low (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the Program Priority Register to very low value.
+@end deftypefun
+
+@deftypefun {void} __ppc_set_ppr_med_high (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Set the Program Priority Register to medium high value.  The medium high
+priority is privileged and may only be set during certain time intervals by
+problem-state programs.  If the program priority is medium high when the time
+interval expires or if an attempt is made to set the priority to medium high
+when it is not allowed, the priority is set to medium.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/probes.texi b/ap/libc/glibc/glibc-2.23/manual/probes.texi
new file mode 100644
index 0000000..7dd56d8
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/probes.texi
@@ -0,0 +1,416 @@
+@node Internal Probes
+@c @node Internal Probes, , POSIX Threads, Top
+@c %MENU% Probes to monitor libc internal behavior
+@chapter Internal probes
+
+In order to aid in debugging and monitoring internal behavior,
+@theglibc{} exposes nearly-zero-overhead SystemTap probes marked with
+the @code{libc} provider.
+
+These probes are not part of the @glibcadj{} stable ABI, and they are
+subject to change or removal across releases.  Our only promise with
+regard to them is that, if we find a need to remove or modify the
+arguments of a probe, the modified probe will have a different name, so
+that program monitors relying on the old probe will not get unexpected
+arguments.
+
+@menu
+* Memory Allocation Probes::  Probes in the memory allocation subsystem
+* Mathematical Function Probes::  Probes in mathematical functions
+* Non-local Goto Probes::  Probes in setjmp and longjmp
+@end menu
+
+@node Memory Allocation Probes
+@section Memory Allocation Probes
+
+These probes are designed to signal relatively unusual situations within
+the virtual memory subsystem of @theglibc{}.
+
+@deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered after the main arena is extended by calling
+@code{sbrk}.  Argument @var{$arg1} is the additional size requested to
+@code{sbrk}, and @var{$arg2} is the pointer that marks the end of the
+@code{sbrk} area, returned in response to the request.
+@end deftp
+
+@deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered after the size of the main arena is decreased by
+calling @code{sbrk}.  Argument @var{$arg1} is the size released by
+@code{sbrk} (the positive value, rather than the negative value passed
+to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of
+the @code{sbrk} area, returned in response to the request.
+@end deftp
+
+@deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered after a new heap is @code{mmap}ed.  Argument
+@var{$arg1} is a pointer to the base of the memory area, where the
+@code{heap_info} data structure is held, and @var{$arg2} is the size of
+the heap.
+@end deftp
+
+@deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered @emph{before} (unlike the other sbrk and heap
+probes) a heap is completely removed via @code{munmap}.  Argument
+@var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the
+heap.
+@end deftp
+
+@deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered after a trailing portion of an @code{mmap}ed
+heap is extended.  Argument @var{$arg1} is a pointer to the heap, and
+@var{$arg2} is the new size of the heap.
+@end deftp
+
+@deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered after a trailing portion of an @code{mmap}ed
+heap is released.  Argument @var{$arg1} is a pointer to the heap, and
+@var{$arg2} is the new size of the heap.
+@end deftp
+
+@deftp Probe memory_malloc_retry (size_t @var{$arg1})
+@deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2})
+@deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2})
+@deftpx Probe memory_calloc_retry (size_t @var{$arg1})
+These probes are triggered when the corresponding functions fail to
+obtain the requested amount of memory from the arena in use, before they
+call @code{arena_get_retry} to select an alternate arena in which to
+retry the allocation.  Argument @var{$arg1} is the amount of memory
+requested by the user; in the @code{calloc} case, that is the total size
+computed from both function arguments.  In the @code{realloc} case,
+@var{$arg2} is the pointer to the memory area being resized.  In the
+@code{memalign} case, @var{$arg2} is the alignment to be used for the
+request, which may be stricter than the value passed to the
+@code{memalign} function.  A @code{memalign} probe is also used by functions
+@code{posix_memalign, valloc} and @code{pvalloc}.
+
+Note that the argument order does @emph{not} match that of the
+corresponding two-argument functions, so that in all of these probes the
+user-requested allocation size is in @var{$arg1}.
+@end deftp
+
+@deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
+This probe is triggered within @code{arena_get_retry} (the function
+called to select the alternate arena in which to retry an allocation
+that failed on the first attempt), before the selection of an alternate
+arena.  This probe is redundant, but much easier to use when it's not
+important to determine which of the various memory allocation functions
+is failing to allocate on the first try.  Argument @var{$arg1} is the
+same as in the function-specific probes, except for extra room for
+padding introduced by functions that have to ensure stricter alignment.
+Argument @var{$arg2} is the arena in which allocation failed.
+@end deftp
+
+@deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
+This probe is triggered when @code{malloc} allocates and initializes an
+additional arena (not the main arena), but before the arena is assigned
+to the running thread or inserted into the internal linked list of
+arenas.  The arena's @code{malloc_state} internal data structure is
+located at @var{$arg1}, within a newly-allocated heap big enough to hold
+at least @var{$arg2} bytes.
+@end deftp
+
+@deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
+This probe is triggered when @code{malloc} has just selected an existing
+arena to reuse, and (temporarily) reserved it for exclusive use.
+Argument @var{$arg1} is a pointer to the newly-selected arena, and
+@var{$arg2} is a pointer to the arena previously used by that thread.
+
+This occurs within
+@code{reused_arena}, right after the mutex mentioned in probe
+@code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
+point to the same arena.  In this configuration, this will usually only
+occur once per thread.  The exception is when a thread first selected
+the main arena, but a subsequent allocation from it fails: then, and
+only then, may we switch to another arena to retry that allocations, and
+for further allocations within that thread.
+@end deftp
+
+@deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
+This probe is triggered when @code{malloc} is about to wait for an arena
+to become available for reuse.  Argument @var{$arg1} holds a pointer to
+the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
+newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
+arena previously used by that thread.
+
+This occurs within
+@code{reused_arena}, when a thread first tries to allocate memory or
+needs a retry after a failure to allocate from the main arena, there
+isn't any free arena, the maximum number of arenas has been reached, and
+an existing arena was chosen for reuse, but its mutex could not be
+immediately acquired.  The mutex in @var{$arg1} is the mutex of the
+selected arena.
+@end deftp
+
+@deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
+This probe is triggered when @code{malloc} has chosen an arena that is
+in the free list for use by a thread, within the @code{get_free_list}
+function.  The argument @var{$arg1} holds a pointer to the selected arena.
+@end deftp
+
+@deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
+This probe is triggered when function @code{mallopt} is called to change
+@code{malloc} internal configuration parameters, before any change to
+the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
+the ones passed to the @code{mallopt} function.
+@end deftp
+
+@deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_MXFAST}, and the requested
+value is in an acceptable range.  Argument @var{$arg1} is the requested
+value, and @var{$arg2} is the previous value of this @code{malloc}
+parameter.
+@end deftp
+
+@deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
+This probe is triggere shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
+@var{$arg1} is the requested value, @var{$arg2} is the previous value of
+this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
+threshold adjustment was already disabled.
+@end deftp
+
+@deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_TOP_PAD}.  Argument
+@var{$arg1} is the requested value, @var{$arg2} is the previous value of
+this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
+threshold adjustment was already disabled.
+@end deftp
+
+@deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
+requested value is in an acceptable range.  Argument @var{$arg1} is the
+requested value, @var{$arg2} is the previous value of this @code{malloc}
+parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
+was already disabled.
+@end deftp
+
+@deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
+@var{$arg1} is the requested value, @var{$arg2} is the previous value of
+this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
+threshold adjustment was already disabled.
+@end deftp
+
+@deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
+@var{$arg1} is the requested value, and @var{$arg2} is the previous
+value of this @code{malloc} parameter.
+@end deftp
+
+@deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_PERTURB}.  Argument
+@var{$arg1} is the requested value, and @var{$arg2} is the previous
+value of this @code{malloc} parameter.
+@end deftp
+
+@deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_ARENA_TEST}, and the
+requested value is in an acceptable range.  Argument @var{$arg1} is the
+requested value, and @var{$arg2} is the previous value of this
+@code{malloc} parameter.
+@end deftp
+
+@deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
+This probe is triggered shortly after the @code{memory_mallopt} probe,
+when the parameter to be changed is @code{M_ARENA_MAX}, and the
+requested value is in an acceptable range.  Argument @var{$arg1} is the
+requested value, and @var{$arg2} is the previous value of this
+@code{malloc} parameter.
+@end deftp
+
+@deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
+This probe is triggered when function @code{free} decides to adjust the
+dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
+the adjusted mmap and trim thresholds, respectively.
+@end deftp
+
+@node Mathematical Function Probes
+@section Mathematical Function Probes
+
+Some mathematical functions fall back to multiple precision arithmetic for
+some inputs to get last bit precision for their return values.  This multiple
+precision fallback is much slower than the default algorithms and may have a
+significant impact on application performance.  The systemtap probe markers
+described in this section may help you determine if your application calls
+mathematical functions with inputs that may result in multiple-precision
+arithmetic.
+
+Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
+precision in the mantissa of the multiple precision number.  Hence, a precision
+level of 32 implies 768 bits of precision in the mantissa.
+
+@deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{exp} function is called with an
+input that results in multiple precision computation with precision
+6.  Argument @var{$arg1} is the input value and @var{$arg2} is the
+computed output.
+@end deftp
+
+@deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{exp} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input value and @var{$arg2} is the
+computed output.
+@end deftp
+
+@deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
+This probe is triggered when the @code{pow} function is called with
+inputs that result in multiple precision computation with precision
+10.  Arguments @var{$arg1} and @var{$arg2} are the input values,
+@code{$arg3} is the value computed in the fast phase of the algorithm
+and @code{$arg4} is the final accurate value.
+@end deftp
+
+@deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
+This probe is triggered when the @code{pow} function is called with an
+input that results in multiple precision computation with precision
+32.  Arguments @var{$arg1} and @var{$arg2} are the input values,
+@code{$arg3} is the value computed in the fast phase of the algorithm
+and @code{$arg4} is the final accurate value.
+@end deftp
+
+@deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{log} function is called with an
+input that results in multiple precision computation.  Argument
+@var{$arg1} is the precision with which the computation succeeded.
+Argument @var{$arg2} is the input and @var{$arg3} is the computed
+output.
+@end deftp
+
+@deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{log} function is called with an
+input that results in multiple precision computation and none of the
+multiple precision computations result in an accurate result.
+Argument @var{$arg1} is the maximum precision with which computations
+were performed.  Argument @var{$arg2} is the input and @var{$arg3} is
+the computed output.
+@end deftp
+
+@deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
+This probe is triggered when the @code{atan2} function is called with
+an input that results in multiple precision computation.  Argument
+@var{$arg1} is the precision with which computation succeeded.
+Arguments @var{$arg2} and @var{$arg3} are inputs to the @code{atan2}
+function and @var{$arg4} is the computed result.
+@end deftp
+
+@deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
+This probe is triggered when the @code{atan} function is called with
+an input that results in multiple precision computation and none of
+the multiple precision computations result in an accurate result.
+Argument @var{$arg1} is the maximum precision with which computations
+were performed.  Arguments @var{$arg2} and @var{$arg3} are inputs to
+the @code{atan2} function and @var{$arg4} is the computed result.
+@end deftp
+
+@deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{atan} function is called with
+an input that results in multiple precision computation.  Argument
+@var{$arg1} is the precision with which computation succeeded.
+Argument @var{$arg2} is the input to the @code{atan} function and
+@var{$arg3} is the computed result.
+@end deftp
+
+@deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{atan} function is called with
+an input that results in multiple precision computation and none of
+the multiple precision computations result in an accurate result.
+Argument @var{$arg1} is the maximum precision with which computations
+were performed.  Argument @var{$arg2} is the input to the @code{atan}
+function and @var{$arg3} is the computed result.
+@end deftp
+
+@deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{tan} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
+is the computed result.
+@end deftp
+
+@deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{asin} function is called with
+an input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
+is the computed result.
+@end deftp
+
+@deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{acos} function is called with
+an input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
+is the computed result.
+@end deftp
+
+@deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{sin} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
+is the computed result.
+@end deftp
+
+@deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
+This probe is triggered when the @code{cos} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
+is the computed result.
+@end deftp
+
+@deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{sin} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
+the error bound of @var{$arg1} and @var{$arg3} is the computed result.
+@end deftp
+
+@deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
+This probe is triggered when the @code{cos} function is called with an
+input that results in multiple precision computation with precision
+32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
+the error bound of @var{$arg1} and @var{$arg3} is the computed result.
+@end deftp
+
+@node Non-local Goto Probes
+@section Non-local Goto Probes
+
+These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
+@code{longjmp} or @code{siglongjmp}.
+
+@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
+This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is
+called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
+passed as the first argument of @code{setjmp} or @code{sigsetjmp},
+@var{$arg2} is the second argument of @code{sigsetjmp} or zero if this
+is a call to @code{setjmp} and @var{$arg3} is a pointer to the return
+address that will be stored in the @code{jmp_buf}.
+@end deftp
+
+@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
+This probe is triggered whenever @code{longjmp} or @code{siglongjmp}
+is called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
+passed as the first argument of @code{longjmp} or @code{siglongjmp},
+@var{$arg2} is the return value passed as the second argument of
+@code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to
+the return address @code{longjmp} or @code{siglongjmp} will return to.
+
+The @code{longjmp} probe is triggered at a point where the registers
+have not yet been restored to the values in the @code{jmp_buf} and
+unwinding will show a call stack including the caller of
+@code{longjmp} or @code{siglongjmp}.
+@end deftp
+
+@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
+This probe is triggered under the same conditions and with the same
+arguments as the @code{longjmp} probe.
+
+The @code{longjmp_target} probe is triggered at a point where the
+registers have been restored to the values in the @code{jmp_buf} and
+unwinding will show a call stack including the caller of @code{setjmp}
+or @code{sigsetjmp}.
+@end deftp
diff --git a/ap/libc/glibc/glibc-2.23/manual/process.texi b/ap/libc/glibc/glibc-2.23/manual/process.texi
new file mode 100644
index 0000000..aa59040
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/process.texi
@@ -0,0 +1,887 @@
+@node Processes, Inter-Process Communication, Program Basics, Top
+@c %MENU% How to create processes and run other programs
+@chapter Processes
+
+@cindex process
+@dfn{Processes} are the primitive units for allocation of system
+resources.  Each process has its own address space and (usually) one
+thread of control.  A process executes a program; you can have multiple
+processes executing the same program, but each process has its own copy
+of the program within its own address space and executes it
+independently of the other copies.
+
+@cindex child process
+@cindex parent process
+Processes are organized hierarchically.  Each process has a @dfn{parent
+process} which explicitly arranged to create it.  The processes created
+by a given parent are called its @dfn{child processes}.  A child
+inherits many of its attributes from the parent process.
+
+This chapter describes how a program can create, terminate, and control
+child processes.  Actually, there are three distinct operations
+involved: creating a new child process, causing the new process to
+execute a program, and coordinating the completion of the child process
+with the original program.
+
+The @code{system} function provides a simple, portable mechanism for
+running another program; it does all three steps automatically.  If you
+need more control over the details of how this is done, you can use the
+primitive functions to do each step individually instead.
+
+@menu
+* Running a Command::           The easy way to run another program.
+* Process Creation Concepts::   An overview of the hard way to do it.
+* Process Identification::      How to get the process ID of a process.
+* Creating a Process::          How to fork a child process.
+* Executing a File::            How to make a process execute another program.
+* Process Completion::          How to tell when a child process has completed.
+* Process Completion Status::   How to interpret the status value
+                                 returned from a child process.
+* BSD Wait Functions::  	More functions, for backward compatibility.
+* Process Creation Example::    A complete example program.
+@end menu
+
+
+@node Running a Command
+@section Running a Command
+@cindex running a command
+
+The easy way to run another program is to use the @code{system}
+function.  This function does all the work of running a subprogram, but
+it doesn't give you much control over the details: you have to wait
+until the subprogram terminates before you can do anything else.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int system (const char *@var{command})
+@pindex sh
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c system @ascuplugin @ascuheap @asulock @aculock @acsmem
+@c  do_system @ascuplugin @ascuheap @asulock @aculock @acsmem
+@c   sigemptyset dup ok
+@c   libc_lock_lock @asulock @aculock
+@c   ADD_REF ok
+@c   sigaction dup ok
+@c   SUB_REF ok
+@c   libc_lock_unlock @aculock
+@c   sigaddset dup ok
+@c   sigprocmask dup ok
+@c   CLEANUP_HANDLER @ascuplugin @ascuheap @acsmem
+@c    libc_cleanup_region_start @ascuplugin @ascuheap @acsmem
+@c     pthread_cleanup_push_defer @ascuplugin @ascuheap @acsmem
+@c      CANCELLATION_P @ascuplugin @ascuheap @acsmem
+@c       CANCEL_ENABLED_AND_CANCELED ok
+@c       do_cancel @ascuplugin @ascuheap @acsmem
+@c    cancel_handler ok
+@c     kill syscall ok
+@c     waitpid dup ok
+@c     libc_lock_lock ok
+@c     sigaction dup ok
+@c     libc_lock_unlock ok
+@c   FORK ok
+@c    clone syscall ok
+@c   waitpid dup ok
+@c   CLEANUP_RESET ok
+@c    libc_cleanup_region_end ok
+@c     pthread_cleanup_pop_restore ok
+@c  SINGLE_THREAD_P ok
+@c  LIBC_CANCEL_ASYNC @ascuplugin @ascuheap @acsmem
+@c   libc_enable_asynccancel @ascuplugin @ascuheap @acsmem
+@c    CANCEL_ENABLED_AND_CANCELED_AND_ASYNCHRONOUS dup ok
+@c    do_cancel dup @ascuplugin @ascuheap @acsmem
+@c  LIBC_CANCEL_RESET ok
+@c   libc_disable_asynccancel ok
+@c    lll_futex_wait dup ok
+This function executes @var{command} as a shell command.  In @theglibc{},
+it always uses the default shell @code{sh} to run the command.
+In particular, it searches the directories in @code{PATH} to find
+programs to execute.  The return value is @code{-1} if it wasn't
+possible to create the shell process, and otherwise is the status of the
+shell process.  @xref{Process Completion}, for details on how this
+status code can be interpreted.
+
+If the @var{command} argument is a null pointer, a return value of zero
+indicates that no command processor is available.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{system} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{system} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+@pindex stdlib.h
+The @code{system} function is declared in the header file
+@file{stdlib.h}.
+@end deftypefun
+
+@strong{Portability Note:} Some C implementations may not have any
+notion of a command processor that can execute other programs.  You can
+determine whether a command processor exists by executing
+@w{@code{system (NULL)}}; if the return value is nonzero, a command
+processor is available.
+
+The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
+Subprocess}) are closely related to the @code{system} function.  They
+allow the parent process to communicate with the standard input and
+output channels of the command being executed.
+
+@node Process Creation Concepts
+@section Process Creation Concepts
+
+This section gives an overview of processes and of the steps involved in
+creating a process and making it run another program.
+
+@cindex process ID
+@cindex process lifetime
+Each process is named by a @dfn{process ID} number.  A unique process ID
+is allocated to each process when it is created.  The @dfn{lifetime} of
+a process ends when its termination is reported to its parent process;
+at that time, all of the process resources, including its process ID,
+are freed.
+
+@cindex creating a process
+@cindex forking a process
+@cindex child process
+@cindex parent process
+Processes are created with the @code{fork} system call (so the operation
+of creating a new process is sometimes called @dfn{forking} a process).
+The @dfn{child process} created by @code{fork} is a copy of the original
+@dfn{parent process}, except that it has its own process ID.
+
+After forking a child process, both the parent and child processes
+continue to execute normally.  If you want your program to wait for a
+child process to finish executing before continuing, you must do this
+explicitly after the fork operation, by calling @code{wait} or
+@code{waitpid} (@pxref{Process Completion}).  These functions give you
+limited information about why the child terminated---for example, its
+exit status code.
+
+A newly forked child process continues to execute the same program as
+its parent process, at the point where the @code{fork} call returns.
+You can use the return value from @code{fork} to tell whether the program
+is running in the parent process or the child.
+
+@cindex process image
+Having several processes run the same program is only occasionally
+useful.  But the child can execute another program using one of the
+@code{exec} functions; see @ref{Executing a File}.  The program that the
+process is executing is called its @dfn{process image}.  Starting
+execution of a new program causes the process to forget all about its
+previous process image; when the new program exits, the process exits
+too, instead of returning to the previous process image.
+
+@node Process Identification
+@section Process Identification
+
+The @code{pid_t} data type represents process IDs.  You can get the
+process ID of a process by calling @code{getpid}.  The function
+@code{getppid} returns the process ID of the parent of the current
+process (this is also known as the @dfn{parent process ID}).  Your
+program should include the header files @file{unistd.h} and
+@file{sys/types.h} to use these functions.
+@pindex sys/types.h
+@pindex unistd.h
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} pid_t
+The @code{pid_t} data type is a signed integer type which is capable
+of representing a process ID.  In @theglibc{}, this is an @code{int}.
+@end deftp
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t getpid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getpid} function returns the process ID of the current process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t getppid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getppid} function returns the process ID of the parent of the
+current process.
+@end deftypefun
+
+@node Creating a Process
+@section Creating a Process
+
+The @code{fork} function is the primitive for creating a process.
+It is declared in the header file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun pid_t fork (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}}
+@c The nptl/.../linux implementation safely collects fork_handlers into
+@c an alloca()ed linked list and increments ref counters; it uses atomic
+@c ops and retries, avoiding locking altogether.  It then takes the
+@c IO_list lock, resets the thread-local pid, and runs fork.  The parent
+@c restores the thread-local pid, releases the lock, and runs parent
+@c handlers, decrementing the ref count and signaling futex wait if
+@c requested by unregister_atfork.  The child bumps the fork generation,
+@c sets the thread-local pid, resets cpu clocks, initializes the robust
+@c mutex list, the stream locks, the IO_list lock, the dynamic loader
+@c lock, runs the child handlers, reseting ref counters to 1, and
+@c initializes the fork lock.  These are all safe, unless atfork
+@c handlers themselves are unsafe.
+The @code{fork} function creates a new process.
+
+If the operation is successful, there are then both parent and child
+processes and both see @code{fork} return, but with different values: it
+returns a value of @code{0} in the child process and returns the child's
+process ID in the parent process.
+
+If process creation failed, @code{fork} returns a value of @code{-1} in
+the parent process.  The following @code{errno} error conditions are
+defined for @code{fork}:
+
+@table @code
+@item EAGAIN
+There aren't enough system resources to create another process, or the
+user already has too many processes running.  This means exceeding the
+@code{RLIMIT_NPROC} resource limit, which can usually be increased;
+@pxref{Limits on Resources}.
+
+@item ENOMEM
+The process requires more space than the system can supply.
+@end table
+@end deftypefun
+
+The specific attributes of the child process that differ from the
+parent process are:
+
+@itemize @bullet
+@item
+The child process has its own unique process ID.
+
+@item
+The parent process ID of the child process is the process ID of its
+parent process.
+
+@item
+The child process gets its own copies of the parent process's open file
+descriptors.  Subsequently changing attributes of the file descriptors
+in the parent process won't affect the file descriptors in the child,
+and vice versa.  @xref{Control Operations}.  However, the file position
+associated with each descriptor is shared by both processes;
+@pxref{File Position}.
+
+@item
+The elapsed processor times for the child process are set to zero;
+see @ref{Processor Time}.
+
+@item
+The child doesn't inherit file locks set by the parent process.
+@c !!! flock locks shared
+@xref{Control Operations}.
+
+@item
+The child doesn't inherit alarms set by the parent process.
+@xref{Setting an Alarm}.
+
+@item
+The set of pending signals (@pxref{Delivery of Signal}) for the child
+process is cleared.  (The child process inherits its mask of blocked
+signals and signal actions from the parent process.)
+@end itemize
+
+
+@comment unistd.h
+@comment BSD
+@deftypefun pid_t vfork (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{}}@acunsafe{@aculock{}}}
+@c The vfork implementation proper is a safe syscall, but it may fall
+@c back to fork if the vfork syscall is not available.
+The @code{vfork} function is similar to @code{fork} but on some systems
+it is more efficient; however, there are restrictions you must follow to
+use it safely.
+
+While @code{fork} makes a complete copy of the calling process's address
+space and allows both the parent and child to execute independently,
+@code{vfork} does not make this copy.  Instead, the child process
+created with @code{vfork} shares its parent's address space until it
+calls @code{_exit} or one of the @code{exec} functions.  In the
+meantime, the parent process suspends execution.
+
+You must be very careful not to allow the child process created with
+@code{vfork} to modify any global data or even local variables shared
+with the parent.  Furthermore, the child process cannot return from (or
+do a long jump out of) the function that called @code{vfork}!  This
+would leave the parent process's control information very confused.  If
+in doubt, use @code{fork} instead.
+
+Some operating systems don't really implement @code{vfork}.  @Theglibc{}
+permits you to use @code{vfork} on all systems, but actually
+executes @code{fork} if @code{vfork} isn't available.  If you follow
+the proper precautions for using @code{vfork}, your program will still
+work even if the system uses @code{fork} instead.
+@end deftypefun
+
+@node Executing a File
+@section Executing a File
+@cindex executing a file
+@cindex @code{exec} functions
+
+This section describes the @code{exec} family of functions, for executing
+a file as a process image.  You can use these functions to make a child
+process execute a new program after it has been forked.
+
+To see the effects of @code{exec} from the point of view of the called
+program, see @ref{Program Basics}.
+
+@pindex unistd.h
+The functions in this family differ in how you specify the arguments,
+but otherwise they all do the same thing.  They are declared in the
+header file @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{execv} function executes the file named by @var{filename} as a
+new process image.
+
+The @var{argv} argument is an array of null-terminated strings that is
+used to provide a value for the @code{argv} argument to the @code{main}
+function of the program to be executed.  The last element of this array
+must be a null pointer.  By convention, the first element of this array
+is the file name of the program sans directory names.  @xref{Program
+Arguments}, for full details on how programs can access these arguments.
+
+The environment for the new process image is taken from the
+@code{environ} variable of the current process image; see
+@ref{Environment Variables}, for information about environments.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is similar to @code{execv}, but the @var{argv} strings are
+specified individually instead of as an array.  A null pointer must be
+passed as the last such argument.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is similar to @code{execv}, but permits you to specify the environment
+for the new program explicitly as the @var{env} argument.  This should
+be an array of strings in the same format as for the @code{environ}
+variable; see @ref{Environment Access}.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, @dots{}, char *const @var{env}@t{[]})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is similar to @code{execl}, but permits you to specify the
+environment for the new program explicitly.  The environment argument is
+passed following the null pointer that marks the last @var{argv}
+argument, and should be an array of strings in the same format as for
+the @code{environ} variable.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{execvp} function is similar to @code{execv}, except that it
+searches the directories listed in the @code{PATH} environment variable
+(@pxref{Standard Environment}) to find the full file name of a
+file from @var{filename} if @var{filename} does not contain a slash.
+
+This function is useful for executing system utility programs, because
+it looks for them in the places that the user has chosen.  Shells use it
+to run the commands that users type.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function is like @code{execl}, except that it performs the same
+file name searching as the @code{execvp} function.
+@end deftypefun
+
+The size of the argument list and environment list taken together must
+not be greater than @code{ARG_MAX} bytes.  @xref{General Limits}.  On
+@gnuhurdsystems{}, the size (which compares against @code{ARG_MAX})
+includes, for each string, the number of characters in the string, plus
+the size of a @code{char *}, plus one, rounded up to a multiple of the
+size of a @code{char *}.  Other systems may have somewhat different
+rules for counting.
+
+These functions normally don't return, since execution of a new program
+causes the currently executing program to go away completely.  A value
+of @code{-1} is returned in the event of a failure.  In addition to the
+usual file name errors (@pxref{File Name Errors}), the following
+@code{errno} error conditions are defined for these functions:
+
+@table @code
+@item E2BIG
+The combined size of the new program's argument list and environment
+list is larger than @code{ARG_MAX} bytes.  @gnuhurdsystems{} have no
+specific limit on the argument list size, so this error code cannot
+result, but you may get @code{ENOMEM} instead if the arguments are too
+big for available memory.
+
+@item ENOEXEC
+The specified file can't be executed because it isn't in the right format.
+
+@item ENOMEM
+Executing the specified file requires more storage than is available.
+@end table
+
+If execution of the new file succeeds, it updates the access time field
+of the file as if the file had been read.  @xref{File Times}, for more
+details about access times of files.
+
+The point at which the file is closed again is not specified, but
+is at some point before the process exits or before another process
+image is executed.
+
+Executing a new process image completely changes the contents of memory,
+copying only the argument and environment strings to new locations.  But
+many other attributes of the process are unchanged:
+
+@itemize @bullet
+@item
+The process ID and the parent process ID.  @xref{Process Creation Concepts}.
+
+@item
+Session and process group membership.  @xref{Concepts of Job Control}.
+
+@item
+Real user ID and group ID, and supplementary group IDs.  @xref{Process
+Persona}.
+
+@item
+Pending alarms.  @xref{Setting an Alarm}.
+
+@item
+Current working directory and root directory.  @xref{Working
+Directory}.  On @gnuhurdsystems{}, the root directory is not copied when
+executing a setuid program; instead the system default root directory
+is used for the new program.
+
+@item
+File mode creation mask.  @xref{Setting Permissions}.
+
+@item
+Process signal mask; see @ref{Process Signal Mask}.
+
+@item
+Pending signals; see @ref{Blocking Signals}.
+
+@item
+Elapsed processor time associated with the process; see @ref{Processor Time}.
+@end itemize
+
+If the set-user-ID and set-group-ID mode bits of the process image file
+are set, this affects the effective user ID and effective group ID
+(respectively) of the process.  These concepts are discussed in detail
+in @ref{Process Persona}.
+
+Signals that are set to be ignored in the existing process image are
+also set to be ignored in the new process image.  All other signals are
+set to the default action in the new process image.  For more
+information about signals, see @ref{Signal Handling}.
+
+File descriptors open in the existing process image remain open in the
+new process image, unless they have the @code{FD_CLOEXEC}
+(close-on-exec) flag set.  The files that remain open inherit all
+attributes of the open file description from the existing process image,
+including file locks.  File descriptors are discussed in @ref{Low-Level I/O}.
+
+Streams, by contrast, cannot survive through @code{exec} functions,
+because they are located in the memory of the process itself.  The new
+process image has no streams except those it creates afresh.  Each of
+the streams in the pre-@code{exec} process image has a descriptor inside
+it, and these descriptors do survive through @code{exec} (provided that
+they do not have @code{FD_CLOEXEC} set).  The new process image can
+reconnect these to new streams using @code{fdopen} (@pxref{Descriptors
+and Streams}).
+
+@node Process Completion
+@section Process Completion
+@cindex process completion
+@cindex waiting for completion of child process
+@cindex testing exit status of child process
+
+The functions described in this section are used to wait for a child
+process to terminate or stop, and determine its status.  These functions
+are declared in the header file @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{waitpid} function is used to request status information from a
+child process whose process ID is @var{pid}.  Normally, the calling
+process is suspended until the child process makes status information
+available by terminating.
+
+Other values for the @var{pid} argument have special interpretations.  A
+value of @code{-1} or @code{WAIT_ANY} requests status information for
+any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
+information for any child process in the same process group as the
+calling process; and any other negative value @minus{} @var{pgid}
+requests information for any child process whose process group ID is
+@var{pgid}.
+
+If status information for a child process is available immediately, this
+function returns immediately without waiting.  If more than one eligible
+child process has status information available, one of them is chosen
+randomly, and its status is returned immediately.  To get the status
+from the other eligible child processes, you need to call @code{waitpid}
+again.
+
+The @var{options} argument is a bit mask.  Its value should be the
+bitwise OR (that is, the @samp{|} operator) of zero or more of the
+@code{WNOHANG} and @code{WUNTRACED} flags.  You can use the
+@code{WNOHANG} flag to indicate that the parent process shouldn't wait;
+and the @code{WUNTRACED} flag to request status information from stopped
+processes as well as processes that have terminated.
+
+The status information from the child process is stored in the object
+that @var{status-ptr} points to, unless @var{status-ptr} is a null pointer.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{waitpid} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{waitpid} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The return value is normally the process ID of the child process whose
+status is reported.  If there are child processes but none of them is
+waiting to be noticed, @code{waitpid} will block until one is.  However,
+if the @code{WNOHANG} option was specified, @code{waitpid} will return
+zero instead of blocking.
+
+If a specific PID to wait for was given to @code{waitpid}, it will
+ignore all other children (if any).  Therefore if there are children
+waiting to be noticed but the child whose PID was specified is not one
+of them, @code{waitpid} will block or return zero as described above.
+
+A value of @code{-1} is returned in case of error.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINTR
+The function was interrupted by delivery of a signal to the calling
+process.  @xref{Interrupted Primitives}.
+
+@item ECHILD
+There are no child processes to wait for, or the specified @var{pid}
+is not a child of the calling process.
+
+@item EINVAL
+An invalid value was provided for the @var{options} argument.
+@end table
+@end deftypefun
+
+These symbolic constants are defined as values for the @var{pid} argument
+to the @code{waitpid} function.
+
+@comment Extra blank lines make it look better.
+@table @code
+@item WAIT_ANY
+
+This constant macro (whose value is @code{-1}) specifies that
+@code{waitpid} should return status information about any child process.
+
+
+@item WAIT_MYPGRP
+This constant (with value @code{0}) specifies that @code{waitpid} should
+return status information about any child process in the same process
+group as the calling process.
+@end table
+
+These symbolic constants are defined as flags for the @var{options}
+argument to the @code{waitpid} function.  You can bitwise-OR the flags
+together to obtain a value to use as the argument.
+
+@table @code
+@item WNOHANG
+
+This flag specifies that @code{waitpid} should return immediately
+instead of waiting, if there is no child process ready to be noticed.
+
+@item WUNTRACED
+
+This flag specifies that @code{waitpid} should report the status of any
+child processes that have been stopped as well as those that have
+terminated.
+@end table
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefun pid_t wait (int *@var{status-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is a simplified version of @code{waitpid}, and is used to wait
+until any one child process terminates.  The call:
+
+@smallexample
+wait (&status)
+@end smallexample
+
+@noindent
+is exactly equivalent to:
+
+@smallexample
+waitpid (-1, &status, 0)
+@end smallexample
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{wait} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{wait} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+@end deftypefun
+
+@comment sys/wait.h
+@comment BSD
+@deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @var{usage} is a null pointer, @code{wait4} is equivalent to
+@code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}.
+
+If @var{usage} is not null, @code{wait4} stores usage figures for the
+child process in @code{*@var{rusage}} (but only if the child has
+terminated, not if it has stopped).  @xref{Resource Usage}.
+
+This function is a BSD extension.
+@end deftypefun
+
+Here's an example of how to use @code{waitpid} to get the status from
+all child processes that have terminated, without ever waiting.  This
+function is designed to be a handler for @code{SIGCHLD}, the signal that
+indicates that at least one child process has terminated.
+
+@smallexample
+@group
+void
+sigchld_handler (int signum)
+@{
+  int pid, status, serrno;
+  serrno = errno;
+  while (1)
+    @{
+      pid = waitpid (WAIT_ANY, &status, WNOHANG);
+      if (pid < 0)
+        @{
+          perror ("waitpid");
+          break;
+        @}
+      if (pid == 0)
+        break;
+      notice_termination (pid, status);
+    @}
+  errno = serrno;
+@}
+@end group
+@end smallexample
+
+@node Process Completion Status
+@section Process Completion Status
+
+If the exit status value (@pxref{Program Termination}) of the child
+process is zero, then the status value reported by @code{waitpid} or
+@code{wait} is also zero.  You can test for other kinds of information
+encoded in the returned status value using the following macros.
+These macros are defined in the header file @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFEXITED (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if the child process terminated
+normally with @code{exit} or @code{_exit}.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WEXITSTATUS (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @code{WIFEXITED} is true of @var{status}, this macro returns the
+low-order 8 bits of the exit status value from the child process.
+@xref{Exit Status}.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFSIGNALED (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if the child process terminated
+because it received a signal that was not handled.
+@xref{Signal Handling}.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WTERMSIG (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
+signal number of the signal that terminated the child process.
+@end deftypefn
+
+@comment sys/wait.h
+@comment BSD
+@deftypefn Macro int WCOREDUMP (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if the child process terminated
+and produced a core dump.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WIFSTOPPED (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro returns a nonzero value if the child process is stopped.
+@end deftypefn
+
+@comment sys/wait.h
+@comment POSIX.1
+@deftypefn Macro int WSTOPSIG (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
+signal number of the signal that caused the child process to stop.
+@end deftypefn
+
+
+@node BSD Wait Functions
+@section BSD Process Wait Functions
+
+@Theglibc{} also provides these related facilities for compatibility
+with BSD Unix.  BSD uses the @code{union wait} data type to represent
+status values rather than an @code{int}.  The two representations are
+actually interchangeable; they describe the same bit patterns.  @Theglibc{}
+defines macros such as @code{WEXITSTATUS} so that they will
+work on either kind of object, and the @code{wait} function is defined
+to accept either type of pointer as its @var{status-ptr} argument.
+
+These functions are declared in @file{sys/wait.h}.
+@pindex sys/wait.h
+
+@comment sys/wait.h
+@comment BSD
+@deftp {Data Type} {union wait}
+This data type represents program termination status values.  It has
+the following members:
+
+@table @code
+@item int w_termsig
+The value of this member is the same as that of the
+@code{WTERMSIG} macro.
+
+@item int w_coredump
+The value of this member is the same as that of the
+@code{WCOREDUMP} macro.
+
+@item int w_retcode
+The value of this member is the same as that of the
+@code{WEXITSTATUS} macro.
+
+@item int w_stopsig
+The value of this member is the same as that of the
+@code{WSTOPSIG} macro.
+@end table
+
+Instead of accessing these members directly, you should use the
+equivalent macros.
+@end deftp
+
+The @code{wait3} function is the predecessor to @code{wait4}, which is
+more flexible.  @code{wait3} is now obsolete.
+
+@comment sys/wait.h
+@comment BSD
+@deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If @var{usage} is a null pointer, @code{wait3} is equivalent to
+@code{waitpid (-1, @var{status-ptr}, @var{options})}.
+
+If @var{usage} is not null, @code{wait3} stores usage figures for the
+child process in @code{*@var{rusage}} (but only if the child has
+terminated, not if it has stopped).  @xref{Resource Usage}.
+@end deftypefun
+
+@node Process Creation Example
+@section Process Creation Example
+
+Here is an example program showing how you might write a function
+similar to the built-in @code{system}.  It executes its @var{command}
+argument using the equivalent of @samp{sh -c @var{command}}.
+
+@smallexample
+#include <stddef.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+
+/* @r{Execute the command using this shell program.}  */
+#define SHELL "/bin/sh"
+
+@group
+int
+my_system (const char *command)
+@{
+  int status;
+  pid_t pid;
+@end group
+
+  pid = fork ();
+  if (pid == 0)
+    @{
+      /* @r{This is the child process.  Execute the shell command.} */
+      execl (SHELL, SHELL, "-c", command, NULL);
+      _exit (EXIT_FAILURE);
+    @}
+  else if (pid < 0)
+    /* @r{The fork failed.  Report failure.}  */
+    status = -1;
+  else
+    /* @r{This is the parent process.  Wait for the child to complete.}  */
+    if (waitpid (pid, &status, 0) != pid)
+      status = -1;
+  return status;
+@}
+@end smallexample
+
+@comment Yes, this example has been tested.
+
+There are a couple of things you should pay attention to in this
+example.
+
+Remember that the first @code{argv} argument supplied to the program
+represents the name of the program being executed.  That is why, in the
+call to @code{execl}, @code{SHELL} is supplied once to name the program
+to execute and a second time to supply a value for @code{argv[0]}.
+
+The @code{execl} call in the child process doesn't return if it is
+successful.  If it fails, you must do something to make the child
+process terminate.  Just returning a bad status code with @code{return}
+would leave two processes running the original program.  Instead, the
+right behavior is for the child process to report failure to its parent
+process.
+
+Call @code{_exit} to accomplish this.  The reason for using @code{_exit}
+instead of @code{exit} is to avoid flushing fully buffered streams such
+as @code{stdout}.  The buffers of these streams probably contain data
+that was copied from the parent process by the @code{fork}, data that
+will be output eventually by the parent process.  Calling @code{exit} in
+the child would output the data twice.  @xref{Termination Internals}.
diff --git a/ap/libc/glibc/glibc-2.23/manual/resource.texi b/ap/libc/glibc/glibc-2.23/manual/resource.texi
new file mode 100644
index 0000000..e68458b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/resource.texi
@@ -0,0 +1,1732 @@
+@node Resource Usage And Limitation, Non-Local Exits, Date and Time, Top
+@c %MENU% Functions for examining resource usage and getting and setting limits
+@chapter Resource Usage And Limitation
+This chapter describes functions for examining how much of various kinds of
+resources (CPU time, memory, etc.) a process has used and getting and setting
+limits on future usage.
+
+@menu
+* Resource Usage::		Measuring various resources used.
+* Limits on Resources::		Specifying limits on resource usage.
+* Priority::			Reading or setting process run priority.
+* Memory Resources::            Querying memory available resources.
+* Processor Resources::         Learn about the processors available.
+@end menu
+
+
+@node Resource Usage
+@section Resource Usage
+
+@pindex sys/resource.h
+The function @code{getrusage} and the data type @code{struct rusage}
+are used to examine the resource usage of a process.  They are declared
+in @file{sys/resource.h}.
+
+@comment sys/resource.h
+@comment BSD
+@deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On HURD, this calls task_info 3 times.  On UNIX, it's a syscall.
+This function reports resource usage totals for processes specified by
+@var{processes}, storing the information in @code{*@var{rusage}}.
+
+In most systems, @var{processes} has only two valid values:
+
+@table @code
+@comment sys/resource.h
+@comment BSD
+@item RUSAGE_SELF
+Just the current process.
+
+@comment sys/resource.h
+@comment BSD
+@item RUSAGE_CHILDREN
+All child processes (direct and indirect) that have already terminated.
+@end table
+
+The return value of @code{getrusage} is zero for success, and @code{-1}
+for failure.
+
+@table @code
+@item EINVAL
+The argument @var{processes} is not valid.
+@end table
+@end deftypefun
+
+One way of getting resource usage for a particular child process is with
+the function @code{wait4}, which returns totals for a child when it
+terminates.  @xref{BSD Wait Functions}.
+
+@comment sys/resource.h
+@comment BSD
+@deftp {Data Type} {struct rusage}
+This data type stores various resource usage statistics.  It has the
+following members, and possibly others:
+
+@table @code
+@item struct timeval ru_utime
+Time spent executing user instructions.
+
+@item struct timeval ru_stime
+Time spent in operating system code on behalf of @var{processes}.
+
+@item long int ru_maxrss
+The maximum resident set size used, in kilobytes.  That is, the maximum
+number of kilobytes of physical memory that @var{processes} used
+simultaneously.
+
+@item long int ru_ixrss
+An integral value expressed in kilobytes times ticks of execution, which
+indicates the amount of memory used by text that was shared with other
+processes.
+
+@item long int ru_idrss
+An integral value expressed the same way, which is the amount of
+unshared memory used for data.
+
+@item long int ru_isrss
+An integral value expressed the same way, which is the amount of
+unshared memory used for stack space.
+
+@item long int ru_minflt
+The number of page faults which were serviced without requiring any I/O.
+
+@item long int ru_majflt
+The number of page faults which were serviced by doing I/O.
+
+@item long int ru_nswap
+The number of times @var{processes} was swapped entirely out of main memory.
+
+@item long int ru_inblock
+The number of times the file system had to read from the disk on behalf
+of @var{processes}.
+
+@item long int ru_oublock
+The number of times the file system had to write to the disk on behalf
+of @var{processes}.
+
+@item long int ru_msgsnd
+Number of IPC messages sent.
+
+@item long int ru_msgrcv
+Number of IPC messages received.
+
+@item long int ru_nsignals
+Number of signals received.
+
+@item long int ru_nvcsw
+The number of times @var{processes} voluntarily invoked a context switch
+(usually to wait for some service).
+
+@item long int ru_nivcsw
+The number of times an involuntary context switch took place (because
+a time slice expired, or another process of higher priority was
+scheduled).
+@end table
+@end deftp
+
+@code{vtimes} is a historical function that does some of what
+@code{getrusage} does.  @code{getrusage} is a better choice.
+
+@code{vtimes} and its @code{vtimes} data structure are declared in
+@file{sys/vtimes.h}.
+@pindex sys/vtimes.h
+
+@comment sys/vtimes.h
+@deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes *@var{child})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Calls getrusage twice.
+
+@code{vtimes} reports resource usage totals for a process.
+
+If @var{current} is non-null, @code{vtimes} stores resource usage totals for
+the invoking process alone in the structure to which it points.  If
+@var{child} is non-null, @code{vtimes} stores resource usage totals for all
+past children (which have terminated) of the invoking process in the structure
+to which it points.
+
+@deftp {Data Type} {struct vtimes}
+This data type contains information about the resource usage of a process.
+Each member corresponds to a member of the @code{struct rusage} data type
+described above.
+
+@table @code
+@item vm_utime
+User CPU time.  Analogous to @code{ru_utime} in @code{struct rusage}
+@item vm_stime
+System CPU time.  Analogous to @code{ru_stime} in @code{struct rusage}
+@item vm_idsrss
+Data and stack memory.  The sum of the values that would be reported as
+@code{ru_idrss} and @code{ru_isrss} in @code{struct rusage}
+@item vm_ixrss
+Shared memory.  Analogous to @code{ru_ixrss} in @code{struct rusage}
+@item vm_maxrss
+Maximent resident set size.  Analogous to @code{ru_maxrss} in
+@code{struct rusage}
+@item vm_majflt
+Major page faults.  Analogous to @code{ru_majflt} in @code{struct rusage}
+@item vm_minflt
+Minor page faults.  Analogous to @code{ru_minflt} in @code{struct rusage}
+@item vm_nswap
+Swap count.  Analogous to @code{ru_nswap} in @code{struct rusage}
+@item vm_inblk
+Disk reads.  Analogous to @code{ru_inblk} in @code{struct rusage}
+@item vm_oublk
+Disk writes.  Analogous to @code{ru_oublk} in @code{struct rusage}
+@end table
+@end deftp
+
+
+The return value is zero if the function succeeds; @code{-1} otherwise.
+
+
+
+@end deftypefun
+An additional historical function for examining resource usage,
+@code{vtimes}, is supported but not documented here.  It is declared in
+@file{sys/vtimes.h}.
+
+@node Limits on Resources
+@section Limiting Resource Usage
+@cindex resource limits
+@cindex limits on resource usage
+@cindex usage limits
+
+You can specify limits for the resource usage of a process.  When the
+process tries to exceed a limit, it may get a signal, or the system call
+by which it tried to do so may fail, depending on the resource.  Each
+process initially inherits its limit values from its parent, but it can
+subsequently change them.
+
+There are two per-process limits associated with a resource:
+@cindex limit
+
+@table @dfn
+@item current limit
+The current limit is the value the system will not allow usage to
+exceed.  It is also called the ``soft limit'' because the process being
+limited can generally raise the current limit at will.
+@cindex current limit
+@cindex soft limit
+
+@item maximum limit
+The maximum limit is the maximum value to which a process is allowed to
+set its current limit.  It is also called the ``hard limit'' because
+there is no way for a process to get around it.  A process may lower
+its own maximum limit, but only the superuser may increase a maximum
+limit.
+@cindex maximum limit
+@cindex hard limit
+@end table
+
+@pindex sys/resource.h
+The symbols for use with @code{getrlimit}, @code{setrlimit},
+@code{getrlimit64}, and @code{setrlimit64} are defined in
+@file{sys/resource.h}.
+
+@comment sys/resource.h
+@comment BSD
+@deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on most systems.
+Read the current and maximum limits for the resource @var{resource}
+and store them in @code{*@var{rlp}}.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+only possible @code{errno} error condition is @code{EFAULT}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{getrlimit64}.  Thus, the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on most systems, wrapper to getrlimit otherwise.
+This function is similar to @code{getrlimit} but its second parameter is
+a pointer to a variable of type @code{struct rlimit64}, which allows it
+to read values which wouldn't fit in the member of a @code{struct
+rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit machine, this function is available under the name
+@code{getrlimit} and so transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment BSD
+@deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on most systems; lock-taking critical section on HURD.
+Store the current and maximum limits for the resource @var{resource}
+in @code{*@var{rlp}}.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is possible:
+
+@table @code
+@item EPERM
+@itemize @bullet
+@item
+The process tried to raise a current limit beyond the maximum limit.
+
+@item
+The process tried to raise a maximum limit, but is not superuser.
+@end itemize
+@end table
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit system this function is in fact @code{setrlimit64}.  Thus, the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment Unix98
+@deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapper for setrlimit or direct syscall.
+This function is similar to @code{setrlimit} but its second parameter is
+a pointer to a variable of type @code{struct rlimit64} which allows it
+to set values which wouldn't fit in the member of a @code{struct
+rlimit}.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32-bit machine this function is available under the name
+@code{setrlimit} and so transparently replaces the old interface.
+@end deftypefun
+
+@comment sys/resource.h
+@comment BSD
+@deftp {Data Type} {struct rlimit}
+This structure is used with @code{getrlimit} to receive limit values,
+and with @code{setrlimit} to specify limit values for a particular process
+and resource.  It has two fields:
+
+@table @code
+@item rlim_t rlim_cur
+The current limit
+
+@item rlim_t rlim_max
+The maximum limit.
+@end table
+
+For @code{getrlimit}, the structure is an output; it receives the current
+values.  For @code{setrlimit}, it specifies the new values.
+@end deftp
+
+For the LFS functions a similar type is defined in @file{sys/resource.h}.
+
+@comment sys/resource.h
+@comment Unix98
+@deftp {Data Type} {struct rlimit64}
+This structure is analogous to the @code{rlimit} structure above, but
+its components have wider ranges.  It has two fields:
+
+@table @code
+@item rlim64_t rlim_cur
+This is analogous to @code{rlimit.rlim_cur}, but with a different type.
+
+@item rlim64_t rlim_max
+This is analogous to @code{rlimit.rlim_max}, but with a different type.
+@end table
+
+@end deftp
+
+Here is a list of resources for which you can specify a limit.  Memory
+and file sizes are measured in bytes.
+
+@table @code
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_CPU
+@vindex RLIMIT_CPU
+The maximum amount of CPU time the process can use.  If it runs for
+longer than this, it gets a signal: @code{SIGXCPU}.  The value is
+measured in seconds.  @xref{Operation Error Signals}.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_FSIZE
+@vindex RLIMIT_FSIZE
+The maximum size of file the process can create.  Trying to write a
+larger file causes a signal: @code{SIGXFSZ}.  @xref{Operation Error
+Signals}.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_DATA
+@vindex RLIMIT_DATA
+The maximum size of data memory for the process.  If the process tries
+to allocate data memory beyond this amount, the allocation function
+fails.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_STACK
+@vindex RLIMIT_STACK
+The maximum stack size for the process.  If the process tries to extend
+its stack past this size, it gets a @code{SIGSEGV} signal.
+@xref{Program Error Signals}.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_CORE
+@vindex RLIMIT_CORE
+The maximum size core file that this process can create.  If the process
+terminates and would dump a core file larger than this, then no core
+file is created.  So setting this limit to zero prevents core files from
+ever being created.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_RSS
+@vindex RLIMIT_RSS
+The maximum amount of physical memory that this process should get.
+This parameter is a guide for the system's scheduler and memory
+allocator; the system may give the process more memory when there is a
+surplus.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_MEMLOCK
+The maximum amount of memory that can be locked into physical memory (so
+it will never be paged out).
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_NPROC
+The maximum number of processes that can be created with the same user ID.
+If you have reached the limit for your user ID, @code{fork} will fail
+with @code{EAGAIN}.  @xref{Creating a Process}.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIMIT_NOFILE
+@vindex RLIMIT_NOFILE
+@itemx RLIMIT_OFILE
+@vindex RLIMIT_OFILE
+The maximum number of files that the process can open.  If it tries to
+open more files than this, its open attempt fails with @code{errno}
+@code{EMFILE}.  @xref{Error Codes}.  Not all systems support this limit;
+GNU does, and 4.4 BSD does.
+
+@comment sys/resource.h
+@comment Unix98
+@item RLIMIT_AS
+@vindex RLIMIT_AS
+The maximum size of total memory that this process should get.  If the
+process tries to allocate more memory beyond this amount with, for
+example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the
+allocation function fails.
+
+@comment sys/resource.h
+@comment BSD
+@item RLIM_NLIMITS
+@vindex RLIM_NLIMITS
+The number of different resource limits.  Any valid @var{resource}
+operand must be less than @code{RLIM_NLIMITS}.
+@end table
+
+@comment sys/resource.h
+@comment BSD
+@deftypevr Constant rlim_t RLIM_INFINITY
+This constant stands for a value of ``infinity'' when supplied as
+the limit value in @code{setrlimit}.
+@end deftypevr
+
+
+The following are historical functions to do some of what the functions
+above do.  The functions above are better choices.
+
+@code{ulimit} and the command symbols are declared in @file{ulimit.h}.
+@pindex ulimit.h
+
+@comment ulimit.h
+@comment BSD
+@deftypefun {long int} ulimit (int @var{cmd}, @dots{})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapper for getrlimit, setrlimit or
+@c sysconf(_SC_OPEN_MAX)->getdtablesize->getrlimit.
+
+@code{ulimit} gets the current limit or sets the current and maximum
+limit for a particular resource for the calling process according to the
+command @var{cmd}.a
+
+If you are getting a limit, the command argument is the only argument.
+If you are setting a limit, there is a second argument:
+@code{long int} @var{limit} which is the value to which you are setting
+the limit.
+
+The @var{cmd} values and the operations they specify are:
+@table @code
+
+@item GETFSIZE
+Get the current limit on the size of a file, in units of 512 bytes.
+
+@item SETFSIZE
+Set the current and maximum limit on the size of a file to @var{limit} *
+512 bytes.
+
+@end table
+
+There are also some other @var{cmd} values that may do things on some
+systems, but they are not supported.
+
+Only the superuser may increase a maximum limit.
+
+When you successfully get a limit, the return value of @code{ulimit} is
+that limit, which is never negative.  When you successfully set a limit,
+the return value is zero.  When the function fails, the return value is
+@code{-1} and @code{errno} is set according to the reason:
+
+@table @code
+@item EPERM
+A process tried to increase a maximum limit, but is not superuser.
+@end table
+
+
+@end deftypefun
+
+@code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}.
+@pindex sys/vlimit.h
+
+@comment sys/vlimit.h
+@comment BSD
+@deftypefun int vlimit (int @var{resource}, int @var{limit})
+@safety{@prelim{}@mtunsafe{@mtasurace{:setrlimit}}@asunsafe{}@acsafe{}}
+@c It calls getrlimit and modifies the rlim_cur field before calling
+@c setrlimit.  There's a window for a concurrent call to setrlimit that
+@c modifies e.g. rlim_max, which will be lost if running as super-user.
+
+@code{vlimit} sets the current limit for a resource for a process.
+
+@var{resource} identifies the resource:
+
+@table @code
+@item LIM_CPU
+Maximum CPU time.  Same as @code{RLIMIT_CPU} for @code{setrlimit}.
+@item LIM_FSIZE
+Maximum file size.  Same as @code{RLIMIT_FSIZE} for @code{setrlimit}.
+@item LIM_DATA
+Maximum data memory.  Same as @code{RLIMIT_DATA} for @code{setrlimit}.
+@item LIM_STACK
+Maximum stack size.  Same as @code{RLIMIT_STACK} for @code{setrlimit}.
+@item LIM_CORE
+Maximum core file size.  Same as @code{RLIMIT_COR} for @code{setrlimit}.
+@item LIM_MAXRSS
+Maximum physical memory.  Same as @code{RLIMIT_RSS} for @code{setrlimit}.
+@end table
+
+The return value is zero for success, and @code{-1} with @code{errno} set
+accordingly for failure:
+
+@table @code
+@item EPERM
+The process tried to set its current limit beyond its maximum limit.
+@end table
+
+@end deftypefun
+
+@node Priority
+@section Process CPU Priority And Scheduling
+@cindex process priority
+@cindex cpu priority
+@cindex priority of a process
+
+When multiple processes simultaneously require CPU time, the system's
+scheduling policy and process CPU priorities determine which processes
+get it.  This section describes how that determination is made and
+@glibcadj{} functions to control it.
+
+It is common to refer to CPU scheduling simply as scheduling and a
+process' CPU priority simply as the process' priority, with the CPU
+resource being implied.  Bear in mind, though, that CPU time is not the
+only resource a process uses or that processes contend for.  In some
+cases, it is not even particularly important.  Giving a process a high
+``priority'' may have very little effect on how fast a process runs with
+respect to other processes.  The priorities discussed in this section
+apply only to CPU time.
+
+CPU scheduling is a complex issue and different systems do it in wildly
+different ways.  New ideas continually develop and find their way into
+the intricacies of the various systems' scheduling algorithms.  This
+section discusses the general concepts, some specifics of systems
+that commonly use @theglibc{}, and some standards.
+
+For simplicity, we talk about CPU contention as if there is only one CPU
+in the system.  But all the same principles apply when a processor has
+multiple CPUs, and knowing that the number of processes that can run at
+any one time is equal to the number of CPUs, you can easily extrapolate
+the information.
+
+The functions described in this section are all defined by the POSIX.1
+and POSIX.1b standards (the @code{sched@dots{}} functions are POSIX.1b).
+However, POSIX does not define any semantics for the values that these
+functions get and set.  In this chapter, the semantics are based on the
+Linux kernel's implementation of the POSIX standard.  As you will see,
+the Linux implementation is quite the inverse of what the authors of the
+POSIX syntax had in mind.
+
+@menu
+* Absolute Priority::               The first tier of priority.  Posix
+* Realtime Scheduling::             Scheduling among the process nobility
+* Basic Scheduling Functions::      Get/set scheduling policy, priority
+* Traditional Scheduling::          Scheduling among the vulgar masses
+* CPU Affinity::                    Limiting execution to certain CPUs
+@end menu
+
+
+
+@node Absolute Priority
+@subsection Absolute Priority
+@cindex absolute priority
+@cindex priority, absolute
+
+Every process has an absolute priority, and it is represented by a number.
+The higher the number, the higher the absolute priority.
+
+@cindex realtime CPU scheduling
+On systems of the past, and most systems today, all processes have
+absolute priority 0 and this section is irrelevant.  In that case,
+@xref{Traditional Scheduling}.  Absolute priorities were invented to
+accommodate realtime systems, in which it is vital that certain processes
+be able to respond to external events happening in real time, which
+means they cannot wait around while some other process that @emph{wants
+to}, but doesn't @emph{need to} run occupies the CPU.
+
+@cindex ready to run
+@cindex preemptive scheduling
+When two processes are in contention to use the CPU at any instant, the
+one with the higher absolute priority always gets it.  This is true even if the
+process with the lower priority is already using the CPU (i.e., the
+scheduling is preemptive).  Of course, we're only talking about
+processes that are running or ``ready to run,'' which means they are
+ready to execute instructions right now.  When a process blocks to wait
+for something like I/O, its absolute priority is irrelevant.
+
+@cindex runnable process
+@strong{NB:}  The term ``runnable'' is a synonym for ``ready to run.''
+
+When two processes are running or ready to run and both have the same
+absolute priority, it's more interesting.  In that case, who gets the
+CPU is determined by the scheduling policy.  If the processes have
+absolute priority 0, the traditional scheduling policy described in
+@ref{Traditional Scheduling} applies.  Otherwise, the policies described
+in @ref{Realtime Scheduling} apply.
+
+You normally give an absolute priority above 0 only to a process that
+can be trusted not to hog the CPU.  Such processes are designed to block
+(or terminate) after relatively short CPU runs.
+
+A process begins life with the same absolute priority as its parent
+process.  Functions described in @ref{Basic Scheduling Functions} can
+change it.
+
+Only a privileged process can change a process' absolute priority to
+something other than @code{0}.  Only a privileged process or the
+target process' owner can change its absolute priority at all.
+
+POSIX requires absolute priority values used with the realtime
+scheduling policies to be consecutive with a range of at least 32.  On
+Linux, they are 1 through 99.  The functions
+@code{sched_get_priority_max} and @code{sched_set_priority_min} portably
+tell you what the range is on a particular system.
+
+
+@subsubsection Using Absolute Priority
+
+One thing you must keep in mind when designing real time applications is
+that having higher absolute priority than any other process doesn't
+guarantee the process can run continuously.  Two things that can wreck a
+good CPU run are interrupts and page faults.
+
+Interrupt handlers live in that limbo between processes.  The CPU is
+executing instructions, but they aren't part of any process.  An
+interrupt will stop even the highest priority process.  So you must
+allow for slight delays and make sure that no device in the system has
+an interrupt handler that could cause too long a delay between
+instructions for your process.
+
+Similarly, a page fault causes what looks like a straightforward
+sequence of instructions to take a long time.  The fact that other
+processes get to run while the page faults in is of no consequence,
+because as soon as the I/O is complete, the high priority process will
+kick them out and run again, but the wait for the I/O itself could be a
+problem.  To neutralize this threat, use @code{mlock} or
+@code{mlockall}.
+
+There are a few ramifications of the absoluteness of this priority on a
+single-CPU system that you need to keep in mind when you choose to set a
+priority and also when you're working on a program that runs with high
+absolute priority.  Consider a process that has higher absolute priority
+than any other process in the system and due to a bug in its program, it
+gets into an infinite loop.  It will never cede the CPU.  You can't run
+a command to kill it because your command would need to get the CPU in
+order to run.  The errant program is in complete control.  It controls
+the vertical, it controls the horizontal.
+
+There are two ways to avoid this: 1) keep a shell running somewhere with
+a higher absolute priority.  2) keep a controlling terminal attached to
+the high priority process group.  All the priority in the world won't
+stop an interrupt handler from running and delivering a signal to the
+process if you hit Control-C.
+
+Some systems use absolute priority as a means of allocating a fixed
+percentage of CPU time to a process.  To do this, a super high priority
+privileged process constantly monitors the process' CPU usage and raises
+its absolute priority when the process isn't getting its entitled share
+and lowers it when the process is exceeding it.
+
+@strong{NB:}  The absolute priority is sometimes called the ``static
+priority.''  We don't use that term in this manual because it misses the
+most important feature of the absolute priority:  its absoluteness.
+
+
+@node Realtime Scheduling
+@subsection Realtime Scheduling
+@cindex realtime scheduling
+
+Whenever two processes with the same absolute priority are ready to run,
+the kernel has a decision to make, because only one can run at a time.
+If the processes have absolute priority 0, the kernel makes this decision
+as described in @ref{Traditional Scheduling}.  Otherwise, the decision
+is as described in this section.
+
+If two processes are ready to run but have different absolute priorities,
+the decision is much simpler, and is described in @ref{Absolute
+Priority}.
+
+Each process has a scheduling policy.  For processes with absolute
+priority other than zero, there are two available:
+
+@enumerate
+@item
+First Come First Served
+@item
+Round Robin
+@end enumerate
+
+The most sensible case is where all the processes with a certain
+absolute priority have the same scheduling policy.  We'll discuss that
+first.
+
+In Round Robin, processes share the CPU, each one running for a small
+quantum of time (``time slice'') and then yielding to another in a
+circular fashion.  Of course, only processes that are ready to run and
+have the same absolute priority are in this circle.
+
+In First Come First Served, the process that has been waiting the
+longest to run gets the CPU, and it keeps it until it voluntarily
+relinquishes the CPU, runs out of things to do (blocks), or gets
+preempted by a higher priority process.
+
+First Come First Served, along with maximal absolute priority and
+careful control of interrupts and page faults, is the one to use when a
+process absolutely, positively has to run at full CPU speed or not at
+all.
+
+Judicious use of @code{sched_yield} function invocations by processes
+with First Come First Served scheduling policy forms a good compromise
+between Round Robin and First Come First Served.
+
+To understand how scheduling works when processes of different scheduling
+policies occupy the same absolute priority, you have to know the nitty
+gritty details of how processes enter and exit the ready to run list:
+
+In both cases, the ready to run list is organized as a true queue, where
+a process gets pushed onto the tail when it becomes ready to run and is
+popped off the head when the scheduler decides to run it.  Note that
+ready to run and running are two mutually exclusive states.  When the
+scheduler runs a process, that process is no longer ready to run and no
+longer in the ready to run list.  When the process stops running, it
+may go back to being ready to run again.
+
+The only difference between a process that is assigned the Round Robin
+scheduling policy and a process that is assigned First Come First Serve
+is that in the former case, the process is automatically booted off the
+CPU after a certain amount of time.  When that happens, the process goes
+back to being ready to run, which means it enters the queue at the tail.
+The time quantum we're talking about is small.  Really small.  This is
+not your father's timesharing.  For example, with the Linux kernel, the
+round robin time slice is a thousand times shorter than its typical
+time slice for traditional scheduling.
+
+A process begins life with the same scheduling policy as its parent process.
+Functions described in @ref{Basic Scheduling Functions} can change it.
+
+Only a privileged process can set the scheduling policy of a process
+that has absolute priority higher than 0.
+
+@node Basic Scheduling Functions
+@subsection Basic Scheduling Functions
+
+This section describes functions in @theglibc{} for setting the
+absolute priority and scheduling policy of a process.
+
+@strong{Portability Note:}  On systems that have the functions in this
+section, the macro _POSIX_PRIORITY_SCHEDULING is defined in
+@file{<unistd.h>}.
+
+For the case that the scheduling policy is traditional scheduling, more
+functions to fine tune the scheduling are in @ref{Traditional Scheduling}.
+
+Don't try to make too much out of the naming and structure of these
+functions.  They don't match the concepts described in this manual
+because the functions are as defined by POSIX.1b, but the implementation
+on systems that use @theglibc{} is the inverse of what the POSIX
+structure contemplates.  The POSIX scheme assumes that the primary
+scheduling parameter is the scheduling policy and that the priority
+value, if any, is a parameter of the scheduling policy.  In the
+implementation, though, the priority value is king and the scheduling
+policy, if anything, only fine tunes the effect of that priority.
+
+The symbols in this section are declared by including file @file{sched.h}.
+
+@comment sched.h
+@comment POSIX
+@deftp {Data Type} {struct sched_param}
+This structure describes an absolute priority.
+@table @code
+@item int sched_priority
+absolute priority value
+@end table
+@end deftp
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_setscheduler (pid_t @var{pid}, int @var{policy}, const struct sched_param *@var{param})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function sets both the absolute priority and the scheduling policy
+for a process.
+
+It assigns the absolute priority value given by @var{param} and the
+scheduling policy @var{policy} to the process with Process ID @var{pid},
+or the calling process if @var{pid} is zero.  If @var{policy} is
+negative, @code{sched_setscheduler} keeps the existing scheduling policy.
+
+The following macros represent the valid values for @var{policy}:
+
+@table @code
+@item SCHED_OTHER
+Traditional Scheduling
+@item SCHED_FIFO
+First In First Out
+@item SCHED_RR
+Round Robin
+@end table
+
+@c The Linux kernel code (in sched.c) actually reschedules the process,
+@c but it puts it at the head of the run queue, so I'm not sure just what
+@c the effect is, but it must be subtle.
+
+On success, the return value is @code{0}.  Otherwise, it is @code{-1}
+and @code{ERRNO} is set accordingly.  The @code{errno} values specific
+to this function are:
+
+@table @code
+@item EPERM
+@itemize @bullet
+@item
+The calling process does not have @code{CAP_SYS_NICE} permission and
+@var{policy} is not @code{SCHED_OTHER} (or it's negative and the
+existing policy is not @code{SCHED_OTHER}.
+
+@item
+The calling process does not have @code{CAP_SYS_NICE} permission and its
+owner is not the target process' owner.  I.e., the effective uid of the
+calling process is neither the effective nor the real uid of process
+@var{pid}.
+@c We need a cross reference to the capabilities section, when written.
+@end itemize
+
+@item ESRCH
+There is no process with pid @var{pid} and @var{pid} is not zero.
+
+@item EINVAL
+@itemize @bullet
+@item
+@var{policy} does not identify an existing scheduling policy.
+
+@item
+The absolute priority value identified by *@var{param} is outside the
+valid range for the scheduling policy @var{policy} (or the existing
+scheduling policy if @var{policy} is negative) or @var{param} is
+null.  @code{sched_get_priority_max} and @code{sched_get_priority_min}
+tell you what the valid range is.
+
+@item
+@var{pid} is negative.
+@end itemize
+@end table
+
+@end deftypefun
+
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_getscheduler (pid_t @var{pid})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function returns the scheduling policy assigned to the process with
+Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero.
+
+The return value is the scheduling policy.  See
+@code{sched_setscheduler} for the possible values.
+
+If the function fails, the return value is instead @code{-1} and
+@code{errno} is set accordingly.
+
+The @code{errno} values specific to this function are:
+
+@table @code
+
+@item ESRCH
+There is no process with pid @var{pid} and it is not zero.
+
+@item EINVAL
+@var{pid} is negative.
+
+@end table
+
+Note that this function is not an exact mate to @code{sched_setscheduler}
+because while that function sets the scheduling policy and the absolute
+priority, this function gets only the scheduling policy.  To get the
+absolute priority, use @code{sched_getparam}.
+
+@end deftypefun
+
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_setparam (pid_t @var{pid}, const struct sched_param *@var{param})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function sets a process' absolute priority.
+
+It is functionally identical to @code{sched_setscheduler} with
+@var{policy} = @code{-1}.
+
+@c in fact, that's how it's implemented in Linux.
+
+@end deftypefun
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_getparam (pid_t @var{pid}, struct sched_param *@var{param})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function returns a process' absolute priority.
+
+@var{pid} is the Process ID (pid) of the process whose absolute priority
+you want to know.
+
+@var{param} is a pointer to a structure in which the function stores the
+absolute priority of the process.
+
+On success, the return value is @code{0}.  Otherwise, it is @code{-1}
+and @code{ERRNO} is set accordingly.  The @code{errno} values specific
+to this function are:
+
+@table @code
+
+@item ESRCH
+There is no process with pid @var{pid} and it is not zero.
+
+@item EINVAL
+@var{pid} is negative.
+
+@end table
+
+@end deftypefun
+
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_get_priority_min (int @var{policy})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function returns the lowest absolute priority value that is
+allowable for a process with scheduling policy @var{policy}.
+
+On Linux, it is 0 for SCHED_OTHER and 1 for everything else.
+
+On success, the return value is @code{0}.  Otherwise, it is @code{-1}
+and @code{ERRNO} is set accordingly.  The @code{errno} values specific
+to this function are:
+
+@table @code
+@item EINVAL
+@var{policy} does not identify an existing scheduling policy.
+@end table
+
+@end deftypefun
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_get_priority_max (int @var{policy})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function returns the highest absolute priority value that is
+allowable for a process that with scheduling policy @var{policy}.
+
+On Linux, it is 0 for SCHED_OTHER and 99 for everything else.
+
+On success, the return value is @code{0}.  Otherwise, it is @code{-1}
+and @code{ERRNO} is set accordingly.  The @code{errno} values specific
+to this function are:
+
+@table @code
+@item EINVAL
+@var{policy} does not identify an existing scheduling policy.
+@end table
+
+@end deftypefun
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_rr_get_interval (pid_t @var{pid}, struct timespec *@var{interval})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+This function returns the length of the quantum (time slice) used with
+the Round Robin scheduling policy, if it is used, for the process with
+Process ID @var{pid}.
+
+It returns the length of time as @var{interval}.
+@c We need a cross-reference to where timespec is explained.  But that
+@c section doesn't exist yet, and the time chapter needs to be slightly
+@c reorganized so there is a place to put it (which will be right next
+@c to timeval, which is presently misplaced).  2000.05.07.
+
+With a Linux kernel, the round robin time slice is always 150
+microseconds, and @var{pid} need not even be a real pid.
+
+The return value is @code{0} on success and in the pathological case
+that it fails, the return value is @code{-1} and @code{errno} is set
+accordingly.  There is nothing specific that can go wrong with this
+function, so there are no specific @code{errno} values.
+
+@end deftypefun
+
+@comment sched.h
+@comment POSIX
+@deftypefun int sched_yield (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on Linux; alias to swtch on HURD.
+
+This function voluntarily gives up the process' claim on the CPU.
+
+Technically, @code{sched_yield} causes the calling process to be made
+immediately ready to run (as opposed to running, which is what it was
+before).  This means that if it has absolute priority higher than 0, it
+gets pushed onto the tail of the queue of processes that share its
+absolute priority and are ready to run, and it will run again when its
+turn next arrives.  If its absolute priority is 0, it is more
+complicated, but still has the effect of yielding the CPU to other
+processes.
+
+If there are no other processes that share the calling process' absolute
+priority, this function doesn't have any effect.
+
+To the extent that the containing program is oblivious to what other
+processes in the system are doing and how fast it executes, this
+function appears as a no-op.
+
+The return value is @code{0} on success and in the pathological case
+that it fails, the return value is @code{-1} and @code{errno} is set
+accordingly.  There is nothing specific that can go wrong with this
+function, so there are no specific @code{errno} values.
+
+@end deftypefun
+
+@node Traditional Scheduling
+@subsection Traditional Scheduling
+@cindex scheduling, traditional
+
+This section is about the scheduling among processes whose absolute
+priority is 0.  When the system hands out the scraps of CPU time that
+are left over after the processes with higher absolute priority have
+taken all they want, the scheduling described herein determines who
+among the great unwashed processes gets them.
+
+@menu
+* Traditional Scheduling Intro::
+* Traditional Scheduling Functions::
+@end menu
+
+@node Traditional Scheduling Intro
+@subsubsection Introduction To Traditional Scheduling
+
+Long before there was absolute priority (See @ref{Absolute Priority}),
+Unix systems were scheduling the CPU using this system.  When Posix came
+in like the Romans and imposed absolute priorities to accommodate the
+needs of realtime processing, it left the indigenous Absolute Priority
+Zero processes to govern themselves by their own familiar scheduling
+policy.
+
+Indeed, absolute priorities higher than zero are not available on many
+systems today and are not typically used when they are, being intended
+mainly for computers that do realtime processing.  So this section
+describes the only scheduling many programmers need to be concerned
+about.
+
+But just to be clear about the scope of this scheduling: Any time a
+process with an absolute priority of 0 and a process with an absolute
+priority higher than 0 are ready to run at the same time, the one with
+absolute priority 0 does not run.  If it's already running when the
+higher priority ready-to-run process comes into existence, it stops
+immediately.
+
+In addition to its absolute priority of zero, every process has another
+priority, which we will refer to as "dynamic priority" because it changes
+over time.  The dynamic priority is meaningless for processes with
+an absolute priority higher than zero.
+
+The dynamic priority sometimes determines who gets the next turn on the
+CPU.  Sometimes it determines how long turns last.  Sometimes it
+determines whether a process can kick another off the CPU.
+
+In Linux, the value is a combination of these things, but mostly it is
+just determines the length of the time slice.  The higher a process'
+dynamic priority, the longer a shot it gets on the CPU when it gets one.
+If it doesn't use up its time slice before giving up the CPU to do
+something like wait for I/O, it is favored for getting the CPU back when
+it's ready for it, to finish out its time slice.  Other than that,
+selection of processes for new time slices is basically round robin.
+But the scheduler does throw a bone to the low priority processes: A
+process' dynamic priority rises every time it is snubbed in the
+scheduling process.  In Linux, even the fat kid gets to play.
+
+The fluctuation of a process' dynamic priority is regulated by another
+value: The ``nice'' value.  The nice value is an integer, usually in the
+range -20 to 20, and represents an upper limit on a process' dynamic
+priority.  The higher the nice number, the lower that limit.
+
+On a typical Linux system, for example, a process with a nice value of
+20 can get only 10 milliseconds on the CPU at a time, whereas a process
+with a nice value of -20 can achieve a high enough priority to get 400
+milliseconds.
+
+The idea of the nice value is deferential courtesy.  In the beginning,
+in the Unix garden of Eden, all processes shared equally in the bounty
+of the computer system.  But not all processes really need the same
+share of CPU time, so the nice value gave a courteous process the
+ability to refuse its equal share of CPU time that others might prosper.
+Hence, the higher a process' nice value, the nicer the process is.
+(Then a snake came along and offered some process a negative nice value
+and the system became the crass resource allocation system we know
+today).
+
+Dynamic priorities tend upward and downward with an objective of
+smoothing out allocation of CPU time and giving quick response time to
+infrequent requests.  But they never exceed their nice limits, so on a
+heavily loaded CPU, the nice value effectively determines how fast a
+process runs.
+
+In keeping with the socialistic heritage of Unix process priority, a
+process begins life with the same nice value as its parent process and
+can raise it at will.  A process can also raise the nice value of any
+other process owned by the same user (or effective user).  But only a
+privileged process can lower its nice value.  A privileged process can
+also raise or lower another process' nice value.
+
+@glibcadj{} functions for getting and setting nice values are described in
+@xref{Traditional Scheduling Functions}.
+
+@node Traditional Scheduling Functions
+@subsubsection Functions For Traditional Scheduling
+
+@pindex sys/resource.h
+This section describes how you can read and set the nice value of a
+process.  All these symbols are declared in @file{sys/resource.h}.
+
+The function and macro names are defined by POSIX, and refer to
+"priority," but the functions actually have to do with nice values, as
+the terms are used both in the manual and POSIX.
+
+The range of valid nice values depends on the kernel, but typically it
+runs from @code{-20} to @code{20}.  A lower nice value corresponds to
+higher priority for the process.  These constants describe the range of
+priority values:
+
+@vtable @code
+@comment sys/resource.h
+@comment BSD
+@item PRIO_MIN
+The lowest valid nice value.
+
+@comment sys/resource.h
+@comment BSD
+@item PRIO_MAX
+The highest valid nice value.
+@end vtable
+
+@comment sys/resource.h
+@comment BSD,POSIX
+@deftypefun int getpriority (int @var{class}, int @var{id})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on UNIX.  On HURD, calls _hurd_priority_which_map.
+Return the nice value of a set of processes; @var{class} and @var{id}
+specify which ones (see below).  If the processes specified do not all
+have the same nice value, this returns the lowest value that any of them
+has.
+
+On success, the return value is @code{0}.  Otherwise, it is @code{-1}
+and @code{ERRNO} is set accordingly.  The @code{errno} values specific
+to this function are:
+
+@table @code
+@item ESRCH
+The combination of @var{class} and @var{id} does not match any existing
+process.
+
+@item EINVAL
+The value of @var{class} is not valid.
+@end table
+
+If the return value is @code{-1}, it could indicate failure, or it could
+be the nice value.  The only way to make certain is to set @code{errno =
+0} before calling @code{getpriority}, then use @code{errno != 0}
+afterward as the criterion for failure.
+@end deftypefun
+
+@comment sys/resource.h
+@comment BSD,POSIX
+@deftypefun int setpriority (int @var{class}, int @var{id}, int @var{niceval})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on UNIX.  On HURD, calls _hurd_priority_which_map.
+Set the nice value of a set of processes to @var{niceval}; @var{class}
+and @var{id} specify which ones (see below).
+
+The return value is @code{0} on success, and @code{-1} on
+failure.  The following @code{errno} error condition are possible for
+this function:
+
+@table @code
+@item ESRCH
+The combination of @var{class} and @var{id} does not match any existing
+process.
+
+@item EINVAL
+The value of @var{class} is not valid.
+
+@item EPERM
+The call would set the nice value of a process which is owned by a different
+user than the calling process (i.e., the target process' real or effective
+uid does not match the calling process' effective uid) and the calling
+process does not have @code{CAP_SYS_NICE} permission.
+
+@item EACCES
+The call would lower the process' nice value and the process does not have
+@code{CAP_SYS_NICE} permission.
+@end table
+
+@end deftypefun
+
+The arguments @var{class} and @var{id} together specify a set of
+processes in which you are interested.  These are the possible values of
+@var{class}:
+
+@vtable @code
+@comment sys/resource.h
+@comment BSD
+@item PRIO_PROCESS
+One particular process.  The argument @var{id} is a process ID (pid).
+
+@comment sys/resource.h
+@comment BSD
+@item PRIO_PGRP
+All the processes in a particular process group.  The argument @var{id} is
+a process group ID (pgid).
+
+@comment sys/resource.h
+@comment BSD
+@item PRIO_USER
+All the processes owned by a particular user (i.e., whose real uid
+indicates the user).  The argument @var{id} is a user ID (uid).
+@end vtable
+
+If the argument @var{id} is 0, it stands for the calling process, its
+process group, or its owner (real uid), according to @var{class}.
+
+@comment unistd.h
+@comment BSD
+@deftypefun int nice (int @var{increment})
+@safety{@prelim{}@mtunsafe{@mtasurace{:setpriority}}@asunsafe{}@acsafe{}}
+@c Calls getpriority before and after setpriority, using the result of
+@c the first call to compute the argument for setpriority.  This creates
+@c a window for a concurrent setpriority (or nice) call to be lost or
+@c exhibit surprising behavior.
+Increment the nice value of the calling process by @var{increment}.
+The return value is the new nice value on success, and @code{-1} on
+failure.  In the case of failure, @code{errno} will be set to the
+same values as for @code{setpriority}.
+
+
+Here is an equivalent definition of @code{nice}:
+
+@smallexample
+int
+nice (int increment)
+@{
+  int result, old = getpriority (PRIO_PROCESS, 0);
+  result = setpriority (PRIO_PROCESS, 0, old + increment);
+  if (result != -1)
+      return old + increment;
+  else
+      return -1;
+@}
+@end smallexample
+@end deftypefun
+
+
+@node CPU Affinity
+@subsection Limiting execution to certain CPUs
+
+On a multi-processor system the operating system usually distributes
+the different processes which are runnable on all available CPUs in a
+way which allows the system to work most efficiently.  Which processes
+and threads run can be to some extend be control with the scheduling
+functionality described in the last sections.  But which CPU finally
+executes which process or thread is not covered.
+
+There are a number of reasons why a program might want to have control
+over this aspect of the system as well:
+
+@itemize @bullet
+@item
+One thread or process is responsible for absolutely critical work
+which under no circumstances must be interrupted or hindered from
+making process by other process or threads using CPU resources.  In
+this case the special process would be confined to a CPU which no
+other process or thread is allowed to use.
+
+@item
+The access to certain resources (RAM, I/O ports) has different costs
+from different CPUs.  This is the case in NUMA (Non-Uniform Memory
+Architecture) machines.  Preferably memory should be accessed locally
+but this requirement is usually not visible to the scheduler.
+Therefore forcing a process or thread to the CPUs which have local
+access to the mostly used memory helps to significantly boost the
+performance.
+
+@item
+In controlled runtimes resource allocation and book-keeping work (for
+instance garbage collection) is performance local to processors.  This
+can help to reduce locking costs if the resources do not have to be
+protected from concurrent accesses from different processors.
+@end itemize
+
+The POSIX standard up to this date is of not much help to solve this
+problem.  The Linux kernel provides a set of interfaces to allow
+specifying @emph{affinity sets} for a process.  The scheduler will
+schedule the thread or process on CPUs specified by the affinity
+masks.  The interfaces which @theglibc{} define follow to some
+extend the Linux kernel interface.
+
+@comment sched.h
+@comment GNU
+@deftp {Data Type} cpu_set_t
+This data set is a bitset where each bit represents a CPU.  How the
+system's CPUs are mapped to bits in the bitset is system dependent.
+The data type has a fixed size; in the unlikely case that the number
+of bits are not sufficient to describe the CPUs of the system a
+different interface has to be used.
+
+This type is a GNU extension and is defined in @file{sched.h}.
+@end deftp
+
+To manipulate the bitset, to set and reset bits, a number of macros is
+defined.  Some of the macros take a CPU number as a parameter.  Here
+it is important to never exceed the size of the bitset.  The following
+macro specifies the number of bits in the @code{cpu_set_t} bitset.
+
+@comment sched.h
+@comment GNU
+@deftypevr Macro int CPU_SETSIZE
+The value of this macro is the maximum number of CPUs which can be
+handled with a @code{cpu_set_t} object.
+@end deftypevr
+
+The type @code{cpu_set_t} should be considered opaque; all
+manipulation should happen via the next four macros.
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_ZERO ok
+@c  __CPU_ZERO_S ok
+@c   memset dup ok
+This macro initializes the CPU set @var{set} to be the empty set.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_SET (int @var{cpu}, cpu_set_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_SET ok
+@c  __CPU_SET_S ok
+@c   __CPUELT ok
+@c   __CPUMASK ok
+This macro adds @var{cpu} to the CPU set @var{set}.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro void CPU_CLR (int @var{cpu}, cpu_set_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_CLR ok
+@c  __CPU_CLR_S ok
+@c   __CPUELT dup ok
+@c   __CPUMASK dup ok
+This macro removes @var{cpu} from the CPU set @var{set}.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+@comment sched.h
+@comment GNU
+@deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c CPU_ISSET ok
+@c  __CPU_ISSET_S ok
+@c   __CPUELT dup ok
+@c   __CPUMASK dup ok
+This macro returns a nonzero value (true) if @var{cpu} is a member
+of the CPU set @var{set}, and zero (false) otherwise.
+
+The @var{cpu} parameter must not have side effects since it is
+evaluated more than once.
+
+This macro is a GNU extension and is defined in @file{sched.h}.
+@end deftypefn
+
+
+CPU bitsets can be constructed from scratch or the currently installed
+affinity mask can be retrieved from the system.
+
+@comment sched.h
+@comment GNU
+@deftypefun int sched_getaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapped syscall to zero out past the kernel cpu set size; Linux
+@c only.
+
+This functions stores the CPU affinity mask for the process or thread
+with the ID @var{pid} in the @var{cpusetsize} bytes long bitmap
+pointed to by @var{cpuset}.  If successful, the function always
+initializes all bits in the @code{cpu_set_t} object and returns zero.
+
+If @var{pid} does not correspond to a process or thread on the system
+the or the function fails for some other reason, it returns @code{-1}
+and @code{errno} is set to represent the error condition.
+
+@table @code
+@item ESRCH
+No process or thread with the given ID found.
+
+@item EFAULT
+The pointer @var{cpuset} is does not point to a valid object.
+@end table
+
+This function is a GNU extension and is declared in @file{sched.h}.
+@end deftypefun
+
+Note that it is not portably possible to use this information to
+retrieve the information for different POSIX threads.  A separate
+interface must be provided for that.
+
+@comment sched.h
+@comment GNU
+@deftypefun int sched_setaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapped syscall to detect attempts to set bits past the kernel cpu
+@c set size; Linux only.
+
+This function installs the @var{cpusetsize} bytes long affinity mask
+pointed to by @var{cpuset} for the process or thread with the ID @var{pid}.
+If successful the function returns zero and the scheduler will in future
+take the affinity information into account.
+
+If the function fails it will return @code{-1} and @code{errno} is set
+to the error code:
+
+@table @code
+@item ESRCH
+No process or thread with the given ID found.
+
+@item EFAULT
+The pointer @var{cpuset} is does not point to a valid object.
+
+@item EINVAL
+The bitset is not valid.  This might mean that the affinity set might
+not leave a processor for the process or thread to run on.
+@end table
+
+This function is a GNU extension and is declared in @file{sched.h}.
+@end deftypefun
+
+
+@node Memory Resources
+@section Querying memory available resources
+
+The amount of memory available in the system and the way it is organized
+determines oftentimes the way programs can and have to work.  For
+functions like @code{mmap} it is necessary to know about the size of
+individual memory pages and knowing how much memory is available enables
+a program to select appropriate sizes for, say, caches.  Before we get
+into these details a few words about memory subsystems in traditional
+Unix systems will be given.
+
+@menu
+* Memory Subsystem::           Overview about traditional Unix memory handling.
+* Query Memory Parameters::    How to get information about the memory
+                                subsystem?
+@end menu
+
+@node Memory Subsystem
+@subsection Overview about traditional Unix memory handling
+
+@cindex address space
+@cindex physical memory
+@cindex physical address
+Unix systems normally provide processes virtual address spaces.  This
+means that the addresses of the memory regions do not have to correspond
+directly to the addresses of the actual physical memory which stores the
+data.  An extra level of indirection is introduced which translates
+virtual addresses into physical addresses.  This is normally done by the
+hardware of the processor.
+
+@cindex shared memory
+Using a virtual address space has several advantage.  The most important
+is process isolation.  The different processes running on the system
+cannot interfere directly with each other.  No process can write into
+the address space of another process (except when shared memory is used
+but then it is wanted and controlled).
+
+Another advantage of virtual memory is that the address space the
+processes see can actually be larger than the physical memory available.
+The physical memory can be extended by storage on an external media
+where the content of currently unused memory regions is stored.  The
+address translation can then intercept accesses to these memory regions
+and make memory content available again by loading the data back into
+memory.  This concept makes it necessary that programs which have to use
+lots of memory know the difference between available virtual address
+space and available physical memory.  If the working set of virtual
+memory of all the processes is larger than the available physical memory
+the system will slow down dramatically due to constant swapping of
+memory content from the memory to the storage media and back.  This is
+called ``thrashing''.
+@cindex thrashing
+
+@cindex memory page
+@cindex page, memory
+A final aspect of virtual memory which is important and follows from
+what is said in the last paragraph is the granularity of the virtual
+address space handling.  When we said that the virtual address handling
+stores memory content externally it cannot do this on a byte-by-byte
+basis.  The administrative overhead does not allow this (leaving alone
+the processor hardware).  Instead several thousand bytes are handled
+together and form a @dfn{page}.  The size of each page is always a power
+of two byte.  The smallest page size in use today is 4096, with 8192,
+16384, and 65536 being other popular sizes.
+
+@node Query Memory Parameters
+@subsection How to get information about the memory subsystem?
+
+The page size of the virtual memory the process sees is essential to
+know in several situations.  Some programming interface (e.g.,
+@code{mmap}, @pxref{Memory-mapped I/O}) require the user to provide
+information adjusted to the page size.  In the case of @code{mmap} is it
+necessary to provide a length argument which is a multiple of the page
+size.  Another place where the knowledge about the page size is useful
+is in memory allocation.  If one allocates pieces of memory in larger
+chunks which are then subdivided by the application code it is useful to
+adjust the size of the larger blocks to the page size.  If the total
+memory requirement for the block is close (but not larger) to a multiple
+of the page size the kernel's memory handling can work more effectively
+since it only has to allocate memory pages which are fully used.  (To do
+this optimization it is necessary to know a bit about the memory
+allocator which will require a bit of memory itself for each block and
+this overhead must not push the total size over the page size multiple.
+
+The page size traditionally was a compile time constant.  But recent
+development of processors changed this.  Processors now support
+different page sizes and they can possibly even vary among different
+processes on the same system.  Therefore the system should be queried at
+runtime about the current page size and no assumptions (except about it
+being a power of two) should be made.
+
+@vindex _SC_PAGESIZE
+The correct interface to query about the page size is @code{sysconf}
+(@pxref{Sysconf Definition}) with the parameter @code{_SC_PAGESIZE}.
+There is a much older interface available, too.
+
+@comment unistd.h
+@comment BSD
+@deftypefun int getpagesize (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Obtained from the aux vec at program startup time.  GNU/Linux/m68k is
+@c the exception, with the possibility of a syscall.
+The @code{getpagesize} function returns the page size of the process.
+This value is fixed for the runtime of the process but can vary in
+different runs of the application.
+
+The function is declared in @file{unistd.h}.
+@end deftypefun
+
+Widely available on @w{System V} derived systems is a method to get
+information about the physical memory the system has.  The call
+
+@vindex _SC_PHYS_PAGES
+@cindex sysconf
+@smallexample
+  sysconf (_SC_PHYS_PAGES)
+@end smallexample
+
+@noindent
+returns the total number of pages of physical the system has.
+This does not mean all this memory is available.  This information can
+be found using
+
+@vindex _SC_AVPHYS_PAGES
+@cindex sysconf
+@smallexample
+  sysconf (_SC_AVPHYS_PAGES)
+@end smallexample
+
+These two values help to optimize applications.  The value returned for
+@code{_SC_AVPHYS_PAGES} is the amount of memory the application can use
+without hindering any other process (given that no other process
+increases its memory usage).  The value returned for
+@code{_SC_PHYS_PAGES} is more or less a hard limit for the working set.
+If all applications together constantly use more than that amount of
+memory the system is in trouble.
+
+@Theglibc{} provides in addition to these already described way to
+get this information two functions.  They are declared in the file
+@file{sys/sysinfo.h}.  Programmers should prefer to use the
+@code{sysconf} method described above.
+
+@comment sys/sysinfo.h
+@comment GNU
+@deftypefun {long int} get_phys_pages (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c This fopens a /proc file and scans it for the requested information.
+The @code{get_phys_pages} function returns the total number of pages of
+physical the system has.  To get the amount of memory this number has to
+be multiplied by the page size.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment sys/sysinfo.h
+@comment GNU
+@deftypefun {long int} get_avphys_pages (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+The @code{get_avphys_pages} function returns the number of available pages of
+physical the system has.  To get the amount of memory this number has to
+be multiplied by the page size.
+
+This function is a GNU extension.
+@end deftypefun
+
+@node Processor Resources
+@section Learn about the processors available
+
+The use of threads or processes with shared memory allows an application
+to take advantage of all the processing power a system can provide.  If
+the task can be parallelized the optimal way to write an application is
+to have at any time as many processes running as there are processors.
+To determine the number of processors available to the system one can
+run
+
+@vindex _SC_NPROCESSORS_CONF
+@cindex sysconf
+@smallexample
+  sysconf (_SC_NPROCESSORS_CONF)
+@end smallexample
+
+@noindent
+which returns the number of processors the operating system configured.
+But it might be possible for the operating system to disable individual
+processors and so the call
+
+@vindex _SC_NPROCESSORS_ONLN
+@cindex sysconf
+@smallexample
+  sysconf (_SC_NPROCESSORS_ONLN)
+@end smallexample
+
+@noindent
+returns the number of processors which are currently online (i.e.,
+available).
+
+For these two pieces of information @theglibc{} also provides
+functions to get the information directly.  The functions are declared
+in @file{sys/sysinfo.h}.
+
+@comment sys/sysinfo.h
+@comment GNU
+@deftypefun int get_nprocs_conf (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c This function reads from from /sys using dir streams (single user, so
+@c no @mtasurace issue), and on some arches, from /proc using streams.
+The @code{get_nprocs_conf} function returns the number of processors the
+operating system configured.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment sys/sysinfo.h
+@comment GNU
+@deftypefun int get_nprocs (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c This function reads from /proc using file descriptor I/O.
+The @code{get_nprocs} function returns the number of available processors.
+
+This function is a GNU extension.
+@end deftypefun
+
+@cindex load average
+Before starting more threads it should be checked whether the processors
+are not already overused.  Unix systems calculate something called the
+@dfn{load average}.  This is a number indicating how many processes were
+running.  This number is average over different periods of times
+(normally 1, 5, and 15 minutes).
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int getloadavg (double @var{loadavg}[], int @var{nelem})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c Calls host_info on HURD; on Linux, opens /proc/loadavg, reads from
+@c it, closes it, without cancellation point, and calls strtod_l with
+@c the C locale to convert the strings to doubles.
+This function gets the 1, 5 and 15 minute load averages of the
+system.  The values are placed in @var{loadavg}.  @code{getloadavg} will
+place at most @var{nelem} elements into the array but never more than
+three elements.  The return value is the number of elements written to
+@var{loadavg}, or -1 on error.
+
+This function is declared in @file{stdlib.h}.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/search.texi b/ap/libc/glibc/glibc-2.23/manual/search.texi
new file mode 100644
index 0000000..662527f
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/search.texi
@@ -0,0 +1,637 @@
+@node Searching and Sorting, Pattern Matching, Message Translation, Top
+@c %MENU% General searching and sorting functions
+@chapter Searching and Sorting
+
+This chapter describes functions for searching and sorting arrays of
+arbitrary objects.  You pass the appropriate comparison function to be
+applied as an argument, along with the size of the objects in the array
+and the total number of elements.
+
+@menu
+* Comparison Functions::        Defining how to compare two objects.
+				 Since the sort and search facilities
+                                 are general, you have to specify the
+                                 ordering.
+* Array Search Function::       The @code{bsearch} function.
+* Array Sort Function::         The @code{qsort} function.
+* Search/Sort Example::         An example program.
+* Hash Search Function::        The @code{hsearch} function.
+* Tree Search Function::        The @code{tsearch} function.
+@end menu
+
+@node Comparison Functions
+@section Defining the Comparison Function
+@cindex Comparison Function
+
+In order to use the sorted array library functions, you have to describe
+how to compare the elements of the array.
+
+To do this, you supply a comparison function to compare two elements of
+the array.  The library will call this function, passing as arguments
+pointers to two array elements to be compared.  Your comparison function
+should return a value the way @code{strcmp} (@pxref{String/Array
+Comparison}) does: negative if the first argument is ``less'' than the
+second, zero if they are ``equal'', and positive if the first argument
+is ``greater''.
+
+Here is an example of a comparison function which works with an array of
+numbers of type @code{double}:
+
+@smallexample
+int
+compare_doubles (const void *a, const void *b)
+@{
+  const double *da = (const double *) a;
+  const double *db = (const double *) b;
+
+  return (*da > *db) - (*da < *db);
+@}
+@end smallexample
+
+The header file @file{stdlib.h} defines a name for the data type of
+comparison functions.  This type is a GNU extension.
+
+@comment stdlib.h
+@comment GNU
+@tindex comparison_fn_t
+@smallexample
+int comparison_fn_t (const void *, const void *);
+@end smallexample
+
+@node Array Search Function
+@section Array Search Function
+@cindex search function (for arrays)
+@cindex binary search function (for arrays)
+@cindex array search function
+
+Generally searching for a specific element in an array means that
+potentially all elements must be checked.  @Theglibc{} contains
+functions to perform linear search.  The prototypes for the following
+two functions can be found in @file{search.h}.
+
+@comment search.h
+@comment SVID
+@deftypefun {void *} lfind (const void *@var{key}, const void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{lfind} function searches in the array with @code{*@var{nmemb}}
+elements of @var{size} bytes pointed to by @var{base} for an element
+which matches the one pointed to by @var{key}.  The function pointed to
+by @var{compar} is used decide whether two elements match.
+
+The return value is a pointer to the matching element in the array
+starting at @var{base} if it is found.  If no matching element is
+available @code{NULL} is returned.
+
+The mean runtime of this function is @code{*@var{nmemb}}/2.  This
+function should only be used if elements often get added to or deleted from
+the array in which case it might not be useful to sort the array before
+searching.
+@end deftypefun
+
+@comment search.h
+@comment SVID
+@deftypefun {void *} lsearch (const void *@var{key}, void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c A signal handler that interrupted an insertion and performed an
+@c insertion itself would leave the array in a corrupt state (e.g. one
+@c new element initialized twice, with parts of both initializations
+@c prevailing, and another uninitialized element), but this is just a
+@c special case of races on user-controlled objects, that have to be
+@c avoided by users.
+
+@c In case of cancellation, we know the array won't be left in a corrupt
+@c state; the new element is initialized before the element count is
+@c incremented, and the compiler can't reorder these operations because
+@c it can't know that they don't alias.  So, we'll either cancel after
+@c the increment and the initialization are both complete, or the
+@c increment won't have taken place, and so how far the initialization
+@c got doesn't matter.
+The @code{lsearch} function is similar to the @code{lfind} function.  It
+searches the given array for an element and returns it if found.  The
+difference is that if no matching element is found the @code{lsearch}
+function adds the object pointed to by @var{key} (with a size of
+@var{size} bytes) at the end of the array and it increments the value of
+@code{*@var{nmemb}} to reflect this addition.
+
+This means for the caller that if it is not sure that the array contains
+the element one is searching for the memory allocated for the array
+starting at @var{base} must have room for at least @var{size} more
+bytes.  If one is sure the element is in the array it is better to use
+@code{lfind} so having more room in the array is always necessary when
+calling @code{lsearch}.
+@end deftypefun
+
+To search a sorted array for an element matching the key, use the
+@code{bsearch} function.  The prototype for this function is in
+the header file @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {void *} bsearch (const void *@var{key}, const void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{bsearch} function searches the sorted array @var{array} for an object
+that is equivalent to @var{key}.  The array contains @var{count} elements,
+each of which is of size @var{size} bytes.
+
+The @var{compare} function is used to perform the comparison.  This
+function is called with two pointer arguments and should return an
+integer less than, equal to, or greater than zero corresponding to
+whether its first argument is considered less than, equal to, or greater
+than its second argument.  The elements of the @var{array} must already
+be sorted in ascending order according to this comparison function.
+
+The return value is a pointer to the matching array element, or a null
+pointer if no match is found.  If the array contains more than one element
+that matches, the one that is returned is unspecified.
+
+This function derives its name from the fact that it is implemented
+using the binary search algorithm.
+@end deftypefun
+
+@node Array Sort Function
+@section Array Sort Function
+@cindex sort function (for arrays)
+@cindex quick sort function (for arrays)
+@cindex array sort function
+
+To sort an array using an arbitrary comparison function, use the
+@code{qsort} function.  The prototype for this function is in
+@file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ISO
+@deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+The @code{qsort} function sorts the array @var{array}.  The array
+contains @var{count} elements, each of which is of size @var{size}.
+
+The @var{compare} function is used to perform the comparison on the
+array elements.  This function is called with two pointer arguments and
+should return an integer less than, equal to, or greater than zero
+corresponding to whether its first argument is considered less than,
+equal to, or greater than its second argument.
+
+@cindex stable sorting
+@strong{Warning:} If two objects compare as equal, their order after
+sorting is unpredictable.  That is to say, the sorting is not stable.
+This can make a difference when the comparison considers only part of
+the elements.  Two elements with the same sort key may differ in other
+respects.
+
+Although the object addresses passed to the comparison function lie
+within the array, they need not correspond with the original locations
+of those objects because the sorting algorithm may swap around objects
+in the array before making some comparisons.  The only way to perform
+a stable sort with @code{qsort} is to first augment the objects with a
+monotonic counter of some kind.
+
+Here is a simple example of sorting an array of doubles in numerical
+order, using the comparison function defined above (@pxref{Comparison
+Functions}):
+
+@smallexample
+@{
+  double *array;
+  int size;
+  @dots{}
+  qsort (array, size, sizeof (double), compare_doubles);
+@}
+@end smallexample
+
+The @code{qsort} function derives its name from the fact that it was
+originally implemented using the ``quick sort'' algorithm.
+
+The implementation of @code{qsort} in this library might not be an
+in-place sort and might thereby use an extra amount of memory to store
+the array.
+@end deftypefun
+
+@node Search/Sort Example
+@section Searching and Sorting Example
+
+Here is an example showing the use of @code{qsort} and @code{bsearch}
+with an array of structures.  The objects in the array are sorted
+by comparing their @code{name} fields with the @code{strcmp} function.
+Then, we can look up individual objects based on their names.
+
+@comment This example is dedicated to the memory of Jim Henson.  RIP.
+@smallexample
+@include search.c.texi
+@end smallexample
+
+@cindex Kermit the frog
+The output from this program looks like:
+
+@smallexample
+Kermit, the frog
+Piggy, the pig
+Gonzo, the whatever
+Fozzie, the bear
+Sam, the eagle
+Robin, the frog
+Animal, the animal
+Camilla, the chicken
+Sweetums, the monster
+Dr. Strangepork, the pig
+Link Hogthrob, the pig
+Zoot, the human
+Dr. Bunsen Honeydew, the human
+Beaker, the human
+Swedish Chef, the human
+
+Animal, the animal
+Beaker, the human
+Camilla, the chicken
+Dr. Bunsen Honeydew, the human
+Dr. Strangepork, the pig
+Fozzie, the bear
+Gonzo, the whatever
+Kermit, the frog
+Link Hogthrob, the pig
+Piggy, the pig
+Robin, the frog
+Sam, the eagle
+Swedish Chef, the human
+Sweetums, the monster
+Zoot, the human
+
+Kermit, the frog
+Gonzo, the whatever
+Couldn't find Janice.
+@end smallexample
+
+
+@node Hash Search Function
+@section The @code{hsearch} function.
+
+The functions mentioned so far in this chapter are for searching in a sorted
+or unsorted array.  There are other methods to organize information
+which later should be searched.  The costs of insert, delete and search
+differ.  One possible implementation is using hashing tables.
+The following functions are declared in the header file @file{search.h}.
+
+@comment search.h
+@comment SVID
+@deftypefun int hcreate (size_t @var{nel})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c hcreate @mtasurace:hsearch @ascuheap @acucorrupt @acsmem
+@c  hcreate_r dup @mtsrace:htab @ascuheap @acucorrupt @acsmem
+The @code{hcreate} function creates a hashing table which can contain at
+least @var{nel} elements.  There is no possibility to grow this table so
+it is necessary to choose the value for @var{nel} wisely.  The method
+used to implement this function might make it necessary to make the
+number of elements in the hashing table larger than the expected maximal
+number of elements.  Hashing tables usually work inefficiently if they are
+filled 80% or more.  The constant access time guaranteed by hashing can
+only be achieved if few collisions exist.  See Knuth's ``The Art of
+Computer Programming, Part 3: Searching and Sorting'' for more
+information.
+
+The weakest aspect of this function is that there can be at most one
+hashing table used through the whole program.  The table is allocated
+in local memory out of control of the programmer.  As an extension @theglibc{}
+provides an additional set of functions with a reentrant
+interface which provide a similar interface but which allow to keep
+arbitrarily many hashing tables.
+
+It is possible to use more than one hashing table in the program run if
+the former table is first destroyed by a call to @code{hdestroy}.
+
+The function returns a non-zero value if successful.  If it return zero
+something went wrong.  This could either mean there is already a hashing
+table in use or the program runs out of memory.
+@end deftypefun
+
+@comment search.h
+@comment SVID
+@deftypefun void hdestroy (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c hdestroy @mtasurace:hsearch @ascuheap @acucorrupt @acsmem
+@c  hdestroy_r dup @mtsrace:htab @ascuheap @acucorrupt @acsmem
+The @code{hdestroy} function can be used to free all the resources
+allocated in a previous call of @code{hcreate}.  After a call to this
+function it is again possible to call @code{hcreate} and allocate a new
+table with possibly different size.
+
+It is important to remember that the elements contained in the hashing
+table at the time @code{hdestroy} is called are @emph{not} freed by this
+function.  It is the responsibility of the program code to free those
+strings (if necessary at all).  Freeing all the element memory is not
+possible without extra, separately kept information since there is no
+function to iterate through all available elements in the hashing table.
+If it is really necessary to free a table and all elements the
+programmer has to keep a list of all table elements and before calling
+@code{hdestroy} s/he has to free all element's data using this list.
+This is a very unpleasant mechanism and it also shows that this kind of
+hashing tables is mainly meant for tables which are created once and
+used until the end of the program run.
+@end deftypefun
+
+Entries of the hashing table and keys for the search are defined using
+this type:
+
+@deftp {Data type} {struct ENTRY}
+Both elements of this structure are pointers to zero-terminated strings.
+This is a limiting restriction of the functionality of the
+@code{hsearch} functions.  They can only be used for data sets which use
+the NUL character always and solely to terminate the records.  It is not
+possible to handle general binary data.
+
+@table @code
+@item char *key
+Pointer to a zero-terminated string of characters describing the key for
+the search or the element in the hashing table.
+@item char *data
+Pointer to a zero-terminated string of characters describing the data.
+If the functions will be called only for searching an existing entry
+this element might stay undefined since it is not used.
+@end table
+@end deftp
+
+@comment search.h
+@comment SVID
+@deftypefun {ENTRY *} hsearch (ENTRY @var{item}, ACTION @var{action})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hsearch}}@asunsafe{}@acunsafe{@acucorrupt{/action==ENTER}}}
+@c hsearch @mtasurace:hsearch @acucorrupt/action==ENTER
+@c  hsearch_r dup @mtsrace:htab @acucorrupt/action==ENTER
+To search in a hashing table created using @code{hcreate} the
+@code{hsearch} function must be used.  This function can perform simple
+search for an element (if @var{action} has the @code{FIND}) or it can
+alternatively insert the key element into the hashing table.  Entries
+are never replaced.
+
+The key is denoted by a pointer to an object of type @code{ENTRY}.  For
+locating the corresponding position in the hashing table only the
+@code{key} element of the structure is used.
+
+If an entry with matching key is found the @var{action} parameter is
+irrelevant.  The found entry is returned.  If no matching entry is found
+and the @var{action} parameter has the value @code{FIND} the function
+returns a @code{NULL} pointer.  If no entry is found and the
+@var{action} parameter has the value @code{ENTER} a new entry is added
+to the hashing table which is initialized with the parameter @var{item}.
+A pointer to the newly added entry is returned.
+@end deftypefun
+
+As mentioned before the hashing table used by the functions described so
+far is global and there can be at any time at most one hashing table in
+the program.  A solution is to use the following functions which are a
+GNU extension.  All have in common that they operate on a hashing table
+which is described by the content of an object of the type @code{struct
+hsearch_data}.  This type should be treated as opaque, none of its
+members should be changed directly.
+
+@comment search.h
+@comment GNU
+@deftypefun int hcreate_r (size_t @var{nel}, struct hsearch_data *@var{htab})
+@safety{@prelim{}@mtsafe{@mtsrace{:htab}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c Unlike the lsearch array, the htab is (at least in part) opaque, so
+@c let's make it absolutely clear that ensuring exclusive access is a
+@c caller responsibility.
+
+@c Cancellation is unlikely to leave the htab in a corrupt state: the
+@c last field to be initialized is the one that tells whether the entire
+@c data structure was initialized, and there's a function call (calloc)
+@c in between that will often ensure all other fields are written before
+@c the table.  However, should this call be inlined (say with LTO), this
+@c assumption may not hold.  The calloc call doesn't cross our library
+@c interface barrier, so let's consider this could happen and mark this
+@c with @acucorrupt.  It's no safety loss, since we already have
+@c @ascuheap anyway...
+
+@c hcreate_r @mtsrace:htab @ascuheap @acucorrupt @acsmem
+@c  isprime ok
+@c  calloc dup @ascuheap @acsmem
+The @code{hcreate_r} function initializes the object pointed to by
+@var{htab} to contain a hashing table with at least @var{nel} elements.
+So this function is equivalent to the @code{hcreate} function except
+that the initialized data structure is controlled by the user.
+
+This allows having more than one hashing table at one time.  The memory
+necessary for the @code{struct hsearch_data} object can be allocated
+dynamically.  It must be initialized with zero before calling this
+function.
+
+The return value is non-zero if the operation was successful.  If the
+return value is zero, something went wrong, which probably means the
+programs ran out of memory.
+@end deftypefun
+
+@comment search.h
+@comment GNU
+@deftypefun void hdestroy_r (struct hsearch_data *@var{htab})
+@safety{@prelim{}@mtsafe{@mtsrace{:htab}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c The table is released while the table pointer still points to it.
+@c Async cancellation is thus unsafe, but it already was because we call
+@c free().  Using the table in a handler while it's being released would
+@c also be dangerous, but calling free() already makes it unsafe, and
+@c the requirement on the caller to ensure exclusive access already
+@c guarantees this doesn't happen, so we don't get @asucorrupt.
+
+@c hdestroy_r @mtsrace:htab @ascuheap @acucorrupt @acsmem
+@c  free dup @ascuheap @acsmem
+The @code{hdestroy_r} function frees all resources allocated by the
+@code{hcreate_r} function for this very same object @var{htab}.  As for
+@code{hdestroy} it is the programs responsibility to free the strings
+for the elements of the table.
+@end deftypefun
+
+@comment search.h
+@comment GNU
+@deftypefun int hsearch_r (ENTRY @var{item}, ACTION @var{action}, ENTRY **@var{retval}, struct hsearch_data *@var{htab})
+@safety{@prelim{}@mtsafe{@mtsrace{:htab}}@assafe{}@acunsafe{@acucorrupt{/action==ENTER}}}
+@c Callers have to ensure mutual exclusion; insertion, if cancelled,
+@c leaves the table in a corrupt state.
+
+@c hsearch_r @mtsrace:htab @acucorrupt/action==ENTER
+@c  strlen dup ok
+@c  strcmp dup ok
+The @code{hsearch_r} function is equivalent to @code{hsearch}.  The
+meaning of the first two arguments is identical.  But instead of
+operating on a single global hashing table the function works on the
+table described by the object pointed to by @var{htab} (which is
+initialized by a call to @code{hcreate_r}).
+
+Another difference to @code{hcreate} is that the pointer to the found
+entry in the table is not the return value of the functions.  It is
+returned by storing it in a pointer variables pointed to by the
+@var{retval} parameter.  The return value of the function is an integer
+value indicating success if it is non-zero and failure if it is zero.
+In the latter case the global variable @var{errno} signals the reason for
+the failure.
+
+@table @code
+@item ENOMEM
+The table is filled and @code{hsearch_r} was called with a so far
+unknown key and @var{action} set to @code{ENTER}.
+@item ESRCH
+The @var{action} parameter is @code{FIND} and no corresponding element
+is found in the table.
+@end table
+@end deftypefun
+
+
+@node Tree Search Function
+@section The @code{tsearch} function.
+
+Another common form to organize data for efficient search is to use
+trees.  The @code{tsearch} function family provides a nice interface to
+functions to organize possibly large amounts of data by providing a mean
+access time proportional to the logarithm of the number of elements.
+@Theglibc{} implementation even guarantees that this bound is
+never exceeded even for input data which cause problems for simple
+binary tree implementations.
+
+The functions described in the chapter are all described in the @w{System
+V} and X/Open specifications and are therefore quite portable.
+
+In contrast to the @code{hsearch} functions the @code{tsearch} functions
+can be used with arbitrary data and not only zero-terminated strings.
+
+The @code{tsearch} functions have the advantage that no function to
+initialize data structures is necessary.  A simple pointer of type
+@code{void *} initialized to @code{NULL} is a valid tree and can be
+extended or searched.  The prototypes for these functions can be found
+in the header file @file{search.h}.
+
+@comment search.h
+@comment SVID
+@deftypefun {void *} tsearch (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar})
+@safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c The tree is not modified in a thread-safe manner, and rotations may
+@c leave the tree in an inconsistent state that could be observed in an
+@c asynchronous signal handler (except for the caller-synchronization
+@c requirement) or after asynchronous cancellation of the thread
+@c performing the rotation or the insertion.
+The @code{tsearch} function searches in the tree pointed to by
+@code{*@var{rootp}} for an element matching @var{key}.  The function
+pointed to by @var{compar} is used to determine whether two elements
+match.  @xref{Comparison Functions}, for a specification of the functions
+which can be used for the @var{compar} parameter.
+
+If the tree does not contain a matching entry the @var{key} value will
+be added to the tree.  @code{tsearch} does not make a copy of the object
+pointed to by @var{key} (how could it since the size is unknown).
+Instead it adds a reference to this object which means the object must
+be available as long as the tree data structure is used.
+
+The tree is represented by a pointer to a pointer since it is sometimes
+necessary to change the root node of the tree.  So it must not be
+assumed that the variable pointed to by @var{rootp} has the same value
+after the call.  This also shows that it is not safe to call the
+@code{tsearch} function more than once at the same time using the same
+tree.  It is no problem to run it more than once at a time on different
+trees.
+
+The return value is a pointer to the matching element in the tree.  If a
+new element was created the pointer points to the new data (which is in
+fact @var{key}).  If an entry had to be created and the program ran out
+of space @code{NULL} is returned.
+@end deftypefun
+
+@comment search.h
+@comment SVID
+@deftypefun {void *} tfind (const void *@var{key}, void *const *@var{rootp}, comparison_fn_t @var{compar})
+@safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@assafe{}@acsafe{}}
+The @code{tfind} function is similar to the @code{tsearch} function.  It
+locates an element matching the one pointed to by @var{key} and returns
+a pointer to this element.  But if no matching element is available no
+new element is entered (note that the @var{rootp} parameter points to a
+constant pointer).  Instead the function returns @code{NULL}.
+@end deftypefun
+
+Another advantage of the @code{tsearch} function in contrast to the
+@code{hsearch} functions is that there is an easy way to remove
+elements.
+
+@comment search.h
+@comment SVID
+@deftypefun {void *} tdelete (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar})
+@safety{@prelim{}@mtsafe{@mtsrace{:rootp}}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+To remove a specific element matching @var{key} from the tree
+@code{tdelete} can be used.  It locates the matching element using the
+same method as @code{tfind}.  The corresponding element is then removed
+and a pointer to the parent of the deleted node is returned by the
+function.  If there is no matching entry in the tree nothing can be
+deleted and the function returns @code{NULL}.  If the root of the tree
+is deleted @code{tdelete} returns some unspecified value not equal to
+@code{NULL}.
+@end deftypefun
+
+@comment search.h
+@comment GNU
+@deftypefun void tdestroy (void *@var{vroot}, __free_fn_t @var{freefct})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+If the complete search tree has to be removed one can use
+@code{tdestroy}.  It frees all resources allocated by the @code{tsearch}
+function to generate the tree pointed to by @var{vroot}.
+
+For the data in each tree node the function @var{freefct} is called.
+The pointer to the data is passed as the argument to the function.  If
+no such work is necessary @var{freefct} must point to a function doing
+nothing.  It is called in any case.
+
+This function is a GNU extension and not covered by the @w{System V} or
+X/Open specifications.
+@end deftypefun
+
+In addition to the function to create and destroy the tree data
+structure, there is another function which allows you to apply a
+function to all elements of the tree.  The function must have this type:
+
+@smallexample
+void __action_fn_t (const void *nodep, VISIT value, int level);
+@end smallexample
+
+The @var{nodep} is the data value of the current node (once given as the
+@var{key} argument to @code{tsearch}).  @var{level} is a numeric value
+which corresponds to the depth of the current node in the tree.  The
+root node has the depth @math{0} and its children have a depth of
+@math{1} and so on.  The @code{VISIT} type is an enumeration type.
+
+@deftp {Data Type} VISIT
+The @code{VISIT} value indicates the status of the current node in the
+tree and how the function is called.  The status of a node is either
+`leaf' or `internal node'.  For each leaf node the function is called
+exactly once, for each internal node it is called three times: before
+the first child is processed, after the first child is processed and
+after both children are processed.  This makes it possible to handle all
+three methods of tree traversal (or even a combination of them).
+
+@table @code
+@item preorder
+The current node is an internal node and the function is called before
+the first child was processed.
+@item postorder
+The current node is an internal node and the function is called after
+the first child was processed.
+@item endorder
+The current node is an internal node and the function is called after
+the second child was processed.
+@item leaf
+The current node is a leaf.
+@end table
+@end deftp
+
+@comment search.h
+@comment SVID
+@deftypefun void twalk (const void *@var{root}, __action_fn_t @var{action})
+@safety{@prelim{}@mtsafe{@mtsrace{:root}}@assafe{}@acsafe{}}
+For each node in the tree with a node pointed to by @var{root}, the
+@code{twalk} function calls the function provided by the parameter
+@var{action}.  For leaf nodes the function is called exactly once with
+@var{value} set to @code{leaf}.  For internal nodes the function is
+called three times, setting the @var{value} parameter or @var{action} to
+the appropriate value.  The @var{level} argument for the @var{action}
+function is computed while descending the tree with increasing the value
+by one for the descend to a child, starting with the value @math{0} for
+the root node.
+
+Since the functions used for the @var{action} parameter to @code{twalk}
+must not modify the tree data, it is safe to run @code{twalk} in more
+than one thread at the same time, working on the same tree.  It is also
+safe to call @code{tfind} in parallel.  Functions which modify the tree
+must not be used, otherwise the behavior is undefined.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/setjmp.texi b/ap/libc/glibc/glibc-2.23/manual/setjmp.texi
new file mode 100644
index 0000000..ec79c26
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/setjmp.texi
@@ -0,0 +1,496 @@
+@node Non-Local Exits, Signal Handling, Resource Usage And Limitation, Top
+@c %MENU% Jumping out of nested function calls
+@chapter Non-Local Exits
+@cindex non-local exits
+@cindex long jumps
+
+Sometimes when your program detects an unusual situation inside a deeply
+nested set of function calls, you would like to be able to immediately
+return to an outer level of control.  This section describes how you can
+do such @dfn{non-local exits} using the @code{setjmp} and @code{longjmp}
+functions.
+
+@menu
+* Intro: Non-Local Intro.        When and how to use these facilities.
+* Details: Non-Local Details.    Functions for non-local exits.
+* Non-Local Exits and Signals::  Portability issues.
+* System V contexts::            Complete context control a la System V.
+@end menu
+
+@node Non-Local Intro, Non-Local Details,  , Non-Local Exits
+@section Introduction to Non-Local Exits
+
+As an example of a situation where a non-local exit can be useful,
+suppose you have an interactive program that has a ``main loop'' that
+prompts for and executes commands.  Suppose the ``read'' command reads
+input from a file, doing some lexical analysis and parsing of the input
+while processing it.  If a low-level input error is detected, it would
+be useful to be able to return immediately to the ``main loop'' instead
+of having to make each of the lexical analysis, parsing, and processing
+phases all have to explicitly deal with error situations initially
+detected by nested calls.
+
+(On the other hand, if each of these phases has to do a substantial
+amount of cleanup when it exits---such as closing files, deallocating
+buffers or other data structures, and the like---then it can be more
+appropriate to do a normal return and have each phase do its own
+cleanup, because a non-local exit would bypass the intervening phases and
+their associated cleanup code entirely.  Alternatively, you could use a
+non-local exit but do the cleanup explicitly either before or after
+returning to the ``main loop''.)
+
+In some ways, a non-local exit is similar to using the @samp{return}
+statement to return from a function.  But while @samp{return} abandons
+only a single function call, transferring control back to the point at
+which it was called, a non-local exit can potentially abandon many
+levels of nested function calls.
+
+You identify return points for non-local exits by calling the function
+@code{setjmp}.  This function saves information about the execution
+environment in which the call to @code{setjmp} appears in an object of
+type @code{jmp_buf}.  Execution of the program continues normally after
+the call to @code{setjmp}, but if an exit is later made to this return
+point by calling @code{longjmp} with the corresponding @w{@code{jmp_buf}}
+object, control is transferred back to the point where @code{setjmp} was
+called.  The return value from @code{setjmp} is used to distinguish
+between an ordinary return and a return made by a call to
+@code{longjmp}, so calls to @code{setjmp} usually appear in an @samp{if}
+statement.
+
+Here is how the example program described above might be set up:
+
+@smallexample
+@include setjmp.c.texi
+@end smallexample
+
+The function @code{abort_to_main_loop} causes an immediate transfer of
+control back to the main loop of the program, no matter where it is
+called from.
+
+The flow of control inside the @code{main} function may appear a little
+mysterious at first, but it is actually a common idiom with
+@code{setjmp}.  A normal call to @code{setjmp} returns zero, so the
+``else'' clause of the conditional is executed.  If
+@code{abort_to_main_loop} is called somewhere within the execution of
+@code{do_command}, then it actually appears as if the @emph{same} call
+to @code{setjmp} in @code{main} were returning a second time with a value
+of @code{-1}.
+
+@need 250
+So, the general pattern for using @code{setjmp} looks something like:
+
+@smallexample
+if (setjmp (@var{buffer}))
+  /* @r{Code to clean up after premature return.} */
+  @dots{}
+else
+  /* @r{Code to be executed normally after setting up the return point.} */
+  @dots{}
+@end smallexample
+
+@node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits
+@section Details of Non-Local Exits
+
+Here are the details on the functions and data structures used for
+performing non-local exits.  These facilities are declared in
+@file{setjmp.h}.
+@pindex setjmp.h
+
+@comment setjmp.h
+@comment ISO
+@deftp {Data Type} jmp_buf
+Objects of type @code{jmp_buf} hold the state information to
+be restored by a non-local exit.  The contents of a @code{jmp_buf}
+identify a specific place to return to.
+@end deftp
+
+@comment setjmp.h
+@comment ISO
+@deftypefn Macro int setjmp (jmp_buf @var{state})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c _setjmp ok
+@c  __sigsetjmp(!savemask) ok
+@c   __sigjmp_save(!savemask) ok, does not call sigprocmask
+When called normally, @code{setjmp} stores information about the
+execution state of the program in @var{state} and returns zero.  If
+@code{longjmp} is later used to perform a non-local exit to this
+@var{state}, @code{setjmp} returns a nonzero value.
+@end deftypefn
+
+@comment setjmp.h
+@comment ISO
+@deftypefun void longjmp (jmp_buf @var{state}, int @var{value})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}}
+@c __libc_siglongjmp @ascuplugin @asucorrupt @asulock/hurd @acucorrupt @aculock/hurd
+@c  _longjmp_unwind @ascuplugin @asucorrupt @acucorrupt
+@c   __pthread_cleanup_upto @ascuplugin @asucorrupt @acucorrupt
+@c     plugins may be unsafe themselves, but even if they weren't, this
+@c     function isn't robust WRT async signals and cancellation:
+@c     cleanups aren't taken off the stack right away, only after all
+@c     cleanups have been run.  This means that async-cancelling
+@c     longjmp, or interrupting longjmp with an async signal handler
+@c     that calls longjmp may run the same cleanups multiple times.
+@c    _JMPBUF_UNWINDS_ADJ ok
+@c    *cleanup_buf->__routine @ascuplugin
+@c  sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd
+@c  __longjmp ok
+This function restores current execution to the state saved in
+@var{state}, and continues execution from the call to @code{setjmp} that
+established that return point.  Returning from @code{setjmp} by means of
+@code{longjmp} returns the @var{value} argument that was passed to
+@code{longjmp}, rather than @code{0}.  (But if @var{value} is given as
+@code{0}, @code{setjmp} returns @code{1}).@refill
+@end deftypefun
+
+There are a lot of obscure but important restrictions on the use of
+@code{setjmp} and @code{longjmp}.  Most of these restrictions are
+present because non-local exits require a fair amount of magic on the
+part of the C compiler and can interact with other parts of the language
+in strange ways.
+
+The @code{setjmp} function is actually a macro without an actual
+function definition, so you shouldn't try to @samp{#undef} it or take
+its address.  In addition, calls to @code{setjmp} are safe in only the
+following contexts:
+
+@itemize @bullet
+@item
+As the test expression of a selection or iteration
+statement (such as @samp{if}, @samp{switch}, or @samp{while}).
+
+@item
+As one operand of an equality or comparison operator that appears as the
+test expression of a selection or iteration statement.  The other
+operand must be an integer constant expression.
+
+@item
+As the operand of a unary @samp{!} operator, that appears as the
+test expression of a selection or iteration statement.
+
+@item
+By itself as an expression statement.
+@end itemize
+
+Return points are valid only during the dynamic extent of the function
+that called @code{setjmp} to establish them.  If you @code{longjmp} to
+a return point that was established in a function that has already
+returned, unpredictable and disastrous things are likely to happen.
+
+You should use a nonzero @var{value} argument to @code{longjmp}.  While
+@code{longjmp} refuses to pass back a zero argument as the return value
+from @code{setjmp}, this is intended as a safety net against accidental
+misuse and is not really good programming style.
+
+When you perform a non-local exit, accessible objects generally retain
+whatever values they had at the time @code{longjmp} was called.  The
+exception is that the values of automatic variables local to the
+function containing the @code{setjmp} call that have been changed since
+the call to @code{setjmp} are indeterminate, unless you have declared
+them @code{volatile}.
+
+@node Non-Local Exits and Signals, System V contexts, Non-Local Details, Non-Local Exits
+@section Non-Local Exits and Signals
+
+In BSD Unix systems, @code{setjmp} and @code{longjmp} also save and
+restore the set of blocked signals; see @ref{Blocking Signals}.  However,
+the POSIX.1 standard requires @code{setjmp} and @code{longjmp} not to
+change the set of blocked signals, and provides an additional pair of
+functions (@code{sigsetjmp} and @code{siglongjmp}) to get the BSD
+behavior.
+
+The behavior of @code{setjmp} and @code{longjmp} in @theglibc{} is
+controlled by feature test macros; see @ref{Feature Test Macros}.  The
+default in @theglibc{} is the POSIX.1 behavior rather than the BSD
+behavior.
+
+The facilities in this section are declared in the header file
+@file{setjmp.h}.
+@pindex setjmp.h
+
+@comment setjmp.h
+@comment POSIX.1
+@deftp {Data Type} sigjmp_buf
+This is similar to @code{jmp_buf}, except that it can also store state
+information about the set of blocked signals.
+@end deftp
+
+@comment setjmp.h
+@comment POSIX.1
+@deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c sigsetjmp @asulock/hurd @aculock/hurd
+@c  __sigsetjmp(savemask) @asulock/hurd @aculock/hurd
+@c   __sigjmp_save(savemask) @asulock/hurd @aculock/hurd
+@c    sigprocmask(SIG_BLOCK probe) dup @asulock/hurd @aculock/hurd
+This is similar to @code{setjmp}.  If @var{savesigs} is nonzero, the set
+of blocked signals is saved in @var{state} and will be restored if a
+@code{siglongjmp} is later performed with this @var{state}.
+@end deftypefun
+
+@comment setjmp.h
+@comment POSIX.1
+@deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuplugin{} @asucorrupt{} @asulock{/hurd}}@acunsafe{@acucorrupt{} @aculock{/hurd}}}
+@c Alias to longjmp.
+This is similar to @code{longjmp} except for the type of its @var{state}
+argument.  If the @code{sigsetjmp} call that set this @var{state} used a
+nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of
+blocked signals.
+@end deftypefun
+
+@node System V contexts,, Non-Local Exits and Signals, Non-Local Exits
+@section Complete Context Control
+
+The Unix standard provides one more set of functions to control the
+execution path and these functions are more powerful than those
+discussed in this chapter so far.  These function were part of the
+original @w{System V} API and by this route were added to the Unix
+API.  Beside on branded Unix implementations these interfaces are not
+widely available.  Not all platforms and/or architectures @theglibc{}
+is available on provide this interface.  Use @file{configure} to
+detect the availability.
+
+Similar to the @code{jmp_buf} and @code{sigjmp_buf} types used for the
+variables to contain the state of the @code{longjmp} functions the
+interfaces of interest here have an appropriate type as well.  Objects
+of this type are normally much larger since more information is
+contained.  The type is also used in a few more places as we will see.
+The types and functions described in this section are all defined and
+declared respectively in the @file{ucontext.h} header file.
+
+@comment ucontext.h
+@comment SVID
+@deftp {Data Type} ucontext_t
+
+The @code{ucontext_t} type is defined as a structure with at least the
+following elements:
+
+@table @code
+@item ucontext_t *uc_link
+This is a pointer to the next context structure which is used if the
+context described in the current structure returns.
+
+@item sigset_t uc_sigmask
+Set of signals which are blocked when this context is used.
+
+@item stack_t uc_stack
+Stack used for this context.  The value need not be (and normally is
+not) the stack pointer.  @xref{Signal Stack}.
+
+@item mcontext_t uc_mcontext
+This element contains the actual state of the process.  The
+@code{mcontext_t} type is also defined in this header but the definition
+should be treated as opaque.  Any use of knowledge of the type makes
+applications less portable.
+
+@end table
+@end deftp
+
+Objects of this type have to be created by the user.  The initialization
+and modification happens through one of the following functions:
+
+@comment ucontext.h
+@comment SVID
+@deftypefun int getcontext (ucontext_t *@var{ucp})
+@safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}}
+@c Linux-only implementations in assembly, including sigprocmask
+@c syscall.  A few cases call the sigprocmask function, but that's safe
+@c too.  The ppc case is implemented in terms of a swapcontext syscall.
+The @code{getcontext} function initializes the variable pointed to by
+@var{ucp} with the context of the calling thread.  The context contains
+the content of the registers, the signal mask, and the current stack.
+Executing the contents would start at the point where the
+@code{getcontext} call just returned.
+
+The function returns @code{0} if successful.  Otherwise it returns
+@code{-1} and sets @var{errno} accordingly.
+@end deftypefun
+
+The @code{getcontext} function is similar to @code{setjmp} but it does
+not provide an indication of whether @code{getcontext} is returning for
+the first time or whether an initialized context has just been restored.
+If this is necessary the user has to determine this herself.  This must
+be done carefully since the context contains registers which might contain
+register variables.  This is a good situation to define variables with
+@code{volatile}.
+
+Once the context variable is initialized it can be used as is or it can
+be modified using the @code{makecontext} function.  The latter is normally
+done when implementing co-routines or similar constructs.
+
+@comment ucontext.h
+@comment SVID
+@deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@assafe{}@acsafe{}}
+@c Linux-only implementations mostly in assembly, nothing unsafe.
+
+The @var{ucp} parameter passed to @code{makecontext} shall be
+initialized by a call to @code{getcontext}.  The context will be
+modified in a way such that if the context is resumed it will start by
+calling the function @code{func} which gets @var{argc} integer arguments
+passed.  The integer arguments which are to be passed should follow the
+@var{argc} parameter in the call to @code{makecontext}.
+
+Before the call to this function the @code{uc_stack} and @code{uc_link}
+element of the @var{ucp} structure should be initialized.  The
+@code{uc_stack} element describes the stack which is used for this
+context.  No two contexts which are used at the same time should use the
+same memory region for a stack.
+
+The @code{uc_link} element of the object pointed to by @var{ucp} should
+be a pointer to the context to be executed when the function @var{func}
+returns or it should be a null pointer.  See @code{setcontext} for more
+information about the exact use.
+@end deftypefun
+
+While allocating the memory for the stack one has to be careful.  Most
+modern processors keep track of whether a certain memory region is
+allowed to contain code which is executed or not.  Data segments and
+heap memory are normally not tagged to allow this.  The result is that
+programs would fail.  Examples for such code include the calling
+sequences the GNU C compiler generates for calls to nested functions.
+Safe ways to allocate stacks correctly include using memory on the
+original threads stack or explicitly allocate memory tagged for
+execution using (@pxref{Memory-mapped I/O}).
+
+@strong{Compatibility note}: The current Unix standard is very imprecise
+about the way the stack is allocated.  All implementations seem to agree
+that the @code{uc_stack} element must be used but the values stored in
+the elements of the @code{stack_t} value are unclear.  @Theglibc{}
+and most other Unix implementations require the @code{ss_sp} value of
+the @code{uc_stack} element to point to the base of the memory region
+allocated for the stack and the size of the memory region is stored in
+@code{ss_size}.  There are implements out there which require
+@code{ss_sp} to be set to the value the stack pointer will have (which
+can, depending on the direction the stack grows, be different).  This
+difference makes the @code{makecontext} function hard to use and it
+requires detection of the platform at compile time.
+
+@comment ucontext.h
+@comment SVID
+@deftypefun int setcontext (const ucontext_t *@var{ucp})
+@safety{@prelim{}@mtsafe{@mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c Linux-only implementations mostly in assembly.  Some ports use
+@c sigreturn or swapcontext syscalls; others restore the signal mask
+@c first and then proceed restore other registers in userland, which
+@c leaves a window for cancellation or async signals with misaligned or
+@c otherwise corrupt stack.  ??? Switching to a different stack, or even
+@c to an earlier state on the same stack, may conflict with pthread
+@c cleanups.  This is not quite MT-Unsafe, it's a different kind of
+@c safety issue.
+
+The @code{setcontext} function restores the context described by
+@var{ucp}.  The context is not modified and can be reused as often as
+wanted.
+
+If the context was created by @code{getcontext} execution resumes with
+the registers filled with the same values and the same stack as if the
+@code{getcontext} call just returned.
+
+If the context was modified with a call to @code{makecontext} execution
+continues with the function passed to @code{makecontext} which gets the
+specified parameters passed.  If this function returns execution is
+resumed in the context which was referenced by the @code{uc_link}
+element of the context structure passed to @code{makecontext} at the
+time of the call.  If @code{uc_link} was a null pointer the application
+terminates normally with an exit status value of @code{EXIT_SUCCESS}
+(@pxref{Program Termination}).
+
+If the context was created by a call to a signal handler or from any
+other source then the behaviour of @code{setcontext} is unspecified.
+
+Since the context contains information about the stack no two threads
+should use the same context at the same time.  The result in most cases
+would be disastrous.
+
+The @code{setcontext} function does not return unless an error occurred
+in which case it returns @code{-1}.
+@end deftypefun
+
+The @code{setcontext} function simply replaces the current context with
+the one described by the @var{ucp} parameter.  This is often useful but
+there are situations where the current context has to be preserved.
+
+@comment ucontext.h
+@comment SVID
+@deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp})
+@safety{@prelim{}@mtsafe{@mtsrace{:oucp} @mtsrace{:ucp}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c Linux-only implementations mostly in assembly.  Some ports call or
+@c inline getcontext and/or setcontext, adjusting the saved context in
+@c between, so we inherit the potential issues of both.
+
+The @code{swapcontext} function is similar to @code{setcontext} but
+instead of just replacing the current context the latter is first saved
+in the object pointed to by @var{oucp} as if this was a call to
+@code{getcontext}.  The saved context would resume after the call to
+@code{swapcontext}.
+
+Once the current context is saved the context described in @var{ucp} is
+installed and execution continues as described in this context.
+
+If @code{swapcontext} succeeds the function does not return unless the
+context @var{oucp} is used without prior modification by
+@code{makecontext}.  The return value in this case is @code{0}.  If the
+function fails it returns @code{-1} and sets @var{errno} accordingly.
+@end deftypefun
+
+@heading Example for SVID Context Handling
+
+The easiest way to use the context handling functions is as a
+replacement for @code{setjmp} and @code{longjmp}.  The context contains
+on most platforms more information which may lead to fewer surprises
+but this also means using these functions is more expensive (besides
+being less portable).
+
+@smallexample
+int
+random_search (int n, int (*fp) (int, ucontext_t *))
+@{
+  volatile int cnt = 0;
+  ucontext_t uc;
+
+  /* @r{Safe current context.}  */
+  if (getcontext (&uc) < 0)
+    return -1;
+
+  /* @r{If we have not tried @var{n} times try again.}  */
+  if (cnt++ < n)
+    /* @r{Call the function with a new random number}
+       @r{and the context}.  */
+    if (fp (rand (), &uc) != 0)
+      /* @r{We found what we were looking for.}  */
+      return 1;
+
+  /* @r{Not found.}  */
+  return 0;
+@}
+@end smallexample
+
+Using contexts in such a way enables emulating exception handling.  The
+search functions passed in the @var{fp} parameter could be very large,
+nested, and complex which would make it complicated (or at least would
+require a lot of code) to leave the function with an error value which
+has to be passed down to the caller.  By using the context it is
+possible to leave the search function in one step and allow restarting
+the search which also has the nice side effect that it can be
+significantly faster.
+
+Something which is harder to implement with @code{setjmp} and
+@code{longjmp} is to switch temporarily to a different execution path
+and then resume where execution was stopped.
+
+@smallexample
+@include swapcontext.c.texi
+@end smallexample
+
+This an example how the context functions can be used to implement
+co-routines or cooperative multi-threading.  All that has to be done is
+to call every once in a while @code{swapcontext} to continue running a
+different context.  It is not recommended to do the context switching from
+the signal handler directly since leaving the signal handler via
+@code{setcontext} if the signal was delivered during code that was not
+asynchronous signal safe could lead to problems. Setting a variable in
+the signal handler and checking it in the body of the functions which
+are executed is a safer approach.  Since @code{swapcontext} is saving the
+current context it is possible to have multiple different scheduling points
+in the code.  Execution will always resume where it was left.
diff --git a/ap/libc/glibc/glibc-2.23/manual/signal.texi b/ap/libc/glibc/glibc-2.23/manual/signal.texi
new file mode 100644
index 0000000..77f3d7c
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/signal.texi
@@ -0,0 +1,3396 @@
+@node Signal Handling, Program Basics, Non-Local Exits, Top
+@c %MENU% How to send, block, and handle signals
+@chapter Signal Handling
+
+@cindex signal
+A @dfn{signal} is a software interrupt delivered to a process.  The
+operating system uses signals to report exceptional situations to an
+executing program.  Some signals report errors such as references to
+invalid memory addresses; others report asynchronous events, such as
+disconnection of a phone line.
+
+@Theglibc{} defines a variety of signal types, each for a
+particular kind of event.  Some kinds of events make it inadvisable or
+impossible for the program to proceed as usual, and the corresponding
+signals normally abort the program.  Other kinds of signals that report
+harmless events are ignored by default.
+
+If you anticipate an event that causes signals, you can define a handler
+function and tell the operating system to run it when that particular
+type of signal arrives.
+
+Finally, one process can send a signal to another process; this allows a
+parent process to abort a child, or two related processes to communicate
+and synchronize.
+
+@menu
+* Concepts of Signals::         Introduction to the signal facilities.
+* Standard Signals::            Particular kinds of signals with
+                                 standard names and meanings.
+* Signal Actions::              Specifying what happens when a
+                                 particular signal is delivered.
+* Defining Handlers::           How to write a signal handler function.
+* Interrupted Primitives::	Signal handlers affect use of @code{open},
+				 @code{read}, @code{write} and other functions.
+* Generating Signals::          How to send a signal to a process.
+* Blocking Signals::            Making the system hold signals temporarily.
+* Waiting for a Signal::        Suspending your program until a signal
+                                 arrives.
+* Signal Stack::                Using a Separate Signal Stack.
+* BSD Signal Handling::         Additional functions for backward
+			         compatibility with BSD.
+@end menu
+
+@node Concepts of Signals
+@section Basic Concepts of Signals
+
+This section explains basic concepts of how signals are generated, what
+happens after a signal is delivered, and how programs can handle
+signals.
+
+@menu
+* 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.
+@end menu
+
+@node Kinds of Signals
+@subsection Some Kinds of Signals
+
+A signal reports the occurrence of an exceptional event.  These are some
+of the events that can cause (or @dfn{generate}, or @dfn{raise}) a
+signal:
+
+@itemize @bullet
+@item
+A program error such as dividing by zero or issuing an address outside
+the valid range.
+
+@item
+A user request to interrupt or terminate the program.  Most environments
+are set up to let a user suspend the program by typing @kbd{C-z}, or
+terminate it with @kbd{C-c}.  Whatever key sequence is used, the
+operating system sends the proper signal to interrupt the process.
+
+@item
+The termination of a child process.
+
+@item
+Expiration of a timer or alarm.
+
+@item
+A call to @code{kill} or @code{raise} by the same process.
+
+@item
+A call to @code{kill} from another process.  Signals are a limited but
+useful form of interprocess communication.
+
+@item
+An attempt to perform an I/O operation that cannot be done.  Examples
+are reading from a pipe that has no writer (@pxref{Pipes and FIFOs}),
+and reading or writing to a terminal in certain situations (@pxref{Job
+Control}).
+@end itemize
+
+Each of these kinds of events (excepting explicit calls to @code{kill}
+and @code{raise}) generates its own particular kind of signal.  The
+various kinds of signals are listed and described in detail in
+@ref{Standard Signals}.
+
+@node Signal Generation
+@subsection Concepts of Signal Generation
+@cindex generation of signals
+
+In general, the events that generate signals fall into three major
+categories: errors, external events, and explicit requests.
+
+An error means that a program has done something invalid and cannot
+continue execution.  But not all kinds of errors generate signals---in
+fact, most do not.  For example, opening a nonexistent file is an error,
+but it does not raise a signal; instead, @code{open} returns @code{-1}.
+In general, errors that are necessarily associated with certain library
+functions are reported by returning a value that indicates an error.
+The errors which raise signals are those which can happen anywhere in
+the program, not just in library calls.  These include division by zero
+and invalid memory addresses.
+
+An external event generally has to do with I/O or other processes.
+These include the arrival of input, the expiration of a timer, and the
+termination of a child process.
+
+An explicit request means the use of a library function such as
+@code{kill} whose purpose is specifically to generate a signal.
+
+Signals may be generated @dfn{synchronously} or @dfn{asynchronously}.  A
+synchronous signal pertains to a specific action in the program, and is
+delivered (unless blocked) during that action.  Most errors generate
+signals synchronously, and so do explicit requests by a process to
+generate a signal for that same process.  On some machines, certain
+kinds of hardware errors (usually floating-point exceptions) are not
+reported completely synchronously, but may arrive a few instructions
+later.
+
+Asynchronous signals are generated by events outside the control of the
+process that receives them.  These signals arrive at unpredictable times
+during execution.  External events generate signals asynchronously, and
+so do explicit requests that apply to some other process.
+
+A given type of signal is either typically synchronous or typically
+asynchronous.  For example, signals for errors are typically synchronous
+because errors generate signals synchronously.  But any type of signal
+can be generated synchronously or asynchronously with an explicit
+request.
+
+@node Delivery of Signal
+@subsection How Signals Are Delivered
+@cindex delivery of signals
+@cindex pending signals
+@cindex blocked signals
+
+When a signal is generated, it becomes @dfn{pending}.  Normally it
+remains pending for just a short period of time and then is
+@dfn{delivered} to the process that was signaled.  However, if that kind
+of signal is currently @dfn{blocked}, it may remain pending
+indefinitely---until signals of that kind are @dfn{unblocked}.  Once
+unblocked, it will be delivered immediately.  @xref{Blocking Signals}.
+
+@cindex specified action (for a signal)
+@cindex default action (for a signal)
+@cindex signal action
+@cindex catching signals
+When the signal is delivered, whether right away or after a long delay,
+the @dfn{specified action} for that signal is taken.  For certain
+signals, such as @code{SIGKILL} and @code{SIGSTOP}, the action is fixed,
+but for most signals, the program has a choice: ignore the signal,
+specify a @dfn{handler function}, or accept the @dfn{default action} for
+that kind of signal.  The program specifies its choice using functions
+such as @code{signal} or @code{sigaction} (@pxref{Signal Actions}).  We
+sometimes say that a handler @dfn{catches} the signal.  While the
+handler is running, that particular signal is normally blocked.
+
+If the specified action for a kind of signal is to ignore it, then any
+such signal which is generated is discarded immediately.  This happens
+even if the signal is also blocked at the time.  A signal discarded in
+this way will never be delivered, not even if the program subsequently
+specifies a different action for that kind of signal and then unblocks
+it.
+
+If a signal arrives which the program has neither handled nor ignored,
+its @dfn{default action} takes place.  Each kind of signal has its own
+default action, documented below (@pxref{Standard Signals}).  For most kinds
+of signals, the default action is to terminate the process.  For certain
+kinds of signals that represent ``harmless'' events, the default action
+is to do nothing.
+
+When a signal terminates a process, its parent process can determine the
+cause of termination by examining the termination status code reported
+by the @code{wait} or @code{waitpid} functions.  (This is discussed in
+more detail in @ref{Process Completion}.)  The information it can get
+includes the fact that termination was due to a signal and the kind of
+signal involved.  If a program you run from a shell is terminated by a
+signal, the shell typically prints some kind of error message.
+
+The signals that normally represent program errors have a special
+property: when one of these signals terminates the process, it also
+writes a @dfn{core dump file} which records the state of the process at
+the time of termination.  You can examine the core dump with a debugger
+to investigate what caused the error.
+
+If you raise a ``program error'' signal by explicit request, and this
+terminates the process, it makes a core dump file just as if the signal
+had been due directly to an error.
+
+@node Standard Signals
+@section Standard Signals
+@cindex signal names
+@cindex names of signals
+
+@pindex signal.h
+@cindex signal number
+This section lists the names for various standard kinds of signals and
+describes what kind of event they mean.  Each signal name is a macro
+which stands for a positive integer---the @dfn{signal number} for that
+kind of signal.  Your programs should never make assumptions about the
+numeric code for a particular kind of signal, but rather refer to them
+always by the names defined here.  This is because the number for a
+given kind of signal can vary from system to system, but the meanings of
+the names are standardized and fairly uniform.
+
+The signal names are defined in the header file @file{signal.h}.
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int NSIG
+The value of this symbolic constant is the total number of signals
+defined.  Since the signal numbers are allocated consecutively,
+@code{NSIG} is also one greater than the largest defined signal number.
+@end deftypevr
+
+@menu
+* 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.
+@end menu
+
+@node Program Error Signals
+@subsection Program Error Signals
+@cindex program error signals
+
+The following signals are generated when a serious program error is
+detected by the operating system or the computer itself.  In general,
+all of these signals are indications that your program is seriously
+broken in some way, and there's usually no way to continue the
+computation which encountered the error.
+
+Some programs handle program error signals in order to tidy up before
+terminating; for example, programs that turn off echoing of terminal
+input should handle program error signals in order to turn echoing back
+on.  The handler should end by specifying the default action for the
+signal that happened and then reraising it; this will cause the program
+to terminate with that signal, as if it had not had a handler.
+(@xref{Termination in Handler}.)
+
+Termination is the sensible ultimate outcome from a program error in
+most programs.  However, programming systems such as Lisp that can load
+compiled user programs might need to keep executing even if a user
+program incurs an error.  These programs have handlers which use
+@code{longjmp} to return control to the command level.
+
+The default action for all of these signals is to cause the process to
+terminate.  If you block or ignore these signals or establish handlers
+for them that return normally, your program will probably break horribly
+when such signals happen, unless they are generated by @code{raise} or
+@code{kill} instead of a real error.
+
+@vindex COREFILE
+When one of these program error signals terminates a process, it also
+writes a @dfn{core dump file} which records the state of the process at
+the time of termination.  The core dump file is named @file{core} and is
+written in whichever directory is current in the process at the time.
+(On @gnuhurdsystems{}, you can specify the file name for core dumps with
+the environment variable @code{COREFILE}.)  The purpose of core dump
+files is so that you can examine them with a debugger to investigate
+what caused the error.
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGFPE
+The @code{SIGFPE} signal reports a fatal arithmetic error.  Although the
+name is derived from ``floating-point exception'', this signal actually
+covers all arithmetic errors, including division by zero and overflow.
+If a program stores integer data in a location which is then used in a
+floating-point operation, this often causes an ``invalid operation''
+exception, because the processor cannot recognize the data as a
+floating-point number.
+@cindex exception
+@cindex floating-point exception
+
+Actual floating-point exceptions are a complicated subject because there
+are many types of exceptions with subtly different meanings, and the
+@code{SIGFPE} signal doesn't distinguish between them.  The @cite{IEEE
+Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985
+and ANSI/IEEE Std 854-1987)}
+defines various floating-point exceptions and requires conforming
+computer systems to report their occurrences.  However, this standard
+does not specify how the exceptions are reported, or what kinds of
+handling and control the operating system can offer to the programmer.
+@end deftypevr
+
+BSD systems provide the @code{SIGFPE} handler with an extra argument
+that distinguishes various causes of the exception.  In order to access
+this argument, you must define the handler to accept two arguments,
+which means you must cast it to a one-argument function type in order to
+establish the handler.  @Theglibc{} does provide this extra
+argument, but the value is meaningful only on operating systems that
+provide the information (BSD systems and @gnusystems{}).
+
+@table @code
+@comment signal.h
+@comment BSD
+@item FPE_INTOVF_TRAP
+@vindex FPE_INTOVF_TRAP
+Integer overflow (impossible in a C program unless you enable overflow
+trapping in a hardware-specific fashion).
+@comment signal.h
+@comment BSD
+@item FPE_INTDIV_TRAP
+@vindex FPE_INTDIV_TRAP
+Integer division by zero.
+@comment signal.h
+@comment BSD
+@item FPE_SUBRNG_TRAP
+@vindex FPE_SUBRNG_TRAP
+Subscript-range (something that C programs never check for).
+@comment signal.h
+@comment BSD
+@item FPE_FLTOVF_TRAP
+@vindex FPE_FLTOVF_TRAP
+Floating overflow trap.
+@comment signal.h
+@comment BSD
+@item FPE_FLTDIV_TRAP
+@vindex FPE_FLTDIV_TRAP
+Floating/decimal division by zero.
+@comment signal.h
+@comment BSD
+@item FPE_FLTUND_TRAP
+@vindex FPE_FLTUND_TRAP
+Floating underflow trap.  (Trapping on floating underflow is not
+normally enabled.)
+@comment signal.h
+@comment BSD
+@item FPE_DECOVF_TRAP
+@vindex FPE_DECOVF_TRAP
+Decimal overflow trap.  (Only a few machines have decimal arithmetic and
+C never uses it.)
+@ignore @c These seem redundant
+@comment signal.h
+@comment BSD
+@item FPE_FLTOVF_FAULT
+@vindex FPE_FLTOVF_FAULT
+Floating overflow fault.
+@comment signal.h
+@comment BSD
+@item FPE_FLTDIV_FAULT
+@vindex FPE_FLTDIV_FAULT
+Floating divide by zero fault.
+@comment signal.h
+@comment BSD
+@item FPE_FLTUND_FAULT
+@vindex FPE_FLTUND_FAULT
+Floating underflow fault.
+@end ignore
+@end table
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGILL
+The name of this signal is derived from ``illegal instruction''; it
+usually means your program is trying to execute garbage or a privileged
+instruction.  Since the C compiler generates only valid instructions,
+@code{SIGILL} typically indicates that the executable file is corrupted,
+or that you are trying to execute data.  Some common ways of getting
+into the latter situation are by passing an invalid object where a
+pointer to a function was expected, or by writing past the end of an
+automatic array (or similar problems with pointers to automatic
+variables) and corrupting other data on the stack such as the return
+address of a stack frame.
+
+@code{SIGILL} can also be generated when the stack overflows, or when
+the system has trouble running the handler for a signal.
+@end deftypevr
+@cindex illegal instruction
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGSEGV
+@cindex segmentation violation
+This signal is generated when a program tries to read or write outside
+the memory that is allocated for it, or to write memory that can only be
+read.  (Actually, the signals only occur when the program goes far
+enough outside to be detected by the system's memory protection
+mechanism.)  The name is an abbreviation for ``segmentation violation''.
+
+Common ways of getting a @code{SIGSEGV} condition include dereferencing
+a null or uninitialized pointer, or when you use a pointer to step
+through an array, but fail to check for the end of the array.  It varies
+among systems whether dereferencing a null pointer generates
+@code{SIGSEGV} or @code{SIGBUS}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGBUS
+This signal is generated when an invalid pointer is dereferenced.  Like
+@code{SIGSEGV}, this signal is typically the result of dereferencing an
+uninitialized pointer.  The difference between the two is that
+@code{SIGSEGV} indicates an invalid access to valid memory, while
+@code{SIGBUS} indicates an access to an invalid address.  In particular,
+@code{SIGBUS} signals often result from dereferencing a misaligned
+pointer, such as referring to a four-word integer at an address not
+divisible by four.  (Each kind of computer has its own requirements for
+address alignment.)
+
+The name of this signal is an abbreviation for ``bus error''.
+@end deftypevr
+@cindex bus error
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGABRT
+@cindex abort signal
+This signal indicates an error detected by the program itself and
+reported by calling @code{abort}.  @xref{Aborting a Program}.
+@end deftypevr
+
+@comment signal.h
+@comment Unix
+@deftypevr Macro int SIGIOT
+Generated by the PDP-11 ``iot'' instruction.  On most machines, this is
+just another name for @code{SIGABRT}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGTRAP
+Generated by the machine's breakpoint instruction, and possibly other
+trap instructions.  This signal is used by debuggers.  Your program will
+probably only see @code{SIGTRAP} if it is somehow executing bad
+instructions.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int  SIGEMT
+Emulator trap; this results from certain unimplemented instructions
+which might be emulated in software, or the operating system's
+failure to properly emulate them.
+@end deftypevr
+
+@comment signal.h
+@comment Unix
+@deftypevr Macro int  SIGSYS
+Bad system call; that is to say, the instruction to trap to the
+operating system was executed, but the code number for the system call
+to perform was invalid.
+@end deftypevr
+
+@node Termination Signals
+@subsection Termination Signals
+@cindex program termination signals
+
+These signals are all used to tell a process to terminate, in one way
+or another.  They have different names because they're used for slightly
+different purposes, and programs might want to handle them differently.
+
+The reason for handling these signals is usually so your program can
+tidy up as appropriate before actually terminating.  For example, you
+might want to save state information, delete temporary files, or restore
+the previous terminal modes.  Such a handler should end by specifying
+the default action for the signal that happened and then reraising it;
+this will cause the program to terminate with that signal, as if it had
+not had a handler.  (@xref{Termination in Handler}.)
+
+The (obvious) default action for all of these signals is to cause the
+process to terminate.
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGTERM
+@cindex termination signal
+The @code{SIGTERM} signal is a generic signal used to cause program
+termination.  Unlike @code{SIGKILL}, this signal can be blocked,
+handled, and ignored.  It is the normal way to politely ask a program to
+terminate.
+
+The shell command @code{kill} generates @code{SIGTERM} by default.
+@pindex kill
+@end deftypevr
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro int SIGINT
+@cindex interrupt signal
+The @code{SIGINT} (``program interrupt'') signal is sent when the user
+types the INTR character (normally @kbd{C-c}).  @xref{Special
+Characters}, for information about terminal driver support for
+@kbd{C-c}.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGQUIT
+@cindex quit signal
+@cindex quit signal
+The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
+controlled by a different key---the QUIT character, usually
+@kbd{C-\}---and produces a core dump when it terminates the process,
+just like a program error signal.  You can think of this as a
+program error condition ``detected'' by the user.
+
+@xref{Program Error Signals}, for information about core dumps.
+@xref{Special Characters}, for information about terminal driver
+support.
+
+Certain kinds of cleanups are best omitted in handling @code{SIGQUIT}.
+For example, if the program creates temporary files, it should handle
+the other termination requests by deleting the temporary files.  But it
+is better for @code{SIGQUIT} not to delete them, so that the user can
+examine them in conjunction with the core dump.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGKILL
+The @code{SIGKILL} signal is used to cause immediate program termination.
+It cannot be handled or ignored, and is therefore always fatal.  It is
+also not possible to block this signal.
+
+This signal is usually generated only by explicit request.  Since it
+cannot be handled, you should generate it only as a last resort, after
+first trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}.
+If a process does not respond to any other termination signals, sending
+it a @code{SIGKILL} signal will almost always cause it to go away.
+
+In fact, if @code{SIGKILL} fails to terminate a process, that by itself
+constitutes an operating system bug which you should report.
+
+The system will generate @code{SIGKILL} for a process itself under some
+unusual conditions where the program cannot possibly continue to run
+(even to run a signal handler).
+@end deftypevr
+@cindex kill signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGHUP
+@cindex hangup signal
+The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
+terminal is disconnected, perhaps because a network or telephone
+connection was broken.  For more information about this, see @ref{Control
+Modes}.
+
+This signal is also used to report the termination of the controlling
+process on a terminal to jobs associated with that session; this
+termination effectively disconnects all processes in the session from
+the controlling terminal.  For more information, see @ref{Termination
+Internals}.
+@end deftypevr
+
+@node Alarm Signals
+@subsection Alarm Signals
+
+These signals are used to indicate the expiration of timers.
+@xref{Setting an Alarm}, for information about functions that cause
+these signals to be sent.
+
+The default behavior for these signals is to cause program termination.
+This default is rarely useful, but no other default would be useful;
+most of the ways of using these signals would require handler functions
+in any case.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGALRM
+This signal typically indicates expiration of a timer that measures real
+or clock time.  It is used by the @code{alarm} function, for example.
+@end deftypevr
+@cindex alarm signal
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGVTALRM
+This signal typically indicates expiration of a timer that measures CPU
+time used by the current process.  The name is an abbreviation for
+``virtual time alarm''.
+@end deftypevr
+@cindex virtual time alarm signal
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGPROF
+This signal typically indicates expiration of a timer that measures
+both CPU time used by the current process, and CPU time expended on
+behalf of the process by the system.  Such a timer is used to implement
+code profiling facilities, hence the name of this signal.
+@end deftypevr
+@cindex profiling alarm signal
+
+
+@node Asynchronous I/O Signals
+@subsection Asynchronous I/O Signals
+
+The signals listed in this section are used in conjunction with
+asynchronous I/O facilities.  You have to take explicit action by
+calling @code{fcntl} to enable a particular file descriptor to generate
+these signals (@pxref{Interrupt Input}).  The default action for these
+signals is to ignore them.
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGIO
+@cindex input available signal
+@cindex output possible signal
+This signal is sent when a file descriptor is ready to perform input
+or output.
+
+On most operating systems, terminals and sockets are the only kinds of
+files that can generate @code{SIGIO}; other kinds, including ordinary
+files, never generate @code{SIGIO} even if you ask them to.
+
+On @gnusystems{} @code{SIGIO} will always be generated properly
+if you successfully set asynchronous mode with @code{fcntl}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGURG
+@cindex urgent data signal
+This signal is sent when ``urgent'' or out-of-band data arrives on a
+socket.  @xref{Out-of-Band Data}.
+@end deftypevr
+
+@comment signal.h
+@comment SVID
+@deftypevr Macro int SIGPOLL
+This is a System V signal name, more or less similar to @code{SIGIO}.
+It is defined only for compatibility.
+@end deftypevr
+
+@node Job Control Signals
+@subsection Job Control Signals
+@cindex job control signals
+
+These signals are used to support job control.  If your system
+doesn't support job control, then these macros are defined but the
+signals themselves can't be raised or handled.
+
+You should generally leave these signals alone unless you really
+understand how job control works.  @xref{Job Control}.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGCHLD
+@cindex child process signal
+This signal is sent to a parent process whenever one of its child
+processes terminates or stops.
+
+The default action for this signal is to ignore it.  If you establish a
+handler for this signal while there are child processes that have
+terminated but not reported their status via @code{wait} or
+@code{waitpid} (@pxref{Process Completion}), whether your new handler
+applies to those processes or not depends on the particular operating
+system.
+@end deftypevr
+
+@comment signal.h
+@comment SVID
+@deftypevr Macro int SIGCLD
+This is an obsolete name for @code{SIGCHLD}.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGCONT
+@cindex continue signal
+You can send a @code{SIGCONT} signal to a process to make it continue.
+This signal is special---it always makes the process continue if it is
+stopped, before the signal is delivered.  The default behavior is to do
+nothing else.  You cannot block this signal.  You can set a handler, but
+@code{SIGCONT} always makes the process continue regardless.
+
+Most programs have no reason to handle @code{SIGCONT}; they simply
+resume execution without realizing they were ever stopped.  You can use
+a handler for @code{SIGCONT} to make a program do something special when
+it is stopped and continued---for example, to reprint a prompt when it
+is suspended while waiting for input.
+@end deftypevr
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGSTOP
+The @code{SIGSTOP} signal stops the process.  It cannot be handled,
+ignored, or blocked.
+@end deftypevr
+@cindex stop signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTSTP
+The @code{SIGTSTP} signal is an interactive stop signal.  Unlike
+@code{SIGSTOP}, this signal can be handled and ignored.
+
+Your program should handle this signal if you have a special need to
+leave files or system tables in a secure state when a process is
+stopped.  For example, programs that turn off echoing should handle
+@code{SIGTSTP} so they can turn echoing back on before stopping.
+
+This signal is generated when the user types the SUSP character
+(normally @kbd{C-z}).  For more information about terminal driver
+support, see @ref{Special Characters}.
+@end deftypevr
+@cindex interactive stop signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTTIN
+A process cannot read from the user's terminal while it is running
+as a background job.  When any process in a background job tries to
+read from the terminal, all of the processes in the job are sent a
+@code{SIGTTIN} signal.  The default action for this signal is to
+stop the process.  For more information about how this interacts with
+the terminal driver, see @ref{Access to the Terminal}.
+@end deftypevr
+@cindex terminal input signal
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGTTOU
+This is similar to @code{SIGTTIN}, but is generated when a process in a
+background job attempts to write to the terminal or set its modes.
+Again, the default action is to stop the process.  @code{SIGTTOU} is
+only generated for an attempt to write to the terminal if the
+@code{TOSTOP} output mode is set; @pxref{Output Modes}.
+@end deftypevr
+@cindex terminal output signal
+
+While a process is stopped, no more signals can be delivered to it until
+it is continued, except @code{SIGKILL} signals and (obviously)
+@code{SIGCONT} signals.  The signals are marked as pending, but not
+delivered until the process is continued.  The @code{SIGKILL} signal
+always causes termination of the process and can't be blocked, handled
+or ignored.  You can ignore @code{SIGCONT}, but it always causes the
+process to be continued anyway if it is stopped.  Sending a
+@code{SIGCONT} signal to a process causes any pending stop signals for
+that process to be discarded.  Likewise, any pending @code{SIGCONT}
+signals for a process are discarded when it receives a stop signal.
+
+When a process in an orphaned process group (@pxref{Orphaned Process
+Groups}) receives a @code{SIGTSTP}, @code{SIGTTIN}, or @code{SIGTTOU}
+signal and does not handle it, the process does not stop.  Stopping the
+process would probably not be very useful, since there is no shell
+program that will notice it stop and allow the user to continue it.
+What happens instead depends on the operating system you are using.
+Some systems may do nothing; others may deliver another signal instead,
+such as @code{SIGKILL} or @code{SIGHUP}.  On @gnuhurdsystems{}, the process
+dies with @code{SIGKILL}; this avoids the problem of many stopped,
+orphaned processes lying around the system.
+
+@ignore
+On @gnuhurdsystems{}, it is possible to reattach to the orphaned process
+group and continue it, so stop signals do stop the process as usual on
+@gnuhurdsystems{} unless you have requested POSIX compatibility ``till it
+hurts.''
+@end ignore
+
+@node Operation Error Signals
+@subsection Operation Error Signals
+
+These signals are used to report various errors generated by an
+operation done by the program.  They do not necessarily indicate a
+programming error in the program, but an error that prevents an
+operating system call from completing.  The default action for all of
+them is to cause the process to terminate.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGPIPE
+@cindex pipe signal
+@cindex broken pipe signal
+Broken pipe.  If you use pipes or FIFOs, you have to design your
+application so that one process opens the pipe for reading before
+another starts writing.  If the reading process never starts, or
+terminates unexpectedly, writing to the pipe or FIFO raises a
+@code{SIGPIPE} signal.  If @code{SIGPIPE} is blocked, handled or
+ignored, the offending call fails with @code{EPIPE} instead.
+
+Pipes and FIFO special files are discussed in more detail in @ref{Pipes
+and FIFOs}.
+
+Another cause of @code{SIGPIPE} is when you try to output to a socket
+that isn't connected.  @xref{Sending Data}.
+@end deftypevr
+
+@comment signal.h
+@comment GNU
+@deftypevr Macro int SIGLOST
+@cindex lost resource signal
+Resource lost.  This signal is generated when you have an advisory lock
+on an NFS file, and the NFS server reboots and forgets about your lock.
+
+On @gnuhurdsystems{}, @code{SIGLOST} is generated when any server program
+dies unexpectedly.  It is usually fine to ignore the signal; whatever
+call was made to the server that died just returns an error.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGXCPU
+CPU time limit exceeded.  This signal is generated when the process
+exceeds its soft resource limit on CPU time.  @xref{Limits on Resources}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGXFSZ
+File size limit exceeded.  This signal is generated when the process
+attempts to extend a file so it exceeds the process's soft resource
+limit on file size.  @xref{Limits on Resources}.
+@end deftypevr
+
+@node Miscellaneous Signals
+@subsection Miscellaneous Signals
+
+These signals are used for various other purposes.  In general, they
+will not affect your program unless it explicitly uses them for something.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SIGUSR1
+@comment signal.h
+@comment POSIX.1
+@deftypevrx Macro int SIGUSR2
+@cindex user signals
+The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to
+use any way you want.  They're useful for simple interprocess
+communication, if you write a signal handler for them in the program
+that receives the signal.
+
+There is an example showing the use of @code{SIGUSR1} and @code{SIGUSR2}
+in @ref{Signaling Another Process}.
+
+The default action is to terminate the process.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGWINCH
+Window size change.  This is generated on some systems (including GNU)
+when the terminal driver's record of the number of rows and columns on
+the screen is changed.  The default action is to ignore it.
+
+If a program does full-screen display, it should handle @code{SIGWINCH}.
+When the signal arrives, it should fetch the new screen size and
+reformat its display accordingly.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SIGINFO
+Information request.  On 4.4 BSD and @gnuhurdsystems{}, this signal is sent
+to all the processes in the foreground process group of the controlling
+terminal when the user types the STATUS character in canonical mode;
+@pxref{Signal Characters}.
+
+If the process is the leader of the process group, the default action is
+to print some status information about the system and what the process
+is doing.  Otherwise the default is to do nothing.
+@end deftypevr
+
+@node Signal Messages
+@subsection Signal Messages
+@cindex signal messages
+
+We mentioned above that the shell prints a message describing the signal
+that terminated a child process.  The clean way to print a message
+describing a signal is to use the functions @code{strsignal} and
+@code{psignal}.  These functions use a signal number to specify which
+kind of signal to describe.  The signal number may come from the
+termination status of a child process (@pxref{Process Completion}) or it
+may come from a signal handler in the same process.
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strsignal (int @var{signum})
+@safety{@prelim{}@mtunsafe{@mtasurace{:strsignal} @mtslocale{}}@asunsafe{@asuinit{} @ascuintl{} @asucorrupt{} @ascuheap{}}@acunsafe{@acuinit{} @acucorrupt{} @acsmem{}}}
+@c strsignal @mtasurace:strsignal @mtslocale @asuinit @ascuintl @asucorrupt @ascuheap @acucorrupt @acsmem
+@c   uses a static buffer if tsd key creation fails
+@c  [once] init
+@c   libc_key_create ok
+@c    pthread_key_create dup ok
+@c  getbuffer @asucorrupt @ascuheap @acsmem
+@c   libc_getspecific ok
+@c    pthread_getspecific dup ok
+@c   malloc dup @ascuheap @acsmem
+@c   libc_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
+@c    pthread_setspecific dup @asucorrupt @ascuheap @acucorrupt @acsmem
+@c  snprintf dup @mtslocale @ascuheap @acsmem
+@c  _ @ascuintl
+This function returns a pointer to a statically-allocated string
+containing a message describing the signal @var{signum}.  You
+should not modify the contents of this string; and, since it can be
+rewritten on subsequent calls, you should save a copy of it if you need
+to reference it later.
+
+@pindex string.h
+This function is a GNU extension, declared in the header file
+@file{string.h}.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun void psignal (int @var{signum}, const char *@var{message})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c psignal @mtslocale @asucorrupt @ascuintl @ascuheap @aculock @acucorrupt @acsmem
+@c  _ @ascuintl
+@c  fxprintf @asucorrupt @aculock @acucorrupt
+@c  asprintf @mtslocale @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+This function prints a message describing the signal @var{signum} to the
+standard error output stream @code{stderr}; see @ref{Standard Streams}.
+
+If you call @code{psignal} with a @var{message} that is either a null
+pointer or an empty string, @code{psignal} just prints the message
+corresponding to @var{signum}, adding a trailing newline.
+
+If you supply a non-null @var{message} argument, then @code{psignal}
+prefixes its output with this string.  It adds a colon and a space
+character to separate the @var{message} from the string corresponding
+to @var{signum}.
+
+@pindex stdio.h
+This function is a BSD feature, declared in the header file @file{signal.h}.
+@end deftypefun
+
+@vindex sys_siglist
+There is also an array @code{sys_siglist} which contains the messages
+for the various signal codes.  This array exists on BSD systems, unlike
+@code{strsignal}.
+
+@node Signal Actions
+@section Specifying Signal Actions
+@cindex signal actions
+@cindex establishing a handler
+
+The simplest way to change the action for a signal is to use the
+@code{signal} function.  You can specify a built-in action (such as to
+ignore the signal), or you can @dfn{establish a handler}.
+
+@Theglibc{} also implements the more versatile @code{sigaction}
+facility.  This section describes both facilities and gives suggestions
+on which to use when.
+
+@menu
+* 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.
+@end menu
+
+@node Basic Signal Handling
+@subsection Basic Signal Handling
+@cindex @code{signal} function
+
+The @code{signal} function provides a simple interface for establishing
+an action for a particular signal.  The function and associated macros
+are declared in the header file @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment GNU
+@deftp {Data Type} sighandler_t
+This is the type of signal handler functions.  Signal handlers take one
+integer argument specifying the signal number, and have return type
+@code{void}.  So, you should define handler functions like this:
+
+@smallexample
+void @var{handler} (int @code{signum}) @{ @dots{} @}
+@end smallexample
+
+The name @code{sighandler_t} for this data type is a GNU extension.
+@end deftp
+
+@comment signal.h
+@comment ISO
+@deftypefun sighandler_t signal (int @var{signum}, sighandler_t @var{action})
+@safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}}
+@c signal ok
+@c  sigemptyset dup ok
+@c  sigaddset dup ok
+@c  sigismember dup ok
+@c  sigaction dup ok
+The @code{signal} function establishes @var{action} as the action for
+the signal @var{signum}.
+
+The first argument, @var{signum}, identifies the signal whose behavior
+you want to control, and should be a signal number.  The proper way to
+specify a signal number is with one of the symbolic signal names
+(@pxref{Standard Signals})---don't use an explicit number, because
+the numerical code for a given kind of signal may vary from operating
+system to operating system.
+
+The second argument, @var{action}, specifies the action to use for the
+signal @var{signum}.  This can be one of the following:
+
+@table @code
+@item SIG_DFL
+@vindex SIG_DFL
+@cindex default action for a signal
+@code{SIG_DFL} specifies the default action for the particular signal.
+The default actions for various kinds of signals are stated in
+@ref{Standard Signals}.
+
+@item SIG_IGN
+@vindex SIG_IGN
+@cindex ignore action for a signal
+@code{SIG_IGN} specifies that the signal should be ignored.
+
+Your program generally should not ignore signals that represent serious
+events or that are normally used to request termination.  You cannot
+ignore the @code{SIGKILL} or @code{SIGSTOP} signals at all.  You can
+ignore program error signals like @code{SIGSEGV}, but ignoring the error
+won't enable the program to continue executing meaningfully.  Ignoring
+user requests such as @code{SIGINT}, @code{SIGQUIT}, and @code{SIGTSTP}
+is unfriendly.
+
+When you do not wish signals to be delivered during a certain part of
+the program, the thing to do is to block them, not ignore them.
+@xref{Blocking Signals}.
+
+@item @var{handler}
+Supply the address of a handler function in your program, to specify
+running this handler as the way to deliver the signal.
+
+For more information about defining signal handler functions,
+see @ref{Defining Handlers}.
+@end table
+
+If you set the action for a signal to @code{SIG_IGN}, or if you set it
+to @code{SIG_DFL} and the default action is to ignore that signal, then
+any pending signals of that type are discarded (even if they are
+blocked).  Discarding the pending signals means that they will never be
+delivered, not even if you subsequently specify another action and
+unblock this kind of signal.
+
+The @code{signal} function returns the action that was previously in
+effect for the specified @var{signum}.  You can save this value and
+restore it later by calling @code{signal} again.
+
+If @code{signal} can't honor the request, it returns @code{SIG_ERR}
+instead.  The following @code{errno} error conditions are defined for
+this function:
+
+@table @code
+@item EINVAL
+You specified an invalid @var{signum}; or you tried to ignore or provide
+a handler for @code{SIGKILL} or @code{SIGSTOP}.
+@end table
+@end deftypefun
+
+@strong{Compatibility Note:} A problem encountered when working with the
+@code{signal} function is that it has different semantics on BSD and
+SVID systems.  The difference is that on SVID systems the signal handler
+is deinstalled after signal delivery.  On BSD systems the
+handler must be explicitly deinstalled.  In @theglibc{} we use the
+BSD version by default.  To use the SVID version you can either use the
+function @code{sysv_signal} (see below) or use the @code{_XOPEN_SOURCE}
+feature select macro (@pxref{Feature Test Macros}).  In general, use of these
+functions should be avoided because of compatibility problems.  It
+is better to use @code{sigaction} if it is available since the results
+are much more reliable.
+
+Here is a simple example of setting up a handler to delete temporary
+files when certain fatal signals happen:
+
+@smallexample
+#include <signal.h>
+
+void
+termination_handler (int signum)
+@{
+  struct temp_file *p;
+
+  for (p = temp_file_list; p; p = p->next)
+    unlink (p->name);
+@}
+
+int
+main (void)
+@{
+  @dots{}
+  if (signal (SIGINT, termination_handler) == SIG_IGN)
+    signal (SIGINT, SIG_IGN);
+  if (signal (SIGHUP, termination_handler) == SIG_IGN)
+    signal (SIGHUP, SIG_IGN);
+  if (signal (SIGTERM, termination_handler) == SIG_IGN)
+    signal (SIGTERM, SIG_IGN);
+  @dots{}
+@}
+@end smallexample
+
+@noindent
+Note that if a given signal was previously set to be ignored, this code
+avoids altering that setting.  This is because non-job-control shells
+often ignore certain signals when starting children, and it is important
+for the children to respect this.
+
+We do not handle @code{SIGQUIT} or the program error signals in this
+example because these are designed to provide information for debugging
+(a core dump), and the temporary files may give useful information.
+
+@comment signal.h
+@comment GNU
+@deftypefun sighandler_t sysv_signal (int @var{signum}, sighandler_t @var{action})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c sysv_signal ok
+@c  sigemptyset dup ok
+@c  sigaction dup ok
+The @code{sysv_signal} implements the behavior of the standard
+@code{signal} function as found on SVID systems.  The difference to BSD
+systems is that the handler is deinstalled after a delivery of a signal.
+
+@strong{Compatibility Note:} As said above for @code{signal}, this
+function should be avoided when possible.  @code{sigaction} is the
+preferred method.
+@end deftypefun
+
+@comment signal.h
+@comment SVID
+@deftypefun sighandler_t ssignal (int @var{signum}, sighandler_t @var{action})
+@safety{@prelim{}@mtsafe{@mtssigintr{}}@assafe{}@acsafe{}}
+@c Aliases signal and bsd_signal.
+The @code{ssignal} function does the same thing as @code{signal}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
+@comment signal.h
+@comment ISO
+@deftypevr Macro sighandler_t SIG_ERR
+The value of this macro is used as the return value from @code{signal}
+to indicate an error.
+@end deftypevr
+
+@ignore
+@comment RMS says that ``we don't do this''.
+Implementations might define additional macros for built-in signal
+actions that are suitable as a @var{action} argument to @code{signal},
+besides @code{SIG_IGN} and @code{SIG_DFL}.  Identifiers whose names
+begin with @samp{SIG_} followed by an uppercase letter are reserved for
+this purpose.
+@end ignore
+
+
+@node Advanced Signal Handling
+@subsection Advanced Signal Handling
+@cindex @code{sigaction} function
+
+The @code{sigaction} function has the same basic effect as
+@code{signal}: to specify how a signal should be handled by the process.
+However, @code{sigaction} offers more control, at the expense of more
+complexity.  In particular, @code{sigaction} allows you to specify
+additional flags to control when the signal is generated and how the
+handler is invoked.
+
+The @code{sigaction} function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftp {Data Type} {struct sigaction}
+Structures of type @code{struct sigaction} are used in the
+@code{sigaction} function to specify all the information about how to
+handle a particular signal.  This structure contains at least the
+following members:
+
+@table @code
+@item sighandler_t sa_handler
+This is used in the same way as the @var{action} argument to the
+@code{signal} function.  The value can be @code{SIG_DFL},
+@code{SIG_IGN}, or a function pointer.  @xref{Basic Signal Handling}.
+
+@item sigset_t sa_mask
+This specifies a set of signals to be blocked while the handler runs.
+Blocking is explained in @ref{Blocking for Handler}.  Note that the
+signal that was delivered is automatically blocked by default before its
+handler is started; this is true regardless of the value in
+@code{sa_mask}.  If you want that signal not to be blocked within its
+handler, you must write code in the handler to unblock it.
+
+@item int sa_flags
+This specifies various flags which can affect the behavior of
+the signal.  These are described in more detail in @ref{Flags for Sigaction}.
+@end table
+@end deftp
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigaction (int @var{signum}, const struct sigaction *restrict @var{action}, struct sigaction *restrict @var{old-action})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @var{action} argument is used to set up a new action for the signal
+@var{signum}, while the @var{old-action} argument is used to return
+information about the action previously associated with this symbol.
+(In other words, @var{old-action} has the same purpose as the
+@code{signal} function's return value---you can check to see what the
+old action in effect for the signal was, and restore it later if you
+want.)
+
+Either @var{action} or @var{old-action} can be a null pointer.  If
+@var{old-action} is a null pointer, this simply suppresses the return
+of information about the old action.  If @var{action} is a null pointer,
+the action associated with the signal @var{signum} is unchanged; this
+allows you to inquire about how a signal is being handled without changing
+that handling.
+
+The return value from @code{sigaction} is zero if it succeeds, and
+@code{-1} on failure.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument is not valid, or you are trying to
+trap or ignore @code{SIGKILL} or @code{SIGSTOP}.
+@end table
+@end deftypefun
+
+@node Signal and Sigaction
+@subsection Interaction of @code{signal} and @code{sigaction}
+
+It's possible to use both the @code{signal} and @code{sigaction}
+functions within a single program, but you have to be careful because
+they can interact in slightly strange ways.
+
+The @code{sigaction} function specifies more information than the
+@code{signal} function, so the return value from @code{signal} cannot
+express the full range of @code{sigaction} possibilities.  Therefore, if
+you use @code{signal} to save and later reestablish an action, it may
+not be able to reestablish properly a handler that was established with
+@code{sigaction}.
+
+To avoid having problems as a result, always use @code{sigaction} to
+save and restore a handler if your program uses @code{sigaction} at all.
+Since @code{sigaction} is more general, it can properly save and
+reestablish any action, regardless of whether it was established
+originally with @code{signal} or @code{sigaction}.
+
+On some systems if you establish an action with @code{signal} and then
+examine it with @code{sigaction}, the handler address that you get may
+not be the same as what you specified with @code{signal}.  It may not
+even be suitable for use as an action argument with @code{signal}.  But
+you can rely on using it as an argument to @code{sigaction}.  This
+problem never happens on @gnusystems{}.
+
+So, you're better off using one or the other of the mechanisms
+consistently within a single program.
+
+@strong{Portability Note:} The basic @code{signal} function is a feature
+of @w{ISO C}, while @code{sigaction} is part of the POSIX.1 standard.  If
+you are concerned about portability to non-POSIX systems, then you
+should use the @code{signal} function instead.
+
+@node Sigaction Function Example
+@subsection @code{sigaction} Function Example
+
+In @ref{Basic Signal Handling}, we gave an example of establishing a
+simple handler for termination signals using @code{signal}.  Here is an
+equivalent example using @code{sigaction}:
+
+@smallexample
+#include <signal.h>
+
+void
+termination_handler (int signum)
+@{
+  struct temp_file *p;
+
+  for (p = temp_file_list; p; p = p->next)
+    unlink (p->name);
+@}
+
+int
+main (void)
+@{
+  @dots{}
+  struct sigaction new_action, old_action;
+
+  /* @r{Set up the structure to specify the new action.} */
+  new_action.sa_handler = termination_handler;
+  sigemptyset (&new_action.sa_mask);
+  new_action.sa_flags = 0;
+
+  sigaction (SIGINT, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGINT, &new_action, NULL);
+  sigaction (SIGHUP, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGHUP, &new_action, NULL);
+  sigaction (SIGTERM, NULL, &old_action);
+  if (old_action.sa_handler != SIG_IGN)
+    sigaction (SIGTERM, &new_action, NULL);
+  @dots{}
+@}
+@end smallexample
+
+The program just loads the @code{new_action} structure with the desired
+parameters and passes it in the @code{sigaction} call.  The usage of
+@code{sigemptyset} is described later; see @ref{Blocking Signals}.
+
+As in the example using @code{signal}, we avoid handling signals
+previously set to be ignored.  Here we can avoid altering the signal
+handler even momentarily, by using the feature of @code{sigaction} that
+lets us examine the current action without specifying a new one.
+
+Here is another example.  It retrieves information about the current
+action for @code{SIGINT} without changing that action.
+
+@smallexample
+struct sigaction query_action;
+
+if (sigaction (SIGINT, NULL, &query_action) < 0)
+  /* @r{@code{sigaction} returns -1 in case of error.} */
+else if (query_action.sa_handler == SIG_DFL)
+  /* @r{@code{SIGINT} is handled in the default, fatal manner.} */
+else if (query_action.sa_handler == SIG_IGN)
+  /* @r{@code{SIGINT} is ignored.} */
+else
+  /* @r{A programmer-defined signal handler is in effect.} */
+@end smallexample
+
+@node Flags for Sigaction
+@subsection Flags for @code{sigaction}
+@cindex signal flags
+@cindex flags for @code{sigaction}
+@cindex @code{sigaction} flags
+
+The @code{sa_flags} member of the @code{sigaction} structure is a
+catch-all for special features.  Most of the time, @code{SA_RESTART} is
+a good value to use for this field.
+
+The value of @code{sa_flags} is interpreted as a bit mask.  Thus, you
+should choose the flags you want to set, @sc{or} those flags together,
+and store the result in the @code{sa_flags} member of your
+@code{sigaction} structure.
+
+Each signal number has its own set of flags.  Each call to
+@code{sigaction} affects one particular signal number, and the flags
+that you specify apply only to that particular signal.
+
+In @theglibc{}, establishing a handler with @code{signal} sets all
+the flags to zero except for @code{SA_RESTART}, whose value depends on
+the settings you have made with @code{siginterrupt}.  @xref{Interrupted
+Primitives}, to see what this is about.
+
+@pindex signal.h
+These macros are defined in the header file @file{signal.h}.
+
+@comment signal.h
+@comment POSIX.1
+@deftypevr Macro int SA_NOCLDSTOP
+This flag is meaningful only for the @code{SIGCHLD} signal.  When the
+flag is set, the system delivers the signal for a terminated child
+process but not for one that is stopped.  By default, @code{SIGCHLD} is
+delivered for both terminated children and stopped children.
+
+Setting this flag for a signal other than @code{SIGCHLD} has no effect.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SA_ONSTACK
+If this flag is set for a particular signal number, the system uses the
+signal stack when delivering that kind of signal.  @xref{Signal Stack}.
+If a signal with this flag arrives and you have not set a signal stack,
+the system terminates the program with @code{SIGILL}.
+@end deftypevr
+
+@comment signal.h
+@comment BSD
+@deftypevr Macro int SA_RESTART
+This flag controls what happens when a signal is delivered during
+certain primitives (such as @code{open}, @code{read} or @code{write}),
+and the signal handler returns normally.  There are two alternatives:
+the library function can resume, or it can return failure with error
+code @code{EINTR}.
+
+The choice is controlled by the @code{SA_RESTART} flag for the
+particular kind of signal that was delivered.  If the flag is set,
+returning from a handler resumes the library function.  If the flag is
+clear, returning from a handler makes the function fail.
+@xref{Interrupted Primitives}.
+@end deftypevr
+
+@node Initial Signal Actions
+@subsection Initial Signal Actions
+@cindex initial signal actions
+
+When a new process is created (@pxref{Creating a Process}), it inherits
+handling of signals from its parent process.  However, when you load a
+new process image using the @code{exec} function (@pxref{Executing a
+File}), any signals that you've defined your own handlers for revert to
+their @code{SIG_DFL} handling.  (If you think about it a little, this
+makes sense; the handler functions from the old program are specific to
+that program, and aren't even present in the address space of the new
+program image.)  Of course, the new program can establish its own
+handlers.
+
+When a program is run by a shell, the shell normally sets the initial
+actions for the child process to @code{SIG_DFL} or @code{SIG_IGN}, as
+appropriate.  It's a good idea to check to make sure that the shell has
+not set up an initial action of @code{SIG_IGN} before you establish your
+own signal handlers.
+
+Here is an example of how to establish a handler for @code{SIGHUP}, but
+not if @code{SIGHUP} is currently ignored:
+
+@smallexample
+@group
+@dots{}
+struct sigaction temp;
+
+sigaction (SIGHUP, NULL, &temp);
+
+if (temp.sa_handler != SIG_IGN)
+  @{
+    temp.sa_handler = handle_sighup;
+    sigemptyset (&temp.sa_mask);
+    sigaction (SIGHUP, &temp, NULL);
+  @}
+@end group
+@end smallexample
+
+@node Defining Handlers
+@section Defining Signal Handlers
+@cindex signal handler function
+
+This section describes how to write a signal handler function that can
+be established with the @code{signal} or @code{sigaction} functions.
+
+A signal handler is just a function that you compile together with the
+rest of the program.  Instead of directly invoking the function, you use
+@code{signal} or @code{sigaction} to tell the operating system to call
+it when a signal arrives.  This is known as @dfn{establishing} the
+handler.  @xref{Signal Actions}.
+
+There are two basic strategies you can use in signal handler functions:
+
+@itemize @bullet
+@item
+You can have the handler function note that the signal arrived by
+tweaking some global data structures, and then return normally.
+
+@item
+You can have the handler function terminate the program or transfer
+control to a point where it can recover from the situation that caused
+the signal.
+@end itemize
+
+You need to take special care in writing handler functions because they
+can be called asynchronously.  That is, a handler might be called at any
+point in the program, unpredictably.  If two signals arrive during a
+very short interval, one handler can run within another.  This section
+describes what your handler should do, and what you should avoid.
+
+@menu
+* 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.
+@end menu
+
+@node Handler Returns
+@subsection Signal Handlers that Return
+
+Handlers which return normally are usually used for signals such as
+@code{SIGALRM} and the I/O and interprocess communication signals.  But
+a handler for @code{SIGINT} might also return normally after setting a
+flag that tells the program to exit at a convenient time.
+
+It is not safe to return normally from the handler for a program error
+signal, because the behavior of the program when the handler function
+returns is not defined after a program error.  @xref{Program Error
+Signals}.
+
+Handlers that return normally must modify some global variable in order
+to have any effect.  Typically, the variable is one that is examined
+periodically by the program during normal operation.  Its data type
+should be @code{sig_atomic_t} for reasons described in @ref{Atomic
+Data Access}.
+
+Here is a simple example of such a program.  It executes the body of
+the loop until it has noticed that a @code{SIGALRM} signal has arrived.
+This technique is useful because it allows the iteration in progress
+when the signal arrives to complete before the loop exits.
+
+@smallexample
+@include sigh1.c.texi
+@end smallexample
+
+@node Termination in Handler
+@subsection Handlers That Terminate the Process
+
+Handler functions that terminate the program are typically used to cause
+orderly cleanup or recovery from program error signals and interactive
+interrupts.
+
+The cleanest way for a handler to terminate the process is to raise the
+same signal that ran the handler in the first place.  Here is how to do
+this:
+
+@smallexample
+volatile sig_atomic_t fatal_error_in_progress = 0;
+
+void
+fatal_error_signal (int sig)
+@{
+@group
+  /* @r{Since this handler is established for more than one kind of signal, }
+     @r{it might still get invoked recursively by delivery of some other kind}
+     @r{of signal.  Use a static variable to keep track of that.} */
+  if (fatal_error_in_progress)
+    raise (sig);
+  fatal_error_in_progress = 1;
+@end group
+
+@group
+  /* @r{Now do the clean up actions:}
+     @r{- reset terminal modes}
+     @r{- kill child processes}
+     @r{- remove lock files} */
+  @dots{}
+@end group
+
+@group
+  /* @r{Now reraise the signal.  We reactivate the signal's}
+     @r{default handling, which is to terminate the process.}
+     @r{We could just call @code{exit} or @code{abort},}
+     @r{but reraising the signal sets the return status}
+     @r{from the process correctly.} */
+  signal (sig, SIG_DFL);
+  raise (sig);
+@}
+@end group
+@end smallexample
+
+@node Longjmp in Handler
+@subsection Nonlocal Control Transfer in Handlers
+@cindex non-local exit, from signal handler
+
+You can do a nonlocal transfer of control out of a signal handler using
+the @code{setjmp} and @code{longjmp} facilities (@pxref{Non-Local
+Exits}).
+
+When the handler does a nonlocal control transfer, the part of the
+program that was running will not continue.  If this part of the program
+was in the middle of updating an important data structure, the data
+structure will remain inconsistent.  Since the program does not
+terminate, the inconsistency is likely to be noticed later on.
+
+There are two ways to avoid this problem.  One is to block the signal
+for the parts of the program that update important data structures.
+Blocking the signal delays its delivery until it is unblocked, once the
+critical updating is finished.  @xref{Blocking Signals}.
+
+The other way is to re-initialize the crucial data structures in the
+signal handler, or to make their values consistent.
+
+Here is a rather schematic example showing the reinitialization of one
+global variable.
+
+@smallexample
+@group
+#include <signal.h>
+#include <setjmp.h>
+
+jmp_buf return_to_top_level;
+
+volatile sig_atomic_t waiting_for_input;
+
+void
+handle_sigint (int signum)
+@{
+  /* @r{We may have been waiting for input when the signal arrived,}
+     @r{but we are no longer waiting once we transfer control.} */
+  waiting_for_input = 0;
+  longjmp (return_to_top_level, 1);
+@}
+@end group
+
+@group
+int
+main (void)
+@{
+  @dots{}
+  signal (SIGINT, sigint_handler);
+  @dots{}
+  while (1) @{
+    prepare_for_command ();
+    if (setjmp (return_to_top_level) == 0)
+      read_and_execute_command ();
+  @}
+@}
+@end group
+
+@group
+/* @r{Imagine this is a subroutine used by various commands.} */
+char *
+read_data ()
+@{
+  if (input_from_terminal) @{
+    waiting_for_input = 1;
+    @dots{}
+    waiting_for_input = 0;
+  @} else @{
+    @dots{}
+  @}
+@}
+@end group
+@end smallexample
+
+
+@node Signals in Handler
+@subsection Signals Arriving While a Handler Runs
+@cindex race conditions, relating to signals
+
+What happens if another signal arrives while your signal handler
+function is running?
+
+When the handler for a particular signal is invoked, that signal is
+automatically blocked until the handler returns.  That means that if two
+signals of the same kind arrive close together, the second one will be
+held until the first has been handled.  (The handler can explicitly
+unblock the signal using @code{sigprocmask}, if you want to allow more
+signals of this type to arrive; see @ref{Process Signal Mask}.)
+
+However, your handler can still be interrupted by delivery of another
+kind of signal.  To avoid this, you can use the @code{sa_mask} member of
+the action structure passed to @code{sigaction} to explicitly specify
+which signals should be blocked while the signal handler runs.  These
+signals are in addition to the signal for which the handler was invoked,
+and any other signals that are normally blocked by the process.
+@xref{Blocking for Handler}.
+
+When the handler returns, the set of blocked signals is restored to the
+value it had before the handler ran.  So using @code{sigprocmask} inside
+the handler only affects what signals can arrive during the execution of
+the handler itself, not what signals can arrive once the handler returns.
+
+@strong{Portability Note:} Always use @code{sigaction} to establish a
+handler for a signal that you expect to receive asynchronously, if you
+want your program to work properly on System V Unix.  On this system,
+the handling of a signal whose handler was established with
+@code{signal} automatically sets the signal's action back to
+@code{SIG_DFL}, and the handler must re-establish itself each time it
+runs.  This practice, while inconvenient, does work when signals cannot
+arrive in succession.  However, if another signal can arrive right away,
+it may arrive before the handler can re-establish itself.  Then the
+second signal would receive the default handling, which could terminate
+the process.
+
+@node Merged Signals
+@subsection Signals Close Together Merge into One
+@cindex handling multiple signals
+@cindex successive signals
+@cindex merging of signals
+
+If multiple signals of the same type are delivered to your process
+before your signal handler has a chance to be invoked at all, the
+handler may only be invoked once, as if only a single signal had
+arrived.  In effect, the signals merge into one.  This situation can
+arise when the signal is blocked, or in a multiprocessing environment
+where the system is busy running some other processes while the signals
+are delivered.  This means, for example, that you cannot reliably use a
+signal handler to count signals.  The only distinction you can reliably
+make is whether at least one signal has arrived since a given time in
+the past.
+
+Here is an example of a handler for @code{SIGCHLD} that compensates for
+the fact that the number of signals received may not equal the number of
+child processes that generate them.  It assumes that the program keeps track
+of all the child processes with a chain of structures as follows:
+
+@smallexample
+struct process
+@{
+  struct process *next;
+  /* @r{The process ID of this child.}  */
+  int pid;
+  /* @r{The descriptor of the pipe or pseudo terminal}
+     @r{on which output comes from this child.}  */
+  int input_descriptor;
+  /* @r{Nonzero if this process has stopped or terminated.}  */
+  sig_atomic_t have_status;
+  /* @r{The status of this child; 0 if running,}
+     @r{otherwise a status value from @code{waitpid}.}  */
+  int status;
+@};
+
+struct process *process_list;
+@end smallexample
+
+This example also uses a flag to indicate whether signals have arrived
+since some time in the past---whenever the program last cleared it to
+zero.
+
+@smallexample
+/* @r{Nonzero means some child's status has changed}
+   @r{so look at @code{process_list} for the details.}  */
+int process_status_change;
+@end smallexample
+
+Here is the handler itself:
+
+@smallexample
+void
+sigchld_handler (int signo)
+@{
+  int old_errno = errno;
+
+  while (1) @{
+    register int pid;
+    int w;
+    struct process *p;
+
+    /* @r{Keep asking for a status until we get a definitive result.}  */
+    do
+      @{
+        errno = 0;
+        pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
+      @}
+    while (pid <= 0 && errno == EINTR);
+
+    if (pid <= 0) @{
+      /* @r{A real failure means there are no more}
+         @r{stopped or terminated child processes, so return.}  */
+      errno = old_errno;
+      return;
+    @}
+
+    /* @r{Find the process that signaled us, and record its status.}  */
+
+    for (p = process_list; p; p = p->next)
+      if (p->pid == pid) @{
+        p->status = w;
+        /* @r{Indicate that the @code{status} field}
+           @r{has data to look at.  We do this only after storing it.}  */
+        p->have_status = 1;
+
+        /* @r{If process has terminated, stop waiting for its output.}  */
+        if (WIFSIGNALED (w) || WIFEXITED (w))
+          if (p->input_descriptor)
+            FD_CLR (p->input_descriptor, &input_wait_mask);
+
+        /* @r{The program should check this flag from time to time}
+           @r{to see if there is any news in @code{process_list}.}  */
+        ++process_status_change;
+      @}
+
+    /* @r{Loop around to handle all the processes}
+       @r{that have something to tell us.}  */
+  @}
+@}
+@end smallexample
+
+Here is the proper way to check the flag @code{process_status_change}:
+
+@smallexample
+if (process_status_change) @{
+  struct process *p;
+  process_status_change = 0;
+  for (p = process_list; p; p = p->next)
+    if (p->have_status) @{
+      @dots{} @r{Examine @code{p->status}} @dots{}
+    @}
+@}
+@end smallexample
+
+@noindent
+It is vital to clear the flag before examining the list; otherwise, if a
+signal were delivered just before the clearing of the flag, and after
+the appropriate element of the process list had been checked, the status
+change would go unnoticed until the next signal arrived to set the flag
+again.  You could, of course, avoid this problem by blocking the signal
+while scanning the list, but it is much more elegant to guarantee
+correctness by doing things in the right order.
+
+The loop which checks process status avoids examining @code{p->status}
+until it sees that status has been validly stored.  This is to make sure
+that the status cannot change in the middle of accessing it.  Once
+@code{p->have_status} is set, it means that the child process is stopped
+or terminated, and in either case, it cannot stop or terminate again
+until the program has taken notice.  @xref{Atomic Usage}, for more
+information about coping with interruptions during accesses of a
+variable.
+
+Here is another way you can test whether the handler has run since the
+last time you checked.  This technique uses a counter which is never
+changed outside the handler.  Instead of clearing the count, the program
+remembers the previous value and sees whether it has changed since the
+previous check.  The advantage of this method is that different parts of
+the program can check independently, each part checking whether there
+has been a signal since that part last checked.
+
+@smallexample
+sig_atomic_t process_status_change;
+
+sig_atomic_t last_process_status_change;
+
+@dots{}
+@{
+  sig_atomic_t prev = last_process_status_change;
+  last_process_status_change = process_status_change;
+  if (last_process_status_change != prev) @{
+    struct process *p;
+    for (p = process_list; p; p = p->next)
+      if (p->have_status) @{
+        @dots{} @r{Examine @code{p->status}} @dots{}
+      @}
+  @}
+@}
+@end smallexample
+
+@node Nonreentrancy
+@subsection Signal Handling and Nonreentrant Functions
+@cindex restrictions on signal handler functions
+
+Handler functions usually don't do very much.  The best practice is to
+write a handler that does nothing but set an external variable that the
+program checks regularly, and leave all serious work to the program.
+This is best because the handler can be called asynchronously, at
+unpredictable times---perhaps in the middle of a primitive function, or
+even between the beginning and the end of a C operator that requires
+multiple instructions.  The data structures being manipulated might
+therefore be in an inconsistent state when the handler function is
+invoked.  Even copying one @code{int} variable into another can take two
+instructions on most machines.
+
+This means you have to be very careful about what you do in a signal
+handler.
+
+@itemize @bullet
+@item
+@cindex @code{volatile} declarations
+If your handler needs to access any global variables from your program,
+declare those variables @code{volatile}.  This tells the compiler that
+the value of the variable might change asynchronously, and inhibits
+certain optimizations that would be invalidated by such modifications.
+
+@item
+@cindex reentrant functions
+If you call a function in the handler, make sure it is @dfn{reentrant}
+with respect to signals, or else make sure that the signal cannot
+interrupt a call to a related function.
+@end itemize
+
+A function can be non-reentrant if it uses memory that is not on the
+stack.
+
+@itemize @bullet
+@item
+If a function uses a static variable or a global variable, or a
+dynamically-allocated object that it finds for itself, then it is
+non-reentrant and any two calls to the function can interfere.
+
+For example, suppose that the signal handler uses @code{gethostbyname}.
+This function returns its value in a static object, reusing the same
+object each time.  If the signal happens to arrive during a call to
+@code{gethostbyname}, or even after one (while the program is still
+using the value), it will clobber the value that the program asked for.
+
+However, if the program does not use @code{gethostbyname} or any other
+function that returns information in the same object, or if it always
+blocks signals around each use, then you are safe.
+
+There are a large number of library functions that return values in a
+fixed object, always reusing the same object in this fashion, and all of
+them cause the same problem.  Function descriptions in this manual
+always mention this behavior.
+
+@item
+If a function uses and modifies an object that you supply, then it is
+potentially non-reentrant; two calls can interfere if they use the same
+object.
+
+This case arises when you do I/O using streams.  Suppose that the
+signal handler prints a message with @code{fprintf}.  Suppose that the
+program was in the middle of an @code{fprintf} call using the same
+stream when the signal was delivered.  Both the signal handler's message
+and the program's data could be corrupted, because both calls operate on
+the same data structure---the stream itself.
+
+However, if you know that the stream that the handler uses cannot
+possibly be used by the program at a time when signals can arrive, then
+you are safe.  It is no problem if the program uses some other stream.
+
+@item
+On most systems, @code{malloc} and @code{free} are not reentrant,
+because they use a static data structure which records what memory
+blocks are free.  As a result, no library functions that allocate or
+free memory are reentrant.  This includes functions that allocate space
+to store a result.
+
+The best way to avoid the need to allocate memory in a handler is to
+allocate in advance space for signal handlers to use.
+
+The best way to avoid freeing memory in a handler is to flag or record
+the objects to be freed, and have the program check from time to time
+whether anything is waiting to be freed.  But this must be done with
+care, because placing an object on a chain is not atomic, and if it is
+interrupted by another signal handler that does the same thing, you
+could ``lose'' one of the objects.
+
+@ignore
+!!! not true
+In @theglibc{}, @code{malloc} and @code{free} are safe to use in
+signal handlers because they block signals.  As a result, the library
+functions that allocate space for a result are also safe in signal
+handlers.  The obstack allocation functions are safe as long as you
+don't use the same obstack both inside and outside of a signal handler.
+@end ignore
+
+@ignore
+@comment Once we have r_alloc again add this paragraph.
+The relocating allocation functions (@pxref{Relocating Allocator})
+are certainly not safe to use in a signal handler.
+@end ignore
+
+@item
+Any function that modifies @code{errno} is non-reentrant, but you can
+correct for this: in the handler, save the original value of
+@code{errno} and restore it before returning normally.  This prevents
+errors that occur within the signal handler from being confused with
+errors from system calls at the point the program is interrupted to run
+the handler.
+
+This technique is generally applicable; if you want to call in a handler
+a function that modifies a particular object in memory, you can make
+this safe by saving and restoring that object.
+
+@item
+Merely reading from a memory object is safe provided that you can deal
+with any of the values that might appear in the object at a time when
+the signal can be delivered.  Keep in mind that assignment to some data
+types requires more than one instruction, which means that the handler
+could run ``in the middle of'' an assignment to the variable if its type
+is not atomic.  @xref{Atomic Data Access}.
+
+@item
+Merely writing into a memory object is safe as long as a sudden change
+in the value, at any time when the handler might run, will not disturb
+anything.
+@end itemize
+
+@node Atomic Data Access
+@subsection Atomic Data Access and Signal Handling
+
+Whether the data in your application concerns atoms, or mere text, you
+have to be careful about the fact that access to a single datum is not
+necessarily @dfn{atomic}.  This means that it can take more than one
+instruction to read or write a single object.  In such cases, a signal
+handler might be invoked in the middle of reading or writing the object.
+
+There are three ways you can cope with this problem.  You can use data
+types that are always accessed atomically; you can carefully arrange
+that nothing untoward happens if an access is interrupted, or you can
+block all signals around any access that had better not be interrupted
+(@pxref{Blocking Signals}).
+
+@menu
+* 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.
+@end menu
+
+@node Non-atomic Example
+@subsubsection Problems with Non-Atomic Access
+
+Here is an example which shows what can happen if a signal handler runs
+in the middle of modifying a variable.  (Interrupting the reading of a
+variable can also lead to paradoxical results, but here we only show
+writing.)
+
+@smallexample
+#include <signal.h>
+#include <stdio.h>
+
+volatile struct two_words @{ int a, b; @} memory;
+
+void
+handler(int signum)
+@{
+   printf ("%d,%d\n", memory.a, memory.b);
+   alarm (1);
+@}
+
+@group
+int
+main (void)
+@{
+   static struct two_words zeros = @{ 0, 0 @}, ones = @{ 1, 1 @};
+   signal (SIGALRM, handler);
+   memory = zeros;
+   alarm (1);
+   while (1)
+     @{
+       memory = zeros;
+       memory = ones;
+     @}
+@}
+@end group
+@end smallexample
+
+This program fills @code{memory} with zeros, ones, zeros, ones,
+alternating forever; meanwhile, once per second, the alarm signal handler
+prints the current contents.  (Calling @code{printf} in the handler is
+safe in this program because it is certainly not being called outside
+the handler when the signal happens.)
+
+Clearly, this program can print a pair of zeros or a pair of ones.  But
+that's not all it can do!  On most machines, it takes several
+instructions to store a new value in @code{memory}, and the value is
+stored one word at a time.  If the signal is delivered in between these
+instructions, the handler might find that @code{memory.a} is zero and
+@code{memory.b} is one (or vice versa).
+
+On some machines it may be possible to store a new value in
+@code{memory} with just one instruction that cannot be interrupted.  On
+these machines, the handler will always print two zeros or two ones.
+
+@node Atomic Types
+@subsubsection Atomic Types
+
+To avoid uncertainty about interrupting access to a variable, you can
+use a particular data type for which access is always atomic:
+@code{sig_atomic_t}.  Reading and writing this data type is guaranteed
+to happen in a single instruction, so there's no way for a handler to
+run ``in the middle'' of an access.
+
+The type @code{sig_atomic_t} is always an integer data type, but which
+one it is, and how many bits it contains, may vary from machine to
+machine.
+
+@comment signal.h
+@comment ISO
+@deftp {Data Type} sig_atomic_t
+This is an integer data type.  Objects of this type are always accessed
+atomically.
+@end deftp
+
+In practice, you can assume that @code{int} is atomic.
+You can also assume that pointer
+types are atomic; that is very convenient.  Both of these assumptions
+are true on all of the machines that @theglibc{} supports and on
+all POSIX systems we know of.
+@c ??? This might fail on a 386 that uses 64-bit pointers.
+
+@node Atomic Usage
+@subsubsection Atomic Usage Patterns
+
+Certain patterns of access avoid any problem even if an access is
+interrupted.  For example, a flag which is set by the handler, and
+tested and cleared by the main program from time to time, is always safe
+even if access actually requires two instructions.  To show that this is
+so, we must consider each access that could be interrupted, and show
+that there is no problem if it is interrupted.
+
+An interrupt in the middle of testing the flag is safe because either it's
+recognized to be nonzero, in which case the precise value doesn't
+matter, or it will be seen to be nonzero the next time it's tested.
+
+An interrupt in the middle of clearing the flag is no problem because
+either the value ends up zero, which is what happens if a signal comes
+in just before the flag is cleared, or the value ends up nonzero, and
+subsequent events occur as if the signal had come in just after the flag
+was cleared.  As long as the code handles both of these cases properly,
+it can also handle a signal in the middle of clearing the flag.  (This
+is an example of the sort of reasoning you need to do to figure out
+whether non-atomic usage is safe.)
+
+Sometimes you can insure uninterrupted access to one object by
+protecting its use with another object, perhaps one whose type
+guarantees atomicity.  @xref{Merged Signals}, for an example.
+
+@node Interrupted Primitives
+@section Primitives Interrupted by Signals
+
+A signal can arrive and be handled while an I/O primitive such as
+@code{open} or @code{read} is waiting for an I/O device.  If the signal
+handler returns, the system faces the question: what should happen next?
+
+POSIX specifies one approach: make the primitive fail right away.  The
+error code for this kind of failure is @code{EINTR}.  This is flexible,
+but usually inconvenient.  Typically, POSIX applications that use signal
+handlers must check for @code{EINTR} after each library function that
+can return it, in order to try the call again.  Often programmers forget
+to check, which is a common source of error.
+
+@Theglibc{} provides a convenient way to retry a call after a
+temporary failure, with the macro @code{TEMP_FAILURE_RETRY}:
+
+@comment unistd.h
+@comment GNU
+@defmac TEMP_FAILURE_RETRY (@var{expression})
+This macro evaluates @var{expression} once, and examines its value as
+type @code{long int}.  If the value equals @code{-1}, that indicates a
+failure and @code{errno} should be set to show what kind of failure.
+If it fails and reports error code @code{EINTR},
+@code{TEMP_FAILURE_RETRY} evaluates it again, and over and over until
+the result is not a temporary failure.
+
+The value returned by @code{TEMP_FAILURE_RETRY} is whatever value
+@var{expression} produced.
+@end defmac
+
+BSD avoids @code{EINTR} entirely and provides a more convenient
+approach: to restart the interrupted primitive, instead of making it
+fail.  If you choose this approach, you need not be concerned with
+@code{EINTR}.
+
+You can choose either approach with @theglibc{}.  If you use
+@code{sigaction} to establish a signal handler, you can specify how that
+handler should behave.  If you specify the @code{SA_RESTART} flag,
+return from that handler will resume a primitive; otherwise, return from
+that handler will cause @code{EINTR}.  @xref{Flags for Sigaction}.
+
+Another way to specify the choice is with the @code{siginterrupt}
+function.  @xref{BSD Signal Handling}.
+
+When you don't specify with @code{sigaction} or @code{siginterrupt} what
+a particular handler should do, it uses a default choice.  The default
+choice in @theglibc{} is to make primitives fail with @code{EINTR}.
+@cindex EINTR, and restarting interrupted primitives
+@cindex restarting interrupted primitives
+@cindex interrupting primitives
+@cindex primitives, interrupting
+@c !!! want to have @cindex system calls @i{see} primitives [no page #]
+
+The description of each primitive affected by this issue
+lists @code{EINTR} among the error codes it can return.
+
+There is one situation where resumption never happens no matter which
+choice you make: when a data-transfer function such as @code{read} or
+@code{write} is interrupted by a signal after transferring part of the
+data.  In this case, the function returns the number of bytes already
+transferred, indicating partial success.
+
+This might at first appear to cause unreliable behavior on
+record-oriented devices (including datagram sockets; @pxref{Datagrams}),
+where splitting one @code{read} or @code{write} into two would read or
+write two records.  Actually, there is no problem, because interruption
+after a partial transfer cannot happen on such devices; they always
+transfer an entire record in one burst, with no waiting once data
+transfer has started.
+
+@node Generating Signals
+@section Generating Signals
+@cindex sending signals
+@cindex raising signals
+@cindex signals, generating
+
+Besides signals that are generated as a result of a hardware trap or
+interrupt, your program can explicitly send signals to itself or to
+another process.
+
+@menu
+* 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.
+@end menu
+
+@node Signaling Yourself
+@subsection Signaling Yourself
+
+A process can send itself a signal with the @code{raise} function.  This
+function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment ISO
+@deftypefun int raise (int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c raise ok
+@c [posix]
+@c  getpid dup ok
+@c  kill dup ok
+@c [linux]
+@c  syscall(gettid) ok
+@c  syscall(tgkill) ok
+The @code{raise} function sends the signal @var{signum} to the calling
+process.  It returns zero if successful and a nonzero value if it fails.
+About the only reason for failure would be if the value of @var{signum}
+is invalid.
+@end deftypefun
+
+@comment signal.h
+@comment SVID
+@deftypefun int gsignal (int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Aliases raise.
+The @code{gsignal} function does the same thing as @code{raise}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
+One convenient use for @code{raise} is to reproduce the default behavior
+of a signal that you have trapped.  For instance, suppose a user of your
+program types the SUSP character (usually @kbd{C-z}; @pxref{Special
+Characters}) to send it an interactive stop signal
+(@code{SIGTSTP}), and you want to clean up some internal data buffers
+before stopping.  You might set this up like this:
+
+@comment RMS suggested getting rid of the handler for SIGCONT in this function.
+@comment But that would require that the handler for SIGTSTP unblock the
+@comment signal before doing the call to raise.  We haven't covered that
+@comment topic yet, and I don't want to distract from the main point of
+@comment the example with a digression to explain what is going on.  As
+@comment the example is written, the signal that is raise'd will be delivered
+@comment as soon as the SIGTSTP handler returns, which is fine.
+
+@smallexample
+#include <signal.h>
+
+/* @r{When a stop signal arrives, set the action back to the default
+   and then resend the signal after doing cleanup actions.} */
+
+void
+tstp_handler (int sig)
+@{
+  signal (SIGTSTP, SIG_DFL);
+  /* @r{Do cleanup actions here.} */
+  @dots{}
+  raise (SIGTSTP);
+@}
+
+/* @r{When the process is continued again, restore the signal handler.} */
+
+void
+cont_handler (int sig)
+@{
+  signal (SIGCONT, cont_handler);
+  signal (SIGTSTP, tstp_handler);
+@}
+
+@group
+/* @r{Enable both handlers during program initialization.} */
+
+int
+main (void)
+@{
+  signal (SIGCONT, cont_handler);
+  signal (SIGTSTP, tstp_handler);
+  @dots{}
+@}
+@end group
+@end smallexample
+
+@strong{Portability note:} @code{raise} was invented by the @w{ISO C}
+committee.  Older systems may not support it, so using @code{kill} may
+be more portable.  @xref{Signaling Another Process}.
+
+@node Signaling Another Process
+@subsection Signaling Another Process
+
+@cindex killing a process
+The @code{kill} function can be used to send a signal to another process.
+In spite of its name, it can be used for a lot of things other than
+causing a process to terminate.  Some examples of situations where you
+might want to send signals between processes are:
+
+@itemize @bullet
+@item
+A parent process starts a child to perform a task---perhaps having the
+child running an infinite loop---and then terminates the child when the
+task is no longer needed.
+
+@item
+A process executes as part of a group, and needs to terminate or notify
+the other processes in the group when an error or other event occurs.
+
+@item
+Two processes need to synchronize while working together.
+@end itemize
+
+This section assumes that you know a little bit about how processes
+work.  For more information on this subject, see @ref{Processes}.
+
+The @code{kill} function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int kill (pid_t @var{pid}, int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c The hurd implementation is not a critical section, so it's not
+@c immediately obvious that, in case of cancellation, it won't leak
+@c ports or the memory allocated by proc_getpgrppids when pid <= 0.
+@c Since none of these make it AC-Unsafe, I'm leaving them out.
+The @code{kill} function sends the signal @var{signum} to the process
+or process group specified by @var{pid}.  Besides the signals listed in
+@ref{Standard Signals}, @var{signum} can also have a value of zero to
+check the validity of the @var{pid}.
+
+The @var{pid} specifies the process or process group to receive the
+signal:
+
+@table @code
+@item @var{pid} > 0
+The process whose identifier is @var{pid}.
+
+@item @var{pid} == 0
+All processes in the same process group as the sender.
+
+@item @var{pid} < -1
+The process group whose identifier is @minus{}@var{pid}.
+
+@item @var{pid} == -1
+If the process is privileged, send the signal to all processes except
+for some special system processes.  Otherwise, send the signal to all
+processes with the same effective user ID.
+@end table
+
+A process can send a signal to itself with a call like @w{@code{kill
+(getpid(), @var{signum})}}.  If @code{kill} is used by a process to send
+a signal to itself, and the signal is not blocked, then @code{kill}
+delivers at least one signal (which might be some other pending
+unblocked signal instead of the signal @var{signum}) to that process
+before it returns.
+
+The return value from @code{kill} is zero if the signal can be sent
+successfully.  Otherwise, no signal is sent, and a value of @code{-1} is
+returned.  If @var{pid} specifies sending a signal to several processes,
+@code{kill} succeeds if it can send the signal to at least one of them.
+There's no way you can tell which of the processes got the signal
+or whether all of them did.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument is an invalid or unsupported number.
+
+@item EPERM
+You do not have the privilege to send a signal to the process or any of
+the processes in the process group named by @var{pid}.
+
+@item ESRCH
+The @var{pid} argument does not refer to an existing process or group.
+@end table
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int killpg (int @var{pgid}, int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Calls kill with -pgid.
+This is similar to @code{kill}, but sends signal @var{signum} to the
+process group @var{pgid}.  This function is provided for compatibility
+with BSD; using @code{kill} to do this is more portable.
+@end deftypefun
+
+As a simple example of @code{kill}, the call @w{@code{kill (getpid (),
+@var{sig})}} has the same effect as @w{@code{raise (@var{sig})}}.
+
+@node Permission for kill
+@subsection Permission for using @code{kill}
+
+There are restrictions that prevent you from using @code{kill} to send
+signals to any random process.  These are intended to prevent antisocial
+behavior such as arbitrarily killing off processes belonging to another
+user.  In typical use, @code{kill} is used to pass signals between
+parent, child, and sibling processes, and in these situations you
+normally do have permission to send signals.  The only common exception
+is when you run a setuid program in a child process; if the program
+changes its real UID as well as its effective UID, you may not have
+permission to send a signal.  The @code{su} program does this.
+
+Whether a process has permission to send a signal to another process
+is determined by the user IDs of the two processes.  This concept is
+discussed in detail in @ref{Process Persona}.
+
+Generally, for a process to be able to send a signal to another process,
+either the sending process must belong to a privileged user (like
+@samp{root}), or the real or effective user ID of the sending process
+must match the real or effective user ID of the receiving process.  If
+the receiving process has changed its effective user ID from the
+set-user-ID mode bit on its process image file, then the owner of the
+process image file is used in place of its current effective user ID.
+In some implementations, a parent process might be able to send signals
+to a child process even if the user ID's don't match, and other
+implementations might enforce other restrictions.
+
+The @code{SIGCONT} signal is a special case.  It can be sent if the
+sender is part of the same session as the receiver, regardless of
+user IDs.
+
+@node Kill Example
+@subsection Using @code{kill} for Communication
+@cindex interprocess communication, with signals
+Here is a longer example showing how signals can be used for
+interprocess communication.  This is what the @code{SIGUSR1} and
+@code{SIGUSR2} signals are provided for.  Since these signals are fatal
+by default, the process that is supposed to receive them must trap them
+through @code{signal} or @code{sigaction}.
+
+In this example, a parent process forks a child process and then waits
+for the child to complete its initialization.  The child process tells
+the parent when it is ready by sending it a @code{SIGUSR1} signal, using
+the @code{kill} function.
+
+@smallexample
+@include sigusr.c.texi
+@end smallexample
+
+This example uses a busy wait, which is bad, because it wastes CPU
+cycles that other programs could otherwise use.  It is better to ask the
+system to wait until the signal arrives.  See the example in
+@ref{Waiting for a Signal}.
+
+@node Blocking Signals
+@section Blocking Signals
+@cindex blocking signals
+
+Blocking a signal means telling the operating system to hold it and
+deliver it later.  Generally, a program does not block signals
+indefinitely---it might as well ignore them by setting their actions to
+@code{SIG_IGN}.  But it is useful to block signals briefly, to prevent
+them from interrupting sensitive operations.  For instance:
+
+@itemize @bullet
+@item
+You can use the @code{sigprocmask} function to block signals while you
+modify global variables that are also modified by the handlers for these
+signals.
+
+@item
+You can set @code{sa_mask} in your @code{sigaction} call to block
+certain signals while a particular signal handler runs.  This way, the
+signal handler can run without being interrupted itself by signals.
+@end itemize
+
+@menu
+* 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.
+@end menu
+
+@node Why Block
+@subsection Why Blocking Signals is Useful
+
+Temporary blocking of signals with @code{sigprocmask} gives you a way to
+prevent interrupts during critical parts of your code.  If signals
+arrive in that part of the program, they are delivered later, after you
+unblock them.
+
+One example where this is useful is for sharing data between a signal
+handler and the rest of the program.  If the type of the data is not
+@code{sig_atomic_t} (@pxref{Atomic Data Access}), then the signal
+handler could run when the rest of the program has only half finished
+reading or writing the data.  This would lead to confusing consequences.
+
+To make the program reliable, you can prevent the signal handler from
+running while the rest of the program is examining or modifying that
+data---by blocking the appropriate signal around the parts of the
+program that touch the data.
+
+Blocking signals is also necessary when you want to perform a certain
+action only if a signal has not arrived.  Suppose that the handler for
+the signal sets a flag of type @code{sig_atomic_t}; you would like to
+test the flag and perform the action if the flag is not set.  This is
+unreliable.  Suppose the signal is delivered immediately after you test
+the flag, but before the consequent action: then the program will
+perform the action even though the signal has arrived.
+
+The only way to test reliably for whether a signal has yet arrived is to
+test while the signal is blocked.
+
+@node Signal Sets
+@subsection Signal Sets
+
+All of the signal blocking functions use a data structure called a
+@dfn{signal set} to specify what signals are affected.  Thus, every
+activity involves two stages: creating the signal set, and then passing
+it as an argument to a library function.
+@cindex signal set
+
+These facilities are declared in the header file @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftp {Data Type} sigset_t
+The @code{sigset_t} data type is used to represent a signal set.
+Internally, it may be implemented as either an integer or structure
+type.
+
+For portability, use only the functions described in this section to
+initialize, change, and retrieve information from @code{sigset_t}
+objects---don't try to manipulate them directly.
+@end deftp
+
+There are two ways to initialize a signal set.  You can initially
+specify it to be empty with @code{sigemptyset} and then add specified
+signals individually.  Or you can specify it to be full with
+@code{sigfillset} and then delete specified signals individually.
+
+You must always initialize the signal set with one of these two
+functions before using it in any other way.  Don't try to set all the
+signals explicitly because the @code{sigset_t} object might include some
+other information (like a version field) that needs to be initialized as
+well.  (In addition, it's not wise to put into your program an
+assumption that the system has no signals aside from the ones you know
+about.)
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigemptyset (sigset_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Just memsets all of set to zero.
+This function initializes the signal set @var{set} to exclude all of the
+defined signals.  It always returns @code{0}.
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigfillset (sigset_t *@var{set})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function initializes the signal set @var{set} to include
+all of the defined signals.  Again, the return value is @code{0}.
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function adds the signal @var{signum} to the signal set @var{set}.
+All @code{sigaddset} does is modify @var{set}; it does not block or
+unblock any signals.
+
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument doesn't specify a valid signal.
+@end table
+@end deftypefun
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function removes the signal @var{signum} from the signal set
+@var{set}.  All @code{sigdelset} does is modify @var{set}; it does not
+block or unblock any signals.  The return value and error conditions are
+the same as for @code{sigaddset}.
+@end deftypefun
+
+Finally, there is a function to test what signals are in a signal set:
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{sigismember} function tests whether the signal @var{signum} is
+a member of the signal set @var{set}.  It returns @code{1} if the signal
+is in the set, @code{0} if not, and @code{-1} if there is an error.
+
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EINVAL
+The @var{signum} argument doesn't specify a valid signal.
+@end table
+@end deftypefun
+
+@node Process Signal Mask
+@subsection Process Signal Mask
+@cindex signal mask
+@cindex process signal mask
+
+The collection of signals that are currently blocked is called the
+@dfn{signal mask}.  Each process has its own signal mask.  When you
+create a new process (@pxref{Creating a Process}), it inherits its
+parent's mask.  You can block or unblock signals with total flexibility
+by modifying the signal mask.
+
+The prototype for the @code{sigprocmask} function is in @file{signal.h}.
+@pindex signal.h
+
+Note that you must not use @code{sigprocmask} in multi-threaded processes,
+because each thread has its own signal mask and there is no single process
+signal mask.  According to POSIX, the behavior of @code{sigprocmask} in a
+multi-threaded process is ``unspecified''.
+Instead, use @code{pthread_sigmask}.
+@ifset linuxthreads
+@xref{Threads and Signal Handling}.
+@end ifset
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigprocmask (int @var{how}, const sigset_t *restrict @var{set}, sigset_t *restrict @var{oldset})
+@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/bsd(SIG_UNBLOCK)}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c This takes the hurd_self_sigstate-returned object's lock on HURD.  On
+@c BSD, SIG_UNBLOCK is emulated with two sigblock calls, which
+@c introduces a race window.
+The @code{sigprocmask} function is used to examine or change the calling
+process's signal mask.  The @var{how} argument determines how the signal
+mask is changed, and must be one of the following values:
+
+@table @code
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_BLOCK
+@item SIG_BLOCK
+Block the signals in @code{set}---add them to the existing mask.  In
+other words, the new mask is the union of the existing mask and
+@var{set}.
+
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_UNBLOCK
+@item SIG_UNBLOCK
+Unblock the signals in @var{set}---remove them from the existing mask.
+
+@comment signal.h
+@comment POSIX.1
+@vindex SIG_SETMASK
+@item SIG_SETMASK
+Use @var{set} for the mask; ignore the previous value of the mask.
+@end table
+
+The last argument, @var{oldset}, is used to return information about the
+old process signal mask.  If you just want to change the mask without
+looking at it, pass a null pointer as the @var{oldset} argument.
+Similarly, if you want to know what's in the mask without changing it,
+pass a null pointer for @var{set} (in this case the @var{how} argument
+is not significant).  The @var{oldset} argument is often used to
+remember the previous signal mask in order to restore it later.  (Since
+the signal mask is inherited over @code{fork} and @code{exec} calls, you
+can't predict what its contents are when your program starts running.)
+
+If invoking @code{sigprocmask} causes any pending signals to be
+unblocked, at least one of those signals is delivered to the process
+before @code{sigprocmask} returns.  The order in which pending signals
+are delivered is not specified, but you can control the order explicitly
+by making multiple @code{sigprocmask} calls to unblock various signals
+one at a time.
+
+The @code{sigprocmask} function returns @code{0} if successful, and @code{-1}
+to indicate an error.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EINVAL
+The @var{how} argument is invalid.
+@end table
+
+You can't block the @code{SIGKILL} and @code{SIGSTOP} signals, but
+if the signal set includes these, @code{sigprocmask} just ignores
+them instead of returning an error status.
+
+Remember, too, that blocking program error signals such as @code{SIGFPE}
+leads to undesirable results for signals generated by an actual program
+error (as opposed to signals sent with @code{raise} or @code{kill}).
+This is because your program may be too broken to be able to continue
+executing to a point where the signal is unblocked again.
+@xref{Program Error Signals}.
+@end deftypefun
+
+@node Testing for Delivery
+@subsection Blocking to Test for Delivery of a Signal
+
+Now for a simple example.  Suppose you establish a handler for
+@code{SIGALRM} signals that sets a flag whenever a signal arrives, and
+your main program checks this flag from time to time and then resets it.
+You can prevent additional @code{SIGALRM} signals from arriving in the
+meantime by wrapping the critical part of the code with calls to
+@code{sigprocmask}, like this:
+
+@smallexample
+/* @r{This variable is set by the SIGALRM signal handler.} */
+volatile sig_atomic_t flag = 0;
+
+int
+main (void)
+@{
+  sigset_t block_alarm;
+
+  @dots{}
+
+  /* @r{Initialize the signal mask.} */
+  sigemptyset (&block_alarm);
+  sigaddset (&block_alarm, SIGALRM);
+
+@group
+  while (1)
+    @{
+      /* @r{Check if a signal has arrived; if so, reset the flag.} */
+      sigprocmask (SIG_BLOCK, &block_alarm, NULL);
+      if (flag)
+        @{
+          @var{actions-if-not-arrived}
+          flag = 0;
+        @}
+      sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
+
+      @dots{}
+    @}
+@}
+@end group
+@end smallexample
+
+@node Blocking for Handler
+@subsection Blocking Signals for a Handler
+@cindex blocking signals, in a handler
+
+When a signal handler is invoked, you usually want it to be able to
+finish without being interrupted by another signal.  From the moment the
+handler starts until the moment it finishes, you must block signals that
+might confuse it or corrupt its data.
+
+When a handler function is invoked on a signal, that signal is
+automatically blocked (in addition to any other signals that are already
+in the process's signal mask) during the time the handler is running.
+If you set up a handler for @code{SIGTSTP}, for instance, then the
+arrival of that signal forces further @code{SIGTSTP} signals to wait
+during the execution of the handler.
+
+However, by default, other kinds of signals are not blocked; they can
+arrive during handler execution.
+
+The reliable way to block other kinds of signals during the execution of
+the handler is to use the @code{sa_mask} member of the @code{sigaction}
+structure.
+
+Here is an example:
+
+@smallexample
+#include <signal.h>
+#include <stddef.h>
+
+void catch_stop ();
+
+void
+install_handler (void)
+@{
+  struct sigaction setup_action;
+  sigset_t block_mask;
+
+  sigemptyset (&block_mask);
+  /* @r{Block other terminal-generated signals while handler runs.} */
+  sigaddset (&block_mask, SIGINT);
+  sigaddset (&block_mask, SIGQUIT);
+  setup_action.sa_handler = catch_stop;
+  setup_action.sa_mask = block_mask;
+  setup_action.sa_flags = 0;
+  sigaction (SIGTSTP, &setup_action, NULL);
+@}
+@end smallexample
+
+This is more reliable than blocking the other signals explicitly in the
+code for the handler.  If you block signals explicitly in the handler,
+you can't avoid at least a short interval at the beginning of the
+handler where they are not yet blocked.
+
+You cannot remove signals from the process's current mask using this
+mechanism.  However, you can make calls to @code{sigprocmask} within
+your handler to block or unblock signals as you wish.
+
+In any case, when the handler returns, the system restores the mask that
+was in place before the handler was entered.  If any signals that become
+unblocked by this restoration are pending, the process will receive
+those signals immediately, before returning to the code that was
+interrupted.
+
+@node Checking for Pending Signals
+@subsection Checking for Pending Signals
+@cindex pending signals, checking for
+@cindex blocked signals, checking for
+@cindex checking for pending signals
+
+You can find out which signals are pending at any time by calling
+@code{sigpending}.  This function is declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigpending (sigset_t *@var{set})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c Direct rt_sigpending syscall on most systems.  On hurd, calls
+@c hurd_self_sigstate, it copies the sigstate's pending while holding
+@c its lock.
+The @code{sigpending} function stores information about pending signals
+in @var{set}.  If there is a pending signal that is blocked from
+delivery, then that signal is a member of the returned set.  (You can
+test whether a particular signal is a member of this set using
+@code{sigismember}; see @ref{Signal Sets}.)
+
+The return value is @code{0} if successful, and @code{-1} on failure.
+@end deftypefun
+
+Testing whether a signal is pending is not often useful.  Testing when
+that signal is not blocked is almost certainly bad design.
+
+Here is an example.
+
+@smallexample
+#include <signal.h>
+#include <stddef.h>
+
+sigset_t base_mask, waiting_mask;
+
+sigemptyset (&base_mask);
+sigaddset (&base_mask, SIGINT);
+sigaddset (&base_mask, SIGTSTP);
+
+/* @r{Block user interrupts while doing other processing.} */
+sigprocmask (SIG_SETMASK, &base_mask, NULL);
+@dots{}
+
+/* @r{After a while, check to see whether any signals are pending.} */
+sigpending (&waiting_mask);
+if (sigismember (&waiting_mask, SIGINT)) @{
+  /* @r{User has tried to kill the process.} */
+@}
+else if (sigismember (&waiting_mask, SIGTSTP)) @{
+  /* @r{User has tried to stop the process.} */
+@}
+@end smallexample
+
+Remember that if there is a particular signal pending for your process,
+additional signals of that same type that arrive in the meantime might
+be discarded.  For example, if a @code{SIGINT} signal is pending when
+another @code{SIGINT} signal arrives, your program will probably only
+see one of them when you unblock this signal.
+
+@strong{Portability Note:} The @code{sigpending} function is new in
+POSIX.1.  Older systems have no equivalent facility.
+
+@node Remembering a Signal
+@subsection Remembering a Signal to Act On Later
+
+Instead of blocking a signal using the library facilities, you can get
+almost the same results by making the handler set a flag to be tested
+later, when you ``unblock''.  Here is an example:
+
+@smallexample
+/* @r{If this flag is nonzero, don't handle the signal right away.} */
+volatile sig_atomic_t signal_pending;
+
+/* @r{This is nonzero if a signal arrived and was not handled.} */
+volatile sig_atomic_t defer_signal;
+
+void
+handler (int signum)
+@{
+  if (defer_signal)
+    signal_pending = signum;
+  else
+    @dots{} /* @r{``Really'' handle the signal.} */
+@}
+
+@dots{}
+
+void
+update_mumble (int frob)
+@{
+  /* @r{Prevent signals from having immediate effect.} */
+  defer_signal++;
+  /* @r{Now update @code{mumble}, without worrying about interruption.} */
+  mumble.a = 1;
+  mumble.b = hack ();
+  mumble.c = frob;
+  /* @r{We have updated @code{mumble}.  Handle any signal that came in.} */
+  defer_signal--;
+  if (defer_signal == 0 && signal_pending != 0)
+    raise (signal_pending);
+@}
+@end smallexample
+
+Note how the particular signal that arrives is stored in
+@code{signal_pending}.  That way, we can handle several types of
+inconvenient signals with the same mechanism.
+
+We increment and decrement @code{defer_signal} so that nested critical
+sections will work properly; thus, if @code{update_mumble} were called
+with @code{signal_pending} already nonzero, signals would be deferred
+not only within @code{update_mumble}, but also within the caller.  This
+is also why we do not check @code{signal_pending} if @code{defer_signal}
+is still nonzero.
+
+The incrementing and decrementing of @code{defer_signal} each require more
+than one instruction; it is possible for a signal to happen in the
+middle.  But that does not cause any problem.  If the signal happens
+early enough to see the value from before the increment or decrement,
+that is equivalent to a signal which came before the beginning of the
+increment or decrement, which is a case that works properly.
+
+It is absolutely vital to decrement @code{defer_signal} before testing
+@code{signal_pending}, because this avoids a subtle bug.  If we did
+these things in the other order, like this,
+
+@smallexample
+  if (defer_signal == 1 && signal_pending != 0)
+    raise (signal_pending);
+  defer_signal--;
+@end smallexample
+
+@noindent
+then a signal arriving in between the @code{if} statement and the decrement
+would be effectively ``lost'' for an indefinite amount of time.  The
+handler would merely set @code{defer_signal}, but the program having
+already tested this variable, it would not test the variable again.
+
+@cindex timing error in signal handling
+Bugs like these are called @dfn{timing errors}.  They are especially bad
+because they happen only rarely and are nearly impossible to reproduce.
+You can't expect to find them with a debugger as you would find a
+reproducible bug.  So it is worth being especially careful to avoid
+them.
+
+(You would not be tempted to write the code in this order, given the use
+of @code{defer_signal} as a counter which must be tested along with
+@code{signal_pending}.  After all, testing for zero is cleaner than
+testing for one.  But if you did not use @code{defer_signal} as a
+counter, and gave it values of zero and one only, then either order
+might seem equally simple.  This is a further advantage of using a
+counter for @code{defer_signal}: it will reduce the chance you will
+write the code in the wrong order and create a subtle bug.)
+
+@node Waiting for a Signal
+@section Waiting for a Signal
+@cindex waiting for a signal
+@cindex @code{pause} function
+
+If your program is driven by external events, or uses signals for
+synchronization, then when it has nothing to do it should probably wait
+until a signal arrives.
+
+@menu
+* 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.
+@end menu
+
+@node Using Pause
+@subsection Using @code{pause}
+
+The simple way to wait until a signal arrives is to call @code{pause}.
+Please read about its disadvantages, in the following section, before
+you use it.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int pause (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c  The signal mask read by sigprocmask may be overridden by another
+@c  thread or by a signal handler before we call sigsuspend.  Is this a
+@c  safety issue?  Probably not.
+@c pause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+@c [ports/linux/generic]
+@c  syscall_pause ok
+@c [posix]
+@c  sigemptyset dup ok
+@c  sigprocmask(SIG_BLOCK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
+@c  sigsuspend dup @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+The @code{pause} function suspends program execution until a signal
+arrives whose action is either to execute a handler function, or to
+terminate the process.
+
+If the signal causes a handler function to be executed, then
+@code{pause} returns.  This is considered an unsuccessful return (since
+``successful'' behavior would be to suspend the program forever), so the
+return value is @code{-1}.  Even if you specify that other primitives
+should resume when a system handler returns (@pxref{Interrupted
+Primitives}), this has no effect on @code{pause}; it always fails when a
+signal is handled.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINTR
+The function was interrupted by delivery of a signal.
+@end table
+
+If the signal causes program termination, @code{pause} doesn't return
+(obviously).
+
+This function is a cancellation point in multithreaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{pause} is
+called.  If the thread gets cancelled these resources stay allocated
+until the program ends.  To avoid this calls to @code{pause} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{pause} function is declared in  @file{unistd.h}.
+@end deftypefun
+
+@node Pause Problems
+@subsection Problems with @code{pause}
+
+The simplicity of @code{pause} can conceal serious timing errors that
+can make a program hang mysteriously.
+
+It is safe to use @code{pause} if the real work of your program is done
+by the signal handlers themselves, and the ``main program'' does nothing
+but call @code{pause}.  Each time a signal is delivered, the handler
+will do the next batch of work that is to be done, and then return, so
+that the main loop of the program can call @code{pause} again.
+
+You can't safely use @code{pause} to wait until one more signal arrives,
+and then resume real work.  Even if you arrange for the signal handler
+to cooperate by setting a flag, you still can't use @code{pause}
+reliably.  Here is an example of this problem:
+
+@smallexample
+/* @r{@code{usr_interrupt} is set by the signal handler.}  */
+if (!usr_interrupt)
+  pause ();
+
+/* @r{Do work once the signal arrives.}  */
+@dots{}
+@end smallexample
+
+@noindent
+This has a bug: the signal could arrive after the variable
+@code{usr_interrupt} is checked, but before the call to @code{pause}.
+If no further signals arrive, the process would never wake up again.
+
+You can put an upper limit on the excess waiting by using @code{sleep}
+in a loop, instead of using @code{pause}.  (@xref{Sleeping}, for more
+about @code{sleep}.)  Here is what this looks like:
+
+@smallexample
+/* @r{@code{usr_interrupt} is set by the signal handler.}
+while (!usr_interrupt)
+  sleep (1);
+
+/* @r{Do work once the signal arrives.}  */
+@dots{}
+@end smallexample
+
+For some purposes, that is good enough.  But with a little more
+complexity, you can wait reliably until a particular signal handler is
+run, using @code{sigsuspend}.
+@ifinfo
+@xref{Sigsuspend}.
+@end ifinfo
+
+@node Sigsuspend
+@subsection Using @code{sigsuspend}
+
+The clean and reliable way to wait for a signal to arrive is to block it
+and then use @code{sigsuspend}.  By using @code{sigsuspend} in a loop,
+you can wait for certain kinds of signals, while letting other kinds of
+signals be handled by their handlers.
+
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigsuspend (const sigset_t *@var{set})
+@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c sigsuspend @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+@c [posix] @mtasurace:sigprocmask/!bsd!linux
+@c   saving and restoring the procmask is racy
+@c  sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
+@c  pause @asulock/hurd @aculock/hurd
+@c [bsd]
+@c  sigismember dup ok
+@c  sigmask dup ok
+@c  sigpause dup ok [no @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd]
+@c [linux]
+@c  do_sigsuspend ok
+This function replaces the process's signal mask with @var{set} and then
+suspends the process until a signal is delivered whose action is either
+to terminate the process or invoke a signal handling function.  In other
+words, the program is effectively suspended until one of the signals that
+is not a member of @var{set} arrives.
+
+If the process is woken up by delivery of a signal that invokes a handler
+function, and the handler function returns, then @code{sigsuspend} also
+returns.
+
+The mask remains @var{set} only as long as @code{sigsuspend} is waiting.
+The function @code{sigsuspend} always restores the previous signal mask
+when it returns.
+
+The return value and error conditions are the same as for @code{pause}.
+@end deftypefun
+
+With @code{sigsuspend}, you can replace the @code{pause} or @code{sleep}
+loop in the previous section with something completely reliable:
+
+@smallexample
+sigset_t mask, oldmask;
+
+@dots{}
+
+/* @r{Set up the mask of signals to temporarily block.} */
+sigemptyset (&mask);
+sigaddset (&mask, SIGUSR1);
+
+@dots{}
+
+/* @r{Wait for a signal to arrive.} */
+sigprocmask (SIG_BLOCK, &mask, &oldmask);
+while (!usr_interrupt)
+  sigsuspend (&oldmask);
+sigprocmask (SIG_UNBLOCK, &mask, NULL);
+@end smallexample
+
+This last piece of code is a little tricky.  The key point to remember
+here is that when @code{sigsuspend} returns, it resets the process's
+signal mask to the original value, the value from before the call to
+@code{sigsuspend}---in this case, the @code{SIGUSR1} signal is once
+again blocked.  The second call to @code{sigprocmask} is
+necessary to explicitly unblock this signal.
+
+One other point: you may be wondering why the @code{while} loop is
+necessary at all, since the program is apparently only waiting for one
+@code{SIGUSR1} signal.  The answer is that the mask passed to
+@code{sigsuspend} permits the process to be woken up by the delivery of
+other kinds of signals, as well---for example, job control signals.  If
+the process is woken up by a signal that doesn't set
+@code{usr_interrupt}, it just suspends itself again until the ``right''
+kind of signal eventually arrives.
+
+This technique takes a few more lines of preparation, but that is needed
+just once for each kind of wait criterion you want to use.  The code
+that actually waits is just four lines.
+
+@node Signal Stack
+@section Using a Separate Signal Stack
+
+A signal stack is a special area of memory to be used as the execution
+stack during signal handlers.  It should be fairly large, to avoid any
+danger that it will overflow in turn; the macro @code{SIGSTKSZ} is
+defined to a canonical size for signal stacks.  You can use
+@code{malloc} to allocate the space for the stack.  Then call
+@code{sigaltstack} or @code{sigstack} to tell the system to use that
+space for the signal stack.
+
+You don't need to write signal handlers differently in order to use a
+signal stack.  Switching from one stack to the other happens
+automatically.  (Some non-GNU debuggers on some machines may get
+confused if you examine a stack trace while a handler that uses the
+signal stack is running.)
+
+There are two interfaces for telling the system to use a separate signal
+stack.  @code{sigstack} is the older interface, which comes from 4.2
+BSD.  @code{sigaltstack} is the newer interface, and comes from 4.4
+BSD.  The @code{sigaltstack} interface has the advantage that it does
+not require your program to know which direction the stack grows, which
+depends on the specific machine and operating system.
+
+@comment signal.h
+@comment XPG
+@deftp {Data Type} stack_t
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This points to the base of the signal stack.
+
+@item size_t ss_size
+This is the size (in bytes) of the signal stack which @samp{ss_sp} points to.
+You should set this to however much space you allocated for the stack.
+
+There are two macros defined in @file{signal.h} that you should use in
+calculating this size:
+
+@vtable @code
+@item SIGSTKSZ
+This is the canonical size for a signal stack.  It is judged to be
+sufficient for normal uses.
+
+@item MINSIGSTKSZ
+This is the amount of signal stack space the operating system needs just
+to implement signal delivery.  The size of a signal stack @strong{must}
+be greater than this.
+
+For most cases, just using @code{SIGSTKSZ} for @code{ss_size} is
+sufficient.  But if you know how much stack space your program's signal
+handlers will need, you may want to use a different size.  In this case,
+you should allocate @code{MINSIGSTKSZ} additional bytes for the signal
+stack and increase @code{ss_size} accordingly.
+@end vtable
+
+@item int ss_flags
+This field contains the bitwise @sc{or} of these flags:
+
+@vtable @code
+@item SS_DISABLE
+This tells the system that it should not use the signal stack.
+
+@item SS_ONSTACK
+This is set by the system, and indicates that the signal stack is
+currently in use.  If this bit is not set, then signals will be
+delivered on the normal user stack.
+@end vtable
+@end table
+@end deftp
+
+@comment signal.h
+@comment XPG
+@deftypefun int sigaltstack (const stack_t *restrict @var{stack}, stack_t *restrict @var{oldstack})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c Syscall on Linux and BSD; the HURD implementation takes a lock on
+@c the hurd_self_sigstate-returned struct.
+The @code{sigaltstack} function specifies an alternate stack for use
+during signal handling.  When a signal is received by the process and
+its action indicates that the signal stack is used, the system arranges
+a switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.  If
+@code{sigaltstack} fails, it sets @code{errno} to one of these values:
+
+@table @code
+@item EINVAL
+You tried to disable a stack that was in fact currently in use.
+
+@item ENOMEM
+The size of the alternate stack was too small.
+It must be greater than @code{MINSIGSTKSZ}.
+@end table
+@end deftypefun
+
+Here is the older @code{sigstack} interface.  You should use
+@code{sigaltstack} instead on systems that have it.
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigstack}
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This is the stack pointer.  If the stack grows downwards on your
+machine, this should point to the top of the area you allocated.  If the
+stack grows upwards, it should point to the bottom.
+
+@item int ss_onstack
+This field is true if the process is currently using this stack.
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigstack (struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c Lossy and dangerous (no size limit) wrapper for sigaltstack.
+The @code{sigstack} function specifies an alternate stack for use during
+signal handling.  When a signal is received by the process and its
+action indicates that the signal stack is used, the system arranges a
+switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.
+@end deftypefun
+
+@node BSD Signal Handling
+@section BSD Signal Handling
+
+This section describes alternative signal handling functions derived
+from BSD Unix.  These facilities were an advance, in their time; today,
+they are mostly obsolete, and supported mainly for compatibility with
+BSD Unix.
+
+There are many similarities between the BSD and POSIX signal handling
+facilities, because the POSIX facilities were inspired by the BSD
+facilities.  Besides having different names for all the functions to
+avoid conflicts, the main difference between the two is that BSD Unix
+represents signal masks as an @code{int} bit mask, rather than as a
+@code{sigset_t} object.
+
+The BSD facilities are declared in @file{signal.h}.
+@pindex signal.h
+
+@comment signal.h
+@comment XPG
+@deftypefun int siginterrupt (int @var{signum}, int @var{failflag})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtssigintr{}}}@asunsafe{}@acunsafe{@acucorrupt{}}}
+@c This calls sigaction twice, once to get the current sigaction for the
+@c specified signal, another to apply the flags change.  This could
+@c override the effects of a concurrent sigaction call.  It also
+@c modifies without any guards the global _sigintr variable, that
+@c bsd_signal reads from, and it may leave _sigintr modified without
+@c overriding the active handler if cancelled between the two
+@c operations.
+This function specifies which approach to use when certain primitives
+are interrupted by handling signal @var{signum}.  If @var{failflag} is
+false, signal @var{signum} restarts primitives.  If @var{failflag} is
+true, handling @var{signum} causes these primitives to fail with error
+code @code{EINTR}.  @xref{Interrupted Primitives}.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefn Macro int sigmask (int @var{signum})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This just shifts signum.
+This macro returns a signal mask that has the bit for signal @var{signum}
+set.  You can bitwise-OR the results of several calls to @code{sigmask}
+together to specify more than one signal.  For example,
+
+@smallexample
+(sigmask (SIGTSTP) | sigmask (SIGSTOP)
+ | sigmask (SIGTTIN) | sigmask (SIGTTOU))
+@end smallexample
+
+@noindent
+specifies a mask that includes all the job-control stop signals.
+@end deftypefn
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigblock (int @var{mask})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c On most POSIX systems, this is a wrapper for sigprocmask(SIG_BLOCK).
+@c The exception are BSD systems other than 4.4, where it is a syscall.
+@c sigblock @asulock/hurd @aculock/hurd
+@c  sigprocmask(SIG_BLOCK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
+This function is equivalent to @code{sigprocmask} (@pxref{Process Signal
+Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
+signals specified by @var{mask} to the calling process's set of blocked
+signals.  The return value is the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigsetmask (int @var{mask})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c On most POSIX systems, this is a wrapper for sigprocmask(SIG_SETMASK).
+@c The exception are BSD systems other than 4.4, where it is a syscall.
+@c sigsetmask @asulock/hurd @aculock/hurd
+@c  sigprocmask(SIG_SETMASK) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
+This function equivalent to @code{sigprocmask} (@pxref{Process
+Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets
+the calling process's signal mask to @var{mask}.  The return value is
+the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigpause (int @var{mask})
+@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask/!bsd!linux}}@asunsafe{@asulock{/hurd}}@acunsafe{@aculock{/hurd}}}
+@c sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+@c [posix]
+@c  __sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+@c   do_sigpause @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+@c    sigprocmask(0) dup @asulock/hurd @aculock/hurd [no @mtasurace:sigprocmask/bsd(SIG_UNBLOCK)]
+@c    sigdelset dup ok
+@c    sigset_set_old_mask dup ok
+@c    sigsuspend dup @mtasurace:sigprocmask/!bsd!linux @asulock/hurd @aculock/hurd
+This function is the equivalent of @code{sigsuspend} (@pxref{Waiting
+for a Signal}):  it sets the calling process's signal mask to @var{mask},
+and waits for a signal to arrive.  On return the previous set of blocked
+signals is restored.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/socket.texi b/ap/libc/glibc/glibc-2.23/manual/socket.texi
new file mode 100644
index 0000000..1d9d527
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/socket.texi
@@ -0,0 +1,3770 @@
+@node Sockets, Low-Level Terminal Interface, Pipes and FIFOs, Top
+@c %MENU% A more complicated IPC mechanism, with networking support
+@chapter Sockets
+
+This chapter describes the GNU facilities for interprocess
+communication using sockets.
+
+@cindex socket
+@cindex interprocess communication, with sockets
+A @dfn{socket} is a generalized interprocess communication channel.
+Like a pipe, a socket is represented as a file descriptor.  Unlike pipes
+sockets support communication between unrelated processes, and even
+between processes running on different machines that communicate over a
+network.  Sockets are the primary means of communicating with other
+machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the
+other familiar network programs use sockets.
+
+Not all operating systems support sockets.  In @theglibc{}, the
+header file @file{sys/socket.h} exists regardless of the operating
+system, and the socket functions always exist, but if the system does
+not really support sockets these functions always fail.
+
+@strong{Incomplete:} We do not currently document the facilities for
+broadcast messages or for configuring Internet interfaces.  The
+reentrant functions and some newer functions that are related to IPv6
+aren't documented either so far.
+
+@menu
+* Socket Concepts::	Basic concepts you need to know about.
+* Communication Styles::Stream communication, datagrams and other styles.
+* Socket Addresses::	How socket names (``addresses'') work.
+* Interface Naming::	Identifying specific network interfaces.
+* Local Namespace::	Details about the local namespace.
+* Internet Namespace::	Details about the Internet namespace.
+* Misc Namespaces::	Other namespaces not documented fully here.
+* Open/Close Sockets::  Creating sockets and destroying them.
+* Connections::		Operations on sockets with connection state.
+* Datagrams::		Operations on datagram sockets.
+* Inetd::		Inetd is a daemon that starts servers on request.
+			   The most convenient way to write a server
+			   is to make it work with Inetd.
+* Socket Options::	Miscellaneous low-level socket options.
+* Networks Database::   Accessing the database of network names.
+@end menu
+
+@node Socket Concepts
+@section Socket Concepts
+
+@cindex communication style (of a socket)
+@cindex style of communication (of a socket)
+When you create a socket, you must specify the style of communication
+you want to use and the type of protocol that should implement it.
+The @dfn{communication style} of a socket defines the user-level
+semantics of sending and receiving data on the socket.  Choosing a
+communication style specifies the answers to questions such as these:
+
+@itemize @bullet
+@item
+@cindex packet
+@cindex byte stream
+@cindex stream (sockets)
+@strong{What are the units of data transmission?}  Some communication
+styles regard the data as a sequence of bytes with no larger
+structure; others group the bytes into records (which are known in
+this context as @dfn{packets}).
+
+@item
+@cindex loss of data on sockets
+@cindex data loss on sockets
+@strong{Can data be lost during normal operation?}  Some communication
+styles guarantee that all the data sent arrives in the order it was
+sent (barring system or network crashes); other styles occasionally
+lose data as a normal part of operation, and may sometimes deliver
+packets more than once or in the wrong order.
+
+Designing a program to use unreliable communication styles usually
+involves taking precautions to detect lost or misordered packets and
+to retransmit data as needed.
+
+@item
+@strong{Is communication entirely with one partner?}  Some
+communication styles are like a telephone call---you make a
+@dfn{connection} with one remote socket and then exchange data
+freely.  Other styles are like mailing letters---you specify a
+destination address for each message you send.
+@end itemize
+
+@cindex namespace (of socket)
+@cindex domain (of socket)
+@cindex socket namespace
+@cindex socket domain
+You must also choose a @dfn{namespace} for naming the socket.  A socket
+name (``address'') is meaningful only in the context of a particular
+namespace.  In fact, even the data type to use for a socket name may
+depend on the namespace.  Namespaces are also called ``domains'', but we
+avoid that word as it can be confused with other usage of the same
+term.  Each namespace has a symbolic name that starts with @samp{PF_}.
+A corresponding symbolic name starting with @samp{AF_} designates the
+address format for that namespace.
+
+@cindex network protocol
+@cindex protocol (of socket)
+@cindex socket protocol
+@cindex protocol family
+Finally you must choose the @dfn{protocol} to carry out the
+communication.  The protocol determines what low-level mechanism is used
+to transmit and receive data.  Each protocol is valid for a particular
+namespace and communication style; a namespace is sometimes called a
+@dfn{protocol family} because of this, which is why the namespace names
+start with @samp{PF_}.
+
+The rules of a protocol apply to the data passing between two programs,
+perhaps on different computers; most of these rules are handled by the
+operating system and you need not know about them.  What you do need to
+know about protocols is this:
+
+@itemize @bullet
+@item
+In order to have communication between two sockets, they must specify
+the @emph{same} protocol.
+
+@item
+Each protocol is meaningful with particular style/namespace
+combinations and cannot be used with inappropriate combinations.  For
+example, the TCP protocol fits only the byte stream style of
+communication and the Internet namespace.
+
+@item
+For each combination of style and namespace there is a @dfn{default
+protocol}, which you can request by specifying 0 as the protocol
+number.  And that's what you should normally do---use the default.
+@end itemize
+
+Throughout the following description at various places
+variables/parameters to denote sizes are required.  And here the trouble
+starts.  In the first implementations the type of these variables was
+simply @code{int}.  On most machines at that time an @code{int} was 32
+bits wide, which created a @emph{de facto} standard requiring 32-bit
+variables.  This is important since references to variables of this type
+are passed to the kernel.
+
+Then the POSIX people came and unified the interface with the words "all
+size values are of type @code{size_t}".  On 64-bit machines
+@code{size_t} is 64 bits wide, so pointers to variables were no longer
+possible.
+
+The Unix98 specification provides a solution by introducing a type
+@code{socklen_t}.  This type is used in all of the cases that POSIX
+changed to use @code{size_t}.  The only requirement of this type is that
+it be an unsigned type of at least 32 bits.  Therefore, implementations
+which require that references to 32-bit variables be passed can be as
+happy as implementations which use 64-bit values.
+
+
+@node Communication Styles
+@section Communication Styles
+
+@Theglibc{} includes support for several different kinds of sockets,
+each with different characteristics.  This section describes the
+supported socket types.  The symbolic constants listed here are
+defined in @file{sys/socket.h}.
+@pindex sys/socket.h
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_STREAM
+The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}).
+It operates over a connection with a particular remote socket and
+transmits data reliably as a stream of bytes.
+
+Use of this style is covered in detail in @ref{Connections}.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_DGRAM
+The @code{SOCK_DGRAM} style is used for sending
+individually-addressed packets unreliably.
+It is the diametrical opposite of @code{SOCK_STREAM}.
+
+Each time you write data to a socket of this kind, that data becomes
+one packet.  Since @code{SOCK_DGRAM} sockets do not have connections,
+you must specify the recipient address with each packet.
+
+The only guarantee that the system makes about your requests to
+transmit data is that it will try its best to deliver each packet you
+send.  It may succeed with the sixth packet after failing with the
+fourth and fifth packets; the seventh packet may arrive before the
+sixth, and may arrive a second time after the sixth.
+
+The typical use for @code{SOCK_DGRAM} is in situations where it is
+acceptable to simply re-send a packet if no response is seen in a
+reasonable amount of time.
+
+@xref{Datagrams}, for detailed information about how to use datagram
+sockets.
+@end deftypevr
+
+@ignore
+@c This appears to be only for the NS domain, which we aren't
+@c discussing and probably won't support either.
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_SEQPACKET
+This style is like @code{SOCK_STREAM} except that the data are
+structured into packets.
+
+A program that receives data over a @code{SOCK_SEQPACKET} socket
+should be prepared to read the entire message packet in a single call
+to @code{read}; if it only reads part of the message, the remainder of
+the message is simply discarded instead of being available for
+subsequent calls to @code{read}.
+
+Many protocols do not support this communication style.
+@end deftypevr
+@end ignore
+
+@ignore
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_RDM
+This style is a reliable version of @code{SOCK_DGRAM}: it sends
+individually addressed packets, but guarantees that each packet sent
+arrives exactly once.
+
+@strong{Warning:} It is not clear this is actually supported
+by any operating system.
+@end deftypevr
+@end ignore
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int SOCK_RAW
+This style provides access to low-level network protocols and
+interfaces.  Ordinary user programs usually have no need to use this
+style.
+@end deftypevr
+
+@node Socket Addresses
+@section Socket Addresses
+
+@cindex address of socket
+@cindex name of socket
+@cindex binding a socket address
+@cindex socket address (name) binding
+The name of a socket is normally called an @dfn{address}.  The
+functions and symbols for dealing with socket addresses were named
+inconsistently, sometimes using the term ``name'' and sometimes using
+``address''.  You can regard these terms as synonymous where sockets
+are concerned.
+
+A socket newly created with the @code{socket} function has no
+address.  Other processes can find it for communication only if you
+give it an address.  We call this @dfn{binding} the address to the
+socket, and the way to do it is with the @code{bind} function.
+
+You need be concerned with the address of a socket if other processes
+are to find it and start communicating with it.  You can specify an
+address for other sockets, but this is usually pointless; the first time
+you send data from a socket, or use it to initiate a connection, the
+system assigns an address automatically if you have not specified one.
+
+Occasionally a client needs to specify an address because the server
+discriminates based on address; for example, the rsh and rlogin
+protocols look at the client's socket address and only bypass password
+checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}).
+
+The details of socket addresses vary depending on what namespace you are
+using.  @xref{Local Namespace}, or @ref{Internet Namespace}, for specific
+information.
+
+Regardless of the namespace, you use the same functions @code{bind} and
+@code{getsockname} to set and examine a socket's address.  These
+functions use a phony data type, @code{struct sockaddr *}, to accept the
+address.  In practice, the address lives in a structure of some other
+data type appropriate to the address format you are using, but you cast
+its address to @code{struct sockaddr *} when you pass it to
+@code{bind}.
+
+@menu
+* Address Formats::		About @code{struct sockaddr}.
+* Setting Address::		Binding an address to a socket.
+* Reading Address::		Reading the address of a socket.
+@end menu
+
+@node Address Formats
+@subsection Address Formats
+
+The functions @code{bind} and @code{getsockname} use the generic data
+type @code{struct sockaddr *} to represent a pointer to a socket
+address.  You can't use this data type effectively to interpret an
+address or construct one; for that, you must use the proper data type
+for the socket's namespace.
+
+Thus, the usual practice is to construct an address of the proper
+namespace-specific type, then cast a pointer to @code{struct sockaddr *}
+when you call @code{bind} or @code{getsockname}.
+
+The one piece of information that you can get from the @code{struct
+sockaddr} data type is the @dfn{address format designator}.  This tells
+you which data type to use to understand the address fully.
+
+@pindex sys/socket.h
+The symbols in this section are defined in the header file
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftp {Data Type} {struct sockaddr}
+The @code{struct sockaddr} type itself has the following members:
+
+@table @code
+@item short int sa_family
+This is the code for the address format of this address.  It
+identifies the format of the data which follows.
+
+@item char sa_data[14]
+This is the actual socket address data, which is format-dependent.  Its
+length also depends on the format, and may well be more than 14.  The
+length 14 of @code{sa_data} is essentially arbitrary.
+@end table
+@end deftp
+
+Each address format has a symbolic name which starts with @samp{AF_}.
+Each of them corresponds to a @samp{PF_} symbol which designates the
+corresponding namespace.  Here is a list of address format names:
+
+@table @code
+@comment sys/socket.h
+@comment POSIX
+@item AF_LOCAL
+@vindex AF_LOCAL
+This designates the address format that goes with the local namespace.
+(@code{PF_LOCAL} is the name of that namespace.)  @xref{Local Namespace
+Details}, for information about this address format.
+
+@comment sys/socket.h
+@comment BSD, Unix98
+@item AF_UNIX
+@vindex AF_UNIX
+This is a synonym for @code{AF_LOCAL}.  Although @code{AF_LOCAL} is
+mandated by POSIX.1g, @code{AF_UNIX} is portable to more systems.
+@code{AF_UNIX} was the traditional name stemming from BSD, so even most
+POSIX systems support it.  It is also the name of choice in the Unix98
+specification. (The same is true for @code{PF_UNIX}
+vs. @code{PF_LOCAL}).
+
+@comment sys/socket.h
+@comment GNU
+@item AF_FILE
+@vindex AF_FILE
+This is another synonym for @code{AF_LOCAL}, for compatibility.
+(@code{PF_FILE} is likewise a synonym for @code{PF_LOCAL}.)
+
+@comment sys/socket.h
+@comment BSD
+@item AF_INET
+@vindex AF_INET
+This designates the address format that goes with the Internet
+namespace.  (@code{PF_INET} is the name of that namespace.)
+@xref{Internet Address Formats}.
+
+@comment sys/socket.h
+@comment IPv6 Basic API
+@item AF_INET6
+This is similar to @code{AF_INET}, but refers to the IPv6 protocol.
+(@code{PF_INET6} is the name of the corresponding namespace.)
+
+@comment sys/socket.h
+@comment BSD
+@item AF_UNSPEC
+@vindex AF_UNSPEC
+This designates no particular address format.  It is used only in rare
+cases, such as to clear out the default destination address of a
+``connected'' datagram socket.  @xref{Sending Datagrams}.
+
+The corresponding namespace designator symbol @code{PF_UNSPEC} exists
+for completeness, but there is no reason to use it in a program.
+@end table
+
+@file{sys/socket.h} defines symbols starting with @samp{AF_} for many
+different kinds of networks, most or all of which are not actually
+implemented.  We will document those that really work as we receive
+information about how to use them.
+
+@node Setting Address
+@subsection Setting the Address of a Socket
+
+@pindex sys/socket.h
+Use the @code{bind} function to assign an address to a socket.  The
+prototype for @code{bind} is in the header file @file{sys/socket.h}.
+For examples of use, see @ref{Local Socket Example}, or see @ref{Inet Example}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, except on Hurd.
+The @code{bind} function assigns an address to the socket
+@var{socket}.  The @var{addr} and @var{length} arguments specify the
+address; the detailed format of the address depends on the namespace.
+The first part of the address is always the format designator, which
+specifies a namespace, and says that the address is in the format of
+that namespace.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item EADDRNOTAVAIL
+The specified address is not available on this machine.
+
+@item EADDRINUSE
+Some other socket is already using the specified address.
+
+@item EINVAL
+The socket @var{socket} already has an address.
+
+@item EACCES
+You do not have permission to access the requested address.  (In the
+Internet domain, only the super-user is allowed to specify a port number
+in the range 0 through @code{IPPORT_RESERVED} minus one; see
+@ref{Ports}.)
+@end table
+
+Additional conditions may be possible depending on the particular namespace
+of the socket.
+@end deftypefun
+
+@node Reading Address
+@subsection Reading the Address of a Socket
+
+@pindex sys/socket.h
+Use the function @code{getsockname} to examine the address of an
+Internet socket.  The prototype for this function is in the header file
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsmem{/hurd}}}
+@c Direct syscall, except on Hurd, where it seems like it might leak
+@c VM if cancelled.
+The @code{getsockname} function returns information about the
+address of the socket @var{socket} in the locations specified by the
+@var{addr} and @var{length-ptr} arguments.  Note that the
+@var{length-ptr} is a pointer; you should initialize it to be the
+allocation size of @var{addr}, and on return it contains the actual
+size of the address data.
+
+The format of the address data depends on the socket namespace.  The
+length of the information is usually fixed for a given namespace, so
+normally you can know exactly how much space is needed and can provide
+that much.  The usual practice is to allocate a place for the value
+using the proper data type for the socket's namespace, then cast its
+address to @code{struct sockaddr *} to pass it to @code{getsockname}.
+
+The return value is @code{0} on success and @code{-1} on error.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item ENOBUFS
+There are not enough internal buffers available for the operation.
+@end table
+@end deftypefun
+
+You can't read the address of a socket in the file namespace.  This is
+consistent with the rest of the system; in general, there's no way to
+find a file's name from a descriptor for that file.
+
+@node Interface Naming
+@section Interface Naming
+
+Each network interface has a name.  This usually consists of a few
+letters that relate to the type of interface, which may be followed by a
+number if there is more than one interface of that type.  Examples
+might be @code{lo} (the loopback interface) and @code{eth0} (the first
+Ethernet interface).
+
+Although such names are convenient for humans, it would be clumsy to
+have to use them whenever a program needs to refer to an interface.  In
+such situations an interface is referred to by its @dfn{index}, which is
+an arbitrarily-assigned small positive integer.
+
+The following functions, constants and data types are declared in the
+header file @file{net/if.h}.
+
+@comment net/if.h
+@deftypevr Constant size_t IFNAMSIZ
+This constant defines the maximum buffer size needed to hold an
+interface name, including its terminating zero byte.
+@end deftypevr
+
+@comment net/if.h
+@comment IPv6 basic API
+@deftypefun {unsigned int} if_nametoindex (const char *@var{ifname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c It opens a socket to use ioctl on the fd to get the index.
+@c opensock may call socket and access multiple times until it finds a
+@c socket family that works.  The Linux implementation has a potential
+@c concurrency issue WRT last_type and last_family not being updated
+@c atomically, but it is harmless; the generic implementation, OTOH,
+@c takes a lock, which makes all callers AS- and AC-Unsafe.
+@c  opensock @asulock @aculock @acsfd
+This function yields the interface index corresponding to a particular
+name.  If no interface exists with the name given, it returns 0.
+@end deftypefun
+
+@comment net/if.h
+@comment IPv6 basic API
+@deftypefun {char *} if_indextoname (unsigned int @var{ifindex}, char *@var{ifname})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c It opens a socket with opensock to use ioctl on the fd to get the
+@c name from the index.
+This function maps an interface index to its corresponding name.  The
+returned name is placed in the buffer pointed to by @code{ifname}, which
+must be at least @code{IFNAMSIZ} bytes in length.  If the index was
+invalid, the function's return value is a null pointer, otherwise it is
+@code{ifname}.
+@end deftypefun
+
+@comment net/if.h
+@comment IPv6 basic API
+@deftp {Data Type} {struct if_nameindex}
+This data type is used to hold the information about a single
+interface.  It has the following members:
+
+@table @code
+@item unsigned int if_index;
+This is the interface index.
+
+@item char *if_name
+This is the null-terminated index name.
+
+@end table
+@end deftp
+
+@comment net/if.h
+@comment IPv6 basic API
+@deftypefun {struct if_nameindex *} if_nameindex (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@aculock{/hurd} @acsfd{} @acsmem{}}}
+@c if_nameindex @ascuheap @asulock/hurd @aculock/hurd @acsfd @acsmem
+@c  [linux]
+@c   netlink_open @acsfd @acsmem/hurd
+@c    socket dup @acsfd
+@c    memset dup ok
+@c    bind dup ok
+@c    netlink_close dup @acsfd
+@c    getsockname dup @acsmem/hurd
+@c   netlink_request @ascuheap @acsmem
+@c    getpagesize dup ok
+@c    malloc dup @ascuheap @acsmem
+@c    netlink_sendreq ok
+@c     memset dup ok
+@c     sendto dup ok
+@c    recvmsg dup ok
+@c    memcpy dup ok
+@c    free dup @ascuheap @acsmem
+@c   netlink_free_handle @ascuheap @acsmem
+@c    free dup @ascuheap @acsmem
+@c   netlink_close @acsfd
+@c    close dup @acsfd
+@c   malloc dup @asuheap @acsmem
+@c   strndup @ascuheap @acsmem
+@c   if_freenameindex @ascuheap @acsmem
+@c  [hurd]
+@c   opensock dup @asulock @aculock @acsfd
+@c   hurd_socket_server ok
+@c   pfinet_siocgifconf ok
+@c   malloc @ascuheap @acsmem
+@c   strdup @ascuheap @acsmem
+@c   ioctl dup ok
+@c   free @ascuheap @acsmem
+This function returns an array of @code{if_nameindex} structures, one
+for every interface that is present.  The end of the list is indicated
+by a structure with an interface of 0 and a null name pointer.  If an
+error occurs, this function returns a null pointer.
+
+The returned structure must be freed with @code{if_freenameindex} after
+use.
+@end deftypefun
+
+@comment net/if.h
+@comment IPv6 basic API
+@deftypefun void if_freenameindex (struct if_nameindex *@var{ptr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c if_freenameindex @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+This function frees the structure returned by an earlier call to
+@code{if_nameindex}.
+@end deftypefun
+
+@node Local Namespace
+@section The Local Namespace
+@cindex local namespace, for sockets
+
+This section describes the details of the local namespace, whose
+symbolic name (required when you create a socket) is @code{PF_LOCAL}.
+The local namespace is also known as ``Unix domain sockets''.  Another
+name is file namespace since socket addresses are normally implemented
+as file names.
+
+@menu
+* 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.
+@end menu
+
+@node Local Namespace Concepts
+@subsection Local Namespace Concepts
+
+In the local namespace socket addresses are file names.  You can specify
+any file name you want as the address of the socket, but you must have
+write permission on the directory containing it.
+@c XXX The following was said to be wrong.
+@c In order to connect to a socket you must have read permission for it.
+It's common to put these files in the @file{/tmp} directory.
+
+One peculiarity of the local namespace is that the name is only used
+when opening the connection; once open the address is not meaningful and
+may not exist.
+
+Another peculiarity is that you cannot connect to such a socket from
+another machine--not even if the other machine shares the file system
+which contains the name of the socket.  You can see the socket in a
+directory listing, but connecting to it never succeeds.  Some programs
+take advantage of this, such as by asking the client to send its own
+process ID, and using the process IDs to distinguish between clients.
+However, we recommend you not use this method in protocols you design,
+as we might someday permit connections from other machines that mount
+the same file systems.  Instead, send each new client an identifying
+number if you want it to have one.
+
+After you close a socket in the local namespace, you should delete the
+file name from the file system.  Use @code{unlink} or @code{remove} to
+do this; see @ref{Deleting Files}.
+
+The local namespace supports just one protocol for any communication
+style; it is protocol number @code{0}.
+
+@node Local Namespace Details
+@subsection Details of Local Namespace
+
+@pindex sys/socket.h
+To create a socket in the local namespace, use the constant
+@code{PF_LOCAL} as the @var{namespace} argument to @code{socket} or
+@code{socketpair}.  This constant is defined in @file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment POSIX
+@deftypevr Macro int PF_LOCAL
+This designates the local namespace, in which socket addresses are local
+names, and its associated family of protocols.  @code{PF_Local} is the
+macro used by Posix.1g.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int PF_UNIX
+This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
+@end deftypevr
+
+@comment sys/socket.h
+@comment GNU
+@deftypevr Macro int PF_FILE
+This is a synonym for @code{PF_LOCAL}, for compatibility's sake.
+@end deftypevr
+
+The structure for specifying socket names in the local namespace is
+defined in the header file @file{sys/un.h}:
+@pindex sys/un.h
+
+@comment sys/un.h
+@comment BSD
+@deftp {Data Type} {struct sockaddr_un}
+This structure is used to specify local namespace socket addresses.  It has
+the following members:
+
+@table @code
+@item short int sun_family
+This identifies the address family or format of the socket address.
+You should store the value @code{AF_LOCAL} to designate the local
+namespace.  @xref{Socket Addresses}.
+
+@item char sun_path[108]
+This is the file name to use.
+
+@strong{Incomplete:}  Why is 108 a magic number?  RMS suggests making
+this a zero-length array and tweaking the following example to use
+@code{alloca} to allocate an appropriate amount of storage based on
+the length of the filename.
+@end table
+@end deftp
+
+You should compute the @var{length} parameter for a socket address in
+the local namespace as the sum of the size of the @code{sun_family}
+component and the string length (@emph{not} the allocation size!) of
+the file name string.  This can be done using the macro @code{SUN_LEN}:
+
+@comment sys/un.h
+@comment BSD
+@deftypefn {Macro} int SUN_LEN (@emph{struct sockaddr_un *} @var{ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The macro computes the length of socket address in the local namespace.
+@end deftypefn
+
+@node Local Socket Example
+@subsection Example of Local-Namespace Sockets
+
+Here is an example showing how to create and name a socket in the local
+namespace.
+
+@smallexample
+@include mkfsock.c.texi
+@end smallexample
+
+@node Internet Namespace
+@section The Internet Namespace
+@cindex Internet namespace, for sockets
+
+This section describes the details of the protocols and socket naming
+conventions used in the Internet namespace.
+
+Originally the Internet namespace used only IP version 4 (IPv4).  With
+the growing number of hosts on the Internet, a new protocol with a
+larger address space was necessary: IP version 6 (IPv6).  IPv6
+introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
+features, and will eventually replace IPv4.
+
+To create a socket in the IPv4 Internet namespace, use the symbolic name
+@code{PF_INET} of this namespace as the @var{namespace} argument to
+@code{socket} or @code{socketpair}.  For IPv6 addresses you need the
+macro @code{PF_INET6}.  These macros are defined in @file{sys/socket.h}.
+@pindex sys/socket.h
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int PF_INET
+This designates the IPv4 Internet namespace and associated family of
+protocols.
+@end deftypevr
+
+@comment sys/socket.h
+@comment X/Open
+@deftypevr Macro int PF_INET6
+This designates the IPv6 Internet namespace and associated family of
+protocols.
+@end deftypevr
+
+A socket address for the Internet namespace includes the following components:
+
+@itemize @bullet
+@item
+The address of the machine you want to connect to.  Internet addresses
+can be specified in several ways; these are discussed in @ref{Internet
+Address Formats}, @ref{Host Addresses} and @ref{Host Names}.
+
+@item
+A port number for that machine.  @xref{Ports}.
+@end itemize
+
+You must ensure that the address and port number are represented in a
+canonical format called @dfn{network byte order}.  @xref{Byte Order},
+for information about this.
+
+@menu
+* Internet Address Formats::    How socket addresses are specified in the
+                                 Internet namespace.
+* Host Addresses::	        All about host addresses of Internet host.
+* 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.
+* Protocols Database::		Referring to protocols by name.
+* Inet Example::	        Putting it all together.
+@end menu
+
+@node Internet Address Formats
+@subsection Internet Socket Address Formats
+
+In the Internet namespace, for both IPv4 (@code{AF_INET}) and IPv6
+(@code{AF_INET6}), a socket address consists of a host address
+and a port on that host.  In addition, the protocol you choose serves
+effectively as a part of the address because local port numbers are
+meaningful only within a particular protocol.
+
+The data types for representing socket addresses in the Internet namespace
+are defined in the header file @file{netinet/in.h}.
+@pindex netinet/in.h
+
+@comment netinet/in.h
+@comment BSD
+@deftp {Data Type} {struct sockaddr_in}
+This is the data type used to represent socket addresses in the
+Internet namespace.  It has the following members:
+
+@table @code
+@item sa_family_t sin_family
+This identifies the address family or format of the socket address.
+You should store the value @code{AF_INET} in this member.
+@xref{Socket Addresses}.
+
+@item struct in_addr sin_addr
+This is the Internet address of the host machine.  @xref{Host
+Addresses}, and @ref{Host Names}, for how to get a value to store
+here.
+
+@item unsigned short int sin_port
+This is the port number.  @xref{Ports}.
+@end table
+@end deftp
+
+When you call @code{bind} or @code{getsockname}, you should specify
+@code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
+you are using an IPv4 Internet namespace socket address.
+
+@deftp {Data Type} {struct sockaddr_in6}
+This is the data type used to represent socket addresses in the IPv6
+namespace.  It has the following members:
+
+@table @code
+@item sa_family_t sin6_family
+This identifies the address family or format of the socket address.
+You should store the value of @code{AF_INET6} in this member.
+@xref{Socket Addresses}.
+
+@item struct in6_addr sin6_addr
+This is the IPv6 address of the host machine.  @xref{Host
+Addresses}, and @ref{Host Names}, for how to get a value to store
+here.
+
+@item uint32_t sin6_flowinfo
+This is a currently unimplemented field.
+
+@item uint16_t sin6_port
+This is the port number.  @xref{Ports}.
+
+@end table
+@end deftp
+
+@node Host Addresses
+@subsection Host Addresses
+
+Each computer on the Internet has one or more @dfn{Internet addresses},
+numbers which identify that computer among all those on the Internet.
+Users typically write IPv4 numeric host addresses as sequences of four
+numbers, separated by periods, as in @samp{128.52.46.32}, and IPv6
+numeric host addresses as sequences of up to eight numbers separated by
+colons, as in @samp{5f03:1200:836f:c100::1}.
+
+Each computer also has one or more @dfn{host names}, which are strings
+of words separated by periods, as in @samp{www.gnu.org}.
+
+Programs that let the user specify a host typically accept both numeric
+addresses and host names.  To open a connection a program needs a
+numeric address, and so must convert a host name to the numeric address
+it stands for.
+
+@menu
+* Abstract Host Addresses::	What a host number consists of.
+* 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.
+@end menu
+
+@node Abstract Host Addresses
+@subsubsection Internet Host Addresses
+@cindex host address, Internet
+@cindex Internet host address
+
+@ifinfo
+Each computer on the Internet has one or more Internet addresses,
+numbers which identify that computer among all those on the Internet.
+@end ifinfo
+
+@cindex network number
+@cindex local network address number
+An IPv4 Internet host address is a number containing four bytes of data.
+Historically these are divided into two parts, a @dfn{network number} and a
+@dfn{local network address number} within that network.  In the
+mid-1990s classless addresses were introduced which changed this
+behavior.  Since some functions implicitly expect the old definitions,
+we first describe the class-based network and will then describe
+classless addresses.  IPv6 uses only classless addresses and therefore
+the following paragraphs don't apply.
+
+The class-based IPv4 network number consists of the first one, two or
+three bytes; the rest of the bytes are the local address.
+
+IPv4 network numbers are registered with the Network Information Center
+(NIC), and are divided into three classes---A, B and C.  The local
+network address numbers of individual machines are registered with the
+administrator of the particular network.
+
+Class A networks have single-byte numbers in the range 0 to 127.  There
+are only a small number of Class A networks, but they can each support a
+very large number of hosts.  Medium-sized Class B networks have two-byte
+network numbers, with the first byte in the range 128 to 191.  Class C
+networks are the smallest; they have three-byte network numbers, with
+the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
+of an Internet address specify a network.  The remaining bytes of the
+Internet address specify the address within that network.
+
+The Class A network 0 is reserved for broadcast to all networks.  In
+addition, the host number 0 within each network is reserved for broadcast
+to all hosts in that network.  These uses are obsolete now but for
+compatibility reasons you shouldn't use network 0 and host number 0.
+
+The Class A network 127 is reserved for loopback; you can always use
+the Internet address @samp{127.0.0.1} to refer to the host machine.
+
+Since a single machine can be a member of multiple networks, it can
+have multiple Internet host addresses.  However, there is never
+supposed to be more than one machine with the same host address.
+
+@c !!! this section could document the IN_CLASS* macros in <netinet/in.h>.
+@c No, it shouldn't since they're obsolete.
+
+@cindex standard dot notation, for Internet addresses
+@cindex dot notation, for Internet addresses
+There are four forms of the @dfn{standard numbers-and-dots notation}
+for Internet addresses:
+
+@table @code
+@item @var{a}.@var{b}.@var{c}.@var{d}
+This specifies all four bytes of the address individually and is the
+commonly used representation.
+
+@item @var{a}.@var{b}.@var{c}
+The last part of the address, @var{c}, is interpreted as a 2-byte quantity.
+This is useful for specifying host addresses in a Class B network with
+network address number @code{@var{a}.@var{b}}.
+
+@item @var{a}.@var{b}
+The last part of the address, @var{b}, is interpreted as a 3-byte quantity.
+This is useful for specifying host addresses in a Class A network with
+network address number @var{a}.
+
+@item @var{a}
+If only one part is given, this corresponds directly to the host address
+number.
+@end table
+
+Within each part of the address, the usual C conventions for specifying
+the radix apply.  In other words, a leading @samp{0x} or @samp{0X} implies
+hexadecimal radix; a leading @samp{0} implies octal; and otherwise decimal
+radix is assumed.
+
+@subsubheading Classless Addresses
+
+IPv4 addresses (and IPv6 addresses also) are now considered classless;
+the distinction between classes A, B and C can be ignored.  Instead an
+IPv4 host address consists of a 32-bit address and a 32-bit mask.  The
+mask contains set bits for the network part and cleared bits for the
+host part.  The network part is contiguous from the left, with the
+remaining bits representing the host.  As a consequence, the netmask can
+simply be specified as the number of set bits.  Classes A, B and C are
+just special cases of this general rule.  For example, class A addresses
+have a netmask of @samp{255.0.0.0} or a prefix length of 8.
+
+Classless IPv4 network addresses are written in numbers-and-dots
+notation with the prefix length appended and a slash as separator.  For
+example the class A network 10 is written as @samp{10.0.0.0/8}.
+
+@subsubheading IPv6 Addresses
+
+IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data.  A host
+address is usually written as eight 16-bit hexadecimal numbers that are
+separated by colons.  Two colons are used to abbreviate strings of
+consecutive zeros.  For example, the IPv6 loopback address
+@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}.
+
+@node Host Address Data Type
+@subsubsection Host Address Data Type
+
+IPv4 Internet host addresses are represented in some contexts as integers
+(type @code{uint32_t}).  In other contexts, the integer is
+packaged inside a structure of type @code{struct in_addr}.  It would
+be better if the usage were made consistent, but it is not hard to extract
+the integer from the structure or put the integer into a structure.
+
+You will find older code that uses @code{unsigned long int} for
+IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct
+in_addr}.  Historically @code{unsigned long int} was a 32-bit number but
+with 64-bit machines this has changed.  Using @code{unsigned long int}
+might break the code if it is used on machines where this type doesn't
+have 32 bits.  @code{uint32_t} is specified by Unix98 and guaranteed to have
+32 bits.
+
+IPv6 Internet host addresses have 128 bits and are packaged inside a
+structure of type @code{struct in6_addr}.
+
+The following basic definitions for Internet addresses are declared in
+the header file @file{netinet/in.h}:
+@pindex netinet/in.h
+
+@comment netinet/in.h
+@comment BSD
+@deftp {Data Type} {struct in_addr}
+This data type is used in certain contexts to contain an IPv4 Internet
+host address.  It has just one field, named @code{s_addr}, which records
+the host address number as an @code{uint32_t}.
+@end deftp
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro {uint32_t} INADDR_LOOPBACK
+You can use this constant to stand for ``the address of this machine,''
+instead of finding its actual address.  It is the IPv4 Internet address
+@samp{127.0.0.1}, which is usually called @samp{localhost}.  This
+special constant saves you the trouble of looking up the address of your
+own machine.  Also, the system usually implements @code{INADDR_LOOPBACK}
+specially, avoiding any network traffic for the case of one machine
+talking to itself.
+@end deftypevr
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro {uint32_t} INADDR_ANY
+You can use this constant to stand for ``any incoming address'' when
+binding to an address.  @xref{Setting Address}.  This is the usual
+address to give in the @code{sin_addr} member of @w{@code{struct
+sockaddr_in}} when you want to accept Internet connections.
+@end deftypevr
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro {uint32_t} INADDR_BROADCAST
+This constant is the address you use to send a broadcast message.
+@c !!! broadcast needs further documented
+@end deftypevr
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro {uint32_t} INADDR_NONE
+This constant is returned by some functions to indicate an error.
+@end deftypevr
+
+@comment netinet/in.h
+@comment IPv6 basic API
+@deftp {Data Type} {struct in6_addr}
+This data type is used to store an IPv6 address.  It stores 128 bits of
+data, which can be accessed (via a union) in a variety of ways.
+@end deftp
+
+@comment netinet/in.h
+@comment IPv6 basic API
+@deftypevr Constant {struct in6_addr} in6addr_loopback
+This constant is the IPv6 address @samp{::1}, the loopback address.  See
+above for a description of what this means.  The macro
+@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your
+own variables to this value.
+@end deftypevr
+
+@comment netinet/in.h
+@comment IPv6 basic API
+@deftypevr Constant {struct in6_addr} in6addr_any
+This constant is the IPv6 address @samp{::}, the unspecified address.  See
+above for a description of what this means.  The macro
+@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your
+own variables to this value.
+@end deftypevr
+
+@node Host Address Functions
+@subsubsection Host Address Functions
+
+@pindex arpa/inet.h
+@noindent
+These additional functions for manipulating Internet addresses are
+declared in the header file @file{arpa/inet.h}.  They represent Internet
+addresses in network byte order, and network numbers and
+local-address-within-network numbers in host byte order.  @xref{Byte
+Order}, for an explanation of network and host byte order.
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun int inet_aton (const char *@var{name}, struct in_addr *@var{addr})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c inet_aton @mtslocale
+@c  isdigit dup @mtslocale
+@c  strtoul dup @mtslocale
+@c  isascii dup @mtslocale
+@c  isspace dup @mtslocale
+@c  htonl dup ok
+This function converts the IPv4 Internet host address @var{name}
+from the standard numbers-and-dots notation into binary data and stores
+it in the @code{struct in_addr} that @var{addr} points to.
+@code{inet_aton} returns nonzero if the address is valid, zero if not.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun {uint32_t} inet_addr (const char *@var{name})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c inet_addr @mtslocale
+@c  inet_aton dup @mtslocale
+This function converts the IPv4 Internet host address @var{name} from the
+standard numbers-and-dots notation into binary data.  If the input is
+not valid, @code{inet_addr} returns @code{INADDR_NONE}.  This is an
+obsolete interface to @code{inet_aton}, described immediately above.  It
+is obsolete because @code{INADDR_NONE} is a valid address
+(255.255.255.255), and @code{inet_aton} provides a cleaner way to
+indicate error return.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun {uint32_t} inet_network (const char *@var{name})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c inet_network @mtslocale
+@c  isdigit dup @mtslocale
+@c  isxdigit dup @mtslocale
+@c  tolower dup @mtslocale
+@c  isspace dup @mtslocale
+This function extracts the network number from the address @var{name},
+given in the standard numbers-and-dots notation.  The returned address is
+in host order.  If the input is not valid, @code{inet_network} returns
+@code{-1}.
+
+The function works only with traditional IPv4 class A, B and C network
+types.  It doesn't work with classless addresses and shouldn't be used
+anymore.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun {char *} inet_ntoa (struct in_addr @var{addr})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asurace{}}@acsafe{}}
+@c inet_ntoa @mtslocale @asurace
+@c   writes to a thread-local static buffer
+@c  snprintf @mtslocale [no @ascuheap or @acsmem]
+This function converts the IPv4 Internet host address @var{addr} to a
+string in the standard numbers-and-dots notation.  The return value is
+a pointer into a statically-allocated buffer.  Subsequent calls will
+overwrite the same buffer, so you should copy the string if you need
+to save it.
+
+In multi-threaded programs each thread has an own statically-allocated
+buffer.  But still subsequent calls of @code{inet_ntoa} in the same
+thread will overwrite the result of the last call.
+
+Instead of @code{inet_ntoa} the newer function @code{inet_ntop} which is
+described below should be used since it handles both IPv4 and IPv6
+addresses.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun {struct in_addr} inet_makeaddr (uint32_t @var{net}, uint32_t @var{local})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c inet_makeaddr ok
+@c  htonl dup ok
+This function makes an IPv4 Internet host address by combining the network
+number @var{net} with the local-address-within-network number
+@var{local}.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun uint32_t inet_lnaof (struct in_addr @var{addr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c inet_lnaof ok
+@c  ntohl dup ok
+@c  IN_CLASSA ok
+@c  IN_CLASSB ok
+This function returns the local-address-within-network part of the
+Internet host address @var{addr}.
+
+The function works only with traditional IPv4 class A, B and C network
+types.  It doesn't work with classless addresses and shouldn't be used
+anymore.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment BSD
+@deftypefun uint32_t inet_netof (struct in_addr @var{addr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c inet_netof ok
+@c  ntohl dup ok
+@c  IN_CLASSA ok
+@c  IN_CLASSB ok
+This function returns the network number part of the Internet host
+address @var{addr}.
+
+The function works only with traditional IPv4 class A, B and C network
+types.  It doesn't work with classless addresses and shouldn't be used
+anymore.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment IPv6 basic API
+@deftypefun int inet_pton (int @var{af}, const char *@var{cp}, void *@var{buf})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c inet_pton @mtslocale
+@c  inet_pton4 ok
+@c   memcpy dup ok
+@c  inet_pton6 @mtslocale
+@c   memset dup ok
+@c   tolower dup @mtslocale
+@c   strchr dup ok
+@c   inet_pton4 dup ok
+@c   memcpy dup ok
+This function converts an Internet address (either IPv4 or IPv6) from
+presentation (textual) to network (binary) format.  @var{af} should be
+either @code{AF_INET} or @code{AF_INET6}, as appropriate for the type of
+address being converted.  @var{cp} is a pointer to the input string, and
+@var{buf} is a pointer to a buffer for the result.  It is the caller's
+responsibility to make sure the buffer is large enough.
+@end deftypefun
+
+@comment arpa/inet.h
+@comment IPv6 basic API
+@deftypefun {const char *} inet_ntop (int @var{af}, const void *@var{cp}, char *@var{buf}, socklen_t @var{len})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c inet_ntop @mtslocale
+@c  inet_ntop4 @mtslocale
+@c   sprintf dup @mtslocale [no @ascuheap or @acsmem]
+@c   strcpy dup ok
+@c  inet_ntop6 @mtslocale
+@c   memset dup ok
+@c   inet_ntop4 dup @mtslocale
+@c   sprintf dup @mtslocale [no @ascuheap or @acsmem]
+@c   strcpy dup ok
+This function converts an Internet address (either IPv4 or IPv6) from
+network (binary) to presentation (textual) form.  @var{af} should be
+either @code{AF_INET} or @code{AF_INET6}, as appropriate.  @var{cp} is a
+pointer to the address to be converted.  @var{buf} should be a pointer
+to a buffer to hold the result, and @var{len} is the length of this
+buffer.  The return value from the function will be this buffer address.
+@end deftypefun
+
+@node Host Names
+@subsubsection Host Names
+@cindex hosts database
+@cindex converting host name to address
+@cindex converting host address to name
+
+Besides the standard numbers-and-dots notation for Internet addresses,
+you can also refer to a host by a symbolic name.  The advantage of a
+symbolic name is that it is usually easier to remember.  For example,
+the machine with Internet address @samp{158.121.106.19} is also known as
+@samp{alpha.gnu.org}; and other machines in the @samp{gnu.org}
+domain can refer to it simply as @samp{alpha}.
+
+@pindex /etc/hosts
+@pindex netdb.h
+Internally, the system uses a database to keep track of the mapping
+between host names and host numbers.  This database is usually either
+the file @file{/etc/hosts} or an equivalent provided by a name server.
+The functions and other symbols for accessing this database are declared
+in @file{netdb.h}.  They are BSD features, defined unconditionally if
+you include @file{netdb.h}.
+
+@comment netdb.h
+@comment BSD
+@deftp {Data Type} {struct hostent}
+This data type is used to represent an entry in the hosts database.  It
+has the following members:
+
+@table @code
+@item char *h_name
+This is the ``official'' name of the host.
+
+@item char **h_aliases
+These are alternative names for the host, represented as a null-terminated
+vector of strings.
+
+@item int h_addrtype
+This is the host address type; in practice, its value is always either
+@code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6
+hosts.  In principle other kinds of addresses could be represented in
+the database as well as Internet addresses; if this were done, you
+might find a value in this field other than @code{AF_INET} or
+@code{AF_INET6}.  @xref{Socket Addresses}.
+
+@item int h_length
+This is the length, in bytes, of each address.
+
+@item char **h_addr_list
+This is the vector of addresses for the host.  (Recall that the host
+might be connected to multiple networks and have different addresses on
+each one.)  The vector is terminated by a null pointer.
+
+@item char *h_addr
+This is a synonym for @code{h_addr_list[0]}; in other words, it is the
+first host address.
+@end table
+@end deftp
+
+As far as the host database is concerned, each address is just a block
+of memory @code{h_length} bytes long.  But in other contexts there is an
+implicit assumption that you can convert IPv4 addresses to a
+@code{struct in_addr} or an @code{uint32_t}.  Host addresses in
+a @code{struct hostent} structure are always given in network byte
+order; see @ref{Byte Order}.
+
+You can use @code{gethostbyname}, @code{gethostbyname2} or
+@code{gethostbyaddr} to search the hosts database for information about
+a particular host.  The information is returned in a
+statically-allocated structure; you must copy the information if you
+need to save it across calls.  You can also use @code{getaddrinfo} and
+@code{getnameinfo} to obtain this information.
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct hostent *} gethostbyname (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyname @mtasurace:hostbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  nss_hostname_digits_dots @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   res_maybe_init(!preinit) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    res_iclose @acsuheap @acsmem @acsfd
+@c     close_not_cancel_no_status dup @acsfd
+@c     free dup @acsuheap @acsmem
+@c    res_vinit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     res_randomid ok
+@c      getpid dup ok
+@c     getenv dup @mtsenv
+@c     strncpy dup ok
+@c     fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c     fsetlocking dup ok [no concurrent uses]
+@c     fgets_unlocked dup ok [no concurrent uses]
+@c     MATCH ok
+@c      strncmp dup ok
+@c     strpbrk dup ok
+@c     strchr dup ok
+@c     inet_aton dup @mtslocale
+@c     htons dup
+@c     inet_pton dup @mtslocale
+@c     malloc dup @ascuheap @acsmem
+@c     IN6_IS_ADDR_LINKLOCAL ok
+@c      htonl dup ok
+@c     IN6_IS_ADDR_MC_LINKLOCAL ok
+@c     if_nametoindex dup @asulock @aculock @acsfd
+@c     strtoul dup @mtslocale
+@c     ISSORTMASK ok
+@c      strchr dup ok
+@c     isascii dup @mtslocale
+@c     isspace dup @mtslocale
+@c     net_mask ok
+@c      ntohl dup ok
+@c      IN_CLASSA dup ok
+@c      htonl dup ok
+@c      IN_CLASSB dup ok
+@c     res_setoptions @mtslocale
+@c      strncmp dup ok
+@c      atoi dup @mtslocale
+@c     fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c     inet_makeaddr dup ok
+@c     gethostname dup ok
+@c     strcpy dup ok
+@c     rawmemchr dup ok
+@c    res_ninit @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     res_vinit dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   isdigit dup @mtslocale
+@c   isxdigit dup @mtslocale
+@c   strlen dup ok
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c   memset dup ok
+@c   inet_aton dup @mtslocale
+@c   inet_pton dup @mtslocale
+@c   strcpy dup ok
+@c   memcpy dup ok
+@c   strchr dup ok
+@c  gethostbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c  set_h_errno ok
+The @code{gethostbyname} function returns information about the host
+named @var{name}.  If the lookup fails, it returns a null pointer.
+@end deftypefun
+
+@comment netdb.h
+@comment IPv6 Basic API
+@deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyname2} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyname2 @mtasurace:hostbyname2 @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  gethostbyname2_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c  set_h_errno dup ok
+The @code{gethostbyname2} function is like @code{gethostbyname}, but
+allows the caller to specify the desired address family (e.g.@:
+@code{AF_INET} or @code{AF_INET6}) of the result.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct hostent *} gethostbyaddr (const void *@var{addr}, socklen_t @var{length}, int @var{format})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostbyaddr} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyaddr @mtasurace:hostbyaddr @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  gethostbyaddr_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c  set_h_errno dup ok
+The @code{gethostbyaddr} function returns information about the host
+with Internet address @var{addr}.  The parameter @var{addr} is not
+really a pointer to char - it can be a pointer to an IPv4 or an IPv6
+address.  The @var{length} argument is the size (in bytes) of the address
+at @var{addr}.  @var{format} specifies the address format; for an IPv4
+Internet address, specify a value of @code{AF_INET}; for an IPv6
+Internet address, use @code{AF_INET6}.
+
+If the lookup fails, @code{gethostbyaddr} returns a null pointer.
+@end deftypefun
+
+@vindex h_errno
+If the name lookup by @code{gethostbyname} or @code{gethostbyaddr}
+fails, you can find out the reason by looking at the value of the
+variable @code{h_errno}.  (It would be cleaner design for these
+functions to set @code{errno}, but use of @code{h_errno} is compatible
+with other systems.)
+
+Here are the error codes that you may find in @code{h_errno}:
+
+@table @code
+@comment netdb.h
+@comment BSD
+@item HOST_NOT_FOUND
+@vindex HOST_NOT_FOUND
+No such host is known in the database.
+
+@comment netdb.h
+@comment BSD
+@item TRY_AGAIN
+@vindex TRY_AGAIN
+This condition happens when the name server could not be contacted.  If
+you try again later, you may succeed then.
+
+@comment netdb.h
+@comment BSD
+@item NO_RECOVERY
+@vindex NO_RECOVERY
+A non-recoverable error occurred.
+
+@comment netdb.h
+@comment BSD
+@item NO_ADDRESS
+@vindex NO_ADDRESS
+The host database contains an entry for the name, but it doesn't have an
+associated Internet address.
+@end table
+
+The lookup functions above all have one in common: they are not
+reentrant and therefore unusable in multi-threaded applications.
+Therefore provides @theglibc{} a new set of functions which can be
+used in this context.
+
+@comment netdb.h
+@comment GNU
+@deftypefun int gethostbyname_r (const char *restrict @var{name}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyname_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  nscd_gethostbyname_r @mtsenv @ascuheap @acsfd @acsmem
+@c   nscd_gethst_r @mtsenv @ascuheap @acsfd @acsmem
+@c    getenv dup @mtsenv
+@c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c    nscd_cache_search dup ok
+@c    memcpy dup ok
+@c    nscd_open_socket dup @acsfd
+@c    readvall dup ok
+@c    readall dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref dup @ascuheap @acsmem
+@c    nscd_unmap dup @ascuheap @acsmem
+@c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  res_hconf_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
+@c   res_hconf.c:do_init @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c    memset dup ok
+@c    getenv dup @mtsenv
+@c    fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c    fsetlocking dup ok [no concurrent uses]
+@c    fgets_unlocked dup ok [no concurrent uses]
+@c    strchrnul dup ok
+@c    res_hconf.c:parse_line @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c     skip_ws dup @mtslocale
+@c     skip_string dup @mtslocale
+@c     strncasecmp dup @mtslocale
+@c     strlen dup ok
+@c     asprintf dup @mtslocale @ascuheap @acsmem
+@c     fxprintf dup @asucorrupt @aculock @acucorrupt
+@c     free dup @ascuheap @acsmem
+@c     arg_trimdomain_list dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c     arg_spoof dup @mtslocale
+@c     arg_bool dup @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c     isspace dup @mtslocale
+@c    fclose dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c    arg_spoof @mtslocale
+@c     skip_string @mtslocale
+@c      isspace dup @mtslocale
+@c     strncasecmp dup @mtslocale
+@c    arg_bool @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c     strncasecmp dup @mtslocale
+@c     asprintf dup @mtslocale @ascuheap @acsmem
+@c     fxprintf dup @asucorrupt @aculock @acucorrupt
+@c     free dup @ascuheap @acsmem
+@c    arg_trimdomain_list @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c     skip_string dup @mtslocale
+@c     asprintf dup @mtslocale @ascuheap @acsmem
+@c     fxprintf dup @asucorrupt @aculock @acucorrupt
+@c     free dup @ascuheap @acsmem
+@c     strndup dup @ascuheap @acsmem
+@c     skip_ws @mtslocale
+@c      isspace dup @mtslocale
+@c  nss_hosts_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_gethostbyname_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  res_hconf_reorder_addrs @asulock @ascuheap @aculock @acsmem @acsfd
+@c   socket dup @acsfd
+@c   libc_lock_lock dup @asulock @aculock
+@c   ifreq @ascuheap @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   if_nextreq dup ok
+@c   ioctl dup ok
+@c   realloc dup @ascuheap @acsmem
+@c   if_freereq dup @acsmem
+@c   libc_lock_unlock dup @aculock
+@c   close dup @acsfd
+The @code{gethostbyname_r} function returns information about the host
+named @var{name}.  The caller must pass a pointer to an object of type
+@code{struct hostent} in the @var{result_buf} parameter.  In addition
+the function may need extra buffer space and the caller must pass an
+pointer and the size of the buffer in the @var{buf} and @var{buflen}
+parameters.
+
+A pointer to the buffer, in which the result is stored, is available in
+@code{*@var{result}} after the function call successfully returned.  The
+buffer passed as the @var{buf} parameter can be freed only once the caller
+has finished with the result hostent struct, or has copied it including all
+the other memory that it points to.  If an error occurs or if no entry is
+found, the pointer @code{*@var{result}} is a null pointer.  Success is
+signalled by a zero return value.  If the function failed the return value
+is an error number.  In addition to the errors defined for
+@code{gethostbyname} it can also be @code{ERANGE}.  In this case the call
+should be repeated with a larger buffer.  Additional error information is
+not stored in the global variable @code{h_errno} but instead in the object
+pointed to by @var{h_errnop}.
+
+Here's a small example:
+@smallexample
+struct hostent *
+gethostname (char *host)
+@{
+  struct hostent *hostbuf, *hp;
+  size_t hstbuflen;
+  char *tmphstbuf;
+  int res;
+  int herr;
+
+  hostbuf = malloc (sizeof (struct hostent));
+  hstbuflen = 1024;
+  tmphstbuf = malloc (hstbuflen);
+
+  while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen,
+                                 &hp, &herr)) == ERANGE)
+    @{
+      /* Enlarge the buffer.  */
+      hstbuflen *= 2;
+      tmphstbuf = realloc (tmphstbuf, hstbuflen);
+    @}
+
+  free (tmphstbuf);
+  /*  Check for errors.  */
+  if (res || hp == NULL)
+    return NULL;
+  return hp;
+@}
+@end smallexample
+@end deftypefun
+
+@comment netdb.h
+@comment GNU
+@deftypefun int gethostbyname2_r (const char *@var{name}, int @var{af}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyname2_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  nss_hostname_digits_dots dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  nscd_gethostbyname2_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
+@c   nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
+@c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
+@c  nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_gethostbyname2_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
+The @code{gethostbyname2_r} function is like @code{gethostbyname_r}, but
+allows the caller to specify the desired address family (e.g.@:
+@code{AF_INET} or @code{AF_INET6}) for the result.
+@end deftypefun
+
+@comment netdb.h
+@comment GNU
+@deftypefun int gethostbyaddr_r (const void *@var{addr}, socklen_t @var{length}, int @var{format}, struct hostent *restrict @var{result_buf}, char *restrict @var{buf}, size_t @var{buflen}, struct hostent **restrict @var{result}, int *restrict @var{h_errnop})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c gethostbyaddr_r @mtsenv @mtslocale @ascudlopen @ascuplugin @asucorrupt @ascuheap @asulock @aculock @acucorrupt @acsmem @acsfd
+@c  memcmp dup ok
+@c  nscd_gethostbyaddr_r @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
+@c   nscd_gethst_r dup @mtsenv @ascuheap @asulock @aculock @acsfd @acsmem
+@c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  res_hconf_init dup @mtsenv @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem [no @asuinit:reshconf @acuinit:reshconf, conditionally called]
+@c  nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_gethostbyaddr_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  res_hconf_reorder_addrs dup @asulock @ascuheap @aculock @acsmem @acsfd
+@c  res_hconf_trim_domains @mtslocale
+@c   res_hconf_trim_domain @mtslocale
+@c    strlen dup ok
+@c    strcasecmp dup @mtslocale
+The @code{gethostbyaddr_r} function returns information about the host
+with Internet address @var{addr}.  The parameter @var{addr} is not
+really a pointer to char - it can be a pointer to an IPv4 or an IPv6
+address.  The @var{length} argument is the size (in bytes) of the address
+at @var{addr}.  @var{format} specifies the address format; for an IPv4
+Internet address, specify a value of @code{AF_INET}; for an IPv6
+Internet address, use @code{AF_INET6}.
+
+Similar to the @code{gethostbyname_r} function, the caller must provide
+buffers for the result and memory used internally.  In case of success
+the function returns zero.  Otherwise the value is an error number where
+@code{ERANGE} has the special meaning that the caller-provided buffer is
+too small.
+@end deftypefun
+
+You can also scan the entire hosts database one entry at a time using
+@code{sethostent}, @code{gethostent} and @code{endhostent}.  Be careful
+when using these functions because they are not reentrant.
+
+@comment netdb.h
+@comment BSD
+@deftypefun void sethostent (int @var{stayopen})
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c sethostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_setent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   set_h_errno dup ok
+@c   setup(nss_hosts_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *lookup_fct = nss_hosts_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:hostent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock dup @aculock
+This function opens the hosts database to begin scanning it.  You can
+then call @code{gethostent} to read the entries.
+
+@c There was a rumor that this flag has different meaning if using the DNS,
+@c but it appears this description is accurate in that case also.
+If the @var{stayopen} argument is nonzero, this sets a flag so that
+subsequent calls to @code{gethostbyname} or @code{gethostbyaddr} will
+not close the database (as they usually would).  This makes for more
+efficiency if you call those functions several times, by avoiding
+reopening the database for each call.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct hostent *} gethostent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtasurace{:hostentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c gethostent @mtasurace:hostent @mtasurace:hostentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent(gethostent_r) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   *func = gethostent_r dup @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c gethostent_r @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent_r(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   setup(nss_hosts_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:hostent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *sfct.f @mtasurace:hostent @ascuplugin
+@c  libc_lock_unlock dup @aculock
+
+This function returns the next entry in the hosts database.  It
+returns a null pointer if there are no more entries.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun void endhostent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:hostent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endhostent @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_endent(nss_hosts_lookup2) @mtasurace:hostent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:hostent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function closes the hosts database.
+@end deftypefun
+
+@node Ports
+@subsection Internet Ports
+@cindex port number
+
+A socket address in the Internet namespace consists of a machine's
+Internet address plus a @dfn{port number} which distinguishes the
+sockets on a given machine (for a given protocol).  Port numbers range
+from 0 to 65,535.
+
+Port numbers less than @code{IPPORT_RESERVED} are reserved for standard
+servers, such as @code{finger} and @code{telnet}.  There is a database
+that keeps track of these, and you can use the @code{getservbyname}
+function to map a service name onto a port number; see @ref{Services
+Database}.
+
+If you write a server that is not one of the standard ones defined in
+the database, you must choose a port number for it.  Use a number
+greater than @code{IPPORT_USERRESERVED}; such numbers are reserved for
+servers and won't ever be generated automatically by the system.
+Avoiding conflicts with servers being run by other users is up to you.
+
+When you use a socket without specifying its address, the system
+generates a port number for it.  This number is between
+@code{IPPORT_RESERVED} and @code{IPPORT_USERRESERVED}.
+
+On the Internet, it is actually legitimate to have two different
+sockets with the same port number, as long as they never both try to
+communicate with the same socket address (host address plus port
+number).  You shouldn't duplicate a port number except in special
+circumstances where a higher-level protocol requires it.  Normally,
+the system won't let you do it; @code{bind} normally insists on
+distinct port numbers.  To reuse a port number, you must set the
+socket option @code{SO_REUSEADDR}.  @xref{Socket-Level Options}.
+
+@pindex netinet/in.h
+These macros are defined in the header file @file{netinet/in.h}.
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro int IPPORT_RESERVED
+Port numbers less than @code{IPPORT_RESERVED} are reserved for
+superuser use.
+@end deftypevr
+
+@comment netinet/in.h
+@comment BSD
+@deftypevr Macro int IPPORT_USERRESERVED
+Port numbers greater than or equal to @code{IPPORT_USERRESERVED} are
+reserved for explicit use; they will never be allocated automatically.
+@end deftypevr
+
+@node Services Database
+@subsection The Services Database
+@cindex services database
+@cindex converting service name to port number
+@cindex converting port number to service name
+
+@pindex /etc/services
+The database that keeps track of ``well-known'' services is usually
+either the file @file{/etc/services} or an equivalent from a name server.
+You can use these utilities, declared in @file{netdb.h}, to access
+the services database.
+@pindex netdb.h
+
+@comment netdb.h
+@comment BSD
+@deftp {Data Type} {struct servent}
+This data type holds information about entries from the services database.
+It has the following members:
+
+@table @code
+@item char *s_name
+This is the ``official'' name of the service.
+
+@item char **s_aliases
+These are alternate names for the service, represented as an array of
+strings.  A null pointer terminates the array.
+
+@item int s_port
+This is the port number for the service.  Port numbers are given in
+network byte order; see @ref{Byte Order}.
+
+@item char *s_proto
+This is the name of the protocol to use with this service.
+@xref{Protocols Database}.
+@end table
+@end deftp
+
+To get information about a particular service, use the
+@code{getservbyname} or @code{getservbyport} functions.  The information
+is returned in a statically-allocated structure; you must copy the
+information if you need to save it across calls.
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct servent *} getservbyname (const char *@var{name}, const char *@var{proto})
+@safety{@prelim{}@mtunsafe{@mtasurace{:servbyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getservbyname =~ getpwuid @mtasurace:servbyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getservbyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getservbyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getservbyname_r @ascuheap @acsfd @acsmem
+@c   nscd_getserv_r @ascuheap @acsfd @acsmem
+@c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c    strlen dup ok
+@c    malloc dup @ascuheap @acsmem
+@c    mempcpy dup ok
+@c    memcpy dup ok
+@c    nscd_cache_search dup ok
+@c    nscd_open_socket dup @acsfd
+@c    readvall dup ok
+@c    readall dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref dup @ascuheap @acsmem
+@c    nscd_unmap dup @ascuheap @acsmem
+@c    free dup @ascuheap @acsmem
+@c  nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getservbyname_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getservbyname} function returns information about the
+service named @var{name} using protocol @var{proto}.  If it can't find
+such a service, it returns a null pointer.
+
+This function is useful for servers as well as for clients; servers
+use it to determine which port they should listen on (@pxref{Listening}).
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct servent *} getservbyport (int @var{port}, const char *@var{proto})
+@safety{@prelim{}@mtunsafe{@mtasurace{:servbyport} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getservbyport =~ getservbyname @mtasurace:servbyport @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getservbyport_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getservbyport_r =~ getservbyname_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getservbyport_r @ascuheap @acsfd @acsmem
+@c   nscd_getserv_r dup @ascuheap @acsfd @acsmem
+@c  nss_services_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getservbyport_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getservbyport} function returns information about the
+service at port @var{port} using protocol @var{proto}.  If it can't
+find such a service, it returns a null pointer.
+@end deftypefun
+
+@noindent
+You can also scan the services database using @code{setservent},
+@code{getservent} and @code{endservent}.  Be careful when using these
+functions because they are not reentrant.
+
+@comment netdb.h
+@comment BSD
+@deftypefun void setservent (int @var{stayopen})
+@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_setent(nss_services_lookup2) @mtasurace:servenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_services_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *lookup_fct = nss_services_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:servent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock dup @aculock
+This function opens the services database to begin scanning it.
+
+If the @var{stayopen} argument is nonzero, this sets a flag so that
+subsequent calls to @code{getservbyname} or @code{getservbyport} will
+not close the database (as they usually would).  This makes for more
+efficiency if you call those functions several times, by avoiding
+reopening the database for each call.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct servent *} getservent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtasurace{:serventbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getservent @mtasurace:servent @mtasurace:serventbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent(getservent_r) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   *func = getservent_r dup @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getservent_r @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent_r(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:servent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *sfct.f @mtasurace:servent @ascuplugin
+@c  libc_lock_unlock dup @aculock
+This function returns the next entry in the services database.  If
+there are no more entries, it returns a null pointer.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun void endservent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:servent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endservent @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_endent(nss_services_lookup2) @mtasurace:servent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_services_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:servent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function closes the services database.
+@end deftypefun
+
+@node Byte Order
+@subsection Byte Order Conversion
+@cindex byte order conversion, for socket
+@cindex converting byte order
+
+@cindex big-endian
+@cindex little-endian
+Different kinds of computers use different conventions for the
+ordering of bytes within a word.  Some computers put the most
+significant byte within a word first (this is called ``big-endian''
+order), and others put it last (``little-endian'' order).
+
+@cindex network byte order
+So that machines with different byte order conventions can
+communicate, the Internet protocols specify a canonical byte order
+convention for data transmitted over the network.  This is known
+as @dfn{network byte order}.
+
+When establishing an Internet socket connection, you must make sure that
+the data in the @code{sin_port} and @code{sin_addr} members of the
+@code{sockaddr_in} structure are represented in network byte order.
+If you are encoding integer data in the messages sent through the
+socket, you should convert this to network byte order too.  If you don't
+do this, your program may fail when running on or talking to other kinds
+of machines.
+
+If you use @code{getservbyname} and @code{gethostbyname} or
+@code{inet_addr} to get the port number and host address, the values are
+already in network byte order, and you can copy them directly into
+the @code{sockaddr_in} structure.
+
+Otherwise, you have to convert the values explicitly.  Use @code{htons}
+and @code{ntohs} to convert values for the @code{sin_port} member.  Use
+@code{htonl} and @code{ntohl} to convert IPv4 addresses for the
+@code{sin_addr} member.  (Remember, @code{struct in_addr} is equivalent
+to @code{uint32_t}.)  These functions are declared in
+@file{netinet/in.h}.
+@pindex netinet/in.h
+
+@comment netinet/in.h
+@comment BSD
+@deftypefun {uint16_t} htons (uint16_t @var{hostshort})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c htons ok
+@c  bswap_16 ok
+@c   bswap_constant_16 ok
+
+This function converts the @code{uint16_t} integer @var{hostshort} from
+host byte order to network byte order.
+@end deftypefun
+
+@comment netinet/in.h
+@comment BSD
+@deftypefun {uint16_t} ntohs (uint16_t @var{netshort})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias to htons.
+This function converts the @code{uint16_t} integer @var{netshort} from
+network byte order to host byte order.
+@end deftypefun
+
+@comment netinet/in.h
+@comment BSD
+@deftypefun {uint32_t} htonl (uint32_t @var{hostlong})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c htonl ok
+@c  bswap_32 dup ok
+This function converts the @code{uint32_t} integer @var{hostlong} from
+host byte order to network byte order.
+
+This is used for IPv4 Internet addresses.
+@end deftypefun
+
+@comment netinet/in.h
+@comment BSD
+@deftypefun {uint32_t} ntohl (uint32_t @var{netlong})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias to htonl.
+This function converts the @code{uint32_t} integer @var{netlong} from
+network byte order to host byte order.
+
+This is used for IPv4 Internet addresses.
+@end deftypefun
+
+@node Protocols Database
+@subsection Protocols Database
+@cindex protocols database
+
+The communications protocol used with a socket controls low-level
+details of how data are exchanged.  For example, the protocol implements
+things like checksums to detect errors in transmissions, and routing
+instructions for messages.  Normal user programs have little reason to
+mess with these details directly.
+
+@cindex TCP (Internet protocol)
+The default communications protocol for the Internet namespace depends on
+the communication style.  For stream communication, the default is TCP
+(``transmission control protocol'').  For datagram communication, the
+default is UDP (``user datagram protocol'').  For reliable datagram
+communication, the default is RDP (``reliable datagram protocol'').
+You should nearly always use the default.
+
+@pindex /etc/protocols
+Internet protocols are generally specified by a name instead of a
+number.  The network protocols that a host knows about are stored in a
+database.  This is usually either derived from the file
+@file{/etc/protocols}, or it may be an equivalent provided by a name
+server.  You look up the protocol number associated with a named
+protocol in the database using the @code{getprotobyname} function.
+
+Here are detailed descriptions of the utilities for accessing the
+protocols database.  These are declared in @file{netdb.h}.
+@pindex netdb.h
+
+@comment netdb.h
+@comment BSD
+@deftp {Data Type} {struct protoent}
+This data type is used to represent entries in the network protocols
+database.  It has the following members:
+
+@table @code
+@item char *p_name
+This is the official name of the protocol.
+
+@item char **p_aliases
+These are alternate names for the protocol, specified as an array of
+strings.  The last element of the array is a null pointer.
+
+@item int p_proto
+This is the protocol number (in host byte order); use this member as the
+@var{protocol} argument to @code{socket}.
+@end table
+@end deftp
+
+You can use @code{getprotobyname} and @code{getprotobynumber} to search
+the protocols database for a specific protocol.  The information is
+returned in a statically-allocated structure; you must copy the
+information if you need to save it across calls.
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct protoent *} getprotobyname (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:protobyname} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getprotobyname =~ getpwuid @mtasurace:protobyname @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getprotobyname_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getprotobyname_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   no nscd support
+@c  nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getprotobyname_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getprotobyname} function returns information about the
+network protocol named @var{name}.  If there is no such protocol, it
+returns a null pointer.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct protoent *} getprotobynumber (int @var{protocol})
+@safety{@prelim{}@mtunsafe{@mtasurace{:protobynumber} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getprotobynumber =~ getpwuid @mtasurace:protobynumber @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getprotobynumber_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getprotobynumber_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   no nscd support
+@c  nss_protocols_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getprotobynumber_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getprotobynumber} function returns information about the
+network protocol with number @var{protocol}.  If there is no such
+protocol, it returns a null pointer.
+@end deftypefun
+
+You can also scan the whole protocols database one protocol at a time by
+using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}.
+Be careful when using these functions because they are not reentrant.
+
+@comment netdb.h
+@comment BSD
+@deftypefun void setprotoent (int @var{stayopen})
+@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_setent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_protocols_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *lookup_fct = nss_protocols_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:protoent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock dup @aculock
+This function opens the protocols database to begin scanning it.
+
+If the @var{stayopen} argument is nonzero, this sets a flag so that
+subsequent calls to @code{getprotobyname} or @code{getprotobynumber} will
+not close the database (as they usually would).  This makes for more
+efficiency if you call those functions several times, by avoiding
+reopening the database for each call.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct protoent *} getprotoent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtasurace{:protoentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getprotoent @mtasurace:protoent @mtasurace:protoentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent(getprotoent_r) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   *func = getprotoent_r dup @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getprotoent_r @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent_r(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:servent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *sfct.f @mtasurace:protoent @ascuplugin
+@c  libc_lock_unlock dup @aculock
+This function returns the next entry in the protocols database.  It
+returns a null pointer if there are no more entries.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun void endprotoent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:protoent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endprotoent @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_endent(nss_protocols_lookup2) @mtasurace:protoent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_protocols_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:protoent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function closes the protocols database.
+@end deftypefun
+
+@node Inet Example
+@subsection Internet Socket Example
+
+Here is an example showing how to create and name a socket in the
+Internet namespace.  The newly created socket exists on the machine that
+the program is running on.  Rather than finding and using the machine's
+Internet address, this example specifies @code{INADDR_ANY} as the host
+address; the system replaces that with the machine's actual address.
+
+@smallexample
+@include mkisock.c.texi
+@end smallexample
+
+Here is another example, showing how you can fill in a @code{sockaddr_in}
+structure, given a host name string and a port number:
+
+@smallexample
+@include isockad.c.texi
+@end smallexample
+
+@node Misc Namespaces
+@section Other Namespaces
+
+@vindex PF_NS
+@vindex PF_ISO
+@vindex PF_CCITT
+@vindex PF_IMPLINK
+@vindex PF_ROUTE
+Certain other namespaces and associated protocol families are supported
+but not documented yet because they are not often used.  @code{PF_NS}
+refers to the Xerox Network Software protocols.  @code{PF_ISO} stands
+for Open Systems Interconnect.  @code{PF_CCITT} refers to protocols from
+CCITT.  @file{socket.h} defines these symbols and others naming protocols
+not actually implemented.
+
+@code{PF_IMPLINK} is used for communicating between hosts and Internet
+Message Processors.  For information on this and @code{PF_ROUTE}, an
+occasionally-used local area routing protocol, see the GNU Hurd Manual
+(to appear in the future).
+
+@node Open/Close Sockets
+@section Opening and Closing Sockets
+
+This section describes the actual library functions for opening and
+closing sockets.  The same functions work for all namespaces and
+connection styles.
+
+@menu
+* Creating a Socket::           How to open a socket.
+* Closing a Socket::            How to close a socket.
+* Socket Pairs::                These are created like pipes.
+@end menu
+
+@node Creating a Socket
+@subsection Creating a Socket
+@cindex creating a socket
+@cindex socket, creating
+@cindex opening a socket
+
+The primitive for creating a socket is the @code{socket} function,
+declared in @file{sys/socket.h}.
+@pindex sys/socket.h
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int socket (int @var{namespace}, int @var{style}, int @var{protocol})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+This function creates a socket and specifies communication style
+@var{style}, which should be one of the socket styles listed in
+@ref{Communication Styles}.  The @var{namespace} argument specifies
+the namespace; it must be @code{PF_LOCAL} (@pxref{Local Namespace}) or
+@code{PF_INET} (@pxref{Internet Namespace}).  @var{protocol}
+designates the specific protocol (@pxref{Socket Concepts}); zero is
+usually right for @var{protocol}.
+
+The return value from @code{socket} is the file descriptor for the new
+socket, or @code{-1} in case of error.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EPROTONOSUPPORT
+The @var{protocol} or @var{style} is not supported by the
+@var{namespace} specified.
+
+@item EMFILE
+The process already has too many file descriptors open.
+
+@item ENFILE
+The system already has too many file descriptors open.
+
+@item EACCES
+The process does not have the privilege to create a socket of the specified
+@var{style} or @var{protocol}.
+
+@item ENOBUFS
+The system ran out of internal buffer space.
+@end table
+
+The file descriptor returned by the @code{socket} function supports both
+read and write operations.  However, like pipes, sockets do not support file
+positioning operations.
+@end deftypefun
+
+For examples of how to call the @code{socket} function,
+see @ref{Local Socket Example}, or @ref{Inet Example}.
+
+
+@node Closing a Socket
+@subsection Closing a Socket
+@cindex socket, closing
+@cindex closing a socket
+@cindex shutting down a socket
+@cindex socket shutdown
+
+When you have finished using a socket, you can simply close its
+file descriptor with @code{close}; see @ref{Opening and Closing Files}.
+If there is still data waiting to be transmitted over the connection,
+normally @code{close} tries to complete this transmission.  You
+can control this behavior using the @code{SO_LINGER} socket option to
+specify a timeout period; see @ref{Socket Options}.
+
+@pindex sys/socket.h
+You can also shut down only reception or transmission on a
+connection by calling @code{shutdown}, which is declared in
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int shutdown (int @var{socket}, int @var{how})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{shutdown} function shuts down the connection of socket
+@var{socket}.  The argument @var{how} specifies what action to
+perform:
+
+@table @code
+@item 0
+Stop receiving data for this socket.  If further data arrives,
+reject it.
+
+@item 1
+Stop trying to transmit data from this socket.  Discard any data
+waiting to be sent.  Stop looking for acknowledgement of data already
+sent; don't retransmit it if it is lost.
+
+@item 2
+Stop both reception and transmission.
+@end table
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+@var{socket} is not a valid file descriptor.
+
+@item ENOTSOCK
+@var{socket} is not a socket.
+
+@item ENOTCONN
+@var{socket} is not connected.
+@end table
+@end deftypefun
+
+@node Socket Pairs
+@subsection Socket Pairs
+@cindex creating a socket pair
+@cindex socket pair
+@cindex opening a socket pair
+
+@pindex sys/socket.h
+A @dfn{socket pair} consists of a pair of connected (but unnamed)
+sockets.  It is very similar to a pipe and is used in much the same
+way.  Socket pairs are created with the @code{socketpair} function,
+declared in @file{sys/socket.h}.  A socket pair is much like a pipe; the
+main difference is that the socket pair is bidirectional, whereas the
+pipe has one input-only end and one output-only end (@pxref{Pipes and
+FIFOs}).
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int socketpair (int @var{namespace}, int @var{style}, int @var{protocol}, int @var{filedes}@t{[2]})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+This function creates a socket pair, returning the file descriptors in
+@code{@var{filedes}[0]} and @code{@var{filedes}[1]}.  The socket pair
+is a full-duplex communications channel, so that both reading and writing
+may be performed at either end.
+
+The @var{namespace}, @var{style} and @var{protocol} arguments are
+interpreted as for the @code{socket} function.  @var{style} should be
+one of the communication styles listed in @ref{Communication Styles}.
+The @var{namespace} argument specifies the namespace, which must be
+@code{AF_LOCAL} (@pxref{Local Namespace}); @var{protocol} specifies the
+communications protocol, but zero is the only meaningful value.
+
+If @var{style} specifies a connectionless communication style, then
+the two sockets you get are not @emph{connected}, strictly speaking,
+but each of them knows the other as the default destination address,
+so they can send packets to each other.
+
+The @code{socketpair} function returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined
+for this function:
+
+@table @code
+@item EMFILE
+The process has too many file descriptors open.
+
+@item EAFNOSUPPORT
+The specified namespace is not supported.
+
+@item EPROTONOSUPPORT
+The specified protocol is not supported.
+
+@item EOPNOTSUPP
+The specified protocol does not support the creation of socket pairs.
+@end table
+@end deftypefun
+
+@node Connections
+@section Using Sockets with Connections
+
+@cindex connection
+@cindex client
+@cindex server
+The most common communication styles involve making a connection to a
+particular other socket, and then exchanging data with that socket
+over and over.  Making a connection is asymmetric; one side (the
+@dfn{client}) acts to request a connection, while the other side (the
+@dfn{server}) makes a socket and waits for the connection request.
+
+@iftex
+@itemize @bullet
+@item
+@ref{Connecting}, describes what the client program must do to
+initiate a connection with a server.
+
+@item
+@ref{Listening} and @ref{Accepting Connections} describe what the
+server program must do to wait for and act upon connection requests
+from clients.
+
+@item
+@ref{Transferring Data}, describes how data are transferred through the
+connected socket.
+@end itemize
+@end iftex
+
+@menu
+* 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.
+@end menu
+
+@node Connecting
+@subsection Making a Connection
+@cindex connecting a socket
+@cindex socket, connecting
+@cindex socket, initiating a connection
+@cindex socket, client actions
+
+In making a connection, the client makes a connection while the server
+waits for and accepts the connection.  Here we discuss what the client
+program must do with the @code{connect} function, which is declared in
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{connect} function initiates a connection from the socket
+with file descriptor @var{socket} to the socket whose address is
+specified by the @var{addr} and @var{length} arguments.  (This socket
+is typically on another machine, and it must be already set up as a
+server.)  @xref{Socket Addresses}, for information about how these
+arguments are interpreted.
+
+Normally, @code{connect} waits until the server responds to the request
+before it returns.  You can set nonblocking mode on the socket
+@var{socket} to make @code{connect} return immediately without waiting
+for the response.  @xref{File Status Flags}, for information about
+nonblocking mode.
+@c !!! how do you tell when it has finished connecting?  I suspect the
+@c way you do it is select for writing.
+
+The normal return value from @code{connect} is @code{0}.  If an error
+occurs, @code{connect} returns @code{-1}.  The following @code{errno}
+error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The socket @var{socket} is not a valid file descriptor.
+
+@item ENOTSOCK
+File descriptor @var{socket} is not a socket.
+
+@item EADDRNOTAVAIL
+The specified address is not available on the remote machine.
+
+@item EAFNOSUPPORT
+The namespace of the @var{addr} is not supported by this socket.
+
+@item EISCONN
+The socket @var{socket} is already connected.
+
+@item ETIMEDOUT
+The attempt to establish the connection timed out.
+
+@item ECONNREFUSED
+The server has actively refused to establish the connection.
+
+@item ENETUNREACH
+The network of the given @var{addr} isn't reachable from this host.
+
+@item EADDRINUSE
+The socket address of the given @var{addr} is already in use.
+
+@item EINPROGRESS
+The socket @var{socket} is non-blocking and the connection could not be
+established immediately.  You can determine when the connection is
+completely established with @code{select}; @pxref{Waiting for I/O}.
+Another @code{connect} call on the same socket, before the connection is
+completely established, will fail with @code{EALREADY}.
+
+@item EALREADY
+The socket @var{socket} is non-blocking and already has a pending
+connection in progress (see @code{EINPROGRESS} above).
+@end table
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+@node Listening
+@subsection Listening for Connections
+@cindex listening (sockets)
+@cindex sockets, server actions
+@cindex sockets, listening
+
+Now let us consider what the server process must do to accept
+connections on a socket.  First it must use the @code{listen} function
+to enable connection requests on the socket, and then accept each
+incoming connection with a call to @code{accept} (@pxref{Accepting
+Connections}).  Once connection requests are enabled on a server socket,
+the @code{select} function reports when the socket has a connection
+ready to be accepted (@pxref{Waiting for I/O}).
+
+The @code{listen} function is not allowed for sockets using
+connectionless communication styles.
+
+You can write a network server that does not even start running until a
+connection to it is requested.  @xref{Inetd Servers}.
+
+In the Internet namespace, there are no special protection mechanisms
+for controlling access to a port; any process on any machine
+can make a connection to your server.  If you want to restrict access to
+your server, make it examine the addresses associated with connection
+requests or implement some other handshaking or identification
+protocol.
+
+In the local namespace, the ordinary file protection bits control who has
+access to connect to the socket.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int listen (int @var{socket}, int @var{n})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+The @code{listen} function enables the socket @var{socket} to accept
+connections, thus making it a server socket.
+
+The argument @var{n} specifies the length of the queue for pending
+connections.  When the queue fills, new clients attempting to connect
+fail with @code{ECONNREFUSED} until the server calls @code{accept} to
+accept a connection from the queue.
+
+The @code{listen} function returns @code{0} on success and @code{-1}
+on failure.  The following @code{errno} error conditions are defined
+for this function:
+
+@table @code
+@item EBADF
+The argument @var{socket} is not a valid file descriptor.
+
+@item ENOTSOCK
+The argument @var{socket} is not a socket.
+
+@item EOPNOTSUPP
+The socket @var{socket} does not support this operation.
+@end table
+@end deftypefun
+
+@node Accepting Connections
+@subsection Accepting Connections
+@cindex sockets, accepting connections
+@cindex accepting connections
+
+When a server receives a connection request, it can complete the
+connection by accepting the request.  Use the function @code{accept}
+to do this.
+
+A socket that has been established as a server can accept connection
+requests from multiple clients.  The server's original socket
+@emph{does not become part of the connection}; instead, @code{accept}
+makes a new socket which participates in the connection.
+@code{accept} returns the descriptor for this socket.  The server's
+original socket remains available for listening for further connection
+requests.
+
+The number of pending connection requests on a server socket is finite.
+If connection requests arrive from clients faster than the server can
+act upon them, the queue can fill up and additional requests are refused
+with an @code{ECONNREFUSED} error.  You can specify the maximum length of
+this queue as an argument to the @code{listen} function, although the
+system may also impose its own internal limit on the length of this
+queue.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length_ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+This function is used to accept a connection request on the server
+socket @var{socket}.
+
+The @code{accept} function waits if there are no connections pending,
+unless the socket @var{socket} has nonblocking mode set.  (You can use
+@code{select} to wait for a pending connection, with a nonblocking
+socket.)  @xref{File Status Flags}, for information about nonblocking
+mode.
+
+The @var{addr} and @var{length-ptr} arguments are used to return
+information about the name of the client socket that initiated the
+connection.  @xref{Socket Addresses}, for information about the format
+of the information.
+
+Accepting a connection does not make @var{socket} part of the
+connection.  Instead, it creates a new socket which becomes
+connected.  The normal return value of @code{accept} is the file
+descriptor for the new socket.
+
+After @code{accept}, the original socket @var{socket} remains open and
+unconnected, and continues listening until you close it.  You can
+accept further connections with @var{socket} by calling @code{accept}
+again.
+
+If an error occurs, @code{accept} returns @code{-1}.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} argument is not a socket.
+
+@item EOPNOTSUPP
+The descriptor @var{socket} does not support this operation.
+
+@item EWOULDBLOCK
+@var{socket} has nonblocking mode set, and there are no pending
+connections immediately available.
+@end table
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+The @code{accept} function is not allowed for sockets using
+connectionless communication styles.
+
+@node Who is Connected
+@subsection Who is Connected to Me?
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int getpeername (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getpeername} function returns the address of the socket that
+@var{socket} is connected to; it stores the address in the memory space
+specified by @var{addr} and @var{length-ptr}.  It stores the length of
+the address in @code{*@var{length-ptr}}.
+
+@xref{Socket Addresses}, for information about the format of the
+address.  In some operating systems, @code{getpeername} works only for
+sockets in the Internet domain.
+
+The return value is @code{0} on success and @code{-1} on error.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The argument @var{socket} is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item ENOTCONN
+The socket @var{socket} is not connected.
+
+@item ENOBUFS
+There are not enough internal buffers available.
+@end table
+@end deftypefun
+
+
+@node Transferring Data
+@subsection Transferring Data
+@cindex reading from a socket
+@cindex writing to a socket
+
+Once a socket has been connected to a peer, you can use the ordinary
+@code{read} and @code{write} operations (@pxref{I/O Primitives}) to
+transfer data.  A socket is a two-way communications channel, so read
+and write operations can be performed at either end.
+
+There are also some I/O modes that are specific to socket operations.
+In order to specify these modes, you must use the @code{recv} and
+@code{send} functions instead of the more generic @code{read} and
+@code{write} functions.  The @code{recv} and @code{send} functions take
+an additional argument which you can use to specify various flags to
+control special I/O modes.  For example, you can specify the
+@code{MSG_OOB} flag to read or write out-of-band data, the
+@code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag
+to control inclusion of routing information on output.
+
+@menu
+* Sending Data::		Sending data with @code{send}.
+* Receiving Data::		Reading data with @code{recv}.
+* Socket Data Options::		Using @code{send} and @code{recv}.
+@end menu
+
+@node Sending Data
+@subsubsection Sending Data
+
+@pindex sys/socket.h
+The @code{send} function is declared in the header file
+@file{sys/socket.h}.  If your @var{flags} argument is zero, you can just
+as well use @code{write} instead of @code{send}; see @ref{I/O
+Primitives}.  If the socket was connected but the connection has broken,
+you get a @code{SIGPIPE} signal for any use of @code{send} or
+@code{write} (@pxref{Miscellaneous Signals}).
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t send (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{send} function is like @code{write}, but with the additional
+flags @var{flags}.  The possible values of @var{flags} are described
+in @ref{Socket Data Options}.
+
+This function returns the number of bytes transmitted, or @code{-1} on
+failure.  If the socket is nonblocking, then @code{send} (like
+@code{write}) can return after sending just part of the data.
+@xref{File Status Flags}, for information about nonblocking mode.
+
+Note, however, that a successful return value merely indicates that
+the message has been sent without error, not necessarily that it has
+been received without error.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item EINTR
+The operation was interrupted by a signal before any data was sent.
+@xref{Interrupted Primitives}.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item EMSGSIZE
+The socket type requires that the message be sent atomically, but the
+message is too large for this to be possible.
+
+@item EWOULDBLOCK
+Nonblocking mode has been set on the socket, and the write operation
+would block.  (Normally @code{send} blocks until the operation can be
+completed.)
+
+@item ENOBUFS
+There is not enough internal buffer space available.
+
+@item ENOTCONN
+You never connected this socket.
+
+@item EPIPE
+This socket was connected but the connection is now broken.  In this
+case, @code{send} generates a @code{SIGPIPE} signal first; if that
+signal is ignored or blocked, or if its handler returns, then
+@code{send} fails with @code{EPIPE}.
+@end table
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+@node Receiving Data
+@subsubsection Receiving Data
+
+@pindex sys/socket.h
+The @code{recv} function is declared in the header file
+@file{sys/socket.h}.  If your @var{flags} argument is zero, you can
+just as well use @code{read} instead of @code{recv}; see @ref{I/O
+Primitives}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t recv (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{recv} function is like @code{read}, but with the additional
+flags @var{flags}.  The possible values of @var{flags} are described
+in @ref{Socket Data Options}.
+
+If nonblocking mode is set for @var{socket}, and no data are available to
+be read, @code{recv} fails immediately rather than waiting.  @xref{File
+Status Flags}, for information about nonblocking mode.
+
+This function returns the number of bytes received, or @code{-1} on failure.
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item EWOULDBLOCK
+Nonblocking mode has been set on the socket, and the read operation
+would block.  (Normally, @code{recv} blocks until there is input
+available to be read.)
+
+@item EINTR
+The operation was interrupted by a signal before any data was read.
+@xref{Interrupted Primitives}.
+
+@item ENOTCONN
+You never connected this socket.
+@end table
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+@node Socket Data Options
+@subsubsection Socket Data Options
+
+@pindex sys/socket.h
+The @var{flags} argument to @code{send} and @code{recv} is a bit
+mask.  You can bitwise-OR the values of the following macros together
+to obtain a value for this argument.  All are defined in the header
+file @file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int MSG_OOB
+Send or receive out-of-band data.  @xref{Out-of-Band Data}.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int MSG_PEEK
+Look at the data but don't remove it from the input queue.  This is
+only meaningful with input functions such as @code{recv}, not with
+@code{send}.
+@end deftypevr
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Macro int MSG_DONTROUTE
+Don't include routing information in the message.  This is only
+meaningful with output operations, and is usually only of interest for
+diagnostic or routing programs.  We don't try to explain it here.
+@end deftypevr
+
+@node Byte Stream Example
+@subsection Byte Stream Socket Example
+
+Here is an example client program that makes a connection for a byte
+stream socket in the Internet namespace.  It doesn't do anything
+particularly interesting once it has connected to the server; it just
+sends a text string to the server and exits.
+
+This program uses @code{init_sockaddr} to set up the socket address; see
+@ref{Inet Example}.
+
+@smallexample
+@include inetcli.c.texi
+@end smallexample
+
+@node Server Example
+@subsection Byte Stream Connection Server Example
+
+The server end is much more complicated.  Since we want to allow
+multiple clients to be connected to the server at the same time, it
+would be incorrect to wait for input from a single client by simply
+calling @code{read} or @code{recv}.  Instead, the right thing to do is
+to use @code{select} (@pxref{Waiting for I/O}) to wait for input on
+all of the open sockets.  This also allows the server to deal with
+additional connection requests.
+
+This particular server doesn't do anything interesting once it has
+gotten a message from a client.  It does close the socket for that
+client when it detects an end-of-file condition (resulting from the
+client shutting down its end of the connection).
+
+This program uses @code{make_socket} to set up the socket address; see
+@ref{Inet Example}.
+
+@smallexample
+@include inetsrv.c.texi
+@end smallexample
+
+@node Out-of-Band Data
+@subsection Out-of-Band Data
+
+@cindex out-of-band data
+@cindex high-priority data
+Streams with connections permit @dfn{out-of-band} data that is
+delivered with higher priority than ordinary data.  Typically the
+reason for sending out-of-band data is to send notice of an
+exceptional condition.  To send out-of-band data use
+@code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending
+Data}).
+
+Out-of-band data are received with higher priority because the
+receiving process need not read it in sequence; to read the next
+available out-of-band data, use @code{recv} with the @code{MSG_OOB}
+flag (@pxref{Receiving Data}).  Ordinary read operations do not read
+out-of-band data; they read only ordinary data.
+
+@cindex urgent socket condition
+When a socket finds that out-of-band data are on their way, it sends a
+@code{SIGURG} signal to the owner process or process group of the
+socket.  You can specify the owner using the @code{F_SETOWN} command
+to the @code{fcntl} function; see @ref{Interrupt Input}.  You must
+also establish a handler for this signal, as described in @ref{Signal
+Handling}, in order to take appropriate action such as reading the
+out-of-band data.
+
+Alternatively, you can test for pending out-of-band data, or wait
+until there is out-of-band data, using the @code{select} function; it
+can wait for an exceptional condition on the socket.  @xref{Waiting
+for I/O}, for more information about @code{select}.
+
+Notification of out-of-band data (whether with @code{SIGURG} or with
+@code{select}) indicates that out-of-band data are on the way; the data
+may not actually arrive until later.  If you try to read the
+out-of-band data before it arrives, @code{recv} fails with an
+@code{EWOULDBLOCK} error.
+
+Sending out-of-band data automatically places a ``mark'' in the stream
+of ordinary data, showing where in the sequence the out-of-band data
+``would have been''.  This is useful when the meaning of out-of-band
+data is ``cancel everything sent so far''.  Here is how you can test,
+in the receiving process, whether any ordinary data was sent before
+the mark:
+
+@smallexample
+success = ioctl (socket, SIOCATMARK, &atmark);
+@end smallexample
+
+The @code{integer} variable @var{atmark} is set to a nonzero value if
+the socket's read pointer has reached the ``mark''.
+
+@c Posix  1.g specifies sockatmark for this ioctl.  sockatmark is not
+@c implemented yet.
+
+Here's a function to discard any ordinary data preceding the
+out-of-band mark:
+
+@smallexample
+int
+discard_until_mark (int socket)
+@{
+  while (1)
+    @{
+      /* @r{This is not an arbitrary limit; any size will do.}  */
+      char buffer[1024];
+      int atmark, success;
+
+      /* @r{If we have reached the mark, return.}  */
+      success = ioctl (socket, SIOCATMARK, &atmark);
+      if (success < 0)
+        perror ("ioctl");
+      if (result)
+        return;
+
+      /* @r{Otherwise, read a bunch of ordinary data and discard it.}
+         @r{This is guaranteed not to read past the mark}
+         @r{if it starts before the mark.}  */
+      success = read (socket, buffer, sizeof buffer);
+      if (success < 0)
+        perror ("read");
+    @}
+@}
+@end smallexample
+
+If you don't want to discard the ordinary data preceding the mark, you
+may need to read some of it anyway, to make room in internal system
+buffers for the out-of-band data.  If you try to read out-of-band data
+and get an @code{EWOULDBLOCK} error, try reading some ordinary data
+(saving it so that you can use it when you want it) and see if that
+makes room.  Here is an example:
+
+@smallexample
+struct buffer
+@{
+  char *buf;
+  int size;
+  struct buffer *next;
+@};
+
+/* @r{Read the out-of-band data from SOCKET and return it}
+   @r{as a `struct buffer', which records the address of the data}
+   @r{and its size.}
+
+   @r{It may be necessary to read some ordinary data}
+   @r{in order to make room for the out-of-band data.}
+   @r{If so, the ordinary data are saved as a chain of buffers}
+   @r{found in the `next' field of the value.}  */
+
+struct buffer *
+read_oob (int socket)
+@{
+  struct buffer *tail = 0;
+  struct buffer *list = 0;
+
+  while (1)
+    @{
+      /* @r{This is an arbitrary limit.}
+         @r{Does anyone know how to do this without a limit?}  */
+#define BUF_SZ 1024
+      char *buf = (char *) xmalloc (BUF_SZ);
+      int success;
+      int atmark;
+
+      /* @r{Try again to read the out-of-band data.}  */
+      success = recv (socket, buf, BUF_SZ, MSG_OOB);
+      if (success >= 0)
+        @{
+          /* @r{We got it, so return it.}  */
+          struct buffer *link
+            = (struct buffer *) xmalloc (sizeof (struct buffer));
+          link->buf = buf;
+          link->size = success;
+          link->next = list;
+          return link;
+        @}
+
+      /* @r{If we fail, see if we are at the mark.}  */
+      success = ioctl (socket, SIOCATMARK, &atmark);
+      if (success < 0)
+        perror ("ioctl");
+      if (atmark)
+        @{
+          /* @r{At the mark; skipping past more ordinary data cannot help.}
+             @r{So just wait a while.}  */
+          sleep (1);
+          continue;
+        @}
+
+      /* @r{Otherwise, read a bunch of ordinary data and save it.}
+         @r{This is guaranteed not to read past the mark}
+         @r{if it starts before the mark.}  */
+      success = read (socket, buf, BUF_SZ);
+      if (success < 0)
+        perror ("read");
+
+      /* @r{Save this data in the buffer list.}  */
+      @{
+        struct buffer *link
+          = (struct buffer *) xmalloc (sizeof (struct buffer));
+        link->buf = buf;
+        link->size = success;
+
+        /* @r{Add the new link to the end of the list.}  */
+        if (tail)
+          tail->next = link;
+        else
+          list = link;
+        tail = link;
+      @}
+    @}
+@}
+@end smallexample
+
+@node Datagrams
+@section Datagram Socket Operations
+
+@cindex datagram socket
+This section describes how to use communication styles that don't use
+connections (styles @code{SOCK_DGRAM} and @code{SOCK_RDM}).  Using
+these styles, you group data into packets and each packet is an
+independent communication.  You specify the destination for each
+packet individually.
+
+Datagram packets are like letters: you send each one independently
+with its own destination address, and they may arrive in the wrong
+order or not at all.
+
+The @code{listen} and @code{accept} functions are not allowed for
+sockets using connectionless communication styles.
+
+@menu
+* 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.
+@end menu
+
+@node Sending Datagrams
+@subsection Sending Datagrams
+@cindex sending a datagram
+@cindex transmitting datagrams
+@cindex datagrams, transmitting
+
+@pindex sys/socket.h
+The normal way of sending data on a datagram socket is by using the
+@code{sendto} function, declared in @file{sys/socket.h}.
+
+You can call @code{connect} on a datagram socket, but this only
+specifies a default destination for further data transmission on the
+socket.  When a socket has a default destination you can use
+@code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O
+Primitives}) to send a packet there.  You can cancel the default
+destination by calling @code{connect} using an address format of
+@code{AF_UNSPEC} in the @var{addr} argument.  @xref{Connecting}, for
+more information about the @code{connect} function.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t sendto (int @var{socket}, const void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{sendto} function transmits the data in the @var{buffer}
+through the socket @var{socket} to the destination address specified
+by the @var{addr} and @var{length} arguments.  The @var{size} argument
+specifies the number of bytes to be transmitted.
+
+The @var{flags} are interpreted the same way as for @code{send}; see
+@ref{Socket Data Options}.
+
+The return value and error conditions are also the same as for
+@code{send}, but you cannot rely on the system to detect errors and
+report them; the most common error is that the packet is lost or there
+is no-one at the specified address to receive it, and the operating
+system on your machine usually does not know this.
+
+It is also possible for one call to @code{sendto} to report an error
+owing to a problem related to a previous call.
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+@node Receiving Datagrams
+@subsection Receiving Datagrams
+@cindex receiving datagrams
+
+The @code{recvfrom} function reads a packet from a datagram socket and
+also tells you where it was sent from.  This function is declared in
+@file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{recvfrom} function reads one packet from the socket
+@var{socket} into the buffer @var{buffer}.  The @var{size} argument
+specifies the maximum number of bytes to be read.
+
+If the packet is longer than @var{size} bytes, then you get the first
+@var{size} bytes of the packet and the rest of the packet is lost.
+There's no way to read the rest of the packet.  Thus, when you use a
+packet protocol, you must always know how long a packet to expect.
+
+The @var{addr} and @var{length-ptr} arguments are used to return the
+address where the packet came from.  @xref{Socket Addresses}.  For a
+socket in the local domain the address information won't be meaningful,
+since you can't read the address of such a socket (@pxref{Local
+Namespace}).  You can specify a null pointer as the @var{addr} argument
+if you are not interested in this information.
+
+The @var{flags} are interpreted the same way as for @code{recv}
+(@pxref{Socket Data Options}).  The return value and error conditions
+are also the same as for @code{recv}.
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+You can use plain @code{recv} (@pxref{Receiving Data}) instead of
+@code{recvfrom} if you don't need to find out who sent the packet
+(either because you know where it should come from or because you
+treat all possible senders alike).  Even @code{read} can be used if
+you don't want to specify @var{flags} (@pxref{I/O Primitives}).
+
+@ignore
+@c sendmsg and recvmsg are like readv and writev in that they
+@c use a series of buffers.  It's not clear this is worth
+@c supporting or that we support them.
+@c !!! they can do more; it is hairy
+
+@comment sys/socket.h
+@comment BSD
+@deftp {Data Type} {struct msghdr}
+@end deftp
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is cancel.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun ssize_t recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+This function is defined as a cancellation point in multi-threaded
+programs, so one has to be prepared for this and make sure that
+allocated resources (like memory, files descriptors, semaphores or
+whatever) are freed even if the thread is canceled.
+@c @xref{pthread_cleanup_push}, for a method how to do this.
+@end deftypefun
+@end ignore
+
+@node Datagram Example
+@subsection Datagram Socket Example
+
+Here is a set of example programs that send messages over a datagram
+stream in the local namespace.  Both the client and server programs use
+the @code{make_named_socket} function that was presented in @ref{Local
+Socket Example}, to create and name their sockets.
+
+First, here is the server program.  It sits in a loop waiting for
+messages to arrive, bouncing each message back to the sender.
+Obviously this isn't a particularly useful program, but it does show
+the general ideas involved.
+
+@smallexample
+@include filesrv.c.texi
+@end smallexample
+
+@node Example Receiver
+@subsection Example of Reading Datagrams
+
+Here is the client program corresponding to the server above.
+
+It sends a datagram to the server and then waits for a reply.  Notice
+that the socket for the client (as well as for the server) in this
+example has to be given a name.  This is so that the server can direct
+a message back to the client.  Since the socket has no associated
+connection state, the only way the server can do this is by
+referencing the name of the client.
+
+@smallexample
+@include filecli.c.texi
+@end smallexample
+
+Keep in mind that datagram socket communications are unreliable.  In
+this example, the client program waits indefinitely if the message
+never reaches the server or if the server's response never comes
+back.  It's up to the user running the program to kill and restart
+it if desired.  A more automatic solution could be to use
+@code{select} (@pxref{Waiting for I/O}) to establish a timeout period
+for the reply, and in case of timeout either re-send the message or
+shut down the socket and exit.
+
+@node Inetd
+@section The @code{inetd} Daemon
+
+We've explained above how to write a server program that does its own
+listening.  Such a server must already be running in order for anyone
+to connect to it.
+
+Another way to provide a service on an Internet port is to let the daemon
+program @code{inetd} do the listening.  @code{inetd} is a program that
+runs all the time and waits (using @code{select}) for messages on a
+specified set of ports.  When it receives a message, it accepts the
+connection (if the socket style calls for connections) and then forks a
+child process to run the corresponding server program.  You specify the
+ports and their programs in the file @file{/etc/inetd.conf}.
+
+@menu
+* Inetd Servers::
+* Configuring Inetd::
+@end menu
+
+@node Inetd Servers
+@subsection @code{inetd} Servers
+
+Writing a server program to be run by @code{inetd} is very simple.  Each time
+someone requests a connection to the appropriate port, a new server
+process starts.  The connection already exists at this time; the
+socket is available as the standard input descriptor and as the
+standard output descriptor (descriptors 0 and 1) in the server
+process.  Thus the server program can begin reading and writing data
+right away.  Often the program needs only the ordinary I/O facilities;
+in fact, a general-purpose filter program that knows nothing about
+sockets can work as a byte stream server run by @code{inetd}.
+
+You can also use @code{inetd} for servers that use connectionless
+communication styles.  For these servers, @code{inetd} does not try to accept
+a connection since no connection is possible.  It just starts the
+server program, which can read the incoming datagram packet from
+descriptor 0.  The server program can handle one request and then
+exit, or you can choose to write it to keep reading more requests
+until no more arrive, and then exit.  You must specify which of these
+two techniques the server uses when you configure @code{inetd}.
+
+@node Configuring Inetd
+@subsection Configuring @code{inetd}
+
+The file @file{/etc/inetd.conf} tells @code{inetd} which ports to listen to
+and what server programs to run for them.  Normally each entry in the
+file is one line, but you can split it onto multiple lines provided
+all but the first line of the entry start with whitespace.  Lines that
+start with @samp{#} are comments.
+
+Here are two standard entries in @file{/etc/inetd.conf}:
+
+@smallexample
+ftp	stream	tcp	nowait	root	/libexec/ftpd	ftpd
+talk	dgram	udp	wait	root	/libexec/talkd	talkd
+@end smallexample
+
+An entry has this format:
+
+@smallexample
+@var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
+@end smallexample
+
+The @var{service} field says which service this program provides.  It
+should be the name of a service defined in @file{/etc/services}.
+@code{inetd} uses @var{service} to decide which port to listen on for
+this entry.
+
+The fields @var{style} and @var{protocol} specify the communication
+style and the protocol to use for the listening socket.  The style
+should be the name of a communication style, converted to lower case
+and with @samp{SOCK_} deleted---for example, @samp{stream} or
+@samp{dgram}.  @var{protocol} should be one of the protocols listed in
+@file{/etc/protocols}.  The typical protocol names are @samp{tcp} for
+byte stream connections and @samp{udp} for unreliable datagrams.
+
+The @var{wait} field should be either @samp{wait} or @samp{nowait}.
+Use @samp{wait} if @var{style} is a connectionless style and the
+server, once started, handles multiple requests as they come in.
+Use @samp{nowait} if @code{inetd} should start a new process for each message
+or request that comes in.  If @var{style} uses connections, then
+@var{wait} @strong{must} be @samp{nowait}.
+
+@var{user} is the user name that the server should run as.  @code{inetd} runs
+as root, so it can set the user ID of its children arbitrarily.  It's
+best to avoid using @samp{root} for @var{user} if you can; but some
+servers, such as Telnet and FTP, read a username and password
+themselves.  These servers need to be root initially so they can log
+in as commanded by the data coming over the network.
+
+@var{program} together with @var{arguments} specifies the command to
+run to start the server.  @var{program} should be an absolute file
+name specifying the executable file to run.  @var{arguments} consists
+of any number of whitespace-separated words, which become the
+command-line arguments of @var{program}.  The first word in
+@var{arguments} is argument zero, which should by convention be the
+program name itself (sans directories).
+
+If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the
+file and obey its new contents by sending the @code{inetd} process the
+@code{SIGHUP} signal.  You'll have to use @code{ps} to determine the
+process ID of the @code{inetd} process as it is not fixed.
+
+@c !!! could document /etc/inetd.sec
+
+@node Socket Options
+@section Socket Options
+@cindex socket options
+
+This section describes how to read or set various options that modify
+the behavior of sockets and their underlying communications protocols.
+
+@cindex level, for socket options
+@cindex socket option level
+When you are manipulating a socket option, you must specify which
+@dfn{level} the option pertains to.  This describes whether the option
+applies to the socket interface, or to a lower-level communications
+protocol interface.
+
+@menu
+* Socket Option Functions::     The basic functions for setting and getting
+                                 socket options.
+* Socket-Level Options::        Details of the options at the socket level.
+@end menu
+
+@node Socket Option Functions
+@subsection Socket Option Functions
+
+@pindex sys/socket.h
+Here are the functions for examining and modifying socket options.
+They are declared in @file{sys/socket.h}.
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getsockopt} function gets information about the value of
+option @var{optname} at level @var{level} for socket @var{socket}.
+
+The option value is stored in a buffer that @var{optval} points to.
+Before the call, you should supply in @code{*@var{optlen-ptr}} the
+size of this buffer; on return, it contains the number of bytes of
+information actually stored in the buffer.
+
+Most options interpret the @var{optval} buffer as a single @code{int}
+value.
+
+The actual return value of @code{getsockopt} is @code{0} on success
+and @code{-1} on failure.  The following @code{errno} error conditions
+are defined:
+
+@table @code
+@item EBADF
+The @var{socket} argument is not a valid file descriptor.
+
+@item ENOTSOCK
+The descriptor @var{socket} is not a socket.
+
+@item ENOPROTOOPT
+The @var{optname} doesn't make sense for the given @var{level}.
+@end table
+@end deftypefun
+
+@comment sys/socket.h
+@comment BSD
+@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, const void *@var{optval}, socklen_t @var{optlen})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is used to set the socket option @var{optname} at level
+@var{level} for socket @var{socket}.  The value of the option is passed
+in the buffer @var{optval} of size @var{optlen}.
+
+@c Argh. -zw
+@iftex
+@hfuzz 6pt
+The return value and error codes for @code{setsockopt} are the same as
+for @code{getsockopt}.
+@end iftex
+@ifinfo
+The return value and error codes for @code{setsockopt} are the same as
+for @code{getsockopt}.
+@end ifinfo
+
+@end deftypefun
+
+@node Socket-Level Options
+@subsection Socket-Level Options
+
+@comment sys/socket.h
+@comment BSD
+@deftypevr Constant int SOL_SOCKET
+Use this constant as the @var{level} argument to @code{getsockopt} or
+@code{setsockopt} to manipulate the socket-level options described in
+this section.
+@end deftypevr
+
+@pindex sys/socket.h
+@noindent
+Here is a table of socket-level option names; all are defined in the
+header file @file{sys/socket.h}.
+
+@table @code
+@comment sys/socket.h
+@comment BSD
+@item SO_DEBUG
+@c Extra blank line here makes the table look better.
+
+This option toggles recording of debugging information in the underlying
+protocol modules.  The value has type @code{int}; a nonzero value means
+``yes''.
+@c !!! should say how this is used
+@c OK, anyone who knows, please explain.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_REUSEADDR
+This option controls whether @code{bind} (@pxref{Setting Address})
+should permit reuse of local addresses for this socket.  If you enable
+this option, you can actually have two sockets with the same Internet
+port number; but the system won't allow you to use the two
+identically-named sockets in a way that would confuse the Internet.  The
+reason for this option is that some higher-level Internet protocols,
+including FTP, require you to keep reusing the same port number.
+
+The value has type @code{int}; a nonzero value means ``yes''.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_KEEPALIVE
+This option controls whether the underlying protocol should
+periodically transmit messages on a connected socket.  If the peer
+fails to respond to these messages, the connection is considered
+broken.  The value has type @code{int}; a nonzero value means
+``yes''.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_DONTROUTE
+This option controls whether outgoing messages bypass the normal
+message routing facilities.  If set, messages are sent directly to the
+network interface instead.  The value has type @code{int}; a nonzero
+value means ``yes''.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_LINGER
+This option specifies what should happen when the socket of a type
+that promises reliable delivery still has untransmitted messages when
+it is closed; see @ref{Closing a Socket}.  The value has type
+@code{struct linger}.
+
+@comment sys/socket.h
+@comment BSD
+@deftp {Data Type} {struct linger}
+This structure type has the following members:
+
+@table @code
+@item int l_onoff
+This field is interpreted as a boolean.  If nonzero, @code{close}
+blocks until the data are transmitted or the timeout period has expired.
+
+@item int l_linger
+This specifies the timeout period, in seconds.
+@end table
+@end deftp
+
+@comment sys/socket.h
+@comment BSD
+@item SO_BROADCAST
+This option controls whether datagrams may be broadcast from the socket.
+The value has type @code{int}; a nonzero value means ``yes''.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_OOBINLINE
+If this option is set, out-of-band data received on the socket is
+placed in the normal input queue.  This permits it to be read using
+@code{read} or @code{recv} without specifying the @code{MSG_OOB}
+flag.  @xref{Out-of-Band Data}.  The value has type @code{int}; a
+nonzero value means ``yes''.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_SNDBUF
+This option gets or sets the size of the output buffer.  The value is a
+@code{size_t}, which is the size in bytes.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_RCVBUF
+This option gets or sets the size of the input buffer.  The value is a
+@code{size_t}, which is the size in bytes.
+
+@comment sys/socket.h
+@comment GNU
+@item SO_STYLE
+@comment sys/socket.h
+@comment BSD
+@itemx SO_TYPE
+This option can be used with @code{getsockopt} only.  It is used to
+get the socket's communication style.  @code{SO_TYPE} is the
+historical name, and @code{SO_STYLE} is the preferred name in GNU.
+The value has type @code{int} and its value designates a communication
+style; see @ref{Communication Styles}.
+
+@comment sys/socket.h
+@comment BSD
+@item SO_ERROR
+@c Extra blank line here makes the table look better.
+
+This option can be used with @code{getsockopt} only.  It is used to reset
+the error status of the socket.  The value is an @code{int}, which represents
+the previous error status.
+@c !!! what is "socket error status"?  this is never defined.
+@end table
+
+@node Networks Database
+@section Networks Database
+@cindex networks database
+@cindex converting network number to network name
+@cindex converting network name to network number
+
+@pindex /etc/networks
+@pindex netdb.h
+Many systems come with a database that records a list of networks known
+to the system developer.  This is usually kept either in the file
+@file{/etc/networks} or in an equivalent from a name server.  This data
+base is useful for routing programs such as @code{route}, but it is not
+useful for programs that simply communicate over the network.  We
+provide functions to access this database, which are declared in
+@file{netdb.h}.
+
+@comment netdb.h
+@comment BSD
+@deftp {Data Type} {struct netent}
+This data type is used to represent information about entries in the
+networks database.  It has the following members:
+
+@table @code
+@item char *n_name
+This is the ``official'' name of the network.
+
+@item char **n_aliases
+These are alternative names for the network, represented as a vector
+of strings.  A null pointer terminates the array.
+
+@item int n_addrtype
+This is the type of the network number; this is always equal to
+@code{AF_INET} for Internet networks.
+
+@item unsigned long int n_net
+This is the network number.  Network numbers are returned in host
+byte order; see @ref{Byte Order}.
+@end table
+@end deftp
+
+Use the @code{getnetbyname} or @code{getnetbyaddr} functions to search
+the networks database for information about a specific network.  The
+information is returned in a statically-allocated structure; you must
+copy the information if you need to save it.
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct netent *} getnetbyname (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netbyname} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getnetbyname =~ getpwuid @mtasurace:netbyname @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getnetbyname_r dup @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getnetbyname_r =~ getpwuid_r @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   no nscd support
+@c  res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getnetbyname_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getnetbyname} function returns information about the network
+named @var{name}.  It returns a null pointer if there is no such
+network.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct netent *} getnetbyaddr (uint32_t @var{net}, int @var{type})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netbyaddr} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getnetbyaddr =~ getpwuid @mtasurace:netbyaddr @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getnetbyaddr_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getnetbyaddr_r =~ getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   no nscd support
+@c  nss_networks_lookup2 =~ nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getnetbyaddr_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getnetbyaddr} function returns information about the network
+of type @var{type} with number @var{net}.  You should specify a value of
+@code{AF_INET} for the @var{type} argument for Internet networks.
+
+@code{getnetbyaddr} returns a null pointer if there is no such
+network.
+@end deftypefun
+
+You can also scan the networks database using @code{setnetent},
+@code{getnetent} and @code{endnetent}.  Be careful when using these
+functions because they are not reentrant.
+
+@comment netdb.h
+@comment BSD
+@deftypefun void setnetent (int @var{stayopen})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_setent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   setup(nss_networks_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *lookup_fct = nss_networks_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:netent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock dup @aculock
+This function opens and rewinds the networks database.
+
+If the @var{stayopen} argument is nonzero, this sets a flag so that
+subsequent calls to @code{getnetbyname} or @code{getnetbyaddr} will
+not close the database (as they usually would).  This makes for more
+efficiency if you call those functions several times, by avoiding
+reopening the database for each call.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun {struct netent *} getnetent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtasurace{:netentbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getnetent @mtasurace:netent @mtasurace:netentbuf @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent(getnetent_r) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   *func = getnetent_r dup @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+@c
+@c getnetent_r @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent_r(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:servent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *sfct.f @mtasurace:netent @ascuplugin
+@c  libc_lock_unlock dup @aculock
+This function returns the next entry in the networks database.  It
+returns a null pointer if there are no more entries.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun void endnetent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:netent} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endnetent @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_endent(nss_networks_lookup2) @mtasurace:netent @mtsenv @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   res_maybe_init(!preinit) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   setup(nss_networks_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:netent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function closes the networks database.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/startup.texi b/ap/libc/glibc/glibc-2.23/manual/startup.texi
new file mode 100644
index 0000000..9a091a5
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/startup.texi
@@ -0,0 +1,1099 @@
+@node Program Basics, Processes, Signal Handling, Top
+@c %MENU% Writing the beginning and end of your program
+@chapter The Basic Program/System Interface
+
+@cindex process
+@cindex program
+@cindex address space
+@cindex thread of control
+@dfn{Processes} are the primitive units for allocation of system
+resources.  Each process has its own address space and (usually) one
+thread of control.  A process executes a program; you can have multiple
+processes executing the same program, but each process has its own copy
+of the program within its own address space and executes it
+independently of the other copies.  Though it may have multiple threads
+of control within the same program and a program may be composed of
+multiple logically separate modules, a process always executes exactly
+one program.
+
+Note that we are using a specific definition of ``program'' for the
+purposes of this manual, which corresponds to a common definition in the
+context of Unix system.  In popular usage, ``program'' enjoys a much
+broader definition; it can refer for example to a system's kernel, an
+editor macro, a complex package of software, or a discrete section of
+code executing within a process.
+
+Writing the program is what this manual is all about.  This chapter
+explains the most basic interface between your program and the system
+that runs, or calls, it.  This includes passing of parameters (arguments
+and environment) from the system, requesting basic services from the
+system, and telling the system the program is done.
+
+A program starts another program with the @code{exec} family of system calls.
+This chapter looks at program startup from the execee's point of view.  To
+see the event from the execor's point of view, see @ref{Executing a File}.
+
+@menu
+* Program Arguments::           Parsing your program's command-line arguments
+* Environment Variables::       Less direct parameters affecting your program
+* Auxiliary Vector::            Least direct parameters affecting your program
+* System Calls::                Requesting service from the system
+* Program Termination::         Telling the system you're done; return status
+@end menu
+
+@node Program Arguments, Environment Variables, , Program Basics
+@section Program Arguments
+@cindex program arguments
+@cindex command line arguments
+@cindex arguments, to program
+
+@cindex program startup
+@cindex startup of program
+@cindex invocation of program
+@cindex @code{main} function
+@findex main
+The system starts a C program by calling the function @code{main}.  It
+is up to you to write a function named @code{main}---otherwise, you
+won't even be able to link your program without errors.
+
+In @w{ISO C} you can define @code{main} either to take no arguments, or to
+take two arguments that represent the command line arguments to the
+program, like this:
+
+@smallexample
+int main (int @var{argc}, char *@var{argv}[])
+@end smallexample
+
+@cindex argc (program argument count)
+@cindex argv (program argument vector)
+The command line arguments are the whitespace-separated tokens given in
+the shell command used to invoke the program; thus, in @samp{cat foo
+bar}, the arguments are @samp{foo} and @samp{bar}.  The only way a
+program can look at its command line arguments is via the arguments of
+@code{main}.  If @code{main} doesn't take arguments, then you cannot get
+at the command line.
+
+The value of the @var{argc} argument is the number of command line
+arguments.  The @var{argv} argument is a vector of C strings; its
+elements are the individual command line argument strings.  The file
+name of the program being run is also included in the vector as the
+first element; the value of @var{argc} counts this element.  A null
+pointer always follows the last element: @code{@var{argv}[@var{argc}]}
+is this null pointer.
+
+For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
+three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
+
+In Unix systems you can define @code{main} a third way, using three arguments:
+
+@smallexample
+int main (int @var{argc}, char *@var{argv}[], char *@var{envp}[])
+@end smallexample
+
+The first two arguments are just the same.  The third argument
+@var{envp} gives the program's environment; it is the same as the value
+of @code{environ}.  @xref{Environment Variables}.  POSIX.1 does not
+allow this three-argument form, so to be portable it is best to write
+@code{main} to take two arguments, and use the value of @code{environ}.
+
+@menu
+* Argument Syntax::             By convention, options start with a hyphen.
+* Parsing Program Arguments::   Ways to parse program options and arguments.
+@end menu
+
+@node Argument Syntax, Parsing Program Arguments, , Program Arguments
+@subsection Program Argument Syntax Conventions
+@cindex program argument syntax
+@cindex syntax, for program arguments
+@cindex command argument syntax
+
+POSIX recommends these conventions for command line arguments.
+@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
+it easy to implement them.
+
+@itemize @bullet
+@item
+Arguments are options if they begin with a hyphen delimiter (@samp{-}).
+
+@item
+Multiple options may follow a hyphen delimiter in a single token if
+the options do not take arguments.  Thus, @samp{-abc} is equivalent to
+@samp{-a -b -c}.
+
+@item
+Option names are single alphanumeric characters (as for @code{isalnum};
+@pxref{Classification of Characters}).
+
+@item
+Certain options require an argument.  For example, the @samp{-o} command
+of the @code{ld} command requires an argument---an output file name.
+
+@item
+An option and its argument may or may not appear as separate tokens.  (In
+other words, the whitespace separating them is optional.)  Thus,
+@w{@samp{-o foo}} and @samp{-ofoo} are equivalent.
+
+@item
+Options typically precede other non-option arguments.
+
+The implementations of @code{getopt} and @code{argp_parse} in @theglibc{}
+normally make it appear as if all the option arguments were
+specified before all the non-option arguments for the purposes of
+parsing, even if the user of your program intermixed option and
+non-option arguments.  They do this by reordering the elements of the
+@var{argv} array.  This behavior is nonstandard; if you want to suppress
+it, define the @code{_POSIX_OPTION_ORDER} environment variable.
+@xref{Standard Environment}.
+
+@item
+The argument @samp{--} terminates all options; any following arguments
+are treated as non-option arguments, even if they begin with a hyphen.
+
+@item
+A token consisting of a single hyphen character is interpreted as an
+ordinary non-option argument.  By convention, it is used to specify
+input from or output to the standard input and output streams.
+
+@item
+Options may be supplied in any order, or appear multiple times.  The
+interpretation is left up to the particular application program.
+@end itemize
+
+@cindex long-named options
+GNU adds @dfn{long options} to these conventions.  Long options consist
+of @samp{--} followed by a name made of alphanumeric characters and
+dashes.  Option names are typically one to three words long, with
+hyphens to separate words.  Users can abbreviate the option names as
+long as the abbreviations are unique.
+
+To specify an argument for a long option, write
+@samp{--@var{name}=@var{value}}.  This syntax enables a long option to
+accept an argument that is itself optional.
+
+Eventually, @gnusystems{} will provide completion for long option names
+in the shell.
+
+@node Parsing Program Arguments, , Argument Syntax, Program Arguments
+@subsection Parsing Program Arguments
+
+@cindex program arguments, parsing
+@cindex command arguments, parsing
+@cindex parsing program arguments
+If the syntax for the command line arguments to your program is simple
+enough, you can simply pick the arguments off from @var{argv} by hand.
+But unless your program takes a fixed number of arguments, or all of the
+arguments are interpreted in the same way (as file names, for example),
+you are usually better off using @code{getopt} (@pxref{Getopt}) or
+@code{argp_parse} (@pxref{Argp}) to do the parsing.
+
+@code{getopt} is more standard (the short-option only version of it is a
+part of the POSIX standard), but using @code{argp_parse} is often
+easier, both for very simple and very complex option structures, because
+it does more of the dirty work for you.
+
+@menu
+* 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}.
+@end menu
+
+@c Getopt and argp start at the @section level so that there's
+@c enough room for their internal hierarchy (mostly a problem with
+@c argp).         -Miles
+
+@include getopt.texi
+@include argp.texi
+
+@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
+@c This is a @section so that it's at the same level as getopt and argp
+@subsubsection Parsing of Suboptions
+
+Having a single level of options is sometimes not enough.  There might
+be too many options which have to be available or a set of options is
+closely related.
+
+For this case some programs use suboptions.  One of the most prominent
+programs is certainly @code{mount}(8).  The @code{-o} option take one
+argument which itself is a comma separated list of options.  To ease the
+programming of code like this the function @code{getsubopt} is
+available.
+
+@comment stdlib.h
+@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c getsubopt ok
+@c  strchrnul dup ok
+@c  memchr dup ok
+@c  strncmp dup ok
+
+The @var{optionp} parameter must be a pointer to a variable containing
+the address of the string to process.  When the function returns the
+reference is updated to point to the next suboption or to the
+terminating @samp{\0} character if there is no more suboption available.
+
+The @var{tokens} parameter references an array of strings containing the
+known suboptions.  All strings must be @samp{\0} terminated and to mark
+the end a null pointer must be stored.  When @code{getsubopt} finds a
+possible legal suboption it compares it with all strings available in
+the @var{tokens} array and returns the index in the string as the
+indicator.
+
+In case the suboption has an associated value introduced by a @samp{=}
+character, a pointer to the value is returned in @var{valuep}.  The
+string is @samp{\0} terminated.  If no argument is available
+@var{valuep} is set to the null pointer.  By doing this the caller can
+check whether a necessary value is given or whether no unexpected value
+is present.
+
+In case the next suboption in the string is not mentioned in the
+@var{tokens} array the starting address of the suboption including a
+possible value is returned in @var{valuep} and the return value of the
+function is @samp{-1}.
+@end deftypefun
+
+@node Suboptions Example, , Suboptions, Parsing Program Arguments
+@subsection Parsing of Suboptions Example
+
+The code which might appear in the @code{mount}(8) program is a perfect
+example of the use of @code{getsubopt}:
+
+@smallexample
+@include subopt.c.texi
+@end smallexample
+
+
+@node Environment Variables, Auxiliary Vector, Program Arguments, Program Basics
+@section Environment Variables
+
+@cindex environment variable
+When a program is executed, it receives information about the context in
+which it was invoked in two ways.  The first mechanism uses the
+@var{argv} and @var{argc} arguments to its @code{main} function, and is
+discussed in @ref{Program Arguments}.  The second mechanism uses
+@dfn{environment variables} and is discussed in this section.
+
+The @var{argv} mechanism is typically used to pass command-line
+arguments specific to the particular program being invoked.  The
+environment, on the other hand, keeps track of information that is
+shared by many programs, changes infrequently, and that is less
+frequently used.
+
+The environment variables discussed in this section are the same
+environment variables that you set using assignments and the
+@code{export} command in the shell.  Programs executed from the shell
+inherit all of the environment variables from the shell.
+@c !!! xref to right part of bash manual when it exists
+
+@cindex environment
+Standard environment variables are used for information about the user's
+home directory, terminal type, current locale, and so on; you can define
+additional variables for other purposes.  The set of all environment
+variables that have values is collectively known as the
+@dfn{environment}.
+
+Names of environment variables are case-sensitive and must not contain
+the character @samp{=}.  System-defined environment variables are
+invariably uppercase.
+
+The values of environment variables can be anything that can be
+represented as a string.  A value must not contain an embedded null
+character, since this is assumed to terminate the string.
+
+
+@menu
+* Environment Access::          How to get and set the values of
+				 environment variables.
+* Standard Environment::        These environment variables have
+                		 standard interpretations.
+@end menu
+
+@node Environment Access
+@subsection Environment Access
+@cindex environment access
+@cindex environment representation
+
+The value of an environment variable can be accessed with the
+@code{getenv} function.  This is declared in the header file
+@file{stdlib.h}.
+@pindex stdlib.h
+
+Libraries should use @code{secure_getenv} instead of @code{getenv}, so
+that they do not accidentally use untrusted environment variables.
+Modifications of environment variables are not allowed in
+multi-threaded programs.  The @code{getenv} and @code{secure_getenv}
+functions can be safely used in multi-threaded programs.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun {char *} getenv (const char *@var{name})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Unguarded access to __environ.
+This function returns a string that is the value of the environment
+variable @var{name}.  You must not modify this string.  In some non-Unix
+systems not using @theglibc{}, it might be overwritten by subsequent
+calls to @code{getenv} (but not by any other library function).  If the
+environment variable @var{name} is not defined, the value is a null
+pointer.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun {char *} secure_getenv (const char *@var{name})
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Calls getenv unless secure mode is enabled.
+This function is similar to @code{getenv}, but it returns a null
+pointer if the environment is untrusted.  This happens when the
+program file has SUID or SGID bits set.  General-purpose libraries
+should always prefer this function over @code{getenv} to avoid
+vulnerabilities if the library is referenced from a SUID/SGID program.
+
+This function is a GNU extension.
+@end deftypefun
+
+
+@comment stdlib.h
+@comment SVID
+@deftypefun int putenv (char *@var{string})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c putenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  strchr dup ok
+@c  strndup dup @ascuheap @acsmem
+@c  add_to_environ dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  free dup @ascuheap @acsmem
+@c  unsetenv dup @mtasuconst:@mtsenv @asulock @aculock
+The @code{putenv} function adds or removes definitions from the environment.
+If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
+definition is added to the environment.  Otherwise, the @var{string} is
+interpreted as the name of an environment variable, and any definition
+for this variable in the environment is removed.
+
+If the function is successful it returns @code{0}.  Otherwise the return
+value is nonzero and @code{errno} is set to indicate the error.
+
+The difference to the @code{setenv} function is that the exact string
+given as the parameter @var{string} is put into the environment.  If the
+user should change the string after the @code{putenv} call this will
+reflect automatically in the environment.  This also requires that
+@var{string} not be an automatic variable whose scope is left before the
+variable is removed from the environment.  The same applies of course to
+dynamically allocated variables which are freed later.
+
+This function is part of the extended Unix interface.  You should define
+@var{_XOPEN_SOURCE} before including any header.
+@end deftypefun
+
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c setenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  add_to_environ @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c   strlen dup ok
+@c   libc_lock_lock @asulock @aculock
+@c   strncmp dup ok
+@c   realloc dup @ascuheap @acsmem
+@c   libc_lock_unlock @aculock
+@c   malloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c   mempcpy dup ok
+@c   memcpy dup ok
+@c   KNOWN_VALUE ok
+@c    tfind(strcmp) [no @mtsrace guarded access]
+@c     strcmp dup ok
+@c   STORE_VALUE @ascuheap @acucorrupt @acsmem
+@c    tsearch(strcmp) @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt guarded access makes for mtsafe and @asulock]
+@c     strcmp dup ok
+The @code{setenv} function can be used to add a new definition to the
+environment.  The entry with the name @var{name} is replaced by the
+value @samp{@var{name}=@var{value}}.  Please note that this is also true
+if @var{value} is the empty string.  To do this a new string is created
+and the strings @var{name} and @var{value} are copied.  A null pointer
+for the @var{value} parameter is illegal.  If the environment already
+contains an entry with key @var{name} the @var{replace} parameter
+controls the action.  If replace is zero, nothing happens.  Otherwise
+the old entry is replaced by the new one.
+
+Please note that you cannot remove an entry completely using this function.
+
+If the function is successful it returns @code{0}.  Otherwise the
+environment is unchanged and the return value is @code{-1} and
+@code{errno} is set.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int unsetenv (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c unsetenv @mtasuconst:@mtsenv @asulock @aculock
+@c  strchr dup ok
+@c  strlen dup ok
+@c  libc_lock_lock @asulock @aculock
+@c  strncmp dup ok
+@c  libc_lock_unlock @aculock
+Using this function one can remove an entry completely from the
+environment.  If the environment contains an entry with the key
+@var{name} this whole entry is removed.  A call to this function is
+equivalent to a call to @code{putenv} when the @var{value} part of the
+string is empty.
+
+The function return @code{-1} if @var{name} is a null pointer, points to
+an empty string, or points to a string containing a @code{=} character.
+It returns @code{0} if the call succeeded.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard.  The BSD version had no return value, though.
+@end deftypefun
+
+There is one more function to modify the whole environment.  This
+function is said to be used in the POSIX.9 (POSIX bindings for Fortran
+77) and so one should expect it did made it into POSIX.1.  But this
+never happened.  But we still provide this function as a GNU extension
+to enable writing standard compliant Fortran environments.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int clearenv (void)
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c clearenv @mtasuconst:@mtsenv @ascuheap @asulock @aculock @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock @aculock
+The @code{clearenv} function removes all entries from the environment.
+Using @code{putenv} and @code{setenv} new entries can be added again
+later.
+
+If the function is successful it returns @code{0}.  Otherwise the return
+value is nonzero.
+@end deftypefun
+
+
+You can deal directly with the underlying representation of environment
+objects to add more variables to the environment (for example, to
+communicate with another program you are about to execute;
+@pxref{Executing a File}).
+
+@comment unistd.h
+@comment POSIX.1
+@deftypevar {char **} environ
+The environment is represented as an array of strings.  Each string is
+of the format @samp{@var{name}=@var{value}}.  The order in which
+strings appear in the environment is not significant, but the same
+@var{name} must not appear more than once.  The last element of the
+array is a null pointer.
+
+This variable is declared in the header file @file{unistd.h}.
+
+If you just want to get the value of an environment variable, use
+@code{getenv}.
+@end deftypevar
+
+Unix systems, and @gnusystems{}, pass the initial value of
+@code{environ} as the third argument to @code{main}.
+@xref{Program Arguments}.
+
+@node Standard Environment
+@subsection Standard Environment Variables
+@cindex standard environment variables
+
+These environment variables have standard meanings.  This doesn't mean
+that they are always present in the environment; but if these variables
+@emph{are} present, they have these meanings.  You shouldn't try to use
+these environment variable names for some other purpose.
+
+@comment Extra blank lines make it look better.
+@table @code
+@item HOME
+@cindex @code{HOME} environment variable
+@cindex home directory
+
+This is a string representing the user's @dfn{home directory}, or
+initial default working directory.
+
+The user can set @code{HOME} to any value.
+If you need to make sure to obtain the proper home directory
+for a particular user, you should not use @code{HOME}; instead,
+look up the user's name in the user database (@pxref{User Database}).
+
+For most purposes, it is better to use @code{HOME}, precisely because
+this lets the user specify the value.
+
+@c !!! also USER
+@item LOGNAME
+@cindex @code{LOGNAME} environment variable
+
+This is the name that the user used to log in.  Since the value in the
+environment can be tweaked arbitrarily, this is not a reliable way to
+identify the user who is running a program; a function like
+@code{getlogin} (@pxref{Who Logged In}) is better for that purpose.
+
+For most purposes, it is better to use @code{LOGNAME}, precisely because
+this lets the user specify the value.
+
+@item PATH
+@cindex @code{PATH} environment variable
+
+A @dfn{path} is a sequence of directory names which is used for
+searching for a file.  The variable @code{PATH} holds a path used
+for searching for programs to be run.
+
+The @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
+use this environment variable, as do many shells and other utilities
+which are implemented in terms of those functions.
+
+The syntax of a path is a sequence of directory names separated by
+colons.  An empty string instead of a directory name stands for the
+current directory (@pxref{Working Directory}).
+
+A typical value for this environment variable might be a string like:
+
+@smallexample
+:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
+@end smallexample
+
+This means that if the user tries to execute a program named @code{foo},
+the system will look for files named @file{foo}, @file{/bin/foo},
+@file{/etc/foo}, and so on.  The first of these files that exists is
+the one that is executed.
+
+@c !!! also TERMCAP
+@item TERM
+@cindex @code{TERM} environment variable
+
+This specifies the kind of terminal that is receiving program output.
+Some programs can make use of this information to take advantage of
+special escape sequences or terminal modes supported by particular kinds
+of terminals.  Many programs which use the termcap library
+(@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
+Manual}) use the @code{TERM} environment variable, for example.
+
+@item TZ
+@cindex @code{TZ} environment variable
+
+This specifies the time zone.  @xref{TZ Variable}, for information about
+the format of this string and how it is used.
+
+@item LANG
+@cindex @code{LANG} environment variable
+
+This specifies the default locale to use for attribute categories where
+neither @code{LC_ALL} nor the specific environment variable for that
+category is set.  @xref{Locales}, for more information about
+locales.
+
+@ignore
+@c I doubt this really exists
+@item LC_ALL
+@cindex @code{LC_ALL} environment variable
+
+This is similar to the @code{LANG} environment variable.  However, its
+value takes precedence over any values provided for the individual
+attribute category environment variables, or for the @code{LANG}
+environment variable.
+@end ignore
+
+@item LC_ALL
+@cindex @code{LC_ALL} environment variable
+
+If this environment variable is set it overrides the selection for all
+the locales done using the other @code{LC_*} environment variables.  The
+value of the other @code{LC_*} environment variables is simply ignored
+in this case.
+
+@item LC_COLLATE
+@cindex @code{LC_COLLATE} environment variable
+
+This specifies what locale to use for string sorting.
+
+@item LC_CTYPE
+@cindex @code{LC_CTYPE} environment variable
+
+This specifies what locale to use for character sets and character
+classification.
+
+@item LC_MESSAGES
+@cindex @code{LC_MESSAGES} environment variable
+
+This specifies what locale to use for printing messages and to parse
+responses.
+
+@item LC_MONETARY
+@cindex @code{LC_MONETARY} environment variable
+
+This specifies what locale to use for formatting monetary values.
+
+@item LC_NUMERIC
+@cindex @code{LC_NUMERIC} environment variable
+
+This specifies what locale to use for formatting numbers.
+
+@item LC_TIME
+@cindex @code{LC_TIME} environment variable
+
+This specifies what locale to use for formatting date/time values.
+
+@item NLSPATH
+@cindex @code{NLSPATH} environment variable
+
+This specifies the directories in which the @code{catopen} function
+looks for message translation catalogs.
+
+@item _POSIX_OPTION_ORDER
+@cindex @code{_POSIX_OPTION_ORDER} environment variable.
+
+If this environment variable is defined, it suppresses the usual
+reordering of command line arguments by @code{getopt} and
+@code{argp_parse}.  @xref{Argument Syntax}.
+
+@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
+@end table
+
+@node Auxiliary Vector
+@section Auxiliary Vector
+@cindex auxiliary vector
+
+When a program is executed, it receives information from the operating
+system about the environment in which it is operating.  The form of this
+information is a table of key-value pairs, where the keys are from the
+set of @samp{AT_} values in @file{elf.h}.  Some of the data is provided
+by the kernel for libc consumption, and may be obtained by ordinary
+interfaces, such as @code{sysconf}.  However, on a platform-by-platform
+basis there may be information that is not available any other way.
+
+@subsection Definition of @code{getauxval}
+@comment sys/auxv.h
+@deftypefun {unsigned long int} getauxval (unsigned long int @var{type})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Reads from hwcap or iterates over constant auxv.
+This function is used to inquire about the entries in the auxiliary
+vector.  The @var{type} argument should be one of the @samp{AT_} symbols
+defined in @file{elf.h}.  If a matching entry is found, the value is
+returned; if the entry is not found, zero is returned and @code{errno} is
+set to @code{ENOENT}.
+@end deftypefun
+
+For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire
+about any instruction set extensions available at runtime.  In this case,
+there will (of necessity) be a platform-specific set of @samp{HWCAP_}
+values masked together that describe the capabilities of the cpu on which
+the program is being executed.
+
+@node System Calls
+@section System Calls
+
+@cindex system call
+A system call is a request for service that a program makes of the
+kernel.  The service is generally something that only the kernel has
+the privilege to do, such as doing I/O.  Programmers don't normally
+need to be concerned with system calls because there are functions in
+@theglibc{} to do virtually everything that system calls do.
+These functions work by making system calls themselves.  For example,
+there is a system call that changes the permissions of a file, but
+you don't need to know about it because you can just use @theglibc{}'s
+@code{chmod} function.
+
+@cindex kernel call
+System calls are sometimes called kernel calls.
+
+However, there are times when you want to make a system call explicitly,
+and for that, @theglibc{} provides the @code{syscall} function.
+@code{syscall} is harder to use and less portable than functions like
+@code{chmod}, but easier and more portable than coding the system call
+in assembler instructions.
+
+@code{syscall} is most useful when you are working with a system call
+which is special to your system or is newer than @theglibc{} you
+are using.  @code{syscall} is implemented in an entirely generic way;
+the function does not know anything about what a particular system
+call does or even if it is valid.
+
+The description of @code{syscall} in this section assumes a certain
+protocol for system calls on the various platforms on which @theglibc{}
+runs.  That protocol is not defined by any strong authority, but
+we won't describe it here either because anyone who is coding
+@code{syscall} probably won't accept anything less than kernel and C
+library source code as a specification of the interface between them
+anyway.
+
+
+@code{syscall} is declared in @file{unistd.h}.
+
+@comment unistd.h
+@comment ???
+@deftypefun {long int} syscall (long int @var{sysno}, @dots{})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{syscall} performs a generic system call.
+
+@cindex system call number
+@var{sysno} is the system call number.  Each kind of system call is
+identified by a number.  Macros for all the possible system call numbers
+are defined in @file{sys/syscall.h}
+
+The remaining arguments are the arguments for the system call, in
+order, and their meanings depend on the kind of system call.  Each kind
+of system call has a definite number of arguments, from zero to five.
+If you code more arguments than the system call takes, the extra ones to
+the right are ignored.
+
+The return value is the return value from the system call, unless the
+system call failed.  In that case, @code{syscall} returns @code{-1} and
+sets @code{errno} to an error code that the system call returned.  Note
+that system calls do not return @code{-1} when they succeed.
+@cindex errno
+
+If you specify an invalid @var{sysno}, @code{syscall} returns @code{-1}
+with @code{errno} = @code{ENOSYS}.
+
+Example:
+
+@smallexample
+
+#include <unistd.h>
+#include <sys/syscall.h>
+#include <errno.h>
+
+@dots{}
+
+int rc;
+
+rc = syscall(SYS_chmod, "/etc/passwd", 0444);
+
+if (rc == -1)
+   fprintf(stderr, "chmod failed, errno = %d\n", errno);
+
+@end smallexample
+
+This, if all the compatibility stars are aligned, is equivalent to the
+following preferable code:
+
+@smallexample
+
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <errno.h>
+
+@dots{}
+
+int rc;
+
+rc = chmod("/etc/passwd", 0444);
+if (rc == -1)
+   fprintf(stderr, "chmod failed, errno = %d\n", errno);
+
+@end smallexample
+
+@end deftypefun
+
+
+@node Program Termination
+@section Program Termination
+@cindex program termination
+@cindex process termination
+
+@cindex exit status value
+The usual way for a program to terminate is simply for its @code{main}
+function to return.  The @dfn{exit status value} returned from the
+@code{main} function is used to report information back to the process's
+parent process or shell.
+
+A program can also terminate normally by calling the @code{exit}
+function.
+
+In addition, programs can be terminated by signals; this is discussed in
+more detail in @ref{Signal Handling}.  The @code{abort} function causes
+a signal that kills the program.
+
+@menu
+* 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.
+@end menu
+
+@node Normal Termination
+@subsection Normal Termination
+
+A process terminates normally when its program signals it is done by
+calling @code{exit}.  Returning from @code{main} is equivalent to
+calling @code{exit}, and the value that @code{main} returns is used as
+the argument to @code{exit}.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun void exit (int @var{status})
+@safety{@prelim{}@mtunsafe{@mtasurace{:exit}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c Access to the atexit/on_exit list, the libc_atexit hook and tls dtors
+@c is not guarded.  Streams must be flushed, and that triggers the usual
+@c AS and AC issues with streams.
+The @code{exit} function tells the system that the program is done, which
+causes it to terminate the process.
+
+@var{status} is the program's exit status, which becomes part of the
+process' termination status.  This function does not return.
+@end deftypefun
+
+Normal termination causes the following actions:
+
+@enumerate
+@item
+Functions that were registered with the @code{atexit} or @code{on_exit}
+functions are called in the reverse order of their registration.  This
+mechanism allows your application to specify its own ``cleanup'' actions
+to be performed at program termination.  Typically, this is used to do
+things like saving program state information in a file, or unlocking
+locks in shared data bases.
+
+@item
+All open streams are closed, writing out any buffered output data.  See
+@ref{Closing Streams}.  In addition, temporary files opened
+with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
+
+@item
+@code{_exit} is called, terminating the program.  @xref{Termination Internals}.
+@end enumerate
+
+@node Exit Status
+@subsection Exit Status
+@cindex exit status
+
+When a program exits, it can return to the parent process a small
+amount of information about the cause of termination, using the
+@dfn{exit status}.  This is a value between 0 and 255 that the exiting
+process passes as an argument to @code{exit}.
+
+Normally you should use the exit status to report very broad information
+about success or failure.  You can't provide a lot of detail about the
+reasons for the failure, and most parent processes would not want much
+detail anyway.
+
+There are conventions for what sorts of status values certain programs
+should return.  The most common convention is simply 0 for success and 1
+for failure.  Programs that perform comparison use a different
+convention: they use status 1 to indicate a mismatch, and status 2 to
+indicate an inability to compare.  Your program should follow an
+existing convention if an existing convention makes sense for it.
+
+A general convention reserves status values 128 and up for special
+purposes.  In particular, the value 128 is used to indicate failure to
+execute another program in a subprocess.  This convention is not
+universally obeyed, but it is a good idea to follow it in your programs.
+
+@strong{Warning:} Don't try to use the number of errors as the exit
+status.  This is actually not very useful; a parent process would
+generally not care how many errors occurred.  Worse than that, it does
+not work, because the status value is truncated to eight bits.
+Thus, if the program tried to report 256 errors, the parent would
+receive a report of 0 errors---that is, success.
+
+For the same reason, it does not work to use the value of @code{errno}
+as the exit status---these can exceed 255.
+
+@strong{Portability note:} Some non-POSIX systems use different
+conventions for exit status values.  For greater portability, you can
+use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
+conventional status value for success and failure, respectively.  They
+are declared in the file @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ISO
+@deftypevr Macro int EXIT_SUCCESS
+This macro can be used with the @code{exit} function to indicate
+successful program completion.
+
+On POSIX systems, the value of this macro is @code{0}.  On other
+systems, the value might be some other (possibly non-constant) integer
+expression.
+@end deftypevr
+
+@comment stdlib.h
+@comment ISO
+@deftypevr Macro int EXIT_FAILURE
+This macro can be used with the @code{exit} function to indicate
+unsuccessful program completion in a general sense.
+
+On POSIX systems, the value of this macro is @code{1}.  On other
+systems, the value might be some other (possibly non-constant) integer
+expression.  Other nonzero status values also indicate failures.  Certain
+programs use different nonzero status values to indicate particular
+kinds of "non-success".  For example, @code{diff} uses status value
+@code{1} to mean that the files are different, and @code{2} or more to
+mean that there was difficulty in opening the files.
+@end deftypevr
+
+Don't confuse a program's exit status with a process' termination status.
+There are lots of ways a process can terminate besides having its program
+finish.  In the event that the process termination @emph{is} caused by program
+termination (i.e., @code{exit}), though, the program's exit status becomes
+part of the process' termination status.
+
+@node Cleanups on Exit
+@subsection Cleanups on Exit
+
+Your program can arrange to run its own cleanup functions if normal
+termination happens.  If you are writing a library for use in various
+application programs, then it is unreliable to insist that all
+applications call the library's cleanup functions explicitly before
+exiting.  It is much more robust to make the cleanup invisible to the
+application, by setting up a cleanup function in the library itself
+using @code{atexit} or @code{on_exit}.
+
+@comment stdlib.h
+@comment ISO
+@deftypefun int atexit (void (*@var{function}) (void))
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c atexit @ascuheap @asulock @aculock @acsmem
+@c  cxa_atexit @ascuheap @asulock @aculock @acsmem
+@c   __internal_atexit @ascuheap @asulock @aculock @acsmem
+@c    __new_exitfn @ascuheap @asulock @aculock @acsmem
+@c     __libc_lock_lock @asulock @aculock
+@c     calloc dup @ascuheap @acsmem
+@c     __libc_lock_unlock @aculock
+@c    atomic_write_barrier dup ok
+The @code{atexit} function registers the function @var{function} to be
+called at normal program termination.  The @var{function} is called with
+no arguments.
+
+The return value from @code{atexit} is zero on success and nonzero if
+the function cannot be registered.
+@end deftypefun
+
+@comment stdlib.h
+@comment SunOS
+@deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c on_exit @ascuheap @asulock @aculock @acsmem
+@c  new_exitfn dup @ascuheap @asulock @aculock @acsmem
+@c  atomic_write_barrier dup ok
+This function is a somewhat more powerful variant of @code{atexit}.  It
+accepts two arguments, a function @var{function} and an arbitrary
+pointer @var{arg}.  At normal program termination, the @var{function} is
+called with two arguments:  the @var{status} value passed to @code{exit},
+and the @var{arg}.
+
+This function is included in @theglibc{} only for compatibility
+for SunOS, and may not be supported by other implementations.
+@end deftypefun
+
+Here's a trivial program that illustrates the use of @code{exit} and
+@code{atexit}:
+
+@smallexample
+@include atexit.c.texi
+@end smallexample
+
+@noindent
+When this program is executed, it just prints the message and exits.
+
+@node Aborting a Program
+@subsection Aborting a Program
+@cindex aborting a program
+
+You can abort your program using the @code{abort} function.  The prototype
+for this function is in @file{stdlib.h}.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ISO
+@deftypefun void abort (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c The implementation takes a recursive lock and attempts to support
+@c calls from signal handlers, but if we're in the middle of flushing or
+@c using streams, we may encounter them in inconsistent states.
+The @code{abort} function causes abnormal program termination.  This
+does not execute cleanup functions registered with @code{atexit} or
+@code{on_exit}.
+
+This function actually terminates the process by raising a
+@code{SIGABRT} signal, and your program can include a handler to
+intercept this signal; see @ref{Signal Handling}.
+@end deftypefun
+
+@c Put in by rms.  Don't remove.
+@cartouche
+@strong{Future Change Warning:} Proposed Federal censorship regulations
+may prohibit us from giving you information about the possibility of
+calling this function.  We would be required to say that this is not an
+acceptable way of terminating a program.
+@end cartouche
+
+@node Termination Internals
+@subsection Termination Internals
+
+The @code{_exit} function is the primitive used for process termination
+by @code{exit}.  It is declared in the header file @file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun void _exit (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall (exit_group or exit); calls __task_terminate on hurd,
+@c and abort in the generic posix implementation.
+The @code{_exit} function is the primitive for causing a process to
+terminate with status @var{status}.  Calling this function does not
+execute cleanup functions registered with @code{atexit} or
+@code{on_exit}.
+@end deftypefun
+
+@comment stdlib.h
+@comment ISO
+@deftypefun void _Exit (int @var{status})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias for _exit.
+The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}.
+The @w{ISO C} committee members were not sure whether the definitions of
+@code{_exit} and @code{_Exit} were compatible so they have not used the
+POSIX name.
+
+This function was introduced in @w{ISO C99} and is declared in
+@file{stdlib.h}.
+@end deftypefun
+
+When a process terminates for any reason---either because the program
+terminates, or as a result of a signal---the
+following things happen:
+
+@itemize @bullet
+@item
+All open file descriptors in the process are closed.  @xref{Low-Level I/O}.
+Note that streams are not flushed automatically when the process
+terminates; see @ref{I/O on Streams}.
+
+@item
+A process exit status is saved to be reported back to the parent process
+via @code{wait} or @code{waitpid}; see @ref{Process Completion}.  If the
+program exited, this status includes as its low-order 8 bits the program
+exit status.
+
+
+@item
+Any child processes of the process being terminated are assigned a new
+parent process.  (On most systems, including GNU, this is the @code{init}
+process, with process ID 1.)
+
+@item
+A @code{SIGCHLD} signal is sent to the parent process.
+
+@item
+If the process is a session leader that has a controlling terminal, then
+a @code{SIGHUP} signal is sent to each process in the foreground job,
+and the controlling terminal is disassociated from that session.
+@xref{Job Control}.
+
+@item
+If termination of a process causes a process group to become orphaned,
+and any member of that process group is stopped, then a @code{SIGHUP}
+signal and a @code{SIGCONT} signal are sent to each process in the
+group.  @xref{Job Control}.
+@end itemize
diff --git a/ap/libc/glibc/glibc-2.23/manual/stdio-fp.c b/ap/libc/glibc/glibc-2.23/manual/stdio-fp.c
new file mode 100644
index 0000000..db94807
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/stdio-fp.c
@@ -0,0 +1,28 @@
+/* This program is to generate one of the examples in stdio.texi.  */
+
+#include <stdio.h>
+
+
+static void
+print (double v)
+{
+  printf ("|%13.4a|%13.4f|%13.4e|%13.4g|\n", v, v, v, v);
+}
+
+
+int
+main (void)
+{
+  print (0.0);
+  print (0.5);
+  print (1.0);
+  print (-1.0);
+  print (100.0);
+  print (1000.0);
+  print (10000.0);
+  print (12345.0);
+  print (100000.0);
+  print (123456.0);
+
+  return 0;
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/stdio.texi b/ap/libc/glibc/glibc-2.23/manual/stdio.texi
new file mode 100644
index 0000000..0326f29
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/stdio.texi
@@ -0,0 +1,5657 @@
+@node I/O on Streams, Low-Level I/O, I/O Overview, Top
+@c %MENU% High-level, portable I/O facilities
+@chapter Input/Output on Streams
+@c fix an overfull:
+@tex
+\hyphenation{which-ever}
+@end tex
+
+This chapter describes the functions for creating streams and performing
+input and output operations on them.  As discussed in @ref{I/O
+Overview}, a stream is a fairly abstract, high-level concept
+representing a communications channel to a file, device, or process.
+
+@menu
+* Streams::                     About the data type representing a stream.
+* Standard Streams::            Streams to the standard input and output
+				 devices are created for you.
+* Opening Streams::             How to create a stream to talk to a file.
+* Closing Streams::             Close a stream when you are finished with it.
+* Streams and Threads::         Issues with streams in threaded programs.
+* Streams and I18N::            Streams in internationalized applications.
+* Simple Output::               Unformatted output by characters and lines.
+* Character Input::             Unformatted input by characters and words.
+* Line Input::                  Reading a line or a record from a stream.
+* Unreading::                   Peeking ahead/pushing back input just read.
+* Block Input/Output::          Input and output operations on blocks of data.
+* Formatted Output::            @code{printf} and related functions.
+* Customizing Printf::          You can define new conversion specifiers for
+				 @code{printf} and friends.
+* Formatted Input::             @code{scanf} and related functions.
+* EOF and Errors::              How you can tell if an I/O error happens.
+* Error Recovery::		What you can do about errors.
+* Binary Streams::              Some systems distinguish between text files
+				 and binary files.
+* File Positioning::            About random-access streams.
+* Portable Positioning::        Random access on peculiar ISO C systems.
+* Stream Buffering::            How to control buffering of streams.
+* Other Kinds of Streams::      Streams that do not necessarily correspond
+				 to an open file.
+* Formatted Messages::          Print strictly formatted messages.
+@end menu
+
+@node Streams
+@section Streams
+
+For historical reasons, the type of the C data structure that represents
+a stream is called @code{FILE} rather than ``stream''.  Since most of
+the library functions deal with objects of type @code{FILE *}, sometimes
+the term @dfn{file pointer} is also used to mean ``stream''.  This leads
+to unfortunate confusion over terminology in many books on C.  This
+manual, however, is careful to use the terms ``file'' and ``stream''
+only in the technical sense.
+@cindex file pointer
+
+@pindex stdio.h
+The @code{FILE} type is declared in the header file @file{stdio.h}.
+
+@comment stdio.h
+@comment ISO
+@deftp {Data Type} FILE
+This is the data type used to represent stream objects.  A @code{FILE}
+object holds all of the internal state information about the connection
+to the associated file, including such things as the file position
+indicator and buffering information.  Each stream also has error and
+end-of-file status indicators that can be tested with the @code{ferror}
+and @code{feof} functions; see @ref{EOF and Errors}.
+@end deftp
+
+@code{FILE} objects are allocated and managed internally by the
+input/output library functions.  Don't try to create your own objects of
+type @code{FILE}; let the library do it.  Your programs should
+deal only with pointers to these objects (that is, @code{FILE *} values)
+rather than the objects themselves.
+@c !!! should say that FILE's have "No user-serviceable parts inside."
+
+@node Standard Streams
+@section Standard Streams
+@cindex standard streams
+@cindex streams, standard
+
+When the @code{main} function of your program is invoked, it already has
+three predefined streams open and available for use.  These represent
+the ``standard'' input and output channels that have been established
+for the process.
+
+These streams are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypevar {FILE *} stdin
+The @dfn{standard input} stream, which is the normal source of input for the
+program.
+@end deftypevar
+@cindex standard input stream
+
+@comment stdio.h
+@comment ISO
+@deftypevar {FILE *} stdout
+The @dfn{standard output} stream, which is used for normal output from
+the program.
+@end deftypevar
+@cindex standard output stream
+
+@comment stdio.h
+@comment ISO
+@deftypevar {FILE *} stderr
+The @dfn{standard error} stream, which is used for error messages and
+diagnostics issued by the program.
+@end deftypevar
+@cindex standard error stream
+
+On @gnusystems{}, you can specify what files or processes correspond to
+these streams using the pipe and redirection facilities provided by the
+shell.  (The primitives shells use to implement these facilities are
+described in @ref{File System Interface}.)  Most other operating systems
+provide similar mechanisms, but the details of how to use them can vary.
+
+In @theglibc{}, @code{stdin}, @code{stdout}, and @code{stderr} are
+normal variables which you can set just like any others.  For example,
+to redirect the standard output to a file, you could do:
+
+@smallexample
+fclose (stdout);
+stdout = fopen ("standard-output-file", "w");
+@end smallexample
+
+Note however, that in other systems @code{stdin}, @code{stdout}, and
+@code{stderr} are macros that you cannot assign to in the normal way.
+But you can use @code{freopen} to get the effect of closing one and
+reopening it.  @xref{Opening Streams}.
+
+The three streams @code{stdin}, @code{stdout}, and @code{stderr} are not
+unoriented at program start (@pxref{Streams and I18N}).
+
+@node Opening Streams
+@section Opening Streams
+
+@cindex opening a stream
+Opening a file with the @code{fopen} function creates a new stream and
+establishes a connection between the stream and a file.  This may
+involve creating a new file.
+
+@pindex stdio.h
+Everything described in this section is declared in the header file
+@file{stdio.h}.
+
+@comment stdio.h
+@comment ISO
+@deftypefun {FILE *} fopen (const char *@var{filename}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+@c fopen may leak the list lock if cancelled within _IO_link_in.
+The @code{fopen} function opens a stream for I/O to the file
+@var{filename}, and returns a pointer to the stream.
+
+The @var{opentype} argument is a string that controls how the file is
+opened and specifies attributes of the resulting stream.  It must begin
+with one of the following sequences of characters:
+
+@table @samp
+@item r
+Open an existing file for reading only.
+
+@item w
+Open the file for writing only.  If the file already exists, it is
+truncated to zero length.  Otherwise a new file is created.
+
+@item a
+Open a file for append access; that is, writing at the end of file only.
+If the file already exists, its initial contents are unchanged and
+output to the stream is appended to the end of the file.
+Otherwise, a new, empty file is created.
+
+@item r+
+Open an existing file for both reading and writing.  The initial contents
+of the file are unchanged and the initial file position is at the
+beginning of the file.
+
+@item w+
+Open a file for both reading and writing.  If the file already exists, it
+is truncated to zero length.  Otherwise, a new file is created.
+
+@item a+
+Open or create file for both reading and appending.  If the file exists,
+its initial contents are unchanged.  Otherwise, a new file is created.
+The initial file position for reading is at the beginning of the file,
+but output is always appended to the end of the file.
+@end table
+
+As you can see, @samp{+} requests a stream that can do both input and
+output.  When using such a stream, you must call @code{fflush}
+(@pxref{Stream Buffering}) or a file positioning function such as
+@code{fseek} (@pxref{File Positioning}) when switching from reading
+to writing or vice versa.  Otherwise, internal buffers might not be
+emptied properly.
+
+Additional characters may appear after these to specify flags for the
+call.  Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
+the only part you are guaranteed will be understood by all systems.
+
+@Theglibc{} defines additional characters for use in @var{opentype}:
+
+@table @samp
+@item c
+The file is opened with cancellation in the I/O functions disabled.
+
+@item e
+The underlying file descriptor will be closed if you use any of the
+@code{exec@dots{}} functions (@pxref{Executing a File}).  (This is
+equivalent to having set @code{FD_CLOEXEC} on that descriptor.
+@xref{Descriptor Flags}.)
+
+@item m
+The file is opened and accessed using @code{mmap}.  This is only
+supported with files opened for reading.
+
+@item x
+Insist on creating a new file---if a file @var{filename} already
+exists, @code{fopen} fails rather than opening it.  If you use
+@samp{x} you are guaranteed that you will not clobber an existing
+file.  This is equivalent to the @code{O_EXCL} option to the
+@code{open} function (@pxref{Opening and Closing Files}).
+
+The @samp{x} modifier is part of @w{ISO C11}.
+@end table
+
+The character @samp{b} in @var{opentype} has a standard meaning; it
+requests a binary stream rather than a text stream.  But this makes no
+difference in POSIX systems (including @gnusystems{}).  If both
+@samp{+} and @samp{b} are specified, they can appear in either order.
+@xref{Binary Streams}.
+
+@cindex stream orientation
+@cindex orientation, stream
+If the @var{opentype} string contains the sequence
+@code{,ccs=@var{STRING}} then @var{STRING} is taken as the name of a
+coded character set and @code{fopen} will mark the stream as
+wide-oriented with appropriate conversion functions in place to convert
+from and to the character set @var{STRING}.  Any other stream
+is opened initially unoriented and the orientation is decided with the
+first file operation.  If the first operation is a wide character
+operation, the stream is not only marked as wide-oriented, also the
+conversion functions to convert to the coded character set used for the
+current locale are loaded.  This will not change anymore from this point
+on even if the locale selected for the @code{LC_CTYPE} category is
+changed.
+
+Any other characters in @var{opentype} are simply ignored.  They may be
+meaningful in other systems.
+
+If the open fails, @code{fopen} returns a null pointer.
+
+When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is in fact @code{fopen64} since the LFS
+interface replaces transparently the old interface.
+@end deftypefun
+
+You can have multiple streams (or file descriptors) pointing to the same
+file open at the same time.  If you do only input, this works
+straightforwardly, but you must be careful if any output streams are
+included.  @xref{Stream/Descriptor Precautions}.  This is equally true
+whether the streams are in one program (not usual) or in several
+programs (which can easily happen).  It may be advantageous to use the
+file locking facilities to avoid simultaneous access.  @xref{File
+Locks}.
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} fopen64 (const char *@var{filename}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+This function is similar to @code{fopen} but the stream it returns a
+pointer for is opened using @code{open64}.  Therefore this stream can be
+used even on files larger than @twoexp{31} bytes on 32 bit machines.
+
+Please note that the return type is still @code{FILE *}.  There is no
+special @code{FILE} type for the LFS interface.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fopen}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int FOPEN_MAX
+The value of this macro is an integer constant expression that
+represents the minimum number of streams that the implementation
+guarantees can be open simultaneously.  You might be able to open more
+than this many streams, but that is not guaranteed.  The value of this
+constant is at least eight, which includes the three standard streams
+@code{stdin}, @code{stdout}, and @code{stderr}.  In POSIX.1 systems this
+value is determined by the @code{OPEN_MAX} parameter; @pxref{General
+Limits}.  In BSD and GNU, it is controlled by the @code{RLIMIT_NOFILE}
+resource limit; @pxref{Limits on Resources}.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypefun {FILE *} freopen (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
+@c Like most I/O operations, this one is guarded by a recursive lock,
+@c released even upon cancellation, but cancellation may leak file
+@c descriptors and leave the stream in an inconsistent state (e.g.,
+@c still bound to the closed descriptor).  Also, if the stream is
+@c part-way through a significant update (say running freopen) when a
+@c signal handler calls freopen again on the same stream, the result is
+@c likely to be an inconsistent stream, and the possibility of closing
+@c twice file descriptor number that the stream used to use, the second
+@c time when it might have already been reused by another thread.
+This function is like a combination of @code{fclose} and @code{fopen}.
+It first closes the stream referred to by @var{stream}, ignoring any
+errors that are detected in the process.  (Because errors are ignored,
+you should not use @code{freopen} on an output stream if you have
+actually done any output using the stream.)  Then the file named by
+@var{filename} is opened with mode @var{opentype} as for @code{fopen},
+and associated with the same stream object @var{stream}.
+
+If the operation fails, a null pointer is returned; otherwise,
+@code{freopen} returns @var{stream}.
+
+@code{freopen} has traditionally been used to connect a standard stream
+such as @code{stdin} with a file of your own choice.  This is useful in
+programs in which use of a standard stream for certain purposes is
+hard-coded.  In @theglibc{}, you can simply close the standard
+streams and open new ones with @code{fopen}.  But other systems lack
+this ability, so using @code{freopen} is more portable.
+
+When the sources are compiling with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is in fact @code{freopen64} since the LFS
+interface replaces transparently the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun {FILE *} freopen64 (const char *@var{filename}, const char *@var{opentype}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsfd{}}}
+This function is similar to @code{freopen}.  The only difference is that
+on 32 bit machine the stream returned is able to read beyond the
+@twoexp{31} bytes limits imposed by the normal interface.  It should be
+noted that the stream pointed to by @var{stream} need not be opened
+using @code{fopen64} or @code{freopen64} since its mode is not important
+for this function.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{freopen}
+and so transparently replaces the old interface.
+@end deftypefun
+
+In some situations it is useful to know whether a given stream is
+available for reading or writing.  This information is normally not
+available and would have to be remembered separately.  Solaris
+introduced a few functions to get this information from the stream
+descriptor and these functions are also available in @theglibc{}.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __freadable (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{__freadable} function determines whether the stream
+@var{stream} was opened to allow reading.  In this case the return value
+is nonzero.  For write-only streams the function returns zero.
+
+This function is declared in @file{stdio_ext.h}.
+@end deftypefun
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __fwritable (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{__fwritable} function determines whether the stream
+@var{stream} was opened to allow writing.  In this case the return value
+is nonzero.  For read-only streams the function returns zero.
+
+This function is declared in @file{stdio_ext.h}.
+@end deftypefun
+
+For slightly different kind of problems there are two more functions.
+They provide even finer-grained information.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __freading (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{__freading} function determines whether the stream
+@var{stream} was last read from or whether it is opened read-only.  In
+this case the return value is nonzero, otherwise it is zero.
+Determining whether a stream opened for reading and writing was last
+used for writing allows to draw conclusions about the content about the
+buffer, among other things.
+
+This function is declared in @file{stdio_ext.h}.
+@end deftypefun
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __fwriting (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{__fwriting} function determines whether the stream
+@var{stream} was last written to or whether it is opened write-only.  In
+this case the return value is nonzero, otherwise it is zero.
+
+This function is declared in @file{stdio_ext.h}.
+@end deftypefun
+
+
+@node Closing Streams
+@section Closing Streams
+
+@cindex closing a stream
+When a stream is closed with @code{fclose}, the connection between the
+stream and the file is canceled.  After you have closed a stream, you
+cannot perform any additional operations on it.
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fclose (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c After fclose, it is undefined behavior to use the stream it points
+@c to.  Therefore, one must only call fclose when the stream is
+@c otherwise unused.  Concurrent uses started before will complete
+@c successfully because of the lock, which makes it MT-Safe.  Calling it
+@c from a signal handler is perfectly safe if the stream is known to be
+@c no longer used, which is a precondition for fclose to be safe in the
+@c first place; since this is no further requirement, fclose is safe for
+@c use in async signals too.  After calling fclose, you can no longer
+@c use the stream, not even to fclose it again, so its memory and file
+@c descriptor may leak if fclose is canceled before @c releasing them.
+@c That the stream must be unused and it becomes unused after the call
+@c is what would enable fclose to be AS- and AC-Safe while freopen
+@c isn't.  However, because of the possibility of leaving __gconv_lock
+@c taken upon cancellation, AC-Safety is lost.
+This function causes @var{stream} to be closed and the connection to
+the corresponding file to be broken.  Any buffered output is written
+and any buffered input is discarded.  The @code{fclose} function returns
+a value of @code{0} if the file was closed successfully, and @code{EOF}
+if an error was detected.
+
+It is important to check for errors when you call @code{fclose} to close
+an output stream, because real, everyday errors can be detected at this
+time.  For example, when @code{fclose} writes the remaining buffered
+output, it might get an error because the disk is full.  Even if you
+know the buffer is empty, errors can still occur when closing a file if
+you are using NFS.
+
+The function @code{fclose} is declared in @file{stdio.h}.
+@end deftypefun
+
+To close all streams currently available @theglibc{} provides
+another function.
+
+@comment stdio.h
+@comment GNU
+@deftypefun int fcloseall (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:streams}}@asunsafe{}@acsafe{}}
+@c Like fclose, using any previously-opened streams after fcloseall is
+@c undefined.  However, the implementation of fcloseall isn't equivalent
+@c to calling fclose for all streams: it just flushes and unbuffers all
+@c streams, without any locking.  It's the flushing without locking that
+@c makes it unsafe.
+This function causes all open streams of the process to be closed and
+the connection to corresponding files to be broken.  All buffered data
+is written and any buffered input is discarded.  The @code{fcloseall}
+function returns a value of @code{0} if all the files were closed
+successfully, and @code{EOF} if an error was detected.
+
+This function should be used only in special situations, e.g., when an
+error occurred and the program must be aborted.  Normally each single
+stream should be closed separately so that problems with individual
+streams can be identified.  It is also problematic since the standard
+streams (@pxref{Standard Streams}) will also be closed.
+
+The function @code{fcloseall} is declared in @file{stdio.h}.
+@end deftypefun
+
+If the @code{main} function to your program returns, or if you call the
+@code{exit} function (@pxref{Normal Termination}), all open streams are
+automatically closed properly.  If your program terminates in any other
+manner, such as by calling the @code{abort} function (@pxref{Aborting a
+Program}) or from a fatal signal (@pxref{Signal Handling}), open streams
+might not be closed properly.  Buffered output might not be flushed and
+files may be incomplete.  For more information on buffering of streams,
+see @ref{Stream Buffering}.
+
+@node Streams and Threads
+@section Streams and Threads
+
+@cindex threads
+@cindex multi-threaded application
+Streams can be used in multi-threaded applications in the same way they
+are used in single-threaded applications.  But the programmer must be
+aware of the possible complications.  It is important to know about
+these also if the program one writes never use threads since the design
+and implementation of many stream functions is heavily influenced by the
+requirements added by multi-threaded programming.
+
+The POSIX standard requires that by default the stream operations are
+atomic.  I.e., issuing two stream operations for the same stream in two
+threads at the same time will cause the operations to be executed as if
+they were issued sequentially.  The buffer operations performed while
+reading or writing are protected from other uses of the same stream.  To
+do this each stream has an internal lock object which has to be
+(implicitly) acquired before any work can be done.
+
+But there are situations where this is not enough and there are also
+situations where this is not wanted.  The implicit locking is not enough
+if the program requires more than one stream function call to happen
+atomically.  One example would be if an output line a program wants to
+generate is created by several function calls.  The functions by
+themselves would ensure only atomicity of their own operation, but not
+atomicity over all the function calls.  For this it is necessary to
+perform the stream locking in the application code.
+
+@comment stdio.h
+@comment POSIX
+@deftypefun void flockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+@c There's no way to tell whether the lock was acquired before or after
+@c cancellation so as to unlock only when appropriate.
+The @code{flockfile} function acquires the internal locking object
+associated with the stream @var{stream}.  This ensures that no other
+thread can explicitly through @code{flockfile}/@code{ftrylockfile} or
+implicit through a call of a stream function lock the stream.  The
+thread will block until the lock is acquired.  An explicit call to
+@code{funlockfile} has to be used to release the lock.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int ftrylockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+The @code{ftrylockfile} function tries to acquire the internal locking
+object associated with the stream @var{stream} just like
+@code{flockfile}.  But unlike @code{flockfile} this function does not
+block if the lock is not available.  @code{ftrylockfile} returns zero if
+the lock was successfully acquired.  Otherwise the stream is locked by
+another thread.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun void funlockfile (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+The @code{funlockfile} function releases the internal locking object of
+the stream @var{stream}.  The stream must have been locked before by a
+call to @code{flockfile} or a successful call of @code{ftrylockfile}.
+The implicit locking performed by the stream operations do not count.
+The @code{funlockfile} function does not return an error status and the
+behavior of a call for a stream which is not locked by the current
+thread is undefined.
+@end deftypefun
+
+The following example shows how the functions above can be used to
+generate an output line atomically even in multi-threaded applications
+(yes, the same job could be done with one @code{fprintf} call but it is
+sometimes not possible):
+
+@smallexample
+FILE *fp;
+@{
+   @dots{}
+   flockfile (fp);
+   fputs ("This is test number ", fp);
+   fprintf (fp, "%d\n", test);
+   funlockfile (fp)
+@}
+@end smallexample
+
+Without the explicit locking it would be possible for another thread to
+use the stream @var{fp} after the @code{fputs} call return and before
+@code{fprintf} was called with the result that the number does not
+follow the word @samp{number}.
+
+From this description it might already be clear that the locking objects
+in streams are no simple mutexes.  Since locking the same stream twice
+in the same thread is allowed the locking objects must be equivalent to
+recursive mutexes.  These mutexes keep track of the owner and the number
+of times the lock is acquired.  The same number of @code{funlockfile}
+calls by the same threads is necessary to unlock the stream completely.
+For instance:
+
+@smallexample
+void
+foo (FILE *fp)
+@{
+  ftrylockfile (fp);
+  fputs ("in foo\n", fp);
+  /* @r{This is very wrong!!!}  */
+  funlockfile (fp);
+@}
+@end smallexample
+
+It is important here that the @code{funlockfile} function is only called
+if the @code{ftrylockfile} function succeeded in locking the stream.  It
+is therefore always wrong to ignore the result of @code{ftrylockfile}.
+And it makes no sense since otherwise one would use @code{flockfile}.
+The result of code like that above is that either @code{funlockfile}
+tries to free a stream that hasn't been locked by the current thread or it
+frees the stream prematurely.  The code should look like this:
+
+@smallexample
+void
+foo (FILE *fp)
+@{
+  if (ftrylockfile (fp) == 0)
+    @{
+      fputs ("in foo\n", fp);
+      funlockfile (fp);
+    @}
+@}
+@end smallexample
+
+Now that we covered why it is necessary to have these locking it is
+necessary to talk about situations when locking is unwanted and what can
+be done.  The locking operations (explicit or implicit) don't come for
+free.  Even if a lock is not taken the cost is not zero.  The operations
+which have to be performed require memory operations that are safe in
+multi-processor environments.  With the many local caches involved in
+such systems this is quite costly.  So it is best to avoid the locking
+completely if it is not needed -- because the code in question is never
+used in a context where two or more threads may use a stream at a time.
+This can be determined most of the time for application code; for
+library code which can be used in many contexts one should default to be
+conservative and use locking.
+
+There are two basic mechanisms to avoid locking.  The first is to use
+the @code{_unlocked} variants of the stream operations.  The POSIX
+standard defines quite a few of those and @theglibc{} adds a few
+more.  These variants of the functions behave just like the functions
+with the name without the suffix except that they do not lock the
+stream.  Using these functions is very desirable since they are
+potentially much faster.  This is not only because the locking
+operation itself is avoided.  More importantly, functions like
+@code{putc} and @code{getc} are very simple and traditionally (before the
+introduction of threads) were implemented as macros which are very fast
+if the buffer is not empty.  With the addition of locking requirements
+these functions are no longer implemented as macros since they would
+expand to too much code.
+But these macros are still available with the same functionality under the new
+names @code{putc_unlocked} and @code{getc_unlocked}.  This possibly huge
+difference of speed also suggests the use of the @code{_unlocked}
+functions even if locking is required.  The difference is that the
+locking then has to be performed in the program:
+
+@smallexample
+void
+foo (FILE *fp, char *buf)
+@{
+  flockfile (fp);
+  while (*buf != '/')
+    putc_unlocked (*buf++, fp);
+  funlockfile (fp);
+@}
+@end smallexample
+
+If in this example the @code{putc} function would be used and the
+explicit locking would be missing the @code{putc} function would have to
+acquire the lock in every call, potentially many times depending on when
+the loop terminates.  Writing it the way illustrated above allows the
+@code{putc_unlocked} macro to be used which means no locking and direct
+manipulation of the buffer of the stream.
+
+A second way to avoid locking is by using a non-standard function which
+was introduced in Solaris and is available in @theglibc{} as well.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __fsetlocking (FILE *@var{stream}, int @var{type})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asulock{}}@acsafe{}}
+@c Changing the implicit-locking status of a stream while it's in use by
+@c another thread may cause a lock to be implicitly acquired and not
+@c released, or vice-versa.  This function should probably hold the lock
+@c while changing this setting, to make sure we don't change it while
+@c there are any concurrent uses.  Meanwhile, callers should acquire the
+@c lock themselves to be safe, and even concurrent uses with external
+@c locking will be fine, as long as functions that require external
+@c locking are not called without holding locks.
+
+The @code{__fsetlocking} function can be used to select whether the
+stream operations will implicitly acquire the locking object of the
+stream @var{stream}.  By default this is done but it can be disabled and
+reinstated using this function.  There are three values defined for the
+@var{type} parameter.
+
+@vtable @code
+@item FSETLOCKING_INTERNAL
+The stream @code{stream} will from now on use the default internal
+locking.  Every stream operation with exception of the @code{_unlocked}
+variants will implicitly lock the stream.
+
+@item FSETLOCKING_BYCALLER
+After the @code{__fsetlocking} function returns the user is responsible
+for locking the stream.  None of the stream operations will implicitly
+do this anymore until the state is set back to
+@code{FSETLOCKING_INTERNAL}.
+
+@item FSETLOCKING_QUERY
+@code{__fsetlocking} only queries the current locking state of the
+stream.  The return value will be @code{FSETLOCKING_INTERNAL} or
+@code{FSETLOCKING_BYCALLER} depending on the state.
+@end vtable
+
+The return value of @code{__fsetlocking} is either
+@code{FSETLOCKING_INTERNAL} or @code{FSETLOCKING_BYCALLER} depending on
+the state of the stream before the call.
+
+This function and the values for the @var{type} parameter are declared
+in @file{stdio_ext.h}.
+@end deftypefun
+
+This function is especially useful when program code has to be used
+which is written without knowledge about the @code{_unlocked} functions
+(or if the programmer was too lazy to use them).
+
+@node Streams and I18N
+@section Streams in Internationalized Applications
+
+@w{ISO C90} introduced the new type @code{wchar_t} to allow handling
+larger character sets.  What was missing was a possibility to output
+strings of @code{wchar_t} directly.  One had to convert them into
+multibyte strings using @code{mbstowcs} (there was no @code{mbsrtowcs}
+yet) and then use the normal stream functions.  While this is doable it
+is very cumbersome since performing the conversions is not trivial and
+greatly increases program complexity and size.
+
+The Unix standard early on (I think in XPG4.2) introduced two additional
+format specifiers for the @code{printf} and @code{scanf} families of
+functions.  Printing and reading of single wide characters was made
+possible using the @code{%C} specifier and wide character strings can be
+handled with @code{%S}.  These modifiers behave just like @code{%c} and
+@code{%s} only that they expect the corresponding argument to have the
+wide character type and that the wide character and string are
+transformed into/from multibyte strings before being used.
+
+This was a beginning but it is still not good enough.  Not always is it
+desirable to use @code{printf} and @code{scanf}.  The other, smaller and
+faster functions cannot handle wide characters.  Second, it is not
+possible to have a format string for @code{printf} and @code{scanf}
+consisting of wide characters.  The result is that format strings would
+have to be generated if they have to contain non-basic characters.
+
+@cindex C++ streams
+@cindex streams, C++
+In the @w{Amendment 1} to @w{ISO C90} a whole new set of functions was
+added to solve the problem.  Most of the stream functions got a
+counterpart which take a wide character or wide character string instead
+of a character or string respectively.  The new functions operate on the
+same streams (like @code{stdout}).  This is different from the model of
+the C++ runtime library where separate streams for wide and normal I/O
+are used.
+
+@cindex orientation, stream
+@cindex stream orientation
+Being able to use the same stream for wide and normal operations comes
+with a restriction: a stream can be used either for wide operations or
+for normal operations.  Once it is decided there is no way back.  Only a
+call to @code{freopen} or @code{freopen64} can reset the
+@dfn{orientation}.  The orientation can be decided in three ways:
+
+@itemize @bullet
+@item
+If any of the normal character functions is used (this includes the
+@code{fread} and @code{fwrite} functions) the stream is marked as not
+wide oriented.
+
+@item
+If any of the wide character functions is used the stream is marked as
+wide oriented.
+
+@item
+The @code{fwide} function can be used to set the orientation either way.
+@end itemize
+
+It is important to never mix the use of wide and not wide operations on
+a stream.  There are no diagnostics issued.  The application behavior
+will simply be strange or the application will simply crash.  The
+@code{fwide} function can help avoiding this.
+
+@comment wchar.h
+@comment ISO
+@deftypefun int fwide (FILE *@var{stream}, int @var{mode})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{}}}
+@c Querying is always safe, but changing the stream when it's in use
+@c upthread may be problematic.  Like most lock-acquiring functions,
+@c this one may leak the lock if canceled.
+
+The @code{fwide} function can be used to set and query the state of the
+orientation of the stream @var{stream}.  If the @var{mode} parameter has
+a positive value the streams get wide oriented, for negative values
+narrow oriented.  It is not possible to overwrite previous orientations
+with @code{fwide}.  I.e., if the stream @var{stream} was already
+oriented before the call nothing is done.
+
+If @var{mode} is zero the current orientation state is queried and
+nothing is changed.
+
+The @code{fwide} function returns a negative value, zero, or a positive
+value if the stream is narrow, not at all, or wide oriented
+respectively.
+
+This function was introduced in @w{Amendment 1} to @w{ISO C90} and is
+declared in @file{wchar.h}.
+@end deftypefun
+
+It is generally a good idea to orient a stream as early as possible.
+This can prevent surprise especially for the standard streams
+@code{stdin}, @code{stdout}, and @code{stderr}.  If some library
+function in some situations uses one of these streams and this use
+orients the stream in a different way the rest of the application
+expects it one might end up with hard to reproduce errors.  Remember
+that no errors are signal if the streams are used incorrectly.  Leaving
+a stream unoriented after creation is normally only necessary for
+library functions which create streams which can be used in different
+contexts.
+
+When writing code which uses streams and which can be used in different
+contexts it is important to query the orientation of the stream before
+using it (unless the rules of the library interface demand a specific
+orientation).  The following little, silly function illustrates this.
+
+@smallexample
+void
+print_f (FILE *fp)
+@{
+  if (fwide (fp, 0) > 0)
+    /* @r{Positive return value means wide orientation.}  */
+    fputwc (L'f', fp);
+  else
+    fputc ('f', fp);
+@}
+@end smallexample
+
+Note that in this case the function @code{print_f} decides about the
+orientation of the stream if it was unoriented before (will not happen
+if the advise above is followed).
+
+The encoding used for the @code{wchar_t} values is unspecified and the
+user must not make any assumptions about it.  For I/O of @code{wchar_t}
+values this means that it is impossible to write these values directly
+to the stream.  This is not what follows from the @w{ISO C} locale model
+either.  What happens instead is that the bytes read from or written to
+the underlying media are first converted into the internal encoding
+chosen by the implementation for @code{wchar_t}.  The external encoding
+is determined by the @code{LC_CTYPE} category of the current locale or
+by the @samp{ccs} part of the mode specification given to @code{fopen},
+@code{fopen64}, @code{freopen}, or @code{freopen64}.  How and when the
+conversion happens is unspecified and it happens invisible to the user.
+
+Since a stream is created in the unoriented state it has at that point
+no conversion associated with it.  The conversion which will be used is
+determined by the @code{LC_CTYPE} category selected at the time the
+stream is oriented.  If the locales are changed at the runtime this
+might produce surprising results unless one pays attention.  This is
+just another good reason to orient the stream explicitly as soon as
+possible, perhaps with a call to @code{fwide}.
+
+@node Simple Output
+@section Simple Output by Characters or Lines
+
+@cindex writing to a stream, by characters
+This section describes functions for performing character- and
+line-oriented output.
+
+These narrow streams functions are declared in the header file
+@file{stdio.h} and the wide stream functions in @file{wchar.h}.
+@pindex stdio.h
+@pindex wchar.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fputc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c If the stream is in use when interrupted by a signal, the recursive
+@c lock won't help ensure the stream is consistent; indeed, if fputc
+@c gets a signal precisely before the post-incremented _IO_write_ptr
+@c value is stored, we may overwrite the interrupted write.  Conversely,
+@c depending on compiler optimizations, the incremented _IO_write_ptr
+@c may be stored before the character is stored in the buffer,
+@c corrupting the stream if async cancel hits between the two stores.
+@c There may be other reasons for AS- and AC-unsafety in the overflow
+@c cases.
+The @code{fputc} function converts the character @var{c} to type
+@code{unsigned char}, and writes it to the stream @var{stream}.
+@code{EOF} is returned if a write error occurs; otherwise the
+character @var{c} is returned.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t fputwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+The @code{fputwc} function writes the wide character @var{wc} to the
+stream @var{stream}.  @code{WEOF} is returned if a write error occurs;
+otherwise the character @var{wc} is returned.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int fputc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c The unlocked functions can't possibly satisfy the MT-Safety
+@c requirements on their own, because they require external locking for
+@c safety.
+The @code{fputc_unlocked} function is equivalent to the @code{fputc}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment POSIX
+@deftypefun wint_t fputwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fputwc_unlocked} function is equivalent to the @code{fputwc}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int putc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+This is just like @code{fputc}, except that most systems implement it as
+a macro, making it faster.  One consequence is that it may evaluate the
+@var{stream} argument more than once, which is an exception to the
+general rule for macros.  @code{putc} is usually the best function to
+use for writing a single character.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+This is just like @code{fputwc}, except that it can be implement as
+a macro, making it faster.  One consequence is that it may evaluate the
+@var{stream} argument more than once, which is an exception to the
+general rule for macros.  @code{putwc} is usually the best function to
+use for writing a single wide character.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int putc_unlocked (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{putc_unlocked} function is equivalent to the @code{putc}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{putwc_unlocked} function is equivalent to the @code{putwc}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int putchar (int @var{c})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+The @code{putchar} function is equivalent to @code{putc} with
+@code{stdout} as the value of the @var{stream} argument.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t putwchar (wchar_t @var{wc})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+The @code{putwchar} function is equivalent to @code{putwc} with
+@code{stdout} as the value of the @var{stream} argument.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int putchar_unlocked (int @var{c})
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{putchar_unlocked} function is equivalent to the @code{putchar}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun wint_t putwchar_unlocked (wchar_t @var{wc})
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdout}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{putwchar_unlocked} function is equivalent to the @code{putwchar}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fputs (const char *@var{s}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+The function @code{fputs} writes the string @var{s} to the stream
+@var{stream}.  The terminating null character is not written.
+This function does @emph{not} add a newline character, either.
+It outputs only the characters in the string.
+
+This function returns @code{EOF} if a write error occurs, and otherwise
+a non-negative value.
+
+For example:
+
+@smallexample
+fputs ("Are ", stdout);
+fputs ("you ", stdout);
+fputs ("hungry?\n", stdout);
+@end smallexample
+
+@noindent
+outputs the text @samp{Are you hungry?} followed by a newline.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int fputws (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+The function @code{fputws} writes the wide character string @var{ws} to
+the stream @var{stream}.  The terminating null character is not written.
+This function does @emph{not} add a newline character, either.  It
+outputs only the characters in the string.
+
+This function returns @code{WEOF} if a write error occurs, and otherwise
+a non-negative value.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int fputs_unlocked (const char *@var{s}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fputs_unlocked} function is equivalent to the @code{fputs}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun int fputws_unlocked (const wchar_t *@var{ws}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fputws_unlocked} function is equivalent to the @code{fputws}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int puts (const char *@var{s})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{puts} function writes the string @var{s} to the stream
+@code{stdout} followed by a newline.  The terminating null character of
+the string is not written.  (Note that @code{fputs} does @emph{not}
+write a newline as this function does.)
+
+@code{puts} is the most convenient function for printing simple
+messages.  For example:
+
+@smallexample
+puts ("This is a message.");
+@end smallexample
+
+@noindent
+outputs the text @samp{This is a message.} followed by a newline.
+@end deftypefun
+
+@comment stdio.h
+@comment SVID
+@deftypefun int putw (int @var{w}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function writes the word @var{w} (that is, an @code{int}) to
+@var{stream}.  It is provided for compatibility with SVID, but we
+recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
+@end deftypefun
+
+@node Character Input
+@section Character Input
+
+@cindex reading from a stream, by characters
+This section describes functions for performing character-oriented
+input.  These narrow streams functions are declared in the header file
+@file{stdio.h} and the wide character functions are declared in
+@file{wchar.h}.
+@pindex stdio.h
+@pindex wchar.h
+
+These functions return an @code{int} or @code{wint_t} value (for narrow
+and wide stream functions respectively) that is either a character of
+input, or the special value @code{EOF}/@code{WEOF} (usually -1).  For
+the narrow stream functions it is important to store the result of these
+functions in a variable of type @code{int} instead of @code{char}, even
+when you plan to use it only as a character.  Storing @code{EOF} in a
+@code{char} variable truncates its value to the size of a character, so
+that it is no longer distinguishable from the valid character
+@samp{(char) -1}.  So always use an @code{int} for the result of
+@code{getc} and friends, and check for @code{EOF} after the call; once
+you've verified that the result is not @code{EOF}, you can be sure that
+it will fit in a @samp{char} variable without loss of information.
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fgetc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c Same caveats as fputc, but instead of losing a write in case of async
+@c signals, we may read the same character more than once, and the
+@c stream may be left in odd states due to cancellation in the underflow
+@c cases.
+This function reads the next character as an @code{unsigned char} from
+the stream @var{stream} and returns its value, converted to an
+@code{int}.  If an end-of-file condition or read error occurs,
+@code{EOF} is returned instead.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t fgetwc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function reads the next wide character from the stream @var{stream}
+and returns its value.  If an end-of-file condition or read error
+occurs, @code{WEOF} is returned instead.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int fgetc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fgetc_unlocked} function is equivalent to the @code{fgetc}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun wint_t fgetwc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fgetwc_unlocked} function is equivalent to the @code{fgetwc}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int getc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This is just like @code{fgetc}, except that it is permissible (and
+typical) for it to be implemented as a macro that evaluates the
+@var{stream} argument more than once.  @code{getc} is often highly
+optimized, so it is usually the best function to use to read a single
+character.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t getwc (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This is just like @code{fgetwc}, except that it is permissible for it to
+be implemented as a macro that evaluates the @var{stream} argument more
+than once.  @code{getwc} can be highly optimized, so it is usually the
+best function to use to read a single wide character.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int getc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{getc_unlocked} function is equivalent to the @code{getc}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun wint_t getwc_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{getwc_unlocked} function is equivalent to the @code{getwc}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int getchar (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
+as the value of the @var{stream} argument.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t getwchar (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{getwchar} function is equivalent to @code{getwc} with @code{stdin}
+as the value of the @var{stream} argument.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int getchar_unlocked (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{getchar_unlocked} function is equivalent to the @code{getchar}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun wint_t getwchar_unlocked (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:stdin}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{getwchar_unlocked} function is equivalent to the @code{getwchar}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+Here is an example of a function that does input using @code{fgetc}.  It
+would work just as well using @code{getc} instead, or using
+@code{getchar ()} instead of @w{@code{fgetc (stdin)}}.  The code would
+also work the same for the wide character stream functions.
+
+@smallexample
+int
+y_or_n_p (const char *question)
+@{
+  fputs (question, stdout);
+  while (1)
+    @{
+      int c, answer;
+      /* @r{Write a space to separate answer from question.} */
+      fputc (' ', stdout);
+      /* @r{Read the first character of the line.}
+	 @r{This should be the answer character, but might not be.} */
+      c = tolower (fgetc (stdin));
+      answer = c;
+      /* @r{Discard rest of input line.} */
+      while (c != '\n' && c != EOF)
+	c = fgetc (stdin);
+      /* @r{Obey the answer if it was valid.} */
+      if (answer == 'y')
+	return 1;
+      if (answer == 'n')
+	return 0;
+      /* @r{Answer was invalid: ask for valid answer.} */
+      fputs ("Please answer y or n:", stdout);
+    @}
+@}
+@end smallexample
+
+@comment stdio.h
+@comment SVID
+@deftypefun int getw (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function reads a word (that is, an @code{int}) from @var{stream}.
+It's provided for compatibility with SVID.  We recommend you use
+@code{fread} instead (@pxref{Block Input/Output}).  Unlike @code{getc},
+any @code{int} value could be a valid result.  @code{getw} returns
+@code{EOF} when it encounters end-of-file or an error, but there is no
+way to distinguish this from an input word with value -1.
+@end deftypefun
+
+@node Line Input
+@section Line-Oriented Input
+
+Since many programs interpret input on the basis of lines, it is
+convenient to have functions to read a line of text from a stream.
+
+Standard C has functions to do this, but they aren't very safe: null
+characters and even (for @code{gets}) long lines can confuse them.  So
+@theglibc{} provides the nonstandard @code{getline} function that
+makes it easy to read lines reliably.
+
+Another GNU extension, @code{getdelim}, generalizes @code{getline}.  It
+reads a delimited record, defined as everything through the next
+occurrence of a specified delimiter character.
+
+All these functions are declared in @file{stdio.h}.
+
+@comment stdio.h
+@comment GNU
+@deftypefun ssize_t getline (char **@var{lineptr}, size_t *@var{n}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c Besides the usual possibility of getting an inconsistent stream in a
+@c signal handler or leaving it inconsistent in case of cancellation,
+@c the possibility of leaving a dangling pointer upon cancellation
+@c between reallocing the buffer at *lineptr and updating the pointer
+@c brings about another case of @acucorrupt.
+This function reads an entire line from @var{stream}, storing the text
+(including the newline and a terminating null character) in a buffer
+and storing the buffer address in @code{*@var{lineptr}}.
+
+Before calling @code{getline}, you should place in @code{*@var{lineptr}}
+the address of a buffer @code{*@var{n}} bytes long, allocated with
+@code{malloc}.  If this buffer is long enough to hold the line,
+@code{getline} stores the line in this buffer.  Otherwise,
+@code{getline} makes the buffer bigger using @code{realloc}, storing the
+new buffer address back in @code{*@var{lineptr}} and the increased size
+back in @code{*@var{n}}.
+@xref{Unconstrained Allocation}.
+
+If you set @code{*@var{lineptr}} to a null pointer, and @code{*@var{n}}
+to zero, before the call, then @code{getline} allocates the initial
+buffer for you by calling @code{malloc}.  This buffer remains allocated
+even if @code{getline} encounters errors and is unable to read any bytes.
+
+In either case, when @code{getline} returns,  @code{*@var{lineptr}} is
+a @code{char *} which points to the text of the line.
+
+When @code{getline} is successful, it returns the number of characters
+read (including the newline, but not including the terminating null).
+This value enables you to distinguish null characters that are part of
+the line from the null character inserted as a terminator.
+
+This function is a GNU extension, but it is the recommended way to read
+lines from a stream.  The alternative standard functions are unreliable.
+
+If an error occurs or end of file is reached without any bytes read,
+@code{getline} returns @code{-1}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun ssize_t getdelim (char **@var{lineptr}, size_t *@var{n}, int @var{delimiter}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c See the getline @acucorrupt note.
+This function is like @code{getline} except that the character which
+tells it to stop reading is not necessarily newline.  The argument
+@var{delimiter} specifies the delimiter character; @code{getdelim} keeps
+reading until it sees that character (or end of file).
+
+The text is stored in @var{lineptr}, including the delimiter character
+and a terminating null.  Like @code{getline}, @code{getdelim} makes
+@var{lineptr} bigger if it isn't big enough.
+
+@code{getline} is in fact implemented in terms of @code{getdelim}, just
+like this:
+
+@smallexample
+ssize_t
+getline (char **lineptr, size_t *n, FILE *stream)
+@{
+  return getdelim (lineptr, n, '\n', stream);
+@}
+@end smallexample
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun {char *} fgets (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{fgets} function reads characters from the stream @var{stream}
+up to and including a newline character and stores them in the string
+@var{s}, adding a null character to mark the end of the string.  You
+must supply @var{count} characters worth of space in @var{s}, but the
+number of characters read is at most @var{count} @minus{} 1.  The extra
+character space is used to hold the null character at the end of the
+string.
+
+If the system is already at end of file when you call @code{fgets}, then
+the contents of the array @var{s} are unchanged and a null pointer is
+returned.  A null pointer is also returned if a read error occurs.
+Otherwise, the return value is the pointer @var{s}.
+
+@strong{Warning:}  If the input data has a null character, you can't tell.
+So don't use @code{fgets} unless you know the data cannot contain a null.
+Don't use it to read files edited by the user because, if the user inserts
+a null character, you should either handle it properly or print a clear
+error message.  We recommend using @code{getline} instead of @code{fgets}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} fgetws (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{fgetws} function reads wide characters from the stream
+@var{stream} up to and including a newline character and stores them in
+the string @var{ws}, adding a null wide character to mark the end of the
+string.  You must supply @var{count} wide characters worth of space in
+@var{ws}, but the number of characters read is at most @var{count}
+@minus{} 1.  The extra character space is used to hold the null wide
+character at the end of the string.
+
+If the system is already at end of file when you call @code{fgetws}, then
+the contents of the array @var{ws} are unchanged and a null pointer is
+returned.  A null pointer is also returned if a read error occurs.
+Otherwise, the return value is the pointer @var{ws}.
+
+@strong{Warning:} If the input data has a null wide character (which are
+null bytes in the input stream), you can't tell.  So don't use
+@code{fgetws} unless you know the data cannot contain a null.  Don't use
+it to read files edited by the user because, if the user inserts a null
+character, you should either handle it properly or print a clear error
+message.
+@comment XXX We need getwline!!!
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun {char *} fgets_unlocked (char *@var{s}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fgets_unlocked} function is equivalent to the @code{fgets}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} fgetws_unlocked (wchar_t *@var{ws}, int @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fgetws_unlocked} function is equivalent to the @code{fgetws}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefn {Deprecated function} {char *} gets (char *@var{s})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The function @code{gets} reads characters from the stream @code{stdin}
+up to the next newline character, and stores them in the string @var{s}.
+The newline character is discarded (note that this differs from the
+behavior of @code{fgets}, which copies the newline character into the
+string).  If @code{gets} encounters a read error or end-of-file, it
+returns a null pointer; otherwise it returns @var{s}.
+
+@strong{Warning:} The @code{gets} function is @strong{very dangerous}
+because it provides no protection against overflowing the string
+@var{s}.  @Theglibc{} includes it for compatibility only.  You
+should @strong{always} use @code{fgets} or @code{getline} instead.  To
+remind you of this, the linker (if using GNU @code{ld}) will issue a
+warning whenever you use @code{gets}.
+@end deftypefn
+
+@node Unreading
+@section Unreading
+@cindex peeking at input
+@cindex unreading characters
+@cindex pushing input back
+
+In parser programs it is often useful to examine the next character in
+the input stream without removing it from the stream.  This is called
+``peeking ahead'' at the input because your program gets a glimpse of
+the input it will read next.
+
+Using stream I/O, you can peek ahead at input by first reading it and
+then @dfn{unreading} it (also called  @dfn{pushing it back} on the stream).
+Unreading a character makes it available to be input again from the stream,
+by  the next call to @code{fgetc} or other input function on that stream.
+
+@menu
+* Unreading Idea::              An explanation of unreading with pictures.
+* How Unread::                  How to call @code{ungetc} to do unreading.
+@end menu
+
+@node Unreading Idea
+@subsection What Unreading Means
+
+Here is a pictorial explanation of unreading.  Suppose you have a
+stream reading a file that contains just six characters, the letters
+@samp{foobar}.  Suppose you have read three characters so far.  The
+situation looks like this:
+
+@smallexample
+f  o  o  b  a  r
+	 ^
+@end smallexample
+
+@noindent
+so the next input character will be @samp{b}.
+
+@c @group   Invalid outside @example
+If instead of reading @samp{b} you unread the letter @samp{o}, you get a
+situation like this:
+
+@smallexample
+f  o  o  b  a  r
+	 |
+      o--
+      ^
+@end smallexample
+
+@noindent
+so that the next input characters will be @samp{o} and @samp{b}.
+@c @end group
+
+@c @group
+If you unread @samp{9} instead of @samp{o}, you get this situation:
+
+@smallexample
+f  o  o  b  a  r
+	 |
+      9--
+      ^
+@end smallexample
+
+@noindent
+so that the next input characters will be @samp{9} and @samp{b}.
+@c @end group
+
+@node How Unread
+@subsection Using @code{ungetc} To Do Unreading
+
+The function to unread a character is called @code{ungetc}, because it
+reverses the action of @code{getc}.
+
+@comment stdio.h
+@comment ISO
+@deftypefun int ungetc (int @var{c}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{ungetc} function pushes back the character @var{c} onto the
+input stream @var{stream}.  So the next input from @var{stream} will
+read @var{c} before anything else.
+
+If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
+@code{EOF}.  This lets you call @code{ungetc} with the return value of
+@code{getc} without needing to check for an error from @code{getc}.
+
+The character that you push back doesn't have to be the same as the last
+character that was actually read from the stream.  In fact, it isn't
+necessary to actually read any characters from the stream before
+unreading them with @code{ungetc}!  But that is a strange way to write a
+program; usually @code{ungetc} is used only to unread a character that
+was just read from the same stream.  @Theglibc{} supports this
+even on files opened in binary mode, but other systems might not.
+
+@Theglibc{} only supports one character of pushback---in other
+words, it does not work to call @code{ungetc} twice without doing input
+in between.  Other systems might let you push back multiple characters;
+then reading from the stream retrieves the characters in the reverse
+order that they were pushed.
+
+Pushing back characters doesn't alter the file; only the internal
+buffering for the stream is affected.  If a file positioning function
+(such as @code{fseek}, @code{fseeko} or @code{rewind}; @pxref{File
+Positioning}) is called, any pending pushed-back characters are
+discarded.
+
+Unreading a character on a stream that is at end of file clears the
+end-of-file indicator for the stream, because it makes the character of
+input available.  After you read that character, trying to read again
+will encounter end of file.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun wint_t ungetwc (wint_t @var{wc}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{ungetwc} function behaves just like @code{ungetc} just that it
+pushes back a wide character.
+@end deftypefun
+
+Here is an example showing the use of @code{getc} and @code{ungetc} to
+skip over whitespace characters.  When this function reaches a
+non-whitespace character, it unreads that character to be seen again on
+the next read operation on the stream.
+
+@smallexample
+#include <stdio.h>
+#include <ctype.h>
+
+void
+skip_whitespace (FILE *stream)
+@{
+  int c;
+  do
+    /* @r{No need to check for @code{EOF} because it is not}
+       @r{@code{isspace}, and @code{ungetc} ignores @code{EOF}.}  */
+    c = getc (stream);
+  while (isspace (c));
+  ungetc (c, stream);
+@}
+@end smallexample
+
+@node Block Input/Output
+@section Block Input/Output
+
+This section describes how to do input and output operations on blocks
+of data.  You can use these functions to read and write binary data, as
+well as to read and write text in fixed-size blocks instead of by
+characters or lines.
+@cindex binary I/O to a stream
+@cindex block I/O to a stream
+@cindex reading from a stream, by blocks
+@cindex writing to a stream, by blocks
+
+Binary files are typically used to read and write blocks of data in the
+same format as is used to represent the data in a running program.  In
+other words, arbitrary blocks of memory---not just character or string
+objects---can be written to a binary file, and meaningfully read in
+again by the same program.
+
+Storing data in binary form is often considerably more efficient than
+using the formatted I/O functions.  Also, for floating-point numbers,
+the binary form avoids possible loss of precision in the conversion
+process.  On the other hand, binary files can't be examined or modified
+easily using many standard file utilities (such as text editors), and
+are not portable between different implementations of the language, or
+different kinds of computers.
+
+These functions are declared in @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun size_t fread (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function reads up to @var{count} objects of size @var{size} into
+the array @var{data}, from the stream @var{stream}.  It returns the
+number of objects actually read, which might be less than @var{count} if
+a read error occurs or the end of the file is reached.  This function
+returns a value of zero (and doesn't read anything) if either @var{size}
+or @var{count} is zero.
+
+If @code{fread} encounters end of file in the middle of an object, it
+returns the number of complete objects read, and discards the partial
+object.  Therefore, the stream remains at the actual end of the file.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun size_t fread_unlocked (void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fread_unlocked} function is equivalent to the @code{fread}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function writes up to @var{count} objects of size @var{size} from
+the array @var{data}, to the stream @var{stream}.  The return value is
+normally @var{count}, if the call succeeds.  Any other value indicates
+some sort of error, such as running out of space.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun size_t fwrite_unlocked (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fwrite_unlocked} function is equivalent to the @code{fwrite}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+@node Formatted Output
+@section Formatted Output
+
+@cindex format string, for @code{printf}
+@cindex template, for @code{printf}
+@cindex formatted output to a stream
+@cindex writing to a stream, formatted
+The functions described in this section (@code{printf} and related
+functions) provide a convenient way to perform formatted output.  You
+call @code{printf} with a @dfn{format string} or @dfn{template string}
+that specifies how to format the values of the remaining arguments.
+
+Unless your program is a filter that specifically performs line- or
+character-oriented processing, using @code{printf} or one of the other
+related functions described in this section is usually the easiest and
+most concise way to perform output.  These functions are especially
+useful for printing error messages, tables of data, and the like.
+
+@menu
+* 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}.
+@end menu
+
+@node Formatted Output Basics
+@subsection Formatted Output Basics
+
+The @code{printf} function can be used to print any number of arguments.
+The template string argument you supply in a call provides
+information not only about the number of additional arguments, but also
+about their types and what style should be used for printing them.
+
+Ordinary characters in the template string are simply written to the
+output stream as-is, while @dfn{conversion specifications} introduced by
+a @samp{%} character in the template cause subsequent arguments to be
+formatted and written to the output stream.  For example,
+@cindex conversion specifications (@code{printf})
+
+@smallexample
+int pct = 37;
+char filename[] = "foo.txt";
+printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
+	filename, pct);
+@end smallexample
+
+@noindent
+produces output like
+
+@smallexample
+Processing of `foo.txt' is 37% finished.
+Please be patient.
+@end smallexample
+
+This example shows the use of the @samp{%d} conversion to specify that
+an @code{int} argument should be printed in decimal notation, the
+@samp{%s} conversion to specify printing of a string argument, and
+the @samp{%%} conversion to print a literal @samp{%} character.
+
+There are also conversions for printing an integer argument as an
+unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
+@samp{%u}, or @samp{%x}, respectively); or as a character value
+(@samp{%c}).
+
+Floating-point numbers can be printed in normal, fixed-point notation
+using the @samp{%f} conversion or in exponential notation using the
+@samp{%e} conversion.  The @samp{%g} conversion uses either @samp{%e}
+or @samp{%f} format, depending on what is more appropriate for the
+magnitude of the particular number.
+
+You can control formatting more precisely by writing @dfn{modifiers}
+between the @samp{%} and the character that indicates which conversion
+to apply.  These slightly alter the ordinary behavior of the conversion.
+For example, most conversion specifications permit you to specify a
+minimum field width and a flag indicating whether you want the result
+left- or right-justified within the field.
+
+The specific flags and modifiers that are permitted and their
+interpretation vary depending on the particular conversion.  They're all
+described in more detail in the following sections.  Don't worry if this
+all seems excessively complicated at first; you can almost always get
+reasonable free-format output without using any of the modifiers at all.
+The modifiers are mostly used to make the output look ``prettier'' in
+tables.
+
+@node Output Conversion Syntax
+@subsection Output Conversion Syntax
+
+This section provides details about the precise syntax of conversion
+specifications that can appear in a @code{printf} template
+string.
+
+Characters in the template string that are not part of a conversion
+specification are printed as-is to the output stream.  Multibyte
+character sequences (@pxref{Character Set Handling}) are permitted in a
+template string.
+
+The conversion specifications in a @code{printf} template string have
+the general form:
+
+@smallexample
+% @r{[} @var{param-no} @r{$]} @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+% @r{[} @var{param-no} @r{$]} @var{flags} @var{width} . @r{*} @r{[} @var{param-no} @r{$]} @var{type} @var{conversion}
+@end smallexample
+
+For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
+is a flag, @samp{10} specifies the field width, the precision is
+@samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies
+the conversion style.  (This particular type specifier says to
+print a @code{long int} argument in decimal notation, with a minimum of
+8 digits left-justified in a field at least 10 characters wide.)
+
+In more detail, output conversion specifications consist of an
+initial @samp{%} character followed in sequence by:
+
+@itemize @bullet
+@item
+An optional specification of the parameter used for this format.
+Normally the parameters to the @code{printf} function are assigned to the
+formats in the order of appearance in the format string.  But in some
+situations (such as message translation) this is not desirable and this
+extension allows an explicit parameter to be specified.
+
+The @var{param-no} parts of the format must be integers in the range of
+1 to the maximum number of arguments present to the function call.  Some
+implementations limit this number to a certainly upper bound.  The exact
+limit can be retrieved by the following constant.
+
+@defvr Macro NL_ARGMAX
+The value of @code{NL_ARGMAX} is the maximum value allowed for the
+specification of a positional parameter in a @code{printf} call.  The
+actual value in effect at runtime can be retrieved by using
+@code{sysconf} using the @code{_SC_NL_ARGMAX} parameter @pxref{Sysconf
+Definition}.
+
+Some system have a quite low limit such as @math{9} for @w{System V}
+systems.  @Theglibc{} has no real limit.
+@end defvr
+
+If any of the formats has a specification for the parameter position all
+of them in the format string shall have one.  Otherwise the behavior is
+undefined.
+
+@item
+Zero or more @dfn{flag characters} that modify the normal behavior of
+the conversion specification.
+@cindex flag character (@code{printf})
+
+@item
+An optional decimal integer specifying the @dfn{minimum field width}.
+If the normal conversion produces fewer characters than this, the field
+is padded with spaces to the specified width.  This is a @emph{minimum}
+value; if the normal conversion produces more characters than this, the
+field is @emph{not} truncated.  Normally, the output is right-justified
+within the field.
+@cindex minimum field width (@code{printf})
+
+You can also specify a field width of @samp{*}.  This means that the
+next argument in the argument list (before the actual value to be
+printed) is used as the field width.  The value must be an @code{int}.
+If the value is negative, this means to set the @samp{-} flag (see
+below) and to use the absolute value as the field width.
+
+@item
+An optional @dfn{precision} to specify the number of digits to be
+written for the numeric conversions.  If the precision is specified, it
+consists of a period (@samp{.}) followed optionally by a decimal integer
+(which defaults to zero if omitted).
+@cindex precision (@code{printf})
+
+You can also specify a precision of @samp{*}.  This means that the next
+argument in the argument list (before the actual value to be printed) is
+used as the precision.  The value must be an @code{int}, and is ignored
+if it is negative.  If you specify @samp{*} for both the field width and
+precision, the field width argument precedes the precision argument.
+Other C library versions may not recognize this syntax.
+
+@item
+An optional @dfn{type modifier character}, which is used to specify the
+data type of the corresponding argument if it differs from the default
+type.  (For example, the integer conversions assume a type of @code{int},
+but you can specify @samp{h}, @samp{l}, or @samp{L} for other integer
+types.)
+@cindex type modifier character (@code{printf})
+
+@item
+A character that specifies the conversion to be applied.
+@end itemize
+
+The exact options that are permitted and how they are interpreted vary
+between the different conversion specifiers.  See the descriptions of the
+individual conversions for information about the particular options that
+they use.
+
+With the @samp{-Wformat} option, the GNU C compiler checks calls to
+@code{printf} and related functions.  It examines the format string and
+verifies that the correct number and types of arguments are supplied.
+There is also a GNU C syntax to tell the compiler that a function you
+write uses a @code{printf}-style format string.
+@xref{Function Attributes, , Declaring Attributes of Functions,
+gcc.info, Using GNU CC}, for more information.
+
+@node Table of Output Conversions
+@subsection Table of Output Conversions
+@cindex output conversions, for @code{printf}
+
+Here is a table summarizing what all the different conversions do:
+
+@table @asis
+@item @samp{%d}, @samp{%i}
+Print an integer as a signed decimal number.  @xref{Integer
+Conversions}, for details.  @samp{%d} and @samp{%i} are synonymous for
+output, but are different when used with @code{scanf} for input
+(@pxref{Table of Input Conversions}).
+
+@item @samp{%o}
+Print an integer as an unsigned octal number.  @xref{Integer
+Conversions}, for details.
+
+@item @samp{%u}
+Print an integer as an unsigned decimal number.  @xref{Integer
+Conversions}, for details.
+
+@item @samp{%x}, @samp{%X}
+Print an integer as an unsigned hexadecimal number.  @samp{%x} uses
+lower-case letters and @samp{%X} uses upper-case.  @xref{Integer
+Conversions}, for details.
+
+@item @samp{%f}
+Print a floating-point number in normal (fixed-point) notation.
+@xref{Floating-Point Conversions}, for details.
+
+@item @samp{%e}, @samp{%E}
+Print a floating-point number in exponential notation.  @samp{%e} uses
+lower-case letters and @samp{%E} uses upper-case.  @xref{Floating-Point
+Conversions}, for details.
+
+@item @samp{%g}, @samp{%G}
+Print a floating-point number in either normal or exponential notation,
+whichever is more appropriate for its magnitude.  @samp{%g} uses
+lower-case letters and @samp{%G} uses upper-case.  @xref{Floating-Point
+Conversions}, for details.
+
+@item @samp{%a}, @samp{%A}
+Print a floating-point number in a hexadecimal fractional notation which
+the exponent to base 2 represented in decimal digits.  @samp{%a} uses
+lower-case letters and @samp{%A} uses upper-case.  @xref{Floating-Point
+Conversions}, for details.
+
+@item @samp{%c}
+Print a single character.  @xref{Other Output Conversions}.
+
+@item @samp{%C}
+This is an alias for @samp{%lc} which is supported for compatibility
+with the Unix standard.
+
+@item @samp{%s}
+Print a string.  @xref{Other Output Conversions}.
+
+@item @samp{%S}
+This is an alias for @samp{%ls} which is supported for compatibility
+with the Unix standard.
+
+@item @samp{%p}
+Print the value of a pointer.  @xref{Other Output Conversions}.
+
+@item @samp{%n}
+Get the number of characters printed so far.  @xref{Other Output Conversions}.
+Note that this conversion specification never produces any output.
+
+@item @samp{%m}
+Print the string corresponding to the value of @code{errno}.
+(This is a GNU extension.)
+@xref{Other Output Conversions}.
+
+@item @samp{%%}
+Print a literal @samp{%} character.  @xref{Other Output Conversions}.
+@end table
+
+If the syntax of a conversion specification is invalid, unpredictable
+things will happen, so don't do this.  If there aren't enough function
+arguments provided to supply values for all the conversion
+specifications in the template string, or if the arguments are not of
+the correct types, the results are unpredictable.  If you supply more
+arguments than conversion specifications, the extra argument values are
+simply ignored; this is sometimes useful.
+
+@node Integer Conversions
+@subsection Integer Conversions
+
+This section describes the options for the @samp{%d}, @samp{%i},
+@samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
+specifications.  These conversions print integers in various formats.
+
+The @samp{%d} and @samp{%i} conversion specifications both print an
+@code{int} argument as a signed decimal number; while @samp{%o},
+@samp{%u}, and @samp{%x} print the argument as an unsigned octal,
+decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
+specification is just like @samp{%x} except that it uses the characters
+@samp{ABCDEF} as digits instead of @samp{abcdef}.
+
+The following flags are meaningful:
+
+@table @asis
+@item @samp{-}
+Left-justify the result in the field (instead of the normal
+right-justification).
+
+@item @samp{+}
+For the signed @samp{%d} and @samp{%i} conversions, print a
+plus sign if the value is positive.
+
+@item @samp{ }
+For the signed @samp{%d} and @samp{%i} conversions, if the result
+doesn't start with a plus or minus sign, prefix it with a space
+character instead.  Since the @samp{+} flag ensures that the result
+includes a sign, this flag is ignored if you supply both of them.
+
+@item @samp{#}
+For the @samp{%o} conversion, this forces the leading digit to be
+@samp{0}, as if by increasing the precision.  For @samp{%x} or
+@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
+to the result.  This doesn't do anything useful for the @samp{%d},
+@samp{%i}, or @samp{%u} conversions.  Using this flag produces output
+which can be parsed by the @code{strtoul} function (@pxref{Parsing of
+Integers}) and @code{scanf} with the @samp{%i} conversion
+(@pxref{Numeric Input Conversions}).
+
+@item @samp{'}
+Separate the digits into groups as specified by the locale specified for
+the @code{LC_NUMERIC} category; @pxref{General Numeric}.  This flag is a
+GNU extension.
+
+@item @samp{0}
+Pad the field with zeros instead of spaces.  The zeros are placed after
+any indication of sign or base.  This flag is ignored if the @samp{-}
+flag is also specified, or if a precision is specified.
+@end table
+
+If a precision is supplied, it specifies the minimum number of digits to
+appear; leading zeros are produced if necessary.  If you don't specify a
+precision, the number is printed with as many digits as it needs.  If
+you convert a value of zero with an explicit precision of zero, then no
+characters at all are produced.
+
+Without a type modifier, the corresponding argument is treated as an
+@code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
+@code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
+@samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
+are variadic, any @code{char} and @code{short} arguments are
+automatically converted to @code{int} by the default argument
+promotions.  For arguments of other integer types, you can use these
+modifiers:
+
+@table @samp
+@item hh
+Specifies that the argument is a @code{signed char} or @code{unsigned
+char}, as appropriate.  A @code{char} argument is converted to an
+@code{int} or @code{unsigned int} by the default argument promotions
+anyway, but the @samp{h} modifier says to convert it back to a
+@code{char} again.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item h
+Specifies that the argument is a @code{short int} or @code{unsigned
+short int}, as appropriate.  A @code{short} argument is converted to an
+@code{int} or @code{unsigned int} by the default argument promotions
+anyway, but the @samp{h} modifier says to convert it back to a
+@code{short} again.
+
+@item j
+Specifies that the argument is a @code{intmax_t} or @code{uintmax_t}, as
+appropriate.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item l
+Specifies that the argument is a @code{long int} or @code{unsigned long
+int}, as appropriate.  Two @samp{l} characters is like the @samp{L}
+modifier, below.
+
+If used with @samp{%c} or @samp{%s} the corresponding parameter is
+considered as a wide character or wide character string respectively.
+This use of @samp{l} was introduced in @w{Amendment 1} to @w{ISO C90}.
+
+@item L
+@itemx ll
+@itemx q
+Specifies that the argument is a @code{long long int}.  (This type is
+an extension supported by the GNU C compiler.  On systems that don't
+support extra-long integers, this is the same as @code{long int}.)
+
+The @samp{q} modifier is another name for the same thing, which comes
+from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
+@code{int}.
+
+@item t
+Specifies that the argument is a @code{ptrdiff_t}.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item z
+@itemx Z
+Specifies that the argument is a @code{size_t}.
+
+@samp{z} was introduced in @w{ISO C99}.  @samp{Z} is a GNU extension
+predating this addition and should not be used in new code.
+@end table
+
+Here is an example.  Using the template string:
+
+@smallexample
+"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
+@end smallexample
+
+@noindent
+to print numbers using the different options for the @samp{%d}
+conversion gives results like:
+
+@smallexample
+|    0|0    |   +0|+0   |    0|00000|     |   00|0|
+|    1|1    |   +1|+1   |    1|00001|    1|   01|1|
+|   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
+|100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
+@end smallexample
+
+In particular, notice what happens in the last case where the number
+is too large to fit in the minimum field width specified.
+
+Here are some more examples showing how unsigned integers print under
+various format options, using the template string:
+
+@smallexample
+"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
+@end smallexample
+
+@smallexample
+|    0|    0|    0|    0|    0|    0|    0|  00000000|
+|    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
+|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
+@end smallexample
+
+
+@node Floating-Point Conversions
+@subsection Floating-Point Conversions
+
+This section discusses the conversion specifications for floating-point
+numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G}
+conversions.
+
+The @samp{%f} conversion prints its argument in fixed-point notation,
+producing output of the form
+@w{[@code{-}]@var{ddd}@code{.}@var{ddd}},
+where the number of digits following the decimal point is controlled
+by the precision you specify.
+
+The @samp{%e} conversion prints its argument in exponential notation,
+producing output of the form
+@w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}.
+Again, the number of digits following the decimal point is controlled by
+the precision.  The exponent always contains at least two digits.  The
+@samp{%E} conversion is similar but the exponent is marked with the letter
+@samp{E} instead of @samp{e}.
+
+The @samp{%g} and @samp{%G} conversions print the argument in the style
+of @samp{%e} or @samp{%E} (respectively) if the exponent would be less
+than -4 or greater than or equal to the precision; otherwise they use
+the @samp{%f} style.  A precision of @code{0}, is taken as 1.
+Trailing zeros are removed from the fractional portion of the result and
+a decimal-point character appears only if it is followed by a digit.
+
+The @samp{%a} and @samp{%A} conversions are meant for representing
+floating-point numbers exactly in textual form so that they can be
+exchanged as texts between different programs and/or machines.  The
+numbers are represented is the form
+@w{[@code{-}]@code{0x}@var{h}@code{.}@var{hhh}@code{p}[@code{+}|@code{-}]@var{dd}}.
+At the left of the decimal-point character exactly one digit is print.
+This character is only @code{0} if the number is denormalized.
+Otherwise the value is unspecified; it is implementation dependent how many
+bits are used.  The number of hexadecimal digits on the right side of
+the decimal-point character is equal to the precision.  If the precision
+is zero it is determined to be large enough to provide an exact
+representation of the number (or it is large enough to distinguish two
+adjacent values if the @code{FLT_RADIX} is not a power of 2,
+@pxref{Floating Point Parameters}).  For the @samp{%a} conversion
+lower-case characters are used to represent the hexadecimal number and
+the prefix and exponent sign are printed as @code{0x} and @code{p}
+respectively.  Otherwise upper-case characters are used and @code{0X}
+and @code{P} are used for the representation of prefix and exponent
+string.  The exponent to the base of two is printed as a decimal number
+using at least one digit but at most as many digits as necessary to
+represent the value exactly.
+
+If the value to be printed represents infinity or a NaN, the output is
+@w{[@code{-}]@code{inf}} or @code{nan} respectively if the conversion
+specifier is @samp{%a}, @samp{%e}, @samp{%f}, or @samp{%g} and it is
+@w{[@code{-}]@code{INF}} or @code{NAN} respectively if the conversion is
+@samp{%A}, @samp{%E}, or @samp{%G}.
+
+The following flags can be used to modify the behavior:
+
+@comment We use @asis instead of @samp so we can have ` ' as an item.
+@table @asis
+@item @samp{-}
+Left-justify the result in the field.  Normally the result is
+right-justified.
+
+@item @samp{+}
+Always include a plus or minus sign in the result.
+
+@item @samp{ }
+If the result doesn't start with a plus or minus sign, prefix it with a
+space instead.  Since the @samp{+} flag ensures that the result includes
+a sign, this flag is ignored if you supply both of them.
+
+@item @samp{#}
+Specifies that the result should always include a decimal point, even
+if no digits follow it.  For the @samp{%g} and @samp{%G} conversions,
+this also forces trailing zeros after the decimal point to be left
+in place where they would otherwise be removed.
+
+@item @samp{'}
+Separate the digits of the integer part of the result into groups as
+specified by the locale specified for the @code{LC_NUMERIC} category;
+@pxref{General Numeric}.  This flag is a GNU extension.
+
+@item @samp{0}
+Pad the field with zeros instead of spaces; the zeros are placed
+after any sign.  This flag is ignored if the @samp{-} flag is also
+specified.
+@end table
+
+The precision specifies how many digits follow the decimal-point
+character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions.  For
+these conversions, the default precision is @code{6}.  If the precision
+is explicitly @code{0}, this suppresses the decimal point character
+entirely.  For the @samp{%g} and @samp{%G} conversions, the precision
+specifies how many significant digits to print.  Significant digits are
+the first digit before the decimal point, and all the digits after it.
+If the precision is @code{0} or not specified for @samp{%g} or @samp{%G},
+it is treated like a value of @code{1}.  If the value being printed
+cannot be expressed accurately in the specified number of digits, the
+value is rounded to the nearest number that fits.
+
+Without a type modifier, the floating-point conversions use an argument
+of type @code{double}.  (By the default argument promotions, any
+@code{float} arguments are automatically converted to @code{double}.)
+The following type modifier is supported:
+
+@table @samp
+@item L
+An uppercase @samp{L} specifies that the argument is a @code{long
+double}.
+@end table
+
+Here are some examples showing how numbers print using the various
+floating-point conversions.  All of the numbers were printed using
+this template string:
+
+@smallexample
+"|%13.4a|%13.4f|%13.4e|%13.4g|\n"
+@end smallexample
+
+Here is the output:
+
+@smallexample
+|  0x0.0000p+0|       0.0000|   0.0000e+00|            0|
+|  0x1.0000p-1|       0.5000|   5.0000e-01|          0.5|
+|  0x1.0000p+0|       1.0000|   1.0000e+00|            1|
+| -0x1.0000p+0|      -1.0000|  -1.0000e+00|           -1|
+|  0x1.9000p+6|     100.0000|   1.0000e+02|          100|
+|  0x1.f400p+9|    1000.0000|   1.0000e+03|         1000|
+| 0x1.3880p+13|   10000.0000|   1.0000e+04|        1e+04|
+| 0x1.81c8p+13|   12345.0000|   1.2345e+04|    1.234e+04|
+| 0x1.86a0p+16|  100000.0000|   1.0000e+05|        1e+05|
+| 0x1.e240p+16|  123456.0000|   1.2346e+05|    1.235e+05|
+@end smallexample
+
+Notice how the @samp{%g} conversion drops trailing zeros.
+
+@node Other Output Conversions
+@subsection Other Output Conversions
+
+This section describes miscellaneous conversions for @code{printf}.
+
+The @samp{%c} conversion prints a single character.  In case there is no
+@samp{l} modifier the @code{int} argument is first converted to an
+@code{unsigned char}.  Then, if used in a wide stream function, the
+character is converted into the corresponding wide character.  The
+@samp{-} flag can be used to specify left-justification in the field,
+but no other flags are defined, and no precision or type modifier can be
+given.  For example:
+
+@smallexample
+printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
+@end smallexample
+
+@noindent
+prints @samp{hello}.
+
+If there is a @samp{l} modifier present the argument is expected to be
+of type @code{wint_t}.  If used in a multibyte function the wide
+character is converted into a multibyte character before being added to
+the output.  In this case more than one output byte can be produced.
+
+The @samp{%s} conversion prints a string.  If no @samp{l} modifier is
+present the corresponding argument must be of type @code{char *} (or
+@code{const char *}).  If used in a wide stream function the string is
+first converted in a wide character string.  A precision can be
+specified to indicate the maximum number of characters to write;
+otherwise characters in the string up to but not including the
+terminating null character are written to the output stream.  The
+@samp{-} flag can be used to specify left-justification in the field,
+but no other flags or type modifiers are defined for this conversion.
+For example:
+
+@smallexample
+printf ("%3s%-6s", "no", "where");
+@end smallexample
+
+@noindent
+prints @samp{ nowhere }.
+
+If there is a @samp{l} modifier present the argument is expected to be of type @code{wchar_t} (or @code{const wchar_t *}).
+
+If you accidentally pass a null pointer as the argument for a @samp{%s}
+conversion, @theglibc{} prints it as @samp{(null)}.  We think this
+is more useful than crashing.  But it's not good practice to pass a null
+argument intentionally.
+
+The @samp{%m} conversion prints the string corresponding to the error
+code in @code{errno}.  @xref{Error Messages}.  Thus:
+
+@smallexample
+fprintf (stderr, "can't open `%s': %m\n", filename);
+@end smallexample
+
+@noindent
+is equivalent to:
+
+@smallexample
+fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
+@end smallexample
+
+@noindent
+The @samp{%m} conversion is a @glibcadj{} extension.
+
+The @samp{%p} conversion prints a pointer value.  The corresponding
+argument must be of type @code{void *}.  In practice, you can use any
+type of pointer.
+
+In @theglibc{}, non-null pointers are printed as unsigned integers,
+as if a @samp{%#x} conversion were used.  Null pointers print as
+@samp{(nil)}.  (Pointers might print differently in other systems.)
+
+For example:
+
+@smallexample
+printf ("%p", "testing");
+@end smallexample
+
+@noindent
+prints @samp{0x} followed by a hexadecimal number---the address of the
+string constant @code{"testing"}.  It does not print the word
+@samp{testing}.
+
+You can supply the @samp{-} flag with the @samp{%p} conversion to
+specify left-justification, but no other flags, precision, or type
+modifiers are defined.
+
+The @samp{%n} conversion is unlike any of the other output conversions.
+It uses an argument which must be a pointer to an @code{int}, but
+instead of printing anything it stores the number of characters printed
+so far by this call at that location.  The @samp{h} and @samp{l} type
+modifiers are permitted to specify that the argument is of type
+@code{short int *} or @code{long int *} instead of @code{int *}, but no
+flags, field width, or precision are permitted.
+
+For example,
+
+@smallexample
+int nchar;
+printf ("%d %s%n\n", 3, "bears", &nchar);
+@end smallexample
+
+@noindent
+prints:
+
+@smallexample
+3 bears
+@end smallexample
+
+@noindent
+and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven
+characters.
+
+
+The @samp{%%} conversion prints a literal @samp{%} character.  This
+conversion doesn't use an argument, and no flags, field width,
+precision, or type modifiers are permitted.
+
+
+@node Formatted Output Functions
+@subsection Formatted Output Functions
+
+This section describes how to call @code{printf} and related functions.
+Prototypes for these functions are in the header file @file{stdio.h}.
+Because these functions take a variable number of arguments, you
+@emph{must} declare prototypes for them before using them.  Of course,
+the easiest way to make sure you have all the right prototypes is to
+just include @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int printf (const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+The @code{printf} function prints the optional arguments under the
+control of the template string @var{template} to the stream
+@code{stdout}.  It returns the number of characters printed, or a
+negative value if there was an output error.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wprintf (const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+The @code{wprintf} function prints the optional arguments under the
+control of the wide template string @var{template} to the stream
+@code{stdout}.  It returns the number of wide characters printed, or a
+negative value if there was an output error.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fprintf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is just like @code{printf}, except that the output is
+written to the stream @var{stream} instead of @code{stdout}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int fwprintf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is just like @code{wprintf}, except that the output is
+written to the stream @var{stream} instead of @code{stdout}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int sprintf (char *@var{s}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is like @code{printf}, except that the output is stored in the character
+array @var{s} instead of written to a stream.  A null character is written
+to mark the end of the string.
+
+The @code{sprintf} function returns the number of characters stored in
+the array @var{s}, not including the terminating null character.
+
+The behavior of this function is undefined if copying takes place
+between objects that overlap---for example, if @var{s} is also given
+as an argument to be printed under control of the @samp{%s} conversion.
+@xref{Copying Strings and Arrays}.
+
+@strong{Warning:} The @code{sprintf} function can be @strong{dangerous}
+because it can potentially output more characters than can fit in the
+allocation size of the string @var{s}.  Remember that the field width
+given in a conversion specification is only a @emph{minimum} value.
+
+To avoid this problem, you can use @code{snprintf} or @code{asprintf},
+described below.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun int swprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is like @code{wprintf}, except that the output is stored in the
+wide character array @var{ws} instead of written to a stream.  A null
+wide character is written to mark the end of the string.  The @var{size}
+argument specifies the maximum number of characters to produce.  The
+trailing null character is counted towards this limit, so you should
+allocate at least @var{size} wide characters for the string @var{ws}.
+
+The return value is the number of characters generated for the given
+input, excluding the trailing null.  If not all output fits into the
+provided buffer a negative value is returned.  You should try again with
+a bigger output string.  @emph{Note:} this is different from how
+@code{snprintf} handles this situation.
+
+Note that the corresponding narrow stream function takes fewer
+parameters.  @code{swprintf} in fact corresponds to the @code{snprintf}
+function.  Since the @code{sprintf} function can be dangerous and should
+be avoided the @w{ISO C} committee refused to make the same mistake
+again and decided to not define a function exactly corresponding to
+@code{sprintf}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int snprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{snprintf} function is similar to @code{sprintf}, except that
+the @var{size} argument specifies the maximum number of characters to
+produce.  The trailing null character is counted towards this limit, so
+you should allocate at least @var{size} characters for the string @var{s}.
+If @var{size} is zero, nothing, not even the null byte, shall be written and
+@var{s} may be a null pointer.
+
+The return value is the number of characters which would be generated
+for the given input, excluding the trailing null.  If this value is
+greater or equal to @var{size}, not all characters from the result have
+been stored in @var{s}.  You should try again with a bigger output
+string.  Here is an example of doing this:
+
+@smallexample
+@group
+/* @r{Construct a message describing the value of a variable}
+   @r{whose name is @var{name} and whose value is @var{value}.} */
+char *
+make_message (char *name, char *value)
+@{
+  /* @r{Guess we need no more than 100 chars of space.} */
+  int size = 100;
+  char *buffer = (char *) xmalloc (size);
+  int nchars;
+@end group
+@group
+  if (buffer == NULL)
+    return NULL;
+
+ /* @r{Try to print in the allocated space.} */
+  nchars = snprintf (buffer, size, "value of %s is %s",
+		     name, value);
+@end group
+@group
+  if (nchars >= size)
+    @{
+      /* @r{Reallocate buffer now that we know
+	 how much space is needed.} */
+      size = nchars + 1;
+      buffer = (char *) xrealloc (buffer, size);
+
+      if (buffer != NULL)
+	/* @r{Try again.} */
+	snprintf (buffer, size, "value of %s is %s",
+		  name, value);
+    @}
+  /* @r{The last call worked, return the string.} */
+  return buffer;
+@}
+@end group
+@end smallexample
+
+In practice, it is often easier just to use @code{asprintf}, below.
+
+@strong{Attention:} In versions of @theglibc{} prior to 2.1 the
+return value is the number of characters stored, not including the
+terminating null; unless there was not enough space in @var{s} to
+store the result in which case @code{-1} is returned.  This was
+changed in order to comply with the @w{ISO C99} standard.
+@end deftypefun
+
+@node Dynamic Output
+@subsection Dynamically Allocating Formatted Output
+
+The functions in this section do formatted output and place the results
+in dynamically allocated memory.
+
+@comment stdio.h
+@comment GNU
+@deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function is similar to @code{sprintf}, except that it dynamically
+allocates a string (as with @code{malloc}; @pxref{Unconstrained
+Allocation}) to hold the output, instead of putting the output in a
+buffer you allocate in advance.  The @var{ptr} argument should be the
+address of a @code{char *} object, and a successful call to
+@code{asprintf} stores a pointer to the newly allocated string at that
+location.
+
+The return value is the number of characters allocated for the buffer, or
+less than zero if an error occurred.  Usually this means that the buffer
+could not be allocated.
+
+Here is how to use @code{asprintf} to get the same result as the
+@code{snprintf} example, but more easily:
+
+@smallexample
+/* @r{Construct a message describing the value of a variable}
+   @r{whose name is @var{name} and whose value is @var{value}.} */
+char *
+make_message (char *name, char *value)
+@{
+  char *result;
+  if (asprintf (&result, "value of %s is %s", name, value) < 0)
+    return NULL;
+  return result;
+@}
+@end smallexample
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+This function is similar to @code{asprintf}, except that it uses the
+obstack @var{obstack} to allocate the space.  @xref{Obstacks}.
+
+The characters are written onto the end of the current object.
+To get at them, you must finish the object with @code{obstack_finish}
+(@pxref{Growing Objects}).@refill
+@end deftypefun
+
+@node Variable Arguments Output
+@subsection Variable Arguments Output Functions
+
+The functions @code{vprintf} and friends are provided so that you can
+define your own variadic @code{printf}-like functions that make use of
+the same internals as the built-in formatted output functions.
+
+The most natural way to define such functions would be to use a language
+construct to say, ``Call @code{printf} and pass this template plus all
+of my arguments after the first five.''  But there is no way to do this
+in C, and it would be hard to provide a way, since at the C language
+level there is no way to tell how many arguments your function received.
+
+Since that method is impossible, we provide alternative functions, the
+@code{vprintf} series, which lets you pass a @code{va_list} to describe
+``all of my arguments after the first five.''
+
+When it is sufficient to define a macro rather than a real function,
+the GNU C compiler provides a way to do this much more easily with macros.
+For example:
+
+@smallexample
+#define myprintf(a, b, c, d, e, rest...) \
+	    printf (mytemplate , ## rest)
+@end smallexample
+
+@noindent
+@xref{Variadic Macros,,, cpp, The C preprocessor}, for details.
+But this is limited to macros, and does not apply to real functions at all.
+
+Before calling @code{vprintf} or the other functions listed in this
+section, you @emph{must} call @code{va_start} (@pxref{Variadic
+Functions}) to initialize a pointer to the variable arguments.  Then you
+can call @code{va_arg} to fetch the arguments that you want to handle
+yourself.  This advances the pointer past those arguments.
+
+Once your @code{va_list} pointer is pointing at the argument of your
+choice, you are ready to call @code{vprintf}.  That argument and all
+subsequent arguments that were passed to your function are used by
+@code{vprintf} along with the template that you specified separately.
+
+@strong{Portability Note:} The value of the @code{va_list} pointer is
+undetermined after the call to @code{vprintf}, so you must not use
+@code{va_arg} after you call @code{vprintf}.  Instead, you should call
+@code{va_end} to retire the pointer from service.  You can call
+@code{va_start} again and begin fetching the arguments from the start of
+the variable argument list.  (Alternatively, you can use @code{va_copy}
+to make a copy of the @code{va_list} pointer before calling
+@code{vfprintf}.)  Calling @code{vprintf} does not destroy the argument
+list of your function, merely the particular pointer that you passed to
+it.
+
+Prototypes for these functions are declared in @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is similar to @code{printf} except that, instead of taking
+a variable number of arguments directly, it takes an argument list
+pointer @var{ap}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int vwprintf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is similar to @code{wprintf} except that, instead of taking
+a variable number of arguments directly, it takes an argument list
+pointer @var{ap}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Although vfprintf sets up a cleanup region to release the lock on the
+@c output stream, it doesn't use it to release args_value or string in
+@c case of cancellation.  This doesn't make it unsafe, but cancelling it
+@c may leak memory.  The unguarded use of __printf_function_table is
+@c also of concern for all callers.
+@c _itoa ok
+@c   _udiv_qrnnd_preinv ok
+@c group_number ok
+@c _i18n_number_rewrite
+@c   __wctrans ok
+@c   __towctrans @mtslocale
+@c   __wcrtomb ok? dup below
+@c   outdigit_value ok
+@c   outdigitwc_value ok
+@c outchar ok
+@c outstring ok
+@c PAD ok
+@c __printf_fp @mtslocale @ascuheap @acsmem
+@c __printf_fphex @mtslocale
+@c __readonly_area
+@c   [GNU/Linux] fopen, strtoul, free
+@c __strerror_r ok if no translation, check otherwise
+@c __btowc ? gconv-modules
+@c __wcrtomb ok (not using internal state) gconv-modules
+@c ARGCHECK
+@c UNBUFFERED_P (tested before taking the stream lock)
+@c buffered_vfprintf ok
+@c __find_spec(wc|mb)
+@c read_int
+@c __libc_use_alloca
+@c process_arg
+@c process_string_arg
+@c extend_alloca
+@c __parse_one_spec(wc|mb)
+@c *__printf_arginfo_table unguarded
+@c __printf_va_arg_table-> unguarded
+@c *__printf_function_table unguarded
+@c done_add
+@c printf_unknown
+@c   outchar
+@c   _itoa_word
+This is the equivalent of @code{fprintf} with the variable argument list
+specified directly as for @code{vprintf}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int vfwprintf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This is the equivalent of @code{fwprintf} with the variable argument list
+specified directly as for @code{vwprintf}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is the equivalent of @code{sprintf} with the variable argument list
+specified directly as for @code{vprintf}.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun int vswprintf (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is the equivalent of @code{swprintf} with the variable argument list
+specified directly as for @code{vwprintf}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is the equivalent of @code{snprintf} with the variable argument list
+specified directly as for @code{vprintf}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{vasprintf} function is the equivalent of @code{asprintf} with the
+variable argument list specified directly as for @code{vprintf}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtsrace{:obstack} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c The obstack is not guarded by mutexes, it might be at an inconsistent
+@c state within a signal handler, and it could be left at an
+@c inconsistent state in case of cancellation.
+The @code{obstack_vprintf} function is the equivalent of
+@code{obstack_printf} with the variable argument list specified directly
+as for @code{vprintf}.@refill
+@end deftypefun
+
+Here's an example showing how you might use @code{vfprintf}.  This is a
+function that prints error messages to the stream @code{stderr}, along
+with a prefix indicating the name of the program
+(@pxref{Error Messages}, for a description of
+@code{program_invocation_short_name}).
+
+@smallexample
+@group
+#include <stdio.h>
+#include <stdarg.h>
+
+void
+eprintf (const char *template, ...)
+@{
+  va_list ap;
+  extern char *program_invocation_short_name;
+
+  fprintf (stderr, "%s: ", program_invocation_short_name);
+  va_start (ap, template);
+  vfprintf (stderr, template, ap);
+  va_end (ap);
+@}
+@end group
+@end smallexample
+
+@noindent
+You could call @code{eprintf} like this:
+
+@smallexample
+eprintf ("file `%s' does not exist\n", filename);
+@end smallexample
+
+In GNU C, there is a special construct you can use to let the compiler
+know that a function uses a @code{printf}-style format string.  Then it
+can check the number and types of arguments in each call to the
+function, and warn you when they do not match the format string.
+For example, take this declaration of @code{eprintf}:
+
+@smallexample
+void eprintf (const char *template, ...)
+	__attribute__ ((format (printf, 1, 2)));
+@end smallexample
+
+@noindent
+This tells the compiler that @code{eprintf} uses a format string like
+@code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
+the format string appears as the first argument;
+and the arguments to satisfy the format begin with the second.
+@xref{Function Attributes, , Declaring Attributes of Functions,
+gcc.info, Using GNU CC}, for more information.
+
+@node Parsing a Template String
+@subsection Parsing a Template String
+@cindex parsing a template string
+
+You can use the function @code{parse_printf_format} to obtain
+information about the number and types of arguments that are expected by
+a given template string.  This function permits interpreters that
+provide interfaces to @code{printf} to avoid passing along invalid
+arguments from the user's program, which could cause a crash.
+
+All the symbols described in this section are declared in the header
+file @file{printf.h}.
+
+@comment printf.h
+@comment GNU
+@deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function returns information about the number and types of
+arguments expected by the @code{printf} template string @var{template}.
+The information is stored in the array @var{argtypes}; each element of
+this array describes one argument.  This information is encoded using
+the various @samp{PA_} macros, listed below.
+
+The argument @var{n} specifies the number of elements in the array
+@var{argtypes}.  This is the maximum number of elements that
+@code{parse_printf_format} will try to write.
+
+@code{parse_printf_format} returns the total number of arguments required
+by @var{template}.  If this number is greater than @var{n}, then the
+information returned describes only the first @var{n} arguments.  If you
+want information about additional arguments, allocate a bigger
+array and call @code{parse_printf_format} again.
+@end deftypefun
+
+The argument types are encoded as a combination of a basic type and
+modifier flag bits.
+
+@comment printf.h
+@comment GNU
+@deftypevr Macro int PA_FLAG_MASK
+This macro is a bitmask for the type modifier flag bits.  You can write
+the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
+flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
+extract just the basic type code.
+@end deftypevr
+
+Here are symbolic constants that represent the basic types; they stand
+for integer values.
+
+@vtable @code
+@comment printf.h
+@comment GNU
+@item PA_INT
+This specifies that the base type is @code{int}.
+
+@comment printf.h
+@comment GNU
+@item PA_CHAR
+This specifies that the base type is @code{int}, cast to @code{char}.
+
+@comment printf.h
+@comment GNU
+@item PA_STRING
+This specifies that the base type is @code{char *}, a null-terminated string.
+
+@comment printf.h
+@comment GNU
+@item PA_POINTER
+This specifies that the base type is @code{void *}, an arbitrary pointer.
+
+@comment printf.h
+@comment GNU
+@item PA_FLOAT
+This specifies that the base type is @code{float}.
+
+@comment printf.h
+@comment GNU
+@item PA_DOUBLE
+This specifies that the base type is @code{double}.
+
+@comment printf.h
+@comment GNU
+@item PA_LAST
+You can define additional base types for your own programs as offsets
+from @code{PA_LAST}.  For example, if you have data types @samp{foo}
+and @samp{bar} with their own specialized @code{printf} conversions,
+you could define encodings for these types as:
+
+@smallexample
+#define PA_FOO  PA_LAST
+#define PA_BAR  (PA_LAST + 1)
+@end smallexample
+@end vtable
+
+Here are the flag bits that modify a basic type.  They are combined with
+the code for the basic type using inclusive-or.
+
+@vtable @code
+@comment printf.h
+@comment GNU
+@item PA_FLAG_PTR
+If this bit is set, it indicates that the encoded type is a pointer to
+the base type, rather than an immediate value.
+For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.
+
+@comment printf.h
+@comment GNU
+@item PA_FLAG_SHORT
+If this bit is set, it indicates that the base type is modified with
+@code{short}.  (This corresponds to the @samp{h} type modifier.)
+
+@comment printf.h
+@comment GNU
+@item PA_FLAG_LONG
+If this bit is set, it indicates that the base type is modified with
+@code{long}.  (This corresponds to the @samp{l} type modifier.)
+
+@comment printf.h
+@comment GNU
+@item PA_FLAG_LONG_LONG
+If this bit is set, it indicates that the base type is modified with
+@code{long long}.  (This corresponds to the @samp{L} type modifier.)
+
+@comment printf.h
+@comment GNU
+@item PA_FLAG_LONG_DOUBLE
+This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
+a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
+@end vtable
+
+@ifinfo
+For an example of using these facilities, see @ref{Example of Parsing}.
+@end ifinfo
+
+@node Example of Parsing
+@subsection Example of Parsing a Template String
+
+Here is an example of decoding argument types for a format string.  We
+assume this is part of an interpreter which contains arguments of type
+@code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
+perhaps others which are not valid here).
+
+@smallexample
+/* @r{Test whether the @var{nargs} specified objects}
+   @r{in the vector @var{args} are valid}
+   @r{for the format string @var{format}:}
+   @r{if so, return 1.}
+   @r{If not, return 0 after printing an error message.}  */
+
+int
+validate_args (char *format, int nargs, OBJECT *args)
+@{
+  int *argtypes;
+  int nwanted;
+
+  /* @r{Get the information about the arguments.}
+     @r{Each conversion specification must be at least two characters}
+     @r{long, so there cannot be more specifications than half the}
+     @r{length of the string.}  */
+
+  argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
+  nwanted = parse_printf_format (string, nelts, argtypes);
+
+  /* @r{Check the number of arguments.}  */
+  if (nwanted > nargs)
+    @{
+      error ("too few arguments (at least %d required)", nwanted);
+      return 0;
+    @}
+
+  /* @r{Check the C type wanted for each argument}
+     @r{and see if the object given is suitable.}  */
+  for (i = 0; i < nwanted; i++)
+    @{
+      int wanted;
+
+      if (argtypes[i] & PA_FLAG_PTR)
+	wanted = STRUCTURE;
+      else
+	switch (argtypes[i] & ~PA_FLAG_MASK)
+	  @{
+	  case PA_INT:
+	  case PA_FLOAT:
+	  case PA_DOUBLE:
+	    wanted = NUMBER;
+	    break;
+	  case PA_CHAR:
+	    wanted = CHAR;
+	    break;
+	  case PA_STRING:
+	    wanted = STRING;
+	    break;
+	  case PA_POINTER:
+	    wanted = STRUCTURE;
+	    break;
+	  @}
+      if (TYPE (args[i]) != wanted)
+	@{
+	  error ("type mismatch for arg number %d", i);
+	  return 0;
+	@}
+    @}
+  return 1;
+@}
+@end smallexample
+
+@node Customizing Printf
+@section Customizing @code{printf}
+@cindex customizing @code{printf}
+@cindex defining new @code{printf} conversions
+@cindex extending @code{printf}
+
+@Theglibc{} lets you define your own custom conversion specifiers
+for @code{printf} template strings, to teach @code{printf} clever ways
+to print the important data structures of your program.
+
+The way you do this is by registering the conversion with the function
+@code{register_printf_function}; see @ref{Registering New Conversions}.
+One of the arguments you pass to this function is a pointer to a handler
+function that produces the actual output; see @ref{Defining the Output
+Handler}, for information on how to write this function.
+
+You can also install a function that just returns information about the
+number and type of arguments expected by the conversion specifier.
+@xref{Parsing a Template String}, for information about this.
+
+The facilities of this section are declared in the header file
+@file{printf.h}.
+
+@menu
+* 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.
+@end menu
+
+@strong{Portability Note:} The ability to extend the syntax of
+@code{printf} template strings is a GNU extension.  ISO standard C has
+nothing similar.
+
+@node Registering New Conversions
+@subsection Registering New Conversions
+
+The function to register a new output conversion is
+@code{register_printf_function}, declared in @file{printf.h}.
+@pindex printf.h
+
+@comment printf.h
+@comment GNU
+@deftypefun int register_printf_function (int @var{spec}, printf_function @var{handler-function}, printf_arginfo_function @var{arginfo-function})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:printfext}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+@c This function is guarded by the global non-recursive libc lock, but
+@c users of the variables it sets aren't, and those should be MT-Safe,
+@c so we're ruling out the use of this extension with threads.  Calling
+@c it from a signal handler may self-deadlock, and cancellation may
+@c leave the lock held, besides leaking allocated memory.
+This function defines the conversion specifier character @var{spec}.
+Thus, if @var{spec} is @code{'Y'}, it defines the conversion @samp{%Y}.
+You can redefine the built-in conversions like @samp{%s}, but flag
+characters like @samp{#} and type modifiers like @samp{l} can never be
+used as conversions; calling @code{register_printf_function} for those
+characters has no effect.  It is advisable not to use lowercase letters,
+since the ISO C standard warns that additional lowercase letters may be
+standardized in future editions of the standard.
+
+The @var{handler-function} is the function called by @code{printf} and
+friends when this conversion appears in a template string.
+@xref{Defining the Output Handler}, for information about how to define
+a function to pass as this argument.  If you specify a null pointer, any
+existing handler function for @var{spec} is removed.
+
+The @var{arginfo-function} is the function called by
+@code{parse_printf_format} when this conversion appears in a
+template string.  @xref{Parsing a Template String}, for information
+about this.
+
+@c The following is not true anymore.  The `parse_printf_format' function
+@c is now also called from `vfprintf' via `parse_one_spec'.
+@c --drepper@gnu, 1996/11/14
+@c
+@c Normally, you install both functions for a conversion at the same time,
+@c but if you are never going to call @code{parse_printf_format}, you do
+@c not need to define an arginfo function.
+
+@strong{Attention:} In @theglibc{} versions before 2.0 the
+@var{arginfo-function} function did not need to be installed unless
+the user used the @code{parse_printf_format} function.  This has changed.
+Now a call to any of the @code{printf} functions will call this
+function when this format specifier appears in the format string.
+
+The return value is @code{0} on success, and @code{-1} on failure
+(which occurs if @var{spec} is out of range).
+
+You can redefine the standard output conversions, but this is probably
+not a good idea because of the potential for confusion.  Library routines
+written by other people could break if you do this.
+@end deftypefun
+
+@node Conversion Specifier Options
+@subsection Conversion Specifier Options
+
+If you define a meaning for @samp{%A}, what if the template contains
+@samp{%+23A} or @samp{%-#A}?  To implement a sensible meaning for these,
+the handler when called needs to be able to get the options specified in
+the template.
+
+Both the @var{handler-function} and @var{arginfo-function} accept an
+argument that points to a @code{struct printf_info}, which contains
+information about the options appearing in an instance of the conversion
+specifier.  This data type is declared in the header file
+@file{printf.h}.
+@pindex printf.h
+
+@comment printf.h
+@comment GNU
+@deftp {Type} {struct printf_info}
+This structure is used to pass information about the options appearing
+in an instance of a conversion specifier in a @code{printf} template
+string to the handler and arginfo functions for that specifier.  It
+contains the following members:
+
+@table @code
+@item int prec
+This is the precision specified.  The value is @code{-1} if no precision
+was specified.  If the precision was given as @samp{*}, the
+@code{printf_info} structure passed to the handler function contains the
+actual value retrieved from the argument list.  But the structure passed
+to the arginfo function contains a value of @code{INT_MIN}, since the
+actual value is not known.
+
+@item int width
+This is the minimum field width specified.  The value is @code{0} if no
+width was specified.  If the field width was given as @samp{*}, the
+@code{printf_info} structure passed to the handler function contains the
+actual value retrieved from the argument list.  But the structure passed
+to the arginfo function contains a value of @code{INT_MIN}, since the
+actual value is not known.
+
+@item wchar_t spec
+This is the conversion specifier character specified.  It's stored in
+the structure so that you can register the same handler function for
+multiple characters, but still have a way to tell them apart when the
+handler function is called.
+
+@item unsigned int is_long_double
+This is a boolean that is true if the @samp{L}, @samp{ll}, or @samp{q}
+type modifier was specified.  For integer conversions, this indicates
+@code{long long int}, as opposed to @code{long double} for floating
+point conversions.
+
+@item unsigned int is_char
+This is a boolean that is true if the @samp{hh} type modifier was specified.
+
+@item unsigned int is_short
+This is a boolean that is true if the @samp{h} type modifier was specified.
+
+@item unsigned int is_long
+This is a boolean that is true if the @samp{l} type modifier was specified.
+
+@item unsigned int alt
+This is a boolean that is true if the @samp{#} flag was specified.
+
+@item unsigned int space
+This is a boolean that is true if the @samp{ } flag was specified.
+
+@item unsigned int left
+This is a boolean that is true if the @samp{-} flag was specified.
+
+@item unsigned int showsign
+This is a boolean that is true if the @samp{+} flag was specified.
+
+@item unsigned int group
+This is a boolean that is true if the @samp{'} flag was specified.
+
+@item unsigned int extra
+This flag has a special meaning depending on the context.  It could
+be used freely by the user-defined handlers but when called from
+the @code{printf} function this variable always contains the value
+@code{0}.
+
+@item unsigned int wide
+This flag is set if the stream is wide oriented.
+
+@item wchar_t pad
+This is the character to use for padding the output to the minimum field
+width.  The value is @code{'0'} if the @samp{0} flag was specified, and
+@code{' '} otherwise.
+@end table
+@end deftp
+
+
+@node Defining the Output Handler
+@subsection Defining the Output Handler
+
+Now let's look at how to define the handler and arginfo functions
+which are passed as arguments to @code{register_printf_function}.
+
+@strong{Compatibility Note:} The interface changed in @theglibc{}
+version 2.0.  Previously the third argument was of type
+@code{va_list *}.
+
+You should define your handler functions with a prototype like:
+
+@smallexample
+int @var{function} (FILE *stream, const struct printf_info *info,
+		    const void *const *args)
+@end smallexample
+
+The @var{stream} argument passed to the handler function is the stream to
+which it should write output.
+
+The @var{info} argument is a pointer to a structure that contains
+information about the various options that were included with the
+conversion in the template string.  You should not modify this structure
+inside your handler function.  @xref{Conversion Specifier Options}, for
+a description of this data structure.
+
+@c The following changes some time back.  --drepper@gnu, 1996/11/14
+@c
+@c The @code{ap_pointer} argument is used to pass the tail of the variable
+@c argument list containing the values to be printed to your handler.
+@c Unlike most other functions that can be passed an explicit variable
+@c argument list, this is a @emph{pointer} to a @code{va_list}, rather than
+@c the @code{va_list} itself.  Thus, you should fetch arguments by
+@c means of @code{va_arg (*ap_pointer, @var{type})}.
+@c
+@c (Passing a pointer here allows the function that calls your handler
+@c function to update its own @code{va_list} variable to account for the
+@c arguments that your handler processes.  @xref{Variadic Functions}.)
+
+The @var{args} is a vector of pointers to the arguments data.
+The number of arguments was determined by calling the argument
+information function provided by the user.
+
+Your handler function should return a value just like @code{printf}
+does: it should return the number of characters it has written, or a
+negative value to indicate an error.
+
+@comment printf.h
+@comment GNU
+@deftp {Data Type} printf_function
+This is the data type that a handler function should have.
+@end deftp
+
+If you are going to use @w{@code{parse_printf_format}} in your
+application, you must also define a function to pass as the
+@var{arginfo-function} argument for each new conversion you install with
+@code{register_printf_function}.
+
+You have to define these functions with a prototype like:
+
+@smallexample
+int @var{function} (const struct printf_info *info,
+		    size_t n, int *argtypes)
+@end smallexample
+
+The return value from the function should be the number of arguments the
+conversion expects.  The function should also fill in no more than
+@var{n} elements of the @var{argtypes} array with information about the
+types of each of these arguments.  This information is encoded using the
+various @samp{PA_} macros.  (You will notice that this is the same
+calling convention @code{parse_printf_format} itself uses.)
+
+@comment printf.h
+@comment GNU
+@deftp {Data Type} printf_arginfo_function
+This type is used to describe functions that return information about
+the number and type of arguments used by a conversion specifier.
+@end deftp
+
+@node Printf Extension Example
+@subsection @code{printf} Extension Example
+
+Here is an example showing how to define a @code{printf} handler function.
+This program defines a data structure called a @code{Widget} and
+defines the @samp{%W} conversion to print information about @w{@code{Widget *}}
+arguments, including the pointer value and the name stored in the data
+structure.  The @samp{%W} conversion supports the minimum field width and
+left-justification options, but ignores everything else.
+
+@smallexample
+@include rprintf.c.texi
+@end smallexample
+
+The output produced by this program looks like:
+
+@smallexample
+|<Widget 0xffeffb7c: mywidget>|
+|      <Widget 0xffeffb7c: mywidget>|
+|<Widget 0xffeffb7c: mywidget>      |
+@end smallexample
+
+@node Predefined Printf Handlers
+@subsection Predefined @code{printf} Handlers
+
+@Theglibc{} also contains a concrete and useful application of the
+@code{printf} handler extension.  There are two functions available
+which implement a special way to print floating-point numbers.
+
+@comment printf.h
+@comment GNU
+@deftypefun int printf_size (FILE *@var{fp}, const struct printf_info *@var{info}, const void *const *@var{args})
+@safety{@prelim{}@mtsafe{@mtsrace{:fp} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @acucorrupt{}}}
+@c This is meant to be called by vfprintf, that should hold the lock on
+@c the stream, but if this function is called directly, output will be
+@c racy, besides the uses of the global locale object while other
+@c threads may be changing it and the possbility of leaving the stream
+@c object in an inconsistent state in case of cancellation.
+Print a given floating point number as for the format @code{%f} except
+that there is a postfix character indicating the divisor for the
+number to make this less than 1000.  There are two possible divisors:
+powers of 1024 or powers of 1000.  Which one is used depends on the
+format character specified while registered this handler.  If the
+character is of lower case, 1024 is used.  For upper case characters,
+1000 is used.
+
+The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
+etc.  The full table is:
+
+@ifinfo
+@multitable {' '} {2^10 (1024)} {zetta} {Upper} {10^24 (1000)}
+@item low @tab Multiplier  @tab From  @tab Upper @tab Multiplier
+@item ' ' @tab 1           @tab       @tab ' '   @tab 1
+@item k   @tab 2^10 (1024) @tab kilo  @tab K     @tab 10^3 (1000)
+@item m   @tab 2^20        @tab mega  @tab M     @tab 10^6
+@item g   @tab 2^30        @tab giga  @tab G     @tab 10^9
+@item t   @tab 2^40        @tab tera  @tab T     @tab 10^12
+@item p   @tab 2^50        @tab peta  @tab P     @tab 10^15
+@item e   @tab 2^60        @tab exa   @tab E     @tab 10^18
+@item z   @tab 2^70        @tab zetta @tab Z     @tab 10^21
+@item y   @tab 2^80        @tab yotta @tab Y     @tab 10^24
+@end multitable
+@end ifinfo
+@iftex
+@tex
+\hbox to\hsize{\hfil\vbox{\offinterlineskip
+\hrule
+\halign{\strut#& \vrule#\tabskip=1em plus2em& {\tt#}\hfil& \vrule#& #\hfil& \vrule#& #\hfil& \vrule#& {\tt#}\hfil& \vrule#& #\hfil& \vrule#\tabskip=0pt\cr
+\noalign{\hrule}
+\omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
+&& \omit low && Multiplier && From && \omit Upper && Multiplier &\cr
+\omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr
+\noalign{\hrule}
+&& {\tt\char32} &&  1 && && {\tt\char32} && 1 &\cr
+&& k && $2^{10} = 1024$ && kilo && K && $10^3 = 1000$ &\cr
+&& m && $2^{20}$ && mega && M && $10^6$ &\cr
+&& g && $2^{30}$ && giga && G && $10^9$ &\cr
+&& t && $2^{40}$ && tera && T && $10^{12}$ &\cr
+&& p && $2^{50}$ && peta && P && $10^{15}$ &\cr
+&& e && $2^{60}$ && exa && E && $10^{18}$ &\cr
+&& z && $2^{70}$ && zetta && Z && $10^{21}$ &\cr
+&& y && $2^{80}$ && yotta && Y && $10^{24}$ &\cr
+\noalign{\hrule}}}\hfil}
+@end tex
+@end iftex
+
+The default precision is 3, i.e., 1024 is printed with a lower-case
+format character as if it were @code{%.3fk} and will yield @code{1.000k}.
+@end deftypefun
+
+Due to the requirements of @code{register_printf_function} we must also
+provide the function which returns information about the arguments.
+
+@comment printf.h
+@comment GNU
+@deftypefun int printf_size_info (const struct printf_info *@var{info}, size_t @var{n}, int *@var{argtypes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function will return in @var{argtypes} the information about the
+used parameters in the way the @code{vfprintf} implementation expects
+it.  The format always takes one argument.
+@end deftypefun
+
+To use these functions both functions must be registered with a call like
+
+@smallexample
+register_printf_function ('B', printf_size, printf_size_info);
+@end smallexample
+
+Here we register the functions to print numbers as powers of 1000 since
+the format character @code{'B'} is an upper-case character.  If we
+would additionally use @code{'b'} in a line like
+
+@smallexample
+register_printf_function ('b', printf_size, printf_size_info);
+@end smallexample
+
+@noindent
+we could also print using a power of 1024.  Please note that all that is
+different in these two lines is the format specifier.  The
+@code{printf_size} function knows about the difference between lower and upper
+case format specifiers.
+
+The use of @code{'B'} and @code{'b'} is no coincidence.  Rather it is
+the preferred way to use this functionality since it is available on
+some other systems which also use format specifiers.
+
+@node Formatted Input
+@section Formatted Input
+
+@cindex formatted input from a stream
+@cindex reading from a stream, formatted
+@cindex format string, for @code{scanf}
+@cindex template, for @code{scanf}
+The functions described in this section (@code{scanf} and related
+functions) provide facilities for formatted input analogous to the
+formatted output facilities.  These functions provide a mechanism for
+reading arbitrary values under the control of a @dfn{format string} or
+@dfn{template string}.
+
+@menu
+* 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.
+@end menu
+
+@node Formatted Input Basics
+@subsection Formatted Input Basics
+
+Calls to @code{scanf} are superficially similar to calls to
+@code{printf} in that arbitrary arguments are read under the control of
+a template string.  While the syntax of the conversion specifications in
+the template is very similar to that for @code{printf}, the
+interpretation of the template is oriented more towards free-format
+input and simple pattern matching, rather than fixed-field formatting.
+For example, most @code{scanf} conversions skip over any amount of
+``white space'' (including spaces, tabs, and newlines) in the input
+file, and there is no concept of precision for the numeric input
+conversions as there is for the corresponding output conversions.
+Ordinarily, non-whitespace characters in the template are expected to
+match characters in the input stream exactly, but a matching failure is
+distinct from an input error on the stream.
+@cindex conversion specifications (@code{scanf})
+
+Another area of difference between @code{scanf} and @code{printf} is
+that you must remember to supply pointers rather than immediate values
+as the optional arguments to @code{scanf}; the values that are read are
+stored in the objects that the pointers point to.  Even experienced
+programmers tend to forget this occasionally, so if your program is
+getting strange errors that seem to be related to @code{scanf}, you
+might want to double-check this.
+
+When a @dfn{matching failure} occurs, @code{scanf} returns immediately,
+leaving the first non-matching character as the next character to be
+read from the stream.  The normal return value from @code{scanf} is the
+number of values that were assigned, so you can use this to determine if
+a matching error happened before all the expected values were read.
+@cindex matching failure, in @code{scanf}
+
+The @code{scanf} function is typically used for things like reading in
+the contents of tables.  For example, here is a function that uses
+@code{scanf} to initialize an array of @code{double}:
+
+@smallexample
+void
+readarray (double *array, int n)
+@{
+  int i;
+  for (i=0; i<n; i++)
+    if (scanf (" %lf", &(array[i])) != 1)
+      invalid_input_error ();
+@}
+@end smallexample
+
+The formatted input functions are not used as frequently as the
+formatted output functions.  Partly, this is because it takes some care
+to use them properly.  Another reason is that it is difficult to recover
+from a matching error.
+
+If you are trying to read input that doesn't match a single, fixed
+pattern, you may be better off using a tool such as Flex to generate a
+lexical scanner, or Bison to generate a parser, rather than using
+@code{scanf}.  For more information about these tools, see @ref{Top, , ,
+flex.info, Flex: The Lexical Scanner Generator}, and @ref{Top, , ,
+bison.info, The Bison Reference Manual}.
+
+@node Input Conversion Syntax
+@subsection Input Conversion Syntax
+
+A @code{scanf} template string is a string that contains ordinary
+multibyte characters interspersed with conversion specifications that
+start with @samp{%}.
+
+Any whitespace character (as defined by the @code{isspace} function;
+@pxref{Classification of Characters}) in the template causes any number
+of whitespace characters in the input stream to be read and discarded.
+The whitespace characters that are matched need not be exactly the same
+whitespace characters that appear in the template string.  For example,
+write @samp{ , } in the template to recognize a comma with optional
+whitespace before and after.
+
+Other characters in the template string that are not part of conversion
+specifications must match characters in the input stream exactly; if
+this is not the case, a matching failure occurs.
+
+The conversion specifications in a @code{scanf} template string
+have the general form:
+
+@smallexample
+% @var{flags} @var{width} @var{type} @var{conversion}
+@end smallexample
+
+In more detail, an input conversion specification consists of an initial
+@samp{%} character followed in sequence by:
+
+@itemize @bullet
+@item
+An optional @dfn{flag character} @samp{*}, which says to ignore the text
+read for this specification.  When @code{scanf} finds a conversion
+specification that uses this flag, it reads input as directed by the
+rest of the conversion specification, but it discards this input, does
+not use a pointer argument, and does not increment the count of
+successful assignments.
+@cindex flag character (@code{scanf})
+
+@item
+An optional flag character @samp{a} (valid with string conversions only)
+which requests allocation of a buffer long enough to store the string in.
+(This is a GNU extension.)
+@xref{Dynamic String Input}.
+
+@item
+An optional decimal integer that specifies the @dfn{maximum field
+width}.  Reading of characters from the input stream stops either when
+this maximum is reached or when a non-matching character is found,
+whichever happens first.  Most conversions discard initial whitespace
+characters (those that don't are explicitly documented), and these
+discarded characters don't count towards the maximum field width.
+String input conversions store a null character to mark the end of the
+input; the maximum field width does not include this terminator.
+@cindex maximum field width (@code{scanf})
+
+@item
+An optional @dfn{type modifier character}.  For example, you can
+specify a type modifier of @samp{l} with integer conversions such as
+@samp{%d} to specify that the argument is a pointer to a @code{long int}
+rather than a pointer to an @code{int}.
+@cindex type modifier character (@code{scanf})
+
+@item
+A character that specifies the conversion to be applied.
+@end itemize
+
+The exact options that are permitted and how they are interpreted vary
+between the different conversion specifiers.  See the descriptions of the
+individual conversions for information about the particular options that
+they allow.
+
+With the @samp{-Wformat} option, the GNU C compiler checks calls to
+@code{scanf} and related functions.  It examines the format string and
+verifies that the correct number and types of arguments are supplied.
+There is also a GNU C syntax to tell the compiler that a function you
+write uses a @code{scanf}-style format string.
+@xref{Function Attributes, , Declaring Attributes of Functions,
+gcc.info, Using GNU CC}, for more information.
+
+@node Table of Input Conversions
+@subsection Table of Input Conversions
+@cindex input conversions, for @code{scanf}
+
+Here is a table that summarizes the various conversion specifications:
+
+@table @asis
+@item @samp{%d}
+Matches an optionally signed integer written in decimal.  @xref{Numeric
+Input Conversions}.
+
+@item @samp{%i}
+Matches an optionally signed integer in any of the formats that the C
+language defines for specifying an integer constant.  @xref{Numeric
+Input Conversions}.
+
+@item @samp{%o}
+Matches an unsigned integer written in octal radix.
+@xref{Numeric Input Conversions}.
+
+@item @samp{%u}
+Matches an unsigned integer written in decimal radix.
+@xref{Numeric Input Conversions}.
+
+@item @samp{%x}, @samp{%X}
+Matches an unsigned integer written in hexadecimal radix.
+@xref{Numeric Input Conversions}.
+
+@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
+Matches an optionally signed floating-point number.  @xref{Numeric Input
+Conversions}.
+
+@item @samp{%s}
+
+Matches a string containing only non-whitespace characters.
+@xref{String Input Conversions}.  The presence of the @samp{l} modifier
+determines whether the output is stored as a wide character string or a
+multibyte string.  If @samp{%s} is used in a wide character function the
+string is converted as with multiple calls to @code{wcrtomb} into a
+multibyte string.  This means that the buffer must provide room for
+@code{MB_CUR_MAX} bytes for each wide character read.  In case
+@samp{%ls} is used in a multibyte function the result is converted into
+wide characters as with multiple calls of @code{mbrtowc} before being
+stored in the user provided buffer.
+
+@item @samp{%S}
+This is an alias for @samp{%ls} which is supported for compatibility
+with the Unix standard.
+
+@item @samp{%[}
+Matches a string of characters that belong to a specified set.
+@xref{String Input Conversions}.  The presence of the @samp{l} modifier
+determines whether the output is stored as a wide character string or a
+multibyte string.  If @samp{%[} is used in a wide character function the
+string is converted as with multiple calls to @code{wcrtomb} into a
+multibyte string.  This means that the buffer must provide room for
+@code{MB_CUR_MAX} bytes for each wide character read.  In case
+@samp{%l[} is used in a multibyte function the result is converted into
+wide characters as with multiple calls of @code{mbrtowc} before being
+stored in the user provided buffer.
+
+@item @samp{%c}
+Matches a string of one or more characters; the number of characters
+read is controlled by the maximum field width given for the conversion.
+@xref{String Input Conversions}.
+
+If the @samp{%c} is used in a wide stream function the read value is
+converted from a wide character to the corresponding multibyte character
+before storing it.  Note that this conversion can produce more than one
+byte of output and therefore the provided buffer be large enough for up
+to @code{MB_CUR_MAX} bytes for each character.  If @samp{%lc} is used in
+a multibyte function the input is treated as a multibyte sequence (and
+not bytes) and the result is converted as with calls to @code{mbrtowc}.
+
+@item @samp{%C}
+This is an alias for @samp{%lc} which is supported for compatibility
+with the Unix standard.
+
+@item @samp{%p}
+Matches a pointer value in the same implementation-defined format used
+by the @samp{%p} output conversion for @code{printf}.  @xref{Other Input
+Conversions}.
+
+@item @samp{%n}
+This conversion doesn't read any characters; it records the number of
+characters read so far by this call.  @xref{Other Input Conversions}.
+
+@item @samp{%%}
+This matches a literal @samp{%} character in the input stream.  No
+corresponding argument is used.  @xref{Other Input Conversions}.
+@end table
+
+If the syntax of a conversion specification is invalid, the behavior is
+undefined.  If there aren't enough function arguments provided to supply
+addresses for all the conversion specifications in the template strings
+that perform assignments, or if the arguments are not of the correct
+types, the behavior is also undefined.  On the other hand, extra
+arguments are simply ignored.
+
+@node Numeric Input Conversions
+@subsection Numeric Input Conversions
+
+This section describes the @code{scanf} conversions for reading numeric
+values.
+
+The @samp{%d} conversion matches an optionally signed integer in decimal
+radix.  The syntax that is recognized is the same as that for the
+@code{strtol} function (@pxref{Parsing of Integers}) with the value
+@code{10} for the @var{base} argument.
+
+The @samp{%i} conversion matches an optionally signed integer in any of
+the formats that the C language defines for specifying an integer
+constant.  The syntax that is recognized is the same as that for the
+@code{strtol} function (@pxref{Parsing of Integers}) with the value
+@code{0} for the @var{base} argument.  (You can print integers in this
+syntax with @code{printf} by using the @samp{#} flag character with the
+@samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
+
+For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
+could be read in as integers under the @samp{%i} conversion.  Each of
+these specifies a number with decimal value @code{10}.
+
+The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned
+integers in octal, decimal, and hexadecimal radices, respectively.  The
+syntax that is recognized is the same as that for the @code{strtoul}
+function (@pxref{Parsing of Integers}) with the appropriate value
+(@code{8}, @code{10}, or @code{16}) for the @var{base} argument.
+
+The @samp{%X} conversion is identical to the @samp{%x} conversion.  They
+both permit either uppercase or lowercase letters to be used as digits.
+
+The default type of the corresponding argument for the @code{%d} and
+@code{%i} conversions is @code{int *}, and @code{unsigned int *} for the
+other integer conversions.  You can use the following type modifiers to
+specify other sizes of integer:
+
+@table @samp
+@item hh
+Specifies that the argument is a @code{signed char *} or @code{unsigned
+char *}.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item h
+Specifies that the argument is a @code{short int *} or @code{unsigned
+short int *}.
+
+@item j
+Specifies that the argument is a @code{intmax_t *} or @code{uintmax_t *}.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item l
+Specifies that the argument is a @code{long int *} or @code{unsigned
+long int *}.  Two @samp{l} characters is like the @samp{L} modifier, below.
+
+If used with @samp{%c} or @samp{%s} the corresponding parameter is
+considered as a pointer to a wide character or wide character string
+respectively.  This use of @samp{l} was introduced in @w{Amendment 1} to
+@w{ISO C90}.
+
+@need 100
+@item ll
+@itemx L
+@itemx q
+Specifies that the argument is a @code{long long int *} or @code{unsigned long long int *}.  (The @code{long long} type is an extension supported by the
+GNU C compiler.  For systems that don't provide extra-long integers, this
+is the same as @code{long int}.)
+
+The @samp{q} modifier is another name for the same thing, which comes
+from 4.4 BSD; a @w{@code{long long int}} is sometimes called a ``quad''
+@code{int}.
+
+@item t
+Specifies that the argument is a @code{ptrdiff_t *}.
+
+This modifier was introduced in @w{ISO C99}.
+
+@item z
+Specifies that the argument is a @code{size_t *}.
+
+This modifier was introduced in @w{ISO C99}.
+@end table
+
+All of the @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, and @samp{%G}
+input conversions are interchangeable.  They all match an optionally
+signed floating point number, in the same syntax as for the
+@code{strtod} function (@pxref{Parsing of Floats}).
+
+For the floating-point input conversions, the default argument type is
+@code{float *}.  (This is different from the corresponding output
+conversions, where the default type is @code{double}; remember that
+@code{float} arguments to @code{printf} are converted to @code{double}
+by the default argument promotions, but @code{float *} arguments are
+not promoted to @code{double *}.)  You can specify other sizes of float
+using these type modifiers:
+
+@table @samp
+@item l
+Specifies that the argument is of type @code{double *}.
+
+@item L
+Specifies that the argument is of type @code{long double *}.
+@end table
+
+For all the above number parsing formats there is an additional optional
+flag @samp{'}.  When this flag is given the @code{scanf} function
+expects the number represented in the input string to be formatted
+according to the grouping rules of the currently selected locale
+(@pxref{General Numeric}).
+
+If the @code{"C"} or @code{"POSIX"} locale is selected there is no
+difference.  But for a locale which specifies values for the appropriate
+fields in the locale the input must have the correct form in the input.
+Otherwise the longest prefix with a correct form is processed.
+
+@node String Input Conversions
+@subsection String Input Conversions
+
+This section describes the @code{scanf} input conversions for reading
+string and character values: @samp{%s}, @samp{%S}, @samp{%[}, @samp{%c},
+and @samp{%C}.
+
+You have two options for how to receive the input from these
+conversions:
+
+@itemize @bullet
+@item
+Provide a buffer to store it in.  This is the default.  You should
+provide an argument of type @code{char *} or @code{wchar_t *} (the
+latter of the @samp{l} modifier is present).
+
+@strong{Warning:} To make a robust program, you must make sure that the
+input (plus its terminating null) cannot possibly exceed the size of the
+buffer you provide.  In general, the only way to do this is to specify a
+maximum field width one less than the buffer size.  @strong{If you
+provide the buffer, always specify a maximum field width to prevent
+overflow.}
+
+@item
+Ask @code{scanf} to allocate a big enough buffer, by specifying the
+@samp{a} flag character.  This is a GNU extension.  You should provide
+an argument of type @code{char **} for the buffer address to be stored
+in.  @xref{Dynamic String Input}.
+@end itemize
+
+The @samp{%c} conversion is the simplest: it matches a fixed number of
+characters, always.  The maximum field width says how many characters to
+read; if you don't specify the maximum, the default is 1.  This
+conversion doesn't append a null character to the end of the text it
+reads.  It also does not skip over initial whitespace characters.  It
+reads precisely the next @var{n} characters, and fails if it cannot get
+that many.  Since there is always a maximum field width with @samp{%c}
+(whether specified, or 1 by default), you can always prevent overflow by
+making the buffer long enough.
+@comment Is character == byte here???  --drepper
+
+If the format is @samp{%lc} or @samp{%C} the function stores wide
+characters which are converted using the conversion determined at the
+time the stream was opened from the external byte stream.  The number of
+bytes read from the medium is limited by @code{MB_CUR_LEN * @var{n}} but
+at most @var{n} wide character get stored in the output string.
+
+The @samp{%s} conversion matches a string of non-whitespace characters.
+It skips and discards initial whitespace, but stops when it encounters
+more whitespace after having read something.  It stores a null character
+at the end of the text that it reads.
+
+For example, reading the input:
+
+@smallexample
+ hello, world
+@end smallexample
+
+@noindent
+with the conversion @samp{%10c} produces @code{" hello, wo"}, but
+reading the same input with the conversion @samp{%10s} produces
+@code{"hello,"}.
+
+@strong{Warning:} If you do not specify a field width for @samp{%s},
+then the number of characters read is limited only by where the next
+whitespace character appears.  This almost certainly means that invalid
+input can make your program crash---which is a bug.
+
+The @samp{%ls} and @samp{%S} format are handled just like @samp{%s}
+except that the external byte sequence is converted using the conversion
+associated with the stream to wide characters with their own encoding.
+A width or precision specified with the format do not directly determine
+how many bytes are read from the stream since they measure wide
+characters.  But an upper limit can be computed by multiplying the value
+of the width or precision by @code{MB_CUR_MAX}.
+
+To read in characters that belong to an arbitrary set of your choice,
+use the @samp{%[} conversion.  You specify the set between the @samp{[}
+character and a following @samp{]} character, using the same syntax used
+in regular expressions for explicit sets of characters.  As special cases:
+
+@itemize @bullet
+@item
+A literal @samp{]} character can be specified as the first character
+of the set.
+
+@item
+An embedded @samp{-} character (that is, one that is not the first or
+last character of the set) is used to specify a range of characters.
+
+@item
+If a caret character @samp{^} immediately follows the initial @samp{[},
+then the set of allowed input characters is the everything @emph{except}
+the characters listed.
+@end itemize
+
+The @samp{%[} conversion does not skip over initial whitespace
+characters.
+
+Note that the @dfn{character class} syntax available in character sets
+that appear inside regular expressions (such as @samp{[:alpha:]}) is
+@emph{not} available in the @samp{%[} conversion.
+
+Here are some examples of @samp{%[} conversions and what they mean:
+
+@table @samp
+@item %25[1234567890]
+Matches a string of up to 25 digits.
+
+@item %25[][]
+Matches a string of up to 25 square brackets.
+
+@item %25[^ \f\n\r\t\v]
+Matches a string up to 25 characters long that doesn't contain any of
+the standard whitespace characters.  This is slightly different from
+@samp{%s}, because if the input begins with a whitespace character,
+@samp{%[} reports a matching failure while @samp{%s} simply discards the
+initial whitespace.
+
+@item %25[a-z]
+Matches up to 25 lowercase characters.
+@end table
+
+As for @samp{%c} and @samp{%s} the @samp{%[} format is also modified to
+produce wide characters if the @samp{l} modifier is present.  All what
+is said about @samp{%ls} above is true for @samp{%l[}.
+
+One more reminder: the @samp{%s} and @samp{%[} conversions are
+@strong{dangerous} if you don't specify a maximum width or use the
+@samp{a} flag, because input too long would overflow whatever buffer you
+have provided for it.  No matter how long your buffer is, a user could
+supply input that is longer.  A well-written program reports invalid
+input with a comprehensible error message, not with a crash.
+
+@node Dynamic String Input
+@subsection Dynamically Allocating String Conversions
+
+A GNU extension to formatted input lets you safely read a string with no
+maximum size.  Using this feature, you don't supply a buffer; instead,
+@code{scanf} allocates a buffer big enough to hold the data and gives
+you its address.  To use this feature, write @samp{a} as a flag
+character, as in @samp{%as} or @samp{%a[0-9a-z]}.
+
+The pointer argument you supply for where to store the input should have
+type @code{char **}.  The @code{scanf} function allocates a buffer and
+stores its address in the word that the argument points to.  You should
+free the buffer with @code{free} when you no longer need it.
+
+Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
+conversion specification to read a ``variable assignment'' of the form
+@samp{@var{variable} = @var{value}}.
+
+@smallexample
+@{
+  char *variable, *value;
+
+  if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
+		 &variable, &value))
+    @{
+      invalid_input_error ();
+      return 0;
+    @}
+
+  @dots{}
+@}
+@end smallexample
+
+@node Other Input Conversions
+@subsection Other Input Conversions
+
+This section describes the miscellaneous input conversions.
+
+The @samp{%p} conversion is used to read a pointer value.  It recognizes
+the same syntax used by the @samp{%p} output conversion for
+@code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal
+number just as the @samp{%x} conversion accepts.  The corresponding
+argument should be of type @code{void **}; that is, the address of a
+place to store a pointer.
+
+The resulting pointer value is not guaranteed to be valid if it was not
+originally written during the same program execution that reads it in.
+
+The @samp{%n} conversion produces the number of characters read so far
+by this call.  The corresponding argument should be of type @code{int *}.
+This conversion works in the same way as the @samp{%n} conversion for
+@code{printf}; see @ref{Other Output Conversions}, for an example.
+
+The @samp{%n} conversion is the only mechanism for determining the
+success of literal matches or conversions with suppressed assignments.
+If the @samp{%n} follows the locus of a matching failure, then no value
+is stored for it since @code{scanf} returns before processing the
+@samp{%n}.  If you store @code{-1} in that argument slot before calling
+@code{scanf}, the presence of @code{-1} after @code{scanf} indicates an
+error occurred before the @samp{%n} was reached.
+
+Finally, the @samp{%%} conversion matches a literal @samp{%} character
+in the input stream, without using an argument.  This conversion does
+not permit any flags, field width, or type modifier to be specified.
+
+@node Formatted Input Functions
+@subsection Formatted Input Functions
+
+Here are the descriptions of the functions for performing formatted
+input.
+Prototypes for these functions are in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int scanf (const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+The @code{scanf} function reads formatted input from the stream
+@code{stdin} under the control of the template string @var{template}.
+The optional arguments are pointers to the places which receive the
+resulting values.
+
+The return value is normally the number of successful assignments.  If
+an end-of-file condition is detected before any matches are performed,
+including matches against whitespace and literal characters in the
+template, then @code{EOF} is returned.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wscanf (const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+The @code{wscanf} function reads formatted input from the stream
+@code{stdin} under the control of the template string @var{template}.
+The optional arguments are pointers to the places which receive the
+resulting values.
+
+The return value is normally the number of successful assignments.  If
+an end-of-file condition is detected before any matches are performed,
+including matches against whitespace and literal characters in the
+template, then @code{WEOF} is returned.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fscanf (FILE *@var{stream}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is just like @code{scanf}, except that the input is read
+from the stream @var{stream} instead of @code{stdin}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int fwscanf (FILE *@var{stream}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is just like @code{wscanf}, except that the input is read
+from the stream @var{stream} instead of @code{stdin}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int sscanf (const char *@var{s}, const char *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is like @code{scanf}, except that the characters are taken from the
+null-terminated string @var{s} instead of from a stream.  Reaching the
+end of the string is treated as an end-of-file condition.
+
+The behavior of this function is undefined if copying takes place
+between objects that overlap---for example, if @var{s} is also given
+as an argument to receive a string read under control of the @samp{%s},
+@samp{%S}, or @samp{%[} conversion.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int swscanf (const wchar_t *@var{ws}, const wchar_t *@var{template}, @dots{})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is like @code{wscanf}, except that the characters are taken from the
+null-terminated string @var{ws} instead of from a stream.  Reaching the
+end of the string is treated as an end-of-file condition.
+
+The behavior of this function is undefined if copying takes place
+between objects that overlap---for example, if @var{ws} is also given as
+an argument to receive a string read under control of the @samp{%s},
+@samp{%S}, or @samp{%[} conversion.
+@end deftypefun
+
+@node Variable Arguments Input
+@subsection Variable Arguments Input Functions
+
+The functions @code{vscanf} and friends are provided so that you can
+define your own variadic @code{scanf}-like functions that make use of
+the same internals as the built-in formatted output functions.
+These functions are analogous to the @code{vprintf} series of output
+functions.  @xref{Variable Arguments Output}, for important
+information on how to use them.
+
+@strong{Portability Note:} The functions listed in this section were
+introduced in @w{ISO C99} and were before available as GNU extensions.
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vscanf (const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is similar to @code{scanf}, but instead of taking
+a variable number of arguments directly, it takes an argument list
+pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int vwscanf (const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This function is similar to @code{wscanf}, but instead of taking
+a variable number of arguments directly, it takes an argument list
+pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}).
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vfscanf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This is the equivalent of @code{fscanf} with the variable argument list
+specified directly as for @code{vscanf}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int vfwscanf (FILE *@var{stream}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+This is the equivalent of @code{fwscanf} with the variable argument list
+specified directly as for @code{vwscanf}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int vsscanf (const char *@var{s}, const char *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is the equivalent of @code{sscanf} with the variable argument list
+specified directly as for @code{vscanf}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int vswscanf (const wchar_t *@var{s}, const wchar_t *@var{template}, va_list @var{ap})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This is the equivalent of @code{swscanf} with the variable argument list
+specified directly as for @code{vwscanf}.
+@end deftypefun
+
+In GNU C, there is a special construct you can use to let the compiler
+know that a function uses a @code{scanf}-style format string.  Then it
+can check the number and types of arguments in each call to the
+function, and warn you when they do not match the format string.
+For details, see @ref{Function Attributes, , Declaring Attributes of Functions,
+gcc.info, Using GNU CC}.
+
+@node EOF and Errors
+@section End-Of-File and Errors
+
+@cindex end of file, on a stream
+Many of the functions described in this chapter return the value of the
+macro @code{EOF} to indicate unsuccessful completion of the operation.
+Since @code{EOF} is used to report both end of file and random errors,
+it's often better to use the @code{feof} function to check explicitly
+for end of file and @code{ferror} to check for errors.  These functions
+check indicators that are part of the internal state of the stream
+object, indicators set if the appropriate condition was detected by a
+previous I/O operation on that stream.
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int EOF
+This macro is an integer value that is returned by a number of narrow
+stream functions to indicate an end-of-file condition, or some other
+error situation.  With @theglibc{}, @code{EOF} is @code{-1}.  In
+other libraries, its value may be some other negative number.
+
+This symbol is declared in @file{stdio.h}.
+@end deftypevr
+
+@comment wchar.h
+@comment ISO
+@deftypevr Macro int WEOF
+This macro is an integer value that is returned by a number of wide
+stream functions to indicate an end-of-file condition, or some other
+error situation.  With @theglibc{}, @code{WEOF} is @code{-1}.  In
+other libraries, its value may be some other negative number.
+
+This symbol is declared in @file{wchar.h}.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypefun int feof (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+The @code{feof} function returns nonzero if and only if the end-of-file
+indicator for the stream @var{stream} is set.
+
+This symbol is declared in @file{stdio.h}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int feof_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c There isn't much of a thread unsafety risk in reading a flag word and
+@c testing a bit in it.
+The @code{feof_unlocked} function is equivalent to the @code{feof}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+
+This symbol is declared in @file{stdio.h}.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int ferror (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+The @code{ferror} function returns nonzero if and only if the error
+indicator for the stream @var{stream} is set, indicating that an error
+has occurred on a previous operation on the stream.
+
+This symbol is declared in @file{stdio.h}.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun int ferror_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{ferror_unlocked} function is equivalent to the @code{ferror}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+
+This symbol is declared in @file{stdio.h}.
+@end deftypefun
+
+In addition to setting the error indicator associated with the stream,
+the functions that operate on streams also set @code{errno} in the same
+way as the corresponding low-level functions that operate on file
+descriptors.  For example, all of the functions that perform output to a
+stream---such as @code{fputc}, @code{printf}, and @code{fflush}---are
+implemented in terms of @code{write}, and all of the @code{errno} error
+conditions defined for @code{write} are meaningful for these functions.
+For more information about the descriptor-level I/O functions, see
+@ref{Low-Level I/O}.
+
+@node Error Recovery
+@section Recovering from errors
+
+You may explicitly clear the error and EOF flags with the @code{clearerr}
+function.
+
+@comment stdio.h
+@comment ISO
+@deftypefun void clearerr (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@aculock{}}}
+This function clears the end-of-file and error indicators for the
+stream @var{stream}.
+
+The file positioning functions (@pxref{File Positioning}) also clear the
+end-of-file indicator for the stream.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun void clearerr_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@assafe{}@acsafe{}}
+The @code{clearerr_unlocked} function is equivalent to the @code{clearerr}
+function except that it does not implicitly lock the stream.
+
+This function is a GNU extension.
+@end deftypefun
+
+Note that it is @emph{not} correct to just clear the error flag and retry
+a failed stream operation.  After a failed write, any number of
+characters since the last buffer flush may have been committed to the
+file, while some buffered data may have been discarded.  Merely retrying
+can thus cause lost or repeated data.
+
+A failed read may leave the file pointer in an inappropriate position for
+a second try.  In both cases, you should seek to a known position before
+retrying.
+
+Most errors that can happen are not recoverable --- a second try will
+always fail again in the same way.  So usually it is best to give up and
+report the error to the user, rather than install complicated recovery
+logic.
+
+One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
+Many stream I/O implementations will treat it as an ordinary error, which
+can be quite inconvenient.  You can avoid this hassle by installing all
+signals with the @code{SA_RESTART} flag.
+
+For similar reasons, setting nonblocking I/O on a stream's file
+descriptor is not usually advisable.
+
+@node Binary Streams
+@section Text and Binary Streams
+
+@gnusystems{} and other POSIX-compatible operating systems organize all
+files as uniform sequences of characters.  However, some other systems
+make a distinction between files containing text and files containing
+binary data, and the input and output facilities of @w{ISO C} provide for
+this distinction.  This section tells you how to write programs portable
+to such systems.
+
+@cindex text stream
+@cindex binary stream
+When you open a stream, you can specify either a @dfn{text stream} or a
+@dfn{binary stream}.  You indicate that you want a binary stream by
+specifying the @samp{b} modifier in the @var{opentype} argument to
+@code{fopen}; see @ref{Opening Streams}.  Without this
+option, @code{fopen} opens the file as a text stream.
+
+Text and binary streams differ in several ways:
+
+@itemize @bullet
+@item
+The data read from a text stream is divided into @dfn{lines} which are
+terminated by newline (@code{'\n'}) characters, while a binary stream is
+simply a long series of characters.  A text stream might on some systems
+fail to handle lines more than 254 characters long (including the
+terminating newline character).
+@cindex lines (in a text file)
+
+@item
+On some systems, text files can contain only printing characters,
+horizontal tab characters, and newlines, and so text streams may not
+support other characters.  However, binary streams can handle any
+character value.
+
+@item
+Space characters that are written immediately preceding a newline
+character in a text stream may disappear when the file is read in again.
+
+@item
+More generally, there need not be a one-to-one mapping between
+characters that are read from or written to a text stream, and the
+characters in the actual file.
+@end itemize
+
+Since a binary stream is always more capable and more predictable than a
+text stream, you might wonder what purpose text streams serve.  Why not
+simply always use binary streams?  The answer is that on these operating
+systems, text and binary streams use different file formats, and the
+only way to read or write ``an ordinary file of text'' that can work
+with other text-oriented programs is through a text stream.
+
+In @theglibc{}, and on all POSIX systems, there is no difference
+between text streams and binary streams.  When you open a stream, you
+get the same kind of stream regardless of whether you ask for binary.
+This stream can handle any file content, and has none of the
+restrictions that text streams sometimes have.
+
+@node File Positioning
+@section File Positioning
+@cindex file positioning on a stream
+@cindex positioning a stream
+@cindex seeking on a stream
+
+The @dfn{file position} of a stream describes where in the file the
+stream is currently reading or writing.  I/O on the stream advances the
+file position through the file.  On @gnusystems{}, the file position is
+represented as an integer, which counts the number of bytes from the
+beginning of the file.  @xref{File Position}.
+
+During I/O to an ordinary disk file, you can change the file position
+whenever you wish, so as to read or write any portion of the file.  Some
+other kinds of files may also permit this.  Files which support changing
+the file position are sometimes referred to as @dfn{random-access}
+files.
+
+You can use the functions in this section to examine or modify the file
+position indicator associated with a stream.  The symbols listed below
+are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun {long int} ftell (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function returns the current file position of the stream
+@var{stream}.
+
+This function can fail if the stream doesn't support file positioning,
+or if the file position can't be represented in a @code{long int}, and
+possibly for other reasons as well.  If a failure occurs, a value of
+@code{-1} is returned.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun off_t ftello (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{ftello} function is similar to @code{ftell}, except that it
+returns a value of type @code{off_t}.  Systems which support this type
+use it to describe all file positions, unlike the POSIX specification
+which uses a long int.  The two are not necessarily the same size.
+Therefore, using ftell can lead to problems if the implementation is
+written on top of a POSIX compliant low-level I/O implementation, and using
+@code{ftello} is preferable whenever it is available.
+
+If this function fails it returns @code{(off_t) -1}.  This can happen due
+to missing support for file positioning or internal errors.  Otherwise
+the return value is the current file position.
+
+The function is an extension defined in the Unix Single Specification
+version 2.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit system this function is in fact @code{ftello64}.  I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun off64_t ftello64 (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is similar to @code{ftello} with the only difference that
+the return value is of type @code{off64_t}.  This also requires that the
+stream @var{stream} was opened using either @code{fopen64},
+@code{freopen64}, or @code{tmpfile64} since otherwise the underlying
+file operations to position the file pointer beyond the @twoexp{31}
+bytes limit might fail.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{ftello}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fseek (FILE *@var{stream}, long int @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{fseek} function is used to change the file position of the
+stream @var{stream}.  The value of @var{whence} must be one of the
+constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}, to
+indicate whether the @var{offset} is relative to the beginning of the
+file, the current file position, or the end of the file, respectively.
+
+This function returns a value of zero if the operation was successful,
+and a nonzero value to indicate failure.  A successful call also clears
+the end-of-file indicator of @var{stream} and discards any characters
+that were ``pushed back'' by the use of @code{ungetc}.
+
+@code{fseek} either flushes any buffered output before setting the file
+position or else remembers it so it will be written later in its proper
+place in the file.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fseeko (FILE *@var{stream}, off_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is similar to @code{fseek} but it corrects a problem with
+@code{fseek} in a system with POSIX types.  Using a value of type
+@code{long int} for the offset is not compatible with POSIX.
+@code{fseeko} uses the correct type @code{off_t} for the @var{offset}
+parameter.
+
+For this reason it is a good idea to prefer @code{ftello} whenever it is
+available since its functionality is (if different at all) closer the
+underlying definition.
+
+The functionality and return value is the same as for @code{fseek}.
+
+The function is an extension defined in the Unix Single Specification
+version 2.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit system this function is in fact @code{fseeko64}.  I.e., the
+LFS interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fseeko64 (FILE *@var{stream}, off64_t @var{offset}, int @var{whence})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is similar to @code{fseeko} with the only difference that
+the @var{offset} parameter is of type @code{off64_t}.  This also
+requires that the stream @var{stream} was opened using either
+@code{fopen64}, @code{freopen64}, or @code{tmpfile64} since otherwise
+the underlying file operations to position the file pointer beyond the
+@twoexp{31} bytes limit might fail.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fseeko}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@strong{Portability Note:} In non-POSIX systems, @code{ftell},
+@code{ftello}, @code{fseek} and @code{fseeko} might work reliably only
+on binary streams.  @xref{Binary Streams}.
+
+The following symbolic constants are defined for use as the @var{whence}
+argument to @code{fseek}.  They are also used with the @code{lseek}
+function (@pxref{I/O Primitives}) and to specify offsets for file locks
+(@pxref{Control Operations}).
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int SEEK_SET
+This is an integer constant which, when used as the @var{whence}
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the beginning of the file.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int SEEK_CUR
+This is an integer constant which, when used as the @var{whence}
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the current file position.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int SEEK_END
+This is an integer constant which, when used as the @var{whence}
+argument to the @code{fseek} or @code{fseeko} function, specifies that
+the offset provided is relative to the end of the file.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypefun void rewind (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{rewind} function positions the stream @var{stream} at the
+beginning of the file.  It is equivalent to calling @code{fseek} or
+@code{fseeko} on the @var{stream} with an @var{offset} argument of
+@code{0L} and a @var{whence} argument of @code{SEEK_SET}, except that
+the return value is discarded and the error indicator for the stream is
+reset.
+@end deftypefun
+
+These three aliases for the @samp{SEEK_@dots{}} constants exist for the
+sake of compatibility with older BSD systems.  They are defined in two
+different header files: @file{fcntl.h} and @file{sys/file.h}.
+
+@table @code
+@comment sys/file.h
+@comment BSD
+@item L_SET
+@vindex L_SET
+An alias for @code{SEEK_SET}.
+
+@comment sys/file.h
+@comment BSD
+@item L_INCR
+@vindex L_INCR
+An alias for @code{SEEK_CUR}.
+
+@comment sys/file.h
+@comment BSD
+@item L_XTND
+@vindex L_XTND
+An alias for @code{SEEK_END}.
+@end table
+
+@node Portable Positioning
+@section Portable File-Position Functions
+
+On @gnusystems{}, the file position is truly a character count.  You
+can specify any character count value as an argument to @code{fseek} or
+@code{fseeko} and get reliable results for any random access file.
+However, some @w{ISO C} systems do not represent file positions in this
+way.
+
+On some systems where text streams truly differ from binary streams, it
+is impossible to represent the file position of a text stream as a count
+of characters from the beginning of the file.  For example, the file
+position on some systems must encode both a record offset within the
+file, and a character offset within the record.
+
+As a consequence, if you want your programs to be portable to these
+systems, you must observe certain rules:
+
+@itemize @bullet
+@item
+The value returned from @code{ftell} on a text stream has no predictable
+relationship to the number of characters you have read so far.  The only
+thing you can rely on is that you can use it subsequently as the
+@var{offset} argument to @code{fseek} or @code{fseeko} to move back to
+the same file position.
+
+@item
+In a call to @code{fseek} or @code{fseeko} on a text stream, either the
+@var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and
+the @var{offset} must be the result of an earlier call to @code{ftell}
+on the same stream.
+
+@item
+The value of the file position indicator of a text stream is undefined
+while there are characters that have been pushed back with @code{ungetc}
+that haven't been read or discarded.  @xref{Unreading}.
+@end itemize
+
+But even if you observe these rules, you may still have trouble for long
+files, because @code{ftell} and @code{fseek} use a @code{long int} value
+to represent the file position.  This type may not have room to encode
+all the file positions in a large file.  Using the @code{ftello} and
+@code{fseeko} functions might help here since the @code{off_t} type is
+expected to be able to hold all file position values but this still does
+not help to handle additional information which must be associated with
+a file position.
+
+So if you do want to support systems with peculiar encodings for the
+file positions, it is better to use the functions @code{fgetpos} and
+@code{fsetpos} instead.  These functions represent the file position
+using the data type @code{fpos_t}, whose internal representation varies
+from system to system.
+
+These symbols are declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftp {Data Type} fpos_t
+This is the type of an object that can encode information about the
+file position of a stream, for use by the functions @code{fgetpos} and
+@code{fsetpos}.
+
+In @theglibc{}, @code{fpos_t} is an opaque data structure that
+contains internal data to represent file offset and conversion state
+information.  In other systems, it might have a different internal
+representation.
+
+When compiling with @code{_FILE_OFFSET_BITS == 64} on a 32 bit machine
+this type is in fact equivalent to @code{fpos64_t} since the LFS
+interface transparently replaces the old interface.
+@end deftp
+
+@comment stdio.h
+@comment Unix98
+@deftp {Data Type} fpos64_t
+This is the type of an object that can encode information about the
+file position of a stream, for use by the functions @code{fgetpos64} and
+@code{fsetpos64}.
+
+In @theglibc{}, @code{fpos64_t} is an opaque data structure that
+contains internal data to represent file offset and conversion state
+information.  In other systems, it might have a different internal
+representation.
+@end deftp
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fgetpos (FILE *@var{stream}, fpos_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function stores the value of the file position indicator for the
+stream @var{stream} in the @code{fpos_t} object pointed to by
+@var{position}.  If successful, @code{fgetpos} returns zero; otherwise
+it returns a nonzero value and stores an implementation-defined positive
+value in @code{errno}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit system the function is in fact @code{fgetpos64}.  I.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fgetpos64 (FILE *@var{stream}, fpos64_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is similar to @code{fgetpos} but the file position is
+returned in a variable of type @code{fpos64_t} to which @var{position}
+points.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fgetpos}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fsetpos (FILE *@var{stream}, const fpos_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function sets the file position indicator for the stream @var{stream}
+to the position @var{position}, which must have been set by a previous
+call to @code{fgetpos} on the same stream.  If successful, @code{fsetpos}
+clears the end-of-file indicator on the stream, discards any characters
+that were ``pushed back'' by the use of @code{ungetc}, and returns a value
+of zero.  Otherwise, @code{fsetpos} returns a nonzero value and stores
+an implementation-defined positive value in @code{errno}.
+
+When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
+32 bit system the function is in fact @code{fsetpos64}.  I.e., the LFS
+interface transparently replaces the old interface.
+@end deftypefun
+
+@comment stdio.h
+@comment Unix98
+@deftypefun int fsetpos64 (FILE *@var{stream}, const fpos64_t *@var{position})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is similar to @code{fsetpos} but the file position used
+for positioning is provided in a variable of type @code{fpos64_t} to
+which @var{position} points.
+
+If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
+bits machine this function is available under the name @code{fsetpos}
+and so transparently replaces the old interface.
+@end deftypefun
+
+@node Stream Buffering
+@section Stream Buffering
+
+@cindex buffering of streams
+Characters that are written to a stream are normally accumulated and
+transmitted asynchronously to the file in a block, instead of appearing
+as soon as they are output by the application program.  Similarly,
+streams often retrieve input from the host environment in blocks rather
+than on a character-by-character basis.  This is called @dfn{buffering}.
+
+If you are writing programs that do interactive input and output using
+streams, you need to understand how buffering works when you design the
+user interface to your program.  Otherwise, you might find that output
+(such as progress or prompt messages) doesn't appear when you intended
+it to, or displays some other unexpected behavior.
+
+This section deals only with controlling when characters are transmitted
+between the stream and the file or device, and @emph{not} with how
+things like echoing, flow control, and the like are handled on specific
+classes of devices.  For information on common control operations on
+terminal devices, see @ref{Low-Level Terminal Interface}.
+
+You can bypass the stream buffering facilities altogether by using the
+low-level input and output functions that operate on file descriptors
+instead.  @xref{Low-Level I/O}.
+
+@menu
+* 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.
+@end menu
+
+@node Buffering Concepts
+@subsection Buffering Concepts
+
+There are three different kinds of buffering strategies:
+
+@itemize @bullet
+@item
+Characters written to or read from an @dfn{unbuffered} stream are
+transmitted individually to or from the file as soon as possible.
+@cindex unbuffered stream
+
+@item
+Characters written to a @dfn{line buffered} stream are transmitted to
+the file in blocks when a newline character is encountered.
+@cindex line buffered stream
+
+@item
+Characters written to or read from a @dfn{fully buffered} stream are
+transmitted to or from the file in blocks of arbitrary size.
+@cindex fully buffered stream
+@end itemize
+
+Newly opened streams are normally fully buffered, with one exception: a
+stream connected to an interactive device such as a terminal is
+initially line buffered.  @xref{Controlling Buffering}, for information
+on how to select a different kind of buffering.  Usually the automatic
+selection gives you the most convenient kind of buffering for the file
+or device you open.
+
+The use of line buffering for interactive devices implies that output
+messages ending in a newline will appear immediately---which is usually
+what you want.  Output that doesn't end in a newline might or might not
+show up immediately, so if you want them to appear immediately, you
+should flush buffered output explicitly with @code{fflush}, as described
+in @ref{Flushing Buffers}.
+
+@node Flushing Buffers
+@subsection Flushing Buffers
+
+@cindex flushing a stream
+@dfn{Flushing} output on a buffered stream means transmitting all
+accumulated characters to the file.  There are many circumstances when
+buffered output on a stream is flushed automatically:
+
+@itemize @bullet
+@item
+When you try to do output and the output buffer is full.
+
+@item
+When the stream is closed.  @xref{Closing Streams}.
+
+@item
+When the program terminates by calling @code{exit}.
+@xref{Normal Termination}.
+
+@item
+When a newline is written, if the stream is line buffered.
+
+@item
+Whenever an input operation on @emph{any} stream actually reads data
+from its file.
+@end itemize
+
+If you want to flush the buffered output at another time, call
+@code{fflush}, which is declared in the header file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int fflush (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function causes any buffered output on @var{stream} to be delivered
+to the file.  If @var{stream} is a null pointer, then
+@code{fflush} causes buffered output on @emph{all} open output streams
+to be flushed.
+
+This function returns @code{EOF} if a write error occurs, or zero
+otherwise.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX
+@deftypefun int fflush_unlocked (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{fflush_unlocked} function is equivalent to the @code{fflush}
+function except that it does not implicitly lock the stream.
+@end deftypefun
+
+The @code{fflush} function can be used to flush all streams currently
+opened.  While this is useful in some situations it does often more than
+necessary since it might be done in situations when terminal input is
+required and the program wants to be sure that all output is visible on
+the terminal.  But this means that only line buffered streams have to be
+flushed.  Solaris introduced a function especially for this.  It was
+always available in @theglibc{} in some form but never officially
+exported.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun void _flushlbf (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+The @code{_flushlbf} function flushes all line buffered streams
+currently opened.
+
+This function is declared in the @file{stdio_ext.h} header.
+@end deftypefun
+
+@strong{Compatibility Note:} Some brain-damaged operating systems have
+been known to be so thoroughly fixated on line-oriented input and output
+that flushing a line buffered stream causes a newline to be written!
+Fortunately, this ``feature'' seems to be becoming less common.  You do
+not need to worry about this with @theglibc{}.
+
+In some situations it might be useful to not flush the output pending
+for a stream but instead simply forget it.  If transmission is costly
+and the output is not needed anymore this is valid reasoning.  In this
+situation a non-standard function introduced in Solaris and available in
+@theglibc{} can be used.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun void __fpurge (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+The @code{__fpurge} function causes the buffer of the stream
+@var{stream} to be emptied.  If the stream is currently in read mode all
+input in the buffer is lost.  If the stream is in output mode the
+buffered output is not written to the device (or whatever other
+underlying storage) and the buffer the cleared.
+
+This function is declared in @file{stdio_ext.h}.
+@end deftypefun
+
+@node Controlling Buffering
+@subsection Controlling Which Kind of Buffering
+
+After opening a stream (but before any other operations have been
+performed on it), you can explicitly specify what kind of buffering you
+want it to have using the @code{setvbuf} function.
+@cindex buffering, controlling
+
+The facilities listed in this section are declared in the header
+file @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment ISO
+@deftypefun int setvbuf (FILE *@var{stream}, char *@var{buf}, int @var{mode}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function is used to specify that the stream @var{stream} should
+have the buffering mode @var{mode}, which can be either @code{_IOFBF}
+(for full buffering), @code{_IOLBF} (for line buffering), or
+@code{_IONBF} (for unbuffered input/output).
+
+If you specify a null pointer as the @var{buf} argument, then @code{setvbuf}
+allocates a buffer itself using @code{malloc}.  This buffer will be freed
+when you close the stream.
+
+Otherwise, @var{buf} should be a character array that can hold at least
+@var{size} characters.  You should not free the space for this array as
+long as the stream remains open and this array remains its buffer.  You
+should usually either allocate it statically, or @code{malloc}
+(@pxref{Unconstrained Allocation}) the buffer.  Using an automatic array
+is not a good idea unless you close the file before exiting the block
+that declares the array.
+
+While the array remains a stream buffer, the stream I/O functions will
+use the buffer for their internal purposes.  You shouldn't try to access
+the values in the array directly while the stream is using it for
+buffering.
+
+The @code{setvbuf} function returns zero on success, or a nonzero value
+if the value of @var{mode} is not valid or if the request could not
+be honored.
+@end deftypefun
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int _IOFBF
+The value of this macro is an integer constant expression that can be
+used as the @var{mode} argument to the @code{setvbuf} function to
+specify that the stream should be fully buffered.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int _IOLBF
+The value of this macro is an integer constant expression that can be
+used as the @var{mode} argument to the @code{setvbuf} function to
+specify that the stream should be line buffered.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int _IONBF
+The value of this macro is an integer constant expression that can be
+used as the @var{mode} argument to the @code{setvbuf} function to
+specify that the stream should be unbuffered.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypevr Macro int BUFSIZ
+The value of this macro is an integer constant expression that is good
+to use for the @var{size} argument to @code{setvbuf}.  This value is
+guaranteed to be at least @code{256}.
+
+The value of @code{BUFSIZ} is chosen on each system so as to make stream
+I/O efficient.  So it is a good idea to use @code{BUFSIZ} as the size
+for the buffer when you call @code{setvbuf}.
+
+Actually, you can get an even better value to use for the buffer size
+by means of the @code{fstat} system call: it is found in the
+@code{st_blksize} field of the file attributes.  @xref{Attribute Meanings}.
+
+Sometimes people also use @code{BUFSIZ} as the allocation size of
+buffers used for related purposes, such as strings used to receive a
+line of input with @code{fgets} (@pxref{Character Input}).  There is no
+particular reason to use @code{BUFSIZ} for this instead of any other
+integer, except that it might lead to doing I/O in chunks of an
+efficient size.
+@end deftypevr
+
+@comment stdio.h
+@comment ISO
+@deftypefun void setbuf (FILE *@var{stream}, char *@var{buf})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+If @var{buf} is a null pointer, the effect of this function is
+equivalent to calling @code{setvbuf} with a @var{mode} argument of
+@code{_IONBF}.  Otherwise, it is equivalent to calling @code{setvbuf}
+with @var{buf}, and a @var{mode} of @code{_IOFBF} and a @var{size}
+argument of @code{BUFSIZ}.
+
+The @code{setbuf} function is provided for compatibility with old code;
+use @code{setvbuf} in all new programs.
+@end deftypefun
+
+@comment stdio.h
+@comment BSD
+@deftypefun void setbuffer (FILE *@var{stream}, char *@var{buf}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+If @var{buf} is a null pointer, this function makes @var{stream} unbuffered.
+Otherwise, it makes @var{stream} fully buffered using @var{buf} as the
+buffer.  The @var{size} argument specifies the length of @var{buf}.
+
+This function is provided for compatibility with old BSD code.  Use
+@code{setvbuf} instead.
+@end deftypefun
+
+@comment stdio.h
+@comment BSD
+@deftypefun void setlinebuf (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+This function makes @var{stream} be line buffered, and allocates the
+buffer for you.
+
+This function is provided for compatibility with old BSD code.  Use
+@code{setvbuf} instead.
+@end deftypefun
+
+It is possible to query whether a given stream is line buffered or not
+using a non-standard function introduced in Solaris and available in
+@theglibc{}.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun int __flbf (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{__flbf} function will return a nonzero value in case the
+stream @var{stream} is line buffered.  Otherwise the return value is
+zero.
+
+This function is declared in the @file{stdio_ext.h} header.
+@end deftypefun
+
+Two more extensions allow to determine the size of the buffer and how
+much of it is used.  These functions were also introduced in Solaris.
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun size_t __fbufsize (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
+The @code{__fbufsize} function return the size of the buffer in the
+stream @var{stream}.  This value can be used to optimize the use of the
+stream.
+
+This function is declared in the @file{stdio_ext.h} header.
+@end deftypefun
+
+@comment stdio_ext.h
+@comment GNU
+@deftypefun size_t __fpending (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acsafe{}}
+The @code{__fpending}
+function returns the number of bytes currently in the output buffer.
+For wide-oriented stream the measuring unit is wide characters.  This
+function should not be used on buffers in read mode or opened read-only.
+
+This function is declared in the @file{stdio_ext.h} header.
+@end deftypefun
+
+@node Other Kinds of Streams
+@section Other Kinds of Streams
+
+@Theglibc{} provides ways for you to define additional kinds of
+streams that do not necessarily correspond to an open file.
+
+One such type of stream takes input from or writes output to a string.
+These kinds of streams are used internally to implement the
+@code{sprintf} and @code{sscanf} functions.  You can also create such a
+stream explicitly, using the functions described in @ref{String Streams}.
+
+More generally, you can define streams that do input/output to arbitrary
+objects using functions supplied by your program.  This protocol is
+discussed in @ref{Custom Streams}.
+
+@strong{Portability Note:} The facilities described in this section are
+specific to GNU.  Other systems or C implementations might or might not
+provide equivalent functionality.
+
+@menu
+* String Streams::              Streams that get data from or put data in
+				 a string or memory buffer.
+* Custom Streams::              Defining your own streams with an arbitrary
+				 input data source and/or output data sink.
+@end menu
+
+@node String Streams
+@subsection String Streams
+
+@cindex stream, for I/O to a string
+@cindex string stream
+The @code{fmemopen} and @code{open_memstream} functions allow you to do
+I/O to a string or memory buffer.  These facilities are declared in
+@file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment GNU
+@deftypefun {FILE *} fmemopen (void *@var{buf}, size_t @var{size}, const char *@var{opentype})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+@c Unlike open_memstream, fmemopen does (indirectly) call _IO_link_in,
+@c bringing with it additional potential for async trouble with
+@c list_all_lock.
+This function opens a stream that allows the access specified by the
+@var{opentype} argument, that reads from or writes to the buffer specified
+by the argument @var{buf}.  This array must be at least @var{size} bytes long.
+
+If you specify a null pointer as the @var{buf} argument, @code{fmemopen}
+dynamically allocates an array @var{size} bytes long (as with @code{malloc};
+@pxref{Unconstrained Allocation}).  This is really only useful
+if you are going to write things to the buffer and then read them back
+in again, because you have no way of actually getting a pointer to the
+buffer (for this, try @code{open_memstream}, below).  The buffer is
+freed when the stream is closed.
+
+The argument @var{opentype} is the same as in @code{fopen}
+(@pxref{Opening Streams}).  If the @var{opentype} specifies
+append mode, then the initial file position is set to the first null
+character in the buffer.  Otherwise the initial file position is at the
+beginning of the buffer.
+
+When a stream open for writing is flushed or closed, a null character
+(zero byte) is written at the end of the buffer if it fits.  You
+should add an extra byte to the @var{size} argument to account for this.
+Attempts to write more than @var{size} bytes to the buffer result
+in an error.
+
+For a stream open for reading, null characters (zero bytes) in the
+buffer do not count as ``end of file''.  Read operations indicate end of
+file only when the file position advances past @var{size} bytes.  So, if
+you want to read characters from a null-terminated string, you should
+supply the length of the string as the @var{size} argument.
+@end deftypefun
+
+Here is an example of using @code{fmemopen} to create a stream for
+reading from a string:
+
+@smallexample
+@include memopen.c.texi
+@end smallexample
+
+This program produces the following output:
+
+@smallexample
+Got f
+Got o
+Got o
+Got b
+Got a
+Got r
+@end smallexample
+
+@comment stdio.h
+@comment GNU
+@deftypefun {FILE *} open_memstream (char **@var{ptr}, size_t *@var{sizeloc})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function opens a stream for writing to a buffer.  The buffer is
+allocated dynamically and grown as necessary, using @code{malloc}.
+After you've closed the stream, this buffer is your responsibility to
+clean up using @code{free} or @code{realloc}.  @xref{Unconstrained Allocation}.
+
+When the stream is closed with @code{fclose} or flushed with
+@code{fflush}, the locations @var{ptr} and @var{sizeloc} are updated to
+contain the pointer to the buffer and its size.  The values thus stored
+remain valid only as long as no further output on the stream takes
+place.  If you do more output, you must flush the stream again to store
+new values before you use them again.
+
+A null character is written at the end of the buffer.  This null character
+is @emph{not} included in the size value stored at @var{sizeloc}.
+
+You can move the stream's file position with @code{fseek} or
+@code{fseeko} (@pxref{File Positioning}).  Moving the file position past
+the end of the data already written fills the intervening space with
+zeroes.
+@end deftypefun
+
+Here is an example of using @code{open_memstream}:
+
+@smallexample
+@include memstrm.c.texi
+@end smallexample
+
+This program produces the following output:
+
+@smallexample
+buf = `hello', size = 5
+buf = `hello, world', size = 12
+@end smallexample
+
+@node Custom Streams
+@subsection Programming Your Own Custom Streams
+@cindex custom streams
+@cindex programming your own streams
+
+This section describes how you can make a stream that gets input from an
+arbitrary data source or writes output to an arbitrary data sink
+programmed by you.  We call these @dfn{custom streams}.  The functions
+and types described here are all GNU extensions.
+
+@c !!! this does not talk at all about the higher-level hooks
+
+@menu
+* 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.
+@end menu
+
+@node Streams and Cookies
+@subsubsection Custom Streams and Cookies
+@cindex cookie, for custom stream
+
+Inside every custom stream is a special object called the @dfn{cookie}.
+This is an object supplied by you which records where to fetch or store
+the data read or written.  It is up to you to define a data type to use
+for the cookie.  The stream functions in the library never refer
+directly to its contents, and they don't even know what the type is;
+they record its address with type @code{void *}.
+
+To implement a custom stream, you must specify @emph{how} to fetch or
+store the data in the specified place.  You do this by defining
+@dfn{hook functions} to read, write, change ``file position'', and close
+the stream.  All four of these functions will be passed the stream's
+cookie so they can tell where to fetch or store the data.  The library
+functions don't know what's inside the cookie, but your functions will
+know.
+
+When you create a custom stream, you must specify the cookie pointer,
+and also the four hook functions stored in a structure of type
+@code{cookie_io_functions_t}.
+
+These facilities are declared in @file{stdio.h}.
+@pindex stdio.h
+
+@comment stdio.h
+@comment GNU
+@deftp {Data Type} {cookie_io_functions_t}
+This is a structure type that holds the functions that define the
+communications protocol between the stream and its cookie.  It has
+the following members:
+
+@table @code
+@item cookie_read_function_t *read
+This is the function that reads data from the cookie.  If the value is a
+null pointer instead of a function, then read operations on this stream
+always return @code{EOF}.
+
+@item cookie_write_function_t *write
+This is the function that writes data to the cookie.  If the value is a
+null pointer instead of a function, then data written to the stream is
+discarded.
+
+@item cookie_seek_function_t *seek
+This is the function that performs the equivalent of file positioning on
+the cookie.  If the value is a null pointer instead of a function, calls
+to @code{fseek} or @code{fseeko} on this stream can only seek to
+locations within the buffer; any attempt to seek outside the buffer will
+return an @code{ESPIPE} error.
+
+@item cookie_close_function_t *close
+This function performs any appropriate cleanup on the cookie when
+closing the stream.  If the value is a null pointer instead of a
+function, nothing special is done to close the cookie when the stream is
+closed.
+@end table
+@end deftp
+
+@comment stdio.h
+@comment GNU
+@deftypefun {FILE *} fopencookie (void *@var{cookie}, const char *@var{opentype}, cookie_io_functions_t @var{io-functions})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
+This function actually creates the stream for communicating with the
+@var{cookie} using the functions in the @var{io-functions} argument.
+The @var{opentype} argument is interpreted as for @code{fopen};
+see @ref{Opening Streams}.  (But note that the ``truncate on
+open'' option is ignored.)  The new stream is fully buffered.
+
+The @code{fopencookie} function returns the newly created stream, or a null
+pointer in case of an error.
+@end deftypefun
+
+@node Hook Functions
+@subsubsection Custom Stream Hook Functions
+@cindex hook functions (of custom streams)
+
+Here are more details on how you should define the four hook functions
+that a custom stream needs.
+
+You should define the function to read data from the cookie as:
+
+@smallexample
+ssize_t @var{reader} (void *@var{cookie}, char *@var{buffer}, size_t @var{size})
+@end smallexample
+
+This is very similar to the @code{read} function; see @ref{I/O
+Primitives}.  Your function should transfer up to @var{size} bytes into
+the @var{buffer}, and return the number of bytes read, or zero to
+indicate end-of-file.  You can return a value of @code{-1} to indicate
+an error.
+
+You should define the function to write data to the cookie as:
+
+@smallexample
+ssize_t @var{writer} (void *@var{cookie}, const char *@var{buffer}, size_t @var{size})
+@end smallexample
+
+This is very similar to the @code{write} function; see @ref{I/O
+Primitives}.  Your function should transfer up to @var{size} bytes from
+the buffer, and return the number of bytes written.  You can return a
+value of @code{0} to indicate an error.  You must not return any
+negative value.
+
+You should define the function to perform seek operations on the cookie
+as:
+
+@smallexample
+int @var{seeker} (void *@var{cookie}, off64_t *@var{position}, int @var{whence})
+@end smallexample
+
+For this function, the @var{position} and @var{whence} arguments are
+interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.
+
+After doing the seek operation, your function should store the resulting
+file position relative to the beginning of the file in @var{position}.
+Your function should return a value of @code{0} on success and @code{-1}
+to indicate an error.
+
+You should define the function to do cleanup operations on the cookie
+appropriate for closing the stream as:
+
+@smallexample
+int @var{cleaner} (void *@var{cookie})
+@end smallexample
+
+Your function should return @code{-1} to indicate an error, and @code{0}
+otherwise.
+
+@comment stdio.h
+@comment GNU
+@deftp {Data Type} cookie_read_function_t
+This is the data type that the read function for a custom stream should have.
+If you declare the function as shown above, this is the type it will have.
+@end deftp
+
+@comment stdio.h
+@comment GNU
+@deftp {Data Type} cookie_write_function_t
+The data type of the write function for a custom stream.
+@end deftp
+
+@comment stdio.h
+@comment GNU
+@deftp {Data Type} cookie_seek_function_t
+The data type of the seek function for a custom stream.
+@end deftp
+
+@comment stdio.h
+@comment GNU
+@deftp {Data Type} cookie_close_function_t
+The data type of the close function for a custom stream.
+@end deftp
+
+@ignore
+Roland says:
+
+@quotation
+There is another set of functions one can give a stream, the
+input-room and output-room functions.  These functions must
+understand stdio internals.  To describe how to use these
+functions, you also need to document lots of how stdio works
+internally (which isn't relevant for other uses of stdio).
+Perhaps I can write an interface spec from which you can write
+good documentation.  But it's pretty complex and deals with lots
+of nitty-gritty details.  I think it might be better to let this
+wait until the rest of the manual is more done and polished.
+@end quotation
+@end ignore
+
+@c ??? This section could use an example.
+
+
+@node Formatted Messages
+@section Formatted Messages
+@cindex formatted messages
+
+On systems which are based on System V messages of programs (especially
+the system tools) are printed in a strict form using the @code{fmtmsg}
+function.  The uniformity sometimes helps the user to interpret messages
+and the strictness tests of the @code{fmtmsg} function ensure that the
+programmer follows some minimal requirements.
+
+@menu
+* Printing Formatted Messages::   The @code{fmtmsg} function.
+* Adding Severity Classes::       Add more severity classes.
+* Example::                       How to use @code{fmtmsg} and @code{addseverity}.
+@end menu
+
+
+@node Printing Formatted Messages
+@subsection Printing Formatted Messages
+
+Messages can be printed to standard error and/or to the console.  To
+select the destination the programmer can use the following two values,
+bitwise OR combined if wanted, for the @var{classification} parameter of
+@code{fmtmsg}:
+
+@vtable @code
+@item MM_PRINT
+Display the message in standard error.
+@item MM_CONSOLE
+Display the message on the system console.
+@end vtable
+
+The erroneous piece of the system can be signalled by exactly one of the
+following values which also is bitwise ORed with the
+@var{classification} parameter to @code{fmtmsg}:
+
+@vtable @code
+@item MM_HARD
+The source of the condition is some hardware.
+@item MM_SOFT
+The source of the condition is some software.
+@item MM_FIRM
+The source of the condition is some firmware.
+@end vtable
+
+A third component of the @var{classification} parameter to @code{fmtmsg}
+can describe the part of the system which detects the problem.  This is
+done by using exactly one of the following values:
+
+@vtable @code
+@item MM_APPL
+The erroneous condition is detected by the application.
+@item MM_UTIL
+The erroneous condition is detected by a utility.
+@item MM_OPSYS
+The erroneous condition is detected by the operating system.
+@end vtable
+
+A last component of @var{classification} can signal the results of this
+message.  Exactly one of the following values can be used:
+
+@vtable @code
+@item MM_RECOVER
+It is a recoverable error.
+@item MM_NRECOV
+It is a non-recoverable error.
+@end vtable
+
+@comment fmtmsg.h
+@comment XPG
+@deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acsafe{}}
+Display a message described by its parameters on the device(s) specified
+in the @var{classification} parameter.  The @var{label} parameter
+identifies the source of the message.  The string should consist of two
+colon separated parts where the first part has not more than 10 and the
+second part not more than 14 characters.  The @var{text} parameter
+describes the condition of the error, the @var{action} parameter possible
+steps to recover from the error and the @var{tag} parameter is a
+reference to the online documentation where more information can be
+found.  It should contain the @var{label} value and a unique
+identification number.
+
+Each of the parameters can be a special value which means this value
+is to be omitted.  The symbolic names for these values are:
+
+@vtable @code
+@item MM_NULLLBL
+Ignore @var{label} parameter.
+@item MM_NULLSEV
+Ignore @var{severity} parameter.
+@item MM_NULLMC
+Ignore @var{classification} parameter.  This implies that nothing is
+actually printed.
+@item MM_NULLTXT
+Ignore @var{text} parameter.
+@item MM_NULLACT
+Ignore @var{action} parameter.
+@item MM_NULLTAG
+Ignore @var{tag} parameter.
+@end vtable
+
+There is another way certain fields can be omitted from the output to
+standard error.  This is described below in the description of
+environment variables influencing the behavior.
+
+The @var{severity} parameter can have one of the values in the following
+table:
+@cindex severity class
+
+@vtable @code
+@item MM_NOSEV
+Nothing is printed, this value is the same as @code{MM_NULLSEV}.
+@item MM_HALT
+This value is printed as @code{HALT}.
+@item MM_ERROR
+This value is printed as @code{ERROR}.
+@item MM_WARNING
+This value is printed as @code{WARNING}.
+@item MM_INFO
+This value is printed as @code{INFO}.
+@end vtable
+
+The numeric value of these five macros are between @code{0} and
+@code{4}.  Using the environment variable @code{SEV_LEVEL} or using the
+@code{addseverity} function one can add more severity levels with their
+corresponding string to print.  This is described below
+(@pxref{Adding Severity Classes}).
+
+@noindent
+If no parameter is ignored the output looks like this:
+
+@smallexample
+@var{label}: @var{severity-string}: @var{text}
+TO FIX: @var{action} @var{tag}
+@end smallexample
+
+The colons, new line characters and the @code{TO FIX} string are
+inserted if necessary, i.e., if the corresponding parameter is not
+ignored.
+
+This function is specified in the X/Open Portability Guide.  It is also
+available on all systems derived from System V.
+
+The function returns the value @code{MM_OK} if no error occurred.  If
+only the printing to standard error failed, it returns @code{MM_NOMSG}.
+If printing to the console fails, it returns @code{MM_NOCON}.  If
+nothing is printed @code{MM_NOTOK} is returned.  Among situations where
+all outputs fail this last value is also returned if a parameter value
+is incorrect.
+@end deftypefun
+
+There are two environment variables which influence the behavior of
+@code{fmtmsg}.  The first is @code{MSGVERB}.  It is used to control the
+output actually happening on standard error (@emph{not} the console
+output).  Each of the five fields can explicitly be enabled.  To do
+this the user has to put the @code{MSGVERB} variable with a format like
+the following in the environment before calling the @code{fmtmsg} function
+the first time:
+
+@smallexample
+MSGVERB=@var{keyword}[:@var{keyword}[:@dots{}]]
+@end smallexample
+
+Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
+@code{action}, and @code{tag}.  If the environment variable is not given
+or is the empty string, a not supported keyword is given or the value is
+somehow else invalid, no part of the message is masked out.
+
+The second environment variable which influences the behavior of
+@code{fmtmsg} is @code{SEV_LEVEL}.  This variable and the change in the
+behavior of @code{fmtmsg} is not specified in the X/Open Portability
+Guide.  It is available in System V systems, though.  It can be used to
+introduce new severity levels.  By default, only the five severity levels
+described above are available.  Any other numeric value would make
+@code{fmtmsg} print nothing.
+
+If the user puts @code{SEV_LEVEL} with a format like
+
+@smallexample
+SEV_LEVEL=[@var{description}[:@var{description}[:@dots{}]]]
+@end smallexample
+
+@noindent
+in the environment of the process before the first call to
+@code{fmtmsg}, where @var{description} has a value of the form
+
+@smallexample
+@var{severity-keyword},@var{level},@var{printstring}
+@end smallexample
+
+The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
+to be present.  The @var{level} part is a string representation of a
+number.  The numeric value must be a number greater than 4.  This value
+must be used in the @var{severity} parameter of @code{fmtmsg} to select
+this class.  It is not possible to overwrite any of the predefined
+classes.  The @var{printstring} is the string printed when a message of
+this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
+not print the numeric value but instead the string representation).
+
+
+@node Adding Severity Classes
+@subsection Adding Severity Classes
+@cindex severity class
+
+There is another possibility to introduce severity classes besides using
+the environment variable @code{SEV_LEVEL}.  This simplifies the task of
+introducing new classes in a running program.  One could use the
+@code{setenv} or @code{putenv} function to set the environment variable,
+but this is toilsome.
+
+@deftypefun int addseverity (int @var{severity}, const char *@var{string})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+This function allows the introduction of new severity classes which can be
+addressed by the @var{severity} parameter of the @code{fmtmsg} function.
+The @var{severity} parameter of @code{addseverity} must match the value
+for the parameter with the same name of @code{fmtmsg}, and @var{string}
+is the string printed in the actual messages instead of the numeric
+value.
+
+If @var{string} is @code{NULL} the severity class with the numeric value
+according to @var{severity} is removed.
+
+It is not possible to overwrite or remove one of the default severity
+classes.  All calls to @code{addseverity} with @var{severity} set to one
+of the values for the default classes will fail.
+
+The return value is @code{MM_OK} if the task was successfully performed.
+If the return value is @code{MM_NOTOK} something went wrong.  This could
+mean that no more memory is available or a class is not available when
+it has to be removed.
+
+This function is not specified in the X/Open Portability Guide although
+the @code{fmtsmg} function is.  It is available on System V systems.
+@end deftypefun
+
+
+@node Example
+@subsection How to use @code{fmtmsg} and @code{addseverity}
+
+Here is a simple example program to illustrate the use of the both
+functions described in this section.
+
+@smallexample
+@include fmtmsgexpl.c.texi
+@end smallexample
+
+The second call to @code{fmtmsg} illustrates a use of this function as
+it usually occurs on System V systems, which heavily use this function.
+It seems worthwhile to give a short explanation here of how this system
+works on System V.  The value of the
+@var{label} field (@code{UX:cat}) says that the error occurred in the
+Unix program @code{cat}.  The explanation of the error follows and the
+value for the @var{action} parameter is @code{"refer to manual"}.  One
+could be more specific here, if necessary.  The @var{tag} field contains,
+as proposed above, the value of the string given for the @var{label}
+parameter, and additionally a unique ID (@code{001} in this case).  For
+a GNU environment this string could contain a reference to the
+corresponding node in the Info page for the program.
+
+@noindent
+Running this program without specifying the @code{MSGVERB} and
+@code{SEV_LEVEL} function produces the following output:
+
+@smallexample
+UX:cat: NOTE2: invalid syntax
+TO FIX: refer to manual UX:cat:001
+@end smallexample
+
+We see the different fields of the message and how the extra glue (the
+colons and the @code{TO FIX} string) are printed.  But only one of the
+three calls to @code{fmtmsg} produced output.  The first call does not
+print anything because the @var{label} parameter is not in the correct
+form.  The string must contain two fields, separated by a colon
+(@pxref{Printing Formatted Messages}).  The third @code{fmtmsg} call
+produced no output since the class with the numeric value @code{6} is
+not defined.  Although a class with numeric value @code{5} is also not
+defined by default, the call to @code{addseverity} introduces it and
+the second call to @code{fmtmsg} produces the above output.
+
+When we change the environment of the program to contain
+@code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
+
+@smallexample
+UX:cat: NOTE2: invalid syntax
+TO FIX: refer to manual UX:cat:001
+label:foo: NOTE: text
+TO FIX: action tag
+@end smallexample
+
+Now the third call to @code{fmtmsg} produced some output and we see how
+the string @code{NOTE} from the environment variable appears in the
+message.
+
+Now we can reduce the output by specifying which fields we are
+interested in.  If we additionally set the environment variable
+@code{MSGVERB} to the value @code{severity:label:action} we get the
+following output:
+
+@smallexample
+UX:cat: NOTE2
+TO FIX: refer to manual
+label:foo: NOTE
+TO FIX: action
+@end smallexample
+
+@noindent
+I.e., the output produced by the @var{text} and the @var{tag} parameters
+to @code{fmtmsg} vanished.  Please also note that now there is no colon
+after the @code{NOTE} and @code{NOTE2} strings in the output.  This is
+not necessary since there is no more output on this line because the text
+is missing.
diff --git a/ap/libc/glibc/glibc-2.23/manual/string.texi b/ap/libc/glibc/glibc-2.23/manual/string.texi
new file mode 100644
index 0000000..016fd0b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/string.texi
@@ -0,0 +1,2872 @@
+@node String and Array Utilities, Character Set Handling, Character Handling, Top
+@c %MENU% Utilities for copying and comparing strings and arrays
+@chapter String and Array Utilities
+
+Operations on strings (null-terminated byte sequences) are an important part of
+many programs.  @Theglibc{} provides an extensive set of string
+utility functions, including functions for copying, concatenating,
+comparing, and searching strings.  Many of these functions can also
+operate on arbitrary regions of storage; for example, the @code{memcpy}
+function can be used to copy the contents of any kind of array.
+
+It's fairly common for beginning C programmers to ``reinvent the wheel''
+by duplicating this functionality in their own code, but it pays to
+become familiar with the library functions and to make use of them,
+since this offers benefits in maintenance, efficiency, and portability.
+
+For instance, you could easily compare one string to another in two
+lines of C code, but if you use the built-in @code{strcmp} function,
+you're less likely to make a mistake.  And, since these library
+functions are typically highly optimized, your program may run faster
+too.
+
+@menu
+* Representation of Strings::   Introduction to basic concepts.
+* String/Array Conventions::    Whether to use a string function or an
+				 arbitrary array function.
+* String Length::               Determining the length of a string.
+* Copying Strings and Arrays::  Functions to copy strings and arrays.
+* Concatenating Strings::       Functions to concatenate strings while copying.
+* Truncating Strings::          Functions to truncate strings while copying.
+* String/Array Comparison::     Functions for byte-wise and character-wise
+				 comparison.
+* Collation Functions::         Functions for collating strings.
+* Search Functions::            Searching for a specific element or substring.
+* Finding Tokens in a String::  Splitting a string into tokens by looking
+				 for delimiters.
+* strfry::                      Function for flash-cooking a string.
+* Trivial Encryption::          Obscuring data.
+* Encode Binary Data::          Encoding and Decoding of Binary Data.
+* Argz and Envz Vectors::       Null-separated string vectors.
+@end menu
+
+@node Representation of Strings
+@section Representation of Strings
+@cindex string, representation of
+
+This section is a quick summary of string concepts for beginning C
+programmers.  It describes how strings are represented in C
+and some common pitfalls.  If you are already familiar with this
+material, you can skip this section.
+
+@cindex string
+A @dfn{string} is a null-terminated array of bytes of type @code{char},
+including the terminating null byte.  String-valued
+variables are usually declared to be pointers of type @code{char *}.
+Such variables do not include space for the text of a string; that has
+to be stored somewhere else---in an array variable, a string constant,
+or dynamically allocated memory (@pxref{Memory Allocation}).  It's up to
+you to store the address of the chosen memory space into the pointer
+variable.  Alternatively you can store a @dfn{null pointer} in the
+pointer variable.  The null pointer does not point anywhere, so
+attempting to reference the string it points to gets an error.
+
+@cindex multibyte character
+@cindex multibyte string
+@cindex wide string
+A @dfn{multibyte character} is a sequence of one or more bytes that
+represents a single character using the locale's encoding scheme; a
+null byte always represents the null character.  A @dfn{multibyte
+string} is a string that consists entirely of multibyte
+characters.  In contrast, a @dfn{wide string} is a null-terminated
+sequence of @code{wchar_t} objects.  A wide-string variable is usually
+declared to be a pointer of type @code{wchar_t *}, by analogy with
+string variables and @code{char *}.  @xref{Extended Char Intro}.
+
+@cindex null byte
+@cindex null wide character
+By convention, the @dfn{null byte}, @code{'\0'},
+marks the end of a string and the @dfn{null wide character},
+@code{L'\0'}, marks the end of a wide string.  For example, in
+testing to see whether the @code{char *} variable @var{p} points to a
+null byte marking the end of a string, you can write
+@code{!*@var{p}} or @code{*@var{p} == '\0'}.
+
+A null byte is quite different conceptually from a null pointer,
+although both are represented by the integer constant @code{0}.
+
+@cindex string literal
+A @dfn{string literal} appears in C program source as a multibyte
+string between double-quote characters (@samp{"}).  If the
+initial double-quote character is immediately preceded by a capital
+@samp{L} (ell) character (as in @code{L"foo"}), it is a wide string
+literal.  String literals can also contribute to @dfn{string
+concatenation}: @code{"a" "b"} is the same as @code{"ab"}.
+For wide strings one can use either
+@code{L"a" L"b"} or @code{L"a" "b"}.  Modification of string literals is
+not allowed by the GNU C compiler, because literals are placed in
+read-only storage.
+
+Arrays that are declared @code{const} cannot be modified
+either.  It's generally good style to declare non-modifiable string
+pointers to be of type @code{const char *}, since this often allows the
+C compiler to detect accidental modifications as well as providing some
+amount of documentation about what your program intends to do with the
+string.
+
+The amount of memory allocated for a byte array may extend past the null byte
+that marks the end of the string that the array contains.  In this
+document, the term @dfn{allocated size} is always used to refer to the
+total amount of memory allocated for an array, while the term
+@dfn{length} refers to the number of bytes up to (but not including)
+the terminating null byte.  Wide strings are similar, except their
+sizes and lengths count wide characters, not bytes.
+@cindex length of string
+@cindex allocation size of string
+@cindex size of string
+@cindex string length
+@cindex string allocation
+
+A notorious source of program bugs is trying to put more bytes into a
+string than fit in its allocated size.  When writing code that extends
+strings or moves bytes into a pre-allocated array, you should be
+very careful to keep track of the length of the text and make explicit
+checks for overflowing the array.  Many of the library functions
+@emph{do not} do this for you!  Remember also that you need to allocate
+an extra byte to hold the null byte that marks the end of the
+string.
+
+@cindex single-byte string
+@cindex multibyte string
+Originally strings were sequences of bytes where each byte represented a
+single character.  This is still true today if the strings are encoded
+using a single-byte character encoding.  Things are different if the
+strings are encoded using a multibyte encoding (for more information on
+encodings see @ref{Extended Char Intro}).  There is no difference in
+the programming interface for these two kind of strings; the programmer
+has to be aware of this and interpret the byte sequences accordingly.
+
+But since there is no separate interface taking care of these
+differences the byte-based string functions are sometimes hard to use.
+Since the count parameters of these functions specify bytes a call to
+@code{memcpy} could cut a multibyte character in the middle and put an
+incomplete (and therefore unusable) byte sequence in the target buffer.
+
+@cindex wide string
+To avoid these problems later versions of the @w{ISO C} standard
+introduce a second set of functions which are operating on @dfn{wide
+characters} (@pxref{Extended Char Intro}).  These functions don't have
+the problems the single-byte versions have since every wide character is
+a legal, interpretable value.  This does not mean that cutting wide
+strings at arbitrary points is without problems.  It normally
+is for alphabet-based languages (except for non-normalized text) but
+languages based on syllables still have the problem that more than one
+wide character is necessary to complete a logical unit.  This is a
+higher level problem which the @w{C library} functions are not designed
+to solve.  But it is at least good that no invalid byte sequences can be
+created.  Also, the higher level functions can also much more easily operate
+on wide characters than on multibyte characters so that a common strategy
+is to use wide characters internally whenever text is more than simply
+copied.
+
+The remaining of this chapter will discuss the functions for handling
+wide strings in parallel with the discussion of
+strings since there is almost always an exact equivalent
+available.
+
+@node String/Array Conventions
+@section String and Array Conventions
+
+This chapter describes both functions that work on arbitrary arrays or
+blocks of memory, and functions that are specific to strings and wide
+strings.
+
+Functions that operate on arbitrary blocks of memory have names
+beginning with @samp{mem} and @samp{wmem} (such as @code{memcpy} and
+@code{wmemcpy}) and invariably take an argument which specifies the size
+(in bytes and wide characters respectively) of the block of memory to
+operate on.  The array arguments and return values for these functions
+have type @code{void *} or @code{wchar_t}.  As a matter of style, the
+elements of the arrays used with the @samp{mem} functions are referred
+to as ``bytes''.  You can pass any kind of pointer to these functions,
+and the @code{sizeof} operator is useful in computing the value for the
+size argument.  Parameters to the @samp{wmem} functions must be of type
+@code{wchar_t *}.  These functions are not really usable with anything
+but arrays of this type.
+
+In contrast, functions that operate specifically on strings and wide
+strings have names beginning with @samp{str} and @samp{wcs}
+respectively (such as @code{strcpy} and @code{wcscpy}) and look for a
+terminating null byte or null wide character instead of requiring an explicit
+size argument to be passed.  (Some of these functions accept a specified
+maximum length, but they also check for premature termination.)
+The array arguments and return values for these
+functions have type @code{char *} and @code{wchar_t *} respectively, and
+the array elements are referred to as ``bytes'' and ``wide
+characters''.
+
+In many cases, there are both @samp{mem} and @samp{str}/@samp{wcs}
+versions of a function.  The one that is more appropriate to use depends
+on the exact situation.  When your program is manipulating arbitrary
+arrays or blocks of storage, then you should always use the @samp{mem}
+functions.  On the other hand, when you are manipulating
+strings it is usually more convenient to use the @samp{str}/@samp{wcs}
+functions, unless you already know the length of the string in advance.
+The @samp{wmem} functions should be used for wide character arrays with
+known size.
+
+@cindex wint_t
+@cindex parameter promotion
+Some of the memory and string functions take single characters as
+arguments.  Since a value of type @code{char} is automatically promoted
+into a value of type @code{int} when used as a parameter, the functions
+are declared with @code{int} as the type of the parameter in question.
+In case of the wide character functions the situation is similar: the
+parameter type for a single wide character is @code{wint_t} and not
+@code{wchar_t}.  This would for many implementations not be necessary
+since @code{wchar_t} is large enough to not be automatically
+promoted, but since the @w{ISO C} standard does not require such a
+choice of types the @code{wint_t} type is used.
+
+@node String Length
+@section String Length
+
+You can get the length of a string using the @code{strlen} function.
+This function is declared in the header file @file{string.h}.
+@pindex string.h
+
+@comment string.h
+@comment ISO
+@deftypefun size_t strlen (const char *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strlen} function returns the length of the
+string @var{s} in bytes.  (In other words, it returns the offset of the
+terminating null byte within the array.)
+
+For example,
+@smallexample
+strlen ("hello, world")
+    @result{} 12
+@end smallexample
+
+When applied to an array, the @code{strlen} function returns
+the length of the string stored there, not its allocated size.  You can
+get the allocated size of the array that holds a string using
+the @code{sizeof} operator:
+
+@smallexample
+char string[32] = "hello, world";
+sizeof (string)
+    @result{} 32
+strlen (string)
+    @result{} 12
+@end smallexample
+
+But beware, this will not work unless @var{string} is the
+array itself, not a pointer to it.  For example:
+
+@smallexample
+char string[32] = "hello, world";
+char *ptr = string;
+sizeof (string)
+    @result{} 32
+sizeof (ptr)
+    @result{} 4  /* @r{(on a machine with 4 byte pointers)} */
+@end smallexample
+
+This is an easy mistake to make when you are working with functions that
+take string arguments; those arguments are always pointers, not arrays.
+
+It must also be noted that for multibyte encoded strings the return
+value does not have to correspond to the number of characters in the
+string.  To get this value the string can be converted to wide
+characters and @code{wcslen} can be used or something like the following
+code can be used:
+
+@smallexample
+/* @r{The input is in @code{string}.}
+   @r{The length is expected in @code{n}.}  */
+@{
+  mbstate_t t;
+  char *scopy = string;
+  /* In initial state.  */
+  memset (&t, '\0', sizeof (t));
+  /* Determine number of characters.  */
+  n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);
+@}
+@end smallexample
+
+This is cumbersome to do so if the number of characters (as opposed to
+bytes) is needed often it is better to work with wide characters.
+@end deftypefun
+
+The wide character equivalent is declared in @file{wchar.h}.
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcslen (const wchar_t *@var{ws})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcslen} function is the wide character equivalent to
+@code{strlen}.  The return value is the number of wide characters in the
+wide string pointed to by @var{ws} (this is also the offset of
+the terminating null wide character of @var{ws}).
+
+Since there are no multi wide character sequences making up one wide
+character the return value is not only the offset in the array, it is
+also the number of wide characters.
+
+This function was introduced in @w{Amendment 1} to @w{ISO C90}.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun size_t strnlen (const char *@var{s}, size_t @var{maxlen})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+If the array @var{s} of size @var{maxlen} contains a null byte,
+the @code{strnlen} function returns the length of the string @var{s} in
+bytes.  Otherwise it
+returns @var{maxlen}.  Therefore this function is equivalent to
+@code{(strlen (@var{s}) < @var{maxlen} ? strlen (@var{s}) : @var{maxlen})}
+but it
+is more efficient and works even if @var{s} is not null-terminated so
+long as @var{maxlen} does not exceed the size of @var{s}'s array.
+
+@smallexample
+char string[32] = "hello, world";
+strnlen (string, 32)
+    @result{} 12
+strnlen (string, 5)
+    @result{} 5
+@end smallexample
+
+This function is a GNU extension and is declared in @file{string.h}.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun size_t wcsnlen (const wchar_t *@var{ws}, size_t @var{maxlen})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{wcsnlen} is the wide character equivalent to @code{strnlen}.  The
+@var{maxlen} parameter specifies the maximum number of wide characters.
+
+This function is a GNU extension and is declared in @file{wchar.h}.
+@end deftypefun
+
+@node Copying Strings and Arrays
+@section Copying Strings and Arrays
+
+You can use the functions described in this section to copy the contents
+of strings, wide strings, and arrays.  The @samp{str} and @samp{mem}
+functions are declared in @file{string.h} while the @samp{w} functions
+are declared in @file{wchar.h}.
+@pindex string.h
+@pindex wchar.h
+@cindex copying strings and arrays
+@cindex string copy functions
+@cindex array copy functions
+@cindex concatenating strings
+@cindex string concatenation functions
+
+A helpful way to remember the ordering of the arguments to the functions
+in this section is that it corresponds to an assignment expression, with
+the destination array specified to the left of the source array.  Most
+of these functions return the address of the destination array; a few
+return the address of the destination's terminating null, or of just
+past the destination.
+
+Most of these functions do not work properly if the source and
+destination arrays overlap.  For example, if the beginning of the
+destination array overlaps the end of the source array, the original
+contents of that part of the source array may get overwritten before it
+is copied.  Even worse, in the case of the string functions, the null
+byte marking the end of the string may be lost, and the copy
+function might get stuck in a loop trashing all the memory allocated to
+your program.
+
+All functions that have problems copying between overlapping arrays are
+explicitly identified in this manual.  In addition to functions in this
+section, there are a few others like @code{sprintf} (@pxref{Formatted
+Output Functions}) and @code{scanf} (@pxref{Formatted Input
+Functions}).
+
+@comment string.h
+@comment ISO
+@deftypefun {void *} memcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{memcpy} function copies @var{size} bytes from the object
+beginning at @var{from} into the object beginning at @var{to}.  The
+behavior of this function is undefined if the two arrays @var{to} and
+@var{from} overlap; use @code{memmove} instead if overlapping is possible.
+
+The value returned by @code{memcpy} is the value of @var{to}.
+
+Here is an example of how you might use @code{memcpy} to copy the
+contents of an array:
+
+@smallexample
+struct foo *oldarray, *newarray;
+int arraysize;
+@dots{}
+memcpy (new, old, arraysize * sizeof (struct foo));
+@end smallexample
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wmemcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wmemcpy} function copies @var{size} wide characters from the object
+beginning at @var{wfrom} into the object beginning at @var{wto}.  The
+behavior of this function is undefined if the two arrays @var{wto} and
+@var{wfrom} overlap; use @code{wmemmove} instead if overlapping is possible.
+
+The following is a possible implementation of @code{wmemcpy} but there
+are more optimizations possible.
+
+@smallexample
+wchar_t *
+wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
+         size_t size)
+@{
+  return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));
+@}
+@end smallexample
+
+The value returned by @code{wmemcpy} is the value of @var{wto}.
+
+This function was introduced in @w{Amendment 1} to @w{ISO C90}.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {void *} mempcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{mempcpy} function is nearly identical to the @code{memcpy}
+function.  It copies @var{size} bytes from the object beginning at
+@code{from} into the object pointed to by @var{to}.  But instead of
+returning the value of @var{to} it returns a pointer to the byte
+following the last written byte in the object beginning at @var{to}.
+I.e., the value is @code{((void *) ((char *) @var{to} + @var{size}))}.
+
+This function is useful in situations where a number of objects shall be
+copied to consecutive memory positions.
+
+@smallexample
+void *
+combine (void *o1, size_t s1, void *o2, size_t s2)
+@{
+  void *result = malloc (s1 + s2);
+  if (result != NULL)
+    mempcpy (mempcpy (result, o1, s1), o2, s2);
+  return result;
+@}
+@end smallexample
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} wmempcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wmempcpy} function is nearly identical to the @code{wmemcpy}
+function.  It copies @var{size} wide characters from the object
+beginning at @code{wfrom} into the object pointed to by @var{wto}.  But
+instead of returning the value of @var{wto} it returns a pointer to the
+wide character following the last written wide character in the object
+beginning at @var{wto}.  I.e., the value is @code{@var{wto} + @var{size}}.
+
+This function is useful in situations where a number of objects shall be
+copied to consecutive memory positions.
+
+The following is a possible implementation of @code{wmemcpy} but there
+are more optimizations possible.
+
+@smallexample
+wchar_t *
+wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
+          size_t size)
+@{
+  return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
+@}
+@end smallexample
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{memmove} copies the @var{size} bytes at @var{from} into the
+@var{size} bytes at @var{to}, even if those two blocks of space
+overlap.  In the case of overlap, @code{memmove} is careful to copy the
+original values of the bytes in the block at @var{from}, including those
+bytes which also belong to the block at @var{to}.
+
+The value returned by @code{memmove} is the value of @var{to}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wmemmove (wchar_t *@var{wto}, const wchar_t *@var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{wmemmove} copies the @var{size} wide characters at @var{wfrom}
+into the @var{size} wide characters at @var{wto}, even if those two
+blocks of space overlap.  In the case of overlap, @code{memmove} is
+careful to copy the original values of the wide characters in the block
+at @var{wfrom}, including those wide characters which also belong to the
+block at @var{wto}.
+
+The following is a possible implementation of @code{wmemcpy} but there
+are more optimizations possible.
+
+@smallexample
+wchar_t *
+wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
+          size_t size)
+@{
+  return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
+@}
+@end smallexample
+
+The value returned by @code{wmemmove} is the value of @var{wto}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment SVID
+@deftypefun {void *} memccpy (void *restrict @var{to}, const void *restrict @var{from}, int @var{c}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function copies no more than @var{size} bytes from @var{from} to
+@var{to}, stopping if a byte matching @var{c} is found.  The return
+value is a pointer into @var{to} one byte past where @var{c} was copied,
+or a null pointer if no byte matching @var{c} appeared in the first
+@var{size} bytes of @var{from}.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {void *} memset (void *@var{block}, int @var{c}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function copies the value of @var{c} (converted to an
+@code{unsigned char}) into each of the first @var{size} bytes of the
+object beginning at @var{block}.  It returns the value of @var{block}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wmemset (wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function copies the value of @var{wc} into each of the first
+@var{size} wide characters of the object beginning at @var{block}.  It
+returns the value of @var{block}.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strcpy (char *restrict @var{to}, const char *restrict @var{from})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This copies bytes from the string @var{from} (up to and including
+the terminating null byte) into the string @var{to}.  Like
+@code{memcpy}, this function has undefined results if the strings
+overlap.  The return value is the value of @var{to}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcscpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This copies wide characters from the wide string @var{wfrom} (up to and
+including the terminating null wide character) into the string
+@var{wto}.  Like @code{wmemcpy}, this function has undefined results if
+the strings overlap.  The return value is the value of @var{wto}.
+@end deftypefun
+
+@comment SVID
+@deftypefun {char *} strdup (const char *@var{s})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function copies the string @var{s} into a newly
+allocated string.  The string is allocated using @code{malloc}; see
+@ref{Unconstrained Allocation}.  If @code{malloc} cannot allocate space
+for the new string, @code{strdup} returns a null pointer.  Otherwise it
+returns a pointer to the new string.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} wcsdup (const wchar_t *@var{ws})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function copies the wide string @var{ws}
+into a newly allocated string.  The string is allocated using
+@code{malloc}; see @ref{Unconstrained Allocation}.  If @code{malloc}
+cannot allocate space for the new string, @code{wcsdup} returns a null
+pointer.  Otherwise it returns a pointer to the new wide string.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment Unknown origin
+@deftypefun {char *} stpcpy (char *restrict @var{to}, const char *restrict @var{from})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is like @code{strcpy}, except that it returns a pointer to
+the end of the string @var{to} (that is, the address of the terminating
+null byte @code{to + strlen (from)}) rather than the beginning.
+
+For example, this program uses @code{stpcpy} to concatenate @samp{foo}
+and @samp{bar} to produce @samp{foobar}, which it then prints.
+
+@smallexample
+@include stpcpy.c.texi
+@end smallexample
+
+This function is not part of the ISO or POSIX standards, and is not
+customary on Unix systems, but we did not invent it either.  Perhaps it
+comes from MS-DOG.
+
+Its behavior is undefined if the strings overlap.  The function is
+declared in @file{string.h}.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} wcpcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is like @code{wcscpy}, except that it returns a pointer to
+the end of the string @var{wto} (that is, the address of the terminating
+null wide character @code{wto + wcslen (wfrom)}) rather than the beginning.
+
+This function is not part of ISO or POSIX but was found useful while
+developing @theglibc{} itself.
+
+The behavior of @code{wcpcpy} is undefined if the strings overlap.
+
+@code{wcpcpy} is a GNU extension and is declared in @file{wchar.h}.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefn {Macro} {char *} strdupa (const char *@var{s})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This macro is similar to @code{strdup} but allocates the new string
+using @code{alloca} instead of @code{malloc} (@pxref{Variable Size
+Automatic}).  This means of course the returned string has the same
+limitations as any block of memory allocated using @code{alloca}.
+
+For obvious reasons @code{strdupa} is implemented only as a macro;
+you cannot get the address of this function.  Despite this limitation
+it is a useful function.  The following code shows a situation where
+using @code{malloc} would be a lot more expensive.
+
+@smallexample
+@include strdupa.c.texi
+@end smallexample
+
+Please note that calling @code{strtok} using @var{path} directly is
+invalid.  It is also not allowed to call @code{strdupa} in the argument
+list of @code{strtok} since @code{strdupa} uses @code{alloca}
+(@pxref{Variable Size Automatic}) can interfere with the parameter
+passing.
+
+This function is only available if GNU CC is used.
+@end deftypefn
+
+@comment string.h
+@comment BSD
+@deftypefun void bcopy (const void *@var{from}, void *@var{to}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is a partially obsolete alternative for @code{memmove}, derived from
+BSD.  Note that it is not quite equivalent to @code{memmove}, because the
+arguments are not in the same order and there is no return value.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun void bzero (void *@var{block}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is a partially obsolete alternative for @code{memset}, derived from
+BSD.  Note that it is not as general as @code{memset}, because the only
+value it can store is zero.
+@end deftypefun
+
+@node Concatenating Strings
+@section Concatenating Strings
+@pindex string.h
+@pindex wchar.h
+@cindex concatenating strings
+@cindex string concatenation functions
+
+The functions described in this section concatenate the contents of a
+string or wide string to another.  They follow the string-copying
+functions in their conventions.  @xref{Copying Strings and Arrays}.
+@samp{strcat} is declared in the header file @file{string.h} while
+@samp{wcscat} is declared in @file{wchar.h}.
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strcat (char *restrict @var{to}, const char *restrict @var{from})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strcat} function is similar to @code{strcpy}, except that the
+bytes from @var{from} are concatenated or appended to the end of
+@var{to}, instead of overwriting it.  That is, the first byte from
+@var{from} overwrites the null byte marking the end of @var{to}.
+
+An equivalent definition for @code{strcat} would be:
+
+@smallexample
+char *
+strcat (char *restrict to, const char *restrict from)
+@{
+  strcpy (to + strlen (to), from);
+  return to;
+@}
+@end smallexample
+
+This function has undefined results if the strings overlap.
+
+As noted below, this function has significant performance issues.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcscat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcscat} function is similar to @code{wcscpy}, except that the
+wide characters from @var{wfrom} are concatenated or appended to the end of
+@var{wto}, instead of overwriting it.  That is, the first wide character from
+@var{wfrom} overwrites the null wide character marking the end of @var{wto}.
+
+An equivalent definition for @code{wcscat} would be:
+
+@smallexample
+wchar_t *
+wcscat (wchar_t *wto, const wchar_t *wfrom)
+@{
+  wcscpy (wto + wcslen (wto), wfrom);
+  return wto;
+@}
+@end smallexample
+
+This function has undefined results if the strings overlap.
+
+As noted below, this function has significant performance issues.
+@end deftypefun
+
+Programmers using the @code{strcat} or @code{wcscat} function (or the
+@code{strncat} or @code{wcsncat} functions defined in
+a later section, for that matter)
+can easily be recognized as lazy and reckless.  In almost all situations
+the lengths of the participating strings are known (it better should be
+since how can one otherwise ensure the allocated size of the buffer is
+sufficient?)  Or at least, one could know them if one keeps track of the
+results of the various function calls.  But then it is very inefficient
+to use @code{strcat}/@code{wcscat}.  A lot of time is wasted finding the
+end of the destination string so that the actual copying can start.
+This is a common example:
+
+@cindex va_copy
+@smallexample
+/* @r{This function concatenates arbitrarily many strings.  The last}
+   @r{parameter must be @code{NULL}.}  */
+char *
+concat (const char *str, @dots{})
+@{
+  va_list ap, ap2;
+  size_t total = 1;
+  const char *s;
+  char *result;
+
+  va_start (ap, str);
+  va_copy (ap2, ap);
+
+  /* @r{Determine how much space we need.}  */
+  for (s = str; s != NULL; s = va_arg (ap, const char *))
+    total += strlen (s);
+
+  va_end (ap);
+
+  result = (char *) malloc (total);
+  if (result != NULL)
+    @{
+      result[0] = '\0';
+
+      /* @r{Copy the strings.}  */
+      for (s = str; s != NULL; s = va_arg (ap2, const char *))
+        strcat (result, s);
+    @}
+
+  va_end (ap2);
+
+  return result;
+@}
+@end smallexample
+
+This looks quite simple, especially the second loop where the strings
+are actually copied.  But these innocent lines hide a major performance
+penalty.  Just imagine that ten strings of 100 bytes each have to be
+concatenated.  For the second string we search the already stored 100
+bytes for the end of the string so that we can append the next string.
+For all strings in total the comparisons necessary to find the end of
+the intermediate results sums up to 5500!  If we combine the copying
+with the search for the allocation we can write this function more
+efficient:
+
+@smallexample
+char *
+concat (const char *str, @dots{})
+@{
+  va_list ap;
+  size_t allocated = 100;
+  char *result = (char *) malloc (allocated);
+
+  if (result != NULL)
+    @{
+      char *newp;
+      char *wp;
+      const char *s;
+
+      va_start (ap, str);
+
+      wp = result;
+      for (s = str; s != NULL; s = va_arg (ap, const char *))
+        @{
+          size_t len = strlen (s);
+
+          /* @r{Resize the allocated memory if necessary.}  */
+          if (wp + len + 1 > result + allocated)
+            @{
+              allocated = (allocated + len) * 2;
+              newp = (char *) realloc (result, allocated);
+              if (newp == NULL)
+                @{
+                  free (result);
+                  return NULL;
+                @}
+              wp = newp + (wp - result);
+              result = newp;
+            @}
+
+          wp = mempcpy (wp, s, len);
+        @}
+
+      /* @r{Terminate the result string.}  */
+      *wp++ = '\0';
+
+      /* @r{Resize memory to the optimal size.}  */
+      newp = realloc (result, wp - result);
+      if (newp != NULL)
+        result = newp;
+
+      va_end (ap);
+    @}
+
+  return result;
+@}
+@end smallexample
+
+With a bit more knowledge about the input strings one could fine-tune
+the memory allocation.  The difference we are pointing to here is that
+we don't use @code{strcat} anymore.  We always keep track of the length
+of the current intermediate result so we can safe us the search for the
+end of the string and use @code{mempcpy}.  Please note that we also
+don't use @code{stpcpy} which might seem more natural since we handle
+with strings.  But this is not necessary since we already know the
+length of the string and therefore can use the faster memory copying
+function.  The example would work for wide characters the same way.
+
+Whenever a programmer feels the need to use @code{strcat} she or he
+should think twice and look through the program whether the code cannot
+be rewritten to take advantage of already calculated results.  Again: it
+is almost always unnecessary to use @code{strcat}.
+
+@node Truncating Strings
+@section Truncating Strings while Copying
+@cindex truncating strings
+@cindex string truncation
+
+The functions described in this section copy or concatenate the
+possibly-truncated contents of a string or array to another, and
+similarly for wide strings.  They follow the string-copying functions
+in their header conventions.  @xref{Copying Strings and Arrays}.  The
+@samp{str} functions are declared in the header file @file{string.h}
+and the @samp{wc} functions are declared in the file @file{wchar.h}.
+
+@comment string.h
+@deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{strcpy} but always copies exactly
+@var{size} bytes into @var{to}.
+
+If @var{from} does not contain a null byte in its first @var{size}
+bytes, @code{strncpy} copies just the first @var{size} bytes.  In this
+case no null terminator is written into @var{to}.
+
+Otherwise @var{from} must be a string with length less than
+@var{size}.  In this case @code{strncpy} copies all of @var{from},
+followed by enough null bytes to add up to @var{size} bytes in all.
+
+The behavior of @code{strncpy} is undefined if the strings overlap.
+
+This function was designed for now-rarely-used arrays consisting of
+non-null bytes followed by zero or more null bytes.  It needs to set
+all @var{size} bytes of the destination, even when @var{size} is much
+greater than the length of @var{from}.  As noted below, this function
+is generally a poor choice for processing text.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcsncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{wcscpy} but always copies exactly
+@var{size} wide characters into @var{wto}.
+
+If @var{wfrom} does not contain a null wide character in its first
+@var{size} wide characters, then @code{wcsncpy} copies just the first
+@var{size} wide characters.  In this case no null terminator is
+written into @var{wto}.
+
+Otherwise @var{wfrom} must be a wide string with length less than
+@var{size}.  In this case @code{wcsncpy} copies all of @var{wfrom},
+followed by enough null wide characters to add up to @var{size} wide
+characters in all.
+
+The behavior of @code{wcsncpy} is undefined if the strings overlap.
+
+This function is the wide-character counterpart of @code{strncpy} and
+suffers from most of the problems that @code{strncpy} does.  For
+example, as noted below, this function is generally a poor choice for
+processing text.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strndup (const char *@var{s}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+This function is similar to @code{strdup} but always copies at most
+@var{size} bytes into the newly allocated string.
+
+If the length of @var{s} is more than @var{size}, then @code{strndup}
+copies just the first @var{size} bytes and adds a closing null byte.
+Otherwise all bytes are copied and the string is terminated.
+
+This function differs from @code{strncpy} in that it always terminates
+the destination string.
+
+As noted below, this function is generally a poor choice for
+processing text.
+
+@code{strndup} is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefn {Macro} {char *} strndupa (const char *@var{s}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{strndup} but like @code{strdupa} it
+allocates the new string using @code{alloca} @pxref{Variable Size
+Automatic}.  The same advantages and limitations of @code{strdupa} are
+valid for @code{strndupa}, too.
+
+This function is implemented only as a macro, just like @code{strdupa}.
+Just as @code{strdupa} this macro also must not be used inside the
+parameter list in a function call.
+
+As noted below, this function is generally a poor choice for
+processing text.
+
+@code{strndupa} is only available if GNU CC is used.
+@end deftypefn
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} stpncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{stpcpy} but copies always exactly
+@var{size} bytes into @var{to}.
+
+If the length of @var{from} is more than @var{size}, then @code{stpncpy}
+copies just the first @var{size} bytes and returns a pointer to the
+byte directly following the one which was copied last.  Note that in
+this case there is no null terminator written into @var{to}.
+
+If the length of @var{from} is less than @var{size}, then @code{stpncpy}
+copies all of @var{from}, followed by enough null bytes to add up
+to @var{size} bytes in all.  This behavior is rarely useful, but it
+is implemented to be useful in contexts where this behavior of the
+@code{strncpy} is used.  @code{stpncpy} returns a pointer to the
+@emph{first} written null byte.
+
+This function is not part of ISO or POSIX but was found useful while
+developing @theglibc{} itself.
+
+Its behavior is undefined if the strings overlap.  The function is
+declared in @file{string.h}.
+
+As noted below, this function is generally a poor choice for
+processing text.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} wcpncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is similar to @code{wcpcpy} but copies always exactly
+@var{wsize} wide characters into @var{wto}.
+
+If the length of @var{wfrom} is more than @var{size}, then
+@code{wcpncpy} copies just the first @var{size} wide characters and
+returns a pointer to the wide character directly following the last
+non-null wide character which was copied last.  Note that in this case
+there is no null terminator written into @var{wto}.
+
+If the length of @var{wfrom} is less than @var{size}, then @code{wcpncpy}
+copies all of @var{wfrom}, followed by enough null wide characters to add up
+to @var{size} wide characters in all.  This behavior is rarely useful, but it
+is implemented to be useful in contexts where this behavior of the
+@code{wcsncpy} is used.  @code{wcpncpy} returns a pointer to the
+@emph{first} written null wide character.
+
+This function is not part of ISO or POSIX but was found useful while
+developing @theglibc{} itself.
+
+Its behavior is undefined if the strings overlap.
+
+As noted below, this function is generally a poor choice for
+processing text.
+
+@code{wcpncpy} is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strncat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is like @code{strcat} except that not more than @var{size}
+bytes from @var{from} are appended to the end of @var{to}, and
+@var{from} need not be null-terminated.  A single null byte is also
+always appended to @var{to}, so the total
+allocated size of @var{to} must be at least @code{@var{size} + 1} bytes
+longer than its initial length.
+
+The @code{strncat} function could be implemented like this:
+
+@smallexample
+@group
+char *
+strncat (char *to, const char *from, size_t size)
+@{
+  size_t len = strlen (to);
+  memcpy (to + len, from, strnlen (from, size));
+  to[len + strnlen (from, size)] = '\0';
+  return to;
+@}
+@end group
+@end smallexample
+
+The behavior of @code{strncat} is undefined if the strings overlap.
+
+As a companion to @code{strncpy}, @code{strncat} was designed for
+now-rarely-used arrays consisting of non-null bytes followed by zero
+or more null bytes.  As noted below, this function is generally a poor
+choice for processing text.  Also, this function has significant
+performance issues.  @xref{Concatenating Strings}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcsncat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is like @code{wcscat} except that not more than @var{size}
+wide characters from @var{from} are appended to the end of @var{to},
+and @var{from} need not be null-terminated.  A single null wide
+character is also always appended to @var{to}, so the total allocated
+size of @var{to} must be at least @code{wcsnlen (@var{wfrom},
+@var{size}) + 1} wide characters longer than its initial length.
+
+The @code{wcsncat} function could be implemented like this:
+
+@smallexample
+@group
+wchar_t *
+wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,
+         size_t size)
+@{
+  size_t len = wcslen (wto);
+  memcpy (wto + len, wfrom, wcsnlen (wfrom, size) * sizeof (wchar_t));
+  wto[len + wcsnlen (wfrom, size)] = L'\0';
+  return wto;
+@}
+@end group
+@end smallexample
+
+The behavior of @code{wcsncat} is undefined if the strings overlap.
+
+As noted below, this function is generally a poor choice for
+processing text.  Also, this function has significant performance
+issues.  @xref{Concatenating Strings}.
+@end deftypefun
+
+Because these functions can abruptly truncate strings or wide strings,
+they are generally poor choices for processing text.  When coping or
+concatening multibyte strings, they can truncate within a multibyte
+character so that the result is not a valid multibyte string.  When
+combining or concatenating multibyte or wide strings, they may
+truncate the output after a combining character, resulting in a
+corrupted grapheme.  They can cause bugs even when processing
+single-byte strings: for example, when calculating an ASCII-only user
+name, a truncated name can identify the wrong user.
+
+Although some buffer overruns can be prevented by manually replacing
+calls to copying functions with calls to truncation functions, there
+are often easier and safer automatic techniques that cause buffer
+overruns to reliably terminate a program, such as GCC's
+@option{-fcheck-pointer-bounds} and @option{-fsanitize=address}
+options.  @xref{Debugging Options,, Options for Debugging Your Program
+or GCC, gcc.info, Using GCC}.  Because truncation functions can mask
+application bugs that would otherwise be caught by the automatic
+techniques, these functions should be used only when the application's
+underlying logic requires truncation.
+
+@strong{Note:} GNU programs should not truncate strings or wide
+strings to fit arbitrary size limits.  @xref{Semantics, , Writing
+Robust Programs, standards, The GNU Coding Standards}.  Instead of
+string-truncation functions, it is usually better to use dynamic
+memory allocation (@pxref{Unconstrained Allocation}) and functions
+such as @code{strdup} or @code{asprintf} to construct strings.
+
+@node String/Array Comparison
+@section String/Array Comparison
+@cindex comparing strings and arrays
+@cindex string comparison functions
+@cindex array comparison functions
+@cindex predicates on strings
+@cindex predicates on arrays
+
+You can use the functions in this section to perform comparisons on the
+contents of strings and arrays.  As well as checking for equality, these
+functions can also be used as the ordering functions for sorting
+operations.  @xref{Searching and Sorting}, for an example of this.
+
+Unlike most comparison operations in C, the string comparison functions
+return a nonzero value if the strings are @emph{not} equivalent rather
+than if they are.  The sign of the value indicates the relative ordering
+of the first part of the strings that are not equivalent:  a
+negative value indicates that the first string is ``less'' than the
+second, while a positive value indicates that the first string is
+``greater''.
+
+The most common use of these functions is to check only for equality.
+This is canonically done with an expression like @w{@samp{! strcmp (s1, s2)}}.
+
+All of these functions are declared in the header file @file{string.h}.
+@pindex string.h
+
+@comment string.h
+@comment ISO
+@deftypefun int memcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{memcmp} compares the @var{size} bytes of memory
+beginning at @var{a1} against the @var{size} bytes of memory beginning
+at @var{a2}.  The value returned has the same sign as the difference
+between the first differing pair of bytes (interpreted as @code{unsigned
+char} objects, then promoted to @code{int}).
+
+If the contents of the two blocks are equal, @code{memcmp} returns
+@code{0}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wmemcmp (const wchar_t *@var{a1}, const wchar_t *@var{a2}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{wmemcmp} compares the @var{size} wide characters
+beginning at @var{a1} against the @var{size} wide characters beginning
+at @var{a2}.  The value returned is smaller than or larger than zero
+depending on whether the first differing wide character is @var{a1} is
+smaller or larger than the corresponding wide character in @var{a2}.
+
+If the contents of the two blocks are equal, @code{wmemcmp} returns
+@code{0}.
+@end deftypefun
+
+On arbitrary arrays, the @code{memcmp} function is mostly useful for
+testing equality.  It usually isn't meaningful to do byte-wise ordering
+comparisons on arrays of things other than bytes.  For example, a
+byte-wise comparison on the bytes that make up floating-point numbers
+isn't likely to tell you anything about the relationship between the
+values of the floating-point numbers.
+
+@code{wmemcmp} is really only useful to compare arrays of type
+@code{wchar_t} since the function looks at @code{sizeof (wchar_t)} bytes
+at a time and this number of bytes is system dependent.
+
+You should also be careful about using @code{memcmp} to compare objects
+that can contain ``holes'', such as the padding inserted into structure
+objects to enforce alignment requirements, extra space at the end of
+unions, and extra bytes at the ends of strings whose length is less
+than their allocated size.  The contents of these ``holes'' are
+indeterminate and may cause strange behavior when performing byte-wise
+comparisons.  For more predictable results, perform an explicit
+component-wise comparison.
+
+For example, given a structure type definition like:
+
+@smallexample
+struct foo
+  @{
+    unsigned char tag;
+    union
+      @{
+        double f;
+        long i;
+        char *p;
+      @} value;
+  @};
+@end smallexample
+
+@noindent
+you are better off writing a specialized comparison function to compare
+@code{struct foo} objects instead of comparing them with @code{memcmp}.
+
+@comment string.h
+@comment ISO
+@deftypefun int strcmp (const char *@var{s1}, const char *@var{s2})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strcmp} function compares the string @var{s1} against
+@var{s2}, returning a value that has the same sign as the difference
+between the first differing pair of bytes (interpreted as
+@code{unsigned char} objects, then promoted to @code{int}).
+
+If the two strings are equal, @code{strcmp} returns @code{0}.
+
+A consequence of the ordering used by @code{strcmp} is that if @var{s1}
+is an initial substring of @var{s2}, then @var{s1} is considered to be
+``less than'' @var{s2}.
+
+@code{strcmp} does not take sorting conventions of the language the
+strings are written in into account.  To get that one has to use
+@code{strcoll}.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wcscmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The @code{wcscmp} function compares the wide string @var{ws1}
+against @var{ws2}.  The value returned is smaller than or larger than zero
+depending on whether the first differing wide character is @var{ws1} is
+smaller or larger than the corresponding wide character in @var{ws2}.
+
+If the two strings are equal, @code{wcscmp} returns @code{0}.
+
+A consequence of the ordering used by @code{wcscmp} is that if @var{ws1}
+is an initial substring of @var{ws2}, then @var{ws1} is considered to be
+``less than'' @var{ws2}.
+
+@code{wcscmp} does not take sorting conventions of the language the
+strings are written in into account.  To get that one has to use
+@code{wcscoll}.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun int strcasecmp (const char *@var{s1}, const char *@var{s2})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Although this calls tolower multiple times, it's a macro, and
+@c strcasecmp is optimized so that the locale pointer is read only once.
+@c There are some asm implementations too, for which the single-read
+@c from locale TLS pointers also applies.
+This function is like @code{strcmp}, except that differences in case are
+ignored, and its arguments must be multibyte strings.
+How uppercase and lowercase characters are related is
+determined by the currently selected locale.  In the standard @code{"C"}
+locale the characters @"A and @"a do not match but in a locale which
+regards these characters as parts of the alphabet they do match.
+
+@noindent
+@code{strcasecmp} is derived from BSD.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun int wcscasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Since towlower is not a macro, the locale object may be read multiple
+@c times.
+This function is like @code{wcscmp}, except that differences in case are
+ignored.  How uppercase and lowercase characters are related is
+determined by the currently selected locale.  In the standard @code{"C"}
+locale the characters @"A and @"a do not match but in a locale which
+regards these characters as parts of the alphabet they do match.
+
+@noindent
+@code{wcscasecmp} is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is the similar to @code{strcmp}, except that no more than
+@var{size} bytes are compared.  In other words, if the two
+strings are the same in their first @var{size} bytes, the
+return value is zero.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wcsncmp (const wchar_t *@var{ws1}, const wchar_t *@var{ws2}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function is the similar to @code{wcscmp}, except that no more than
+@var{size} wide characters are compared.  In other words, if the two
+strings are the same in their first @var{size} wide characters, the
+return value is zero.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun int strncasecmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is like @code{strncmp}, except that differences in case
+are ignored, and the compared parts of the arguments should consist of
+valid multibyte characters.
+Like @code{strcasecmp}, it is locale dependent how
+uppercase and lowercase characters are related.
+
+@noindent
+@code{strncasecmp} is a GNU extension.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun int wcsncasecmp (const wchar_t *@var{ws1}, const wchar_t *@var{s2}, size_t @var{n})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is like @code{wcsncmp}, except that differences in case
+are ignored.  Like @code{wcscasecmp}, it is locale dependent how
+uppercase and lowercase characters are related.
+
+@noindent
+@code{wcsncasecmp} is a GNU extension.
+@end deftypefun
+
+Here are some examples showing the use of @code{strcmp} and
+@code{strncmp} (equivalent examples can be constructed for the wide
+character functions).  These examples assume the use of the ASCII
+character set.  (If some other character set---say, EBCDIC---is used
+instead, then the glyphs are associated with different numeric codes,
+and the return values and ordering may differ.)
+
+@smallexample
+strcmp ("hello", "hello")
+    @result{} 0    /* @r{These two strings are the same.} */
+strcmp ("hello", "Hello")
+    @result{} 32   /* @r{Comparisons are case-sensitive.} */
+strcmp ("hello", "world")
+    @result{} -15  /* @r{The byte @code{'h'} comes before @code{'w'}.} */
+strcmp ("hello", "hello, world")
+    @result{} -44  /* @r{Comparing a null byte against a comma.} */
+strncmp ("hello", "hello, world", 5)
+    @result{} 0    /* @r{The initial 5 bytes are the same.} */
+strncmp ("hello, world", "hello, stupid world!!!", 5)
+    @result{} 0    /* @r{The initial 5 bytes are the same.} */
+@end smallexample
+
+@comment string.h
+@comment GNU
+@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c Calls isdigit multiple times, locale may change in between.
+The @code{strverscmp} function compares the string @var{s1} against
+@var{s2}, considering them as holding indices/version numbers.  The
+return value follows the same conventions as found in the
+@code{strcmp} function.  In fact, if @var{s1} and @var{s2} contain no
+digits, @code{strverscmp} behaves like @code{strcmp}.
+
+Basically, we compare strings normally (byte by byte), until
+we find a digit in each string - then we enter a special comparison
+mode, where each sequence of digits is taken as a whole.  If we reach the
+end of these two parts without noticing a difference, we return to the
+standard comparison mode.  There are two types of numeric parts:
+"integral" and "fractional" (those  begin with a '0').  The types
+of the numeric parts affect the way we sort them:
+
+@itemize @bullet
+@item
+integral/integral: we compare values as you would expect.
+
+@item
+fractional/integral: the fractional part is less than the integral one.
+Again, no surprise.
+
+@item
+fractional/fractional: the things become a bit more complex.
+If the common prefix contains only leading zeroes, the longest part is less
+than the other one; else the comparison behaves normally.
+@end itemize
+
+@smallexample
+strverscmp ("no digit", "no digit")
+    @result{} 0    /* @r{same behavior as strcmp.} */
+strverscmp ("item#99", "item#100")
+    @result{} <0   /* @r{same prefix, but 99 < 100.} */
+strverscmp ("alpha1", "alpha001")
+    @result{} >0   /* @r{fractional part inferior to integral one.} */
+strverscmp ("part1_f012", "part1_f01")
+    @result{} >0   /* @r{two fractional parts.} */
+strverscmp ("foo.009", "foo.0")
+    @result{} <0   /* @r{idem, but with leading zeroes only.} */
+@end smallexample
+
+This function is especially useful when dealing with filename sorting,
+because filenames frequently hold indices/version numbers.
+
+@code{strverscmp} is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun int bcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is an obsolete alias for @code{memcmp}, derived from BSD.
+@end deftypefun
+
+@node Collation Functions
+@section Collation Functions
+
+@cindex collating strings
+@cindex string collation functions
+
+In some locales, the conventions for lexicographic ordering differ from
+the strict numeric ordering of character codes.  For example, in Spanish
+most glyphs with diacritical marks such as accents are not considered
+distinct letters for the purposes of collation.  On the other hand, the
+two-character sequence @samp{ll} is treated as a single letter that is
+collated immediately after @samp{l}.
+
+You can use the functions @code{strcoll} and @code{strxfrm} (declared in
+the headers file @file{string.h}) and @code{wcscoll} and @code{wcsxfrm}
+(declared in the headers file @file{wchar}) to compare strings using a
+collation ordering appropriate for the current locale.  The locale used
+by these functions in particular can be specified by setting the locale
+for the @code{LC_COLLATE} category; see @ref{Locales}.
+@pindex string.h
+@pindex wchar.h
+
+In the standard C locale, the collation sequence for @code{strcoll} is
+the same as that for @code{strcmp}.  Similarly, @code{wcscoll} and
+@code{wcscmp} are the same in this situation.
+
+Effectively, the way these functions work is by applying a mapping to
+transform the characters in a multibyte string to a byte
+sequence that represents
+the string's position in the collating sequence of the current locale.
+Comparing two such byte sequences in a simple fashion is equivalent to
+comparing the strings with the locale's collating sequence.
+
+The functions @code{strcoll} and @code{wcscoll} perform this translation
+implicitly, in order to do one comparison.  By contrast, @code{strxfrm}
+and @code{wcsxfrm} perform the mapping explicitly.  If you are making
+multiple comparisons using the same string or set of strings, it is
+likely to be more efficient to use @code{strxfrm} or @code{wcsxfrm} to
+transform all the strings just once, and subsequently compare the
+transformed strings with @code{strcmp} or @code{wcscmp}.
+
+@comment string.h
+@comment ISO
+@deftypefun int strcoll (const char *@var{s1}, const char *@var{s2})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls strcoll_l with the current locale, which dereferences only the
+@c LC_COLLATE data pointer.
+The @code{strcoll} function is similar to @code{strcmp} but uses the
+collating sequence of the current locale for collation (the
+@code{LC_COLLATE} locale).  The arguments are multibyte strings.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun int wcscoll (const wchar_t *@var{ws1}, const wchar_t *@var{ws2})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Same as strcoll, but calling wcscoll_l.
+The @code{wcscoll} function is similar to @code{wcscmp} but uses the
+collating sequence of the current locale for collation (the
+@code{LC_COLLATE} locale).
+@end deftypefun
+
+Here is an example of sorting an array of strings, using @code{strcoll}
+to compare them.  The actual sort algorithm is not written here; it
+comes from @code{qsort} (@pxref{Array Sort Function}).  The job of the
+code shown here is to say how to compare the strings while sorting them.
+(Later on in this section, we will show a way to do this more
+efficiently using @code{strxfrm}.)
+
+@smallexample
+/* @r{This is the comparison function used with @code{qsort}.} */
+
+int
+compare_elements (const void *v1, const void *v2)
+@{
+  char * const *p1 = v1;
+  char * const *p2 = v2;
+
+  return strcoll (*p1, *p2);
+@}
+
+/* @r{This is the entry point---the function to sort}
+   @r{strings using the locale's collating sequence.} */
+
+void
+sort_strings (char **array, int nstrings)
+@{
+  /* @r{Sort @code{temp_array} by comparing the strings.} */
+  qsort (array, nstrings,
+         sizeof (char *), compare_elements);
+@}
+@end smallexample
+
+@cindex converting string to collation order
+@comment string.h
+@comment ISO
+@deftypefun size_t strxfrm (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The function @code{strxfrm} transforms the multibyte string
+@var{from} using the
+collation transformation determined by the locale currently selected for
+collation, and stores the transformed string in the array @var{to}.  Up
+to @var{size} bytes (including a terminating null byte) are
+stored.
+
+The behavior is undefined if the strings @var{to} and @var{from}
+overlap; see @ref{Copying Strings and Arrays}.
+
+The return value is the length of the entire transformed string.  This
+value is not affected by the value of @var{size}, but if it is greater
+or equal than @var{size}, it means that the transformed string did not
+entirely fit in the array @var{to}.  In this case, only as much of the
+string as actually fits was stored.  To get the whole transformed
+string, call @code{strxfrm} again with a bigger output array.
+
+The transformed string may be longer than the original string, and it
+may also be shorter.
+
+If @var{size} is zero, no bytes are stored in @var{to}.  In this
+case, @code{strxfrm} simply returns the number of bytes that would
+be the length of the transformed string.  This is useful for determining
+what size the allocated array should be.  It does not matter what
+@var{to} is if @var{size} is zero; @var{to} may even be a null pointer.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcsxfrm (wchar_t *restrict @var{wto}, const wchar_t *@var{wfrom}, size_t @var{size})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The function @code{wcsxfrm} transforms wide string @var{wfrom}
+using the collation transformation determined by the locale currently
+selected for collation, and stores the transformed string in the array
+@var{wto}.  Up to @var{size} wide characters (including a terminating null
+wide character) are stored.
+
+The behavior is undefined if the strings @var{wto} and @var{wfrom}
+overlap; see @ref{Copying Strings and Arrays}.
+
+The return value is the length of the entire transformed wide
+string.  This value is not affected by the value of @var{size}, but if
+it is greater or equal than @var{size}, it means that the transformed
+wide string did not entirely fit in the array @var{wto}.  In
+this case, only as much of the wide string as actually fits
+was stored.  To get the whole transformed wide string, call
+@code{wcsxfrm} again with a bigger output array.
+
+The transformed wide string may be longer than the original
+wide string, and it may also be shorter.
+
+If @var{size} is zero, no wide characters are stored in @var{to}.  In this
+case, @code{wcsxfrm} simply returns the number of wide characters that
+would be the length of the transformed wide string.  This is
+useful for determining what size the allocated array should be (remember
+to multiply with @code{sizeof (wchar_t)}).  It does not matter what
+@var{wto} is if @var{size} is zero; @var{wto} may even be a null pointer.
+@end deftypefun
+
+Here is an example of how you can use @code{strxfrm} when
+you plan to do many comparisons.  It does the same thing as the previous
+example, but much faster, because it has to transform each string only
+once, no matter how many times it is compared with other strings.  Even
+the time needed to allocate and free storage is much less than the time
+we save, when there are many strings.
+
+@smallexample
+struct sorter @{ char *input; char *transformed; @};
+
+/* @r{This is the comparison function used with @code{qsort}}
+   @r{to sort an array of @code{struct sorter}.} */
+
+int
+compare_elements (const void *v1, const void *v2)
+@{
+  const struct sorter *p1 = v1;
+  const struct sorter *p2 = v2;
+
+  return strcmp (p1->transformed, p2->transformed);
+@}
+
+/* @r{This is the entry point---the function to sort}
+   @r{strings using the locale's collating sequence.} */
+
+void
+sort_strings_fast (char **array, int nstrings)
+@{
+  struct sorter temp_array[nstrings];
+  int i;
+
+  /* @r{Set up @code{temp_array}.  Each element contains}
+     @r{one input string and its transformed string.} */
+  for (i = 0; i < nstrings; i++)
+    @{
+      size_t length = strlen (array[i]) * 2;
+      char *transformed;
+      size_t transformed_length;
+
+      temp_array[i].input = array[i];
+
+      /* @r{First try a buffer perhaps big enough.}  */
+      transformed = (char *) xmalloc (length);
+
+      /* @r{Transform @code{array[i]}.}  */
+      transformed_length = strxfrm (transformed, array[i], length);
+
+      /* @r{If the buffer was not large enough, resize it}
+         @r{and try again.}  */
+      if (transformed_length >= length)
+        @{
+          /* @r{Allocate the needed space. +1 for terminating}
+             @r{@code{'\0'} byte.}  */
+          transformed = (char *) xrealloc (transformed,
+                                           transformed_length + 1);
+
+          /* @r{The return value is not interesting because we know}
+             @r{how long the transformed string is.}  */
+          (void) strxfrm (transformed, array[i],
+                          transformed_length + 1);
+        @}
+
+      temp_array[i].transformed = transformed;
+    @}
+
+  /* @r{Sort @code{temp_array} by comparing transformed strings.} */
+  qsort (temp_array, nstrings,
+         sizeof (struct sorter), compare_elements);
+
+  /* @r{Put the elements back in the permanent array}
+     @r{in their sorted order.} */
+  for (i = 0; i < nstrings; i++)
+    array[i] = temp_array[i].input;
+
+  /* @r{Free the strings we allocated.} */
+  for (i = 0; i < nstrings; i++)
+    free (temp_array[i].transformed);
+@}
+@end smallexample
+
+The interesting part of this code for the wide character version would
+look like this:
+
+@smallexample
+void
+sort_strings_fast (wchar_t **array, int nstrings)
+@{
+  @dots{}
+      /* @r{Transform @code{array[i]}.}  */
+      transformed_length = wcsxfrm (transformed, array[i], length);
+
+      /* @r{If the buffer was not large enough, resize it}
+         @r{and try again.}  */
+      if (transformed_length >= length)
+        @{
+          /* @r{Allocate the needed space. +1 for terminating}
+             @r{@code{L'\0'} wide character.}  */
+          transformed = (wchar_t *) xrealloc (transformed,
+                                              (transformed_length + 1)
+                                              * sizeof (wchar_t));
+
+          /* @r{The return value is not interesting because we know}
+             @r{how long the transformed string is.}  */
+          (void) wcsxfrm (transformed, array[i],
+                          transformed_length + 1);
+        @}
+  @dots{}
+@end smallexample
+
+@noindent
+Note the additional multiplication with @code{sizeof (wchar_t)} in the
+@code{realloc} call.
+
+@strong{Compatibility Note:} The string collation functions are a new
+feature of @w{ISO C90}.  Older C dialects have no equivalent feature.
+The wide character versions were introduced in @w{Amendment 1} to @w{ISO
+C90}.
+
+@node Search Functions
+@section Search Functions
+
+This section describes library functions which perform various kinds
+of searching operations on strings and arrays.  These functions are
+declared in the header file @file{string.h}.
+@pindex string.h
+@cindex search functions (for strings)
+@cindex string search functions
+
+@comment string.h
+@comment ISO
+@deftypefun {void *} memchr (const void *@var{block}, int @var{c}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function finds the first occurrence of the byte @var{c} (converted
+to an @code{unsigned char}) in the initial @var{size} bytes of the
+object beginning at @var{block}.  The return value is a pointer to the
+located byte, or a null pointer if no match was found.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wmemchr (const wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function finds the first occurrence of the wide character @var{wc}
+in the initial @var{size} wide characters of the object beginning at
+@var{block}.  The return value is a pointer to the located wide
+character, or a null pointer if no match was found.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {void *} rawmemchr (const void *@var{block}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Often the @code{memchr} function is used with the knowledge that the
+byte @var{c} is available in the memory block specified by the
+parameters.  But this means that the @var{size} parameter is not really
+needed and that the tests performed with it at runtime (to check whether
+the end of the block is reached) are not needed.
+
+The @code{rawmemchr} function exists for just this situation which is
+surprisingly frequent.  The interface is similar to @code{memchr} except
+that the @var{size} parameter is missing.  The function will look beyond
+the end of the block pointed to by @var{block} in case the programmer
+made an error in assuming that the byte @var{c} is present in the block.
+In this case the result is unspecified.  Otherwise the return value is a
+pointer to the located byte.
+
+This function is of special interest when looking for the end of a
+string.  Since all strings are terminated by a null byte a call like
+
+@smallexample
+   rawmemchr (str, '\0')
+@end smallexample
+
+@noindent
+will never go beyond the end of the string.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {void *} memrchr (const void *@var{block}, int @var{c}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{memrchr} is like @code{memchr}, except that it searches
+backwards from the end of the block defined by @var{block} and @var{size}
+(instead of forwards from the front).
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strchr (const char *@var{string}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strchr} function finds the first occurrence of the byte
+@var{c} (converted to a @code{char}) in the string
+beginning at @var{string}.  The return value is a pointer to the located
+byte, or a null pointer if no match was found.
+
+For example,
+@smallexample
+strchr ("hello, world", 'l')
+    @result{} "llo, world"
+strchr ("hello, world", '?')
+    @result{} NULL
+@end smallexample
+
+The terminating null byte is considered to be part of the string,
+so you can use this function get a pointer to the end of a string by
+specifying zero as the value of the @var{c} argument.
+
+When @code{strchr} returns a null pointer, it does not let you know
+the position of the terminating null byte it has found.  If you
+need that information, it is better (but less portable) to use
+@code{strchrnul} than to search for it a second time.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcschr (const wchar_t *@var{wstring}, int @var{wc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcschr} function finds the first occurrence of the wide
+character @var{wc} in the wide string
+beginning at @var{wstring}.  The return value is a pointer to the
+located wide character, or a null pointer if no match was found.
+
+The terminating null wide character is considered to be part of the wide
+string, so you can use this function get a pointer to the end
+of a wide string by specifying a null wide character as the
+value of the @var{wc} argument.  It would be better (but less portable)
+to use @code{wcschrnul} in this case, though.
+@end deftypefun
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strchrnul (const char *@var{string}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{strchrnul} is the same as @code{strchr} except that if it does
+not find the byte, it returns a pointer to string's terminating
+null byte rather than a null pointer.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment wchar.h
+@comment GNU
+@deftypefun {wchar_t *} wcschrnul (const wchar_t *@var{wstring}, wchar_t @var{wc})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{wcschrnul} is the same as @code{wcschr} except that if it does not
+find the wide character, it returns a pointer to the wide string's
+terminating null wide character rather than a null pointer.
+
+This function is a GNU extension.
+@end deftypefun
+
+One useful, but unusual, use of the @code{strchr}
+function is when one wants to have a pointer pointing to the null byte
+terminating a string.  This is often written in this way:
+
+@smallexample
+  s += strlen (s);
+@end smallexample
+
+@noindent
+This is almost optimal but the addition operation duplicated a bit of
+the work already done in the @code{strlen} function.  A better solution
+is this:
+
+@smallexample
+  s = strchr (s, '\0');
+@end smallexample
+
+There is no restriction on the second parameter of @code{strchr} so it
+could very well also be zero.  Those readers thinking very
+hard about this might now point out that the @code{strchr} function is
+more expensive than the @code{strlen} function since we have two abort
+criteria.  This is right.  But in @theglibc{} the implementation of
+@code{strchr} is optimized in a special way so that @code{strchr}
+actually is faster.
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strrchr (const char *@var{string}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{strrchr} is like @code{strchr}, except that it searches
+backwards from the end of the string @var{string} (instead of forwards
+from the front).
+
+For example,
+@smallexample
+strrchr ("hello, world", 'l')
+    @result{} "ld"
+@end smallexample
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcsrchr (const wchar_t *@var{wstring}, wchar_t @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{wcsrchr} is like @code{wcschr}, except that it searches
+backwards from the end of the string @var{wstring} (instead of forwards
+from the front).
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{strchr}, except that it searches @var{haystack} for a
+substring @var{needle} rather than just a single byte.  It
+returns a pointer into the string @var{haystack} that is the first
+byte of the substring, or a null pointer if no match was found.  If
+@var{needle} is an empty string, the function returns @var{haystack}.
+
+For example,
+@smallexample
+strstr ("hello, world", "l")
+    @result{} "llo, world"
+strstr ("hello, world", "wo")
+    @result{} "world"
+@end smallexample
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcsstr (const wchar_t *@var{haystack}, const wchar_t *@var{needle})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{wcschr}, except that it searches @var{haystack} for a
+substring @var{needle} rather than just a single wide character.  It
+returns a pointer into the string @var{haystack} that is the first wide
+character of the substring, or a null pointer if no match was found.  If
+@var{needle} is an empty string, the function returns @var{haystack}.
+@end deftypefun
+
+@comment wchar.h
+@comment XPG
+@deftypefun {wchar_t *} wcswcs (const wchar_t *@var{haystack}, const wchar_t *@var{needle})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{wcswcs} is a deprecated alias for @code{wcsstr}.  This is the
+name originally used in the X/Open Portability Guide before the
+@w{Amendment 1} to @w{ISO C90} was published.
+@end deftypefun
+
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strcasestr (const char *@var{haystack}, const char *@var{needle})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c There may be multiple calls of strncasecmp, each accessing the locale
+@c object independently.
+This is like @code{strstr}, except that it ignores case in searching for
+the substring.   Like @code{strcasecmp}, it is locale dependent how
+uppercase and lowercase characters are related, and arguments are
+multibyte strings.
+
+
+For example,
+@smallexample
+strcasestr ("hello, world", "L")
+    @result{} "llo, world"
+strcasestr ("hello, World", "wo")
+    @result{} "World"
+@end smallexample
+@end deftypefun
+
+
+@comment string.h
+@comment GNU
+@deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is like @code{strstr}, but @var{needle} and @var{haystack} are byte
+arrays rather than strings.  @var{needle-len} is the
+length of @var{needle} and @var{haystack-len} is the length of
+@var{haystack}.@refill
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strspn} (``string span'') function returns the length of the
+initial substring of @var{string} that consists entirely of bytes that
+are members of the set specified by the string @var{skipset}.  The order
+of the bytes in @var{skipset} is not important.
+
+For example,
+@smallexample
+strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
+    @result{} 5
+@end smallexample
+
+In a multibyte string, characters consisting of
+more than one byte are not treated as single entities.  Each byte is treated
+separately.  The function is not locale-dependent.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcsspn (const wchar_t *@var{wstring}, const wchar_t *@var{skipset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcsspn} (``wide character string span'') function returns the
+length of the initial substring of @var{wstring} that consists entirely
+of wide characters that are members of the set specified by the string
+@var{skipset}.  The order of the wide characters in @var{skipset} is not
+important.
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun size_t strcspn (const char *@var{string}, const char *@var{stopset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strcspn} (``string complement span'') function returns the length
+of the initial substring of @var{string} that consists entirely of bytes
+that are @emph{not} members of the set specified by the string @var{stopset}.
+(In other words, it returns the offset of the first byte in @var{string}
+that is a member of the set @var{stopset}.)
+
+For example,
+@smallexample
+strcspn ("hello, world", " \t\n,.;!?")
+    @result{} 5
+@end smallexample
+
+In a multibyte string, characters consisting of
+more than one byte are not treated as a single entities.  Each byte is treated
+separately.  The function is not locale-dependent.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun size_t wcscspn (const wchar_t *@var{wstring}, const wchar_t *@var{stopset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcscspn} (``wide character string complement span'') function
+returns the length of the initial substring of @var{wstring} that
+consists entirely of wide characters that are @emph{not} members of the
+set specified by the string @var{stopset}.  (In other words, it returns
+the offset of the first wide character in @var{string} that is a member of
+the set @var{stopset}.)
+@end deftypefun
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strpbrk (const char *@var{string}, const char *@var{stopset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{strpbrk} (``string pointer break'') function is related to
+@code{strcspn}, except that it returns a pointer to the first byte
+in @var{string} that is a member of the set @var{stopset} instead of the
+length of the initial substring.  It returns a null pointer if no such
+byte from @var{stopset} is found.
+
+@c @group  Invalid outside the example.
+For example,
+
+@smallexample
+strpbrk ("hello, world", " \t\n,.;!?")
+    @result{} ", world"
+@end smallexample
+@c @end group
+
+In a multibyte string, characters consisting of
+more than one byte are not treated as single entities.  Each byte is treated
+separately.  The function is not locale-dependent.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcspbrk (const wchar_t *@var{wstring}, const wchar_t *@var{stopset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{wcspbrk} (``wide character string pointer break'') function is
+related to @code{wcscspn}, except that it returns a pointer to the first
+wide character in @var{wstring} that is a member of the set
+@var{stopset} instead of the length of the initial substring.  It
+returns a null pointer if no such wide character from @var{stopset} is found.
+@end deftypefun
+
+
+@subsection Compatibility String Search Functions
+
+@comment string.h
+@comment BSD
+@deftypefun {char *} index (const char *@var{string}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{index} is another name for @code{strchr}; they are exactly the same.
+New code should always use @code{strchr} since this name is defined in
+@w{ISO C} while @code{index} is a BSD invention which never was available
+on @w{System V} derived systems.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun {char *} rindex (const char *@var{string}, int @var{c})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{rindex} is another name for @code{strrchr}; they are exactly the same.
+New code should always use @code{strrchr} since this name is defined in
+@w{ISO C} while @code{rindex} is a BSD invention which never was available
+on @w{System V} derived systems.
+@end deftypefun
+
+@node Finding Tokens in a String
+@section Finding Tokens in a String
+
+@cindex tokenizing strings
+@cindex breaking a string into tokens
+@cindex parsing tokens from a string
+It's fairly common for programs to have a need to do some simple kinds
+of lexical analysis and parsing, such as splitting a command string up
+into tokens.  You can do this with the @code{strtok} function, declared
+in the header file @file{string.h}.
+@pindex string.h
+
+@comment string.h
+@comment ISO
+@deftypefun {char *} strtok (char *restrict @var{newstring}, const char *restrict @var{delimiters})
+@safety{@prelim{}@mtunsafe{@mtasurace{:strtok}}@asunsafe{}@acsafe{}}
+A string can be split into tokens by making a series of calls to the
+function @code{strtok}.
+
+The string to be split up is passed as the @var{newstring} argument on
+the first call only.  The @code{strtok} function uses this to set up
+some internal state information.  Subsequent calls to get additional
+tokens from the same string are indicated by passing a null pointer as
+the @var{newstring} argument.  Calling @code{strtok} with another
+non-null @var{newstring} argument reinitializes the state information.
+It is guaranteed that no other library function ever calls @code{strtok}
+behind your back (which would mess up this internal state information).
+
+The @var{delimiters} argument is a string that specifies a set of delimiters
+that may surround the token being extracted.  All the initial bytes
+that are members of this set are discarded.  The first byte that is
+@emph{not} a member of this set of delimiters marks the beginning of the
+next token.  The end of the token is found by looking for the next
+byte that is a member of the delimiter set.  This byte in the
+original string @var{newstring} is overwritten by a null byte, and the
+pointer to the beginning of the token in @var{newstring} is returned.
+
+On the next call to @code{strtok}, the searching begins at the next
+byte beyond the one that marked the end of the previous token.
+Note that the set of delimiters @var{delimiters} do not have to be the
+same on every call in a series of calls to @code{strtok}.
+
+If the end of the string @var{newstring} is reached, or if the remainder of
+string consists only of delimiter bytes, @code{strtok} returns
+a null pointer.
+
+In a multibyte string, characters consisting of
+more than one byte are not treated as single entities.  Each byte is treated
+separately.  The function is not locale-dependent.
+@end deftypefun
+
+@comment wchar.h
+@comment ISO
+@deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const wchar_t *@var{delimiters}, wchar_t **@var{save_ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+A string can be split into tokens by making a series of calls to the
+function @code{wcstok}.
+
+The string to be split up is passed as the @var{newstring} argument on
+the first call only.  The @code{wcstok} function uses this to set up
+some internal state information.  Subsequent calls to get additional
+tokens from the same wide string are indicated by passing a
+null pointer as the @var{newstring} argument, which causes the pointer
+previously stored in @var{save_ptr} to be used instead.
+
+The @var{delimiters} argument is a wide string that specifies
+a set of delimiters that may surround the token being extracted.  All
+the initial wide characters that are members of this set are discarded.
+The first wide character that is @emph{not} a member of this set of
+delimiters marks the beginning of the next token.  The end of the token
+is found by looking for the next wide character that is a member of the
+delimiter set.  This wide character in the original wide
+string @var{newstring} is overwritten by a null wide character, the
+pointer past the overwritten wide character is saved in @var{save_ptr},
+and the pointer to the beginning of the token in @var{newstring} is
+returned.
+
+On the next call to @code{wcstok}, the searching begins at the next
+wide character beyond the one that marked the end of the previous token.
+Note that the set of delimiters @var{delimiters} do not have to be the
+same on every call in a series of calls to @code{wcstok}.
+
+If the end of the wide string @var{newstring} is reached, or
+if the remainder of string consists only of delimiter wide characters,
+@code{wcstok} returns a null pointer.
+@end deftypefun
+
+@strong{Warning:} Since @code{strtok} and @code{wcstok} alter the string
+they is parsing, you should always copy the string to a temporary buffer
+before parsing it with @code{strtok}/@code{wcstok} (@pxref{Copying Strings
+and Arrays}).  If you allow @code{strtok} or @code{wcstok} to modify
+a string that came from another part of your program, you are asking for
+trouble; that string might be used for other purposes after
+@code{strtok} or @code{wcstok} has modified it, and it would not have
+the expected value.
+
+The string that you are operating on might even be a constant.  Then
+when @code{strtok} or @code{wcstok} tries to modify it, your program
+will get a fatal signal for writing in read-only memory.  @xref{Program
+Error Signals}.  Even if the operation of @code{strtok} or @code{wcstok}
+would not require a modification of the string (e.g., if there is
+exactly one token) the string can (and in the @glibcadj{} case will) be
+modified.
+
+This is a special case of a general principle: if a part of a program
+does not have as its purpose the modification of a certain data
+structure, then it is error-prone to modify the data structure
+temporarily.
+
+The function @code{strtok} is not reentrant, whereas @code{wcstok} is.
+@xref{Nonreentrancy}, for a discussion of where and why reentrancy is
+important.
+
+Here is a simple example showing the use of @code{strtok}.
+
+@comment Yes, this example has been tested.
+@smallexample
+#include <string.h>
+#include <stddef.h>
+
+@dots{}
+
+const char string[] = "words separated by spaces -- and, punctuation!";
+const char delimiters[] = " .,;:!-";
+char *token, *cp;
+
+@dots{}
+
+cp = strdupa (string);                /* Make writable copy.  */
+token = strtok (cp, delimiters);      /* token => "words" */
+token = strtok (NULL, delimiters);    /* token => "separated" */
+token = strtok (NULL, delimiters);    /* token => "by" */
+token = strtok (NULL, delimiters);    /* token => "spaces" */
+token = strtok (NULL, delimiters);    /* token => "and" */
+token = strtok (NULL, delimiters);    /* token => "punctuation" */
+token = strtok (NULL, delimiters);    /* token => NULL */
+@end smallexample
+
+@Theglibc{} contains two more functions for tokenizing a string
+which overcome the limitation of non-reentrancy.  They are not
+available available for wide strings.
+
+@comment string.h
+@comment POSIX
+@deftypefun {char *} strtok_r (char *@var{newstring}, const char *@var{delimiters}, char **@var{save_ptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Just like @code{strtok}, this function splits the string into several
+tokens which can be accessed by successive calls to @code{strtok_r}.
+The difference is that, as in @code{wcstok}, the information about the
+next token is stored in the space pointed to by the third argument,
+@var{save_ptr}, which is a pointer to a string pointer.  Calling
+@code{strtok_r} with a null pointer for @var{newstring} and leaving
+@var{save_ptr} between the calls unchanged does the job without
+hindering reentrancy.
+
+This function is defined in POSIX.1 and can be found on many systems
+which support multi-threading.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun {char *} strsep (char **@var{string_ptr}, const char *@var{delimiter})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function has a similar functionality as @code{strtok_r} with the
+@var{newstring} argument replaced by the @var{save_ptr} argument.  The
+initialization of the moving pointer has to be done by the user.
+Successive calls to @code{strsep} move the pointer along the tokens
+separated by @var{delimiter}, returning the address of the next token
+and updating @var{string_ptr} to point to the beginning of the next
+token.
+
+One difference between @code{strsep} and @code{strtok_r} is that if the
+input string contains more than one byte from @var{delimiter} in a
+row @code{strsep} returns an empty string for each pair of bytes
+from @var{delimiter}.  This means that a program normally should test
+for @code{strsep} returning an empty string before processing it.
+
+This function was introduced in 4.3BSD and therefore is widely available.
+@end deftypefun
+
+Here is how the above example looks like when @code{strsep} is used.
+
+@comment Yes, this example has been tested.
+@smallexample
+#include <string.h>
+#include <stddef.h>
+
+@dots{}
+
+const char string[] = "words separated by spaces -- and, punctuation!";
+const char delimiters[] = " .,;:!-";
+char *running;
+char *token;
+
+@dots{}
+
+running = strdupa (string);
+token = strsep (&running, delimiters);    /* token => "words" */
+token = strsep (&running, delimiters);    /* token => "separated" */
+token = strsep (&running, delimiters);    /* token => "by" */
+token = strsep (&running, delimiters);    /* token => "spaces" */
+token = strsep (&running, delimiters);    /* token => "" */
+token = strsep (&running, delimiters);    /* token => "" */
+token = strsep (&running, delimiters);    /* token => "" */
+token = strsep (&running, delimiters);    /* token => "and" */
+token = strsep (&running, delimiters);    /* token => "" */
+token = strsep (&running, delimiters);    /* token => "punctuation" */
+token = strsep (&running, delimiters);    /* token => "" */
+token = strsep (&running, delimiters);    /* token => NULL */
+@end smallexample
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} basename (const char *@var{filename})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The GNU version of the @code{basename} function returns the last
+component of the path in @var{filename}.  This function is the preferred
+usage, since it does not modify the argument, @var{filename}, and
+respects trailing slashes.  The prototype for @code{basename} can be
+found in @file{string.h}.  Note, this function is overriden by the XPG
+version, if @file{libgen.h} is included.
+
+Example of using GNU @code{basename}:
+
+@smallexample
+#include <string.h>
+
+int
+main (int argc, char *argv[])
+@{
+  char *prog = basename (argv[0]);
+
+  if (argc < 2)
+    @{
+      fprintf (stderr, "Usage %s <arg>\n", prog);
+      exit (1);
+    @}
+
+  @dots{}
+@}
+@end smallexample
+
+@strong{Portability Note:} This function may produce different results
+on different systems.
+
+@end deftypefun
+
+@comment libgen.h
+@comment XPG
+@deftypefun {char *} basename (char *@var{path})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This is the standard XPG defined @code{basename}.  It is similar in
+spirit to the GNU version, but may modify the @var{path} by removing
+trailing '/' bytes.  If the @var{path} is made up entirely of '/'
+bytes, then "/" will be returned.  Also, if @var{path} is
+@code{NULL} or an empty string, then "." is returned.  The prototype for
+the XPG version can be found in @file{libgen.h}.
+
+Example of using XPG @code{basename}:
+
+@smallexample
+#include <libgen.h>
+
+int
+main (int argc, char *argv[])
+@{
+  char *prog;
+  char *path = strdupa (argv[0]);
+
+  prog = basename (path);
+
+  if (argc < 2)
+    @{
+      fprintf (stderr, "Usage %s <arg>\n", prog);
+      exit (1);
+    @}
+
+  @dots{}
+
+@}
+@end smallexample
+@end deftypefun
+
+@comment libgen.h
+@comment XPG
+@deftypefun {char *} dirname (char *@var{path})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{dirname} function is the compliment to the XPG version of
+@code{basename}.  It returns the parent directory of the file specified
+by @var{path}.  If @var{path} is @code{NULL}, an empty string, or
+contains no '/' bytes, then "." is returned.  The prototype for this
+function can be found in @file{libgen.h}.
+@end deftypefun
+
+@node strfry
+@section strfry
+
+The function below addresses the perennial programming quandary: ``How do
+I take good data in string form and painlessly turn it into garbage?''
+This is actually a fairly simple task for C programmers who do not use
+@theglibc{} string functions, but for programs based on @theglibc{},
+the @code{strfry} function is the preferred method for
+destroying string data.
+
+The prototype for this function is in @file{string.h}.
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strfry (char *@var{string})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Calls initstate_r, time, getpid, strlen, and random_r.
+
+@code{strfry} creates a pseudorandom anagram of a string, replacing the
+input with the anagram in place.  For each position in the string,
+@code{strfry} swaps it with a position in the string selected at random
+(from a uniform distribution).  The two positions may be the same.
+
+The return value of @code{strfry} is always @var{string}.
+
+@strong{Portability Note:}  This function is unique to @theglibc{}.
+
+@end deftypefun
+
+
+@node Trivial Encryption
+@section Trivial Encryption
+@cindex encryption
+
+
+The @code{memfrob} function converts an array of data to something
+unrecognizable and back again.  It is not encryption in its usual sense
+since it is easy for someone to convert the encrypted data back to clear
+text.  The transformation is analogous to Usenet's ``Rot13'' encryption
+method for obscuring offensive jokes from sensitive eyes and such.
+Unlike Rot13, @code{memfrob} works on arbitrary binary data, not just
+text.
+@cindex Rot13
+
+For true encryption, @xref{Cryptographic Functions}.
+
+This function is declared in @file{string.h}.
+@pindex string.h
+
+@comment string.h
+@comment GNU
+@deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{memfrob} transforms (frobnicates) each byte of the data structure
+at @var{mem}, which is @var{length} bytes long, by bitwise exclusive
+oring it with binary 00101010.  It does the transformation in place and
+its return value is always @var{mem}.
+
+Note that @code{memfrob} a second time on the same data structure
+returns it to its original state.
+
+This is a good function for hiding information from someone who doesn't
+want to see it or doesn't want to see it very much.  To really prevent
+people from retrieving the information, use stronger encryption such as
+that described in @xref{Cryptographic Functions}.
+
+@strong{Portability Note:}  This function is unique to @theglibc{}.
+
+@end deftypefun
+
+@node Encode Binary Data
+@section Encode Binary Data
+
+To store or transfer binary data in environments which only support text
+one has to encode the binary data by mapping the input bytes to
+bytes in the range allowed for storing or transferring.  SVID
+systems (and nowadays XPG compliant systems) provide minimal support for
+this task.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {char *} l64a (long int @var{n})
+@safety{@prelim{}@mtunsafe{@mtasurace{:l64a}}@asunsafe{}@acsafe{}}
+This function encodes a 32-bit input value using bytes from the
+basic character set.  It returns a pointer to a 7 byte buffer which
+contains an encoded version of @var{n}.  To encode a series of bytes the
+user must copy the returned string to a destination buffer.  It returns
+the empty string if @var{n} is zero, which is somewhat bizarre but
+mandated by the standard.@*
+@strong{Warning:} Since a static buffer is used this function should not
+be used in multi-threaded programs.  There is no thread-safe alternative
+to this function in the C library.@*
+@strong{Compatibility Note:} The XPG standard states that the return
+value of @code{l64a} is undefined if @var{n} is negative.  In the GNU
+implementation, @code{l64a} treats its argument as unsigned, so it will
+return a sensible encoding for any nonzero @var{n}; however, portable
+programs should not rely on this.
+
+To encode a large buffer @code{l64a} must be called in a loop, once for
+each 32-bit word of the buffer.  For example, one could do something
+like this:
+
+@smallexample
+char *
+encode (const void *buf, size_t len)
+@{
+  /* @r{We know in advance how long the buffer has to be.} */
+  unsigned char *in = (unsigned char *) buf;
+  char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);
+  char *cp = out, *p;
+
+  /* @r{Encode the length.} */
+  /* @r{Using `htonl' is necessary so that the data can be}
+     @r{decoded even on machines with different byte order.}
+     @r{`l64a' can return a string shorter than 6 bytes, so }
+     @r{we pad it with encoding of 0 (}'.'@r{) at the end by }
+     @r{hand.} */
+
+  p = stpcpy (cp, l64a (htonl (len)));
+  cp = mempcpy (p, "......", 6 - (p - cp));
+
+  while (len > 3)
+    @{
+      unsigned long int n = *in++;
+      n = (n << 8) | *in++;
+      n = (n << 8) | *in++;
+      n = (n << 8) | *in++;
+      len -= 4;
+      p = stpcpy (cp, l64a (htonl (n)));
+      cp = mempcpy (p, "......", 6 - (p - cp));
+    @}
+  if (len > 0)
+    @{
+      unsigned long int n = *in++;
+      if (--len > 0)
+        @{
+          n = (n << 8) | *in++;
+          if (--len > 0)
+            n = (n << 8) | *in;
+        @}
+      cp = stpcpy (cp, l64a (htonl (n)));
+    @}
+  *cp = '\0';
+  return out;
+@}
+@end smallexample
+
+It is strange that the library does not provide the complete
+functionality needed but so be it.
+
+@end deftypefun
+
+To decode data produced with @code{l64a} the following function should be
+used.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {long int} a64l (const char *@var{string})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The parameter @var{string} should contain a string which was produced by
+a call to @code{l64a}.  The function processes at least 6 bytes of
+this string, and decodes the bytes it finds according to the table
+below.  It stops decoding when it finds a byte not in the table,
+rather like @code{atoi}; if you have a buffer which has been broken into
+lines, you must be careful to skip over the end-of-line bytes.
+
+The decoded number is returned as a @code{long int} value.
+@end deftypefun
+
+The @code{l64a} and @code{a64l} functions use a base 64 encoding, in
+which each byte of an encoded string represents six bits of an
+input word.  These symbols are used for the base 64 digits:
+
+@multitable {xxxxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx}
+@item              @tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5 @tab 6 @tab 7
+@item       0      @tab @code{.} @tab @code{/} @tab @code{0} @tab @code{1}
+                   @tab @code{2} @tab @code{3} @tab @code{4} @tab @code{5}
+@item       8      @tab @code{6} @tab @code{7} @tab @code{8} @tab @code{9}
+                   @tab @code{A} @tab @code{B} @tab @code{C} @tab @code{D}
+@item       16     @tab @code{E} @tab @code{F} @tab @code{G} @tab @code{H}
+                   @tab @code{I} @tab @code{J} @tab @code{K} @tab @code{L}
+@item       24     @tab @code{M} @tab @code{N} @tab @code{O} @tab @code{P}
+                   @tab @code{Q} @tab @code{R} @tab @code{S} @tab @code{T}
+@item       32     @tab @code{U} @tab @code{V} @tab @code{W} @tab @code{X}
+                   @tab @code{Y} @tab @code{Z} @tab @code{a} @tab @code{b}
+@item       40     @tab @code{c} @tab @code{d} @tab @code{e} @tab @code{f}
+                   @tab @code{g} @tab @code{h} @tab @code{i} @tab @code{j}
+@item       48     @tab @code{k} @tab @code{l} @tab @code{m} @tab @code{n}
+                   @tab @code{o} @tab @code{p} @tab @code{q} @tab @code{r}
+@item       56     @tab @code{s} @tab @code{t} @tab @code{u} @tab @code{v}
+                   @tab @code{w} @tab @code{x} @tab @code{y} @tab @code{z}
+@end multitable
+
+This encoding scheme is not standard.  There are some other encoding
+methods which are much more widely used (UU encoding, MIME encoding).
+Generally, it is better to use one of these encodings.
+
+@node Argz and Envz Vectors
+@section Argz and Envz Vectors
+
+@cindex argz vectors (string vectors)
+@cindex string vectors, null-byte separated
+@cindex argument vectors, null-byte separated
+@dfn{argz vectors} are vectors of strings in a contiguous block of
+memory, each element separated from its neighbors by null bytes
+(@code{'\0'}).
+
+@cindex envz vectors (environment vectors)
+@cindex environment vectors, null-byte separated
+@dfn{Envz vectors} are an extension of argz vectors where each element is a
+name-value pair, separated by a @code{'='} byte (as in a Unix
+environment).
+
+@menu
+* Argz Functions::              Operations on argz vectors.
+* Envz Functions::              Additional operations on environment vectors.
+@end menu
+
+@node Argz Functions, Envz Functions, , Argz and Envz Vectors
+@subsection Argz Functions
+
+Each argz vector is represented by a pointer to the first element, of
+type @code{char *}, and a size, of type @code{size_t}, both of which can
+be initialized to @code{0} to represent an empty argz vector.  All argz
+functions accept either a pointer and a size argument, or pointers to
+them, if they will be modified.
+
+The argz functions use @code{malloc}/@code{realloc} to allocate/grow
+argz vectors, and so any argz vector creating using these functions may
+be freed by using @code{free}; conversely, any argz function that may
+grow a string expects that string to have been allocated using
+@code{malloc} (those argz functions that only examine their arguments or
+modify them in place will work on any sort of memory).
+@xref{Unconstrained Allocation}.
+
+All argz functions that do memory allocation have a return type of
+@code{error_t}, and return @code{0} for success, and @code{ENOMEM} if an
+allocation error occurs.
+
+@pindex argz.h
+These functions are declared in the standard include file @file{argz.h}.
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_create (char *const @var{argv}[], char **@var{argz}, size_t *@var{argz_len})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{argz_create} function converts the Unix-style argument vector
+@var{argv} (a vector of pointers to normal C strings, terminated by
+@code{(char *)0}; @pxref{Program Arguments}) into an argz vector with
+the same elements, which is returned in @var{argz} and @var{argz_len}.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_create_sep (const char *@var{string}, int @var{sep}, char **@var{argz}, size_t *@var{argz_len})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{argz_create_sep} function converts the string
+@var{string} into an argz vector (returned in @var{argz} and
+@var{argz_len}) by splitting it into elements at every occurrence of the
+byte @var{sep}.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {size_t} argz_count (const char *@var{argz}, size_t @var{arg_len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Returns the number of elements in the argz vector @var{argz} and
+@var{argz_len}.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {void} argz_extract (const char *@var{argz}, size_t @var{argz_len}, char **@var{argv})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{argz_extract} function converts the argz vector @var{argz} and
+@var{argz_len} into a Unix-style argument vector stored in @var{argv},
+by putting pointers to every element in @var{argz} into successive
+positions in @var{argv}, followed by a terminator of @code{0}.
+@var{Argv} must be pre-allocated with enough space to hold all the
+elements in @var{argz} plus the terminating @code{(char *)0}
+(@code{(argz_count (@var{argz}, @var{argz_len}) + 1) * sizeof (char *)}
+bytes should be enough).  Note that the string pointers stored into
+@var{argv} point into @var{argz}---they are not copies---and so
+@var{argz} must be copied if it will be changed while @var{argv} is
+still active.  This function is useful for passing the elements in
+@var{argz} to an exec function (@pxref{Executing a File}).
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {void} argz_stringify (char *@var{argz}, size_t @var{len}, int @var{sep})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{argz_stringify} converts @var{argz} into a normal string with
+the elements separated by the byte @var{sep}, by replacing each
+@code{'\0'} inside @var{argz} (except the last one, which terminates the
+string) with @var{sep}.  This is handy for printing @var{argz} in a
+readable manner.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_add (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls strlen and argz_append.
+The @code{argz_add} function adds the string @var{str} to the end of the
+argz vector @code{*@var{argz}}, and updates @code{*@var{argz}} and
+@code{*@var{argz_len}} accordingly.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_add_sep (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}, int @var{delim})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{argz_add_sep} function is similar to @code{argz_add}, but
+@var{str} is split into separate elements in the result at occurrences of
+the byte @var{delim}.  This is useful, for instance, for
+adding the components of a Unix search path to an argz vector, by using
+a value of @code{':'} for @var{delim}.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_append (char **@var{argz}, size_t *@var{argz_len}, const char *@var{buf}, size_t @var{buf_len})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{argz_append} function appends @var{buf_len} bytes starting at
+@var{buf} to the argz vector @code{*@var{argz}}, reallocating
+@code{*@var{argz}} to accommodate it, and adding @var{buf_len} to
+@code{*@var{argz_len}}.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {void} argz_delete (char **@var{argz}, size_t *@var{argz_len}, char *@var{entry})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls free if no argument is left.
+If @var{entry} points to the beginning of one of the elements in the
+argz vector @code{*@var{argz}}, the @code{argz_delete} function will
+remove this entry and reallocate @code{*@var{argz}}, modifying
+@code{*@var{argz}} and @code{*@var{argz_len}} accordingly.  Note that as
+destructive argz functions usually reallocate their argz argument,
+pointers into argz vectors such as @var{entry} will then become invalid.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {error_t} argz_insert (char **@var{argz}, size_t *@var{argz_len}, char *@var{before}, const char *@var{entry})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls argz_add or realloc and memmove.
+The @code{argz_insert} function inserts the string @var{entry} into the
+argz vector @code{*@var{argz}} at a point just before the existing
+element pointed to by @var{before}, reallocating @code{*@var{argz}} and
+updating @code{*@var{argz}} and @code{*@var{argz_len}}.  If @var{before}
+is @code{0}, @var{entry} is added to the end instead (as if by
+@code{argz_add}).  Since the first element is in fact the same as
+@code{*@var{argz}}, passing in @code{*@var{argz}} as the value of
+@var{before} will result in @var{entry} being inserted at the beginning.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun {char *} argz_next (const char *@var{argz}, size_t @var{argz_len}, const char *@var{entry})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{argz_next} function provides a convenient way of iterating
+over the elements in the argz vector @var{argz}.  It returns a pointer
+to the next element in @var{argz} after the element @var{entry}, or
+@code{0} if there are no elements following @var{entry}.  If @var{entry}
+is @code{0}, the first element of @var{argz} is returned.
+
+This behavior suggests two styles of iteration:
+
+@smallexample
+    char *entry = 0;
+    while ((entry = argz_next (@var{argz}, @var{argz_len}, entry)))
+      @var{action};
+@end smallexample
+
+(the double parentheses are necessary to make some C compilers shut up
+about what they consider a questionable @code{while}-test) and:
+
+@smallexample
+    char *entry;
+    for (entry = @var{argz};
+         entry;
+         entry = argz_next (@var{argz}, @var{argz_len}, entry))
+      @var{action};
+@end smallexample
+
+Note that the latter depends on @var{argz} having a value of @code{0} if
+it is empty (rather than a pointer to an empty block of memory); this
+invariant is maintained for argz vectors created by the functions here.
+@end deftypefun
+
+@comment argz.h
+@comment GNU
+@deftypefun error_t argz_replace (@w{char **@var{argz}, size_t *@var{argz_len}}, @w{const char *@var{str}, const char *@var{with}}, @w{unsigned *@var{replace_count}})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+Replace any occurrences of the string @var{str} in @var{argz} with
+@var{with}, reallocating @var{argz} as necessary.  If
+@var{replace_count} is non-zero, @code{*@var{replace_count}} will be
+incremented by number of replacements performed.
+@end deftypefun
+
+@node Envz Functions, , Argz Functions, Argz and Envz Vectors
+@subsection Envz Functions
+
+Envz vectors are just argz vectors with additional constraints on the form
+of each element; as such, argz functions can also be used on them, where it
+makes sense.
+
+Each element in an envz vector is a name-value pair, separated by a @code{'='}
+byte; if multiple @code{'='} bytes are present in an element, those
+after the first are considered part of the value, and treated like all other
+non-@code{'\0'} bytes.
+
+If @emph{no} @code{'='} bytes are present in an element, that element is
+considered the name of a ``null'' entry, as distinct from an entry with an
+empty value: @code{envz_get} will return @code{0} if given the name of null
+entry, whereas an entry with an empty value would result in a value of
+@code{""}; @code{envz_entry} will still find such entries, however.  Null
+entries can be removed with @code{envz_strip} function.
+
+As with argz functions, envz functions that may allocate memory (and thus
+fail) have a return type of @code{error_t}, and return either @code{0} or
+@code{ENOMEM}.
+
+@pindex envz.h
+These functions are declared in the standard include file @file{envz.h}.
+
+@comment envz.h
+@comment GNU
+@deftypefun {char *} envz_entry (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{envz_entry} function finds the entry in @var{envz} with the name
+@var{name}, and returns a pointer to the whole entry---that is, the argz
+element which begins with @var{name} followed by a @code{'='} byte.  If
+there is no entry with that name, @code{0} is returned.
+@end deftypefun
+
+@comment envz.h
+@comment GNU
+@deftypefun {char *} envz_get (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{envz_get} function finds the entry in @var{envz} with the name
+@var{name} (like @code{envz_entry}), and returns a pointer to the value
+portion of that entry (following the @code{'='}).  If there is no entry with
+that name (or only a null entry), @code{0} is returned.
+@end deftypefun
+
+@comment envz.h
+@comment GNU
+@deftypefun {error_t} envz_add (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}, const char *@var{value})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+@c Calls envz_remove, which calls enz_entry and argz_delete, and then
+@c argz_add or equivalent code that reallocs and appends name=value.
+The @code{envz_add} function adds an entry to @code{*@var{envz}}
+(updating @code{*@var{envz}} and @code{*@var{envz_len}}) with the name
+@var{name}, and value @var{value}.  If an entry with the same name
+already exists in @var{envz}, it is removed first.  If @var{value} is
+@code{0}, then the new entry will the special null type of entry
+(mentioned above).
+@end deftypefun
+
+@comment envz.h
+@comment GNU
+@deftypefun {error_t} envz_merge (char **@var{envz}, size_t *@var{envz_len}, const char *@var{envz2}, size_t @var{envz2_len}, int @var{override})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{envz_merge} function adds each entry in @var{envz2} to @var{envz},
+as if with @code{envz_add}, updating @code{*@var{envz}} and
+@code{*@var{envz_len}}.  If @var{override} is true, then values in @var{envz2}
+will supersede those with the same name in @var{envz}, otherwise not.
+
+Null entries are treated just like other entries in this respect, so a null
+entry in @var{envz} can prevent an entry of the same name in @var{envz2} from
+being added to @var{envz}, if @var{override} is false.
+@end deftypefun
+
+@comment envz.h
+@comment GNU
+@deftypefun {void} envz_strip (char **@var{envz}, size_t *@var{envz_len})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{envz_strip} function removes any null entries from @var{envz},
+updating @code{*@var{envz}} and @code{*@var{envz_len}}.
+@end deftypefun
+
+@comment envz.h
+@comment GNU
+@deftypefun {void} envz_remove (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
+The @code{envz_remove} function removes an entry named @var{name} from
+@var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}.
+@end deftypefun
+
+@c FIXME this are undocumented:
+@c strcasecmp_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcasecmp
diff --git a/ap/libc/glibc/glibc-2.23/manual/summary.awk b/ap/libc/glibc/glibc-2.23/manual/summary.awk
new file mode 100644
index 0000000..7f721e9
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/summary.awk
@@ -0,0 +1,133 @@
+# awk script to create summary.texinfo from the library texinfo files.
+# Copyright (C) 1992-2016 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+
+# The GNU C Library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+
+# The GNU C Library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with the GNU C Library; if not, see
+# <http://www.gnu.org/licenses/>.
+
+# This script recognizes sequences that look like:
+#	@comment HEADER.h
+#	@comment STANDARD
+#	@def... ITEM | @item ITEM | @vindex ITEM
+
+BEGIN { header = 0;
+nameword["@defun"]=1
+nameword["@defunx"]=1
+nameword["@defmac"]=1
+nameword["@defmacx"]=1
+nameword["@defspec"]=1
+nameword["@defspecx"]=1
+nameword["@defvar"]=1
+nameword["@defvarx"]=1
+nameword["@defopt"]=1
+nameword["@defoptx"]=1
+nameword["@deffn"]=2
+nameword["@deffnx"]=2
+nameword["@defvr"]=2
+nameword["@defvrx"]=2
+nameword["@deftp"]=2
+nameword["@deftpx"]=2
+nameword["@deftypefun"]=2
+nameword["@deftypefunx"]=2
+nameword["@deftypevar"]=2
+nameword["@deftypevarx"]=2
+nameword["@deftypefn"]=3
+nameword["@deftypefnx"]=3
+nameword["@deftypevr"]=3
+nameword["@deftypevrx"]=3
+firstword["@defun"]=1
+firstword["@defunx"]=1
+firstword["@defmac"]=1
+firstword["@defmacx"]=1
+firstword["@defspec"]=1
+firstword["@defspecx"]=1
+firstword["@defvar"]=1
+firstword["@defvarx"]=1
+firstword["@defopt"]=1
+firstword["@defoptx"]=1
+firstword["@deffn"]=2
+firstword["@deffnx"]=2
+firstword["@defvr"]=2
+firstword["@defvrx"]=2
+firstword["@deftp"]=2
+firstword["@deftpx"]=2
+firstword["@deftypefun"]=1
+firstword["@deftypefunx"]=1
+firstword["@deftypevar"]=1
+firstword["@deftypevarx"]=1
+firstword["@deftypefn"]=2
+firstword["@deftypefnx"]=2
+firstword["@deftypevr"]=2
+firstword["@deftypevrx"]=2
+nameword["@item"]=1
+firstword["@item"]=1
+nameword["@itemx"]=1
+firstword["@itemx"]=1
+nameword["@vindex"]=1
+firstword["@vindex"]=1
+
+print "@c DO NOT EDIT THIS FILE!"
+print "@c This file is generated by summary.awk from the Texinfo sources."
+}
+
+$1 == "@node" { node=$2;
+		for (i = 3; i <= NF; ++i)
+		 { node=node " " $i; if ( $i ~ /,/ ) break; }
+		sub (/,[, ]*$/, "", node);
+	      }
+
+$1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}";
+				  for (i = 3; i <= NF; ++i)
+				    header=header ", @file{" $i "}"
+				}
+
+$1 == "@comment" && $2 == "(none)" { header = -1; }
+
+$1 == "@comment" && header != 0 { std=$2;
+				  for (i=3;i<=NF;++i) std=std " " $i }
+
+header != 0 && $1 ~ /@def|@item|@vindex/ \
+	{ defn=""; name=""; curly=0; n=1;
+	  for (i = 2; i <= NF; ++i) {
+	    if ($i ~ /^{/ && $i !~ /}/) {
+	      curly=1
+	      word=substr ($i, 2, length ($i))
+	    }
+	    else {
+	      if (curly) {
+	        if ($i ~ /}$/) {
+		  curly=0
+		  word=word " " substr ($i, 1, length ($i) - 1)
+	        } else
+		  word=word " " $i
+	      }
+	      # Handle a single word in braces.
+	      else if ($i ~ /^{.*}$/)
+		word=substr ($i, 2, length ($i) - 2)
+	      else
+	        word=$i
+	      if (!curly) {
+		if (n >= firstword[$1])
+		  defn=defn " " word
+		if (n == nameword[$1])
+		  name=word
+		++n
+	      }
+	    }
+	  }
+	  printf "@comment %s%c", name, 12 # FF
+	  printf "@item%s%c%c", defn, 12, 12
+	  if (header != -1) printf "%s ", header;
+	  printf "(%s):  @ref{%s}.%c\n", std, node, 12;
+	  header = 0 }
diff --git a/ap/libc/glibc/glibc-2.23/manual/sysinfo.texi b/ap/libc/glibc/glibc-2.23/manual/sysinfo.texi
new file mode 100644
index 0000000..1fbfb95
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/sysinfo.texi
@@ -0,0 +1,1289 @@
+@node System Management, System Configuration, Users and Groups, Top
+@c %MENU% Controlling the system and getting information about it
+@chapter System Management
+
+This chapter describes facilities for controlling the system that
+underlies a process (including the operating system and hardware) and
+for getting information about it.  Anyone can generally use the
+informational facilities, but usually only a properly privileged process
+can make changes.
+
+
+@menu
+* Host Identification::         Determining the name of the machine.
+* Platform Type::               Determining operating system and basic
+                                  machine type
+* Filesystem Handling::         Controlling/querying mounts
+* System Parameters::           Getting and setting various system parameters
+@end menu
+
+To get information on parameters of the system that are built into the
+system, such as the maximum length of a filename, @ref{System
+Configuration}.
+
+@node Host Identification
+@section Host Identification
+
+This section explains how to identify the particular system on which your
+program is running.  First, let's review the various ways computer systems
+are named, which is a little complicated because of the history of the
+development of the Internet.
+
+Every Unix system (also known as a host) has a host name, whether it's
+connected to a network or not.  In its simplest form, as used before
+computer networks were an issue, it's just a word like @samp{chicken}.
+@cindex host name
+
+But any system attached to the Internet or any network like it conforms
+to a more rigorous naming convention as part of the Domain Name System
+(DNS).  In DNS, every host name is composed of two parts:
+@cindex DNS
+@cindex Domain Name System
+
+@enumerate
+@item
+hostname
+@cindex hostname
+@item
+domain name
+@cindex domain name
+@end enumerate
+
+You will note that ``hostname'' looks a lot like ``host name'', but is
+not the same thing, and that people often incorrectly refer to entire
+host names as ``domain names.''
+
+In DNS, the full host name is properly called the FQDN (Fully Qualified
+Domain Name) and consists of the hostname, then a period, then the
+domain name.  The domain name itself usually has multiple components
+separated by periods.  So for example, a system's hostname may be
+@samp{chicken} and its domain name might be @samp{ai.mit.edu}, so
+its FQDN (which is its host name) is @samp{chicken.ai.mit.edu}.
+@cindex FQDN
+
+Adding to the confusion, though, is that DNS is not the only name space
+in which a computer needs to be known.  Another name space is the
+NIS (aka YP) name space.  For NIS purposes, there is another domain
+name, which is called the NIS domain name or the YP domain name.  It
+need not have anything to do with the DNS domain name.
+@cindex YP
+@cindex NIS
+@cindex NIS domain name
+@cindex YP domain name
+
+Confusing things even more is the fact that in DNS, it is possible for
+multiple FQDNs to refer to the same system.  However, there is always
+exactly one of them that is the true host name, and it is called the
+canonical FQDN.
+
+In some contexts, the host name is called a ``node name.''
+
+For more information on DNS host naming, see @ref{Host Names}.
+
+@pindex hostname
+@pindex hostid
+@pindex unistd.h
+Prototypes for these functions appear in @file{unistd.h}.
+
+The programs @code{hostname}, @code{hostid}, and @code{domainname} work
+by calling these functions.
+
+@comment unistd.h
+@comment BSD
+@deftypefun int gethostname (char *@var{name}, size_t @var{size})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on unix; implemented in terms of uname on posix and of
+@c hurd_get_host_config on hurd.
+This function returns the host name of the system on which it is called,
+in the array @var{name}.  The @var{size} argument specifies the size of
+this array, in bytes.  Note that this is @emph{not} the DNS hostname.
+If the system participates in DNS, this is the FQDN (see above).
+
+The return value is @code{0} on success and @code{-1} on failure.  In
+@theglibc{}, @code{gethostname} fails if @var{size} is not large
+enough; then you can try again with a larger array.  The following
+@code{errno} error condition is defined for this function:
+
+@table @code
+@item ENAMETOOLONG
+The @var{size} argument is less than the size of the host name plus one.
+@end table
+
+@pindex sys/param.h
+On some systems, there is a symbol for the maximum possible host name
+length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
+But you can't count on this to exist, so it is cleaner to handle
+failure and try again.
+
+@code{gethostname} stores the beginning of the host name in @var{name}
+even if the host name won't entirely fit.  For some purposes, a
+truncated host name is good enough.  If it is, you can ignore the
+error code.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int sethostname (const char *@var{name}, size_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on unix; implemented in terms of hurd_set_host_config
+@c on hurd.
+The @code{sethostname} function sets the host name of the system that
+calls it to @var{name}, a string with length @var{length}.  Only
+privileged processes are permitted to do this.
+
+Usually @code{sethostname} gets called just once, at system boot time.
+Often, the program that calls it sets it to the value it finds in the
+file @code{/etc/hostname}.
+@cindex /etc/hostname
+
+Be sure to set the host name to the full host name, not just the DNS
+hostname (see above).
+
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EPERM
+This process cannot set the host name because it is not privileged.
+@end table
+@end deftypefun
+
+@comment unistd.h
+@comment ???
+@deftypefun int getdomainnname (char *@var{name}, size_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Syscalls uname, then strlen and memcpy.
+@cindex NIS domain name
+@cindex YP domain name
+
+@code{getdomainname} returns the NIS (aka YP) domain name of the system
+on which it is called.  Note that this is not the more popular DNS
+domain name.  Get that with @code{gethostname}.
+
+The specifics of this function are analogous to @code{gethostname}, above.
+
+@end deftypefun
+
+@comment unistd.h
+@comment ???
+@deftypefun int setdomainname (const char *@var{name}, size_t @var{length})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall.
+@cindex NIS domain name
+@cindex YP domain name
+
+@code{getdomainname} sets the NIS (aka YP) domain name of the system
+on which it is called.  Note that this is not the more popular DNS
+domain name.  Set that with @code{sethostname}.
+
+The specifics of this function are analogous to @code{sethostname}, above.
+
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun {long int} gethostid (void)
+@safety{@prelim{}@mtsafe{@mtshostid{} @mtsenv{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{} @acsfd{}}}
+@c On HURD, calls _hurd_get_host_config and strtol.  On Linux, open
+@c HOSTIDFILE, reads an int32_t and closes; if that fails, it calls
+@c gethostname and gethostbyname_r to use the h_addr.
+This function returns the ``host ID'' of the machine the program is
+running on.  By convention, this is usually the primary Internet IP address
+of that machine, converted to a @w{@code{long int}}.  However, on some
+systems it is a meaningless but unique number which is hard-coded for
+each machine.
+
+This is not widely used.  It arose in BSD 4.2, but was dropped in BSD 4.4.
+It is not required by POSIX.
+
+The proper way to query the IP address is to use @code{gethostbyname}
+on the results of @code{gethostname}.  For more information on IP addresses,
+@xref{Host Addresses}.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int sethostid (long int @var{id})
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtshostid{}}}@asunsafe{}@acunsafe{@acucorrupt{} @acsfd{}}}
+The @code{sethostid} function sets the ``host ID'' of the host machine
+to @var{id}.  Only privileged processes are permitted to do this.  Usually
+it happens just once, at system boot time.
+
+The proper way to establish the primary IP address of a system
+is to configure the IP address resolver to associate that IP address with
+the system's host name as returned by @code{gethostname}.  For example,
+put a record for the system in @file{/etc/hosts}.
+
+See @code{gethostid} above for more information on host ids.
+
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+This process cannot set the host name because it is not privileged.
+
+@item ENOSYS
+The operating system does not support setting the host ID.  On some
+systems, the host ID is a meaningless but unique number hard-coded for
+each machine.
+@end table
+@end deftypefun
+
+@node Platform Type
+@section Platform Type Identification
+
+You can use the @code{uname} function to find out some information about
+the type of computer your program is running on.  This function and the
+associated data type are declared in the header file
+@file{sys/utsname.h}.
+@pindex sys/utsname.h
+
+As a bonus, @code{uname} also gives some information identifying the
+particular system your program is running on.  This is the same information
+which you can get with functions targeted to this purpose described in
+@ref{Host Identification}.
+
+
+@comment sys/utsname.h
+@comment POSIX.1
+@deftp {Data Type} {struct utsname}
+The @code{utsname} structure is used to hold information returned
+by the @code{uname} function.  It has the following members:
+
+@table @code
+@item char sysname[]
+This is the name of the operating system in use.
+
+@item char release[]
+This is the current release level of the operating system implementation.
+
+@item char version[]
+This is the current version level within the release of the operating
+system.
+
+@item char machine[]
+This is a description of the type of hardware that is in use.
+
+Some systems provide a mechanism to interrogate the kernel directly for
+this information.  On systems without such a mechanism, @theglibc{}
+fills in this field based on the configuration name that was
+specified when building and installing the library.
+
+GNU uses a three-part name to describe a system configuration; the three
+parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
+are separated with dashes.  Any possible combination of three names is
+potentially meaningful, but most such combinations are meaningless in
+practice and even the meaningful ones are not necessarily supported by
+any particular GNU program.
+
+Since the value in @code{machine} is supposed to describe just the
+hardware, it consists of the first two parts of the configuration name:
+@samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
+
+@quotation
+@code{"sparc-sun"},
+@code{"i386-@var{anything}"},
+@code{"m68k-hp"},
+@code{"m68k-sony"},
+@code{"m68k-sun"},
+@code{"mips-dec"}
+@end quotation
+
+@item char nodename[]
+This is the host name of this particular computer.  In @theglibc{},
+the value is the same as that returned by @code{gethostname};
+see @ref{Host Identification}.
+
+@ gethostname() is implemented with a call to uname().
+
+@item char domainname[]
+This is the NIS or YP domain name.  It is the same value returned by
+@code{getdomainname}; see @ref{Host Identification}.  This element
+is a relatively recent invention and use of it is not as portable as
+use of the rest of the structure.
+
+@c getdomainname() is implemented with a call to uname().
+
+@end table
+@end deftp
+
+@comment sys/utsname.h
+@comment POSIX.1
+@deftypefun int uname (struct utsname *@var{info})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall on unix; the posix fallback is to call gethostname and
+@c then fills in the other fields with constants; on HURD, it calls
+@c proc_uname and then gethostname.
+The @code{uname} function fills in the structure pointed to by
+@var{info} with information about the operating system and host machine.
+A non-negative value indicates that the data was successfully stored.
+
+@code{-1} as the value indicates an error.  The only error possible is
+@code{EFAULT}, which we normally don't mention as it is always a
+possibility.
+@end deftypefun
+
+
+@node Filesystem Handling
+@section Controlling and Querying Mounts
+
+All files are in filesystems, and before you can access any file, its
+filesystem must be mounted.  Because of Unix's concept of
+@emph{Everything is a file}, mounting of filesystems is central to doing
+almost anything.  This section explains how to find out what filesystems
+are currently mounted and what filesystems are available for mounting,
+and how to change what is mounted.
+
+The classic filesystem is the contents of a disk drive.  The concept is
+considerably more abstract, though, and lots of things other than disk
+drives can be mounted.
+
+Some block devices don't correspond to traditional devices like disk
+drives.  For example, a loop device is a block device whose driver uses
+a regular file in another filesystem as its medium.  So if that regular
+file contains appropriate data for a filesystem, you can by mounting the
+loop device essentially mount a regular file.
+
+Some filesystems aren't based on a device of any kind.  The ``proc''
+filesystem, for example, contains files whose data is made up by the
+filesystem driver on the fly whenever you ask for it.  And when you
+write to it, the data you write causes changes in the system.  No data
+gets stored.
+
+@c It would be good to mention NFS mounts here.
+
+@menu
+* Mount Information::           What is or could be mounted?
+* Mount-Unmount-Remount::       Controlling what is mounted and how
+@end menu
+
+@node Mount Information, Mount-Unmount-Remount, , Filesystem Handling
+@subsection Mount Information
+
+For some programs it is desirable and necessary to access information
+about whether a certain filesystem is mounted and, if it is, where, or
+simply to get lists of all the available filesystems.  @Theglibc{}
+provides some functions to retrieve this information portably.
+
+Traditionally Unix systems have a file named @file{/etc/fstab} which
+describes all possibly mounted filesystems.  The @code{mount} program
+uses this file to mount at startup time of the system all the
+necessary filesystems.  The information about all the filesystems
+actually mounted is normally kept in a file named either
+@file{/var/run/mtab} or @file{/etc/mtab}.  Both files share the same
+syntax and it is crucial that this syntax is followed all the time.
+Therefore it is best to never directly write the files.  The functions
+described in this section can do this and they also provide the
+functionality to convert the external textual representation to the
+internal representation.
+
+Note that the @file{fstab} and @file{mtab} files are maintained on a
+system by @emph{convention}.  It is possible for the files not to exist
+or not to be consistent with what is really mounted or available to
+mount, if the system's administration policy allows it.  But programs
+that mount and unmount filesystems typically maintain and use these
+files as described herein.
+
+@vindex _PATH_FSTAB
+@vindex _PATH_MNTTAB
+@vindex _PATH_MOUNTED
+@vindex FSTAB
+@vindex MNTTAB
+@vindex MOUNTED
+The filenames given above should never be used directly.  The portable
+way to handle these file is to use the macro @code{_PATH_FSTAB},
+defined in @file{fstab.h}, or @code{_PATH_MNTTAB}, defined in
+@file{mntent.h} and @file{paths.h}, for @file{fstab}; and the macro
+@code{_PATH_MOUNTED}, also defined in @file{mntent.h} and
+@file{paths.h}, for @file{mtab}.  There are also two alternate macro
+names @code{FSTAB}, @code{MNTTAB}, and @code{MOUNTED} defined but
+these names are deprecated and kept only for backward compatibility.
+The names @code{_PATH_MNTTAB} and @code{_PATH_MOUNTED} should always be used.
+
+@menu
+* fstab::                       The @file{fstab} file
+* mtab::                        The @file{mtab} file
+* Other Mount Information::     Other (non-libc) sources of mount information
+@end menu
+
+@node fstab
+@subsubsection The @file{fstab} file
+
+The internal representation for entries of the file is @w{@code{struct
+fstab}}, defined in @file{fstab.h}.
+
+@comment fstab.h
+@comment BSD
+@deftp {Data Type} {struct fstab}
+This structure is used with the @code{getfsent}, @code{getfsspec}, and
+@code{getfsfile} functions.
+
+@table @code
+@item char *fs_spec
+This element describes the device from which the filesystem is mounted.
+Normally this is the name of a special device, such as a hard disk
+partition, but it could also be a more or less generic string.  For
+@dfn{NFS} it would be a hostname and directory name combination.
+
+Even though the element is not declared @code{const} it shouldn't be
+modified.  The missing @code{const} has historic reasons, since this
+function predates @w{ISO C}.  The same is true for the other string
+elements of this structure.
+
+@item char *fs_file
+This describes the mount point on the local system.  I.e., accessing any
+file in this filesystem has implicitly or explicitly this string as a
+prefix.
+
+@item char *fs_vfstype
+This is the type of the filesystem.  Depending on what the underlying
+kernel understands it can be any string.
+
+@item char *fs_mntops
+This is a string containing options passed to the kernel with the
+@code{mount} call.  Again, this can be almost anything.  There can be
+more than one option, separated from the others by a comma.  Each option
+consists of a name and an optional value part, introduced by an @code{=}
+character.
+
+If the value of this element must be processed it should ideally be done
+using the @code{getsubopt} function; see @ref{Suboptions}.
+
+@item const char *fs_type
+This name is poorly chosen.  This element points to a string (possibly
+in the @code{fs_mntops} string) which describes the modes with which the
+filesystem is mounted.  @file{fstab} defines five macros to describe the
+possible values:
+
+@vtable @code
+@item FSTAB_RW
+The filesystems gets mounted with read and write enabled.
+@item FSTAB_RQ
+The filesystems gets mounted with read and write enabled.  Write access
+is restricted by quotas.
+@item FSTAB_RO
+The filesystem gets mounted read-only.
+@item FSTAB_SW
+This is not a real filesystem, it is a swap device.
+@item FSTAB_XX
+This entry from the @file{fstab} file is totally ignored.
+@end vtable
+
+Testing for equality with these value must happen using @code{strcmp}
+since these are all strings.  Comparing the pointer will probably always
+fail.
+
+@item int fs_freq
+This element describes the dump frequency in days.
+
+@item int fs_passno
+This element describes the pass number on parallel dumps.  It is closely
+related to the @code{dump} utility used on Unix systems.
+@end table
+@end deftp
+
+
+To read the entire content of the of the @file{fstab} file @theglibc{}
+contains a set of three functions which are designed in the usual way.
+
+@comment fstab.h
+@comment BSD
+@deftypefun int setfsent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:fsent}}@asunsafe{@ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c setfsent @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c  fstab_init(1) @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c   malloc dup @ascuheap @acsmem
+@c   rewind dup @asucorrupt @acucorrupt [no @aculock]
+@c   setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock
+This function makes sure that the internal read pointer for the
+@file{fstab} file is at the beginning of the file.  This is done by
+either opening the file or resetting the read pointer.
+
+Since the file handle is internal to the libc this function is not
+thread-safe.
+
+This function returns a non-zero value if the operation was successful
+and the @code{getfs*} functions can be used to read the entries of the
+file.
+@end deftypefun
+
+@comment fstab.h
+@comment BSD
+@deftypefun void endfsent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:fsent}}@asunsafe{@ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c endfsent @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c  endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd
+This function makes sure that all resources acquired by a prior call to
+@code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are
+freed.
+@end deftypefun
+
+@comment fstab.h
+@comment BSD
+@deftypefun {struct fstab *} getfsent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c getfsent @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  fstab_init(0) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c  fstab_fetch @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+@c   getmntent_r dup @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+@c  fstab_convert @mtasurace:fsent
+@c   hasmntopt dup ok
+This function returns the next entry of the @file{fstab} file.  If this
+is the first call to any of the functions handling @file{fstab} since
+program start or the last call of @code{endfsent}, the file will be
+opened.
+
+The function returns a pointer to a variable of type @code{struct
+fstab}.  This variable is shared by all threads and therefore this
+function is not thread-safe.  If an error occurred @code{getfsent}
+returns a @code{NULL} pointer.
+@end deftypefun
+
+@comment fstab.h
+@comment BSD
+@deftypefun {struct fstab *} getfsspec (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c getffsspec @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  fstab_init(1) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c  fstab_fetch dup @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+@c  strcmp dup ok
+@c  fstab_convert dup @mtasurace:fsent
+This function returns the next entry of the @file{fstab} file which has
+a string equal to @var{name} pointed to by the @code{fs_spec} element.
+Since there is normally exactly one entry for each special device it
+makes no sense to call this function more than once for the same
+argument.  If this is the first call to any of the functions handling
+@file{fstab} since program start or the last call of @code{endfsent},
+the file will be opened.
+
+The function returns a pointer to a variable of type @code{struct
+fstab}.  This variable is shared by all threads and therefore this
+function is not thread-safe.  If an error occurred @code{getfsent}
+returns a @code{NULL} pointer.
+@end deftypefun
+
+@comment fstab.h
+@comment BSD
+@deftypefun {struct fstab *} getfsfile (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:fsent} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c getffsfile @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c  fstab_init(1) dup @mtasurace:fsent @ascuheap @asucorrupt @asulock @acucorrupt @aculock @acsmem @acsfd
+@c  fstab_fetch dup @mtasurace:fsent @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+@c  strcmp dup ok
+@c  fstab_convert dup @mtasurace:fsent
+This function returns the next entry of the @file{fstab} file which has
+a string equal to @var{name} pointed to by the @code{fs_file} element.
+Since there is normally exactly one entry for each mount point it
+makes no sense to call this function more than once for the same
+argument.  If this is the first call to any of the functions handling
+@file{fstab} since program start or the last call of @code{endfsent},
+the file will be opened.
+
+The function returns a pointer to a variable of type @code{struct
+fstab}.  This variable is shared by all threads and therefore this
+function is not thread-safe.  If an error occurred @code{getfsent}
+returns a @code{NULL} pointer.
+@end deftypefun
+
+
+@node mtab
+@subsubsection The @file{mtab} file
+The following functions and data structure access the @file{mtab} file.
+
+@comment mntent.h
+@comment BSD
+@deftp {Data Type} {struct mntent}
+This structure is used with the @code{getmntent}, @code{getmntent_t},
+@code{addmntent}, and @code{hasmntopt} functions.
+
+@table @code
+@item char *mnt_fsname
+This element contains a pointer to a string describing the name of the
+special device from which the filesystem is mounted.  It corresponds to
+the @code{fs_spec} element in @code{struct fstab}.
+
+@item char *mnt_dir
+This element points to a string describing the mount point of the
+filesystem.  It corresponds to the @code{fs_file} element in
+@code{struct fstab}.
+
+@item char *mnt_type
+@code{mnt_type} describes the filesystem type and is therefore
+equivalent to @code{fs_vfstype} in @code{struct fstab}.  @file{mntent.h}
+defines a few symbolic names for some of the values this string can have.
+But since the kernel can support arbitrary filesystems it does not
+make much sense to give them symbolic names.  If one knows the symbol
+name one also knows the filesystem name.  Nevertheless here follows the
+list of the symbols provided in @file{mntent.h}.
+
+@vtable @code
+@item MNTTYPE_IGNORE
+This symbol expands to @code{"ignore"}.  The value is sometime used in
+@file{fstab} files to make sure entries are not used without removing them.
+@item MNTTYPE_NFS
+Expands to @code{"nfs"}.  Using this macro sometimes could make sense
+since it names the default NFS implementation, in case both version 2
+and 3 are supported.
+@item MNTTYPE_SWAP
+This symbol expands to @code{"swap"}.  It names the special @file{fstab}
+entry which names one of the possibly multiple swap partitions.
+@end vtable
+
+@item char *mnt_opts
+The element contains a string describing the options used while mounting
+the filesystem.  As for the equivalent element @code{fs_mntops} of
+@code{struct fstab} it is best to use the function @code{getsubopt}
+(@pxref{Suboptions}) to access the parts of this string.
+
+The @file{mntent.h} file defines a number of macros with string values
+which correspond to some of the options understood by the kernel.  There
+might be many more options which are possible so it doesn't make much sense
+to rely on these macros but to be consistent here is the list:
+
+@vtable @code
+@item MNTOPT_DEFAULTS
+Expands to @code{"defaults"}.  This option should be used alone since it
+indicates all values for the customizable values are chosen to be the
+default.
+@item MNTOPT_RO
+Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
+filesystem is mounted read-only.
+@item MNTOPT_RW
+Expand to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
+filesystem is mounted with read and write permissions.
+@item MNTOPT_SUID
+Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
+Change Persona}) is respected when a program from the filesystem is
+started.
+@item MNTOPT_NOSUID
+Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
+the SUID bit for all files from the filesystem is ignored.
+@item MNTOPT_NOAUTO
+Expands to @code{"noauto"}.  At startup time the @code{mount} program
+will ignore this entry if it is started with the @code{-a} option to
+mount all filesystems mentioned in the @file{fstab} file.
+@end vtable
+
+As for the @code{FSTAB_*} entries introduced above it is important to
+use @code{strcmp} to check for equality.
+
+@item mnt_freq
+This elements corresponds to @code{fs_freq} and also specifies the
+frequency in days in which dumps are made.
+
+@item mnt_passno
+This element is equivalent to @code{fs_passno} with the same meaning
+which is uninteresting for all programs beside @code{dump}.
+@end table
+@end deftp
+
+For accessing the @file{mtab} file there is again a set of three
+functions to access all entries in a row.  Unlike the functions to
+handle @file{fstab} these functions do not access a fixed file and there
+is even a thread safe variant of the get function.  Beside this @theglibc
+contains functions to alter the file and test for specific options.
+
+@comment mntent.h
+@comment BSD
+@deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
+@c setmntent @ascuheap @asulock @acsmem @acsfd @aculock
+@c  strlen dup ok
+@c  mempcpy dup ok
+@c  memcpy dup ok
+@c  fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c  fsetlocking dup ok [no @mtasurace:stream @asulock: exclusive stream]
+The @code{setmntent} function prepares the file named @var{FILE} which
+must be in the format of a @file{fstab} and @file{mtab} file for the
+upcoming processing through the other functions of the family.  The
+@var{mode} parameter can be chosen in the way the @var{opentype}
+parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen.  If
+the file is opened for writing the file is also allowed to be empty.
+
+If the file was successfully opened @code{setmntent} returns a file
+descriptor for future use.  Otherwise the return value is @code{NULL}
+and @code{errno} is set accordingly.
+@end deftypefun
+
+@comment mntent.h
+@comment BSD
+@deftypefun int endmntent (FILE *@var{stream})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c endmntent @ascuheap @asulock @aculock @acsmem @acsfd
+@c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+This function takes for the @var{stream} parameter a file handle which
+previously was returned from the @code{setmntent} call.
+@code{endmntent} closes the stream and frees all resources.
+
+The return value is @math{1} unless an error occurred in which case it
+is @math{0}.
+@end deftypefun
+
+@comment mntent.h
+@comment BSD
+@deftypefun {struct mntent *} getmntent (FILE *@var{stream})
+@safety{@prelim{}@mtunsafe{@mtasurace{:mntentbuf} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asuinit{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsmem{}}}
+@c getmntent @mtasurace:mntentbuf @mtslocale @asucorrupt @ascuheap @asuinit @acuinit @acucorrupt @aculock @acsmem
+@c  libc_once @ascuheap @asuinit @acuinit @acsmem
+@c   allocate @ascuheap @acsmem
+@c    malloc dup @ascuheap @acsmem
+@c  getmntent_r dup @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+The @code{getmntent} function takes as the parameter a file handle
+previously returned by successful call to @code{setmntent}.  It returns
+a pointer to a static variable of type @code{struct mntent} which is
+filled with the information from the next entry from the file currently
+read.
+
+The file format used prescribes the use of spaces or tab characters to
+separate the fields.  This makes it harder to use name containing one
+of these characters (e.g., mount points using spaces).  Therefore
+these characters are encoded in the files and the @code{getmntent}
+function takes care of the decoding while reading the entries back in.
+@code{'\040'} is used to encode a space character, @code{'\011'} to
+encode a tab character, @code{'\012'} to encode a newline character,
+and @code{'\\'} to encode a backslash.
+
+If there was an error or the end of the file is reached the return value
+is @code{NULL}.
+
+This function is not thread-safe since all calls to this function return
+a pointer to the same static variable.  @code{getmntent_r} should be
+used in situations where multiple threads access the file.
+@end deftypefun
+
+@comment mntent.h
+@comment BSD
+@deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mntent *@var{result}, char *@var{buffer}, int @var{bufsize})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c getmntent_r @mtslocale @asucorrupt @ascuheap @acucorrupt @aculock @acsmem
+@c  flockfile dup @aculock
+@c  fgets_unlocked dup @asucorrupt @acucorrupt [locked, so no @mtsrace:stream]
+@c  funlockfile dup @aculock
+@c  strchr dup ok
+@c  strspn dup ok
+@c  strsep dup ok
+@c  decode_name ok
+@c  sscanf dup @mtslocale @ascuheap @acsmem
+The @code{getmntent_r} function is the reentrant variant of
+@code{getmntent}.  It also returns the next entry from the file and
+returns a pointer.  The actual variable the values are stored in is not
+static, though.  Instead the function stores the values in the variable
+pointed to by the @var{result} parameter.  Additional information (e.g.,
+the strings pointed to by the elements of the result) are kept in the
+buffer of size @var{bufsize} pointed to by @var{buffer}.
+
+Escaped characters (space, tab, backslash) are converted back in the
+same way as it happens for @code{getmentent}.
+
+The function returns a @code{NULL} pointer in error cases.  Errors could be:
+@itemize @bullet
+@item
+error while reading the file,
+@item
+end of file reached,
+@item
+@var{bufsize} is too small for reading a complete new entry.
+@end itemize
+@end deftypefun
+
+@comment mntent.h
+@comment BSD
+@deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
+@safety{@prelim{}@mtsafe{@mtsrace{:stream} @mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
+@c addmntent @mtasurace:stream @mtslocale @asucorrupt @acucorrupt
+@c  fseek dup @asucorrupt @acucorrupt [no @aculock]
+@c  encode_name ok
+@c  fprintf dup @mtslocale @asucorrupt @acucorrupt [no @ascuheap @acsmem, no @aculock]
+@c  fflush dup @asucorrupt @acucorrupt [no @aculock]
+The @code{addmntent} function allows adding a new entry to the file
+previously opened with @code{setmntent}.  The new entries are always
+appended.  I.e., even if the position of the file descriptor is not at
+the end of the file this function does not overwrite an existing entry
+following the current position.
+
+The implication of this is that to remove an entry from a file one has
+to create a new file while leaving out the entry to be removed and after
+closing the file remove the old one and rename the new file to the
+chosen name.
+
+This function takes care of spaces and tab characters in the names to be
+written to the file.  It converts them and the backslash character into
+the format describe in the @code{getmntent} description above.
+
+This function returns @math{0} in case the operation was successful.
+Otherwise the return value is @math{1} and @code{errno} is set
+appropriately.
+@end deftypefun
+
+@comment mntent.h
+@comment BSD
+@deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c hasmntopt ok
+@c  strlen dup ok
+@c  strstr dup ok
+@c  strchr dup ok
+This function can be used to check whether the string pointed to by the
+@code{mnt_opts} element of the variable pointed to by @var{mnt} contains
+the option @var{opt}.  If this is true a pointer to the beginning of the
+option in the @code{mnt_opts} element is returned.  If no such option
+exists the function returns @code{NULL}.
+
+This function is useful to test whether a specific option is present but
+when all options have to be processed one is better off with using the
+@code{getsubopt} function to iterate over all options in the string.
+@end deftypefun
+
+@node Other Mount Information
+@subsubsection Other (Non-libc) Sources of Mount Information
+
+On a system with a Linux kernel and the @code{proc} filesystem, you can
+get information on currently mounted filesystems from the file
+@file{mounts} in the @code{proc} filesystem.  Its format is similar to
+that of the @file{mtab} file, but represents what is truly mounted
+without relying on facilities outside the kernel to keep @file{mtab} up
+to date.
+
+
+@node Mount-Unmount-Remount, , Mount Information, Filesystem Handling
+@subsection Mount, Unmount, Remount
+
+This section describes the functions for mounting, unmounting, and
+remounting filesystems.
+
+Only the superuser can mount, unmount, or remount a filesystem.
+
+These functions do not access the @file{fstab} and @file{mtab} files.  You
+should maintain and use these separately.  @xref{Mount Information}.
+
+The symbols in this section are declared in @file{sys/mount.h}.
+
+@comment sys/mount.h
+@comment SVID, BSD
+@deftypefun {int} mount (const char *@var{special_file}, const char *@var{dir}, const char *@var{fstype}, unsigned long int @var{options}, const void *@var{data})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall.
+
+@code{mount} mounts or remounts a filesystem.  The two operations are
+quite different and are merged rather unnaturally into this one function.
+The @code{MS_REMOUNT} option, explained below, determines whether
+@code{mount} mounts or remounts.
+
+For a mount, the filesystem on the block device represented by the
+device special file named @var{special_file} gets mounted over the mount
+point @var{dir}.  This means that the directory @var{dir} (along with any
+files in it) is no longer visible; in its place (and still with the name
+@var{dir}) is the root directory of the filesystem on the device.
+
+As an exception, if the filesystem type (see below) is one which is not
+based on a device (e.g. ``proc''), @code{mount} instantiates a
+filesystem and mounts it over @var{dir} and ignores @var{special_file}.
+
+For a remount, @var{dir} specifies the mount point where the filesystem
+to be remounted is (and remains) mounted and @var{special_file} is
+ignored.  Remounting a filesystem means changing the options that control
+operations on the filesystem while it is mounted.  It does not mean
+unmounting and mounting again.
+
+For a mount, you must identify the type of the filesystem as
+@var{fstype}.  This type tells the kernel how to access the filesystem
+and can be thought of as the name of a filesystem driver.  The
+acceptable values are system dependent.  On a system with a Linux kernel
+and the @code{proc} filesystem, the list of possible values is in the
+file @file{filesystems} in the @code{proc} filesystem (e.g. type
+@kbd{cat /proc/filesystems} to see the list).  With a Linux kernel, the
+types of filesystems that @code{mount} can mount, and their type names,
+depends on what filesystem drivers are configured into the kernel or
+loaded as loadable kernel modules.  An example of a common value for
+@var{fstype} is @code{ext2}.
+
+For a remount, @code{mount} ignores @var{fstype}.
+
+@c This is traditionally called "rwflag" for historical reasons.
+@c No point in confusing people today, though.
+@var{options} specifies a variety of options that apply until the
+filesystem is unmounted or remounted.  The precise meaning of an option
+depends on the filesystem and with some filesystems, an option may have
+no effect at all.  Furthermore, for some filesystems, some of these
+options (but never @code{MS_RDONLY}) can be overridden for individual
+file accesses via @code{ioctl}.
+
+@var{options} is a bit string with bit fields defined using the
+following mask and masked value macros:
+
+@table @code
+@item MS_MGC_MASK
+This multibit field contains a magic number.  If it does not have the value
+@code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
+the @var{data} argument is a null string, regardless of their actual values.
+
+@item MS_REMOUNT
+This bit on means to remount the filesystem.  Off means to mount it.
+@c There is a mask MS_RMT_MASK in mount.h that says only two of the options
+@c can be reset by remount.  But the Linux kernel has its own version of
+@c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
+@c libc just passes the arguments straight through to the kernel.
+
+@item MS_RDONLY
+This bit on specifies that no writing to the filesystem shall be allowed
+while it is mounted.  This cannot be overridden by @code{ioctl}.  This
+option is available on nearly all filesystems.
+
+@item S_IMMUTABLE
+This bit on specifies that no writing to the files in the filesystem
+shall be allowed while it is mounted.  This can be overridden for a
+particular file access by a properly privileged call to @code{ioctl}.
+This option is a relatively new invention and is not available on many
+filesystems.
+
+@item S_APPEND
+This bit on specifies that the only file writing that shall be allowed
+while the filesystem is mounted is appending.  Some filesystems allow
+this to be overridden for a particular process by a properly privileged
+call to @code{ioctl}.  This is a relatively new invention and is not
+available on many filesystems.
+
+@item MS_NOSUID
+This bit on specifies that Setuid and Setgid permissions on files in the
+filesystem shall be ignored while it is mounted.
+
+@item MS_NOEXEC
+This bit on specifies that no files in the filesystem shall be executed
+while the filesystem is mounted.
+
+@item MS_NODEV
+This bit on specifies that no device special files in the filesystem
+shall be accessible while the filesystem is mounted.
+
+@item MS_SYNCHRONOUS
+This bit on specifies that all writes to the filesystem while it is
+mounted shall be synchronous; i.e., data shall be synced before each
+write completes rather than held in the buffer cache.
+
+@item MS_MANDLOCK
+This bit on specifies that mandatory locks on files shall be permitted while
+the filesystem is mounted.
+
+@item MS_NOATIME
+This bit on specifies that access times of files shall not be updated when
+the files are accessed while the filesystem is mounted.
+
+@item MS_NODIRATIME
+This bit on specifies that access times of directories shall not be updated
+when the directories are accessed while the filesystem in mounted.
+
+@c there is also S_QUOTA Linux fs.h (mount.h still uses its former name
+@c S_WRITE), but I can't see what it does.  Turns on quotas, I guess.
+
+@end table
+
+Any bits not covered by the above masks should be set off; otherwise,
+results are undefined.
+
+The meaning of @var{data} depends on the filesystem type and is controlled
+entirely by the filesystem driver in the kernel.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
+
+mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
+
+@end group
+@end smallexample
+
+Appropriate arguments for @code{mount} are conventionally recorded in
+the @file{fstab} table.  @xref{Mount Information}.
+
+The return value is zero if the mount or remount is successful.  Otherwise,
+it is @code{-1} and @code{errno} is set appropriately.  The values of
+@code{errno} are filesystem dependent, but here is a general list:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item ENODEV
+The file system type @var{fstype} is not known to the kernel.
+@item ENOTBLK
+The file @var{dev} is not a block device special file.
+@item EBUSY
+
+@itemize @bullet
+
+@item
+The device is already mounted.
+
+@item
+The mount point is busy.  (E.g. it is some process' working directory or
+has a filesystem mounted on it already).
+
+@item
+The request is to remount read-only, but there are files open for write.
+@end itemize
+
+@item EINVAL
+@itemize @bullet
+
+@item
+A remount was attempted, but there is no filesystem mounted over the
+specified mount point.
+
+@item
+The supposed filesystem has an invalid superblock.
+
+@end itemize
+
+@item EACCES
+@itemize @bullet
+
+@item
+The filesystem is inherently read-only (possibly due to a switch on the
+device) and the process attempted to mount it read/write (by setting the
+@code{MS_RDONLY} bit off).
+
+@item
+@var{special_file} or @var{dir} is not accessible due to file permissions.
+
+@item
+@var{special_file} is not accessible because it is in a filesystem that is
+mounted with the @code{MS_NODEV} option.
+
+@end itemize
+
+@item EM_FILE
+The table of dummy devices is full.  @code{mount} needs to create a
+dummy device (aka ``unnamed'' device) if the filesystem being mounted is
+not one that uses a device.
+
+@end table
+
+@end deftypefun
+
+
+@comment sys/mount.h
+@comment GNU
+@deftypefun {int} umount2 (const char *@var{file}, int @var{flags})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall.
+
+@code{umount2} unmounts a filesystem.
+
+You can identify the filesystem to unmount either by the device special
+file that contains the filesystem or by the mount point.  The effect is
+the same.  Specify either as the string @var{file}.
+
+@var{flags} contains the one-bit field identified by the following
+mask macro:
+
+@table @code
+
+@item MNT_FORCE
+This bit on means to force the unmounting even if the filesystem is
+busy, by making it unbusy first.  If the bit is off and the filesystem is
+busy, @code{umount2} fails with @code{errno} = @code{EBUSY}.  Depending
+on the filesystem, this may override all, some, or no busy conditions.
+
+@end table
+
+All other bits in @var{flags} should be set to zero; otherwise, the result
+is undefined.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+umount2("/mnt", MNT_FORCE);
+
+umount2("/dev/hdd1", 0);
+
+@end group
+@end smallexample
+
+After the filesystem is unmounted, the directory that was the mount point
+is visible, as are any files in it.
+
+As part of unmounting, @code{umount2} syncs the filesystem.
+
+If the unmounting is successful, the return value is zero.  Otherwise, it
+is @code{-1} and @code{errno} is set accordingly:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item EBUSY
+The filesystem cannot be unmounted because it is busy.  E.g. it contains
+a directory that is some process's working directory or a file that some
+process has open.  With some filesystems in some cases, you can avoid
+this failure with the @code{MNT_FORCE} option.
+
+@item EINVAL
+@var{file} validly refers to a file, but that file is neither a mount
+point nor a device special file of a currently mounted filesystem.
+
+@end table
+
+This function is not available on all systems.
+@end deftypefun
+
+@comment sys/mount.h
+@comment SVID, GNU
+@deftypefun {int} umount (const char *@var{file})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall or wrapper for umount2.
+
+@code{umount} does the same thing as @code{umount2} with @var{flags} set
+to zeroes.  It is more widely available than @code{umount2} but since it
+lacks the possibility to forcefully unmount a filesystem is deprecated
+when @code{umount2} is also available.
+@end deftypefun
+
+
+
+@node System Parameters
+@section System Parameters
+
+This section describes the @code{sysctl} function, which gets and sets
+a variety of system parameters.
+
+The symbols used in this section are declared in the file @file{sys/sysctl.h}.
+
+@comment sys/sysctl.h
+@comment BSD
+@deftypefun int sysctl (int *@var{names}, int @var{nlen}, void *@var{oldval}, size_t *@var{oldlenp}, void *@var{newval}, size_t @var{newlen})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall, Linux only.
+
+@code{sysctl} gets or sets a specified system parameter.  There are so
+many of these parameters that it is not practical to list them all here,
+but here are some examples:
+
+@itemize @bullet
+@item network domain name
+@item paging parameters
+@item network Address Resolution Protocol timeout time
+@item maximum number of files that may be open
+@item root filesystem device
+@item when kernel was built
+@end itemize
+
+The set of available parameters depends on the kernel configuration and
+can change while the system is running, particularly when you load and
+unload loadable kernel modules.
+
+The system parameters with which @code{syslog} is concerned are arranged
+in a hierarchical structure like a hierarchical filesystem.  To identify
+a particular parameter, you specify a path through the structure in a
+way analogous to specifying the pathname of a file.  Each component of
+the path is specified by an integer and each of these integers has a
+macro defined for it by @file{sys/sysctl.h}.  @var{names} is the path, in
+the form of an array of integers.  Each component of the path is one
+element of the array, in order.  @var{nlen} is the number of components
+in the path.
+
+For example, the first component of the path for all the paging
+parameters is the value @code{CTL_VM}.  For the free page thresholds, the
+second component of the path is @code{VM_FREEPG}.  So to get the free
+page threshold values, make @var{names} an array containing the two
+elements @code{CTL_VM} and @code{VM_FREEPG} and make @var{nlen} = 2.
+
+
+The format of the value of a parameter depends on the parameter.
+Sometimes it is an integer; sometimes it is an ASCII string; sometimes
+it is an elaborate structure.  In the case of the free page thresholds
+used in the example above, the parameter value is a structure containing
+several integers.
+
+In any case, you identify a place to return the parameter's value with
+@var{oldval} and specify the amount of storage available at that
+location as *@var{oldlenp}.  *@var{oldlenp} does double duty because it
+is also the output location that contains the actual length of the
+returned value.
+
+If you don't want the parameter value returned, specify a null pointer
+for @var{oldval}.
+
+To set the parameter, specify the address and length of the new value
+as @var{newval} and @var{newlen}.  If you don't want to set the parameter,
+specify a null pointer as @var{newval}.
+
+If you get and set a parameter in the same @code{sysctl} call, the value
+returned is the value of the parameter before it was set.
+
+Each system parameter has a set of permissions similar to the
+permissions for a file (including the permissions on directories in its
+path) that determine whether you may get or set it.  For the purposes of
+these permissions, every parameter is considered to be owned by the
+superuser and Group 0 so processes with that effective uid or gid may
+have more access to system parameters.  Unlike with files, the superuser
+does not invariably have full permission to all system parameters, because
+some of them are designed not to be changed ever.
+
+
+@code{sysctl} returns a zero return value if it succeeds.  Otherwise, it
+returns @code{-1} and sets @code{errno} appropriately.  Besides the
+failures that apply to all system calls, the following are the
+@code{errno} codes for all possible failures:
+
+@table @code
+@item EPERM
+The process is not permitted to access one of the components of the
+path of the system parameter or is not permitted to access the system parameter
+itself in the way (read or write) that it requested.
+@c There is some indication in the Linux 2.2 code that the code is trying to
+@c return EACCES here, but the EACCES value never actually makes it to the
+@c user.
+@item ENOTDIR
+There is no system parameter corresponding to @var{name}.
+@item EFAULT
+@var{oldval} is not null, which means the process wanted to read the parameter,
+but *@var{oldlenp} is zero, so there is no place to return it.
+@item EINVAL
+@itemize @bullet
+@item
+The process attempted to set a system parameter to a value that is not valid
+for that parameter.
+@item
+The space provided for the return of the system parameter is not the right
+size for that parameter.
+@end itemize
+@item ENOMEM
+This value may be returned instead of the more correct @code{EINVAL} in some
+cases where the space provided for the return of the system parameter is too
+small.
+
+@end table
+
+@end deftypefun
+
+If you have a Linux kernel with the @code{proc} filesystem, you can get
+and set most of the same parameters by reading and writing to files in
+the @code{sys} directory of the @code{proc} filesystem.  In the @code{sys}
+directory, the directory structure represents the hierarchical structure
+of the parameters.  E.g. you can display the free page thresholds with
+@smallexample
+cat /proc/sys/vm/freepages
+@end smallexample
+@c In Linux, the sysctl() and /proc instances of the parameter are created
+@c together.  The proc filesystem accesses the same data structure as
+@c sysctl(), which has special fields in it for /proc.  But it is still
+@c possible to create a sysctl-only parameter.
+
+Some more traditional and more widely available, though less general,
+@glibcadj{} functions for getting and setting some of the same system
+parameters are:
+
+@itemize @bullet
+@item
+@code{getdomainname}, @code{setdomainname}
+@item
+@code{gethostname}, @code{sethostname} (@xref{Host Identification}.)
+@item
+@code{uname} (@xref{Platform Type}.)
+@end itemize
diff --git a/ap/libc/glibc/glibc-2.23/manual/syslog.texi b/ap/libc/glibc/glibc-2.23/manual/syslog.texi
new file mode 100644
index 0000000..a08e103
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/syslog.texi
@@ -0,0 +1,578 @@
+@node Syslog, Mathematics, Low-Level Terminal Interface, Top
+@c %MENU% System logging and messaging
+@chapter Syslog
+
+
+This chapter describes facilities for issuing and logging messages of
+system administration interest.  This chapter has nothing to do with
+programs issuing messages to their own users or keeping private logs
+(One would typically do that with the facilities described in
+@ref{I/O on Streams}).
+
+Most systems have a facility called ``Syslog'' that allows programs to
+submit messages of interest to system administrators and can be
+configured to pass these messages on in various ways, such as printing
+on the console, mailing to a particular person, or recording in a log
+file for future reference.
+
+A program uses the facilities in this chapter to submit such messages.
+
+@menu
+* Overview of Syslog::           Overview of a system's Syslog facility
+* Submitting Syslog Messages::   Functions to submit messages to Syslog
+@end menu
+
+@node Overview of Syslog
+@section Overview of Syslog
+
+System administrators have to deal with lots of different kinds of
+messages from a plethora of subsystems within each system, and usually
+lots of systems as well.  For example, an FTP server might report every
+connection it gets.  The kernel might report hardware failures on a disk
+drive.  A DNS server might report usage statistics at regular intervals.
+
+Some of these messages need to be brought to a system administrator's
+attention immediately.  And it may not be just any system administrator
+-- there may be a particular system administrator who deals with a
+particular kind of message.  Other messages just need to be recorded for
+future reference if there is a problem.  Still others may need to have
+information extracted from them by an automated process that generates
+monthly reports.
+
+To deal with these messages, most Unix systems have a facility called
+"Syslog."  It is generally based on a daemon called ``Syslogd''
+Syslogd listens for messages on a Unix domain socket named
+@file{/dev/log}.  Based on classification information in the messages
+and its configuration file (usually @file{/etc/syslog.conf}), Syslogd
+routes them in various ways.  Some of the popular routings are:
+
+@itemize @bullet
+@item
+Write to the system console
+@item
+Mail to a specific user
+@item
+Write to a log file
+@item
+Pass to another daemon
+@item
+Discard
+@end itemize
+
+Syslogd can also handle messages from other systems.  It listens on the
+@code{syslog} UDP port as well as the local socket for messages.
+
+Syslog can handle messages from the kernel itself.  But the kernel
+doesn't write to @file{/dev/log}; rather, another daemon (sometimes
+called ``Klogd'') extracts messages from the kernel and passes them on to
+Syslog as any other process would (and it properly identifies them as
+messages from the kernel).
+
+Syslog can even handle messages that the kernel issued before Syslogd or
+Klogd was running.  A Linux kernel, for example, stores startup messages
+in a kernel message ring and they are normally still there when Klogd
+later starts up.  Assuming Syslogd is running by the time Klogd starts,
+Klogd then passes everything in the message ring to it.
+
+In order to classify messages for disposition, Syslog requires any process
+that submits a message to it to provide two pieces of classification
+information with it:
+
+@table @asis
+@item facility
+This identifies who submitted the message.  There are a small number of
+facilities defined.  The kernel, the mail subsystem, and an FTP server
+are examples of recognized facilities.  For the complete list,
+@xref{syslog; vsyslog}.  Keep in mind that these are
+essentially arbitrary classifications.  "Mail subsystem" doesn't have any
+more meaning than the system administrator gives to it.
+
+@item priority
+This tells how important the content of the message is.  Examples of
+defined priority values are: debug, informational, warning, critical.
+For the complete list, see @ref{syslog; vsyslog}.  Except for
+the fact that the priorities have a defined order, the meaning of each
+of these priorities is entirely determined by the system administrator.
+
+@end table
+
+A ``facility/priority'' is a number that indicates both the facility
+and the priority.
+
+@strong{Warning:} This terminology is not universal.  Some people use
+``level'' to refer to the priority and ``priority'' to refer to the
+combination of facility and priority.  A Linux kernel has a concept of a
+message ``level,'' which corresponds both to a Syslog priority and to a
+Syslog facility/priority (It can be both because the facility code for
+the kernel is zero, and that makes priority and facility/priority the
+same value).
+
+@Theglibc{} provides functions to submit messages to Syslog.  They
+do it by writing to the @file{/dev/log} socket.  @xref{Submitting Syslog
+Messages}.
+
+The @glibcadj{} functions only work to submit messages to the Syslog
+facility on the same system.  To submit a message to the Syslog facility
+on another system, use the socket I/O functions to write a UDP datagram
+to the @code{syslog} UDP port on that system.  @xref{Sockets}.
+
+
+@node Submitting Syslog Messages
+@section Submitting Syslog Messages
+
+@Theglibc{} provides functions to submit messages to the Syslog
+facility:
+
+@menu
+* openlog::                      Open connection to Syslog
+* syslog; vsyslog::              Submit message to Syslog
+* closelog::                     Close connection to Syslog
+* setlogmask::                   Cause certain messages to be ignored
+* Syslog Example::               Example of all of the above
+@end menu
+
+These functions only work to submit messages to the Syslog facility on
+the same system.  To submit a message to the Syslog facility on another
+system, use the socket I/O functions to write a UDP datagram to the
+@code{syslog} UDP port on that system.  @xref{Sockets}.
+
+
+
+@node openlog
+@subsection openlog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c openlog @asulock @aculock @acsfd
+@c  libc_lock_lock @asulock @aculock
+@c  openlog_internal @acsfd [always guarded by syslog_lock, so no race]
+@c   strncpy dup ok
+@c   socket dup @acsfd
+@c   fcntl dup ok
+@c   connect dup ok
+@c   close dup @acsfd
+@c  cancel_handler(NULL) @aculock
+@c   libc_lock_unlock @aculock
+
+@code{openlog} opens or reopens a connection to Syslog in preparation
+for submitting messages.
+
+@var{ident} is an arbitrary identification string which future
+@code{syslog} invocations will prefix to each message.  This is intended
+to identify the source of the message, and people conventionally set it
+to the name of the program that will submit the messages.
+
+If @var{ident} is NULL, or if @code{openlog} is not called, the default
+identification string used in Syslog messages will be the program name,
+taken from argv[0].
+
+Please note that the string pointer @var{ident} will be retained
+internally by the Syslog routines.  You must not free the memory that
+@var{ident} points to.  It is also dangerous to pass a reference to an
+automatic variable since leaving the scope would mean ending the
+lifetime of the variable.  If you want to change the @var{ident} string,
+you must call @code{openlog} again; overwriting the string pointed to by
+@var{ident} is not thread-safe.
+
+You can cause the Syslog routines to drop the reference to @var{ident} and
+go back to the default string (the program name taken from argv[0]), by
+calling @code{closelog}: @xref{closelog}.
+
+In particular, if you are writing code for a shared library that might get
+loaded and then unloaded (e.g. a PAM module), and you use @code{openlog},
+you must call @code{closelog} before any point where your library might
+get unloaded, as in this example:
+
+@smallexample
+#include <syslog.h>
+
+void
+shared_library_function (void)
+@{
+  openlog ("mylibrary", option, priority);
+
+  syslog (LOG_INFO, "shared library has been invoked");
+
+  closelog ();
+@}
+@end smallexample
+
+Without the call to @code{closelog}, future invocations of @code{syslog}
+by the program using the shared library may crash, if the library gets
+unloaded and the memory containing the string @code{"mylibrary"} becomes
+unmapped.  This is a limitation of the BSD syslog interface.
+
+@code{openlog} may or may not open the @file{/dev/log} socket, depending
+on @var{option}.  If it does, it tries to open it and connect it as a
+stream socket.  If that doesn't work, it tries to open it and connect it
+as a datagram socket.  The socket has the ``Close on Exec'' attribute,
+so the kernel will close it if the process performs an exec.
+
+You don't have to use @code{openlog}.  If you call @code{syslog} without
+having called @code{openlog}, @code{syslog} just opens the connection
+implicitly and uses defaults for the information in @var{ident} and
+@var{options}.
+
+@var{options} is a bit string, with the bits as defined by the following
+single bit masks:
+
+@table @code
+@item LOG_PERROR
+If on, @code{openlog} sets up the connection so that any @code{syslog}
+on this connection writes its message to the calling process' Standard
+Error stream in addition to submitting it to Syslog.  If off, @code{syslog}
+does not write the message to Standard Error.
+
+@item LOG_CONS
+If on, @code{openlog} sets up the connection so that a @code{syslog} on
+this connection that fails to submit a message to Syslog writes the
+message instead to system console.  If off, @code{syslog} does not write
+to the system console (but of course Syslog may write messages it
+receives to the console).
+
+@item LOG_PID
+When on, @code{openlog} sets up the connection so that a @code{syslog}
+on this connection inserts the calling process' Process ID (PID) into
+the message.  When off, @code{openlog} does not insert the PID.
+
+@item LOG_NDELAY
+When on, @code{openlog} opens and connects the @file{/dev/log} socket.
+When off, a future @code{syslog} call must open and connect the socket.
+
+@strong{Portability note:}  In early systems, the sense of this bit was
+exactly the opposite.
+
+@item LOG_ODELAY
+This bit does nothing.  It exists for backward compatibility.
+
+@end table
+
+If any other bit in @var{options} is on, the result is undefined.
+
+@var{facility} is the default facility code for this connection.  A
+@code{syslog} on this connection that specifies default facility causes
+this facility to be associated with the message.  See @code{syslog} for
+possible values.  A value of zero means the default default, which is
+@code{LOG_USER}.
+
+If a Syslog connection is already open when you call @code{openlog},
+@code{openlog} ``reopens'' the connection.  Reopening is like opening
+except that if you specify zero for the default facility code, the
+default facility code simply remains unchanged and if you specify
+LOG_NDELAY and the socket is already open and connected, @code{openlog}
+just leaves it that way.
+
+@c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the
+@c default log facility to LOG_USER, which means the default default log
+@c facility could be whatever the default log facility was for a previous
+@c Syslog connection.  I have documented what the function should be rather
+@c than what it is because I think if anyone ever gets concerned, the code
+@c will change.
+
+@end deftypefun
+
+
+@node syslog; vsyslog
+@subsection syslog, vsyslog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@c syslog() is implemented as a call to vsyslog().
+@comment syslog.h
+@comment BSD
+@deftypefun void syslog (int @var{facility_priority}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c syslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  va_start dup ok
+@c  vsyslog_chk @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   syslog(INTERNALLOG) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   open_memstream @ascuheap @acsmem
+@c   stpcpy dup ok
+@c   getpid dup ok
+@c   mempcpy dup ok
+@c   fsetlocking [no @mtasurace:stream @asulock for exclusive stream]
+@c   fprintf @mtslocale @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt on temp memstream]
+@c   time dup ok
+@c   localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   strftime_l(C) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   ftell dup ok [no @asucorrupt @aculock @acucorrupt on temp memstream]
+@c   fputs_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c   putc_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c   vfprintf/vfprintf_chk dup @mtslocale @ascuheap @acsmem [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c   fclose dup @ascuheap @acsmem [no @asulock @aculock @acsfd on caller-locked memstream]
+@c   writev dup ok
+@c   libc_lock_lock dup @asulock @aculock
+@c   memset dup ok
+@c   sigemptyset dup ok
+@c   sigaction(SIGPIPE) dup @mtasusig:PIPE @acusig:PIPE
+@c   openlog_internal dup @acsfd
+@c   send dup ok
+@c   closelog_internal dup @acsfd
+@c   open dup @acsfd
+@c   dprintf dup ok
+@c   libc_lock_unlock @asulock @aculock
+@c   free dup @acsuheap @acsmem
+@c  va_end dup ok
+
+@code{syslog} submits a message to the Syslog facility.  It does this by
+writing to the Unix domain socket @code{/dev/log}.
+
+@code{syslog} submits the message with the facility and priority indicated
+by @var{facility_priority}.  The macro @code{LOG_MAKEPRI} generates a
+facility/priority from a facility and a priority, as in the following
+example:
+
+@smallexample
+LOG_MAKEPRI(LOG_USER, LOG_WARNING)
+@end smallexample
+
+The possible values for the facility code are (macros):
+
+@c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means
+@c if you try to use it here, just selects default.
+
+@vtable @code
+@item LOG_USER
+A miscellaneous user process
+@item LOG_MAIL
+Mail
+@item LOG_DAEMON
+A miscellaneous system daemon
+@item LOG_AUTH
+Security (authorization)
+@item LOG_SYSLOG
+Syslog
+@item LOG_LPR
+Central printer
+@item LOG_NEWS
+Network news (e.g. Usenet)
+@item LOG_UUCP
+UUCP
+@item LOG_CRON
+Cron and At
+@item LOG_AUTHPRIV
+Private security (authorization)
+@item LOG_FTP
+Ftp server
+@item LOG_LOCAL0
+Locally defined
+@item LOG_LOCAL1
+Locally defined
+@item LOG_LOCAL2
+Locally defined
+@item LOG_LOCAL3
+Locally defined
+@item LOG_LOCAL4
+Locally defined
+@item LOG_LOCAL5
+Locally defined
+@item LOG_LOCAL6
+Locally defined
+@item LOG_LOCAL7
+Locally defined
+@end vtable
+
+Results are undefined if the facility code is anything else.
+
+@strong{NB:} @code{syslog} recognizes one other facility code: that of
+the kernel.  But you can't specify that facility code with these
+functions.  If you try, it looks the same to @code{syslog} as if you are
+requesting the default facility.  But you wouldn't want to anyway,
+because any program that uses @theglibc{} is not the kernel.
+
+You can use just a priority code as @var{facility_priority}.  In that
+case, @code{syslog} assumes the default facility established when the
+Syslog connection was opened.  @xref{Syslog Example}.
+
+The possible values for the priority code are (macros):
+
+@vtable @code
+@item LOG_EMERG
+The message says the system is unusable.
+@item LOG_ALERT
+Action on the message must be taken immediately.
+@item LOG_CRIT
+The message states a critical condition.
+@item LOG_ERR
+The message describes an error.
+@item LOG_WARNING
+The message is a warning.
+@item LOG_NOTICE
+The message describes a normal but important event.
+@item LOG_INFO
+The message is purely informational.
+@item LOG_DEBUG
+The message is only for debugging purposes.
+@end vtable
+
+Results are undefined if the priority code is anything else.
+
+If the process does not presently have a Syslog connection open (i.e.,
+it did not call @code{openlog}), @code{syslog} implicitly opens the
+connection the same as @code{openlog} would, with the following defaults
+for information that would otherwise be included in an @code{openlog}
+call: The default identification string is the program name.  The
+default default facility is @code{LOG_USER}.  The default for all the
+connection options in @var{options} is as if those bits were off.
+@code{syslog} leaves the Syslog connection open.
+
+If the @file{/dev/log} socket is not open and connected, @code{syslog}
+opens and connects it, the same as @code{openlog} with the
+@code{LOG_NDELAY} option would.
+
+@code{syslog} leaves @file{/dev/log} open and connected unless its attempt
+to send the message failed, in which case @code{syslog} closes it (with the
+hope that a future implicit open will restore the Syslog connection to a
+usable state).
+
+Example:
+
+@smallexample
+
+#include <syslog.h>
+syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
+        "Unable to make network connection to %s.  Error=%m", host);
+
+@end smallexample
+
+@end deftypefun
+
+
+@comment syslog.h
+@comment BSD
+@deftypefun void vsyslog (int @var{facility_priority}, const char *@var{format}, va_list @var{arglist})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c vsyslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  vsyslog_chk dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+
+This is functionally identical to @code{syslog}, with the BSD style variable
+length argument.
+
+@end deftypefun
+
+
+@node closelog
+@subsection closelog
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun void closelog (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c closelog @asulock @aculock @acsfd
+@c  libc_lock_lock @asulock @aculock
+@c  closelog_internal @acsfd [always guarded by syslog_lock, so no race]
+@c   close dup@acsfd
+@c  cancel_handler(NULL) @aculock
+@c   libc_lock_unlock @aculock
+
+@code{closelog} closes the current Syslog connection, if there is one.
+This includes closing the @file{/dev/log} socket, if it is open.
+@code{closelog} also sets the identification string for Syslog messages
+back to the default, if @code{openlog} was called with a non-NULL argument
+to @var{ident}.  The default identification string is the program name
+taken from argv[0].
+
+If you are writing shared library code that uses @code{openlog} to
+generate custom syslog output, you should use @code{closelog} to drop
+@theglibc{}'s internal reference to the @var{ident} pointer when you are
+done.  Please read the section on @code{openlog} for more information:
+@xref{openlog}.
+
+@code{closelog} does not flush any buffers.  You do not have to call
+@code{closelog} before re-opening a Syslog connection with @code{openlog}.
+Syslog connections are automatically closed on exec or exit.
+
+@end deftypefun
+
+
+@node setlogmask
+@subsection setlogmask
+
+The symbols referred to in this section are declared in the file
+@file{syslog.h}.
+
+@comment syslog.h
+@comment BSD
+@deftypefun int setlogmask (int @var{mask})
+@safety{@prelim{}@mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{}}
+@c Read and modify are not guarded by syslog_lock, so concurrent changes
+@c or even uses are undefined.  This should use an atomic swap instead,
+@c at least for modifications.
+
+@code{setlogmask} sets a mask (the ``logmask'') that determines which
+future @code{syslog} calls shall be ignored.  If a program has not
+called @code{setlogmask}, @code{syslog} doesn't ignore any calls.  You
+can use @code{setlogmask} to specify that messages of particular
+priorities shall be ignored in the future.
+
+A @code{setlogmask} call overrides any previous @code{setlogmask} call.
+
+Note that the logmask exists entirely independently of opening and
+closing of Syslog connections.
+
+Setting the logmask has a similar effect to, but is not the same as,
+configuring Syslog.  The Syslog configuration may cause Syslog to
+discard certain messages it receives, but the logmask causes certain
+messages never to get submitted to Syslog in the first place.
+
+@var{mask} is a bit string with one bit corresponding to each of the
+possible message priorities.  If the bit is on, @code{syslog} handles
+messages of that priority normally.  If it is off, @code{syslog}
+discards messages of that priority.  Use the message priority macros
+described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct
+an appropriate @var{mask} value, as in this example:
+
+@smallexample
+LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)
+@end smallexample
+
+or
+
+@smallexample
+~(LOG_MASK(LOG_INFO))
+@end smallexample
+
+There is also a @code{LOG_UPTO} macro, which generates a mask with the bits
+on for a certain priority and all priorities above it:
+
+@smallexample
+LOG_UPTO(LOG_ERROR)
+@end smallexample
+
+The unfortunate naming of the macro is due to the fact that internally,
+higher numbers are used for lower message priorities.
+
+@end deftypefun
+
+
+@node Syslog Example
+@subsection Syslog Example
+
+Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}:
+
+This example sets the logmask so that debug and informational messages
+get discarded without ever reaching Syslog.  So the second @code{syslog}
+in the example does nothing.
+
+@smallexample
+#include <syslog.h>
+
+setlogmask (LOG_UPTO (LOG_NOTICE));
+
+openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
+
+syslog (LOG_NOTICE, "Program started by User %d", getuid ());
+syslog (LOG_INFO, "A tree falls in a forest");
+
+closelog ();
+
+@end smallexample
diff --git a/ap/libc/glibc/glibc-2.23/manual/terminal.texi b/ap/libc/glibc/glibc-2.23/manual/terminal.texi
new file mode 100644
index 0000000..0f0354b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/terminal.texi
@@ -0,0 +1,2307 @@
+@node Low-Level Terminal Interface, Syslog, Sockets, Top
+@c %MENU% How to change the characteristics of a terminal device
+@chapter Low-Level Terminal Interface
+
+This chapter describes functions that are specific to terminal devices.
+You can use these functions to do things like turn off input echoing;
+set serial line characteristics such as line speed and flow control; and
+change which characters are used for end-of-file, command-line editing,
+sending signals, and similar control functions.
+
+Most of the functions in this chapter operate on file descriptors.
+@xref{Low-Level I/O}, for more information about what a file
+descriptor is and how to open a file descriptor for a terminal device.
+
+@menu
+* Is It a Terminal::            How to determine if a file is a terminal
+			         device, and what its name is.
+* I/O Queues::                  About flow control and typeahead.
+* Canonical or Not::            Two basic styles of input processing.
+* Terminal Modes::              How to examine and modify flags controlling
+			         details of terminal I/O: echoing,
+                                 signals, editing.  Posix.
+* BSD Terminal Modes::          BSD compatible terminal mode setting
+* Line Control::                Sending break sequences, clearing
+                                 terminal buffers @dots{}
+* Noncanon Example::            How to read single characters without echo.
+* Pseudo-Terminals::            How to open a pseudo-terminal.
+@end menu
+
+@node Is It a Terminal
+@section Identifying Terminals
+@cindex terminal identification
+@cindex identifying terminals
+
+The functions described in this chapter only work on files that
+correspond to terminal devices.  You can find out whether a file
+descriptor is associated with a terminal by using the @code{isatty}
+function.
+
+@pindex unistd.h
+Prototypes for the functions in this section are declared in the header
+file @file{unistd.h}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int isatty (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c isatty ok
+@c  tcgetattr dup ok
+This function returns @code{1} if @var{filedes} is a file descriptor
+associated with an open terminal device, and @math{0} otherwise.
+@end deftypefun
+
+If a file descriptor is associated with a terminal, you can get its
+associated file name using the @code{ttyname} function.  See also the
+@code{ctermid} function, described in @ref{Identifying the Terminal}.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {char *} ttyname (int @var{filedes})
+@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
+@c  isatty dup ok
+@c  fstat dup ok
+@c  memcpy dup ok
+@c  getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
+@c   opendir @ascuheap @acsmem @acsfd
+@c   readdir ok [protected by exclusive access]
+@c   strcmp dup ok
+@c   free dup @asulock @aculock @acsfd @acsmem
+@c   malloc dup @asulock @aculock @acsfd @acsmem
+@c   closedir @ascuheap @acsmem @acsfd
+@c   mempcpy dup ok
+@c   stat dup ok
+If the file descriptor @var{filedes} is associated with a terminal
+device, the @code{ttyname} function returns a pointer to a
+statically-allocated, null-terminated string containing the file name of
+the terminal file.  The value is a null pointer if the file descriptor
+isn't associated with a terminal, or the file name cannot be determined.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
+@c ttyname_r @ascuheap @acsmem @acsfd
+@c  isatty dup ok
+@c  fstat dup ok
+@c  memcpy dup ok
+@c  getttyname_r @ascuheap @acsmem @acsfd
+@c   opendir @ascuheap @acsmem @acsfd
+@c   readdir ok [protected by exclusive access]
+@c   strcmp dup ok
+@c   closedir @ascuheap @acsmem @acsfd
+@c   stpncpy dup ok
+@c   stat dup ok
+The @code{ttyname_r} function is similar to the @code{ttyname} function
+except that it places its result into the user-specified buffer starting
+at @var{buf} with length @var{len}.
+
+The normal return value from @code{ttyname_r} is @math{0}.  Otherwise an
+error number is returned to indicate the error.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal.
+
+@item ERANGE
+The buffer length @var{len} is too small to store the string to be
+returned.
+@end table
+@end deftypefun
+
+@node I/O Queues
+@section I/O Queues
+
+Many of the remaining functions in this section refer to the input and
+output queues of a terminal device.  These queues implement a form of
+buffering @emph{within the kernel} independent of the buffering
+implemented by I/O streams (@pxref{I/O on Streams}).
+
+@cindex terminal input queue
+@cindex typeahead buffer
+The @dfn{terminal input queue} is also sometimes referred to as its
+@dfn{typeahead buffer}.  It holds the characters that have been received
+from the terminal but not yet read by any process.
+
+The size of the input queue is described by the @code{MAX_INPUT} and
+@w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits for Files}.  You
+are guaranteed a queue size of at least @code{MAX_INPUT}, but the queue
+might be larger, and might even dynamically change size.  If input flow
+control is enabled by setting the @code{IXOFF} input mode bit
+(@pxref{Input Modes}), the terminal driver transmits STOP and START
+characters to the terminal when necessary to prevent the queue from
+overflowing.  Otherwise, input may be lost if it comes in too fast from
+the terminal.  In canonical mode, all input stays in the queue until a
+newline character is received, so the terminal input queue can fill up
+when you type a very long line.  @xref{Canonical or Not}.
+
+@cindex terminal output queue
+The @dfn{terminal output queue} is like the input queue, but for output;
+it contains characters that have been written by processes, but not yet
+transmitted to the terminal.  If output flow control is enabled by
+setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
+terminal driver obeys START and STOP characters sent by the terminal to
+stop and restart transmission of output.
+
+@dfn{Clearing} the terminal input queue means discarding any characters
+that have been received but not yet read.  Similarly, clearing the
+terminal output queue means discarding any characters that have been
+written but not yet transmitted.
+
+@node Canonical or Not
+@section Two Styles of Input: Canonical or Not
+
+POSIX systems support two basic modes of input: canonical and
+noncanonical.
+
+@cindex canonical input processing
+In @dfn{canonical input processing} mode, terminal input is processed in
+lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No
+input can be read until an entire line has been typed by the user, and
+the @code{read} function (@pxref{I/O Primitives}) returns at most a
+single line of input, no matter how many bytes are requested.
+
+In canonical input mode, the operating system provides input editing
+facilities: some characters are interpreted specially to perform editing
+operations within the current line of text, such as ERASE and KILL.
+@xref{Editing Characters}.
+
+The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
+the maximum number of bytes which may appear in a single line of
+canonical input.  @xref{Limits for Files}.  You are guaranteed a maximum
+line length of at least @code{MAX_CANON} bytes, but the maximum might be
+larger, and might even dynamically change size.
+
+@cindex noncanonical input processing
+In @dfn{noncanonical input processing} mode, characters are not grouped
+into lines, and ERASE and KILL processing is not performed.  The
+granularity with which bytes are read in noncanonical input mode is
+controlled by the MIN and TIME settings.  @xref{Noncanonical Input}.
+
+Most programs use canonical input mode, because this gives the user a
+way to edit input line by line.  The usual reason to use noncanonical
+mode is when the program accepts single-character commands or provides
+its own editing facilities.
+
+The choice of canonical or noncanonical input is controlled by the
+@code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.
+@xref{Local Modes}.
+
+@node Terminal Modes
+@section Terminal Modes
+
+@pindex termios.h
+This section describes the various terminal attributes that control how
+input and output are done.  The functions, data structures, and symbolic
+constants are all declared in the header file @file{termios.h}.
+
+Don't confuse terminal attributes with file attributes.  A device special
+file which is associated with a terminal has file attributes as described
+in @ref{File Attributes}.  These are unrelated to the attributes of the
+terminal device itself, which are discussed in this section.
+
+@menu
+* 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.
+@end menu
+
+@node Mode Data Types
+@subsection Terminal Mode Data Types
+@cindex terminal mode data types
+
+The entire collection of attributes of a terminal is stored in a
+structure of type @code{struct termios}.  This structure is used
+with the functions @code{tcgetattr} and @code{tcsetattr} to read
+and set the attributes.
+
+@comment termios.h
+@comment POSIX.1
+@deftp {Data Type} {struct termios}
+Structure that records all the I/O attributes of a terminal.  The
+structure includes at least the following members:
+
+@table @code
+@item tcflag_t c_iflag
+A bit mask specifying flags for input modes; see @ref{Input Modes}.
+
+@item tcflag_t c_oflag
+A bit mask specifying flags for output modes; see @ref{Output Modes}.
+
+@item tcflag_t c_cflag
+A bit mask specifying flags for control modes; see @ref{Control Modes}.
+
+@item tcflag_t c_lflag
+A bit mask specifying flags for local modes; see @ref{Local Modes}.
+
+@item cc_t c_cc[NCCS]
+An array specifying which characters are associated with various
+control functions; see @ref{Special Characters}.
+@end table
+
+The @code{struct termios} structure also contains members which
+encode input and output transmission speeds, but the representation is
+not specified.  @xref{Line Speed}, for how to examine and store the
+speed values.
+@end deftp
+
+The following sections describe the details of the members of the
+@code{struct termios} structure.
+
+@comment termios.h
+@comment POSIX.1
+@deftp {Data Type} tcflag_t
+This is an unsigned integer type used to represent the various
+bit masks for terminal flags.
+@end deftp
+
+@comment termios.h
+@comment POSIX.1
+@deftp {Data Type} cc_t
+This is an unsigned integer type used to represent characters associated
+with various terminal control functions.
+@end deftp
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int NCCS
+The value of this macro is the number of elements in the @code{c_cc}
+array.
+@end deftypevr
+
+@node Mode Functions
+@subsection Terminal Mode Functions
+@cindex terminal mode functions
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Converting the kernel-returned termios data structure to the userland
+@c format does not ensure atomic or consistent writing.
+This function is used to examine the attributes of the terminal
+device with file descriptor @var{filedes}.  The attributes are returned
+in the structure that @var{termios-p} points to.
+
+If successful, @code{tcgetattr} returns @math{0}.  A return value of @math{-1}
+indicates an error.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal.
+@end table
+@end deftypefun
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Converting the incoming termios data structure to the kernel format
+@c does not ensure atomic or consistent reading.
+This function sets the attributes of the terminal device with file
+descriptor @var{filedes}.  The new attributes are taken from the
+structure that @var{termios-p} points to.
+
+The @var{when} argument specifies how to deal with input and output
+already queued.  It can be one of the following values:
+
+@table @code
+@comment termios.h
+@comment POSIX.1
+@item TCSANOW
+@vindex TCSANOW
+Make the change immediately.
+
+@comment termios.h
+@comment POSIX.1
+@item TCSADRAIN
+@vindex TCSADRAIN
+Make the change after waiting until all queued output has been written.
+You should usually use this option when changing parameters that affect
+output.
+
+@comment termios.h
+@comment POSIX.1
+@item TCSAFLUSH
+@vindex TCSAFLUSH
+This is like @code{TCSADRAIN}, but also discards any queued input.
+
+@comment termios.h
+@comment BSD
+@item TCSASOFT
+@vindex TCSASOFT
+This is a flag bit that you can add to any of the above alternatives.
+Its meaning is to inhibit alteration of the state of the terminal
+hardware.  It is a BSD extension; it is only supported on BSD systems
+and @gnuhurdsystems{}.
+
+Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}
+bit in the @code{c_cflag} member of the structure @var{termios-p} points
+to.  @xref{Control Modes}, for a description of @code{CIGNORE}.
+@end table
+
+If this function is called from a background process on its controlling
+terminal, normally all processes in the process group are sent a
+@code{SIGTTOU} signal, in the same way as if the process were trying to
+write to the terminal.  The exception is if the calling process itself
+is ignoring or blocking @code{SIGTTOU} signals, in which case the
+operation is performed and no signal is sent.  @xref{Job Control}.
+
+If successful, @code{tcsetattr} returns @math{0}.  A return value of
+@math{-1} indicates an error.  The following @code{errno} error
+conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal.
+
+@item EINVAL
+Either the value of the @code{when} argument is not valid, or there is
+something wrong with the data in the @var{termios-p} argument.
+@end table
+@end deftypefun
+
+Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
+device with a file descriptor, the attributes are those of the terminal
+device itself and not of the file descriptor.  This means that the
+effects of changing terminal attributes are persistent; if another
+process opens the terminal file later on, it will see the changed
+attributes even though it doesn't have anything to do with the open file
+descriptor you originally specified in changing the attributes.
+
+Similarly, if a single process has multiple or duplicated file
+descriptors for the same terminal device, changing the terminal
+attributes affects input and output to all of these file
+descriptors.  This means, for example, that you can't open one file
+descriptor or stream to read from a terminal in the normal
+line-buffered, echoed mode; and simultaneously have another file
+descriptor for the same terminal that you use to read from it in
+single-character, non-echoed mode.  Instead, you have to explicitly
+switch the terminal back and forth between the two modes.
+
+@node Setting Modes
+@subsection Setting Terminal Modes Properly
+
+When you set terminal modes, you should call @code{tcgetattr} first to
+get the current modes of the particular terminal device, modify only
+those modes that you are really interested in, and store the result with
+@code{tcsetattr}.
+
+It's a bad idea to simply initialize a @code{struct termios} structure
+to a chosen set of attributes and pass it directly to @code{tcsetattr}.
+Your program may be run years from now, on systems that support members
+not documented in this manual.  The way to avoid setting these members
+to unreasonable values is to avoid changing them.
+
+What's more, different terminal devices may require different mode
+settings in order to function properly.  So you should avoid blindly
+copying attributes from one terminal device to another.
+
+When a member contains a collection of independent flags, as the
+@code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
+setting the entire member is a bad idea, because particular operating
+systems have their own flags.  Instead, you should start with the
+current value of the member and alter only the flags whose values matter
+in your program, leaving any other flags unchanged.
+
+Here is an example of how to set one flag (@code{ISTRIP}) in the
+@code{struct termios} structure while properly preserving all the other
+data in the structure:
+
+@smallexample
+@group
+int
+set_istrip (int desc, int value)
+@{
+  struct termios settings;
+  int result;
+@end group
+
+@group
+  result = tcgetattr (desc, &settings);
+  if (result < 0)
+    @{
+      perror ("error in tcgetattr");
+      return 0;
+    @}
+@end group
+@group
+  settings.c_iflag &= ~ISTRIP;
+  if (value)
+    settings.c_iflag |= ISTRIP;
+@end group
+@group
+  result = tcsetattr (desc, TCSANOW, &settings);
+  if (result < 0)
+    @{
+      perror ("error in tcsetattr");
+      return 0;
+   @}
+  return 1;
+@}
+@end group
+@end smallexample
+
+@node Input Modes
+@subsection Input Modes
+
+This section describes the terminal attribute flags that control
+fairly low-level aspects of input processing: handling of parity errors,
+break signals, flow control, and @key{RET} and @key{LFD} characters.
+
+All of these flags are bits in the @code{c_iflag} member of the
+@code{struct termios} structure.  The member is an integer, and you
+change flags using the operators @code{&}, @code{|} and @code{^}.  Don't
+try to specify the entire value for @code{c_iflag}---instead, change
+only specific flags and leave the rest untouched (@pxref{Setting
+Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t INPCK
+@cindex parity checking
+If this bit is set, input parity checking is enabled.  If it is not set,
+no checking at all is done for parity errors on input; the
+characters are simply passed through to the application.
+
+Parity checking on input processing is independent of whether parity
+detection and generation on the underlying terminal hardware is enabled;
+see @ref{Control Modes}.  For example, you could clear the @code{INPCK}
+input mode flag and set the @code{PARENB} control mode flag to ignore
+parity errors on input, but still generate parity on output.
+
+If this bit is set, what happens when a parity error is detected depends
+on whether the @code{IGNPAR} or @code{PARMRK} bits are set.  If neither
+of these bits are set, a byte with a parity error is passed to the
+application as a @code{'\0'} character.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IGNPAR
+If this bit is set, any byte with a framing or parity error is ignored.
+This is only useful if @code{INPCK} is also set.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t PARMRK
+If this bit is set, input bytes with parity or framing errors are marked
+when passed to the program.  This bit is meaningful only when
+@code{INPCK} is set and @code{IGNPAR} is not set.
+
+The way erroneous bytes are marked is with two preceding bytes,
+@code{377} and @code{0}.  Thus, the program actually reads three bytes
+for one erroneous byte received from the terminal.
+
+If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)
+is not set, the program might confuse it with the prefix that marks a
+parity error.  So a valid byte @code{0377} is passed to the program as
+two bytes, @code{0377} @code{0377}, in this case.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ISTRIP
+If this bit is set, valid input bytes are stripped to seven bits;
+otherwise, all eight bits are available for programs to read.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IGNBRK
+If this bit is set, break conditions are ignored.
+
+@cindex break condition, detecting
+A @dfn{break condition} is defined in the context of asynchronous
+serial data transmission as a series of zero-value bits longer than a
+single byte.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t BRKINT
+If this bit is set and @code{IGNBRK} is not set, a break condition
+clears the terminal input and output queues and raises a @code{SIGINT}
+signal for the foreground process group associated with the terminal.
+
+If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
+passed to the application as a single @code{'\0'} character if
+@code{PARMRK} is not set, or otherwise as a three-character sequence
+@code{'\377'}, @code{'\0'}, @code{'\0'}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IGNCR
+If this bit is set, carriage return characters (@code{'\r'}) are
+discarded on input.  Discarding carriage return may be useful on
+terminals that send both carriage return and linefeed when you type the
+@key{RET} key.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ICRNL
+If this bit is set and @code{IGNCR} is not set, carriage return characters
+(@code{'\r'}) received as input are passed to the application as newline
+characters (@code{'\n'}).
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t INLCR
+If this bit is set, newline characters (@code{'\n'}) received as input
+are passed to the application as carriage return characters (@code{'\r'}).
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IXOFF
+If this bit is set, start/stop control on input is enabled.  In other
+words, the computer sends STOP and START characters as necessary to
+prevent input from coming in faster than programs are reading it.  The
+idea is that the actual terminal hardware that is generating the input
+data responds to a STOP character by suspending transmission, and to a
+START character by resuming transmission.  @xref{Start/Stop Characters}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IXON
+If this bit is set, start/stop control on output is enabled.  In other
+words, if the computer receives a STOP character, it suspends output
+until a START character is received.  In this case, the STOP and START
+characters are never passed to the application program.  If this bit is
+not set, then START and STOP can be read as ordinary characters.
+@xref{Start/Stop Characters}.
+@c !!! mention this interferes with using C-s and C-q for programs like emacs
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t IXANY
+If this bit is set, any input character restarts output when output has
+been suspended with the STOP character.  Otherwise, only the START
+character restarts output.
+
+This is a BSD extension; it exists only on BSD systems and
+@gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t IMAXBEL
+If this bit is set, then filling up the terminal input buffer sends a
+BEL character (code @code{007}) to the terminal to ring the bell.
+
+This is a BSD extension.
+@end deftypevr
+
+@node Output Modes
+@subsection Output Modes
+
+This section describes the terminal flags and fields that control how
+output characters are translated and padded for display.  All of these
+are contained in the @code{c_oflag} member of the @w{@code{struct termios}}
+structure.
+
+The @code{c_oflag} member itself is an integer, and you change the flags
+and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
+try to specify the entire value for @code{c_oflag}---instead, change
+only specific flags and leave the rest untouched (@pxref{Setting
+Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t OPOST
+If this bit is set, output data is processed in some unspecified way so
+that it is displayed appropriately on the terminal device.  This
+typically includes mapping newline characters (@code{'\n'}) onto
+carriage return and linefeed pairs.
+
+If this bit isn't set, the characters are transmitted as-is.
+@end deftypevr
+
+The following three bits are effective only if @code{OPOST} is set.
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ONLCR
+If this bit is set, convert the newline character on output into a pair
+of characters, carriage return followed by linefeed.
+@end deftypevr
+
+@comment termios.h (optional)
+@comment BSD
+@deftypevr Macro tcflag_t OXTABS
+If this bit is set, convert tab characters on output into the appropriate
+number of spaces to emulate a tab stop every eight columns.  This bit
+exists only on BSD systems and @gnuhurdsystems{}; on
+@gnulinuxsystems{} it is available as @code{XTABS}.
+@end deftypevr
+
+@comment termios.h (optional)
+@comment BSD
+@deftypevr Macro tcflag_t ONOEOT
+If this bit is set, discard @kbd{C-d} characters (code @code{004}) on
+output.  These characters cause many dial-up terminals to disconnect.
+This bit exists only on BSD systems and @gnuhurdsystems{}.
+@end deftypevr
+
+@node Control Modes
+@subsection Control Modes
+
+This section describes the terminal flags and fields that control
+parameters usually associated with asynchronous serial data
+transmission.  These flags may not make sense for other kinds of
+terminal ports (such as a network connection pseudo-terminal).  All of
+these are contained in the @code{c_cflag} member of the @code{struct
+termios} structure.
+
+The @code{c_cflag} member itself is an integer, and you change the flags
+and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
+try to specify the entire value for @code{c_cflag}---instead, change
+only specific flags and leave the rest untouched (@pxref{Setting
+Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CLOCAL
+If this bit is set, it indicates that the terminal is connected
+``locally'' and that the modem status lines (such as carrier detect)
+should be ignored.
+@cindex modem status lines
+@cindex carrier detect
+
+On many systems if this bit is not set and you call @code{open} without
+the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
+connection is established.
+
+If this bit is not set and a modem disconnect is detected, a
+@code{SIGHUP} signal is sent to the controlling process group for the
+terminal (if it has one).  Normally, this causes the process to exit;
+see @ref{Signal Handling}.  Reading from the terminal after a disconnect
+causes an end-of-file condition, and writing causes an @code{EIO} error
+to be returned.  The terminal device must be closed and reopened to
+clear the condition.
+@cindex modem disconnect
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t HUPCL
+If this bit is set, a modem disconnect is generated when all processes
+that have the terminal device open have either closed the file or exited.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CREAD
+If this bit is set, input can be read from the terminal.  Otherwise,
+input is discarded when it arrives.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CSTOPB
+If this bit is set, two stop bits are used.  Otherwise, only one stop bit
+is used.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t PARENB
+If this bit is set, generation and detection of a parity bit are enabled.
+@xref{Input Modes}, for information on how input parity errors are handled.
+
+If this bit is not set, no parity bit is added to output characters, and
+input characters are not checked for correct parity.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t PARODD
+This bit is only useful if @code{PARENB} is set.  If @code{PARODD} is set,
+odd parity is used, otherwise even parity is used.
+@end deftypevr
+
+The control mode flags also includes a field for the number of bits per
+character.  You can use the @code{CSIZE} macro as a mask to extract the
+value, like this: @code{settings.c_cflag & CSIZE}.
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CSIZE
+This is a mask for the number of bits per character.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CS5
+This specifies five bits per byte.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CS6
+This specifies six bits per byte.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CS7
+This specifies seven bits per byte.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t CS8
+This specifies eight bits per byte.
+@end deftypevr
+
+The following four bits are BSD extensions; these exist only on BSD
+systems and @gnuhurdsystems{}.
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t CCTS_OFLOW
+If this bit is set, enable flow control of output based on the CTS wire
+(RS232 protocol).
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t CRTS_IFLOW
+If this bit is set, enable flow control of input based on the RTS wire
+(RS232 protocol).
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t MDMBUF
+If this bit is set, enable carrier-based flow control of output.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t CIGNORE
+If this bit is set, it says to ignore the control modes and line speed
+values entirely.  This is only meaningful in a call to @code{tcsetattr}.
+
+The @code{c_cflag} member and the line speed values returned by
+@code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the
+call.  @code{CIGNORE} is useful if you want to set all the software
+modes in the other members, but leave the hardware details in
+@code{c_cflag} unchanged.  (This is how the @code{TCSASOFT} flag to
+@code{tcsettattr} works.)
+
+This bit is never set in the structure filled in by @code{tcgetattr}.
+@end deftypevr
+
+@node Local Modes
+@subsection Local Modes
+
+This section describes the flags for the @code{c_lflag} member of the
+@code{struct termios} structure.  These flags generally control
+higher-level aspects of input processing than the input modes flags
+described in @ref{Input Modes}, such as echoing, signals, and the choice
+of canonical or noncanonical input.
+
+The @code{c_lflag} member itself is an integer, and you change the flags
+and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
+try to specify the entire value for @code{c_lflag}---instead, change
+only specific flags and leave the rest untouched (@pxref{Setting
+Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ICANON
+This bit, if set, enables canonical input processing mode.  Otherwise,
+input is processed in noncanonical mode.  @xref{Canonical or Not}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ECHO
+If this bit is set, echoing of input characters back to the terminal
+is enabled.
+@cindex echo of terminal input
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ECHOE
+If this bit is set, echoing indicates erasure of input with the ERASE
+character by erasing the last character in the current line from the
+screen.  Otherwise, the character erased is re-echoed to show what has
+happened (suitable for a printing terminal).
+
+This bit only controls the display behavior; the @code{ICANON} bit by
+itself controls actual recognition of the ERASE character and erasure of
+input, without which @code{ECHOE} is simply irrelevant.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t ECHOPRT
+This bit is like @code{ECHOE}, enables display of the ERASE character in
+a way that is geared to a hardcopy terminal.  When you type the ERASE
+character, a @samp{\} character is printed followed by the first
+character erased.  Typing the ERASE character again just prints the next
+character erased.  Then, the next time you type a normal character, a
+@samp{/} character is printed before the character echoes.
+
+This is a BSD extension, and exists only in BSD systems and
+@gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ECHOK
+This bit enables special display of the KILL character by moving to a
+new line after echoing the KILL character normally.  The behavior of
+@code{ECHOKE} (below) is nicer to look at.
+
+If this bit is not set, the KILL character echoes just as it would if it
+were not the KILL character.  Then it is up to the user to remember that
+the KILL character has erased the preceding input; there is no
+indication of this on the screen.
+
+This bit only controls the display behavior; the @code{ICANON} bit by
+itself controls actual recognition of the KILL character and erasure of
+input, without which @code{ECHOK} is simply irrelevant.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t ECHOKE
+This bit is similar to @code{ECHOK}.  It enables special display of the
+KILL character by erasing on the screen the entire line that has been
+killed.  This is a BSD extension, and exists only in BSD systems and
+@gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ECHONL
+If this bit is set and the @code{ICANON} bit is also set, then the
+newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit
+is not set.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t ECHOCTL
+If this bit is set and the @code{ECHO} bit is also set, echo control
+characters with @samp{^} followed by the corresponding text character.
+Thus, control-A echoes as @samp{^A}.  This is usually the preferred mode
+for interactive input, because echoing a control character back to the
+terminal could have some undesired effect on the terminal.
+
+This is a BSD extension, and exists only in BSD systems and
+@gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t ISIG
+This bit controls whether the INTR, QUIT, and SUSP characters are
+recognized.  The functions associated with these characters are performed
+if and only if this bit is set.  Being in canonical or noncanonical
+input mode has no affect on the interpretation of these characters.
+
+You should use caution when disabling recognition of these characters.
+Programs that cannot be interrupted interactively are very
+user-unfriendly.  If you clear this bit, your program should provide
+some alternate interface that allows the user to interactively send the
+signals associated with these characters, or to escape from the program.
+@cindex interactive signals, from terminal
+
+@xref{Signal Characters}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t IEXTEN
+POSIX.1 gives @code{IEXTEN} implementation-defined meaning,
+so you cannot rely on this interpretation on all systems.
+
+On BSD systems and @gnulinuxhurdsystems{}, it enables the LNEXT and
+DISCARD characters.
+@xref{Other Special}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t NOFLSH
+Normally, the INTR, QUIT, and SUSP characters cause input and output
+queues for the terminal to be cleared.  If this bit is set, the queues
+are not cleared.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro tcflag_t TOSTOP
+If this bit is set and the system supports job control, then
+@code{SIGTTOU} signals are generated by background processes that
+attempt to write to the terminal.  @xref{Access to the Terminal}.
+@end deftypevr
+
+The following bits are BSD extensions; they exist only on BSD systems
+and @gnuhurdsystems{}.
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t ALTWERASE
+This bit determines how far the WERASE character should erase.  The
+WERASE character erases back to the beginning of a word; the question
+is, where do words begin?
+
+If this bit is clear, then the beginning of a word is a nonwhitespace
+character following a whitespace character.  If the bit is set, then the
+beginning of a word is an alphanumeric character or underscore following
+a character which is none of those.
+
+@xref{Editing Characters}, for more information about the WERASE character.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t FLUSHO
+This is the bit that toggles when the user types the DISCARD character.
+While this bit is set, all output is discarded.  @xref{Other Special}.
+@end deftypevr
+
+@comment termios.h (optional)
+@comment BSD
+@deftypevr Macro tcflag_t NOKERNINFO
+Setting this bit disables handling of the STATUS character.
+@xref{Other Special}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro tcflag_t PENDIN
+If this bit is set, it indicates that there is a line of input that
+needs to be reprinted.  Typing the REPRINT character sets this bit; the
+bit remains set until reprinting is finished.  @xref{Editing Characters}.
+@end deftypevr
+
+@c EXTPROC is too obscure to document now.  --roland
+
+@node Line Speed
+@subsection Line Speed
+@cindex line speed
+@cindex baud rate
+@cindex terminal line speed
+@cindex terminal line speed
+
+The terminal line speed tells the computer how fast to read and write
+data on the terminal.
+
+If the terminal is connected to a real serial line, the terminal speed
+you specify actually controls the line---if it doesn't match the
+terminal's own idea of the speed, communication does not work.  Real
+serial ports accept only certain standard speeds.  Also, particular
+hardware may not support even all the standard speeds.  Specifying a
+speed of zero hangs up a dialup connection and turns off modem control
+signals.
+
+If the terminal is not a real serial line (for example, if it is a
+network connection), then the line speed won't really affect data
+transmission speed, but some programs will use it to determine the
+amount of padding needed.  It's best to specify a line speed value that
+matches the actual speed of the actual terminal, but you can safely
+experiment with different values to vary the amount of padding.
+
+There are actually two line speeds for each terminal, one for input and
+one for output.  You can set them independently, but most often
+terminals use the same speed for both directions.
+
+The speed values are stored in the @code{struct termios} structure, but
+don't try to access them in the @code{struct termios} structure
+directly.  Instead, you should use the following functions to read and
+store them:
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct access to a single termios field, except on Linux, where
+@c multiple accesses may take place.  No worries either way, callers
+@c must ensure mutual exclusion on such non-opaque types.
+This function returns the output line speed stored in the structure
+@code{*@var{termios-p}}.
+@end deftypefun
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function returns the input line speed stored in the structure
+@code{*@var{termios-p}}.
+@end deftypefun
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function stores @var{speed} in @code{*@var{termios-p}} as the output
+speed.  The normal return value is @math{0}; a value of @math{-1}
+indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
+returns @math{-1}.
+@end deftypefun
+
+@comment termios.h
+@comment POSIX.1
+@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+This function stores @var{speed} in @code{*@var{termios-p}} as the input
+speed.  The normal return value is @math{0}; a value of @math{-1}
+indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
+returns @math{-1}.
+@end deftypefun
+
+@comment termios.h
+@comment BSD
+@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c There's no guarantee that the two calls are atomic, but since this is
+@c not an opaque type, callers ought to ensure mutual exclusion to the
+@c termios object.
+
+@c cfsetspeed ok
+@c  cfsetispeed ok
+@c  cfsetospeed ok
+This function stores @var{speed} in @code{*@var{termios-p}} as both the
+input and output speeds.  The normal return value is @math{0}; a value
+of @math{-1} indicates an error.  If @var{speed} is not a speed,
+@code{cfsetspeed} returns @math{-1}.  This function is an extension in
+4.4 BSD.
+@end deftypefun
+
+@comment termios.h
+@comment POSIX.1
+@deftp {Data Type} speed_t
+The @code{speed_t} type is an unsigned integer data type used to
+represent line speeds.
+@end deftp
+
+The functions @code{cfsetospeed} and @code{cfsetispeed} report errors
+only for speed values that the system simply cannot handle.  If you
+specify a speed value that is basically acceptable, then those functions
+will succeed.  But they do not check that a particular hardware device
+can actually support the specified speeds---in fact, they don't know
+which device you plan to set the speed for.  If you use @code{tcsetattr}
+to set the speed of a particular device to a value that it cannot
+handle, @code{tcsetattr} returns @math{-1}.
+
+@strong{Portability note:} In @theglibc{}, the functions above
+accept speeds measured in bits per second as input, and return speed
+values measured in bits per second.  Other libraries require speeds to
+be indicated by special codes.  For POSIX.1 portability, you must use
+one of the following symbols to represent the speed; their precise
+numeric values are system-dependent, but each name has a fixed meaning:
+@code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on.
+There is no portable way to represent any speed but these, but these are
+the only speeds that typical serial lines can support.
+
+@comment termios.h
+@comment POSIX.1
+@vindex B0
+@comment termios.h
+@comment POSIX.1
+@vindex B50
+@comment termios.h
+@comment POSIX.1
+@vindex B75
+@comment termios.h
+@comment POSIX.1
+@vindex B110
+@comment termios.h
+@comment POSIX.1
+@vindex B134
+@comment termios.h
+@comment POSIX.1
+@vindex B150
+@comment termios.h
+@comment POSIX.1
+@vindex B200
+@comment termios.h
+@comment POSIX.1
+@vindex B300
+@comment termios.h
+@comment POSIX.1
+@vindex B600
+@comment termios.h
+@comment POSIX.1
+@vindex B1200
+@comment termios.h
+@comment POSIX.1
+@vindex B1800
+@comment termios.h
+@comment POSIX.1
+@vindex B2400
+@comment termios.h
+@comment POSIX.1
+@vindex B4800
+@comment termios.h
+@comment POSIX.1
+@vindex B9600
+@comment termios.h
+@comment POSIX.1
+@vindex B19200
+@comment termios.h
+@comment POSIX.1
+@vindex B38400
+@comment termios.h
+@comment GNU
+@vindex B57600
+@comment termios.h
+@comment GNU
+@vindex B115200
+@comment termios.h
+@comment GNU
+@vindex B230400
+@comment termios.h
+@comment GNU
+@vindex B460800
+@smallexample
+B0  B50  B75  B110  B134  B150  B200
+B300  B600  B1200  B1800  B2400  B4800
+B9600  B19200  B38400  B57600  B115200
+B230400  B460800
+@end smallexample
+
+@vindex EXTA
+@vindex EXTB
+BSD defines two additional speed symbols as aliases: @code{EXTA} is an
+alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}.
+These aliases are obsolete.
+
+@node Special Characters
+@subsection Special Characters
+
+In canonical input, the terminal driver recognizes a number of special
+characters which perform various control functions.  These include the
+ERASE character (usually @key{DEL}) for editing input, and other editing
+characters.  The INTR character (normally @kbd{C-c}) for sending a
+@code{SIGINT} signal, and other signal-raising characters, may be
+available in either canonical or noncanonical input mode.  All these
+characters are described in this section.
+
+The particular characters used are specified in the @code{c_cc} member
+of the @code{struct termios} structure.  This member is an array; each
+element specifies the character for a particular role.  Each element has
+a symbolic constant that stands for the index of that element---for
+example, @code{VINTR} is the index of the element that specifies the INTR
+character, so storing @code{'='} in @code{@var{termios}.c_cc[VINTR]}
+specifies @samp{=} as the INTR character.
+
+@vindex _POSIX_VDISABLE
+On some systems, you can disable a particular special character function
+by specifying the value @code{_POSIX_VDISABLE} for that role.  This
+value is unequal to any possible character code.  @xref{Options for
+Files}, for more information about how to tell whether the operating
+system you are using supports @code{_POSIX_VDISABLE}.
+
+@menu
+* 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.
+@end menu
+
+@node Editing Characters
+@subsubsection Characters for Input Editing
+
+These special characters are active only in canonical input mode.
+@xref{Canonical or Not}.
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VEOF
+@cindex EOF character
+This is the subscript for the EOF character in the special control
+character array.  @code{@var{termios}.c_cc[VEOF]} holds the character
+itself.
+
+The EOF character is recognized only in canonical input mode.  It acts
+as a line terminator in the same way as a newline character, but if the
+EOF character is typed at the beginning of a line it causes @code{read}
+to return a byte count of zero, indicating end-of-file.  The EOF
+character itself is discarded.
+
+Usually, the EOF character is @kbd{C-d}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VEOL
+@cindex EOL character
+This is the subscript for the EOL character in the special control
+character array.  @code{@var{termios}.c_cc[VEOL]} holds the character
+itself.
+
+The EOL character is recognized only in canonical input mode.  It acts
+as a line terminator, just like a newline character.  The EOL character
+is not discarded; it is read as the last character in the input line.
+
+@c !!! example: this is set to ESC by 4.3 csh with "set filec" so it can
+@c complete partial lines without using cbreak or raw mode.
+
+You don't need to use the EOL character to make @key{RET} end a line.
+Just set the ICRNL flag.  In fact, this is the default state of
+affairs.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VEOL2
+@cindex EOL2 character
+This is the subscript for the EOL2 character in the special control
+character array.  @code{@var{termios}.c_cc[VEOL2]} holds the character
+itself.
+
+The EOL2 character works just like the EOL character (see above), but it
+can be a different character.  Thus, you can specify two characters to
+terminate an input line, by setting EOL to one of them and EOL2 to the
+other.
+
+The EOL2 character is a BSD extension; it exists only on BSD systems
+and @gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VERASE
+@cindex ERASE character
+This is the subscript for the ERASE character in the special control
+character array.  @code{@var{termios}.c_cc[VERASE]} holds the
+character itself.
+
+The ERASE character is recognized only in canonical input mode.  When
+the user types the erase character, the previous character typed is
+discarded.  (If the terminal generates multibyte character sequences,
+this may cause more than one byte of input to be discarded.)  This
+cannot be used to erase past the beginning of the current line of text.
+The ERASE character itself is discarded.
+@c !!! mention ECHOE here
+
+Usually, the ERASE character is @key{DEL}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VWERASE
+@cindex WERASE character
+This is the subscript for the WERASE character in the special control
+character array.  @code{@var{termios}.c_cc[VWERASE]} holds the character
+itself.
+
+The WERASE character is recognized only in canonical mode.  It erases an
+entire word of prior input, and any whitespace after it; whitespace
+characters before the word are not erased.
+
+The definition of a ``word'' depends on the setting of the
+@code{ALTWERASE} mode; @pxref{Local Modes}.
+
+If the @code{ALTWERASE} mode is not set, a word is defined as a sequence
+of any characters except space or tab.
+
+If the @code{ALTWERASE} mode is set, a word is defined as a sequence of
+characters containing only letters, numbers, and underscores, optionally
+followed by one character that is not a letter, number, or underscore.
+
+The WERASE character is usually @kbd{C-w}.
+
+This is a BSD extension.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VKILL
+@cindex KILL character
+This is the subscript for the KILL character in the special control
+character array.  @code{@var{termios}.c_cc[VKILL]} holds the character
+itself.
+
+The KILL character is recognized only in canonical input mode.  When the
+user types the kill character, the entire contents of the current line
+of input are discarded.  The kill character itself is discarded too.
+
+The KILL character is usually @kbd{C-u}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VREPRINT
+@cindex REPRINT character
+This is the subscript for the REPRINT character in the special control
+character array.  @code{@var{termios}.c_cc[VREPRINT]} holds the character
+itself.
+
+The REPRINT character is recognized only in canonical mode.  It reprints
+the current input line.  If some asynchronous output has come while you
+are typing, this lets you see the line you are typing clearly again.
+
+The REPRINT character is usually @kbd{C-r}.
+
+This is a BSD extension.
+@end deftypevr
+
+@node Signal Characters
+@subsubsection Characters that Cause Signals
+
+These special characters may be active in either canonical or noncanonical
+input mode, but only when the @code{ISIG} flag is set (@pxref{Local
+Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VINTR
+@cindex INTR character
+@cindex interrupt character
+This is the subscript for the INTR character in the special control
+character array.  @code{@var{termios}.c_cc[VINTR]} holds the character
+itself.
+
+The INTR (interrupt) character raises a @code{SIGINT} signal for all
+processes in the foreground job associated with the terminal.  The INTR
+character itself is then discarded.  @xref{Signal Handling}, for more
+information about signals.
+
+Typically, the INTR character is @kbd{C-c}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VQUIT
+@cindex QUIT character
+This is the subscript for the QUIT character in the special control
+character array.  @code{@var{termios}.c_cc[VQUIT]} holds the character
+itself.
+
+The QUIT character raises a @code{SIGQUIT} signal for all processes in
+the foreground job associated with the terminal.  The QUIT character
+itself is then discarded.  @xref{Signal Handling}, for more information
+about signals.
+
+Typically, the QUIT character is @kbd{C-\}.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VSUSP
+@cindex SUSP character
+@cindex suspend character
+This is the subscript for the SUSP character in the special control
+character array.  @code{@var{termios}.c_cc[VSUSP]} holds the character
+itself.
+
+The SUSP (suspend) character is recognized only if the implementation
+supports job control (@pxref{Job Control}).  It causes a @code{SIGTSTP}
+signal to be sent to all processes in the foreground job associated with
+the terminal.  The SUSP character itself is then discarded.
+@xref{Signal Handling}, for more information about signals.
+
+Typically, the SUSP character is @kbd{C-z}.
+@end deftypevr
+
+Few applications disable the normal interpretation of the SUSP
+character.  If your program does this, it should provide some other
+mechanism for the user to stop the job.  When the user invokes this
+mechanism, the program should send a @code{SIGTSTP} signal to the
+process group of the process, not just to the process itself.
+@xref{Signaling Another Process}.
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VDSUSP
+@cindex DSUSP character
+@cindex delayed suspend character
+This is the subscript for the DSUSP character in the special control
+character array.  @code{@var{termios}.c_cc[VDSUSP]} holds the character
+itself.
+
+The DSUSP (suspend) character is recognized only if the implementation
+supports job control (@pxref{Job Control}).  It sends a @code{SIGTSTP}
+signal, like the SUSP character, but not right away---only when the
+program tries to read it as input.  Not all systems with job control
+support DSUSP; only BSD-compatible systems (including @gnuhurdsystems{}).
+
+@xref{Signal Handling}, for more information about signals.
+
+Typically, the DSUSP character is @kbd{C-y}.
+@end deftypevr
+
+@node Start/Stop Characters
+@subsubsection Special Characters for Flow Control
+
+These special characters may be active in either canonical or noncanonical
+input mode, but their use is controlled by the flags @code{IXON} and
+@code{IXOFF} (@pxref{Input Modes}).
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VSTART
+@cindex START character
+This is the subscript for the START character in the special control
+character array.  @code{@var{termios}.c_cc[VSTART]} holds the
+character itself.
+
+The START character is used to support the @code{IXON} and @code{IXOFF}
+input modes.  If @code{IXON} is set, receiving a START character resumes
+suspended output; the START character itself is discarded.  If
+@code{IXANY} is set, receiving any character at all resumes suspended
+output; the resuming character is not discarded unless it is the START
+character.  @code{IXOFF} is set, the system may also transmit START
+characters to the terminal.
+
+The usual value for the START character is @kbd{C-q}.  You may not be
+able to change this value---the hardware may insist on using @kbd{C-q}
+regardless of what you specify.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VSTOP
+@cindex STOP character
+This is the subscript for the STOP character in the special control
+character array.  @code{@var{termios}.c_cc[VSTOP]} holds the character
+itself.
+
+The STOP character is used to support the @code{IXON} and @code{IXOFF}
+input modes.  If @code{IXON} is set, receiving a STOP character causes
+output to be suspended; the STOP character itself is discarded.  If
+@code{IXOFF} is set, the system may also transmit STOP characters to the
+terminal, to prevent the input queue from overflowing.
+
+The usual value for the STOP character is @kbd{C-s}.  You may not be
+able to change this value---the hardware may insist on using @kbd{C-s}
+regardless of what you specify.
+@end deftypevr
+
+@node Other Special
+@subsubsection Other Special Characters
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VLNEXT
+@cindex LNEXT character
+This is the subscript for the LNEXT character in the special control
+character array.  @code{@var{termios}.c_cc[VLNEXT]} holds the character
+itself.
+
+The LNEXT character is recognized only when @code{IEXTEN} is set, but in
+both canonical and noncanonical mode.  It disables any special
+significance of the next character the user types.  Even if the
+character would normally perform some editing function or generate a
+signal, it is read as a plain character.  This is the analogue of the
+@kbd{C-q} command in Emacs.  ``LNEXT'' stands for ``literal next.''
+
+The LNEXT character is usually @kbd{C-v}.
+
+This character is available on BSD systems and @gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VDISCARD
+@cindex DISCARD character
+This is the subscript for the DISCARD character in the special control
+character array.  @code{@var{termios}.c_cc[VDISCARD]} holds the character
+itself.
+
+The DISCARD character is recognized only when @code{IEXTEN} is set, but
+in both canonical and noncanonical mode.  Its effect is to toggle the
+discard-output flag.  When this flag is set, all program output is
+discarded.  Setting the flag also discards all output currently in the
+output buffer.  Typing any other character resets the flag.
+
+This character is available on BSD systems and @gnulinuxhurdsystems{}.
+@end deftypevr
+
+@comment termios.h
+@comment BSD
+@deftypevr Macro int VSTATUS
+@cindex STATUS character
+This is the subscript for the STATUS character in the special control
+character array.  @code{@var{termios}.c_cc[VSTATUS]} holds the character
+itself.
+
+The STATUS character's effect is to print out a status message about how
+the current process is running.
+
+The STATUS character is recognized only in canonical mode, and only if
+@code{NOKERNINFO} is not set.
+
+This character is available only on BSD systems and @gnuhurdsystems{}.
+@end deftypevr
+
+@node Noncanonical Input
+@subsection Noncanonical Input
+
+In noncanonical input mode, the special editing characters such as
+ERASE and KILL are ignored.  The system facilities for the user to edit
+input are disabled in noncanonical mode, so that all input characters
+(unless they are special for signal or flow-control purposes) are passed
+to the application program exactly as typed.  It is up to the
+application program to give the user ways to edit the input, if
+appropriate.
+
+Noncanonical mode offers special parameters called MIN and TIME for
+controlling whether and how long to wait for input to be available.  You
+can even use them to avoid ever waiting---to return immediately with
+whatever input is available, or with no input.
+
+The MIN and TIME are stored in elements of the @code{c_cc} array, which
+is a member of the @w{@code{struct termios}} structure.  Each element of
+this array has a particular role, and each element has a symbolic
+constant that stands for the index of that element.  @code{VMIN} and
+@code{VMAX} are the names for the indices in the array of the MIN and
+TIME slots.
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VMIN
+@cindex MIN termios slot
+This is the subscript for the MIN slot in the @code{c_cc} array.  Thus,
+@code{@var{termios}.c_cc[VMIN]} is the value itself.
+
+The MIN slot is only meaningful in noncanonical input mode; it
+specifies the minimum number of bytes that must be available in the
+input queue in order for @code{read} to return.
+@end deftypevr
+
+@comment termios.h
+@comment POSIX.1
+@deftypevr Macro int VTIME
+@cindex TIME termios slot
+This is the subscript for the TIME slot in the @code{c_cc} array.  Thus,
+@code{@var{termios}.c_cc[VTIME]} is the value itself.
+
+The TIME slot is only meaningful in noncanonical input mode; it
+specifies how long to wait for input before returning, in units of 0.1
+seconds.
+@end deftypevr
+
+The MIN and TIME values interact to determine the criterion for when
+@code{read} should return; their precise meanings depend on which of
+them are nonzero.  There are four possible cases:
+
+@itemize @bullet
+@item
+Both TIME and MIN are nonzero.
+
+In this case, TIME specifies how long to wait after each input character
+to see if more input arrives.  After the first character received,
+@code{read} keeps waiting until either MIN bytes have arrived in all, or
+TIME elapses with no further input.
+
+@code{read} always blocks until the first character arrives, even if
+TIME elapses first.  @code{read} can return more than MIN characters if
+more than MIN happen to be in the queue.
+
+@item
+Both MIN and TIME are zero.
+
+In this case, @code{read} always returns immediately with as many
+characters as are available in the queue, up to the number requested.
+If no input is immediately available, @code{read} returns a value of
+zero.
+
+@item
+MIN is zero but TIME has a nonzero value.
+
+In this case, @code{read} waits for time TIME for input to become
+available; the availability of a single byte is enough to satisfy the
+read request and cause @code{read} to return.  When it returns, it
+returns as many characters as are available, up to the number requested.
+If no input is available before the timer expires, @code{read} returns a
+value of zero.
+
+@item
+TIME is zero but MIN has a nonzero value.
+
+In this case, @code{read} waits until at least MIN bytes are available
+in the queue.  At that time, @code{read} returns as many characters as
+are available, up to the number requested.  @code{read} can return more
+than MIN characters if more than MIN happen to be in the queue.
+@end itemize
+
+What happens if MIN is 50 and you ask to read just 10 bytes?
+Normally, @code{read} waits until there are 50 bytes in the buffer (or,
+more generally, the wait condition described above is satisfied), and
+then reads 10 of them, leaving the other 40 buffered in the operating
+system for a subsequent call to @code{read}.
+
+@strong{Portability note:} On some systems, the MIN and TIME slots are
+actually the same as the EOF and EOL slots.  This causes no serious
+problem because the MIN and TIME slots are used only in noncanonical
+input and the EOF and EOL slots are used only in canonical input, but it
+isn't very clean.  @Theglibc{} allocates separate slots for these
+uses.
+
+@comment termios.h
+@comment BSD
+@deftypefun void cfmakeraw (struct termios *@var{termios-p})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c There's no guarantee the changes are atomic, but since this is not an
+@c opaque type, callers ought to ensure mutual exclusion to the termios
+@c object.
+This function provides an easy way to set up @code{*@var{termios-p}} for
+what has traditionally been called ``raw mode'' in BSD.  This uses
+noncanonical input, and turns off most processing to give an unmodified
+channel to the terminal.
+
+It does exactly this:
+@smallexample
+  @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
+                                |INLCR|IGNCR|ICRNL|IXON);
+  @var{termios-p}->c_oflag &= ~OPOST;
+  @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
+  @var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
+  @var{termios-p}->c_cflag |= CS8;
+@end smallexample
+@end deftypefun
+
+
+@node BSD Terminal Modes
+@section BSD Terminal Modes
+@cindex terminal modes, BSD
+
+The usual way to get and set terminal modes is with the functions described
+in @ref{Terminal Modes}.  However, on some systems you can use the
+BSD-derived functions in this section to do some of the same thing.  On
+many systems, these functions do not exist.  Even with @theglibc{},
+the functions simply fail with @code{errno} = @code{ENOSYS} with many
+kernels, including Linux.
+
+The symbols used in this section are declared in @file{sgtty.h}.
+
+@comment termios.h
+@comment BSD
+@deftp {Data Type} {struct sgttyb}
+This structure is an input or output parameter list for @code{gtty} and
+@code{stty}.
+
+@table @code
+@item char sg_ispeed
+Line speed for input
+@item char sg_ospeed
+Line speed for output
+@item char sg_erase
+Erase character
+@item char sg_kill
+Kill character
+@item int sg_flags
+Various flags
+@end table
+@end deftp
+
+@comment sgtty.h
+@comment BSD
+@deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct ioctl, BSD only.
+This function gets the attributes of a terminal.
+
+@code{gtty} sets *@var{attributes} to describe the terminal attributes
+of the terminal which is open with file descriptor @var{filedes}.
+@end deftypefun
+
+@comment sgtty.h
+@comment BSD
+@deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct ioctl, BSD only.
+
+This function sets the attributes of a terminal.
+
+@code{stty} sets the terminal attributes of the terminal which is open with
+file descriptor @var{filedes} to those described by *@var{filedes}.
+@end deftypefun
+
+@node Line Control
+@section Line Control Functions
+@cindex terminal line control functions
+
+These functions perform miscellaneous control actions on terminal
+devices.  As regards terminal access, they are treated like doing
+output: if any of these functions is used by a background process on its
+controlling terminal, normally all processes in the process group are
+sent a @code{SIGTTOU} signal.  The exception is if the calling process
+itself is ignoring or blocking @code{SIGTTOU} signals, in which case the
+operation is performed and no signal is sent.  @xref{Job Control}.
+
+@cindex break condition, generating
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}}
+@c On Linux, this calls just one out of two ioctls; on BSD, it's two
+@c ioctls with a select (for the delay only) in between, the first
+@c setting and the latter clearing the break status.  The BSD
+@c implementation may leave the break enabled if cancelled, and threads
+@c and signals may cause the break to be interrupted before requested.
+This function generates a break condition by transmitting a stream of
+zero bits on the terminal associated with the file descriptor
+@var{filedes}.  The duration of the break is controlled by the
+@var{duration} argument.  If zero, the duration is between 0.25 and 0.5
+seconds.  The meaning of a nonzero value depends on the operating system.
+
+This function does nothing if the terminal is not an asynchronous serial
+data port.
+
+The return value is normally zero.  In the event of an error, a value
+of @math{-1} is returned.  The following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal device.
+@end table
+@end deftypefun
+
+
+@cindex flushing terminal output queue
+@cindex terminal output queue, flushing
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcdrain (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct ioctl.
+The @code{tcdrain} function waits until all queued
+output to the terminal @var{filedes} has been transmitted.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{tcdrain} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{tcdrain} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The return value is normally zero.  In the event of an error, a value
+of @math{-1} is returned.  The following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal device.
+
+@item EINTR
+The operation was interrupted by delivery of a signal.
+@xref{Interrupted Primitives}.
+@end table
+@end deftypefun
+
+
+@cindex clearing terminal input queue
+@cindex terminal input queue, clearing
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcflush (int @var{filedes}, int @var{queue})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct ioctl.
+The @code{tcflush} function is used to clear the input and/or output
+queues associated with the terminal file @var{filedes}.  The @var{queue}
+argument specifies which queue(s) to clear, and can be one of the
+following values:
+
+@c Extra blank lines here make it look better.
+@table @code
+@vindex TCIFLUSH
+@item TCIFLUSH
+
+Clear any input data received, but not yet read.
+
+@vindex TCOFLUSH
+@item TCOFLUSH
+
+Clear any output data written, but not yet transmitted.
+
+@vindex TCIOFLUSH
+@item TCIOFLUSH
+
+Clear both queued input and output.
+@end table
+
+The return value is normally zero.  In the event of an error, a value
+of @math{-1} is returned.  The following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal device.
+
+@item EINVAL
+A bad value was supplied as the @var{queue} argument.
+@end table
+
+It is unfortunate that this function is named @code{tcflush}, because
+the term ``flush'' is normally used for quite another operation---waiting
+until all output is transmitted---and using it for discarding input or
+output would be confusing.  Unfortunately, the name @code{tcflush} comes
+from POSIX and we cannot change it.
+@end deftypefun
+
+@cindex flow control, terminal
+@cindex terminal flow control
+@comment termios.h
+@comment POSIX.1
+@deftypefun int tcflow (int @var{filedes}, int @var{action})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}}
+@c Direct ioctl on Linux.  On BSD, the TCO* actions are a single ioctl,
+@c whereas the TCI actions first call tcgetattr and then write to the fd
+@c the c_cc character corresponding to the action; there's a window for
+@c another thread to change the xon/xoff characters.
+The @code{tcflow} function is used to perform operations relating to
+XON/XOFF flow control on the terminal file specified by @var{filedes}.
+
+The @var{action} argument specifies what operation to perform, and can
+be one of the following values:
+
+@table @code
+@vindex TCOOFF
+@item TCOOFF
+Suspend transmission of output.
+
+@vindex TCOON
+@item TCOON
+Restart transmission of output.
+
+@vindex TCIOFF
+@item TCIOFF
+Transmit a STOP character.
+
+@vindex TCION
+@item TCION
+Transmit a START character.
+@end table
+
+For more information about the STOP and START characters, see @ref{Special
+Characters}.
+
+The return value is normally zero.  In the event of an error, a value
+of @math{-1} is returned.  The following @code{errno} error conditions
+are defined for this function:
+
+@table @code
+@vindex EBADF
+@item EBADF
+The @var{filedes} is not a valid file descriptor.
+
+@vindex ENOTTY
+@item ENOTTY
+The @var{filedes} is not associated with a terminal device.
+
+@vindex EINVAL
+@item EINVAL
+A bad value was supplied as the @var{action} argument.
+@end table
+@end deftypefun
+
+@node Noncanon Example
+@section Noncanonical Mode Example
+
+Here is an example program that shows how you can set up a terminal
+device to read single characters in noncanonical input mode, without
+echo.
+
+@smallexample
+@include termios.c.texi
+@end smallexample
+
+This program is careful to restore the original terminal modes before
+exiting or terminating with a signal.  It uses the @code{atexit}
+function (@pxref{Cleanups on Exit}) to make sure this is done
+by @code{exit}.
+
+@ignore
+@c !!!! the example doesn't handle any signals!
+The signals handled in the example are the ones that typically occur due
+to actions of the user.  It might be desirable to handle other signals
+such as SIGSEGV that can result from bugs in the program.
+@end ignore
+
+The shell is supposed to take care of resetting the terminal modes when
+a process is stopped or continued; see @ref{Job Control}.  But some
+existing shells do not actually do this, so you may wish to establish
+handlers for job control signals that reset terminal modes.  The above
+example does so.
+
+
+@node Pseudo-Terminals
+@section Pseudo-Terminals
+@cindex pseudo-terminals
+
+A @dfn{pseudo-terminal} is a special interprocess communication channel
+that acts like a terminal.  One end of the channel is called the
+@dfn{master} side or @dfn{master pseudo-terminal device}, the other side
+is called the @dfn{slave} side.  Data written to the master side is
+received by the slave side as if it was the result of a user typing at
+an ordinary terminal, and data written to the slave side is sent to the
+master side as if it was written on an ordinary terminal.
+
+Pseudo terminals are the way programs like @code{xterm} and @code{emacs}
+implement their terminal emulation functionality.
+
+@menu
+* Allocation::             Allocating a pseudo terminal.
+* Pseudo-Terminal Pairs::  How to open both sides of a
+                            pseudo-terminal in a single operation.
+@end menu
+
+@node Allocation
+@subsection Allocating Pseudo-Terminals
+@cindex allocating pseudo-terminals
+
+@pindex stdlib.h
+This subsection describes functions for allocating a pseudo-terminal,
+and for making this pseudo-terminal available for actual use.  These
+functions are declared in the header file @file{stdlib.h}.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int getpt (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+@c On BSD, tries to open multiple potential pty names, returning on the
+@c first success.  On Linux, try posix_openpt first, then fallback to
+@c the BSD implementation.  The posix implementation opens the ptmx
+@c device, checks with statfs that /dev/pts is a devpts or that /dev is
+@c a devfs, and returns the fd; static variables devpts_mounted and
+@c have_no_dev_ptmx are safely initialized so as to avoid repeated
+@c tests.
+The @code{getpt} function returns a new file descriptor for the next
+available master pseudo-terminal.  The normal return value from
+@code{getpt} is a non-negative integer file descriptor.  In the case of
+an error, a value of @math{-1} is returned instead.  The following
+@code{errno} conditions are defined for this function:
+
+@table @code
+@item ENOENT
+There are no free master pseudo-terminals available.
+@end table
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun int grantpt (int @var{filedes})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  unix/grantpt:pts_name @acsuheap @acsmem
+@c   ptsname_internal dup ok (but this is Linux-only!)
+@c   memchr dup ok
+@c   realloc dup @acsuheap @acsmem
+@c   malloc dup @acsuheap @acsmem
+@c   free dup @acsuheap @acsmem
+@c  fcntl dup ok
+@c  getuid dup ok
+@c  chown dup ok
+@c  sysconf(_SC_GETGR_R_SIZE_MAX) ok
+@c  getgrnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getgid dup ok
+@c  chmod dup ok
+@c  fork dup @aculock
+@c  [child]
+@c   setrlimit
+@c   dup2
+@c   CLOSE_ALL_FDS
+@c   execle
+@c   _exit
+@c  waitpid dup ok
+@c  WIFEXITED dup ok
+@c  WEXITSTATUS dup ok
+@c  free dup @ascuheap @acsmem
+The @code{grantpt} function changes the ownership and access permission
+of the slave pseudo-terminal device corresponding to the master
+pseudo-terminal device associated with the file descriptor
+@var{filedes}.  The owner is set from the real user ID of the calling
+process (@pxref{Process Persona}), and the group is set to a special
+group (typically @dfn{tty}) or from the real group ID of the calling
+process.  The access permission is set such that the file is both
+readable and writable by the owner and only writable by the group.
+
+On some systems this function is implemented by invoking a special
+@code{setuid} root program (@pxref{How Change Persona}).  As a
+consequence, installing a signal handler for the @code{SIGCHLD} signal
+(@pxref{Job Control Signals}) may interfere with a call to
+@code{grantpt}.
+
+The normal return value from @code{grantpt} 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:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument is not associated with a master pseudo-terminal
+device.
+
+@item EACCES
+The slave pseudo-terminal device corresponding to the master associated
+with @var{filedes} could not be accessed.
+@end table
+
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun int unlockpt (int @var{filedes})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
+@c unlockpt @ascuheap/bsd @acsmem @acsfd
+@c /bsd
+@c  ptsname_r dup @ascuheap @acsmem @acsfd
+@c  revoke ok (syscall)
+@c /linux
+@c  ioctl dup ok
+The @code{unlockpt} function unlocks the slave pseudo-terminal device
+corresponding to the master pseudo-terminal device associated with the
+file descriptor @var{filedes}.  On many systems, the slave can only be
+opened after unlocking, so portable applications should always call
+@code{unlockpt} before trying to open the slave.
+
+The normal return value from @code{unlockpt} 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:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument is not associated with a master pseudo-terminal
+device.
+@end table
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun {char *} ptsname (int @var{filedes})
+@safety{@prelim{}@mtunsafe{@mtasurace{:ptsname}}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
+@c ptsname @mtasurace:ptsname @ascuheap/bsd @acsmem @acsfd
+@c  ptsname_r dup @ascuheap/bsd @acsmem @acsfd
+If the file descriptor @var{filedes} is associated with a
+master pseudo-terminal device, the @code{ptsname} function returns a
+pointer to a statically-allocated, null-terminated string containing the
+file name of the associated slave pseudo-terminal file.  This string
+might be overwritten by subsequent calls to @code{ptsname}.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}}
+@c ptsname_r @ascuheap/bsd @acsmem @acsfd
+@c /hurd
+@c  term_get_peername ok
+@c  strlen dup ok
+@c  memcpy dup ok
+@c /bsd
+@c  isatty dup ok
+@c  strlen dup ok
+@c  ttyname_r dup @ascuheap @acsmem @acsfd
+@c  stat dup ok
+@c /linux
+@c  ptsname_internal ok
+@c   isatty dup ok
+@c   ioctl dup ok
+@c   strlen dup ok
+@c   itoa_word dup ok
+@c   stpcpy dup ok
+@c   memcpy dup ok
+@c   fxstat64 dup ok
+@c   MASTER_P ok
+@c    major ok
+@c     gnu_dev_major ok
+@c    minor ok
+@c     gnu_dev_minor ok
+@c   minor dup ok
+@c   xstat64 dup ok
+@c   S_ISCHR dup ok
+@c   SLAVE_P ok
+@c    major dup ok
+@c    minor dup ok
+The @code{ptsname_r} function is similar to the @code{ptsname} function
+except that it places its result into the user-specified buffer starting
+at @var{buf} with length @var{len}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@strong{Portability Note:} On @w{System V} derived systems, the file
+returned by the @code{ptsname} and @code{ptsname_r} functions may be
+STREAMS-based, and therefore require additional processing after opening
+before it actually behaves as a pseudo terminal.
+@c FIXME: xref STREAMS
+
+Typical usage of these functions is illustrated by the following example:
+@smallexample
+int
+open_pty_pair (int *amaster, int *aslave)
+@{
+  int master, slave;
+  char *name;
+
+  master = getpt ();
+  if (master < 0)
+    return 0;
+
+  if (grantpt (master) < 0 || unlockpt (master) < 0)
+    goto close_master;
+  name = ptsname (master);
+  if (name == NULL)
+    goto close_master;
+
+  slave = open (name, O_RDWR);
+  if (slave == -1)
+    goto close_master;
+
+  if (isastream (slave))
+    @{
+      if (ioctl (slave, I_PUSH, "ptem") < 0
+          || ioctl (slave, I_PUSH, "ldterm") < 0)
+        goto close_slave;
+    @}
+
+  *amaster = master;
+  *aslave = slave;
+  return 1;
+
+close_slave:
+  close (slave);
+
+close_master:
+  close (master);
+  return 0;
+@}
+@end smallexample
+
+@node Pseudo-Terminal Pairs
+@subsection Opening a Pseudo-Terminal Pair
+@cindex opening a pseudo-terminal pair
+
+These functions, derived from BSD, are available in the separate
+@file{libutil} library, and declared in @file{pty.h}.
+
+@comment pty.h
+@comment BSD
+@deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c openpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getpt @acsfd
+@c  grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  unlockpt dup @ascuheap/bsd @acsmem @acsfd
+@c  openpty:pts_name @acsuheap @acsmem @acsfd
+@c   ptsname_r dup @ascuheap/bsd @acsmem @acsfd
+@c   realloc dup @acsuheap @acsmem
+@c   malloc dup @acsuheap @acsmem
+@c   free dup @acsuheap @acsmem
+@c  open dup @acsfd
+@c  free dup @acsuheap @acsmem
+@c  tcsetattr dup ok
+@c  ioctl dup ok
+@c  strcpy dup ok
+@c  close dup @acsfd
+This function allocates and opens a pseudo-terminal pair, returning the
+file descriptor for the master in @var{*amaster}, and the file
+descriptor for the slave in @var{*aslave}.  If the argument @var{name}
+is not a null pointer, the file name of the slave pseudo-terminal
+device is stored in @code{*name}.  If @var{termp} is not a null pointer,
+the terminal attributes of the slave are set to the ones specified in
+the structure that @var{termp} points to (@pxref{Terminal Modes}).
+Likewise, if the @var{winp} is not a null pointer, the screen size of
+the slave is set to the values specified in the structure that
+@var{winp} points to.
+
+The normal return value from @code{openpty} is @math{0}; a value of
+@math{-1} is returned in case of failure.  The following @code{errno}
+conditions are defined for this function:
+
+@table @code
+@item ENOENT
+There are no free pseudo-terminal pairs available.
+@end table
+
+@strong{Warning:} Using the @code{openpty} function with @var{name} not
+set to @code{NULL} is @strong{very dangerous} because it provides no
+protection against overflowing the string @var{name}.  You should use
+the @code{ttyname} function on the file descriptor returned in
+@var{*slave} to find out the file name of the slave pseudo-terminal
+device instead.
+@end deftypefun
+
+@comment pty.h
+@comment BSD
+@deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c forkpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  openpty dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  fork dup @aculock
+@c  close dup @acsfd
+@c  /child
+@c   close dup @acsfd
+@c   login_tty dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
+@c   _exit dup ok
+@c  close dup @acsfd
+This function is similar to the @code{openpty} function, but in
+addition, forks a new process (@pxref{Creating a Process}) and makes the
+newly opened slave pseudo-terminal device the controlling terminal
+(@pxref{Controlling Terminal}) for the child process.
+
+If the operation is successful, there are then both parent and child
+processes and both see @code{forkpty} return, but with different values:
+it returns a value of @math{0} in the child process and returns the child's
+process ID in the parent process.
+
+If the allocation of a pseudo-terminal pair or the process creation
+failed, @code{forkpty} returns a value of @math{-1} in the parent
+process.
+
+@strong{Warning:} The @code{forkpty} function has the same problems with
+respect to the @var{name} argument as @code{openpty}.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/texinfo.tex b/ap/libc/glibc/glibc-2.23/manual/texinfo.tex
new file mode 100644
index 0000000..75d52b4
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/texinfo.tex
@@ -0,0 +1,11103 @@
+% texinfo.tex -- TeX macros to handle Texinfo files.
+%
+% Load plain if necessary, i.e., if running under initex.
+\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
+%
+\def\texinfoversion{2016-01-04.21}
+%
+% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
+% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016
+% Free Software Foundation, Inc.
+%
+% This texinfo.tex file is free software: you can redistribute it and/or
+% modify it under the terms of the GNU General Public License as
+% published by the Free Software Foundation, either version 3 of the
+% License, or (at your option) any later version.
+%
+% This texinfo.tex file is distributed in the hope that it will be
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+% General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with this program.  If not, see <http://www.gnu.org/licenses/>.
+%
+% As a special exception, when this file is read by TeX when processing
+% a Texinfo source document, you may use the result without
+% restriction. This Exception is an additional permission under section 7
+% of the GNU General Public License, version 3 ("GPLv3").
+%
+% Please try the latest version of texinfo.tex before submitting bug
+% reports; you can get the latest version from:
+%   http://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or
+%   http://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or
+%   http://www.gnu.org/software/texinfo/ (the Texinfo home page)
+% The texinfo.tex in any given distribution could well be out
+% of date, so if that's what you're using, please check.
+%
+% Send bug reports to bug-texinfo@gnu.org.  Please include including a
+% complete document in each bug report with which we can reproduce the
+% problem.  Patches are, of course, greatly appreciated.
+%
+% To process a Texinfo manual with TeX, it's most reliable to use the
+% texi2dvi shell script that comes with the distribution.  For a simple
+% manual foo.texi, however, you can get away with this:
+%   tex foo.texi
+%   texindex foo.??
+%   tex foo.texi
+%   tex foo.texi
+%   dvips foo.dvi -o  # or whatever; this makes foo.ps.
+% The extra TeX runs get the cross-reference information correct.
+% Sometimes one run after texindex suffices, and sometimes you need more
+% than two; texi2dvi does it as many times as necessary.
+%
+% It is possible to adapt texinfo.tex for other languages, to some
+% extent.  You can get the existing language-specific files from the
+% full Texinfo distribution.
+%
+% The GNU Texinfo home page is http://www.gnu.org/software/texinfo.
+
+
+\message{Loading texinfo [version \texinfoversion]:}
+
+% If in a .fmt file, print the version number
+% and turn on active characters that we couldn't do earlier because
+% they might have appeared in the input file name.
+\everyjob{\message{[Texinfo version \texinfoversion]}%
+  \catcode`+=\active \catcode`\_=\active}
+
+\chardef\other=12
+
+% We never want plain's \outer definition of \+ in Texinfo.
+% For @tex, we can use \tabalign.
+\let\+ = \relax
+
+% Save some plain tex macros whose names we will redefine.
+\let\ptexb=\b
+\let\ptexbullet=\bullet
+\let\ptexc=\c
+\let\ptexcomma=\,
+\let\ptexdot=\.
+\let\ptexdots=\dots
+\let\ptexend=\end
+\let\ptexequiv=\equiv
+\let\ptexexclam=\!
+\let\ptexfootnote=\footnote
+\let\ptexgtr=>
+\let\ptexhat=^
+\let\ptexi=\i
+\let\ptexindent=\indent
+\let\ptexinsert=\insert
+\let\ptexlbrace=\{
+\let\ptexless=<
+\let\ptexnewwrite\newwrite
+\let\ptexnoindent=\noindent
+\let\ptexplus=+
+\let\ptexraggedright=\raggedright
+\let\ptexrbrace=\}
+\let\ptexslash=\/
+\let\ptexsp=\sp
+\let\ptexstar=\*
+\let\ptexsup=\sup
+\let\ptext=\t
+\let\ptextop=\top
+{\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode
+
+% If this character appears in an error message or help string, it
+% starts a new line in the output.
+\newlinechar = `^^J
+
+% Use TeX 3.0's \inputlineno to get the line number, for better error
+% messages, but if we're using an old version of TeX, don't do anything.
+%
+\ifx\inputlineno\thisisundefined
+  \let\linenumber = \empty % Pre-3.0.
+\else
+  \def\linenumber{l.\the\inputlineno:\space}
+\fi
+
+% Set up fixed words for English if not already set.
+\ifx\putwordAppendix\undefined  \gdef\putwordAppendix{Appendix}\fi
+\ifx\putwordChapter\undefined   \gdef\putwordChapter{Chapter}\fi
+\ifx\putworderror\undefined     \gdef\putworderror{error}\fi
+\ifx\putwordfile\undefined      \gdef\putwordfile{file}\fi
+\ifx\putwordin\undefined        \gdef\putwordin{in}\fi
+\ifx\putwordIndexIsEmpty\undefined       \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
+\ifx\putwordIndexNonexistent\undefined   \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
+\ifx\putwordInfo\undefined      \gdef\putwordInfo{Info}\fi
+\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
+\ifx\putwordMethodon\undefined  \gdef\putwordMethodon{Method on}\fi
+\ifx\putwordNoTitle\undefined   \gdef\putwordNoTitle{No Title}\fi
+\ifx\putwordof\undefined        \gdef\putwordof{of}\fi
+\ifx\putwordon\undefined        \gdef\putwordon{on}\fi
+\ifx\putwordpage\undefined      \gdef\putwordpage{page}\fi
+\ifx\putwordsection\undefined   \gdef\putwordsection{section}\fi
+\ifx\putwordSection\undefined   \gdef\putwordSection{Section}\fi
+\ifx\putwordsee\undefined       \gdef\putwordsee{see}\fi
+\ifx\putwordSee\undefined       \gdef\putwordSee{See}\fi
+\ifx\putwordShortTOC\undefined  \gdef\putwordShortTOC{Short Contents}\fi
+\ifx\putwordTOC\undefined       \gdef\putwordTOC{Table of Contents}\fi
+%
+\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
+\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
+\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
+\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
+\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
+\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
+\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
+\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
+\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
+\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
+\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
+\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
+%
+\ifx\putwordDefmac\undefined    \gdef\putwordDefmac{Macro}\fi
+\ifx\putwordDefspec\undefined   \gdef\putwordDefspec{Special Form}\fi
+\ifx\putwordDefvar\undefined    \gdef\putwordDefvar{Variable}\fi
+\ifx\putwordDefopt\undefined    \gdef\putwordDefopt{User Option}\fi
+\ifx\putwordDeffunc\undefined   \gdef\putwordDeffunc{Function}\fi
+
+% Give the space character the catcode for a space.
+\def\spaceisspace{\catcode`\ =10\relax}
+
+\chardef\dashChar  = `\-
+\chardef\slashChar = `\/
+\chardef\underChar = `\_
+
+% Ignore a token.
+%
+\def\gobble#1{}
+
+% The following is used inside several \edef's.
+\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname}
+
+% Hyphenation fixes.
+\hyphenation{
+  Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script
+  ap-pen-dix bit-map bit-maps
+  data-base data-bases eshell fall-ing half-way long-est man-u-script
+  man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm
+  par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces
+  spell-ing spell-ings
+  stand-alone strong-est time-stamp time-stamps which-ever white-space
+  wide-spread wrap-around
+}
+
+% Sometimes it is convenient to have everything in the transcript file
+% and nothing on the terminal.  We don't just call \tracingall here,
+% since that produces some useless output on the terminal.  We also make
+% some effort to order the tracing commands to reduce output in the log
+% file; cf. trace.sty in LaTeX.
+%
+\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
+\def\loggingall{%
+  \tracingstats2
+  \tracingpages1
+  \tracinglostchars2  % 2 gives us more in etex
+  \tracingparagraphs1
+  \tracingoutput1
+  \tracingmacros2
+  \tracingrestores1
+  \showboxbreadth\maxdimen \showboxdepth\maxdimen
+  \ifx\eTeXversion\thisisundefined\else % etex gives us more logging
+    \tracingscantokens1
+    \tracingifs1
+    \tracinggroups1
+    \tracingnesting2
+    \tracingassigns1
+  \fi
+  \tracingcommands3  % 3 gives us more in etex
+  \errorcontextlines16
+}%
+
+% @errormsg{MSG}.  Do the index-like expansions on MSG, but if things
+% aren't perfect, it's not the end of the world, being an error message,
+% after all.
+%
+\def\errormsg{\begingroup \indexnofonts \doerrormsg}
+\def\doerrormsg#1{\errmessage{#1}}
+
+% add check for \lastpenalty to plain's definitions.  If the last thing
+% we did was a \nobreak, we don't want to insert more space.
+%
+\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
+  \removelastskip\penalty-50\smallskip\fi\fi}
+\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
+  \removelastskip\penalty-100\medskip\fi\fi}
+\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
+  \removelastskip\penalty-200\bigskip\fi\fi}
+
+% Output routine
+%
+
+% For a final copy, take out the rectangles
+% that mark overfull boxes (in case you have decided
+% that the text looks ok even though it passes the margin).
+%
+\def\finalout{\overfullrule=0pt }
+
+% Do @cropmarks to get crop marks.
+%
+\newif\ifcropmarks
+\let\cropmarks = \cropmarkstrue
+%
+% Dimensions to add cropmarks at corners.
+% Added by P. A. MacKay, 12 Nov. 1986
+%
+\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
+\newdimen\cornerlong  \cornerlong=1pc
+\newdimen\cornerthick \cornerthick=.3pt
+\newdimen\topandbottommargin \topandbottommargin=.75in
+
+% Output a mark which sets \thischapter, \thissection and \thiscolor.
+% We dump everything together because we only have one kind of mark.
+% This works because we only use \botmark / \topmark, not \firstmark.
+%
+% A mark contains a subexpression of the \ifcase ... \fi construct.
+% \get*marks macros below extract the needed part using \ifcase.
+%
+% Another complication is to let the user choose whether \thischapter
+% (\thissection) refers to the chapter (section) in effect at the top
+% of a page, or that at the bottom of a page.
+
+% \domark is called twice inside \chapmacro, to add one
+% mark before the section break, and one after.
+%   In the second call \prevchapterdefs is the same as \lastchapterdefs,
+% and \prevsectiondefs is the same as \lastsectiondefs.
+%   Then if the page is not broken at the mark, some of the previous
+% section appears on the page, and we can get the name of this section
+% from \firstmark for @everyheadingmarks top.
+%   @everyheadingmarks bottom uses \botmark.
+%
+% See page 260 of The TeXbook.
+\def\domark{%
+  \toks0=\expandafter{\lastchapterdefs}%
+  \toks2=\expandafter{\lastsectiondefs}%
+  \toks4=\expandafter{\prevchapterdefs}%
+  \toks6=\expandafter{\prevsectiondefs}%
+  \toks8=\expandafter{\lastcolordefs}%
+  \mark{%
+                   \the\toks0 \the\toks2  % 0: marks for @everyheadingmarks top
+      \noexpand\or \the\toks4 \the\toks6  % 1: for @everyheadingmarks bottom
+    \noexpand\else \the\toks8             % 2: color marks
+  }%
+}
+
+% \gettopheadingmarks, \getbottomheadingmarks,
+% \getcolormarks - extract needed part of mark.
+%
+% \topmark doesn't work for the very first chapter (after the title
+% page or the contents), so we use \firstmark there -- this gets us
+% the mark with the chapter defs, unless the user sneaks in, e.g.,
+% @setcolor (or @url, or @link, etc.) between @contents and the very
+% first @chapter.
+\def\gettopheadingmarks{%
+  \ifcase0\topmark\fi
+  \ifx\thischapter\empty \ifcase0\firstmark\fi \fi
+}
+\def\getbottomheadingmarks{\ifcase1\botmark\fi}
+\def\getcolormarks{\ifcase2\topmark\fi}
+
+% Avoid "undefined control sequence" errors.
+\def\lastchapterdefs{}
+\def\lastsectiondefs{}
+\def\lastsection{}
+\def\prevchapterdefs{}
+\def\prevsectiondefs{}
+\def\lastcolordefs{}
+
+% Margin to add to right of even pages, to left of odd pages.
+\newdimen\bindingoffset
+\newdimen\normaloffset
+\newdimen\pagewidth \newdimen\pageheight
+
+% Main output routine.
+%
+\chardef\PAGE = 255
+\output = {\onepageout{\pagecontents\PAGE}}
+
+\newbox\headlinebox
+\newbox\footlinebox
+
+% \onepageout takes a vbox as an argument.
+% \shipout a vbox for a single page, adding an optional header, footer,
+% cropmarks, and footnote.  This also causes index entries for this page
+% to be written to the auxiliary files.
+%
+\def\onepageout#1{%
+  \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
+  %
+  \ifodd\pageno  \advance\hoffset by \bindingoffset
+  \else \advance\hoffset by -\bindingoffset\fi
+  %
+  % Common context changes for both heading and footing.
+  % Do this outside of the \shipout so @code etc. will be expanded in
+  % the headline as they should be, not taken literally (outputting ''code).
+  \def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars}
+  %
+  % Retrieve the information for the headings from the marks in the page,
+  % and call Plain TeX's \makeheadline and \makefootline, which use the
+  % values in \headline and \footline.
+  %
+  % This is used to check if we are on the first page of a chapter.
+  \ifcase1\topmark\fi
+  \let\prevchaptername\thischaptername
+  \ifcase0\firstmark\fi
+  \let\curchaptername\thischaptername
+  %
+  \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
+  \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
+  %
+  \ifx\curchaptername\prevchaptername
+    \let\thischapterheading\thischapter
+  \else
+    % \thischapterheading is the same as \thischapter except it is blank
+    % for the first page of a chapter.  This is to prevent the chapter name
+    % being shown twice.
+    \def\thischapterheading{}%
+  \fi
+  %
+  \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}%
+  \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}%
+  %
+  {%
+    % Set context for writing to auxiliary files like index files.
+    % Have to do this stuff outside the \shipout because we want it to
+    % take effect in \write's, yet the group defined by the \vbox ends
+    % before the \shipout runs.
+    %
+    \indexdummies         % don't expand commands in the output.
+    \normalturnoffactive  % \ in index entries must not stay \, e.g., if
+               % the page break happens to be in the middle of an example.
+               % We don't want .vr (or whatever) entries like this:
+               % \entry{{\indexbackslash }acronym}{32}{\code {\acronym}}
+               % "\acronym" won't work when it's read back in;
+               % it needs to be
+               % {\code {{\backslashcurfont }acronym}
+    \shipout\vbox{%
+      % Do this early so pdf references go to the beginning of the page.
+      \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi
+      %
+      \ifcropmarks \vbox to \outervsize\bgroup
+        \hsize = \outerhsize
+        \vskip-\topandbottommargin
+        \vtop to0pt{%
+          \line{\ewtop\hfil\ewtop}%
+          \nointerlineskip
+          \line{%
+            \vbox{\moveleft\cornerthick\nstop}%
+            \hfill
+            \vbox{\moveright\cornerthick\nstop}%
+          }%
+          \vss}%
+        \vskip\topandbottommargin
+        \line\bgroup
+          \hfil % center the page within the outer (page) hsize.
+          \ifodd\pageno\hskip\bindingoffset\fi
+          \vbox\bgroup
+      \fi
+      %
+      \unvbox\headlinebox
+      \pagebody{#1}%
+      \ifdim\ht\footlinebox > 0pt
+        % Only leave this space if the footline is nonempty.
+        % (We lessened \vsize for it in \oddfootingyyy.)
+        % The \baselineskip=24pt in plain's \makefootline has no effect.
+        \vskip 24pt
+        \unvbox\footlinebox
+      \fi
+      %
+      \ifcropmarks
+          \egroup % end of \vbox\bgroup
+        \hfil\egroup % end of (centering) \line\bgroup
+        \vskip\topandbottommargin plus1fill minus1fill
+        \boxmaxdepth = \cornerthick
+        \vbox to0pt{\vss
+          \line{%
+            \vbox{\moveleft\cornerthick\nsbot}%
+            \hfill
+            \vbox{\moveright\cornerthick\nsbot}%
+          }%
+          \nointerlineskip
+          \line{\ewbot\hfil\ewbot}%
+        }%
+      \egroup % \vbox from first cropmarks clause
+      \fi
+    }% end of \shipout\vbox
+  }% end of group with \indexdummies
+  \advancepageno
+  \ifnum\outputpenalty>-20000 \else\dosupereject\fi
+}
+
+\newinsert\margin \dimen\margin=\maxdimen
+
+% Main part of page, including any footnotes
+\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
+{\catcode`\@ =11
+\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
+% marginal hacks, juha@viisa.uucp (Juha Takala)
+\ifvoid\margin\else % marginal info is present
+  \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
+\dimen@=\dp#1\relax \unvbox#1\relax
+\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
+\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
+}
+
+% Here are the rules for the cropmarks.  Note that they are
+% offset so that the space between them is truly \outerhsize or \outervsize
+% (P. A. MacKay, 12 November, 1986)
+%
+\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
+\def\nstop{\vbox
+  {\hrule height\cornerthick depth\cornerlong width\cornerthick}}
+\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
+\def\nsbot{\vbox
+  {\hrule height\cornerlong depth\cornerthick width\cornerthick}}
+
+
+% Argument parsing
+
+% Parse an argument, then pass it to #1.  The argument is the rest of
+% the input line (except we remove a trailing comment).  #1 should be a
+% macro which expects an ordinary undelimited TeX argument.
+% For example, \def\foo{\parsearg\fooxxx}.
+%
+\def\parsearg{\parseargusing{}}
+\def\parseargusing#1#2{%
+  \def\argtorun{#2}%
+  \begingroup
+    \obeylines
+    \spaceisspace
+    #1%
+    \parseargline\empty% Insert the \empty token, see \finishparsearg below.
+}
+
+{\obeylines %
+  \gdef\parseargline#1^^M{%
+    \endgroup % End of the group started in \parsearg.
+    \argremovecomment #1\comment\ArgTerm%
+  }%
+}
+
+% First remove any @comment, then any @c comment.  Also remove a @texinfoc
+% comment (see \scanmacro for details).  Pass the result on to \argcheckspaces.
+\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
+\def\argremovec#1\c#2\ArgTerm{\argremovetexinfoc #1\texinfoc\ArgTerm}
+\def\argremovetexinfoc#1\texinfoc#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
+
+% Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space.
+%
+% \argremovec might leave us with trailing space, e.g.,
+%    @end itemize  @c foo
+% This space token undergoes the same procedure and is eventually removed
+% by \finishparsearg.
+%
+\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M}
+\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M}
+\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{%
+  \def\temp{#3}%
+  \ifx\temp\empty
+    % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp:
+    \let\temp\finishparsearg
+  \else
+    \let\temp\argcheckspaces
+  \fi
+  % Put the space token in:
+  \temp#1 #3\ArgTerm
+}
+
+% If a _delimited_ argument is enclosed in braces, they get stripped; so
+% to get _exactly_ the rest of the line, we had to prevent such situation.
+% We prepended an \empty token at the very beginning and we expand it now,
+% just before passing the control to \argtorun.
+% (Similarly, we have to think about #3 of \argcheckspacesY above: it is
+% either the null string, or it ends with \^^M---thus there is no danger
+% that a pair of braces would be stripped.
+%
+% But first, we have to remove the trailing space token.
+%
+\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}}
+
+
+% \parseargdef - define a command taking an argument on the line
+%
+% \parseargdef\foo{...}
+%	is roughly equivalent to
+% \def\foo{\parsearg\Xfoo}
+% \def\Xfoo#1{...}
+\def\parseargdef#1{%
+  \expandafter \doparseargdef \csname\string#1\endcsname #1%
+}
+\def\doparseargdef#1#2{%
+  \def#2{\parsearg#1}%
+  \def#1##1%
+}
+
+% Several utility definitions with active space:
+{
+  \obeyspaces
+  \gdef\obeyedspace{ }
+
+  % Make each space character in the input produce a normal interword
+  % space in the output.  Don't allow a line break at this space, as this
+  % is used only in environments like @example, where each line of input
+  % should produce a line of output anyway.
+  %
+  \gdef\sepspaces{\obeyspaces\let =\tie}
+
+  % If an index command is used in an @example environment, any spaces
+  % therein should become regular spaces in the raw index file, not the
+  % expansion of \tie (\leavevmode \penalty \@M \ ).
+  \gdef\unsepspaces{\let =\space}
+}
+
+
+\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
+
+% Define the framework for environments in texinfo.tex.  It's used like this:
+%
+%   \envdef\foo{...}
+%   \def\Efoo{...}
+%
+% It's the responsibility of \envdef to insert \begingroup before the
+% actual body; @end closes the group after calling \Efoo.  \envdef also
+% defines \thisenv, so the current environment is known; @end checks
+% whether the environment name matches.  The \checkenv macro can also be
+% used to check whether the current environment is the one expected.
+%
+% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
+% are not treated as environments; they don't open a group.  (The
+% implementation of @end takes care not to call \endgroup in this
+% special case.)
+
+
+% At run-time, environments start with this:
+\def\startenvironment#1{\begingroup\def\thisenv{#1}}
+% initialize
+\let\thisenv\empty
+
+% ... but they get defined via ``\envdef\foo{...}'':
+\long\def\envdef#1#2{\def#1{\startenvironment#1#2}}
+\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}}
+
+% Check whether we're in the right environment:
+\def\checkenv#1{%
+  \def\temp{#1}%
+  \ifx\thisenv\temp
+  \else
+    \badenverr
+  \fi
+}
+
+% Environment mismatch, #1 expected:
+\def\badenverr{%
+  \errhelp = \EMsimple
+  \errmessage{This command can appear only \inenvironment\temp,
+    not \inenvironment\thisenv}%
+}
+\def\inenvironment#1{%
+  \ifx#1\empty
+    outside of any environment%
+  \else
+    in environment \expandafter\string#1%
+  \fi
+}
+
+% @end foo executes the definition of \Efoo.
+% But first, it executes a specialized version of \checkenv
+%
+\parseargdef\end{%
+  \if 1\csname iscond.#1\endcsname
+  \else
+    % The general wording of \badenverr may not be ideal.
+    \expandafter\checkenv\csname#1\endcsname
+    \csname E#1\endcsname
+    \endgroup
+  \fi
+}
+
+\newhelp\EMsimple{Press RETURN to continue.}
+
+
+% Be sure we're in horizontal mode when doing a tie, since we make space
+% equivalent to this in @example-like environments. Otherwise, a space
+% at the beginning of a line will start with \penalty -- and
+% since \penalty is valid in vertical mode, we'd end up putting the
+% penalty on the vertical list instead of in the new paragraph.
+{\catcode`@ = 11
+ % Avoid using \@M directly, because that causes trouble
+ % if the definition is written into an index file.
+ \global\let\tiepenalty = \@M
+ \gdef\tie{\leavevmode\penalty\tiepenalty\ }
+}
+
+% @: forces normal size whitespace following.
+\def\:{\spacefactor=1000 }
+
+% @* forces a line break.
+\def\*{\unskip\hfil\break\hbox{}\ignorespaces}
+
+% @/ allows a line break.
+\let\/=\allowbreak
+
+% @. is an end-of-sentence period.
+\def\.{.\spacefactor=\endofsentencespacefactor\space}
+
+% @! is an end-of-sentence bang.
+\def\!{!\spacefactor=\endofsentencespacefactor\space}
+
+% @? is an end-of-sentence query.
+\def\?{?\spacefactor=\endofsentencespacefactor\space}
+
+% @frenchspacing on|off  says whether to put extra space after punctuation.
+%
+\def\onword{on}
+\def\offword{off}
+%
+\parseargdef\frenchspacing{%
+  \def\temp{#1}%
+  \ifx\temp\onword \plainfrenchspacing
+  \else\ifx\temp\offword \plainnonfrenchspacing
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @frenchspacing option `\temp', must be on|off}%
+  \fi\fi
+}
+
+% @w prevents a word break.  Without the \leavevmode, @w at the
+% beginning of a paragraph, when TeX is still in vertical mode, would
+% produce a whole line of output instead of starting the paragraph.
+\def\w#1{\leavevmode\hbox{#1}}
+
+% @group ... @end group forces ... to be all on one page, by enclosing
+% it in a TeX vbox.  We use \vtop instead of \vbox to construct the box
+% to keep its height that of a normal line.  According to the rules for
+% \topskip (p.114 of the TeXbook), the glue inserted is
+% max (\topskip - \ht (first item), 0).  If that height is large,
+% therefore, no glue is inserted, and the space between the headline and
+% the text is small, which looks bad.
+%
+% Another complication is that the group might be very large.  This can
+% cause the glue on the previous page to be unduly stretched, because it
+% does not have much material.  In this case, it's better to add an
+% explicit \vfill so that the extra space is at the bottom.  The
+% threshold for doing this is if the group is more than \vfilllimit
+% percent of a page (\vfilllimit can be changed inside of @tex).
+%
+\newbox\groupbox
+\def\vfilllimit{0.7}
+%
+\envdef\group{%
+  \ifnum\catcode`\^^M=\active \else
+    \errhelp = \groupinvalidhelp
+    \errmessage{@group invalid in context where filling is enabled}%
+  \fi
+  \startsavinginserts
+  %
+  \setbox\groupbox = \vtop\bgroup
+    % Do @comment since we are called inside an environment such as
+    % @example, where each end-of-line in the input causes an
+    % end-of-line in the output.  We don't want the end-of-line after
+    % the `@group' to put extra space in the output.  Since @group
+    % should appear on a line by itself (according to the Texinfo
+    % manual), we don't worry about eating any user text.
+    \comment
+}
+%
+% The \vtop produces a box with normal height and large depth; thus, TeX puts
+% \baselineskip glue before it, and (when the next line of text is done)
+% \lineskip glue after it.  Thus, space below is not quite equal to space
+% above.  But it's pretty close.
+\def\Egroup{%
+    % To get correct interline space between the last line of the group
+    % and the first line afterwards, we have to propagate \prevdepth.
+    \endgraf % Not \par, as it may have been set to \lisppar.
+    \global\dimen1 = \prevdepth
+  \egroup           % End the \vtop.
+  \addgroupbox
+  \prevdepth = \dimen1
+  \checkinserts
+}
+
+\def\addgroupbox{
+  % \dimen0 is the vertical size of the group's box.
+  \dimen0 = \ht\groupbox  \advance\dimen0 by \dp\groupbox
+  % \dimen2 is how much space is left on the page (more or less).
+  \dimen2 = \pageheight   \advance\dimen2 by -\pagetotal
+  % if the group doesn't fit on the current page, and it's a big big
+  % group, force a page break.
+  \ifdim \dimen0 > \dimen2
+    \ifdim \pagetotal < \vfilllimit\pageheight
+      \page
+    \fi
+  \fi
+  \box\groupbox
+}
+
+%
+% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
+% message, so this ends up printing `@group can only ...'.
+%
+\newhelp\groupinvalidhelp{%
+group can only be used in environments such as @example,^^J%
+where each line of input produces a line of output.}
+
+% @need space-in-mils
+% forces a page break if there is not space-in-mils remaining.
+
+\newdimen\mil  \mil=0.001in
+
+\parseargdef\need{%
+  % Ensure vertical mode, so we don't make a big box in the middle of a
+  % paragraph.
+  \par
+  %
+  % If the @need value is less than one line space, it's useless.
+  \dimen0 = #1\mil
+  \dimen2 = \ht\strutbox
+  \advance\dimen2 by \dp\strutbox
+  \ifdim\dimen0 > \dimen2
+    %
+    % Do a \strut just to make the height of this box be normal, so the
+    % normal leading is inserted relative to the preceding line.
+    % And a page break here is fine.
+    \vtop to #1\mil{\strut\vfil}%
+    %
+    % TeX does not even consider page breaks if a penalty added to the
+    % main vertical list is 10000 or more.  But in order to see if the
+    % empty box we just added fits on the page, we must make it consider
+    % page breaks.  On the other hand, we don't want to actually break the
+    % page after the empty box.  So we use a penalty of 9999.
+    %
+    % There is an extremely small chance that TeX will actually break the
+    % page at this \penalty, if there are no other feasible breakpoints in
+    % sight.  (If the user is using lots of big @group commands, which
+    % almost-but-not-quite fill up a page, TeX will have a hard time doing
+    % good page breaking, for example.)  However, I could not construct an
+    % example where a page broke at this \penalty; if it happens in a real
+    % document, then we can reconsider our strategy.
+    \penalty9999
+    %
+    % Back up by the size of the box, whether we did a page break or not.
+    \kern -#1\mil
+    %
+    % Do not allow a page break right after this kern.
+    \nobreak
+  \fi
+}
+
+% @br   forces paragraph break (and is undocumented).
+
+\let\br = \par
+
+% @page forces the start of a new page.
+%
+\def\page{\par\vfill\supereject}
+
+% @exdent text....
+% outputs text on separate line in roman font, starting at standard page margin
+
+% This records the amount of indent in the innermost environment.
+% That's how much \exdent should take out.
+\newskip\exdentamount
+
+% This defn is used inside fill environments such as @defun.
+\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}
+
+% This defn is used inside nofill environments such as @example.
+\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount
+  \leftline{\hskip\leftskip{\rm#1}}}}
+
+% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current
+% paragraph.  For more general purposes, use the \margin insertion
+% class.  WHICH is `l' or `r'.  Not documented, written for gawk manual.
+%
+\newskip\inmarginspacing \inmarginspacing=1cm
+\def\strutdepth{\dp\strutbox}
+%
+\def\doinmargin#1#2{\strut\vadjust{%
+  \nobreak
+  \kern-\strutdepth
+  \vtop to \strutdepth{%
+    \baselineskip=\strutdepth
+    \vss
+    % if you have multiple lines of stuff to put here, you'll need to
+    % make the vbox yourself of the appropriate size.
+    \ifx#1l%
+      \llap{\ignorespaces #2\hskip\inmarginspacing}%
+    \else
+      \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}%
+    \fi
+    \null
+  }%
+}}
+\def\inleftmargin{\doinmargin l}
+\def\inrightmargin{\doinmargin r}
+%
+% @inmargin{TEXT [, RIGHT-TEXT]}
+% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
+% else use TEXT for both).
+%
+\def\inmargin#1{\parseinmargin #1,,\finish}
+\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
+  \setbox0 = \hbox{\ignorespaces #2}%
+  \ifdim\wd0 > 0pt
+    \def\lefttext{#1}%  have both texts
+    \def\righttext{#2}%
+  \else
+    \def\lefttext{#1}%  have only one text
+    \def\righttext{#1}%
+  \fi
+  %
+  \ifodd\pageno
+    \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin
+  \else
+    \def\temp{\inleftmargin\lefttext}%
+  \fi
+  \temp
+}
+
+% @| inserts a changebar to the left of the current line.  It should
+% surround any changed text.  This approach does *not* work if the
+% change spans more than two lines of output.  To handle that, we would
+% have adopt a much more difficult approach (putting marks into the main
+% vertical list for the beginning and end of each change).  This command
+% is not documented, not supported, and doesn't work.
+%
+\def\|{%
+  % \vadjust can only be used in horizontal mode.
+  \leavevmode
+  %
+  % Append this vertical mode material after the current line in the output.
+  \vadjust{%
+    % We want to insert a rule with the height and depth of the current
+    % leading; that is exactly what \strutbox is supposed to record.
+    \vskip-\baselineskip
+    %
+    % \vadjust-items are inserted at the left edge of the type.  So
+    % the \llap here moves out into the left-hand margin.
+    \llap{%
+      %
+      % For a thicker or thinner bar, change the `1pt'.
+      \vrule height\baselineskip width1pt
+      %
+      % This is the space between the bar and the text.
+      \hskip 12pt
+    }%
+  }%
+}
+
+% @include FILE -- \input text of FILE.
+%
+\def\include{\parseargusing\filenamecatcodes\includezzz}
+\def\includezzz#1{%
+  \pushthisfilestack
+  \def\thisfile{#1}%
+  {%
+    \makevalueexpandable  % we want to expand any @value in FILE.
+    \turnoffactive        % and allow special characters in the expansion
+    \indexnofonts         % Allow `@@' and other weird things in file names.
+    \wlog{texinfo.tex: doing @include of #1^^J}%
+    \edef\temp{\noexpand\input #1 }%
+    %
+    % This trickery is to read FILE outside of a group, in case it makes
+    % definitions, etc.
+    \expandafter
+  }\temp
+  \popthisfilestack
+}
+\def\filenamecatcodes{%
+  \catcode`\\=\other
+  \catcode`~=\other
+  \catcode`^=\other
+  \catcode`_=\other
+  \catcode`|=\other
+  \catcode`<=\other
+  \catcode`>=\other
+  \catcode`+=\other
+  \catcode`-=\other
+  \catcode`\`=\other
+  \catcode`\'=\other
+}
+
+\def\pushthisfilestack{%
+  \expandafter\pushthisfilestackX\popthisfilestack\StackTerm
+}
+\def\pushthisfilestackX{%
+  \expandafter\pushthisfilestackY\thisfile\StackTerm
+}
+\def\pushthisfilestackY #1\StackTerm #2\StackTerm {%
+  \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}%
+}
+
+\def\popthisfilestack{\errthisfilestackempty}
+\def\errthisfilestackempty{\errmessage{Internal error:
+  the stack of filenames is empty.}}
+%
+\def\thisfile{}
+
+% @center line
+% outputs that line, centered.
+%
+\parseargdef\center{%
+  \ifhmode
+    \let\centersub\centerH
+  \else
+    \let\centersub\centerV
+  \fi
+  \centersub{\hfil \ignorespaces#1\unskip \hfil}%
+  \let\centersub\relax % don't let the definition persist, just in case
+}
+\def\centerH#1{{%
+  \hfil\break
+  \advance\hsize by -\leftskip
+  \advance\hsize by -\rightskip
+  \line{#1}%
+  \break
+}}
+%
+\newcount\centerpenalty
+\def\centerV#1{%
+  % The idea here is the same as in \startdefun, \cartouche, etc.: if
+  % @center is the first thing after a section heading, we need to wipe
+  % out the negative parskip inserted by \sectionheading, but still
+  % prevent a page break here.
+  \centerpenalty = \lastpenalty
+  \ifnum\centerpenalty>10000 \vskip\parskip \fi
+  \ifnum\centerpenalty>9999 \penalty\centerpenalty \fi
+  \line{\kern\leftskip #1\kern\rightskip}%
+}
+
+% @sp n   outputs n lines of vertical space
+%
+\parseargdef\sp{\vskip #1\baselineskip}
+
+% @comment ...line which is ignored...
+% @c is the same as @comment
+% @ignore ... @end ignore  is another way to write a comment
+%
+\def\comment{\begingroup \catcode`\^^M=\active%
+\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other\commentxxx}%
+
+{\catcode`\^^M=\active%
+\gdef\commentxxx#1^^M{\endgroup%
+\futurelet\nexttoken\commentxxxx}%
+\gdef\commentxxxx{\ifx\nexttoken\aftermacro\expandafter\comment\fi}%
+}
+
+\def\c{\begingroup \catcode`\^^M=\active%
+\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
+\cxxx}
+{\catcode`\^^M=\active \gdef\cxxx#1^^M{\endgroup}}
+% See comment in \scanmacro about why the definitions of @c and @comment differ
+
+% @paragraphindent NCHARS
+% We'll use ems for NCHARS, close enough.
+% NCHARS can also be the word `asis' or `none'.
+% We cannot feasibly implement @paragraphindent asis, though.
+%
+\def\asisword{asis} % no translation, these are keywords
+\def\noneword{none}
+%
+\parseargdef\paragraphindent{%
+  \def\temp{#1}%
+  \ifx\temp\asisword
+  \else
+    \ifx\temp\noneword
+      \defaultparindent = 0pt
+    \else
+      \defaultparindent = #1em
+    \fi
+  \fi
+  \parindent = \defaultparindent
+}
+
+% @exampleindent NCHARS
+% We'll use ems for NCHARS like @paragraphindent.
+% It seems @exampleindent asis isn't necessary, but
+% I preserve it to make it similar to @paragraphindent.
+\parseargdef\exampleindent{%
+  \def\temp{#1}%
+  \ifx\temp\asisword
+  \else
+    \ifx\temp\noneword
+      \lispnarrowing = 0pt
+    \else
+      \lispnarrowing = #1em
+    \fi
+  \fi
+}
+
+% @firstparagraphindent WORD
+% If WORD is `none', then suppress indentation of the first paragraph
+% after a section heading.  If WORD is `insert', then do indent at such
+% paragraphs.
+%
+% The paragraph indentation is suppressed or not by calling
+% \suppressfirstparagraphindent, which the sectioning commands do.
+% We switch the definition of this back and forth according to WORD.
+% By default, we suppress indentation.
+%
+\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent}
+\def\insertword{insert}
+%
+\parseargdef\firstparagraphindent{%
+  \def\temp{#1}%
+  \ifx\temp\noneword
+    \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent
+  \else\ifx\temp\insertword
+    \let\suppressfirstparagraphindent = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @firstparagraphindent option `\temp'}%
+  \fi\fi
+}
+
+% Here is how we actually suppress indentation.  Redefine \everypar to
+% \kern backwards by \parindent, and then reset itself to empty.
+%
+% We also make \indent itself not actually do anything until the next
+% paragraph.
+%
+\gdef\dosuppressfirstparagraphindent{%
+  \gdef\indent  {\restorefirstparagraphindent \indent}%
+  \gdef\noindent{\restorefirstparagraphindent \noindent}%
+  \global\everypar = {\kern -\parindent \restorefirstparagraphindent}%
+}
+%
+\gdef\restorefirstparagraphindent{%
+  \global\let\indent = \ptexindent
+  \global\let\noindent = \ptexnoindent
+  \global\everypar = {}%
+}
+
+
+% @refill is a no-op.
+\let\refill=\relax
+
+% @setfilename INFO-FILENAME - ignored
+\let\setfilename=\comment
+
+% @bye.
+\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
+
+
+\message{pdf,}
+% adobe `portable' document format
+\newcount\tempnum
+\newcount\lnkcount
+\newtoks\filename
+\newcount\filenamelength
+\newcount\pgn
+\newtoks\toksA
+\newtoks\toksB
+\newtoks\toksC
+\newtoks\toksD
+\newbox\boxA
+\newbox\boxB
+\newcount\countA
+\newif\ifpdf
+\newif\ifpdfmakepagedest
+
+% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
+% can be set).  So we test for \relax and 0 as well as being undefined.
+\ifx\pdfoutput\thisisundefined
+\else
+  \ifx\pdfoutput\relax
+  \else
+    \ifcase\pdfoutput
+    \else
+      \pdftrue
+    \fi
+  \fi
+\fi
+
+% PDF uses PostScript string constants for the names of xref targets,
+% for display in the outlines, and in other places.  Thus, we have to
+% double any backslashes.  Otherwise, a name like "\node" will be
+% interpreted as a newline (\n), followed by o, d, e.  Not good.
+%
+% See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and
+% related messages.  The final outcome is that it is up to the TeX user
+% to double the backslashes and otherwise make the string valid, so
+% that's what we do.  pdftex 1.30.0 (ca.2005) introduced a primitive to
+% do this reliably, so we use it.
+
+% #1 is a control sequence in which to do the replacements,
+% which we \xdef.
+\def\txiescapepdf#1{%
+  \ifx\pdfescapestring\thisisundefined
+    % No primitive available; should we give a warning or log?
+    % Many times it won't matter.
+  \else
+    % The expandable \pdfescapestring primitive escapes parentheses,
+    % backslashes, and other special chars.
+    \xdef#1{\pdfescapestring{#1}}%
+  \fi
+}
+
+\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images
+with PDF output, and none of those formats could be found.  (.eps cannot
+be supported due to the design of the PDF format; use regular TeX (DVI
+output) for that.)}
+
+\ifpdf
+  %
+  % Color manipulation macros using ideas from pdfcolor.tex,
+  % except using rgb instead of cmyk; the latter is said to render as a
+  % very dark gray on-screen and a very dark halftone in print, instead
+  % of actual black. The dark red here is dark enough to print on paper as
+  % nearly black, but still distinguishable for online viewing.  We use
+  % black by default, though.
+  \def\rgbDarkRed{0.50 0.09 0.12}
+  \def\rgbBlack{0 0 0}
+  %
+  % rg sets the color for filling (usual text, etc.);
+  % RG sets the color for stroking (thin rules, e.g., normal _'s).
+  \def\pdfsetcolor#1{\pdfliteral{#1 rg  #1 RG}}
+  %
+  % Set color, and create a mark which defines \thiscolor accordingly,
+  % so that \makeheadline knows which color to restore.
+  \def\setcolor#1{%
+    \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}%
+    \domark
+    \pdfsetcolor{#1}%
+  }
+  %
+  \def\maincolor{\rgbBlack}
+  \pdfsetcolor{\maincolor}
+  \edef\thiscolor{\maincolor}
+  \def\lastcolordefs{}
+  %
+  \def\makefootline{%
+    \baselineskip24pt
+    \line{\pdfsetcolor{\maincolor}\the\footline}%
+  }
+  %
+  \def\makeheadline{%
+    \vbox to 0pt{%
+      \vskip-22.5pt
+      \line{%
+        \vbox to8.5pt{}%
+        % Extract \thiscolor definition from the marks.
+        \getcolormarks
+        % Typeset the headline with \maincolor, then restore the color.
+        \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}%
+      }%
+      \vss
+    }%
+    \nointerlineskip
+  }
+  %
+  %
+  \pdfcatalog{/PageMode /UseOutlines}
+  %
+  % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
+  \def\dopdfimage#1#2#3{%
+    \def\pdfimagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
+    \def\pdfimageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
+    %
+    % pdftex (and the PDF format) support .pdf, .png, .jpg (among
+    % others).  Let's try in that order, PDF first since if
+    % someone has a scalable image, presumably better to use that than a
+    % bitmap.
+    \let\pdfimgext=\empty
+    \begingroup
+      \openin 1 #1.pdf \ifeof 1
+        \openin 1 #1.PDF \ifeof 1
+          \openin 1 #1.png \ifeof 1
+            \openin 1 #1.jpg \ifeof 1
+              \openin 1 #1.jpeg \ifeof 1
+                \openin 1 #1.JPG \ifeof 1
+                  \errhelp = \nopdfimagehelp
+                  \errmessage{Could not find image file #1 for pdf}%
+                \else \gdef\pdfimgext{JPG}%
+                \fi
+              \else \gdef\pdfimgext{jpeg}%
+              \fi
+            \else \gdef\pdfimgext{jpg}%
+            \fi
+          \else \gdef\pdfimgext{png}%
+          \fi
+        \else \gdef\pdfimgext{PDF}%
+        \fi
+      \else \gdef\pdfimgext{pdf}%
+      \fi
+      \closein 1
+    \endgroup
+    %
+    % without \immediate, ancient pdftex seg faults when the same image is
+    % included twice.  (Version 3.14159-pre-1.0-unofficial-20010704.)
+    \ifnum\pdftexversion < 14
+      \immediate\pdfimage
+    \else
+      \immediate\pdfximage
+    \fi
+      \ifdim \wd0 >0pt width \pdfimagewidth \fi
+      \ifdim \wd2 >0pt height \pdfimageheight \fi
+      \ifnum\pdftexversion<13
+         #1.\pdfimgext
+       \else
+         {#1.\pdfimgext}%
+       \fi
+    \ifnum\pdftexversion < 14 \else
+      \pdfrefximage \pdflastximage
+    \fi}
+  %
+  \def\pdfmkdest#1{{%
+    % We have to set dummies so commands such as @code, and characters
+    % such as \, aren't expanded when present in a section title.
+    \indexnofonts
+    \turnoffactive
+    \makevalueexpandable
+    \def\pdfdestname{#1}%
+    \txiescapepdf\pdfdestname
+    \safewhatsit{\pdfdest name{\pdfdestname} xyz}%
+  }}
+  %
+  % used to mark target names; must be expandable.
+  \def\pdfmkpgn#1{#1}
+  %
+  % by default, use black for everything.
+  \def\urlcolor{\rgbBlack}
+  \def\linkcolor{\rgbBlack}
+  \def\endlink{\setcolor{\maincolor}\pdfendlink}
+  %
+  % Adding outlines to PDF; macros for calculating structure of outlines
+  % come from Petr Olsak
+  \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
+    \else \csname#1\endcsname \fi}
+  \def\advancenumber#1{\tempnum=\expnumber{#1}\relax
+    \advance\tempnum by 1
+    \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
+  %
+  % #1 is the section text, which is what will be displayed in the
+  % outline by the pdf viewer.  #2 is the pdf expression for the number
+  % of subentries (or empty, for subsubsections).  #3 is the node text,
+  % which might be empty if this toc entry had no corresponding node.
+  % #4 is the page number
+  %
+  \def\dopdfoutline#1#2#3#4{%
+    % Generate a link to the node text if that exists; else, use the
+    % page number.  We could generate a destination for the section
+    % text in the case where a section has no node, but it doesn't
+    % seem worth the trouble, since most documents are normally structured.
+    \edef\pdfoutlinedest{#3}%
+    \ifx\pdfoutlinedest\empty
+      \def\pdfoutlinedest{#4}%
+    \else
+      \txiescapepdf\pdfoutlinedest
+    \fi
+    %
+    % Also escape PDF chars in the display string.
+    \edef\pdfoutlinetext{#1}%
+    \txiescapepdf\pdfoutlinetext
+    %
+    \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}%
+  }
+  %
+  \def\pdfmakeoutlines{%
+    \begingroup
+      % Read toc silently, to get counts of subentries for \pdfoutline.
+      \def\partentry##1##2##3##4{}% ignore parts in the outlines
+      \def\numchapentry##1##2##3##4{%
+	\def\thischapnum{##2}%
+	\def\thissecnum{0}%
+	\def\thissubsecnum{0}%
+      }%
+      \def\numsecentry##1##2##3##4{%
+	\advancenumber{chap\thischapnum}%
+	\def\thissecnum{##2}%
+	\def\thissubsecnum{0}%
+      }%
+      \def\numsubsecentry##1##2##3##4{%
+	\advancenumber{sec\thissecnum}%
+	\def\thissubsecnum{##2}%
+      }%
+      \def\numsubsubsecentry##1##2##3##4{%
+	\advancenumber{subsec\thissubsecnum}%
+      }%
+      \def\thischapnum{0}%
+      \def\thissecnum{0}%
+      \def\thissubsecnum{0}%
+      %
+      % use \def rather than \let here because we redefine \chapentry et
+      % al. a second time, below.
+      \def\appentry{\numchapentry}%
+      \def\appsecentry{\numsecentry}%
+      \def\appsubsecentry{\numsubsecentry}%
+      \def\appsubsubsecentry{\numsubsubsecentry}%
+      \def\unnchapentry{\numchapentry}%
+      \def\unnsecentry{\numsecentry}%
+      \def\unnsubsecentry{\numsubsecentry}%
+      \def\unnsubsubsecentry{\numsubsubsecentry}%
+      \readdatafile{toc}%
+      %
+      % Read toc second time, this time actually producing the outlines.
+      % The `-' means take the \expnumber as the absolute number of
+      % subentries, which we calculated on our first read of the .toc above.
+      %
+      % We use the node names as the destinations.
+      \def\numchapentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
+      \def\numsecentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
+      \def\numsubsecentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}%
+      \def\numsubsubsecentry##1##2##3##4{% count is always zero
+        \dopdfoutline{##1}{}{##3}{##4}}%
+      %
+      % PDF outlines are displayed using system fonts, instead of
+      % document fonts.  Therefore we cannot use special characters,
+      % since the encoding is unknown.  For example, the eogonek from
+      % Latin 2 (0xea) gets translated to a | character.  Info from
+      % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100.
+      %
+      % TODO this right, we have to translate 8-bit characters to
+      % their "best" equivalent, based on the @documentencoding.  Too
+      % much work for too little return.  Just use the ASCII equivalents
+      % we use for the index sort strings.
+      %
+      \indexnofonts
+      \setupdatafile
+      % We can have normal brace characters in the PDF outlines, unlike
+      % Texinfo index files.  So set that up.
+      \def\{{\lbracecharliteral}%
+      \def\}{\rbracecharliteral}%
+      \catcode`\\=\active \otherbackslash
+      \input \tocreadfilename
+    \endgroup
+  }
+  {\catcode`[=1 \catcode`]=2
+   \catcode`{=\other \catcode`}=\other
+   \gdef\lbracecharliteral[{]%
+   \gdef\rbracecharliteral[}]%
+  ]
+  %
+  \def\skipspaces#1{\def\PP{#1}\def\D{|}%
+    \ifx\PP\D\let\nextsp\relax
+    \else\let\nextsp\skipspaces
+      \addtokens{\filename}{\PP}%
+      \advance\filenamelength by 1
+    \fi
+    \nextsp}
+  \def\getfilename#1{%
+    \filenamelength=0
+    % If we don't expand the argument now, \skipspaces will get
+    % snagged on things like "@value{foo}".
+    \edef\temp{#1}%
+    \expandafter\skipspaces\temp|\relax
+  }
+  \ifnum\pdftexversion < 14
+    \let \startlink \pdfannotlink
+  \else
+    \let \startlink \pdfstartlink
+  \fi
+  % make a live url in pdf output.
+  \def\pdfurl#1{%
+    \begingroup
+      % it seems we really need yet another set of dummies; have not
+      % tried to figure out what each command should do in the context
+      % of @url.  for now, just make @/ a no-op, that's the only one
+      % people have actually reported a problem with.
+      %
+      \normalturnoffactive
+      \def\@{@}%
+      \let\/=\empty
+      \makevalueexpandable
+      % do we want to go so far as to use \indexnofonts instead of just
+      % special-casing \var here?
+      \def\var##1{##1}%
+      %
+      \leavevmode\setcolor{\urlcolor}%
+      \startlink attr{/Border [0 0 0]}%
+        user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
+    \endgroup}
+  \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
+  \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
+  \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
+  \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
+  \def\maketoks{%
+    \expandafter\poptoks\the\toksA|ENDTOKS|\relax
+    \ifx\first0\adn0
+    \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
+    \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
+    \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
+    \else
+      \ifnum0=\countA\else\makelink\fi
+      \ifx\first.\let\next=\done\else
+        \let\next=\maketoks
+        \addtokens{\toksB}{\the\toksD}
+        \ifx\first,\addtokens{\toksB}{\space}\fi
+      \fi
+    \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+    \next}
+  \def\makelink{\addtokens{\toksB}%
+    {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
+  \def\pdflink#1{%
+    \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
+    \setcolor{\linkcolor}#1\endlink}
+  \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
+\else
+  % non-pdf mode
+  \let\pdfmkdest = \gobble
+  \let\pdfurl = \gobble
+  \let\endlink = \relax
+  \let\setcolor = \gobble
+  \let\pdfsetcolor = \gobble
+  \let\pdfmakeoutlines = \relax
+\fi  % \ifx\pdfoutput
+
+
+\message{fonts,}
+
+% Change the current font style to #1, remembering it in \curfontstyle.
+% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in
+% italics, not bold italics.
+%
+\def\setfontstyle#1{%
+  \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd.
+  \csname ten#1\endcsname  % change the current font
+}
+
+% Select #1 fonts with the current style.
+%
+\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname}
+
+\def\rm{\fam=0 \setfontstyle{rm}}
+\def\it{\fam=\itfam \setfontstyle{it}}
+\def\sl{\fam=\slfam \setfontstyle{sl}}
+\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
+\def\tt{\fam=\ttfam \setfontstyle{tt}}
+
+% Unfortunately, we have to override this for titles and the like, since
+% in those cases "rm" is bold.  Sigh.
+\def\rmisbold{\rm\def\curfontstyle{bf}}
+
+% Texinfo sort of supports the sans serif font style, which plain TeX does not.
+% So we set up a \sf.
+\newfam\sffam
+\def\sf{\fam=\sffam \setfontstyle{sf}}
+\let\li = \sf % Sometimes we call it \li, not \sf.
+
+% We don't need math for this font style.
+\def\ttsl{\setfontstyle{ttsl}}
+
+
+% Set the baselineskip to #1, and the lineskip and strut size
+% correspondingly.  There is no deep meaning behind these magic numbers
+% used as factors; they just match (closely enough) what Knuth defined.
+%
+\def\lineskipfactor{.08333}
+\def\strutheightpercent{.70833}
+\def\strutdepthpercent {.29167}
+%
+% can get a sort of poor man's double spacing by redefining this.
+\def\baselinefactor{1}
+%
+\newdimen\textleading
+\def\setleading#1{%
+  \dimen0 = #1\relax
+  \normalbaselineskip = \baselinefactor\dimen0
+  \normallineskip = \lineskipfactor\normalbaselineskip
+  \normalbaselines
+  \setbox\strutbox =\hbox{%
+    \vrule width0pt height\strutheightpercent\baselineskip
+                    depth \strutdepthpercent \baselineskip
+  }%
+}
+
+% PDF CMaps.  See also LaTeX's t1.cmap.
+%
+% do nothing with this by default.
+\expandafter\let\csname cmapOT1\endcsname\gobble
+\expandafter\let\csname cmapOT1IT\endcsname\gobble
+\expandafter\let\csname cmapOT1TT\endcsname\gobble
+
+% if we are producing pdf, and we have \pdffontattr, then define cmaps.
+% (\pdffontattr was introduced many years ago, but people still run
+% older pdftex's; it's easy to conditionalize, so we do.)
+\ifpdf \ifx\pdffontattr\thisisundefined \else
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1-0)
+%%Title: (TeX-OT1-0 TeX OT1 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<23> <26> <0023>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+40 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+%
+% \cmapOT1IT
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1IT-0)
+%%Title: (TeX-OT1IT-0 TeX OT1IT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1IT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1IT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<25> <26> <0025>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+42 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<23> <0023>
+<24> <00A3>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1IT\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+%
+% \cmapOT1TT
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1TT-0)
+%%Title: (TeX-OT1TT-0 TeX OT1TT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1TT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1TT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+5 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<21> <26> <0021>
+<28> <5F> <0028>
+<61> <7E> <0061>
+endbfrange
+32 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <2191>
+<0C> <2193>
+<0D> <0027>
+<0E> <00A1>
+<0F> <00BF>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<20> <2423>
+<27> <2019>
+<60> <2018>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1TT\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+\fi\fi
+
+
+% Set the font macro #1 to the font named \fontprefix#2.
+% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
+% encoding (only OT1, OT1IT and OT1TT are allowed, or empty to omit).
+% Example:
+% #1 = \textrm
+% #2 = \rmshape
+% #3 = 10
+% #4 = \mainmagstep
+% #5 = OT1
+%
+\def\setfont#1#2#3#4#5{%
+  \font#1=\fontprefix#2#3 scaled #4
+  \csname cmap#5\endcsname#1%
+}
+% This is what gets called when #5 of \setfont is empty.
+\let\cmap\gobble
+%
+% (end of cmaps)
+
+% Use cm as the default font prefix.
+% To specify the font prefix, you must define \fontprefix
+% before you read in texinfo.tex.
+\ifx\fontprefix\thisisundefined
+\def\fontprefix{cm}
+\fi
+% Support font families that don't use the same naming scheme as CM.
+\def\rmshape{r}
+\def\rmbshape{bx}               % where the normal face is bold
+\def\bfshape{b}
+\def\bxshape{bx}
+\def\ttshape{tt}
+\def\ttbshape{tt}
+\def\ttslshape{sltt}
+\def\itshape{ti}
+\def\itbshape{bxti}
+\def\slshape{sl}
+\def\slbshape{bxsl}
+\def\sfshape{ss}
+\def\sfbshape{ss}
+\def\scshape{csc}
+\def\scbshape{csc}
+
+% Definitions for a main text size of 11pt.  (The default in Texinfo.)
+%
+\def\definetextfontsizexi{%
+% Text fonts (11.2pt, magstep1).
+\def\textnominalsize{11pt}
+\edef\mainmagstep{\magstephalf}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+\def\textecsize{1095}
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstep1}{OT1}
+\setfont\deftt\ttshape{10}{\magstep1}{OT1TT}
+\setfont\defsl\slshape{10}{\magstep1}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf
+\let\tenttsl=\defttsl \let\tensl=\defsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+\def\smallecsize{0900}
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+\def\smallerecsize{0800}
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\titleecsize{2074}
+
+% Chapter (and unnumbered) fonts (17.28pt).
+\def\chapnominalsize{17pt}
+\setfont\chaprm\rmbshape{12}{\magstep2}{OT1}
+\setfont\chapit\itbshape{10}{\magstep3}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep3}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT}
+\setfont\chapsf\sfbshape{17}{1000}{OT1}
+\let\chapbf=\chaprm
+\setfont\chapsc\scbshape{10}{\magstep3}{OT1}
+\font\chapi=cmmi12 scaled \magstep2
+\font\chapsy=cmsy10 scaled \magstep3
+\def\chapecsize{1728}
+
+% Section fonts (14.4pt).
+\def\secnominalsize{14pt}
+\setfont\secrm\rmbshape{12}{\magstep1}{OT1}
+\setfont\secrmnotbold\rmshape{12}{\magstep1}{OT1}
+\setfont\secit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep2}{OT1}
+\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\secsf\sfbshape{12}{\magstep1}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep2}{OT1}
+\font\seci=cmmi12 scaled \magstep1
+\font\secsy=cmsy10 scaled \magstep2
+\def\sececsize{1440}
+
+% Subsection fonts (13.15pt).
+\def\ssecnominalsize{13pt}
+\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1}
+\setfont\ssecit\itbshape{10}{1315}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1315}{OT1}
+\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT}
+\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1315}{OT1}
+\font\sseci=cmmi12 scaled \magstephalf
+\font\ssecsy=cmsy10 scaled 1315
+\def\ssececsize{1200}
+
+% Reduced fonts for @acro in text (10pt).
+\def\reducednominalsize{10pt}
+\setfont\reducedrm\rmshape{10}{1000}{OT1}
+\setfont\reducedtt\ttshape{10}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{1000}{OT1}
+\setfont\reducedit\itshape{10}{1000}{OT1IT}
+\setfont\reducedsl\slshape{10}{1000}{OT1}
+\setfont\reducedsf\sfshape{10}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{1000}{OT1}
+\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT}
+\font\reducedi=cmmi10
+\font\reducedsy=cmsy10
+\def\reducedecsize{1000}
+
+\textleading = 13.2pt % line spacing for 11pt CM
+\textfonts            % reset the current fonts
+\rm
+} % end of 11pt text font size definitions, \definetextfontsizexi
+
+
+% Definitions to make the main text be 10pt Computer Modern, with
+% section, chapter, etc., sizes following suit.  This is for the GNU
+% Press printing of the Emacs 22 manual.  Maybe other manuals in the
+% future.  Used with @smallbook, which sets the leading to 12pt.
+%
+\def\definetextfontsizex{%
+% Text fonts (10pt).
+\def\textnominalsize{10pt}
+\edef\mainmagstep{1000}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+\def\textecsize{1000}
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstephalf}{OT1}
+\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT}
+\setfont\defsl\slshape{10}{\magstephalf}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf
+\let\tensl=\defsl \let\tenttsl=\defttsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+\def\smallecsize{0900}
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+\def\smallerecsize{0800}
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\titleecsize{2074}
+
+% Chapter fonts (14.4pt).
+\def\chapnominalsize{14pt}
+\setfont\chaprm\rmbshape{12}{\magstep1}{OT1}
+\setfont\chapit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep2}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\chapsf\sfbshape{12}{\magstep1}{OT1}
+\let\chapbf\chaprm
+\setfont\chapsc\scbshape{10}{\magstep2}{OT1}
+\font\chapi=cmmi12 scaled \magstep1
+\font\chapsy=cmsy10 scaled \magstep2
+\def\chapecsize{1440}
+
+% Section fonts (12pt).
+\def\secnominalsize{12pt}
+\setfont\secrm\rmbshape{12}{1000}{OT1}
+\setfont\secit\itbshape{10}{\magstep1}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep1}{OT1}
+\setfont\sectt\ttbshape{12}{1000}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT}
+\setfont\secsf\sfbshape{12}{1000}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep1}{OT1}
+\font\seci=cmmi12
+\font\secsy=cmsy10 scaled \magstep1
+\def\sececsize{1200}
+
+% Subsection fonts (10pt).
+\def\ssecnominalsize{10pt}
+\setfont\ssecrm\rmbshape{10}{1000}{OT1}
+\setfont\ssecit\itbshape{10}{1000}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1000}{OT1}
+\setfont\ssectt\ttbshape{10}{1000}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT}
+\setfont\ssecsf\sfbshape{10}{1000}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1000}{OT1}
+\font\sseci=cmmi10
+\font\ssecsy=cmsy10
+\def\ssececsize{1000}
+
+% Reduced fonts for @acro in text (9pt).
+\def\reducednominalsize{9pt}
+\setfont\reducedrm\rmshape{9}{1000}{OT1}
+\setfont\reducedtt\ttshape{9}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{900}{OT1}
+\setfont\reducedit\itshape{9}{1000}{OT1IT}
+\setfont\reducedsl\slshape{9}{1000}{OT1}
+\setfont\reducedsf\sfshape{9}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{900}{OT1}
+\setfont\reducedttsl\ttslshape{10}{900}{OT1TT}
+\font\reducedi=cmmi9
+\font\reducedsy=cmsy9
+\def\reducedecsize{0900}
+
+\divide\parskip by 2  % reduce space between paragraphs
+\textleading = 12pt   % line spacing for 10pt CM
+\textfonts            % reset the current fonts
+\rm
+} % end of 10pt text font size definitions, \definetextfontsizex
+
+
+% We provide the user-level command
+%   @fonttextsize 10
+% (or 11) to redefine the text font size.  pt is assumed.
+%
+\def\xiword{11}
+\def\xword{10}
+\def\xwordpt{10pt}
+%
+\parseargdef\fonttextsize{%
+  \def\textsizearg{#1}%
+  %\wlog{doing @fonttextsize \textsizearg}%
+  %
+  % Set \globaldefs so that documents can use this inside @tex, since
+  % makeinfo 4.8 does not support it, but we need it nonetheless.
+  %
+ \begingroup \globaldefs=1
+  \ifx\textsizearg\xword \definetextfontsizex
+  \else \ifx\textsizearg\xiword \definetextfontsizexi
+  \else
+    \errhelp=\EMsimple
+    \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'}
+  \fi\fi
+ \endgroup
+}
+
+% In order for the font changes to affect most math symbols and letters,
+% we have to define the \textfont of the standard families.  We don't
+% bother to reset \scriptfont and \scriptscriptfont; awaiting user need.
+%
+\def\resetmathfonts{%
+  \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
+  \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
+  \textfont\ttfam=\tentt \textfont\sffam=\tensf
+}
+
+% The font-changing commands redefine the meanings of \tenSTYLE, instead
+% of just \STYLE.  We do this because \STYLE needs to also set the
+% current \fam for math mode.  Our \STYLE (e.g., \rm) commands hardwire
+% \tenSTYLE to set the current font.
+%
+% Each font-changing command also sets the names \lsize (one size lower)
+% and \lllsize (three sizes lower).  These relative commands are used
+% in, e.g., the LaTeX logo and acronyms.
+%
+% This all needs generalizing, badly.
+%
+\def\textfonts{%
+  \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
+  \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
+  \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy
+  \let\tenttsl=\textttsl
+  \def\curfontsize{text}%
+  \def\lsize{reduced}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{\textleading}}
+\def\titlefonts{%
+  \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
+  \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
+  \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
+  \let\tenttsl=\titlettsl
+  \def\curfontsize{title}%
+  \def\lsize{chap}\def\lllsize{subsec}%
+  \resetmathfonts \setleading{27pt}}
+\def\titlefont#1{{\titlefonts\rmisbold #1}}
+\def\chapfonts{%
+  \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
+  \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
+  \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy
+  \let\tenttsl=\chapttsl
+  \def\curfontsize{chap}%
+  \def\lsize{sec}\def\lllsize{text}%
+  \resetmathfonts \setleading{19pt}}
+\def\secfonts{%
+  \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
+  \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
+  \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy
+  \let\tenttsl=\secttsl
+  \def\curfontsize{sec}%
+  \def\lsize{subsec}\def\lllsize{reduced}%
+  \resetmathfonts \setleading{17pt}}
+\def\subsecfonts{%
+  \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
+  \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
+  \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy
+  \let\tenttsl=\ssecttsl
+  \def\curfontsize{ssec}%
+  \def\lsize{text}\def\lllsize{small}%
+  \resetmathfonts \setleading{15pt}}
+\let\subsubsecfonts = \subsecfonts
+\def\reducedfonts{%
+  \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl
+  \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc
+  \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy
+  \let\tenttsl=\reducedttsl
+  \def\curfontsize{reduced}%
+  \def\lsize{small}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{10.5pt}}
+\def\smallfonts{%
+  \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
+  \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
+  \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
+  \let\tenttsl=\smallttsl
+  \def\curfontsize{small}%
+  \def\lsize{smaller}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{10.5pt}}
+\def\smallerfonts{%
+  \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
+  \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
+  \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
+  \let\tenttsl=\smallerttsl
+  \def\curfontsize{smaller}%
+  \def\lsize{smaller}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{9.5pt}}
+
+% Fonts for short table of contents.
+\setfont\shortcontrm\rmshape{12}{1000}{OT1}
+\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1}  % no cmb12
+\setfont\shortcontsl\slshape{12}{1000}{OT1}
+\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
+
+% Define these just so they can be easily changed for other fonts.
+\def\angleleft{$\langle$}
+\def\angleright{$\rangle$}
+
+% Set the fonts to use with the @small... environments.
+\let\smallexamplefonts = \smallfonts
+
+% About \smallexamplefonts.  If we use \smallfonts (9pt), @smallexample
+% can fit this many characters:
+%   8.5x11=86   smallbook=72  a4=90  a5=69
+% If we use \scriptfonts (8pt), then we can fit this many characters:
+%   8.5x11=90+  smallbook=80  a4=90+  a5=77
+% For me, subjectively, the few extra characters that fit aren't worth
+% the additional smallness of 8pt.  So I'm making the default 9pt.
+%
+% By the way, for comparison, here's what fits with @example (10pt):
+%   8.5x11=71  smallbook=60  a4=75  a5=58
+% --karl, 24jan03.
+
+% Set up the default fonts, so we can use them for creating boxes.
+%
+\definetextfontsizexi
+
+
+\message{markup,}
+
+% Check if we are currently using a typewriter font.  Since all the
+% Computer Modern typewriter fonts have zero interword stretch (and
+% shrink), and it is reasonable to expect all typewriter fonts to have
+% this property, we can check that font parameter.
+%
+\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
+
+% Markup style infrastructure.  \defmarkupstylesetup\INITMACRO will
+% define and register \INITMACRO to be called on markup style changes.
+% \INITMACRO can check \currentmarkupstyle for the innermost
+% style and the set of \ifmarkupSTYLE switches for all styles
+% currently in effect.
+\newif\ifmarkupvar
+\newif\ifmarkupsamp
+\newif\ifmarkupkey
+%\newif\ifmarkupfile % @file == @samp.
+%\newif\ifmarkupoption % @option == @samp.
+\newif\ifmarkupcode
+\newif\ifmarkupkbd
+%\newif\ifmarkupenv % @env == @code.
+%\newif\ifmarkupcommand % @command == @code.
+\newif\ifmarkuptex % @tex (and part of @math, for now).
+\newif\ifmarkupexample
+\newif\ifmarkupverb
+\newif\ifmarkupverbatim
+
+\let\currentmarkupstyle\empty
+
+\def\setupmarkupstyle#1{%
+  \csname markup#1true\endcsname
+  \def\currentmarkupstyle{#1}%
+  \markupstylesetup
+}
+
+\let\markupstylesetup\empty
+
+\def\defmarkupstylesetup#1{%
+  \expandafter\def\expandafter\markupstylesetup
+    \expandafter{\markupstylesetup #1}%
+  \def#1%
+}
+
+% Markup style setup for left and right quotes.
+\defmarkupstylesetup\markupsetuplq{%
+  \expandafter\let\expandafter \temp
+    \csname markupsetuplq\currentmarkupstyle\endcsname
+  \ifx\temp\relax \markupsetuplqdefault \else \temp \fi
+}
+
+\defmarkupstylesetup\markupsetuprq{%
+  \expandafter\let\expandafter \temp
+    \csname markupsetuprq\currentmarkupstyle\endcsname
+  \ifx\temp\relax \markupsetuprqdefault \else \temp \fi
+}
+
+{
+\catcode`\'=\active
+\catcode`\`=\active
+
+\gdef\markupsetuplqdefault{\let`\lq}
+\gdef\markupsetuprqdefault{\let'\rq}
+
+\gdef\markupsetcodequoteleft{\let`\codequoteleft}
+\gdef\markupsetcodequoteright{\let'\codequoteright}
+}
+
+\let\markupsetuplqcode \markupsetcodequoteleft
+\let\markupsetuprqcode \markupsetcodequoteright
+%
+\let\markupsetuplqexample \markupsetcodequoteleft
+\let\markupsetuprqexample \markupsetcodequoteright
+%
+\let\markupsetuplqkbd     \markupsetcodequoteleft
+\let\markupsetuprqkbd     \markupsetcodequoteright
+%
+\let\markupsetuplqsamp \markupsetcodequoteleft
+\let\markupsetuprqsamp \markupsetcodequoteright
+%
+\let\markupsetuplqverb \markupsetcodequoteleft
+\let\markupsetuprqverb \markupsetcodequoteright
+%
+\let\markupsetuplqverbatim \markupsetcodequoteleft
+\let\markupsetuprqverbatim \markupsetcodequoteright
+
+% Allow an option to not use regular directed right quote/apostrophe
+% (char 0x27), but instead the undirected quote from cmtt (char 0x0d).
+% The undirected quote is ugly, so don't make it the default, but it
+% works for pasting with more pdf viewers (at least evince), the
+% lilypond developers report.  xpdf does work with the regular 0x27.
+%
+\def\codequoteright{%
+  \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
+    \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
+      '%
+    \else \char'15 \fi
+  \else \char'15 \fi
+}
+%
+% and a similar option for the left quote char vs. a grave accent.
+% Modern fonts display ASCII 0x60 as a grave accent, so some people like
+% the code environments to do likewise.
+%
+\def\codequoteleft{%
+  \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
+    \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
+      % [Knuth] pp. 380,381,391
+      % \relax disables Spanish ligatures ?` and !` of \tt font.
+      \relax`%
+    \else \char'22 \fi
+  \else \char'22 \fi
+}
+
+% Commands to set the quote options.
+%
+\parseargdef\codequoteundirected{%
+  \def\temp{#1}%
+  \ifx\temp\onword
+    \expandafter\let\csname SETtxicodequoteundirected\endcsname
+      = t%
+  \else\ifx\temp\offword
+    \expandafter\let\csname SETtxicodequoteundirected\endcsname
+      = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @codequoteundirected value `\temp', must be on|off}%
+  \fi\fi
+}
+%
+\parseargdef\codequotebacktick{%
+  \def\temp{#1}%
+  \ifx\temp\onword
+    \expandafter\let\csname SETtxicodequotebacktick\endcsname
+      = t%
+  \else\ifx\temp\offword
+    \expandafter\let\csname SETtxicodequotebacktick\endcsname
+      = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @codequotebacktick value `\temp', must be on|off}%
+  \fi\fi
+}
+
+% [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font.
+\def\noligaturesquoteleft{\relax\lq}
+
+% Count depth in font-changes, for error checks
+\newcount\fontdepth \fontdepth=0
+
+% Font commands.
+
+% #1 is the font command (\sl or \it), #2 is the text to slant.
+% If we are in a monospaced environment, however, 1) always use \ttsl,
+% and 2) do not add an italic correction.
+\def\dosmartslant#1#2{%
+  \ifusingtt
+    {{\ttsl #2}\let\next=\relax}%
+    {\def\next{{#1#2}\futurelet\next\smartitaliccorrection}}%
+  \next
+}
+\def\smartslanted{\dosmartslant\sl}
+\def\smartitalic{\dosmartslant\it}
+
+% Output an italic correction unless \next (presumed to be the following
+% character) is such as not to need one.
+\def\smartitaliccorrection{%
+  \ifx\next,%
+  \else\ifx\next-%
+  \else\ifx\next.%
+  \else\ifx\next\.%
+  \else\ifx\next\comma%
+  \else\ptexslash
+  \fi\fi\fi\fi\fi
+  \aftersmartic
+}
+
+% Unconditional use \ttsl, and no ic.  @var is set to this for defuns.
+\def\ttslanted#1{{\ttsl #1}}
+
+% @cite is like \smartslanted except unconditionally use \sl.  We never want
+% ttsl for book titles, do we?
+\def\cite#1{{\sl #1}\futurelet\next\smartitaliccorrection}
+
+\def\aftersmartic{}
+\def\var#1{%
+  \let\saveaftersmartic = \aftersmartic
+  \def\aftersmartic{\null\let\aftersmartic=\saveaftersmartic}%
+  \smartslanted{#1}%
+}
+
+\let\i=\smartitalic
+\let\slanted=\smartslanted
+\let\dfn=\smartslanted
+\let\emph=\smartitalic
+
+% Explicit font changes: @r, @sc, undocumented @ii.
+\def\r#1{{\rm #1}}              % roman font
+\def\sc#1{{\smallcaps#1}}       % smallcaps font
+\def\ii#1{{\it #1}}             % italic font
+
+% @b, explicit bold.  Also @strong.
+\def\b#1{{\bf #1}}
+\let\strong=\b
+
+% @sansserif, explicit sans.
+\def\sansserif#1{{\sf #1}}
+
+% We can't just use \exhyphenpenalty, because that only has effect at
+% the end of a paragraph.  Restore normal hyphenation at the end of the
+% group within which \nohyphenation is presumably called.
+%
+\def\nohyphenation{\hyphenchar\font = -1  \aftergroup\restorehyphenation}
+\def\restorehyphenation{\hyphenchar\font = `- }
+
+% Set sfcode to normal for the chars that usually have another value.
+% Can't use plain's \frenchspacing because it uses the `\x notation, and
+% sometimes \x has an active definition that messes things up.
+%
+\catcode`@=11
+  \def\plainfrenchspacing{%
+    \sfcode`\.=\@m \sfcode`\?=\@m \sfcode`\!=\@m
+    \sfcode`\:=\@m \sfcode`\;=\@m \sfcode`\,=\@m
+    \def\endofsentencespacefactor{1000}% for @. and friends
+  }
+  \def\plainnonfrenchspacing{%
+    \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000
+    \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
+    \def\endofsentencespacefactor{3000}% for @. and friends
+  }
+\catcode`@=\other
+\def\endofsentencespacefactor{3000}% default
+
+% @t, explicit typewriter.
+\def\t#1{%
+  {\tt \rawbackslash \plainfrenchspacing #1}%
+  \null
+}
+
+% @samp.
+\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}}
+
+% @indicateurl is \samp, that is, with quotes.
+\let\indicateurl=\samp
+
+% @code (and similar) prints in typewriter, but with spaces the same
+% size as normal in the surrounding text, without hyphenation, etc.
+% This is a subroutine for that.
+\def\tclose#1{%
+  {%
+    % Change normal interword space to be same as for the current font.
+    \spaceskip = \fontdimen2\font
+    %
+    % Switch to typewriter.
+    \tt
+    %
+    % But `\ ' produces the large typewriter interword space.
+    \def\ {{\spaceskip = 0pt{} }}%
+    %
+    % Turn off hyphenation.
+    \nohyphenation
+    %
+    \rawbackslash
+    \plainfrenchspacing
+    #1%
+  }%
+  \null % reset spacefactor to 1000
+}
+
+% We *must* turn on hyphenation at `-' and `_' in @code.
+% (But see \codedashfinish below.)
+% Otherwise, it is too hard to avoid overfull hboxes
+% in the Emacs manual, the Library manual, etc.
+%
+% Unfortunately, TeX uses one parameter (\hyphenchar) to control
+% both hyphenation at - and hyphenation within words.
+% We must therefore turn them both off (\tclose does that)
+% and arrange explicitly to hyphenate at a dash. -- rms.
+{
+  \catcode`\-=\active \catcode`\_=\active
+  \catcode`\'=\active \catcode`\`=\active
+  \global\let'=\rq \global\let`=\lq  % default definitions
+  %
+  \global\def\code{\begingroup
+    \setupmarkupstyle{code}%
+    % The following should really be moved into \setupmarkupstyle handlers.
+    \catcode\dashChar=\active  \catcode\underChar=\active
+    \ifallowcodebreaks
+     \let-\codedash
+     \let_\codeunder
+    \else
+     \let-\normaldash
+     \let_\realunder
+    \fi
+    % Given -foo (with a single dash), we do not want to allow a break
+    % after the hyphen.
+    \global\let\codedashprev=\codedash
+    %
+    \codex
+  }
+  %
+  \gdef\codedash{\futurelet\next\codedashfinish}
+  \gdef\codedashfinish{%
+    \normaldash % always output the dash character itself.
+    %
+    % Now, output a discretionary to allow a line break, unless
+    % (a) the next character is a -, or
+    % (b) the preceding character is a -.
+    % E.g., given --posix, we do not want to allow a break after either -.
+    % Given --foo-bar, we do want to allow a break between the - and the b.
+    \ifx\next\codedash \else
+      \ifx\codedashprev\codedash
+      \else \discretionary{}{}{}\fi
+    \fi
+    % we need the space after the = for the case when \next itself is a
+    % space token; it would get swallowed otherwise.  As in @code{- a}.
+    \global\let\codedashprev= \next
+  }
+}
+\def\normaldash{-}
+%
+\def\codex #1{\tclose{#1}\endgroup}
+
+\def\codeunder{%
+  % this is all so @math{@code{var_name}+1} can work.  In math mode, _
+  % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
+  % will therefore expand the active definition of _, which is us
+  % (inside @code that is), therefore an endless loop.
+  \ifusingtt{\ifmmode
+               \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
+             \else\normalunderscore \fi
+             \discretionary{}{}{}}%
+            {\_}%
+}
+
+% An additional complication: the above will allow breaks after, e.g.,
+% each of the four underscores in __typeof__.  This is bad.
+% @allowcodebreaks provides a document-level way to turn breaking at -
+% and _ on and off.
+%
+\newif\ifallowcodebreaks  \allowcodebreakstrue
+
+\def\keywordtrue{true}
+\def\keywordfalse{false}
+
+\parseargdef\allowcodebreaks{%
+  \def\txiarg{#1}%
+  \ifx\txiarg\keywordtrue
+    \allowcodebreakstrue
+  \else\ifx\txiarg\keywordfalse
+    \allowcodebreaksfalse
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @allowcodebreaks option `\txiarg', must be true|false}%
+  \fi\fi
+}
+
+% For @command, @env, @file, @option quotes seem unnecessary,
+% so use \code rather than \samp.
+\let\command=\code
+\let\env=\code
+\let\file=\code
+\let\option=\code
+
+% @uref (abbreviation for `urlref') aka @url takes an optional
+% (comma-separated) second argument specifying the text to display and
+% an optional third arg as text to display instead of (rather than in
+% addition to) the url itself.  First (mandatory) arg is the url.
+
+% TeX-only option to allow changing PDF output to show only the second
+% arg (if given), and not the url (which is then just the link target).
+\newif\ifurefurlonlylink
+
+% The main macro is \urefbreak, which allows breaking at expected
+% places within the url.  (There used to be another version, which
+% didn't support automatic breaking.)
+\def\urefbreak{\begingroup \urefcatcodes \dourefbreak}
+\let\uref=\urefbreak
+%
+\def\dourefbreak#1{\urefbreakfinish #1,,,\finish}
+\def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example
+  \unsepspaces
+  \pdfurl{#1}%
+  \setbox0 = \hbox{\ignorespaces #3}%
+  \ifdim\wd0 > 0pt
+    \unhbox0 % third arg given, show only that
+  \else
+    \setbox0 = \hbox{\ignorespaces #2}% look for second arg
+    \ifdim\wd0 > 0pt
+      \ifpdf
+        \ifurefurlonlylink
+          % PDF plus option to not display url, show just arg
+          \unhbox0
+        \else
+          % PDF, normally display both arg and url for consistency,
+          % visibility, if the pdf is eventually used to print, etc.
+          \unhbox0\ (\urefcode{#1})%
+        \fi
+      \else
+        \unhbox0\ (\urefcode{#1})% DVI, always show arg and url
+      \fi
+    \else
+      \urefcode{#1}% only url given, so show it
+    \fi
+  \fi
+  \endlink
+\endgroup}
+
+% Allow line breaks around only a few characters (only).
+\def\urefcatcodes{%
+  \catcode`\&=\active \catcode`\.=\active
+  \catcode`\#=\active \catcode`\?=\active
+  \catcode`\/=\active
+}
+{
+  \urefcatcodes
+  %
+  \global\def\urefcode{\begingroup
+    \setupmarkupstyle{code}%
+    \urefcatcodes
+    \let&\urefcodeamp
+    \let.\urefcodedot
+    \let#\urefcodehash
+    \let?\urefcodequest
+    \let/\urefcodeslash
+    \codex
+  }
+  %
+  % By default, they are just regular characters.
+  \global\def&{\normalamp}
+  \global\def.{\normaldot}
+  \global\def#{\normalhash}
+  \global\def?{\normalquest}
+  \global\def/{\normalslash}
+}
+
+% we put a little stretch before and after the breakable chars, to help
+% line breaking of long url's.  The unequal skips make look better in
+% cmtt at least, especially for dots.
+\def\urefprestretchamount{.13em}
+\def\urefpoststretchamount{.1em}
+\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax}
+\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax}
+%
+\def\urefcodeamp{\urefprestretch \&\urefpoststretch}
+\def\urefcodedot{\urefprestretch .\urefpoststretch}
+\def\urefcodehash{\urefprestretch \#\urefpoststretch}
+\def\urefcodequest{\urefprestretch ?\urefpoststretch}
+\def\urefcodeslash{\futurelet\next\urefcodeslashfinish}
+{
+  \catcode`\/=\active
+  \global\def\urefcodeslashfinish{%
+    \urefprestretch \slashChar
+    % Allow line break only after the final / in a sequence of
+    % slashes, to avoid line break between the slashes in http://.
+    \ifx\next/\else \urefpoststretch \fi
+  }
+}
+
+% One more complication: by default we'll break after the special
+% characters, but some people like to break before the special chars, so
+% allow that.  Also allow no breaking at all, for manual control.
+%
+\parseargdef\urefbreakstyle{%
+  \def\txiarg{#1}%
+  \ifx\txiarg\wordnone
+    \def\urefprebreak{\nobreak}\def\urefpostbreak{\nobreak}
+  \else\ifx\txiarg\wordbefore
+    \def\urefprebreak{\allowbreak}\def\urefpostbreak{\nobreak}
+  \else\ifx\txiarg\wordafter
+    \def\urefprebreak{\nobreak}\def\urefpostbreak{\allowbreak}
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @urefbreakstyle setting `\txiarg'}%
+  \fi\fi\fi
+}
+\def\wordafter{after}
+\def\wordbefore{before}
+\def\wordnone{none}
+
+\urefbreakstyle after
+
+% @url synonym for @uref, since that's how everyone uses it.
+%
+\let\url=\uref
+
+% rms does not like angle brackets --karl, 17may97.
+% So now @email is just like @uref, unless we are pdf.
+%
+%\def\email#1{\angleleft{\tt #1}\angleright}
+\ifpdf
+  \def\email#1{\doemail#1,,\finish}
+  \def\doemail#1,#2,#3\finish{\begingroup
+    \unsepspaces
+    \pdfurl{mailto:#1}%
+    \setbox0 = \hbox{\ignorespaces #2}%
+    \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
+    \endlink
+  \endgroup}
+\else
+  \let\email=\uref
+\fi
+
+% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
+%   `example' (@kbd uses ttsl only inside of @example and friends),
+%   or `code' (@kbd uses normal tty font always).
+\parseargdef\kbdinputstyle{%
+  \def\txiarg{#1}%
+  \ifx\txiarg\worddistinct
+    \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
+  \else\ifx\txiarg\wordexample
+    \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
+  \else\ifx\txiarg\wordcode
+    \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @kbdinputstyle setting `\txiarg'}%
+  \fi\fi\fi
+}
+\def\worddistinct{distinct}
+\def\wordexample{example}
+\def\wordcode{code}
+
+% Default is `distinct'.
+\kbdinputstyle distinct
+
+% @kbd is like @code, except that if the argument is just one @key command,
+% then @kbd has no effect.
+\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}}
+
+\def\xkey{\key}
+\def\kbdsub#1#2#3\par{%
+  \def\one{#1}\def\three{#3}\def\threex{??}%
+  \ifx\one\xkey\ifx\threex\three \key{#2}%
+  \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
+  \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
+}
+
+% definition of @key that produces a lozenge.  Doesn't adjust to text size.
+%\setfont\keyrm\rmshape{8}{1000}{OT1}
+%\font\keysy=cmsy9
+%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
+%  \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
+%    \vbox{\hrule\kern-0.4pt
+%     \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
+%    \kern-0.4pt\hrule}%
+%  \kern-.06em\raise0.4pt\hbox{\angleright}}}}
+
+% definition of @key with no lozenge.  If the current font is already
+% monospace, don't change it; that way, we respect @kbdinputstyle.  But
+% if it isn't monospace, then use \tt.
+%
+\def\key#1{{\setupmarkupstyle{key}%
+  \nohyphenation
+  \ifmonospace\else\tt\fi
+  #1}\null}
+
+% @clicksequence{File @click{} Open ...}
+\def\clicksequence#1{\begingroup #1\endgroup}
+
+% @clickstyle @arrow   (by default)
+\parseargdef\clickstyle{\def\click{#1}}
+\def\click{\arrow}
+
+% Typeset a dimension, e.g., `in' or `pt'.  The only reason for the
+% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
+%
+\def\dmn#1{\thinspace #1}
+
+% @acronym for "FBI", "NATO", and the like.
+% We print this one point size smaller, since it's intended for
+% all-uppercase.
+%
+\def\acronym#1{\doacronym #1,,\finish}
+\def\doacronym#1,#2,#3\finish{%
+  {\selectfonts\lsize #1}%
+  \def\temp{#2}%
+  \ifx\temp\empty \else
+    \space ({\unsepspaces \ignorespaces \temp \unskip})%
+  \fi
+  \null % reset \spacefactor=1000
+}
+
+% @abbr for "Comput. J." and the like.
+% No font change, but don't do end-of-sentence spacing.
+%
+\def\abbr#1{\doabbr #1,,\finish}
+\def\doabbr#1,#2,#3\finish{%
+  {\plainfrenchspacing #1}%
+  \def\temp{#2}%
+  \ifx\temp\empty \else
+    \space ({\unsepspaces \ignorespaces \temp \unskip})%
+  \fi
+  \null % reset \spacefactor=1000
+}
+
+% @asis just yields its argument.  Used with @table, for example.
+%
+\def\asis#1{#1}
+
+% @math outputs its argument in math mode.
+%
+% One complication: _ usually means subscripts, but it could also mean
+% an actual _ character, as in @math{@var{some_variable} + 1}.  So make
+% _ active, and distinguish by seeing if the current family is \slfam,
+% which is what @var uses.
+{
+  \catcode`\_ = \active
+  \gdef\mathunderscore{%
+    \catcode`\_=\active
+    \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
+  }
+}
+% Another complication: we want \\ (and @\) to output a math (or tt) \.
+% FYI, plain.tex uses \\ as a temporary control sequence (for no
+% particular reason), but this is not advertised and we don't care.
+%
+% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
+\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
+%
+\def\math{%
+  \ifmmode\else % only go into math if not in math mode already
+    \tex
+    \mathunderscore
+    \let\\ = \mathbackslash
+    \mathactive
+    % make the texinfo accent commands work in math mode
+    \let\"=\ddot
+    \let\'=\acute
+    \let\==\bar
+    \let\^=\hat
+    \let\`=\grave
+    \let\u=\breve
+    \let\v=\check
+    \let\~=\tilde
+    \let\dotaccent=\dot
+    % have to provide another name for sup operator
+    \let\mathopsup=\sup
+  $\expandafter\finishmath\fi
+}
+\def\finishmath#1{#1$\endgroup}  % Close the group opened by \tex.
+
+% Some active characters (such as <) are spaced differently in math.
+% We have to reset their definitions in case the @math was an argument
+% to a command which sets the catcodes (such as @item or @section).
+%
+{
+  \catcode`^ = \active
+  \catcode`< = \active
+  \catcode`> = \active
+  \catcode`+ = \active
+  \catcode`' = \active
+  \gdef\mathactive{%
+    \let^ = \ptexhat
+    \let< = \ptexless
+    \let> = \ptexgtr
+    \let+ = \ptexplus
+    \let' = \ptexquoteright
+  }
+}
+
+% for @sub and @sup, if in math mode, just do a normal sub/superscript.
+% If in text, use math to place as sub/superscript, but switch
+% into text mode, with smaller fonts.  This is a different font than the
+% one used for real math sub/superscripts (8pt vs. 7pt), but let's not
+% fix it (significant additions to font machinery) until someone notices.
+%
+\def\sub{\ifmmode \expandafter\sb \else \expandafter\finishsub\fi}
+\def\finishsub#1{$\sb{\hbox{\selectfonts\lllsize #1}}$}%
+%
+\def\sup{\ifmmode \expandafter\ptexsp \else \expandafter\finishsup\fi}
+\def\finishsup#1{$\ptexsp{\hbox{\selectfonts\lllsize #1}}$}%
+
+% @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}.
+% Ignore unless FMTNAME == tex; then it is like @iftex and @tex,
+% except specified as a normal braced arg, so no newlines to worry about.
+%
+\def\outfmtnametex{tex}
+%
+\long\def\inlinefmt#1{\doinlinefmt #1,\finish}
+\long\def\doinlinefmt#1,#2,\finish{%
+  \def\inlinefmtname{#1}%
+  \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi
+}
+%
+% @inlinefmtifelse{FMTNAME,THEN-TEXT,ELSE-TEXT} expands THEN-TEXT if
+% FMTNAME is tex, else ELSE-TEXT.
+\long\def\inlinefmtifelse#1{\doinlinefmtifelse #1,,,\finish}
+\long\def\doinlinefmtifelse#1,#2,#3,#4,\finish{%
+  \def\inlinefmtname{#1}%
+  \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\else \ignorespaces #3\fi
+}
+%
+% For raw, must switch into @tex before parsing the argument, to avoid
+% setting catcodes prematurely.  Doing it this way means that, for
+% example, @inlineraw{html, foo{bar} gets a parse error instead of being
+% ignored.  But this isn't important because if people want a literal
+% *right* brace they would have to use a command anyway, so they may as
+% well use a command to get a left brace too.  We could re-use the
+% delimiter character idea from \verb, but it seems like overkill.
+%
+\long\def\inlineraw{\tex \doinlineraw}
+\long\def\doinlineraw#1{\doinlinerawtwo #1,\finish}
+\def\doinlinerawtwo#1,#2,\finish{%
+  \def\inlinerawname{#1}%
+  \ifx\inlinerawname\outfmtnametex \ignorespaces #2\fi
+  \endgroup % close group opened by \tex.
+}
+
+% @inlineifset{VAR, TEXT} expands TEXT if VAR is @set.
+%
+\long\def\inlineifset#1{\doinlineifset #1,\finish}
+\long\def\doinlineifset#1,#2,\finish{%
+  \def\inlinevarname{#1}%
+  \expandafter\ifx\csname SET\inlinevarname\endcsname\relax
+  \else\ignorespaces#2\fi
+}
+
+% @inlineifclear{VAR, TEXT} expands TEXT if VAR is not @set.
+%
+\long\def\inlineifclear#1{\doinlineifclear #1,\finish}
+\long\def\doinlineifclear#1,#2,\finish{%
+  \def\inlinevarname{#1}%
+  \expandafter\ifx\csname SET\inlinevarname\endcsname\relax \ignorespaces#2\fi
+}
+
+
+\message{glyphs,}
+% and logos.
+
+% @@ prints an @, as does @atchar{}.
+\def\@{\char64 }
+\let\atchar=\@
+
+% @{ @} @lbracechar{} @rbracechar{} all generate brace characters.
+% Unless we're in typewriter, use \ecfont because the CM text fonts do
+% not have braces, and we don't want to switch into math.
+\def\mylbrace{{\ifmonospace\else\ecfont\fi \char123}}
+\def\myrbrace{{\ifmonospace\else\ecfont\fi \char125}}
+\let\{=\mylbrace \let\lbracechar=\{
+\let\}=\myrbrace \let\rbracechar=\}
+\begingroup
+  % Definitions to produce \{ and \} commands for indices,
+  % and @{ and @} for the aux/toc files.
+  \catcode`\{ = \other \catcode`\} = \other
+  \catcode`\[ = 1 \catcode`\] = 2
+  \catcode`\! = 0 \catcode`\\ = \other
+  !gdef!lbracecmd[\{]%
+  !gdef!rbracecmd[\}]%
+  !gdef!lbraceatcmd[@{]%
+  !gdef!rbraceatcmd[@}]%
+!endgroup
+
+% @comma{} to avoid , parsing problems.
+\let\comma = ,
+
+% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
+% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H.
+\let\, = \ptexc
+\let\dotaccent = \ptexdot
+\def\ringaccent#1{{\accent23 #1}}
+\let\tieaccent = \ptext
+\let\ubaraccent = \ptexb
+\let\udotaccent = \d
+
+% Other special characters: @questiondown @exclamdown @ordf @ordm
+% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss.
+\def\questiondown{?`}
+\def\exclamdown{!`}
+\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}}
+\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}}
+
+% Dotless i and dotless j, used for accents.
+\def\imacro{i}
+\def\jmacro{j}
+\def\dotless#1{%
+  \def\temp{#1}%
+  \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi
+  \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi
+  \else \errmessage{@dotless can be used only with i or j}%
+  \fi\fi
+}
+
+% The \TeX{} logo, as in plain, but resetting the spacing so that a
+% period following counts as ending a sentence.  (Idea found in latex.)
+%
+\edef\TeX{\TeX \spacefactor=1000 }
+
+% @LaTeX{} logo.  Not quite the same results as the definition in
+% latex.ltx, since we use a different font for the raised A; it's most
+% convenient for us to use an explicitly smaller font, rather than using
+% the \scriptstyle font (since we don't reset \scriptstyle and
+% \scriptscriptstyle).
+%
+\def\LaTeX{%
+  L\kern-.36em
+  {\setbox0=\hbox{T}%
+   \vbox to \ht0{\hbox{%
+     \ifx\textnominalsize\xwordpt
+       % for 10pt running text, \lllsize (8pt) is too small for the A in LaTeX.
+       % Revert to plain's \scriptsize, which is 7pt.
+       \count255=\the\fam $\fam\count255 \scriptstyle A$%
+     \else
+       % For 11pt, we can use our lllsize.
+       \selectfonts\lllsize A%
+     \fi
+     }%
+     \vss
+  }}%
+  \kern-.15em
+  \TeX
+}
+
+% Some math mode symbols.  Define \ensuremath to switch into math mode
+% unless we are already there.  Expansion tricks may not be needed here,
+% but safer, and can't hurt.
+\def\ensuremath{\ifmmode \expandafter\asis \else\expandafter\ensuredmath \fi}
+\def\ensuredmath#1{$\relax#1$}
+%
+\def\bullet{\ensuremath\ptexbullet}
+\def\geq{\ensuremath\ge}
+\def\leq{\ensuremath\le}
+\def\minus{\ensuremath-}
+
+% @dots{} outputs an ellipsis using the current font.
+% We do .5em per period so that it has the same spacing in the cm
+% typewriter fonts as three actual period characters; on the other hand,
+% in other typewriter fonts three periods are wider than 1.5em.  So do
+% whichever is larger.
+%
+\def\dots{%
+  \leavevmode
+  \setbox0=\hbox{...}% get width of three periods
+  \ifdim\wd0 > 1.5em
+    \dimen0 = \wd0
+  \else
+    \dimen0 = 1.5em
+  \fi
+  \hbox to \dimen0{%
+    \hskip 0pt plus.25fil
+    .\hskip 0pt plus1fil
+    .\hskip 0pt plus1fil
+    .\hskip 0pt plus.5fil
+  }%
+}
+
+% @enddots{} is an end-of-sentence ellipsis.
+%
+\def\enddots{%
+  \dots
+  \spacefactor=\endofsentencespacefactor
+}
+
+% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+%
+% Since these characters are used in examples, they should be an even number of
+% \tt widths. Each \tt character is 1en, so two makes it 1em.
+%
+\def\point{$\star$}
+\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}}
+\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
+\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}}
+\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
+\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}}
+
+% The @error{} command.
+% Adapted from the TeXbook's \boxit.
+%
+\newbox\errorbox
+%
+{\tentt \global\dimen0 = 3em}% Width of the box.
+\dimen2 = .55pt % Thickness of rules
+% The text. (`r' is open on the right, `e' somewhat less so on the left.)
+\setbox0 = \hbox{\kern-.75pt \reducedsf \putworderror\kern-1.5pt}
+%
+\setbox\errorbox=\hbox to \dimen0{\hfil
+   \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
+   \advance\hsize by -2\dimen2 % Rules.
+   \vbox{%
+      \hrule height\dimen2
+      \hbox{\vrule width\dimen2 \kern3pt          % Space to left of text.
+         \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
+         \kern3pt\vrule width\dimen2}% Space to right.
+      \hrule height\dimen2}
+    \hfil}
+%
+\def\error{\leavevmode\lower.7ex\copy\errorbox}
+
+% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
+%
+\def\pounds{{\it\$}}
+
+% @euro{} comes from a separate font, depending on the current style.
+% We use the free feym* fonts from the eurosym package by Henrik
+% Theiling, which support regular, slanted, bold and bold slanted (and
+% "outlined" (blackboard board, sort of) versions, which we don't need).
+% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
+%
+% Although only regular is the truly official Euro symbol, we ignore
+% that.  The Euro is designed to be slightly taller than the regular
+% font height.
+%
+% feymr - regular
+% feymo - slanted
+% feybr - bold
+% feybo - bold slanted
+%
+% There is no good (free) typewriter version, to my knowledge.
+% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
+% Hmm.
+%
+% Also doesn't work in math.  Do we need to do math with euro symbols?
+% Hope not.
+%
+%
+\def\euro{{\eurofont e}}
+\def\eurofont{%
+  % We set the font at each command, rather than predefining it in
+  % \textfonts and the other font-switching commands, so that
+  % installations which never need the symbol don't have to have the
+  % font installed.
+  %
+  % There is only one designed size (nominal 10pt), so we always scale
+  % that to the current nominal size.
+  %
+  % By the way, simply using "at 1em" works for cmr10 and the like, but
+  % does not work for cmbx10 and other extended/shrunken fonts.
+  %
+  \def\eurosize{\csname\curfontsize nominalsize\endcsname}%
+  %
+  \ifx\curfontstyle\bfstylename
+    % bold:
+    \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
+  \else
+    % regular:
+    \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
+  \fi
+  \thiseurofont
+}
+
+% Glyphs from the EC fonts.  We don't use \let for the aliases, because
+% sometimes we redefine the original macro, and the alias should reflect
+% the redefinition.
+%
+% Use LaTeX names for the Icelandic letters.
+\def\DH{{\ecfont \char"D0}} % Eth
+\def\dh{{\ecfont \char"F0}} % eth
+\def\TH{{\ecfont \char"DE}} % Thorn
+\def\th{{\ecfont \char"FE}} % thorn
+%
+\def\guillemetleft{{\ecfont \char"13}}
+\def\guillemotleft{\guillemetleft}
+\def\guillemetright{{\ecfont \char"14}}
+\def\guillemotright{\guillemetright}
+\def\guilsinglleft{{\ecfont \char"0E}}
+\def\guilsinglright{{\ecfont \char"0F}}
+\def\quotedblbase{{\ecfont \char"12}}
+\def\quotesinglbase{{\ecfont \char"0D}}
+%
+% This positioning is not perfect (see the ogonek LaTeX package), but
+% we have the precomposed glyphs for the most common cases.  We put the
+% tests to use those glyphs in the single \ogonek macro so we have fewer
+% dummy definitions to worry about for index entries, etc.
+%
+% ogonek is also used with other letters in Lithuanian (IOU), but using
+% the precomposed glyphs for those is not so easy since they aren't in
+% the same EC font.
+\def\ogonek#1{{%
+  \def\temp{#1}%
+  \ifx\temp\macrocharA\Aogonek
+  \else\ifx\temp\macrochara\aogonek
+  \else\ifx\temp\macrocharE\Eogonek
+  \else\ifx\temp\macrochare\eogonek
+  \else
+    \ecfont \setbox0=\hbox{#1}%
+    \ifdim\ht0=1ex\accent"0C #1%
+    \else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}%
+    \fi
+  \fi\fi\fi\fi
+  }%
+}
+\def\Aogonek{{\ecfont \char"81}}\def\macrocharA{A}
+\def\aogonek{{\ecfont \char"A1}}\def\macrochara{a}
+\def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E}
+\def\eogonek{{\ecfont \char"A6}}\def\macrochare{e}
+%
+% Use the European Computer Modern fonts (cm-super in outline format)
+% for non-CM glyphs.  That is ec* for regular text and tc* for the text
+% companion symbols (LaTeX TS1 encoding).  Both are part of the ec
+% package and follow the same conventions.
+%
+\def\ecfont{\etcfont{e}}
+\def\tcfont{\etcfont{t}}
+%
+\def\etcfont#1{%
+  % We can't distinguish serif/sans and italic/slanted, but this
+  % is used for crude hacks anyway (like adding French and German
+  % quotes to documents typeset with CM, where we lose kerning), so
+  % hopefully nobody will notice/care.
+  \edef\ecsize{\csname\curfontsize ecsize\endcsname}%
+  \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}%
+  \ifmonospace
+    % typewriter:
+    \font\thisecfont = #1ctt\ecsize \space at \nominalsize
+  \else
+    \ifx\curfontstyle\bfstylename
+      % bold:
+      \font\thisecfont = #1cb\ifusingit{i}{x}\ecsize \space at \nominalsize
+    \else
+      % regular:
+      \font\thisecfont = #1c\ifusingit{ti}{rm}\ecsize \space at \nominalsize
+    \fi
+  \fi
+  \thisecfont
+}
+
+% @registeredsymbol - R in a circle.  The font for the R should really
+% be smaller yet, but lllsize is the best we can do for now.
+% Adapted from the plain.tex definition of \copyright.
+%
+\def\registeredsymbol{%
+  $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}%
+               \hfil\crcr\Orb}}%
+    }$%
+}
+
+% @textdegree - the normal degrees sign.
+%
+\def\textdegree{$^\circ$}
+
+% Laurent Siebenmann reports \Orb undefined with:
+%  Textures 1.7.7 (preloaded format=plain 93.10.14)  (68K)  16 APR 2004 02:38
+% so we'll define it if necessary.
+%
+\ifx\Orb\thisisundefined
+\def\Orb{\mathhexbox20D}
+\fi
+
+% Quotes.
+\chardef\quotedblleft="5C
+\chardef\quotedblright=`\"
+\chardef\quoteleft=`\`
+\chardef\quoteright=`\'
+
+
+\message{page headings,}
+
+\newskip\titlepagetopglue \titlepagetopglue = 1.5in
+\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
+
+% First the title page.  Must do @settitle before @titlepage.
+\newif\ifseenauthor
+\newif\iffinishedtitlepage
+
+% Do an implicit @contents or @shortcontents after @end titlepage if the
+% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
+%
+\newif\ifsetcontentsaftertitlepage
+ \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
+\newif\ifsetshortcontentsaftertitlepage
+ \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
+
+\parseargdef\shorttitlepage{%
+  \begingroup \hbox{}\vskip 1.5in \chaprm \centerline{#1}%
+  \endgroup\page\hbox{}\page}
+
+\envdef\titlepage{%
+  % Open one extra group, as we want to close it in the middle of \Etitlepage.
+  \begingroup
+    \parindent=0pt \textfonts
+    % Leave some space at the very top of the page.
+    \vglue\titlepagetopglue
+    % No rule at page bottom unless we print one at the top with @title.
+    \finishedtitlepagetrue
+    %
+    % Most title ``pages'' are actually two pages long, with space
+    % at the top of the second.  We don't want the ragged left on the second.
+    \let\oldpage = \page
+    \def\page{%
+      \iffinishedtitlepage\else
+	 \finishtitlepage
+      \fi
+      \let\page = \oldpage
+      \page
+      \null
+    }%
+}
+
+\def\Etitlepage{%
+    \iffinishedtitlepage\else
+	\finishtitlepage
+    \fi
+    % It is important to do the page break before ending the group,
+    % because the headline and footline are only empty inside the group.
+    % If we use the new definition of \page, we always get a blank page
+    % after the title page, which we certainly don't want.
+    \oldpage
+  \endgroup
+  %
+  % Need this before the \...aftertitlepage checks so that if they are
+  % in effect the toc pages will come out with page numbers.
+  \HEADINGSon
+  %
+  % If they want short, they certainly want long too.
+  \ifsetshortcontentsaftertitlepage
+    \shortcontents
+    \contents
+    \global\let\shortcontents = \relax
+    \global\let\contents = \relax
+  \fi
+  %
+  \ifsetcontentsaftertitlepage
+    \contents
+    \global\let\contents = \relax
+    \global\let\shortcontents = \relax
+  \fi
+}
+
+\def\finishtitlepage{%
+  \vskip4pt \hrule height 2pt width \hsize
+  \vskip\titlepagebottomglue
+  \finishedtitlepagetrue
+}
+
+% Settings used for typesetting titles: no hyphenation, no indentation,
+% don't worry much about spacing, ragged right.  This should be used
+% inside a \vbox, and fonts need to be set appropriately first.  Because
+% it is always used for titles, nothing else, we call \rmisbold.  \par
+% should be specified before the end of the \vbox, since a vbox is a group.
+%
+\def\raggedtitlesettings{%
+  \rmisbold
+  \hyphenpenalty=10000
+  \parindent=0pt
+  \tolerance=5000
+  \ptexraggedright
+}
+
+% Macros to be used within @titlepage:
+
+\let\subtitlerm=\tenrm
+\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
+
+\parseargdef\title{%
+  \checkenv\titlepage
+  \vbox{\titlefonts \raggedtitlesettings #1\par}%
+  % print a rule at the page bottom also.
+  \finishedtitlepagefalse
+  \vskip4pt \hrule height 4pt width \hsize \vskip4pt
+}
+
+\parseargdef\subtitle{%
+  \checkenv\titlepage
+  {\subtitlefont \rightline{#1}}%
+}
+
+% @author should come last, but may come many times.
+% It can also be used inside @quotation.
+%
+\parseargdef\author{%
+  \def\temp{\quotation}%
+  \ifx\thisenv\temp
+    \def\quotationauthor{#1}% printed in \Equotation.
+  \else
+    \checkenv\titlepage
+    \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
+    {\secfonts\rmisbold \leftline{#1}}%
+  \fi
+}
+
+
+% Set up page headings and footings.
+
+\let\thispage=\folio
+
+\newtoks\evenheadline    % headline on even pages
+\newtoks\oddheadline     % headline on odd pages
+\newtoks\evenfootline    % footline on even pages
+\newtoks\oddfootline     % footline on odd pages
+
+% Now make \makeheadline and \makefootline in Plain TeX use those variables
+\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
+                            \else \the\evenheadline \fi}}
+\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
+                            \else \the\evenfootline \fi}\HEADINGShook}
+\let\HEADINGShook=\relax
+
+% Commands to set those variables.
+% For example, this is what  @headings on  does
+% @evenheading @thistitle|@thispage|@thischapter
+% @oddheading @thischapter|@thispage|@thistitle
+% @evenfooting @thisfile||
+% @oddfooting ||@thisfile
+
+
+\def\evenheading{\parsearg\evenheadingxxx}
+\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
+\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddheading{\parsearg\oddheadingxxx}
+\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
+\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
+
+\def\evenfooting{\parsearg\evenfootingxxx}
+\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish}
+\def\evenfootingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddfooting{\parsearg\oddfootingxxx}
+\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish}
+\def\oddfootingyyy #1\|#2\|#3\|#4\finish{%
+  \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
+  %
+  % Leave some space for the footline.  Hopefully ok to assume
+  % @evenfooting will not be used by itself.
+  \global\advance\pageheight by -12pt
+  \global\advance\vsize by -12pt
+}
+
+\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}}
+
+% @evenheadingmarks top     \thischapter <- chapter at the top of a page
+% @evenheadingmarks bottom  \thischapter <- chapter at the bottom of a page
+%
+% The same set of arguments for:
+%
+% @oddheadingmarks
+% @evenfootingmarks
+% @oddfootingmarks
+% @everyheadingmarks
+% @everyfootingmarks
+
+% These define \getoddheadingmarks, \getevenheadingmarks,
+% \getoddfootingmarks, and \getevenfootingmarks, each to one of
+% \gettopheadingmarks, \getbottomheadingmarks.
+%
+\def\evenheadingmarks{\headingmarks{even}{heading}}
+\def\oddheadingmarks{\headingmarks{odd}{heading}}
+\def\evenfootingmarks{\headingmarks{even}{footing}}
+\def\oddfootingmarks{\headingmarks{odd}{footing}}
+\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1}
+                          \headingmarks{odd}{heading}{#1} }
+\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1}
+                          \headingmarks{odd}{footing}{#1} }
+% #1 = even/odd, #2 = heading/footing, #3 = top/bottom.
+\def\headingmarks#1#2#3 {%
+  \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname
+  \global\expandafter\let\csname get#1#2marks\endcsname \temp
+}
+
+\everyheadingmarks bottom
+\everyfootingmarks bottom
+
+% @headings double      turns headings on for double-sided printing.
+% @headings single      turns headings on for single-sided printing.
+% @headings off         turns them off.
+% @headings on          same as @headings double, retained for compatibility.
+% @headings after       turns on double-sided headings after this page.
+% @headings doubleafter turns on double-sided headings after this page.
+% @headings singleafter turns on single-sided headings after this page.
+% By default, they are off at the start of a document,
+% and turned `on' after @end titlepage.
+
+\def\headings #1 {\csname HEADINGS#1\endcsname}
+
+\def\headingsoff{% non-global headings elimination
+  \evenheadline={\hfil}\evenfootline={\hfil}%
+   \oddheadline={\hfil}\oddfootline={\hfil}%
+}
+
+\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting
+\HEADINGSoff  % it's the default
+
+% When we turn headings on, set the page number to 1.
+% For double-sided printing, put current file name in lower left corner,
+% chapter name on inside top of right hand pages, document
+% title on inside top of left hand pages, and page numbers on outside top
+% edge of all pages.
+\def\HEADINGSdouble{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+\let\contentsalignmacro = \chappager
+
+% For single-sided printing, chapter title goes across top left of page,
+% page number on top right.
+\def\HEADINGSsingle{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapterheading\hfil\folio}}
+\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+\def\HEADINGSon{\HEADINGSdouble}
+
+\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
+\let\HEADINGSdoubleafter=\HEADINGSafter
+\def\HEADINGSdoublex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+
+\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
+\def\HEADINGSsinglex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapterheading\hfil\folio}}
+\global\oddheadline={\line{\thischapterheading\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+
+% Subroutines used in generating headings
+% This produces Day Month Year style of output.
+% Only define if not already defined, in case a txi-??.tex file has set
+% up a different format (e.g., txi-cs.tex does this).
+\ifx\today\thisisundefined
+\def\today{%
+  \number\day\space
+  \ifcase\month
+  \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
+  \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
+  \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
+  \fi
+  \space\number\year}
+\fi
+
+% @settitle line...  specifies the title of the document, for headings.
+% It generates no output of its own.
+\def\thistitle{\putwordNoTitle}
+\def\settitle{\parsearg{\gdef\thistitle}}
+
+
+\message{tables,}
+% Tables -- @table, @ftable, @vtable, @item(x).
+
+% default indentation of table text
+\newdimen\tableindent \tableindent=.8in
+% default indentation of @itemize and @enumerate text
+\newdimen\itemindent  \itemindent=.3in
+% margin between end of table item and start of table text.
+\newdimen\itemmargin  \itemmargin=.1in
+
+% used internally for \itemindent minus \itemmargin
+\newdimen\itemmax
+
+% Note @table, @ftable, and @vtable define @item, @itemx, etc., with
+% these defs.
+% They also define \itemindex
+% to index the item name in whatever manner is desired (perhaps none).
+
+\newif\ifitemxneedsnegativevskip
+
+\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
+
+\def\internalBitem{\smallbreak \parsearg\itemzzz}
+\def\internalBitemx{\itemxpar \parsearg\itemzzz}
+
+\def\itemzzz #1{\begingroup %
+  \advance\hsize by -\rightskip
+  \advance\hsize by -\tableindent
+  \setbox0=\hbox{\itemindicate{#1}}%
+  \itemindex{#1}%
+  \nobreak % This prevents a break before @itemx.
+  %
+  % If the item text does not fit in the space we have, put it on a line
+  % by itself, and do not allow a page break either before or after that
+  % line.  We do not start a paragraph here because then if the next
+  % command is, e.g., @kindex, the whatsit would get put into the
+  % horizontal list on a line by itself, resulting in extra blank space.
+  \ifdim \wd0>\itemmax
+    %
+    % Make this a paragraph so we get the \parskip glue and wrapping,
+    % but leave it ragged-right.
+    \begingroup
+      \advance\leftskip by-\tableindent
+      \advance\hsize by\tableindent
+      \advance\rightskip by0pt plus1fil\relax
+      \leavevmode\unhbox0\par
+    \endgroup
+    %
+    % We're going to be starting a paragraph, but we don't want the
+    % \parskip glue -- logically it's part of the @item we just started.
+    \nobreak \vskip-\parskip
+    %
+    % Stop a page break at the \parskip glue coming up.  However, if
+    % what follows is an environment such as @example, there will be no
+    % \parskip glue; then the negative vskip we just inserted would
+    % cause the example and the item to crash together.  So we use this
+    % bizarre value of 10001 as a signal to \aboveenvbreak to insert
+    % \parskip glue after all.  Section titles are handled this way also.
+    %
+    \penalty 10001
+    \endgroup
+    \itemxneedsnegativevskipfalse
+  \else
+    % The item text fits into the space.  Start a paragraph, so that the
+    % following text (if any) will end up on the same line.
+    \noindent
+    % Do this with kerns and \unhbox so that if there is a footnote in
+    % the item text, it can migrate to the main vertical list and
+    % eventually be printed.
+    \nobreak\kern-\tableindent
+    \dimen0 = \itemmax  \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
+    \unhbox0
+    \nobreak\kern\dimen0
+    \endgroup
+    \itemxneedsnegativevskiptrue
+  \fi
+}
+
+\def\item{\errmessage{@item while not in a list environment}}
+\def\itemx{\errmessage{@itemx while not in a list environment}}
+
+% @table, @ftable, @vtable.
+\envdef\table{%
+  \let\itemindex\gobble
+  \tablecheck{table}%
+}
+\envdef\ftable{%
+  \def\itemindex ##1{\doind {fn}{\code{##1}}}%
+  \tablecheck{ftable}%
+}
+\envdef\vtable{%
+  \def\itemindex ##1{\doind {vr}{\code{##1}}}%
+  \tablecheck{vtable}%
+}
+\def\tablecheck#1{%
+  \ifnum \the\catcode`\^^M=\active
+    \endgroup
+    \errmessage{This command won't work in this context; perhaps the problem is
+      that we are \inenvironment\thisenv}%
+    \def\next{\doignore{#1}}%
+  \else
+    \let\next\tablex
+  \fi
+  \next
+}
+\def\tablex#1{%
+  \def\itemindicate{#1}%
+  \parsearg\tabley
+}
+\def\tabley#1{%
+  {%
+    \makevalueexpandable
+    \edef\temp{\noexpand\tablez #1\space\space\space}%
+    \expandafter
+  }\temp \endtablez
+}
+\def\tablez #1 #2 #3 #4\endtablez{%
+  \aboveenvbreak
+  \ifnum 0#1>0 \advance \leftskip by #1\mil \fi
+  \ifnum 0#2>0 \tableindent=#2\mil \fi
+  \ifnum 0#3>0 \advance \rightskip by #3\mil \fi
+  \itemmax=\tableindent
+  \advance \itemmax by -\itemmargin
+  \advance \leftskip by \tableindent
+  \exdentamount=\tableindent
+  \parindent = 0pt
+  \parskip = \smallskipamount
+  \ifdim \parskip=0pt \parskip=2pt \fi
+  \let\item = \internalBitem
+  \let\itemx = \internalBitemx
+}
+\def\Etable{\endgraf\afterenvbreak}
+\let\Eftable\Etable
+\let\Evtable\Etable
+\let\Eitemize\Etable
+\let\Eenumerate\Etable
+
+% This is the counter used by @enumerate, which is really @itemize
+
+\newcount \itemno
+
+\envdef\itemize{\parsearg\doitemize}
+
+\def\doitemize#1{%
+  \aboveenvbreak
+  \itemmax=\itemindent
+  \advance\itemmax by -\itemmargin
+  \advance\leftskip by \itemindent
+  \exdentamount=\itemindent
+  \parindent=0pt
+  \parskip=\smallskipamount
+  \ifdim\parskip=0pt \parskip=2pt \fi
+  %
+  % Try typesetting the item mark so that if the document erroneously says
+  % something like @itemize @samp (intending @table), there's an error
+  % right away at the @itemize.  It's not the best error message in the
+  % world, but it's better than leaving it to the @item.  This means if
+  % the user wants an empty mark, they have to say @w{} not just @w.
+  \def\itemcontents{#1}%
+  \setbox0 = \hbox{\itemcontents}%
+  %
+  % @itemize with no arg is equivalent to @itemize @bullet.
+  \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
+  %
+  \let\item=\itemizeitem
+}
+
+% Definition of @item while inside @itemize and @enumerate.
+%
+\def\itemizeitem{%
+  \advance\itemno by 1  % for enumerations
+  {\let\par=\endgraf \smallbreak}% reasonable place to break
+  {%
+   % If the document has an @itemize directly after a section title, a
+   % \nobreak will be last on the list, and \sectionheading will have
+   % done a \vskip-\parskip.  In that case, we don't want to zero
+   % parskip, or the item text will crash with the heading.  On the
+   % other hand, when there is normal text preceding the item (as there
+   % usually is), we do want to zero parskip, or there would be too much
+   % space.  In that case, we won't have a \nobreak before.  At least
+   % that's the theory.
+   \ifnum\lastpenalty<10000 \parskip=0in \fi
+   \noindent
+   \hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
+   %
+   \ifinner\else
+     \vadjust{\penalty 1200}% not good to break after first line of item.
+   \fi
+   % We can be in inner vertical mode in a footnote, although an
+   % @itemize looks awful there.
+  }%
+  \flushcr
+}
+
+% \splitoff TOKENS\endmark defines \first to be the first token in
+% TOKENS, and \rest to be the remainder.
+%
+\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
+
+% Allow an optional argument of an uppercase letter, lowercase letter,
+% or number, to specify the first label in the enumerated list.  No
+% argument is the same as `1'.
+%
+\envparseargdef\enumerate{\enumeratey #1  \endenumeratey}
+\def\enumeratey #1 #2\endenumeratey{%
+  % If we were given no argument, pretend we were given `1'.
+  \def\thearg{#1}%
+  \ifx\thearg\empty \def\thearg{1}\fi
+  %
+  % Detect if the argument is a single token.  If so, it might be a
+  % letter.  Otherwise, the only valid thing it can be is a number.
+  % (We will always have one token, because of the test we just made.
+  % This is a good thing, since \splitoff doesn't work given nothing at
+  % all -- the first parameter is undelimited.)
+  \expandafter\splitoff\thearg\endmark
+  \ifx\rest\empty
+    % Only one token in the argument.  It could still be anything.
+    % A ``lowercase letter'' is one whose \lccode is nonzero.
+    % An ``uppercase letter'' is one whose \lccode is both nonzero, and
+    %   not equal to itself.
+    % Otherwise, we assume it's a number.
+    %
+    % We need the \relax at the end of the \ifnum lines to stop TeX from
+    % continuing to look for a <number>.
+    %
+    \ifnum\lccode\expandafter`\thearg=0\relax
+      \numericenumerate % a number (we hope)
+    \else
+      % It's a letter.
+      \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
+        \lowercaseenumerate % lowercase letter
+      \else
+        \uppercaseenumerate % uppercase letter
+      \fi
+    \fi
+  \else
+    % Multiple tokens in the argument.  We hope it's a number.
+    \numericenumerate
+  \fi
+}
+
+% An @enumerate whose labels are integers.  The starting integer is
+% given in \thearg.
+%
+\def\numericenumerate{%
+  \itemno = \thearg
+  \startenumeration{\the\itemno}%
+}
+
+% The starting (lowercase) letter is in \thearg.
+\def\lowercaseenumerate{%
+  \itemno = \expandafter`\thearg
+  \startenumeration{%
+    % Be sure we're not beyond the end of the alphabet.
+    \ifnum\itemno=0
+      \errmessage{No more lowercase letters in @enumerate; get a bigger
+                  alphabet}%
+    \fi
+    \char\lccode\itemno
+  }%
+}
+
+% The starting (uppercase) letter is in \thearg.
+\def\uppercaseenumerate{%
+  \itemno = \expandafter`\thearg
+  \startenumeration{%
+    % Be sure we're not beyond the end of the alphabet.
+    \ifnum\itemno=0
+      \errmessage{No more uppercase letters in @enumerate; get a bigger
+                  alphabet}
+    \fi
+    \char\uccode\itemno
+  }%
+}
+
+% Call \doitemize, adding a period to the first argument and supplying the
+% common last two arguments.  Also subtract one from the initial value in
+% \itemno, since @item increments \itemno.
+%
+\def\startenumeration#1{%
+  \advance\itemno by -1
+  \doitemize{#1.}\flushcr
+}
+
+% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
+% to @enumerate.
+%
+\def\alphaenumerate{\enumerate{a}}
+\def\capsenumerate{\enumerate{A}}
+\def\Ealphaenumerate{\Eenumerate}
+\def\Ecapsenumerate{\Eenumerate}
+
+
+% @multitable macros
+% Amy Hendrickson, 8/18/94, 3/6/96
+%
+% @multitable ... @end multitable will make as many columns as desired.
+% Contents of each column will wrap at width given in preamble.  Width
+% can be specified either with sample text given in a template line,
+% or in percent of \hsize, the current width of text on page.
+
+% Table can continue over pages but will only break between lines.
+
+% To make preamble:
+%
+% Either define widths of columns in terms of percent of \hsize:
+%   @multitable @columnfractions .25 .3 .45
+%   @item ...
+%
+%   Numbers following @columnfractions are the percent of the total
+%   current hsize to be used for each column. You may use as many
+%   columns as desired.
+
+
+% Or use a template:
+%   @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+%   @item ...
+%   using the widest term desired in each column.
+
+% Each new table line starts with @item, each subsequent new column
+% starts with @tab. Empty columns may be produced by supplying @tab's
+% with nothing between them for as many times as empty columns are needed,
+% ie, @tab@tab@tab will produce two empty columns.
+
+% @item, @tab do not need to be on their own lines, but it will not hurt
+% if they are.
+
+% Sample multitable:
+
+%   @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+%   @item first col stuff @tab second col stuff @tab third col
+%   @item
+%   first col stuff
+%   @tab
+%   second col stuff
+%   @tab
+%   third col
+%   @item first col stuff @tab second col stuff
+%   @tab Many paragraphs of text may be used in any column.
+%
+%         They will wrap at the width determined by the template.
+%   @item@tab@tab This will be in third column.
+%   @end multitable
+
+% Default dimensions may be reset by user.
+% @multitableparskip is vertical space between paragraphs in table.
+% @multitableparindent is paragraph indent in table.
+% @multitablecolmargin is horizontal space to be left between columns.
+% @multitablelinespace is space to leave between table items, baseline
+%                                                            to baseline.
+%   0pt means it depends on current normal line spacing.
+%
+\newskip\multitableparskip
+\newskip\multitableparindent
+\newdimen\multitablecolspace
+\newskip\multitablelinespace
+\multitableparskip=0pt
+\multitableparindent=6pt
+\multitablecolspace=12pt
+\multitablelinespace=0pt
+
+% Macros used to set up halign preamble:
+%
+\let\endsetuptable\relax
+\def\xendsetuptable{\endsetuptable}
+\let\columnfractions\relax
+\def\xcolumnfractions{\columnfractions}
+\newif\ifsetpercent
+
+% #1 is the @columnfraction, usually a decimal number like .5, but might
+% be just 1.  We just use it, whatever it is.
+%
+\def\pickupwholefraction#1 {%
+  \global\advance\colcount by 1
+  \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}%
+  \setuptable
+}
+
+\newcount\colcount
+\def\setuptable#1{%
+  \def\firstarg{#1}%
+  \ifx\firstarg\xendsetuptable
+    \let\go = \relax
+  \else
+    \ifx\firstarg\xcolumnfractions
+      \global\setpercenttrue
+    \else
+      \ifsetpercent
+         \let\go\pickupwholefraction
+      \else
+         \global\advance\colcount by 1
+         \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a
+                   % separator; typically that is always in the input, anyway.
+         \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
+      \fi
+    \fi
+    \ifx\go\pickupwholefraction
+      % Put the argument back for the \pickupwholefraction call, so
+      % we'll always have a period there to be parsed.
+      \def\go{\pickupwholefraction#1}%
+    \else
+      \let\go = \setuptable
+    \fi%
+  \fi
+  \go
+}
+
+% multitable-only commands.
+%
+% @headitem starts a heading row, which we typeset in bold.  Assignments
+% have to be global since we are inside the implicit group of an
+% alignment entry.  \everycr below resets \everytab so we don't have to
+% undo it ourselves.
+\def\headitemfont{\b}% for people to use in the template row; not changeable
+\def\headitem{%
+  \checkenv\multitable
+  \crcr
+  \gdef\headitemcrhook{\nobreak}% attempt to avoid page break after headings
+  \global\everytab={\bf}% can't use \headitemfont since the parsing differs
+  \the\everytab % for the first item
+}%
+%
+% default for tables with no headings.
+\let\headitemcrhook=\relax
+%
+% A \tab used to include \hskip1sp.  But then the space in a template
+% line is not enough.  That is bad.  So let's go back to just `&' until
+% we again encounter the problem the 1sp was intended to solve.
+%					--karl, nathan@acm.org, 20apr99.
+\def\tab{\checkenv\multitable &\the\everytab}%
+
+% @multitable ... @end multitable definitions:
+%
+\newtoks\everytab  % insert after every tab.
+%
+\envdef\multitable{%
+  \vskip\parskip
+  \startsavinginserts
+  %
+  % @item within a multitable starts a normal row.
+  % We use \def instead of \let so that if one of the multitable entries
+  % contains an @itemize, we don't choke on the \item (seen as \crcr aka
+  % \endtemplate) expanding \doitemize.
+  \def\item{\crcr}%
+  %
+  \tolerance=9500
+  \hbadness=9500
+  \setmultitablespacing
+  \parskip=\multitableparskip
+  \parindent=\multitableparindent
+  \overfullrule=0pt
+  \global\colcount=0
+  %
+  \everycr = {%
+    \noalign{%
+      \global\everytab={}% Reset from possible headitem.
+      \global\colcount=0 % Reset the column counter.
+      %
+      % Check for saved footnotes, etc.:
+      \checkinserts
+      %
+      % Perhaps a \nobreak, then reset:
+      \headitemcrhook
+      \global\let\headitemcrhook=\relax
+    }%
+  }%
+  %
+  \parsearg\domultitable
+}
+\def\domultitable#1{%
+  % To parse everything between @multitable and @item:
+  \setuptable#1 \endsetuptable
+  %
+  % This preamble sets up a generic column definition, which will
+  % be used as many times as user calls for columns.
+  % \vtop will set a single line and will also let text wrap and
+  % continue for many paragraphs if desired.
+  \halign\bgroup &%
+    \global\advance\colcount by 1
+    \multistrut
+    \vtop{%
+      % Use the current \colcount to find the correct column width:
+      \hsize=\expandafter\csname col\the\colcount\endcsname
+      %
+      % In order to keep entries from bumping into each other
+      % we will add a \leftskip of \multitablecolspace to all columns after
+      % the first one.
+      %
+      % If a template has been used, we will add \multitablecolspace
+      % to the width of each template entry.
+      %
+      % If the user has set preamble in terms of percent of \hsize we will
+      % use that dimension as the width of the column, and the \leftskip
+      % will keep entries from bumping into each other.  Table will start at
+      % left margin and final column will justify at right margin.
+      %
+      % Make sure we don't inherit \rightskip from the outer environment.
+      \rightskip=0pt
+      \ifnum\colcount=1
+	% The first column will be indented with the surrounding text.
+	\advance\hsize by\leftskip
+      \else
+	\ifsetpercent \else
+	  % If user has not set preamble in terms of percent of \hsize
+	  % we will advance \hsize by \multitablecolspace.
+	  \advance\hsize by \multitablecolspace
+	\fi
+       % In either case we will make \leftskip=\multitablecolspace:
+      \leftskip=\multitablecolspace
+      \fi
+      % Ignoring space at the beginning and end avoids an occasional spurious
+      % blank line, when TeX decides to break the line at the space before the
+      % box from the multistrut, so the strut ends up on a line by itself.
+      % For example:
+      % @multitable @columnfractions .11 .89
+      % @item @code{#}
+      % @tab Legal holiday which is valid in major parts of the whole country.
+      % Is automatically provided with highlighting sequences respectively
+      % marking characters.
+      \noindent\ignorespaces##\unskip\multistrut
+    }\cr
+}
+\def\Emultitable{%
+  \crcr
+  \egroup % end the \halign
+  \global\setpercentfalse
+}
+
+\def\setmultitablespacing{%
+  \def\multistrut{\strut}% just use the standard line spacing
+  %
+  % Compute \multitablelinespace (if not defined by user) for use in
+  % \multitableparskip calculation.  We used define \multistrut based on
+  % this, but (ironically) that caused the spacing to be off.
+  % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100.
+\ifdim\multitablelinespace=0pt
+\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
+\global\advance\multitablelinespace by-\ht0
+\fi
+% Test to see if parskip is larger than space between lines of
+% table. If not, do nothing.
+%        If so, set to same dimension as multitablelinespace.
+\ifdim\multitableparskip>\multitablelinespace
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
+                                      % than skip between lines in the table.
+\fi%
+\ifdim\multitableparskip=0pt
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
+                                      % than skip between lines in the table.
+\fi}
+
+
+\message{conditionals,}
+
+% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext,
+% @ifnotxml always succeed.  They currently do nothing; we don't
+% attempt to check whether the conditionals are properly nested.  But we
+% have to remember that they are conditionals, so that @end doesn't
+% attempt to close an environment group.
+%
+\def\makecond#1{%
+  \expandafter\let\csname #1\endcsname = \relax
+  \expandafter\let\csname iscond.#1\endcsname = 1
+}
+\makecond{iftex}
+\makecond{ifnotdocbook}
+\makecond{ifnothtml}
+\makecond{ifnotinfo}
+\makecond{ifnotplaintext}
+\makecond{ifnotxml}
+
+% Ignore @ignore, @ifhtml, @ifinfo, and the like.
+%
+\def\direntry{\doignore{direntry}}
+\def\documentdescription{\doignore{documentdescription}}
+\def\docbook{\doignore{docbook}}
+\def\html{\doignore{html}}
+\def\ifdocbook{\doignore{ifdocbook}}
+\def\ifhtml{\doignore{ifhtml}}
+\def\ifinfo{\doignore{ifinfo}}
+\def\ifnottex{\doignore{ifnottex}}
+\def\ifplaintext{\doignore{ifplaintext}}
+\def\ifxml{\doignore{ifxml}}
+\def\ignore{\doignore{ignore}}
+\def\menu{\doignore{menu}}
+\def\xml{\doignore{xml}}
+
+% Ignore text until a line `@end #1', keeping track of nested conditionals.
+%
+% A count to remember the depth of nesting.
+\newcount\doignorecount
+
+\def\doignore#1{\begingroup
+  % Scan in ``verbatim'' mode:
+  \obeylines
+  \catcode`\@ = \other
+  \catcode`\{ = \other
+  \catcode`\} = \other
+  %
+  % Make sure that spaces turn into tokens that match what \doignoretext wants.
+  \spaceisspace
+  %
+  % Count number of #1's that we've seen.
+  \doignorecount = 0
+  %
+  % Swallow text until we reach the matching `@end #1'.
+  \dodoignore{#1}%
+}
+
+{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source.
+  \obeylines %
+  %
+  \gdef\dodoignore#1{%
+    % #1 contains the command name as a string, e.g., `ifinfo'.
+    %
+    % Define a command to find the next `@end #1'.
+    \long\def\doignoretext##1^^M@end #1{%
+      \doignoretextyyy##1^^M@#1\_STOP_}%
+    %
+    % And this command to find another #1 command, at the beginning of a
+    % line.  (Otherwise, we would consider a line `@c @ifset', for
+    % example, to count as an @ifset for nesting.)
+    \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}%
+    %
+    % And now expand that command.
+    \doignoretext ^^M%
+  }%
+}
+
+\def\doignoreyyy#1{%
+  \def\temp{#1}%
+  \ifx\temp\empty			% Nothing found.
+    \let\next\doignoretextzzz
+  \else					% Found a nested condition, ...
+    \advance\doignorecount by 1
+    \let\next\doignoretextyyy		% ..., look for another.
+    % If we're here, #1 ends with ^^M\ifinfo (for example).
+  \fi
+  \next #1% the token \_STOP_ is present just after this macro.
+}
+
+% We have to swallow the remaining "\_STOP_".
+%
+\def\doignoretextzzz#1{%
+  \ifnum\doignorecount = 0	% We have just found the outermost @end.
+    \let\next\enddoignore
+  \else				% Still inside a nested condition.
+    \advance\doignorecount by -1
+    \let\next\doignoretext      % Look for the next @end.
+  \fi
+  \next
+}
+
+% Finish off ignored text.
+{ \obeylines%
+  % Ignore anything after the last `@end #1'; this matters in verbatim
+  % environments, where otherwise the newline after an ignored conditional
+  % would result in a blank line in the output.
+  \gdef\enddoignore#1^^M{\endgroup\ignorespaces}%
+}
+
+
+% @set VAR sets the variable VAR to an empty value.
+% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
+%
+% Since we want to separate VAR from REST-OF-LINE (which might be
+% empty), we can't just use \parsearg; we have to insert a space of our
+% own to delimit the rest of the line, and then take it out again if we
+% didn't need it.
+% We rely on the fact that \parsearg sets \catcode`\ =10.
+%
+\parseargdef\set{\setyyy#1 \endsetyyy}
+\def\setyyy#1 #2\endsetyyy{%
+  {%
+    \makevalueexpandable
+    \def\temp{#2}%
+    \edef\next{\gdef\makecsname{SET#1}}%
+    \ifx\temp\empty
+      \next{}%
+    \else
+      \setzzz#2\endsetzzz
+    \fi
+  }%
+}
+% Remove the trailing space \setxxx inserted.
+\def\setzzz#1 \endsetzzz{\next{#1}}
+
+% @clear VAR clears (i.e., unsets) the variable VAR.
+%
+\parseargdef\clear{%
+  {%
+    \makevalueexpandable
+    \global\expandafter\let\csname SET#1\endcsname=\relax
+  }%
+}
+
+% @value{foo} gets the text saved in variable foo.
+\def\value{\begingroup\makevalueexpandable\valuexxx}
+\def\valuexxx#1{\expandablevalue{#1}\endgroup}
+{
+  \catcode`\-=\active \catcode`\_=\active
+  %
+  \gdef\makevalueexpandable{%
+    \let\value = \expandablevalue
+    % We don't want these characters active, ...
+    \catcode`\-=\other \catcode`\_=\other
+    % ..., but we might end up with active ones in the argument if
+    % we're called from @code, as @code{@value{foo-bar_}}, though.
+    % So \let them to their normal equivalents.
+    \let-\normaldash \let_\normalunderscore
+  }
+}
+
+% We have this subroutine so that we can handle at least some @value's
+% properly in indexes (we call \makevalueexpandable in \indexdummies).
+% The command has to be fully expandable (if the variable is set), since
+% the result winds up in the index file.  This means that if the
+% variable's value contains other Texinfo commands, it's almost certain
+% it will fail (although perhaps we could fix that with sufficient work
+% to do a one-level expansion on the result, instead of complete).
+%
+% Unfortunately, this has the consequence that when _ is in the *value*
+% of an @set, it does not print properly in the roman fonts (get the cmr
+% dot accent at position 126 instead).  No fix comes to mind, and it's
+% been this way since 2003 or earlier, so just ignore it.
+%
+\def\expandablevalue#1{%
+  \expandafter\ifx\csname SET#1\endcsname\relax
+    {[No value for ``#1'']}%
+    \message{Variable `#1', used in @value, is not set.}%
+  \else
+    \csname SET#1\endcsname
+  \fi
+}
+
+% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
+% with @set.
+%
+% To get the special treatment we need for `@end ifset,' we call
+% \makecond and then redefine.
+%
+\makecond{ifset}
+\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}}
+\def\doifset#1#2{%
+  {%
+    \makevalueexpandable
+    \let\next=\empty
+    \expandafter\ifx\csname SET#2\endcsname\relax
+      #1% If not set, redefine \next.
+    \fi
+    \expandafter
+  }\next
+}
+\def\ifsetfail{\doignore{ifset}}
+
+% @ifclear VAR ... @end executes the `...' iff VAR has never been
+% defined with @set, or has been undefined with @clear.
+%
+% The `\else' inside the `\doifset' parameter is a trick to reuse the
+% above code: if the variable is not set, do nothing, if it is set,
+% then redefine \next to \ifclearfail.
+%
+\makecond{ifclear}
+\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
+\def\ifclearfail{\doignore{ifclear}}
+
+% @ifcommandisdefined CMD ... @end executes the `...' if CMD (written
+% without the @) is in fact defined.  We can only feasibly check at the
+% TeX level, so something like `mathcode' is going to considered
+% defined even though it is not a Texinfo command.
+%
+\makecond{ifcommanddefined}
+\def\ifcommanddefined{\parsearg{\doifcmddefined{\let\next=\ifcmddefinedfail}}}
+%
+\def\doifcmddefined#1#2{{%
+    \makevalueexpandable
+    \let\next=\empty
+    \expandafter\ifx\csname #2\endcsname\relax
+      #1% If not defined, \let\next as above.
+    \fi
+    \expandafter
+  }\next
+}
+\def\ifcmddefinedfail{\doignore{ifcommanddefined}}
+
+% @ifcommandnotdefined CMD ... handled similar to @ifclear above.
+\makecond{ifcommandnotdefined}
+\def\ifcommandnotdefined{%
+  \parsearg{\doifcmddefined{\else \let\next=\ifcmdnotdefinedfail}}}
+\def\ifcmdnotdefinedfail{\doignore{ifcommandnotdefined}}
+
+% Set the `txicommandconditionals' variable, so documents have a way to
+% test if the @ifcommand...defined conditionals are available.
+\set txicommandconditionals
+
+% @dircategory CATEGORY  -- specify a category of the dir file
+% which this file should belong to.  Ignore this in TeX.
+\let\dircategory=\comment
+
+% @defininfoenclose.
+\let\definfoenclose=\comment
+
+
+\message{indexing,}
+% Index generation facilities
+
+% Define \newwrite to be identical to plain tex's \newwrite
+% except not \outer, so it can be used within macros and \if's.
+\edef\newwrite{\makecsname{ptexnewwrite}}
+
+% \newindex {foo} defines an index named IX.
+% It automatically defines \IXindex such that
+% \IXindex ...rest of line... puts an entry in the index IX.
+% It also defines \IXindfile to be the number of the output channel for
+% the file that accumulates this index.  The file's extension is IX.
+% The name of an index should be no more than 2 characters long
+% for the sake of vms.
+%
+\def\newindex#1{%
+  \expandafter\chardef\csname#1indfile\endcsname=0
+  \expandafter\xdef\csname#1index\endcsname{%     % Define @#1index
+    \noexpand\doindex{#1}}
+}
+
+% @defindex foo  ==  \newindex{foo}
+%
+\def\defindex{\parsearg\newindex}
+
+% Define @defcodeindex, like @defindex except put all entries in @code.
+%
+\def\defcodeindex{\parsearg\newcodeindex}
+%
+\def\newcodeindex#1{%
+  \expandafter\chardef\csname#1indfile\endcsname=0
+  \expandafter\xdef\csname#1index\endcsname{%
+    \noexpand\docodeindex{#1}}%
+}
+
+% The default indices:
+\newindex{cp}%      concepts,
+\newcodeindex{fn}%  functions,
+\newcodeindex{vr}%  variables,
+\newcodeindex{tp}%  types,
+\newcodeindex{ky}%  keys
+\newcodeindex{pg}%  and programs.
+
+
+% @synindex foo bar    makes index foo feed into index bar.
+% Do this instead of @defindex foo if you don't want it as a separate index.
+%
+% @syncodeindex foo bar   similar, but put all entries made for index foo
+% inside @code.
+%
+\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
+\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}
+
+% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
+% #3 the target index (bar).
+\def\dosynindex#1#2#3{%
+  % Only do \closeout if we haven't already done it, else we'll end up
+  % closing the target index.
+  \expandafter \ifx\csname donesynindex#2\endcsname \relax
+    % The \closeout helps reduce unnecessary open files; the limit on the
+    % Acorn RISC OS is a mere 16 files.
+    \expandafter\closeout\csname#2indfile\endcsname
+    \expandafter\let\csname donesynindex#2\endcsname = 1
+  \fi
+  % redefine \fooindfile:
+  \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
+  \expandafter\let\csname#2indfile\endcsname=\temp
+  % redefine \fooindex:
+  \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}%
+}
+
+% Define \doindex, the driver for all index macros.
+% Argument #1 is generated by the calling \fooindex macro,
+% and it the two-letter name of the index.
+
+\def\doindex#1{\edef\indexname{#1}\parsearg\doindexxxx}
+\def\doindexxxx #1{\doind{\indexname}{#1}}
+
+% like the previous two, but they put @code around the argument.
+\def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx}
+\def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}}
+
+% Used when writing an index entry out to an index file, to prevent
+% expansion of Texinfo commands that can appear in an index entry.
+%
+\def\indexdummies{%
+  \escapechar = `\\     % use backslash in output files.
+  \def\@{@}% change to @@ when we switch to @ as escape char in index files.
+  \def\ {\realbackslash\space }%
+  %
+  % Need these unexpandable (because we define \tt as a dummy)
+  % definitions when @{ or @} appear in index entry text.  Also, more
+  % complicated, when \tex is in effect and \{ is a \delimiter again.
+  % We can't use \lbracecmd and \rbracecmd because texindex assumes
+  % braces and backslashes are used only as delimiters.  Perhaps we
+  % should use @lbracechar and @rbracechar?
+  \def\{{{\tt\char123}}%
+  \def\}{{\tt\char125}}%
+  %
+  % Do the redefinitions.
+  \commondummies
+}
+
+% For the aux and toc files, @ is the escape character.  So we want to
+% redefine everything using @ as the escape character (instead of
+% \realbackslash, still used for index files).  When everything uses @,
+% this will be simpler.
+%
+\def\atdummies{%
+  \def\@{@@}%
+  \def\ {@ }%
+  \let\{ = \lbraceatcmd
+  \let\} = \rbraceatcmd
+  %
+  % Do the redefinitions.
+  \commondummies
+  \otherbackslash
+}
+
+% Called from \indexdummies and \atdummies.
+%
+\def\commondummies{%
+  % \definedummyword defines \#1 as \string\#1\space, thus effectively
+  % preventing its expansion.  This is used only for control words,
+  % not control letters, because the \space would be incorrect for
+  % control characters, but is needed to separate the control word
+  % from whatever follows.
+  %
+  % For control letters, we have \definedummyletter, which omits the
+  % space.
+  %
+  % These can be used both for control words that take an argument and
+  % those that do not.  If it is followed by {arg} in the input, then
+  % that will dutifully get written to the index (or wherever).
+  %
+  \def\definedummyword  ##1{\def##1{\string##1\space}}%
+  \def\definedummyletter##1{\def##1{\string##1}}%
+  \let\definedummyaccent\definedummyletter
+  %
+  \commondummiesnofonts
+  %
+  \definedummyletter\_%
+  \definedummyletter\-%
+  %
+  % Non-English letters.
+  \definedummyword\AA
+  \definedummyword\AE
+  \definedummyword\DH
+  \definedummyword\L
+  \definedummyword\O
+  \definedummyword\OE
+  \definedummyword\TH
+  \definedummyword\aa
+  \definedummyword\ae
+  \definedummyword\dh
+  \definedummyword\exclamdown
+  \definedummyword\l
+  \definedummyword\o
+  \definedummyword\oe
+  \definedummyword\ordf
+  \definedummyword\ordm
+  \definedummyword\questiondown
+  \definedummyword\ss
+  \definedummyword\th
+  %
+  % Although these internal commands shouldn't show up, sometimes they do.
+  \definedummyword\bf
+  \definedummyword\gtr
+  \definedummyword\hat
+  \definedummyword\less
+  \definedummyword\sf
+  \definedummyword\sl
+  \definedummyword\tclose
+  \definedummyword\tt
+  %
+  \definedummyword\LaTeX
+  \definedummyword\TeX
+  %
+  % Assorted special characters.
+  \definedummyword\arrow
+  \definedummyword\bullet
+  \definedummyword\comma
+  \definedummyword\copyright
+  \definedummyword\registeredsymbol
+  \definedummyword\dots
+  \definedummyword\enddots
+  \definedummyword\entrybreak
+  \definedummyword\equiv
+  \definedummyword\error
+  \definedummyword\euro
+  \definedummyword\expansion
+  \definedummyword\geq
+  \definedummyword\guillemetleft
+  \definedummyword\guillemetright
+  \definedummyword\guilsinglleft
+  \definedummyword\guilsinglright
+  \definedummyword\lbracechar
+  \definedummyword\leq
+  \definedummyword\mathopsup
+  \definedummyword\minus
+  \definedummyword\ogonek
+  \definedummyword\pounds
+  \definedummyword\point
+  \definedummyword\print
+  \definedummyword\quotedblbase
+  \definedummyword\quotedblleft
+  \definedummyword\quotedblright
+  \definedummyword\quoteleft
+  \definedummyword\quoteright
+  \definedummyword\quotesinglbase
+  \definedummyword\rbracechar
+  \definedummyword\result
+  \definedummyword\sub
+  \definedummyword\sup
+  \definedummyword\textdegree
+  %
+  % We want to disable all macros so that they are not expanded by \write.
+  \macrolist
+  %
+  \normalturnoffactive
+  %
+  % Handle some cases of @value -- where it does not contain any
+  % (non-fully-expandable) commands.
+  \makevalueexpandable
+}
+
+% \commondummiesnofonts: common to \commondummies and \indexnofonts.
+% Define \definedumyletter, \definedummyaccent and \definedummyword before
+% using.
+%
+\def\commondummiesnofonts{%
+  % Control letters and accents.
+  \definedummyletter\!%
+  \definedummyaccent\"%
+  \definedummyaccent\'%
+  \definedummyletter\*%
+  \definedummyaccent\,%
+  \definedummyletter\.%
+  \definedummyletter\/%
+  \definedummyletter\:%
+  \definedummyaccent\=%
+  \definedummyletter\?%
+  \definedummyaccent\^%
+  \definedummyaccent\`%
+  \definedummyaccent\~%
+  \definedummyword\u
+  \definedummyword\v
+  \definedummyword\H
+  \definedummyword\dotaccent
+  \definedummyword\ogonek
+  \definedummyword\ringaccent
+  \definedummyword\tieaccent
+  \definedummyword\ubaraccent
+  \definedummyword\udotaccent
+  \definedummyword\dotless
+  %
+  % Texinfo font commands.
+  \definedummyword\b
+  \definedummyword\i
+  \definedummyword\r
+  \definedummyword\sansserif
+  \definedummyword\sc
+  \definedummyword\slanted
+  \definedummyword\t
+  %
+  % Commands that take arguments.
+  \definedummyword\abbr
+  \definedummyword\acronym
+  \definedummyword\anchor
+  \definedummyword\cite
+  \definedummyword\code
+  \definedummyword\command
+  \definedummyword\dfn
+  \definedummyword\dmn
+  \definedummyword\email
+  \definedummyword\emph
+  \definedummyword\env
+  \definedummyword\file
+  \definedummyword\image
+  \definedummyword\indicateurl
+  \definedummyword\inforef
+  \definedummyword\kbd
+  \definedummyword\key
+  \definedummyword\math
+  \definedummyword\option
+  \definedummyword\pxref
+  \definedummyword\ref
+  \definedummyword\samp
+  \definedummyword\strong
+  \definedummyword\tie
+  \definedummyword\U
+  \definedummyword\uref
+  \definedummyword\url
+  \definedummyword\var
+  \definedummyword\verb
+  \definedummyword\w
+  \definedummyword\xref
+}
+
+% For testing: output @{ and @} in index sort strings as \{ and \}.
+\newif\ifusebracesinindexes
+
+\let\indexlbrace\relax
+\let\indexrbrace\relax
+
+{\catcode`\@=0
+\catcode`\\=13
+  @gdef@backslashdisappear{@def\{}}
+}
+
+{
+\catcode`\<=13
+\catcode`\-=13
+\catcode`\`=13
+  \gdef\indexnonalnumdisappear{%
+    \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax\else
+      % @set txiindexlquoteignore makes us ignore left quotes in the sort term.
+      % (Introduced for FSFS 2nd ed.)
+      \let`=\empty
+    \fi
+    %
+    \expandafter\ifx\csname SETtxiindexbackslashignore\endcsname\relax\else
+      \backslashdisappear
+    \fi
+    %
+    \expandafter\ifx\csname SETtxiindexhyphenignore\endcsname\relax\else
+      \def-{}%
+    \fi
+    \expandafter\ifx\csname SETtxiindexlessthanignore\endcsname\relax\else
+      \def<{}%
+    \fi
+    \expandafter\ifx\csname SETtxiindexatsignignore\endcsname\relax\else
+      \def\@{}%
+    \fi
+  }
+
+  \gdef\indexnonalnumreappear{%
+    \useindexbackslash
+    \let-\normaldash
+    \let<\normalless
+    \def\@{@}%
+  }
+}
+
+
+% \indexnofonts is used when outputting the strings to sort the index
+% by, and when constructing control sequence names.  It eliminates all
+% control sequences and just writes whatever the best ASCII sort string
+% would be for a given command (usually its argument).
+%
+\def\indexnofonts{%
+  % Accent commands should become @asis.
+  \def\definedummyaccent##1{\let##1\asis}%
+  % We can just ignore other control letters.
+  \def\definedummyletter##1{\let##1\empty}%
+  % All control words become @asis by default; overrides below.
+  \let\definedummyword\definedummyaccent
+  \commondummiesnofonts
+  %
+  % Don't no-op \tt, since it isn't a user-level command
+  % and is used in the definitions of the active chars like <, >, |, etc.
+  % Likewise with the other plain tex font commands.
+  %\let\tt=\asis
+  %
+  \def\ { }%
+  \def\@{@}%
+  \def\_{\normalunderscore}%
+  \def\-{}% @- shouldn't affect sorting
+  %
+  \def\lbracechar{{\indexlbrace}}%
+  \def\rbracechar{{\indexrbrace}}%
+  \let\{=\lbracechar
+  \let\}=\rbracechar
+  %
+  %
+  % Non-English letters.
+  \def\AA{AA}%
+  \def\AE{AE}%
+  \def\DH{DZZ}%
+  \def\L{L}%
+  \def\OE{OE}%
+  \def\O{O}%
+  \def\TH{TH}%
+  \def\aa{aa}%
+  \def\ae{ae}%
+  \def\dh{dzz}%
+  \def\exclamdown{!}%
+  \def\l{l}%
+  \def\oe{oe}%
+  \def\ordf{a}%
+  \def\ordm{o}%
+  \def\o{o}%
+  \def\questiondown{?}%
+  \def\ss{ss}%
+  \def\th{th}%
+  %
+  \def\LaTeX{LaTeX}%
+  \def\TeX{TeX}%
+  %
+  % Assorted special characters.
+  % (The following {} will end up in the sort string, but that's ok.)
+  \def\arrow{->}%
+  \def\bullet{bullet}%
+  \def\comma{,}%
+  \def\copyright{copyright}%
+  \def\dots{...}%
+  \def\enddots{...}%
+  \def\equiv{==}%
+  \def\error{error}%
+  \def\euro{euro}%
+  \def\expansion{==>}%
+  \def\geq{>=}%
+  \def\guillemetleft{<<}%
+  \def\guillemetright{>>}%
+  \def\guilsinglleft{<}%
+  \def\guilsinglright{>}%
+  \def\leq{<=}%
+  \def\minus{-}%
+  \def\point{.}%
+  \def\pounds{pounds}%
+  \def\print{-|}%
+  \def\quotedblbase{"}%
+  \def\quotedblleft{"}%
+  \def\quotedblright{"}%
+  \def\quoteleft{`}%
+  \def\quoteright{'}%
+  \def\quotesinglbase{,}%
+  \def\registeredsymbol{R}%
+  \def\result{=>}%
+  \def\textdegree{o}%
+  %
+  % We need to get rid of all macros, leaving only the arguments (if present).
+  % Of course this is not nearly correct, but it is the best we can do for now.
+  % makeinfo does not expand macros in the argument to @deffn, which ends up
+  % writing an index entry, and texindex isn't prepared for an index sort entry
+  % that starts with \.
+  %
+  % Since macro invocations are followed by braces, we can just redefine them
+  % to take a single TeX argument.  The case of a macro invocation that
+  % goes to end-of-line is not handled.
+  %
+  \macrolist
+}
+
+
+\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
+
+% Most index entries go through here, but \dosubind is the general case.
+% #1 is the index name, #2 is the entry text.
+\def\doind#1#2{\dosubind{#1}{#2}{}}
+
+% There is also \dosubind {index}{topic}{subtopic}
+% which makes an entry in a two-level index such as the operation index.
+% TODO: Two-level index?  Operation index?
+
+% Workhorse for all indexes.
+% #1 is name of index, #2 is stuff to put there, #3 is subentry --
+% empty if called from \doind, as we usually are (the main exception
+% is with most defuns, which call us directly).
+%
+\def\dosubind#1#2#3{%
+  \iflinks
+  {%
+    \requireopenindexfile{#1}%
+    % Store the main index entry text (including the third arg).
+    \toks0 = {#2}%
+    % If third arg is present, precede it with a space.
+    \def\thirdarg{#3}%
+    \ifx\thirdarg\empty \else
+      \toks0 = \expandafter{\the\toks0 \space #3}%
+    \fi
+    %
+    \edef\writeto{\csname#1indfile\endcsname}%
+    %
+    \safewhatsit\dosubindwrite
+  }%
+  \fi
+}
+
+% Check if an index file has been opened, and if not, open it.
+\def\requireopenindexfile#1{%
+\ifnum\csname #1indfile\endcsname=0
+  \expandafter\newwrite \csname#1indfile\endcsname
+  \edef\suffix{#1}%
+  % A .fls suffix would conflict with the file extension for the output
+  % of -recorder, so use .f1s instead.
+  \ifx\suffix\indexisfl\def\suffix{f1}\fi
+  % Open the file
+  \immediate\openout\csname#1indfile\endcsname \jobname.\suffix
+  % Using \immediate here prevents an object entering into the current box,
+  % which could confound checks such as those in \safewhatsit for preceding
+  % skips.
+\fi}
+\def\indexisfl{fl}
+
+% Output \ as {\indexbackslash}, because \ is an escape character in
+% the index files.
+\let\indexbackslash=\relax
+{\catcode`\@=0 \catcode`\\=\active
+  @gdef@useindexbackslash{@def\{{@indexbackslash}}}
+}
+
+% Definition for writing index entry text.
+\def\sortas#1{\ignorespaces}%
+
+% Definition for writing index entry sort key.  Should occur at the at
+% the beginning of the index entry, like
+%     @cindex @sortas{september} \september
+% The \ignorespaces takes care of following space, but there's no way
+% to remove space before it.
+{
+\catcode`\-=13
+\gdef\indexwritesortas{%
+  \begingroup
+  \indexnonalnumreappear
+  \indexwritesortasxxx}
+\gdef\indexwritesortasxxx#1{%
+  \xdef\indexsortkey{#1}\endgroup}
+}
+
+
+% Write the entry in \toks0 to the index file.
+%
+\def\dosubindwrite{%
+  % Put the index entry in the margin if desired.
+  \ifx\SETmarginindex\relax\else
+    \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}%
+  \fi
+  %
+  % Remember, we are within a group.
+  \indexdummies % Must do this here, since \bf, etc expand at this stage
+  \useindexbackslash % \indexbackslash isn't defined now so it will be output
+                     % as is; and it will print as backslash.
+  % Get the string to sort by, by processing the index entry with all
+  % font commands turned off.
+  {\indexnofonts
+   \indexnonalnumdisappear
+   \xdef\indexsortkey{}%
+   \let\sortas=\indexwritesortas
+   \edef\temp{\the\toks0}%
+   \setbox\dummybox = \hbox{\temp}% Make sure to execute any \sortas
+   \ifx\indexsortkey\empty
+     \xdef\indexsortkey{\temp}%
+     \ifx\indexsortkey\empty\xdef\indexsortkey{ }\fi
+   \fi
+  }%
+  %
+  % Set up the complete index entry, with both the sort key and
+  % the original text, including any font commands.  We write
+  % three arguments to \entry to the .?? file (four in the
+  % subentry case), texindex reduces to two when writing the .??s
+  % sorted result.
+  \edef\temp{%
+    \write\writeto{%
+      \string\entry{\indexsortkey}{\noexpand\folio}{\the\toks0}}%
+  }%
+  \temp
+}
+\newbox\dummybox % used above
+
+% Take care of unwanted page breaks/skips around a whatsit:
+%
+% If a skip is the last thing on the list now, preserve it
+% by backing up by \lastskip, doing the \write, then inserting
+% the skip again.  Otherwise, the whatsit generated by the
+% \write or \pdfdest will make \lastskip zero.  The result is that
+% sequences like this:
+% @end defun
+% @tindex whatever
+% @defun ...
+% will have extra space inserted, because the \medbreak in the
+% start of the @defun won't see the skip inserted by the @end of
+% the previous defun.
+%
+% But don't do any of this if we're not in vertical mode.  We
+% don't want to do a \vskip and prematurely end a paragraph.
+%
+% Avoid page breaks due to these extra skips, too.
+%
+% But wait, there is a catch there:
+% We'll have to check whether \lastskip is zero skip.  \ifdim is not
+% sufficient for this purpose, as it ignores stretch and shrink parts
+% of the skip.  The only way seems to be to check the textual
+% representation of the skip.
+%
+% The following is almost like \def\zeroskipmacro{0.0pt} except that
+% the ``p'' and ``t'' characters have catcode \other, not 11 (letter).
+%
+\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname}
+%
+\newskip\whatsitskip
+\newcount\whatsitpenalty
+%
+% ..., ready, GO:
+%
+\def\safewhatsit#1{\ifhmode
+  #1%
+ \else
+  % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
+  \whatsitskip = \lastskip
+  \edef\lastskipmacro{\the\lastskip}%
+  \whatsitpenalty = \lastpenalty
+  %
+  % If \lastskip is nonzero, that means the last item was a
+  % skip.  And since a skip is discardable, that means this
+  % -\whatsitskip glue we're inserting is preceded by a
+  % non-discardable item, therefore it is not a potential
+  % breakpoint, therefore no \nobreak needed.
+  \ifx\lastskipmacro\zeroskipmacro
+  \else
+    \vskip-\whatsitskip
+  \fi
+  %
+  #1%
+  %
+  \ifx\lastskipmacro\zeroskipmacro
+    % If \lastskip was zero, perhaps the last item was a penalty, and
+    % perhaps it was >=10000, e.g., a \nobreak.  In that case, we want
+    % to re-insert the same penalty (values >10000 are used for various
+    % signals); since we just inserted a non-discardable item, any
+    % following glue (such as a \parskip) would be a breakpoint.  For example:
+    %   @deffn deffn-whatever
+    %   @vindex index-whatever
+    %   Description.
+    % would allow a break between the index-whatever whatsit
+    % and the "Description." paragraph.
+    \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
+  \else
+    % On the other hand, if we had a nonzero \lastskip,
+    % this make-up glue would be preceded by a non-discardable item
+    % (the whatsit from the \write), so we must insert a \nobreak.
+    \nobreak\vskip\whatsitskip
+  \fi
+\fi}
+
+% The index entry written in the file actually looks like
+%  \entry {sortstring}{page}{topic}
+% or
+%  \entry {sortstring}{page}{topic}{subtopic}
+% The texindex program reads in these files and writes files
+% containing these kinds of lines:
+%  \initial {c}
+%     before the first topic whose initial is c
+%  \entry {topic}{pagelist}
+%     for a topic that is used without subtopics
+%  \primary {topic}
+%     for the beginning of a topic that is used with subtopics
+%  \secondary {subtopic}{pagelist}
+%     for each subtopic.
+
+% Define the user-accessible indexing commands
+% @findex, @vindex, @kindex, @cindex.
+
+\def\findex {\fnindex}
+\def\kindex {\kyindex}
+\def\cindex {\cpindex}
+\def\vindex {\vrindex}
+\def\tindex {\tpindex}
+\def\pindex {\pgindex}
+
+\def\cindexsub {\begingroup\obeylines\cindexsub}
+{\obeylines %
+\gdef\cindexsub "#1" #2^^M{\endgroup %
+\dosubind{cp}{#2}{#1}}}
+
+% Define the macros used in formatting output of the sorted index material.
+
+% @printindex causes a particular index (the ??s file) to get printed.
+% It does not print any chapter heading (usually an @unnumbered).
+%
+\parseargdef\printindex{\begingroup
+  \dobreak \chapheadingskip{10000}%
+  %
+  \smallfonts \rm
+  \tolerance = 9500
+  \plainfrenchspacing
+  \everypar = {}% don't want the \kern\-parindent from indentation suppression.
+  %
+  % See if the index file exists and is nonempty.
+  % Change catcode of @ here so that if the index file contains
+  % \initial {@}
+  % as its first line, TeX doesn't complain about mismatched braces
+  % (because it thinks @} is a control sequence).
+  \catcode`\@ = 11
+  % See comment in \requireopenindexfile.
+  \def\indexname{#1}\ifx\indexname\indexisfl\def\indexname{f1}\fi
+  \openin 1 \jobname.\indexname s
+  \ifeof 1
+    % \enddoublecolumns gets confused if there is no text in the index,
+    % and it loses the chapter title and the aux file entries for the
+    % index.  The easiest way to prevent this problem is to make sure
+    % there is some text.
+    \putwordIndexNonexistent
+  \else
+    \catcode`\\ = 0
+    \escapechar = `\\
+    %
+    % If the index file exists but is empty, then \openin leaves \ifeof
+    % false.  We have to make TeX try to read something from the file, so
+    % it can discover if there is anything in it.
+    \read 1 to \thisline
+    \ifeof 1
+      \putwordIndexIsEmpty
+    \else
+      % Index files are almost Texinfo source, but we use \ as the escape
+      % character.  It would be better to use @, but that's too big a change
+      % to make right now.
+      \def\indexbackslash{\ttbackslash}%
+      \let\indexlbrace\{   % Likewise, set these sequences for braces
+      \let\indexrbrace\}   % used in the sort key.
+      \begindoublecolumns
+      \let\entryorphanpenalty=\indexorphanpenalty
+      %
+      % Read input from the index file line by line.
+      \loopdo
+        \ifeof1
+          \let\firsttoken\relax
+        \else
+          \read 1 to \nextline
+          \edef\act{\gdef\noexpand\firsttoken{\getfirsttoken\nextline}}%
+          \act
+        \fi
+        \thisline
+        %
+        \ifeof1\else
+        \let\thisline\nextline
+      \repeat
+      %%
+      \enddoublecolumns
+    \fi
+  \fi
+  \closein 1
+\endgroup}
+
+\def\getfirsttoken#1{\expandafter\getfirsttokenx#1\endfirsttoken}
+\long\def\getfirsttokenx#1#2\endfirsttoken{\noexpand#1}
+
+\def\loopdo#1\repeat{\def\body{#1}\loopdoxxx}
+\def\loopdoxxx{\let\next=\relax\body\let\next=\loopdoxxx\fi\next}
+
+% These macros are used by the sorted index file itself.
+% Change them to control the appearance of the index.
+
+{\catcode`\/=13 \catcode`\-=13 \catcode`\^=13 \catcode`\~=13 \catcode`\_=13
+\catcode`\|=13 \catcode`\<=13 \catcode`\>=13 \catcode`\+=13 \catcode`\"=13
+\catcode`\$=3
+\gdef\initialglyphs{%
+  % Some changes for non-alphabetic characters.  Using the glyphs from the
+  % math fonts looks more consistent than the typewriter font used elsewhere
+  % for these characters.
+  \def\indexbackslash{\math{\backslash}}%
+  \let\\=\indexbackslash
+  %
+  % Can't get bold backslash so don't use bold forward slash
+  \catcode`\/=13
+  \def/{{\secrmnotbold \normalslash}}%
+  \def-{{\normaldash\normaldash}}% en dash `--'
+  \def^{{\chapbf \normalcaret}}%
+  \def~{{\chapbf \normaltilde}}%
+  \def\_{%
+     \leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }%
+  \def|{$\vert$}%
+  \def<{$\less$}%
+  \def>{$\gtr$}%
+  \def+{$\normalplus$}%
+}}
+
+\def\initial{%
+  \bgroup
+  \initialglyphs
+  \initialx
+}
+
+\def\initialx#1{%
+  % Remove any glue we may have, we'll be inserting our own.
+  \removelastskip
+  %
+  % We like breaks before the index initials, so insert a bonus.
+  % The glue before the bonus allows a little bit of space at the
+  % bottom of a column to reduce an increase in inter-line spacing.
+  \nobreak
+  \vskip 0pt plus 5\baselineskip
+  \penalty -300
+  \vskip 0pt plus -5\baselineskip
+  %
+  % Typeset the initial.  Making this add up to a whole number of
+  % baselineskips increases the chance of the dots lining up from column
+  % to column.  It still won't often be perfect, because of the stretch
+  % we need before each entry, but it's better.
+  %
+  % No shrink because it confuses \balancecolumns.
+  \vskip 1.67\baselineskip plus 1\baselineskip
+  \leftline{\secfonts \kern-0.05em \secbf #1}%
+  % \secfonts is inside the argument of \leftline so that the change of
+  % \baselineskip will not affect any glue inserted before the vbox that
+  % \leftline creates.
+  % Do our best not to break after the initial.
+  \nobreak
+  \vskip .33\baselineskip plus .1\baselineskip
+  \egroup % \initialglyphs
+}
+
+\newdimen\entryrightmargin
+\entryrightmargin=0pt
+
+% \entry typesets a paragraph consisting of the text (#1), dot leaders, and
+% then page number (#2) flushed to the right margin.  It is used for index
+% and table of contents entries.  The paragraph is indented by \leftskip.
+%
+\def\entry{%
+  \begingroup
+    %
+    % Start a new paragraph if necessary, so our assignments below can't
+    % affect previous text.
+    \par
+    %
+    % No extra space above this paragraph.
+    \parskip = 0in
+    %
+    % When reading the text of entry, convert explicit line breaks
+    % from @* into spaces.  The user might give these in long section
+    % titles, for instance.
+    \def\*{\unskip\space\ignorespaces}%
+    \def\entrybreak{\hfil\break}% An undocumented command
+    %
+    % A bit of stretch before each entry for the benefit of balancing
+    % columns.
+    \vskip 0pt plus0.5pt
+    %
+    % Swallow the left brace of the text (first parameter):
+    \afterassignment\doentry
+    \let\temp =
+}
+\def\entrybreak{\unskip\space\ignorespaces}%
+\def\doentry{%
+    % Save the text of the entry
+    \global\setbox\boxA=\hbox\bgroup
+    \bgroup % Instead of the swallowed brace.
+      \noindent
+      \aftergroup\finishentry
+      % And now comes the text of the entry.
+      % Not absorbing as a macro argument reduces the chance of problems
+      % with catcodes occurring.
+}
+{\catcode`\@=11
+\gdef\finishentry#1{%
+    \egroup % end box A
+    \dimen@ = \wd\boxA % Length of text of entry
+    \global\setbox\boxA=\hbox\bgroup\unhbox\boxA
+    % #1 is the page number.
+    %
+    % Get the width of the page numbers, and only use
+    % leaders if they are present.
+    \global\setbox\boxB = \hbox{#1}%
+    \ifdim\wd\boxB = 0pt
+      \null\nobreak\hfill\ %
+    \else
+      %
+      \null\nobreak\indexdotfill % Have leaders before the page number.
+      %
+      \ifpdf
+        \pdfgettoks#1.%
+        \bgroup\let\domark\relax
+          \hskip\skip\thinshrinkable\the\toksA
+        \egroup
+        % The redefinion of \domark stops marks being added in \pdflink to
+        % preserve coloured links across page boundaries.  Otherwise the marks
+        % would get in the way of \lastbox in \insertindexentrybox.
+      \else
+        \hskip\skip\thinshrinkable #1%
+      \fi
+    \fi
+    \egroup % end \boxA
+    \ifdim\wd\boxB = 0pt
+      \global\setbox\entryindexbox=\vbox{\unhbox\boxA}%
+    \else
+    \global\setbox\entryindexbox=\vbox\bgroup
+      \prevdepth=\entrylinedepth
+      \noindent
+      % We want the text of the entries to be aligned to the left, and the
+      % page numbers to be aligned to the right.
+      %
+      \advance\leftskip by 0pt plus 1fil
+      \advance\leftskip by 0pt plus -1fill
+      \rightskip = 0pt plus -1fil
+      \advance\rightskip by 0pt plus 1fill
+      % Cause last line, which could consist of page numbers on their own
+      % if the list of page numbers is long, to be aligned to the right.
+      \parfillskip=0pt plus -1fill
+      %
+      \hangindent=1em
+      %
+      \advance\rightskip by \entryrightmargin
+      % Determine how far we can stretch into the margin.
+      % This allows, e.g., "Appendix H  GNU Free Documentation License" to
+      % fit on one line in @letterpaper format.
+      \ifdim\entryrightmargin>2.1em
+        \dimen@i=2.1em
+      \else
+        \dimen@i=0em
+      \fi
+      \advance \parfillskip by 0pt minus 1\dimen@i
+      %
+      \dimen@ii = \hsize
+      \advance\dimen@ii by -1\leftskip
+      \advance\dimen@ii by -1\entryrightmargin
+      \advance\dimen@ii by 1\dimen@i
+      \ifdim\wd\boxA > \dimen@ii % If the entry doesn't fit in one line
+      \ifdim\dimen@ > 0.8\dimen@ii   % due to long index text
+        \dimen@ = 0.7\dimen@ % Try to split the text roughly evenly
+        \dimen@ii = \hsize
+        \advance \dimen@ii by -1em
+        \ifnum\dimen@>\dimen@ii
+          % If the entry is too long, use the whole line
+          \dimen@ = \dimen@ii
+        \fi
+        \advance\leftskip by 0pt plus 1fill % ragged right
+        \advance \dimen@ by 1\rightskip
+        \parshape = 2 0pt \dimen@ 1em \dimen@ii
+        % Ideally we'd add a finite glue at the end of the first line only, but
+        % TeX doesn't seem to provide a way to do such a thing.
+      \fi\fi
+      \unhbox\boxA
+      %
+      % Do not prefer a separate line ending with a hyphen to fewer lines.
+      \finalhyphendemerits = 0
+      %
+      % Word spacing - no stretch
+      \spaceskip=\fontdimen2\font minus \fontdimen4\font
+      %
+      \linepenalty=1000  % Discourage line breaks.
+      \hyphenpenalty=5000  % Discourage hyphenation.
+      %
+      \par % format the paragraph
+    \egroup % The \vbox
+    \fi
+  \endgroup
+  % delay text of entry until after penalty
+  \bgroup\aftergroup\insertindexentrybox
+  \entryorphanpenalty
+}}
+
+\newskip\thinshrinkable
+\skip\thinshrinkable=.15em minus .15em
+
+\newbox\entryindexbox
+\def\insertindexentrybox{%
+  \copy\entryindexbox
+  % The following gets the depth of the last box.  This is for even
+  % line spacing when entries span several lines.
+  \setbox\dummybox\vbox{%
+    \unvbox\entryindexbox
+    \nointerlineskip
+    \lastbox
+    \global\entrylinedepth=\prevdepth
+  }%
+  % Note that we couldn't simply \unvbox\entryindexbox followed by
+  % \nointerlineskip\lastbox to remove the last box and then reinstate it,
+  % because this resets how far the box has been \moveleft'ed to 0.  \unvbox
+  % doesn't affect \prevdepth either.
+}
+\newdimen\entrylinedepth
+
+% Default is no penalty
+\let\entryorphanpenalty\egroup
+
+% Used from \printindex.  \firsttoken should be the first token
+% after the \entry.  If it's not another \entry, we are at the last
+% line of a group of index entries, so insert a penalty to discourage
+% orphaned index entries.
+\long\def\indexorphanpenalty{%
+  \def\isentry{\entry}%
+  \ifx\firsttoken\isentry
+  \else
+    \unskip\penalty 9000
+    % The \unskip here stops breaking before the glue.  It relies on the
+    % \vskip above being there, otherwise there is an error
+    % "You can't use `\unskip' in vertical mode".  There has to be glue
+    % in the current vertical list that hasn't been added to the
+    % "current page".  See Chapter 24 of the TeXbook.  This contradicts
+    % Section 8.3.7 in "TeX by Topic," though.
+  \fi
+  \egroup % now comes the box added with \aftergroup
+}
+
+% Like plain.tex's \dotfill, except uses up at least 1 em.
+% The filll stretch here overpowers both the fil and fill stretch to push
+% the page number to the right.
+\def\indexdotfill{\cleaders
+  \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1filll}
+
+
+\def\primary #1{\line{#1\hfil}}
+
+\newskip\secondaryindent \secondaryindent=0.5cm
+\def\secondary#1#2{{%
+  \parfillskip=0in
+  \parskip=0in
+  \hangindent=1in
+  \hangafter=1
+  \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
+  \ifpdf
+    \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
+  \else
+    #2
+  \fi
+  \par
+}}
+
+% Define two-column mode, which we use to typeset indexes.
+% Adapted from the TeXbook, page 416, which is to say,
+% the manmac.tex format used to print the TeXbook itself.
+\catcode`\@=11  % private names
+
+\newbox\partialpage
+\newdimen\doublecolumnhsize
+\newdimen\doublecolumntopgap
+\doublecolumntopgap = 0pt
+
+% Use inside an output routine to save \topmark and \firstmark
+\def\savemarks{%
+  \global\savedtopmark=\expandafter{\topmark }%
+  \global\savedfirstmark=\expandafter{\firstmark }%
+}
+\newtoks\savedtopmark
+\newtoks\savedfirstmark
+
+% Set \topmark and \firstmark for next time \output runs.
+% Can't be run from withinside \output (because any material
+% added while an output routine is active, including
+% penalties, is saved for after it finishes).  The page so far
+% should be empty, otherwise what's on it will be thrown away.
+\def\restoremarks{%
+  \mark{\the\savedtopmark}%
+  \bgroup\output = {%
+    \setbox\dummybox=\box\PAGE
+  }abc\eject\egroup
+  % "abc" because output routine doesn't fire for a completely empty page.
+  \mark{\the\savedfirstmark}%
+}
+
+\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
+  % If not much space left on page, start a new page.
+  \ifdim\pagetotal>0.8\vsize\vfill\eject\fi
+  %
+  % Grab any single-column material above us.
+  \output = {%
+    %
+    % Here is a possibility not foreseen in manmac: if we accumulate a
+    % whole lot of material, we might end up calling this \output
+    % routine twice in a row (see the doublecol-lose test, which is
+    % essentially a couple of indexes with @setchapternewpage off).  In
+    % that case we just ship out what is in \partialpage with the normal
+    % output routine.  Generally, \partialpage will be empty when this
+    % runs and this will be a no-op.  See the indexspread.tex test case.
+    \ifvoid\partialpage \else
+      \onepageout{\pagecontents\partialpage}%
+    \fi
+    %
+    \global\setbox\partialpage = \vbox{%
+      % Unvbox the main output page.
+      \unvbox\PAGE
+      \kern-\topskip \kern\baselineskip
+    }%
+    \savemarks
+  }%
+  \eject % run that output routine to set \partialpage
+  \restoremarks
+  %
+  % We recover the two marks that the last output routine saved in order
+  % to propagate the information in marks added around a chapter heading,
+  % which could be otherwise be lost by the time the final page is output.
+  %
+  %
+  % Use the double-column output routine for subsequent pages.
+  \output = {\doublecolumnout}%
+  %
+  % Change the page size parameters.  We could do this once outside this
+  % routine, in each of @smallbook, @afourpaper, and the default 8.5x11
+  % format, but then we repeat the same computation.  Repeating a couple
+  % of assignments once per index is clearly meaningless for the
+  % execution time, so we may as well do it in one place.
+  %
+  % First we halve the line length, less a little for the gutter between
+  % the columns.  We compute the gutter based on the line length, so it
+  % changes automatically with the paper format.  The magic constant
+  % below is chosen so that the gutter has the same value (well, +-<1pt)
+  % as it did when we hard-coded it.
+  %
+  % We put the result in a separate register, \doublecolumhsize, so we
+  % can restore it in \pagesofar, after \hsize itself has (potentially)
+  % been clobbered.
+  %
+  \doublecolumnhsize = \hsize
+    \advance\doublecolumnhsize by -.04154\hsize
+    \divide\doublecolumnhsize by 2
+  \hsize = \doublecolumnhsize
+  %
+  % Double the \vsize as well.  (We don't need a separate register here,
+  % since nobody clobbers \vsize.)
+  \global\doublecolumntopgap = \topskip
+  \global\advance\doublecolumntopgap by -1\baselineskip
+  \advance\vsize by -1\doublecolumntopgap
+  \vsize = 2\vsize
+  \topskip=0pt
+  \global\entrylinedepth=0pt\relax
+}
+
+% The double-column output routine for all double-column pages except
+% the last, which is done by \balancecolumns.
+%
+\def\doublecolumnout{%
+  %
+  \splittopskip=\topskip \splitmaxdepth=\maxdepth
+  % Get the available space for the double columns -- the normal
+  % (undoubled) page height minus any material left over from the
+  % previous page.
+  \dimen@ = \vsize
+  \divide\dimen@ by 2
+  \advance\dimen@ by -\ht\partialpage
+  %
+  % box0 will be the left-hand column, box2 the right.
+  \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
+  \onepageout\pagesofar
+  \unvbox255
+  \penalty\outputpenalty
+}
+%
+% Re-output the contents of the output page -- any previous material,
+% followed by the two boxes we just split, in box0 and box2.
+\def\pagesofar{%
+  \unvbox\partialpage
+  %
+  \hsize = \doublecolumnhsize
+  \wd0=\hsize \wd2=\hsize
+  \vbox{%
+    \vskip\doublecolumntopgap
+    \hbox to\pagewidth{\box0\hfil\box2}}%
+}
+
+
+% Finished with with double columns.
+\def\enddoublecolumns{%
+  % The following penalty ensures that the page builder is exercised
+  % _before_ we change the output routine.  This is necessary in the
+  % following situation:
+  %
+  % The last section of the index consists only of a single entry.
+  % Before this section, \pagetotal is less than \pagegoal, so no
+  % break occurs before the last section starts.  However, the last
+  % section, consisting of \initial and the single \entry, does not
+  % fit on the page and has to be broken off.  Without the following
+  % penalty the page builder will not be exercised until \eject
+  % below, and by that time we'll already have changed the output
+  % routine to the \balancecolumns version, so the next-to-last
+  % double-column page will be processed with \balancecolumns, which
+  % is wrong:  The two columns will go to the main vertical list, with
+  % the broken-off section in the recent contributions.  As soon as
+  % the output routine finishes, TeX starts reconsidering the page
+  % break.  The two columns and the broken-off section both fit on the
+  % page, because the two columns now take up only half of the page
+  % goal.  When TeX sees \eject from below which follows the final
+  % section, it invokes the new output routine that we've set after
+  % \balancecolumns below; \onepageout will try to fit the two columns
+  % and the final section into the vbox of \pageheight (see
+  % \pagebody), causing an overfull box.
+  %
+  % Note that glue won't work here, because glue does not exercise the
+  % page builder, unlike penalties (see The TeXbook, pp. 280-281).
+  \penalty0
+  %
+  \output = {%
+    % Split the last of the double-column material.
+    \savemarks
+    \balancecolumns
+    %
+    % Having called \balancecolumns once, we do not
+    % want to call it again.  Therefore, reset \output to its normal
+    % definition right away.
+    \global\output = {\onepageout{\pagecontents\PAGE}}%
+  }%
+  \eject
+  \endgroup % started in \begindoublecolumns
+  \restoremarks
+  % Leave the double-column material on the current page, no automatic
+  % page break.
+  \box\balancedcolumns
+  %
+  % \pagegoal was set to the doubled \vsize above, since we restarted
+  % the current page.  We're now back to normal single-column
+  % typesetting, so reset \pagegoal to the normal \vsize (after the
+  % \endgroup where \vsize got restored).
+  \pagegoal = \vsize
+}
+\newbox\balancedcolumns
+\setbox\balancedcolumns=\vbox{shouldnt see this}%
+%
+% Only called for the last of the double column material.  \doublecolumnout
+% does the others.
+\def\balancecolumns{%
+  \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
+  \dimen@ = \ht0
+  \advance\dimen@ by \topskip
+  \advance\dimen@ by-\baselineskip
+  \ifdim\dimen@<14\baselineskip
+    % Don't split a short final column in two.
+    \setbox2=\vbox{}%
+  \else
+    \divide\dimen@ by 2 % target to split to
+    \dimen@ii = \dimen@
+    \splittopskip = \topskip
+    % Loop until the second column is no higher than the first
+    {%
+      \vbadness = 10000
+      \loop
+        \global\setbox3 = \copy0
+        \global\setbox1 = \vsplit3 to \dimen@
+        % Remove glue from bottom of first column to
+        % make sure it is higher than the second.
+        \global\setbox1 = \vbox{\unvbox1\unpenalty\unskip}%
+      \ifdim\ht3>\ht1
+        \global\advance\dimen@ by 1pt
+      \repeat
+    }%
+    \multiply\dimen@ii by 4
+    \divide\dimen@ii by 5
+    \ifdim\ht3<\dimen@ii
+      % Column heights are too different, so don't make their bottoms
+      % flush with each other.  The glue at the end of the second column
+      % allows a second column to stretch, reducing the difference in
+      % height between the two.
+      \setbox0=\vbox to\dimen@{\unvbox1\vfill}%
+      \setbox2=\vbox to\dimen@{\unvbox3\vskip 0pt plus 0.3\ht0}%
+    \else
+      \setbox0=\vbox to\dimen@{\unvbox1}%
+      \setbox2=\vbox to\dimen@{\unvbox3}%
+    \fi
+  \fi
+  %
+  \global\setbox\balancedcolumns=\vbox{\pagesofar}%
+}
+\catcode`\@ = \other
+
+
+\message{sectioning,}
+% Chapters, sections, etc.
+
+% Let's start with @part.
+\outer\parseargdef\part{\partzzz{#1}}
+\def\partzzz#1{%
+  \chapoddpage
+  \null
+  \vskip.3\vsize  % move it down on the page a bit
+  \begingroup
+    \noindent \titlefonts\rmisbold #1\par % the text
+    \let\lastnode=\empty      % no node to associate with
+    \writetocentry{part}{#1}{}% but put it in the toc
+    \headingsoff              % no headline or footline on the part page
+    % This outputs a mark at the end of the page that clears \thischapter
+    % and \thissection, as is done in \startcontents.
+    \let\pchapsepmacro\relax
+    \chapmacro{}{Yomitfromtoc}{}%
+    \chapoddpage
+  \endgroup
+}
+
+% \unnumberedno is an oxymoron.  But we count the unnumbered
+% sections so that we can refer to them unambiguously in the pdf
+% outlines by their "section number".  We avoid collisions with chapter
+% numbers by starting them at 10000.  (If a document ever has 10000
+% chapters, we're in trouble anyway, I'm sure.)
+\newcount\unnumberedno \unnumberedno = 10000
+\newcount\chapno
+\newcount\secno        \secno=0
+\newcount\subsecno     \subsecno=0
+\newcount\subsubsecno  \subsubsecno=0
+
+% This counter is funny since it counts through charcodes of letters A, B, ...
+\newcount\appendixno  \appendixno = `\@
+%
+% \def\appendixletter{\char\the\appendixno}
+% We do the following ugly conditional instead of the above simple
+% construct for the sake of pdftex, which needs the actual
+% letter in the expansion, not just typeset.
+%
+\def\appendixletter{%
+  \ifnum\appendixno=`A A%
+  \else\ifnum\appendixno=`B B%
+  \else\ifnum\appendixno=`C C%
+  \else\ifnum\appendixno=`D D%
+  \else\ifnum\appendixno=`E E%
+  \else\ifnum\appendixno=`F F%
+  \else\ifnum\appendixno=`G G%
+  \else\ifnum\appendixno=`H H%
+  \else\ifnum\appendixno=`I I%
+  \else\ifnum\appendixno=`J J%
+  \else\ifnum\appendixno=`K K%
+  \else\ifnum\appendixno=`L L%
+  \else\ifnum\appendixno=`M M%
+  \else\ifnum\appendixno=`N N%
+  \else\ifnum\appendixno=`O O%
+  \else\ifnum\appendixno=`P P%
+  \else\ifnum\appendixno=`Q Q%
+  \else\ifnum\appendixno=`R R%
+  \else\ifnum\appendixno=`S S%
+  \else\ifnum\appendixno=`T T%
+  \else\ifnum\appendixno=`U U%
+  \else\ifnum\appendixno=`V V%
+  \else\ifnum\appendixno=`W W%
+  \else\ifnum\appendixno=`X X%
+  \else\ifnum\appendixno=`Y Y%
+  \else\ifnum\appendixno=`Z Z%
+  % The \the is necessary, despite appearances, because \appendixletter is
+  % expanded while writing the .toc file.  \char\appendixno is not
+  % expandable, thus it is written literally, thus all appendixes come out
+  % with the same letter (or @) in the toc without it.
+  \else\char\the\appendixno
+  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
+
+% Each @chapter defines these (using marks) as the number+name, number
+% and name of the chapter.  Page headings and footings can use
+% these.  @section does likewise.
+\def\thischapter{}
+\def\thischapternum{}
+\def\thischaptername{}
+\def\thissection{}
+\def\thissectionnum{}
+\def\thissectionname{}
+
+\newcount\absseclevel % used to calculate proper heading level
+\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count
+
+% @raisesections: treat @section as chapter, @subsection as section, etc.
+\def\raisesections{\global\advance\secbase by -1}
+\let\up=\raisesections % original BFox name
+
+% @lowersections: treat @chapter as section, @section as subsection, etc.
+\def\lowersections{\global\advance\secbase by 1}
+\let\down=\lowersections % original BFox name
+
+% we only have subsub.
+\chardef\maxseclevel = 3
+%
+% A numbered section within an unnumbered changes to unnumbered too.
+% To achieve this, remember the "biggest" unnum. sec. we are currently in:
+\chardef\unnlevel = \maxseclevel
+%
+% Trace whether the current chapter is an appendix or not:
+% \chapheadtype is "N" or "A", unnumbered chapters are ignored.
+\def\chapheadtype{N}
+
+% Choose a heading macro
+% #1 is heading type
+% #2 is heading level
+% #3 is text for heading
+\def\genhead#1#2#3{%
+  % Compute the abs. sec. level:
+  \absseclevel=#2
+  \advance\absseclevel by \secbase
+  % Make sure \absseclevel doesn't fall outside the range:
+  \ifnum \absseclevel < 0
+    \absseclevel = 0
+  \else
+    \ifnum \absseclevel > 3
+      \absseclevel = 3
+    \fi
+  \fi
+  % The heading type:
+  \def\headtype{#1}%
+  \if \headtype U%
+    \ifnum \absseclevel < \unnlevel
+      \chardef\unnlevel = \absseclevel
+    \fi
+  \else
+    % Check for appendix sections:
+    \ifnum \absseclevel = 0
+      \edef\chapheadtype{\headtype}%
+    \else
+      \if \headtype A\if \chapheadtype N%
+	\errmessage{@appendix... within a non-appendix chapter}%
+      \fi\fi
+    \fi
+    % Check for numbered within unnumbered:
+    \ifnum \absseclevel > \unnlevel
+      \def\headtype{U}%
+    \else
+      \chardef\unnlevel = 3
+    \fi
+  \fi
+  % Now print the heading:
+  \if \headtype U%
+    \ifcase\absseclevel
+	\unnumberedzzz{#3}%
+    \or \unnumberedseczzz{#3}%
+    \or \unnumberedsubseczzz{#3}%
+    \or \unnumberedsubsubseczzz{#3}%
+    \fi
+  \else
+    \if \headtype A%
+      \ifcase\absseclevel
+	  \appendixzzz{#3}%
+      \or \appendixsectionzzz{#3}%
+      \or \appendixsubseczzz{#3}%
+      \or \appendixsubsubseczzz{#3}%
+      \fi
+    \else
+      \ifcase\absseclevel
+	  \chapterzzz{#3}%
+      \or \seczzz{#3}%
+      \or \numberedsubseczzz{#3}%
+      \or \numberedsubsubseczzz{#3}%
+      \fi
+    \fi
+  \fi
+  \suppressfirstparagraphindent
+}
+
+% an interface:
+\def\numhead{\genhead N}
+\def\apphead{\genhead A}
+\def\unnmhead{\genhead U}
+
+% @chapter, @appendix, @unnumbered.  Increment top-level counter, reset
+% all lower-level sectioning counters to zero.
+%
+% Also set \chaplevelprefix, which we prepend to @float sequence numbers
+% (e.g., figures), q.v.  By default (before any chapter), that is empty.
+\let\chaplevelprefix = \empty
+%
+\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz
+\def\chapterzzz#1{%
+  % section resetting is \global in case the chapter is in a group, such
+  % as an @include file.
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\chapno by 1
+  %
+  % Used for \float.
+  \gdef\chaplevelprefix{\the\chapno.}%
+  \resetallfloatnos
+  %
+  % \putwordChapter can contain complex things in translations.
+  \toks0=\expandafter{\putwordChapter}%
+  \message{\the\toks0 \space \the\chapno}%
+  %
+  % Write the actual heading.
+  \chapmacro{#1}{Ynumbered}{\the\chapno}%
+  %
+  % So @section and the like are numbered underneath this chapter.
+  \global\let\section = \numberedsec
+  \global\let\subsection = \numberedsubsec
+  \global\let\subsubsection = \numberedsubsubsec
+}
+
+\outer\parseargdef\appendix{\apphead0{#1}} % normally calls appendixzzz
+%
+\def\appendixzzz#1{%
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\appendixno by 1
+  \gdef\chaplevelprefix{\appendixletter.}%
+  \resetallfloatnos
+  %
+  % \putwordAppendix can contain complex things in translations.
+  \toks0=\expandafter{\putwordAppendix}%
+  \message{\the\toks0 \space \appendixletter}%
+  %
+  \chapmacro{#1}{Yappendix}{\appendixletter}%
+  %
+  \global\let\section = \appendixsec
+  \global\let\subsection = \appendixsubsec
+  \global\let\subsubsection = \appendixsubsubsec
+}
+
+% normally unnmhead0 calls unnumberedzzz:
+\outer\parseargdef\unnumbered{\unnmhead0{#1}}
+\def\unnumberedzzz#1{%
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\unnumberedno by 1
+  %
+  % Since an unnumbered has no number, no prefix for figures.
+  \global\let\chaplevelprefix = \empty
+  \resetallfloatnos
+  %
+  % This used to be simply \message{#1}, but TeX fully expands the
+  % argument to \message.  Therefore, if #1 contained @-commands, TeX
+  % expanded them.  For example, in `@unnumbered The @cite{Book}', TeX
+  % expanded @cite (which turns out to cause errors because \cite is meant
+  % to be executed, not expanded).
+  %
+  % Anyway, we don't want the fully-expanded definition of @cite to appear
+  % as a result of the \message, we just want `@cite' itself.  We use
+  % \the<toks register> to achieve this: TeX expands \the<toks> only once,
+  % simply yielding the contents of <toks register>.  (We also do this for
+  % the toc entries.)
+  \toks0 = {#1}%
+  \message{(\the\toks0)}%
+  %
+  \chapmacro{#1}{Ynothing}{\the\unnumberedno}%
+  %
+  \global\let\section = \unnumberedsec
+  \global\let\subsection = \unnumberedsubsec
+  \global\let\subsubsection = \unnumberedsubsubsec
+}
+
+% @centerchap is like @unnumbered, but the heading is centered.
+\outer\parseargdef\centerchap{%
+  \let\centerparametersmaybe = \centerparameters
+  \unnmhead0{#1}%
+  \let\centerparametersmaybe = \relax
+}
+
+% @top is like @unnumbered.
+\let\top\unnumbered
+
+% Sections.
+%
+\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz
+\def\seczzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%
+}
+
+% normally calls appendixsectionzzz:
+\outer\parseargdef\appendixsection{\apphead1{#1}}
+\def\appendixsectionzzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%
+}
+\let\appendixsec\appendixsection
+
+% normally calls unnumberedseczzz:
+\outer\parseargdef\unnumberedsec{\unnmhead1{#1}}
+\def\unnumberedseczzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%
+}
+
+% Subsections.
+%
+% normally calls numberedsubseczzz:
+\outer\parseargdef\numberedsubsec{\numhead2{#1}}
+\def\numberedsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%
+}
+
+% normally calls appendixsubseczzz:
+\outer\parseargdef\appendixsubsec{\apphead2{#1}}
+\def\appendixsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Yappendix}%
+                 {\appendixletter.\the\secno.\the\subsecno}%
+}
+
+% normally calls unnumberedsubseczzz:
+\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}}
+\def\unnumberedsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Ynothing}%
+                 {\the\unnumberedno.\the\secno.\the\subsecno}%
+}
+
+% Subsubsections.
+%
+% normally numberedsubsubseczzz:
+\outer\parseargdef\numberedsubsubsec{\numhead3{#1}}
+\def\numberedsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Ynumbered}%
+                 {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+% normally appendixsubsubseczzz:
+\outer\parseargdef\appendixsubsubsec{\apphead3{#1}}
+\def\appendixsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Yappendix}%
+                 {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+% normally unnumberedsubsubseczzz:
+\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}}
+\def\unnumberedsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Ynothing}%
+                 {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+% These macros control what the section commands do, according
+% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
+% Define them by default for a numbered chapter.
+\let\section = \numberedsec
+\let\subsection = \numberedsubsec
+\let\subsubsection = \numberedsubsubsec
+
+% Define @majorheading, @heading and @subheading
+
+\def\majorheading{%
+  {\advance\chapheadingskip by 10pt \chapbreak }%
+  \parsearg\chapheadingzzz
+}
+
+\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
+\def\chapheadingzzz#1{%
+  \vbox{\chapfonts \raggedtitlesettings #1\par}%
+  \nobreak\bigskip \nobreak
+  \suppressfirstparagraphindent
+}
+
+% @heading, @subheading, @subsubheading.
+\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+
+% These macros generate a chapter, section, etc. heading only
+% (including whitespace, linebreaking, etc. around it),
+% given all the information in convenient, parsed form.
+
+% Args are the skip and penalty (usually negative)
+\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
+
+% Parameter controlling skip before chapter headings (if needed)
+\newskip\chapheadingskip
+
+% Define plain chapter starts, and page on/off switching for it.
+\def\chapbreak{\dobreak \chapheadingskip {-4000}}
+
+% Start a new page
+\def\chappager{\par\vfill\supereject}
+
+% \chapoddpage - start on an odd page for a new chapter
+% Because \domark is called before \chapoddpage, the filler page will
+% get the headings for the next chapter, which is wrong.  But we don't
+% care -- we just disable all headings on the filler page.
+\def\chapoddpage{%
+  \chappager
+  \ifodd\pageno \else
+    \begingroup
+      \headingsoff
+      \null
+      \chappager
+    \endgroup
+  \fi
+}
+
+\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
+
+\def\CHAPPAGoff{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chapbreak
+\global\let\pagealignmacro=\chappager}
+
+\def\CHAPPAGon{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chappager
+\global\let\pagealignmacro=\chappager
+\global\def\HEADINGSon{\HEADINGSsingle}}
+
+\def\CHAPPAGodd{%
+\global\let\contentsalignmacro = \chapoddpage
+\global\let\pchapsepmacro=\chapoddpage
+\global\let\pagealignmacro=\chapoddpage
+\global\def\HEADINGSon{\HEADINGSdouble}}
+
+\CHAPPAGon
+
+% \chapmacro - Chapter opening.
+%
+% #1 is the text, #2 is the section type (Ynumbered, Ynothing,
+% Yappendix, Yomitfromtoc), #3 the chapter number.
+% Not used for @heading series.
+%
+% To test against our argument.
+\def\Ynothingkeyword{Ynothing}
+\def\Yappendixkeyword{Yappendix}
+\def\Yomitfromtockeyword{Yomitfromtoc}
+%
+\def\chapmacro#1#2#3{%
+  \checkenv{}% chapters, etc., should not start inside an environment.
+  %
+  % Insert the first mark before the heading break (see notes for \domark).
+  \let\prevchapterdefs=\lastchapterdefs
+  \let\prevsectiondefs=\lastsectiondefs
+  \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}%
+                        \gdef\thissection{}}%
+  %
+  \def\temptype{#2}%
+  \ifx\temptype\Ynothingkeyword
+    \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
+                          \gdef\thischapter{\thischaptername}}%
+  \else\ifx\temptype\Yomitfromtockeyword
+    \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
+                          \gdef\thischapter{}}%
+  \else\ifx\temptype\Yappendixkeyword
+    \toks0={#1}%
+    \xdef\lastchapterdefs{%
+      \gdef\noexpand\thischaptername{\the\toks0}%
+      \gdef\noexpand\thischapternum{\appendixletter}%
+      % \noexpand\putwordAppendix avoids expanding indigestible
+      % commands in some of the translations.
+      \gdef\noexpand\thischapter{\noexpand\putwordAppendix{}
+                                 \noexpand\thischapternum:
+                                 \noexpand\thischaptername}%
+    }%
+  \else
+    \toks0={#1}%
+    \xdef\lastchapterdefs{%
+      \gdef\noexpand\thischaptername{\the\toks0}%
+      \gdef\noexpand\thischapternum{\the\chapno}%
+      % \noexpand\putwordChapter avoids expanding indigestible
+      % commands in some of the translations.
+      \gdef\noexpand\thischapter{\noexpand\putwordChapter{}
+                                 \noexpand\thischapternum:
+                                 \noexpand\thischaptername}%
+    }%
+  \fi\fi\fi
+  %
+  % Output the mark.  Pass it through \safewhatsit, to take care of
+  % the preceding space.
+  \safewhatsit\domark
+  %
+  % Insert the chapter heading break.
+  \pchapsepmacro
+  %
+  % Now the second mark, after the heading break.  No break points
+  % between here and the heading.
+  \let\prevchapterdefs=\lastchapterdefs
+  \let\prevsectiondefs=\lastsectiondefs
+  \domark
+  %
+  {%
+    \chapfonts \rmisbold
+    \let\footnote=\errfootnoteheading % give better error message
+    %
+    % Have to define \lastsection before calling \donoderef, because the
+    % xref code eventually uses it.  On the other hand, it has to be called
+    % after \pchapsepmacro, or the headline will change too soon.
+    \gdef\lastsection{#1}%
+    %
+    % Only insert the separating space if we have a chapter/appendix
+    % number, and don't print the unnumbered ``number''.
+    \ifx\temptype\Ynothingkeyword
+      \setbox0 = \hbox{}%
+      \def\toctype{unnchap}%
+    \else\ifx\temptype\Yomitfromtockeyword
+      \setbox0 = \hbox{}% contents like unnumbered, but no toc entry
+      \def\toctype{omit}%
+    \else\ifx\temptype\Yappendixkeyword
+      \setbox0 = \hbox{\putwordAppendix{} #3\enspace}%
+      \def\toctype{app}%
+    \else
+      \setbox0 = \hbox{#3\enspace}%
+      \def\toctype{numchap}%
+    \fi\fi\fi
+    %
+    % Write the toc entry for this chapter.  Must come before the
+    % \donoderef, because we include the current node name in the toc
+    % entry, and \donoderef resets it to empty.
+    \writetocentry{\toctype}{#1}{#3}%
+    %
+    % For pdftex, we have to write out the node definition (aka, make
+    % the pdfdest) after any page break, but before the actual text has
+    % been typeset.  If the destination for the pdf outline is after the
+    % text, then jumping from the outline may wind up with the text not
+    % being visible, for instance under high magnification.
+    \donoderef{#2}%
+    %
+    % Typeset the actual heading.
+    \nobreak % Avoid page breaks at the interline glue.
+    \vbox{\raggedtitlesettings \hangindent=\wd0 \centerparametersmaybe
+          \unhbox0 #1\par}%
+  }%
+  \nobreak\bigskip % no page break after a chapter title
+  \nobreak
+}
+
+% @centerchap -- centered and unnumbered.
+\let\centerparametersmaybe = \relax
+\def\centerparameters{%
+  \advance\rightskip by 3\rightskip
+  \leftskip = \rightskip
+  \parfillskip = 0pt
+}
+
+
+% I don't think this chapter style is supported any more, so I'm not
+% updating it with the new noderef stuff.  We'll see.  --karl, 11aug03.
+%
+\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
+%
+\def\unnchfopen #1{%
+  \chapoddpage
+  \vbox{\chapfonts \raggedtitlesettings #1\par}%
+  \nobreak\bigskip\nobreak
+}
+\def\chfopen #1#2{\chapoddpage {\chapfonts
+\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
+\par\penalty 5000 %
+}
+\def\centerchfopen #1{%
+  \chapoddpage
+  \vbox{\chapfonts \raggedtitlesettings \hfill #1\hfill}%
+  \nobreak\bigskip \nobreak
+}
+\def\CHAPFopen{%
+  \global\let\chapmacro=\chfopen
+  \global\let\centerchapmacro=\centerchfopen}
+
+
+% Section titles.  These macros combine the section number parts and
+% call the generic \sectionheading to do the printing.
+%
+\newskip\secheadingskip
+\def\secheadingbreak{\dobreak \secheadingskip{-1000}}
+
+% Subsection titles.
+\newskip\subsecheadingskip
+\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}}
+
+% Subsubsection titles.
+\def\subsubsecheadingskip{\subsecheadingskip}
+\def\subsubsecheadingbreak{\subsecheadingbreak}
+
+
+% Print any size, any type, section title.
+%
+% #1 is the text of the title,
+% #2 is the section level (sec/subsec/subsubsec),
+% #3 is the section type (Ynumbered, Ynothing, Yappendix, Yomitfromtoc),
+% #4 is the section number.
+%
+\def\seckeyword{sec}
+%
+\def\sectionheading#1#2#3#4{%
+  {%
+    \def\sectionlevel{#2}%
+    \def\temptype{#3}%
+    %
+    % It is ok for the @heading series commands to appear inside an
+    % environment (it's been historically allowed, though the logic is
+    % dubious), but not the others.
+    \ifx\temptype\Yomitfromtockeyword\else
+      \checkenv{}% non-@*heading should not be in an environment.
+    \fi
+    \let\footnote=\errfootnoteheading
+    %
+    % Switch to the right set of fonts.
+    \csname #2fonts\endcsname \rmisbold
+    %
+    % Insert first mark before the heading break (see notes for \domark).
+    \let\prevsectiondefs=\lastsectiondefs
+    \ifx\temptype\Ynothingkeyword
+      \ifx\sectionlevel\seckeyword
+        \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}%
+                              \gdef\thissection{\thissectionname}}%
+      \fi
+    \else\ifx\temptype\Yomitfromtockeyword
+      % Don't redefine \thissection.
+    \else\ifx\temptype\Yappendixkeyword
+      \ifx\sectionlevel\seckeyword
+        \toks0={#1}%
+        \xdef\lastsectiondefs{%
+          \gdef\noexpand\thissectionname{\the\toks0}%
+          \gdef\noexpand\thissectionnum{#4}%
+          % \noexpand\putwordSection avoids expanding indigestible
+          % commands in some of the translations.
+          \gdef\noexpand\thissection{\noexpand\putwordSection{}
+                                     \noexpand\thissectionnum:
+                                     \noexpand\thissectionname}%
+        }%
+      \fi
+    \else
+      \ifx\sectionlevel\seckeyword
+        \toks0={#1}%
+        \xdef\lastsectiondefs{%
+          \gdef\noexpand\thissectionname{\the\toks0}%
+          \gdef\noexpand\thissectionnum{#4}%
+          % \noexpand\putwordSection avoids expanding indigestible
+          % commands in some of the translations.
+          \gdef\noexpand\thissection{\noexpand\putwordSection{}
+                                     \noexpand\thissectionnum:
+                                     \noexpand\thissectionname}%
+        }%
+      \fi
+    \fi\fi\fi
+    %
+    % Go into vertical mode.  Usually we'll already be there, but we
+    % don't want the following whatsit to end up in a preceding paragraph
+    % if the document didn't happen to have a blank line.
+    \par
+    %
+    % Output the mark.  Pass it through \safewhatsit, to take care of
+    % the preceding space.
+    \safewhatsit\domark
+    %
+    % Insert space above the heading.
+    \csname #2headingbreak\endcsname
+    %
+    % Now the second mark, after the heading break.  No break points
+    % between here and the heading.
+    \global\let\prevsectiondefs=\lastsectiondefs
+    \domark
+    %
+    % Only insert the space after the number if we have a section number.
+    \ifx\temptype\Ynothingkeyword
+      \setbox0 = \hbox{}%
+      \def\toctype{unn}%
+      \gdef\lastsection{#1}%
+    \else\ifx\temptype\Yomitfromtockeyword
+      % for @headings -- no section number, don't include in toc,
+      % and don't redefine \lastsection.
+      \setbox0 = \hbox{}%
+      \def\toctype{omit}%
+      \let\sectionlevel=\empty
+    \else\ifx\temptype\Yappendixkeyword
+      \setbox0 = \hbox{#4\enspace}%
+      \def\toctype{app}%
+      \gdef\lastsection{#1}%
+    \else
+      \setbox0 = \hbox{#4\enspace}%
+      \def\toctype{num}%
+      \gdef\lastsection{#1}%
+    \fi\fi\fi
+    %
+    % Write the toc entry (before \donoderef).  See comments in \chapmacro.
+    \writetocentry{\toctype\sectionlevel}{#1}{#4}%
+    %
+    % Write the node reference (= pdf destination for pdftex).
+    % Again, see comments in \chapmacro.
+    \donoderef{#3}%
+    %
+    % Interline glue will be inserted when the vbox is completed.
+    % That glue will be a valid breakpoint for the page, since it'll be
+    % preceded by a whatsit (usually from the \donoderef, or from the
+    % \writetocentry if there was no node).  We don't want to allow that
+    % break, since then the whatsits could end up on page n while the
+    % section is on page n+1, thus toc/etc. are wrong.  Debian bug 276000.
+    \nobreak
+    %
+    % Output the actual section heading.
+    \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
+          \hangindent=\wd0  % zero if no section number
+          \unhbox0 #1}%
+  }%
+  % Add extra space after the heading -- half of whatever came above it.
+  % Don't allow stretch, though.
+  \kern .5 \csname #2headingskip\endcsname
+  %
+  % Do not let the kern be a potential breakpoint, as it would be if it
+  % was followed by glue.
+  \nobreak
+  %
+  % We'll almost certainly start a paragraph next, so don't let that
+  % glue accumulate.  (Not a breakpoint because it's preceded by a
+  % discardable item.)  However, when a paragraph is not started next
+  % (\startdefun, \cartouche, \center, etc.), this needs to be wiped out
+  % or the negative glue will cause weirdly wrong output, typically
+  % obscuring the section heading with something else.
+  \vskip-\parskip
+  %
+  % This is so the last item on the main vertical list is a known
+  % \penalty > 10000, so \startdefun, etc., can recognize the situation
+  % and do the needful.
+  \penalty 10001
+}
+
+
+\message{toc,}
+% Table of contents.
+\newwrite\tocfile
+
+% Write an entry to the toc file, opening it if necessary.
+% Called from @chapter, etc.
+%
+% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno}
+% We append the current node name (if any) and page number as additional
+% arguments for the \{chap,sec,...}entry macros which will eventually
+% read this.  The node name is used in the pdf outlines as the
+% destination to jump to.
+%
+% We open the .toc file for writing here instead of at @setfilename (or
+% any other fixed time) so that @contents can be anywhere in the document.
+% But if #1 is `omit', then we don't do anything.  This is used for the
+% table of contents chapter openings themselves.
+%
+\newif\iftocfileopened
+\def\omitkeyword{omit}%
+%
+\def\writetocentry#1#2#3{%
+  \edef\writetoctype{#1}%
+  \ifx\writetoctype\omitkeyword \else
+    \iftocfileopened\else
+      \immediate\openout\tocfile = \jobname.toc
+      \global\tocfileopenedtrue
+    \fi
+    %
+    \iflinks
+      {\atdummies
+       \edef\temp{%
+         \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}%
+       \temp
+      }%
+    \fi
+  \fi
+  %
+  % Tell \shipout to create a pdf destination on each page, if we're
+  % writing pdf.  These are used in the table of contents.  We can't
+  % just write one on every page because the title pages are numbered
+  % 1 and 2 (the page numbers aren't printed), and so are the first
+  % two pages of the document.  Thus, we'd have two destinations named
+  % `1', and two named `2'.
+  \ifpdf \global\pdfmakepagedesttrue \fi
+}
+
+
+% These characters do not print properly in the Computer Modern roman
+% fonts, so we must take special care.  This is more or less redundant
+% with the Texinfo input format setup at the end of this file.
+%
+\def\activecatcodes{%
+  \catcode`\"=\active
+  \catcode`\$=\active
+  \catcode`\<=\active
+  \catcode`\>=\active
+  \catcode`\\=\active
+  \catcode`\^=\active
+  \catcode`\_=\active
+  \catcode`\|=\active
+  \catcode`\~=\active
+}
+
+
+% Read the toc file, which is essentially Texinfo input.
+\def\readtocfile{%
+  \setupdatafile
+  \activecatcodes
+  \input \tocreadfilename
+}
+
+\newskip\contentsrightmargin \contentsrightmargin=1in
+\newcount\savepageno
+\newcount\lastnegativepageno \lastnegativepageno = -1
+
+% Prepare to read what we've written to \tocfile.
+%
+\def\startcontents#1{%
+  % If @setchapternewpage on, and @headings double, the contents should
+  % start on an odd page, unlike chapters.  Thus, we maintain
+  % \contentsalignmacro in parallel with \pagealignmacro.
+  % From: Torbjorn Granlund <tege@matematik.su.se>
+  \contentsalignmacro
+  \immediate\closeout\tocfile
+  %
+  % Don't need to put `Contents' or `Short Contents' in the headline.
+  % It is abundantly clear what they are.
+  \chapmacro{#1}{Yomitfromtoc}{}%
+  %
+  \savepageno = \pageno
+  \begingroup                  % Set up to handle contents files properly.
+    \raggedbottom              % Worry more about breakpoints than the bottom.
+    \entryrightmargin=\contentsrightmargin % Don't use the full line length.
+    %
+    % Roman numerals for page numbers.
+    \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
+}
+
+% redefined for the two-volume lispref.  We always output on
+% \jobname.toc even if this is redefined.
+%
+\def\tocreadfilename{\jobname.toc}
+
+% Normal (long) toc.
+%
+\def\contents{%
+  \startcontents{\putwordTOC}%
+    \openin 1 \tocreadfilename\space
+    \ifeof 1 \else
+      \readtocfile
+    \fi
+    \vfill \eject
+    \contentsalignmacro % in case @setchapternewpage odd is in effect
+    \ifeof 1 \else
+      \pdfmakeoutlines
+    \fi
+    \closein 1
+  \endgroup
+  \lastnegativepageno = \pageno
+  \global\pageno = \savepageno
+}
+
+% And just the chapters.
+\def\summarycontents{%
+  \startcontents{\putwordShortTOC}%
+    %
+    \let\partentry = \shortpartentry
+    \let\numchapentry = \shortchapentry
+    \let\appentry = \shortchapentry
+    \let\unnchapentry = \shortunnchapentry
+    % We want a true roman here for the page numbers.
+    \secfonts
+    \let\rm=\shortcontrm \let\bf=\shortcontbf
+    \let\sl=\shortcontsl \let\tt=\shortconttt
+    \rm
+    \hyphenpenalty = 10000
+    \advance\baselineskip by 1pt % Open it up a little.
+    \def\numsecentry##1##2##3##4{}
+    \let\appsecentry = \numsecentry
+    \let\unnsecentry = \numsecentry
+    \let\numsubsecentry = \numsecentry
+    \let\appsubsecentry = \numsecentry
+    \let\unnsubsecentry = \numsecentry
+    \let\numsubsubsecentry = \numsecentry
+    \let\appsubsubsecentry = \numsecentry
+    \let\unnsubsubsecentry = \numsecentry
+    \openin 1 \tocreadfilename\space
+    \ifeof 1 \else
+      \readtocfile
+    \fi
+    \closein 1
+    \vfill \eject
+    \contentsalignmacro % in case @setchapternewpage odd is in effect
+  \endgroup
+  \lastnegativepageno = \pageno
+  \global\pageno = \savepageno
+}
+\let\shortcontents = \summarycontents
+
+% Typeset the label for a chapter or appendix for the short contents.
+% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
+%
+\def\shortchaplabel#1{%
+  % This space should be enough, since a single number is .5em, and the
+  % widest letter (M) is 1em, at least in the Computer Modern fonts.
+  % But use \hss just in case.
+  % (This space doesn't include the extra space that gets added after
+  % the label; that gets put in by \shortchapentry above.)
+  %
+  % We'd like to right-justify chapter numbers, but that looks strange
+  % with appendix letters.  And right-justifying numbers and
+  % left-justifying letters looks strange when there is less than 10
+  % chapters.  Have to read the whole toc once to know how many chapters
+  % there are before deciding ...
+  \hbox to 1em{#1\hss}%
+}
+
+% These macros generate individual entries in the table of contents.
+% The first argument is the chapter or section name.
+% The last argument is the page number.
+% The arguments in between are the chapter number, section number, ...
+
+% Parts, in the main contents.  Replace the part number, which doesn't
+% exist, with an empty box.  Let's hope all the numbers have the same width.
+% Also ignore the page number, which is conventionally not printed.
+\def\numeralbox{\setbox0=\hbox{8}\hbox to \wd0{\hfil}}
+\def\partentry#1#2#3#4{\dochapentry{\numeralbox\labelspace#1}{}}
+%
+% Parts, in the short toc.
+\def\shortpartentry#1#2#3#4{%
+  \penalty-300
+  \vskip.5\baselineskip plus.15\baselineskip minus.1\baselineskip
+  \shortchapentry{{\bf #1}}{\numeralbox}{}{}%
+}
+
+% Chapters, in the main contents.
+\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}}
+
+% Chapters, in the short toc.
+% See comments in \dochapentry re vbox and related settings.
+\def\shortchapentry#1#2#3#4{%
+  \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}%
+}
+
+% Appendices, in the main contents.
+% Need the word Appendix, and a fixed-size box.
+%
+\def\appendixbox#1{%
+  % We use M since it's probably the widest letter.
+  \setbox0 = \hbox{\putwordAppendix{} M}%
+  \hbox to \wd0{\putwordAppendix{} #1\hss}}
+%
+\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\hskip.7em#1}{#4}}
+
+% Unnumbered chapters.
+\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}}
+\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}}
+
+% Sections.
+\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}}
+\let\appsecentry=\numsecentry
+\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}}
+
+% Subsections.
+\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsecentry=\numsubsecentry
+\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
+
+% And subsubsections.
+\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsubsecentry=\numsubsubsecentry
+\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}}
+
+% This parameter controls the indentation of the various levels.
+% Same as \defaultparindent.
+\newdimen\tocindent \tocindent = 15pt
+
+% Now for the actual typesetting. In all these, #1 is the text and #2 is the
+% page number.
+%
+% If the toc has to be broken over pages, we want it to be at chapters
+% if at all possible; hence the \penalty.
+\def\dochapentry#1#2{%
+   \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
+   \begingroup
+     % Move the page numbers slightly to the right
+     \advance\entryrightmargin by -0.05em
+     \chapentryfonts
+     \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+   \endgroup
+   \nobreak\vskip .25\baselineskip plus.1\baselineskip
+}
+
+\def\dosecentry#1#2{\begingroup
+  \secentryfonts \leftskip=\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsecentry#1#2{\begingroup
+  \subsecentryfonts \leftskip=2\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsubsecentry#1#2{\begingroup
+  \subsubsecentryfonts \leftskip=3\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+% We use the same \entry macro as for the index entries.
+\let\tocentry = \entry
+
+% Space between chapter (or whatever) number and the title.
+\def\labelspace{\hskip1em \relax}
+
+\def\dopageno#1{{\rm #1}}
+\def\doshortpageno#1{{\rm #1}}
+
+\def\chapentryfonts{\secfonts \rm}
+\def\secentryfonts{\textfonts}
+\def\subsecentryfonts{\textfonts}
+\def\subsubsecentryfonts{\textfonts}
+
+
+\message{environments,}
+% @foo ... @end foo.
+
+% @tex ... @end tex    escapes into raw TeX temporarily.
+% One exception: @ is still an escape character, so that @end tex works.
+% But \@ or @@ will get a plain @ character.
+
+\envdef\tex{%
+  \setupmarkupstyle{tex}%
+  \catcode `\\=0 \catcode `\{=1 \catcode `\}=2
+  \catcode `\$=3 \catcode `\&=4 \catcode `\#=6
+  \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
+  \catcode `\%=14
+  \catcode `\+=\other
+  \catcode `\"=\other
+  \catcode `\|=\other
+  \catcode `\<=\other
+  \catcode `\>=\other
+  \catcode `\`=\other
+  \catcode `\'=\other
+  \escapechar=`\\
+  %
+  % ' is active in math mode (mathcode"8000).  So reset it, and all our
+  % other math active characters (just in case), to plain's definitions.
+  \mathactive
+  %
+  % Inverse of the list at the beginning of the file.
+  \let\b=\ptexb
+  \let\bullet=\ptexbullet
+  \let\c=\ptexc
+  \let\,=\ptexcomma
+  \let\.=\ptexdot
+  \let\dots=\ptexdots
+  \let\equiv=\ptexequiv
+  \let\!=\ptexexclam
+  \let\i=\ptexi
+  \let\indent=\ptexindent
+  \let\noindent=\ptexnoindent
+  \let\{=\ptexlbrace
+  \let\+=\tabalign
+  \let\}=\ptexrbrace
+  \let\/=\ptexslash
+  \let\sp=\ptexsp
+  \let\*=\ptexstar
+  %\let\sup=\ptexsup % do not redefine, we want @sup to work in math mode
+  \let\t=\ptext
+  \expandafter \let\csname top\endcsname=\ptextop  % we've made it outer
+  \let\frenchspacing=\plainfrenchspacing
+  %
+  \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
+  \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
+  \def\@{@}%
+}
+% There is no need to define \Etex.
+
+% Define @lisp ... @end lisp.
+% @lisp environment forms a group so it can rebind things,
+% including the definition of @end lisp (which normally is erroneous).
+
+% Amount to narrow the margins by for @lisp.
+\newskip\lispnarrowing \lispnarrowing=0.4in
+
+% This is the definition that ^^M gets inside @lisp, @example, and other
+% such environments.  \null is better than a space, since it doesn't
+% have any width.
+\def\lisppar{\null\endgraf}
+
+% This space is always present above and below environments.
+\newskip\envskipamount \envskipamount = 0pt
+
+% Make spacing and below environment symmetrical.  We use \parskip here
+% to help in doing that, since in @example-like environments \parskip
+% is reset to zero; thus the \afterenvbreak inserts no space -- but the
+% start of the next paragraph will insert \parskip.
+%
+\def\aboveenvbreak{{%
+  % =10000 instead of <10000 because of a special case in \itemzzz and
+  % \sectionheading, q.v.
+  \ifnum \lastpenalty=10000 \else
+    \advance\envskipamount by \parskip
+    \endgraf
+    \ifdim\lastskip<\envskipamount
+      \removelastskip
+      \ifnum\lastpenalty<10000
+        % Penalize breaking before the environment, because preceding text
+        % often leads into it.
+        \penalty100
+      \fi
+      \vskip\envskipamount
+    \fi
+  \fi
+}}
+
+\def\afterenvbreak{{%
+  % =10000 instead of <10000 because of a special case in \itemzzz and
+  % \sectionheading, q.v.
+  \ifnum \lastpenalty=10000 \else
+    \advance\envskipamount by \parskip
+    \endgraf
+    \ifdim\lastskip<\envskipamount
+      \removelastskip
+      % it's not a good place to break if the last penalty was \nobreak
+      % or better ...
+      \ifnum\lastpenalty<10000 \penalty-50 \fi
+      \vskip\envskipamount
+    \fi
+  \fi
+}}
+
+% \nonarrowing is a flag.  If "set", @lisp etc don't narrow margins; it will
+% also clear it, so that its embedded environments do the narrowing again.
+\let\nonarrowing=\relax
+
+% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
+% environment contents.
+\font\circle=lcircle10
+\newdimen\circthick
+\newdimen\cartouter\newdimen\cartinner
+\newskip\normbskip\newskip\normpskip\newskip\normlskip
+\circthick=\fontdimen8\circle
+%
+\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
+\def\ctr{{\hskip 6pt\circle\char'010}}
+\def\cbl{{\circle\char'012\hskip -6pt}}
+\def\cbr{{\hskip 6pt\circle\char'011}}
+\def\carttop{\hbox to \cartouter{\hskip\lskip
+        \ctl\leaders\hrule height\circthick\hfil\ctr
+        \hskip\rskip}}
+\def\cartbot{\hbox to \cartouter{\hskip\lskip
+        \cbl\leaders\hrule height\circthick\hfil\cbr
+        \hskip\rskip}}
+%
+\newskip\lskip\newskip\rskip
+
+\envdef\cartouche{%
+  \ifhmode\par\fi  % can't be in the midst of a paragraph.
+  \startsavinginserts
+  \lskip=\leftskip \rskip=\rightskip
+  \leftskip=0pt\rightskip=0pt % we want these *outside*.
+  \cartinner=\hsize \advance\cartinner by-\lskip
+  \advance\cartinner by-\rskip
+  \cartouter=\hsize
+  \advance\cartouter by 18.4pt	% allow for 3pt kerns on either
+				% side, and for 6pt waste from
+				% each corner char, and rule thickness
+  \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
+  %
+  % If this cartouche directly follows a sectioning command, we need the
+  % \parskip glue (backspaced over by default) or the cartouche can
+  % collide with the section heading.
+  \ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi
+  %
+  \setbox\groupbox=\vbox\bgroup
+      \baselineskip=0pt\parskip=0pt\lineskip=0pt
+      \carttop
+      \hbox\bgroup
+	  \hskip\lskip
+	  \vrule\kern3pt
+	  \vbox\bgroup
+	      \kern3pt
+	      \hsize=\cartinner
+	      \baselineskip=\normbskip
+	      \lineskip=\normlskip
+	      \parskip=\normpskip
+	      \vskip -\parskip
+	      \comment % For explanation, see the end of def\group.
+}
+\def\Ecartouche{%
+              \ifhmode\par\fi
+	      \kern3pt
+	  \egroup
+	  \kern3pt\vrule
+	  \hskip\rskip
+      \egroup
+      \cartbot
+  \egroup
+  \addgroupbox
+  \checkinserts
+}
+
+
+% This macro is called at the beginning of all the @example variants,
+% inside a group.
+\newdimen\nonfillparindent
+\def\nonfillstart{%
+  \aboveenvbreak
+  \ifdim\hfuzz < 12pt \hfuzz = 12pt \fi % Don't be fussy
+  \sepspaces % Make spaces be word-separators rather than space tokens.
+  \let\par = \lisppar % don't ignore blank lines
+  \obeylines % each line of input is a line of output
+  \parskip = 0pt
+  % Turn off paragraph indentation but redefine \indent to emulate
+  % the normal \indent.
+  \nonfillparindent=\parindent
+  \parindent = 0pt
+  \let\indent\nonfillindent
+  %
+  \emergencystretch = 0pt % don't try to avoid overfull boxes
+  \ifx\nonarrowing\relax
+    \advance \leftskip by \lispnarrowing
+    \exdentamount=\lispnarrowing
+  \else
+    \let\nonarrowing = \relax
+  \fi
+  \let\exdent=\nofillexdent
+}
+
+\begingroup
+\obeyspaces
+% We want to swallow spaces (but not other tokens) after the fake
+% @indent in our nonfill-environments, where spaces are normally
+% active and set to @tie, resulting in them not being ignored after
+% @indent.
+\gdef\nonfillindent{\futurelet\temp\nonfillindentcheck}%
+\gdef\nonfillindentcheck{%
+\ifx\temp %
+\expandafter\nonfillindentgobble%
+\else%
+\leavevmode\nonfillindentbox%
+\fi%
+}%
+\endgroup
+\def\nonfillindentgobble#1{\nonfillindent}
+\def\nonfillindentbox{\hbox to \nonfillparindent{\hss}}
+
+% If you want all examples etc. small: @set dispenvsize small.
+% If you want even small examples the full size: @set dispenvsize nosmall.
+% This affects the following displayed environments:
+%    @example, @display, @format, @lisp
+%
+\def\smallword{small}
+\def\nosmallword{nosmall}
+\let\SETdispenvsize\relax
+\def\setnormaldispenv{%
+  \ifx\SETdispenvsize\smallword
+    % end paragraph for sake of leading, in case document has no blank
+    % line.  This is redundant with what happens in \aboveenvbreak, but
+    % we need to do it before changing the fonts, and it's inconvenient
+    % to change the fonts afterward.
+    \ifnum \lastpenalty=10000 \else \endgraf \fi
+    \smallexamplefonts \rm
+  \fi
+}
+\def\setsmalldispenv{%
+  \ifx\SETdispenvsize\nosmallword
+  \else
+    \ifnum \lastpenalty=10000 \else \endgraf \fi
+    \smallexamplefonts \rm
+  \fi
+}
+
+% We often define two environments, @foo and @smallfoo.
+% Let's do it in one command.  #1 is the env name, #2 the definition.
+\def\makedispenvdef#1#2{%
+  \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}%
+  \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}%
+  \expandafter\let\csname E#1\endcsname \afterenvbreak
+  \expandafter\let\csname Esmall#1\endcsname \afterenvbreak
+}
+
+% Define two environment synonyms (#1 and #2) for an environment.
+\def\maketwodispenvdef#1#2#3{%
+  \makedispenvdef{#1}{#3}%
+  \makedispenvdef{#2}{#3}%
+}
+%
+% @lisp: indented, narrowed, typewriter font;
+% @example: same as @lisp.
+%
+% @smallexample and @smalllisp: use smaller fonts.
+% Originally contributed by Pavel@xerox.
+%
+\maketwodispenvdef{lisp}{example}{%
+  \nonfillstart
+  \tt\setupmarkupstyle{example}%
+  \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
+  \gobble % eat return
+}
+% @display/@smalldisplay: same as @lisp except keep current font.
+%
+\makedispenvdef{display}{%
+  \nonfillstart
+  \gobble
+}
+
+% @format/@smallformat: same as @display except don't narrow margins.
+%
+\makedispenvdef{format}{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \gobble
+}
+
+% @flushleft: same as @format, but doesn't obey \SETdispenvsize.
+\envdef\flushleft{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \gobble
+}
+\let\Eflushleft = \afterenvbreak
+
+% @flushright.
+%
+\envdef\flushright{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \advance\leftskip by 0pt plus 1fill\relax
+  \gobble
+}
+\let\Eflushright = \afterenvbreak
+
+
+% @raggedright does more-or-less normal line breaking but no right
+% justification.  From plain.tex.  Don't stretch around special
+% characters in urls in this environment, since the stretch at the right
+% should be enough.
+\envdef\raggedright{%
+  \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax
+  \def\urefprestretchamount{0pt}%
+  \def\urefpoststretchamount{0pt}%
+}
+\let\Eraggedright\par
+
+\envdef\raggedleft{%
+  \parindent=0pt \leftskip0pt plus2em
+  \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
+  \hbadness=10000 % Last line will usually be underfull, so turn off
+                  % badness reporting.
+}
+\let\Eraggedleft\par
+
+\envdef\raggedcenter{%
+  \parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em
+  \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
+  \hbadness=10000 % Last line will usually be underfull, so turn off
+                  % badness reporting.
+}
+\let\Eraggedcenter\par
+
+
+% @quotation does normal linebreaking (hence we can't use \nonfillstart)
+% and narrows the margins.  We keep \parskip nonzero in general, since
+% we're doing normal filling.  So, when using \aboveenvbreak and
+% \afterenvbreak, temporarily make \parskip 0.
+%
+\makedispenvdef{quotation}{\quotationstart}
+%
+\def\quotationstart{%
+  \indentedblockstart % same as \indentedblock, but increase right margin too.
+  \ifx\nonarrowing\relax
+    \advance\rightskip by \lispnarrowing
+  \fi
+  \parsearg\quotationlabel
+}
+
+% We have retained a nonzero parskip for the environment, since we're
+% doing normal filling.
+%
+\def\Equotation{%
+  \par
+  \ifx\quotationauthor\thisisundefined\else
+    % indent a bit.
+    \leftline{\kern 2\leftskip \sl ---\quotationauthor}%
+  \fi
+  {\parskip=0pt \afterenvbreak}%
+}
+\def\Esmallquotation{\Equotation}
+
+% If we're given an argument, typeset it in bold with a colon after.
+\def\quotationlabel#1{%
+  \def\temp{#1}%
+  \ifx\temp\empty \else
+    {\bf #1: }%
+  \fi
+}
+
+% @indentedblock is like @quotation, but indents only on the left and
+% has no optional argument.
+%
+\makedispenvdef{indentedblock}{\indentedblockstart}
+%
+\def\indentedblockstart{%
+  {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
+  \parindent=0pt
+  %
+  % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+  \ifx\nonarrowing\relax
+    \advance\leftskip by \lispnarrowing
+    \exdentamount = \lispnarrowing
+  \else
+    \let\nonarrowing = \relax
+  \fi
+}
+
+% Keep a nonzero parskip for the environment, since we're doing normal filling.
+%
+\def\Eindentedblock{%
+  \par
+  {\parskip=0pt \afterenvbreak}%
+}
+\def\Esmallindentedblock{\Eindentedblock}
+
+
+% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
+% If we want to allow any <char> as delimiter,
+% we need the curly braces so that makeinfo sees the @verb command, eg:
+% `@verbx...x' would look like the '@verbx' command.  --janneke@gnu.org
+%
+% [Knuth]: Donald Ervin Knuth, 1996.  The TeXbook.
+%
+% [Knuth] p.344; only we need to do the other characters Texinfo sets
+% active too.  Otherwise, they get lost as the first character on a
+% verbatim line.
+\def\dospecials{%
+  \do\ \do\\\do\{\do\}\do\$\do\&%
+  \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
+  \do\<\do\>\do\|\do\@\do+\do\"%
+  % Don't do the quotes -- if we do, @set txicodequoteundirected and
+  % @set txicodequotebacktick will not have effect on @verb and
+  % @verbatim, and ?` and !` ligatures won't get disabled.
+  %\do\`\do\'%
+}
+%
+% [Knuth] p. 380
+\def\uncatcodespecials{%
+  \def\do##1{\catcode`##1=\other}\dospecials}
+%
+% Setup for the @verb command.
+%
+% Eight spaces for a tab
+\begingroup
+  \catcode`\^^I=\active
+  \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }}
+\endgroup
+%
+\def\setupverb{%
+  \tt  % easiest (and conventionally used) font for verbatim
+  \def\par{\leavevmode\endgraf}%
+  \setupmarkupstyle{verb}%
+  \tabeightspaces
+  % Respect line breaks,
+  % print special symbols as themselves, and
+  % make each space count
+  % must do in this order:
+  \obeylines \uncatcodespecials \sepspaces
+}
+
+% Setup for the @verbatim environment
+%
+% Real tab expansion.
+\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
+%
+% We typeset each line of the verbatim in an \hbox, so we can handle
+% tabs.  The \global is in case the verbatim line starts with an accent,
+% or some other command that starts with a begin-group.  Otherwise, the
+% entire \verbbox would disappear at the corresponding end-group, before
+% it is typeset.  Meanwhile, we can't have nested verbatim commands
+% (can we?), so the \global won't be overwriting itself.
+\newbox\verbbox
+\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup}
+%
+\begingroup
+  \catcode`\^^I=\active
+  \gdef\tabexpand{%
+    \catcode`\^^I=\active
+    \def^^I{\leavevmode\egroup
+      \dimen\verbbox=\wd\verbbox % the width so far, or since the previous tab
+      \divide\dimen\verbbox by\tabw
+      \multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw
+      \advance\dimen\verbbox by\tabw  % advance to next multiple of \tabw
+      \wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox
+    }%
+  }
+\endgroup
+
+% start the verbatim environment.
+\def\setupverbatim{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \tt % easiest (and conventionally used) font for verbatim
+  % The \leavevmode here is for blank lines.  Otherwise, we would
+  % never \starttabox and the \egroup would end verbatim mode.
+  \def\par{\leavevmode\egroup\box\verbbox\endgraf}%
+  \tabexpand
+  \setupmarkupstyle{verbatim}%
+  % Respect line breaks,
+  % print special symbols as themselves, and
+  % make each space count.
+  % Must do in this order:
+  \obeylines \uncatcodespecials \sepspaces
+  \everypar{\starttabbox}%
+}
+
+% Do the @verb magic: verbatim text is quoted by unique
+% delimiter characters.  Before first delimiter expect a
+% right brace, after last delimiter expect closing brace:
+%
+%    \def\doverb'{'<char>#1<char>'}'{#1}
+%
+% [Knuth] p. 382; only eat outer {}
+\begingroup
+  \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other
+  \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next]
+\endgroup
+%
+\def\verb{\begingroup\setupverb\doverb}
+%
+%
+% Do the @verbatim magic: define the macro \doverbatim so that
+% the (first) argument ends when '@end verbatim' is reached, ie:
+%
+%     \def\doverbatim#1@end verbatim{#1}
+%
+% For Texinfo it's a lot easier than for LaTeX,
+% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
+% we need not redefine '\', '{' and '}'.
+%
+% Inspired by LaTeX's verbatim command set [latex.ltx]
+%
+\begingroup
+  \catcode`\ =\active
+  \obeylines %
+  % ignore everything up to the first ^^M, that's the newline at the end
+  % of the @verbatim input line itself.  Otherwise we get an extra blank
+  % line in the output.
+  \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
+  % We really want {...\end verbatim} in the body of the macro, but
+  % without the active space; thus we have to use \xdef and \gobble.
+\endgroup
+%
+\envdef\verbatim{%
+    \setupverbatim\doverbatim
+}
+\let\Everbatim = \afterenvbreak
+
+
+% @verbatiminclude FILE - insert text of file in verbatim environment.
+%
+\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude}
+%
+\def\doverbatiminclude#1{%
+  {%
+    \makevalueexpandable
+    \setupverbatim
+    \indexnofonts       % Allow `@@' and other weird things in file names.
+    \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}%
+    \input #1
+    \afterenvbreak
+  }%
+}
+
+% @copying ... @end copying.
+% Save the text away for @insertcopying later.
+%
+% We save the uninterpreted tokens, rather than creating a box.
+% Saving the text in a box would be much easier, but then all the
+% typesetting commands (@smallbook, font changes, etc.) have to be done
+% beforehand -- and a) we want @copying to be done first in the source
+% file; b) letting users define the frontmatter in as flexible order as
+% possible is desirable.
+%
+\def\copying{\checkenv{}\begingroup\scanargctxt\docopying}
+\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}}
+%
+\def\insertcopying{%
+  \begingroup
+    \parindent = 0pt  % paragraph indentation looks wrong on title page
+    \scanexp\copyingtext
+  \endgroup
+}
+
+
+\message{defuns,}
+% @defun etc.
+
+\newskip\defbodyindent \defbodyindent=.4in
+\newskip\defargsindent \defargsindent=50pt
+\newskip\deflastargmargin \deflastargmargin=18pt
+\newcount\defunpenalty
+
+% Start the processing of @deffn:
+\def\startdefun{%
+  \ifnum\lastpenalty<10000
+    \medbreak
+    \defunpenalty=10003 % Will keep this @deffn together with the
+                        % following @def command, see below.
+  \else
+    % If there are two @def commands in a row, we'll have a \nobreak,
+    % which is there to keep the function description together with its
+    % header.  But if there's nothing but headers, we need to allow a
+    % break somewhere.  Check specifically for penalty 10002, inserted
+    % by \printdefunline, instead of 10000, since the sectioning
+    % commands also insert a nobreak penalty, and we don't want to allow
+    % a break between a section heading and a defun.
+    %
+    % As a further refinement, we avoid "club" headers by signalling
+    % with penalty of 10003 after the very first @deffn in the
+    % sequence (see above), and penalty of 10002 after any following
+    % @def command.
+    \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi
+    %
+    % Similarly, after a section heading, do not allow a break.
+    % But do insert the glue.
+    \medskip  % preceded by discardable penalty, so not a breakpoint
+  \fi
+  %
+  \parindent=0in
+  \advance\leftskip by \defbodyindent
+  \exdentamount=\defbodyindent
+}
+
+\def\dodefunx#1{%
+  % First, check whether we are in the right environment:
+  \checkenv#1%
+  %
+  % As above, allow line break if we have multiple x headers in a row.
+  % It's not a great place, though.
+  \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi
+  %
+  % And now, it's time to reuse the body of the original defun:
+  \expandafter\gobbledefun#1%
+}
+\def\gobbledefun#1\startdefun{}
+
+% \printdefunline \deffnheader{text}
+%
+\def\printdefunline#1#2{%
+  \begingroup
+    % call \deffnheader:
+    #1#2 \endheader
+    % common ending:
+    \interlinepenalty = 10000
+    \advance\rightskip by 0pt plus 1fil\relax
+    \endgraf
+    \nobreak\vskip -\parskip
+    \penalty\defunpenalty  % signal to \startdefun and \dodefunx
+    % Some of the @defun-type tags do not enable magic parentheses,
+    % rendering the following check redundant.  But we don't optimize.
+    \checkparencounts
+  \endgroup
+}
+
+\def\Edefun{\endgraf\medbreak}
+
+% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
+% the only thing remaining is to define \deffnheader.
+%
+\def\makedefun#1{%
+  \expandafter\let\csname E#1\endcsname = \Edefun
+  \edef\temp{\noexpand\domakedefun
+    \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}%
+  \temp
+}
+
+% \domakedefun \deffn \deffnx \deffnheader { (defn. of \deffnheader) }
+%
+% Define \deffn and \deffnx, without parameters.
+% \deffnheader has to be defined explicitly.
+%
+\def\domakedefun#1#2#3{%
+  \envdef#1{%
+    \startdefun
+    \doingtypefnfalse    % distinguish typed functions from all else
+    \parseargusing\activeparens{\printdefunline#3}%
+  }%
+  \def#2{\dodefunx#1}%
+  \def#3%
+}
+
+\newif\ifdoingtypefn       % doing typed function?
+\newif\ifrettypeownline    % typeset return type on its own line?
+
+% @deftypefnnewline on|off says whether the return type of typed functions
+% are printed on their own line.  This affects @deftypefn, @deftypefun,
+% @deftypeop, and @deftypemethod.
+%
+\parseargdef\deftypefnnewline{%
+  \def\temp{#1}%
+  \ifx\temp\onword
+    \expandafter\let\csname SETtxideftypefnnl\endcsname
+      = \empty
+  \else\ifx\temp\offword
+    \expandafter\let\csname SETtxideftypefnnl\endcsname
+      = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @txideftypefnnl value `\temp',
+                must be on|off}%
+  \fi\fi
+}
+
+% Untyped functions:
+
+% @deffn category name args
+\makedefun{deffn}{\deffngeneral{}}
+
+% @deffn category class name args
+\makedefun{defop}#1 {\defopon{#1\ \putwordon}}
+
+% \defopon {category on}class name args
+\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deffngeneral {subind}category name args
+%
+\def\deffngeneral#1#2 #3 #4\endheader{%
+  % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}.
+  \dosubind{fn}{\code{#3}}{#1}%
+  \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}%
+}
+
+% Typed functions:
+
+% @deftypefn category type name args
+\makedefun{deftypefn}{\deftypefngeneral{}}
+
+% @deftypeop category class type name args
+\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}}
+
+% \deftypeopon {category on}class type name args
+\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypefngeneral {subind}category type name args
+%
+\def\deftypefngeneral#1#2 #3 #4 #5\endheader{%
+  \dosubind{fn}{\code{#4}}{#1}%
+  \doingtypefntrue
+  \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+% Typed variables:
+
+% @deftypevr category type var args
+\makedefun{deftypevr}{\deftypecvgeneral{}}
+
+% @deftypecv category class type var args
+\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}}
+
+% \deftypecvof {category of}class type var args
+\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypecvgeneral {subind}category type var args
+%
+\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{%
+  \dosubind{vr}{\code{#4}}{#1}%
+  \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+% Untyped variables:
+
+% @defvr category var args
+\makedefun{defvr}#1 {\deftypevrheader{#1} {} }
+
+% @defcv category class var args
+\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}}
+
+% \defcvof {category of}class var args
+\def\defcvof#1#2 {\deftypecvof{#1}#2 {} }
+
+% Types:
+
+% @deftp category name args
+\makedefun{deftp}#1 #2 #3\endheader{%
+  \doind{tp}{\code{#2}}%
+  \defname{#1}{}{#2}\defunargs{#3\unskip}%
+}
+
+% Remaining @defun-like shortcuts:
+\makedefun{defun}{\deffnheader{\putwordDeffunc} }
+\makedefun{defmac}{\deffnheader{\putwordDefmac} }
+\makedefun{defspec}{\deffnheader{\putwordDefspec} }
+\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} }
+\makedefun{defvar}{\defvrheader{\putwordDefvar} }
+\makedefun{defopt}{\defvrheader{\putwordDefopt} }
+\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} }
+\makedefun{defmethod}{\defopon\putwordMethodon}
+\makedefun{deftypemethod}{\deftypeopon\putwordMethodon}
+\makedefun{defivar}{\defcvof\putwordInstanceVariableof}
+\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof}
+
+% \defname, which formats the name of the @def (not the args).
+% #1 is the category, such as "Function".
+% #2 is the return type, if any.
+% #3 is the function name.
+%
+% We are followed by (but not passed) the arguments, if any.
+%
+\def\defname#1#2#3{%
+  \par
+  % Get the values of \leftskip and \rightskip as they were outside the @def...
+  \advance\leftskip by -\defbodyindent
+  %
+  % Determine if we are typesetting the return type of a typed function
+  % on a line by itself.
+  \rettypeownlinefalse
+  \ifdoingtypefn  % doing a typed function specifically?
+    % then check user option for putting return type on its own line:
+    \expandafter\ifx\csname SETtxideftypefnnl\endcsname\relax \else
+      \rettypeownlinetrue
+    \fi
+  \fi
+  %
+  % How we'll format the category name.  Putting it in brackets helps
+  % distinguish it from the body text that may end up on the next line
+  % just below it.
+  \def\temp{#1}%
+  \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi}
+  %
+  % Figure out line sizes for the paragraph shape.  We'll always have at
+  % least two.
+  \tempnum = 2
+  %
+  % The first line needs space for \box0; but if \rightskip is nonzero,
+  % we need only space for the part of \box0 which exceeds it:
+  \dimen0=\hsize  \advance\dimen0 by -\wd0  \advance\dimen0 by \rightskip
+  %
+  % If doing a return type on its own line, we'll have another line.
+  \ifrettypeownline
+    \advance\tempnum by 1
+    \def\maybeshapeline{0in \hsize}%
+  \else
+    \def\maybeshapeline{}%
+  \fi
+  %
+  % The continuations:
+  \dimen2=\hsize  \advance\dimen2 by -\defargsindent
+  %
+  % The final paragraph shape:
+  \parshape \tempnum  0in \dimen0  \maybeshapeline  \defargsindent \dimen2
+  %
+  % Put the category name at the right margin.
+  \noindent
+  \hbox to 0pt{%
+    \hfil\box0 \kern-\hsize
+    % \hsize has to be shortened this way:
+    \kern\leftskip
+    % Intentionally do not respect \rightskip, since we need the space.
+  }%
+  %
+  % Allow all lines to be underfull without complaint:
+  \tolerance=10000 \hbadness=10000
+  \exdentamount=\defbodyindent
+  {%
+    % defun fonts. We use typewriter by default (used to be bold) because:
+    % . we're printing identifiers, they should be in tt in principle.
+    % . in languages with many accents, such as Czech or French, it's
+    %   common to leave accents off identifiers.  The result looks ok in
+    %   tt, but exceedingly strange in rm.
+    % . we don't want -- and --- to be treated as ligatures.
+    % . this still does not fix the ?` and !` ligatures, but so far no
+    %   one has made identifiers using them :).
+    \df \tt
+    \def\temp{#2}% text of the return type
+    \ifx\temp\empty\else
+      \tclose{\temp}% typeset the return type
+      \ifrettypeownline
+        % put return type on its own line; prohibit line break following:
+        \hfil\vadjust{\nobreak}\break
+      \else
+        \space  % type on same line, so just followed by a space
+      \fi
+    \fi           % no return type
+    #3% output function name
+  }%
+  {\rm\enskip}% hskip 0.5 em of \tenrm
+  %
+  \boldbrax
+  % arguments will be output next, if any.
+}
+
+% Print arguments in slanted roman (not ttsl), inconsistently with using
+% tt for the name.  This is because literal text is sometimes needed in
+% the argument list (groff manual), and ttsl and tt are not very
+% distinguishable.  Prevent hyphenation at `-' chars.
+%
+\def\defunargs#1{%
+  % use sl by default (not ttsl),
+  % tt for the names.
+  \df \sl \hyphenchar\font=0
+  %
+  % On the other hand, if an argument has two dashes (for instance), we
+  % want a way to get ttsl.  We used to recommend @var for that, so
+  % leave the code in, but it's strange for @var to lead to typewriter.
+  % Nowadays we recommend @code, since the difference between a ttsl hyphen
+  % and a tt hyphen is pretty tiny.  @code also disables ?` !`.
+  \def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}%
+  #1%
+  \sl\hyphenchar\font=45
+}
+
+% We want ()&[] to print specially on the defun line.
+%
+\def\activeparens{%
+  \catcode`\(=\active \catcode`\)=\active
+  \catcode`\[=\active \catcode`\]=\active
+  \catcode`\&=\active
+}
+
+% Make control sequences which act like normal parenthesis chars.
+\let\lparen = ( \let\rparen = )
+
+% Be sure that we always have a definition for `(', etc.  For example,
+% if the fn name has parens in it, \boldbrax will not be in effect yet,
+% so TeX would otherwise complain about undefined control sequence.
+{
+  \activeparens
+  \global\let(=\lparen \global\let)=\rparen
+  \global\let[=\lbrack \global\let]=\rbrack
+  \global\let& = \&
+
+  \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
+  \gdef\magicamp{\let&=\amprm}
+}
+
+\newcount\parencount
+
+% If we encounter &foo, then turn on ()-hacking afterwards
+\newif\ifampseen
+\def\amprm#1 {\ampseentrue{\bf\&#1 }}
+
+\def\parenfont{%
+  \ifampseen
+    % At the first level, print parens in roman,
+    % otherwise use the default font.
+    \ifnum \parencount=1 \rm \fi
+  \else
+    % The \sf parens (in \boldbrax) actually are a little bolder than
+    % the contained text.  This is especially needed for [ and ] .
+    \sf
+  \fi
+}
+\def\infirstlevel#1{%
+  \ifampseen
+    \ifnum\parencount=1
+      #1%
+    \fi
+  \fi
+}
+\def\bfafterword#1 {#1 \bf}
+
+\def\opnr{%
+  \global\advance\parencount by 1
+  {\parenfont(}%
+  \infirstlevel \bfafterword
+}
+\def\clnr{%
+  {\parenfont)}%
+  \infirstlevel \sl
+  \global\advance\parencount by -1
+}
+
+\newcount\brackcount
+\def\lbrb{%
+  \global\advance\brackcount by 1
+  {\bf[}%
+}
+\def\rbrb{%
+  {\bf]}%
+  \global\advance\brackcount by -1
+}
+
+\def\checkparencounts{%
+  \ifnum\parencount=0 \else \badparencount \fi
+  \ifnum\brackcount=0 \else \badbrackcount \fi
+}
+% these should not use \errmessage; the glibc manual, at least, actually
+% has such constructs (when documenting function pointers).
+\def\badparencount{%
+  \message{Warning: unbalanced parentheses in @def...}%
+  \global\parencount=0
+}
+\def\badbrackcount{%
+  \message{Warning: unbalanced square brackets in @def...}%
+  \global\brackcount=0
+}
+
+
+\message{macros,}
+% @macro.
+
+% To do this right we need a feature of e-TeX, \scantokens,
+% which we arrange to emulate with a temporary file in ordinary TeX.
+\ifx\eTeXversion\thisisundefined
+  \newwrite\macscribble
+  \def\scantokens#1{%
+    \toks0={#1}%
+    \immediate\openout\macscribble=\jobname.tmp
+    \immediate\write\macscribble{\the\toks0}%
+    \immediate\closeout\macscribble
+    \input \jobname.tmp
+  }
+\fi
+
+\let\aftermacroxxx\relax
+\def\aftermacro{\aftermacroxxx}
+
+% alias because \c means cedilla in @tex or @math
+\let\texinfoc=\c
+
+% Used at the time of macro expansion.
+% Argument is macro body with arguments substituted
+\def\scanmacro#1{%
+  \newlinechar`\^^M
+  \def\xprocessmacroarg{\eatspaces}%
+  %
+  % Process the macro body under the current catcode regime.
+  \scantokens{#1\texinfoc}\aftermacro%
+  %
+  % The \c is to remove the \newlinechar added by \scantokens, and
+  % can be noticed by \parsearg.
+  %   The \aftermacro allows a \comment at the end of the macro definition
+  % to duplicate itself past the final \newlinechar added by \scantokens:
+  % this is used in the definition of \group to comment out a newline.  We
+  % don't do the same for \c to support Texinfo files with macros that ended
+  % with a @c, which should no longer be necessary.
+  %   We avoid surrounding the call to \scantokens with \bgroup and \egroup
+  % to allow macros to open or close groups themselves.
+}
+
+% Used for copying and captions
+\def\scanexp#1{%
+  \bgroup
+  % Undo catcode changes of \startcontents and \printindex
+  % When called from @insertcopying or (short)caption, we need active
+  % backslash to get it printed correctly.
+  % FIXME: This may not be needed.
+  %\catcode`\@=0 \catcode`\\=\active \escapechar=`\@
+  \edef\temp{\noexpand\scanmacro{#1}}%
+  \temp
+  \egroup
+}
+
+\newcount\paramno   % Count of parameters
+\newtoks\macname    % Macro name
+\newif\ifrecursive  % Is it recursive?
+
+% List of all defined macros in the form
+%    \definedummyword\macro1\definedummyword\macro2...
+% Currently is also contains all @aliases; the list can be split
+% if there is a need.
+\def\macrolist{}
+
+% Add the macro to \macrolist
+\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname}
+\def\addtomacrolistxxx#1{%
+     \toks0 = \expandafter{\macrolist\definedummyword#1}%
+     \xdef\macrolist{\the\toks0}%
+}
+
+% Utility routines.
+% This does \let #1 = #2, with \csnames; that is,
+%   \let \csname#1\endcsname = \csname#2\endcsname
+% (except of course we have to play expansion games).
+%
+\def\cslet#1#2{%
+  \expandafter\let
+  \csname#1\expandafter\endcsname
+  \csname#2\endcsname
+}
+
+% Trim leading and trailing spaces off a string.
+% Concepts from aro-bend problem 15 (see CTAN).
+{\catcode`\@=11
+\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
+\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
+\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
+\def\unbrace#1{#1}
+\unbrace{\gdef\trim@@@ #1 } #2@{#1}
+}
+
+% Trim a single trailing ^^M off a string.
+{\catcode`\^^M=\other \catcode`\Q=3%
+\gdef\eatcr #1{\eatcra #1Q^^MQ}%
+\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
+\gdef\eatcrb#1Q#2Q{#1}%
+}
+
+% Macro bodies are absorbed as an argument in a context where
+% all characters are catcode 10, 11 or 12, except \ which is active
+% (as in normal texinfo). It is necessary to change the definition of \
+% to recognize macro arguments; this is the job of \mbodybackslash.
+%
+% Non-ASCII encodings make 8-bit characters active, so un-activate
+% them to avoid their expansion.  Must do this non-globally, to
+% confine the change to the current group.
+%
+% It's necessary to have hard CRs when the macro is executed. This is
+% done by making ^^M (\endlinechar) catcode 12 when reading the macro
+% body, and then making it the \newlinechar in \scanmacro.
+%
+\def\scanctxt{% used as subroutine
+  \catcode`\"=\other
+  \catcode`\+=\other
+  \catcode`\<=\other
+  \catcode`\>=\other
+  \catcode`\^=\other
+  \catcode`\_=\other
+  \catcode`\|=\other
+  \catcode`\~=\other
+  \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi
+}
+
+\def\scanargctxt{% used for copying and captions, not macros.
+  \scanctxt
+  \catcode`\@=\other
+  \catcode`\\=\other
+  \catcode`\^^M=\other
+}
+
+\def\macrobodyctxt{% used for @macro definitions
+  \scanctxt
+  \catcode`\ =\other
+  \catcode`\@=\other
+  \catcode`\{=\other
+  \catcode`\}=\other
+  \catcode`\^^M=\other
+  \usembodybackslash
+}
+
+% Used when scanning braced macro arguments.  Note, however, that catcode
+% changes here are ineffectual if the macro invocation was nested inside
+% an argument to another Texinfo command.
+\def\macroargctxt{%
+  \scanctxt
+  \catcode`\ =\active
+  \catcode`\^^M=\other
+  \catcode`\\=\active
+}
+
+\def\macrolineargctxt{% used for whole-line arguments without braces
+  \scanctxt
+  \catcode`\{=\other
+  \catcode`\}=\other
+}
+
+% \mbodybackslash is the definition of \ in @macro bodies.
+% It maps \foo\ => \csname macarg.foo\endcsname => #N
+% where N is the macro parameter number.
+% We define \csname macarg.\endcsname to be \realbackslash, so
+% \\ in macro replacement text gets you a backslash.
+%
+{\catcode`@=0 @catcode`@\=@active
+ @gdef@usembodybackslash{@let\=@mbodybackslash}
+ @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
+}
+\expandafter\def\csname macarg.\endcsname{\realbackslash}
+
+\def\margbackslash#1{\char`\#1 }
+
+\def\macro{\recursivefalse\parsearg\macroxxx}
+\def\rmacro{\recursivetrue\parsearg\macroxxx}
+
+\def\macroxxx#1{%
+  \getargs{#1}% now \macname is the macname and \argl the arglist
+  \ifx\argl\empty       % no arguments
+     \paramno=0\relax
+  \else
+     \expandafter\parsemargdef \argl;%
+     \if\paramno>256\relax
+       \ifx\eTeXversion\thisisundefined
+         \errhelp = \EMsimple
+         \errmessage{You need eTeX to compile a file with macros with more than 256 arguments}
+       \fi
+     \fi
+  \fi
+  \if1\csname ismacro.\the\macname\endcsname
+     \message{Warning: redefining \the\macname}%
+  \else
+     \expandafter\ifx\csname \the\macname\endcsname \relax
+     \else \errmessage{Macro name \the\macname\space already defined}\fi
+     \global\cslet{macsave.\the\macname}{\the\macname}%
+     \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
+     \addtomacrolist{\the\macname}%
+  \fi
+  \begingroup \macrobodyctxt
+  \ifrecursive \expandafter\parsermacbody
+  \else \expandafter\parsemacbody
+  \fi}
+
+\parseargdef\unmacro{%
+  \if1\csname ismacro.#1\endcsname
+    \global\cslet{#1}{macsave.#1}%
+    \global\expandafter\let \csname ismacro.#1\endcsname=0%
+    % Remove the macro name from \macrolist:
+    \begingroup
+      \expandafter\let\csname#1\endcsname \relax
+      \let\definedummyword\unmacrodo
+      \xdef\macrolist{\macrolist}%
+    \endgroup
+  \else
+    \errmessage{Macro #1 not defined}%
+  \fi
+}
+
+% Called by \do from \dounmacro on each macro.  The idea is to omit any
+% macro definitions that have been changed to \relax.
+%
+\def\unmacrodo#1{%
+  \ifx #1\relax
+    % remove this
+  \else
+    \noexpand\definedummyword \noexpand#1%
+  \fi
+}
+
+% \getargs -- Parse the arguments to a @macro line.  Set \macname to
+% the name of the macro, and \argl to the braced argument list.
+\def\getargs#1{\getargsxxx#1{}}
+\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
+\def\getmacname#1 #2\relax{\macname={#1}}
+\def\getmacargs#1{\def\argl{#1}}
+% This made use of the feature that if the last token of a
+% <parameter list> is #, then the preceding argument is delimited by
+% an opening brace, and that opening brace is not consumed.
+
+% Parse the optional {params} list to @macro or @rmacro.
+% Set \paramno to the number of arguments,
+% and \paramlist to a parameter text for the macro (e.g. #1,#2,#3 for a
+% three-param macro.)  Define \macarg.BLAH for each BLAH in the params
+% list to some hook where the argument is to be expanded.  If there are
+% less than 10 arguments that hook is to be replaced by ##N where N
+% is the position in that list, that is to say the macro arguments are to be
+% defined `a la TeX in the macro body.
+%
+% That gets used by \mbodybackslash (above).
+%
+% If there are 10 or more arguments, a different technique is used: see
+% \parsemmanyargdef.
+%
+\def\parsemargdef#1;{%
+  \paramno=0\def\paramlist{}%
+  \let\hash\relax
+  % \hash is redefined to `#' later to get it into definitions
+  \let\processmacroarg\relax
+  \parsemargdefxxx#1,;,%
+  \ifnum\paramno<10\relax\else
+    \paramno0\relax
+    \parsemmanyargdef@@#1,;,% 10 or more arguments
+  \fi
+}
+\def\parsemargdefxxx#1,{%
+  \if#1;\let\next=\relax
+  \else \let\next=\parsemargdefxxx
+    \advance\paramno by 1
+    \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
+        {\processmacroarg{\hash\the\paramno}}%
+    \edef\paramlist{\paramlist\hash\the\paramno,}%
+  \fi\next}
+
+% \parsemacbody, \parsermacbody
+%
+% Read recursive and nonrecursive macro bodies. (They're different since
+% rec and nonrec macros end differently.)
+%
+% We are in \macrobodyctxt, and the \xdef causes backslashshes in the macro
+% body to be transformed.
+% Set \macrobody to the body of the macro, and call \defmacro.
+%
+{\catcode`\ =\other\long\gdef\parsemacbody#1@end macro{%
+\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
+{\catcode`\ =\other\long\gdef\parsermacbody#1@end rmacro{%
+\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
+
+% Make @ a letter, so that we can make private-to-Texinfo macro names.
+\edef\texiatcatcode{\the\catcode`\@}
+\catcode `@=11\relax
+
+%%%%%%%%%%%%%% Code for > 10 arguments only   %%%%%%%%%%%%%%%%%%
+
+% If there are 10 or more arguments, a different technique is used, where the
+% hook remains in the body, and when macro is to be expanded the body is
+% processed again to replace the arguments.
+%
+% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the
+% argument N value and then \edef the body (nothing else will expand because of
+% the catcode regime under which the body was input).
+%
+% If you compile with TeX (not eTeX), and you have macros with 10 or more
+% arguments, no macro can have more than 256 arguments (else error).
+%
+% In case that there are 10 or more arguments we parse again the arguments
+% list to set new definitions for the \macarg.BLAH macros corresponding to
+% each BLAH argument. It was anyhow needed to parse already once this list
+% in order to count the arguments, and as macros with at most 9 arguments
+% are by far more frequent than macro with 10 or more arguments, defining
+% twice the \macarg.BLAH macros does not cost too much processing power.
+\def\parsemmanyargdef@@#1,{%
+  \if#1;\let\next=\relax
+  \else
+    \let\next=\parsemmanyargdef@@
+    \edef\tempb{\eatspaces{#1}}%
+    \expandafter\def\expandafter\tempa
+       \expandafter{\csname macarg.\tempb\endcsname}%
+    % Note that we need some extra \noexpand\noexpand, this is because we
+    % don't want \the  to be expanded in the \parsermacbody  as it uses an
+    % \xdef .
+    \expandafter\edef\tempa
+      {\noexpand\noexpand\noexpand\the\toks\the\paramno}%
+    \advance\paramno by 1\relax
+  \fi\next}
+
+
+\let\endargs@\relax
+\let\nil@\relax
+\def\nilm@{\nil@}%
+\long\def\nillm@{\nil@}%
+
+% This macro is expanded during the Texinfo macro expansion, not during its
+% definition.  It gets all the arguments' values and assigns them to macros
+% macarg.ARGNAME
+%
+% #1 is the macro name
+% #2 is the list of argument names
+% #3 is the list of argument values
+\def\getargvals@#1#2#3{%
+  \def\macargdeflist@{}%
+  \def\saveparamlist@{#2}% Need to keep a copy for parameter expansion.
+  \def\paramlist{#2,\nil@}%
+  \def\macroname{#1}%
+  \begingroup
+  \macroargctxt
+  \def\argvaluelist{#3,\nil@}%
+  \def\@tempa{#3}%
+  \ifx\@tempa\empty
+    \setemptyargvalues@
+  \else
+    \getargvals@@
+  \fi
+}
+\def\getargvals@@{%
+  \ifx\paramlist\nilm@
+      % Some sanity check needed here that \argvaluelist is also empty.
+      \ifx\argvaluelist\nillm@
+      \else
+        \errhelp = \EMsimple
+        \errmessage{Too many arguments in macro `\macroname'!}%
+      \fi
+      \let\next\macargexpandinbody@
+  \else
+    \ifx\argvaluelist\nillm@
+       % No more arguments values passed to macro.  Set remaining named-arg
+       % macros to empty.
+       \let\next\setemptyargvalues@
+    \else
+      % pop current arg name into \@tempb
+      \def\@tempa##1{\pop@{\@tempb}{\paramlist}##1\endargs@}%
+      \expandafter\@tempa\expandafter{\paramlist}%
+       % pop current argument value into \@tempc
+      \def\@tempa##1{\longpop@{\@tempc}{\argvaluelist}##1\endargs@}%
+      \expandafter\@tempa\expandafter{\argvaluelist}%
+       % Here \@tempb is the current arg name and \@tempc is the current arg value.
+       % First place the new argument macro definition into \@tempd
+       \expandafter\macname\expandafter{\@tempc}%
+       \expandafter\let\csname macarg.\@tempb\endcsname\relax
+       \expandafter\def\expandafter\@tempe\expandafter{%
+         \csname macarg.\@tempb\endcsname}%
+       \edef\@tempd{\long\def\@tempe{\the\macname}}%
+       \push@\@tempd\macargdeflist@
+       \let\next\getargvals@@
+    \fi
+  \fi
+  \next
+}
+
+\def\push@#1#2{%
+  \expandafter\expandafter\expandafter\def
+  \expandafter\expandafter\expandafter#2%
+  \expandafter\expandafter\expandafter{%
+  \expandafter#1#2}%
+}
+
+% Replace arguments by their values in the macro body, and place the result
+% in macro \@tempa.
+%
+\def\macvalstoargs@{%
+  %  To do this we use the property that token registers that are \the'ed
+  % within an \edef  expand only once. So we are going to place all argument
+  % values into respective token registers.
+  %
+  % First we save the token context, and initialize argument numbering.
+  \begingroup
+    \paramno0\relax
+    % Then, for each argument number #N, we place the corresponding argument
+    % value into a new token list register \toks#N
+    \expandafter\putargsintokens@\saveparamlist@,;,%
+    % Then, we expand the body so that argument are replaced by their
+    % values. The trick for values not to be expanded themselves is that they
+    % are within tokens and that tokens expand only once in an \edef .
+    \edef\@tempc{\csname mac.\macroname .body\endcsname}%
+    % Now we restore the token stack pointer to free the token list registers
+    % which we have used, but we make sure that expanded body is saved after
+    % group.
+    \expandafter
+  \endgroup
+  \expandafter\def\expandafter\@tempa\expandafter{\@tempc}%
+  }
+
+% Define the named-macro outside of this group and then close this group.
+%
+\def\macargexpandinbody@{%
+  \expandafter
+  \endgroup
+  \macargdeflist@
+  % First the replace in body the macro arguments by their values, the result
+  % is in \@tempa .
+  \macvalstoargs@
+  % Then we point at the \norecurse or \gobble (for recursive) macro value
+  % with \@tempb .
+  \expandafter\let\expandafter\@tempb\csname mac.\macroname .recurse\endcsname
+  % Depending on whether it is recursive or not, we need some tailing
+  % \egroup .
+  \ifx\@tempb\gobble
+     \let\@tempc\relax
+  \else
+     \let\@tempc\egroup
+  \fi
+  % And now we do the real job:
+  \edef\@tempd{\noexpand\@tempb{\macroname}\noexpand\scanmacro{\@tempa}\@tempc}%
+  \@tempd
+}
+
+\def\putargsintokens@#1,{%
+  \if#1;\let\next\relax
+  \else
+    \let\next\putargsintokens@
+    % First we allocate the new token list register, and give it a temporary
+    % alias \@tempb .
+    \toksdef\@tempb\the\paramno
+    % Then we place the argument value into that token list register.
+    \expandafter\let\expandafter\@tempa\csname macarg.#1\endcsname
+    \expandafter\@tempb\expandafter{\@tempa}%
+    \advance\paramno by 1\relax
+  \fi
+  \next
+}
+
+% Trailing missing arguments are set to empty.
+%
+\def\setemptyargvalues@{%
+  \ifx\paramlist\nilm@
+    \let\next\macargexpandinbody@
+  \else
+    \expandafter\setemptyargvaluesparser@\paramlist\endargs@
+    \let\next\setemptyargvalues@
+  \fi
+  \next
+}
+
+\def\setemptyargvaluesparser@#1,#2\endargs@{%
+  \expandafter\def\expandafter\@tempa\expandafter{%
+    \expandafter\def\csname macarg.#1\endcsname{}}%
+  \push@\@tempa\macargdeflist@
+  \def\paramlist{#2}%
+}
+
+% #1 is the element target macro
+% #2 is the list macro
+% #3,#4\endargs@ is the list value
+\def\pop@#1#2#3,#4\endargs@{%
+   \def#1{#3}%
+   \def#2{#4}%
+}
+\long\def\longpop@#1#2#3,#4\endargs@{%
+   \long\def#1{#3}%
+   \long\def#2{#4}%
+}
+
+
+%%%%%%%%%%%%%% End of code for > 10 arguments %%%%%%%%%%%%%%%%%%
+
+
+
+% Remove following spaces at the expansion stage.
+% This works because spaces are discarded before each argument when TeX is
+% getting the arguments for a macro.
+% This must not be immediately followed by a }.
+\long\def\gobblespaces#1{#1}
+
+% This defines a Texinfo @macro or @rmacro, called by \parsemacbody.
+%    \macrobody has the body of the macro in it, with placeholders for
+% its parameters, looking like "\processmacroarg{\hash 1}".
+%    \paramno is the number of parameters
+%    \paramlist is a TeX parameter text, e.g. "#1,#2,#3,"
+% There are eight cases: recursive and nonrecursive macros of zero, one,
+% up to nine, and many arguments.
+% \xdef is used so that macro definitions will survive the file
+% they're defined in: @include reads the file inside a group.
+%
+\def\defmacro{%
+  \let\hash=##% convert placeholders to macro parameter chars
+  \ifnum\paramno=1
+    \def\processmacroarg{\gobblespaces}%
+    % This removes the pair of braces around the argument.  We don't
+    % use \eatspaces, because this can cause ends of lines to be lost
+    % when the argument to \eatspaces is read, leading to line-based
+    % commands like "@itemize" not being read correctly.
+  \else
+    \def\processmacroarg{\xprocessmacroarg}%
+    \let\xprocessmacroarg\relax
+  \fi
+  \ifrecursive   %%%%%%%%%%%%%% Recursive %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    \ifcase\paramno
+    % 0
+      \expandafter\xdef\csname\the\macname\endcsname{%
+        \noexpand\scanmacro{\macrobody}}%
+    \or % 1
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup
+         \noexpand\braceorline
+         \expandafter\noexpand\csname\the\macname @@@\endcsname}%
+      \expandafter\xdef\csname\the\macname @@@\endcsname##1{%
+         \expandafter\noexpand\csname\the\macname @@@@\endcsname{%
+           \noexpand\gobblespaces##1\empty}%
+           % The \empty is for \gobblespaces in case #1 is empty
+         }%
+      \expandafter\xdef\csname\the\macname @@@@\endcsname##1{%
+         \egroup\noexpand\scanmacro{\macrobody}}%
+    \else
+      \ifnum\paramno<10\relax % at most 9
+        % See non-recursive section below for comments
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \bgroup
+          \noexpand\expandafter
+          \noexpand\macroargctxt
+          \noexpand\expandafter
+          \expandafter\noexpand\csname\the\macname @@\endcsname}%
+        \expandafter\xdef\csname\the\macname @@\endcsname##1{%
+            \noexpand\passargtomacro
+            \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}%
+        \expandafter\xdef\csname\the\macname @@@\endcsname##1{%
+            \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}%
+        \expandafter\expandafter
+        \expandafter\xdef
+        \expandafter\expandafter
+          \csname\the\macname @@@@\endcsname\paramlist{%
+            \egroup\noexpand\scanmacro{\macrobody}}%
+      \else % 10 or more
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \noexpand\getargvals@{\the\macname}{\argl}%
+        }%
+        \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody
+        \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble
+      \fi
+    \fi
+  \else  %%%%%%%%%%%%%%%%%%%%%% Non-recursive %%%%%%%%%%%%%%%%%%%%%%%%%%
+    \ifcase\paramno
+    % 0
+      \expandafter\xdef\csname\the\macname\endcsname{%
+        \noexpand\scanmacro{\macrobody}}%
+    \or % 1
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup
+         \noexpand\braceorline
+         \expandafter\noexpand\csname\the\macname @@@\endcsname}%
+      \expandafter\xdef\csname\the\macname @@@\endcsname##1{%
+         \expandafter\noexpand\csname\the\macname @@@@\endcsname{%
+           \noexpand\gobblespaces##1\empty}%
+           % The \empty is for \gobblespaces in case #1 is empty
+         }%
+      \expandafter\xdef\csname\the\macname @@@@\endcsname##1{%
+        \egroup
+        \noexpand\scanmacro{\macrobody}%
+        }%
+    \else % at most 9
+      \ifnum\paramno<10\relax
+        % @MACNAME sets the context for reading the macro argument
+        % @MACNAME@@ gets the argument, processes backslashes and appends a
+        % comma.
+        % @MACNAME@@@ removes braces surrounding the argument list.
+        % @MACNAME@@@@ scans the macro body with arguments substituted.
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \bgroup
+          \noexpand\expandafter  % This \expandafter skip any spaces after the
+          \noexpand\macroargctxt % macro before we change the catcode of space.
+          \noexpand\expandafter
+          \expandafter\noexpand\csname\the\macname @@\endcsname}%
+        \expandafter\xdef\csname\the\macname @@\endcsname##1{%
+            \noexpand\passargtomacro
+            \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}%
+        \expandafter\xdef\csname\the\macname @@@\endcsname##1{%
+            \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}%
+        \expandafter\expandafter
+        \expandafter\xdef
+        \expandafter\expandafter
+          \csname\the\macname @@@@\endcsname\paramlist{%
+            \egroup\noexpand\scanmacro{\macrobody}}%
+      \else % 10 or more:
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \noexpand\getargvals@{\the\macname}{\argl}%
+        }%
+        \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody
+        \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse
+      \fi
+    \fi
+  \fi}
+
+\catcode `\@\texiatcatcode\relax % end private-to-Texinfo catcodes
+
+\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+{\catcode`\@=0 \catcode`\\=13  % We need to manipulate \ so use @ as escape
+@catcode`@_=11  % private names
+@catcode`@!=11  % used as argument separator
+
+% \passargtomacro#1#2 -
+% Call #1 with a list of tokens #2, with any doubled backslashes in #2
+% compressed to one.
+%
+% This implementation works by expansion, and not execution (so we cannot use
+% \def or similar).  This reduces the risk of this failing in contexts where
+% complete expansion is done with no execution (for example, in writing out to
+% an auxiliary file for an index entry).
+%
+% State is kept in the input stream: the argument passed to
+% @look_ahead, @gobble_and_check_finish and @add_segment is
+%
+% THE_MACRO ARG_RESULT ! {PENDING_BS} NEXT_TOKEN  (... rest of input)
+%
+% where:
+% THE_MACRO - name of the macro we want to call
+% ARG_RESULT - argument list we build to pass to that macro
+% PENDING_BS - either a backslash or nothing
+% NEXT_TOKEN - used to look ahead in the input stream to see what's coming next
+
+@gdef@passargtomacro#1#2{%
+  @add_segment #1!{}@relax#2\@_finish\%
+}
+@gdef@_finish{@_finishx} @global@let@_finishx@relax
+
+% #1 - THE_MACRO ARG_RESULT
+% #2 - PENDING_BS
+% #3 - NEXT_TOKEN
+% #4 used to look ahead
+%
+% If the next token is not a backslash, process the rest of the argument;
+% otherwise, remove the next token.
+@gdef@look_ahead#1!#2#3#4{%
+  @ifx#4\%
+   @expandafter@gobble_and_check_finish
+  @else
+   @expandafter@add_segment
+  @fi#1!{#2}#4#4%
+}
+
+% #1 - THE_MACRO ARG_RESULT
+% #2 - PENDING_BS
+% #3 - NEXT_TOKEN
+% #4 should be a backslash, which is gobbled.
+% #5 looks ahead
+%
+% Double backslash found.  Add a single backslash, and look ahead.
+@gdef@gobble_and_check_finish#1!#2#3#4#5{%
+  @add_segment#1\!{}#5#5%
+}
+
+@gdef@is_fi{@fi}
+
+% #1 - THE_MACRO ARG_RESULT
+% #2 - PENDING_BS
+% #3 - NEXT_TOKEN
+% #4 is input stream until next backslash
+%
+% Input stream is either at the start of the argument, or just after a
+% backslash sequence, either a lone backslash, or a doubled backslash.
+% NEXT_TOKEN contains the first token in the input stream: if it is \finish,
+% finish; otherwise, append to ARG_RESULT the segment of the argument up until
+% the next backslash.  PENDING_BACKSLASH contains a backslash to represent
+% a backslash just before the start of the input stream that has not been
+% added to ARG_RESULT.
+@gdef@add_segment#1!#2#3#4\{%
+@ifx#3@_finish
+  @call_the_macro#1!%
+@else
+  % append the pending backslash to the result, followed by the next segment
+  @expandafter@is_fi@look_ahead#1#2#4!{\}@fi
+  % this @fi is discarded by @look_ahead.
+  % we can't get rid of it with \expandafter because we don't know how
+  % long #4 is.
+}
+
+% #1 - THE_MACRO
+% #2 - ARG_RESULT
+% #3 discards the res of the conditional in @add_segment, and @is_fi ends the
+% conditional.
+@gdef@call_the_macro#1#2!#3@fi{@is_fi #1{#2}}
+
+}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% \braceorline MAC is used for a one-argument macro MAC.  It checks
+% whether the next non-whitespace character is a {.  It sets the context
+% for reading the argument (slightly different in the two cases).  Then,
+% to read the argument, in the whole-line case, it then calls the regular
+% \parsearg MAC; in the lbrace case, it calls \passargtomacro MAC.
+%
+\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx}
+\def\braceorlinexxx{%
+  \ifx\nchar\bgroup
+    \macroargctxt
+    \expandafter\passargtomacro
+  \else
+    \macrolineargctxt\expandafter\parsearg
+  \fi \macnamexxx}
+
+
+% @alias.
+% We need some trickery to remove the optional spaces around the equal
+% sign.  Make them active and then expand them all to nothing.
+%
+\def\alias{\parseargusing\obeyspaces\aliasxxx}
+\def\aliasxxx #1{\aliasyyy#1\relax}
+\def\aliasyyy #1=#2\relax{%
+  {%
+    \expandafter\let\obeyedspace=\empty
+    \addtomacrolist{#1}%
+    \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}%
+  }%
+  \next
+}
+
+
+\message{cross references,}
+
+\newwrite\auxfile
+\newif\ifhavexrefs    % True if xref values are known.
+\newif\ifwarnedxrefs  % True if we warned once that they aren't known.
+
+% @inforef is relatively simple.
+\def\inforef #1{\inforefzzz #1,,,,**}
+\def\inforefzzz #1,#2,#3,#4**{%
+  \putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
+  node \samp{\ignorespaces#1{}}}
+
+% @node's only job in TeX is to define \lastnode, which is used in
+% cross-references.  The @node line might or might not have commas, and
+% might or might not have spaces before the first comma, like:
+% @node foo , bar , ...
+% We don't want such trailing spaces in the node name.
+%
+\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse}
+%
+% also remove a trailing comma, in case of something like this:
+% @node Help-Cross,  ,  , Cross-refs
+\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse}
+\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}}
+
+\let\nwnode=\node
+\let\lastnode=\empty
+
+% Write a cross-reference definition for the current node.  #1 is the
+% type (Ynumbered, Yappendix, Ynothing).
+%
+\def\donoderef#1{%
+  \ifx\lastnode\empty\else
+    \setref{\lastnode}{#1}%
+    \global\let\lastnode=\empty
+  \fi
+}
+
+% @anchor{NAME} -- define xref target at arbitrary point.
+%
+\newcount\savesfregister
+%
+\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
+\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
+\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
+
+% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an
+% anchor), which consists of three parts:
+% 1) NAME-title - the current sectioning name taken from \lastsection,
+%                 or the anchor name.
+% 2) NAME-snt   - section number and type, passed as the SNT arg, or
+%                 empty for anchors.
+% 3) NAME-pg    - the page number.
+%
+% This is called from \donoderef, \anchor, and \dofloat.  In the case of
+% floats, there is an additional part, which is not written here:
+% 4) NAME-lof   - the text as it should appear in a @listoffloats.
+%
+\def\setref#1#2{%
+  \pdfmkdest{#1}%
+  \iflinks
+    {%
+      \requireauxfile
+      \atdummies  % preserve commands, but don't expand them
+      \edef\writexrdef##1##2{%
+	\write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef
+	  ##1}{##2}}% these are parameters of \writexrdef
+      }%
+      \toks0 = \expandafter{\lastsection}%
+      \immediate \writexrdef{title}{\the\toks0 }%
+      \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc.
+      \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, at \shipout
+    }%
+  \fi
+}
+
+% @xrefautosectiontitle on|off says whether @section(ing) names are used
+% automatically in xrefs, if the third arg is not explicitly specified.
+% This was provided as a "secret" @set xref-automatic-section-title
+% variable, now it's official.
+%
+\parseargdef\xrefautomaticsectiontitle{%
+  \def\temp{#1}%
+  \ifx\temp\onword
+    \expandafter\let\csname SETxref-automatic-section-title\endcsname
+      = \empty
+  \else\ifx\temp\offword
+    \expandafter\let\csname SETxref-automatic-section-title\endcsname
+      = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @xrefautomaticsectiontitle value `\temp',
+                must be on|off}%
+  \fi\fi
+}
+
+% 
+% @xref, @pxref, and @ref generate cross-references.  For \xrefX, #1 is
+% the node name, #2 the name of the Info cross-reference, #3 the printed
+% node name, #4 the name of the Info file, #5 the name of the printed
+% manual.  All but the node name can be omitted.
+%
+\def\pxref{\putwordsee{} \xrefXX}
+\def\xref{\putwordSee{} \xrefXX}
+\def\ref{\xrefXX}
+
+\def\xrefXX#1{\def\xrefXXarg{#1}\futurelet\tokenafterxref\xrefXXX}
+\def\xrefXXX{\expandafter\xrefX\expandafter[\xrefXXarg,,,,,,,]}
+%
+\newbox\toprefbox
+\newbox\printedrefnamebox
+\newbox\infofilenamebox
+\newbox\printedmanualbox
+%
+\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
+  \unsepspaces
+  %
+  % Get args without leading/trailing spaces.
+  \def\printedrefname{\ignorespaces #3}%
+  \setbox\printedrefnamebox = \hbox{\printedrefname\unskip}%
+  %
+  \def\infofilename{\ignorespaces #4}%
+  \setbox\infofilenamebox = \hbox{\infofilename\unskip}%
+  %
+  \def\printedmanual{\ignorespaces #5}%
+  \setbox\printedmanualbox  = \hbox{\printedmanual\unskip}%
+  %
+  % If the printed reference name (arg #3) was not explicitly given in
+  % the @xref, figure out what we want to use.
+  \ifdim \wd\printedrefnamebox = 0pt
+    % No printed node name was explicitly given.
+    \expandafter\ifx\csname SETxref-automatic-section-title\endcsname \relax
+      % Not auto section-title: use node name inside the square brackets.
+      \def\printedrefname{\ignorespaces #1}%
+    \else
+      % Auto section-title: use chapter/section title inside
+      % the square brackets if we have it.
+      \ifdim \wd\printedmanualbox > 0pt
+        % It is in another manual, so we don't have it; use node name.
+        \def\printedrefname{\ignorespaces #1}%
+      \else
+        \ifhavexrefs
+          % We (should) know the real title if we have the xref values.
+          \def\printedrefname{\refx{#1-title}{}}%
+        \else
+          % Otherwise just copy the Info node name.
+          \def\printedrefname{\ignorespaces #1}%
+        \fi%
+      \fi
+    \fi
+  \fi
+  %
+  % Make link in pdf output.
+  \ifpdf
+    {\indexnofonts
+     \turnoffactive
+     \makevalueexpandable
+     % This expands tokens, so do it after making catcode changes, so _
+     % etc. don't get their TeX definitions.  This ignores all spaces in
+     % #4, including (wrongly) those in the middle of the filename.
+     \getfilename{#4}%
+     %
+     % This (wrongly) does not take account of leading or trailing
+     % spaces in #1, which should be ignored.
+     \edef\pdfxrefdest{#1}%
+     \ifx\pdfxrefdest\empty
+       \def\pdfxrefdest{Top}% no empty targets
+     \else
+       \txiescapepdf\pdfxrefdest  % escape PDF special chars
+     \fi
+     %
+     \leavevmode
+     \startlink attr{/Border [0 0 0]}%
+     \ifnum\filenamelength>0
+       goto file{\the\filename.pdf} name{\pdfxrefdest}%
+     \else
+       goto name{\pdfmkpgn{\pdfxrefdest}}%
+     \fi
+    }%
+    \setcolor{\linkcolor}%
+  \fi
+  %
+  % Float references are printed completely differently: "Figure 1.2"
+  % instead of "[somenode], p.3".  We distinguish them by the
+  % LABEL-title being set to a magic string.
+  {%
+    % Have to otherify everything special to allow the \csname to
+    % include an _ in the xref name, etc.
+    \indexnofonts
+    \turnoffactive
+    \expandafter\global\expandafter\let\expandafter\Xthisreftitle
+      \csname XR#1-title\endcsname
+  }%
+  \iffloat\Xthisreftitle
+    % If the user specified the print name (third arg) to the ref,
+    % print it instead of our usual "Figure 1.2".
+    \ifdim\wd\printedrefnamebox = 0pt
+      \refx{#1-snt}{}%
+    \else
+      \printedrefname
+    \fi
+    %
+    % If the user also gave the printed manual name (fifth arg), append
+    % "in MANUALNAME".
+    \ifdim \wd\printedmanualbox > 0pt
+      \space \putwordin{} \cite{\printedmanual}%
+    \fi
+  \else
+    % node/anchor (non-float) references.
+    %
+    % If we use \unhbox to print the node names, TeX does not insert
+    % empty discretionaries after hyphens, which means that it will not
+    % find a line break at a hyphen in a node names.  Since some manuals
+    % are best written with fairly long node names, containing hyphens,
+    % this is a loss.  Therefore, we give the text of the node name
+    % again, so it is as if TeX is seeing it for the first time.
+    %
+    \ifdim \wd\printedmanualbox > 0pt
+      % Cross-manual reference with a printed manual name.
+      %
+      \crossmanualxref{\cite{\printedmanual\unskip}}%
+    %
+    \else\ifdim \wd\infofilenamebox > 0pt
+      % Cross-manual reference with only an info filename (arg 4), no
+      % printed manual name (arg 5).  This is essentially the same as
+      % the case above; we output the filename, since we have nothing else.
+      %
+      \crossmanualxref{\code{\infofilename\unskip}}%
+    %
+    \else
+      % Reference within this manual.
+      %
+      % _ (for example) has to be the character _ for the purposes of the
+      % control sequence corresponding to the node, but it has to expand
+      % into the usual \leavevmode...\vrule stuff for purposes of
+      % printing. So we \turnoffactive for the \refx-snt, back on for the
+      % printing, back off for the \refx-pg.
+      {\turnoffactive
+       % Only output a following space if the -snt ref is nonempty; for
+       % @unnumbered and @anchor, it won't be.
+       \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
+       \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
+      }%
+      % output the `[mynode]' via the macro below so it can be overridden.
+      \xrefprintnodename\printedrefname
+      %
+      % But we always want a comma and a space:
+      ,\space
+      %
+      % output the `page 3'.
+      \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
+           \ifx,\tokenafterxref
+      \else\ifx.\tokenafterxref
+      \else\ifx;\tokenafterxref
+      \else\ifx)\tokenafterxref
+      \else,% add a , if xref not followed by punctuation
+      \fi\fi\fi\fi
+    \fi\fi
+  \fi
+  \endlink
+\endgroup}
+
+% Output a cross-manual xref to #1.  Used just above (twice).
+%
+% Only include the text "Section ``foo'' in" if the foo is neither
+% missing or Top.  Thus, @xref{,,,foo,The Foo Manual} outputs simply
+% "see The Foo Manual", the idea being to refer to the whole manual.
+%
+% But, this being TeX, we can't easily compare our node name against the
+% string "Top" while ignoring the possible spaces before and after in
+% the input.  By adding the arbitrary 7sp below, we make it much less
+% likely that a real node name would have the same width as "Top" (e.g.,
+% in a monospaced font).  Hopefully it will never happen in practice.
+%
+% For the same basic reason, we retypeset the "Top" at every
+% reference, since the current font is indeterminate.
+%
+\def\crossmanualxref#1{%
+  \setbox\toprefbox = \hbox{Top\kern7sp}%
+  \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}%
+  \ifdim \wd2 > 7sp  % nonempty?
+    \ifdim \wd2 = \wd\toprefbox \else  % same as Top?
+      \putwordSection{} ``\printedrefname'' \putwordin{}\space
+    \fi
+  \fi
+  #1%
+}
+
+% This macro is called from \xrefX for the `[nodename]' part of xref
+% output.  It's a separate macro only so it can be changed more easily,
+% since square brackets don't work well in some documents.  Particularly
+% one that Bob is working on :).
+%
+\def\xrefprintnodename#1{[#1]}
+
+% Things referred to by \setref.
+%
+\def\Ynothing{}
+\def\Yomitfromtoc{}
+\def\Ynumbered{%
+  \ifnum\secno=0
+    \putwordChapter@tie \the\chapno
+  \else \ifnum\subsecno=0
+    \putwordSection@tie \the\chapno.\the\secno
+  \else \ifnum\subsubsecno=0
+    \putwordSection@tie \the\chapno.\the\secno.\the\subsecno
+  \else
+    \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno
+  \fi\fi\fi
+}
+\def\Yappendix{%
+  \ifnum\secno=0
+     \putwordAppendix@tie @char\the\appendixno{}%
+  \else \ifnum\subsecno=0
+     \putwordSection@tie @char\the\appendixno.\the\secno
+  \else \ifnum\subsubsecno=0
+    \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno
+  \else
+    \putwordSection@tie
+      @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno
+  \fi\fi\fi
+}
+
+% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
+% If its value is nonempty, SUFFIX is output afterward.
+%
+\def\refx#1#2{%
+  \requireauxfile
+  {%
+    \indexnofonts
+    \otherbackslash
+    \expandafter\global\expandafter\let\expandafter\thisrefX
+      \csname XR#1\endcsname
+  }%
+  \ifx\thisrefX\relax
+    % If not defined, say something at least.
+    \angleleft un\-de\-fined\angleright
+    \iflinks
+      \ifhavexrefs
+        {\toks0 = {#1}% avoid expansion of possibly-complex value
+         \message{\linenumber Undefined cross reference `\the\toks0'.}}%
+      \else
+        \ifwarnedxrefs\else
+          \global\warnedxrefstrue
+          \message{Cross reference values unknown; you must run TeX again.}%
+        \fi
+      \fi
+    \fi
+  \else
+    % It's defined, so just use it.
+    \thisrefX
+  \fi
+  #2% Output the suffix in any case.
+}
+
+% This is the macro invoked by entries in the aux file.  Usually it's
+% just a \def (we prepend XR to the control sequence name to avoid
+% collisions).  But if this is a float type, we have more work to do.
+%
+\def\xrdef#1#2{%
+  {% The node name might contain 8-bit characters, which in our current
+   % implementation are changed to commands like @'e.  Don't let these
+   % mess up the control sequence name.
+    \indexnofonts
+    \turnoffactive
+    \xdef\safexrefname{#1}%
+  }%
+  %
+  \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref
+  %
+  % Was that xref control sequence that we just defined for a float?
+  \expandafter\iffloat\csname XR\safexrefname\endcsname
+    % it was a float, and we have the (safe) float type in \iffloattype.
+    \expandafter\let\expandafter\floatlist
+      \csname floatlist\iffloattype\endcsname
+    %
+    % Is this the first time we've seen this float type?
+    \expandafter\ifx\floatlist\relax
+      \toks0 = {\do}% yes, so just \do
+    \else
+      % had it before, so preserve previous elements in list.
+      \toks0 = \expandafter{\floatlist\do}%
+    \fi
+    %
+    % Remember this xref in the control sequence \floatlistFLOATTYPE,
+    % for later use in \listoffloats.
+    \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0
+      {\safexrefname}}%
+  \fi
+}
+
+% If working on a large document in chapters, it is convenient to
+% be able to disable indexing, cross-referencing, and contents, for test runs.
+% This is done with @novalidate at the beginning of the file.
+%
+\newif\iflinks \linkstrue % by default we want the aux files.
+\let\novalidate = \linksfalse
+
+% Used when writing to the aux file, or when using data from it.
+\def\requireauxfile{%
+  \iflinks
+    \tryauxfile
+    % Open the new aux file.  TeX will close it automatically at exit.
+    \immediate\openout\auxfile=\jobname.aux
+  \fi
+  \global\let\requireauxfile=\relax   % Only do this once.
+}
+
+% Read the last existing aux file, if any.  No error if none exists.
+%
+\def\tryauxfile{%
+  \openin 1 \jobname.aux
+  \ifeof 1 \else
+    \readdatafile{aux}%
+    \global\havexrefstrue
+  \fi
+  \closein 1
+}
+
+\def\setupdatafile{%
+  \catcode`\^^@=\other
+  \catcode`\^^A=\other
+  \catcode`\^^B=\other
+  \catcode`\^^C=\other
+  \catcode`\^^D=\other
+  \catcode`\^^E=\other
+  \catcode`\^^F=\other
+  \catcode`\^^G=\other
+  \catcode`\^^H=\other
+  \catcode`\^^K=\other
+  \catcode`\^^L=\other
+  \catcode`\^^N=\other
+  \catcode`\^^P=\other
+  \catcode`\^^Q=\other
+  \catcode`\^^R=\other
+  \catcode`\^^S=\other
+  \catcode`\^^T=\other
+  \catcode`\^^U=\other
+  \catcode`\^^V=\other
+  \catcode`\^^W=\other
+  \catcode`\^^X=\other
+  \catcode`\^^Z=\other
+  \catcode`\^^[=\other
+  \catcode`\^^\=\other
+  \catcode`\^^]=\other
+  \catcode`\^^^=\other
+  \catcode`\^^_=\other
+  % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc.
+  % in xref tags, i.e., node names.  But since ^^e4 notation isn't
+  % supported in the main text, it doesn't seem desirable.  Furthermore,
+  % that is not enough: for node names that actually contain a ^
+  % character, we would end up writing a line like this: 'xrdef {'hat
+  % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
+  % argument, and \hat is not an expandable control sequence.  It could
+  % all be worked out, but why?  Either we support ^^ or we don't.
+  %
+  % The other change necessary for this was to define \auxhat:
+  % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
+  % and then to call \auxhat in \setq.
+  %
+  \catcode`\^=\other
+  %
+  % Special characters.  Should be turned off anyway, but...
+  \catcode`\~=\other
+  \catcode`\[=\other
+  \catcode`\]=\other
+  \catcode`\"=\other
+  \catcode`\_=\other
+  \catcode`\|=\other
+  \catcode`\<=\other
+  \catcode`\>=\other
+  \catcode`\$=\other
+  \catcode`\#=\other
+  \catcode`\&=\other
+  \catcode`\%=\other
+  \catcode`+=\other % avoid \+ for paranoia even though we've turned it off
+  %
+  % This is to support \ in node names and titles, since the \
+  % characters end up in a \csname.  It's easier than
+  % leaving it active and making its active definition an actual \
+  % character.  What I don't understand is why it works in the *value*
+  % of the xrdef.  Seems like it should be a catcode12 \, and that
+  % should not typeset properly.  But it works, so I'm moving on for
+  % now.  --karl, 15jan04.
+  \catcode`\\=\other
+  %
+  % Make the characters 128-255 be printing characters.
+  {\setnonasciicharscatcodenonglobal\other}%
+  %
+  % @ is our escape character in .aux files, and we need braces.
+  \catcode`\{=1
+  \catcode`\}=2
+  \catcode`\@=0
+}
+
+\def\readdatafile#1{%
+\begingroup
+  \setupdatafile
+  \input\jobname.#1
+\endgroup}
+
+
+\message{insertions,}
+% including footnotes.
+
+\newcount \footnoteno
+
+% The trailing space in the following definition for supereject is
+% vital for proper filling; pages come out unaligned when you do a
+% pagealignmacro call if that space before the closing brace is
+% removed. (Generally, numeric constants should always be followed by a
+% space to prevent strange expansion errors.)
+\def\supereject{\par\penalty -20000\footnoteno =0 }
+
+% @footnotestyle is meaningful for Info output only.
+\let\footnotestyle=\comment
+
+{\catcode `\@=11
+%
+% Auto-number footnotes.  Otherwise like plain.
+\gdef\footnote{%
+  \global\advance\footnoteno by \@ne
+  \edef\thisfootno{$^{\the\footnoteno}$}%
+  %
+  % In case the footnote comes at the end of a sentence, preserve the
+  % extra spacing after we do the footnote number.
+  \let\@sf\empty
+  \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi
+  %
+  % Remove inadvertent blank space before typesetting the footnote number.
+  \unskip
+  \thisfootno\@sf
+  \dofootnote
+}%
+
+% Don't bother with the trickery in plain.tex to not require the
+% footnote text as a parameter.  Our footnotes don't need to be so general.
+%
+% Oh yes, they do; otherwise, @ifset (and anything else that uses
+% \parseargline) fails inside footnotes because the tokens are fixed when
+% the footnote is read.  --karl, 16nov96.
+%
+\gdef\dofootnote{%
+  \insert\footins\bgroup
+  %
+  % Nested footnotes are not supported in TeX, that would take a lot
+  % more work.  (\startsavinginserts does not suffice.)
+  \let\footnote=\errfootnotenest
+  %
+  % We want to typeset this text as a normal paragraph, even if the
+  % footnote reference occurs in (for example) a display environment.
+  % So reset some parameters.
+  \hsize=\pagewidth
+  \interlinepenalty\interfootnotelinepenalty
+  \splittopskip\ht\strutbox % top baseline for broken footnotes
+  \splitmaxdepth\dp\strutbox
+  \floatingpenalty\@MM
+  \leftskip\z@skip
+  \rightskip\z@skip
+  \spaceskip\z@skip
+  \xspaceskip\z@skip
+  \parindent\defaultparindent
+  %
+  \smallfonts \rm
+  %
+  % Because we use hanging indentation in footnotes, a @noindent appears
+  % to exdent this text, so make it be a no-op.  makeinfo does not use
+  % hanging indentation so @noindent can still be needed within footnote
+  % text after an @example or the like (not that this is good style).
+  \let\noindent = \relax
+  %
+  % Hang the footnote text off the number.  Use \everypar in case the
+  % footnote extends for more than one paragraph.
+  \everypar = {\hang}%
+  \textindent{\thisfootno}%
+  %
+  % Don't crash into the line above the footnote text.  Since this
+  % expands into a box, it must come within the paragraph, lest it
+  % provide a place where TeX can split the footnote.
+  \footstrut
+  %
+  % Invoke rest of plain TeX footnote routine.
+  \futurelet\next\fo@t
+}
+}%end \catcode `\@=11
+
+\def\errfootnotenest{%
+  \errhelp=\EMsimple
+  \errmessage{Nested footnotes not supported in texinfo.tex,
+    even though they work in makeinfo; sorry}
+}
+
+\def\errfootnoteheading{%
+  \errhelp=\EMsimple
+  \errmessage{Footnotes in chapters, sections, etc., are not supported}
+}
+
+% In case a @footnote appears in a vbox, save the footnote text and create
+% the real \insert just after the vbox finished.  Otherwise, the insertion
+% would be lost.
+% Similarly, if a @footnote appears inside an alignment, save the footnote
+% text to a box and make the \insert when a row of the table is finished.
+% And the same can be done for other insert classes.  --kasal, 16nov03.
+%
+% Replace the \insert primitive by a cheating macro.
+% Deeper inside, just make sure that the saved insertions are not spilled
+% out prematurely.
+%
+\def\startsavinginserts{%
+  \ifx \insert\ptexinsert
+    \let\insert\saveinsert
+  \else
+    \let\checkinserts\relax
+  \fi
+}
+
+% This \insert replacement works for both \insert\footins{foo} and
+% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}.
+%
+\def\saveinsert#1{%
+  \edef\next{\noexpand\savetobox \makeSAVEname#1}%
+  \afterassignment\next
+  % swallow the left brace
+  \let\temp =
+}
+\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}}
+\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1}
+
+\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi}
+
+\def\placesaveins#1{%
+  \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname
+    {\box#1}%
+}
+
+% eat @SAVE -- beware, all of them have catcode \other:
+{
+  \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials  %  ;-)
+  \gdef\gobblesave @SAVE{}
+}
+
+% initialization:
+\def\newsaveins #1{%
+  \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}%
+  \next
+}
+\def\newsaveinsX #1{%
+  \csname newbox\endcsname #1%
+  \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts
+    \checksaveins #1}%
+}
+
+% initialize:
+\let\checkinserts\empty
+\newsaveins\footins
+\newsaveins\margin
+
+
+% @image.  We use the macros from epsf.tex to support this.
+% If epsf.tex is not installed and @image is used, we complain.
+%
+% Check for and read epsf.tex up front.  If we read it only at @image
+% time, we might be inside a group, and then its definitions would get
+% undone and the next image would fail.
+\openin 1 = epsf.tex
+\ifeof 1 \else
+  % Do not bother showing banner with epsf.tex v2.7k (available in
+  % doc/epsf.tex and on ctan).
+  \def\epsfannounce{\toks0 = }%
+  \input epsf.tex
+\fi
+\closein 1
+%
+% We will only complain once about lack of epsf.tex.
+\newif\ifwarnednoepsf
+\newhelp\noepsfhelp{epsf.tex must be installed for images to
+  work.  It is also included in the Texinfo distribution, or you can get
+  it from ftp://tug.org/tex/epsf.tex.}
+%
+\def\image#1{%
+  \ifx\epsfbox\thisisundefined
+    \ifwarnednoepsf \else
+      \errhelp = \noepsfhelp
+      \errmessage{epsf.tex not found, images will be ignored}%
+      \global\warnednoepsftrue
+    \fi
+  \else
+    \imagexxx #1,,,,,\finish
+  \fi
+}
+%
+% Arguments to @image:
+% #1 is (mandatory) image filename; we tack on .eps extension.
+% #2 is (optional) width, #3 is (optional) height.
+% #4 is (ignored optional) html alt text.
+% #5 is (ignored optional) extension.
+% #6 is just the usual extra ignored arg for parsing stuff.
+\newif\ifimagevmode
+\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
+  \catcode`\^^M = 5     % in case we're inside an example
+  \normalturnoffactive  % allow _ et al. in names
+  \def\xprocessmacroarg{\eatspaces}% in case we are being used via a macro
+  % If the image is by itself, center it.
+  \ifvmode
+    \imagevmodetrue
+  \else \ifx\centersub\centerV
+    % for @center @image, we need a vbox so we can have our vertical space
+    \imagevmodetrue
+    \vbox\bgroup % vbox has better behavior than vtop herev
+  \fi\fi
+  %
+  \ifimagevmode
+    \nobreak\medskip
+    % Usually we'll have text after the image which will insert
+    % \parskip glue, so insert it here too to equalize the space
+    % above and below.
+    \nobreak\vskip\parskip
+    \nobreak
+  \fi
+  %
+  % Leave vertical mode so that indentation from an enclosing
+  %  environment such as @quotation is respected.
+  % However, if we're at the top level, we don't want the
+  %  normal paragraph indentation.
+  % On the other hand, if we are in the case of @center @image, we don't
+  %  want to start a paragraph, which will create a hsize-width box and
+  %  eradicate the centering.
+  \ifx\centersub\centerV\else \noindent \fi
+  %
+  % Output the image.
+  \ifpdf
+    \dopdfimage{#1}{#2}{#3}%
+  \else
+    % \epsfbox itself resets \epsf?size at each figure.
+    \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
+    \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
+    \epsfbox{#1.eps}%
+  \fi
+  %
+  \ifimagevmode
+    \medskip  % space after a standalone image
+  \fi
+  \ifx\centersub\centerV \egroup \fi
+\endgroup}
+
+
+% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables,
+% etc.  We don't actually implement floating yet, we always include the
+% float "here".  But it seemed the best name for the future.
+%
+\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish}
+
+% There may be a space before second and/or third parameter; delete it.
+\def\eatcommaspace#1, {#1,}
+
+% #1 is the optional FLOATTYPE, the text label for this float, typically
+% "Figure", "Table", "Example", etc.  Can't contain commas.  If omitted,
+% this float will not be numbered and cannot be referred to.
+%
+% #2 is the optional xref label.  Also must be present for the float to
+% be referable.
+%
+% #3 is the optional positioning argument; for now, it is ignored.  It
+% will somehow specify the positions allowed to float to (here, top, bottom).
+%
+% We keep a separate counter for each FLOATTYPE, which we reset at each
+% chapter-level command.
+\let\resetallfloatnos=\empty
+%
+\def\dofloat#1,#2,#3,#4\finish{%
+  \let\thiscaption=\empty
+  \let\thisshortcaption=\empty
+  %
+  % don't lose footnotes inside @float.
+  %
+  % BEWARE: when the floats start float, we have to issue warning whenever an
+  % insert appears inside a float which could possibly float. --kasal, 26may04
+  %
+  \startsavinginserts
+  %
+  % We can't be used inside a paragraph.
+  \par
+  %
+  \vtop\bgroup
+    \def\floattype{#1}%
+    \def\floatlabel{#2}%
+    \def\floatloc{#3}% we do nothing with this yet.
+    %
+    \ifx\floattype\empty
+      \let\safefloattype=\empty
+    \else
+      {%
+        % the floattype might have accents or other special characters,
+        % but we need to use it in a control sequence name.
+        \indexnofonts
+        \turnoffactive
+        \xdef\safefloattype{\floattype}%
+      }%
+    \fi
+    %
+    % If label is given but no type, we handle that as the empty type.
+    \ifx\floatlabel\empty \else
+      % We want each FLOATTYPE to be numbered separately (Figure 1,
+      % Table 1, Figure 2, ...).  (And if no label, no number.)
+      %
+      \expandafter\getfloatno\csname\safefloattype floatno\endcsname
+      \global\advance\floatno by 1
+      %
+      {%
+        % This magic value for \lastsection is output by \setref as the
+        % XREFLABEL-title value.  \xrefX uses it to distinguish float
+        % labels (which have a completely different output format) from
+        % node and anchor labels.  And \xrdef uses it to construct the
+        % lists of floats.
+        %
+        \edef\lastsection{\floatmagic=\safefloattype}%
+        \setref{\floatlabel}{Yfloat}%
+      }%
+    \fi
+    %
+    % start with \parskip glue, I guess.
+    \vskip\parskip
+    %
+    % Don't suppress indentation if a float happens to start a section.
+    \restorefirstparagraphindent
+}
+
+% we have these possibilities:
+% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap
+% @float Foo,lbl & no caption:    Foo 1.1
+% @float Foo & @caption{Cap}:     Foo: Cap
+% @float Foo & no caption:        Foo
+% @float ,lbl & Caption{Cap}:     1.1: Cap
+% @float ,lbl & no caption:       1.1
+% @float & @caption{Cap}:         Cap
+% @float & no caption:
+%
+\def\Efloat{%
+    \let\floatident = \empty
+    %
+    % In all cases, if we have a float type, it comes first.
+    \ifx\floattype\empty \else \def\floatident{\floattype}\fi
+    %
+    % If we have an xref label, the number comes next.
+    \ifx\floatlabel\empty \else
+      \ifx\floattype\empty \else % if also had float type, need tie first.
+        \appendtomacro\floatident{\tie}%
+      \fi
+      % the number.
+      \appendtomacro\floatident{\chaplevelprefix\the\floatno}%
+    \fi
+    %
+    % Start the printed caption with what we've constructed in
+    % \floatident, but keep it separate; we need \floatident again.
+    \let\captionline = \floatident
+    %
+    \ifx\thiscaption\empty \else
+      \ifx\floatident\empty \else
+	\appendtomacro\captionline{: }% had ident, so need a colon between
+      \fi
+      %
+      % caption text.
+      \appendtomacro\captionline{\scanexp\thiscaption}%
+    \fi
+    %
+    % If we have anything to print, print it, with space before.
+    % Eventually this needs to become an \insert.
+    \ifx\captionline\empty \else
+      \vskip.5\parskip
+      \captionline
+      %
+      % Space below caption.
+      \vskip\parskip
+    \fi
+    %
+    % If have an xref label, write the list of floats info.  Do this
+    % after the caption, to avoid chance of it being a breakpoint.
+    \ifx\floatlabel\empty \else
+      % Write the text that goes in the lof to the aux file as
+      % \floatlabel-lof.  Besides \floatident, we include the short
+      % caption if specified, else the full caption if specified, else nothing.
+      {%
+        \requireauxfile
+        \atdummies
+        %
+        % since we read the caption text in the macro world, where ^^M
+        % is turned into a normal character, we have to scan it back, so
+        % we don't write the literal three characters "^^M" into the aux file.
+	\scanexp{%
+	  \xdef\noexpand\gtemp{%
+	    \ifx\thisshortcaption\empty
+	      \thiscaption
+	    \else
+	      \thisshortcaption
+	    \fi
+	  }%
+	}%
+        \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident
+	  \ifx\gtemp\empty \else : \gtemp \fi}}%
+      }%
+    \fi
+  \egroup  % end of \vtop
+  %
+  % place the captured inserts
+  %
+  % BEWARE: when the floats start floating, we have to issue warning
+  % whenever an insert appears inside a float which could possibly
+  % float. --kasal, 26may04
+  %
+  \checkinserts
+}
+
+% Append the tokens #2 to the definition of macro #1, not expanding either.
+%
+\def\appendtomacro#1#2{%
+  \expandafter\def\expandafter#1\expandafter{#1#2}%
+}
+
+% @caption, @shortcaption
+%
+\def\caption{\docaption\thiscaption}
+\def\shortcaption{\docaption\thisshortcaption}
+\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption}
+\def\defcaption#1#2{\egroup \def#1{#2}}
+
+% The parameter is the control sequence identifying the counter we are
+% going to use.  Create it if it doesn't exist and assign it to \floatno.
+\def\getfloatno#1{%
+  \ifx#1\relax
+      % Haven't seen this figure type before.
+      \csname newcount\endcsname #1%
+      %
+      % Remember to reset this floatno at the next chap.
+      \expandafter\gdef\expandafter\resetallfloatnos
+        \expandafter{\resetallfloatnos #1=0 }%
+  \fi
+  \let\floatno#1%
+}
+
+% \setref calls this to get the XREFLABEL-snt value.  We want an @xref
+% to the FLOATLABEL to expand to "Figure 3.1".  We call \setref when we
+% first read the @float command.
+%
+\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}%
+
+% Magic string used for the XREFLABEL-title value, so \xrefX can
+% distinguish floats from other xref types.
+\def\floatmagic{!!float!!}
+
+% #1 is the control sequence we are passed; we expand into a conditional
+% which is true if #1 represents a float ref.  That is, the magic
+% \lastsection value which we \setref above.
+%
+\def\iffloat#1{\expandafter\doiffloat#1==\finish}
+%
+% #1 is (maybe) the \floatmagic string.  If so, #2 will be the
+% (safe) float type for this float.  We set \iffloattype to #2.
+%
+\def\doiffloat#1=#2=#3\finish{%
+  \def\temp{#1}%
+  \def\iffloattype{#2}%
+  \ifx\temp\floatmagic
+}
+
+% @listoffloats FLOATTYPE - print a list of floats like a table of contents.
+%
+\parseargdef\listoffloats{%
+  \def\floattype{#1}% floattype
+  {%
+    % the floattype might have accents or other special characters,
+    % but we need to use it in a control sequence name.
+    \indexnofonts
+    \turnoffactive
+    \xdef\safefloattype{\floattype}%
+  }%
+  %
+  % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE.
+  \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax
+    \ifhavexrefs
+      % if the user said @listoffloats foo but never @float foo.
+      \message{\linenumber No `\safefloattype' floats to list.}%
+    \fi
+  \else
+    \begingroup
+      \leftskip=\tocindent  % indent these entries like a toc
+      \let\do=\listoffloatsdo
+      \csname floatlist\safefloattype\endcsname
+    \endgroup
+  \fi
+}
+
+% This is called on each entry in a list of floats.  We're passed the
+% xref label, in the form LABEL-title, which is how we save it in the
+% aux file.  We strip off the -title and look up \XRLABEL-lof, which
+% has the text we're supposed to typeset here.
+%
+% Figures without xref labels will not be included in the list (since
+% they won't appear in the aux file).
+%
+\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish}
+\def\listoffloatsdoentry#1-title\finish{{%
+  % Can't fully expand XR#1-lof because it can contain anything.  Just
+  % pass the control sequence.  On the other hand, XR#1-pg is just the
+  % page number, and we want to fully expand that so we can get a link
+  % in pdf output.
+  \toksA = \expandafter{\csname XR#1-lof\endcsname}%
+  %
+  % use the same \entry macro we use to generate the TOC and index.
+  \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}%
+  \writeentry
+}}
+
+
+\message{localization,}
+
+% For single-language documents, @documentlanguage is usually given very
+% early, just after @documentencoding.  Single argument is the language
+% (de) or locale (de_DE) abbreviation.
+%
+{
+  \catcode`\_ = \active
+  \globaldefs=1
+\parseargdef\documentlanguage{%
+  \tex % read txi-??.tex file in plain TeX.
+    % Read the file by the name they passed if it exists.
+    \let_ = \normalunderscore  % normal _ character for filename test
+    \openin 1 txi-#1.tex
+    \ifeof 1
+      \documentlanguagetrywithoutunderscore #1_\finish
+    \else
+      \globaldefs = 1  % everything in the txi-LL files needs to persist
+      \input txi-#1.tex
+    \fi
+    \closein 1
+  \endgroup % end raw TeX
+}
+%
+% If they passed de_DE, and txi-de_DE.tex doesn't exist,
+% try txi-de.tex.
+%
+\gdef\documentlanguagetrywithoutunderscore#1_#2\finish{%
+  \openin 1 txi-#1.tex
+  \ifeof 1
+    \errhelp = \nolanghelp
+    \errmessage{Cannot read language file txi-#1.tex}%
+  \else
+    \globaldefs = 1  % everything in the txi-LL files needs to persist
+    \input txi-#1.tex
+  \fi
+  \closein 1
+}
+}% end of special _ catcode
+%
+\newhelp\nolanghelp{The given language definition file cannot be found or
+is empty.  Maybe you need to install it?  Putting it in the current
+directory should work if nowhere else does.}
+
+% This macro is called from txi-??.tex files; the first argument is the
+% \language name to set (without the "\lang@" prefix), the second and
+% third args are \{left,right}hyphenmin.
+%
+% The language names to pass are determined when the format is built.
+% See the etex.log file created at that time, e.g.,
+% /usr/local/texlive/2008/texmf-var/web2c/pdftex/etex.log.
+%
+% With TeX Live 2008, etex now includes hyphenation patterns for all
+% available languages.  This means we can support hyphenation in
+% Texinfo, at least to some extent.  (This still doesn't solve the
+% accented characters problem.)
+%
+\catcode`@=11
+\def\txisetlanguage#1#2#3{%
+  % do not set the language if the name is undefined in the current TeX.
+  \expandafter\ifx\csname lang@#1\endcsname \relax
+    \message{no patterns for #1}%
+  \else
+    \global\language = \csname lang@#1\endcsname
+  \fi
+  % but there is no harm in adjusting the hyphenmin values regardless.
+  \global\lefthyphenmin = #2\relax
+  \global\righthyphenmin = #3\relax
+}
+
+% Get input by bytes instead of by UTF-8 codepoints for XeTeX and LuaTeX,
+% otherwise the encoding support is completely broken.
+\ifx\XeTeXrevision\thisisundefined
+\else
+\XeTeXinputencoding "bytes"
+\fi
+
+\ifx\luatexversion\thisisundefined
+\else
+\directlua{
+local utf8_char, byte, gsub = unicode.utf8.char, string.byte, string.gsub
+
+local function convert_char (char)
+  return utf8_char(byte(char))
+end
+
+local function convert_line (line)
+  return gsub(line, ".", convert_char)
+end
+
+callback.register("process_input_buffer", convert_line)
+}
+\fi
+
+
+% Helpers for encodings.
+% Set the catcode of characters 128 through 255 to the specified number.
+%
+\def\setnonasciicharscatcode#1{%
+   \count255=128
+   \loop\ifnum\count255<256
+      \global\catcode\count255=#1\relax
+      \advance\count255 by 1
+   \repeat
+}
+
+\def\setnonasciicharscatcodenonglobal#1{%
+   \count255=128
+   \loop\ifnum\count255<256
+      \catcode\count255=#1\relax
+      \advance\count255 by 1
+   \repeat
+}
+
+% @documentencoding sets the definition of non-ASCII characters
+% according to the specified encoding.
+%
+\def\documentencoding{\parseargusing\filenamecatcodes\documentencodingzzz}
+\def\documentencodingzzz#1{%
+  % Encoding being declared for the document.
+  \def\declaredencoding{\csname #1.enc\endcsname}%
+  %
+  % Supported encodings: names converted to tokens in order to be able
+  % to compare them with \ifx.
+  \def\ascii{\csname US-ASCII.enc\endcsname}%
+  \def\latnine{\csname ISO-8859-15.enc\endcsname}%
+  \def\latone{\csname ISO-8859-1.enc\endcsname}%
+  \def\lattwo{\csname ISO-8859-2.enc\endcsname}%
+  \def\utfeight{\csname UTF-8.enc\endcsname}%
+  %
+  \ifx \declaredencoding \ascii
+     \asciichardefs
+  %
+  \else \ifx \declaredencoding \lattwo
+     \setnonasciicharscatcode\active
+     \lattwochardefs
+  %
+  \else \ifx \declaredencoding \latone
+     \setnonasciicharscatcode\active
+     \latonechardefs
+  %
+  \else \ifx \declaredencoding \latnine
+     \setnonasciicharscatcode\active
+     \latninechardefs
+  %
+  \else \ifx \declaredencoding \utfeight
+     \setnonasciicharscatcode\active
+     % since we already invoked \utfeightchardefs at the top level
+     % (below), do not re-invoke it, then our check for duplicated
+     % definitions triggers.  Making non-ascii chars active is enough.
+  %
+  \else
+    \message{Ignoring unknown document encoding: #1.}%
+  %
+  \fi % utfeight
+  \fi % latnine
+  \fi % latone
+  \fi % lattwo
+  \fi % ascii
+}
+
+% emacs-page
+% A message to be logged when using a character that isn't available
+% the default font encoding (OT1).
+%
+\def\missingcharmsg#1{\message{Character missing, sorry: #1.}}
+
+% Take account of \c (plain) vs. \, (Texinfo) difference.
+\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi}
+
+% First, make active non-ASCII characters in order for them to be
+% correctly categorized when TeX reads the replacement text of
+% macros containing the character definitions.
+\setnonasciicharscatcode\active
+%
+% Latin1 (ISO-8859-1) character definitions.
+\def\latonechardefs{%
+  \gdef^^a0{\tie}
+  \gdef^^a1{\exclamdown}
+  \gdef^^a2{{\tcfont \char162}} % cent
+  \gdef^^a3{\pounds}
+  \gdef^^a4{{\tcfont \char164}} % currency
+  \gdef^^a5{{\tcfont \char165}} % yen
+  \gdef^^a6{{\tcfont \char166}} % broken bar
+  \gdef^^a7{\S}
+  \gdef^^a8{\"{}}
+  \gdef^^a9{\copyright}
+  \gdef^^aa{\ordf}
+  \gdef^^ab{\guillemetleft}
+  \gdef^^ac{\ensuremath\lnot}
+  \gdef^^ad{\-}
+  \gdef^^ae{\registeredsymbol}
+  \gdef^^af{\={}}
+  %
+  \gdef^^b0{\textdegree}
+  \gdef^^b1{$\pm$}
+  \gdef^^b2{$^2$}
+  \gdef^^b3{$^3$}
+  \gdef^^b4{\'{}}
+  \gdef^^b5{$\mu$}
+  \gdef^^b6{\P}
+  \gdef^^b7{\ensuremath\cdot}
+  \gdef^^b8{\cedilla\ }
+  \gdef^^b9{$^1$}
+  \gdef^^ba{\ordm}
+  \gdef^^bb{\guillemetright}
+  \gdef^^bc{$1\over4$}
+  \gdef^^bd{$1\over2$}
+  \gdef^^be{$3\over4$}
+  \gdef^^bf{\questiondown}
+  %
+  \gdef^^c0{\`A}
+  \gdef^^c1{\'A}
+  \gdef^^c2{\^A}
+  \gdef^^c3{\~A}
+  \gdef^^c4{\"A}
+  \gdef^^c5{\ringaccent A}
+  \gdef^^c6{\AE}
+  \gdef^^c7{\cedilla C}
+  \gdef^^c8{\`E}
+  \gdef^^c9{\'E}
+  \gdef^^ca{\^E}
+  \gdef^^cb{\"E}
+  \gdef^^cc{\`I}
+  \gdef^^cd{\'I}
+  \gdef^^ce{\^I}
+  \gdef^^cf{\"I}
+  %
+  \gdef^^d0{\DH}
+  \gdef^^d1{\~N}
+  \gdef^^d2{\`O}
+  \gdef^^d3{\'O}
+  \gdef^^d4{\^O}
+  \gdef^^d5{\~O}
+  \gdef^^d6{\"O}
+  \gdef^^d7{$\times$}
+  \gdef^^d8{\O}
+  \gdef^^d9{\`U}
+  \gdef^^da{\'U}
+  \gdef^^db{\^U}
+  \gdef^^dc{\"U}
+  \gdef^^dd{\'Y}
+  \gdef^^de{\TH}
+  \gdef^^df{\ss}
+  %
+  \gdef^^e0{\`a}
+  \gdef^^e1{\'a}
+  \gdef^^e2{\^a}
+  \gdef^^e3{\~a}
+  \gdef^^e4{\"a}
+  \gdef^^e5{\ringaccent a}
+  \gdef^^e6{\ae}
+  \gdef^^e7{\cedilla c}
+  \gdef^^e8{\`e}
+  \gdef^^e9{\'e}
+  \gdef^^ea{\^e}
+  \gdef^^eb{\"e}
+  \gdef^^ec{\`{\dotless i}}
+  \gdef^^ed{\'{\dotless i}}
+  \gdef^^ee{\^{\dotless i}}
+  \gdef^^ef{\"{\dotless i}}
+  %
+  \gdef^^f0{\dh}
+  \gdef^^f1{\~n}
+  \gdef^^f2{\`o}
+  \gdef^^f3{\'o}
+  \gdef^^f4{\^o}
+  \gdef^^f5{\~o}
+  \gdef^^f6{\"o}
+  \gdef^^f7{$\div$}
+  \gdef^^f8{\o}
+  \gdef^^f9{\`u}
+  \gdef^^fa{\'u}
+  \gdef^^fb{\^u}
+  \gdef^^fc{\"u}
+  \gdef^^fd{\'y}
+  \gdef^^fe{\th}
+  \gdef^^ff{\"y}
+}
+
+% Latin9 (ISO-8859-15) encoding character definitions.
+\def\latninechardefs{%
+  % Encoding is almost identical to Latin1.
+  \latonechardefs
+  %
+  \gdef^^a4{\euro}
+  \gdef^^a6{\v S}
+  \gdef^^a8{\v s}
+  \gdef^^b4{\v Z}
+  \gdef^^b8{\v z}
+  \gdef^^bc{\OE}
+  \gdef^^bd{\oe}
+  \gdef^^be{\"Y}
+}
+
+% Latin2 (ISO-8859-2) character definitions.
+\def\lattwochardefs{%
+  \gdef^^a0{\tie}
+  \gdef^^a1{\ogonek{A}}
+  \gdef^^a2{\u{}}
+  \gdef^^a3{\L}
+  \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
+  \gdef^^a5{\v L}
+  \gdef^^a6{\'S}
+  \gdef^^a7{\S}
+  \gdef^^a8{\"{}}
+  \gdef^^a9{\v S}
+  \gdef^^aa{\cedilla S}
+  \gdef^^ab{\v T}
+  \gdef^^ac{\'Z}
+  \gdef^^ad{\-}
+  \gdef^^ae{\v Z}
+  \gdef^^af{\dotaccent Z}
+  %
+  \gdef^^b0{\textdegree}
+  \gdef^^b1{\ogonek{a}}
+  \gdef^^b2{\ogonek{ }}
+  \gdef^^b3{\l}
+  \gdef^^b4{\'{}}
+  \gdef^^b5{\v l}
+  \gdef^^b6{\'s}
+  \gdef^^b7{\v{}}
+  \gdef^^b8{\cedilla\ }
+  \gdef^^b9{\v s}
+  \gdef^^ba{\cedilla s}
+  \gdef^^bb{\v t}
+  \gdef^^bc{\'z}
+  \gdef^^bd{\H{}}
+  \gdef^^be{\v z}
+  \gdef^^bf{\dotaccent z}
+  %
+  \gdef^^c0{\'R}
+  \gdef^^c1{\'A}
+  \gdef^^c2{\^A}
+  \gdef^^c3{\u A}
+  \gdef^^c4{\"A}
+  \gdef^^c5{\'L}
+  \gdef^^c6{\'C}
+  \gdef^^c7{\cedilla C}
+  \gdef^^c8{\v C}
+  \gdef^^c9{\'E}
+  \gdef^^ca{\ogonek{E}}
+  \gdef^^cb{\"E}
+  \gdef^^cc{\v E}
+  \gdef^^cd{\'I}
+  \gdef^^ce{\^I}
+  \gdef^^cf{\v D}
+  %
+  \gdef^^d0{\DH}
+  \gdef^^d1{\'N}
+  \gdef^^d2{\v N}
+  \gdef^^d3{\'O}
+  \gdef^^d4{\^O}
+  \gdef^^d5{\H O}
+  \gdef^^d6{\"O}
+  \gdef^^d7{$\times$}
+  \gdef^^d8{\v R}
+  \gdef^^d9{\ringaccent U}
+  \gdef^^da{\'U}
+  \gdef^^db{\H U}
+  \gdef^^dc{\"U}
+  \gdef^^dd{\'Y}
+  \gdef^^de{\cedilla T}
+  \gdef^^df{\ss}
+  %
+  \gdef^^e0{\'r}
+  \gdef^^e1{\'a}
+  \gdef^^e2{\^a}
+  \gdef^^e3{\u a}
+  \gdef^^e4{\"a}
+  \gdef^^e5{\'l}
+  \gdef^^e6{\'c}
+  \gdef^^e7{\cedilla c}
+  \gdef^^e8{\v c}
+  \gdef^^e9{\'e}
+  \gdef^^ea{\ogonek{e}}
+  \gdef^^eb{\"e}
+  \gdef^^ec{\v e}
+  \gdef^^ed{\'{\dotless{i}}}
+  \gdef^^ee{\^{\dotless{i}}}
+  \gdef^^ef{\v d}
+  %
+  \gdef^^f0{\dh}
+  \gdef^^f1{\'n}
+  \gdef^^f2{\v n}
+  \gdef^^f3{\'o}
+  \gdef^^f4{\^o}
+  \gdef^^f5{\H o}
+  \gdef^^f6{\"o}
+  \gdef^^f7{$\div$}
+  \gdef^^f8{\v r}
+  \gdef^^f9{\ringaccent u}
+  \gdef^^fa{\'u}
+  \gdef^^fb{\H u}
+  \gdef^^fc{\"u}
+  \gdef^^fd{\'y}
+  \gdef^^fe{\cedilla t}
+  \gdef^^ff{\dotaccent{}}
+}
+
+% UTF-8 character definitions.
+%
+% This code to support UTF-8 is based on LaTeX's utf8.def, with some
+% changes for Texinfo conventions.  It is included here under the GPL by
+% permission from Frank Mittelbach and the LaTeX team.
+%
+\newcount\countUTFx
+\newcount\countUTFy
+\newcount\countUTFz
+
+\gdef\UTFviiiTwoOctets#1#2{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\endcsname}
+%
+\gdef\UTFviiiThreeOctets#1#2#3{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname}
+%
+\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname}
+
+\gdef\UTFviiiDefined#1{%
+  \ifx #1\relax
+    \message{\linenumber Unicode char \string #1 not defined for Texinfo}%
+  \else
+    \expandafter #1%
+  \fi
+}
+
+\begingroup
+  \catcode`\~13
+  \catcode`\"12
+
+  \def\UTFviiiLoop{%
+    \global\catcode\countUTFx\active
+    \uccode`\~\countUTFx
+    \uppercase\expandafter{\UTFviiiTmp}%
+    \advance\countUTFx by 1
+    \ifnum\countUTFx < \countUTFy
+      \expandafter\UTFviiiLoop
+    \fi}
+
+  \countUTFx = "C2
+  \countUTFy = "E0
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiTwoOctets\string~}}
+  \UTFviiiLoop
+
+  \countUTFx = "E0
+  \countUTFy = "F0
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiThreeOctets\string~}}
+  \UTFviiiLoop
+
+  \countUTFx = "F0
+  \countUTFy = "F4
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiFourOctets\string~}}
+  \UTFviiiLoop
+\endgroup
+
+\def\globallet{\global\let} % save some \expandafter's below
+
+% @U{xxxx} to produce U+xxxx, if we support it.
+\def\U#1{%
+  \expandafter\ifx\csname uni:#1\endcsname \relax
+    \errhelp = \EMsimple
+    \errmessage{Unicode character U+#1 not supported, sorry}%
+  \else
+    \csname uni:#1\endcsname
+  \fi
+}
+
+\begingroup
+  \catcode`\"=12
+  \catcode`\<=12
+  \catcode`\.=12
+  \catcode`\,=12
+  \catcode`\;=12
+  \catcode`\!=12
+  \catcode`\~=13
+  \gdef\DeclareUnicodeCharacter#1#2{%
+    \countUTFz = "#1\relax
+    %\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}%
+    \begingroup
+      \parseXMLCharref
+      \def\UTFviiiTwoOctets##1##2{%
+        \csname u8:##1\string ##2\endcsname}%
+      \def\UTFviiiThreeOctets##1##2##3{%
+        \csname u8:##1\string ##2\string ##3\endcsname}%
+      \def\UTFviiiFourOctets##1##2##3##4{%
+        \csname u8:##1\string ##2\string ##3\string ##4\endcsname}%
+      \expandafter\expandafter\expandafter\expandafter
+       \expandafter\expandafter\expandafter
+       \gdef\UTFviiiTmp{#2}%
+      %
+      \expandafter\ifx\csname uni:#1\endcsname \relax \else
+       \message{Internal error, already defined: #1}%
+      \fi
+      %
+      % define an additional control sequence for this code point.
+      \expandafter\globallet\csname uni:#1\endcsname \UTFviiiTmp
+    \endgroup}
+
+  \gdef\parseXMLCharref{%
+    \ifnum\countUTFz < "A0\relax
+      \errhelp = \EMsimple
+      \errmessage{Cannot define Unicode char value < 00A0}%
+    \else\ifnum\countUTFz < "800\relax
+      \parseUTFviiiA,%
+      \parseUTFviiiB C\UTFviiiTwoOctets.,%
+    \else\ifnum\countUTFz < "10000\relax
+      \parseUTFviiiA;%
+      \parseUTFviiiA,%
+      \parseUTFviiiB E\UTFviiiThreeOctets.{,;}%
+    \else
+      \parseUTFviiiA;%
+      \parseUTFviiiA,%
+      \parseUTFviiiA!%
+      \parseUTFviiiB F\UTFviiiFourOctets.{!,;}%
+    \fi\fi\fi
+  }
+
+  \gdef\parseUTFviiiA#1{%
+    \countUTFx = \countUTFz
+    \divide\countUTFz by 64
+    \countUTFy = \countUTFz
+    \multiply\countUTFz by 64
+    \advance\countUTFx by -\countUTFz
+    \advance\countUTFx by 128
+    \uccode `#1\countUTFx
+    \countUTFz = \countUTFy}
+
+  \gdef\parseUTFviiiB#1#2#3#4{%
+    \advance\countUTFz by "#10\relax
+    \uccode `#3\countUTFz
+    \uppercase{\gdef\UTFviiiTmp{#2#3#4}}}
+\endgroup
+
+% https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_M
+% U+0000..U+007F = https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)
+% U+0080..U+00FF = https://en.wikipedia.org/wiki/Latin-1_Supplement_(Unicode_block)
+% U+0100..U+017F = https://en.wikipedia.org/wiki/Latin_Extended-A
+% U+0180..U+024F = https://en.wikipedia.org/wiki/Latin_Extended-B
+%
+% Many of our renditions are less than wonderful, and all the missing
+% characters are available somewhere.  Loading the necessary fonts
+% awaits user request.  We can't truly support Unicode without
+% reimplementing everything that's been done in LaTeX for many years,
+% plus probably using luatex or xetex, and who knows what else.
+% We won't be doing that here in this simple file.  But we can try to at
+% least make most of the characters not bomb out.
+%
+\def\utfeightchardefs{%
+  \DeclareUnicodeCharacter{00A0}{\tie}
+  \DeclareUnicodeCharacter{00A1}{\exclamdown}
+  \DeclareUnicodeCharacter{00A2}{{\tcfont \char162}}% 0242=cent
+  \DeclareUnicodeCharacter{00A3}{\pounds}
+  \DeclareUnicodeCharacter{00A4}{{\tcfont \char164}}% 0244=currency
+  \DeclareUnicodeCharacter{00A5}{{\tcfont \char165}}% 0245=yen
+  \DeclareUnicodeCharacter{00A6}{{\tcfont \char166}}% 0246=brokenbar
+  \DeclareUnicodeCharacter{00A7}{\S}
+  \DeclareUnicodeCharacter{00A8}{\"{ }}
+  \DeclareUnicodeCharacter{00A9}{\copyright}
+  \DeclareUnicodeCharacter{00AA}{\ordf}
+  \DeclareUnicodeCharacter{00AB}{\guillemetleft}
+  \DeclareUnicodeCharacter{00AC}{\ensuremath\lnot}
+  \DeclareUnicodeCharacter{00AD}{\-}
+  \DeclareUnicodeCharacter{00AE}{\registeredsymbol}
+  \DeclareUnicodeCharacter{00AF}{\={ }}
+
+  \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}
+  \DeclareUnicodeCharacter{00B1}{\ensuremath\pm}
+  \DeclareUnicodeCharacter{00B2}{$^2$}
+  \DeclareUnicodeCharacter{00B3}{$^3$}
+  \DeclareUnicodeCharacter{00B4}{\'{ }}
+  \DeclareUnicodeCharacter{00B5}{$\mu$}
+  \DeclareUnicodeCharacter{00B6}{\P}
+  \DeclareUnicodeCharacter{00B7}{\ensuremath\cdot}
+  \DeclareUnicodeCharacter{00B8}{\cedilla{ }}
+  \DeclareUnicodeCharacter{00B9}{$^1$}
+  \DeclareUnicodeCharacter{00BA}{\ordm}
+  \DeclareUnicodeCharacter{00BB}{\guillemetright}
+  \DeclareUnicodeCharacter{00BC}{$1\over4$}
+  \DeclareUnicodeCharacter{00BD}{$1\over2$}
+  \DeclareUnicodeCharacter{00BE}{$3\over4$}
+  \DeclareUnicodeCharacter{00BF}{\questiondown}
+
+  \DeclareUnicodeCharacter{00C0}{\`A}
+  \DeclareUnicodeCharacter{00C1}{\'A}
+  \DeclareUnicodeCharacter{00C2}{\^A}
+  \DeclareUnicodeCharacter{00C3}{\~A}
+  \DeclareUnicodeCharacter{00C4}{\"A}
+  \DeclareUnicodeCharacter{00C5}{\AA}
+  \DeclareUnicodeCharacter{00C6}{\AE}
+  \DeclareUnicodeCharacter{00C7}{\cedilla{C}}
+  \DeclareUnicodeCharacter{00C8}{\`E}
+  \DeclareUnicodeCharacter{00C9}{\'E}
+  \DeclareUnicodeCharacter{00CA}{\^E}
+  \DeclareUnicodeCharacter{00CB}{\"E}
+  \DeclareUnicodeCharacter{00CC}{\`I}
+  \DeclareUnicodeCharacter{00CD}{\'I}
+  \DeclareUnicodeCharacter{00CE}{\^I}
+  \DeclareUnicodeCharacter{00CF}{\"I}
+
+  \DeclareUnicodeCharacter{00D0}{\DH}
+  \DeclareUnicodeCharacter{00D1}{\~N}
+  \DeclareUnicodeCharacter{00D2}{\`O}
+  \DeclareUnicodeCharacter{00D3}{\'O}
+  \DeclareUnicodeCharacter{00D4}{\^O}
+  \DeclareUnicodeCharacter{00D5}{\~O}
+  \DeclareUnicodeCharacter{00D6}{\"O}
+  \DeclareUnicodeCharacter{00D7}{\ensuremath\times}
+  \DeclareUnicodeCharacter{00D8}{\O}
+  \DeclareUnicodeCharacter{00D9}{\`U}
+  \DeclareUnicodeCharacter{00DA}{\'U}
+  \DeclareUnicodeCharacter{00DB}{\^U}
+  \DeclareUnicodeCharacter{00DC}{\"U}
+  \DeclareUnicodeCharacter{00DD}{\'Y}
+  \DeclareUnicodeCharacter{00DE}{\TH}
+  \DeclareUnicodeCharacter{00DF}{\ss}
+
+  \DeclareUnicodeCharacter{00E0}{\`a}
+  \DeclareUnicodeCharacter{00E1}{\'a}
+  \DeclareUnicodeCharacter{00E2}{\^a}
+  \DeclareUnicodeCharacter{00E3}{\~a}
+  \DeclareUnicodeCharacter{00E4}{\"a}
+  \DeclareUnicodeCharacter{00E5}{\aa}
+  \DeclareUnicodeCharacter{00E6}{\ae}
+  \DeclareUnicodeCharacter{00E7}{\cedilla{c}}
+  \DeclareUnicodeCharacter{00E8}{\`e}
+  \DeclareUnicodeCharacter{00E9}{\'e}
+  \DeclareUnicodeCharacter{00EA}{\^e}
+  \DeclareUnicodeCharacter{00EB}{\"e}
+  \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}}
+  \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}}
+  \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
+  \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
+
+  \DeclareUnicodeCharacter{00F0}{\dh}
+  \DeclareUnicodeCharacter{00F1}{\~n}
+  \DeclareUnicodeCharacter{00F2}{\`o}
+  \DeclareUnicodeCharacter{00F3}{\'o}
+  \DeclareUnicodeCharacter{00F4}{\^o}
+  \DeclareUnicodeCharacter{00F5}{\~o}
+  \DeclareUnicodeCharacter{00F6}{\"o}
+  \DeclareUnicodeCharacter{00F7}{\ensuremath\div}
+  \DeclareUnicodeCharacter{00F8}{\o}
+  \DeclareUnicodeCharacter{00F9}{\`u}
+  \DeclareUnicodeCharacter{00FA}{\'u}
+  \DeclareUnicodeCharacter{00FB}{\^u}
+  \DeclareUnicodeCharacter{00FC}{\"u}
+  \DeclareUnicodeCharacter{00FD}{\'y}
+  \DeclareUnicodeCharacter{00FE}{\th}
+  \DeclareUnicodeCharacter{00FF}{\"y}
+
+  \DeclareUnicodeCharacter{0100}{\=A}
+  \DeclareUnicodeCharacter{0101}{\=a}
+  \DeclareUnicodeCharacter{0102}{\u{A}}
+  \DeclareUnicodeCharacter{0103}{\u{a}}
+  \DeclareUnicodeCharacter{0104}{\ogonek{A}}
+  \DeclareUnicodeCharacter{0105}{\ogonek{a}}
+  \DeclareUnicodeCharacter{0106}{\'C}
+  \DeclareUnicodeCharacter{0107}{\'c}
+  \DeclareUnicodeCharacter{0108}{\^C}
+  \DeclareUnicodeCharacter{0109}{\^c}
+  \DeclareUnicodeCharacter{010A}{\dotaccent{C}}
+  \DeclareUnicodeCharacter{010B}{\dotaccent{c}}
+  \DeclareUnicodeCharacter{010C}{\v{C}}
+  \DeclareUnicodeCharacter{010D}{\v{c}}
+  \DeclareUnicodeCharacter{010E}{\v{D}}
+  \DeclareUnicodeCharacter{010F}{d'}
+
+  \DeclareUnicodeCharacter{0110}{\DH}
+  \DeclareUnicodeCharacter{0111}{\dh}
+  \DeclareUnicodeCharacter{0112}{\=E}
+  \DeclareUnicodeCharacter{0113}{\=e}
+  \DeclareUnicodeCharacter{0114}{\u{E}}
+  \DeclareUnicodeCharacter{0115}{\u{e}}
+  \DeclareUnicodeCharacter{0116}{\dotaccent{E}}
+  \DeclareUnicodeCharacter{0117}{\dotaccent{e}}
+  \DeclareUnicodeCharacter{0118}{\ogonek{E}}
+  \DeclareUnicodeCharacter{0119}{\ogonek{e}}
+  \DeclareUnicodeCharacter{011A}{\v{E}}
+  \DeclareUnicodeCharacter{011B}{\v{e}}
+  \DeclareUnicodeCharacter{011C}{\^G}
+  \DeclareUnicodeCharacter{011D}{\^g}
+  \DeclareUnicodeCharacter{011E}{\u{G}}
+  \DeclareUnicodeCharacter{011F}{\u{g}}
+
+  \DeclareUnicodeCharacter{0120}{\dotaccent{G}}
+  \DeclareUnicodeCharacter{0121}{\dotaccent{g}}
+  \DeclareUnicodeCharacter{0122}{\cedilla{G}}
+  \DeclareUnicodeCharacter{0123}{\cedilla{g}}
+  \DeclareUnicodeCharacter{0124}{\^H}
+  \DeclareUnicodeCharacter{0125}{\^h}
+  \DeclareUnicodeCharacter{0126}{\missingcharmsg{H WITH STROKE}}
+  \DeclareUnicodeCharacter{0127}{\missingcharmsg{h WITH STROKE}}
+  \DeclareUnicodeCharacter{0128}{\~I}
+  \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}
+  \DeclareUnicodeCharacter{012A}{\=I}
+  \DeclareUnicodeCharacter{012B}{\={\dotless{i}}}
+  \DeclareUnicodeCharacter{012C}{\u{I}}
+  \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}
+  \DeclareUnicodeCharacter{012E}{\ogonek{I}}
+  \DeclareUnicodeCharacter{012F}{\ogonek{i}}
+
+  \DeclareUnicodeCharacter{0130}{\dotaccent{I}}
+  \DeclareUnicodeCharacter{0131}{\dotless{i}}
+  \DeclareUnicodeCharacter{0132}{IJ}
+  \DeclareUnicodeCharacter{0133}{ij}
+  \DeclareUnicodeCharacter{0134}{\^J}
+  \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}
+  \DeclareUnicodeCharacter{0136}{\cedilla{K}}
+  \DeclareUnicodeCharacter{0137}{\cedilla{k}}
+  \DeclareUnicodeCharacter{0138}{\ensuremath\kappa}
+  \DeclareUnicodeCharacter{0139}{\'L}
+  \DeclareUnicodeCharacter{013A}{\'l}
+  \DeclareUnicodeCharacter{013B}{\cedilla{L}}
+  \DeclareUnicodeCharacter{013C}{\cedilla{l}}
+  \DeclareUnicodeCharacter{013D}{L'}% should kern
+  \DeclareUnicodeCharacter{013E}{l'}% should kern
+  \DeclareUnicodeCharacter{013F}{L\U{00B7}}
+
+  \DeclareUnicodeCharacter{0140}{l\U{00B7}}
+  \DeclareUnicodeCharacter{0141}{\L}
+  \DeclareUnicodeCharacter{0142}{\l}
+  \DeclareUnicodeCharacter{0143}{\'N}
+  \DeclareUnicodeCharacter{0144}{\'n}
+  \DeclareUnicodeCharacter{0145}{\cedilla{N}}
+  \DeclareUnicodeCharacter{0146}{\cedilla{n}}
+  \DeclareUnicodeCharacter{0147}{\v{N}}
+  \DeclareUnicodeCharacter{0148}{\v{n}}
+  \DeclareUnicodeCharacter{0149}{'n}
+  \DeclareUnicodeCharacter{014A}{\missingcharmsg{ENG}}
+  \DeclareUnicodeCharacter{014B}{\missingcharmsg{eng}}
+  \DeclareUnicodeCharacter{014C}{\=O}
+  \DeclareUnicodeCharacter{014D}{\=o}
+  \DeclareUnicodeCharacter{014E}{\u{O}}
+  \DeclareUnicodeCharacter{014F}{\u{o}}
+
+  \DeclareUnicodeCharacter{0150}{\H{O}}
+  \DeclareUnicodeCharacter{0151}{\H{o}}
+  \DeclareUnicodeCharacter{0152}{\OE}
+  \DeclareUnicodeCharacter{0153}{\oe}
+  \DeclareUnicodeCharacter{0154}{\'R}
+  \DeclareUnicodeCharacter{0155}{\'r}
+  \DeclareUnicodeCharacter{0156}{\cedilla{R}}
+  \DeclareUnicodeCharacter{0157}{\cedilla{r}}
+  \DeclareUnicodeCharacter{0158}{\v{R}}
+  \DeclareUnicodeCharacter{0159}{\v{r}}
+  \DeclareUnicodeCharacter{015A}{\'S}
+  \DeclareUnicodeCharacter{015B}{\'s}
+  \DeclareUnicodeCharacter{015C}{\^S}
+  \DeclareUnicodeCharacter{015D}{\^s}
+  \DeclareUnicodeCharacter{015E}{\cedilla{S}}
+  \DeclareUnicodeCharacter{015F}{\cedilla{s}}
+
+  \DeclareUnicodeCharacter{0160}{\v{S}}
+  \DeclareUnicodeCharacter{0161}{\v{s}}
+  \DeclareUnicodeCharacter{0162}{\cedilla{T}}
+  \DeclareUnicodeCharacter{0163}{\cedilla{t}}
+  \DeclareUnicodeCharacter{0164}{\v{T}}
+  \DeclareUnicodeCharacter{0165}{\v{t}}
+  \DeclareUnicodeCharacter{0166}{\missingcharmsg{H WITH STROKE}}
+  \DeclareUnicodeCharacter{0167}{\missingcharmsg{h WITH STROKE}}
+  \DeclareUnicodeCharacter{0168}{\~U}
+  \DeclareUnicodeCharacter{0169}{\~u}
+  \DeclareUnicodeCharacter{016A}{\=U}
+  \DeclareUnicodeCharacter{016B}{\=u}
+  \DeclareUnicodeCharacter{016C}{\u{U}}
+  \DeclareUnicodeCharacter{016D}{\u{u}}
+  \DeclareUnicodeCharacter{016E}{\ringaccent{U}}
+  \DeclareUnicodeCharacter{016F}{\ringaccent{u}}
+
+  \DeclareUnicodeCharacter{0170}{\H{U}}
+  \DeclareUnicodeCharacter{0171}{\H{u}}
+  \DeclareUnicodeCharacter{0172}{\ogonek{U}}
+  \DeclareUnicodeCharacter{0173}{\ogonek{u}}
+  \DeclareUnicodeCharacter{0174}{\^W}
+  \DeclareUnicodeCharacter{0175}{\^w}
+  \DeclareUnicodeCharacter{0176}{\^Y}
+  \DeclareUnicodeCharacter{0177}{\^y}
+  \DeclareUnicodeCharacter{0178}{\"Y}
+  \DeclareUnicodeCharacter{0179}{\'Z}
+  \DeclareUnicodeCharacter{017A}{\'z}
+  \DeclareUnicodeCharacter{017B}{\dotaccent{Z}}
+  \DeclareUnicodeCharacter{017C}{\dotaccent{z}}
+  \DeclareUnicodeCharacter{017D}{\v{Z}}
+  \DeclareUnicodeCharacter{017E}{\v{z}}
+  \DeclareUnicodeCharacter{017F}{\missingcharmsg{LONG S}}
+
+  \DeclareUnicodeCharacter{01C4}{D\v{Z}}
+  \DeclareUnicodeCharacter{01C5}{D\v{z}}
+  \DeclareUnicodeCharacter{01C6}{d\v{z}}
+  \DeclareUnicodeCharacter{01C7}{LJ}
+  \DeclareUnicodeCharacter{01C8}{Lj}
+  \DeclareUnicodeCharacter{01C9}{lj}
+  \DeclareUnicodeCharacter{01CA}{NJ}
+  \DeclareUnicodeCharacter{01CB}{Nj}
+  \DeclareUnicodeCharacter{01CC}{nj}
+  \DeclareUnicodeCharacter{01CD}{\v{A}}
+  \DeclareUnicodeCharacter{01CE}{\v{a}}
+  \DeclareUnicodeCharacter{01CF}{\v{I}}
+
+  \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}}
+  \DeclareUnicodeCharacter{01D1}{\v{O}}
+  \DeclareUnicodeCharacter{01D2}{\v{o}}
+  \DeclareUnicodeCharacter{01D3}{\v{U}}
+  \DeclareUnicodeCharacter{01D4}{\v{u}}
+
+  \DeclareUnicodeCharacter{01E2}{\={\AE}}
+  \DeclareUnicodeCharacter{01E3}{\={\ae}}
+  \DeclareUnicodeCharacter{01E6}{\v{G}}
+  \DeclareUnicodeCharacter{01E7}{\v{g}}
+  \DeclareUnicodeCharacter{01E8}{\v{K}}
+  \DeclareUnicodeCharacter{01E9}{\v{k}}
+
+  \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}}
+  \DeclareUnicodeCharacter{01F1}{DZ}
+  \DeclareUnicodeCharacter{01F2}{Dz}
+  \DeclareUnicodeCharacter{01F3}{dz}
+  \DeclareUnicodeCharacter{01F4}{\'G}
+  \DeclareUnicodeCharacter{01F5}{\'g}
+  \DeclareUnicodeCharacter{01F8}{\`N}
+  \DeclareUnicodeCharacter{01F9}{\`n}
+  \DeclareUnicodeCharacter{01FC}{\'{\AE}}
+  \DeclareUnicodeCharacter{01FD}{\'{\ae}}
+  \DeclareUnicodeCharacter{01FE}{\'{\O}}
+  \DeclareUnicodeCharacter{01FF}{\'{\o}}
+
+  \DeclareUnicodeCharacter{021E}{\v{H}}
+  \DeclareUnicodeCharacter{021F}{\v{h}}
+
+  \DeclareUnicodeCharacter{0226}{\dotaccent{A}}
+  \DeclareUnicodeCharacter{0227}{\dotaccent{a}}
+  \DeclareUnicodeCharacter{0228}{\cedilla{E}}
+  \DeclareUnicodeCharacter{0229}{\cedilla{e}}
+  \DeclareUnicodeCharacter{022E}{\dotaccent{O}}
+  \DeclareUnicodeCharacter{022F}{\dotaccent{o}}
+
+  \DeclareUnicodeCharacter{0232}{\=Y}
+  \DeclareUnicodeCharacter{0233}{\=y}
+  \DeclareUnicodeCharacter{0237}{\dotless{j}}
+
+  \DeclareUnicodeCharacter{02DB}{\ogonek{ }}
+
+  % Greek letters upper case
+  \DeclareUnicodeCharacter{0391}{{\it A}}
+  \DeclareUnicodeCharacter{0392}{{\it B}}
+  \DeclareUnicodeCharacter{0393}{\ensuremath{\mit\Gamma}}
+  \DeclareUnicodeCharacter{0394}{\ensuremath{\mit\Delta}}
+  \DeclareUnicodeCharacter{0395}{{\it E}}
+  \DeclareUnicodeCharacter{0396}{{\it Z}}
+  \DeclareUnicodeCharacter{0397}{{\it H}}
+  \DeclareUnicodeCharacter{0398}{\ensuremath{\mit\Theta}}
+  \DeclareUnicodeCharacter{0399}{{\it I}}
+  \DeclareUnicodeCharacter{039A}{{\it K}}
+  \DeclareUnicodeCharacter{039B}{\ensuremath{\mit\Lambda}}
+  \DeclareUnicodeCharacter{039C}{{\it M}}
+  \DeclareUnicodeCharacter{039D}{{\it N}}
+  \DeclareUnicodeCharacter{039E}{\ensuremath{\mit\Xi}}
+  \DeclareUnicodeCharacter{039F}{{\it O}}
+  \DeclareUnicodeCharacter{03A0}{\ensuremath{\mit\Pi}}
+  \DeclareUnicodeCharacter{03A1}{{\it P}}
+  %\DeclareUnicodeCharacter{03A2}{} % none - corresponds to final sigma
+  \DeclareUnicodeCharacter{03A3}{\ensuremath{\mit\Sigma}}
+  \DeclareUnicodeCharacter{03A4}{{\it T}}
+  \DeclareUnicodeCharacter{03A5}{\ensuremath{\mit\Upsilon}}
+  \DeclareUnicodeCharacter{03A6}{\ensuremath{\mit\Phi}}
+  \DeclareUnicodeCharacter{03A7}{{\it X}}
+  \DeclareUnicodeCharacter{03A8}{\ensuremath{\mit\Psi}}
+  \DeclareUnicodeCharacter{03A9}{\ensuremath{\mit\Omega}}
+
+  % Vowels with accents
+  \DeclareUnicodeCharacter{0390}{\ensuremath{\ddot{\acute\iota}}}
+  \DeclareUnicodeCharacter{03AC}{\ensuremath{\acute\alpha}}
+  \DeclareUnicodeCharacter{03AD}{\ensuremath{\acute\epsilon}}
+  \DeclareUnicodeCharacter{03AE}{\ensuremath{\acute\eta}}
+  \DeclareUnicodeCharacter{03AF}{\ensuremath{\acute\iota}}
+  \DeclareUnicodeCharacter{03B0}{\ensuremath{\acute{\ddot\upsilon}}}
+
+  % Standalone accent
+  \DeclareUnicodeCharacter{0384}{\ensuremath{\acute{\ }}}
+
+  % Greek letters lower case
+  \DeclareUnicodeCharacter{03B1}{\ensuremath\alpha}
+  \DeclareUnicodeCharacter{03B2}{\ensuremath\beta}
+  \DeclareUnicodeCharacter{03B3}{\ensuremath\gamma}
+  \DeclareUnicodeCharacter{03B4}{\ensuremath\delta}
+  \DeclareUnicodeCharacter{03B5}{\ensuremath\epsilon}
+  \DeclareUnicodeCharacter{03B6}{\ensuremath\zeta}
+  \DeclareUnicodeCharacter{03B7}{\ensuremath\eta}
+  \DeclareUnicodeCharacter{03B8}{\ensuremath\theta}
+  \DeclareUnicodeCharacter{03B9}{\ensuremath\iota}
+  \DeclareUnicodeCharacter{03BA}{\ensuremath\kappa}
+  \DeclareUnicodeCharacter{03BB}{\ensuremath\lambda}
+  \DeclareUnicodeCharacter{03BC}{\ensuremath\mu}
+  \DeclareUnicodeCharacter{03BD}{\ensuremath\nu}
+  \DeclareUnicodeCharacter{03BE}{\ensuremath\xi}
+  \DeclareUnicodeCharacter{03BF}{{\it o}} % omicron
+  \DeclareUnicodeCharacter{03C0}{\ensuremath\pi}
+  \DeclareUnicodeCharacter{03C1}{\ensuremath\rho}
+  \DeclareUnicodeCharacter{03C2}{\ensuremath\varsigma}
+  \DeclareUnicodeCharacter{03C3}{\ensuremath\sigma}
+  \DeclareUnicodeCharacter{03C4}{\ensuremath\tau}
+  \DeclareUnicodeCharacter{03C5}{\ensuremath\upsilon}
+  \DeclareUnicodeCharacter{03C6}{\ensuremath\phi}
+  \DeclareUnicodeCharacter{03C7}{\ensuremath\chi}
+  \DeclareUnicodeCharacter{03C8}{\ensuremath\psi}
+  \DeclareUnicodeCharacter{03C9}{\ensuremath\omega}
+
+  % More Greek vowels with accents
+  \DeclareUnicodeCharacter{03CA}{\ensuremath{\ddot\iota}}
+  \DeclareUnicodeCharacter{03CB}{\ensuremath{\ddot\upsilon}}
+  \DeclareUnicodeCharacter{03CC}{\ensuremath{\acute o}}
+  \DeclareUnicodeCharacter{03CD}{\ensuremath{\acute\upsilon}}
+  \DeclareUnicodeCharacter{03CE}{\ensuremath{\acute\omega}}
+
+  % Variant Greek letters
+  \DeclareUnicodeCharacter{03D1}{\ensuremath\vartheta}
+  \DeclareUnicodeCharacter{03D6}{\ensuremath\varpi}
+  \DeclareUnicodeCharacter{03F1}{\ensuremath\varrho}
+
+  \DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
+  \DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
+  \DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
+  \DeclareUnicodeCharacter{1E05}{\udotaccent{b}}
+  \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}}
+  \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}}
+  \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}}
+  \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}}
+  \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}}
+  \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}}
+  \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}}
+  \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}}
+
+  \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}}
+  \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}}
+
+  \DeclareUnicodeCharacter{1E20}{\=G}
+  \DeclareUnicodeCharacter{1E21}{\=g}
+  \DeclareUnicodeCharacter{1E22}{\dotaccent{H}}
+  \DeclareUnicodeCharacter{1E23}{\dotaccent{h}}
+  \DeclareUnicodeCharacter{1E24}{\udotaccent{H}}
+  \DeclareUnicodeCharacter{1E25}{\udotaccent{h}}
+  \DeclareUnicodeCharacter{1E26}{\"H}
+  \DeclareUnicodeCharacter{1E27}{\"h}
+
+  \DeclareUnicodeCharacter{1E30}{\'K}
+  \DeclareUnicodeCharacter{1E31}{\'k}
+  \DeclareUnicodeCharacter{1E32}{\udotaccent{K}}
+  \DeclareUnicodeCharacter{1E33}{\udotaccent{k}}
+  \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}}
+  \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}}
+  \DeclareUnicodeCharacter{1E36}{\udotaccent{L}}
+  \DeclareUnicodeCharacter{1E37}{\udotaccent{l}}
+  \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}}
+  \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}}
+  \DeclareUnicodeCharacter{1E3E}{\'M}
+  \DeclareUnicodeCharacter{1E3F}{\'m}
+
+  \DeclareUnicodeCharacter{1E40}{\dotaccent{M}}
+  \DeclareUnicodeCharacter{1E41}{\dotaccent{m}}
+  \DeclareUnicodeCharacter{1E42}{\udotaccent{M}}
+  \DeclareUnicodeCharacter{1E43}{\udotaccent{m}}
+  \DeclareUnicodeCharacter{1E44}{\dotaccent{N}}
+  \DeclareUnicodeCharacter{1E45}{\dotaccent{n}}
+  \DeclareUnicodeCharacter{1E46}{\udotaccent{N}}
+  \DeclareUnicodeCharacter{1E47}{\udotaccent{n}}
+  \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}}
+  \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}}
+
+  \DeclareUnicodeCharacter{1E54}{\'P}
+  \DeclareUnicodeCharacter{1E55}{\'p}
+  \DeclareUnicodeCharacter{1E56}{\dotaccent{P}}
+  \DeclareUnicodeCharacter{1E57}{\dotaccent{p}}
+  \DeclareUnicodeCharacter{1E58}{\dotaccent{R}}
+  \DeclareUnicodeCharacter{1E59}{\dotaccent{r}}
+  \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}}
+  \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}}
+  \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}}
+  \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}}
+
+  \DeclareUnicodeCharacter{1E60}{\dotaccent{S}}
+  \DeclareUnicodeCharacter{1E61}{\dotaccent{s}}
+  \DeclareUnicodeCharacter{1E62}{\udotaccent{S}}
+  \DeclareUnicodeCharacter{1E63}{\udotaccent{s}}
+  \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}}
+  \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}}
+  \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}}
+  \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}}
+  \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}}
+  \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}}
+
+  \DeclareUnicodeCharacter{1E7C}{\~V}
+  \DeclareUnicodeCharacter{1E7D}{\~v}
+  \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}}
+  \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}}
+
+  \DeclareUnicodeCharacter{1E80}{\`W}
+  \DeclareUnicodeCharacter{1E81}{\`w}
+  \DeclareUnicodeCharacter{1E82}{\'W}
+  \DeclareUnicodeCharacter{1E83}{\'w}
+  \DeclareUnicodeCharacter{1E84}{\"W}
+  \DeclareUnicodeCharacter{1E85}{\"w}
+  \DeclareUnicodeCharacter{1E86}{\dotaccent{W}}
+  \DeclareUnicodeCharacter{1E87}{\dotaccent{w}}
+  \DeclareUnicodeCharacter{1E88}{\udotaccent{W}}
+  \DeclareUnicodeCharacter{1E89}{\udotaccent{w}}
+  \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}}
+  \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}}
+  \DeclareUnicodeCharacter{1E8C}{\"X}
+  \DeclareUnicodeCharacter{1E8D}{\"x}
+  \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}}
+  \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}}
+
+  \DeclareUnicodeCharacter{1E90}{\^Z}
+  \DeclareUnicodeCharacter{1E91}{\^z}
+  \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}}
+  \DeclareUnicodeCharacter{1E93}{\udotaccent{z}}
+  \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}}
+  \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}}
+  \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}}
+  \DeclareUnicodeCharacter{1E97}{\"t}
+  \DeclareUnicodeCharacter{1E98}{\ringaccent{w}}
+  \DeclareUnicodeCharacter{1E99}{\ringaccent{y}}
+
+  \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}}
+  \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}}
+
+  \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}}
+  \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}}
+  \DeclareUnicodeCharacter{1EBC}{\~E}
+  \DeclareUnicodeCharacter{1EBD}{\~e}
+
+  \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}}
+  \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}}
+  \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}}
+  \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}}
+
+  \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}}
+  \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}}
+
+  \DeclareUnicodeCharacter{1EF2}{\`Y}
+  \DeclareUnicodeCharacter{1EF3}{\`y}
+  \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}}
+
+  \DeclareUnicodeCharacter{1EF8}{\~Y}
+  \DeclareUnicodeCharacter{1EF9}{\~y}
+
+  % Punctuation
+  \DeclareUnicodeCharacter{2013}{--}
+  \DeclareUnicodeCharacter{2014}{---}
+  \DeclareUnicodeCharacter{2018}{\quoteleft}
+  \DeclareUnicodeCharacter{2019}{\quoteright}
+  \DeclareUnicodeCharacter{201A}{\quotesinglbase}
+  \DeclareUnicodeCharacter{201C}{\quotedblleft}
+  \DeclareUnicodeCharacter{201D}{\quotedblright}
+  \DeclareUnicodeCharacter{201E}{\quotedblbase}
+  \DeclareUnicodeCharacter{2020}{\ensuremath\dagger}
+  \DeclareUnicodeCharacter{2021}{\ensuremath\ddagger}
+  \DeclareUnicodeCharacter{2022}{\bullet}
+  \DeclareUnicodeCharacter{202F}{\thinspace}
+  \DeclareUnicodeCharacter{2026}{\dots}
+  \DeclareUnicodeCharacter{2039}{\guilsinglleft}
+  \DeclareUnicodeCharacter{203A}{\guilsinglright}
+
+  \DeclareUnicodeCharacter{20AC}{\euro}
+
+  \DeclareUnicodeCharacter{2192}{\expansion}
+  \DeclareUnicodeCharacter{21D2}{\result}
+
+  % Mathematical symbols
+  \DeclareUnicodeCharacter{2200}{\ensuremath\forall}
+  \DeclareUnicodeCharacter{2203}{\ensuremath\exists}
+  \DeclareUnicodeCharacter{2208}{\ensuremath\in}
+  \DeclareUnicodeCharacter{2212}{\minus}
+  \DeclareUnicodeCharacter{2217}{\ast}
+  \DeclareUnicodeCharacter{221E}{\ensuremath\infty}
+  \DeclareUnicodeCharacter{2225}{\ensuremath\parallel}
+  \DeclareUnicodeCharacter{2227}{\ensuremath\wedge}
+  \DeclareUnicodeCharacter{2229}{\ensuremath\cap}
+  \DeclareUnicodeCharacter{2261}{\equiv}
+  \DeclareUnicodeCharacter{2264}{\ensuremath\leq}
+  \DeclareUnicodeCharacter{2265}{\ensuremath\geq}
+  \DeclareUnicodeCharacter{2282}{\ensuremath\subset}
+  \DeclareUnicodeCharacter{2287}{\ensuremath\supseteq}
+
+  \DeclareUnicodeCharacter{2016}{\ensuremath\Vert}
+  \DeclareUnicodeCharacter{2032}{\ensuremath\prime}
+  \DeclareUnicodeCharacter{210F}{\ensuremath\hbar}
+  \DeclareUnicodeCharacter{2111}{\ensuremath\Im}
+  \DeclareUnicodeCharacter{2113}{\ensuremath\ell}
+  \DeclareUnicodeCharacter{2118}{\ensuremath\wp}
+  \DeclareUnicodeCharacter{211C}{\ensuremath\Re}
+  \DeclareUnicodeCharacter{2127}{\ensuremath\mho}
+  \DeclareUnicodeCharacter{2135}{\ensuremath\aleph}
+  \DeclareUnicodeCharacter{2190}{\ensuremath\leftarrow}
+  \DeclareUnicodeCharacter{2191}{\ensuremath\uparrow}
+  \DeclareUnicodeCharacter{2193}{\ensuremath\downarrow}
+  \DeclareUnicodeCharacter{2194}{\ensuremath\leftrightarrow}
+  \DeclareUnicodeCharacter{2195}{\ensuremath\updownarrow}
+  \DeclareUnicodeCharacter{2196}{\ensuremath\nwarrow}
+  \DeclareUnicodeCharacter{2197}{\ensuremath\nearrow}
+  \DeclareUnicodeCharacter{2198}{\ensuremath\searrow}
+  \DeclareUnicodeCharacter{2199}{\ensuremath\swarrow}
+  \DeclareUnicodeCharacter{21A6}{\ensuremath\mapsto}
+  \DeclareUnicodeCharacter{21A9}{\ensuremath\hookleftarrow}
+  \DeclareUnicodeCharacter{21AA}{\ensuremath\hookrightarrow}
+  \DeclareUnicodeCharacter{21BC}{\ensuremath\leftharpoonup}
+  \DeclareUnicodeCharacter{21BD}{\ensuremath\leftharpoondown}
+  \DeclareUnicodeCharacter{21BE}{\ensuremath\upharpoonright}
+  \DeclareUnicodeCharacter{21C0}{\ensuremath\rightharpoonup}
+  \DeclareUnicodeCharacter{21C1}{\ensuremath\rightharpoondown}
+  \DeclareUnicodeCharacter{21CC}{\ensuremath\rightleftharpoons}
+  \DeclareUnicodeCharacter{21D0}{\ensuremath\Leftarrow}
+  \DeclareUnicodeCharacter{21D1}{\ensuremath\Uparrow}
+  \DeclareUnicodeCharacter{21D3}{\ensuremath\Downarrow}
+  \DeclareUnicodeCharacter{21D4}{\ensuremath\Leftrightarrow}
+  \DeclareUnicodeCharacter{21D5}{\ensuremath\Updownarrow}
+  \DeclareUnicodeCharacter{21DD}{\ensuremath\leadsto}
+  \DeclareUnicodeCharacter{2201}{\ensuremath\complement}
+  \DeclareUnicodeCharacter{2202}{\ensuremath\partial}
+  \DeclareUnicodeCharacter{2205}{\ensuremath\emptyset}
+  \DeclareUnicodeCharacter{2207}{\ensuremath\nabla}
+  \DeclareUnicodeCharacter{2209}{\ensuremath\notin}
+  \DeclareUnicodeCharacter{220B}{\ensuremath\owns}
+  \DeclareUnicodeCharacter{220F}{\ensuremath\prod}
+  \DeclareUnicodeCharacter{2210}{\ensuremath\coprod}
+  \DeclareUnicodeCharacter{2211}{\ensuremath\sum}
+  \DeclareUnicodeCharacter{2213}{\ensuremath\mp}
+  \DeclareUnicodeCharacter{2218}{\ensuremath\circ}
+  \DeclareUnicodeCharacter{221A}{\ensuremath\surd}
+  \DeclareUnicodeCharacter{221D}{\ensuremath\propto}
+  \DeclareUnicodeCharacter{2220}{\ensuremath\angle}
+  \DeclareUnicodeCharacter{2223}{\ensuremath\mid}
+  \DeclareUnicodeCharacter{2228}{\ensuremath\vee}
+  \DeclareUnicodeCharacter{222A}{\ensuremath\cup}
+  \DeclareUnicodeCharacter{222B}{\ensuremath\smallint}
+  \DeclareUnicodeCharacter{222E}{\ensuremath\oint}
+  \DeclareUnicodeCharacter{223C}{\ensuremath\sim}
+  \DeclareUnicodeCharacter{2240}{\ensuremath\wr}
+  \DeclareUnicodeCharacter{2243}{\ensuremath\simeq}
+  \DeclareUnicodeCharacter{2245}{\ensuremath\cong}
+  \DeclareUnicodeCharacter{2248}{\ensuremath\approx}
+  \DeclareUnicodeCharacter{224D}{\ensuremath\asymp}
+  \DeclareUnicodeCharacter{2250}{\ensuremath\doteq}
+  \DeclareUnicodeCharacter{2260}{\ensuremath\neq}
+  \DeclareUnicodeCharacter{226A}{\ensuremath\ll}
+  \DeclareUnicodeCharacter{226B}{\ensuremath\gg}
+  \DeclareUnicodeCharacter{227A}{\ensuremath\prec}
+  \DeclareUnicodeCharacter{227B}{\ensuremath\succ}
+  \DeclareUnicodeCharacter{2283}{\ensuremath\supset}
+  \DeclareUnicodeCharacter{2286}{\ensuremath\subseteq}
+  \DeclareUnicodeCharacter{228E}{\ensuremath\uplus}
+  \DeclareUnicodeCharacter{228F}{\ensuremath\sqsubset}
+  \DeclareUnicodeCharacter{2290}{\ensuremath\sqsupset}
+  \DeclareUnicodeCharacter{2291}{\ensuremath\sqsubseteq}
+  \DeclareUnicodeCharacter{2292}{\ensuremath\sqsupseteq}
+  \DeclareUnicodeCharacter{2293}{\ensuremath\sqcap}
+  \DeclareUnicodeCharacter{2294}{\ensuremath\sqcup}
+  \DeclareUnicodeCharacter{2295}{\ensuremath\oplus}
+  \DeclareUnicodeCharacter{2296}{\ensuremath\ominus}
+  \DeclareUnicodeCharacter{2297}{\ensuremath\otimes}
+  \DeclareUnicodeCharacter{2298}{\ensuremath\oslash}
+  \DeclareUnicodeCharacter{2299}{\ensuremath\odot}
+  \DeclareUnicodeCharacter{22A2}{\ensuremath\vdash}
+  \DeclareUnicodeCharacter{22A3}{\ensuremath\dashv}
+  \DeclareUnicodeCharacter{22A4}{\ensuremath\ptextop}
+  \DeclareUnicodeCharacter{22A5}{\ensuremath\bot}
+  \DeclareUnicodeCharacter{22A8}{\ensuremath\models}
+  \DeclareUnicodeCharacter{22B4}{\ensuremath\unlhd}
+  \DeclareUnicodeCharacter{22B5}{\ensuremath\unrhd}
+  \DeclareUnicodeCharacter{22C0}{\ensuremath\bigwedge}
+  \DeclareUnicodeCharacter{22C1}{\ensuremath\bigvee}
+  \DeclareUnicodeCharacter{22C2}{\ensuremath\bigcap}
+  \DeclareUnicodeCharacter{22C3}{\ensuremath\bigcup}
+  \DeclareUnicodeCharacter{22C4}{\ensuremath\diamond}
+  \DeclareUnicodeCharacter{22C5}{\ensuremath\cdot}
+  \DeclareUnicodeCharacter{22C6}{\ensuremath\star}
+  \DeclareUnicodeCharacter{22C8}{\ensuremath\bowtie}
+  \DeclareUnicodeCharacter{2308}{\ensuremath\lceil}
+  \DeclareUnicodeCharacter{2309}{\ensuremath\rceil}
+  \DeclareUnicodeCharacter{230A}{\ensuremath\lfloor}
+  \DeclareUnicodeCharacter{230B}{\ensuremath\rfloor}
+  \DeclareUnicodeCharacter{2322}{\ensuremath\frown}
+  \DeclareUnicodeCharacter{2323}{\ensuremath\smile}
+
+  \DeclareUnicodeCharacter{25A1}{\ensuremath\Box}
+  \DeclareUnicodeCharacter{25B3}{\ensuremath\triangle}
+  \DeclareUnicodeCharacter{25B7}{\ensuremath\triangleright}
+  \DeclareUnicodeCharacter{25BD}{\ensuremath\bigtriangledown}
+  \DeclareUnicodeCharacter{25C1}{\ensuremath\triangleleft}
+  \DeclareUnicodeCharacter{25C7}{\ensuremath\Diamond}
+  \DeclareUnicodeCharacter{2660}{\ensuremath\spadesuit}
+  \DeclareUnicodeCharacter{2661}{\ensuremath\heartsuit}
+  \DeclareUnicodeCharacter{2662}{\ensuremath\diamondsuit}
+  \DeclareUnicodeCharacter{2663}{\ensuremath\clubsuit}
+  \DeclareUnicodeCharacter{266D}{\ensuremath\flat}
+  \DeclareUnicodeCharacter{266E}{\ensuremath\natural}
+  \DeclareUnicodeCharacter{266F}{\ensuremath\sharp}
+  \DeclareUnicodeCharacter{26AA}{\ensuremath\bigcirc}
+  \DeclareUnicodeCharacter{27B9}{\ensuremath\rangle}
+  \DeclareUnicodeCharacter{27C2}{\ensuremath\perp}
+  \DeclareUnicodeCharacter{27E8}{\ensuremath\langle}
+  \DeclareUnicodeCharacter{27F5}{\ensuremath\longleftarrow}
+  \DeclareUnicodeCharacter{27F6}{\ensuremath\longrightarrow}
+  \DeclareUnicodeCharacter{27F7}{\ensuremath\longleftrightarrow}
+  \DeclareUnicodeCharacter{27FC}{\ensuremath\longmapsto}
+  \DeclareUnicodeCharacter{29F5}{\ensuremath\setminus}
+  \DeclareUnicodeCharacter{2A00}{\ensuremath\bigodot}
+  \DeclareUnicodeCharacter{2A01}{\ensuremath\bigoplus}
+  \DeclareUnicodeCharacter{2A02}{\ensuremath\bigotimes}
+  \DeclareUnicodeCharacter{2A04}{\ensuremath\biguplus}
+  \DeclareUnicodeCharacter{2A06}{\ensuremath\bigsqcup}
+  \DeclareUnicodeCharacter{2A1D}{\ensuremath\Join}
+  \DeclareUnicodeCharacter{2A3F}{\ensuremath\amalg}
+  \DeclareUnicodeCharacter{2AAF}{\ensuremath\preceq}
+  \DeclareUnicodeCharacter{2AB0}{\ensuremath\succeq}
+
+  \global\mathchardef\checkmark="1370 % actually the square root sign
+  \DeclareUnicodeCharacter{2713}{\ensuremath\checkmark}
+}% end of \utfeightchardefs
+
+% US-ASCII character definitions.
+\def\asciichardefs{% nothing need be done
+   \relax
+}
+
+% Latin1 (ISO-8859-1) character definitions.
+\def\nonasciistringdefs{%
+  \setnonasciicharscatcode\active
+  \def\defstringchar##1{\def##1{\string##1}}%
+  %
+  \defstringchar^^80\defstringchar^^81\defstringchar^^82\defstringchar^^83%
+  \defstringchar^^84\defstringchar^^85\defstringchar^^86\defstringchar^^87%
+  \defstringchar^^88\defstringchar^^89\defstringchar^^8a\defstringchar^^8b%
+  \defstringchar^^8c\defstringchar^^8d\defstringchar^^8e\defstringchar^^8f%
+  %
+  \defstringchar^^90\defstringchar^^91\defstringchar^^92\defstringchar^^93%
+  \defstringchar^^94\defstringchar^^95\defstringchar^^96\defstringchar^^97%
+  \defstringchar^^98\defstringchar^^99\defstringchar^^9a\defstringchar^^9b%
+  \defstringchar^^9c\defstringchar^^9d\defstringchar^^9e\defstringchar^^9f%
+  %
+  \defstringchar^^a0\defstringchar^^a1\defstringchar^^a2\defstringchar^^a3%
+  \defstringchar^^a4\defstringchar^^a5\defstringchar^^a6\defstringchar^^a7%
+  \defstringchar^^a8\defstringchar^^a9\defstringchar^^aa\defstringchar^^ab%
+  \defstringchar^^ac\defstringchar^^ad\defstringchar^^ae\defstringchar^^af%
+  %
+  \defstringchar^^b0\defstringchar^^b1\defstringchar^^b2\defstringchar^^b3%
+  \defstringchar^^b4\defstringchar^^b5\defstringchar^^b6\defstringchar^^b7%
+  \defstringchar^^b8\defstringchar^^b9\defstringchar^^ba\defstringchar^^bb%
+  \defstringchar^^bc\defstringchar^^bd\defstringchar^^be\defstringchar^^bf%
+  %
+  \defstringchar^^c0\defstringchar^^c1\defstringchar^^c2\defstringchar^^c3%
+  \defstringchar^^c4\defstringchar^^c5\defstringchar^^c6\defstringchar^^c7%
+  \defstringchar^^c8\defstringchar^^c9\defstringchar^^ca\defstringchar^^cb%
+  \defstringchar^^cc\defstringchar^^cd\defstringchar^^ce\defstringchar^^cf%
+  %
+  \defstringchar^^d0\defstringchar^^d1\defstringchar^^d2\defstringchar^^d3%
+  \defstringchar^^d4\defstringchar^^d5\defstringchar^^d6\defstringchar^^d7%
+  \defstringchar^^d8\defstringchar^^d9\defstringchar^^da\defstringchar^^db%
+  \defstringchar^^dc\defstringchar^^dd\defstringchar^^de\defstringchar^^df%
+  %
+  \defstringchar^^e0\defstringchar^^e1\defstringchar^^e2\defstringchar^^e3%
+  \defstringchar^^e4\defstringchar^^e5\defstringchar^^e6\defstringchar^^e7%
+  \defstringchar^^e8\defstringchar^^e9\defstringchar^^ea\defstringchar^^eb%
+  \defstringchar^^ec\defstringchar^^ed\defstringchar^^ee\defstringchar^^ef%
+  %
+  \defstringchar^^f0\defstringchar^^f1\defstringchar^^f2\defstringchar^^f3%
+  \defstringchar^^f4\defstringchar^^f5\defstringchar^^f6\defstringchar^^f7%
+  \defstringchar^^f8\defstringchar^^f9\defstringchar^^fa\defstringchar^^fb%
+  \defstringchar^^fc\defstringchar^^fd\defstringchar^^fe\defstringchar^^ff%
+}
+
+
+% define all the unicode characters we know about, for the sake of @U.
+\utfeightchardefs
+
+
+% Make non-ASCII characters printable again for compatibility with
+% existing Texinfo documents that may use them, even without declaring a
+% document encoding.
+%
+\setnonasciicharscatcode \other
+
+
+\message{formatting,}
+
+\newdimen\defaultparindent \defaultparindent = 15pt
+
+\chapheadingskip = 15pt plus 4pt minus 2pt
+\secheadingskip = 12pt plus 3pt minus 2pt
+\subsecheadingskip = 9pt plus 2pt minus 2pt
+
+% Prevent underfull vbox error messages.
+\vbadness = 10000
+
+% Don't be very finicky about underfull hboxes, either.
+\hbadness = 6666
+
+% Following George Bush, get rid of widows and orphans.
+\widowpenalty=10000
+\clubpenalty=10000
+
+% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
+% using an old version of TeX, don't do anything.  We want the amount of
+% stretch added to depend on the line length, hence the dependence on
+% \hsize.  We call this whenever the paper size is set.
+%
+\def\setemergencystretch{%
+  \ifx\emergencystretch\thisisundefined
+    % Allow us to assign to \emergencystretch anyway.
+    \def\emergencystretch{\dimen0}%
+  \else
+    \emergencystretch = .15\hsize
+  \fi
+}
+
+% Parameters in order: 1) textheight; 2) textwidth;
+% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip;
+% 7) physical page height; 8) physical page width.
+%
+% We also call \setleading{\textleading}, so the caller should define
+% \textleading.  The caller should also set \parskip.
+%
+\def\internalpagesizes#1#2#3#4#5#6#7#8{%
+  \voffset = #3\relax
+  \topskip = #6\relax
+  \splittopskip = \topskip
+  %
+  \vsize = #1\relax
+  \advance\vsize by \topskip
+  \outervsize = \vsize
+  \advance\outervsize by 2\topandbottommargin
+  \pageheight = \vsize
+  %
+  \hsize = #2\relax
+  \outerhsize = \hsize
+  \advance\outerhsize by 0.5in
+  \pagewidth = \hsize
+  %
+  \normaloffset = #4\relax
+  \bindingoffset = #5\relax
+  %
+  \ifpdf
+    \pdfpageheight #7\relax
+    \pdfpagewidth #8\relax
+    % if we don't reset these, they will remain at "1 true in" of
+    % whatever layout pdftex was dumped with.
+    \pdfhorigin = 1 true in
+    \pdfvorigin = 1 true in
+  \fi
+  %
+  \setleading{\textleading}
+  %
+  \parindent = \defaultparindent
+  \setemergencystretch
+}
+
+% @letterpaper (the default).
+\def\letterpaper{{\globaldefs = 1
+  \parskip = 3pt plus 2pt minus 1pt
+  \textleading = 13.2pt
+  %
+  % If page is nothing but text, make it come out even.
+  \internalpagesizes{607.2pt}{6in}% that's 46 lines
+                    {\voffset}{.25in}%
+                    {\bindingoffset}{36pt}%
+                    {11in}{8.5in}%
+}}
+
+% Use @smallbook to reset parameters for 7x9.25 trim size.
+\def\smallbook{{\globaldefs = 1
+  \parskip = 2pt plus 1pt
+  \textleading = 12pt
+  %
+  \internalpagesizes{7.5in}{5in}%
+                    {-.2in}{0in}%
+                    {\bindingoffset}{16pt}%
+                    {9.25in}{7in}%
+  %
+  \lispnarrowing = 0.3in
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = .5cm
+}}
+
+% Use @smallerbook to reset parameters for 6x9 trim size.
+% (Just testing, parameters still in flux.)
+\def\smallerbook{{\globaldefs = 1
+  \parskip = 1.5pt plus 1pt
+  \textleading = 12pt
+  %
+  \internalpagesizes{7.4in}{4.8in}%
+                    {-.2in}{-.4in}%
+                    {0pt}{14pt}%
+                    {9in}{6in}%
+  %
+  \lispnarrowing = 0.25in
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = .4cm
+}}
+
+% Use @afourpaper to print on European A4 paper.
+\def\afourpaper{{\globaldefs = 1
+  \parskip = 3pt plus 2pt minus 1pt
+  \textleading = 13.2pt
+  %
+  % Double-side printing via postscript on Laserjet 4050
+  % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm.
+  % To change the settings for a different printer or situation, adjust
+  % \normaloffset until the front-side and back-side texts align.  Then
+  % do the same for \bindingoffset.  You can set these for testing in
+  % your texinfo source file like this:
+  % @tex
+  % \global\normaloffset = -6mm
+  % \global\bindingoffset = 10mm
+  % @end tex
+  \internalpagesizes{673.2pt}{160mm}% that's 51 lines
+                    {\voffset}{\hoffset}%
+                    {\bindingoffset}{44pt}%
+                    {297mm}{210mm}%
+  %
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = 5mm
+}}
+
+% Use @afivepaper to print on European A5 paper.
+% From romildo@urano.iceb.ufop.br, 2 July 2000.
+% He also recommends making @example and @lisp be small.
+\def\afivepaper{{\globaldefs = 1
+  \parskip = 2pt plus 1pt minus 0.1pt
+  \textleading = 12.5pt
+  %
+  \internalpagesizes{160mm}{120mm}%
+                    {\voffset}{\hoffset}%
+                    {\bindingoffset}{8pt}%
+                    {210mm}{148mm}%
+  %
+  \lispnarrowing = 0.2in
+  \tolerance = 800
+  \hfuzz = 1.2pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = 2mm
+  \tableindent = 12mm
+}}
+
+% A specific text layout, 24x15cm overall, intended for A4 paper.
+\def\afourlatex{{\globaldefs = 1
+  \afourpaper
+  \internalpagesizes{237mm}{150mm}%
+                    {\voffset}{4.6mm}%
+                    {\bindingoffset}{7mm}%
+                    {297mm}{210mm}%
+  %
+  % Must explicitly reset to 0 because we call \afourpaper.
+  \globaldefs = 0
+}}
+
+% Use @afourwide to print on A4 paper in landscape format.
+\def\afourwide{{\globaldefs = 1
+  \afourpaper
+  \internalpagesizes{241mm}{165mm}%
+                    {\voffset}{-2.95mm}%
+                    {\bindingoffset}{7mm}%
+                    {297mm}{210mm}%
+  \globaldefs = 0
+}}
+
+% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
+% Perhaps we should allow setting the margins, \topskip, \parskip,
+% and/or leading, also. Or perhaps we should compute them somehow.
+%
+\parseargdef\pagesizes{\pagesizesyyy #1,,\finish}
+\def\pagesizesyyy#1,#2,#3\finish{{%
+  \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
+  \globaldefs = 1
+  %
+  \parskip = 3pt plus 2pt minus 1pt
+  \setleading{\textleading}%
+  %
+  \dimen0 = #1\relax
+  \advance\dimen0 by \voffset
+  %
+  \dimen2 = \hsize
+  \advance\dimen2 by \normaloffset
+  %
+  \internalpagesizes{#1}{\hsize}%
+                    {\voffset}{\normaloffset}%
+                    {\bindingoffset}{44pt}%
+                    {\dimen0}{\dimen2}%
+}}
+
+% Set default to letter.
+%
+\letterpaper
+
+
+\message{and turning on texinfo input format.}
+
+\def^^L{\par} % remove \outer, so ^L can appear in an @comment
+
+% DEL is a comment character, in case @c does not suffice.
+\catcode`\^^? = 14
+
+% Define macros to output various characters with catcode for normal text.
+\catcode`\"=\other \def\normaldoublequote{"}
+\catcode`\$=\other \def\normaldollar{$}%$ font-lock fix
+\catcode`\+=\other \def\normalplus{+}
+\catcode`\<=\other \def\normalless{<}
+\catcode`\>=\other \def\normalgreater{>}
+\catcode`\^=\other \def\normalcaret{^}
+\catcode`\_=\other \def\normalunderscore{_}
+\catcode`\|=\other \def\normalverticalbar{|}
+\catcode`\~=\other \def\normaltilde{~}
+
+% This macro is used to make a character print one way in \tt
+% (where it can probably be output as-is), and another way in other fonts,
+% where something hairier probably needs to be done.
+%
+% #1 is what to print if we are indeed using \tt; #2 is what to print
+% otherwise.  Since all the Computer Modern typewriter fonts have zero
+% interword stretch (and shrink), and it is reasonable to expect all
+% typewriter fonts to have this, we can check that font parameter.
+%
+\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
+
+% Same as above, but check for italic font.  Actually this also catches
+% non-italic slanted fonts since it is impossible to distinguish them from
+% italic fonts.  But since this is only used by $ and it uses \sl anyway
+% this is not a problem.
+\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
+
+% Set catcodes for Texinfo file
+
+% Active characters for printing the wanted glyph.
+% Most of these we simply print from the \tt font, but for some, we can
+% use math or other variants that look better in normal text.
+%
+\catcode`\"=\active
+\def\activedoublequote{{\tt\char34}}
+\let"=\activedoublequote
+\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde
+\chardef\hatchar=`\^
+\catcode`\^=\active \def\activehat{{\tt \hatchar}} \let^ = \activehat
+
+\catcode`\_=\active
+\def_{\ifusingtt\normalunderscore\_}
+\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }
+\let\realunder=_
+
+\catcode`\|=\active \def|{{\tt\char124}}
+
+\chardef \less=`\<
+\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless
+\chardef \gtr=`\>
+\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr
+\catcode`\+=\active \def+{{\tt \char 43}}
+\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
+\catcode`\-=\active \let-=\normaldash
+
+
+% used for headline/footline in the output routine, in case the page
+% breaks in the middle of an @tex block.
+\def\texinfochars{%
+  \let< = \activeless
+  \let> = \activegtr
+  \let~ = \activetilde
+  \let^ = \activehat
+  \markupsetuplqdefault \markupsetuprqdefault
+  \let\b = \strong
+  \let\i = \smartitalic
+  % in principle, all other definitions in \tex have to be undone too.
+}
+
+% Used sometimes to turn off (effectively) the active characters even after
+% parsing them.
+\def\turnoffactive{%
+  \normalturnoffactive
+  \otherbackslash
+}
+
+\catcode`\@=0
+
+% \backslashcurfont outputs one backslash character in current font,
+% as in \char`\\.
+\global\chardef\backslashcurfont=`\\
+\global\let\rawbackslashxx=\backslashcurfont  % let existing .??s files work
+
+% \realbackslash is an actual character `\' with catcode other, and
+% \doublebackslash is two of them (for the pdf outlines).
+{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}}
+
+% In Texinfo, backslash is an active character; it prints the backslash
+% in fixed width font.
+\catcode`\\=\active  % @ for escape char from now on.
+
+% Print a typewriter backslash.  For math mode, we can't simply use
+% \backslashcurfont: the story here is that in math mode, the \char
+% of \backslashcurfont ends up printing the roman \ from the math symbol
+% font (because \char in math mode uses the \mathcode, and plain.tex
+% sets \mathcode`\\="026E).  Hence we use an explicit \mathchar,
+% which is the decimal equivalent of "715c (class 7, e.g., use \fam;
+% ignored family value; char position "5C).  We can't use " for the
+% usual hex value because it has already been made active.
+
+@def@ttbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}}
+@let@backslashchar = @ttbackslash % @backslashchar{} is for user documents.
+
+% \rawbackslash defines an active \ to do \backslashcurfont.
+% \otherbackslash defines an active \ to be a literal `\' character with
+% catcode other.  We switch back and forth between these.
+@gdef@rawbackslash{@let\=@backslashcurfont}
+@gdef@otherbackslash{@let\=@realbackslash}
+
+% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
+% the literal character `\'.
+%
+{@catcode`- = @active
+ @gdef@normalturnoffactive{%
+   @nonasciistringdefs
+   @let-=@normaldash
+   @let"=@normaldoublequote
+   @let$=@normaldollar %$ font-lock fix
+   @let+=@normalplus
+   @let<=@normalless
+   @let>=@normalgreater
+   @let^=@normalcaret
+   @let_=@normalunderscore
+   @let|=@normalverticalbar
+   @let~=@normaltilde
+   @let\=@ttbackslash
+   @markupsetuplqdefault
+   @markupsetuprqdefault
+   @unsepspaces
+ }
+}
+
+% If a .fmt file is being used, characters that might appear in a file
+% name cannot be active until we have parsed the command line.
+% So turn them off again, and have @fixbackslash turn them back on.
+@catcode`+=@other @catcode`@_=@other
+
+% \enablebackslashhack - allow file to begin `\input texinfo'
+%
+% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
+% That is what \eatinput is for; after that, the `\' should revert to printing
+% a backslash.
+% If the file did not have a `\input texinfo', then it is turned off after
+% the first line; otherwise the first `\' in the file would cause an error.
+% This is used on the very last line of this file, texinfo.tex.
+% We also use @c to call @fixbackslash, in case ends of lines are hidden.
+{
+@catcode`@^=7
+@catcode`@^^M=13@gdef@enablebackslashhack{%
+  @global@let\ = @eatinput%
+  @catcode`@^^M=13%
+  @def@c{@fixbackslash@c}%
+  @def ^^M{@let^^M@secondlinenl}%
+  @gdef @secondlinenl{@let^^M@thirdlinenl}%
+  @gdef @thirdlinenl{@fixbackslash}%
+}}
+
+{@catcode`@^=7 @catcode`@^^M=13%
+@gdef@eatinput input texinfo#1^^M{@fixbackslash}}
+
+% Emergency active definition of newline, in case an active newline token
+% appears by mistake.
+{@catcode`@^=7 @catcode13=13%
+@gdef@enableemergencynewline{%
+  @gdef^^M{%
+    @par%
+    %<warning: active newline>@par%
+}}}
+
+
+@gdef@fixbackslash{%
+  @ifx\@eatinput @let\ = @ttbackslash @fi
+  @catcode13=5 % regular end of line
+  @enableemergencynewline
+  @let@c=@texinfoc
+  % Also turn back on active characters that might appear in the input
+  % file name, in case not using a pre-dumped format.
+  @catcode`+=@active
+  @catcode`@_=@active
+  %
+  % If texinfo.cnf is present on the system, read it.
+  % Useful for site-wide @afourpaper, etc.  This macro, @fixbackslash, gets
+  % called at the beginning of every Texinfo file.  Not opening texinfo.cnf
+  % directly in this file, texinfo.tex, makes it possible to make a format
+  % file for Texinfo.
+  %
+  @openin 1 texinfo.cnf
+  @ifeof 1 @else @input texinfo.cnf @fi
+  @closein 1
+}
+
+
+% Say @foo, not \foo, in error messages.
+@escapechar = `@@
+
+% These (along with & and #) are made active for url-breaking, so need
+% active definitions as the normal characters.
+@def@normaldot{.}
+@def@normalquest{?}
+@def@normalslash{/}
+
+% These look ok in all fonts, so just make them not special.
+% @hashchar{} gets its own user-level command, because of #line.
+@catcode`@& = @other @def@normalamp{&}
+@catcode`@# = @other @def@normalhash{#}
+@catcode`@% = @other @def@normalpercent{%}
+
+@let @hashchar = @normalhash
+
+@c Finally, make ` and ' active, so that txicodequoteundirected and
+@c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}.  If we
+@c don't make ` and ' active, @code will not get them as active chars.
+@c Do this last of all since we use ` in the previous @catcode assignments.
+@catcode`@'=@active
+@catcode`@`=@active
+@markupsetuplqdefault
+@markupsetuprqdefault
+
+@c Local variables:
+@c eval: (add-hook 'write-file-hooks 'time-stamp)
+@c page-delimiter: "^\\\\message\\|emacs-page"
+@c time-stamp-start: "def\\\\texinfoversion{"
+@c time-stamp-format: "%:y-%02m-%02d.%02H"
+@c time-stamp-end: "}"
+@c End:
+
+@c vim:sw=2:
+
+@ignore
+   arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115
+@end ignore
+@enablebackslashhack
diff --git a/ap/libc/glibc/glibc-2.23/manual/texis.awk b/ap/libc/glibc/glibc-2.23/manual/texis.awk
new file mode 100644
index 0000000..1537247
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/texis.awk
@@ -0,0 +1,21 @@
+BEGIN {
+    print "texis = \\";
+    for(x = 1; x < ARGC; x++)
+    {
+	input[0] = ARGV[x];
+	print ARGV[x], "\\";
+	for (s = 0; s >= 0; s--)
+	{
+	    while ((getline < input[s]) > 0)
+	    {
+		if ($1 == "@include")
+		{
+		    input[++s] = $2;
+		    print $2, "\\";
+		}
+	    }
+	    close(input[s]);
+	}
+    }
+    print "";
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/threads.texi b/ap/libc/glibc/glibc-2.23/manual/threads.texi
new file mode 100644
index 0000000..00cc725
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/threads.texi
@@ -0,0 +1,252 @@
+@node POSIX Threads
+@c @node POSIX Threads, Internal Probes, Cryptographic Functions, Top
+@chapter POSIX Threads
+@c %MENU% POSIX Threads
+@cindex pthreads
+
+This chapter describes the @glibcadj{} POSIX Thread implementation.
+
+@menu
+* Thread-specific Data::          Support for creating and
+				  managing thread-specific data
+* Non-POSIX Extensions::          Additional functions to extend
+				  POSIX Thread functionality
+@end menu
+
+@node Thread-specific Data
+@section Thread-specific Data
+
+The @glibcadj{} implements functions to allow users to create and manage
+data specific to a thread.  Such data may be destroyed at thread exit,
+if a destructor is provided.  The following functions are defined:
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c pthread_key_create ok
+@c  KEY_UNUSED ok
+@c  KEY_USABLE ok
+Create a thread-specific data key for the calling thread, referenced by
+@var{key}.
+
+Objects declared with the C++11 @code{thread_local} keyword are destroyed
+before thread-specific data, so they should not be used in thread-specific
+data destructors or even as members of the thread-specific data, since the
+latter is passed as an argument to the destructor function.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_key_delete (pthread_key_t @var{key})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c pthread_key_delete ok
+@c   This uses atomic compare and exchange to increment the seq number
+@c   after testing it's not a KEY_UNUSED seq number.
+@c  KEY_UNUSED dup ok
+Destroy the thread-specific data @var{key} in the calling thread.  The
+destructor for the thread-specific data is not called during destruction, nor
+is it called during thread exit.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun void *pthread_getspecific (pthread_key_t @var{key})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c pthread_getspecific ok
+Return the thread-specific data associated with @var{key} in the calling
+thread.
+@end deftypefun
+
+@comment pthread.h
+@comment POSIX
+@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
+@c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
+@c   a level2 block may be allocated by a signal handler after
+@c   another call already made a decision to allocate it, thus losing
+@c   the allocated value.  the seq number is updated before the
+@c   value, which might cause an earlier-generation value to seem
+@c   current if setspecific is cancelled or interrupted by a signal
+@c  KEY_UNUSED ok
+@c  calloc dup @ascuheap @acsmem
+Associate the thread-specific @var{value} with @var{key} in the calling thread.
+@end deftypefun
+
+
+@node Non-POSIX Extensions
+@section Non-POSIX Extensions
+
+In addition to implementing the POSIX API for threads, @theglibc{} provides
+additional functions and interfaces to provide functionality not specified in
+the standard.
+
+@menu
+* Default Thread Attributes::             Setting default attributes for
+					  threads in a process.
+@end menu
+
+@node Default Thread Attributes
+@subsection Setting Process-wide defaults for thread attributes
+
+@Theglibc{} provides non-standard API functions to set and get the default
+attributes used in the creation of threads in a process.
+
+@comment pthread.h
+@comment GNU
+@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c Takes lock around read from default_pthread_attr.
+Get the default attribute values and set @var{attr} to match.  This
+function returns @math{0} on success and a non-zero error code on
+failure.
+@end deftypefun
+
+@comment pthread.h
+@comment GNU
+@deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr})
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem
+@c  check_sched_policy_attr ok
+@c  check_sched_priority_attr ok
+@c   sched_get_priority_min dup ok
+@c   sched_get_priority_max dup ok
+@c  check_stacksize_attr ok
+@c  lll_lock @asulock @aculock
+@c  free dup @ascuheap @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  memcpy dup ok
+@c  lll_unlock @asulock @aculock
+Set the default attribute values to match the values in @var{attr}.  The
+function returns @math{0} on success and a non-zero error code on failure.
+The following error codes are defined for this function:
+
+@table @code
+@item EINVAL
+At least one of the values in @var{attr} does not qualify as valid for the
+attributes or the stack address is set in the attribute.
+@item ENOMEM
+The system does not have sufficient memory.
+@end table
+@end deftypefun
+
+@c FIXME these are undocumented:
+@c pthread_atfork
+@c pthread_attr_destroy
+@c pthread_attr_getaffinity_np
+@c pthread_attr_getdetachstate
+@c pthread_attr_getguardsize
+@c pthread_attr_getinheritsched
+@c pthread_attr_getschedparam
+@c pthread_attr_getschedpolicy
+@c pthread_attr_getscope
+@c pthread_attr_getstack
+@c pthread_attr_getstackaddr
+@c pthread_attr_getstacksize
+@c pthread_attr_init
+@c pthread_attr_setaffinity_np
+@c pthread_attr_setdetachstate
+@c pthread_attr_setguardsize
+@c pthread_attr_setinheritsched
+@c pthread_attr_setschedparam
+@c pthread_attr_setschedpolicy
+@c pthread_attr_setscope
+@c pthread_attr_setstack
+@c pthread_attr_setstackaddr
+@c pthread_attr_setstacksize
+@c pthread_barrierattr_destroy
+@c pthread_barrierattr_getpshared
+@c pthread_barrierattr_init
+@c pthread_barrierattr_setpshared
+@c pthread_barrier_destroy
+@c pthread_barrier_init
+@c pthread_barrier_wait
+@c pthread_cancel
+@c pthread_cleanup_push
+@c pthread_cleanup_pop
+@c pthread_condattr_destroy
+@c pthread_condattr_getclock
+@c pthread_condattr_getpshared
+@c pthread_condattr_init
+@c pthread_condattr_setclock
+@c pthread_condattr_setpshared
+@c pthread_cond_broadcast
+@c pthread_cond_destroy
+@c pthread_cond_init
+@c pthread_cond_signal
+@c pthread_cond_timedwait
+@c pthread_cond_wait
+@c pthread_create
+@c pthread_detach
+@c pthread_equal
+@c pthread_exit
+@c pthread_getaffinity_np
+@c pthread_getattr_np
+@c pthread_getconcurrency
+@c pthread_getcpuclockid
+@c pthread_getname_np
+@c pthread_getschedparam
+@c pthread_join
+@c pthread_kill
+@c pthread_kill_other_threads_np
+@c pthread_mutexattr_destroy
+@c pthread_mutexattr_getkind_np
+@c pthread_mutexattr_getprioceiling
+@c pthread_mutexattr_getprotocol
+@c pthread_mutexattr_getpshared
+@c pthread_mutexattr_getrobust
+@c pthread_mutexattr_getrobust_np
+@c pthread_mutexattr_gettype
+@c pthread_mutexattr_init
+@c pthread_mutexattr_setkind_np
+@c pthread_mutexattr_setprioceiling
+@c pthread_mutexattr_setprotocol
+@c pthread_mutexattr_setpshared
+@c pthread_mutexattr_setrobust
+@c pthread_mutexattr_setrobust_np
+@c pthread_mutexattr_settype
+@c pthread_mutex_consistent
+@c pthread_mutex_consistent_np
+@c pthread_mutex_destroy
+@c pthread_mutex_getprioceiling
+@c pthread_mutex_init
+@c pthread_mutex_lock
+@c pthread_mutex_setprioceiling
+@c pthread_mutex_timedlock
+@c pthread_mutex_trylock
+@c pthread_mutex_unlock
+@c pthread_once
+@c pthread_rwlockattr_destroy
+@c pthread_rwlockattr_getkind_np
+@c pthread_rwlockattr_getpshared
+@c pthread_rwlockattr_init
+@c pthread_rwlockattr_setkind_np
+@c pthread_rwlockattr_setpshared
+@c pthread_rwlock_destroy
+@c pthread_rwlock_init
+@c pthread_rwlock_rdlock
+@c pthread_rwlock_timedrdlock
+@c pthread_rwlock_timedwrlock
+@c pthread_rwlock_tryrdlock
+@c pthread_rwlock_trywrlock
+@c pthread_rwlock_unlock
+@c pthread_rwlock_wrlock
+@c pthread_self
+@c pthread_setaffinity_np
+@c pthread_setcancelstate
+@c pthread_setcanceltype
+@c pthread_setconcurrency
+@c pthread_setname_np
+@c pthread_setschedparam
+@c pthread_setschedprio
+@c pthread_sigmask
+@c pthread_sigqueue
+@c pthread_spin_destroy
+@c pthread_spin_init
+@c pthread_spin_lock
+@c pthread_spin_trylock
+@c pthread_spin_unlock
+@c pthread_testcancel
+@c pthread_timedjoin_np
+@c pthread_tryjoin_np
+@c pthread_yield
diff --git a/ap/libc/glibc/glibc-2.23/manual/time.texi b/ap/libc/glibc/glibc-2.23/manual/time.texi
new file mode 100644
index 0000000..f94cbe4
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/time.texi
@@ -0,0 +1,2922 @@
+@node Date and Time, Resource Usage And Limitation, Arithmetic, Top
+@c %MENU% Functions for getting the date and time and formatting them nicely
+@chapter Date and Time
+
+This chapter describes functions for manipulating dates and times,
+including functions for determining what time it is and conversion
+between different time representations.
+
+@menu
+* Time Basics::                 Concepts and definitions.
+* Elapsed Time::                Data types to represent elapsed times
+* Processor And CPU Time::      Time a program has spent executing.
+* Calendar Time::               Manipulation of ``real'' dates and times.
+* Setting an Alarm::            Sending a signal after a specified time.
+* Sleeping::                    Waiting for a period of time.
+@end menu
+
+
+@node Time Basics
+@section Time Basics
+@cindex time
+
+Discussing time in a technical manual can be difficult because the word
+``time'' in English refers to lots of different things.  In this manual,
+we use a rigorous terminology to avoid confusion, and the only thing we
+use the simple word ``time'' for is to talk about the abstract concept.
+
+A @dfn{calendar time} is a point in the time continuum, for example
+November 4, 1990 at 18:02.5 UTC.  Sometimes this is called ``absolute
+time''.
+@cindex calendar time
+
+We don't speak of a ``date'', because that is inherent in a calendar
+time.
+@cindex date
+
+An @dfn{interval} is a contiguous part of the time continuum between two
+calendar times, for example the hour between 9:00 and 10:00 on July 4,
+1980.
+@cindex interval
+
+An @dfn{elapsed time} is the length of an interval, for example, 35
+minutes.  People sometimes sloppily use the word ``interval'' to refer
+to the elapsed time of some interval.
+@cindex elapsed time
+@cindex time, elapsed
+
+An @dfn{amount of time} is a sum of elapsed times, which need not be of
+any specific intervals.  For example, the amount of time it takes to
+read a book might be 9 hours, independently of when and in how many
+sittings it is read.
+
+A @dfn{period} is the elapsed time of an interval between two events,
+especially when they are part of a sequence of regularly repeating
+events.
+@cindex period of time
+
+@dfn{CPU time} is like calendar time, except that it is based on the
+subset of the time continuum when a particular process is actively
+using a CPU.  CPU time is, therefore, relative to a process.
+@cindex CPU time
+
+@dfn{Processor time} is an amount of time that a CPU is in use.  In
+fact, it's a basic system resource, since there's a limit to how much
+can exist in any given interval (that limit is the elapsed time of the
+interval times the number of CPUs in the processor).  People often call
+this CPU time, but we reserve the latter term in this manual for the
+definition above.
+@cindex processor time
+
+@node Elapsed Time
+@section Elapsed Time
+@cindex elapsed time
+
+One way to represent an elapsed time is with a simple arithmetic data
+type, as with the following function to compute the elapsed time between
+two calendar times.  This function is declared in @file{time.h}.
+
+@comment time.h
+@comment ISO
+@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{difftime} function returns the number of seconds of elapsed
+time between calendar time @var{time1} and calendar time @var{time0}, as
+a value of type @code{double}.  The difference ignores leap seconds
+unless leap second support is enabled.
+
+In @theglibc{}, you can simply subtract @code{time_t} values.  But on
+other systems, the @code{time_t} data type might use some other encoding
+where subtraction doesn't work directly.
+@end deftypefun
+
+@Theglibc{} provides two data types specifically for representing
+an elapsed time.  They are used by various @glibcadj{} functions, and
+you can use them for your own purposes too.  They're exactly the same
+except that one has a resolution in microseconds, and the other, newer
+one, is in nanoseconds.
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct timeval}
+@cindex timeval
+The @code{struct timeval} structure represents an elapsed time.  It is
+declared in @file{sys/time.h} and has the following members:
+
+@table @code
+@item time_t tv_sec
+This represents the number of whole seconds of elapsed time.
+
+@item long int tv_usec
+This is the rest of the elapsed time (a fraction of a second),
+represented as the number of microseconds.  It is always less than one
+million.
+
+@end table
+@end deftp
+
+@comment sys/time.h
+@comment POSIX.1
+@deftp {Data Type} {struct timespec}
+@cindex timespec
+The @code{struct timespec} structure represents an elapsed time.  It is
+declared in @file{time.h} and has the following members:
+
+@table @code
+@item time_t tv_sec
+This represents the number of whole seconds of elapsed time.
+
+@item long int tv_nsec
+This is the rest of the elapsed time (a fraction of a second),
+represented as the number of nanoseconds.  It is always less than one
+billion.
+
+@end table
+@end deftp
+
+It is often necessary to subtract two values of type @w{@code{struct
+timeval}} or @w{@code{struct timespec}}.  Here is the best way to do
+this.  It works even on some peculiar operating systems where the
+@code{tv_sec} member has an unsigned type.
+
+@smallexample
+@include timeval_subtract.c.texi
+@end smallexample
+
+Common functions that use @code{struct timeval} are @code{gettimeofday}
+and @code{settimeofday}.
+
+
+There are no @glibcadj{} functions specifically oriented toward
+dealing with elapsed times, but the calendar time, processor time, and
+alarm and sleeping functions have a lot to do with them.
+
+
+@node Processor And CPU Time
+@section Processor And CPU Time
+
+If you're trying to optimize your program or measure its efficiency,
+it's very useful to know how much processor time it uses.  For that,
+calendar time and elapsed times are useless because a process may spend
+time waiting for I/O or for other processes to use the CPU.  However,
+you can get the information with the functions in this section.
+
+CPU time (@pxref{Time Basics}) is represented by the data type
+@code{clock_t}, which is a number of @dfn{clock ticks}.  It gives the
+total amount of time a process has actively used a CPU since some
+arbitrary event.  On @gnusystems{}, that event is the creation of the
+process.  While arbitrary in general, the event is always the same event
+for any particular process, so you can always measure how much time on
+the CPU a particular computation takes by examining the process' CPU
+time before and after the computation.
+@cindex CPU time
+@cindex clock ticks
+@cindex ticks, clock
+
+On @gnulinuxhurdsystems{}, @code{clock_t} is equivalent to @code{long int} and
+@code{CLOCKS_PER_SEC} is an integer value.  But in other systems, both
+@code{clock_t} and the macro @code{CLOCKS_PER_SEC} can be either integer
+or floating-point types.  Casting CPU time values to @code{double}, as
+in the example above, makes sure that operations such as arithmetic and
+printing work properly and consistently no matter what the underlying
+representation is.
+
+Note that the clock can wrap around.  On a 32bit system with
+@code{CLOCKS_PER_SEC} set to one million this function will return the
+same value approximately every 72 minutes.
+
+For additional functions to examine a process' use of processor time,
+and to control it, see @ref{Resource Usage And Limitation}.
+
+
+@menu
+* CPU Time::                    The @code{clock} function.
+* Processor Time::              The @code{times} function.
+@end menu
+
+@node CPU Time
+@subsection CPU Time Inquiry
+
+To get a process' CPU time, you can use the @code{clock} function.  This
+facility is declared in the header file @file{time.h}.
+@pindex time.h
+
+In typical usage, you call the @code{clock} function at the beginning
+and end of the interval you want to time, subtract the values, and then
+divide by @code{CLOCKS_PER_SEC} (the number of clock ticks per second)
+to get processor time, like this:
+
+@smallexample
+@group
+#include <time.h>
+
+clock_t start, end;
+double cpu_time_used;
+
+start = clock();
+@dots{} /* @r{Do the work.} */
+end = clock();
+cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
+@end group
+@end smallexample
+
+Do not use a single CPU time as an amount of time; it doesn't work that
+way.  Either do a subtraction as shown above or query processor time
+directly.  @xref{Processor Time}.
+
+Different computers and operating systems vary wildly in how they keep
+track of CPU time.  It's common for the internal processor clock
+to have a resolution somewhere between a hundredth and millionth of a
+second.
+
+@comment time.h
+@comment ISO
+@deftypevr Macro int CLOCKS_PER_SEC
+The value of this macro is the number of clock ticks per second measured
+by the @code{clock} function.  POSIX requires that this value be one
+million independent of the actual resolution.
+@end deftypevr
+
+@comment time.h
+@comment ISO
+@deftp {Data Type} clock_t
+This is the type of the value returned by the @code{clock} function.
+Values of type @code{clock_t} are numbers of clock ticks.
+@end deftp
+
+@comment time.h
+@comment ISO
+@deftypefun clock_t clock (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On Hurd, this calls task_info twice and adds user and system time
+@c from both basic and thread time info structs.  On generic posix,
+@c calls times and adds utime and stime.  On bsd, calls getrusage and
+@c safely converts stime and utime to clock.  On linux, calls
+@c clock_gettime.
+This function returns the calling process' current CPU time.  If the CPU
+time is not available or cannot be represented, @code{clock} returns the
+value @code{(clock_t)(-1)}.
+@end deftypefun
+
+
+@node Processor Time
+@subsection Processor Time Inquiry
+
+The @code{times} function returns information about a process'
+consumption of processor time in a @w{@code{struct tms}} object, in
+addition to the process' CPU time.  @xref{Time Basics}.  You should
+include the header file @file{sys/times.h} to use this facility.
+@cindex processor time
+@cindex CPU time
+@pindex sys/times.h
+
+@comment sys/times.h
+@comment POSIX.1
+@deftp {Data Type} {struct tms}
+The @code{tms} structure is used to return information about process
+times.  It contains at least the following members:
+
+@table @code
+@item clock_t tms_utime
+This is the total processor time the calling process has used in
+executing the instructions of its program.
+
+@item clock_t tms_stime
+This is the processor time the system has used on behalf of the calling
+process.
+
+@item clock_t tms_cutime
+This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
+values of all terminated child processes of the calling process, whose
+status has been reported to the parent process by @code{wait} or
+@code{waitpid}; see @ref{Process Completion}.  In other words, it
+represents the total processor time used in executing the instructions
+of all the terminated child processes of the calling process, excluding
+child processes which have not yet been reported by @code{wait} or
+@code{waitpid}.
+@cindex child process
+
+@item clock_t tms_cstime
+This is similar to @code{tms_cutime}, but represents the total processor
+time system has used on behalf of all the terminated child processes
+of the calling process.
+@end table
+
+All of the times are given in numbers of clock ticks.  Unlike CPU time,
+these are the actual amounts of time; not relative to any event.
+@xref{Creating a Process}.
+@end deftp
+
+@comment time.h
+@comment POSIX.1
+@deftypevr Macro int CLK_TCK
+This is an obsolete name for the number of clock ticks per second.  Use
+@code{sysconf (_SC_CLK_TCK)} instead.
+@end deftypevr
+
+@comment sys/times.h
+@comment POSIX.1
+@deftypefun clock_t times (struct tms *@var{buffer})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On HURD, this calls task_info twice, for basic and thread times info,
+@c adding user and system times into tms, and then gettimeofday, to
+@c compute the real time.  On BSD, it calls getclktck, getrusage (twice)
+@c and time.  On Linux, it's a syscall with special handling to account
+@c for clock_t counts that look like error values.
+The @code{times} function stores the processor time information for
+the calling process in @var{buffer}.
+
+The return value is the number of clock ticks since an arbitrary point
+in the past, e.g. since system start-up.  @code{times} returns
+@code{(clock_t)(-1)} to indicate failure.
+@end deftypefun
+
+@strong{Portability Note:} The @code{clock} function described in
+@ref{CPU Time} is specified by the @w{ISO C} standard.  The
+@code{times} function is a feature of POSIX.1.  On @gnusystems{}, the
+CPU time is defined to be equivalent to the sum of the @code{tms_utime}
+and @code{tms_stime} fields returned by @code{times}.
+
+@node Calendar Time
+@section Calendar Time
+
+This section describes facilities for keeping track of calendar time.
+@xref{Time Basics}.
+
+@Theglibc{} represents calendar time three ways:
+
+@itemize @bullet
+@item
+@dfn{Simple time} (the @code{time_t} data type) is a compact
+representation, typically giving the number of seconds of elapsed time
+since some implementation-specific base time.
+@cindex simple time
+
+@item
+There is also a "high-resolution time" representation.  Like simple
+time, this represents a calendar time as an elapsed time since a base
+time, but instead of measuring in whole seconds, it uses a @code{struct
+timeval} data type, which includes fractions of a second.  Use this time
+representation instead of simple time when you need greater precision.
+@cindex high-resolution time
+
+@item
+@dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data
+type) represents a calendar time as a set of components specifying the
+year, month, and so on in the Gregorian calendar, for a specific time
+zone.  This calendar time representation is usually used only to
+communicate with people.
+@cindex local time
+@cindex broken-down time
+@cindex Gregorian calendar
+@cindex calendar, Gregorian
+@end itemize
+
+@menu
+* 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.
+* High Accuracy Clock::         Maintaining a high accuracy system clock.
+* Formatting Calendar Time::    Converting times to strings.
+* Parsing Date and Time::       Convert textual time and date information back
+                                 into broken-down time values.
+* 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.
+@end menu
+
+@node Simple Calendar Time
+@subsection Simple Calendar Time
+
+This section describes the @code{time_t} data type for representing calendar
+time as simple time, and the functions which operate on simple time objects.
+These facilities are declared in the header file @file{time.h}.
+@pindex time.h
+
+@cindex epoch
+@comment time.h
+@comment ISO
+@deftp {Data Type} time_t
+This is the data type used to represent simple time.  Sometimes, it also
+represents an elapsed time.  When interpreted as a calendar time value,
+it represents the number of seconds elapsed since 00:00:00 on January 1,
+1970, Coordinated Universal Time.  (This calendar time is sometimes
+referred to as the @dfn{epoch}.)  POSIX requires that this count not
+include leap seconds, but on some systems this count includes leap seconds
+if you set @code{TZ} to certain values (@pxref{TZ Variable}).
+
+Note that a simple time has no concept of local time zone.  Calendar
+Time @var{T} is the same instant in time regardless of where on the
+globe the computer is.
+
+In @theglibc{}, @code{time_t} is equivalent to @code{long int}.
+In other systems, @code{time_t} might be either an integer or
+floating-point type.
+@end deftp
+
+The function @code{difftime} tells you the elapsed time between two
+simple calendar times, which is not always as easy to compute as just
+subtracting.  @xref{Elapsed Time}.
+
+@comment time.h
+@comment ISO
+@deftypefun time_t time (time_t *@var{result})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{time} function returns the current calendar time as a value of
+type @code{time_t}.  If the argument @var{result} is not a null pointer,
+the calendar time value is also stored in @code{*@var{result}}.  If the
+current calendar time is not available, the value
+@w{@code{(time_t)(-1)}} is returned.
+@end deftypefun
+
+@c The GNU C library implements stime() with a call to settimeofday() on
+@c Linux.
+@comment time.h
+@comment SVID, XPG
+@deftypefun int stime (const time_t *@var{newtime})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On unix, this is implemented in terms of settimeofday.
+@code{stime} sets the system clock, i.e., it tells the system that the
+current calendar time is @var{newtime}, where @code{newtime} is
+interpreted as described in the above definition of @code{time_t}.
+
+@code{settimeofday} is a newer function which sets the system clock to
+better than one second precision.  @code{settimeofday} is generally a
+better choice than @code{stime}.  @xref{High-Resolution Calendar}.
+
+Only the superuser can set the system clock.
+
+If the function succeeds, the return value is zero.  Otherwise, it is
+@code{-1} and @code{errno} is set accordingly:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@end table
+@end deftypefun
+
+
+
+@node High-Resolution Calendar
+@subsection High-Resolution Calendar
+
+The @code{time_t} data type used to represent simple times has a
+resolution of only one second.  Some applications need more precision.
+
+So, @theglibc{} also contains functions which are capable of
+representing calendar times to a higher resolution than one second.  The
+functions and the associated data types described in this section are
+declared in @file{sys/time.h}.
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct timezone}
+The @code{struct timezone} structure is used to hold minimal information
+about the local time zone.  It has the following members:
+
+@table @code
+@item int tz_minuteswest
+This is the number of minutes west of UTC.
+
+@item int tz_dsttime
+If nonzero, Daylight Saving Time applies during some part of the year.
+@end table
+
+The @code{struct timezone} type is obsolete and should never be used.
+Instead, use the facilities described in @ref{Time Zone Functions}.
+@end deftp
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On most GNU/Linux systems this is a direct syscall, but the posix/
+@c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and
+@c localtime_r, saving and restoring tzname in an unsafe manner.
+@c On some GNU/Linux variants, ifunc resolvers are used in shared libc
+@c for vdso resolution.  ifunc-vdso-revisit.
+The @code{gettimeofday} function returns the current calendar time as
+the elapsed time since the epoch in the @code{struct timeval} structure
+indicated by @var{tp}.  (@pxref{Elapsed Time} for a description of
+@code{struct timeval}).  Information about the time zone is returned in
+the structure pointed at @var{tzp}.  If the @var{tzp} argument is a null
+pointer, time zone information is ignored.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
+
+@table @code
+@item ENOSYS
+The operating system does not support getting time zone information, and
+@var{tzp} is not a null pointer.  @gnusystems{} do not
+support using @w{@code{struct timezone}} to represent time zone
+information; that is an obsolete feature of 4.3 BSD.
+Instead, use the facilities described in @ref{Time Zone Functions}.
+@end table
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On HURD, it calls host_set_time with a privileged port.  On other
+@c unix systems, it's a syscall.
+The @code{settimeofday} function sets the current calendar time in the
+system clock according to the arguments.  As for @code{gettimeofday},
+the calendar time is represented as the elapsed time since the epoch.
+As for @code{gettimeofday}, time zone information is ignored if
+@var{tzp} is a null pointer.
+
+You must be a privileged user in order to use @code{settimeofday}.
+
+Some kernels automatically set the system clock from some source such as
+a hardware clock when they start up.  Others, including Linux, place the
+system clock in an ``invalid'' state (in which attempts to read the clock
+fail).  A call of @code{stime} removes the system clock from an invalid
+state, and system startup scripts typically run a program that calls
+@code{stime}.
+
+@code{settimeofday} causes a sudden jump forwards or backwards, which
+can cause a variety of problems in a system.  Use @code{adjtime} (below)
+to make a smooth transition from one time to another by temporarily
+speeding up or slowing down the clock.
+
+With a Linux kernel, @code{adjtimex} does the same thing and can also
+make permanent changes to the speed of the system clock so it doesn't
+need to be corrected as often.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EPERM
+This process cannot set the clock because it is not privileged.
+
+@item ENOSYS
+The operating system does not support setting time zone information, and
+@var{tzp} is not a null pointer.
+@end table
+@end deftypefun
+
+@c On Linux, GNU libc implements adjtime() as a call to adjtimex().
+@comment sys/time.h
+@comment BSD
+@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On hurd and mach, call host_adjust_time with a privileged port.  On
+@c Linux, it's implemented in terms of adjtimex.  On other unixen, it's
+@c a syscall.
+This function speeds up or slows down the system clock in order to make
+a gradual adjustment.  This ensures that the calendar time reported by
+the system clock is always monotonically increasing, which might not
+happen if you simply set the clock.
+
+The @var{delta} argument specifies a relative adjustment to be made to
+the clock time.  If negative, the system clock is slowed down for a
+while until it has lost this much elapsed time.  If positive, the system
+clock is speeded up for a while.
+
+If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
+function returns information about any previous time adjustment that
+has not yet completed.
+
+This function is typically used to synchronize the clocks of computers
+in a local network.  You must be a privileged user to use it.
+
+With a Linux kernel, you can use the @code{adjtimex} function to
+permanently change the clock speed.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
+
+@table @code
+@item EPERM
+You do not have privilege to set the time.
+@end table
+@end deftypefun
+
+@strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
+and @code{adjtime} functions are derived from BSD.
+
+
+Symbols for the following function are declared in @file{sys/timex.h}.
+
+@comment sys/timex.h
+@comment GNU
+@deftypefun int adjtimex (struct timex *@var{timex})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c It's a syscall, only available on linux.
+
+@code{adjtimex} is functionally identical to @code{ntp_adjtime}.
+@xref{High Accuracy Clock}.
+
+This function is present only with a Linux kernel.
+
+@end deftypefun
+
+@node Broken-down Time
+@subsection Broken-down Time
+@cindex broken-down time
+@cindex calendar time and broken-down time
+
+Calendar time is represented by the usual @glibcadj{} functions as an
+elapsed time since a fixed base calendar time.  This is convenient for
+computation, but has no relation to the way people normally think of
+calendar time.  By contrast, @dfn{broken-down time} is a binary
+representation of calendar time separated into year, month, day, and so
+on.  Broken-down time values are not useful for calculations, but they
+are useful for printing human readable time information.
+
+A broken-down time value is always relative to a choice of time
+zone, and it also indicates which time zone that is.
+
+The symbols in this section are declared in the header file @file{time.h}.
+
+@comment time.h
+@comment ISO
+@deftp {Data Type} {struct tm}
+This is the data type used to represent a broken-down time.  The structure
+contains at least the following members, which can appear in any order.
+
+@table @code
+@item int tm_sec
+This is the number of full seconds since the top of the minute (normally
+in the range @code{0} through @code{59}, but the actual upper limit is
+@code{60}, to allow for leap seconds if leap second support is
+available).
+@cindex leap second
+
+@item int tm_min
+This is the number of full minutes since the top of the hour (in the
+range @code{0} through @code{59}).
+
+@item int tm_hour
+This is the number of full hours past midnight (in the range @code{0} through
+@code{23}).
+
+@item int tm_mday
+This is the ordinal day of the month (in the range @code{1} through @code{31}).
+Watch out for this one!  As the only ordinal number in the structure, it is
+inconsistent with the rest of the structure.
+
+@item int tm_mon
+This is the number of full calendar months since the beginning of the
+year (in the range @code{0} through @code{11}).  Watch out for this one!
+People usually use ordinal numbers for month-of-year (where January = 1).
+
+@item int tm_year
+This is the number of full calendar years since 1900.
+
+@item int tm_wday
+This is the number of full days since Sunday (in the range @code{0} through
+@code{6}).
+
+@item int tm_yday
+This is the number of full days since the beginning of the year (in the
+range @code{0} through @code{365}).
+
+@item int tm_isdst
+@cindex Daylight Saving Time
+@cindex summer time
+This is a flag that indicates whether Daylight Saving Time is (or was, or
+will be) in effect at the time described.  The value is positive if
+Daylight Saving Time is in effect, zero if it is not, and negative if the
+information is not available.
+
+@item long int tm_gmtoff
+This field describes the time zone that was used to compute this
+broken-down time value, including any adjustment for daylight saving; it
+is the number of seconds that you must add to UTC to get local time.
+You can also think of this as the number of seconds east of UTC.  For
+example, for U.S. Eastern Standard Time, the value is @code{-5*60*60}.
+The @code{tm_gmtoff} field is derived from BSD and is a GNU library
+extension; it is not visible in a strict @w{ISO C} environment.
+
+@item const char *tm_zone
+This field is the name for the time zone that was used to compute this
+broken-down time value.  Like @code{tm_gmtoff}, this field is a BSD and
+GNU extension, and is not visible in a strict @w{ISO C} environment.
+@end table
+@end deftp
+
+
+@comment time.h
+@comment ISO
+@deftypefun {struct tm *} localtime (const time_t *@var{time})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c Calls tz_convert with a static buffer.
+@c localtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+The @code{localtime} function converts the simple time pointed to by
+@var{time} to broken-down time representation, expressed relative to the
+user's specified time zone.
+
+The return value is a pointer to a static broken-down time structure, which
+might be overwritten by subsequent calls to @code{ctime}, @code{gmtime},
+or @code{localtime}.  (But no other library function overwrites the contents
+of this object.)
+
+The return value is the null pointer if @var{time} cannot be represented
+as a broken-down time; typically this is because the year cannot fit into
+an @code{int}.
+
+Calling @code{localtime} also sets the current time zone as if
+@code{tzset} were called.  @xref{Time Zone Functions}.
+@end deftypefun
+
+Using the @code{localtime} function is a big problem in multi-threaded
+programs.  The result is returned in a static buffer and this is used in
+all threads.  POSIX.1c introduced a variant of this function.
+
+@comment time.h
+@comment POSIX.1c
+@deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c localtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  tz_convert(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   libc_lock_lock dup @asulock @aculock
+@c   tzset_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     always called with tzset_lock held
+@c     sets static is_initialized before initialization;
+@c     reads and sets old_tz; sets tz_rules.
+@c     some of the issues only apply on the first call.
+@c     subsequent calls only trigger these when called by localtime;
+@c     otherwise, they're ok.
+@c    getenv dup @mtsenv
+@c    strcmp dup ok
+@c    strdup @ascuheap
+@c    tzfile_read @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     memcmp dup ok
+@c     strstr dup ok
+@c     getenv dup @mtsenv
+@c     asprintf dup @mtslocale @ascuheap @acsmem
+@c     stat64 dup ok
+@c     fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c     fileno dup ok
+@c     fstat64 dup ok
+@c     fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c     free dup @ascuheap @acsmem
+@c     fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive]
+@c     fread_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
+@c     memcpy dup ok
+@c     decode ok
+@c      bswap_32 dup ok
+@c     fseek dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
+@c     ftello dup ok [no @mtasurace:stream @asucorrupt @acucorrupt]
+@c     malloc dup @ascuheap @acsmem
+@c     decode64 ok
+@c      bswap_64 dup ok
+@c     getc_unlocked ok [no @mtasurace:stream @asucorrupt @acucorrupt]
+@c     tzstring dup @ascuheap @acsmem
+@c     compute_tzname_max dup ok [guarded by tzset_lock]
+@c    memset dup ok
+@c    update_vars ok [guarded by tzset_lock]
+@c      sets daylight, timezone, tzname and tzname_cur_max;
+@c      called only with tzset_lock held, unless tzset_parse_tz
+@c      (internal, but not static) gets called by users; given the its
+@c      double-underscore-prefixed name, this interface violation could
+@c      be regarded as undefined behavior.
+@c     strlen ok
+@c    tzset_parse_tz @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     sscanf dup @mtslocale @ascuheap @acsmem
+@c     isalnum dup @mtsenv
+@c     tzstring @ascuheap @acsmem
+@c       reads and changes tzstring_list without synchronization, but
+@c       only called with tzset_lock held (save for interface violations)
+@c      strlen dup ok
+@c      malloc dup @ascuheap @acsmem
+@c      strcpy dup ok
+@c     isdigit dup @mtslocale
+@c     compute_offset ok
+@c     tzfile_default @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c       sets tzname, timezone, types, zone_names, rule_*off, etc; no guards
+@c      strlen dup ok
+@c      tzfile_read dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c      mempcpy dup ok
+@c      compute_tzname_max ok [if guarded by tzset_lock]
+@c        iterates over zone_names; no guards
+@c     free dup @ascuheap @acsmem
+@c     strtoul dup @mtslocale
+@c     update_vars dup ok
+@c   tzfile_compute(use_localtime) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c     sets tzname; no guards.  with !use_localtime, as in gmtime, it's ok
+@c    tzstring dup @acsuheap @acsmem
+@c    tzset_parse_tz dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    offtime dup ok
+@c    tz_compute dup ok
+@c    strcmp dup ok
+@c   offtime ok
+@c    isleap dup ok
+@c   tz_compute ok
+@c    compute_change ok
+@c     isleap ok
+@c   libc_lock_unlock dup @aculock
+
+The @code{localtime_r} function works just like the @code{localtime}
+function.  It takes a pointer to a variable containing a simple time
+and converts it to the broken-down time format.
+
+But the result is not placed in a static buffer.  Instead it is placed
+in the object of type @code{struct tm} to which the parameter
+@var{resultp} points.
+
+If the conversion is successful the function returns a pointer to the
+object the result was written into, i.e., it returns @var{resultp}.
+@end deftypefun
+
+
+@comment time.h
+@comment ISO
+@deftypefun {struct tm *} gmtime (const time_t *@var{time})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c gmtime @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  tz_convert dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+This function is similar to @code{localtime}, except that the broken-down
+time is expressed as Coordinated Universal Time (UTC) (formerly called
+Greenwich Mean Time (GMT)) rather than relative to a local time zone.
+
+@end deftypefun
+
+As for the @code{localtime} function we have the problem that the result
+is placed in a static variable.  POSIX.1c also provides a replacement for
+@code{gmtime}.
+
+@comment time.h
+@comment POSIX.1c
+@deftypefun {struct tm *} gmtime_r (const time_t *@var{time}, struct tm *@var{resultp})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c You'd think tz_convert could avoid some safety issues with
+@c !use_localtime, but no such luck: tzset_internal will always bring
+@c about all possible AS and AC problems when it's first called.
+@c Calling any of localtime,gmtime_r once would run the initialization
+@c and avoid the heap, mem and fd issues in gmtime* in subsequent calls,
+@c but the unsafe locking would remain.
+@c gmtime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  tz_convert(gmtime_r) dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+This function is similar to @code{localtime_r}, except that it converts
+just like @code{gmtime} the given time as Coordinated Universal Time.
+
+If the conversion is successful the function returns a pointer to the
+object the result was written into, i.e., it returns @var{resultp}.
+@end deftypefun
+
+
+@comment time.h
+@comment ISO
+@deftypefun time_t mktime (struct tm *@var{brokentime})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c mktime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   passes a static localtime_offset to mktime_internal; it is read
+@c   once, used as an initial guess, and updated at the end, but not
+@c   used except as a guess for subsequent calls, so it should be safe.
+@c   Even though a compiler might delay the load and perform it multiple
+@c   times (bug 16346), there are at least two unconditional uses of the
+@c   auto variable in which the first load is stored, separated by a
+@c   call to an external function, and a conditional change of the
+@c   variable before the external call, so refraining from allocating a
+@c   local variable at the first load would be a very bad optimization.
+@c  tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  mktime_internal(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   ydhms_diff ok
+@c   ranged_convert(localtime_r) @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    *convert = localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    time_t_avg dup ok
+@c   guess_time_tm dup ok
+@c    ydhms_diff dup ok
+@c    time_t_add_ok ok
+@c     time_t_avg ok
+@c   isdst_differ ok
+@c   time_t_int_add_ok ok
+The @code{mktime} function converts a broken-down time structure to a
+simple time representation.  It also normalizes the contents of the
+broken-down time structure, and fills in some components based on the
+values of the others.
+
+The @code{mktime} function ignores the specified contents of the
+@code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone}
+members of the broken-down time
+structure.  It uses the values of the other components to determine the
+calendar time; it's permissible for these components to have
+unnormalized values outside their normal ranges.  The last thing that
+@code{mktime} does is adjust the components of the @var{brokentime}
+structure, including the members that were initially ignored.
+
+If the specified broken-down time cannot be represented as a simple time,
+@code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
+the contents of @var{brokentime}.
+
+Calling @code{mktime} also sets the current time zone as if
+@code{tzset} were called; @code{mktime} uses this information instead
+of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone}
+members.  @xref{Time Zone Functions}.
+@end deftypefun
+
+@comment time.h
+@comment ???
+@deftypefun time_t timelocal (struct tm *@var{brokentime})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c Alias to mktime.
+
+@code{timelocal} is functionally identical to @code{mktime}, but more
+mnemonically named.  Note that it is the inverse of the @code{localtime}
+function.
+
+@strong{Portability note:}  @code{mktime} is essentially universally
+available.  @code{timelocal} is rather rare.
+
+@end deftypefun
+
+@comment time.h
+@comment ???
+@deftypefun time_t timegm (struct tm *@var{brokentime})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c timegm @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   gmtime_offset triggers the same caveats as localtime_offset in mktime.
+@c   although gmtime_r, as called by mktime, might save some issues,
+@c   tzset calls tzset_internal with always, which forces
+@c   reinitialization, so all issues may arise.
+@c  tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  mktime_internal(gmtime_r) @asulock @aculock
+@c ..gmtime_r @asulock @aculock
+@c    ... dup ok
+@c    tz_convert(!use_localtime) @asulock @aculock
+@c     ... dup @asulock @aculock
+@c     tzfile_compute(!use_localtime) ok
+
+@code{timegm} is functionally identical to @code{mktime} except it
+always takes the input values to be Coordinated Universal Time (UTC)
+regardless of any local time zone setting.
+
+Note that @code{timegm} is the inverse of @code{gmtime}.
+
+@strong{Portability note:}  @code{mktime} is essentially universally
+available.  @code{timegm} is rather rare.  For the most portable
+conversion from a UTC broken-down time to a simple time, set
+the @code{TZ} environment variable to UTC, call @code{mktime}, then set
+@code{TZ} back.
+
+@end deftypefun
+
+
+
+@node High Accuracy Clock
+@subsection High Accuracy Clock
+
+@cindex time, high precision
+@cindex clock, high accuracy
+@pindex sys/timex.h
+@c On Linux, GNU libc implements ntp_gettime() and npt_adjtime() as calls
+@c to adjtimex().
+The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an
+interface to monitor and manipulate the system clock to maintain high
+accuracy time.  For example, you can fine tune the speed of the clock
+or synchronize it with another time source.
+
+A typical use of these functions is by a server implementing the Network
+Time Protocol to synchronize the clocks of multiple systems and high
+precision clocks.
+
+These functions are declared in @file{sys/timex.h}.
+
+@tindex struct ntptimeval
+@deftp {Data Type} {struct ntptimeval}
+This structure is used for information about the system clock.  It
+contains the following members:
+@table @code
+@item struct timeval time
+This is the current calendar time, expressed as the elapsed time since
+the epoch.  The @code{struct timeval} data type is described in
+@ref{Elapsed Time}.
+
+@item long int maxerror
+This is the maximum error, measured in microseconds.  Unless updated
+via @code{ntp_adjtime} periodically, this value will reach some
+platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds.  This value can
+be set by @code{ntp_adjtime} to indicate the estimated offset of the
+system clock from the true calendar time.
+@end table
+@end deftp
+
+@comment sys/timex.h
+@comment GNU
+@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapper for adjtimex.
+The @code{ntp_gettime} function sets the structure pointed to by
+@var{tptr} to current values.  The elements of the structure afterwards
+contain the values the timer implementation in the kernel assumes.  They
+might or might not be correct.  If they are not a @code{ntp_adjtime}
+call is necessary.
+
+The return value is @code{0} on success and other values on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item TIME_ERROR
+The precision clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care.
+@end table
+@end deftypefun
+
+@tindex struct timex
+@deftp {Data Type} {struct timex}
+This structure is used to control and monitor the system clock.  It
+contains the following members:
+@table @code
+@item unsigned int modes
+This variable controls whether and which values are set.  Several
+symbolic constants have to be combined with @emph{binary or} to specify
+the effective mode.  These constants start with @code{MOD_}.
+
+@item long int offset
+This value indicates the current offset of the system clock from the true
+calendar time.  The value is given in microseconds.  If bit
+@code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other
+dependent values) can be set.  The offset's absolute value must not
+exceed @code{MAXPHASE}.
+
+
+@item long int frequency
+This value indicates the difference in frequency between the true
+calendar time and the system clock.  The value is expressed as scaled
+PPM (parts per million, 0.0001%).  The scaling is @code{1 <<
+SHIFT_USEC}.  The value can be set with bit @code{MOD_FREQUENCY}, but
+the absolute value must not exceed @code{MAXFREQ}.
+
+@item long int maxerror
+This is the maximum error, measured in microseconds.  A new value can be
+set using bit @code{MOD_MAXERROR}.  Unless updated via
+@code{ntp_adjtime} periodically, this value will increase steadily
+and reach some platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds.  This value can
+be set using bit @code{MOD_ESTERROR}.
+
+@item int status
+This variable reflects the various states of the clock machinery.  There
+are symbolic constants for the significant bits, starting with
+@code{STA_}.  Some of these flags can be updated using the
+@code{MOD_STATUS} bit.
+
+@item long int constant
+This value represents the bandwidth or stiffness of the PLL (phase
+locked loop) implemented in the kernel.  The value can be changed using
+bit @code{MOD_TIMECONST}.
+
+@item long int precision
+This value represents the accuracy or the maximum error when reading the
+system clock.  The value is expressed in microseconds.
+
+@item long int tolerance
+This value represents the maximum frequency error of the system clock in
+scaled PPM.  This value is used to increase the @code{maxerror} every
+second.
+
+@item struct timeval time
+The current calendar time.
+
+@item long int tick
+The elapsed time between clock ticks in microseconds.  A clock tick is a
+periodic timer interrupt on which the system clock is based.
+
+@item long int ppsfreq
+This is the first of a few optional variables that are present only if
+the system clock can use a PPS (pulse per second) signal to discipline
+the system clock.  The value is expressed in scaled PPM and it denotes
+the difference in frequency between the system clock and the PPS signal.
+
+@item long int jitter
+This value expresses a median filtered average of the PPS signal's
+dispersion in microseconds.
+
+@item int shift
+This value is a binary exponent for the duration of the PPS calibration
+interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}.
+
+@item long int stabil
+This value represents the median filtered dispersion of the PPS
+frequency in scaled PPM.
+
+@item long int jitcnt
+This counter represents the number of pulses where the jitter exceeded
+the allowed maximum @code{MAXTIME}.
+
+@item long int calcnt
+This counter reflects the number of successful calibration intervals.
+
+@item long int errcnt
+This counter represents the number of calibration errors (caused by
+large offsets or jitter).
+
+@item long int stbcnt
+This counter denotes the number of calibrations where the stability
+exceeded the threshold.
+@end table
+@end deftp
+
+@comment sys/timex.h
+@comment GNU
+@deftypefun int ntp_adjtime (struct timex *@var{tptr})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias to adjtimex syscall.
+The @code{ntp_adjtime} function sets the structure specified by
+@var{tptr} to current values.
+
+In addition, @code{ntp_adjtime} updates some settings to match what you
+pass to it in *@var{tptr}.  Use the @code{modes} element of *@var{tptr}
+to select what settings to update.  You can set @code{offset},
+@code{freq}, @code{maxerror}, @code{esterror}, @code{status},
+@code{constant}, and @code{tick}.
+
+@code{modes} = zero means set nothing.
+
+Only the superuser can update settings.
+
+@c On Linux, ntp_adjtime() also does the adjtime() function if you set
+@c modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc implements
+@c adjtime()).  But this should be considered an internal function because
+@c it's so inconsistent with the rest of what ntp_adjtime() does and is
+@c forced in an ugly way into the struct timex.  So we don't document it
+@c and instead document adjtime() as the way to achieve the function.
+
+The return value is @code{0} on success and other values on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item TIME_ERROR
+The high accuracy clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care.  Another reason could be that the specified new values
+are not allowed.
+
+@item EPERM
+The process specified a settings update, but is not superuser.
+
+@end table
+
+For more details see RFC1305 (Network Time Protocol, Version 3) and
+related documents.
+
+@strong{Portability note:} Early versions of @theglibc{} did not
+have this function but did have the synonymous @code{adjtimex}.
+
+@end deftypefun
+
+
+@node Formatting Calendar Time
+@subsection Formatting Calendar Time
+
+The functions described in this section format calendar time values as
+strings.  These functions are declared in the header file @file{time.h}.
+@pindex time.h
+
+@comment time.h
+@comment ISO
+@deftypefun {char *} asctime (const struct tm *@var{brokentime})
+@safety{@prelim{}@mtunsafe{@mtasurace{:asctime} @mtslocale{}}@asunsafe{}@acsafe{}}
+@c asctime @mtasurace:asctime @mtslocale
+@c   Uses a static buffer.
+@c  asctime_internal @mtslocale
+@c   snprintf dup @mtslocale [no @acsuheap @acsmem]
+@c   ab_day_name @mtslocale
+@c   ab_month_name @mtslocale
+The @code{asctime} function converts the broken-down time value that
+@var{brokentime} points to into a string in a standard format:
+
+@smallexample
+"Tue May 21 13:46:22 1991\n"
+@end smallexample
+
+The abbreviations for the days of week are: @samp{Sun}, @samp{Mon},
+@samp{Tue}, @samp{Wed}, @samp{Thu}, @samp{Fri}, and @samp{Sat}.
+
+The abbreviations for the months are: @samp{Jan}, @samp{Feb},
+@samp{Mar}, @samp{Apr}, @samp{May}, @samp{Jun}, @samp{Jul}, @samp{Aug},
+@samp{Sep}, @samp{Oct}, @samp{Nov}, and @samp{Dec}.
+
+The return value points to a statically allocated string, which might be
+overwritten by subsequent calls to @code{asctime} or @code{ctime}.
+(But no other library function overwrites the contents of this
+string.)
+@end deftypefun
+
+@comment time.h
+@comment POSIX.1c
+@deftypefun {char *} asctime_r (const struct tm *@var{brokentime}, char *@var{buffer})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+@c asctime_r @mtslocale
+@c  asctime_internal dup @mtslocale
+This function is similar to @code{asctime} but instead of placing the
+result in a static buffer it writes the string in the buffer pointed to
+by the parameter @var{buffer}.  This buffer should have room
+for at least 26 bytes, including the terminating null.
+
+If no error occurred the function returns a pointer to the string the
+result was written into, i.e., it returns @var{buffer}.  Otherwise
+return @code{NULL}.
+@end deftypefun
+
+
+@comment time.h
+@comment ISO
+@deftypefun {char *} ctime (const time_t *@var{time})
+@safety{@prelim{}@mtunsafe{@mtasurace{:tmbuf} @mtasurace{:asctime} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c ctime @mtasurace:tmbuf @mtasurace:asctime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  localtime dup @mtasurace:tmbuf @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  asctime dup @mtasurace:asctime @mtslocale
+The @code{ctime} function is similar to @code{asctime}, except that you
+specify the calendar time argument as a @code{time_t} simple time value
+rather than in broken-down local time format.  It is equivalent to
+
+@smallexample
+asctime (localtime (@var{time}))
+@end smallexample
+
+Calling @code{ctime} also sets the current time zone as if
+@code{tzset} were called.  @xref{Time Zone Functions}.
+@end deftypefun
+
+@comment time.h
+@comment POSIX.1c
+@deftypefun {char *} ctime_r (const time_t *@var{time}, char *@var{buffer})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c ctime_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  asctime_r dup @mtslocale
+This function is similar to @code{ctime}, but places the result in the
+string pointed to by @var{buffer}.  It is equivalent to (written using
+gcc extensions, @pxref{Statement Exprs,,,gcc,Porting and Using gcc}):
+
+@smallexample
+(@{ struct tm tm; asctime_r (localtime_r (time, &tm), buf); @})
+@end smallexample
+
+If no error occurred the function returns a pointer to the string the
+result was written into, i.e., it returns @var{buffer}.  Otherwise
+return @code{NULL}.
+@end deftypefun
+
+
+@comment time.h
+@comment ISO
+@deftypefun size_t strftime (char *@var{s}, size_t @var{size}, const char *@var{template}, const struct tm *@var{brokentime})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c strftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  strftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   strftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    add ok
+@c     memset_zero dup ok
+@c     memset_space dup ok
+@c    strlen dup ok
+@c    mbrlen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
+@c    mbsinit dup ok
+@c    cpy ok
+@c     add dup ok
+@c     memcpy_lowcase ok
+@c      TOLOWER ok
+@c       tolower_l ok
+@c     memcpy_uppcase ok
+@c      TOUPPER ok
+@c       toupper_l ok
+@c     MEMCPY ok
+@c      memcpy dup ok
+@c    ISDIGIT ok
+@c    STRLEN ok
+@c     strlen dup ok
+@c    strftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    TOUPPER dup ok
+@c    nl_get_era_entry @ascuheap @asulock @acsmem @aculock
+@c     nl_init_era_entries @ascuheap @asulock @acsmem @aculock
+@c      libc_rwlock_wrlock dup @asulock @aculock
+@c      malloc dup @ascuheap @acsmem
+@c      memset dup ok
+@c      free dup @ascuheap @acsmem
+@c      realloc dup @ascuheap @acsmem
+@c      memcpy dup ok
+@c      strchr dup ok
+@c      wcschr dup ok
+@c      libc_rwlock_unlock dup @asulock @aculock
+@c     ERA_DATE_CMP ok
+@c    DO_NUMBER ok
+@c    DO_NUMBER_SPACEPAD ok
+@c    nl_get_alt_digit @ascuheap @asulock @acsmem @aculock
+@c     libc_rwlock_wrlock dup @asulock @aculock
+@c     nl_init_alt_digit @ascuheap @acsmem
+@c      malloc dup @ascuheap @acsmem
+@c      memset dup ok
+@c      strchr dup ok
+@c     libc_rwlock_unlock dup @aculock
+@c    memset_space ok
+@c     memset dup ok
+@c    memset_zero ok
+@c     memset dup ok
+@c    mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    iso_week_days ok
+@c    isleap ok
+@c    tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    tm_diff ok
+This function is similar to the @code{sprintf} function (@pxref{Formatted
+Input}), but the conversion specifications that can appear in the format
+template @var{template} are specialized for printing components of the date
+and time @var{brokentime} according to the locale currently specified for
+time conversion (@pxref{Locales}) and the current time zone
+(@pxref{Time Zone Functions}).
+
+Ordinary characters appearing in the @var{template} are copied to the
+output string @var{s}; this can include multibyte character sequences.
+Conversion specifiers are introduced by a @samp{%} character, followed
+by an optional flag which can be one of the following.  These flags
+are all GNU extensions.  The first three affect only the output of
+numbers:
+
+@table @code
+@item _
+The number is padded with spaces.
+
+@item -
+The number is not padded at all.
+
+@item 0
+The number is padded with zeros even if the format specifies padding
+with spaces.
+
+@item ^
+The output uses uppercase characters, but only if this is possible
+(@pxref{Case Conversion}).
+@end table
+
+The default action is to pad the number with zeros to keep it a constant
+width.  Numbers that do not have a range indicated below are never
+padded, since there is no natural width for them.
+
+Following the flag an optional specification of the width is possible.
+This is specified in decimal notation.  If the natural size of the
+output is of the field has less than the specified number of characters,
+the result is written right adjusted and space padded to the given
+size.
+
+An optional modifier can follow the optional flag and width
+specification.  The modifiers, which were first standardized by
+POSIX.2-1992 and by @w{ISO C99}, are:
+
+@table @code
+@item E
+Use the locale's alternate representation for date and time.  This
+modifier applies to the @code{%c}, @code{%C}, @code{%x}, @code{%X},
+@code{%y} and @code{%Y} format specifiers.  In a Japanese locale, for
+example, @code{%Ex} might yield a date format based on the Japanese
+Emperors' reigns.
+
+@item O
+Use the locale's alternate numeric symbols for numbers.  This modifier
+applies only to numeric format specifiers.
+@end table
+
+If the format supports the modifier but no alternate representation
+is available, it is ignored.
+
+The conversion specifier ends with a format specifier taken from the
+following list.  The whole @samp{%} sequence is replaced in the output
+string as follows:
+
+@table @code
+@item %a
+The abbreviated weekday name according to the current locale.
+
+@item %A
+The full weekday name according to the current locale.
+
+@item %b
+The abbreviated month name according to the current locale.
+
+@item %B
+The full month name according to the current locale.
+
+Using @code{%B} together with @code{%d} produces grammatically
+incorrect results for some locales.
+
+@item %c
+The preferred calendar time representation for the current locale.
+
+@item %C
+The century of the year.  This is equivalent to the greatest integer not
+greater than the year divided by 100.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %d
+The day of the month as a decimal number (range @code{01} through @code{31}).
+
+@item %D
+The date using the format @code{%m/%d/%y}.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %e
+The day of the month like with @code{%d}, but padded with blank (range
+@code{ 1} through @code{31}).
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %F
+The date using the format @code{%Y-%m-%d}.  This is the form specified
+in the @w{ISO 8601} standard and is the preferred form for all uses.
+
+This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
+
+@item %g
+The year corresponding to the ISO week number, but without the century
+(range @code{00} through @code{99}).  This has the same format and value
+as @code{%y}, except that if the ISO week number (see @code{%V}) belongs
+to the previous or next year, that year is used instead.
+
+This format was first standardized by @w{ISO C99} and by POSIX.1-2001.
+
+@item %G
+The year corresponding to the ISO week number.  This has the same format
+and value as @code{%Y}, except that if the ISO week number (see
+@code{%V}) belongs to the previous or next year, that year is used
+instead.
+
+This format was first standardized by @w{ISO C99} and by POSIX.1-2001
+but was previously available as a GNU extension.
+
+@item %h
+The abbreviated month name according to the current locale.  The action
+is the same as for @code{%b}.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %H
+The hour as a decimal number, using a 24-hour clock (range @code{00} through
+@code{23}).
+
+@item %I
+The hour as a decimal number, using a 12-hour clock (range @code{01} through
+@code{12}).
+
+@item %j
+The day of the year as a decimal number (range @code{001} through @code{366}).
+
+@item %k
+The hour as a decimal number, using a 24-hour clock like @code{%H}, but
+padded with blank (range @code{ 0} through @code{23}).
+
+This format is a GNU extension.
+
+@item %l
+The hour as a decimal number, using a 12-hour clock like @code{%I}, but
+padded with blank (range @code{ 1} through @code{12}).
+
+This format is a GNU extension.
+
+@item %m
+The month as a decimal number (range @code{01} through @code{12}).
+
+@item %M
+The minute as a decimal number (range @code{00} through @code{59}).
+
+@item %n
+A single @samp{\n} (newline) character.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %p
+Either @samp{AM} or @samp{PM}, according to the given time value; or the
+corresponding strings for the current locale.  Noon is treated as
+@samp{PM} and midnight as @samp{AM}.  In most locales
+@samp{AM}/@samp{PM} format is not supported, in such cases @code{"%p"}
+yields an empty string.
+
+@ignore
+We currently have a problem with makeinfo.  Write @samp{AM} and @samp{am}
+both results in `am'.  I.e., the difference in case is not visible anymore.
+@end ignore
+@item %P
+Either @samp{am} or @samp{pm}, according to the given time value; or the
+corresponding strings for the current locale, printed in lowercase
+characters.  Noon is treated as @samp{pm} and midnight as @samp{am}.  In
+most locales @samp{AM}/@samp{PM} format is not supported, in such cases
+@code{"%P"} yields an empty string.
+
+This format is a GNU extension.
+
+@item %r
+The complete calendar time using the AM/PM format of the current locale.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+In the POSIX locale, this format is equivalent to @code{%I:%M:%S %p}.
+
+@item %R
+The hour and minute in decimal numbers using the format @code{%H:%M}.
+
+This format was first standardized by @w{ISO C99} and by POSIX.1-2001
+but was previously available as a GNU extension.
+
+@item %s
+The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
+Leap seconds are not counted unless leap second support is available.
+
+This format is a GNU extension.
+
+@item %S
+The seconds as a decimal number (range @code{00} through @code{60}).
+
+@item %t
+A single @samp{\t} (tabulator) character.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %T
+The time of day using decimal numbers using the format @code{%H:%M:%S}.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %u
+The day of the week as a decimal number (range @code{1} through
+@code{7}), Monday being @code{1}.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %U
+The week number of the current year as a decimal number (range @code{00}
+through @code{53}), starting with the first Sunday as the first day of
+the first week.  Days preceding the first Sunday in the year are
+considered to be in week @code{00}.
+
+@item %V
+The @w{ISO 8601:1988} week number as a decimal number (range @code{01}
+through @code{53}).  ISO weeks start with Monday and end with Sunday.
+Week @code{01} of a year is the first week which has the majority of its
+days in that year; this is equivalent to the week containing the year's
+first Thursday, and it is also equivalent to the week containing January
+4.  Week @code{01} of a year can contain days from the previous year.
+The week before week @code{01} of a year is the last week (@code{52} or
+@code{53}) of the previous year even if it contains days from the new
+year.
+
+This format was first standardized by POSIX.2-1992 and by @w{ISO C99}.
+
+@item %w
+The day of the week as a decimal number (range @code{0} through
+@code{6}), Sunday being @code{0}.
+
+@item %W
+The week number of the current year as a decimal number (range @code{00}
+through @code{53}), starting with the first Monday as the first day of
+the first week.  All days preceding the first Monday in the year are
+considered to be in week @code{00}.
+
+@item %x
+The preferred date representation for the current locale.
+
+@item %X
+The preferred time of day representation for the current locale.
+
+@item %y
+The year without a century as a decimal number (range @code{00} through
+@code{99}).  This is equivalent to the year modulo 100.
+
+@item %Y
+The year as a decimal number, using the Gregorian calendar.  Years
+before the year @code{1} are numbered @code{0}, @code{-1}, and so on.
+
+@item %z
+@w{RFC 822}/@w{ISO 8601:1988} style numeric time zone (e.g.,
+@code{-0600} or @code{+0100}), or nothing if no time zone is
+determinable.
+
+This format was first standardized by @w{ISO C99} and by POSIX.1-2001
+but was previously available as a GNU extension.
+
+In the POSIX locale, a full @w{RFC 822} timestamp is generated by the format
+@w{@samp{"%a, %d %b %Y %H:%M:%S %z"}} (or the equivalent
+@w{@samp{"%a, %d %b %Y %T %z"}}).
+
+@item %Z
+The time zone abbreviation (empty if the time zone can't be determined).
+
+@item %%
+A literal @samp{%} character.
+@end table
+
+The @var{size} parameter can be used to specify the maximum number of
+characters to be stored in the array @var{s}, including the terminating
+null character.  If the formatted time requires more than @var{size}
+characters, @code{strftime} returns zero and the contents of the array
+@var{s} are undefined.  Otherwise the return value indicates the
+number of characters placed in the array @var{s}, not including the
+terminating null character.
+
+@emph{Warning:} This convention for the return value which is prescribed
+in @w{ISO C} can lead to problems in some situations.  For certain
+format strings and certain locales the output really can be the empty
+string and this cannot be discovered by testing the return value only.
+E.g., in most locales the AM/PM time format is not supported (most of
+the world uses the 24 hour time representation).  In such locales
+@code{"%p"} will return the empty string, i.e., the return value is
+zero.  To detect situations like this something similar to the following
+code should be used:
+
+@smallexample
+buf[0] = '\1';
+len = strftime (buf, bufsize, format, tp);
+if (len == 0 && buf[0] != '\0')
+  @{
+    /* Something went wrong in the strftime call.  */
+    @dots{}
+  @}
+@end smallexample
+
+If @var{s} is a null pointer, @code{strftime} does not actually write
+anything, but instead returns the number of characters it would have written.
+
+Calling @code{strftime} also sets the current time zone as if
+@code{tzset} were called; @code{strftime} uses this information
+instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone}
+members.  @xref{Time Zone Functions}.
+
+For an example of @code{strftime}, see @ref{Time Functions Example}.
+@end deftypefun
+
+@comment time.h
+@comment ISO/Amend1
+@deftypefun size_t wcsftime (wchar_t *@var{s}, size_t @var{size}, const wchar_t *@var{template}, const struct tm *@var{brokentime})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c wcsftime @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c  wcsftime_l @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c   wcsftime_internal @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    add ok
+@c     memset_zero dup ok
+@c     memset_space dup ok
+@c    wcslen dup ok
+@c    cpy ok
+@c     add dup ok
+@c     memcpy_lowcase ok
+@c      TOLOWER ok
+@c       towlower_l dup ok
+@c     memcpy_uppcase ok
+@c      TOUPPER ok
+@c       towupper_l dup ok
+@c     MEMCPY ok
+@c      wmemcpy dup ok
+@c    widen @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c     memset dup ok
+@c     mbsrtowcs_l @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd [no @mtasurace:mbstate/!ps]
+@c    ISDIGIT ok
+@c    STRLEN ok
+@c     wcslen dup ok
+@c    wcsftime_internal dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c    TOUPPER dup ok
+@c    nl_get_era_entry dup @ascuheap @asulock @acsmem @aculock
+@c    DO_NUMBER ok
+@c    DO_NUMBER_SPACEPAD ok
+@c    nl_get_walt_digit dup @ascuheap @asulock @acsmem @aculock
+@c     libc_rwlock_wrlock dup @asulock @aculock
+@c     nl_init_alt_digit dup @ascuheap @acsmem
+@c     malloc dup @ascuheap @acsmem
+@c     memset dup ok
+@c     wcschr dup ok
+@c     libc_rwlock_unlock dup @aculock
+@c    memset_space ok
+@c     wmemset dup ok
+@c    memset_zero ok
+@c     wmemset dup ok
+@c    mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    iso_week_days ok
+@c    isleap ok
+@c    tzset dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    gmtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    tm_diff ok
+The @code{wcsftime} function is equivalent to the @code{strftime}
+function with the difference that it operates on wide character
+strings.  The buffer where the result is stored, pointed to by @var{s},
+must be an array of wide characters.  The parameter @var{size} which
+specifies the size of the output buffer gives the number of wide
+character, not the number of bytes.
+
+Also the format string @var{template} is a wide character string.  Since
+all characters needed to specify the format string are in the basic
+character set it is portably possible to write format strings in the C
+source code using the @code{L"@dots{}"} notation.  The parameter
+@var{brokentime} has the same meaning as in the @code{strftime} call.
+
+The @code{wcsftime} function supports the same flags, modifiers, and
+format specifiers as the @code{strftime} function.
+
+The return value of @code{wcsftime} is the number of wide characters
+stored in @code{s}.  When more characters would have to be written than
+can be placed in the buffer @var{s} the return value is zero, with the
+same problems indicated in the @code{strftime} documentation.
+@end deftypefun
+
+@node Parsing Date and Time
+@subsection Convert textual time and date information back
+
+The @w{ISO C} standard does not specify any functions which can convert
+the output of the @code{strftime} function back into a binary format.
+This led to a variety of more-or-less successful implementations with
+different interfaces over the years.  Then the Unix standard was
+extended by the addition of two functions: @code{strptime} and
+@code{getdate}.  Both have strange interfaces but at least they are
+widely available.
+
+@menu
+* Low-Level Time String Parsing::  Interpret string according to given format.
+* General Time String Parsing::    User-friendly function to parse data and
+                                    time strings.
+@end menu
+
+@node Low-Level Time String Parsing
+@subsubsection Interpret string according to given format
+
+The first function is rather low-level.  It is nevertheless frequently
+used in software since it is better known.  Its interface and
+implementation are heavily influenced by the @code{getdate} function,
+which is defined and implemented in terms of calls to @code{strptime}.
+
+@comment time.h
+@comment XPG4
+@deftypefun {char *} strptime (const char *@var{s}, const char *@var{fmt}, struct tm *@var{tp})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c strptime @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  strptime_internal @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   memset dup ok
+@c   ISSPACE ok
+@c    isspace_l dup ok
+@c   match_char ok
+@c   match_string ok
+@c    strlen dup ok
+@c    strncasecmp_l dup ok
+@c   strcmp dup ok
+@c   recursive @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c    strptime_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   get_number ok
+@c    ISSPACE dup ok
+@c   localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   nl_select_era_entry @ascuheap @asulock @acsmem @aculock
+@c    nl_init_era_entries dup @ascuheap @asulock @acsmem @aculock
+@c   get_alt_number dup @ascuheap @asulock @acsmem @aculock
+@c    nl_parse_alt_digit dup @ascuheap @asulock @acsmem @aculock
+@c     libc_rwlock_wrlock dup @asulock @aculock
+@c     nl_init_alt_digit dup @ascuheap @acsmem
+@c     libc_rwlock_unlock dup @aculock
+@c    get_number dup ok
+@c   day_of_the_week ok
+@c   day_of_the_year ok
+The @code{strptime} function parses the input string @var{s} according
+to the format string @var{fmt} and stores its results in the
+structure @var{tp}.
+
+The input string could be generated by a @code{strftime} call or
+obtained any other way.  It does not need to be in a human-recognizable
+format; e.g. a date passed as @code{"02:1999:9"} is acceptable, even
+though it is ambiguous without context.  As long as the format string
+@var{fmt} matches the input string the function will succeed.
+
+The user has to make sure, though, that the input can be parsed in a
+unambiguous way.  The string @code{"1999112"} can be parsed using the
+format @code{"%Y%m%d"} as 1999-1-12, 1999-11-2, or even 19991-1-2.  It
+is necessary to add appropriate separators to reliably get results.
+
+The format string consists of the same components as the format string
+of the @code{strftime} function.  The only difference is that the flags
+@code{_}, @code{-}, @code{0}, and @code{^} are not allowed.
+@comment Is this really the intention?  --drepper
+Several of the distinct formats of @code{strftime} do the same work in
+@code{strptime} since differences like case of the input do not matter.
+For reasons of symmetry all formats are supported, though.
+
+The modifiers @code{E} and @code{O} are also allowed everywhere the
+@code{strftime} function allows them.
+
+The formats are:
+
+@table @code
+@item %a
+@itemx %A
+The weekday name according to the current locale, in abbreviated form or
+the full name.
+
+@item %b
+@itemx %B
+@itemx %h
+The month name according to the current locale, in abbreviated form or
+the full name.
+
+@item %c
+The date and time representation for the current locale.
+
+@item %Ec
+Like @code{%c} but the locale's alternative date and time format is used.
+
+@item %C
+The century of the year.
+
+It makes sense to use this format only if the format string also
+contains the @code{%y} format.
+
+@item %EC
+The locale's representation of the period.
+
+Unlike @code{%C} it sometimes makes sense to use this format since some
+cultures represent years relative to the beginning of eras instead of
+using the Gregorian years.
+
+@item %d
+@item %e
+The day of the month as a decimal number (range @code{1} through @code{31}).
+Leading zeroes are permitted but not required.
+
+@item %Od
+@itemx %Oe
+Same as @code{%d} but using the locale's alternative numeric symbols.
+
+Leading zeroes are permitted but not required.
+
+@item %D
+Equivalent to @code{%m/%d/%y}.
+
+@item %F
+Equivalent to @code{%Y-%m-%d}, which is the @w{ISO 8601} date
+format.
+
+This is a GNU extension following an @w{ISO C99} extension to
+@code{strftime}.
+
+@item %g
+The year corresponding to the ISO week number, but without the century
+(range @code{00} through @code{99}).
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+This format is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %G
+The year corresponding to the ISO week number.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+This format is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %H
+@itemx %k
+The hour as a decimal number, using a 24-hour clock (range @code{00} through
+@code{23}).
+
+@code{%k} is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %OH
+Same as @code{%H} but using the locale's alternative numeric symbols.
+
+@item %I
+@itemx %l
+The hour as a decimal number, using a 12-hour clock (range @code{01} through
+@code{12}).
+
+@code{%l} is a GNU extension following a GNU extension of @code{strftime}.
+
+@item %OI
+Same as @code{%I} but using the locale's alternative numeric symbols.
+
+@item %j
+The day of the year as a decimal number (range @code{1} through @code{366}).
+
+Leading zeroes are permitted but not required.
+
+@item %m
+The month as a decimal number (range @code{1} through @code{12}).
+
+Leading zeroes are permitted but not required.
+
+@item %Om
+Same as @code{%m} but using the locale's alternative numeric symbols.
+
+@item %M
+The minute as a decimal number (range @code{0} through @code{59}).
+
+Leading zeroes are permitted but not required.
+
+@item %OM
+Same as @code{%M} but using the locale's alternative numeric symbols.
+
+@item %n
+@itemx %t
+Matches any white space.
+
+@item %p
+@item %P
+The locale-dependent equivalent to @samp{AM} or @samp{PM}.
+
+This format is not useful unless @code{%I} or @code{%l} is also used.
+Another complication is that the locale might not define these values at
+all and therefore the conversion fails.
+
+@code{%P} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %r
+The complete time using the AM/PM format of the current locale.
+
+A complication is that the locale might not define this format at all
+and therefore the conversion fails.
+
+@item %R
+The hour and minute in decimal numbers using the format @code{%H:%M}.
+
+@code{%R} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %s
+The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
+Leap seconds are not counted unless leap second support is available.
+
+@code{%s} is a GNU extension following a GNU extension to @code{strftime}.
+
+@item %S
+The seconds as a decimal number (range @code{0} through @code{60}).
+
+Leading zeroes are permitted but not required.
+
+@strong{NB:} The Unix specification says the upper bound on this value
+is @code{61}, a result of a decision to allow double leap seconds.  You
+will not see the value @code{61} because no minute has more than one
+leap second, but the myth persists.
+
+@item %OS
+Same as @code{%S} but using the locale's alternative numeric symbols.
+
+@item %T
+Equivalent to the use of @code{%H:%M:%S} in this place.
+
+@item %u
+The day of the week as a decimal number (range @code{1} through
+@code{7}), Monday being @code{1}.
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %U
+The week number of the current year as a decimal number (range @code{0}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@item %OU
+Same as @code{%U} but using the locale's alternative numeric symbols.
+
+@item %V
+The @w{ISO 8601:1988} week number as a decimal number (range @code{1}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %w
+The day of the week as a decimal number (range @code{0} through
+@code{6}), Sunday being @code{0}.
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %Ow
+Same as @code{%w} but using the locale's alternative numeric symbols.
+
+@item %W
+The week number of the current year as a decimal number (range @code{0}
+through @code{53}).
+
+Leading zeroes are permitted but not required.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %OW
+Same as @code{%W} but using the locale's alternative numeric symbols.
+
+@item %x
+The date using the locale's date format.
+
+@item %Ex
+Like @code{%x} but the locale's alternative data representation is used.
+
+@item %X
+The time using the locale's time format.
+
+@item %EX
+Like @code{%X} but the locale's alternative time representation is used.
+
+@item %y
+The year without a century as a decimal number (range @code{0} through
+@code{99}).
+
+Leading zeroes are permitted but not required.
+
+Note that it is questionable to use this format without
+the @code{%C} format.  The @code{strptime} function does regard input
+values in the range @math{68} to @math{99} as the years @math{1969} to
+@math{1999} and the values @math{0} to @math{68} as the years
+@math{2000} to @math{2068}.  But maybe this heuristic fails for some
+input data.
+
+Therefore it is best to avoid @code{%y} completely and use @code{%Y}
+instead.
+
+@item %Ey
+The offset from @code{%EC} in the locale's alternative representation.
+
+@item %Oy
+The offset of the year (from @code{%C}) using the locale's alternative
+numeric symbols.
+
+@item %Y
+The year as a decimal number, using the Gregorian calendar.
+
+@item %EY
+The full alternative year representation.
+
+@item %z
+The offset from GMT in @w{ISO 8601}/RFC822 format.
+
+@item %Z
+The timezone name.
+
+@emph{Note:} Currently, this is not fully implemented.  The format is
+recognized, input is consumed but no field in @var{tm} is set.
+
+@item %%
+A literal @samp{%} character.
+@end table
+
+All other characters in the format string must have a matching character
+in the input string.  Exceptions are white spaces in the input string
+which can match zero or more whitespace characters in the format string.
+
+@strong{Portability Note:} The XPG standard advises applications to use
+at least one whitespace character (as specified by @code{isspace}) or
+other non-alphanumeric characters between any two conversion
+specifications.  @Theglibc{} does not have this limitation but
+other libraries might have trouble parsing formats like
+@code{"%d%m%Y%H%M%S"}.
+
+The @code{strptime} function processes the input string from right to
+left.  Each of the three possible input elements (white space, literal,
+or format) are handled one after the other.  If the input cannot be
+matched to the format string the function stops.  The remainder of the
+format and input strings are not processed.
+
+The function returns a pointer to the first character it was unable to
+process.  If the input string contains more characters than required by
+the format string the return value points right after the last consumed
+input character.  If the whole input string is consumed the return value
+points to the @code{NULL} byte at the end of the string.  If an error
+occurs, i.e., @code{strptime} fails to match all of the format string,
+the function returns @code{NULL}.
+@end deftypefun
+
+The specification of the function in the XPG standard is rather vague,
+leaving out a few important pieces of information.  Most importantly, it
+does not specify what happens to those elements of @var{tm} which are
+not directly initialized by the different formats.  The
+implementations on different Unix systems vary here.
+
+The @glibcadj{} implementation does not touch those fields which are not
+directly initialized.  Exceptions are the @code{tm_wday} and
+@code{tm_yday} elements, which are recomputed if any of the year, month,
+or date elements changed.  This has two implications:
+
+@itemize @bullet
+@item
+Before calling the @code{strptime} function for a new input string, you
+should prepare the @var{tm} structure you pass.  Normally this will mean
+initializing all values are to zero.  Alternatively, you can set all
+fields to values like @code{INT_MAX}, allowing you to determine which
+elements were set by the function call.  Zero does not work here since
+it is a valid value for many of the fields.
+
+Careful initialization is necessary if you want to find out whether a
+certain field in @var{tm} was initialized by the function call.
+
+@item
+You can construct a @code{struct tm} value with several consecutive
+@code{strptime} calls.  A useful application of this is e.g. the parsing
+of two separate strings, one containing date information and the other
+time information.  By parsing one after the other without clearing the
+structure in-between, you can construct a complete broken-down time.
+@end itemize
+
+The following example shows a function which parses a string which is
+contains the date information in either US style or @w{ISO 8601} form:
+
+@smallexample
+const char *
+parse_date (const char *input, struct tm *tm)
+@{
+  const char *cp;
+
+  /* @r{First clear the result structure.}  */
+  memset (tm, '\0', sizeof (*tm));
+
+  /* @r{Try the ISO format first.}  */
+  cp = strptime (input, "%F", tm);
+  if (cp == NULL)
+    @{
+      /* @r{Does not match.  Try the US form.}  */
+      cp = strptime (input, "%D", tm);
+    @}
+
+  return cp;
+@}
+@end smallexample
+
+@node General Time String Parsing
+@subsubsection A More User-friendly Way to Parse Times and Dates
+
+The Unix standard defines another function for parsing date strings.
+The interface is weird, but if the function happens to suit your
+application it is just fine.  It is problematic to use this function
+in multi-threaded programs or libraries, since it returns a pointer to
+a static variable, and uses a global variable and global state (an
+environment variable).
+
+@comment time.h
+@comment Unix98
+@defvar getdate_err
+This variable of type @code{int} contains the error code of the last
+unsuccessful call to @code{getdate}.  Defined values are:
+
+@table @math
+@item 1
+The environment variable @code{DATEMSK} is not defined or null.
+@item 2
+The template file denoted by the @code{DATEMSK} environment variable
+cannot be opened.
+@item 3
+Information about the template file cannot retrieved.
+@item 4
+The template file is not a regular file.
+@item 5
+An I/O error occurred while reading the template file.
+@item 6
+Not enough memory available to execute the function.
+@item 7
+The template file contains no matching template.
+@item 8
+The input date is invalid, but would match a template otherwise.  This
+includes dates like February 31st, and dates which cannot be represented
+in a @code{time_t} variable.
+@end table
+@end defvar
+
+@comment time.h
+@comment Unix98
+@deftypefun {struct tm *} getdate (const char *@var{string})
+@safety{@prelim{}@mtunsafe{@mtasurace{:getdate} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c getdate @mtasurace:getdate @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  getdate_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+The interface to @code{getdate} is the simplest possible for a function
+to parse a string and return the value.  @var{string} is the input
+string and the result is returned in a statically-allocated variable.
+
+The details about how the string is processed are hidden from the user.
+In fact, they can be outside the control of the program.  Which formats
+are recognized is controlled by the file named by the environment
+variable @code{DATEMSK}.  This file should contain
+lines of valid format strings which could be passed to @code{strptime}.
+
+The @code{getdate} function reads these format strings one after the
+other and tries to match the input string.  The first line which
+completely matches the input string is used.
+
+Elements not initialized through the format string retain the values
+present at the time of the @code{getdate} function call.
+
+The formats recognized by @code{getdate} are the same as for
+@code{strptime}.  See above for an explanation.  There are only a few
+extensions to the @code{strptime} behavior:
+
+@itemize @bullet
+@item
+If the @code{%Z} format is given the broken-down time is based on the
+current time of the timezone matched, not of the current timezone of the
+runtime environment.
+
+@emph{Note}: This is not implemented (currently).  The problem is that
+timezone names are not unique.  If a fixed timezone is assumed for a
+given string (say @code{EST} meaning US East Coast time), then uses for
+countries other than the USA will fail.  So far we have found no good
+solution to this.
+
+@item
+If only the weekday is specified the selected day depends on the current
+date.  If the current weekday is greater or equal to the @code{tm_wday}
+value the current week's day is chosen, otherwise the day next week is chosen.
+
+@item
+A similar heuristic is used when only the month is given and not the
+year.  If the month is greater than or equal to the current month, then
+the current year is used.  Otherwise it wraps to next year.  The first
+day of the month is assumed if one is not explicitly specified.
+
+@item
+The current hour, minute, and second are used if the appropriate value is
+not set through the format.
+
+@item
+If no date is given tomorrow's date is used if the time is
+smaller than the current time.  Otherwise today's date is taken.
+@end itemize
+
+It should be noted that the format in the template file need not only
+contain format elements.  The following is a list of possible format
+strings (taken from the Unix standard):
+
+@smallexample
+%m
+%A %B %d, %Y %H:%M:%S
+%A
+%B
+%m/%d/%y %I %p
+%d,%m,%Y %H:%M
+at %A the %dst of %B in %Y
+run job at %I %p,%B %dnd
+%A den %d. %B %Y %H.%M Uhr
+@end smallexample
+
+As you can see, the template list can contain very specific strings like
+@code{run job at %I %p,%B %dnd}.  Using the above list of templates and
+assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the
+following results for the given input.
+
+@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item        Input @tab     Match @tab Result
+@item        Mon @tab       %a @tab    Mon Sep 22 12:19:47 EDT 1986
+@item        Sun @tab       %a @tab    Sun Sep 28 12:19:47 EDT 1986
+@item        Fri @tab       %a @tab    Fri Sep 26 12:19:47 EDT 1986
+@item        September @tab %B @tab    Mon Sep 1 12:19:47 EDT 1986
+@item        January @tab   %B @tab    Thu Jan 1 12:19:47 EST 1987
+@item        December @tab  %B @tab    Mon Dec 1 12:19:47 EST 1986
+@item        Sep Mon @tab   %b %a @tab Mon Sep 1 12:19:47 EDT 1986
+@item        Jan Fri @tab   %b %a @tab Fri Jan 2 12:19:47 EST 1987
+@item        Dec Mon @tab   %b %a @tab Mon Dec 1 12:19:47 EST 1986
+@item        Jan Wed 1989 @tab  %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989
+@item        Fri 9 @tab     %a %H @tab Fri Sep 26 09:00:00 EDT 1986
+@item        Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987
+@item        10:30 @tab     %H:%M @tab Tue Sep 23 10:30:00 EDT 1986
+@item        13:30 @tab     %H:%M @tab Mon Sep 22 13:30:00 EDT 1986
+@end multitable
+
+The return value of the function is a pointer to a static variable of
+type @w{@code{struct tm}}, or a null pointer if an error occurred.  The
+result is only valid until the next @code{getdate} call, making this
+function unusable in multi-threaded applications.
+
+The @code{errno} variable is @emph{not} changed.  Error conditions are
+stored in the global variable @code{getdate_err}.  See the
+description above for a list of the possible error values.
+
+@emph{Warning:} The @code{getdate} function should @emph{never} be
+used in SUID-programs.  The reason is obvious: using the
+@code{DATEMSK} environment variable you can get the function to open
+any arbitrary file and chances are high that with some bogus input
+(such as a binary file) the program will crash.
+@end deftypefun
+
+@comment time.h
+@comment GNU
+@deftypefun int getdate_r (const char *@var{string}, struct tm *@var{tp})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c getdate_r @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  getenv dup @mtsenv
+@c  stat64 dup ok
+@c  access dup ok
+@c  fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c  fsetlocking dup ok [no @mtasurace:stream @asulock, exclusive]
+@c  isspace dup @mtslocale
+@c  strlen dup ok
+@c  malloc dup @ascuheap @acsmem
+@c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  memcpy dup ok
+@c  getline dup @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt, exclusive]
+@c  strptime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  feof_unlocked dup ok
+@c  free dup @ascuheap @acsmem
+@c  ferror_unlocked dup dup ok
+@c  time dup ok
+@c  localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  first_wday @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c   memset dup ok
+@c   mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  check_mday ok
+@c  mktime dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+The @code{getdate_r} function is the reentrant counterpart of
+@code{getdate}.  It does not use the global variable @code{getdate_err}
+to signal an error, but instead returns an error code.  The same error
+codes as described in the @code{getdate_err} documentation above are
+used, with 0 meaning success.
+
+Moreover, @code{getdate_r} stores the broken-down time in the variable
+of type @code{struct tm} pointed to by the second argument, rather than
+in a static variable.
+
+This function is not defined in the Unix standard.  Nevertheless it is
+available on some other Unix systems as well.
+
+The warning against using @code{getdate} in SUID-programs applies to
+@code{getdate_r} as well.
+@end deftypefun
+
+@node TZ Variable
+@subsection Specifying the Time Zone with @code{TZ}
+
+In POSIX systems, a user can specify the time zone by means of the
+@code{TZ} environment variable.  For information about how to set
+environment variables, see @ref{Environment Variables}.  The functions
+for accessing the time zone are declared in @file{time.h}.
+@pindex time.h
+@cindex time zone
+
+You should not normally need to set @code{TZ}.  If the system is
+configured properly, the default time zone will be correct.  You might
+set @code{TZ} if you are using a computer over a network from a
+different time zone, and would like times reported to you in the time
+zone local to you, rather than what is local to the computer.
+
+In POSIX.1 systems the value of the @code{TZ} variable can be in one of
+three formats.  With @theglibc{}, the most common format is the
+last one, which can specify a selection from a large database of time
+zone information for many regions of the world.  The first two formats
+are used to describe the time zone information directly, which is both
+more cumbersome and less precise.  But the POSIX.1 standard only
+specifies the details of the first two formats, so it is good to be
+familiar with them in case you come across a POSIX.1 system that doesn't
+support a time zone information database.
+
+The first format is used when there is no Daylight Saving Time (or
+summer time) in the local time zone:
+
+@smallexample
+@r{@var{std} @var{offset}}
+@end smallexample
+
+The @var{std} string specifies the name of the time zone.  It must be
+three or more characters long and must not contain a leading colon,
+embedded digits, commas, nor plus and minus signs.  There is no space
+character separating the time zone name from the @var{offset}, so these
+restrictions are necessary to parse the specification correctly.
+
+The @var{offset} specifies the time value you must add to the local time
+to get a Coordinated Universal Time value.  It has syntax like
+[@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]].  This
+is positive if the local time zone is west of the Prime Meridian and
+negative if it is east.  The hour must be between @code{0} and
+@code{24}, and the minute and seconds between @code{0} and @code{59}.
+
+For example, here is how we would specify Eastern Standard Time, but
+without any Daylight Saving Time alternative:
+
+@smallexample
+EST+5
+@end smallexample
+
+The second format is used when there is Daylight Saving Time:
+
+@smallexample
+@r{@var{std} @var{offset} @var{dst} [@var{offset}]@code{,}@var{start}[@code{/}@var{time}]@code{,}@var{end}[@code{/}@var{time}]}
+@end smallexample
+
+The initial @var{std} and @var{offset} specify the standard time zone, as
+described above.  The @var{dst} string and @var{offset} specify the name
+and offset for the corresponding Daylight Saving Time zone; if the
+@var{offset} is omitted, it defaults to one hour ahead of standard time.
+
+The remainder of the specification describes when Daylight Saving Time is
+in effect.  The @var{start} field is when Daylight Saving Time goes into
+effect and the @var{end} field is when the change is made back to standard
+time.  The following formats are recognized for these fields:
+
+@table @code
+@item J@var{n}
+This specifies the Julian day, with @var{n} between @code{1} and @code{365}.
+February 29 is never counted, even in leap years.
+
+@item @var{n}
+This specifies the Julian day, with @var{n} between @code{0} and @code{365}.
+February 29 is counted in leap years.
+
+@item M@var{m}.@var{w}.@var{d}
+This specifies day @var{d} of week @var{w} of month @var{m}.  The day
+@var{d} must be between @code{0} (Sunday) and @code{6}.  The week
+@var{w} must be between @code{1} and @code{5}; week @code{1} is the
+first week in which day @var{d} occurs, and week @code{5} specifies the
+@emph{last} @var{d} day in the month.  The month @var{m} should be
+between @code{1} and @code{12}.
+@end table
+
+The @var{time} fields specify when, in the local time currently in
+effect, the change to the other time occurs.  If omitted, the default is
+@code{02:00:00}.  The hours part of the time fields can range from
+@minus{}167 through 167; this is an extension to POSIX.1, which allows
+only the range 0 through 24.
+
+Here are some example @code{TZ} values, including the appropriate
+Daylight Saving Time and its dates of applicability.  In North
+American Eastern Standard Time (EST) and Eastern Daylight Time (EDT),
+the normal offset from UTC is 5 hours; since this is
+west of the prime meridian, the sign is positive.  Summer time begins on
+March's second Sunday at 2:00am, and ends on November's first Sunday
+at 2:00am.
+
+@smallexample
+EST+5EDT,M3.2.0/2,M11.1.0/2
+@end smallexample
+
+Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours
+ahead of the prime meridian in winter, springing forward an hour on
+March's fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or
+after March 23), and falling back on October's last Sunday at 02:00.
+
+@smallexample
+IST-2IDT,M3.4.4/26,M10.5.0
+@end smallexample
+
+Western Argentina Summer Time (WARST) is 3 hours behind the prime
+meridian all year.  There is a dummy fall-back transition on December
+31 at 25:00 daylight saving time (i.e., 24:00 standard time,
+equivalent to January 1 at 00:00 standard time), and a simultaneous
+spring-forward transition on January 1 at 00:00 standard time, so
+daylight saving time is in effect all year and the initial @code{WART}
+is a placeholder.
+
+@smallexample
+WART4WARST,J1/0,J365/25
+@end smallexample
+
+Western Greenland Time (WGT) and Western Greenland Summer Time (WGST)
+are 3 hours behind UTC in the winter.  Its clocks follow the European
+Union rules of springing forward by one hour on March's last Sunday at
+01:00 UTC (@minus{}02:00 local time) and falling back on October's
+last Sunday at 01:00 UTC (@minus{}01:00 local time).
+
+@smallexample
+WGT3WGST,M3.5.0/-2,M10.5.0/-1
+@end smallexample
+
+The schedule of Daylight Saving Time in any particular jurisdiction has
+changed over the years.  To be strictly correct, the conversion of dates
+and times in the past should be based on the schedule that was in effect
+then.  However, this format has no facilities to let you specify how the
+schedule has changed from year to year.  The most you can do is specify
+one particular schedule---usually the present day schedule---and this is
+used to convert any date, no matter when.  For precise time zone
+specifications, it is best to use the time zone information database
+(see below).
+
+The third format looks like this:
+
+@smallexample
+:@var{characters}
+@end smallexample
+
+Each operating system interprets this format differently; in
+@theglibc{}, @var{characters} is the name of a file which describes the time
+zone.
+
+@pindex /etc/localtime
+@pindex localtime
+If the @code{TZ} environment variable does not have a value, the
+operation chooses a time zone by default.  In @theglibc{}, the
+default time zone is like the specification @samp{TZ=:/etc/localtime}
+(or @samp{TZ=:/usr/local/etc/localtime}, depending on how @theglibc{}
+was configured; @pxref{Installation}).  Other C libraries use their own
+rule for choosing the default time zone, so there is little we can say
+about them.
+
+@cindex time zone database
+@pindex /usr/share/zoneinfo
+@pindex zoneinfo
+If @var{characters} begins with a slash, it is an absolute file name;
+otherwise the library looks for the file
+@w{@file{/usr/share/zoneinfo/@var{characters}}}.  The @file{zoneinfo}
+directory contains data files describing local time zones in many
+different parts of the world.  The names represent major cities, with
+subdirectories for geographical areas; for example,
+@file{America/New_York}, @file{Europe/London}, @file{Asia/Hong_Kong}.
+These data files are installed by the system administrator, who also
+sets @file{/etc/localtime} to point to the data file for the local time
+zone.  The files typically come from the @url{http://www.iana.org/time-zones,
+Time Zone Database} of time zone and daylight saving time
+information for most regions of the world, which is maintained by a
+community of volunteers and put in the public domain.
+
+@node Time Zone Functions
+@subsection Functions and Variables for Time Zones
+
+@comment time.h
+@comment POSIX.1
+@deftypevar {char *} tzname [2]
+The array @code{tzname} contains two strings, which are the standard
+names of the pair of time zones (standard and Daylight
+Saving) that the user has selected.  @code{tzname[0]} is the name of
+the standard time zone (for example, @code{"EST"}), and @code{tzname[1]}
+is the name for the time zone when Daylight Saving Time is in use (for
+example, @code{"EDT"}).  These correspond to the @var{std} and @var{dst}
+strings (respectively) from the @code{TZ} environment variable.  If
+Daylight Saving Time is never used, @code{tzname[1]} is the empty string.
+
+The @code{tzname} array is initialized from the @code{TZ} environment
+variable whenever @code{tzset}, @code{ctime}, @code{strftime},
+@code{mktime}, or @code{localtime} is called.  If multiple abbreviations
+have been used (e.g. @code{"EWT"} and @code{"EDT"} for U.S. Eastern War
+Time and Eastern Daylight Time), the array contains the most recent
+abbreviation.
+
+The @code{tzname} array is required for POSIX.1 compatibility, but in
+GNU programs it is better to use the @code{tm_zone} member of the
+broken-down time structure, since @code{tm_zone} reports the correct
+abbreviation even when it is not the latest one.
+
+Though the strings are declared as @code{char *} the user must refrain
+from modifying these strings.  Modifying the strings will almost certainly
+lead to trouble.
+
+@end deftypevar
+
+@comment time.h
+@comment POSIX.1
+@deftypefun void tzset (void)
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c tzset @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  tzset_internal dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_unlock dup @aculock
+The @code{tzset} function initializes the @code{tzname} variable from
+the value of the @code{TZ} environment variable.  It is not usually
+necessary for your program to call this function, because it is called
+automatically when you use the other time conversion functions that
+depend on the time zone.
+@end deftypefun
+
+The following variables are defined for compatibility with System V
+Unix.  Like @code{tzname}, these variables are set by calling
+@code{tzset} or the other time conversion functions.
+
+@comment time.h
+@comment SVID
+@deftypevar {long int} timezone
+This contains the difference between UTC and the latest local standard
+time, in seconds west of UTC.  For example, in the U.S. Eastern time
+zone, the value is @code{5*60*60}.  Unlike the @code{tm_gmtoff} member
+of the broken-down time structure, this value is not adjusted for
+daylight saving, and its sign is reversed.  In GNU programs it is better
+to use @code{tm_gmtoff}, since it contains the correct offset even when
+it is not the latest one.
+@end deftypevar
+
+@comment time.h
+@comment SVID
+@deftypevar int daylight
+This variable has a nonzero value if Daylight Saving Time rules apply.
+A nonzero value does not necessarily mean that Daylight Saving Time is
+now in effect; it means only that Daylight Saving Time is sometimes in
+effect.
+@end deftypevar
+
+@node Time Functions Example
+@subsection Time Functions Example
+
+Here is an example program showing the use of some of the calendar time
+functions.
+
+@smallexample
+@include strftim.c.texi
+@end smallexample
+
+It produces output like this:
+
+@smallexample
+Wed Jul 31 13:02:36 1991
+Today is Wednesday, July 31.
+The time is 01:02 PM.
+@end smallexample
+
+
+@node Setting an Alarm
+@section Setting an Alarm
+
+The @code{alarm} and @code{setitimer} functions provide a mechanism for a
+process to interrupt itself in the future.  They do this by setting a
+timer; when the timer expires, the process receives a signal.
+
+@cindex setting an alarm
+@cindex interval timer, setting
+@cindex alarms, setting
+@cindex timers, setting
+Each process has three independent interval timers available:
+
+@itemize @bullet
+@item
+A real-time timer that counts elapsed time.  This timer sends a
+@code{SIGALRM} signal to the process when it expires.
+@cindex real-time timer
+@cindex timer, real-time
+
+@item
+A virtual timer that counts processor time used by the process.  This timer
+sends a @code{SIGVTALRM} signal to the process when it expires.
+@cindex virtual timer
+@cindex timer, virtual
+
+@item
+A profiling timer that counts both processor time used by the process,
+and processor time spent in system calls on behalf of the process.  This
+timer sends a @code{SIGPROF} signal to the process when it expires.
+@cindex profiling timer
+@cindex timer, profiling
+
+This timer is useful for profiling in interpreters.  The interval timer
+mechanism does not have the fine granularity necessary for profiling
+native code.
+@c @xref{profil} !!!
+@end itemize
+
+You can only have one timer of each kind set at any given time.  If you
+set a timer that has not yet expired, that timer is simply reset to the
+new value.
+
+You should establish a handler for the appropriate alarm signal using
+@code{signal} or @code{sigaction} before issuing a call to
+@code{setitimer} or @code{alarm}.  Otherwise, an unusual chain of events
+could cause the timer to expire before your program establishes the
+handler.  In this case it would be terminated, since termination is the
+default action for the alarm signals.  @xref{Signal Handling}.
+
+To be able to use the alarm function to interrupt a system call which
+might block otherwise indefinitely it is important to @emph{not} set the
+@code{SA_RESTART} flag when registering the signal handler using
+@code{sigaction}.  When not using @code{sigaction} things get even
+uglier: the @code{signal} function has to fixed semantics with respect
+to restarts.  The BSD semantics for this function is to set the flag.
+Therefore, if @code{sigaction} for whatever reason cannot be used, it is
+necessary to use @code{sysv_signal} and not @code{signal}.
+
+The @code{setitimer} function is the primary means for setting an alarm.
+This facility is declared in the header file @file{sys/time.h}.  The
+@code{alarm} function, declared in @file{unistd.h}, provides a somewhat
+simpler interface for setting the real-time timer.
+@pindex unistd.h
+@pindex sys/time.h
+
+@comment sys/time.h
+@comment BSD
+@deftp {Data Type} {struct itimerval}
+This structure is used to specify when a timer should expire.  It contains
+the following members:
+@table @code
+@item struct timeval it_interval
+This is the period between successive timer interrupts.  If zero, the
+alarm will only be sent once.
+
+@item struct timeval it_value
+This is the period between now and the first timer interrupt.  If zero,
+the alarm is disabled.
+@end table
+
+The @code{struct timeval} data type is described in @ref{Elapsed Time}.
+@end deftp
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old})
+@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
+@c This function is marked with @mtstimer because the same set of timers
+@c is shared by all threads of a process, so calling it in one thread
+@c may interfere with timers set by another thread.  This interference
+@c is not regarded as destructive, because the interface specification
+@c makes this overriding while returning the previous value the expected
+@c behavior, and the kernel will serialize concurrent calls so that the
+@c last one prevails, with each call getting the timer information from
+@c the timer installed by the previous call in that serialization.
+The @code{setitimer} function sets the timer specified by @var{which}
+according to @var{new}.  The @var{which} argument can have a value of
+@code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, or @code{ITIMER_PROF}.
+
+If @var{old} is not a null pointer, @code{setitimer} returns information
+about any previous unexpired timer of the same kind in the structure it
+points to.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EINVAL
+The timer period is too large.
+@end table
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getitimer} function stores information about the timer specified
+by @var{which} in the structure pointed at by @var{old}.
+
+The return value and error conditions are the same as for @code{setitimer}.
+@end deftypefun
+
+@comment sys/time.h
+@comment BSD
+@vtable @code
+@item ITIMER_REAL
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the real-time
+timer.
+
+@comment sys/time.h
+@comment BSD
+@item ITIMER_VIRTUAL
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the virtual
+timer.
+
+@comment sys/time.h
+@comment BSD
+@item ITIMER_PROF
+This constant can be used as the @var{which} argument to the
+@code{setitimer} and @code{getitimer} functions to specify the profiling
+timer.
+@end vtable
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {unsigned int} alarm (unsigned int @var{seconds})
+@safety{@prelim{}@mtsafe{@mtstimer{}}@assafe{}@acsafe{}}
+@c Wrapper for setitimer.
+The @code{alarm} function sets the real-time timer to expire in
+@var{seconds} seconds.  If you want to cancel any existing alarm, you
+can do this by calling @code{alarm} with a @var{seconds} argument of
+zero.
+
+The return value indicates how many seconds remain before the previous
+alarm would have been sent.  If there is no previous alarm, @code{alarm}
+returns zero.
+@end deftypefun
+
+The @code{alarm} function could be defined in terms of @code{setitimer}
+like this:
+
+@smallexample
+unsigned int
+alarm (unsigned int seconds)
+@{
+  struct itimerval old, new;
+  new.it_interval.tv_usec = 0;
+  new.it_interval.tv_sec = 0;
+  new.it_value.tv_usec = 0;
+  new.it_value.tv_sec = (long int) seconds;
+  if (setitimer (ITIMER_REAL, &new, &old) < 0)
+    return 0;
+  else
+    return old.it_value.tv_sec;
+@}
+@end smallexample
+
+There is an example showing the use of the @code{alarm} function in
+@ref{Handler Returns}.
+
+If you simply want your process to wait for a given number of seconds,
+you should use the @code{sleep} function.  @xref{Sleeping}.
+
+You shouldn't count on the signal arriving precisely when the timer
+expires.  In a multiprocessing environment there is typically some
+amount of delay involved.
+
+@strong{Portability Note:} The @code{setitimer} and @code{getitimer}
+functions are derived from BSD Unix, while the @code{alarm} function is
+specified by the POSIX.1 standard.  @code{setitimer} is more powerful than
+@code{alarm}, but @code{alarm} is more widely used.
+
+@node Sleeping
+@section Sleeping
+
+The function @code{sleep} gives a simple way to make the program wait
+for a short interval.  If your program doesn't use signals (except to
+terminate), then you can expect @code{sleep} to wait reliably throughout
+the specified interval.  Otherwise, @code{sleep} can return sooner if a
+signal arrives; if you want to wait for a given interval regardless of
+signals, use @code{select} (@pxref{Waiting for I/O}) and don't specify
+any descriptors to wait for.
+@c !!! select can get EINTR; using SA_RESTART makes sleep win too.
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {unsigned int} sleep (unsigned int @var{seconds})
+@safety{@prelim{}@mtunsafe{@mtascusig{:SIGCHLD/linux}}@asunsafe{}@acunsafe{}}
+@c On Mach, it uses ports and calls time.  On generic posix, it calls
+@c nanosleep.  On Linux, it temporarily blocks SIGCHLD, which is MT- and
+@c AS-Unsafe, and in a way that makes it AC-Unsafe (C-unsafe, even!).
+The @code{sleep} function waits for @var{seconds} or until a signal
+is delivered, whichever happens first.
+
+If @code{sleep} function returns because the requested interval is over,
+it returns a value of zero.  If it returns because of delivery of a
+signal, its return value is the remaining time in the sleep interval.
+
+The @code{sleep} function is declared in @file{unistd.h}.
+@end deftypefun
+
+Resist the temptation to implement a sleep for a fixed amount of time by
+using the return value of @code{sleep}, when nonzero, to call
+@code{sleep} again.  This will work with a certain amount of accuracy as
+long as signals arrive infrequently.  But each signal can cause the
+eventual wakeup time to be off by an additional second or so.  Suppose a
+few signals happen to arrive in rapid succession by bad luck---there is
+no limit on how much this could shorten or lengthen the wait.
+
+Instead, compute the calendar time at which the program should stop
+waiting, and keep trying to wait until that calendar time.  This won't
+be off by more than a second.  With just a little more work, you can use
+@code{select} and make the waiting period quite accurate.  (Of course,
+heavy system load can cause additional unavoidable delays---unless the
+machine is dedicated to one application, there is no way you can avoid
+this.)
+
+On some systems, @code{sleep} can do strange things if your program uses
+@code{SIGALRM} explicitly.  Even if @code{SIGALRM} signals are being
+ignored or blocked when @code{sleep} is called, @code{sleep} might
+return prematurely on delivery of a @code{SIGALRM} signal.  If you have
+established a handler for @code{SIGALRM} signals and a @code{SIGALRM}
+signal is delivered while the process is sleeping, the action taken
+might be just to cause @code{sleep} to return instead of invoking your
+handler.  And, if @code{sleep} is interrupted by delivery of a signal
+whose handler requests an alarm or alters the handling of @code{SIGALRM},
+this handler and @code{sleep} will interfere.
+
+On @gnusystems{}, it is safe to use @code{sleep} and @code{SIGALRM} in
+the same program, because @code{sleep} does not work by means of
+@code{SIGALRM}.
+
+@comment time.h
+@comment POSIX.1
+@deftypefun int nanosleep (const struct timespec *@var{requested_time}, struct timespec *@var{remaining})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c On Linux, it's a syscall.  On Mach, it calls gettimeofday and uses
+@c ports.
+If resolution to seconds is not enough the @code{nanosleep} function can
+be used.  As the name suggests the sleep interval can be specified in
+nanoseconds.  The actual elapsed time of the sleep interval might be
+longer since the system rounds the elapsed time you request up to the
+next integer multiple of the actual resolution the system can deliver.
+
+*@code{requested_time} is the elapsed time of the interval you want to
+sleep.
+
+The function returns as *@code{remaining} the elapsed time left in the
+interval for which you requested to sleep.  If the interval completed
+without getting interrupted by a signal, this is zero.
+
+@code{struct timespec} is described in @xref{Elapsed Time}.
+
+If the function returns because the interval is over the return value is
+zero.  If the function returns @math{-1} the global variable @var{errno}
+is set to the following values:
+
+@table @code
+@item EINTR
+The call was interrupted because a signal was delivered to the thread.
+If the @var{remaining} parameter is not the null pointer the structure
+pointed to by @var{remaining} is updated to contain the remaining
+elapsed time.
+
+@item EINVAL
+The nanosecond value in the @var{requested_time} parameter contains an
+illegal value.  Either the value is negative or greater than or equal to
+1000 million.
+@end table
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{nanosleep} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{nanosleep} should
+be protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
+The @code{nanosleep} function is declared in @file{time.h}.
+@end deftypefun
diff --git a/ap/libc/glibc/glibc-2.23/manual/tsort.awk b/ap/libc/glibc/glibc-2.23/manual/tsort.awk
new file mode 100644
index 0000000..82ac3de
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/tsort.awk
@@ -0,0 +1,46 @@
+#!/usr/bin/awk -f
+# Generate topologically sorted list of manual chapters.
+# Copyright (C) 1998-2016 Free Software Foundation, Inc.
+# Written by Ulrich Drepper <drepper@cygnus.com>, 1998.
+
+BEGIN {
+  cnt = 0
+  dnt = 0
+}
+{
+  to[dnt] = $1
+  from[dnt] = $2
+  ++dnt
+  all[cnt++] = $1
+}
+END {
+  do {
+    moved = 0
+    for (i = 0; i < dnt; ++i) {
+      for (j = 0; j < cnt; ++j) {
+	if (all[j] == from[i]) {
+	  for (k = j + 1; k < cnt; ++k) {
+	    if (all[k] == to[i]) {
+	      break;
+	    }
+	  }
+	  if (k < cnt) {
+	    for (l = k - 1; l >= j; --l) {
+	      all[l + 1] = all[l]
+	    }
+	    all[j] = to[i]
+	    break;
+	  }
+	}
+      }
+      if (j < cnt) {
+	moved = 1
+	break
+      }
+    }
+  } while (moved)
+
+  for (i = 0; i < cnt; ++i) {
+    print all[i];
+  }
+}
diff --git a/ap/libc/glibc/glibc-2.23/manual/users.texi b/ap/libc/glibc/glibc-2.23/manual/users.texi
new file mode 100644
index 0000000..e8f0f3b
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/users.texi
@@ -0,0 +1,2859 @@
+@node Users and Groups, System Management, Name Service Switch, Top
+@c %MENU% How users are identified and classified
+@chapter Users and Groups
+
+Every user who can log in on the system is identified by a unique number
+called the @dfn{user ID}.  Each process has an effective user ID which
+says which user's access permissions it has.
+
+Users are classified into @dfn{groups} for access control purposes.  Each
+process has one or more @dfn{group ID values} which say which groups the
+process can use for access to files.
+
+The effective user and group IDs of a process collectively form its
+@dfn{persona}.  This determines which files the process can access.
+Normally, a process inherits its persona from the parent process, but
+under special circumstances a process can change its persona and thus
+change its access permissions.
+
+Each file in the system also has a user ID and a group ID.  Access
+control works by comparing the user and group IDs of the file with those
+of the running process.
+
+The system keeps a database of all the registered users, and another
+database of all the defined groups.  There are library functions you
+can use to examine these databases.
+
+@menu
+* User and Group IDs::          Each user has a unique numeric ID;
+				 likewise for groups.
+* Process Persona::             The user IDs and group IDs of a process.
+* Why Change Persona::          Why a program might need to change
+				 its user and/or group IDs.
+* How Change Persona::          Changing the user and group IDs.
+* Reading Persona::             How to examine the user and group IDs.
+
+* Setting User ID::             Functions for setting the user ID.
+* Setting Groups::              Functions for setting the group IDs.
+
+* Enable/Disable Setuid::       Turning setuid access on and off.
+* Setuid Program Example::      The pertinent parts of one sample program.
+* Tips for Setuid::             How to avoid granting unlimited access.
+
+* Who Logged In::               Getting the name of the user who logged in,
+				 or of the real user ID of the current process.
+
+* User Accounting Database::    Keeping information about users and various
+                                 actions in databases.
+
+* User Database::               Functions and data structures for
+                        	 accessing the user database.
+* Group Database::              Functions and data structures for
+                        	 accessing the group database.
+* Database Example::            Example program showing the use of database
+				 inquiry functions.
+* Netgroup Database::           Functions for accessing the netgroup database.
+@end menu
+
+@node User and Group IDs
+@section User and Group IDs
+
+@cindex login name
+@cindex user name
+@cindex user ID
+Each user account on a computer system is identified by a @dfn{user
+name} (or @dfn{login name}) and @dfn{user ID}.  Normally, each user name
+has a unique user ID, but it is possible for several login names to have
+the same user ID.  The user names and corresponding user IDs are stored
+in a data base which you can access as described in @ref{User Database}.
+
+@cindex group name
+@cindex group ID
+Users are classified in @dfn{groups}.  Each user name belongs to one
+@dfn{default group} and may also belong to any number of
+@dfn{supplementary groups}.  Users who are members of the same group can
+share resources (such as files) that are not accessible to users who are
+not a member of that group.  Each group has a @dfn{group name} and
+@dfn{group ID}.  @xref{Group Database}, for how to find information
+about a group ID or group name.
+
+@node Process Persona
+@section The Persona of a Process
+@cindex persona
+@cindex effective user ID
+@cindex effective group ID
+@cindex supplementary group IDs
+
+@c When Hurd is more widely used, explain multiple effective user IDs
+@c here. -zw
+At any time, each process has an @dfn{effective user ID}, a @dfn{effective
+group ID}, and a set of @dfn{supplementary group IDs}.  These IDs
+determine the privileges of the process.  They are collectively
+called the @dfn{persona} of the process, because they determine ``who it
+is'' for purposes of access control.
+
+Your login shell starts out with a persona which consists of your user
+ID, your default group ID, and your supplementary group IDs (if you are
+in more than one group).  In normal circumstances, all your other processes
+inherit these values.
+
+@cindex real user ID
+@cindex real group ID
+A process also has a @dfn{real user ID} which identifies the user who
+created the process, and a @dfn{real group ID} which identifies that
+user's default group.  These values do not play a role in access
+control, so we do not consider them part of the persona.  But they are
+also important.
+
+Both the real and effective user ID can be changed during the lifetime
+of a process.  @xref{Why Change Persona}.
+
+For details on how a process's effective user ID and group IDs affect
+its permission to access files, see @ref{Access Permission}.
+
+The effective user ID of a process also controls permissions for sending
+signals using the @code{kill} function.  @xref{Signaling Another
+Process}.
+
+Finally, there are many operations which can only be performed by a
+process whose effective user ID is zero.  A process with this user ID is
+a @dfn{privileged process}.  Commonly the user name @code{root} is
+associated with user ID 0, but there may be other user names with this
+ID.
+@c !!! should mention POSIX capabilities here.
+
+@node Why Change Persona
+@section Why Change the Persona of a Process?
+
+The most obvious situation where it is necessary for a process to change
+its user and/or group IDs is the @code{login} program.  When
+@code{login} starts running, its user ID is @code{root}.  Its job is to
+start a shell whose user and group IDs are those of the user who is
+logging in.  (To accomplish this fully, @code{login} must set the real
+user and group IDs as well as its persona.  But this is a special case.)
+
+The more common case of changing persona is when an ordinary user
+program needs access to a resource that wouldn't ordinarily be
+accessible to the user actually running it.
+
+For example, you may have a file that is controlled by your program but
+that shouldn't be read or modified directly by other users, either
+because it implements some kind of locking protocol, or because you want
+to preserve the integrity or privacy of the information it contains.
+This kind of restricted access can be implemented by having the program
+change its effective user or group ID to match that of the resource.
+
+Thus, imagine a game program that saves scores in a file.  The game
+program itself needs to be able to update this file no matter who is
+running it, but if users can write the file without going through the
+game, they can give themselves any scores they like.  Some people
+consider this undesirable, or even reprehensible.  It can be prevented
+by creating a new user ID and login name (say, @code{games}) to own the
+scores file, and make the file writable only by this user.  Then, when
+the game program wants to update this file, it can change its effective
+user ID to be that for @code{games}.  In effect, the program must
+adopt the persona of @code{games} so it can write the scores file.
+
+@node How Change Persona
+@section How an Application Can Change Persona
+@cindex @code{setuid} programs
+@cindex saved set-user-ID
+@cindex saved set-group-ID
+@cindex @code{_POSIX_SAVED_IDS}
+
+The ability to change the persona of a process can be a source of
+unintentional privacy violations, or even intentional abuse.  Because of
+the potential for problems, changing persona is restricted to special
+circumstances.
+
+You can't arbitrarily set your user ID or group ID to anything you want;
+only privileged processes can do that.  Instead, the normal way for a
+program to change its persona is that it has been set up in advance to
+change to a particular user or group.  This is the function of the setuid
+and setgid bits of a file's access mode.  @xref{Permission Bits}.
+
+When the setuid bit of an executable file is on, executing that file
+gives the process a third user ID: the @dfn{file user ID}.  This ID is
+set to the owner ID of the file.  The system then changes the effective
+user ID to the file user ID.  The real user ID remains as it was.
+Likewise, if the setgid bit is on, the process is given a @dfn{file
+group ID} equal to the group ID of the file, and its effective group ID
+is changed to the file group ID.
+
+If a process has a file ID (user or group), then it can at any time
+change its effective ID to its real ID and back to its file ID.
+Programs use this feature to relinquish their special privileges except
+when they actually need them.  This makes it less likely that they can
+be tricked into doing something inappropriate with their privileges.
+
+@strong{Portability Note:} Older systems do not have file IDs.
+To determine if a system has this feature, you can test the compiler
+define @code{_POSIX_SAVED_IDS}.  (In the POSIX standard, file IDs are
+known as saved IDs.)
+
+@xref{File Attributes}, for a more general discussion of file modes and
+accessibility.
+
+@node Reading Persona
+@section Reading the Persona of a Process
+
+Here are detailed descriptions of the functions for reading the user and
+group IDs of a process, both real and effective.  To use these
+facilities, you must include the header files @file{sys/types.h} and
+@file{unistd.h}.
+@pindex unistd.h
+@pindex sys/types.h
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} uid_t
+This is an integer data type used to represent user IDs.  In
+@theglibc{}, this is an alias for @code{unsigned int}.
+@end deftp
+
+@comment sys/types.h
+@comment POSIX.1
+@deftp {Data Type} gid_t
+This is an integer data type used to represent group IDs.  In
+@theglibc{}, this is an alias for @code{unsigned int}.
+@end deftp
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun uid_t getuid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Atomic syscall, except on hurd, where it takes a lock within a hurd
+@c critical section.
+The @code{getuid} function returns the real user ID of the process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun gid_t getgid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getgid} function returns the real group ID of the process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun uid_t geteuid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{geteuid} function returns the effective user ID of the process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun gid_t getegid (void)
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getegid} function returns the effective group ID of the process.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{getgroups} function is used to inquire about the supplementary
+group IDs of the process.  Up to @var{count} of these group IDs are
+stored in the array @var{groups}; the return value from the function is
+the number of group IDs actually stored.  If @var{count} is smaller than
+the total number of supplementary group IDs, then @code{getgroups}
+returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}.
+
+If @var{count} is zero, then @code{getgroups} just returns the total
+number of supplementary group IDs.  On systems that do not support
+supplementary groups, this will always be zero.
+
+Here's how to use @code{getgroups} to read all the supplementary group
+IDs:
+
+@smallexample
+@group
+gid_t *
+read_all_groups (void)
+@{
+  int ngroups = getgroups (0, NULL);
+  gid_t *groups
+    = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
+  int val = getgroups (ngroups, groups);
+  if (val < 0)
+    @{
+      free (groups);
+      return NULL;
+    @}
+  return groups;
+@}
+@end group
+@end smallexample
+@end deftypefun
+
+@node Setting User ID
+@section Setting the User ID
+
+This section describes the functions for altering the user ID (real
+and/or effective) of a process.  To use these facilities, you must
+include the header files @file{sys/types.h} and @file{unistd.h}.
+@pindex unistd.h
+@pindex sys/types.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int seteuid (uid_t @var{neweuid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c seteuid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL @asulock @aculock
+@c    This may be just a unix syscall, or the ugliness below used by
+@c    nptl to propagate the syscall to all cloned processes used to
+@c    implement threads.
+@c   nptl_setxid @asulock @aculock
+@c     while holding the stack_alloc_lock, mark with SETXID_BITMASK all
+@c     threads that are not exiting, signal them until no thread remains
+@c     marked, clear the marks and run the syscall, then release the lock.
+@c    lll_lock @asulock @aculock
+@c    list_for_each ok
+@c    list_entry ok
+@c    setxid_mark_thread ok
+@c      if a thread is initializing, wait for it to be cloned.
+@c      mark it with SETXID_BITMASK if it's not exiting
+@c    setxid_signal_thread ok
+@c      if a thread is marked with SETXID_BITMASK,
+@c        send it the SIGSETXID signal
+@c    setxid_unmark_thread ok
+@c      clear SETXID_BITMASK and release the futex if SETXID_BITMASK is
+@c      set.
+@c    <syscall> ok
+@c    lll_unlock @aculock
+@c
+@c  sighandler_setxid ok
+@c    issue the syscall, clear SETXID_BITMASK, release the futex, and
+@c    wake up the signaller loop if the counter reached zero.
+This function sets the effective user ID of a process to @var{neweuid},
+provided that the process is allowed to change its effective user ID.  A
+privileged process (effective user ID zero) can change its effective
+user ID to any legal value.  An unprivileged process with a file user ID
+can change its effective user ID to its real user ID or to its file user
+ID.  Otherwise, a process may not change its effective user ID at all.
+
+The @code{seteuid} function returns a value of @code{0} to indicate
+successful completion, and a value of @code{-1} to indicate an error.
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EINVAL
+The value of the @var{neweuid} argument is invalid.
+
+@item EPERM
+The process may not change to the specified ID.
+@end table
+
+Older systems (those without the @code{_POSIX_SAVED_IDS} feature) do not
+have this function.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int setuid (uid_t @var{newuid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setuid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+If the calling process is privileged, this function sets both the real
+and effective user ID of the process to @var{newuid}.  It also deletes
+the file user ID of the process, if any.  @var{newuid} may be any
+legal value.  (Once this has been done, there is no way to recover the
+old effective user ID.)
+
+If the process is not privileged, and the system supports the
+@code{_POSIX_SAVED_IDS} feature, then this function behaves like
+@code{seteuid}.
+
+The return values and error conditions are the same as for @code{seteuid}.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setreuid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+This function sets the real user ID of the process to @var{ruid} and the
+effective user ID to @var{euid}.  If @var{ruid} is @code{-1}, it means
+not to change the real user ID; likewise if @var{euid} is @code{-1}, it
+means not to change the effective user ID.
+
+The @code{setreuid} function exists for compatibility with 4.3 BSD Unix,
+which does not support file IDs.  You can use this function to swap the
+effective and real user IDs of the process.  (Privileged processes are
+not limited to this particular usage.)  If file IDs are supported, you
+should use that feature instead of this function.  @xref{Enable/Disable
+Setuid}.
+
+The return value is @code{0} on success and @code{-1} on failure.
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EPERM
+The process does not have the appropriate privileges; you do not
+have permission to change to the specified ID.
+@end table
+@end deftypefun
+
+@node Setting Groups
+@section Setting the Group IDs
+
+This section describes the functions for altering the group IDs (real
+and effective) of a process.  To use these facilities, you must include
+the header files @file{sys/types.h} and @file{unistd.h}.
+@pindex unistd.h
+@pindex sys/types.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int setegid (gid_t @var{newgid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setegid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+This function sets the effective group ID of the process to
+@var{newgid}, provided that the process is allowed to change its group
+ID.  Just as with @code{seteuid}, if the process is privileged it may
+change its effective group ID to any value; if it isn't, but it has a
+file group ID, then it may change to its real group ID or file group ID;
+otherwise it may not change its effective group ID.
+
+Note that a process is only privileged if its effective @emph{user} ID
+is zero.  The effective group ID only affects access permissions.
+
+The return values and error conditions for @code{setegid} are the same
+as those for @code{seteuid}.
+
+This function is only present if @code{_POSIX_SAVED_IDS} is defined.
+@end deftypefun
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int setgid (gid_t @var{newgid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setgid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+This function sets both the real and effective group ID of the process
+to @var{newgid}, provided that the process is privileged.  It also
+deletes the file group ID, if any.
+
+If the process is not privileged, then @code{setgid} behaves like
+@code{setegid}.
+
+The return values and error conditions for @code{setgid} are the same
+as those for @code{seteuid}.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun int setregid (gid_t @var{rgid}, gid_t @var{egid})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setregid @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+This function sets the real group ID of the process to @var{rgid} and
+the effective group ID to @var{egid}.  If @var{rgid} is @code{-1}, it
+means not to change the real group ID; likewise if @var{egid} is
+@code{-1}, it means not to change the effective group ID.
+
+The @code{setregid} function is provided for compatibility with 4.3 BSD
+Unix, which does not support file IDs.  You can use this function to
+swap the effective and real group IDs of the process.  (Privileged
+processes are not limited to this usage.)  If file IDs are supported,
+you should use that feature instead of using this function.
+@xref{Enable/Disable Setuid}.
+
+The return values and error conditions for @code{setregid} are the same
+as those for @code{setreuid}.
+@end deftypefun
+
+@code{setuid} and @code{setgid} behave differently depending on whether
+the effective user ID at the time is zero.  If it is not zero, they
+behave like @code{seteuid} and @code{setegid}.  If it is, they change
+both effective and real IDs and delete the file ID.  To avoid confusion,
+we recommend you always use @code{seteuid} and @code{setegid} except
+when you know the effective user ID is zero and your intent is to change
+the persona permanently.  This case is rare---most of the programs that
+need it, such as @code{login} and @code{su}, have already been written.
+
+Note that if your program is setuid to some user other than @code{root},
+there is no way to drop privileges permanently.
+
+The system also lets privileged processes change their supplementary
+group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
+should include the header file @file{grp.h}.
+@pindex grp.h
+
+@comment grp.h
+@comment BSD
+@deftypefun int setgroups (size_t @var{count}, const gid_t *@var{groups})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c setgroups @asulock @aculock
+@c  INLINE_SETXID_SYSCALL dup @asulock @aculock
+This function sets the process's supplementary group IDs.  It can only
+be called from privileged processes.  The @var{count} argument specifies
+the number of group IDs in the array @var{groups}.
+
+This function returns @code{0} if successful and @code{-1} on error.
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EPERM
+The calling process is not privileged.
+@end table
+@end deftypefun
+
+@comment grp.h
+@comment BSD
+@deftypefun int initgroups (const char *@var{user}, gid_t @var{group})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}}
+@c initgroups @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  sysconf(_SC_NGROUPS_MAX) dup @acsfd
+@c  MIN dup ok
+@c  malloc @ascuheap @acsmem
+@c  internal_getgrouplist @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nscd_getgrouplist @ascuheap @acsfd @acsmem
+@c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c    nscd_cache_search dup ok
+@c    nscd_open_socket dup @acsfd
+@c    realloc dup @ascuheap @acsmem
+@c    readall dup ok
+@c    memcpy dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref dup @ascuheap @acsmem
+@c    nscd_unmap dup @ascuheap @acsmem
+@c   nss_database_lookup dup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c   nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   compat_call @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    sysconf(_SC_GETGR_R_SIZE_MAX) ok
+@c    nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *getgrent_fct @ascuplugin
+@c    *setgrent_fct @ascuplugin
+@c    *endgrent_fct @ascuplugin
+@c    realloc dup @ascuheap @acsmem
+@c    free dup @ascuheap @acsmem
+@c   *initgroups_dyn_fct @ascuplugin
+@c   nss_next_action dup ok
+@c  setgroups dup @asulock @aculock
+@c  free dup @ascuheap @acsmem
+The @code{initgroups} function sets the process's supplementary group
+IDs to be the normal default for the user name @var{user}.  The group
+@var{group} is automatically included.
+
+This function works by scanning the group database for all the groups
+@var{user} belongs to.  It then calls @code{setgroups} with the list it
+has constructed.
+
+The return values and error conditions are the same as for
+@code{setgroups}.
+@end deftypefun
+
+If you are interested in the groups a particular user belongs to, but do
+not want to change the process's supplementary group IDs, you can use
+@code{getgrouplist}.  To use @code{getgrouplist}, your programs should
+include the header file @file{grp.h}.
+@pindex grp.h
+
+@comment grp.h
+@comment BSD
+@deftypefun int getgrouplist (const char *@var{user}, gid_t @var{group}, gid_t *@var{groups}, int *@var{ngroups})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}}
+@c getgrouplist @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  MAX dup ok
+@c  malloc dup @ascuheap @acsmem
+@c  internal_getgrouplist dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  memcpy dup ok
+@c  free dup @ascuheap @acsmem
+The @code{getgrouplist} function scans the group database for all the
+groups @var{user} belongs to.  Up to *@var{ngroups} group IDs
+corresponding to these groups are stored in the array @var{groups}; the
+return value from the function is the number of group IDs actually
+stored.  If *@var{ngroups} is smaller than the total number of groups
+found, then @code{getgrouplist} returns a value of @code{-1} and stores
+the actual number of groups in *@var{ngroups}.  The group @var{group} is
+automatically included in the list of groups returned by
+@code{getgrouplist}.
+
+Here's how to use @code{getgrouplist} to read all supplementary groups
+for @var{user}:
+
+@smallexample
+@group
+gid_t *
+supplementary_groups (char *user)
+@{
+  int ngroups = 16;
+  gid_t *groups
+    = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
+  struct passwd *pw = getpwnam (user);
+
+  if (pw == NULL)
+    return NULL;
+
+  if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0)
+    @{
+      groups = xrealloc (ngroups * sizeof (gid_t));
+      getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups);
+    @}
+  return groups;
+@}
+@end group
+@end smallexample
+@end deftypefun
+
+@node Enable/Disable Setuid
+@section Enabling and Disabling Setuid Access
+
+A typical setuid program does not need its special access all of the
+time.  It's a good idea to turn off this access when it isn't needed,
+so it can't possibly give unintended access.
+
+If the system supports the @code{_POSIX_SAVED_IDS} feature, you can
+accomplish this with @code{seteuid}.  When the game program starts, its
+real user ID is @code{jdoe}, its effective user ID is @code{games}, and
+its saved user ID is also @code{games}.  The program should record both
+user ID values once at the beginning, like this:
+
+@smallexample
+user_user_id = getuid ();
+game_user_id = geteuid ();
+@end smallexample
+
+Then it can turn off game file access with
+
+@smallexample
+seteuid (user_user_id);
+@end smallexample
+
+@noindent
+and turn it on with
+
+@smallexample
+seteuid (game_user_id);
+@end smallexample
+
+@noindent
+Throughout this process, the real user ID remains @code{jdoe} and the
+file user ID remains @code{games}, so the program can always set its
+effective user ID to either one.
+
+On other systems that don't support file user IDs, you can
+turn setuid access on and off by using @code{setreuid} to swap the real
+and effective user IDs of the process, as follows:
+
+@smallexample
+setreuid (geteuid (), getuid ());
+@end smallexample
+
+@noindent
+This special case is always allowed---it cannot fail.
+
+Why does this have the effect of toggling the setuid access?  Suppose a
+game program has just started, and its real user ID is @code{jdoe} while
+its effective user ID is @code{games}.  In this state, the game can
+write the scores file.  If it swaps the two uids, the real becomes
+@code{games} and the effective becomes @code{jdoe}; now the program has
+only @code{jdoe} access.  Another swap brings @code{games} back to
+the effective user ID and restores access to the scores file.
+
+In order to handle both kinds of systems, test for the saved user ID
+feature with a preprocessor conditional, like this:
+
+@smallexample
+#ifdef _POSIX_SAVED_IDS
+  seteuid (user_user_id);
+#else
+  setreuid (geteuid (), getuid ());
+#endif
+@end smallexample
+
+@node Setuid Program Example
+@section Setuid Program Example
+
+Here's an example showing how to set up a program that changes its
+effective user ID.
+
+This is part of a game program called @code{caber-toss} that manipulates
+a file @file{scores} that should be writable only by the game program
+itself.  The program assumes that its executable file will be installed
+with the setuid bit set and owned by the same user as the @file{scores}
+file.  Typically, a system administrator will set up an account like
+@code{games} for this purpose.
+
+The executable file is given mode @code{4755}, so that doing an
+@samp{ls -l} on it produces output like:
+
+@smallexample
+-rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
+@end smallexample
+
+@noindent
+The setuid bit shows up in the file modes as the @samp{s}.
+
+The scores file is given mode @code{644}, and doing an @samp{ls -l} on
+it shows:
+
+@smallexample
+-rw-r--r--  1 games           0 Jul 31 15:33 scores
+@end smallexample
+
+Here are the parts of the program that show how to set up the changed
+user ID.  This program is conditionalized so that it makes use of the
+file IDs feature if it is supported, and otherwise uses @code{setreuid}
+to swap the effective and real user IDs.
+
+@smallexample
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+#include <stdlib.h>
+
+
+/* @r{Remember the effective and real UIDs.} */
+
+static uid_t euid, ruid;
+
+
+/* @r{Restore the effective UID to its original value.} */
+
+void
+do_setuid (void)
+@{
+  int status;
+
+#ifdef _POSIX_SAVED_IDS
+  status = seteuid (euid);
+#else
+  status = setreuid (ruid, euid);
+#endif
+  if (status < 0) @{
+    fprintf (stderr, "Couldn't set uid.\n");
+    exit (status);
+    @}
+@}
+
+
+@group
+/* @r{Set the effective UID to the real UID.} */
+
+void
+undo_setuid (void)
+@{
+  int status;
+
+#ifdef _POSIX_SAVED_IDS
+  status = seteuid (ruid);
+#else
+  status = setreuid (euid, ruid);
+#endif
+  if (status < 0) @{
+    fprintf (stderr, "Couldn't set uid.\n");
+    exit (status);
+    @}
+@}
+@end group
+
+/* @r{Main program.} */
+
+int
+main (void)
+@{
+  /* @r{Remember the real and effective user IDs.}  */
+  ruid = getuid ();
+  euid = geteuid ();
+  undo_setuid ();
+
+  /* @r{Do the game and record the score.}  */
+  @dots{}
+@}
+@end smallexample
+
+Notice how the first thing the @code{main} function does is to set the
+effective user ID back to the real user ID.  This is so that any other
+file accesses that are performed while the user is playing the game use
+the real user ID for determining permissions.  Only when the program
+needs to open the scores file does it switch back to the file user ID,
+like this:
+
+@smallexample
+/* @r{Record the score.} */
+
+int
+record_score (int score)
+@{
+  FILE *stream;
+  char *myname;
+
+  /* @r{Open the scores file.} */
+  do_setuid ();
+  stream = fopen (SCORES_FILE, "a");
+  undo_setuid ();
+
+@group
+  /* @r{Write the score to the file.} */
+  if (stream)
+    @{
+      myname = cuserid (NULL);
+      if (score < 0)
+        fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
+      else
+        fprintf (stream, "%10s: %d feet.\n", myname, score);
+      fclose (stream);
+      return 0;
+    @}
+  else
+    return -1;
+@}
+@end group
+@end smallexample
+
+@node Tips for Setuid
+@section Tips for Writing Setuid Programs
+
+It is easy for setuid programs to give the user access that isn't
+intended---in fact, if you want to avoid this, you need to be careful.
+Here are some guidelines for preventing unintended access and
+minimizing its consequences when it does occur:
+
+@itemize @bullet
+@item
+Don't have @code{setuid} programs with privileged user IDs such as
+@code{root} unless it is absolutely necessary.  If the resource is
+specific to your particular program, it's better to define a new,
+nonprivileged user ID or group ID just to manage that resource.
+It's better if you can write your program to use a special group than a
+special user.
+
+@item
+Be cautious about using the @code{exec} functions in combination with
+changing the effective user ID.  Don't let users of your program execute
+arbitrary programs under a changed user ID.  Executing a shell is
+especially bad news.  Less obviously, the @code{execlp} and @code{execvp}
+functions are a potential risk (since the program they execute depends
+on the user's @code{PATH} environment variable).
+
+If you must @code{exec} another program under a changed ID, specify an
+absolute file name (@pxref{File Name Resolution}) for the executable,
+and make sure that the protections on that executable and @emph{all}
+containing directories are such that ordinary users cannot replace it
+with some other program.
+
+You should also check the arguments passed to the program to make sure
+they do not have unexpected effects.  Likewise, you should examine the
+environment variables.  Decide which arguments and variables are safe,
+and reject all others.
+
+You should never use @code{system} in a privileged program, because it
+invokes a shell.
+
+@item
+Only use the user ID controlling the resource in the part of the program
+that actually uses that resource.  When you're finished with it, restore
+the effective user ID back to the actual user's user ID.
+@xref{Enable/Disable Setuid}.
+
+@item
+If the @code{setuid} part of your program needs to access other files
+besides the controlled resource, it should verify that the real user
+would ordinarily have permission to access those files.  You can use the
+@code{access} function (@pxref{Access Permission}) to check this; it
+uses the real user and group IDs, rather than the effective IDs.
+@end itemize
+
+@node Who Logged In
+@section Identifying Who Logged In
+@cindex login name, determining
+@cindex user ID, determining
+
+You can use the functions listed in this section to determine the login
+name of the user who is running a process, and the name of the user who
+logged in the current session.  See also the function @code{getuid} and
+friends (@pxref{Reading Persona}).  How this information is collected by
+the system and how to control/add/remove information from the background
+storage is described in @ref{User Accounting Database}.
+
+The @code{getlogin} function is declared in @file{unistd.h}, while
+@code{cuserid} and @code{L_cuserid} are declared in @file{stdio.h}.
+@pindex stdio.h
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.1
+@deftypefun {char *} getlogin (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:getlogin} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getlogin (linux) @mtasurace:getlogin @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getlogin_r_loginuid dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getlogin_fd0 (unix) @mtasurace:getlogin @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem
+@c    uses static buffer name => @mtasurace:getlogin
+@c   ttyname_r dup @ascuheap @acsmem @acsfd
+@c   strncpy dup ok
+@c   setutent dup @mtasurace:utent @asulock @aculock @acsfd
+@c   getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c   endutent dup @mtasurace:utent @asulock @aculock
+@c   libc_lock_unlock dup ok
+@c   strlen dup ok
+@c   memcpy dup ok
+@c
+@c getlogin_r (linux) @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getlogin_r_loginuid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   open_not_cancel_2 dup @acsfd
+@c   read_not_cancel dup ok
+@c   close_not_cancel_no_status dup @acsfd
+@c   strtoul @mtslocale
+@c   getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @asulock @aculock @acsfd @acsmem
+@c   strlen dup ok
+@c   memcpy dup ok
+@c   free dup @asulock @aculock @acsfd @acsmem
+@c  getlogin_r_fd0 (unix) @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsmem @acsfd
+@c   ttyname_r dup @ascuheap @acsmem @acsfd
+@c   strncpy dup ok
+@c   libc_lock_lock dup @asulock @aculock
+@c   *libc_utmp_jump_table->setutent dup @mtasurace:utent @acsfd
+@c   *libc_utmp_jump_table->getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer
+@c   *libc_utmp_jump_table->endutent dup @mtasurace:utent @asulock @aculock
+@c   libc_lock_unlock dup ok
+@c   strlen dup ok
+@c   memcpy dup ok
+The @code{getlogin} function returns a pointer to a string containing the
+name of the user logged in on the controlling terminal of the process,
+or a null pointer if this information cannot be determined.  The string
+is statically allocated and might be overwritten on subsequent calls to
+this function or to @code{cuserid}.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX.1
+@deftypefun {char *} cuserid (char *@var{string})
+@safety{@prelim{}@mtunsafe{@mtasurace{:cuserid/!string} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c cuserid @mtasurace:cuserid/!string @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   if string is NULL, cuserid will overwrite and return a static buffer
+@c  geteuid dup ok
+@c  getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  strncpy dup ok
+The @code{cuserid} function returns a pointer to a string containing a
+user name associated with the effective ID of the process.  If
+@var{string} is not a null pointer, it should be an array that can hold
+at least @code{L_cuserid} characters; the string is returned in this
+array.  Otherwise, a pointer to a string in a static area is returned.
+This string is statically allocated and might be overwritten on
+subsequent calls to this function or to @code{getlogin}.
+
+The use of this function is deprecated since it is marked to be
+withdrawn in XPG4.2 and has already been removed from newer revisions of
+POSIX.1.
+@end deftypefun
+
+@comment stdio.h
+@comment POSIX.1
+@deftypevr Macro int L_cuserid
+An integer constant that indicates how long an array you might need to
+store a user name.
+@end deftypevr
+
+These functions let your program identify positively the user who is
+running or the user who logged in this session.  (These can differ when
+setuid programs are involved; see @ref{Process Persona}.)  The user cannot
+do anything to fool these functions.
+
+For most purposes, it is more useful to use the environment variable
+@code{LOGNAME} to find out who the user is.  This is more flexible
+precisely because the user can set @code{LOGNAME} arbitrarily.
+@xref{Standard Environment}.
+
+
+@node User Accounting Database
+@section The User Accounting Database
+@cindex user accounting database
+
+Most Unix-like operating systems keep track of logged in users by
+maintaining a user accounting database.  This user accounting database
+stores for each terminal, who has logged on, at what time, the process
+ID of the user's login shell, etc., etc., but also stores information
+about the run level of the system, the time of the last system reboot,
+and possibly more.
+
+The user accounting database typically lives in @file{/etc/utmp},
+@file{/var/adm/utmp} or @file{/var/run/utmp}.  However, these files
+should @strong{never} be accessed directly.  For reading information
+from and writing information to the user accounting database, the
+functions described in this section should be used.
+
+
+@menu
+* 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.
+@end menu
+
+@node Manipulating the Database
+@subsection Manipulating the User Accounting Database
+
+These functions and the corresponding data structures are declared in
+the header file @file{utmp.h}.
+@pindex utmp.h
+
+@comment utmp.h
+@comment SVID
+@deftp {Data Type} {struct exit_status}
+The @code{exit_status} data structure is used to hold information about
+the exit status of processes marked as @code{DEAD_PROCESS} in the user
+accounting database.
+
+@table @code
+@item short int e_termination
+The exit status of the process.
+
+@item short int e_exit
+The exit status of the process.
+@end table
+@end deftp
+
+@deftp {Data Type} {struct utmp}
+The @code{utmp} data structure is used to hold information about entries
+in the user accounting database.  On @gnusystems{} it has the following
+members:
+
+@table @code
+@item short int ut_type
+Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL},
+@code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS},
+@code{LOGIN_PROCESS}, @code{USER_PROCESS}, @code{DEAD_PROCESS} or
+@code{ACCOUNTING}.
+
+@item pid_t ut_pid
+The process ID number of the login process.
+
+@item char ut_line[]
+The device name of the tty (without @file{/dev/}).
+
+@item char ut_id[]
+The inittab ID of the process.
+
+@item char ut_user[]
+The user's login name.
+
+@item char ut_host[]
+The name of the host from which the user logged in.
+
+@item struct exit_status ut_exit
+The exit status of a process marked as @code{DEAD_PROCESS}.
+
+@item long ut_session
+The Session ID, used for windowing.
+
+@item struct timeval ut_tv
+Time the entry was made.  For entries of type @code{OLD_TIME} this is
+the time when the system clock changed, and for entries of type
+@code{NEW_TIME} this is the time the system clock was set to.
+
+@item int32_t ut_addr_v6[4]
+The Internet address of a remote host.
+@end table
+@end deftp
+
+The @code{ut_type}, @code{ut_pid}, @code{ut_id}, @code{ut_tv}, and
+@code{ut_host} fields are not available on all systems.  Portable
+applications therefore should be prepared for these situations.  To help
+doing this the @file{utmp.h} header provides macros
+@code{_HAVE_UT_TYPE}, @code{_HAVE_UT_PID}, @code{_HAVE_UT_ID},
+@code{_HAVE_UT_TV}, and @code{_HAVE_UT_HOST} if the respective field is
+available.  The programmer can handle the situations by using
+@code{#ifdef} in the program code.
+
+The following macros are defined for use as values for the
+@code{ut_type} member of the @code{utmp} structure.  The values are
+integer constants.
+
+@table @code
+@comment utmp.h
+@comment SVID
+@vindex EMPTY
+@item EMPTY
+This macro is used to indicate that the entry contains no valid user
+accounting information.
+
+@comment utmp.h
+@comment SVID
+@vindex RUN_LVL
+@item RUN_LVL
+This macro is used to identify the systems runlevel.
+
+@comment utmp.h
+@comment SVID
+@vindex BOOT_TIME
+@item BOOT_TIME
+This macro is used to identify the time of system boot.
+
+@comment utmp.h
+@comment SVID
+@vindex OLD_TIME
+@item OLD_TIME
+This macro is used to identify the time when the system clock changed.
+
+@comment utmp.h
+@comment SVID
+@vindex NEW_TIME
+@item NEW_TIME
+This macro is used to identify the time after the system changed.
+
+@comment utmp.h
+@comment SVID
+@vindex INIT_PROCESS
+@item INIT_PROCESS
+This macro is used to identify a process spawned by the init process.
+
+@comment utmp.h
+@comment SVID
+@vindex LOGIN_PROCESS
+@item LOGIN_PROCESS
+This macro is used to identify the session leader of a logged in user.
+
+@comment utmp.h
+@comment SVID
+@vindex USER_PROCESS
+@item USER_PROCESS
+This macro is used to identify a user process.
+
+@comment utmp.h
+@comment SVID
+@vindex DEAD_PROCESS
+@item DEAD_PROCESS
+This macro is used to identify a terminated process.
+
+@comment utmp.h
+@comment SVID
+@vindex ACCOUNTING
+@item ACCOUNTING
+???
+@end table
+
+The size of the @code{ut_line}, @code{ut_id}, @code{ut_user} and
+@code{ut_host} arrays can be found using the @code{sizeof} operator.
+
+Many older systems have, instead of an @code{ut_tv} member, an
+@code{ut_time} member, usually of type @code{time_t}, for representing
+the time associated with the entry.  Therefore, for backwards
+compatibility only, @file{utmp.h} defines @code{ut_time} as an alias for
+@code{ut_tv.tv_sec}.
+
+@comment utmp.h
+@comment SVID
+@deftypefun void setutent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c Besides the static variables in utmp_file.c, there's the jump_table.
+@c They're both modified while holding a lock, but other threads may
+@c cause the variables to be modified between calling this function and
+@c others that rely on the internal state it sets up.
+
+@c setutent @mtasurace:utent @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->setutent @mtasurace:utent @acsfd
+@c   setutent_unknown @mtasurace:utent @acsfd
+@c    *libc_utmp_file_functions.setutent = setutent_file @mtasurace:utent @acsfd
+@c      open_not_cancel_2 dup @acsfd
+@c      fcntl_not_cancel dup ok
+@c      close_not_cancel_no_status dup @acsfd
+@c      lseek64 dup ok
+@c  libc_lock_unlock dup ok
+This function opens the user accounting database to begin scanning it.
+You can then call @code{getutent}, @code{getutid} or @code{getutline} to
+read entries and @code{pututline} to write entries.
+
+If the database is already open, it resets the input to the beginning of
+the database.
+@end deftypefun
+
+@comment utmp.h
+@comment SVID
+@deftypefun {struct utmp *} getutent (void)
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtasurace{:utentbuf} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c The static buffer that holds results is allocated with malloc at
+@c the first call; the test is not thread-safe, so multiple concurrent
+@c calls could malloc multiple buffers.
+
+@c getutent @mtuinit @mtasurace:utent @mtasurace:utentbuf @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem
+@c  malloc @asulock @aculock @acsfd @acsmem
+@c  getutent_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+The @code{getutent} function reads the next entry from the user
+accounting database.  It returns a pointer to the entry, which is
+statically allocated and may be overwritten by subsequent calls to
+@code{getutent}.  You must copy the contents of the structure if you
+wish to save the information or you can use the @code{getutent_r}
+function which stores the data in a user-provided buffer.
+
+A null pointer is returned in case no further entry is available.
+@end deftypefun
+
+@comment utmp.h
+@comment SVID
+@deftypefun void endutent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c endutent @mtasurace:utent @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->endutent @mtasurace:utent @acsfd
+@c   endutent_unknown ok
+@c   endutent_file @mtasurace:utent @acsfd
+@c    close_not_cancel_no_status dup @acsfd
+@c  libc_lock_unlock dup ok
+This function closes the user accounting database.
+@end deftypefun
+
+@comment utmp.h
+@comment SVID
+@deftypefun {struct utmp *} getutid (const struct utmp *@var{id})
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+@c Same caveats as getutline.
+@c
+@c getutid @mtuinit @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsmem @acsfd
+@c   uses a static buffer malloced on the first call
+@c  malloc dup @ascuheap @acsmem
+@c  getutid_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+This function searches forward from the current point in the database
+for an entry that matches @var{id}.  If the @code{ut_type} member of the
+@var{id} structure is one of @code{RUN_LVL}, @code{BOOT_TIME},
+@code{OLD_TIME} or @code{NEW_TIME} the entries match if the
+@code{ut_type} members are identical.  If the @code{ut_type} member of
+the @var{id} structure is @code{INIT_PROCESS}, @code{LOGIN_PROCESS},
+@code{USER_PROCESS} or @code{DEAD_PROCESS}, the entries match if the
+@code{ut_type} member of the entry read from the database is one of
+these four, and the @code{ut_id} members match.  However if the
+@code{ut_id} member of either the @var{id} structure or the entry read
+from the database is empty it checks if the @code{ut_line} members match
+instead.  If a matching entry is found, @code{getutid} returns a pointer
+to the entry, which is statically allocated, and may be overwritten by a
+subsequent call to @code{getutent}, @code{getutid} or @code{getutline}.
+You must copy the contents of the structure if you wish to save the
+information.
+
+A null pointer is returned in case the end of the database is reached
+without a match.
+
+The @code{getutid} function may cache the last read entry.  Therefore,
+if you are using @code{getutid} to search for multiple occurrences, it
+is necessary to zero out the static data after each call.  Otherwise
+@code{getutid} could just return a pointer to the same entry over and
+over again.
+@end deftypefun
+
+@comment utmp.h
+@comment SVID
+@deftypefun {struct utmp *} getutline (const struct utmp *@var{line})
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c The static buffer that holds results is allocated with malloc at
+@c the first call; the test is not thread-safe, so multiple concurrent
+@c calls could malloc multiple buffers.
+
+@c getutline @mtuinit @mtasurace:utent @mtascusig:ALRM @mtascutimer @ascuheap @asulock @aculock @acsfd @acsmem
+@c  malloc @asulock @aculock @acsfd @acsmem
+@c  getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+This function searches forward from the current point in the database
+until it finds an entry whose @code{ut_type} value is
+@code{LOGIN_PROCESS} or @code{USER_PROCESS}, and whose @code{ut_line}
+member matches the @code{ut_line} member of the @var{line} structure.
+If it finds such an entry, it returns a pointer to the entry which is
+statically allocated, and may be overwritten by a subsequent call to
+@code{getutent}, @code{getutid} or @code{getutline}.  You must copy the
+contents of the structure if you wish to save the information.
+
+A null pointer is returned in case the end of the database is reached
+without a match.
+
+The @code{getutline} function may cache the last read entry.  Therefore
+if you are using @code{getutline} to search for multiple occurrences, it
+is necessary to zero out the static data after each call.  Otherwise
+@code{getutline} could just return a pointer to the same entry over and
+over again.
+@end deftypefun
+
+@comment utmp.h
+@comment SVID
+@deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c pututline @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->pututline @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd
+@c   pututline_unknown @mtasurace:utent @acsfd
+@c    setutent_unknown dup @mtasurace:utent @acsfd
+@c   pututline_file @mtascusig:ALRM @mtascutimer @acsfd
+@c    TRANSFORM_UTMP_FILE_NAME ok
+@c     strcmp dup ok
+@c     acesss dup ok
+@c    open_not_cancel_2 dup @acsfd
+@c    fcntl_not_cancel dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    llseek dup ok
+@c    dup2 dup ok
+@c    utmp_equal dup ok
+@c    internal_getut_r dup @mtascusig:ALRM @mtascutimer
+@c    LOCK_FILE dup @mtascusig:ALRM @mtasctimer
+@c    LOCKING_FAILED dup ok
+@c    ftruncate64 dup ok
+@c    write_not_cancel dup ok
+@c    UNLOCK_FILE dup @mtasctimer
+@c  libc_lock_unlock dup @aculock
+The @code{pututline} function inserts the entry @code{*@var{utmp}} at
+the appropriate place in the user accounting database.  If it finds that
+it is not already at the correct place in the database, it uses
+@code{getutid} to search for the position to insert the entry, however
+this will not modify the static structure returned by @code{getutent},
+@code{getutid} and @code{getutline}.  If this search fails, the entry
+is appended to the database.
+
+The @code{pututline} function returns a pointer to a copy of the entry
+inserted in the user accounting database, or a null pointer if the entry
+could not be added.  The following @code{errno} error conditions are
+defined for this function:
+
+@table @code
+@item EPERM
+The process does not have the appropriate privileges; you cannot modify
+the user accounting database.
+@end table
+@end deftypefun
+
+All the @code{get*} functions mentioned before store the information
+they return in a static buffer.  This can be a problem in multi-threaded
+programs since the data returned for the request is overwritten by the
+return value data in another thread.  Therefore @theglibc{}
+provides as extensions three more functions which return the data in a
+user-provided buffer.
+
+@comment utmp.h
+@comment GNU
+@deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c getutent_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->getutent_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd
+@c   getutent_r_unknown @mtasurace:utent @acsfd
+@c    setutent_unknown dup @mtasurace:utent @acsfd
+@c   getutent_r_file @mtasurace:utent @mtascusig:ALRM @mtascutimer
+@c    LOCK_FILE @mtascusig:ALRM @mtascutimer
+@c     alarm dup @mtascutimer
+@c     sigemptyset dup ok
+@c     sigaction dup ok
+@c     memset dup ok
+@c     fcntl_not_cancel dup ok
+@c    LOCKING_FAILED ok
+@c    read_not_cancel dup ok
+@c    UNLOCK_FILE @mtascutimer
+@c     fcntl_not_cancel dup ok
+@c     alarm dup @mtascutimer
+@c     sigaction dup ok
+@c    memcpy dup ok
+@c  libc_lock_unlock dup ok
+The @code{getutent_r} is equivalent to the @code{getutent} function.  It
+returns the next entry from the database.  But instead of storing the
+information in a static buffer it stores it in the buffer pointed to by
+the parameter @var{buffer}.
+
+If the call was successful, the function returns @code{0} and the
+pointer variable pointed to by the parameter @var{result} contains a
+pointer to the buffer which contains the result (this is most probably
+the same value as @var{buffer}).  If something went wrong during the
+execution of @code{getutent_r} the function returns @code{-1}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment utmp.h
+@comment GNU
+@deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c getutid_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->getutid_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd
+@c   getutid_r_unknown @mtasurace:utent @acsfd
+@c    setutent_unknown dup @mtasurace:utent @acsfd
+@c   getutid_r_file @mtascusig:ALRM @mtascutimer
+@c    internal_getut_r @mtascusig:ALRM @mtascutimer
+@c     LOCK_FILE dup @mtascusig:ALRM @mtascutimer
+@c     LOCKING_FAILED dup ok
+@c     read_not_cancel dup ok
+@c     utmp_equal ok
+@c      strncmp dup ok
+@c     UNLOCK_FILE dup @mtascutimer
+@c    memcpy dup ok
+@c  libc_lock_unlock dup @aculock
+This function retrieves just like @code{getutid} the next entry matching
+the information stored in @var{id}.  But the result is stored in the
+buffer pointed to by the parameter @var{buffer}.
+
+If successful the function returns @code{0} and the pointer variable
+pointed to by the parameter @var{result} contains a pointer to the
+buffer with the result (probably the same as @var{result}.  If not
+successful the function return @code{-1}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment utmp.h
+@comment GNU
+@deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c getutline_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->getutline_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @acsfd
+@c   getutline_r_unknown @mtasurace:utent @acsfd
+@c    setutent_unknown dup @mtasurace:utent @acsfd
+@c   getutline_r_file @mtasurace:utent @mtascusig:ALRM @mtascutimer
+@c    LOCK_FILE @mtascusig:ALRM @mtascutimer
+@c     alarm dup @mtascutimer
+@c     sigemptyset dup ok
+@c     sigaction dup ok
+@c     memset dup ok
+@c     fcntl_not_cancel dup ok
+@c    LOCKING_FAILED ok
+@c    read_not_cancel dup ok
+@c    strncmp dup ok
+@c    UNLOCK_FILE @mtascutimer
+@c     fcntl_not_cancel dup ok
+@c     alarm dup @mtascutimer
+@c     sigaction dup ok
+@c    memcpy dup ok
+@c  libc_lock_unlock dup ok
+This function retrieves just like @code{getutline} the next entry
+matching the information stored in @var{line}.  But the result is stored
+in the buffer pointed to by the parameter @var{buffer}.
+
+If successful the function returns @code{0} and the pointer variable
+pointed to by the parameter @var{result} contains a pointer to the
+buffer with the result (probably the same as @var{result}.  If not
+successful the function return @code{-1}.
+
+This function is a GNU extension.
+@end deftypefun
+
+
+In addition to the user accounting database, most systems keep a number
+of similar databases.  For example most systems keep a log file with all
+previous logins (usually in @file{/etc/wtmp} or @file{/var/log/wtmp}).
+
+For specifying which database to examine, the following function should
+be used.
+
+@comment utmp.h
+@comment SVID
+@deftypefun int utmpname (const char *@var{file})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+@c utmpname @mtasurace:utent @asulock @ascuheap @aculock @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  *libc_utmp_jump_table->endutent dup @mtasurace:utent
+@c  strcmp dup ok
+@c  free dup @ascuheap @acsmem
+@c  strdup dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+The @code{utmpname} function changes the name of the database to be
+examined to @var{file}, and closes any previously opened database.  By
+default @code{getutent}, @code{getutid}, @code{getutline} and
+@code{pututline} read from and write to the user accounting database.
+
+The following macros are defined for use as the @var{file} argument:
+
+@deftypevr Macro {char *} _PATH_UTMP
+This macro is used to specify the user accounting database.
+@end deftypevr
+
+@deftypevr Macro {char *} _PATH_WTMP
+This macro is used to specify the user accounting log file.
+@end deftypevr
+
+The @code{utmpname} function returns a value of @code{0} if the new name
+was successfully stored, and a value of @code{-1} to indicate an error.
+Note that @code{utmpname} does not try to open the database, and that
+therefore the return value does not say anything about whether the
+database can be successfully opened.
+@end deftypefun
+
+Specially for maintaining log-like databases @theglibc{} provides
+the following function:
+
+@comment utmp.h
+@comment SVID
+@deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp})
+@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}}
+@c updwtmp @mtascusig:ALRM @mtascutimer @acsfd
+@c  TRANSFORM_UTMP_FILE_NAME dup ok
+@c  *libc_utmp_file_functions->updwtmp = updwtmp_file @mtascusig:ALRM @mtascutimer @acsfd
+@c   open_not_cancel_2 dup @acsfd
+@c   LOCK_FILE dup @mtascusig:ALRM @mtascutimer
+@c   LOCKING_FAILED dup ok
+@c   lseek64 dup ok
+@c   ftruncate64 dup ok
+@c   write_not_cancel dup ok
+@c   UNLOCK_FILE dup @mtascutimer
+@c   close_not_cancel_no_status dup @acsfd
+The @code{updwtmp} function appends the entry *@var{utmp} to the
+database specified by @var{wtmp_file}.  For possible values for the
+@var{wtmp_file} argument see the @code{utmpname} function.
+@end deftypefun
+
+@strong{Portability Note:} Although many operating systems provide a
+subset of these functions, they are not standardized.  There are often
+subtle differences in the return types, and there are considerable
+differences between the various definitions of @code{struct utmp}.  When
+programming for @theglibc{}, it is probably best to stick
+with the functions described in this section.  If however, you want your
+program to be portable, consider using the XPG functions described in
+@ref{XPG Functions}, or take a look at the BSD compatible functions in
+@ref{Logging In and Out}.
+
+
+@node XPG Functions
+@subsection XPG User Accounting Database Functions
+
+These functions, described in the X/Open Portability Guide, are declared
+in the header file @file{utmpx.h}.
+@pindex utmpx.h
+
+@deftp {Data Type} {struct utmpx}
+The @code{utmpx} data structure contains at least the following members:
+
+@table @code
+@item short int ut_type
+Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL},
+@code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS},
+@code{LOGIN_PROCESS}, @code{USER_PROCESS} or @code{DEAD_PROCESS}.
+
+@item pid_t ut_pid
+The process ID number of the login process.
+
+@item char ut_line[]
+The device name of the tty (without @file{/dev/}).
+
+@item char ut_id[]
+The inittab ID of the process.
+
+@item char ut_user[]
+The user's login name.
+
+@item struct timeval ut_tv
+Time the entry was made.  For entries of type @code{OLD_TIME} this is
+the time when the system clock changed, and for entries of type
+@code{NEW_TIME} this is the time the system clock was set to.
+@end table
+In @theglibc{}, @code{struct utmpx} is identical to @code{struct
+utmp} except for the fact that including @file{utmpx.h} does not make
+visible the declaration of @code{struct exit_status}.
+@end deftp
+
+The following macros are defined for use as values for the
+@code{ut_type} member of the @code{utmpx} structure.  The values are
+integer constants and are, in @theglibc{}, identical to the
+definitions in @file{utmp.h}.
+
+@table @code
+@comment utmpx.h
+@comment XPG4.2
+@vindex EMPTY
+@item EMPTY
+This macro is used to indicate that the entry contains no valid user
+accounting information.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex RUN_LVL
+@item RUN_LVL
+This macro is used to identify the systems runlevel.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex BOOT_TIME
+@item BOOT_TIME
+This macro is used to identify the time of system boot.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex OLD_TIME
+@item OLD_TIME
+This macro is used to identify the time when the system clock changed.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex NEW_TIME
+@item NEW_TIME
+This macro is used to identify the time after the system changed.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex INIT_PROCESS
+@item INIT_PROCESS
+This macro is used to identify a process spawned by the init process.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex LOGIN_PROCESS
+@item LOGIN_PROCESS
+This macro is used to identify the session leader of a logged in user.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex USER_PROCESS
+@item USER_PROCESS
+This macro is used to identify a user process.
+
+@comment utmpx.h
+@comment XPG4.2
+@vindex DEAD_PROCESS
+@item DEAD_PROCESS
+This macro is used to identify a terminated process.
+@end table
+
+The size of the @code{ut_line}, @code{ut_id} and @code{ut_user} arrays
+can be found using the @code{sizeof} operator.
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun void setutxent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+This function is similar to @code{setutent}.  In @theglibc{} it is
+simply an alias for @code{setutent}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun {struct utmpx *} getutxent (void)
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+The @code{getutxent} function is similar to @code{getutent}, but returns
+a pointer to a @code{struct utmpx} instead of @code{struct utmp}.  In
+@theglibc{} it simply is an alias for @code{getutent}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun void endutxent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+This function is similar to @code{endutent}.  In @theglibc{} it is
+simply an alias for @code{endutent}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id})
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
+This function is similar to @code{getutid}, but uses @code{struct utmpx}
+instead of @code{struct utmp}.  In @theglibc{} it is simply an alias
+for @code{getutid}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line})
+@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+This function is similar to @code{getutid}, but uses @code{struct utmpx}
+instead of @code{struct utmp}.  In @theglibc{} it is simply an alias
+for @code{getutline}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+The @code{pututxline} function is functionally identical to
+@code{pututline}, but uses @code{struct utmpx} instead of @code{struct
+utmp}.  In @theglibc{}, @code{pututxline} is simply an alias for
+@code{pututline}.
+@end deftypefun
+
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun int utmpxname (const char *@var{file})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
+The @code{utmpxname} function is functionally identical to
+@code{utmpname}.  In @theglibc{}, @code{utmpxname} is simply an
+alias for @code{utmpname}.
+@end deftypefun
+
+You can translate between a traditional @code{struct utmp} and an XPG
+@code{struct utmpx} with the following functions.  In @theglibc{},
+these functions are merely copies, since the two structures are
+identical.
+
+@comment utmpx.h
+@comment utmp.h
+@comment GNU
+@deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{getutmp} copies the information, insofar as the structures are
+compatible, from @var{utmpx} to @var{utmp}.
+@end deftypefun
+
+@comment utmpx.h
+@comment utmp.h
+@comment GNU
+@deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@code{getutmpx} copies the information, insofar as the structures are
+compatible, from @var{utmp} to @var{utmpx}.
+@end deftypefun
+
+
+@node Logging In and Out
+@subsection Logging In and Out
+
+These functions, derived from BSD, are available in the separate
+@file{libutil} library, and declared in @file{utmp.h}.
+@pindex utmp.h
+
+Note that the @code{ut_user} member of @code{struct utmp} is called
+@code{ut_name} in BSD.  Therefore, @code{ut_name} is defined as an alias
+for @code{ut_user} in @file{utmp.h}.
+
+@comment utmp.h
+@comment BSD
+@deftypefun int login_tty (int @var{filedes})
+@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c If this function is canceled, it may have succeeded in redirecting
+@c only some of the standard streams to the newly opened terminal.
+@c Should there be a safety annotation for this?
+@c login_tty @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
+@c  setsid dup ok
+@c  ioctl dup ok
+@c  ttyname dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd
+@c  close dup @acsfd
+@c  open dup @acsfd
+@c  dup2 dup ok
+This function makes @var{filedes} the controlling terminal of the
+current process, redirects standard input, standard output and
+standard error output to this terminal, and closes @var{filedes}.
+
+This function returns @code{0} on successful completion, and @code{-1}
+on error.
+@end deftypefun
+
+@comment utmp.h
+@comment BSD
+@deftypefun void login (const struct utmp *@var{entry})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsfd{} @acsmem{}}}
+@c login @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acucorrupt @acsfd @acsmem
+@c  getpid dup ok
+@c  tty_name @ascuheap @acucorrupt @acsmem @acsfd
+@c   ttyname_r dup @ascuheap @acsmem @acsfd
+@c   memchr dup ok
+@c   realloc dup @ascuheap @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  strncmp dup ok
+@c  basename dup ok
+@c  strncpy dup ok
+@c  utmpname dup @mtasurace:utent @asulock @ascuheap @aculock @acsmem
+@c  setutent dup @mtasurace:utent @asulock @aculock @acsfd
+@c  pututline dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  endutent dup @mtasurace:utent @asulock @aculock
+@c  free dup @ascuheap @acsmem
+@c  updwtmp dup @mtascusig:ALRM @mtascutimer @acsfd
+The @code{login} functions inserts an entry into the user accounting
+database.  The @code{ut_line} member is set to the name of the terminal
+on standard input.  If standard input is not a terminal @code{login}
+uses standard output or standard error output to determine the name of
+the terminal.  If @code{struct utmp} has a @code{ut_type} member,
+@code{login} sets it to @code{USER_PROCESS}, and if there is an
+@code{ut_pid} member, it will be set to the process ID of the current
+process.  The remaining entries are copied from @var{entry}.
+
+A copy of the entry is written to the user accounting log file.
+@end deftypefun
+
+@comment utmp.h
+@comment BSD
+@deftypefun int logout (const char *@var{ut_line})
+@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
+@c logout @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acsfd @acsmem
+@c  utmpname dup @mtasurace:utent @asulock @ascuheap @aculock @acsmem
+@c  setutent dup @mtasurace:utent @asulock @aculock @acsfd
+@c  strncpy dup ok
+@c  getutline_r dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  bzero dup ok
+@c  gettimeofday dup ok
+@c  time dup ok
+@c  pututline dup @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
+@c  endutent dup @mtasurace:utent @asulock @aculock
+This function modifies the user accounting database to indicate that the
+user on @var{ut_line} has logged out.
+
+The @code{logout} function returns @code{1} if the entry was successfully
+written to the database, or @code{0} on error.
+@end deftypefun
+
+@comment utmp.h
+@comment BSD
+@deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host})
+@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}}
+@c logwtmp @mtascusig:ALRM @mtascutimer @acsfd
+@c  memset dup ok
+@c  getpid dup ok
+@c  strncpy dup ok
+@c  gettimeofday dup ok
+@c  time dup ok
+@c  updwtmp dup @mtascusig:ALRM @mtascutimer @acsfd
+The @code{logwtmp} function appends an entry to the user accounting log
+file, for the current time and the information provided in the
+@var{ut_line}, @var{ut_name} and @var{ut_host} arguments.
+@end deftypefun
+
+@strong{Portability Note:} The BSD @code{struct utmp} only has the
+@code{ut_line}, @code{ut_name}, @code{ut_host} and @code{ut_time}
+members.  Older systems do not even have the @code{ut_host} member.
+
+
+@node User Database
+@section User Database
+@cindex user database
+@cindex password database
+@pindex /etc/passwd
+
+This section describes how to search and scan the database of registered
+users.  The database itself is kept in the file @file{/etc/passwd} on
+most systems, but on some systems a special network server gives access
+to it.
+
+@menu
+* 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.
+@end menu
+
+@node User Data Structure
+@subsection The Data Structure that Describes a User
+
+The functions and data structures for accessing the system user database
+are declared in the header file @file{pwd.h}.
+@pindex pwd.h
+
+@comment pwd.h
+@comment POSIX.1
+@deftp {Data Type} {struct passwd}
+The @code{passwd} data structure is used to hold information about
+entries in the system user data base.  It has at least the following members:
+
+@table @code
+@item char *pw_name
+The user's login name.
+
+@item char *pw_passwd.
+The encrypted password string.
+
+@item uid_t pw_uid
+The user ID number.
+
+@item gid_t pw_gid
+The user's default group ID number.
+
+@item char *pw_gecos
+A string typically containing the user's real name, and possibly other
+information such as a phone number.
+
+@item char *pw_dir
+The user's home directory, or initial working directory.  This might be
+a null pointer, in which case the interpretation is system-dependent.
+
+@item char *pw_shell
+The user's default shell, or the initial program run when the user logs in.
+This might be a null pointer, indicating that the system default should
+be used.
+@end table
+@end deftp
+
+@node Lookup User
+@subsection Looking Up One User
+@cindex converting user ID to user name
+@cindex converting user name to user ID
+
+You can search the system user database for information about a
+specific user using @code{getpwuid} or @code{getpwnam}.  These
+functions are declared in @file{pwd.h}.
+
+@comment pwd.h
+@comment POSIX.1
+@deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwuid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getpwuid @mtasurace:pwuid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+This function returns a pointer to a statically-allocated structure
+containing information about the user whose user ID is @var{uid}.  This
+structure may be overwritten on subsequent calls to @code{getpwuid}.
+
+A null pointer value indicates there is no user in the data base with
+user ID @var{uid}.
+@end deftypefun
+
+@comment pwd.h
+@comment POSIX.1c
+@deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getpwuid_r @ascuheap @acsfd @acsmem
+@c   itoa_word dup ok
+@c   nscd_getpw_r @ascuheap @acsfd @acsmem
+@c    nscd_get_map_ref @ascuheap @acsfd @acsmem
+@c     nscd_acquire_maplock ok
+@c     nscd_get_mapping @ascuheap @acsfd @acsmem
+@c      open_socket dup @acsfd
+@c      memset dup ok
+@c      wait_on_socket dup ok
+@c      recvmsg dup ok
+@c      strcmp dup ok
+@c      fstat64 dup ok
+@c      mmap dup @acsmem
+@c      munmap dup @acsmem
+@c      malloc dup @ascuheap @acsmem
+@c      close dup ok
+@c      nscd_unmap dup @ascuheap @acsmem
+@c    nscd_cache_search ok
+@c     nis_hash ok
+@c     memcmp dup ok
+@c    nscd_open_socket @acsfd
+@c     open_socket @acsfd
+@c      socket dup @acsfd
+@c      fcntl dup ok
+@c      strcpy dup ok
+@c      connect dup ok
+@c      send dup ok
+@c      gettimeofday dup ok
+@c      poll dup ok
+@c      close_not_cancel_no_status dup @acsfd
+@c     wait_on_socket dup ok
+@c     read dup ok
+@c     close_not_cancel_no_status dup @acsfd
+@c    readall ok
+@c     read dup ok
+@c     wait_on_socket ok
+@c      poll dup ok
+@c      gettimeofday dup ok
+@c    memcpy dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref @ascuheap @acsmem
+@c     nscd_unmap dup @ascuheap @acsmem
+@c    nscd_unmap @ascuheap @acsmem
+@c     munmap dup ok
+@c     free dup @ascuheap @acsmem
+@c  nss_passwd_lookup2 @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_database_lookup @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c    libc_lock_lock @asulock @aculock
+@c    libc_lock_unlock @aculock
+@c    nss_parse_file @mtslocale @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c     fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c     fsetlocking dup ok [no concurrent uses]
+@c     malloc dup @asulock @aculock @acsfd @acsmem
+@c     fclose dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c     getline dup @ascuheap @aculock @acucorrupt @acsmem
+@c     strchrnul dup ok
+@c     nss_getline @mtslocale @ascuheap @acsmem
+@c      isspace @mtslocale^^
+@c      strlen dup ok
+@c      malloc dup @asulock @aculock @acsfd @acsmem
+@c      memcpy dup ok
+@c      nss_parse_service_list dup @mtslocale^, @ascuheap @acsmem
+@c     feof_unlocked dup ok
+@c     free dup @asulock @aculock @acsfd @acsmem
+@c    strcmp dup ok
+@c    nss_parse_service_list @mtslocale^, @ascuheap @acsmem
+@c     isspace @mtslocale^^
+@c     malloc dup @asulock @aculock @acsfd @acsmem
+@c     mempcpy dup ok
+@c     strncasecmp dup ok
+@c     free dup @asulock @aculock @acsfd @acsmem
+@c    malloc dup @asulock @aculock @acsfd @acsmem
+@c   nss_lookup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup_function @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     libc_lock_lock @asulock @aculock
+@c     tsearch @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt due to locking]
+@c      known_compare ok
+@c       strcmp dup ok
+@c     malloc dup @ascuheap @acsmem
+@c     tdelete @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt due to locking]
+@c     free dup @ascuheap @acsmem
+@c     nss_load_library @ascudlopen @ascuplugin @ascuheap @asulock @aculock @acsfd @acsmem
+@c      nss_new_service @ascuheap @acsmem
+@c       strcmp dup ok
+@c       malloc dup @ascuheap @acsmem
+@c      strlen dup ok
+@c      stpcpy dup ok
+@c      libc_dlopen @ascudlopen @ascuheap @asulock @aculock @acsfd @acsmem
+@c      libc_dlsym dup @asulock @aculock @acsfd @acsmem
+@c      *ifct(*nscd_init_cb) @ascuplugin
+@c     stpcpy dup ok
+@c     libc_dlsym dup @asulock @aculock @acsfd @acsmem
+@c     libc_lock_unlock dup ok
+@c    nss_next_action ok
+@c  *fct.l -> _nss_*_getpwuid_r @ascuplugin
+@c  nss_next2 @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_next_action dup ok
+@c   nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+
+@c _nss_files_getpwuid_r @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  internal_setent @ascuheap @asulock @aculock @acsmem @acsfd
+@c   fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c   fileno dup ok
+@c   fcntl dup ok
+@c   fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c   rewind dup @aculock [stream guarded by non-recursive pwent lock]
+@c  internal_getent @mtslocale^
+@c   fgets_unlocked dup ok [stream guarded by non-recursive pwent lock]
+@c   isspace dup @mtslocale^^
+@c   _nss_files_parse_pwent = parse_line ok
+@c    strpbrk dup ok
+@c  internal_endent @ascuheap @asulock @aculock @acsmem @acsfd
+@c   fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_unlock dup @aculock
+
+@c _nss_nis_getpwuid_r ... not fully reviewed (assumed) @asuinit @asulock @acucorrupt @aculock
+@c  yp_get_default_domain @asulock @aculock
+@c   libc_lock_lock dup @asulock @aculock
+@c   getdomainname dup ok
+@c   strcmp dup ok
+@c   libc_lock_unlock dup @aculock
+@c  snprintf dup @ascuheap @acsmem
+@c  yp_match
+@c   do_ypcall_tr(xdr_ypreq_key,xdr_ypresp_val)
+@c    do_ypcall(xdr_ypreq_key,xdr_ypresp_val)
+@c     libc_lock_lock @asulock @aculock
+@c     strcmp
+@c     yp_bind
+@c     ypclnt_call
+@c      clnt_call
+@c      clnt_perror
+@c     libc_lock_unlock @aculock
+@c     yp_unbind_locked
+@c     yp_unbind
+@c      strcmp dup ok
+@c      calloc dup @asulock @aculock @acsfd @acsmem
+@c      yp_bind_file
+@c       strlen dup ok
+@c       snprintf dup @ascuheap @acsmem
+@c       open dup @acsfd [cancelpt]
+@c       pread dup [cancelpt]
+@c       yp_bind_client_create
+@c       close dup @acsfd [cancelpt]
+@c      yp_bind_ypbindprog
+@c       clnttcp_create
+@c       clnt_destroy
+@c       clnt_call(xdr_domainname,xdr_ypbind_resp)
+@c       memset dup ok
+@c       yp_bind_client_create
+@c      free dup @asulock @aculock @acsfd @acsmem
+@c     calloc dup @asulock @aculock @acsfd @acsmem
+@c     free dup @asulock @aculock @acsfd @acsmem
+@c    ypprot_err
+@c   memcpy dup ok
+@c   xdr_free(xdr_ypresp_val)
+@c    xdr_ypresp_val
+@c     xdr_ypstat
+@c      xdr_enum
+@c       XDR_PUTLONG
+@c        *x_putlong
+@c       XDR_GETLONG
+@c        *x_getlong
+@c       xdr_long
+@c        XDR_PUTLONG dup
+@c        XDR_GETLONG dup
+@c       xdr_short
+@c        XDR_PUTLONG dup
+@c        XDR_GETLONG dup
+@c     xdr_valdat
+@c      xdr_bytes
+@c       xdr_u_int
+@c        XDR_PUTLONG dup
+@c        XDR_GETLONG dup
+@c       mem_alloc @ascuheap @acsmem
+@c        malloc dup @ascuheap @acsmem
+@c       xdr_opaque
+@c        XDR_GETBYTES
+@c         *x_getbytes
+@c        XDR_PUTBYTES
+@c         *x_putbytes
+@c       mem_free @ascuheap @acsmem
+@c        free dup @ascuheap @acsmem
+@c  yperr2nss ok
+@c  strchr dup ok
+@c  _nls_default_nss @asuinit @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c   init @asuinit^, @ascuheap @asulock @acucorrupt @acsmem @acsfd @aculock
+@c    fopen dup @ascuheap @asulock @acsmem @acsfd @aculock
+@c    fsetlocking ok [no concurrent uses]
+@c    feof_unlocked dup ok
+@c    getline dup @ascuheap @aculock @acucorrupt @acsmem
+@c    isspace dup @mtslocale^^
+@c    strncmp dup ok
+@c    free dup @asulock @acsmem @acsfd @aculock
+@c    fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  free dup @asulock @acsmem @acsfd @aculock
+@c  mempcpy dup ok
+@c  strncpy dup ok
+@c  isspace dup @mtslocale^^
+@c  _nss_files_parse_pwent ok
+This function is similar to @code{getpwuid} in that it returns
+information about the user whose user ID is @var{uid}.  However, it
+fills the user supplied structure pointed to by @var{result_buf} with
+the information instead of using a static buffer.  The first
+@var{buflen} bytes of the additional buffer pointed to by @var{buffer}
+are used to contain additional information, normally strings which are
+pointed to by the elements of the result structure.
+
+If a user with ID @var{uid} is found, the pointer returned in
+@var{result} points to the record which contains the wanted data (i.e.,
+@var{result} contains the value @var{result_buf}).  If no user is found
+or if an error occurred, the pointer returned in @var{result} is a null
+pointer.  The function returns zero or an error code.  If the buffer
+@var{buffer} is too small to contain all the needed information, the
+error code @code{ERANGE} is returned and @var{errno} is set to
+@code{ERANGE}.
+@end deftypefun
+
+
+@comment pwd.h
+@comment POSIX.1
+@deftypefun {struct passwd *} getpwnam (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getpwnam @mtasurace:pwnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+This function returns a pointer to a statically-allocated structure
+containing information about the user whose user name is @var{name}.
+This structure may be overwritten on subsequent calls to
+@code{getpwnam}.
+
+A null pointer return indicates there is no user named @var{name}.
+@end deftypefun
+
+@comment pwd.h
+@comment POSIX.1c
+@deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getpwnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getpwnam_r @ascuheap @asulock @aculock @acsfd @acsmem
+@c   strlen dup ok
+@c   nscd_getpw_r dup @ascuheap @asulock @aculock @acsfd @acsmem
+@c  nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c
+@c _nss_files_getpwnam_r @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_lock dup @asulock @aculock
+@c  internal_setent dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  internal_getent dup @mtslocale^
+@c  strcmp dup ok
+@c  internal_endent dup @ascuheap @asulock @aculock @acsmem @acsfd
+@c  libc_lock_unlock dup @aculock
+@c
+@c _nss_*_getpwnam_r (assumed) @asuinit @asulock @acucorrupt @aculock
+
+This function is similar to @code{getpwnam} in that is returns
+information about the user whose user name is @var{name}.  However, like
+@code{getpwuid_r}, it fills the user supplied buffers in
+@var{result_buf} and @var{buffer} with the information instead of using
+a static buffer.
+
+The return values are the same as for @code{getpwuid_r}.
+@end deftypefun
+
+
+@node Scanning All Users
+@subsection Scanning the List of All Users
+@cindex scanning the user list
+
+This section explains how a program can read the list of all users in
+the system, one user at a time.  The functions described here are
+declared in @file{pwd.h}.
+
+You can use the @code{fgetpwent} function to read user entries from a
+particular file.
+
+@comment pwd.h
+@comment SVID
+@deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
+@safety{@prelim{}@mtunsafe{@mtasurace{:fpwent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c fgetpwent @mtasurace:fpwent @asucorrupt @asulock @acucorrupt @aculock
+@c  fgetpos dup @asucorrupt @aculock @acucorrupt
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  fgetpwent_r dup @asucorrupt @acucorrupt @aculock
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  fsetpos dup @asucorrupt @aculock @acucorrupt
+@c  libc_lock_unlock dup @aculock
+This function reads the next user entry from @var{stream} and returns a
+pointer to the entry.  The structure is statically allocated and is
+rewritten on subsequent calls to @code{fgetpwent}.  You must copy the
+contents of the structure if you wish to save the information.
+
+The stream must correspond to a file in the same format as the standard
+password database file.
+@end deftypefun
+
+@comment pwd.h
+@comment GNU
+@deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c fgetpwent_r @asucorrupt @acucorrupt @aculock
+@c  flockfile dup @aculock
+@c  fgets_unlocked @asucorrupt @acucorrupt [no @mtsrace due to explicit locking]
+@c  feof_unlocked dup ok
+@c  funlockfile dup @aculock
+@c  isspace dup @mtslocale^^
+@c  parse_line dup ok
+This function is similar to @code{fgetpwent} in that it reads the next
+user entry from @var{stream}.  But the result is returned in the
+structure pointed to by @var{result_buf}.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+The stream must correspond to a file in the same format as the standard
+password database file.
+
+If the function returns zero @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occurred the return value is nonzero and @var{result} contains a null
+pointer.
+@end deftypefun
+
+The way to scan all the entries in the user database is with
+@code{setpwent}, @code{getpwent}, and @code{endpwent}.
+
+@comment pwd.h
+@comment SVID, BSD
+@deftypefun void setpwent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_setent(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    ** resolv's res_maybe_init not called here
+@c   setup(nss_passwd_lookup2) @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *lookup_fct = nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:pwent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function initializes a stream which @code{getpwent} and
+@code{getpwent_r} use to read the user database.
+@end deftypefun
+
+@comment pwd.h
+@comment POSIX.1
+@deftypefun {struct passwd *} getpwent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtasurace{:pwentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getpwent @mtasurace:pwent @mtasurace:pwentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent(getpwent_r) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c   *func = getpwent_r dup @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   realloc dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+The @code{getpwent} function reads the next entry from the stream
+initialized by @code{setpwent}.  It returns a pointer to the entry.  The
+structure is statically allocated and is rewritten on subsequent calls
+to @code{getpwent}.  You must copy the contents of the structure if you
+wish to save the information.
+
+A null pointer is returned when no more entries are available.
+@end deftypefun
+
+@comment pwd.h
+@comment GNU
+@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c The static buffer here is not the result_buf, but rather the
+@c variables that keep track of what nss backend we've last used, and
+@c whatever internal state the nss backend uses to keep track of the
+@c last read entry.
+@c getpwent_r @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nss_getent_r(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:pwent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *sfct.f @mtasurace:pwent @ascuplugin
+@c  libc_lock_unlock dup @aculock
+This function is similar to @code{getpwent} in that it returns the next
+entry from the stream initialized by @code{setpwent}.  Like
+@code{fgetpwent_r}, it uses the user-supplied buffers in
+@var{result_buf} and @var{buffer} to return the information requested.
+
+The return values are the same as for @code{fgetpwent_r}.
+
+@end deftypefun
+
+@comment pwd.h
+@comment SVID, BSD
+@deftypefun void endpwent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock @asulock @aculock
+@c  nss_endent(nss_passwd_lookup2) @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    ** resolv's res_maybe_init not called here
+@c   setup(nss_passwd_lookup2) dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct.f @mtasurace:pwent @ascuplugin
+@c   nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_unlock @aculock
+This function closes the internal stream used by @code{getpwent} or
+@code{getpwent_r}.
+@end deftypefun
+
+@node Writing a User Entry
+@subsection Writing a User Entry
+
+@comment pwd.h
+@comment SVID
+@deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c putpwent @mtslocale @asucorrupt @aculock @acucorrupt
+@c  fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem]
+This function writes the user entry @code{*@var{p}} to the stream
+@var{stream}, in the format used for the standard user database
+file.  The return value is zero on success and nonzero on failure.
+
+This function exists for compatibility with SVID.  We recommend that you
+avoid using it, because it makes sense only on the assumption that the
+@code{struct passwd} structure has no members except the standard ones;
+on a system which merges the traditional Unix data base with other
+extended information about users, adding an entry using this function
+would inevitably leave out much of the important information.
+@c Then how are programmers to modify the password file? -zw
+
+The group and user ID fields are left empty if the group or user name
+starts with a - or +.
+
+The function @code{putpwent} is declared in @file{pwd.h}.
+@end deftypefun
+
+@node Group Database
+@section Group Database
+@cindex group database
+@pindex /etc/group
+
+This section describes how to search and scan the database of
+registered groups.  The database itself is kept in the file
+@file{/etc/group} on most systems, but on some systems a special network
+service provides access to it.
+
+@menu
+* 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.
+@end menu
+
+@node Group Data Structure
+@subsection The Data Structure for a Group
+
+The functions and data structures for accessing the system group
+database are declared in the header file @file{grp.h}.
+@pindex grp.h
+
+@comment grp.h
+@comment POSIX.1
+@deftp {Data Type} {struct group}
+The @code{group} structure is used to hold information about an entry in
+the system group database.  It has at least the following members:
+
+@table @code
+@item char *gr_name
+The name of the group.
+
+@item gid_t gr_gid
+The group ID of the group.
+
+@item char **gr_mem
+A vector of pointers to the names of users in the group.  Each user name
+is a null-terminated string, and the vector itself is terminated by a
+null pointer.
+@end table
+@end deftp
+
+@node Lookup Group
+@subsection Looking Up One Group
+@cindex converting group name to group ID
+@cindex converting group ID to group name
+
+You can search the group database for information about a specific
+group using @code{getgrgid} or @code{getgrnam}.  These functions are
+declared in @file{grp.h}.
+
+@comment grp.h
+@comment POSIX.1
+@deftypefun {struct group *} getgrgid (gid_t @var{gid})
+@safety{@prelim{}@mtunsafe{@mtasurace{:grgid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrgid =~ getpwuid dup @mtasurace:grgid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getgrgid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function returns a pointer to a statically-allocated structure
+containing information about the group whose group ID is @var{gid}.
+This structure may be overwritten by subsequent calls to
+@code{getgrgid}.
+
+A null pointer indicates there is no group with ID @var{gid}.
+@end deftypefun
+
+@comment grp.h
+@comment POSIX.1c
+@deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrgid_r =~ getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getgrgid_r @ascuheap @acsfd @acsmem
+@c   itoa_word dup ok
+@c   nscd_getgr_r @ascuheap @acsfd @acsmem
+@c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c    nscd_cache_search dup ok
+@c    nscd_open_socket dup @acsfd
+@c    readvall ok
+@c     readv dup ok
+@c     memcpy dup ok
+@c      wait_on_socket dup ok
+@c    memcpy dup ok
+@c    readall dup ok
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref dup @ascuheap @acsmem
+@c    nscd_unmap dup @ascuheap @acsmem
+@c  nss_group_lookup2 =~ nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l -> _nss_*_getgrgid_r @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function is similar to @code{getgrgid} in that it returns
+information about the group whose group ID is @var{gid}.  However, it
+fills the user supplied structure pointed to by @var{result_buf} with
+the information instead of using a static buffer.  The first
+@var{buflen} bytes of the additional buffer pointed to by @var{buffer}
+are used to contain additional information, normally strings which are
+pointed to by the elements of the result structure.
+
+If a group with ID @var{gid} is found, the pointer returned in
+@var{result} points to the record which contains the wanted data (i.e.,
+@var{result} contains the value @var{result_buf}).  If no group is found
+or if an error occurred, the pointer returned in @var{result} is a null
+pointer.  The function returns zero or an error code.  If the buffer
+@var{buffer} is too small to contain all the needed information, the
+error code @code{ERANGE} is returned and @var{errno} is set to
+@code{ERANGE}.
+@end deftypefun
+
+@comment grp.h
+@comment SVID, BSD
+@deftypefun {struct group *} getgrnam (const char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:grnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrnam =~ getpwnam dup @mtasurace:grnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  getgrnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function returns a pointer to a statically-allocated structure
+containing information about the group whose group name is @var{name}.
+This structure may be overwritten by subsequent calls to
+@code{getgrnam}.
+
+A null pointer indicates there is no group named @var{name}.
+@end deftypefun
+
+@comment grp.h
+@comment POSIX.1c
+@deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrnam_r =~ getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_getgrnam_r @ascuheap @asulock @aculock @acsfd @acsmem
+@c   strlen dup ok
+@c   nscd_getgr_r dup @ascuheap @asulock @aculock @acsfd @acsmem
+@c  nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *fct.l @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function is similar to @code{getgrnam} in that is returns
+information about the group whose group name is @var{name}.  Like
+@code{getgrgid_r}, it uses the user supplied buffers in
+@var{result_buf} and @var{buffer}, not a static buffer.
+
+The return values are the same as for @code{getgrgid_r}
+@code{ERANGE}.
+@end deftypefun
+
+@node Scanning All Groups
+@subsection Scanning the List of All Groups
+@cindex scanning the group list
+
+This section explains how a program can read the list of all groups in
+the system, one group at a time.  The functions described here are
+declared in @file{grp.h}.
+
+You can use the @code{fgetgrent} function to read group entries from a
+particular file.
+
+@comment grp.h
+@comment SVID
+@deftypefun {struct group *} fgetgrent (FILE *@var{stream})
+@safety{@prelim{}@mtunsafe{@mtasurace{:fgrent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c fgetgrent @mtasurace:fgrent @asucorrupt @asulock @acucorrupt @aculock
+@c  fgetpos dup @asucorrupt @aculock @acucorrupt
+@c  libc_lock_lock dup @asulock @aculock
+@c  malloc dup @ascuheap @acsmem
+@c  fgetgrent_r dup @asucorrupt @acucorrupt @aculock
+@c  realloc dup @ascuheap @acsmem
+@c  free dup @ascuheap @acsmem
+@c  fsetpos dup @asucorrupt @aculock @acucorrupt
+@c  libc_lock_unlock dup @aculock
+The @code{fgetgrent} function reads the next entry from @var{stream}.
+It returns a pointer to the entry.  The structure is statically
+allocated and is overwritten on subsequent calls to @code{fgetgrent}.  You
+must copy the contents of the structure if you wish to save the
+information.
+
+The stream must correspond to a file in the same format as the standard
+group database file.
+@end deftypefun
+
+@comment grp.h
+@comment GNU
+@deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c fgetgrent_r @asucorrupt @acucorrupt @aculock
+@c  flockfile dup @aculock
+@c  fgets_unlocked @asucorrupt @acucorrupt [no @mtsrace due to explicit locking]
+@c  feof_unlocked dup ok
+@c  funlockfile dup @aculock
+@c  isspace dup @mtslocale^^
+@c  parse_line dup ok
+This function is similar to @code{fgetgrent} in that it reads the next
+user entry from @var{stream}.  But the result is returned in the
+structure pointed to by @var{result_buf}.  The first @var{buflen} bytes
+of the additional buffer pointed to by @var{buffer} are used to contain
+additional information, normally strings which are pointed to by the
+elements of the result structure.
+
+This stream must correspond to a file in the same format as the standard
+group database file.
+
+If the function returns zero @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occurred the return value is non-zero and @var{result} contains a null
+pointer.
+@end deftypefun
+
+The way to scan all the entries in the group database is with
+@code{setgrent}, @code{getgrent}, and @code{endgrent}.
+
+@comment grp.h
+@comment SVID, BSD
+@deftypefun void setgrent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setgrent =~ setpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c ...*lookup_fct = nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function initializes a stream for reading from the group data base.
+You use this stream by calling @code{getgrent} or @code{getgrent_r}.
+@end deftypefun
+
+@comment grp.h
+@comment SVID, BSD
+@deftypefun {struct group *} getgrent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtasurace{:grentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrent =~ getpwent dup @mtasurace:grent @mtasurace:grentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *func = getgrent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+The @code{getgrent} function reads the next entry from the stream
+initialized by @code{setgrent}.  It returns a pointer to the entry.  The
+structure is statically allocated and is overwritten on subsequent calls
+to @code{getgrent}.  You must copy the contents of the structure if you
+wish to save the information.
+@end deftypefun
+
+@comment grp.h
+@comment GNU
+@deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getgrent_r =~ getpwent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function is similar to @code{getgrent} in that it returns the next
+entry from the stream initialized by @code{setgrent}.  Like
+@code{fgetgrent_r}, it places the result in user-supplied buffers
+pointed to @var{result_buf} and @var{buffer}.
+
+If the function returns zero @var{result} contains a pointer to the data
+(normally equal to @var{result_buf}).  If errors occurred the return
+value is non-zero and @var{result} contains a null pointer.
+@end deftypefun
+
+@comment grp.h
+@comment SVID, BSD
+@deftypefun void endgrent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endgrent =~ endpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function closes the internal stream used by @code{getgrent} or
+@code{getgrent_r}.
+@end deftypefun
+
+@node Database Example
+@section User and Group Database Example
+
+Here is an example program showing the use of the system database inquiry
+functions.  The program prints some information about the user running
+the program.
+
+@smallexample
+@include db.c.texi
+@end smallexample
+
+Here is some output from this program:
+
+@smallexample
+I am Throckmorton Snurd.
+My login name is snurd.
+My uid is 31093.
+My home directory is /home/fsg/snurd.
+My default shell is /bin/sh.
+My default group is guest (12).
+The members of this group are:
+  friedman
+  tami
+@end smallexample
+
+@node Netgroup Database
+@section Netgroup Database
+
+@menu
+* 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.
+@end menu
+
+@node Netgroup Data
+@subsection Netgroup Data
+
+@cindex Netgroup
+Sometimes it is useful to group users according to other criteria
+(@pxref{Group Database}).  E.g., it is useful to associate a certain
+group of users with a certain machine.  On the other hand grouping of
+host names is not supported so far.
+
+In Sun Microsystems SunOS appeared a new kind of database, the netgroup
+database.  It allows grouping hosts, users, and domains freely, giving
+them individual names.  To be more concrete, a netgroup is a list of triples
+consisting of a host name, a user name, and a domain name where any of
+the entries can be a wildcard entry matching all inputs.  A last
+possibility is that names of other netgroups can also be given in the
+list specifying a netgroup.  So one can construct arbitrary hierarchies
+without loops.
+
+Sun's implementation allows netgroups only for the @code{nis} or
+@code{nisplus} service, @pxref{Services in the NSS configuration}.  The
+implementation in @theglibc{} has no such restriction.  An entry
+in either of the input services must have the following form:
+
+@smallexample
+@var{groupname} ( @var{groupname} | @code{(}@var{hostname}@code{,}@var{username}@code{,}@code{domainname}@code{)} )+
+@end smallexample
+
+Any of the fields in the triple can be empty which means anything
+matches.  While describing the functions we will see that the opposite
+case is useful as well.  I.e., there may be entries which will not
+match any input.  For entries like this, a name consisting of the single
+character @code{-} shall be used.
+
+@node Lookup Netgroup
+@subsection Looking up one Netgroup
+
+The lookup functions for netgroups are a bit different to all other
+system database handling functions.  Since a single netgroup can contain
+many entries a two-step process is needed.  First a single netgroup is
+selected and then one can iterate over all entries in this netgroup.
+These functions are declared in @file{netdb.h}.
+
+@comment netdb.h
+@comment BSD
+@deftypefun int setnetgrent (const char *@var{netgroup})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c setnetgrent @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  nscd_setnetgrent @ascuheap @acsfd @acsmem
+@c   __nscd_setnetgrent @ascuheap @acsfd @acsmem
+@c    strlen dup ok
+@c    nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c    nscd_cache_search dup ok
+@c    nscd_open_socket dup @acsfd
+@c    malloc dup @ascuheap @acsmem
+@c    readall dup ok
+@c    free dup @ascuheap @acsmem
+@c    close_not_cancel_no_status dup @acsfd
+@c    nscd_drop_map_ref dup @ascuheap @acsmem
+@c    nscd_unmap dup @ascuheap @acsmem
+@c  internal_setnetgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   free_memory dup @ascuheap @acsmem
+@c    free dup @ascuheap @acsmem
+@c   internal_setnetgrent_reuse @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    endnetgrent_hook dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     *endfct @ascuplugin
+@c    (netgroup::)setup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     nss_netgroup_lookup dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c      nss_netgroup_lookup2 =~ nss_passwd_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c     nss_lookup dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *fct.f @ascuplugin
+@c    nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c    *endfct @ascuplugin
+@c    strlen dup ok
+@c    malloc dup @ascuheap @acsmem
+@c    memcpy dup ok
+@c  libc_lock_unlock dup @aculock
+A call to this function initializes the internal state of the library to
+allow following calls of the @code{getnetgrent} to iterate over all entries
+in the netgroup with name @var{netgroup}.
+
+When the call is successful (i.e., when a netgroup with this name exists)
+the return value is @code{1}.  When the return value is @code{0} no
+netgroup of this name is known or some other error occurred.
+@end deftypefun
+
+It is important to remember that there is only one single state for
+iterating the netgroups.  Even if the programmer uses the
+@code{getnetgrent_r} function the result is not really reentrant since
+always only one single netgroup at a time can be processed.  If the
+program needs to process more than one netgroup simultaneously she
+must protect this by using external locking.  This problem was
+introduced in the original netgroups implementation in SunOS and since
+we must stay compatible it is not possible to change this.
+
+Some other functions also use the netgroups state.  Currently these are
+the @code{innetgr} function and parts of the implementation of the
+@code{compat} service part of the NSS implementation.
+
+@comment netdb.h
+@comment BSD
+@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtasurace{:netgrentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getnetgrent @mtasurace:netgrent @mtasurace:netgrentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   uses unsafely a static buffer allocated within a libc_once call
+@c  allocate (libc_once) @ascuheap @acsmem
+@c   malloc dup @ascuheap @acsmem
+@c  getnetgrent_r dup @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+This function returns the next unprocessed entry of the currently
+selected netgroup.  The string pointers, in which addresses are passed in
+the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
+after a successful call pointers to appropriate strings.  If the string
+in the next entry is empty the pointer has the value @code{NULL}.
+The returned string pointers are only valid if none of the netgroup
+related functions are called.
+
+The return value is @code{1} if the next entry was successfully read.  A
+value of @code{0} means no further entries exist or internal errors occurred.
+@end deftypefun
+
+@comment netdb.h
+@comment GNU
+@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, size_t @var{buflen})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c getnetgrent_r @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  internal_getnetgrent_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   *fct @ascuplugin
+@c   nscd_getnetgrent ok
+@c    rawmemchr dup ok
+@c   internal_setnetgrent_reuse dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   strcmp dup ok
+@c   malloc dup @ascuheap @acsmem
+@c   memcpy dup ok
+@c  libc_lock_unlock dup @aculock
+This function is similar to @code{getnetgrent} with only one exception:
+the strings the three string pointers @var{hostp}, @var{userp}, and
+@var{domainp} point to, are placed in the buffer of @var{buflen} bytes
+starting at @var{buffer}.  This means the returned values are valid
+even after other netgroup related functions are called.
+
+The return value is @code{1} if the next entry was successfully read and
+the buffer contains enough room to place the strings in it.  @code{0} is
+returned in case no more entries are found, the buffer is too small, or
+internal errors occurred.
+
+This function is a GNU extension.  The original implementation in the
+SunOS libc does not provide this function.
+@end deftypefun
+
+@comment netdb.h
+@comment BSD
+@deftypefun void endnetgrent (void)
+@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c endnetgrent @mtasurace:netgrent @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  libc_lock_lock dup @asulock @aculock
+@c  internal_endnetgrent @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   endnetgrent_hook dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c   free_memory dup @ascuheap @acsmem
+@c  libc_lock_unlock dup @aculock
+This function frees all buffers which were allocated to process the last
+selected netgroup.  As a result all string pointers returned by calls
+to @code{getnetgrent} are invalid afterwards.
+@end deftypefun
+
+@node Netgroup Membership
+@subsection Testing for Netgroup Membership
+
+It is often not necessary to scan the whole netgroup since often the
+only interesting question is whether a given entry is part of the
+selected netgroup.
+
+@comment netdb.h
+@comment BSD
+@deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain})
+@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
+@c This function does not use the static data structure that the
+@c *netgrent* ones do, but since each nss must maintains internal state
+@c to support iteration and concurrent iteration will interfere
+@c destructively, we regard this internal state as a static buffer.
+@c getnetgrent_r iteration in each nss backend.
+@c innetgr @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  nscd_innetgr @ascuheap @acsfd @acsmem
+@c   strlen dup ok
+@c   malloc dup @ascuheap @acsmem
+@c   stpcpy dup ok
+@c   nscd_get_map_ref dup @ascuheap @acsfd @acsmem
+@c   nscd_cache_search dup ok
+@c   nscd_open_socket dup @acsfd
+@c   close_not_cancel_no_status dup @acsfd
+@c   nscd_drop_map_ref dup @ascuheap @acsmem
+@c   nscd_unmap dup @ascuheap @acsmem
+@c   free dup @ascuheap @acsmem
+@c  memset dup ok
+@c  (netgroup::)setup dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *setfct.f @ascuplugin
+@c  nss_lookup_function dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  *getfct @ascuplugin
+@c  strcmp dup ok
+@c  strlen dup ok
+@c  malloc dup @ascuheap @acsmem
+@c  memcpy dup ok
+@c  strcasecmp dup
+@c  *endfct @ascuplugin
+@c  nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
+@c  free_memory dup @ascuheap @acsmem
+This function tests whether the triple specified by the parameters
+@var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup
+@var{netgroup}.  Using this function has the advantage that
+
+@enumerate
+@item
+no other netgroup function can use the global netgroup state since
+internal locking is used and
+@item
+the function is implemented more efficiently than successive calls
+to the other @code{set}/@code{get}/@code{endnetgrent} functions.
+@end enumerate
+
+Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
+@code{NULL} which means any value is accepted in this position.  This is
+also true for the name @code{-} which should not match any other string
+otherwise.
+
+The return value is @code{1} if an entry matching the given triple is
+found in the netgroup.  The return value is @code{0} if the netgroup
+itself is not found, the netgroup does not contain the triple or
+internal errors occurred.
+@end deftypefun
+
+@c FIXME these are undocumented:
+@c setresgid
+@c setresuid
diff --git a/ap/libc/glibc/glibc-2.23/manual/xtract-typefun.awk b/ap/libc/glibc/glibc-2.23/manual/xtract-typefun.awk
new file mode 100644
index 0000000..57e567f
--- /dev/null
+++ b/ap/libc/glibc/glibc-2.23/manual/xtract-typefun.awk
@@ -0,0 +1,43 @@
+#!/usr/local/bin/gawk -f
+BEGIN {
+  last_node="";
+}
+
+/^@node/ {
+  name = $0;
+  sub(/^@node +/, "", name);
+  sub(/[@,].*$/, "", name);
+  last_node = name;
+}
+
+/^@deftype(fn|vr)/ {
+# The string we want is $4, except that if there were brace blocks
+# before that point then it gets shifted to the right, since awk
+# doesn't know from brace blocks.
+  id = 4; check = 2; squig = 0;
+  while(check < id)
+  {
+    if($check ~ /{/) squig++;
+    if($check ~ /}/) squig--;
+    if(squig) id++;
+    check++;
+  }
+
+  gsub(/[(){}*]/, "", $id);
+  printf ("* %s: (libc)%s.\n", $id, last_node);
+}
+
+/^@deftypefun/ {
+# Likewise, except it's $3 theoretically.
+  id = 3; check = 2; squig = 0;
+  while(check < id)
+  {
+    if($check ~ /{/) squig++;
+    if($check ~ /}/) squig--;
+    if(squig) id++;
+    check++;
+  }
+
+  gsub(/[(){}*]/, "", $id);
+  printf ("* %s: (libc)%s.\n", $id, last_node);
+}