XAttr

XAttr makes working with Extended Attributes a natural part of Foundation. Both NSURL and NSFileHandle objects gain the ability to read and write extended attributes using an API that fits right in with Cocoa. Add the power of metadata to your app!

Works with iOS, macOS, watchOS and tvOS.

For more info on Darwin's extended attribute APIs – which underlie this module – see Apple's man pages for listxattr, getxattr, setxattr, and removexattr.

Here's a simple example of working with extended attributes using a file URL:

import XAttr

let myURL = URL(fileURLWithPath: "/path/to/file")

let data = "value".data(using: .utf8)!

// Set an attribute
try myURL.setExtendedAttribute(name: "com.example.attribute", value: data)
// List attributes
let names = try myURL.extendedAttributeNames()
// Get an attribute's value
let value = try myURL.extendedAttributeValue(forName: "com.example.attribute")
// Remove an attribute
try myURL.removeExtendedAttribute(forName: "com.example.attribute")

// Set multiple attributes
try myURL.setExtendedAttributes(attrs: ["com.example.attribute1": data, "com.example.attribute2": data])
// Get multiple attributes' values (all available)
let attrs = try myURL.extendedAttributeValues(forNames: nil)
// Remove multiple attributes (all)
try myURL.removeExtendedAttributes(forNames: nil)

Requires Swift 5.7.

Add XAttr as a dependency to your project:

// Package.swift

import PackageDescription

let package = Package(
    name: "YourProjectName",
    dependencies: [
        .package(url: "https://github.com/jozefizso/swift-xattr", majorVersion: 3),
    ]
)

XAttr is easy to use. This section contains the all the basic information required. Be sure to check out the Quick Help in Xcode for more detail.

The following methods are available to both URL and FileHandle objects:

extendedAttributeValue(forName: String, options: XAttrOptions = []) throws -> Data

extendedAttributeValues(forNames: [String]?, options: XAttrOptions = []) throws -> [String: Data]

Supply a list of names to retrieve, or nil to retrieve all available attributes.

setExtendedAttribute(name: String, value: Data, options: XAttrOptions = []) throws

setExtendedAttributes(attrs: [String: Data], options: XAttrOptions = []) throws

Supply a dictionary of name:value pairs to be set on the target.

extendedAttributeNames(options: XAttrOptions = []) throws -> [String]

removeExtendedAttribute(forName: String, options: XAttrOptions = []) throws

removeExtendedAttributes(forNames: [String]?, options: XAttrOptions = []) throws

Supply a list of names to remove, or nil to remove all existing attributes.

XAttrOptions provides the following options:

Note: If neither CreateOnly nor ReplaceOnly are specified, the attribute will be created/updated regardless of its current status.

An NSError will be thrown if the system is not able to get/set/list/remove an extended attribute. The error will have the Foundation built-in domain NSPOSIXErrorDomain. The error's code property will represent the POSIX error code reported by the system, and the error's localizedDescription property will contain an explanation of the error.

Additionally, if the system was able to retrieve an attribute's name, but was not able to decode it, an NSError with the Foundation built-in domain NSCocoaErrorDomain and code NSFileReadInapplicableStringEncodingError will be thrown.

Finally, if an error is encountered while getting/setting/removing multiple extended attributes, the specific attribute that caused the error will be named in the error's userInfo dictionary, at the key ExtendedAttributeNameKey.

XAttr is licensed under the permissive ISC License.
XAttr is a fork of Foundation-XAttr repository.

Copyright (c) 2016, Justin Pawela and contributors Copyright 2023 Cisco Systems, Inc.