1LCHOWN(3P)                 POSIX Programmer's Manual                LCHOWN(3P)
2
3
4

PROLOG

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

NAME

12       lchown - change the owner and group of a symbolic link
13

SYNOPSIS

15       #include <unistd.h>
16
17       int lchown(const char *path, uid_t owner, gid_t group);
18
19

DESCRIPTION

21       The lchown() function shall be equivalent to  chown(),  except  in  the
22       case  where  the  named file is a symbolic link. In this case, lchown()
23       shall change the ownership of the  symbolic  link  file  itself,  while
24       chown()  changes  the  ownership  of the file or directory to which the
25       symbolic link refers.
26

RETURN VALUE

28       Upon successful completion, lchown()  shall  return  0.  Otherwise,  it
29       shall return -1 and set errno to indicate an error.
30

ERRORS

32       The lchown() function shall fail if:
33
34       EACCES Search permission is denied on a component of the path prefix of
35              path.
36
37       EINVAL The owner or group ID is not a value supported by the  implemen‐
38              tation.
39
40       ELOOP  A loop exists in symbolic links encountered during resolution of
41              the path argument.
42
43       ENAMETOOLONG
44              The length of a pathname exceeds {PATH_MAX} or a pathname compo‐
45              nent is longer than {NAME_MAX}.
46
47       ENOENT A component of path does not name an existing file or path is an
48              empty string.
49
50       ENOTDIR
51              A component of the path prefix of path is not a directory.
52
53       EOPNOTSUPP
54              The path argument names a symbolic link and  the  implementation
55              does not support setting the owner or group of a symbolic link.
56
57       EPERM  The  effective  user ID does not match the owner of the file and
58              the process does not have appropriate privileges.
59
60       EROFS  The file resides on a read-only file system.
61
62
63       The lchown() function may fail if:
64
65       EIO    An I/O error occurred while reading or writing to the file  sys‐
66              tem.
67
68       EINTR  A signal was caught during execution of the function.
69
70       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
71              resolution of the path argument.
72
73       ENAMETOOLONG
74              Pathname resolution of a symbolic link produced an  intermediate
75              result whose length exceeds {PATH_MAX}.
76
77
78       The following sections are informative.
79

EXAMPLES

81   Changing the Current Owner of a File
82       The following example shows how to change the ownership of the symbolic
83       link named /modules/pass1 to the user ID associated  with  "jones"  and
84       the group ID associated with "cnd".
85
86       The  numeric  value for the user ID is obtained by using the getpwnam()
87       function.  The numeric value for the group ID is obtained by using  the
88       getgrnam() function.
89
90
91              #include <sys/types.h>
92              #include <unistd.h>
93              #include <pwd.h>
94              #include <grp.h>
95
96
97              struct passwd *pwd;
98              struct group  *grp;
99              char          *path = "/modules/pass1";
100              ...
101              pwd = getpwnam("jones");
102              grp = getgrnam("cnd");
103              lchown(path, pwd->pw_uid, grp->gr_gid);
104

APPLICATION USAGE

106       On  implementations  which  support symbolic links as directory entries
107       rather than files, lchown() may fail.
108

RATIONALE

110       None.
111

FUTURE DIRECTIONS

113       None.
114

SEE ALSO

116       chown(),    symlink(),    the    Base     Definitions     volume     of
117       IEEE Std 1003.1-2001, <unistd.h>
118

120       Portions  of  this text are reprinted and reproduced in electronic form
121       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
122       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
123       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
124       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
125       event of any discrepancy between this version and the original IEEE and
126       The  Open Group Standard, the original IEEE and The Open Group Standard
127       is the referee document. The original Standard can be  obtained  online
128       at http://www.opengroup.org/unix/online.html .
129
130
131
132IEEE/The Open Group                  2003                           LCHOWN(3P)
Impressum