chgrp(P)                                               chgrp(P)





NAME
       chgrp - change the file group ownership

SYNOPSIS
       chgrp [-hR] group file ...

       chgrp -R [-H | -L | -P ] group file ...


DESCRIPTION
       The  chgrp  utility  shall  set the group ID of the file
       named by each file operand to the group ID specified  by
       the group 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 chgrp 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 argu-
              ment.

              The user ID of the file  shall  be  used  as  the
              owner argument.

              The specified group ID shall be used as the group
              argument.

       Unless chgrp 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 chgrp 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  group IDs for symbolic
              links, for each file operand that names a file of
              type  symbolic  link,  chgrp shall attempt to set
              the group ID of the symbolic link instead of  the
              file referenced by the symbolic link. If the sys-
              tem does  not  support  group  IDs  for  symbolic
              links, for each file operand that names a file of
              type symbolic link, chgrp 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, chgrp shall change the group
              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, chgrp shall change
              the group of the directory referenced by the sym-
              bolic  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,  chgrp
              shall change the group ID of the symbolic link if
              the system supports  this  operation.  The  chgrp
              utility shall not follow the symbolic link to any
              other part of the file hierarchy.

       -R     Recursively change file group IDs. For each  file
              operand  that  names  a  directory,  chgrp  shall
              change the group 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:

       group  A group name from the group database or a numeric
              group ID. Either specifies a group ID to be given
              to  each  file named by one of the file operands.
              If a numeric group operand exists  in  the  group
              database  as  a  group  name, the group ID number
              associated with that group name is  used  as  the
              group ID.

       file   A pathname of a file whose group ID is to be mod-
              ified.


STDIN
       Not used.

INPUT FILES
       None.

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

       LANG   Provide a default value for the internationaliza-
              tion variables that are unset or null.  (See  the
              Base  Definitions volume of IEEE Std 1003.1-2001,
              Section 8.2, Internationalization  Variables  for
              the  precedence of internationalization variables
              used to determine  the  values  of  locale  cate-
              gories.)

       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 chgrp to a user
       with  appropriate privileges when the group specified is
       not the effective group ID or one of  the  supplementary
       group IDs of the calling process.

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. The standard developers chose
       to mask these by specifying only 0 and >0 as  exit  val-
       ues.

       The  functionality  of  chgrp is described substantially
       through references to chown(). In this way, there is  no
       duplication of effort required for describing the inter-
       actions of permissions, multiple groups, and so on.

FUTURE DIRECTIONS
       None.

SEE ALSO
       chmod() , chown() ,  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.open-
       group.org/unix/online.html .



POSIX                         2003                     chgrp(P)
