Subject: misc/30002: getopt_long.3 man page leaves out important info
To: None <misc-bug-people@netbsd.org, gnats-admin@netbsd.org,>
From: None <hsaliak@kasba.ath.cx>
List: netbsd-bugs
Date: 04/18/2005 08:08:00
>Number:         30002
>Category:       misc
>Synopsis:       getopt_long.3 man page leaves out important info
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Mon Apr 18 08:08:00 +0000 2005
>Originator:     Kailash Sethuraman
>Release:        NetBSD 2.0_RC1
>Organization:
	
>Environment:

	ident getopt_long.3                     
	getopt_long.3:
	     $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc Exp $

System: NetBSD kasba 2.0_RC1 NetBSD 2.0_RC1 (MYKERN) #0: Sun Oct 17 18:17:47 SGT 2004 hsaliak@kasba:/usr/src/sys/arch/i386/compile/MYKERN i386
Architecture: i386
Machine: i386
>Description:
	getopt_long's  man page does not state that the array of struct options
	- long_options,
	must be terminated with an element filled with zeroes. The example of
	getopt_long's usage in the manpage is correct, but the reader is left
	to infer this vital info. The index option to getopt_long is also not
	documented. 
	This issue also affects getopt_long.3 man page in -current. 
>How-To-Repeat:
	Inspection  the man page.
>Fix:

	Apply the following patch to the getopt_long man page 
	src/sys/lib/libc/stdlib/getopt_long.3 
	
--- getopt_long.3.orig	2005-04-18 13:28:07.000000000 +0800
+++ getopt_long.3	2005-04-18 13:42:37.000000000 +0800
@@ -40,7 +40,7 @@
 .Sh SYNOPSIS
 .In getopt.h
 .Ft int
-.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long options" "int *index"
+.Fn getopt_long "int argc" "char * const *argv" "const char *optstring" "struct option *long_options" "int *index"
 .Sh DESCRIPTION
 The
 .Fn getopt_long
@@ -138,6 +138,19 @@
 to the corresponding short option will make this function act just
 like
 .Xr getopt 3 .
+.Pp
+If the 
+.Fa index
+field is not
+.Dv NULL ,
+the integer pointed by it will be set to the index of the long option relative
+to the
+.Fa long_options
+array.
+.Pp
+The last element of the
+.Fa long_options 
+array has to be filled with zeroes. 
 .Sh EXAMPLES
 .Bd -literal -compact
 extern char *optarg;

>Unformatted: