From 052b6a6c94cc330dfbc09ff7b5f03c943deb7ca2 Mon Sep 17 00:00:00 2001 From: Ulrich Drepper Date: Tue, 1 Sep 1998 14:31:49 +0000 Subject: Update. 1998-08-09 Geoff Keating * sysdeps/powerpc/Makefile [subdir=elf]: Add new files split out of dl-machine.h. * sysdeps/powerpc/dl-machine.c: New file. * sysdeps/powerpc/dl-machine.h: Move much stuff into separate files. Revise ELF_PREFERRED_ADDRESS to take account of the new mapping information (fixes bug involving huge bloated web browser). Set ELF_MACHINE_PLTREL_OVERLAP. * sysdeps/powerpc/dl-start.S: New file. * elf/dl-load.c (_dl_map_object_from_fd): Initialise l_map_start, l_map_end. * elf/do-rel.h: Call elf_machine_rel only once (to save space). * elf/dynamic-link.h: Allow PLT relocs to be in the middle of the others. Call elf_dynamic_do_##reloc only once (to save even more space). * elf/link.h: Add new members l_map_start and l_map_end to keep track of the memory map. * elf/rtld.c (_dl_start): Initialise l_map_start for ld.so and the executable. 1998-09-01 11:53 Ulrich Drepper * debug/Makefile (catchsegv): We need not rewrite SOVER anymore. Reported by Andreas Jaeger. * posix/glob.h: Use __size_t instead of size_t in definitions and make sure this is defined. * manual/locale.texi: Almost complete rewrite. Document more functions --- manual/examples/argp-ex1.c | 5 +++++ manual/examples/argp-ex2.c | 21 +++++++++++++++++- manual/examples/argp-ex3.c | 54 +++++++++++++++++++++++++++++++++++++++++++++- manual/examples/argp-ex4.c | 23 ++++++++++++++++++++ manual/startup.texi | 6 +++--- 5 files changed, 104 insertions(+), 5 deletions(-) (limited to 'manual') diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c index c87ebbb532..50ac0ed978 100644 --- a/manual/examples/argp-ex1.c +++ b/manual/examples/argp-ex1.c @@ -1,5 +1,10 @@ /* Argp example #1 -- a minimal program using argp */ +/* 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 int main (int argc, char **argv) diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c index d1b149b494..55f59f2ab8 100644 --- a/manual/examples/argp-ex2.c +++ b/manual/examples/argp-ex2.c @@ -1,11 +1,30 @@ /* Argp example #2 -- a pretty minimal program using argp */ +/* 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 becuase they will almost always be constant + for a given program, even if it uses different argument + parsers for various tasks). */ + #include const char *argp_program_version = "argp-ex2 1.0"; const char *argp_program_bug_address = - ""; + ""; /* Program documentation. */ static char doc[] = diff --git a/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c index 363ee59e11..87d993f8ae 100644 --- a/manual/examples/argp-ex3.c +++ b/manual/examples/argp-ex3.c @@ -1,11 +1,63 @@ /* Argp example #3 -- a program with options and arguments using argp */ +/* 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 argumens 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 const char *argp_program_version = "argp-ex3 1.0"; const char *argp_program_bug_address = - ""; + ""; /* Program documentation. */ static char doc[] = diff --git a/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c index 24dd417a81..fa5a8d00ec 100644 --- a/manual/examples/argp-ex4.c +++ b/manual/examples/argp-ex4.c @@ -1,5 +1,28 @@ /* Argp example #4 -- a program with somewhat more complicated options */ +/* 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 documenation strings are also passed to + the `gettext' function, for possible translation into the + current locale. */ + #include #include #include diff --git a/manual/startup.texi b/manual/startup.texi index dd21c89e6f..bea6c39676 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -82,7 +82,7 @@ allow this three-argument form, so to be portable it is best to write * Parsing Program Arguments:: Ways to parse program options and arguments. @end menu -@node Argument Syntax +@node Argument Syntax, Parsing Program Arguments, , Program Arguments @subsection Program Argument Syntax Conventions @cindex program argument syntax @cindex syntax, for program arguments @@ -154,7 +154,7 @@ accept an argument that is itself optional. Eventually, the GNU system will provide completion for long option names in the shell. -@node Parsing Program Arguments +@node Parsing Program Arguments, , Argument Syntax, Program Arguments @subsection Parsing Program Arguments @cindex program arguments, parsing @@ -188,7 +188,7 @@ it does more of the dirty work for you. @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 -@section Parsing of Suboptions +@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 -- cgit v1.2.3