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