---
name: "setxattr"
section: "2"
platform: "macos"
package: "xnu"
version: "12377.121.6"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/setxattr"
---

# setxattr(2)

set an extended attribute value

## NAME

**setxattr,** **fsetxattr** – set an extended attribute value

## SYNOPSIS

**#include \<sys/xattr.h\>**

*int*\

**setxattr**(*const char \*path*, *const char \*name*, *void \*value*, *size\_t size*, *u\_int32\_t position*, *int options*);

*int*\

**fsetxattr**(*int fd*, *const char \*name*, *void \*value*, *size\_t size*, *u\_int32\_t position*, *int options*);

## DESCRIPTION

Extended attributes extend the basic attributes associated with files and directories in the file system.  They are stored as name:data pairs associated with file system objects (files, directories, symlinks, etc).

**setxattr**() associates *name* and *data* together as an attribute of *path*.

An extended attribute's *name* is a simple NULL-terminated UTF-8 string. *Value* is a pointer to a data buffer of *size* bytes containing textual or binary data to be associated with the extended attribute. *Position* specifies the offset within the extended attribute.  In the current implementation, only the resource fork extended attribute makes use of this argument.  For all others, *position* is reserved and should be set to zero.

*options* controls how the attribute is set:

- XATTR\_NOFOLLOW

  do not follow symbolic links. **setxattr**() normally sets attributes on the target of *path* if it is a symbolic link. With this option, **setxattr**() will act on the link itself.

- XATTR\_NOFOLLOW\_ANY

  do not follow any symbolic links encountered during pathname resolution. An error is returned if a symlink is encountered before the last component of path.

- XATTR\_RESOLVE\_BENEATH

  If *path* does not reside in the hierarchy beneath the starting directory, an error is returned.

- XATTR\_CREATE

  fail if the named attribute already exists.

- XATTR\_REPLACE

  fail if the named attribute does not exist.  Failure to specify XATTR\_REPLACE or XATTR\_CREATE allows creation and replacement.

**fsetxattr**() is identical to **setxattr**(), except that it sets an extended attribute on an open file referenced by file descriptor *fd*.

## NOTES

On some filesystems, such as HFS+, setting the extended attribute com.apple.ResourceFork will update the modification time (\`\`mtime'') of the file.

Due to historical reasons, the XATTR\_FINDERINFO\_NAME (defined to be  “com.apple.FinderInfo”) extended attribute must be 32 bytes; see the ATTR\_CMN\_FNDRINFO section in [getattrlist(2)](/getattrlist/2.md).

The maximum supported size of extended attribute can be found out using  [pathconf(2)](/pathconf/2.md) with \_PC\_XATTR\_SIZE\_BITS option.

## RETURN VALUES

On success, 0 is returned.  On failure, -1 is returned and the global variable *errno* is set as follows.

## ERRORS

- \[EEXIST\]

  *options* contains *XATTR\_CREATE* and the named attribute already exists.

- \[ENOATTR\]

  *options* is set to *XATTR\_REPLACE* and the named attribute does not exist.

- \[ENOTSUP\]

  The file system does not support extended attributes or has them disabled.

- \[EROFS\]

  The file system is mounted read-only.

- \[ERANGE\]

  The data size of the attribute is out of range (some attributes have size restrictions).

- \[EPERM\]

  Attributes cannot be associated with this type of object.  For example, attributes are not allowed for resource forks.

- \[EINVAL\]

  *name* or *options* is invalid. *name* must be valid UTF-8 and *options* must make sense.

- \[EINVAL\]

  XATTR\_NOFOLLOW, XATTR\_NOFOLLOW\_ANY or XATTR\_RESOLVE\_BENEATH option was passed in **fsetxattr**().

- \[ENOTDIR\]

  A component of *path* is not a directory.

- \[ENAMETOOLONG\]

  *name* exceeded XATTR\_MAXNAMELEN UTF-8 bytes, or a component of *path* exceeded NAME\_MAX characters, or the entire *path* exceeded PATH\_MAX characters.

- \[EACCES\]

  Search permission is denied for a component of *path* or permission to set the attribute is denied.

- \[ELOOP\]

  Too many symbolic links were encountered resolving *path*.

- \[ELOOP\]

  If XATTR\_NOFOLLOW\_ANY option was passed and a symbolic link was encountered in translating the pathname.

- \[ENOTCAPABLE\]

  If XATTR\_RESOLVE\_BENEATH was passed and *path* does not reside in the directory hierarchy beneath the starting directory.

- \[EFAULT\]

  *path* or *name* points to an invalid address.

- \[EIO\]

  An I/O error occurred while reading from or writing to the file system.

- \[E2BIG\]

  The data size of the extended attribute is too large.

- \[ENOSPC\]

  Not enough space left on the file system.

## SEE ALSO

[getxattr(2)](/getxattr/2.md), [listxattr(2)](/listxattr/2.md), [removexattr(2)](/removexattr/2.md), [pathconf(2)](/pathconf/2.md)

## HISTORY

**setxattr**() and **fsetxattr**() first appeared in Mac OS X 10.4.