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