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