xref: /netbsd-src/share/man/man9/vnsubr.9 (revision b7b7574d3bf8eeb51a1fa3977b59142ec6434a55)
1.\"     $NetBSD: vnsubr.9,v 1.42 2014/02/27 16:51:37 hannken Exp $
2.\"
3.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Gregory McGarry.
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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd February 27, 2014
31.Dt VNSUBR 9
32.Os
33.Sh NAME
34.Nm vnsubr ,
35.Nm vn_bwrite ,
36.Nm vn_close ,
37.Nm vn_default_error ,
38.Nm vn_isunder ,
39.Nm vn_lock ,
40.Nm vn_markexec ,
41.Nm vn_marktext ,
42.Nm vn_rdwr ,
43.Nm vn_open ,
44.Nm vn_stat ,
45.Nm vn_writechk
46.Nd high-level convenience functions for vnode operations
47.Sh SYNOPSIS
48.In sys/param.h
49.In sys/lock.h
50.In sys/vnode.h
51.Ft int
52.Fn vn_bwrite "void *ap"
53.Ft int
54.Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred"
55.Ft int
56.Fn vn_default_error "void *v"
57.Ft int
58.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l"
59.Ft int
60.Fn vn_lock "struct vnode *vp" "int flags"
61.Ft void
62.Fn vn_markexec "struct vnode *vp"
63.Ft void
64.Fn vn_marktext "struct vnode *vp"
65.Ft int
66.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode"
67.Ft int
68.Fo vn_rdwr
69.Fa "enum uio_rw rw" "struct vnode *vp" "void *base"
70.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg"
71.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l"
72.Fc
73.Ft int
74.Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies"
75.Ft int
76.Fn vn_stat "struct vnode *vp" "struct stat *sb"
77.Ft int
78.Fn vn_writechk "struct vnode *vp"
79.Sh DESCRIPTION
80The high-level functions described in this page are convenience
81functions for simplified access to the vnode operations described in
82.Xr vnodeops 9 .
83.Sh FUNCTIONS
84.Bl -tag -width compact
85.It Fn vn_bwrite "ap"
86Common code for block write operations.
87.It Fn vn_close "vp" "flags" "cred"
88Common code for a vnode close.
89The argument
90.Fa vp
91is the unlocked vnode of the vnode to close.
92.Fn vn_close
93simply locks the vnode, invokes the vnode operation
94.Xr VOP_CLOSE 9
95and calls
96.Fn vput
97to return the vnode to the freelist or holdlist.
98Note that
99.Fn vn_close
100expects an unlocked, referenced vnode and will dereference the vnode
101prior to returning.
102If the operation is successful zero is returned,
103otherwise an appropriate error is returned.
104.It Fn vn_default_error "v"
105A generic "default" routine that just returns error.
106It is used by a file system to specify unsupported operations in
107the vnode operations vector.
108.It Fn vn_isunder "dvp" "rvp" "l"
109Common code to check if one directory specified by the vnode
110.Fa rvp
111can be found inside the directory specified by the vnode
112.Fa dvp .
113The argument
114.Fa l
115is the calling process.
116.Fn vn_isunder
117is intended to be used in
118.Xr chroot 2 ,
119.Xr chdir 2 ,
120.Xr fchdir 2 ,
121etc., to ensure that
122.Xr chroot 2
123actually means something.
124If the operation is successful zero is returned, otherwise 1 is returned.
125.It Fn vn_lock "vp" "flags"
126Common code to acquire the lock for vnode
127.Fa vp .
128The argument
129.Fa flags
130specifies the flags used to lock the vnode.
131There are the following flags:
132.Pp
133.Bl -tag -offset indent -width LK_EXCLUSIVE -compact
134.It LK_SHARED
135shared lock
136.It LK_EXCLUSIVE
137exclusive lock
138.It LK_NOWAIT
139do not sleep to await lock
140.It LK_RETRY
141allow lock operation on dead vnode
142.El
143.Pp
144If the operation is successful zero is returned, otherwise an
145appropriate error code is returned.
146.Pp
147.Fn vn_lock
148must not be called when the vnode's reference count is zero.
149Instead,
150.Xr vget 9
151should be used.
152.It Fn vn_markexec "vp"
153Common code to mark the vnode
154.Fa vp
155as containing executable code of a running process.
156.It Fn vn_marktext "vp"
157Common code to mark the vnode
158.Fa vp
159as being the text of a running process.
160.It Fn vn_open "ndp" "fmode" "cmode"
161Common code for vnode open operations.
162The pathname is described in the nameidata pointer (see
163.Xr namei 9 ) .
164The arguments
165.Fa fmode
166and
167.Fa cmode
168specify the
169.Xr open 2
170file mode and the access permissions for creation.
171.Fn vn_open
172checks  permissions and invokes the
173.Xr VOP_OPEN 9
174or
175.Xr VOP_CREATE 9
176vnode operations.
177If the operation is successful zero is returned and the vnode is locked,
178otherwise an appropriate error code is returned.
179.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l"
180Common code to package up an I/O request on a vnode into a uio and
181then perform the I/O.
182The argument
183.Fa rw
184specifies whether the I/O is a read
185.Pq Dv UIO_READ
186or write
187.Pq Dv UIO_WRITE
188operation.
189The vnode is specified by
190.Fa vp .
191The arguments
192.Fa l
193and
194.Fa cred
195are the calling lwp and its credentials.
196If
197.Fa ioflg
198contains
199.Dv IO_NODELOCKED ,
200it is expected that the vnode is locked.
201.Fa ioflg
202will be passed to
203.Fn VOP_READ Ns No / Ns Fn VOP_WRITE .
204The remaining arguments specify the uio parameters.
205For further information on these parameters see
206.Xr uiomove 9 .
207.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies"
208Common code for reading the contents of a directory.
209The argument
210.Fa fp
211is the file structure,
212.Fa buf
213is the buffer for placing the struct dirent structures.
214The arguments
215.Fa cookies
216and
217.Fa ncookies
218specify the addresses for the list and number of directory seek
219cookies generated for NFS.
220Both
221.Fa cookies
222and
223.Fa ncookies
224should be
225.Dv NULL
226if they aren't required to be returned by
227.Fn vn_readdir .
228If the operation is successful zero is returned, otherwise an
229appropriate error code is returned.
230.It Fn vn_stat "vp" "sb"
231Common code for a vnode stat operation.
232The vnode is specified by the argument
233.Fa vp ,
234and
235.Fa sb
236is the buffer to return the stat information.
237.Fn vn_stat
238basically calls the vnode operation
239.Xr VOP_GETATTR 9
240and transfers the contents of a vattr structure into a struct stat.
241If the operation is successful zero is returned, otherwise an
242appropriate error code is returned.
243.It Fn vn_writechk "vp"
244Common code to check for write permission on the vnode
245.Fa vp .
246A vnode is read-only if it is in use as a process's text image.
247If the vnode is read-only ETEXTBSY is returned, otherwise zero is
248returned to indicate that the vnode can be written to.
249.El
250.Sh ERRORS
251.Bl -tag -width Er
252.It Bq Er EBUSY
253The LK_NOWAIT flag was set and
254.Fn vn_lock
255would have slept.
256.It Bq Er ENOENT
257The vnode has been reclaimed and is dead.
258This error is only returned if the LK_RETRY flag is not passed to
259.Fn vn_lock .
260.It Bq Er ETXTBSY
261Cannot write to a vnode since is a process's text image.
262.El
263.Sh CODE REFERENCES
264The high-level convenience functions are implemented within the files
265.Pa sys/kern/vfs_vnops.c
266and
267.Pa sys/sys/vnode.h .
268.Sh SEE ALSO
269.Xr file 9 ,
270.Xr intro 9 ,
271.Xr lock 9 ,
272.Xr namei 9 ,
273.Xr vattr 9 ,
274.Xr vfs 9 ,
275.Xr vnode 9 ,
276.Xr vnodeops 9
277