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 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.It Fa td 87The calling thread. 88.El 89.Pp 90Attributes which are not being modified by 91.Fn VOP_SETATTR 92should be set to the value 93.Dv VNOVAL ; 94.Fn VATTR_NULL 95may be used to clear all the values, and should generally be used to reset 96the contents of 97.Fa *vap 98prior to setting specific values. 99.Sh LOCKS 100Both 101.Fn VOP_GETATTR 102and 103.Fn VOP_STAT 104expect the vnode to be locked on entry and will leave the vnode locked on 105return. 106The lock type can be either shared or exclusive. 107.Pp 108.Fn VOP_SETATTR 109expects the vnode to be locked on entry and will leave the vnode locked on 110return. 111The lock type must be exclusive. 112.Sh RETURN VALUES 113.Fn VOP_GETATTR 114returns 0 if it was able to retrieve the attribute data via 115.Fa *vap , 116otherwise an appropriate error is returned. 117.Fn VOP_SETATTR 118returns zero if the attributes were changed successfully, otherwise an 119appropriate error is returned. 120.Fn VOP_STAT 121returns 0 if it was able to retrieve the attribute data 122.Fa *sb , 123otherwise an appropriate error is returned. 124.Sh ERRORS 125.Bl -tag -width Er 126.It Bq Er EPERM 127The file is immutable. 128.It Bq Er EACCES 129The caller does not have permission to modify the file or directory attributes. 130.It Bq Er EROFS 131The 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 138This manual page was written by 139.An Doug Rabson . 140