# lchown

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           lchown — change the owner and group of a symbolic link
    


## SYNOPSIS



           #include <unistd.h>
    
           int lchown(const char *_path_ , uid_t _owner_ , gid_t _group_);
    


## DESCRIPTION



           The _lchown_() function shall be equivalent to _chown_(), except in
           the case where the named file is a symbolic link. In this case,
           _lchown_() shall change the ownership of the symbolic link file
           itself, while _chown_() changes the ownership of the file or
           directory to which the symbolic link refers.
    


## RETURN VALUE



           Upon successful completion, _lchown_() shall return 0. Otherwise, it
           shall return -1 and set _errno_ to indicate an error.
    


## ERRORS



           The _lchown_() function shall fail if:
    
           **EACCES** Search permission is denied on a component of the path
                  prefix of _path_.
    
           **EINVAL** The owner or group ID is not a value supported by the
                  implementation.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **ENOTDIR**
                  A component of the path prefix names an existing file that
                  is neither a directory nor a symbolic link to a directory,
                  or the _path_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters and the last pathname component names an
                  existing file that is neither a directory nor a symbolic
                  link to a directory.
    
           **EPERM** The effective user ID does not match the owner of the file
                  and the process does not have appropriate privileges.
    
           **EROFS** The file resides on a read-only file system.
    
           The _lchown_() function may fail if:
    
           **EIO** An I/O error occurred while reading or writing to the file
                  system.
    
           **EINTR** A signal was caught during execution of the function.
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           _The following sections are informative._
    


## EXAMPLES



       **Changing the Current Owner of a File**
           The following example shows how to change the ownership of the
           symbolic link named **/modules/pass1** to the user ID associated with
           ``jones'' and the group ID associated with ``cnd''.
    
           The numeric value for the user ID is obtained by using the
           _getpwnam_() function. The numeric value for the group ID is
           obtained by using the _getgrnam_() function.
    
               #include <sys/types.h>
               #include <unistd.h>
               #include <pwd.h>
               #include <grp.h>
    
               struct passwd *pwd;
               struct group  *grp;
               char          *path = "/modules/pass1";
               ...
               pwd = getpwnam("jones");
               grp = getgrnam("cnd");
               lchown(path, pwd->pw_uid, grp->gr_gid);
    


## APPLICATION USAGE



           On implementations which support symbolic links as directory
           entries rather than files, _lchown_() may fail.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *