bsd/man/man2/chown.2

   1 .\"     $OpenBSD: chown.2,v 1.3 1997/01/26 05:10:33 downsj Exp $
   2 .\"     $NetBSD: chown.2,v 1.10 1995/10/12 15:40:47 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1980, 1991, 1993, 1994
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)chown.2     8.4 (Berkeley) 4/19/94
  36 .\"
  37 .Dd January 25, 1997
  38 .Dt CHOWN 2
  39 .Os
  40 .Sh NAME
  41 .Nm chown ,
  42 .Nm fchown
  43 .Nd change owner and group of a file or link
  44 .Sh SYNOPSIS
  45 .Fd #include <sys/types.h>
  46 .Fd #include <unistd.h>
  47 .Ft int
  48 .Fn chown "const char *path" "uid_t owner" "gid_t group"
  49 .Ft int
  50 .Fn fchown "int fd" "uid_t owner" "gid_t group"
  51 .Sh DESCRIPTION
  52 The owner ID and group ID of the file (or link)
  53 named by
  54 .Fa path
  55 or referenced by
  56 .Fa fd
  57 is changed as specified by the arguments
  58 .Fa owner
  59 and
  60 .Fa group .
  61 The owner of a file may change the
  62 .Fa group
  63 to a group of which
  64 he or she is a member,
  65 but the change
  66 .Fa owner
  67 capability is restricted to the super-user.
  68 .Pp
  69 .Fn Chown
  70 clears the set-user-id and set-group-id bits
  71 on the file
  72 to prevent accidental or mischievous creation of
  73 set-user-id and set-group-id programs.
  74 .Pp
  75 .Fn Fchown
  76 is particularly useful when used in conjunction
  77 with the file locking primitives (see
  78 .Xr flock 2 ) .
  79 .Pp
  80 One of the owner or group id's
  81 may be left unchanged by specifying it as -1.
  82 .Sh RETURN VALUES
  83 Zero is returned if the operation was successful;
  84 -1 is returned if an error occurs, with a more specific
  85 error code being placed in the global variable
  86 .Va errno .
  87 .Sh ERRORS
  88 .Fn Chown
  89 will fail and the file or link will be unchanged if:
  90 .Bl -tag -width Er
  91 .It Bq Er ENOTDIR
  92 A component of the path prefix is not a directory.
  93 .It Bq Er ENAMETOOLONG
  94 A component of a pathname exceeded
  95 .Dv {NAME_MAX}
  96 characters, or an entire path name exceeded
  97 .Dv {PATH_MAX}
  98 characters.
  99 .It Bq Er ENOENT
 100 The named file does not exist.
 101 .It Bq Er EACCES
 102 Search permission is denied for a component of the path prefix.
 103 .It Bq Er ELOOP
 104 Too many symbolic links were encountered in translating the pathname.
 105 .It Bq Er EPERM
 106 The effective user ID is not the super-user.
 107 .It Bq Er EROFS
 108 The named file resides on a read-only file system.
 109 .It Bq Er EFAULT
 110 .Fa Path
 111 points outside the process's allocated address space.
 112 .It Bq Er EIO
 113 An I/O error occurred while reading from or writing to the file system.
 114 .El
 115 .Pp
 116 .Fn Fchown
 117 will fail if:
 118 .Bl -tag -width Er
 119 .It Bq Er EBADF
 120 .Fa fd
 121 does not refer to a valid descriptor.
 122 .It Bq Er EINVAL
 123 .Fa fd
 124 refers to a socket, not a file.
 125 .It Bq Er EPERM
 126 The effective user ID is not the super-user.
 127 .It Bq Er EROFS
 128 The named file resides on a read-only file system.
 129 .It Bq Er EIO
 130 An I/O error occurred while reading from or writing to the file system.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr chown 8 ,
 134 .Xr chgrp 1 ,
 135 .Xr chmod 2 ,
 136 .Xr flock 2
 137 .Sh STANDARDS
 138 The
 139 .Fn chown
 140 function is expected to conform to
 141 .St -p1003.1-88 .
 142 .Sh HISTORY
 143 The
 144 .Fn fchown
 145 function call appeared in
 146 .Bx 4.2 .
 147 .Pp
 148 The
 149 .Fn chown
 150 and
 151 .Fn fchown
 152 functions were changed to follow symbolic links in
 153 .Bx 4.4 .