getopt_long(3): note an inconsistency with getopt(3) in BUGS

getopt_long(3) will not allow an `optind` setting of 0 to be bug-for-bug
compatible with the GNU implementation, as some software does rely on
it.  Document it as a BUG, since it affects previous declarations of
compatibility with getopt(3).

Reviewed by:	pauamma (markup)
Sponsored by:	Klara, Inc.
Differential Revision:	https://reviews.freebsd.org/D37867

1 files changed, 17 insertions, 1 deletions

diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3
index ab5da7387a45..0ac5d574c38e 100644
--- a/lib/libc/stdlib/getopt_long.3
+++ b/lib/libc/stdlib/getopt_long.3
@@ -31,7 +31,7 @@
 .\"     @(#)getopt.3	8.5 (Berkeley) 4/27/95
 .\" $FreeBSD$
 .\"
-.Dd May 2, 2018
+.Dd December 24, 2022
 .Dt GETOPT_LONG 3
 .Os
 .Sh NAME
@@ -546,3 +546,19 @@ is set).
 The implementation can completely replace
 .Xr getopt 3 ,
 but right now we are using separate code.
+.Pp
+.Nm
+makes the assumption that the first argument should always be skipped because
+it's typically the program name.
+As a result, setting
+.Va optind
+to 0 will indicate that
+.Nm
+should reset, and
+.Va optind
+will be set to 1 in the process.
+This behavior differs from
+.Xr getopt 3 ,
+which will handle an
+.Va optind
+value of 0 as expected and process the first element.