From abc@ai1.anchorage.mtaonline.net  Sat Jan  1 21:18:55 2005
Return-Path: <abc@ai1.anchorage.mtaonline.net>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id B70CD16A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  1 Jan 2005 21:18:55 +0000 (GMT)
Received: from ai1.anchorage.mtaonline.net (ai1.anchorage.mtaonline.net [12.21.201.252])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 1023743D3F
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  1 Jan 2005 21:18:54 +0000 (GMT)
	(envelope-from abc@ai1.anchorage.mtaonline.net)
Received: from en26.ai1.anchorage.mtaonline.net (root@faxsrvr [192.168.0.26])
	by ai1.anchorage.mtaonline.net (8.12.9p2/8.12.9) with ESMTP id j01LLXqc088998
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 1 Jan 2005 12:21:33 -0900 (AKST)
	(envelope-from abc@ai1.anchorage.mtaonline.net)
Received: (from abc@localhost)
	by en26.ai1.anchorage.mtaonline.net (8.12.11/8.12.11) id j01LMvuB044976;
	Sat, 1 Jan 2005 21:22:57 GMT
	(envelope-from abc@ai1.anchorage.mtaonline.net)
Message-Id: <200501012122.j01LMvuB044976@en26.ai1.anchorage.mtaonline.net>
Date: Sat, 1 Jan 2005 21:22:57 GMT
From: abc@ai1.anchorage.mtaonline.net
Reply-To:
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: opendir manpage

>Number:         75711
>Category:       docs
>Synopsis:       [patch] opendir(3) missing ERRORS section
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    keramida
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jan 01 21:20:15 GMT 2005
>Closed-Date:    
>Last-Modified:  Mon Dec 29 17:31:41 UTC 2008
>Originator:     Joe Public
>Release:        i386 FreeBSD 4.10-RELEASE
>Organization:
no org
>Environment:
FreeBSD ai1.anchorage.mtaonline.net 4.10-RELEASE FreeBSD 4.10-RELEASE #0: Mon Jul  5 18:00:22 AKDT 2004     root@:/usr/src/sys/compile/MYKERN  i386

>Description:
opendir() manpage missing errno info.
>How-To-Repeat:
man opendir(), only the closedir() info states errno settings.
>Fix:
state errno settings covering all functions in the manpage.
>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Ruslan Ermilov <ru@freebsd.org>
Cc: abc@ai1.anchorage.mtaonline.net, bug-followup@freebsd.org
Subject: Re: docs/75711: opendir manpage
Date: Wed, 2 Mar 2005 03:37:45 +0200

 abc@ai1.anchorage.mtaonline.net wrote:
 > man opendir(), only the closedir() info states errno settings.
 
 The opendir() implementation in libc calls the following functions or
 systems calls that may fail: close(), fcntl(), fstat(), malloc(),
 mergesort(), open(), stat(), reallocf().
 
 Should we document the join of all the possible errors these calls may
 fail with in opendir()'s manpage?

From: abc@ai1.anchorage.mtaonline.net
To: "Giorgos Keramidas" <keramida@freebsd.org>
Cc: abc@ai1.anchorage.mtaonline.net, bug-followup@freebsd.org
Subject: Re: docs/75711: opendir manpage
Date: Wed, 2 Mar 2005 03:49:15 GMT

 > abc@ai1.anchorage.mtaonline.net wrote:
 > > man opendir(), only the closedir() info states errno settings.
 
 > The opendir() implementation in libc calls the following functions or
 > systems calls that may fail: close(), fcntl(), fstat(), malloc(),
 > mergesort(), open(), stat(), reallocf().
 
 > Should we document the join of all the possible errors these calls may
 > fail with in opendir()'s manpage?
 
 the manpage should at LEAST state that it sets the
 extern "errno", otherwise, it is assumed it doesn't,
 and this assumption can easily result in programming
 catastrophies.
 
 if "errno" is not documented, and thus, not checked
 for in a program, "errno" will get trapped by some
 other function that does check for it.
 
 all calls that may set "errno" should explicity
 say so - so programmers can check for it after
 a call.
 
 thank you.
Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Thu Mar 3 17:31:18 GMT 2005 
Responsible-Changed-Why:  
I'll work on adding a proper ERRORS section to opendir(3). 

http://www.freebsd.org/cgi/query-pr.cgi?pr=75711 

