about summary refs log tree commit diff
path: root/manual
diff options
context:
space:
mode:
authorRoland McGrath <roland@gnu.org>1996-07-14 06:04:09 +0000
committerRoland McGrath <roland@gnu.org>1996-07-14 06:04:09 +0000
commit2064087b5f1a0a3a189fcd6a3012376f5545be31 (patch)
tree6f02a4e4364004352f2d785146b5dc12444e83b9 /manual
parent842907c6f8e6022f443175072e65bc516eb0973b (diff)
downloadglibc-2064087b5f1a0a3a189fcd6a3012376f5545be31.tar.gz
glibc-2064087b5f1a0a3a189fcd6a3012376f5545be31.tar.xz
glibc-2064087b5f1a0a3a189fcd6a3012376f5545be31.zip
Sun Jul 14 01:51:39 1996 Roland McGrath <roland@delasyd.gnu.ai.mit.edu> cvs/libc-960714
	* manual/Makefile (glibc-targets): Variable and targets removed.

Sat Jul 13 23:50:17 1996  Roland McGrath  <roland@delasyd.gnu.ai.mit.edu>

	* manual/Makefile (lib): New phony target.  Depend on stamp files.
	($(objpfx)stamp%-$(subdir)): New rule to create them when necessary.

1996-07-13  Paul Eggert  <eggert@twinsun.com>

	* time/strftime.c (strftime): Use space padding for %e, %k, %l,
	to match Emacs format-time-string specification.
	(DO_NUMBER_SPACEPAD): Renamed from DO_NUMBER_NOPAD.

Sat Jul 13 20:17:38 1996  Roland McGrath  <roland@delasyd.gnu.ai.mit.edu>

	* elf/dl-deps.c (_dl_map_object_deps): Take new args PRELOADS and
	NPRELOADS, vector of `struct link_map *'s; add them to the searchlist
	between MAP and its deps.
	* elf/link.h: Fix decl.
	* elf/rtld.c (dl_main): If not secure, parse LD_PRELOAD for
	colon-separated list of names, map those and pass vector of ptrs as
	PRELOADS list to _dl_map_object_deps.
	* elf/dl-runtime.c (_dl_object_relocation_scope): Pass new args to
	_dl_map_object_deps with empty preload list.
	* elf/dl-open.c (_dl_open): Likewise.

	* sysdeps/mach/hurd/dl-sysdep.c (_dl_sysdep_open_zero_fill): Function
	removed.
	(__mmap): Pass MACH_PORT_NULL for memobj port when (flags & MAP_ANON).
	* sysdeps/generic/dl-sysdep.c (_dl_sysdep_open_zero_fill):
	Conditionalize defn on [! MAP_ANON].
	* elf/dl-minimal.c (malloc): Conditionalize use of _dl_zerofd
	on [! MAP_ANON].
	* elf/rtld.c (dl_main): Likewise.
	* elf/dl-load.c (_dl_zerofd): Conditionalize defn on [! MAP_ANON].
	(_dl_map_object_from_fd): Conditionalize initialization of _dl_zerofd.

	* elf/dl-fini.c (_dl_fini): Skip finalizer for executable itself.

Sat Jul 13 02:47:53 1996  David Mosberger-Tang  <davidm@azstarnet.com>

	* stdlib/random.c (__random): Declare as int32_t to be in sync
	with declaration.

	* socket/Makefile (headers): Add socketbits.h.

	* misc/mntent.c (endmntent): Allow for NULL stream.  SunOS does
	it that way.

	* grp/initgroups.c (initgroups): Add groups that user is a member
 	of, not the ones he is _not_ a member of.

	* nss/nsswitch.c (known_compare): Make known_compare() a static
 	instead of a local function.  The latter are difficult to debug
 	and slow to execute on certain platforms.

	* sysdeps/posix/ttyname_r.c (ttyname_r): Use sizeof (dev) - 1 in
 	place of sizeof (dev).  The size of a literal string includes the
 	NUL byte.

	* sysdeps/unix/getlogin.c (getlogin): Initialize ut_fd with -1.

Thu Jul 11 16:59:10 1996  David Mosberger-Tang  <davidm@azstarnet.com>

	* misc/mntent.c (addmntent): Seek to end of file before writing
 	entry.  Return 1 on error, not -1.

Tue Jul  9 19:08:05 1996  David Mosberger-Tang  <davidm@azstarnet.com>

	* sysdeps/unix/sysv/linux/syscalls.list: Mark bdflush as EXTRA
	syscall.

Fri Jul  5 18:44:55 1996  David Mosberger-Tang  <davidm@azstarnet.com>

	* sysdeps/unix/sysv/linux/alpha/ioperm.c (port_to_cpu_addr): Size
 	shift amount for Jensen must be 5 not 4.

Sat Jul 13 20:04:28 1996  Roland McGrath  <roland@delasyd.gnu.ai.mit.edu>

	* socket/sys/socket.h (struct osockaddr): New type.

Sat Jul 13 03:50:53 1996  Ulrich Drepper  <drepper@cygnus.com>

	* misc/Makefile (routines): Add qefgcvt and qefgcvt_r.
	* misc/efgcvt.c, misc/efgcvt_r.c: Change code so that the `double'
	and `long double' versions can be generated.
	* misc/qefgcvt.c, misc/qefgcvt_r.c: New files.  Define macros
	so that included efgcvt{,_r}.c file generate `long double'
	versions.
	* stdlib/stdlib.h: Add prototypes for q[efg]cvt() and q[ef]cvt_r()
	functions.

	* manual/startup.texi: Document new getsubopt function.
	* manual/examples/subopt.c: New example program for documenting
	getsubopt function.

Fri Jul 12 23:58:37 1996  Ulrich Drepper  <drepper@cygnus.com>

	* stdlib/Makefile (routines): Add getsubopt.
	* stdlib/stdlib.h: Add prototype for getsubopt.
	* stdlib/getsubopt.c: New file.  Implement getsubopt function
	to handle suboption parsing.
Diffstat (limited to 'manual')
-rw-r--r--manual/Makefile23
-rw-r--r--manual/examples/subopt.c75
-rw-r--r--manual/startup.texi68
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