fchown()--Change Owner and Group of File by Descriptor

 #include <unistd.h>

 int fchown(int fildes, uid_t owner, gid_t group);  

The fchown() function changes the owner and group of a file. 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), fchown() fails with the [EBUSY] error.

When fchown() completes successfully, it marks the change time of the file to be updated.

Parameters

fildes

(Input) The file descriptor of the file.

owner

(Input) The new user ID to be set for file.

group

(Input) The new group ID to be set for file.

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 *ALLOBJ special authority. If the caller does have *ALLOBJ special authority, the bits are not changed. This does not apply to directories, FIFO special files, or pipes. See the chmod() documentation.

Authorities

Note: Adopted authority is not used.

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

Object Referred to	Authority Required	errno
Object, when changing the owner	See Note (1)	EPERM
Object, when changing the primary group	See Note (2)	EPERM
Note: The required authorization varies for each object type. See the following commands in the iSeries Security Reference book for details: CHGOBJOWN CHGOBJPGP

Authorization Required for fchown() in the QDLS File System

Authorization Required for fchown() in the QOPT File System

Return Value

0

fchown() was successful.

-1

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

Error Conditions

If fchown() 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 function:

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. 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, a [ENOTSUP] error is returned.

   
   
3. 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 (WRKOBJPGP) CL command.

   
   
4. QFileSvr.400 File System Differences

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

   
   
5. QNetWare File System Differences

   Primary group is not supported. The GID must be zero on this API.

   
   
6. 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)
  
• chown()--Change Owner and Group of File
  
• chmod()--Change File Authorizations
  
• fchmod()--Change File Authorizations by Descriptor
  
• mkdir()--Make Directory
  
• open()--Open File
  
• stat()--Get File Information

Example

See Code disclaimer information for information pertaining to code examples.

The following example changes the owner ID and group ID:

#include <stdio.h>
#include <fcntl.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_IWUSR)) < 0)
    perror("creat() error");
  else {
    stat(fn, &info);
    printf("original owner was %d and group was %d\n", info.st_uid,
           info.st_gid);
    if (fchown(file_descriptor, 152, 0) != 0)
      perror("fchown() error");
    else {
      stat(fn, &info);
      printf("after fchown(), owner is %d and group is %d\n",
             info.st_uid, info.st_gid);
    }
    close(file_descriptor);
    unlink(fn);
  }
}

Output:

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