git: d646513e57c9 - main - getopt_long(3): note an inconsistency with getopt(3) in BUGS

The branch main has been updated by kevans:

URL: https://cgit.FreeBSD.org/src/commit/?id=d646513e57c9d59a7c0cc27a4d41518110db4359

commit d646513e57c9d59a7c0cc27a4d41518110db4359
Author:     Kyle Evans <kevans@FreeBSD.org>
AuthorDate: 2023-02-11 05:31:13 +0000
Commit:     Kyle Evans <kevans@FreeBSD.org>
CommitDate: 2023-02-11 05:32:50 +0000

    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
---
 lib/libc/stdlib/getopt_long.3 | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

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.