Add "RETURN VALUES" sections

2 files changed, 52 insertions, 2 deletions

diff --git a/lib/libc/stdlib/getopt.3 b/lib/libc/stdlib/getopt.3
index f261edcab73..0a28fa9e604 100644
--- a/lib/libc/stdlib/getopt.3
+++ b/lib/libc/stdlib/getopt.3
@@ -29,7 +29,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$OpenBSD: getopt.3,v 1.18 2002/12/04 20:31:30 millert Exp $
+.\"	$OpenBSD: getopt.3,v 1.19 2002/12/04 21:42:22 millert Exp $
 .\"
 .Dd April 19, 1994
 .Dt GETOPT 3
@@ -126,6 +126,29 @@ When all options have been processed (i.e., up to the first non-option
 argument),
 .Fn getopt
 returns \-1.
+.Sh RETURN VALUES
+The
+.Fn getopt
+function returns the next known option character in
+.Fa optstring .
+If
+.Fn getopt
+encounters a character not found in
+.Fa optstring
+or if it detects a missing option argument,
+it returns
+.Sq ? .
+If
+.Fa optstring
+has a leading
+.Sq \:
+then a missing option argument causes
+.Sq \:
+to be returned instead of
+.Sq ? .
+The
+.Fn getopt
+function returns \-1 when the argument list is exhausted.
 .Sh EXAMPLES
 .Bd -literal -compact
 int bflag, ch, fd;
diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3
index d55f4ead533..cfbe255e6c1 100644
--- a/lib/libc/stdlib/getopt_long.3
+++ b/lib/libc/stdlib/getopt_long.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getopt_long.3,v 1.1 2002/12/03 20:24:30 millert Exp $
+.\"	$OpenBSD: getopt_long.3,v 1.2 2002/12/04 21:42:22 millert Exp $
 .\"	$NetBSD: getopt_long.3,v 1.11 2002/10/02 10:54:19 wiz Exp $
 .\"
 .\" Copyright (c) 1988, 1991, 1993
@@ -163,6 +163,33 @@ If an option starting with
 .Sq -
 does not match a long option but does match a single-character option,
 the single-character option is returned.
+.Sh RETURN VALUES
+If the
+.Fa flag
+field in
+.Li struct option
+is
+.Dv NULL ,
+.Fn getopt_long
+and
+.Fn getopt_long_only
+return the value specified in the
+.Fa val
+field, which is usually just the corresponding short option.
+If
+.Fa flag
+is not
+.Dv NULL ,
+these functions return 0 and store
+.Fa val
+in the location pointed to by
+.Fa flag .
+These functions return
+.Sq \:
+if there was a missing option argument,
+.Sq ?
+if the user specified an unknown or ambiguous option, and
+\-1 when the argument list has been exhausted.
 .Sh EXAMPLES
 .Bd -literal -compact
 int bflag, ch, fd;