1.\" Copyright (c) 1996 Doug Rabson 2.\" 3.\" All rights reserved. 4.\" 5.\" This program is free software. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/VOP_LOOKUP.9,v 1.8.2.5 2001/12/17 11:30:18 ru Exp $ 28.\" 29.Dd October 13, 2014 30.Dt VOP_OLD_LOOKUP 9 31.Os 32.Sh NAME 33.Nm VOP_OLD_LOOKUP 34.Nd lookup a component of a pathname 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/vnode.h 38.In sys/namei.h 39.Ft int 40.Fn VOP_OLD_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" 41.Sh DESCRIPTION 42This entry point looks up a single pathname component in a given directory. 43.Pp 44Its arguments are: 45.Bl -tag -width vpp 46.It Fa dvp 47the locked vnode of the directory to search 48.It Fa vpp 49the address of a variable where the resulting locked vnode should be stored 50.It Fa cnp 51the pathname component to be searched for 52.El 53.Pp 54.Fa Cnp 55is a pointer to a componentname structure defined as follows: 56.Bd -literal 57struct componentname { 58 /* 59 * Arguments to lookup. 60 */ 61 u_long cn_nameiop; /* namei operation */ 62 u_long cn_flags; /* flags to namei */ 63 struct thread *cn_td; /* process requesting lookup */ 64 struct ucred *cn_cred; /* credentials */ 65 /* 66 * Shared between lookup and commit routines. 67 */ 68 char *cn_nameptr; /* pointer to looked up name */ 69 long cn_namelen; /* length of looked up component */ 70 long cn_consume; /* chars to consume in lookup() */ 71 int cn_timeout; /* if CNP_CACHETIMEOUT is set, in ticks */ 72 struct vnode *cn_notvp; /* used by NFS to check for collision */ 73}; 74.Ed 75.Pp 76Convert a component of a pathname into a pointer to a locked vnode. 77This is a very central and rather complicated routine. 78If the file system is not maintained in a strict tree hierarchy, 79this can result in a deadlock situation. 80.Pp 81The 82.Fa cnp->cn_nameiop 83argument is 84.Dv NAMEI_LOOKUP , 85.Dv NAMEI_CREATE , 86.Dv NAMEI_RENAME , 87or 88.Dv NAMEI_DELETE 89depending on the intended use of the object. 90When 91.Dv NAMEI_CREATE , 92.Dv NAMEI_RENAME , 93or 94.Dv NAMEI_DELETE 95is specified, information usable in 96creating, renaming, or deleting a directory entry may be calculated. 97.Pp 98Overall outline of VOP_LOOKUP: 99.Bd -ragged -offset indent 100Check accessibility of directory. 101Look for name in cache, if found, then return name. 102Search for name in directory, goto to found or notfound as appropriate. 103.Ed 104.Pp 105notfound: 106.Bd -ragged -offset indent 107If creating or renaming and at end of pathname, 108return 109.Er EJUSTRETURN , 110leaving info on available slots else return 111.Er ENOENT . 112.Ed 113.Pp 114found: 115.Bd -ragged -offset indent 116If at end of path and deleting, return information to allow delete. 117If at end of path and renaming, lock target 118inode and return info to allow rename. 119If not at end, add name to cache; if at end and neither creating 120nor deleting, add name to cache. 121.Ed 122.Sh LOCKS 123The directory, 124.Fa dvp 125should be locked on entry. 126If an error (note: the return value 127.Er EJUSTRETURN 128is not considered an error) 129is detected, it will be returned locked. 130Otherwise, it will be unlocked unless 131.Dv CNP_LOCKPARENT 132is specified in 133.Fa cnp->cn_flags . 134If an entry is found in the directory, it will be returned locked. 135.Sh RETURN VALUES 136Zero is returned with 137.Fa *vpp 138set to the locked vnode of the file if the component is found. 139If the component being searched for is ".", then the vnode just has 140an extra reference added to it with 141.Xr vref 9 . 142The caller must take care to release the locks appropriately in this 143case. 144.Pp 145If the component is not found and the operation is 146.Dv NAMEI_CREATE 147or 148.Dv NAMEI_RENAME 149the special return value 150.Er EJUSTRETURN 151is returned. 152Otherwise, an appropriate error code is returned. 153.Sh ERRORS 154.Bl -tag -width Er 155.It Bq Er ENOTDIR 156The vnode 157.Fa dvp 158does not represent a directory. 159.It Bq Er ENOENT 160The component 161.Fa dvp 162was not found in this directory. 163.It Bq Er EACCES 164access for the specified operation is denied. 165.It Bq Er EJUSTRETURN 166a 167.Dv NAMEI_CREATE 168or 169.Dv NAMEI_RENAME 170operation would be successful 171.El 172.Sh SEE ALSO 173.Xr vnode 9 , 174.Xr VOP_ACCESS 9 , 175.Xr VOP_OLD_CREATE 9 , 176.Xr VOP_OLD_MKDIR 9 , 177.Xr VOP_OLD_MKNOD 9 , 178.Xr VOP_OLD_RENAME 9 , 179.Xr VOP_OLD_SYMLINK 9 180.Sh HISTORY 181The function 182.Nm 183appeared in 184.Bx 4.3 . 185.Sh AUTHORS 186This man page was written by 187.An Doug Rabson , 188with some text from comments in 189.Pa sys/vfs/ufs/ufs_lookup.c . 190