trivial mkpasswd defect

trivial mkpasswd defect

[Jon LaBadie]

mkpasswd reports '?' is a valid help option but fails to accept it.

	$ mkpasswd --help
	Usage: mkpasswd [OPTION]... [domain]

	This program prints a /etc/passwd file to stdout

	Options:
		... snip ...
	   -?,--help               displays this message
	 
	$ mkpasswd -?
	mkpasswd: unknown option -- ?

-- 
Jon H. LaBadie                  jcyg@jgcomp.com
 JG Computing
 4455 Province Line Road        (609) 252-0159
 Princeton, NJ  08540-4322      (609) 683-7220 (fax)

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Corinna Vinschen]

On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> mkpasswd reports '?' is a valid help option but fails to accept it.
> 
> 	$ mkpasswd --help
> 	Usage: mkpasswd [OPTION]... [domain]
> 
> 	This program prints a /etc/passwd file to stdout
> 
> 	Options:
> 		... snip ...
> 	   -?,--help               displays this message
> 	 
> 	$ mkpasswd -?
> 	mkpasswd: unknown option -- ?

Thanks.  This will go away in the next version.

Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Developer                                mailto:cygwin@cygwin.com
Red Hat, Inc.

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Bernard A Badger]

> -----Original Message-----
> From: cygwin-owner@cygwin.com [mailto:cygwin-owner@cygwin.com]On Behalf
> Of Corinna Vinschen
> Sent: Wednesday, May 29, 2002 11:32 AM
> To: cygwin@cygwin.com
> Cc: Jon LaBadie
> Subject: Re: trivial mkpasswd defect
>
>
> On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> > mkpasswd reports '?' is a valid help option but fails to accept it.
> >
> > 	$ mkpasswd --help
> > 	Usage: mkpasswd [OPTION]... [domain]
> >
> > 	This program prints a /etc/passwd file to stdout
> >
> > 	Options:
> > 		... snip ...
> > 	   -?,--help               displays this message
> >
> > 	$ mkpasswd -?
> > 	mkpasswd: unknown option -- ?
>
> Thanks.  This will go away in the next version.

I hope you mean that '-?' will work, not that '-?' will be taken out of the
usage.


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Stuart Brady]

On Wed, 29 May 2002, Bernard A Badger wrote:

> I hope you mean that '-?' will work, not that '-?' will be taken out of the
> usage.

Shouldn't it be -h rather than -?, for the same reason that -* would be 
a bad idea? What's wrong with --help anyway?
-- 
Stuart Brady


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Corinna Vinschen]

On Wed, May 29, 2002 at 12:27:15PM -0400, Bernard A Badger wrote:
> > > 	mkpasswd: unknown option -- ?
> >
> > Thanks.  This will go away in the next version.
> 
> I hope you mean that '-?' will work, not that '-?' will be taken out of the
> usage.

The latter.  All cygwin utils which are part of the cygwin package
will get a unified usage (-h, --help).

Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Developer                                mailto:cygwin@cygwin.com
Red Hat, Inc.

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Michael A Chase]

On Wed, 29 May 2002 12:27:15 -0400 Bernard A Badger <bab@vx.com> wrote:

> > -----Original Message-----
> > From: cygwin-owner@cygwin.com [mailto:cygwin-owner@cygwin.com]On Behalf
> > Of Corinna Vinschen
> > Sent: Wednesday, May 29, 2002 11:32 AM
> > To: cygwin@cygwin.com
> > Cc: Jon LaBadie
> > Subject: Re: trivial mkpasswd defect
> >
> > On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> > > mkpasswd reports '?' is a valid help option but fails to accept it.
> > >
> . . .
> > >         $ mkpasswd -?
> > >         mkpasswd: unknown option -- ?
> >
> > Thanks.  This will go away in the next version.
> 
> I hope you mean that '-?' will work, not that '-?' will be taken out of the
> usage.

In Unix envronments -h is more commonly used for help.  '-?' as an option
is subject to filename expansion which can lead to odd behavior if it isn't
quoted.

