1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1996 Doug Rabson 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd August 8, 2018 30.Dt VOP_LOOKUP 9 31.Os 32.Sh NAME 33.Nm VOP_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_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. 52It is a pointer to a componentname structure defined as follows: 53.Bd -literal 54struct componentname { 55 /* 56 * Arguments to lookup. 57 */ 58 u_long cn_nameiop; /* namei operation */ 59 u_long cn_flags; /* flags to namei */ 60 struct thread *cn_thread; /* thread requesting lookup */ 61 struct ucred *cn_cred; /* credentials */ 62 int cn_lkflags; /* Lock flags LK_EXCLUSIVE or LK_SHARED */ 63 /* 64 * Shared between lookup and commit routines. 65 */ 66 char *cn_pnbuf; /* pathname buffer */ 67 char *cn_nameptr; /* pointer to looked up name */ 68 long cn_namelen; /* length of looked up component */ 69}; 70.Ed 71.El 72.Pp 73Convert a component of a pathname into a pointer to a locked vnode. 74This is a very central and rather complicated routine. 75If the file system is not maintained in a strict tree hierarchy, 76this can result in a deadlock situation. 77.Pp 78The 79.Fa cnp->cn_nameiop 80argument is 81.Dv LOOKUP , 82.Dv CREATE , 83.Dv RENAME , 84or 85.Dv DELETE 86depending on the intended use of the object. 87When 88.Dv CREATE , 89.Dv RENAME , 90or 91.Dv DELETE 92is specified, information usable in 93creating, renaming, or deleting a directory entry may be calculated. 94.Pp 95Overall outline of VOP_LOOKUP: 96.Bd -ragged -offset indent 97Check accessibility of directory. 98Look for name in cache, if found, then return name. 99Search for name in directory, goto to found or notfound as appropriate. 100.Ed 101.Pp 102notfound: 103.Bd -ragged -offset indent 104If creating or renaming and at end of pathname, 105return 106.Er EJUSTRETURN , 107leaving info on available slots else return 108.Er ENOENT . 109.Ed 110.Pp 111found: 112.Bd -ragged -offset indent 113If at end of path and deleting, return information to allow delete. 114If at end of path and renaming, lock target 115inode and return info to allow rename. 116If not at end, add name to cache; if at end and neither creating 117nor deleting, add name to cache. 118.Ed 119.Sh LOCKS 120The directory 121.Fa dvp 122should be locked on entry and exit, regardless of error condition. 123If an entry is found in the directory, it will be returned locked. 124.Sh RETURN VALUES 125Zero is returned with 126.Fa *vpp 127set to the locked vnode of the file if the component is found. 128If the component being searched for is ".", then the vnode just has 129an extra reference added to it with 130.Xr vref 9 . 131The caller must take care to release the locks appropriately in this 132case. 133.Pp 134If the component is not found and the operation is 135.Dv CREATE 136or 137.Dv RENAME , 138the flag 139.Dv ISLASTCN 140is specified and the operation would succeed, the special return value 141.Er EJUSTRETURN 142is returned. 143Otherwise, an appropriate error code is returned. 144.Sh ERRORS 145.Bl -tag -width Er 146.It Bq Er ENOTDIR 147The vnode 148.Fa dvp 149does not represent a directory. 150.It Bq Er ENOENT 151The component 152.Fa dvp 153was not found in this directory. 154.It Bq Er EACCES 155Access for the specified operation is denied. 156.It Bq Er EJUSTRETURN 157A 158.Dv CREATE 159or 160.Dv RENAME 161operation would be successful. 162.El 163.Sh SEE ALSO 164.Xr vnode 9 , 165.Xr VOP_ACCESS 9 , 166.Xr VOP_CREATE 9 , 167.Xr VOP_MKDIR 9 , 168.Xr VOP_MKNOD 9 , 169.Xr VOP_RENAME 9 , 170.Xr VOP_SYMLINK 9 171.Sh HISTORY 172The function 173.Nm 174appeared in 175.Bx 4.3 . 176.Sh AUTHORS 177This manual page was written by 178.An Doug Rabson , 179with some text from comments in 180.Pa ufs_lookup.c . 181