Re: misc/43795: getmntopts(3) man page doesn't describe return values and error handling well

[Guy Harris <guy%alum.mit.edu@localhost>]

The following reply was made to PR misc/43795; it has been noted by GNATS.

From: Guy Harris <guy%alum.mit.edu@localhost>
To: gnats-bugs%netbsd.org@localhost
Cc: 
Subject: Re: misc/43795: getmntopts(3) man page doesn't describe return values 
and error handling well
Date: Mon, 23 Aug 2010 17:56:48 -0700

 Fix:
 
 *** ~gharris/src/netbsd/current/lib/libutil/getmntopts.3       =
 2010-08-23 17:10:34.000000000 -0700
 --- ./getmntopts.3     2010-08-23 17:34:23.000000000 -0700
 ***************
 *** 51,57 ****
   The
   .Fn getmntopts
   function takes a comma separated option list and a list
 ! of valid option names, and computes the bitmask
   corresponding to the requested set of options.
   .Pp
   The string
 --- 51,57 ----
   The
   .Fn getmntopts
   function takes a comma separated option list and a list
 ! of valid option names, and computes the bitmasks
   corresponding to the requested set of options.
   .Pp
   The string
 ***************
 *** 141,157 ****
   .Dv NULL
   first element.
   .Pp
   The
   .Fn getmntoptstr
   function returns the string value of the named option, if such a value
 ! was set it the option string.
   .Pp
   The
   .Fn getmntoptnum
 ! returns the long value of the named option, if such a value was set it =
 the
   option string.
 ! It prints an error message and exits if the value was not
 ! set, or could not be converted from a string to a long.
   .Pp
   The
   .Fn freemntopts
 --- 141,199 ----
   .Dv NULL
   first element.
   .Pp
 + .Fn getmntopts
 + returns a
 + .Li "mntoptparse_t"
 + handle that can be used in subsequent
 + .Fn getmntoptstr
 + and
 + .Fn getmntoptnum
 + calls to fetch a value for an option and that must be freed with a =
 call
 + to
 + .Fn freemntopts .
 + If an error occurred, then if the external integer value
 + .Va getmnt_silent
 + is zero then
 + .Fn getmntopts
 + prints an error message and exits;
 + if
 + .Va getmnt_silent
 + is non-zero then
 + .Fn getmntopts
 + returns
 + .Dv NULL .
 + .Pp
   The
   .Fn getmntoptstr
   function returns the string value of the named option, if such a value
 ! was set in the option string.
 ! If the value was not set, then if the external integer value
 ! .Va getmnt_silent
 ! is zero then
 ! .Fn getmntoptstr
 ! prints an error message and exits;
 ! if
 ! .Va getmnt_silent
 ! is non-zero then
 ! .Fn getmntoptstr
 ! returns
 ! .Dv NULL .
   .Pp
   The
   .Fn getmntoptnum
 ! returns the long value of the named option, if such a value was set in =
 the
   option string.
 ! If the value was not set, or could not be converted from a string to a
 ! long, then if the external integer value
 ! .Va getmnt_silent
 ! is zero then
 ! .Fn getmntoptnum
 ! prints an error message and exits;
 ! if
 ! .Va getmnt_silent
 ! is non-zero then
 ! .Fn getmntoptnum
 ! returns \-1.
   .Pp
   The
   .Fn freemntopts
 ***************
 *** 172,178 ****
   .Fn getmntoptstr
   returns
   .Dv NULL
 ! if the option does not have an argument, or the option string.
   .Fn getmntoptnum
   returns \-1 if an error occurred.
   .Sh EXAMPLES
 --- 214,220 ----
   .Fn getmntoptstr
   returns
   .Dv NULL
 ! if an error occurred.
   .Fn getmntoptnum
   returns \-1 if an error occurred.
   .Sh EXAMPLES
 ***************
 *** 214,222 ****
   If the external integer variable
   .Va getmnt_silent
   is zero then the
 ! .Fn getmntopts
 ! function displays an error message and exits if an
 ! unrecognized option is encountered.
   By default
   .Va getmnt_silent
   is zero.
 --- 256,266 ----
   If the external integer variable
   .Va getmnt_silent
   is zero then the
 ! .Fn getmntopts ,
 ! .Fn getmntoptstr ,
 ! and
 ! .Fn getmntoptnum
 ! functions display an error message and exit if an error occurred.
   By default
   .Va getmnt_silent
   is zero.