-- 
Mac :})
** I normally forward private questions to the appropriate mail list. **
Ask Smarter: http://www.tuxedo.org/~esr/faqs/smart-questions.html
Give a hobbit a fish and he eats fish for a day.
Give a hobbit a ring and he eats fish for an age.



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Bernard A Badger]

> -----Original Message-----
> From: Michael A Chase [mailto:mchase@ix.netcom.com]
> To: Bernard A Badger; cygwin@cygwin.com
> Subject: Re: trivial mkpasswd defect
> On Wed, 29 May 2002 12:27:15 -0400 Bernard A Badger <bab@vx.com> wrote:
>
> > > -----Original Message-----
> > > On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> > > > mkpasswd reports '?' is a valid help option but fails to accept it.
> > > >         $ mkpasswd -?
> > > >         mkpasswd: unknown option -- ?
> > >
> > > Thanks.  This will go away in the next version.
> >
> > I hope you mean that '-?' will work, not that '-?' will be taken out of the
> > usage.
>
> In Unix envronments -h is more commonly used for help.  '-?' as an option
> is subject to filename expansion which can lead to odd behavior if it isn't
> quoted.
Well, the example from man 2 getopt has this:

    while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
        switch(c) {
        ....
        case '?':
                    fprintf(stderr,
                            "Unrecognized option: -%c\n", optopt);
            errflg++;
        }
    }
    if (errflg) {
        fprintf(stderr, "usage: . . . ");
        exit(2);

Which exemplifies the custom of printing the "usage" upon an error.
Since '?' cannot be used as a getopt option, it is guaranteed to cause
getopt to return '?' no matter what the option characters are.

I saw this on a SGI Irix, and I checked at www.opengroup.org for the POSIX
standard.

Of course, if you're not following POSIX, and aren't using getopt, it may not
work.  Your personal experience of '-h' being a "help" option, probably carries
less weight than the endorsement of POSIX ;-)


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Michael A Chase]

On Wed, 29 May 2002 17:45:35 -0400 Bernard A Badger <bab@vx.com> wrote:

> > -----Original Message-----
> > From: Michael A Chase [mailto:mchase@ix.netcom.com]
> > To: Bernard A Badger; cygwin@cygwin.com
> > Subject: Re: trivial mkpasswd defect
> > On Wed, 29 May 2002 12:27:15 -0400 Bernard A Badger <bab@vx.com> wrote:
> >
> > > > -----Original Message-----
> > > > On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> > > > > mkpasswd reports '?' is a valid help option but fails to accept
> it.
> > > > >         $ mkpasswd -?
> > > > >         mkpasswd: unknown option -- ?
> > > >
> > > > Thanks.  This will go away in the next version.
> > >
> > > I hope you mean that '-?' will work, not that '-?' will be taken out of the
> > > usage.
> >
> > In Unix envronments -h is more commonly used for help.  '-?' as an option
> > is subject to filename expansion which can lead to odd behavior if it isn't
> > quoted.

> Well, the example from man 2 getopt has this:
> 
>     while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
>         switch(c) {
>         ....
>         case '?':
>                     fprintf(stderr,
>                             "Unrecognized option: -%c\n", optopt);
>             errflg++;
>         }
>     }
>     if (errflg) {
>         fprintf(stderr, "usage: . . . ");
>         exit(2);
> 
> Which exemplifies the custom of printing the "usage" upon an error.
> Since '?' cannot be used as a getopt option, it is guaranteed to cause
> getopt to return '?' no matter what the option characters are.
> 
> I saw this on a SGI Irix, and I checked at www.opengroup.org for the POSIX
> standard.
> 
> Of course, if you're not following POSIX, and aren't using getopt, it  may not
> work.  Your personal experience of '-h' being a "help" option, probably carries
> less weight than the endorsement of POSIX ;-)

I don't see anything there that says that POSIX endorses '-?' for
displaying the usage message.  It just shows how to handle invalid option
characters.  If getopt sees an invalid character after '-' it returns '?' and puts the
invalid character ("?" in your example) in optopt.  In that example, I'd expect to see

