1CHMOD(2)                   Linux Programmer's Manual                  CHMOD(2)
2
3
4

NAME

6       chmod, fchmod, fchmodat - change permissions of a file
7

SYNOPSIS

9       #include <sys/stat.h>
10
11       int chmod(const char *pathname, mode_t mode);
12       int fchmod(int fd, mode_t mode);
13
14       #include <fcntl.h>           /* Definition of AT_* constants */
15       #include <sys/stat.h>
16
17       int fchmodat(int dirfd, const char *pathname, mode_t mode, int flags);
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       fchmod():
22           Since glibc 2.24:
23               _POSIX_C_SOURCE >= 199309L
24           Glibc 2.19 to 2.23
25               _POSIX_C_SOURCE
26           Glibc 2.16 to 2.19:
27               _BSD_SOURCE || _POSIX_C_SOURCE
28           Glibc 2.12 to 2.16:
29               _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
30                   _POSIX_C_SOURCE >= 200809L
31           Glibc 2.11 and earlier:
32               _BSD_SOURCE || _XOPEN_SOURCE >= 500
33
34       fchmodat():
35           Since glibc 2.10:
36               _POSIX_C_SOURCE >= 200809L
37           Before glibc 2.10:
38               _ATFILE_SOURCE
39

DESCRIPTION

41       The  chmod()  and fchmod() system calls change a files mode bits.  (The
42       file mode consists of the file permission bits  plus  the  set-user-ID,
43       set-group-ID,  and sticky bits.)  These system calls differ only in how
44       the file is specified:
45
46       * chmod() changes the mode of the  file  specified  whose  pathname  is
47         given in pathname, which is dereferenced if it is a symbolic link.
48
49       * fchmod()  changes  the  mode of the file referred to by the open file
50         descriptor fd.
51
52       The new file mode is specified in mode, which is a bit mask created  by
53       ORing together zero or more of the following:
54
55       S_ISUID  (04000)  set-user-ID   (set   process  effective  user  ID  on
56                         execve(2))
57
58       S_ISGID  (02000)  set-group-ID  (set  process  effective  group  ID  on
59                         execve(2);   mandatory   locking,   as  described  in
60                         fcntl(2); take a new file's group from parent  direc‐
61                         tory, as described in chown(2) and mkdir(2))
62
63       S_ISVTX  (01000)  sticky bit (restricted deletion flag, as described in
64                         unlink(2))
65
66       S_IRUSR  (00400)  read by owner
67
68       S_IWUSR  (00200)  write by owner
69
70       S_IXUSR  (00100)  execute/search by owner ("search" applies for  direc‐
71                         tories,  and  means that entries within the directory
72                         can be accessed)
73
74       S_IRGRP  (00040)  read by group
75
76       S_IWGRP  (00020)  write by group
77
78       S_IXGRP  (00010)  execute/search by group
79
80       S_IROTH  (00004)  read by others
81
82       S_IWOTH  (00002)  write by others
83
84       S_IXOTH  (00001)  execute/search by others
85
86       The effective UID of the calling process must match the  owner  of  the
87       file,  or  the  process  must  be  privileged  (Linux: it must have the
88       CAP_FOWNER capability).
89
90       If the calling process is not privileged  (Linux:  does  not  have  the
91       CAP_FSETID  capability),  and  the group of the file does not match the
92       effective group ID of the process or one  of  its  supplementary  group
93       IDs,  the  S_ISGID  bit  will be turned off, but this will not cause an
94       error to be returned.
95
96       As a security measure, depending on the filesystem, the set-user-ID and
97       set-group-ID  execution  bits  may  be turned off if a file is written.
98       (On Linux, this occurs  if  the  writing  process  does  not  have  the
99       CAP_FSETID  capability.)   On  some filesystems, only the superuser can
100       set the sticky bit, which may have a special meaning.  For  the  sticky
101       bit,  and  for  set-user-ID  and  set-group-ID bits on directories, see
102       inode(7).
103
104       On NFS filesystems, restricting the permissions will immediately influ‐
105       ence  already  open  files,  because  the access control is done on the
106       server, but open files are maintained by the client.  Widening the per‐
107       missions  may  be  delayed  for  other  clients if attribute caching is
108       enabled on them.
109
110   fchmodat()
111       The fchmodat() system call operates in exactly the same way as chmod(),
112       except for the differences described here.
113
114       If  the  pathname given in pathname is relative, then it is interpreted
115       relative to the directory referred to  by  the  file  descriptor  dirfd
116       (rather  than  relative to the current working directory of the calling
117       process, as is done by chmod() for a relative pathname).
118
119       If pathname is relative and dirfd is the special value  AT_FDCWD,  then
120       pathname  is  interpreted  relative to the current working directory of
121       the calling process (like chmod()).
122
123       If pathname is absolute, then dirfd is ignored.
124
125       flags can either be 0, or include the following flag:
126
127       AT_SYMLINK_NOFOLLOW
128              If pathname is a symbolic link, do not dereference  it:  instead
129              operate  on  the link itself.  This flag is not currently imple‐
130              mented.
131
132       See openat(2) for an explanation of the need for fchmodat().
133

