docs/127908: [PATCH] readdir(3) error documentation

[Matthew D. Fuller]

>Number:         127908
>Category:       docs
>Synopsis:       [PATCH] readdir(3) error documentation
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Oct 07 01:40:01 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     Matthew D. Fuller
>Release:        FreeBSD 7.0-BETA4 i386
>Organization:
>Environment:
System: FreeBSD draco.over-yonder.net 7.0-BETA4 FreeBSD 7.0-BETA4 #0: Sun Dec 9 18:37:58 CST 2007 root at draco.over-yonder.net:/bsd/obj/bsd/src/sys/DRACO i386


	
>Description:
	The manpage for readdir(3) doesn't document the possible error
	returns.  The only mention it makes in fact is misleading, since it
	doesn't describe something that can happen.

	The rest of the functions really should have their errno values
	documented as well, probably with the addition of a ERRORS section to
	the manpage.  But this patch gets one step closer, anyway.

>How-To-Repeat:
	
>Fix:


Index: directory.3
===================================================================
RCS file: /usr/cvs/src/lib/libc/gen/directory.3,v
retrieving revision 1.17
diff -u -r1.17 directory.3
--- directory.3	16 Apr 2008 18:59:36 -0000	1.17
+++ directory.3	7 Oct 2008 01:26:30 -0000
@@ -122,9 +122,12 @@
 returns a pointer to the next directory entry.
 It returns
 .Dv NULL
-upon reaching the end of the directory or detecting an invalid
-.Fn seekdir
-operation.
+upon reaching the end of the directory or on error.
+In the event of an error,
+.Va errno
+may be set to any of the values documented for the
+.Xr getdirentries 2
+system call.
 .Pp
 The
 .Fn readdir_r

>Release-Note:
>Audit-Trail:
>Unformatted: