jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: chmod.2,v 1.29 2025/05/20 02:43:01 kn Exp $
2.\" $NetBSD: chmod.2,v 1.7 1995/02/27 12:32:06 cgd Exp $
3.\"
4.\" Copyright (c) 1980, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
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.\" 3. Neither the name of the University nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93
32.\"
33.Dd $Mdocdate: May 20 2025 $
34.Dt CHMOD 2
35.Os
36.Sh NAME
37.Nm chmod ,
38.Nm fchmodat ,
39.Nm fchmod
40.Nd change mode of file
41.Sh SYNOPSIS
42.In sys/stat.h
43.Ft int
44.Fn chmod "const char *path" "mode_t mode"
45.Ft int
46.Fn fchmod "int fd" "mode_t mode"
47.In sys/stat.h
48.In fcntl.h
49.Ft int
50.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag"
51.Sh DESCRIPTION
52The
53.Fn chmod
54function sets the file permission bits of the file specified by the pathname
55.Fa path
56to
57.Fa mode .
58.Fn chmod
59verifies that the process owner (user) either owns the specified file
60or is the superuser.
61.Pp
62The
63.Fa mode
64argument is the bitwise OR of zero or more of the permission bit masks
65from the following list:
66.Bd -literal -offset indent
67#define S_IRWXU 0000700 /* RWX mask for owner */
68#define S_IRUSR 0000400 /* R for owner */
69#define S_IWUSR 0000200 /* W for owner */
70#define S_IXUSR 0000100 /* X for owner */
71
72#define S_IRWXG 0000070 /* RWX mask for group */
73#define S_IRGRP 0000040 /* R for group */
74#define S_IWGRP 0000020 /* W for group */
75#define S_IXGRP 0000010 /* X for group */
76
77#define S_IRWXO 0000007 /* RWX mask for other */
78#define S_IROTH 0000004 /* R for other */
79#define S_IWOTH 0000002 /* W for other */
80#define S_IXOTH 0000001 /* X for other */
81
82#define S_ISUID 0004000 /* set user id on execution */
83#define S_ISGID 0002000 /* set group id on execution */
84#define S_ISVTX 0001000 /* save swapped text even after use */
85.Ed
86.Pp
87Mode
88.Dv ISVTX
89(the
90.Em sticky bit )
91on a file has no effect, although the superuser can still set it.
92If it is set on a directory, an unprivileged user may not delete or rename
93files of other users in that directory.
94The sticky bit may be set by any user on a directory which the user owns
95or has appropriate permissions.
96For more details of the properties of the sticky bit, see
97.Xr sticky 8 .
98.Pp
99Writing or changing the owner of a file turns off the set-user-ID and
100set-group-ID bits unless the user is the superuser.
101This makes the system somewhat more secure by protecting
102set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID)
103if they are modified, at the expense of a degree of compatibility.
104.Pp
105The
106.Fn fchmodat
107function is equivalent to
108.Fn chmod
109except in the case where
110.Fa path
111specifies a relative path.
112In this case the file to be changed is determined relative to the directory
113associated with the file descriptor
114.Fa fd
115instead of the current working directory.
116.Pp
117If
118.Fn fchmodat
119is passed the special value
120.Dv AT_FDCWD
121(defined in
122.In fcntl.h )
123in the
124.Fa fd
125parameter, the current working directory is used.
126If
127.Fa flag
128is also zero, the behavior is identical to a call to
129.Fn chmod .
130.Pp
131The
132.Fa flag
133argument is the bitwise OR of zero or more of the following values:
134.Pp
135.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact
136.It Dv AT_SYMLINK_NOFOLLOW
137If
138.Fa path
139names a symbolic link, then the mode of the symbolic link is changed.
140.El
141.Pp
142The
143.Fn fchmod
144function is equivalent to
145.Fn chmod
146except that the file whose permissions are changed is specified
147by the file descriptor
148.Fa fd .
149.Sh RETURN VALUES
150.Rv -std
151.Sh ERRORS
152The
153.Fn chmod
154and
155.Fn fchmodat
156functions will fail and the file mode will be unchanged if:
157.Bl -tag -width Er
158.It Bq Er ENOTDIR
159A component of the path prefix is not a directory.
160.It Bq Er ENAMETOOLONG
161A component of a pathname exceeded
162.Dv NAME_MAX
163characters, or an entire pathname (including the terminating NUL)
164exceeded
165.Dv PATH_MAX
166bytes.
167.It Bq Er ENOENT
168The named file does not exist.
169.It Bq Er EACCES
170Search permission is denied for a component of the path prefix.
171.It Bq Er EINVAL
172.Fa mode
173contains bits other than the file type and those described above.
174.It Bq Er ELOOP
175Too many symbolic links were encountered in translating the pathname.
176.It Bq Er EPERM
177The effective user ID does not match the owner of the file and
178the effective user ID is not the superuser.
179.It Bq Er EROFS
180The named file resides on a read-only file system.
181.It Bq Er EFAULT
182.Fa path
183points outside the process's allocated address space.
184.It Bq Er EIO
185An I/O error occurred while reading from or writing to the file system.
186.It Bq Er EFTYPE
187An unprivileged user attempted to set a file's mode to
188.Dv ISVTX .
189.El
190.Pp
191Additionally, the
192.Fn fchmodat
193function will fail if:
194.Bl -tag -width Er
195.It Bq Er EINVAL
196The value of the
197.Fa flag
198argument was neither zero nor
199.Dv AT_SYMLINK_NOFOLLOW .
200.It Bq Er EBADF
201The
202.Fa path
203argument specifies a relative path and the
204.Fa fd
205argument is neither
206.Dv AT_FDCWD
207nor a valid file descriptor.
208.It Bq Er ENOTDIR
209The
210.Fa path
211argument specifies a relative path and the
212.Fa fd
213argument is a valid file descriptor but it does not reference a directory.
214.It Bq Er EOPNOTSUPP
215The
216.Fa flag
217argument specifies
218.Dv AT_SYMLINK_NOFOLLOW
219on a symbolic link and the file system does not support that operation.
220.It Bq Er EACCES
221The
222.Fa path
223argument specifies a relative path but search permission is denied
224for the directory which the
225.Fa fd
226file descriptor references.
227.El
228.Pp
229.Fn fchmod
230will fail and the file mode will be unchanged if:
231.Bl -tag -width Er
232.It Bq Er EBADF
233The descriptor is not valid.
234.It Bq Er EINVAL
235.Fa fd
236refers to a socket, not to a file.
237.It Bq Er EINVAL
238.Fa mode
239contains bits other than the file type and those described above.
240.It Bq Er EPERM
241The effective user ID does not match the owner of the file and
242the effective user ID is not the superuser.
243.It Bq Er EROFS
244The file resides on a read-only file system.
245.It Bq Er EIO
246An I/O error occurred while reading from or writing to the file system.
247.El
248.Sh SEE ALSO
249.Xr chmod 1 ,
250.Xr chown 2 ,
251.Xr open 2 ,
252.Xr stat 2 ,
253.Xr sticky 8
254.Sh STANDARDS
255The
256.Fn chmod ,
257.Fn fchmod ,
258and
259.Fn fchmodat
260functions are expected to conform to
261.St -p1003.1-2008 .
262.Sh HISTORY
263The
264.Fn chmod
265system call first appeared in
266.At v1 ;
267.Fn fchmod
268in
269.Bx 4.1c ;
270and
271.Fn fchmodat
272has been available since
273.Ox 5.0 .