Differences between current version and predecessor to the previous major change of fchown(2).
Other diffs: Previous Revision, Previous Author, or view the Annotated Edit History
| Newer page: | version 2 | Last edited on Sunday, November 3, 2002 2:38:03 pm | by PerryLorier | |
| Older page: | version 1 | Last edited on Tuesday, June 4, 2002 12:23:40 am | by perry | Revert |
@@ -1,207 +1,95 @@
-CHOWN
-!!!CHOWN
-NAME
-SYNOPSIS
-DESCRIPTION
-RETURN VALUE
-ERRORS
-NOTES
-CONFORMING TO
-RESTRICTIONS
-SEE ALSO
-----
!!NAME
-
-
-chown,
fchown, lchown
- change ownership of a file
+fchown - change ownership of a file
!!SYNOPSIS
+ __#include <sys/types.h>__ /* For uid_t and gid_t */
+ __#include <unistd.h>__ /* for fchown prototype */
-__#include
__
-#include
__
+
__int fchown(int
__ ''fd''__, uid_t__ ''owner''__, gid_t__ ''group''__);
__
-
-__int chown(const char *__''path''__, uid_t__
-''owner''__, gid_t__ ''group''__);
-int fchown(int__ ''fd''__, uid_t__ ''owner''__,
-gid_t__ ''group''__);
-int lchown(const char *__''path''__, uid_t__
-''owner''__, gid_t__
-''group''__);__
!!DESCRIPTION
-
-
-''path'' or by
-
-
-
+The owner of the file specified by ''fd'' is changed. Only the super-user may change the owner of a file. The owner of a file may change the group of the file to any group of which that owner is a member. The
super-user may change the group arbitrarily.
+If the ''owner'' or ''group'' is specified as -1, then that ID is not changed.
-If
the ''
owner''
or ''group
'' is specified as
-1
, then
-that ID
is not changed
.
+When
the owner or group of an executable file are changed by a non-super-user, the S_ISUID and S_ISGID mode bits are cleared. POSIX does not specify whether this also should happen when root does the
''chown
''; the Linux behaviour depends on the kernel version. In case of a non
-group-executable file (with clear S_IXGRP bit) the S_ISGID bit indicates mandatory locking
, and
is not cleared by a ''chown''
.
-
-When the owner or group of an executable file are changed by
-a non-super-user, the S_ISUID and S_ISGID mode bits are
-cleared. POSIX does not specify whether this also should
-happen when root does the ''chown''; the Linux behaviour
-depends on the kernel version. In case of a
-non-group-executable file (with clear S_IXGRP bit) the
-S_ISGID bit indicates mandatory locking, and is not cleared
-by a ''chown''.
!!RETURN VALUE
+On success, zero is returned. On error, -1 is returned, and ''errno'' is set appropriately.
-
-On success, zero is returned. On error, -1 is returned, and
-''errno'' is set appropriately.
!!ERRORS
-
-
Depending on the file system, other errors can be returned.
-The more general errors for __chown__ are listed
-below:
+;[EPERM]: The effective UID does not match the owner of the file, and is not zero; or the ''owner'' or ''group'' were specified incorrectly.
+;[EROFS]: The named file resides on a read-only file system.
+;[ENOMEM]: Insufficient kernel memory was available.
+;[EBADF]: The descriptor is not valid.
+;[ENOENT]: See above.
+;[EIO]: A low-level I/O error occurred while modifying the inode.
-__EPERM__
-
-
-The effective UID does not match the owner of the file, and
-is not zero; or the ''owner'' or ''group'' were
-specified incorrectly.
-
-
-__EROFS__
-
-
-The named file resides on a read-only file
-system.
-
-
-__EFAULT__
-
-
-''path'' points outside your accessible address
-space.
-
-
-__ENAMETOOLONG__
-
-
-''path'' is too long.
-
-
-__ENOENT__
-
-
-The file does not exist.
-
-
-__ENOMEM__
-
-
-Insufficient kernel memory was available.
-
-
-__ENOTDIR__
-
-
-A component of the path prefix is not a
-directory.
-
-
-__EACCES__
-
-
-Search permission is denied on a component of the path
-prefix.
-
-
-__ELOOP__
-
-
-Too many symbolic links were encountered in resolving
-''path''.
-
-
-The general errors for __fchown__ are listed
-below:
-
-
-__EBADF__
-
-
-The descriptor is not valid.
-
-
-__ENOENT__
-
-
-See above.
-
-
-__EPERM__
-
-
-See above.
-
-
-__EROFS__
-
-
-See above.
-
-
-__EIO__
-
-
-A low-level I/O error occurred while modifying the
-inode.
!!NOTES
+The prototype for __fchown__ is only available if ___BSD_SOURCE__ is defined (either explicitly, or implicitly, by not defining _POSIX_SOURCE or compiling with the -ansi flag).
+!!CONFORMING TO
+The __fchown__ call conforms to 4.4BSD and SVr4. SVr4 documents additional [EINVAL], [EIO], [EINTR], and [ENOLINK] error conditions.
-In versions of Linux prior to 2.1.81
(and distinct from
-.1.46
), __chown__ did not follow symbolic links. Since
-Linux 2.1
.81
, __chown__ does follow symbolic links, and
-there is a new
system call __lchown__ that does not
-follow symbolic links. Since Linux 2.1.86
, this new call
-that has the same semantics as the old __chown__
) has
-got
the same syscall number,
and __chown__ got
the newly
-introduced number
.
+!!RESTRICTIONS
+The fchown
(2) semantics are deliberately violated on NFS file systems which have UID mapping enabled
. Additionally
, the semantics of all
system calls which access the file contents are violated
, because fchown
(2
) may
+cause immediate access revocation on already open files. Client side caching may lead to a delay between
the time where ownership have been changed to allow access for a user
and the time where the file can actually be accessed by the user on other clients
.
+!!EXAMPLE
+ /*
+ * This program creates a file, and uses fchown to change it's ownership.
+ *
+ * This program will fail with an error unless run as root.
+ */
-The prototype
for __fchown__ is only available if
-___BSD_SOURCE__ is defined
(either explicitly, or
-implicitly, by not defining _POSIX_SOURCE or compiling with
-the -ansi flag
).
-!!CONFORMING TO
+ #include <sys/stat.h> /*
for S
_* constants */
+ #include <sys/types.h> /* for mode
_t for creat
(2) */
+ #include <unistd.h> /* for fchown(2) prototype */
+ #include <string.h> /* for strerror(3
) prototype */
+ #include <fcntl
.h> /* for creat(2) prototype */
+ #include <stdio.h> /* for fprintf(3),stderr protype */
+ #include <errno.h> /* for errno prototype */
+ #define FILENAME "/tmp/fchown.example"
+ #define UID 100
+ #define GID 100
-The __chown__ call conforms to SVr4, SVID, POSIX, X/OPEN.
-The 4.4BSD version can only be used by the superuser
(that
-is
, ordinary users cannot give away files
). SVr4 documents
-EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no ENOMEM.
-POSIX.1 does not document ENOMEM or ELOOP error
-conditions.
+ int main
(int argc
,char **argv
)
+ {
+ int fd;
+ fd = creat(FILENAME,S_IRUSR|S_IWUSR);
+ if (fd<0) {
+ fprintf(
+ stderr,
+ "creat(\"%s\",S_IRUSR|S_IWUSR): %s (%i)\n",
+ FILENAME,
+ strerror(errno),
+ errno);
+ return 1;
+ }
+ if (fchown(fd,UID,GID)==-1) {
+ fprintf(
+ stderr,
+ "fchown(fd,%i,%i): %s (%i)\n",
+ UID,
+ GID,
+ strerror(errno),
+ errno);
+ return 1;
+ }
+ close(fd);
+ printf(
+ "%s successfully changed to uid=%i, gid=%i\n",
+ FILENAME,
+ UID,
+ GID);
+ return 0;
+ }
-The __fchown__ call conforms to 4.4BSD and SVr4. SVr4
-documents additional EINVAL, EIO, EINTR, and ENOLINK error
-conditions.
-!!RESTRICTIONS
-
-The __chown__() semantics are deliberately violated on
-NFS file systems which have UID mapping enabled.
-Additionally, the semantics of all system calls which access
-the file contents are violated, because __chown__() may
-cause immediate access revocation on already open files.
-Client side caching may lead to a delay between the time
-where ownership have been changed to allow access for a user
-and the time where the file can actually be accessed by the
-user on other clients.
!!SEE ALSO
-
-
-
-----
+chown(2), lchown(2),
chmod(2), flock(2)
