From nobody@FreeBSD.org  Thu Jan 14 05:20:54 2010
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 80EEF106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 14 Jan 2010 05:20:54 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 565638FC19
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 14 Jan 2010 05:20:54 +0000 (UTC)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id o0E5KsmT030633
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 14 Jan 2010 05:20:54 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id o0E5KsgU030632;
	Thu, 14 Jan 2010 05:20:54 GMT
	(envelope-from nobody)
Message-Id: <201001140520.o0E5KsgU030632@www.freebsd.org>
Date: Thu, 14 Jan 2010 05:20:54 GMT
From: Lachlan Kang <LCRTRIfFu91c710azO2Y@live.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] namei(9) return values
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         142816
>Category:       docs
>Synopsis:       [patch] namei(9) return values
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 14 05:30:02 UTC 2010
>Closed-Date:    Thu Jan 14 15:26:14 UTC 2010
>Last-Modified:  Thu Jan 14 17:34:52 UTC 2010
>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:

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/142816: commit references a PR
Date: Thu, 14 Jan 2010 14:36:54 +0000 (UTC)

 Author: jhb
 Date: Thu Jan 14 14:36:39 2010
 New Revision: 202284
 URL: http://svn.freebsd.org/changeset/base/202284
 
 Log:
   - Update required headers for namei() to add <sys/fcntl.h> and remove
     <sys/proc.h>.
   - Add RETURN VALUES and ERROR sections for namei()'s error return values.
   - Add a missing link to NDHASGIANT.9.
   
   PR:		docs/142815, docs/142816
   Submitted by:	Lachlan Kang (1, 2)
   MFC after:	3 days
 
 Modified:
   head/share/man/man9/Makefile
   head/share/man/man9/namei.9
 
 Modified: head/share/man/man9/Makefile
 ==============================================================================
 --- head/share/man/man9/Makefile	Thu Jan 14 14:30:54 2010	(r202283)
 +++ head/share/man/man9/Makefile	Thu Jan 14 14:36:39 2010	(r202284)
 @@ -903,7 +903,8 @@ MLINKS+=mutex.9 mtx_assert.9 \
  	mutex.9 mtx_unlock_spin.9 \
  	mutex.9 mtx_unlock_spin_flags.9
  MLINKS+=namei.9 NDFREE.9 \
 -	namei.9 NDINIT.9
 +	namei.9 NDINIT.9 \
 +	namei.9 NDHASGIANT.9
  MLINKS+=pbuf.9 getpbuf.9 \
  	pbuf.9 relpbuf.9 \
  	pbuf.9 trypbuf.9
 
 Modified: head/share/man/man9/namei.9
 ==============================================================================
 --- head/share/man/man9/namei.9	Thu Jan 14 14:30:54 2010	(r202283)
 +++ head/share/man/man9/namei.9	Thu Jan 14 14:36:39 2010	(r202284)
 @@ -44,7 +44,7 @@
  .Nd pathname translation and lookup operations
  .Sh SYNOPSIS
  .In sys/param.h
 -.In sys/proc.h
 +.In sys/fcntl.h
  .In sys/namei.h
  .Ft int
  .Fn namei "struct nameidata *ndp"
 @@ -315,6 +315,34 @@ flag can be passed to the
  .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 ENOTDIR
 +A component of the specified pathname is not a directory when a directory is
 +expected.
 +.It Bq Er ENAMETOOLONG
 +A component of a pathname exceeded 255 characters,
 +or an entire pathname exceeded 1023 characters.
 +.It Bq Er ENOENT
 +A component of the specified pathname does not exist,
 +or the pathname is an empty string.
 +.It Bq Er ACCES
 +An attempt is made to access a file in a way forbidden by its file access
 +permissions.
 +.It Bq Er ELOOP
 +Too many symbolic links were encountered in translating the pathname.
 +.It Bq Er EISDIR
 +An attempt is made to open a directory with write mode specified.
 +.It Bq Er EROFS
 +An attempt is made to modify a file or directory on a read-only file system.
 +.El
  .Sh FILES
  .Bl -tag
  .It Pa src/sys/kern/vfs_lookup.c
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: John Baldwin <jhb@freebsd.org>
To: freebsd-doc@freebsd.org
Cc: Lachlan Kang <LCRTRIfFu91c710azO2Y@live.co.uk>,
 freebsd-gnats-submit@freebsd.org
Subject: Re: docs/142816: [patch] namei(9) return values
Date: Thu, 14 Jan 2010 09:30:43 -0500

 Thanks!  I've modified this slightly (added missing line breaks to ease 
 translation work) and changed the error descriptions to more closely match 
 what is used in open(2).
 
 -- 
 John Baldwin
State-Changed-From-To: open->closed 
State-Changed-By: jhb 
State-Changed-When: Thu Jan 14 15:25:45 UTC 2010 
State-Changed-Why:  
Fix committed, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=142816 
>Unformatted:
