]>
Commit | Line | Data |
---|---|---|
f81fb444 | 1 | \(aq" Hey Emacs! This file is -*- nroff -*- source. |
fea681da MK |
2 | .\" |
3 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
6a2df4ee | 4 | .\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) |
c11b1abf | 5 | .\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
6 | .\" |
7 | .\" Permission is granted to make and distribute verbatim copies of this | |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
26 | .\" | |
27 | .\" Modified by Michael Haardt <michael@moria.de> | |
28 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified 1996-07-09 by Andries Brouwer <aeb@cwi.nl> | |
30 | .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> | |
31 | .\" Modified 1997-05-18 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de> | |
c11b1abf | 32 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
6a2df4ee | 33 | .\" 2007-07-08, mtk, added an example program; updated SYNOPSIS |
fea681da | 34 | .\" |
cc4615cc | 35 | .TH CHOWN 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
36 | .SH NAME |
37 | chown, fchown, lchown \- change ownership of a file | |
38 | .SH SYNOPSIS | |
fea681da MK |
39 | .B #include <unistd.h> |
40 | .sp | |
41 | .BI "int chown(const char *" path ", uid_t " owner ", gid_t " group ); | |
42 | .br | |
43 | .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); | |
44 | .br | |
45 | .BI "int lchown(const char *" path ", uid_t " owner ", gid_t " group ); | |
cc4615cc MK |
46 | .sp |
47 | .in -4n | |
48 | Feature Test Macro Requirements for glibc (see | |
49 | .BR feature_test_macros (7)): | |
50 | .in | |
51 | .sp | |
52 | .BR fchown (), | |
53 | .BR lchown (): | |
54 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 | |
fea681da | 55 | .SH DESCRIPTION |
6cb0b6a0 | 56 | .\" FIXME . The description here could be improved to explicitly say |
373485dd | 57 | .\" what the differences are between chown() and lchown() |
fea681da MK |
58 | These system calls change the owner and group of the file specified by |
59 | .I path | |
60 | or by | |
61 | .IR fd . | |
62 | Only a privileged process (Linux: one with the | |
63 | .B CAP_CHOWN | |
64 | capability) may change the owner of a file. | |
65 | The owner of a file may change the group of the file | |
66 | to any group of which that owner is a member. | |
67 | A privileged process (Linux: with | |
68 | .BR CAP_CHOWN ) | |
69 | may change the group arbitrarily. | |
70 | ||
71 | If the | |
72 | .I owner | |
73 | or | |
74 | .I group | |
75 | is specified as \-1, then that ID is not changed. | |
76 | ||
2c8d1c7d | 77 | When the owner or group of an executable file are changed by a non-superuser, |
682edefb MK |
78 | the |
79 | .B S_ISUID | |
80 | and | |
81 | .B S_ISGID | |
82 | mode bits are cleared. | |
c13182ef | 83 | POSIX does not specify whether |
fea681da | 84 | this also should happen when root does the |
e1d6264d | 85 | .BR chown (); |
d9bfdb9c | 86 | the Linux behavior depends on the kernel version. |
fea681da MK |
87 | .\" In Linux 2.0 kernels, superuser was like everyone else |
88 | .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. | |
89 | .\" Since 2.2.13, superuser is once more like everyone else. | |
eacd521c | 90 | In case of a non-group-executable file (i.e., one for which the |
682edefb | 91 | .B S_IXGRP |
eacd521c | 92 | bit is not set) the |
682edefb MK |
93 | .B S_ISGID |
94 | bit indicates mandatory locking, and is not cleared by a | |
e1d6264d | 95 | .BR chown (). |
fea681da | 96 | .SH "RETURN VALUE" |
c13182ef MK |
97 | On success, zero is returned. |
98 | On error, \-1 is returned, and | |
fea681da MK |
99 | .I errno |
100 | is set appropriately. | |
101 | .SH ERRORS | |
c13182ef MK |
102 | Depending on the file system, other errors can be returned. |
103 | The more general errors for | |
e511ffb6 | 104 | .BR chown () |
fea681da MK |
105 | are listed below. |
106 | .TP | |
107 | .B EACCES | |
108 | Search permission is denied on a component of the path prefix. | |
109 | (See also | |
ad7cc990 | 110 | .BR path_resolution (7).) |
fea681da MK |
111 | .TP |
112 | .B EFAULT | |
113 | .I path | |
114 | points outside your accessible address space. | |
115 | .TP | |
116 | .B ELOOP | |
117 | Too many symbolic links were encountered in resolving | |
118 | .IR path . | |
119 | .TP | |
120 | .B ENAMETOOLONG | |
121 | .I path | |
122 | is too long. | |
123 | .TP | |
124 | .B ENOENT | |
125 | The file does not exist. | |
126 | .TP | |
127 | .B ENOMEM | |
128 | Insufficient kernel memory was available. | |
129 | .TP | |
130 | .B ENOTDIR | |
131 | A component of the path prefix is not a directory. | |
132 | .TP | |
133 | .B EPERM | |
134 | The calling process did not have the required permissions | |
135 | (see above) to change owner and/or group. | |
136 | .TP | |
137 | .B EROFS | |
138 | The named file resides on a read-only file system. | |
139 | .PP | |
140 | The general errors for | |
e511ffb6 | 141 | .BR fchown () |
fea681da MK |
142 | are listed below: |
143 | .TP | |
144 | .B EBADF | |
145 | The descriptor is not valid. | |
146 | .TP | |
147 | .B EIO | |
148 | A low-level I/O error occurred while modifying the inode. | |
149 | .TP | |
150 | .B ENOENT | |
151 | See above. | |
152 | .TP | |
153 | .B EPERM | |
154 | See above. | |
155 | .TP | |
156 | .B EROFS | |
157 | See above. | |
a1d5f77c MK |
158 | .SH "CONFORMING TO" |
159 | 4.4BSD, SVr4, POSIX.1-2001. | |
160 | ||
161 | The 4.4BSD version can only be | |
162 | used by the superuser (that is, ordinary users cannot give away files). | |
163 | .\" chown(): | |
164 | .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no | |
165 | .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. | |
166 | .\" fchown(): | |
167 | .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK | |
168 | .\" error conditions. | |
fea681da | 169 | .SH NOTES |
b07cd0a9 MK |
170 | The |
171 | .BR chown () | |
172 | semantics are deliberately violated on NFS file systems | |
173 | which have UID mapping enabled. | |
174 | Additionally, the semantics of all system | |
175 | calls which access the file contents are violated, because | |
176 | .BR chown () | |
177 | may cause immediate access revocation on already open files. | |
178 | Client side | |
179 | caching may lead to a delay between the time where ownership have | |
180 | been changed to allow access for a user and the time where the file can | |
181 | actually be accessed by the user on other clients. | |
182 | ||
fea681da | 183 | In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), |
e511ffb6 | 184 | .BR chown () |
fea681da MK |
185 | did not follow symbolic links. |
186 | Since Linux 2.1.81, | |
e511ffb6 | 187 | .BR chown () |
fea681da | 188 | does follow symbolic links, and there is a new system call |
e511ffb6 | 189 | .BR lchown () |
fea681da MK |
190 | that does not follow symbolic links. |
191 | Since Linux 2.1.86, this new call (that has the same semantics | |
192 | as the old | |
e511ffb6 | 193 | .BR chown ()) |
fea681da | 194 | has got the same syscall number, and |
e511ffb6 | 195 | .BR chown () |
fea681da | 196 | got the newly introduced number. |
6a2df4ee MK |
197 | .SH EXAMPLE |
198 | .PP | |
199 | The following program changes the ownership of the file named in | |
200 | its second command-line argument to the value specified in its | |
1e50031b | 201 | first command-line argument. |
6a2df4ee MK |
202 | The new owner can be specified either as a numeric user ID, |
203 | or as a username (which is converted to a user ID by using | |
204 | .BR getpwnam (3) | |
205 | to perform a lookup in the system password file). | |
206 | .nf | |
207 | ||
208 | #include <pwd.h> | |
209 | #include <stdio.h> | |
210 | #include <stdlib.h> | |
211 | #include <unistd.h> | |
212 | ||
213 | int | |
214 | main(int argc, char *argv[]) | |
215 | { | |
216 | uid_t uid; | |
217 | struct passwd *pwd; | |
218 | char *endptr; | |
219 | ||
f81fb444 | 220 | if (argc != 3 || argv[1][0] == \(aq\\0\(aq) { |
6a2df4ee MK |
221 | fprintf(stderr, "%s <owner> <file>\\n", argv[0]); |
222 | exit(EXIT_FAILURE); | |
223 | } | |
224 | ||
225 | uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */ | |
226 | ||
f81fb444 | 227 | if (*endptr != \(aq\\0\(aq) { /* Was not pure numeric string */ |
0adc4176 | 228 | pwd = getpwnam(argv[1]); /* Try getting UID for username */ |
6a2df4ee MK |
229 | if (pwd == NULL) { |
230 | perror("getpwnam"); | |
231 | exit(EXIT_FAILURE); | |
232 | } | |
233 | ||
234 | uid = pwd\->pw_uid; | |
e0bf9127 | 235 | } |
6a2df4ee MK |
236 | |
237 | if (chown(argv[2], uid, \-1) == \-1) { | |
238 | perror("chown"); | |
239 | exit(EXIT_FAILURE); | |
240 | } /* if */ | |
e0bf9127 | 241 | |
6a2df4ee MK |
242 | exit(EXIT_SUCCESS); |
243 | } /* main */ | |
244 | .fi | |
fea681da MK |
245 | .SH "SEE ALSO" |
246 | .BR chmod (2), | |
22e3b8b1 | 247 | .BR fchownat (2), |
fea681da | 248 | .BR flock (2), |
ad7cc990 | 249 | .BR path_resolution (7) |