xattr

Last updated 23 days ago

Get and manipulate extended attributes for files and directories

This submodule provides functions for getting and setting the extended attributes for files and directories. Access to extended attributes is provided through the Darwin xattr functions defined in the /usr/include/sys/xattr.h header. Attribute names are expected to conform to proper UTF-8 strings and values are represented as raw data -- in Lua raw data is presented as bytes in a string object but the bytes are not required to conform to peroper UTF-8 byte code sequences. This module does not perform any encoding or decoding of the raw data.

All of the functions provided by this module can take an options table. Note that not all options are valid for all functions. The options table should be a Lua table containing an array of zero or more of the following strings:

  • "noFollow" - do not follow symbolic links; this can be used to access the attributes of the link itself.

  • "hfsCompression" - access HFS Plus Compression extended attributes for the file or directory, if present

  • "createOnly" - when setting an attribute value, fail if the attribute already exists

  • "replaceOnly" - when setting an attribute value, fail if the attribute does not already exist

Note that the following options did not seem to be valid for the initial tests performed when developing this module and may refer the kernel level features not available to Hammerspoon; they are included here for full compatibility with the library as defined in its header. If you have more information about these options or can provide examples or documentation about their use, please submit an issue to the Hammerspoon github repository so we can provide better documentation here.

  • "noSecurity" - bypass authorization checking

  • "noDefault" - bypass the default extended attribute file (dot-underscore file)

API Overview

API Documentation

Functions

get

Signature

`hs.fs.xattr.get(path, attribute, [options], [position]) -> string

true

nil` </span>

Type

Function

Description

Set the extended attribute to the value provided for the path specified.

Parameters

Returns

Signature

`hs.fs.xattr.getHumanReadable(path, attribute, [options], [position]) -> string

true

nil` </span>

Type

Function

Description

A wrapper to hs.fs.xattr.get which returns non UTF-8 data as a hexadecimal dump provided by hs.utf8.hexDump.

Parameters

Returns

Notes

list

Signature

hs.fs.xattr.list(path, [options]) -> table

Type

Function

Description

Returns a list of the extended attributes currently defined for the specified file or directory

Parameters

Returns

remove

Signature

hs.fs.xattr.remove(path, attribute, [options]) -> boolean

Type

Function

Description

Removes the specified extended attribute from the file or directory at the path specified.

Parameters

Returns

set

Signature

hs.fs.xattr.set(path, attribute, value, [options], [position]) -> boolean

Type

Function

Description

Set the extended attribute to the value provided for the path specified.

Parameters

Returns