From: Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/75711: opendir(3) missing ERRORS section
Date: Thu, 17 May 2007 10:56:51 +0200

 --5vNYLRcllDrimb99
 Content-Type: text/plain; charset=utf-8
 Content-Disposition: inline
 Content-Transfer-Encoding: 8bit
 
 Here's a patch that cleans up some of directory(3).
 I've tested the errors and actually encountered a case where you can get
 EFAULT returned from stat() since the call just passes along blindly a NULL
 argument if you gave that to opendir() as dirname argument. Also attached is a
 short-circuit for that case in libc/gen/diropen.c. I think it makes sense to
 return ENOENT for that case since it fits the description.
 I've also renamed filename to dirname to more accurately reflect what the call
 operates on.
 For the wording of the added text I used the SUS texts, since I understand we
 have permission to do that nowadays.
 
 This manual page will need further cleanups, most likely resulting in the
 splitting of some calls to their own pages to keep the layout sane enough to
 follow.
 
 Please add a [patch] in front of the PR's synopsis.
 
 -- 
 Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
 イェルーン ラウフロック ヴァン デル ウェルヴェン
 http://www.in-nomine.org/ | http://www.rangaku.org/
 All conditioned things are impermanent. Work out your own salvation with
 diligence...
 
 --5vNYLRcllDrimb99
 Content-Type: text/x-diff; charset=us-ascii
 Content-Disposition: attachment; filename="libc-gen-directory.3.diff"
 
 Index: directory.3
 ===================================================================
 RCS file: /usr/ncvs/FreeBSD/src/lib/libc/gen/directory.3,v
 retrieving revision 1.16
 diff -u -r1.16 directory.3
 --- directory.3	9 Jan 2007 00:27:53 -0000	1.16
 +++ directory.3	17 May 2007 08:42:44 -0000
 @@ -47,7 +47,7 @@
  .In sys/types.h
  .In dirent.h
  .Ft DIR *
 -.Fn opendir "const char *filename"
 +.Fn opendir "const char *dirname"
  .Ft struct dirent *
  .Fn readdir "DIR *dirp"
  .Ft int
 @@ -67,7 +67,7 @@
  .Fn opendir
  function
  opens the directory named by
 -.Fa filename ,
 +.Fa dirname ,
  associates a
  .Em directory stream
  with it
 @@ -75,13 +75,6 @@
  returns a pointer to be used to identify the
  .Em directory stream
  in subsequent operations.
 -The pointer
 -.Dv NULL
 -is returned if
 -.Fa filename
 -cannot be accessed, or if it cannot
 -.Xr malloc 3
 -enough memory to hold the whole thing.
  .Pp
  The
  .Fn readdir
 @@ -184,12 +177,56 @@
  (void)closedir(dirp);
  return NOT_FOUND;
  .Ed
 +.Sh RETURN VALUES
 +Upon successful completion,
 +.Fn opendir
 +shall return a pointer to an object of type DIR.
 +Otherwise, a null pointer shall be returned and
 +.Va errno
 +set to indicate the error.
 +.Sh ERRORS
 +The
 +.Fn opendir
 +function shall fail if:
 +.Bl -tag -width Er
 +.It Bq Er EACCESS
 +Search permission is denied for the component of the path prefix of
 +.Fa dirname
 +or read permission is denied for
 +.Fa dirname .
 +.It Bq Er ELOOP
 +A loop exists in symbolic links encountered during resolution of the
 +.Fa dirname
 +argument.
 +.It Bq Er ENAMETOOLONG
 +The length of the
 +.Fa dirname
 +argument exceeds
 +.Brq Dv PATH_MAX
 +or
 +a pathname component is longer than
 +.Brq Dv NAME_MAX .
 +.It Bq Er ENOENT
 +A component of
 +.Fa dirname
 +does not name an existing directory or
 +.Fa dirname
 +is an empty string.
 +.It Bq Er ENOTDIR
 +A component of
 +.Fa dirname
 +is not a directory.
  .Sh SEE ALSO
  .Xr close 2 ,
  .Xr lseek 2 ,
  .Xr open 2 ,
  .Xr read 2 ,
  .Xr dir 5
 +.Sh STANDARDS
 +The function
 +.Fn opendir
 +is believed to conform to
 +.St -p1003.1-2004 .
  .Sh HISTORY
  The
  .Fn opendir ,
 Index: opendir.c
 ===================================================================
 RCS file: /usr/ncvs/FreeBSD/src/lib/libc/gen/opendir.c,v
 retrieving revision 1.23
 diff -u -r1.23 opendir.c
 --- opendir.c	9 Jan 2007 00:27:54 -0000	1.23
 +++ opendir.c	17 May 2007 08:53:25 -0000
 @@ -54,6 +54,10 @@
  opendir(name)
  	const char *name;
  {
 +	if (name == NULL) {
 +		errno = ENOENT;
 +		return (NULL);
 +	}
  
  	return (__opendir2(name, DTF_HIDEW|DTF_NODUP));
  }
 
 --5vNYLRcllDrimb99--
>Unformatted:
