lchown()--Change Owner and Group of Symbolic Link

 #include <unistd.h>

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

The lchown() function changes the owner and group of a file. If the named file is a symbolic link, lchown() changes the owner or group of the link itself rather than the object to which the link points. 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), lchown() fails with the [EBUSY] error.

When lchown() 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 QlgLchown()--Change Owner and Group of Symbolic Link 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. If the value is -1, the user ID is not changed.

group

(Input) The group ID (GID) of the new group for the file. If the value is -1, the group ID is not changed.

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. See the chmod() documentation.

Authorities

Note: Adopted authority is not used.

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

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

Authorization Required for lchown() in the QDLS File System

Authorization Required for lchown() in the QOPT File System

Return Value

0

lchown() was successful.

-1

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

Error Conditions

If lchown() 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. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   lchown() 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, a [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 (WRKOBJPGP) CL command.

   
   
5. QFileSvr.400 File System Differences

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

   
   
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 APIs )
  
• The <limits.h> file
  
• 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
  
• QlgLchown()--Change Owner and Group of Symbolic Link

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 link_name[]="temp.link";
  char fn[]="temp.file";
  struct stat info;

  if (symlink(fn, link_name) == -1)
    perror("symlink() error");
  else {
    lstat(link_name, &info);
    printf("original owner was %d and group was %d\n", info.st_uid,
           info.st_gid);
    if (lchown(link_name, 152, 0) != 0)
      perror("lchown() error");
    else {
      lstat(link_name, &info);
      printf("after lchown(), owner is %d and group is %d\n",
             info.st_uid, info.st_gid);
    }
    unlink(link_name);
  }
}