Unrecognized option -?
<<usage message>>

From 'man bash':

getopts optstring name [args]
       getopts is used by shell procedures to parse positional parameters.   optstring  contains  the
       option  characters  to  be  recognized;  if  a character is followed by a colon, the option is
       expected to have an argument, which should be separated from it by white space.  The colon and
       question  mark  characters  may  not  be  used as option characters. . . .

I don't have the man page for getopt() handy, but I think it contains the
same restriction.

-- 
Mac :})
** I normally forward private questions to the appropriate mail list. **
Ask Smarter: http://www.tuxedo.org/~esr/faqs/smart-questions.html
Give a hobbit a fish and he eats fish for a day.
Give a hobbit a ring and he eats fish for an age.



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Michael A Chase]

On Wed, 29 May 2002 15:33:19 -0700 (Pacific Daylight Time) Michael A Chase <mchase@ix.netcom.com> wrote:

> I don't see anything there that says that POSIX endorses '-?' for
> displaying the usage message.  It just shows how to handle invalid option
> characters.  If getopt sees an invalid character after '-' it returns '?' and puts the
> invalid character ("?" in your example) in optopt.  In that example, I'd
> expect to see
. . .

I should have been explicit about one item.  Asking for help shouldn't be
an error.

-- 
Mac :})
** I normally forward private questions to the appropriate mail list. **
Ask Smarter: http://www.tuxedo.org/~esr/faqs/smart-questions.html
Give a hobbit a fish and he eats fish for a day.
Give a hobbit a ring and he eats fish for an age.



--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Bernard A Badger]

> -----Original Message-----
> From: cygwin-owner@cygwin.com [mailto:cygwin-owner@cygwin.com]On Behalf
> Of Michael A Chase
...
> On Wed, 29 May 2002 15:33:19 -0700 (Pacific Daylight Time) Michael A
> Chase <mchase@ix.netcom.com> wrote:
>
> > I don't see anything there that says that POSIX endorses '-?' for
> > displaying the usage message.  It just shows how to handle invalid option
> > characters.  If getopt sees an invalid character after '-' it
> returns '?' and puts the
> > invalid character ("?" in your example) in optopt.  In that example, I'd
> > expect to see
> . . .
>
> I should have been explicit about one item.  Asking for help shouldn't be
> an error.

Well, I agree with you.  That's why it's nice to have -h, or --help.  They're
not errors.  However, if you get -? what should you do?  Print the usage and
return an error.

According to the Cygwin Overview:
	The Cygwin tools are ports of the popular GNU development tools and
	utilities for Windows NT and 9x.
And the GNU guidelines support POSIX (with extensions).
<BLOCKQUOTE>
Standards for Command Line Interfaces

It is a good idea to follow the POSIX guidelines for the command-line options of
a program. The easiest way to do this is to use getopt to parse them. Note that
the GNU version of getopt will normally permit options anywhere among the
arguments unless the special argument `--' is used. This is not what POSIX
specifies; it is a GNU extension.
</BLOCKQUOTE>

A lot of commands with extensive "help" have a brief usage command that mentions
how to get the longer help.

My point---and I'm sticking to it---is that if you get -? you _should_ print
something.  I don't mind at all using -h and/or --help or even --tutorial,
but the bedrock of it all is to respond to the user that commits an error with
an intelligible message about usage.

I'd even concede that you don't have to put -? in the usage message itself.
It's sort of a ground-level default for getopt()-compatible commands.
From that point of view, -? is just a useful "trick" to see how the command
responds to errors.  However, since it is so convenient, I encourage
advertising its presence in the usage and man page.

Someone brought up the point about -? being wildcard.  This is true, and
users "should" be aware of this, even though there's hardly ever a file
name that matches it.  (If there were, <code>foo *</code> would generate
"options" instead of file names.  So this is something best avoided.
(BTW, you could say <code>foo ./*</code> to be safe.))

In http://www.gnu.org/prep/standards_18.html#SEC18
<BLOCKQUOTE>
All programs should support two standard options: `--version' and `--help'.
...
--help
This option should output brief documentation for how to invoke the program, on
standard output, then exit successfully. Other options and arguments should be
ignored once this is seen, and the program should not perform its normal
function.
</BLOCKQUOTE>

