Confusion over wording in glob(3)

[Garrett Cooper]

On Mon, Aug 2, 2010 at 12:35 AM, Garrett Cooper <yanegomi at gmail.com> wrote:
>    I have some question about the ambiguity of the ERRORS section in
> our glob(3) manpage.
>
> POSIX states:
>
> ERRORS
>
>    The glob() function shall fail and return the corresponding value if:
>
>    GLOB_ABORTED
>        The scan was stopped because GLOB_ERR was set or (*errfunc())
> returned non-zero.
>    GLOB_NOMATCH
>        The pattern does not match any existing pathname, and
> GLOB_NOCHECK was not set in flags.
>    GLOB_NOSPACE
>        An attempt to allocate memory failed.
>
> (Note that there's no mention of `errno').
> Our manpage states:
>
>     If glob() terminates due to an error, it sets errno and returns one of
>     the following non-zero constants, which are defined in the include file
>     <glob.h>:
>
>     GLOB_NOSPACE  An attempt to allocate memory failed, or if errno was 0
>                   GLOB_LIMIT was specified in the flags and pglob->gl_matchc
>                   or more patterns were matched.
>
>     GLOB_ABORTED  The scan was stopped because an error was encountered and
>                   either GLOB_ERR was set or (*errfunc)() returned non-zero.
>
>     GLOB_NOMATCH  The pattern did not match a pathname and GLOB_NOCHECK was
>                   not set.
>
> (Note the mention of errno).
> So far I've only been able to hit a sensical error case once by doing
> the following (but that could have been a side-effect from a malloc(3)
> failure in terms of finding malloc.conf -- don't know for sure). The
> rest of the time I get errno = 0:
>
> $ cc -o test_glob test_glob.c
> $ ln -f test_glob test_glob_nomatch
> $ ./test_glob_nomatch
> NOMATCH
> glob(./test_glob_nomatch.*) didn't match: 0: Unknown error: 0
>
> So I suppose my question is: should the confusing wording be removed
> for clarity?

    Looking over the manpages a bit more closely, it might help if I
had specified GLOB_ERR -- but it would help if that was spelled out
more clearly in the manpage (I tend to skim to the bottom of manpages
for the error and return code sections, so I missed that point).
Thanks!
-Garrett