diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 23 | ||||
| -rw-r--r-- | manual/examples/subopt.c | 75 | ||||
| -rw-r--r-- | manual/startup.texi | 68 |
3 files changed, 146 insertions, 20 deletions
diff --git a/manual/Makefile b/manual/Makefile index 7197ecf7a9..eb9fff71ee 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -105,11 +105,6 @@ glibc-doc-$(edition).tar: $(doc-only-dist) $(distribute) uuencode $< < $< > $@.new mv -f $@.new $@ -# The parent makefile sometimes invokes us with targets `subdir_REAL-TARGET'. -subdir_%: % ; -# For targets we don't define, do nothing. -subdir_%: ; - .PHONY: mostlyclean distclean realclean clean mostlyclean: -rm -f libc.dvi libc.info* @@ -151,20 +146,22 @@ endif TAGS: $(minimal-dist) $(ETAGS) -o $@ $^ -# These are targets that each glibc subdirectory is expected to understand. -# ../Rules defines them for code subdirectories; for us, they are no-ops. -glibc-targets := subdir_lib objects objs others tests subdir_lint.out \ - subdir_echo-headers subdir_echo-distinfo stubs -.PHONY: $(glibc-targets) -$(glibc-targets): +# The parent makefile sometimes invokes us with targets `subdir_REAL-TARGET'. +subdir_%: % ; +# For targets we don't define, do nothing. +subdir_%: ; +# Create stamp files if they don't exist, so the parent makefile's rules for +# updating the library archives are happy with us, and never think we have +# changed the library. +.PHONY: lib stubs +lib: $(foreach o,$(object-suffixes),$(objpfx)stamp$o-$(subdir)) stubs: $(common-objpfx)stub-manual -$(common-objpfx)stub-manual ../po/manual.pot: +$(objpfx)stamp%-$(subdir) $(common-objpfx)stub-manual ../po/manual.pot: cp /dev/null $@ # The top-level glibc Makefile expects subdir_install to update the stubs file. subdir_install: stubs - # Get rid of these variables if they came from the parent. routines = diff --git a/manual/examples/subopt.c b/manual/examples/subopt.c new file mode 100644 index 0000000000..4a89f6441e --- /dev/null +++ b/manual/examples/subopt.c @@ -0,0 +1,75 @@ +#include <stdio.h> +#include <stdlib.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 +}; + +const char *mount_opts[] = +{ + [RO_OPTION] = "ro", + [RW_OPTION] = "rw", + [READ_SIZE_OPTION] = "rsize", + [WRITE_SIZE_OPTION] = "wsize" +}; + +int +main (int argc, char *argv[]) +{ + char *subopts, *value; + int opt; + + while ((opt = getopt (argc, argv, "at:o:")) != EOF) + 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/manual/startup.texi b/manual/startup.texi index 654a4e8376..1313d4c2a7 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -83,12 +83,14 @@ 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 Options:: The @code{getopt} function. -* Example of Getopt:: An example of parsing options with @code{getopt}. -* Long Options:: GNU suggests utilities accept long-named options. +* Argument Syntax:: By convention, options start with a hyphen. +* Parsing Options:: The @code{getopt} function. +* Example of Getopt:: An example of parsing options with @code{getopt}. +* Long Options:: GNU suggests utilities accept long-named options. Here is how to do that. -* Long Option Example:: An example of using @code{getopt_long}. +* Long Option Example:: An example of using @code{getopt_long}. +* Suboptions:: Some programs need more detailed options. +* Suboptions Example:: This shows how it could be done for @code{mount}. @end menu @node Argument Syntax @@ -409,6 +411,58 @@ When @code{getopt_long} has no more options to handle, it returns @include longopt.c.texi @end smallexample +@node Suboptions +@subsection 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}, const char* const *@var{tokens}, char **@var{valuep}) + +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 +@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 @section Environment Variables @@ -448,9 +502,9 @@ character, since this is assumed to terminate the string. @menu -* Environment Access:: How to get and set the values of +* Environment Access:: How to get and set the values of environment variables. -* Standard Environment:: These environment variables have +* Standard Environment:: These environment variables have standard interpretations. @end menu |