Strangely enough, the table of long options,
http://www.gnu.org/prep/standards_19.html#SEC19
doesn't mention -h as an alternative to --help.
In fact -h is only mentioned as a synonym to --header:
`header'
`-h' in objdump and recode

Using -? _should_ be considered an error, in the sense of non-zero return value.
The getopt example does this:
>     if (errflg) {
>         fprintf(stderr, "usage: . . . ");
>         exit(2);
In this (POSIX) example,
http://www.opengroup.org/onlinepubs/007904975/functions/getopt.html
-? (or some other error such as -a and -b together) was the only way
to generate the usage string.  The GNU standard is a bit more friendly,
requiring a consistent error-free way to generate usage.

Using --help (GNU required) or -h (AFAICS optional) should be considered
successful, and should return 0.





--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Bernard A Badger]

> On Wed, 29 May 2002 17:45:35 -0400 Bernard A Badger <bab@vx.com> wrote:
[SNIP] 
> I don't see anything there that says that POSIX endorses '-?' for
> displaying the usage message.  It just shows how to handle invalid option
> characters.  If getopt sees an invalid character after '-' it returns 
> '?' and puts the
> invalid character ("?" in your example) in optopt.  In that example, 
> I'd expect to see
> 
> Unrecognized option -?
> <<usage message>>
> 
> >From 'man bash':
> 
> getopts optstring name [args]
>        getopts is used by shell procedures to parse positional 
> parameters.   optstring  contains  the
>        option  characters  to  be  recognized;  if  a character is 
> followed by a colon, the option is
>        expected to have an argument, which should be separated from 
> it by white space.  The colon and
>        question  mark  characters  may  not  be  used as option 
> characters. . . .
> 
> I don't have the man page for getopt() handy, but I think it contains the
> same restriction.

Oh, I didn't understand what you meant.  You think that '-?' cannot be used
as an option.

Yes, it's true that you cannot have '?' as an legal option character.  
This is because getopt returns the option character that was used, 
and '?' is used as an error indication.  Whenever the user calls the 
command with an error, '?' is returned instead of a legal option character.  
Thus, all illegal options -- and options with missing arguments ---
conveniently come back as a single character '?'.  

But so does '-?' !  That means that '-?' is _always_ illegal.  
The programmer cannot make -? a legal option, 
but the user can deliberately invoke it as an illegal option syntax.
The user can _rely_ on it being erroneous!

If you provide an illegal option, the command is supposed to 
print a usage message to stderr and fail (return a non-zero error code).
That's exactly what the example did.

Since this is hard-coded into the getopt() function, many commands are
written with '-?' in mind.  Since the user can get a usage this way, 
it's not necessary, in POSIX, to have -h as an option.  
(But see my other mail about GNU and --help requirement.)

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Christopher Faylor]

On Thu, May 30, 2002 at 09:19:18AM -0400, Bernard A Badger wrote:
>In this (POSIX) example,
>http://www.opengroup.org/onlinepubs/007904975/functions/getopt.html
>-? (or some other error such as -a and -b together) was the only way
>to generate the usage string.  The GNU standard is a bit more friendly,
>requiring a consistent error-free way to generate usage.
>
>Using --help (GNU required) or -h (AFAICS optional) should be considered
>successful, and should return 0.

Have you actually tried the latest version of the cygwin utilities?  The
cygwin snapshots contain the very latest version of things like 'mount'.
Joshua Daniel Franklin has expended considerable effort in regularizing
the output of the commands wrt --help and usage output.

cgf
--
Please do not send me personal email with cygwin questions.
Use the resources at http://cygwin.com/ .

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

RE: trivial mkpasswd defect

[Bernard A Badger]

