docs/142816: [patch] namei(9) return values

[Lachlan Kang]

>Number:         142816
>Category:       docs
>Synopsis:       [patch] namei(9) return values
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 14 05:30:02 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator:     Lachlan Kang
>Release:        FreeBSD 8.0-RELEASE
>Organization:
>Environment:
>Description:
The manpage namei(9) does not specify the return value of the function namei().
The function namei() returns 0 on success, or errno on failure.
I skimmed through the namei() source code (src/sys/kern/vfs_lookup.c) and added a simple RETURN VALUES and ERRORS section to the namei(9) manpage.
The error code descriptions were simply copied from intro(2).
>How-To-Repeat:
man 9 namei
>Fix:
Add a RETURN VALUES and ERRORS section to namei(9).

Patch attached with submission follows:

Index: head/share/man/man9/namei.9
===================================================================
--- head/share/man/man9/namei.9	(revision 202273)
+++ head/share/man/man9/namei.9	(working copy)
@@ -315,6 +315,30 @@
 .Fn NDFREE
 function.
 .El
+.Sh RETURN VALUES
+If successful,
+.Fn namei
+will return 0, otherwise it will return an error.
+.Sh ERRORS
+Errors which
+.Fn namei
+may return:
+.Bl -tag -width Er
+.It Bq Er ENOENT
+No such file or directory. A component of a specified pathname did not exist, or the pathname was an empty string.
+.It Bq Er ACCES
+Permission denied. An attempt was made to access a file in a way forbidden by its file access permissions.
+.It Bq Er ENOTDIR
+Not a directory. A component of the specified pathname existed, but it was not a directory, when a directory was expected.
+.It Bq Er EISDIR
+Is a directory. An attempt was made to open a directory with write mode specified.
+.It Bq Er EROFS
+Read-only file system. An attempt was made to modify a file or directory on a file system that was read-only at the time.
+.It Bq Er ELOOP
+Too many levels of symbolic links. A path name lookup involved more than 32 (MAXSYMLINKS) symbolic links.
+.It Bq Er ENAMETOOLONG
+File name too long. A component of a path name exceeded {NAME_MAX} characters, or an entire path name exceeded {PATH_MAX} characters.
+.El
 .Sh FILES
 .Bl -tag
 .It Pa src/sys/kern/vfs_lookup.c


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