xref: /dragonfly/share/man/man9/VOP_ATTRIB.9 (revision 2d8a3be7) 
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: src/share/man/man9/VOP_ATTRIB.9,v 1.9.2.2 2001/12/17 11:30:18 ru Exp $
30.\" $DragonFly: src/share/man/man9/VOP_ATTRIB.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
31.\"
32.Dd July 24, 1996
33.Os
34.Dt VOP_ATTRIB 9
35.Sh NAME
36.Nm VOP_GETATTR ,
37.Nm VOP_SETATTR
38.Nd get and set attributes on a file or directory
39.Sh SYNOPSIS
40.In sys/param.h
41.In sys/vnode.h
42.Ft int
43.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" "struct proc *p"
44.Ft int
45.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" "struct proc *p"
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
51The arguments are:
52.Bl -tag -width cred
53.It Ar vp
54the vnode of the file
55.It Ar vap
56the attributes of the file
57.It Ar cred
58the user credentials of the calling process
59.It Ar p
60the process
61.El
62.Pp
63Attributes which are not being modified by
64.Xr VOP_SETATTR 9
65should be set to the value
66.Dv VNOVAL .
67.Sh LOCKS
68.Xr VOP_GETATTR 9
69expects the vnode to be locked on entry and will leave the vnode locked on
70return.
71.Pp
72.Xr VOP_SETATTR 9
73expects the vnode to be locked on entry and will leave the vnode locked on
74return.
75.Sh RETURN VALUES
76.Xr VOP_GETATTR 9
77returns information about the file in
78.Fa *vap .
79.Xr VOP_SETATTR 9
80returns zero if the attributes were changed successfully, otherwise an
81appropriate error is returned.
82.Sh PSEUDOCODE
83.Bd -literal
84int
85vop_getattr(struct vnode *vp, struct vattr *vap,
86	    struct ucred *cred, struct proc *p)
87{
88    /*
89     * Fill in the contents of *vap with information from
90     * the filesystem.
91     */
92    ...;
93
94    return 0;
95}
96
97int
98vop_setattr(struct vnode *vp, struct vattr *vap,
99	    struct ucred *cred, struct proc *p)
100{
101    /*
102     * Check for unsettable attributes.
103     */
104    if ((vap->va_type != VNON) || (vap->va_nlink != VNOVAL) ||
105	(vap->va_fsid != VNOVAL) || (vap->va_fileid != VNOVAL) ||
106	(vap->va_blocksize != VNOVAL) || (vap->va_rdev != VNOVAL) ||
107	((int)vap->va_bytes != VNOVAL) || (vap->va_gen != VNOVAL)) {
108	return (EINVAL);
109    }
110
111    if (vap->va_flags != VNOVAL) {
112	/*
113	 * Set the immutable and append flags of the file.
114	 */
115    }
116
117    if (vap->va_uid != (uid_t)VNOVAL || vap->va_gid != (gid_t)VNOVAL) {
118	/*
119	 * Change owner and/or group of the file.
120	 */
121    }
122
123    if (vap->va_size != VNOVAL) {
124	/*
125	 * Truncate the file to the specified size.
126	 */
127    }
128
129    if (vap->va_atime.tv_sec != VNOVAL || vap->va_mtime.tv_sec != VNOVAL) {
130	/*
131	 * Change access and/or modification time of file.
132	 */
133    }
134
135    if (vap->va_mode != (mode_t)VNOVAL) {
136	/*
137	 * Change permissions of file.
138	 */
139    }
140
141    return 0;
142}
143.Ed
144.Sh ERRORS
145.Bl -tag -width Er
146.It Bq Er EPERM
147The file is immutable
148.It Bq Er EACCES
149Permission denied
150.It Bq Er EROFS
151The filesystem is readonly
152.El
153.Sh SEE ALSO
154.Xr vnode 9 ,
155.Xr VOP_ACCESS 9
156.Sh AUTHORS
157This man page was written by
158.An Doug Rabson .
159