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