From owner-svn-src-stable-11@freebsd.org Mon Aug 20 00:51:21 2018 Return-Path: Delivered-To: svn-src-stable-11@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 D1F78107DF09; Mon, 20 Aug 2018 00:51:20 +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 8795272D05; Mon, 20 Aug 2018 00:51:20 +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 4ECBC6383; Mon, 20 Aug 2018 00:51:20 +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 w7K0pKAp077088; Mon, 20 Aug 2018 00:51:20 GMT (envelope-from kevans@FreeBSD.org) Received: (from kevans@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w7K0pKtH077087; Mon, 20 Aug 2018 00:51:20 GMT (envelope-from kevans@FreeBSD.org) Message-Id: <201808200051.w7K0pKtH077087@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kevans set sender to kevans@FreeBSD.org using -f From: Kyle Evans Date: Mon, 20 Aug 2018 00:51:20 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r338079 - stable/11/lib/libc/stdlib X-SVN-Group: stable-11 X-SVN-Commit-Author: kevans X-SVN-Commit-Paths: stable/11/lib/libc/stdlib X-SVN-Commit-Revision: 338079 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-stable-11@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: SVN commit messages for only the 11-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Aug 2018 00:51:21 -0000 Author: kevans Date: Mon Aug 20 00:51:19 2018 New Revision: 338079 URL: https://svnweb.freebsd.org/changeset/base/338079 Log: MFC r337666: getopt_long(3): Document behavior, optstring leading characters 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. Modified: stable/11/lib/libc/stdlib/getopt_long.3 Directory Properties: stable/11/ (props changed) Modified: stable/11/lib/libc/stdlib/getopt_long.3 ============================================================================== --- stable/11/lib/libc/stdlib/getopt_long.3 Mon Aug 20 00:50:11 2018 (r338078) +++ stable/11/lib/libc/stdlib/getopt_long.3 Mon Aug 20 00:51:19 2018 (r338079) @@ -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