share/man/man9/VOP_ACCESS.9

   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
  45 This entry point checks the access permissions of the file against the
  46 given credentials.
  47 .Pp
  48 Its arguments are:
  49 .Bl -tag -width mode
  50 .It Ar vp
  51 the vnode of the file to check
  52 .It Ar mode
  53 the type of access required
  54 .It Ar cred
  55 the user credentials to check
  56 .It Ar p
  57 the process which is checking
  58 .El
  59 .Pp
  60 The
  61 .Fa mode
  62 is a mask which can contain
  63 .Dv VREAD ,
  64 .Dv VWRITE
  65 or
  66 .Dv VEXEC .
  67 .Sh LOCKS
  68 The vnode will be locked on entry and should remain locked on return.
  69 .Sh RETURN VALUES
  70 If the file is accessible in the specified way, then zero is returned,
  71 otherwise an appropriate error code is returned.
  72 .Sh PSEUDOCODE
  73 .Bd -literal
  74 int
  75 vop_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
 142 An attempt was made to change an immutable file
 143 .It Bq Er EACCES
 144 Permission denied
 145 .El
 146 .Sh SEE ALSO
 147 .Xr vnode 9
 148 .Sh AUTHORS
 149 This man page was written by
 150 .An Doug Rabson .