From owner-freebsd-standards@FreeBSD.ORG  Mon Aug  2 07:35:39 2010
Return-Path: <owner-freebsd-standards@FreeBSD.ORG>
Delivered-To: standards@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 48D331065673
	for <standards@freebsd.org>; Mon,  2 Aug 2010 07:35:39 +0000 (UTC)
	(envelope-from yanegomi@gmail.com)
Received: from mail-gy0-f182.google.com (mail-gy0-f182.google.com
	[209.85.160.182])
	by mx1.freebsd.org (Postfix) with ESMTP id 086F88FC13
	for <standards@freebsd.org>; Mon,  2 Aug 2010 07:35:38 +0000 (UTC)
Received: by gyg4 with SMTP id 4so1471608gyg.13
	for <standards@freebsd.org>; Mon, 02 Aug 2010 00:35:38 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=domainkey-signature:mime-version:received:received:date:message-id
	:subject:from:to:content-type;
	bh=FIRyN4BRV1q2/99YbzPgXmflVhnAasCNdDpvHszu7fo=;
	b=X9iGoy+EJq11EyQa+fd5BxdccDc4avghQltsA5yHpHnY5Drl95NVmUfoHDqHDq60dZ
	yxEgp3aCeOh1KnSJ4hNLlsxIZg2Bl0soLdJQSR77RU/rDWx3cXANrojoKKWchHPs93gT
	CinWVGdpRJFFFQ5bYl8bYb4wAM83fkjyXOjUE=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:date:message-id:subject:from:to:content-type;
	b=v9h/9n3IUaWVap+Y/wEofiNZmOJuqmqBHTQrPino1W0yGC4a4tM7ZGpSZQeD1+8CiB
	IjrKgOPCxV/OqI6/LZS99JRQbU2TwtG5oIcJCV+afeui4MskrAjaNv2yj3YyjobPcoXU
	e58DpCmmWzo8wg9LU9jtoFctoHIiuAsO3P+6M=
MIME-Version: 1.0
Received: by 10.150.170.15 with SMTP id s15mr6330920ybe.400.1280734538181; 
	Mon, 02 Aug 2010 00:35:38 -0700 (PDT)
Received: by 10.231.187.104 with HTTP; Mon, 2 Aug 2010 00:35:38 -0700 (PDT)
Date: Mon, 2 Aug 2010 00:35:38 -0700
Message-ID: <AANLkTinoKOxBxQ0NmXyXvHuTeNQ9Nx=HGgGwb8pAK-xF@mail.gmail.com>
From: Garrett Cooper <yanegomi@gmail.com>
To: standards@freebsd.org
Content-Type: text/plain; charset=ISO-8859-1
Cc: 
Subject: Confusion over wording in glob(3)
X-BeenThere: freebsd-standards@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: Standards compliance <freebsd-standards.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-standards>, 
	<mailto:freebsd-standards-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-standards>
List-Post: <mailto:freebsd-standards@freebsd.org>
List-Help: <mailto:freebsd-standards-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-standards>, 
	<mailto:freebsd-standards-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Mon, 02 Aug 2010 07:35:39 -0000

    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?

Thanks,
-Garrett

/* test_glob.c */
#include <err.h>
#include <errno.h>
#include <glob.h>
#include <limits.h>
#include <stdio.h>
#include <string.h>

int
main(int argc, char **argv)
{
	char p[PATH_MAX];
	glob_t globp;
	int err, ret;

	sprintf(p, "%s.*", *argv);

	printf("glob(%s) ", p);
	ret = glob(p, GLOB_NOESCAPE, NULL, &globp);
	err = errno;
	if (ret == 0) {
		if (globp.gl_pathc)
			printf("matches !\n");
		else
			errx(1, "what what...?\n");
	} else {
		switch (ret) {
		case GLOB_NOSPACE:
			fprintf(stderr, "NOSPACE\n");
			break;
		case GLOB_ABORTED:
			fprintf(stderr, "ABORTED\n");
			break;
		case GLOB_NOMATCH:
			fprintf(stderr, "NOMATCH\n");
			break;
		default:
			fprintf(stderr, "unknown: %d\n", ret);
		}
		printf("didn't match: %d: %s\n", err, strerror(err));
	}

	globfree(&globp);
	return (ret);
}