share/man/man9/VOP_ATTRIB.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_ATTRIB.9,v 1.9.2.2 2001/12/17 11:30:18 ru Exp $
  28 .\" $DragonFly: src/share/man/man9/VOP_ATTRIB.9,v 1.3 2004/06/01 11:36:53 hmp Exp $
  29 .\"
  30 .Dd July 24, 1996
  31 .Os
  32 .Dt VOP_ATTRIB 9
  33 .Sh NAME
  34 .Nm VOP_GETATTR ,
  35 .Nm VOP_SETATTR
  36 .Nd get and set attributes on a file or directory
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/vnode.h
  40 .Ft int
  41 .Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" "struct proc *p"
  42 .Ft int
  43 .Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" "struct proc *p"
  44 .Sh DESCRIPTION
  45 These entry points manipulate various attributes of a file or directory,
  46 including file permissions, owner, group, size,
  47 access time and modification time.
  48 .Pp
  49 The arguments are:
  50 .Bl -tag -width cred
  51 .It Ar vp
  52 the vnode of the file
  53 .It Ar vap
  54 the attributes of the file
  55 .It Ar cred
  56 the user credentials of the calling process
  57 .It Ar p
  58 the process
  59 .El
  60 .Pp
  61 Attributes which are not being modified by
  62 .Xr VOP_SETATTR 9
  63 should be set to the value
  64 .Dv VNOVAL .
  65 .Sh LOCKS
  66 .Xr VOP_GETATTR 9
  67 expects the vnode to be locked on entry and will leave the vnode locked on
  68 return.
  69 .Pp
  70 .Xr VOP_SETATTR 9
  71 expects the vnode to be locked on entry and will leave the vnode locked on
  72 return.
  73 .Sh RETURN VALUES
  74 .Xr VOP_GETATTR 9
  75 returns information about the file in
  76 .Fa *vap .
  77 .Xr VOP_SETATTR 9
  78 returns zero if the attributes were changed successfully, otherwise an
  79 appropriate error is returned.
  80 .Sh PSEUDOCODE
  81 .Bd -literal
  82 int
  83 vop_getattr(struct vnode *vp, struct vattr *vap,
  84             struct ucred *cred, struct proc *p)
  85 {
  86     /*
  87      * Fill in the contents of *vap with information from
  88      * the filesystem.
  89      */
  90     ...;
  91
  92     return 0;
  93 }
  94
  95 int
  96 vop_setattr(struct vnode *vp, struct vattr *vap,
  97             struct ucred *cred, struct proc *p)
  98 {
  99     /*
 100      * Check for unsettable attributes.
 101      */
 102     if ((vap->va_type != VNON) || (vap->va_nlink != VNOVAL) ||
 103         (vap->va_fsid != VNOVAL) || (vap->va_fileid != VNOVAL) ||
 104         (vap->va_blocksize != VNOVAL) || (vap->va_rdev != VNOVAL) ||
 105         ((int)vap->va_bytes != VNOVAL) || (vap->va_gen != VNOVAL)) {
 106         return (EINVAL);
 107     }
 108
 109     if (vap->va_flags != VNOVAL) {
 110         /*
 111          * Set the immutable and append flags of the file.
 112          */
 113     }
 114
 115     if (vap->va_uid != (uid_t)VNOVAL || vap->va_gid != (gid_t)VNOVAL) {
 116         /*
 117          * Change owner and/or group of the file.
 118          */
 119     }
 120
 121     if (vap->va_size != VNOVAL) {
 122         /*
 123          * Truncate the file to the specified size.
 124          */
 125     }
 126
 127     if (vap->va_atime.tv_sec != VNOVAL || vap->va_mtime.tv_sec != VNOVAL) {
 128         /*
 129          * Change access and/or modification time of file.
 130          */
 131     }
 132
 133     if (vap->va_mode != (mode_t)VNOVAL) {
 134         /*
 135          * Change permissions of file.
 136          */
 137     }
 138
 139     return 0;
 140 }
 141 .Ed
 142 .Sh ERRORS
 143 .Bl -tag -width Er
 144 .It Bq Er EPERM
 145 The file is immutable
 146 .It Bq Er EACCES
 147 Permission denied
 148 .It Bq Er EROFS
 149 The filesystem is readonly
 150 .El
 151 .Sh SEE ALSO
 152 .Xr vnode 9 ,
 153 .Xr VOP_ACCESS 9
 154 .Sh AUTHORS
 155 This man page was written by
 156 .An Doug Rabson .