xref: /dragonfly/share/man/man9/VOP_ACCESS.9 (revision 333227be) 
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_ACCESS.9,v 1.7.2.4 2001/12/17 11:30:18 ru Exp $
28.\" $DragonFly: src/share/man/man9/VOP_ACCESS.9,v 1.3 2004/06/01 11:36:53 hmp Exp $
29.\"
30.Dd July 24, 1996
31.Os
32.Dt VOP_ACCESS 9
33.Sh NAME
34.Nm VOP_ACCESS
35.Nd "check access permissions of a file or Unix domain socket"
36.Sh SYNOPSIS
37.In sys/param.h
38.In sys/vnode.h
39.Ft int
40.Fn VOP_ACCESS "struct vnode *vp" "int mode" "struct ucred *cred" "struct proc *p"
41.Sh DESCRIPTION
42This entry point checks the access permissions of the file against the
43given credentials.
44.Pp
45Its arguments are:
46.Bl -tag -width mode
47.It Ar vp
48the vnode of the file to check
49.It Ar mode
50the type of access required
51.It Ar cred
52the user credentials to check
53.It Ar p
54the process which is checking
55.El
56.Pp
57The
58.Fa mode
59is a mask which can contain
60.Dv VREAD ,
61.Dv VWRITE
62or
63.Dv VEXEC .
64.Sh LOCKS
65The vnode will be locked on entry and should remain locked on return.
66.Sh RETURN VALUES
67If the file is accessible in the specified way, then zero is returned,
68otherwise an appropriate error code is returned.
69.Sh PSEUDOCODE
70.Bd -literal
71int
72vop_access(struct vnode *vp, int mode, struct ucred *cred, struct proc *p)
73{
74    int error;
75
76    /*
77     * Disallow write attempts on read-only file systems;
78     * unless the file is a socket, fifo, or a block or
79     * character device resident on the file system.
80     */
81    if (mode & VWRITE) {
82	switch (vp->v_type) {
83	case VDIR:
84	case VLNK:
85	case VREG:
86	    if (vp->v_mount->mnt_flag & MNT_RDONLY)
87		return EROFS;
88
89	    break;
90	}
91    }
92
93    /* If immutable bit set, nobody gets to write it. */
94    if ((mode & VWRITE) && vp has immutable bit set)
95	return EPERM;
96
97    /* Otherwise, user id 0 always gets access. */
98    if (cred->cr_uid == 0)
99	return 0;
100
101    mask = 0;
102
103    /* Otherwise, check the owner. */
104    if (cred->cr_uid == owner of vp) {
105	if (mode & VEXEC)
106	    mask |= S_IXUSR;
107	if (mode & VREAD)
108	    mask |= S_IRUSR;
109	if (mode & VWRITE)
110	    mask |= S_IWUSR;
111	return (((mode of vp) & mask) == mask ? 0 : EACCES);
112    }
113
114    /* Otherwise, check the groups. */
115    for (i = 0, gp = cred->cr_groups; i < cred->cr_ngroups; i++, gp++)
116	if (group of vp == *gp) {
117	    if (mode & VEXEC)
118		mask |= S_IXGRP;
119	    if (mode & VREAD)
120		mask |= S_IRGRP;
121	    if (mode & VWRITE)
122		mask |= S_IWGRP;
123	    return (((mode of vp) & mask) == mask ? 0 : EACCES);
124	}
125
126    /* Otherwise, check everyone else. */
127    if (mode & VEXEC)
128	mask |= S_IXOTH;
129    if (mode & VREAD)
130	mask |= S_IROTH;
131    if (mode & VWRITE)
132	mask |= S_IWOTH;
133    return (((mode of vp) & mask) == mask ? 0 : EACCES);
134}
135.Ed
136.Sh ERRORS
137.Bl -tag -width Er
138.It Bq Er EPERM
139An attempt was made to change an immutable file
140.It Bq Er EACCES
141Permission denied
142.El
143.Sh SEE ALSO
144.Xr vnode 9
145.Sh AUTHORS
146This man page was written by
147.An Doug Rabson .
148