diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/.cvsignore | 2 | ||||
| -rw-r--r-- | manual/Makefile | 21 | ||||
| -rw-r--r-- | manual/arith.texi | 2 | ||||
| -rw-r--r-- | manual/examples/argp-ex1.c | 9 | ||||
| -rw-r--r-- | manual/examples/argp-ex2.c | 25 | ||||
| -rw-r--r-- | manual/examples/argp-ex3.c | 100 | ||||
| -rw-r--r-- | manual/examples/argp-ex4.c | 144 | ||||
| -rw-r--r-- | manual/intro.texi | 2 | ||||
| -rw-r--r-- | manual/libc.texinfo | 6 | ||||
| -rw-r--r-- | manual/pattern.texi | 157 | ||||
| -rw-r--r-- | manual/texinfo.tex | 26 |
11 files changed, 474 insertions, 20 deletions
diff --git a/manual/.cvsignore b/manual/.cvsignore index 51a9a04ef2..7c305176da 100644 --- a/manual/.cvsignore +++ b/manual/.cvsignore @@ -9,4 +9,4 @@ glibc-* *.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs chapters chapters-incl1 chapters-incl2 summary.texi stamp-* -distinfo +distinfo dir-add.texi diff --git a/manual/Makefile b/manual/Makefile index 5f05524049..80ab3dc30a 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -34,7 +34,7 @@ ifneq (,$(wildcard ../Makeconfig)) include ../Makeconfig endif -# Set chapters and chapters-incl. +# Set chapters and chapters-incl[12]. -include chapters chapters: libc.texinfo $(find-includes) @@ -76,7 +76,10 @@ stamp-summary: summary.awk $(chapters) $(chapters-incl) # access to the documentation of the function, variables, and other # definitions. dir-add.texi: xtract-typefun.awk $(chapters) - $(GAWK) -f $^ | sort > $@.new; + (echo "@dircategory GNU C library functions"; \ + echo "@direntry"; \ + $(GAWK) -f $^ | sort; \ + echo "@end direntry";) > $@.new mv -f $@.new $@ # Generate Texinfo files from the C source for the example programs. @@ -97,8 +100,8 @@ distribute = $(minimal-dist) \ $(patsubst examples/%.c,%.c.texi,$(filter examples/%.c, \ $(minimal-dist))) \ libc.info* libc.?? libc.??s texinfo.tex summary.texi \ - stamp-summary chapters chapters-incl \ - xtract-typefun.awk + stamp-summary chapters chapters-incl1 chapters-incl2 \ + xtract-typefun.awk dir-add.texi dir-add.info export distribute := $(distribute) tar-it = tar chovf $@ $^ @@ -127,18 +130,22 @@ glibc-doc-$(edition).tar: $(doc-only-dist) $(distribute) .PHONY: mostlyclean distclean realclean clean mostlyclean: - -rm -f libc.dvi libc.info* + -rm -f libc.dvi libc.info* dir-add.info clean: mostlyclean distclean: clean indices = cp fn pg tp vr ky realclean: distclean -rm -f chapters chapters-incl summary.texi stamp-summary *.c.texi -rm -f $(foreach index,$(indices),libc.$(index) libc.$(index)s) - -rm -f libc.log libc.aux libc.toc + -rm -f libc.log libc.aux libc.toc dir-add.texi .PHONY: install subdir_install installdirs install-data install-data subdir_install: install -install: $(inst_infodir)/libc.info +install: $(inst_infodir)/libc.info dir-add.info + @if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \ + install-info --info-dir=$(inst_infodir) $(inst_infodir)/libc.info;\ + install-info --info-dir=$(inst_infodir) dir-add.info;\ + else : ; fi # Catchall implicit rule for other installation targets from the parent. install-%: ; diff --git a/manual/arith.texi b/manual/arith.texi index efe0489e40..1268e37e31 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -196,7 +196,7 @@ extensions. @section Floating-Point Number Classification Functions Instead of using the BSD specific functions from the last section it is -better to use those in this section will are introduced in the @w{ISO C +better to use those in this section which are introduced in the @w{ISO C 9X} standard and are therefore widely available. @comment math.h diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c new file mode 100644 index 0000000000..c87ebbb532 --- /dev/null +++ b/manual/examples/argp-ex1.c @@ -0,0 +1,9 @@ +/* Argp example #1 -- a minimal program using argp */ + +#include <argp.h> + +int main (int argc, char **argv) +{ + argp_parse (0, argc, argv, 0, 0, 0); + exit (0); +} diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c new file mode 100644 index 0000000000..d1b149b494 --- /dev/null +++ b/manual/examples/argp-ex2.c @@ -0,0 +1,25 @@ +/* Argp example #2 -- a pretty minimal program using argp */ + +#include <argp.h> + +const char *argp_program_version = + "argp-ex2 1.0"; +const char *argp_program_bug_address = + "<bug-gnu-utils@@prep.ai.mit.edu>"; + +/* Program documentation. */ +static char doc[] = + "Argp example #2 -- a pretty minimal program using argp"; + +/* Our argpument 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/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c new file mode 100644 index 0000000000..363ee59e11 --- /dev/null +++ b/manual/examples/argp-ex3.c @@ -0,0 +1,100 @@ +/* Argp example #3 -- a program with options and arguments using argp */ + +#include <argp.h> + +const char *argp_program_version = + "argp-ex3 1.0"; +const char *argp_program_bug_address = + "<bug-gnu-utils@@prep.ai.mit.edu>"; + +/* 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/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c new file mode 100644 index 0000000000..24dd417a81 --- /dev/null +++ b/manual/examples/argp-ex4.c @@ -0,0 +1,144 @@ +/* Argp example #4 -- a program with somewhat more complicated options */ + +#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/manual/intro.texi b/manual/intro.texi index b8f4c8c6ba..7597807274 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -222,7 +222,7 @@ the XPG specifies the requirements for systems which are intended to be a Unix system. The GNU C library complies to the X/Open Portability Guide, Issue 4.2, -with the with all extensions common to XSI (X/Open System Interface) +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 diff --git a/manual/libc.texinfo b/manual/libc.texinfo index e821807a17..2951f66fcc 100644 --- a/manual/libc.texinfo +++ b/manual/libc.texinfo @@ -4,6 +4,12 @@ @settitle The GNU C Library @setchapternewpage odd +@comment Tell install-info what to do. +@dircategory GNU libraries +@direntry +* Libc: (libc). C library. +@end direntry + @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 diff --git a/manual/pattern.texi b/manual/pattern.texi index 6ac481ab6e..020a40e7da 100644 --- a/manual/pattern.texi +++ b/manual/pattern.texi @@ -118,8 +118,9 @@ 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}. +* 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 @@ -134,7 +135,9 @@ it fills in the structure's fields to tell you about the results. @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. +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 @@ -156,6 +159,47 @@ 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 @w{@code{int +(*) (const char *, struct stat *)}}. + +This is a GNU extension. @end table @end deftp @@ -318,6 +362,113 @@ repeatedly. It handles the flag @code{GLOB_NOESCAPE} by turning on the @code{FNM_NOESCAPE} flag in calls to @code{fnmatch}. @end table +@node More Flags for Globbing +@subsection More Flags for Globbing + +Beside the flags descibed 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. + +@table @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 @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 mathing braces is separated into single +expressions by splitting at @code{,} (comma) characters. The commas +themself 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 + +This functionality is equivalent to what is available in C-shells. +@end table + + @node Regular Expressions @section Regular Expression Matching diff --git a/manual/texinfo.tex b/manual/texinfo.tex index 95c825389d..e1dfbcbd53 100644 --- a/manual/texinfo.tex +++ b/manual/texinfo.tex @@ -1,5 +1,5 @@ %% TeX macros to handle Texinfo files. -%% $Id: texinfo.tex,v 2.201 1997/06/05 11:28:54 drepper Exp $ +%% $Id: texinfo.tex,v 2.202 1997/06/12 20:07:10 drepper Exp $ % Copyright (C) 1985, 86, 88, 90, 91, 92, 93, % 94, 95, 96, 97 Free Software Foundation, Inc. @@ -36,7 +36,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 2.201 $ +\deftexinfoversion$Revision: 2.202 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -120,7 +120,7 @@ % For @cropmarks command. % Do @cropmarks to get crop marks. -% +% \newif\ifcropmarks \let\cropmarks = \cropmarkstrue % @@ -1338,13 +1338,25 @@ where each line of input produces a line of output.} \else{\tclose{\ttsl\look}}\fi \else{\tclose{\ttsl\look}}\fi} -% @url, @uref, @email. Quotes do not seem necessary. +% @url, @email. Quotes do not seem necessary. \let\url=\code % perhaps include a hypertex \special eventually -\let\uref=\code % rms does not like the angle brackets --karl, 17may97. %\def\email#1{$\langle${\tt #1}$\rangle$} \let\email=\code +% @uref (abbreviation for `urlref') takes an optional second argument +% specifying the text to display. First (mandatory) arg is the url. +% +\def\uref#1{\urefxxx #1,,\finish} +\def\urefxxx#1,#2,#3\finish{% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \unhbox0\ (\code{#1})% + \else + \code{#1}% + \fi +} + % 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 @@ -2089,7 +2101,7 @@ July\or August\or September\or October\or November\or December\fi \global\colcount=0\relax}} } -\def\setmultitablespacing{% test to see if user has set \multitablelinespace. +\def\setultitablespacing{% test to see if user has set \multitablelinespace. % If so, do nothing. If not, give it an appropriate dimension based on % current baselineskip. \ifdim\multitablelinespace=0pt @@ -2557,7 +2569,7 @@ width0pt\relax} \fi \def\begindoublecolumns{\begingroup % ended by \enddoublecolumns % Grab any single-column material above us. \output = {\global\setbox\partialpage = \vbox{% - % + % % 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 |