share/man/man9/VOP_ACCESS.9

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