chown()--Change Owner and Group of File

 #include <unistd.h>

 int chown(const char *path, uid_t owner, gid_t group);  

The chown() function changes the owner and primary group of a file. If the named file is a symbolic link, chown() resolves the symbolic link. The permissions of the previous owner or primary group to the object are revoked.

If the file is checked out by another user (someone other than the user profile of the current job), chown() fails with the [EBUSY] error.

When chown() completes successfully, it updates the change time of the file.

Parameters

path

(Input) A pointer to the null-terminated path name of the file whose owner and group are being changed.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgChown()--Change Owner and Group of File for a description and an example of supplying the path in any CCSID.

owner

(Input) The user ID (UID) of the new owner of the file.

group

(Input) The group ID (GID) of the new primary group for the file.

The new primary group user cannot be the owner of the object.

Note: Changing the owner or the primary group causes the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of the file mode to be cleared, unless the caller has all object (*ALLOBJ) special authority. If the caller does have *ALLOBJ special authority, the bits are not changed. This does not apply to directories or FIFO special files. See the chmod() documentation.

Authorities

Note: Adopted authority is not used.

Authorization Required for chown() (excluding QSYS.LIB, independent ASP QSYS.LIB, and QDLS)

Authorization Required for chown() in the QSYS.LIB and independent ASP QSYS.LIB File Systems

Authorization Required for chown() in the QDLS File System

Authorization Required for chown() in the QOPT File System

Return Value

0

chown() was successful.

-1

chown() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If chown() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error Messages

The following messages may be sent from this API:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   chown() is not supported for member (.MBR) objects.

   
   
3. QDLS File System Differences

   The owner and primary group of the /QDLS directory (root folder) cannot be changed. If an attempt is made to change the owner and primary group, error ENOTSUP error is returned.

   
   
4. QOPT File System Differences

   Changing the owner and primary group is allowed only for an object that exists on a volume formatted in Universal Disk Format (UDF). For all other media formats, ENOTSUP will be returned.

   QOPT file system objects that have owners will not be recognized by the Work with Objects by Owner (WRKOBJOWN) CL command. Likewise, QOPT objects that have a primary group will not be recognized by the Work Objects by Primary Group) CL command.

   
   
5. QFileSvr.400 File System Differences

   The QFileSvr.400 file system does not support chown().

   
   
6. QNetWare File System Differences

   The QNetWare file system does not support primary group. The GID must be zero.

   
   
7. QNTC File System Differences

   The owner of files and directories cannot be changed. All files and directories in QNTC are owned by the QDFTOWN user profile.

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
• The <limits.h> file (see Header Files for UNIX-Type Functions)
• chmod()--Change File Authorizations
• fchown()--Change Owner and Group of File by Descriptor
• fstat()--Get File Information by Descriptor
• lstat()--Get File or Link Information
• stat()--Get File Information
• QlgChown()--Change Owner and Group of File

Example

See Code disclaimer information for information pertaining to code examples.

The following example changes the owner and group of a file:

#include <stdio.h>
#include <unistd.h>
#include <sys/stat.h>
#include <sys/types.h>

main() {
  char fn[]="temp.file";
  int file_descriptor;
  struct stat info;

  if ((file_descriptor = creat(fn, S_IRWXU)) == -1)
    perror("creat() error");
  else {
    close(file_descriptor);
    stat(fn, &info);
    printf("original owner was %d and group was %d\n", info.st_uid,
           info.st_gid);
    if (chown(fn, 152, 0) != 0)
      perror("chown() error");
    else {
      stat(fn, &info);
      printf("after chown(), owner is %d and group is %d\n",
             info.st_uid, info.st_gid);
    }
    unlink(fn);
  }
}

Output:

original owner was 137 and group was 0
after chown(), owner is 152 and group is 0