1CHMOD(3P)                  POSIX Programmer's Manual                 CHMOD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       chmod, fchmodat — change mode of a file
13

SYNOPSIS

15       #include <sys/stat.h>
16
17       int chmod(const char *path, mode_t mode);
18
19       #include <fcntl.h>
20
21       int fchmodat(int fd, const char *path, mode_t mode, int flag);
22

DESCRIPTION

24       The chmod() function shall change S_ISUID, S_ISGID,  S_ISVTX,  and  the
25       file  permission  bits  of the file named by the pathname pointed to by
26       the path argument to the corresponding bits in the mode  argument.  The
27       application  shall  ensure  that  the  effective user ID of the process
28       matches the owner of the file or the process has appropriate privileges
29       in order to do this.
30
31       S_ISUID,  S_ISGID,  S_ISVTX, and the file permission bits are described
32       in <sys/stat.h>.
33
34       If the calling process does not have appropriate privileges, and if the
35       group  ID  of  the file does not match the effective group ID or one of
36       the supplementary group IDs and if the file  is  a  regular  file,  bit
37       S_ISGID (set-group-ID on execution) in the file's mode shall be cleared
38       upon successful return from chmod().
39
40       Additional implementation-defined restrictions may  cause  the  S_ISUID
41       and S_ISGID bits in mode to be ignored.
42
43       Upon successful completion, chmod() shall mark for update the last file
44       status change timestamp of the file.
45
46       The fchmodat() function shall be equivalent  to  the  chmod()  function
47       except  in  the case where path specifies a relative path. In this case
48       the file to be changed is determined relative to the directory  associ‐
49       ated  with the file descriptor fd instead of the current working direc‐
50       tory. If the access mode of the open file description  associated  with
51       the  file  descriptor is not O_SEARCH, the function shall check whether
52       directory searches are permitted using the current permissions  of  the
53       directory  underlying  the  file  descriptor.  If  the  access  mode is
54       O_SEARCH, the function shall not perform the check.
55
56       Values for flag are constructed by a bitwise-inclusive OR of flags from
57       the following list, defined in <fcntl.h>:
58
59       AT_SYMLINK_NOFOLLOW
60             If path names a symbolic link, then the mode of the symbolic link
61             is changed.
62
63       If fchmodat() is passed the special value AT_FDCWD in the fd parameter,
64       the  current working directory shall be used. If also flag is zero, the
65       behavior shall be identical to a call to chmod().
66

RETURN VALUE

68       Upon successful completion, these functions shall return 0.  Otherwise,
69       these functions shall return -1 and set errno to indicate the error. If
70       -1 is returned, no change to the file mode occurs.
71

ERRORS

73       These functions shall fail if:
74
75       EACCES Search permission is denied on a component of the path prefix.
76
77       ELOOP  A loop exists in symbolic links encountered during resolution of
78              the path argument.
79
80       ENAMETOOLONG
81              The  length  of  a  component  of  a  pathname  is  longer  than
82              {NAME_MAX}.
83
84       ENOENT A component of path does not name an existing file or path is an
85              empty string.
86
87       ENOTDIR
88              A  component  of  the path prefix names an existing file that is
89              neither a directory nor a symbolic link to a directory,  or  the
90              path  argument  contains  at least one non-<slash> character and
91              ends with one or more trailing <slash> characters and  the  last
92              pathname  component  names  an  existing  file that is neither a
93              directory nor a symbolic link to a directory.
94
95       EPERM  The effective user ID does not match the owner of the  file  and
96              the process does not have appropriate privileges.
97
98       EROFS  The named file resides on a read-only file system.
99
100       The fchmodat() function shall fail if:
101
102       EACCES The  access mode of the open file description associated with fd
103              is not O_SEARCH and the permissions of the directory  underlying
104              fd do not permit directory searches.
105
106       EBADF  The  path  argument does not specify an absolute path and the fd
107              argument is neither AT_FDCWD nor a valid  file  descriptor  open
108              for reading or searching.
109
110       ENOTDIR
111              The  path  argument  is  not  an  absolute path and fd is a file
112              descriptor associated with a non-directory file.
113
114       These functions may fail if:
115
116       EINTR  A signal was caught during execution of the function.
117
118       EINVAL The value of the mode argument is invalid.
119
120       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
121              resolution of the path argument.
122
123       ENAMETOOLONG
124              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
125              tion of a symbolic link produced an intermediate result  with  a
126              length that exceeds {PATH_MAX}.
127
128       The fchmodat() function may fail if:
129
130       EINVAL The value of the flag argument is invalid.
131
132       EOPNOTSUPP
133              The  AT_SYMLINK_NOFOLLOW  bit  is set in the flag argument, path
134              names a symbolic link, and the system does not support  changing
135              the mode of a symbolic link.
136
137       The following sections are informative.
138