> -----Original Message-----
> From: cygwin-owner@cygwin.com [mailto:cygwin-owner@cygwin.com]On Behalf
> Of Christopher Faylor
> Sent: Thursday, May 30, 2002 11:20 AM
> To: cygwin@cygwin.com
> Subject: Re: trivial mkpasswd defect
>
> On Thu, May 30, 2002 at 09:19:18AM -0400, Bernard A Badger wrote:
> >In this (POSIX) example,
> >http://www.opengroup.org/onlinepubs/007904975/functions/getopt.html
> >-? (or some other error such as -a and -b together) was the only way
> >to generate the usage string.  The GNU standard is a bit more friendly,
> >requiring a consistent error-free way to generate usage.
> >
> >Using --help (GNU required) or -h (AFAICS optional) should be considered
> >successful, and should return 0.
>
> Have you actually tried the latest version of the cygwin utilities?  The
> cygwin snapshots contain the very latest version of things like 'mount'.
> Joshua Daniel Franklin has expended considerable effort in regularizing
> the output of the commands wrt --help and usage output.
Not to this point.  I was responding to what people wrote.
Don't try to confuse the issue with the facts. ;-)

Corinna Vinschen said something ambiguous about -?, and that's what got me
started.
> > > 	$ mkpasswd -?
> > > 	mkpasswd: unknown option -- ?
> >
[Corinna]
> > Thanks.  This will go away in the next version.
[ME]
> I hope you mean that '-?' will work, not that '-?' will be taken out of the
> usage.
It is ambiguous because it isn't clear from the message what "this" refers to.

Of course, it was clear to Corinna Vinschen, and the patch submitter, Joshua D.
Franklin.

He said:
> She meant what she said. See
> http://cygwin.com/ml/cygwin-patches/2002-q2/msg00103.html
> for details. Or better yet, the CVS.

To me "what she said" was ambiguous.

Now, if I bother to check out the un-mentioned antecedents, by
looking in Mr. Franklin's patch,
http://cygwin.com/ml/cygwin-patches/2002-q2/msg00103/mkpasswd.c-patch
I have discovered these facts:
1) Nice patch!
2) -?, didn't change, it still prints out
	Try `mkpasswd --help' for more information.
3) The help message can, as always, only be printed using --help, or -h.
4) The help message erroneously said that -? would print the help message.
This is common POSIX practice, if the help message is short.
With GNU getopt_long, the messages are usually a bit more verbose,
and GNU requires --help anyway.
Thus -? often just says, in effect, "try '--help'".
5) The patch fixes this, typo,
"   -?,--help               displays this message\n\n"
into
"   -h,--help               displays this message\n"
I had thought that they were saying that they were changing mkpasswd to use
-h instead of -?.  What they were doing was changing the documentation to
match the program.

So, I'm happy now.
mkpasswd -h is fully documented, and
mkpasswd -? still produces a helpful error message.


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/

Re: trivial mkpasswd defect

[Joshua Daniel Franklin]

> > On Wed, May 29, 2002 at 10:14:14AM -0400, Jon LaBadie wrote:
> > > mkpasswd reports '?' is a valid help option but fails to accept it.
> > >
> > > 	$ mkpasswd --help
> > > 	Usage: mkpasswd [OPTION]... [domain]
> > >
> > > 	This program prints a /etc/passwd file to stdout
> > >
> > > 	Options:
> > > 		... snip ...
> > > 	   -?,--help               displays this message
> > >
> > > 	$ mkpasswd -?
> > > 	mkpasswd: unknown option -- ?
> >
> > Thanks.  This will go away in the next version.
> 
> I hope you mean that '-?' will work, not that '-?' will be taken out of the
> usage.
> 
She meant what she said. See 

http://cygwin.com/ml/cygwin-patches/2002-q2/msg00103.html

for details. Or better yet, the CVS.

__________________________________________________
Do You Yahoo!?
Yahoo! - Official partner of 2002 FIFA World Cup
http://fifaworldcup.yahoo.com

--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/