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.Dd October 2, 2021 30.Dt VOP_ATTRIB 9 31.Os 32.Sh NAME 33.Nm VOP_GETATTR , 34.Nm VOP_SETATTR 35.Nd get and set attributes on a file or directory 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/vnode.h 39.Ft int 40.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" 41.Ft int 42.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" 43.Ft int 44.Fn VOP_STAT "struct vnode *vp" "struct stat *sb" "struct ucred *active_cred" \ 45"struct ucred *file_cred" 46.Sh DESCRIPTION 47These entry points manipulate various attributes of a file or directory, 48including file permissions, owner, group, size, 49access time and modification time. 50.Pp 51.Fn VOP_STAT 52returns data in a format suitable for the 53.Xr stat 2 54system call and by default is implemented as a wrapper around 55.Fn VOP_GETATTR . 56Filesystems may want to implement their own variant for performance reasons. 57.Pp 58For 59.Fn VOP_GETATTR 60and 61.Fn VOP_SETATTR 62the arguments are: 63.Bl -tag -width cred 64.It Fa vp 65The vnode of the file. 66.It Fa vap 67The attributes of the file. 68.It Fa cred 69The user credentials of the calling thread. 70.El 71.Pp 72For 73.Fn VOP_STAT 74the arguments are: 75.Bl -tag -width active_cred 76.It Fa vp 77The vnode of the file. 78.It Fa sb 79The attributes of the file. 80.It Fa active_cred 81The user credentials of the calling thread. 82.It Fa file_cred 83The credentials installed on the file description pointing to the vnode or NOCRED. 84.El 85.Pp 86Attributes which are not being modified by 87.Fn VOP_SETATTR 88should be set to the value 89.Dv VNOVAL ; 90.Fn VATTR_NULL 91may be used to clear all the values, and should generally be used to reset 92the contents of 93.Fa *vap 94prior to setting specific values. 95.Sh LOCKS 96Both 97.Fn VOP_GETATTR 98and 99.Fn VOP_STAT 100expect the vnode to be locked on entry and will leave the vnode locked on 101return. 102The lock type can be either shared or exclusive. 103.Pp 104.Fn VOP_SETATTR 105expects the vnode to be locked on entry and will leave the vnode locked on 106return. 107The lock type must be exclusive. 108.Sh RETURN VALUES 109.Fn VOP_GETATTR 110returns 0 if it was able to retrieve the attribute data via 111.Fa *vap , 112otherwise an appropriate error is returned. 113.Fn VOP_SETATTR 114returns zero if the attributes were changed successfully, otherwise an 115appropriate error is returned. 116.Fn VOP_STAT 117returns 0 if it was able to retrieve the attribute data 118.Fa *sb , 119otherwise an appropriate error is returned. 120.Sh ERRORS 121.Bl -tag -width Er 122.It Bq Er EPERM 123The file is immutable. 124.It Bq Er EACCES 125The caller does not have permission to modify the file or directory attributes. 126.It Bq Er EROFS 127The file system is read-only. 128.El 129.Sh SEE ALSO 130.Xr VFS 9 , 131.Xr vnode 9 , 132.Xr VOP_ACCESS 9 133.Sh AUTHORS 134This manual page was written by 135.An Doug Rabson . 136