EXAMPLES

140   Setting Read Permissions for User, Group, and Others
141       The  following  example sets read permissions for the owner, group, and
142       others.
143
144
145           #include <sys/stat.h>
146
147           const char *path;
148           ...
149           chmod(path, S_IRUSR|S_IRGRP|S_IROTH);
150
151   Setting Read, Write, and Execute Permissions for the Owner Only
152       The following example sets read, write, and execute permissions for the
153       owner, and no permissions for group and others.
154
155
156           #include <sys/stat.h>
157
158           const char *path;
159           ...
160           chmod(path, S_IRWXU);
161
162   Setting Different Permissions for Owner, Group, and Other
163       The  following  example  sets owner permissions for CHANGEFILE to read,
164       write, and execute, group permissions to read and  execute,  and  other
165       permissions to read.
166
167
168           #include <sys/stat.h>
169
170           #define CHANGEFILE "/etc/myfile"
171           ...
172           chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH);
173
174   Setting and Checking File Permissions
175       The  following  example  sets the file permission bits for a file named
176       /home/cnd/mod1, then calls the stat() function to  verify  the  permis‐
177       sions.
178
179
180           #include <sys/types.h>
181           #include <sys/stat.h>
182
183           int status;
184           struct stat buffer
185           ...
186           chmod("/home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH);
187           status = stat("/home/cnd/mod1", &buffer);
188

APPLICATION USAGE

190       In order to ensure that the S_ISUID and S_ISGID bits are set, an appli‐
191       cation requiring this should use stat() after a successful  chmod()  to
192       verify this.
193
194       Any  file  descriptors  currently open by any process on the file could
195       possibly become invalid if the mode of the file is changed to  a  value
196       which would deny access to that process. One situation where this could
197       occur is on a stateless file system. This behavior will not occur in  a
198       conforming environment.
199

RATIONALE

201       This  volume  of POSIX.1‐2017 specifies that the S_ISGID bit is cleared
202       by chmod() on a regular file under certain conditions. This  is  speci‐
203       fied on the assumption that regular files may be executed, and the sys‐
204       tem should prevent users from making executable setgid() files  perform
205       with  privileges that the caller does not have. On implementations that
206       support execution of other  file  types,  the  S_ISGID  bit  should  be
207       cleared for those file types under the same circumstances.
208
209       Implementations  that  use the S_ISUID bit to indicate some other func‐
210       tion (for example, mandatory record locking)  on  non-executable  files
211       need  not clear this bit on writing. They should clear the bit for exe‐
212       cutable files and any other cases where the bit grants  special  powers
213       to  processes  that change the file contents. Similar comments apply to
214       the S_ISGID bit.
215
216       The purpose of the fchmodat() function is to enable changing  the  mode
217       of  files in directories other than the current working directory with‐
218       out exposure to race conditions.  Any part of the path of a file  could
219       be  changed  in parallel to a call to chmod(), resulting in unspecified
220       behavior. By opening a file descriptor for  the  target  directory  and
221       using  the  fchmodat()  function  it can be guaranteed that the changed
222       file is located relative to the desired directory. Some implementations
223       might  allow changing the mode of symbolic links. This is not supported
224       by the interfaces in the POSIX specification. Systems with such support
225       provide  an  interface named lchmod().  To support such implementations
226       fchmodat() has a flag parameter.
227

FUTURE DIRECTIONS

229       None.
230

SEE ALSO

232       access(), chown(),  exec,  fstatat(),  fstatvfs(),  mkdir(),  mkfifo(),
233       mknod(), open()
234
235       The  Base  Definitions volume of POSIX.1‐2017, <fcntl.h>, <sys_stat.h>,
236       <sys_types.h>
237
239       Portions of this text are reprinted and reproduced in  electronic  form
240       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
241       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
242       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
243       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
244       event of any discrepancy between this version and the original IEEE and
245       The Open Group Standard, the original IEEE and The Open Group  Standard
246       is  the  referee document. The original Standard can be obtained online
247       at http://www.opengroup.org/unix/online.html .
248
249       Any typographical or formatting errors that appear  in  this  page  are
250       most likely to have been introduced during the conversion of the source
251       files to man page format. To report such errors,  see  https://www.ker
252       nel.org/doc/man-pages/reporting_bugs.html .
253
254
255
256IEEE/The Open Group                  2017                            CHMOD(3P)
Impressum