xref: /freebsd/share/man/man9/VOP_ACCESS.9 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\" -*- nroff -*-
2.\" -*- nroff -*-
3.\"
4.\" Copyright (c) 1996 Doug Rabson
5.\"
6.\" All rights reserved.
7.\"
8.\" This program is free software.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd July 24, 1996
33.Os
34.Dt VOP_ACCESS 9
35.Sh NAME
36.Nm VOP_ACCESS
37.Nd "check access permissions of a file or Unix domain socket"
38.Sh SYNOPSIS
39.In sys/param.h
40.In sys/vnode.h
41.Ft int
42.Fn VOP_ACCESS "struct vnode *vp" "int mode" "struct ucred *cred" "struct thread *td"
43.Sh DESCRIPTION
44This entry point checks the access permissions of the file against the
45given credentials.
46.Pp
47Its arguments are:
48.Bl -tag -width mode
49.It Fa vp
50The vnode of the file to check.
51.It Fa mode
52The type of access required.
53.It Fa cred
54The user credentials to check.
55.It Fa td
56The thread which is checking.
57.El
58.Pp
59The
60.Fa mode
61is a mask which can contain
62.Dv VREAD ,
63.Dv VWRITE
64or
65.Dv VEXEC .
66.Sh LOCKS
67The vnode will be locked on entry and should remain locked on return.
68.Sh RETURN VALUES
69If the file is accessible in the specified way, then zero is returned,
70otherwise an appropriate error code is returned.
71.Sh PSEUDOCODE
72.Bd -literal
73int
74vop_access(struct vnode *vp, int mode, struct ucred *cred, struct thread *td)
75{
76    int error;
77
78    /*
79     * Disallow write attempts on read-only file systems;
80     * unless the file is a socket, fifo, or a block or
81     * character device resident on the filesystem.
82     */
83    if (mode & VWRITE) {
84	switch (vp->v_type) {
85	case VDIR:
86	case VLNK:
87	case VREG:
88	    if (vp->v_mount->mnt_flag & MNT_RDONLY)
89		return EROFS;
90
91	    break;
92	}
93    }
94
95    /* If immutable bit set, nobody gets to write it. */
96    if ((mode & VWRITE) && vp has immutable bit set)
97	return EPERM;
98
99    /* Otherwise, user id 0 always gets access. */
100    if (cred->cr_uid == 0)
101	return 0;
102
103    mask = 0;
104
105    /* Otherwise, check the owner. */
106    if (cred->cr_uid == owner of vp) {
107	if (mode & VEXEC)
108	    mask |= S_IXUSR;
109	if (mode & VREAD)
110	    mask |= S_IRUSR;
111	if (mode & VWRITE)
112	    mask |= S_IWUSR;
113	return (((mode of vp) & mask) == mask ? 0 : EACCES);
114    }
115
116    /* Otherwise, check the groups. */
117    for (i = 0, gp = cred->cr_groups; i < cred->cr_ngroups; i++, gp++)
118	if (group of vp == *gp) {
119	    if (mode & VEXEC)
120		mask |= S_IXGRP;
121	    if (mode & VREAD)
122		mask |= S_IRGRP;
123	    if (mode & VWRITE)
124		mask |= S_IWGRP;
125	    return (((mode of vp) & mask) == mask ? 0 : EACCES);
126	}
127
128    /* Otherwise, check everyone else. */
129    if (mode & VEXEC)
130	mask |= S_IXOTH;
131    if (mode & VREAD)
132	mask |= S_IROTH;
133    if (mode & VWRITE)
134	mask |= S_IWOTH;
135    return (((mode of vp) & mask) == mask ? 0 : EACCES);
136}
137.Ed
138.Sh ERRORS
139.Bl -tag -width Er
140.It Bq Er EPERM
141An attempt was made to change an immutable file.
142.It Bq Er EACCES
143The permission bits the file mode or the ACL do not permit the
144requested access.
145.El
146.Sh SEE ALSO
147.Xr vaccess 9 ,
148.Xr vaccess_acl_posix1e 9 ,
149.Xr vnode 9
150.Sh AUTHORS
151This manual page was written by
152.An Doug Rabson .
153