xref: /dragonfly/share/man/man9/VOP_ATTRIB.9 (revision d8082429) 
1.\" Copyright (c) 1996 Doug Rabson
2.\"
3.\" All rights reserved.
4.\"
5.\" This program is free software.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" $FreeBSD: src/share/man/man9/VOP_ATTRIB.9,v 1.9.2.2 2001/12/17 11:30:18 ru Exp $
28.\"
29.Dd July 24, 1996
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" "struct proc *p"
41.Ft int
42.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" "struct proc *p"
43.Sh DESCRIPTION
44These entry points manipulate various attributes of a file or directory,
45including file permissions, owner, group, size,
46access time and modification time.
47.Pp
48The arguments are:
49.Bl -tag -width cred
50.It Ar vp
51the vnode of the file
52.It Ar vap
53the attributes of the file
54.It Ar cred
55the user credentials of the calling process
56.It Ar p
57the process
58.El
59.Pp
60Attributes which are not being modified by
61.Xr VOP_SETATTR 9
62should be set to the value
63.Dv VNOVAL .
64.Sh LOCKS
65.Xr VOP_GETATTR 9
66expects the vnode to be locked on entry and will leave the vnode locked on
67return.
68.Pp
69.Xr VOP_SETATTR 9
70expects the vnode to be locked on entry and will leave the vnode locked on
71return.
72.Sh RETURN VALUES
73.Xr VOP_GETATTR 9
74returns information about the file in
75.Fa *vap .
76.Xr VOP_SETATTR 9
77returns zero if the attributes were changed successfully, otherwise an
78appropriate error is returned.
79.Sh PSEUDOCODE
80.Bd -literal
81int
82vop_getattr(struct vnode *vp, struct vattr *vap,
83	    struct ucred *cred, struct proc *p)
84{
85    /*
86     * Fill in the contents of *vap with information from
87     * the filesystem.
88     */
89    ...;
90
91    return 0;
92}
93
94int
95vop_setattr(struct vnode *vp, struct vattr *vap,
96	    struct ucred *cred, struct proc *p)
97{
98    /*
99     * Check for unsettable attributes.
100     */
101    if ((vap->va_type != VNON) || (vap->va_nlink != VNOVAL) ||
102	(vap->va_fsid != VNOVAL) || (vap->va_fileid != VNOVAL) ||
103	(vap->va_blocksize != VNOVAL) || (vap->va_rdev != VNOVAL) ||
104	((int)vap->va_bytes != VNOVAL) || (vap->va_gen != VNOVAL)) {
105	return (EINVAL);
106    }
107
108    if (vap->va_flags != VNOVAL) {
109	/*
110	 * Set the immutable and append flags of the file.
111	 */
112    }
113
114    if (vap->va_uid != (uid_t)VNOVAL || vap->va_gid != (gid_t)VNOVAL) {
115	/*
116	 * Change owner and/or group of the file.
117	 */
118    }
119
120    if (vap->va_size != VNOVAL) {
121	/*
122	 * Truncate the file to the specified size.
123	 */
124    }
125
126    if (vap->va_atime.tv_sec != VNOVAL || vap->va_mtime.tv_sec != VNOVAL) {
127	/*
128	 * Change access and/or modification time of file.
129	 */
130    }
131
132    if (vap->va_mode != (mode_t)VNOVAL) {
133	/*
134	 * Change permissions of file.
135	 */
136    }
137
138    return 0;
139}
140.Ed
141.Sh ERRORS
142.Bl -tag -width Er
143.It Bq Er EPERM
144The file is immutable
145.It Bq Er EACCES
146Permission denied
147.It Bq Er EROFS
148The filesystem is readonly
149.El
150.Sh SEE ALSO
151.Xr vnode 9 ,
152.Xr VOP_ACCESS 9
153.Sh AUTHORS
154This man page was written by
155.An Doug Rabson .
156