Add the lchflags() syscall.
[dragonfly.git] / lib / libc / sys / chflags.2
CommitLineData
984263bc
MD
1.\" Copyright (c) 1989, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. 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.3 (Berkeley) 5/2/95
33.\" $FreeBSD: src/lib/libc/sys/chflags.2,v 1.11.2.7 2001/12/14 18:34:00 ru Exp $
91fdc001 34.\" $DragonFly: src/lib/libc/sys/chflags.2,v 1.5 2008/11/11 00:55:49 pavalos Exp $
984263bc 35.\"
91fdc001 36.Dd November 10, 2008
984263bc
MD
37.Dt CHFLAGS 2
38.Os
39.Sh NAME
40.Nm chflags ,
91fdc001 41.Nm lchflags ,
984263bc
MD
42.Nm fchflags
43.Nd set file flags
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In sys/stat.h
48.In unistd.h
49.Ft int
50.Fn chflags "const char *path" "u_long flags"
51.Ft int
91fdc001
PA
52.Fn lchflags "const char *path" "u_long flags"
53.Ft int
984263bc
MD
54.Fn fchflags "int fd" "u_long flags"
55.Sh DESCRIPTION
56The file whose name
57is given by
58.Fa path
59or referenced by the descriptor
60.Fa fd
61has its flags changed to
62.Fa flags .
63.Pp
91fdc001
PA
64The
65.Fn lchflags
66system call is like
67.Fn chflags
68except in the case where the named file is a symbolic link,
69in which case
70.Fn lchflags
71will change the flags of the link itself,
72rather than the file it points to.
73.Pp
984263bc
MD
74The flags specified are formed by
75.Em or Ns 'ing
76the following values
77.Pp
78.Bl -tag -width "SF_IMMUTABLE" -compact -offset indent
79.It UF_NODUMP
80Do not dump the file.
81.It UF_IMMUTABLE
82The file may not be changed.
83.It UF_APPEND
84The file may only be appended to.
85.It UF_NOUNLINK
86The file may not be renamed or deleted.
448f0be3
TN
87.It UF_NOHISTORY
88Do not retain history for file.
984263bc
MD
89.It UF_OPAQUE
90The directory is opaque when viewed through a union stack.
91.It SF_ARCHIVED
92The file may be archived.
93.It SF_IMMUTABLE
94The file may not be changed.
95.It SF_APPEND
96The file may only be appended to.
97.It SF_NOUNLINK
98The file may not be renamed or deleted.
448f0be3
TN
99.It SF_NOHISTORY
100Do not retain history for file.
984263bc
MD
101.El
102.Pp
103The
104.Dq UF_IMMUTABLE ,
105.Dq UF_APPEND ,
106.Dq UF_NOUNLINK ,
03b8c8c1 107.Dq UF_NOHISTORY ,
984263bc
MD
108.Dq UF_NODUMP ,
109and
110.Dq UF_OPAQUE
111flags may be set or unset by either the owner of a file or the super-user.
112.Pp
113The
114.Dq SF_IMMUTABLE ,
115.Dq SF_APPEND ,
116.Dq SF_NOUNLINK ,
448f0be3 117.Dq SF_NOHISTORY ,
984263bc
MD
118and
119.Dq SF_ARCHIVED
120flags may only be set or unset by the super-user.
121Attempts by the non-super-user to set the super-user only flags
122are silently ignored.
123These flags may be set at any time, but normally may only be unset when
124the system is in single-user mode.
125(See
126.Xr init 8
127for details.)
128.Sh RETURN VALUES
129.Rv -std
130.Sh ERRORS
131.Fn Chflags
132will fail if:
133.Bl -tag -width Er
134.It Bq Er ENOTDIR
135A component of the path prefix is not a directory.
136.It Bq Er ENAMETOOLONG
137A component of a pathname exceeded 255 characters,
138or an entire path name exceeded 1023 characters.
139.It Bq Er ENOENT
140The named file does not exist.
141.It Bq Er EACCES
142Search permission is denied for a component of the path prefix.
143.It Bq Er ELOOP
144Too many symbolic links were encountered in translating the pathname.
145.It Bq Er EPERM
146The effective user ID does not match the owner of the file and
147the effective user ID is not the super-user.
148.It Bq Er EROFS
149The named file resides on a read-only file system.
150.It Bq Er EFAULT
151.Fa Path
152points outside the process's allocated address space.
153.It Bq Er EIO
154An
155.Tn I/O
156error occurred while reading from or writing to the file system.
157.It Bq Er EOPNOTSUPP
158The underlying file system does not support file flags.
159.El
160.Pp
161.Fn Fchflags
162will fail if:
163.Bl -tag -width Er
164.It Bq Er EBADF
165The descriptor is not valid.
166.It Bq Er EINVAL
167.Fa fd
168refers to a socket, not to a file.
169.It Bq Er EPERM
170The effective user ID does not match the owner of the file and
171the effective user ID is not the super-user.
172.It Bq Er EROFS
173The file resides on a read-only file system.
174.It Bq Er EIO
175An
176.Tn I/O
177error occurred while reading from or writing to the file system.
178.It Bq Er EOPNOTSUPP
179The underlying file system does not support file flags.
180.El
181.Sh SEE ALSO
182.Xr chflags 1 ,
183.Xr fflagstostr 3 ,
184.Xr strtofflags 3 ,
185.Xr init 8 ,
186.Xr mount_union 8
187.Sh HISTORY
188The
189.Nm chflags
190and
191.Nm fchflags
192functions first appeared in
193.Bx 4.4 .