1.\"	$MirOS: src/lib/libc/sys/chflags.2,v 1.2 2007/05/19 21:47:41 tg Exp $
2.\"	$OpenBSD: chflags.2,v 1.20 2005/09/12 20:06:26 miod Exp $
3.\"	$NetBSD: chflags.2,v 1.6 1995/02/27 12:32:03 cgd Exp $
4.\"
5.\" Copyright (c) 1989, 1993
6.\"	The Regents of the University of California.  All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	@(#)chflags.2	8.1 (Berkeley) 6/9/93
33.\"
34.Dd May 19, 2007
35.Dt CHFLAGS 2
36.Os
37.Sh NAME
38.Nm chflags ,
39.Nm lchflags ,
40.Nm fchflags
41.Nd set flags of a file or link
42.Sh SYNOPSIS
43.Fd #include <sys/stat.h>
44.Fd #include <unistd.h>
45.Ft int
46.Fn chflags "const char *path"  "unsigned int flags"
47.Ft int
48.Fn lchflags "const char *path"  "unsigned int flags"
49.Ft int
50.Fn fchflags "int fd" "unsigned int flags"
51.Sh DESCRIPTION
52The file whose name is given by
53.Fa path
54or referenced by the descriptor
55.Fa fd
56has its flags changed to
57.Fa flags .
58.Fn lchflags
59operates similarly to
60.Fn chflags
61but does not follow symbolic links.
62It allows the filesystem flags of a symbolic link to be set.
63.Pp
64The flags specified are formed by
65.Tn OR Ns 'ing
66the following values:
67.Pp
68.Bl -tag -width "SF_IMMUTABLE" -compact -offset indent
69.It Dv UF_NODUMP
70Do not dump the file.
71.It Dv UF_IMMUTABLE
72The file may not be changed.
73.It Dv UF_APPEND
74The file may only be appended to.
75.\".It ARCHIVED
76.\"File is archived.
77.It Dv SF_IMMUTABLE
78The file may not be changed.
79.It Dv SF_APPEND
80The file may only be appended to.
81.El
82.Pp
83The
84.Dv UF_IMMUTABLE
85and
86.Dv UF_APPEND
87flags may be set or unset by either the owner of a file or the superuser.
88.Pp
89The
90.Dv SF_IMMUTABLE
91and
92.Dv SF_APPEND
93flags may only be set or unset by the superuser.
94They may be set at any time, but normally may only be unset when
95the system is in single-user mode.
96(See
97.Xr init 8
98for details.)
99.Sh RETURN VALUES
100Upon successful completion, a value of 0 is returned.
101Otherwise, \-1 is returned and the global variable
102.Va errno
103is set to indicate the error.
104.Sh ERRORS
105.Fn chflags
106or
107.Fn lchflags
108will fail if:
109.Bl -tag -width Er
110.It Bq Er ENOTDIR
111A component of the path prefix is not a directory.
112.It Bq Er ENAMETOOLONG
113A component of a pathname exceeded
114.Dv {NAME_MAX}
115characters, or an entire path name exceeded
116.Dv {PATH_MAX}
117characters.
118.It Bq Er ENOENT
119The named file does not exist.
120.It Bq Er EACCES
121Search permission is denied for a component of the path prefix.
122.It Bq Er ELOOP
123Too many symbolic links were encountered in translating the pathname.
124.It Bq Er EPERM
125The effective user ID does not match the owner of the file and
126the effective user ID is not the superuser, or the effective user ID
127is not the superuser and at least one of the super-user-only flags
128for the named file would be changed.
129.It Bq Er EOPNOTSUPP
130The named file resides on a file system that does not support file
131flags.
132.It Bq Er EROFS
133The named file resides on a read-only file system.
134.It Bq Er EFAULT
135.Fa path
136points outside the process's allocated address space.
137.It Bq Er EIO
138An
139.Tn I/O
140error occurred while reading from or writing to the file system.
141.It Bq Er EINVAL
142The
143.Fa flags
144value is invalid.
145.It Bq Er EINVAL
146The descriptor references a block or character device and the effective
147user ID is not the superuser.
148.El
149.Pp
150.Fn fchflags
151will fail if:
152.Bl -tag -width Er
153.It Bq Er EBADF
154The descriptor is not valid.
155.It Bq Er EINVAL
156.Fa fd
157refers to a socket, not to a file.
158.It Bq Er EINVAL
159The descriptor references a block or character device and the effective
160user ID is not the superuser.
161.It Bq Er EINVAL
162The
163.Fa flags
164value is invalid.
165.It Bq Er EPERM
166The effective user ID does not match the owner of the file and
167the effective user ID is not the superuser, or the effective user ID
168is not the superuser and at least one of the super-user-only flags
169for the named file would be changed.
170.It Bq Er EOPNOTSUPP
171The named file resides on a file system that does not support file
172flags.
173.It Bq Er EROFS
174The file resides on a read-only file system.
175.It Bq Er EIO
176An
177.Tn I/O
178error occurred while reading from or writing to the file system.
179.El
180.Sh SEE ALSO
181.Xr chflags 1 ,
182.Xr init 8
183.Sh HISTORY
184The
185.Fn chflags
186and
187.Fn fchflags
188functions first appeared in
189.Bx 4.4 .
190The
191.Fn lchflags
192function call appeared in
193.Mx 10 .
194