Fri Nov 19 23:51:17 2021 UTC ()
Mention that fchmod conforms to XPG 4.2. Bump date.


(wiz)
diff -r1.48 -r1.49 src/lib/libc/sys/chmod.2
cvs diff -r1.48 -r1.49 src/lib/libc/sys/chmod.2 (switch to unified diff)

--- src/lib/libc/sys/chmod.2 2019/09/01 19:13:57 1.48
+++ src/lib/libc/sys/chmod.2 2021/11/19 23:51:16 1.49
@@ -1,302 +1,307 @@ @@ -1,302 +1,307 @@
1.\" $NetBSD: chmod.2,v 1.48 2019/09/01 19:13:57 sevan Exp $ 1.\" $NetBSD: chmod.2,v 1.49 2021/11/19 23:51:16 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 1980, 1991, 1993 3.\" Copyright (c) 1980, 1991, 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
15.\" may be used to endorse or promote products derived from this software 15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission. 16.\" without specific prior written permission.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE. 28.\" SUCH DAMAGE.
29.\" 29.\"
30.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 30.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93
31.\" 31.\"
32.Dd September 1, 2019 32.Dd November 20, 2021
33.Dt CHMOD 2 33.Dt CHMOD 2
34.Os 34.Os
35.Sh NAME 35.Sh NAME
36.Nm chmod , 36.Nm chmod ,
37.Nm lchmod , 37.Nm lchmod ,
38.Nm fchmod , 38.Nm fchmod ,
39.Nm fchmodat 39.Nm fchmodat
40.Nd change mode of file 40.Nd change mode of file
41.Sh LIBRARY 41.Sh LIBRARY
42.Lb libc 42.Lb libc
43.Sh SYNOPSIS 43.Sh SYNOPSIS
44.In sys/stat.h 44.In sys/stat.h
45.Ft int 45.Ft int
46.Fn chmod "const char *path" "mode_t mode" 46.Fn chmod "const char *path" "mode_t mode"
47.Ft int 47.Ft int
48.Fn lchmod "const char *path" "mode_t mode" 48.Fn lchmod "const char *path" "mode_t mode"
49.Ft int 49.Ft int
50.Fn fchmod "int fd" "mode_t mode" 50.Fn fchmod "int fd" "mode_t mode"
51.In sys/stat.h 51.In sys/stat.h
52.In fcntl.h 52.In fcntl.h
53.Ft int 53.Ft int
54.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" 54.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag"
55.Sh DESCRIPTION 55.Sh DESCRIPTION
56The function 56The function
57.Fn chmod 57.Fn chmod
58sets the file permission bits 58sets the file permission bits
59of the file 59of the file
60specified by the pathname 60specified by the pathname
61.Fa path 61.Fa path
62to 62to
63.Fa mode . 63.Fa mode .
64.Fn fchmod 64.Fn fchmod
65sets the permission bits of the specified 65sets the permission bits of the specified
66file descriptor 66file descriptor
67.Fa fd . 67.Fa fd .
68.Fn lchmod 68.Fn lchmod
69is like 69is like
70.Fn chmod 70.Fn chmod
71except in the case where the named file is a symbolic link, 71except in the case where the named file is a symbolic link,
72in which case 72in which case
73.Fn lchmod 73.Fn lchmod
74sets the permission bits of the link, 74sets the permission bits of the link,
75while 75while
76.Fn chmod 76.Fn chmod
77sets the bits of the file the link references. 77sets the bits of the file the link references.
78.Pp 78.Pp
79.Fn fchmodat 79.Fn fchmodat
80works the same way as 80works the same way as
81.Fn chmod 81.Fn chmod
82(or 82(or
83.Fn lchmod 83.Fn lchmod
84if 84if
85.Dv AT_SYMLINK_NOFOLLOW 85.Dv AT_SYMLINK_NOFOLLOW
86is set in 86is set in
87.Fa flag ) 87.Fa flag )
88except if 88except if
89.Fa path 89.Fa path
90is relative. 90is relative.
91In that case, it is looked up from a directory whose file 91In that case, it is looked up from a directory whose file
92descriptor was passed as 92descriptor was passed as
93.Fa fd . 93.Fa fd .
94Search permission is required on this directory. 94Search permission is required on this directory.
95.\" (These alternatives await a decision about the semantics of O_SEARCH) 95.\" (These alternatives await a decision about the semantics of O_SEARCH)
96.\" Search permission is required on this directory 96.\" Search permission is required on this directory
97.\" except if 97.\" except if
98.\" .Fa fd 98.\" .Fa fd
99.\" was opened with the 99.\" was opened with the
100.\" .Dv O_SEARCH 100.\" .Dv O_SEARCH
101.\" flag. 101.\" flag.
102.\" - or - 102.\" - or -
103.\" This file descriptor must have been opened with the 103.\" This file descriptor must have been opened with the
104.\" .Dv O_SEARCH 104.\" .Dv O_SEARCH
105.\" flag. 105.\" flag.
106.Fa fd 106.Fa fd
107except if that file descriptor was opened with the 107except if that file descriptor was opened with the
108.Dv O_SEARCH 108.Dv O_SEARCH
109flag. 109flag.
110.Fa fd 110.Fa fd
111can be set to 111can be set to
112.Dv AT_FDCWD 112.Dv AT_FDCWD
113in order to specify the current directory. 113in order to specify the current directory.
114.Pp 114.Pp
115.Fn chmod 115.Fn chmod
116verifies that the process owner (user) either owns 116verifies that the process owner (user) either owns
117the file specified by 117the file specified by
118.Fa path 118.Fa path
119(or 119(or
120.Fa fd ) , 120.Fa fd ) ,
121or 121or
122is the super-user. 122is the super-user.
123A mode is created from 123A mode is created from
124.Em or'd 124.Em or'd
125permission bit masks 125permission bit masks
126defined in 126defined in
127.In sys/stat.h : 127.In sys/stat.h :
128.Bd -literal -offset indent -compact 128.Bd -literal -offset indent -compact
129#define S_IRWXU 0000700 /* RWX mask for owner */ 129#define S_IRWXU 0000700 /* RWX mask for owner */
130#define S_IRUSR 0000400 /* R for owner */ 130#define S_IRUSR 0000400 /* R for owner */
131#define S_IWUSR 0000200 /* W for owner */ 131#define S_IWUSR 0000200 /* W for owner */
132#define S_IXUSR 0000100 /* X for owner */ 132#define S_IXUSR 0000100 /* X for owner */
133 133
134#define S_IRWXG 0000070 /* RWX mask for group */ 134#define S_IRWXG 0000070 /* RWX mask for group */
135#define S_IRGRP 0000040 /* R for group */ 135#define S_IRGRP 0000040 /* R for group */
136#define S_IWGRP 0000020 /* W for group */ 136#define S_IWGRP 0000020 /* W for group */
137#define S_IXGRP 0000010 /* X for group */ 137#define S_IXGRP 0000010 /* X for group */
138 138
139#define S_IRWXO 0000007 /* RWX mask for other */ 139#define S_IRWXO 0000007 /* RWX mask for other */
140#define S_IROTH 0000004 /* R for other */ 140#define S_IROTH 0000004 /* R for other */
141#define S_IWOTH 0000002 /* W for other */ 141#define S_IWOTH 0000002 /* W for other */
142#define S_IXOTH 0000001 /* X for other */ 142#define S_IXOTH 0000001 /* X for other */
143 143
144#define S_ISUID 0004000 /* set user id on execution */ 144#define S_ISUID 0004000 /* set user id on execution */
145#define S_ISGID 0002000 /* set group id on execution */ 145#define S_ISGID 0002000 /* set group id on execution */
146#define S_ISVTX 0001000 /* sticky bit */ 146#define S_ISVTX 0001000 /* sticky bit */
147.Ed 147.Ed
148.Pp 148.Pp
149The mode 149The mode
150.Dv ISVTX 150.Dv ISVTX
151(the 151(the
152.Sq sticky bit ) 152.Sq sticky bit )
153can be set on regular files, but has no effect. 153can be set on regular files, but has no effect.
154For historical reasons this can be done only by the super-user. 154For historical reasons this can be done only by the super-user.
155.Pp 155.Pp
156If mode 156If mode
157.Dv ISVTX 157.Dv ISVTX
158(the 158(the
159.Sq sticky bit ) 159.Sq sticky bit )
160is set on a directory, 160is set on a directory,
161an unprivileged user may not delete or rename 161an unprivileged user may not delete or rename
162files of other users in that directory. 162files of other users in that directory.
163The sticky bit may be set by any user on a directory which the user 163The sticky bit may be set by any user on a directory which the user
164owns or has appropriate permissions. 164owns or has appropriate permissions.
165.Pp 165.Pp
166For more information about the history and properties of the sticky bit, see 166For more information about the history and properties of the sticky bit, see
167.Xr sticky 7 . 167.Xr sticky 7 .
168.Pp 168.Pp
169Changing the owner of a file 169Changing the owner of a file
170turns off the set-user-id and set-group-id bits; 170turns off the set-user-id and set-group-id bits;
171writing to a file 171writing to a file
172turns off the set-user-id and set-group-id bits 172turns off the set-user-id and set-group-id bits
173unless the user is the super-user. 173unless the user is the super-user.
174This makes the system somewhat more secure 174This makes the system somewhat more secure
175by protecting set-user-id (set-group-id) files 175by protecting set-user-id (set-group-id) files
176from remaining set-user-id (set-group-id) if they are modified, 176from remaining set-user-id (set-group-id) if they are modified,
177at the expense of a degree of compatibility. 177at the expense of a degree of compatibility.
178.Sh RETURN VALUES 178.Sh RETURN VALUES
179.Rv -std chmod lchmod fchmod fchmodat 179.Rv -std chmod lchmod fchmod fchmodat
180.Sh ERRORS 180.Sh ERRORS
181.Fn chmod , 181.Fn chmod ,
182.Fn lchmod 182.Fn lchmod
183and 183and
184.Fn fchmodat 184.Fn fchmodat
185will fail and the file mode will be unchanged if: 185will fail and the file mode will be unchanged if:
186.Bl -tag -width Er 186.Bl -tag -width Er
187.It Bq Er EACCES 187.It Bq Er EACCES
188Search permission is denied for a component of the path prefix. 188Search permission is denied for a component of the path prefix.
189.It Bq Er EFAULT 189.It Bq Er EFAULT
190.Fa path 190.Fa path
191points outside the process's allocated address space. 191points outside the process's allocated address space.
192.It Bq Er EFTYPE 192.It Bq Er EFTYPE
193The effective user ID is not the super-user, the 193The effective user ID is not the super-user, the
194.Fa mode 194.Fa mode
195includes the sticky bit 195includes the sticky bit
196.Pq Dv S_ISVTX , 196.Pq Dv S_ISVTX ,
197and 197and
198.Fa path 198.Fa path
199does not refer to a directory. 199does not refer to a directory.
200.It Bq Er EIO 200.It Bq Er EIO
201An I/O error occurred while reading from or writing to the file system. 201An I/O error occurred while reading from or writing to the file system.
202.It Bq Er ELOOP 202.It Bq Er ELOOP
203Too many symbolic links were encountered in translating the pathname. 203Too many symbolic links were encountered in translating the pathname.
204.It Bq Er ENAMETOOLONG 204.It Bq Er ENAMETOOLONG
205A component of a pathname exceeded 205A component of a pathname exceeded
206.Brq Dv NAME_MAX 206.Brq Dv NAME_MAX
207characters, or an entire path name exceeded 207characters, or an entire path name exceeded
208.Brq Dv PATH_MAX 208.Brq Dv PATH_MAX
209characters. 209characters.
210.It Bq Er ENOENT 210.It Bq Er ENOENT
211The named file does not exist. 211The named file does not exist.
212.It Bq Er ENOTDIR 212.It Bq Er ENOTDIR
213A component of the path prefix is not a directory. 213A component of the path prefix is not a directory.
214.It Bq Er EPERM 214.It Bq Er EPERM
215The effective user ID does not match the owner of the file and 215The effective user ID does not match the owner of the file and
216the effective user ID is not the super-user; or 216the effective user ID is not the super-user; or
217the mode includes the setgid bit 217the mode includes the setgid bit
218.Pq Dv S_ISGID 218.Pq Dv S_ISGID
219but the file's group is neither the effective group ID nor is it in the 219but the file's group is neither the effective group ID nor is it in the
220group access list. 220group access list.
221.It Bq Er EROFS 221.It Bq Er EROFS
222The named file resides on a read-only file system. 222The named file resides on a read-only file system.
223.El 223.El
224.Pp 224.Pp
225In addition, 225In addition,
226.Fn fchmodat 226.Fn fchmodat
227will fail if: 227will fail if:
228.Bl -tag -width Er 228.Bl -tag -width Er
229.It Bq Er EBADF 229.It Bq Er EBADF
230.Fa path 230.Fa path
231does not specify an absolute path and 231does not specify an absolute path and
232.Fa fd 232.Fa fd
233is neither 233is neither
234.Dv AT_FDCWD 234.Dv AT_FDCWD
235nor a valid file descriptor open for reading or searching. 235nor a valid file descriptor open for reading or searching.
236.It Bq Er ENOTDIR 236.It Bq Er ENOTDIR
237.Fa path 237.Fa path
238is not an absolute path and 238is not an absolute path and
239.Fa fd 239.Fa fd
240is a file descriptor associated with a non-directory file. 240is a file descriptor associated with a non-directory file.
241.El 241.El
242.Pp 242.Pp
243.Fn fchmod 243.Fn fchmod
244will fail if: 244will fail if:
245.Bl -tag -width Er 245.Bl -tag -width Er
246.It Bq Er EBADF 246.It Bq Er EBADF
247The descriptor is not valid. 247The descriptor is not valid.
248.It Bq Er EFTYPE 248.It Bq Er EFTYPE
249The effective user ID is not the super-user, the 249The effective user ID is not the super-user, the
250.Fa mode 250.Fa mode
251includes the sticky bit 251includes the sticky bit
252.Pq Dv S_ISVTX , 252.Pq Dv S_ISVTX ,
253and 253and
254.Fa fd 254.Fa fd
255does not refer to a directory. 255does not refer to a directory.
256.It Bq Er EINVAL 256.It Bq Er EINVAL
257.Fa fd 257.Fa fd
258refers to a socket, not to a file. 258refers to a socket, not to a file.
259.It Bq Er EIO 259.It Bq Er EIO
260An I/O error occurred while reading from or writing to the file system. 260An I/O error occurred while reading from or writing to the file system.
261.It Bq Er EPERM 261.It Bq Er EPERM
262The effective user ID does not match the owner of the file and 262The effective user ID does not match the owner of the file and
263the effective user ID is not the super-user; or 263the effective user ID is not the super-user; or
264the mode includes the setgid bit 264the mode includes the setgid bit
265.Pq Dv S_ISGID 265.Pq Dv S_ISGID
266but the file's group is neither the effective group ID nor is it in the 266but the file's group is neither the effective group ID nor is it in the
267group access list. 267group access list.
268.It Bq Er EROFS 268.It Bq Er EROFS
269The file resides on a read-only file system. 269The file resides on a read-only file system.
270.El 270.El
271.Sh SEE ALSO 271.Sh SEE ALSO
272.Xr chmod 1 , 272.Xr chmod 1 ,
273.Xr chflags 2 , 273.Xr chflags 2 ,
274.Xr chown 2 , 274.Xr chown 2 ,
275.Xr open 2 , 275.Xr open 2 ,
276.Xr stat 2 , 276.Xr stat 2 ,
277.Xr getmode 3 , 277.Xr getmode 3 ,
278.Xr setmode 3 , 278.Xr setmode 3 ,
279.Xr sticky 7 , 279.Xr sticky 7 ,
280.Xr symlink 7 280.Xr symlink 7
281.Sh STANDARDS 281.Sh STANDARDS
282The 282The
283.Fn chmod 283.Fn chmod
284function conforms to 284function conforms to
285.St -p1003.1-90 . 285.St -p1003.1-90 .
 286The
 287.Fn fchmod
 288function conforms to
 289.St -xpg4.2 .
 290The
286.Fn fchmodat 291.Fn fchmodat
287function conforms to 292function conforms to
288.St -p1003.1-2008 . 293.St -p1003.1-2008 .
289.Sh HISTORY 294.Sh HISTORY
290The 295The
291.Fn chmod 296.Fn chmod
292function call appeared in 297function call appeared in
293.At v1 . 298.At v1 .
294The 299The
295.Fn fchmod 300.Fn fchmod
296function call 301function call
297appeared in 302appeared in
298.Bx 4.2 . 303.Bx 4.2 .
299The 304The
300.Fn lchmod 305.Fn lchmod
301function call appeared in 306function call appeared in
302.Nx 1.3 . 307.Nx 1.3 .