xref: /minix3/lib/libc/sys/chmod.2 (revision 84d9c625bfea59e274550651111ae9edfdc40fbd)
1*84d9c625SLionel Sambuc.\"	$NetBSD: chmod.2,v 1.47 2013/10/15 11:43:21 njoly Exp $
22fe8fb19SBen Gras.\"
32fe8fb19SBen Gras.\" Copyright (c) 1980, 1991, 1993
42fe8fb19SBen Gras.\"	The Regents of the University of California.  All rights reserved.
52fe8fb19SBen Gras.\"
62fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
72fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
82fe8fb19SBen Gras.\" are met:
92fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
102fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
112fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
122fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
132fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
142fe8fb19SBen Gras.\" 3. Neither the name of the University nor the names of its contributors
152fe8fb19SBen Gras.\"    may be used to endorse or promote products derived from this software
162fe8fb19SBen Gras.\"    without specific prior written permission.
172fe8fb19SBen Gras.\"
182fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
192fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
202fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
212fe8fb19SBen Gras.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
222fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
232fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
242fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
252fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
262fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
272fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
282fe8fb19SBen Gras.\" SUCH DAMAGE.
292fe8fb19SBen Gras.\"
302fe8fb19SBen Gras.\"     @(#)chmod.2	8.1 (Berkeley) 6/4/93
312fe8fb19SBen Gras.\"
32*84d9c625SLionel Sambuc.Dd July 29, 2013
332fe8fb19SBen Gras.Dt CHMOD 2
342fe8fb19SBen Gras.Os
352fe8fb19SBen Gras.Sh NAME
362fe8fb19SBen Gras.Nm chmod ,
372fe8fb19SBen Gras.Nm lchmod ,
38*84d9c625SLionel Sambuc.Nm fchmod ,
39*84d9c625SLionel Sambuc.Nm fchmodat
402fe8fb19SBen Gras.Nd change mode of file
412fe8fb19SBen Gras.Sh LIBRARY
422fe8fb19SBen Gras.Lb libc
432fe8fb19SBen Gras.Sh SYNOPSIS
442fe8fb19SBen Gras.In sys/stat.h
452fe8fb19SBen Gras.Ft int
462fe8fb19SBen Gras.Fn chmod "const char *path" "mode_t mode"
472fe8fb19SBen Gras.Ft int
482fe8fb19SBen Gras.Fn lchmod "const char *path" "mode_t mode"
492fe8fb19SBen Gras.Ft int
502fe8fb19SBen Gras.Fn fchmod "int fd" "mode_t mode"
51*84d9c625SLionel Sambuc.In sys/stat.h
52*84d9c625SLionel Sambuc.In fcntl.h
53*84d9c625SLionel Sambuc.Ft int
54*84d9c625SLionel Sambuc.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag"
552fe8fb19SBen Gras.Sh DESCRIPTION
562fe8fb19SBen GrasThe function
572fe8fb19SBen Gras.Fn chmod
582fe8fb19SBen Grassets the file permission bits
592fe8fb19SBen Grasof the file
602fe8fb19SBen Grasspecified by the pathname
612fe8fb19SBen Gras.Fa path
622fe8fb19SBen Grasto
632fe8fb19SBen Gras.Fa mode .
642fe8fb19SBen Gras.Fn fchmod
652fe8fb19SBen Grassets the permission bits of the specified
662fe8fb19SBen Grasfile descriptor
672fe8fb19SBen Gras.Fa fd .
682fe8fb19SBen Gras.Fn lchmod
692fe8fb19SBen Grasis like
702fe8fb19SBen Gras.Fn chmod
712fe8fb19SBen Grasexcept in the case where the named file is a symbolic link,
722fe8fb19SBen Grasin which case
732fe8fb19SBen Gras.Fn lchmod
742fe8fb19SBen Grassets the permission bits of the link,
752fe8fb19SBen Graswhile
762fe8fb19SBen Gras.Fn chmod
772fe8fb19SBen Grassets the bits of the file the link references.
78*84d9c625SLionel Sambuc.Pp
79*84d9c625SLionel Sambuc.Fn fchmodat
80*84d9c625SLionel Sambucworks the same way as
81*84d9c625SLionel Sambuc.Fn chmod
82*84d9c625SLionel Sambuc(or
83*84d9c625SLionel Sambuc.Fn lchmod
84*84d9c625SLionel Sambucif
85*84d9c625SLionel Sambuc.Dv AT_SYMLINK_NOFOLLOW
86*84d9c625SLionel Sambucis set in
87*84d9c625SLionel Sambuc.Fa flag )
88*84d9c625SLionel Sambucexcept if
89*84d9c625SLionel Sambuc.Fa path
90*84d9c625SLionel Sambucis relative.
91*84d9c625SLionel SambucIn that case, it is looked up from a directory whose file
92*84d9c625SLionel Sambucdescriptor was passed as
93*84d9c625SLionel Sambuc.Fa fd .
94*84d9c625SLionel SambucSearch permission is required on this directory.
95*84d9c625SLionel Sambuc.\"    (These alternatives await a decision about the semantics of O_SEARCH)
96*84d9c625SLionel Sambuc.\" Search permission is required on this directory
97*84d9c625SLionel Sambuc.\" except if
98*84d9c625SLionel Sambuc.\" .Fa fd
99*84d9c625SLionel Sambuc.\" was opened with the
100*84d9c625SLionel Sambuc.\" .Dv O_SEARCH
101*84d9c625SLionel Sambuc.\" flag.
102*84d9c625SLionel Sambuc.\"    - or -
103*84d9c625SLionel Sambuc.\" This file descriptor must have been opened with the
104*84d9c625SLionel Sambuc.\" .Dv O_SEARCH
105*84d9c625SLionel Sambuc.\" flag.
106*84d9c625SLionel Sambuc.Fa fd
107*84d9c625SLionel Sambucexcept if that file descriptor was opened with the
108*84d9c625SLionel Sambuc.Dv O_SEARCH
109*84d9c625SLionel Sambucflag.
110*84d9c625SLionel Sambuc.Fa fd
111*84d9c625SLionel Sambuccan be set to
112*84d9c625SLionel Sambuc.Dv AT_FDCWD
113*84d9c625SLionel Sambucin order to specify the current directory.
114*84d9c625SLionel Sambuc.Pp
1152fe8fb19SBen Gras.Fn chmod
1162fe8fb19SBen Grasverifies that the process owner (user) either owns
1172fe8fb19SBen Grasthe file specified by
1182fe8fb19SBen Gras.Fa path
1192fe8fb19SBen Gras(or
1202fe8fb19SBen Gras.Fa fd ) ,
1212fe8fb19SBen Grasor
1222fe8fb19SBen Grasis the super-user.
1232fe8fb19SBen GrasA mode is created from
1242fe8fb19SBen Gras.Em or'd
1252fe8fb19SBen Graspermission bit masks
1262fe8fb19SBen Grasdefined in
1272fe8fb19SBen Gras.In sys/stat.h :
1282fe8fb19SBen Gras.Bd -literal -offset indent -compact
1292fe8fb19SBen Gras#define S_IRWXU 0000700    /* RWX mask for owner */
1302fe8fb19SBen Gras#define S_IRUSR 0000400    /* R for owner */
1312fe8fb19SBen Gras#define S_IWUSR 0000200    /* W for owner */
1322fe8fb19SBen Gras#define S_IXUSR 0000100    /* X for owner */
1332fe8fb19SBen Gras
1342fe8fb19SBen Gras#define S_IRWXG 0000070    /* RWX mask for group */
1352fe8fb19SBen Gras#define S_IRGRP 0000040    /* R for group */
1362fe8fb19SBen Gras#define S_IWGRP 0000020    /* W for group */
1372fe8fb19SBen Gras#define S_IXGRP 0000010    /* X for group */
1382fe8fb19SBen Gras
1392fe8fb19SBen Gras#define S_IRWXO 0000007    /* RWX mask for other */
1402fe8fb19SBen Gras#define S_IROTH 0000004    /* R for other */
1412fe8fb19SBen Gras#define S_IWOTH 0000002    /* W for other */
1422fe8fb19SBen Gras#define S_IXOTH 0000001    /* X for other */
1432fe8fb19SBen Gras
1442fe8fb19SBen Gras#define S_ISUID 0004000    /* set user id on execution */
1452fe8fb19SBen Gras#define S_ISGID 0002000    /* set group id on execution */
146f14fb602SLionel Sambuc#define S_ISVTX 0001000    /* sticky bit */
1472fe8fb19SBen Gras.Ed
1482fe8fb19SBen Gras.Pp
149f14fb602SLionel SambucThe mode
1502fe8fb19SBen Gras.Dv ISVTX
1512fe8fb19SBen Gras(the
1522fe8fb19SBen Gras.Sq sticky bit )
153f14fb602SLionel Sambuccan be set on regular files, but has no effect.
154f14fb602SLionel SambucFor historical reasons this can be done only by the super-user.
1552fe8fb19SBen Gras.Pp
1562fe8fb19SBen GrasIf mode
1572fe8fb19SBen Gras.Dv ISVTX
1582fe8fb19SBen Gras(the
1592fe8fb19SBen Gras.Sq sticky bit )
1602fe8fb19SBen Grasis set on a directory,
1612fe8fb19SBen Grasan unprivileged user may not delete or rename
1622fe8fb19SBen Grasfiles of other users in that directory.
1632fe8fb19SBen GrasThe sticky bit may be set by any user on a directory which the user
1642fe8fb19SBen Grasowns or has appropriate permissions.
1652fe8fb19SBen Gras.Pp
166f14fb602SLionel SambucFor more information about the history and properties of the sticky bit, see
1672fe8fb19SBen Gras.Xr sticky 7 .
1682fe8fb19SBen Gras.Pp
1692fe8fb19SBen GrasChanging the owner of a file
1702fe8fb19SBen Grasturns off the set-user-id and set-group-id bits;
1712fe8fb19SBen Graswriting to a file
1722fe8fb19SBen Grasturns off the set-user-id and set-group-id bits
1732fe8fb19SBen Grasunless the user is the super-user.
1742fe8fb19SBen GrasThis makes the system somewhat more secure
1752fe8fb19SBen Grasby protecting set-user-id (set-group-id) files
1762fe8fb19SBen Grasfrom remaining set-user-id (set-group-id) if they are modified,
1772fe8fb19SBen Grasat the expense of a degree of compatibility.
1782fe8fb19SBen Gras.Sh RETURN VALUES
179*84d9c625SLionel Sambuc.Rv -std chmod lchmod fchmod fchmodat
1802fe8fb19SBen Gras.Sh ERRORS
181*84d9c625SLionel Sambuc.Fn chmod ,
1822fe8fb19SBen Gras.Fn lchmod
183*84d9c625SLionel Sambucand
184*84d9c625SLionel Sambuc.Fn fchmodat
1852fe8fb19SBen Graswill fail and the file mode will be unchanged if:
1862fe8fb19SBen Gras.Bl -tag -width Er
187f14fb602SLionel Sambuc.It Bq Er EACCES
188f14fb602SLionel SambucSearch permission is denied for a component of the path prefix.
189f14fb602SLionel Sambuc.It Bq Er EFAULT
190f14fb602SLionel Sambuc.Fa path
191f14fb602SLionel Sambucpoints outside the process's allocated address space.
192f14fb602SLionel Sambuc.It Bq Er EFTYPE
193f14fb602SLionel SambucThe effective user ID is not the super-user, the
194f14fb602SLionel Sambuc.Fa mode
195f14fb602SLionel Sambucincludes the sticky bit
196f14fb602SLionel Sambuc.Pq Dv S_ISVTX ,
197f14fb602SLionel Sambucand
198f14fb602SLionel Sambuc.Fa path
199f14fb602SLionel Sambucdoes not refer to a directory.
200f14fb602SLionel Sambuc.It Bq Er EIO
201f14fb602SLionel SambucAn I/O error occurred while reading from or writing to the file system.
202f14fb602SLionel Sambuc.It Bq Er ELOOP
203f14fb602SLionel SambucToo many symbolic links were encountered in translating the pathname.
2042fe8fb19SBen Gras.It Bq Er ENAMETOOLONG
2052fe8fb19SBen GrasA component of a pathname exceeded
2062fe8fb19SBen Gras.Brq Dv NAME_MAX
2072fe8fb19SBen Grascharacters, or an entire path name exceeded
2082fe8fb19SBen Gras.Brq Dv PATH_MAX
2092fe8fb19SBen Grascharacters.
2102fe8fb19SBen Gras.It Bq Er ENOENT
2112fe8fb19SBen GrasThe named file does not exist.
212f14fb602SLionel Sambuc.It Bq Er ENOTDIR
213f14fb602SLionel SambucA component of the path prefix is not a directory.
2142fe8fb19SBen Gras.It Bq Er EPERM
2152fe8fb19SBen GrasThe effective user ID does not match the owner of the file and
216f14fb602SLionel Sambucthe effective user ID is not the super-user; or
217f14fb602SLionel Sambucthe mode includes the setgid bit
2182fe8fb19SBen Gras.Pq Dv S_ISGID
2192fe8fb19SBen Grasbut the file's group is neither the effective group ID nor is it in the
2202fe8fb19SBen Grasgroup access list.
2212fe8fb19SBen Gras.It Bq Er EROFS
2222fe8fb19SBen GrasThe named file resides on a read-only file system.
2232fe8fb19SBen Gras.El
2242fe8fb19SBen Gras.Pp
225*84d9c625SLionel SambucIn addition,
226*84d9c625SLionel Sambuc.Fn fchmodat
227*84d9c625SLionel Sambucwill fail if:
228*84d9c625SLionel Sambuc.Bl -tag -width Er
229*84d9c625SLionel Sambuc.It Bq Er EBADF
230*84d9c625SLionel Sambuc.Fa path
231*84d9c625SLionel Sambucdoes not specify an absolute path and
232*84d9c625SLionel Sambuc.Fa fd
233*84d9c625SLionel Sambucis neither
234*84d9c625SLionel Sambuc.Dv AT_FDCWD
235*84d9c625SLionel Sambucnor a valid file descriptor open for reading or searching.
236*84d9c625SLionel Sambuc.It Bq Er ENOTDIR
237*84d9c625SLionel Sambuc.Fa path
238*84d9c625SLionel Sambucis not an absolute path and
239*84d9c625SLionel Sambuc.Fa fd
240*84d9c625SLionel Sambucis a file descriptor associated with a non-directory file.
241*84d9c625SLionel Sambuc.El
242*84d9c625SLionel Sambuc.Pp
2432fe8fb19SBen Gras.Fn fchmod
2442fe8fb19SBen Graswill fail if:
2452fe8fb19SBen Gras.Bl -tag -width Er
2462fe8fb19SBen Gras.It Bq Er EBADF
2472fe8fb19SBen GrasThe descriptor is not valid.
2482fe8fb19SBen Gras.It Bq Er EFTYPE
2492fe8fb19SBen GrasThe effective user ID is not the super-user, the
2502fe8fb19SBen Gras.Fa mode
2512fe8fb19SBen Grasincludes the sticky bit
2522fe8fb19SBen Gras.Pq Dv S_ISVTX ,
2532fe8fb19SBen Grasand
2542fe8fb19SBen Gras.Fa fd
2552fe8fb19SBen Grasdoes not refer to a directory.
256f14fb602SLionel Sambuc.It Bq Er EINVAL
257f14fb602SLionel Sambuc.Fa fd
258f14fb602SLionel Sambucrefers to a socket, not to a file.
259f14fb602SLionel Sambuc.It Bq Er EIO
260f14fb602SLionel SambucAn I/O error occurred while reading from or writing to the file system.
261f14fb602SLionel Sambuc.It Bq Er EPERM
262f14fb602SLionel SambucThe effective user ID does not match the owner of the file and
263f14fb602SLionel Sambucthe effective user ID is not the super-user; or
264f14fb602SLionel Sambucthe mode includes the setgid bit
265f14fb602SLionel Sambuc.Pq Dv S_ISGID
266f14fb602SLionel Sambucbut the file's group is neither the effective group ID nor is it in the
267f14fb602SLionel Sambucgroup access list.
268f14fb602SLionel Sambuc.It Bq Er EROFS
269f14fb602SLionel SambucThe file resides on a read-only file system.
2702fe8fb19SBen Gras.El
2712fe8fb19SBen Gras.Sh SEE ALSO
2722fe8fb19SBen Gras.Xr chmod 1 ,
2732fe8fb19SBen Gras.Xr chflags 2 ,
2742fe8fb19SBen Gras.Xr chown 2 ,
2752fe8fb19SBen Gras.Xr open 2 ,
2762fe8fb19SBen Gras.Xr stat 2 ,
2772fe8fb19SBen Gras.Xr getmode 3 ,
2782fe8fb19SBen Gras.Xr setmode 3 ,
2792fe8fb19SBen Gras.Xr sticky 7 ,
2802fe8fb19SBen Gras.Xr symlink 7
2812fe8fb19SBen Gras.Sh STANDARDS
2822fe8fb19SBen GrasThe
2832fe8fb19SBen Gras.Fn chmod
2842fe8fb19SBen Grasfunction conforms to
2852fe8fb19SBen Gras.St -p1003.1-90 .
286*84d9c625SLionel Sambuc.Fn fchmodat
287*84d9c625SLionel Sambucfunction conforms to
288*84d9c625SLionel Sambuc.St -p1003.1-2008 .
2892fe8fb19SBen Gras.Sh HISTORY
2902fe8fb19SBen GrasThe
2912fe8fb19SBen Gras.Fn fchmod
2922fe8fb19SBen Grasfunction call
2932fe8fb19SBen Grasappeared in
2942fe8fb19SBen Gras.Bx 4.2 .
2952fe8fb19SBen GrasThe
2962fe8fb19SBen Gras.Fn lchmod
2972fe8fb19SBen Grasfunction call appeared in
2982fe8fb19SBen Gras.Nx 1.3 .
299