chown(P)                                               chown(P)





NAME
       chown - change the file ownership

SYNOPSIS
       chown [-hR] owner[:group] file ...

       chown -R [-H | -L | -P ] owner[:group] file ...


DESCRIPTION
       The  chown  utility  shall  set  the user ID of the file
       named by each file operand to the user ID  specified  by
       the owner operand.

       For  each  file  operand,  or, if the -R option is used,
       each file encountered while walking the directory  trees
       specified  by the file operands, the chown utility shall
       perform  actions  equivalent  to  the  chown()  function
       defined    in    the   System   Interfaces   volume   of
       IEEE Std 1003.1-2001, called with  the  following  argu-
       ments:

       The file operand shall be used as the path argument.

       The  user ID indicated by the owner portion of the first
       operand shall be used as the owner argument.

       If the group portion of the first operand is given,  the
       group  ID  indicated  by  it  shall be used as the group
       argument; otherwise, the group ownership  shall  not  be
       changed.

       Unless  chown  is  invoked by a process with appropriate
       privileges, the set-user-ID and set-group-ID bits  of  a
       regular  file  shall  be cleared upon successful comple-
       tion; the set-user-ID and  set-group-ID  bits  of  other
       file types may be cleared.

OPTIONS
       The  chown utility shall conform to the Base Definitions
       volume of IEEE Std 1003.1-2001,  Section  12.2,  Utility
       Syntax Guidelines.

       The  following  options shall be supported by the imple-
       mentation:

       -h     If the system  supports  user  IDs  for  symbolic
              links, for each file operand that names a file of
              type symbolic link, chown shall  attempt  to  set
              the  user ID of the symbolic link.  If the system
              supports group IDs  for  symbolic  links,  and  a
              group  ID  was  specified,  for each file operand
              that names a file of type  symbolic  link,  chown
              shall attempt to set the group ID of the symbolic
              link. If the system  does  not  support  user  or
              group IDs for symbolic links, for each file oper-
              and that names a  file  of  type  symbolic  link,
              chown shall do nothing more with the current file
              and shall go on to any remaining files.

       -H     If the -R option is specified and a symbolic link
              referencing a file of type directory is specified
              on the command line, chown shall change the  user
              ID  (and group ID, if specified) of the directory
              referenced by the symbolic link and all files  in
              the file hierarchy below it.

       -L     If the -R option is specified and a symbolic link
              referencing a file of type directory is specified
              on  the  command  line  or encountered during the
              traversal of a file hierarchy, chown shall change
              the  user  ID (and group ID, if specified) of the
              directory referenced by the symbolic link and all
              files in the file hierarchy below it.

       -P     If the -R option is specified and a symbolic link
              is specified on the command line  or  encountered
              during  the  traversal of a file hierarchy, chown
              shall change the owner ID (and group ID, if spec-
              ified)  of  the  symbolic link if the system sup-
              ports this operation. The chown utility shall not
              follow the symbolic link to any other part of the
              file hierarchy.

       -R     Recursively change file user and group  IDs.  For
              each  file  operand that names a directory, chown
              shall change the user ID (and group ID, if speci-
              fied)  of the directory and all files in the file
              hierarchy below it. Unless a -H, -L, or -P option
              is  specified,  it  is unspecified which of these
              options will be used as the default.


       Specifying  more  than  one  of  the  mutually-exclusive
       options -H, -L, and -P shall not be considered an error.
       The last option specified shall determine  the  behavior
       of the utility.

OPERANDS
       The following operands shall be supported:

       owner[:group]
              A user ID and optional group ID to be assigned to
              file. The owner portion of this operand shall  be
              a  user  name from the user database or a numeric
              user ID. Either specifies a user ID  which  shall
              be  given  to  each file named by one of the file
              operands. If a numeric owner  operand  exists  in
              the  user  database  as  a user name, the user ID
              number associated with that user  name  shall  be
              used as the user ID. Similarly, if the group por-
              tion of this operand is present, it  shall  be  a
              group  name  from the group database or a numeric
              group ID. Either specifies a group ID which shall
              be given to each file. If a numeric group operand
              exists in the group database as a group name, the
              group  ID  number associated with that group name
              shall be used as the group ID.

       file   A pathname of a file whose user ID is to be modi-
              fied.


STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The  following  environment  variables  shall affect the
       execution of chown:

       LANG   Provide    a    default     value     for     the
              internationalization  variables that are unset or
              null.  (See  the  Base  Definitions   volume   of
              IEEE Std 1003.1-2001, Section 8.2, International-
              ization Variables for the precedence of  interna-
              tionalization  variables  used  to  determine the
              values of locale categories.)

       LC_ALL If set to a non-empty string value, override  the
              values  of  all  the  other  internationalization
              variables.

       LC_CTYPE
              Determine the locale for  the  interpretation  of
              sequences  of  bytes  of  text data as characters
              (for example, single-byte as  opposed  to  multi-
              byte characters in arguments).

       LC_MESSAGES
              Determine  the  locale  that  should  be  used to
              affect the format and contents of diagnostic mes-
              sages written to standard error.

       NLSPATH
              Determine  the  location  of message catalogs for
              the processing of LC_MESSAGES .


ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The standard error shall be  used  only  for  diagnostic
       messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

        0     The   utility   executed   successfully  and  all
              requested changes were made.

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       Only the owner of a file or the  user  with  appropriate
       privileges may change the owner or group of a file.

       Some implementations restrict the use of chown to a user
       with appropriate privileges.

EXAMPLES
       None.

RATIONALE
       The System V and BSD versions use different exit  status
       codes.  Some  implementations  used the exit status as a
       count of the number of errors that occurred; this  prac-
       tice  is  unworkable  since it can overflow the range of
       valid exit status values. These are masked by specifying
       only 0 and >0 as exit values.

       The  functionality  of  chown is described substantially
       through references to functions in the System Interfaces
       volume of IEEE Std 1003.1-2001. In this way, there is no
       duplication of effort required for describing the inter-
       actions of permissions, multiple groups, and so on.

       The  4.3  BSD  method of specifying both owner and group
       was included  in  this  volume  of  IEEE Std 1003.1-2001
       because:

              There  are  cases where the desired end condition
              could not be achieved using the chgrp  and  chown
              (that  only  changed  the user ID) utilities. (If
              the current owner is not a member of the  desired
              group  and  the  desired owner is not a member of
              the current group,  the  chown()  function  could
              fail  unless  both owner and group are changed at
              the same time.)

              Even if they could be changed  independently,  in
              cases  where  both  are being changed, there is a
              100% performance penalty caused by  being  forced
              to invoke both utilities.

       The  BSD  syntax  user[.  group]  was  changed to user[:
       group] in this volume  of  IEEE Std 1003.1-2001  because
       the period is a valid character in login names (as spec-
       ified   by    the    Base    Definitions    volume    of
       IEEE Std 1003.1-2001,  login names consist of characters
       in the portable filename character set). The colon char-
       acter was chosen as the replacement for the period char-
       acter because it would never be allowed as  a  character
       in  a  user name or group name on historical implementa-
       tions.

       The -R option is considered  by  some  observers  as  an
       undesirable  departure  from  the historical UNIX system
       tools approach; since a tool, find,  already  exists  to
       recurse  over  directories,  there  seemed to be no good
       reason to require other tools to have to duplicate  that
       functionality.   However,  the  -R  option was deemed an
       important user convenience, is far more  efficient  than
       forking  a  separate  process  for  each  element of the
       directory hierarchy, and  is  in  widespread  historical
       use.

FUTURE DIRECTIONS
       None.

SEE ALSO
       chmod   ,  chgrp  ,  the  System  Interfaces  volume  of
       IEEE Std 1003.1-2001, chown()

COPYRIGHT
       Portions of this text are reprinted  and  reproduced  in
       electronic  form  from  IEEE  Std  1003.1, 2003 Edition,
       Standard for Information Technology -- Portable  Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute  of  Electrical  and Electronics Engineers, Inc and
       The Open Group. In the event of any discrepancy  between
       this  version  and  the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard
       is  the  referee  document. The original Standard can be
       obtained                    online                    at
       http://www.opengroup.org/unix/online.html .



POSIX                         2003                     chown(P)