RETURN VALUE

135       On success, zero is returned.  On error, -1 is returned, and  errno  is
136       set appropriately.
137

ERRORS

139       Depending  on  the filesystem, errors other than those listed below can
140       be returned.
141
142       The more general errors for chmod() are listed below:
143
144       EACCES Search permission is denied on a component of the  path  prefix.
145              (See also path_resolution(7).)
146
147       EFAULT pathname points outside your accessible address space.
148
149       EIO    An I/O error occurred.
150
151       ELOOP  Too many symbolic links were encountered in resolving pathname.
152
153       ENAMETOOLONG
154              pathname is too long.
155
156       ENOENT The file does not exist.
157
158       ENOMEM Insufficient kernel memory was available.
159
160       ENOTDIR
161              A component of the path prefix is not a directory.
162
163       EPERM  The  effective UID does not match the owner of the file, and the
164              process  is  not  privileged  (Linux:  it  does  not  have   the
165              CAP_FOWNER capability).
166
167       EPERM  The   file   is   marked   immutable   or   append-only.    (See
168              ioctl_iflags(2).)
169
170       EROFS  The named file resides on a read-only filesystem.
171
172       The general errors for fchmod() are listed below:
173
174       EBADF  The file descriptor fd is not valid.
175
176       EIO    See above.
177
178       EPERM  See above.
179
180       EROFS  See above.
181
182       The same errors that occur for chmod() can also occur  for  fchmodat().
183       The following additional errors can occur for fchmodat():
184
185       EBADF  dirfd is not a valid file descriptor.
186
187       EINVAL Invalid flag specified in flags.
188
189       ENOTDIR
190              pathname is relative and dirfd is a file descriptor referring to
191              a file other than a directory.
192
193       ENOTSUP
194              flags specified AT_SYMLINK_NOFOLLOW, which is not supported.
195

VERSIONS

197       fchmodat() was added to Linux in kernel  2.6.16;  library  support  was
198       added to glibc in version 2.4.
199

CONFORMING TO

201       chmod(), fchmod(): 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008.
202
203       fchmodat(): POSIX.1-2008.
204

NOTES

206   C library/kernel differences
207       The  GNU  C  library  fchmodat() wrapper function implements the POSIX-
208       specified interface described in this  page.   This  interface  differs
209       from  the  underlying  Linux  system  call, which does not have a flags
210       argument.
211
212   Glibc notes
213       On older kernels where fchmodat() is  unavailable,  the  glibc  wrapper
214       function falls back to the use of chmod().  When pathname is a relative
215       pathname, glibc constructs a pathname based on  the  symbolic  link  in
216       /proc/self/fd that corresponds to the dirfd argument.
217

SEE ALSO

219       chmod(1), chown(2), execve(2), open(2), stat(2), inode(7), path_resolu‐
220       tion(7), symlink(7)
221

COLOPHON

223       This page is part of release 5.04 of the Linux  man-pages  project.   A
224       description  of  the project, information about reporting bugs, and the
225       latest    version    of    this    page,    can     be     found     at
226       https://www.kernel.org/doc/man-pages/.
227
228
229
230Linux                             2017-09-15                          CHMOD(2)
Impressum