From owner-svn-src-head@freebsd.org Sun Aug 12 00:08:15 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 18CAD1057287; Sun, 12 Aug 2018 00:08:15 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id C06969668E; Sun, 12 Aug 2018 00:08:14 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 9D4071E5E5; Sun, 12 Aug 2018 00:08:14 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w7C08EiC056849; Sun, 12 Aug 2018 00:08:14 GMT (envelope-from kevans@FreeBSD.org) Received: (from kevans@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w7C08ECi056848; Sun, 12 Aug 2018 00:08:14 GMT (envelope-from kevans@FreeBSD.org) Message-Id: <201808120008.w7C08ECi056848@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kevans set sender to kevans@FreeBSD.org using -f From: Kyle Evans Date: Sun, 12 Aug 2018 00:08:14 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r337666 - head/lib/libc/stdlib X-SVN-Group: head X-SVN-Commit-Author: kevans X-SVN-Commit-Paths: head/lib/libc/stdlib X-SVN-Commit-Revision: 337666 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 12 Aug 2018 00:08:15 -0000 Author: kevans Date: Sun Aug 12 00:08:14 2018 New Revision: 337666 URL: https://svnweb.freebsd.org/changeset/base/337666 Log: getopt_long(3): Document behavior of leading characters in optstring Leading '+', '-', and ':' in optstring have special meaning. We briefly mention that the first two have special meaning in that we say POSIXLY_CORRECT turns them off, but we don't actually document their meaning. Add a paragraph to RETURN VALUES explaining how they control the treatment of non-option arguments. A leading ':' has no mention; add a note that it suppresses warnings about missing arguments. Reviewed by: jilles MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D14142 Modified: head/lib/libc/stdlib/getopt_long.3 Modified: head/lib/libc/stdlib/getopt_long.3 ============================================================================== --- head/lib/libc/stdlib/getopt_long.3 Sun Aug 12 00:06:21 2018 (r337665) +++ head/lib/libc/stdlib/getopt_long.3 Sun Aug 12 00:08:14 2018 (r337666) @@ -31,7 +31,7 @@ .\" @(#)getopt.3 8.5 (Berkeley) 4/27/95 .\" $FreeBSD$ .\" -.Dd December 25, 2011 +.Dd May 2, 2018 .Dt GETOPT_LONG 3 .Os .Sh NAME @@ -207,12 +207,53 @@ these functions return 0 and store .Fa val in the location pointed to by .Fa flag . +.Pp These functions return .Ql \&: -if there was a missing option argument, +if there was a missing option argument and error messages are suppressed, .Ql \&? if the user specified an unknown or ambiguous option, and \-1 when the argument list has been exhausted. +The default behavior when a missing option argument is encountered is to write +an error and return +.Ql \&? . +Specifying +.Ql \&: +in +.Fa optstr +will cause the error message to be suppressed and +.Ql \&: +to be returned instead. +.Pp +In addition to +.Ql \&: , +a leading +.Ql \&+ +or +.Ql \&- +in +.Fa optstr +also has special meaning. +If either of these are specified, they must appear before +.Ql \&: . +.Pp +A leading +.Ql \&+ +indicates that processing should be halted at the first non-option argument, +matching the default behavior of +.Xr getopt 3 . +The default behavior without +.Ql \&+ +is to permute non-option argments to the end of +.Fa argv . +.Pp +A leading +.Ql \&- +indicates that all non-option arguments should be treated as if they are +arguments to a literal +.Ql \&1 +flag (i.e., the function call will return the value 1, rather than the char +literal '1'). .Sh ENVIRONMENT .Bl -tag -width ".Ev POSIXLY_CORRECT" .It Ev POSIXLY_CORRECT