__lchattr(), __lchattr64() — Change the attributes of a file or directory when they point to a symbolic or external link

Standards

Standards / Extensions C or C++ Dependencies
z/OS® UNIX
 both z/OS V1R5

Format

__lchattr:
#define _OPEN_SYS_FILE_EXT 1
#include <sys/stat.h>

int __lchattr (char *pathname, attrib_t *attributes, int attributes_len);
__lchattr64:
#define _LARGE_TIME_API 
#define _OPEN_SYS_FILE_EXT 1
#include <sys/stat.h>

int __lchattr64(char *pathname, attrib64_t *attributes, int attributes_len);

Compile requirement: Use of the __lchattr64 function requires the long long data type. For more information on how to make the long long data type available, see z/OS XL C/C++ Language Reference.

General description

The __lchattr() function modifies the attributes that are associated with a file. The pathname specifies a symbolic or external link (a pointer to another file, directory, or data set).

The __lchattr() service changes the attributes of the symbolic link itself, provided the attributes requested can apply to a symbolic link. Only the owner and security label can be changed for a symbolic link, all other attributes do not apply and will be ignored.

The attributes argument is the address of an attrib_t structure which is used to identify the attributes to be modified and the new values desired. The attrib_t type is an f_attributes structure as defined in <sys/stat.h> for use with the __lchattr() function. For proper behavior, the user should ensure that this structure has been initialized to zeros before it is populated. The f_attributes structure is defined as indicated in Table 1.

The __lchattr64() function behaves exactly like __lchattr() except __lchattr64() uses struct attrib64_t instead of struct attrib_t to support time beyond 03:14:07 UTC on January 19, 2038.

The attrib64_t type is an f_attributes64 structure as defined in <sys/stat.h> for use with the __lchattr64() function.

Returned value

If successful, __lchattr() returns 0.

If unsuccessful, __lchattr() returns -1 and sets errno to one of the following values:
EACCES
The calling process did not have appropriate permissions. Possible reasons include:
  • The calling process was attempting to set access time or modification time to current time, and the effective UID of the calling process does not match the owner of the file; the process does not have write permission for the file; or the process does not have appropriate privileges.
  • The calling process was attempting to truncate the file, and it does not have write permission for the file.
EFBIG
The calling process was attempting to change the size of a file, but the specified length is greater than the maximum file size limit for the process.
EINVAL
The attributes structure containing the requested changes is not valid.
ELOOP
A loop exists in symbolic links that were encountered during resolution of the pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of pathname.
ENAMETOOLONG
pathname is longer than 1023 characters, or a component of the pathname is longer than 255 characters (Filename truncation is not supported).
ENOENT
No file named pathname was found.
ENOTDIR
Some component of pathname is not a directory.
EPERM
The operation is not permitted for one of the following reasons:
  • The calling process was attempting to change the mode or the file format, but the effective UID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges.
  • The calling process was attempting to change the owner, but it does not have appropriate privileges.
  • The calling process was attempting to change the general attribute bits, but it does not have write permission for the file.
  • The calling process was attempting to set a time value (not current time), but the effective user ID does not match the owner of the file, and it does not have appropriate privileges.
  • The calling process was attempting to set the change time or reference time to current time, but it does not have write permission for the file.
  • The calling process was attempting to change auditing flags, but the effective UID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges.
  • The calling process was attempting to change the Security Auditor's auditing flags, but the user does not have auditor authority.
  • Attributes indicate that the security label is to be set, and one or more of the following conditions applies:
    • The calling process does not have RACF® SPECIAL authorization and appropriate privileges.
    • The security label currently associated with the file is already set.
EROFS
pathname specifies a file that is on a read-only file system.

Related information