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