share/man/man9/VOP_ATTRIB.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 1996 Doug Rabson
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" This program is free software.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd August 8, 2020
  32 .Dt VOP_ATTRIB 9
  33 .Os
  34 .Sh NAME
  35 .Nm VOP_GETATTR ,
  36 .Nm VOP_SETATTR
  37 .Nd get and set attributes on a file or directory
  38 .Sh SYNOPSIS
  39 .In sys/param.h
  40 .In sys/vnode.h
  41 .Ft int
  42 .Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred"
  43 .Ft int
  44 .Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred"
  45 .Ft int
  46 .Fn VOP_STAT "struct vnode *vp" "struct stat *sb" "struct ucred *active_cred" \
  47 "struct ucred *file_cred" "struct thread *td"
  48 .Sh DESCRIPTION
  49 These entry points manipulate various attributes of a file or directory,
  50 including file permissions, owner, group, size,
  51 access time and modification time.
  52 .Pp
  53 .Fn VOP_STAT
  54 returns data in a format suitable for the
  55 .Xr stat 2
  56 system call and by default is implemented as a wrapper around
  57 .Fn VOP_GETATTR .
  58 Filesystems may want to implement their own variant for performance reasons.
  59 .Pp
  60 For
  61 .Fn VOP_GETATTR
  62 and
  63 .Fn VOP_SETATTR
  64 the arguments are:
  65 .Bl -tag -width cred
  66 .It Fa vp
  67 The vnode of the file.
  68 .It Fa vap
  69 The attributes of the file.
  70 .It Fa cred
  71 The user credentials of the calling thread.
  72 .El
  73 .Pp
  74 For
  75 .Fn VOP_STAT
  76 the arguments are:
  77 .Bl -tag -width active_cred
  78 .It Fa vp
  79 The vnode of the file.
  80 .It Fa sb
  81 The attributes of the file.
  82 .It Fa active_cred
  83 The user credentials of the calling thread.
  84 .It Fa file_cred
  85 The credentials installed on the file description pointing to the vnode or NOCRED.
  86 .It Fa td
  87 The calling thread.
  88 .El
  89 .Pp
  90 Attributes which are not being modified by
  91 .Fn VOP_SETATTR
  92 should be set to the value
  93 .Dv VNOVAL ;
  94 .Fn VATTR_NULL
  95 may be used to clear all the values, and should generally be used to reset
  96 the contents of
  97 .Fa *vap
  98 prior to setting specific values.
  99 .Sh LOCKS
 100 Both
 101 .Fn VOP_GETATTR
 102 and
 103 .Fn VOP_STAT
 104 expect the vnode to be locked on entry and will leave the vnode locked on
 105 return.
 106 The lock type can be either shared or exclusive.
 107 .Pp
 108 .Fn VOP_SETATTR
 109 expects the vnode to be locked on entry and will leave the vnode locked on
 110 return.
 111 The lock type must be exclusive.
 112 .Sh RETURN VALUES
 113 .Fn VOP_GETATTR
 114 returns 0 if it was able to retrieve the attribute data via
 115 .Fa *vap ,
 116 otherwise an appropriate error is returned.
 117 .Fn VOP_SETATTR
 118 returns zero if the attributes were changed successfully, otherwise an
 119 appropriate error is returned.
 120 .Fn VOP_STAT
 121 returns 0 if it was able to retrieve the attribute data
 122 .Fa *sb ,
 123 otherwise an appropriate error is returned.
 124 .Sh ERRORS
 125 .Bl -tag -width Er
 126 .It Bq Er EPERM
 127 The file is immutable.
 128 .It Bq Er EACCES
 129 The caller does not have permission to modify the file or directory attributes.
 130 .It Bq Er EROFS
 131 The file system is read-only.
 132 .El
 133 .Sh SEE ALSO
 134 .Xr VFS 9 ,
 135 .Xr vnode 9 ,
 136 .Xr VOP_ACCESS 9
 137 .Sh AUTHORS
 138 This manual page was written by
 139 .An Doug Rabson .