diff options
Diffstat (limited to 'static/freebsd/man7/named_attribute.7 3.html')
| -rw-r--r-- | static/freebsd/man7/named_attribute.7 3.html | 220 |
1 files changed, 0 insertions, 220 deletions
diff --git a/static/freebsd/man7/named_attribute.7 3.html b/static/freebsd/man7/named_attribute.7 3.html deleted file mode 100644 index 7b958f9e..00000000 --- a/static/freebsd/man7/named_attribute.7 3.html +++ /dev/null @@ -1,220 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">NAMED_ATTRIBUTE(7)</td> - <td class="head-vol">Miscellaneous Information Manual</td> - <td class="head-rtitle">NAMED_ATTRIBUTE(7)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">named_attribute</code> — - <span class="Nd">Solaris-like extended attribute system interface</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Description of the system interface for named attributes (the NFS - Version 4 terminology).</p> -<section class="Ss"> -<h2 class="Ss" id="Introduction"><a class="permalink" href="#Introduction">Introduction</a></h2> -<p class="Pp">This document describes an alternate system interface for extended - attributes as compared to <a class="Xr">extattr(2)</a>. It is based on the - interface provided by Solaris and NFS Version 4.</p> -<p class="Pp">This interface associates a directory, known as a named attribute - directory, to a file system object. This directory is read in the same - manner as a normal directory via the <a class="Xr">getdents(2)</a> or - <a class="Xr">getdirentries(2)</a> system calls. The - <span class="Pa">.</span> and <span class="Pa">..</span> entries refer to - the directory itself and to the associated file object, respectively. The - other entries in this directory are the names of the extended attributes for - the associated file object and are referred to as named attributes. These - named attributes are regular files used to store the attribute's value.</p> -<p class="Pp">A named attribute directory does not live in the file system's - name space. It is accessed via an <a class="Xr">open(2)</a> or - <a class="Xr">openat(2)</a> system call done on a file to query the named - attributes for the file, with the <code class="Dv">O_NAMEDATTR</code> flag - specified and a <var class="Fa">path</var> argument of - <span class="Pa">.</span>. This file descriptor can be used as the - <var class="Fa">fd</var> argument for a variety of system calls, such as: - <a class="Xr">fchdir(2)</a>, <a class="Xr">unlinkat(2)</a> and - <a class="Xr">renameat(2)</a>. <a class="Xr">renameat(2)</a> is only - permitted to rename a named attribute within the same named attribute - directory.</p> -<p class="Pp">When a file descriptor for a file object in the file system's - namespace is used as the <var class="Fa">fd</var> argument of an - <a class="Xr">openat(2)</a> along with the <var class="Fa">flag</var> - <code class="Dv">O_NAMEDATTR</code> and a <var class="Fa">path</var> - argument that is the name of a named attribute (not - <span class="Pa">.</span> or <span class="Pa">..</span> ), a file descriptor - for the named attribute is returned. If the <var class="Fa">flag</var> - <code class="Dv">O_CREAT</code> is specified, the named attribute will be - created if it does not exist. The <var class="Fa">path</var> argument must - be a single component name, with no embedded “/” in it. I/O on - these named attribute file descriptors may be performed by standard I/O - system calls such as: <a class="Xr">read(2)</a>, <a class="Xr">write(2)</a>, - <a class="Xr">lseek(2)</a> and <a class="Xr">ftruncate(2)</a>.</p> -<p class="Pp">The <code class="Dv">_PC_NAMEDATTR_ENABLED</code> - <var class="Fa">name</var> argument to <a class="Xr">pathconf(2)</a> will - return 1 if the file system supports named attributes. The - <code class="Dv">_PC_HAS_NAMEDATTR</code> <var class="Fa">name</var> - argument to <a class="Xr">pathconf(2)</a> will return 1 if there are one or - more named attributes for the file. If an application does a - <a class="Xr">openat(2)</a> of “.” to open a named attribute - directory when no named attribute directory exists, an empty named attribute - directory will be created. Testing <code class="Dv">_PC_HAS_NAMEDATTR</code> - can be done to avoid creating these named attribute directories - unnecessarily.</p> -<p class="Pp">The named attribute interface is a different mechanism/system call - interface for manipulating extended attributes compared with - <a class="Xr">extattr(2)</a>. Although the named attribute machanism might - require different internal implementation of extended attributes within a - file system, both ZFS and NFSv4 provide both mechanisms, which can be used - interchangeably to manipulate extended attributes, but with a few - limitations.</p> -<ul class="Bl-bullet"> - <li>The <a class="Xr">extattr(2)</a> interface requires that an extended - attribute's value be set or acquired via a single system call using a - single buffer. This limits the size of the attribute's value.</li> - <li>The named attribute interface does not support system namespace extended - attributes and, as such, system namespace extended attributes must be - manipulated via <a class="Xr">extattr(2)</a>.</li> - <li>For ZFS, if an extended attribute with a value that is a small length in - bytes is created when the ZFS <code class="Dv">xattr</code> property is - set to “sa”, that extended attribute is only visible via - <a class="Xr">extattr(2)</a> and not as a named attribute. - Archiving/de-archiving the file via <a class="Xr">tar(1)</a> after setting - the <code class="Dv">xattr</code> property to “dir” will - make the attribute(s) visible as both named attributes and via - <a class="Xr">extattr(2)</a>.</li> - <li>For ZFS, it is also possible to create two attributes with the same name - by creating one when the ZFS <code class="Dv">xattr</code> property is set - to “sa” and then creating another one with the same name - after the ZFS property <code class="Dv">xattr</code> has been changed to - “dir”. The one created when the ZFS - <code class="Dv">xattr</code> property is set to “sa” may be - removed via <a class="Xr">rmextattr(8)</a>.</li> - <li>To avoid these issues for ZFS, it is strongly recommended that the ZFS - property <code class="Dv">xattr</code> be set to “dir” as - soon as the file system is created, if named attributes are to be used on - the file system.</li> -</ul> -<p class="Pp">The named attribute mechanism/system call interface provides - certain advantages over <a class="Xr">extattr(2)</a>. Since the attribute's - value is updated via <a class="Xr">read(2)</a> and - <a class="Xr">write(2)</a> system calls, the attribute's data may be as - large as any regular file and may be partially updated. (Note that this - interface does not provide the atomicity guarantee that - <a class="Xr">extattr(2)</a> does.) The permission to access a named - attribute directory is determined from the access control information for - the associated file object. However, access control information can be set - on each individual attribute in a manner similar to a regular file. This - provides “per attribute” granular control over attribute - permissions via <a class="Xr">fchown(2)</a>.</p> -<p class="Pp">At this time, the only local file system which supports this - interface is ZFS and only if the <code class="Dv">xattr</code> property is - set to “dir”. (Note that, even when “zfs get xattr - <file-system>” shows “on” the command “zfs - set xattr=dir <file-system>” must be done, followed by a - remount to make the setting take effect.) A NFSv4 mount will also support - this interface, but only if the NFSv4 server file system supports named - attributes (the openattr operation). The <span class="Ux">FreeBSD</span> - NFSv4 server supports named attributes only for ZFS exported file systems - where the “xattr” property is set to “dir” for - the file system.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<div class="Bd Li"> -<pre>#include <stdio.h> -#include <dirent.h> -#include <fcntl.h> -#include <unistd.h> - -... - -/* For a file called "myfile". Failure checks removed for brevity. */ -int file_fd, nameddir_fd, namedattr_fd; -ssize_t siz; -char buf[DIRBLKSIZ], *cp; -struct dirent *dp; -long named_enabled, has_named_attrs; - -... -/* Check to see if named attributes are supported. */ -named_enabled = pathconf("myfile", _PC_NAMEDATTR_ENABLED); -if (named_enabled <= 0) - err(1, "Named attributes not enabled"); -/* Test to see if named attribute(s) exist for the file. */ -has_named_attrs = pathconf("myfile", _PC_HAS_NAMEDATTR); -if (has_named_attrs == 1) - printf("myfile has named attribute(s)\n"); -else - printf("myfile does not have any named attributes\n"); -/* Open a named attribute directory. */ -file_fd = open("myfile", O_RDONLY, 0); -nameddir_fd = openat(file_fd, ".", O_NAMEDATTR, 0); -... -/* and read it, assuming it all fits in DIRBLKSIZ for simplicity. */ -siz = getdents(fd, buf, sizeof(buf)); -cp = buf; -while (cp < &buf[siz]) { - dp = (struct dirent *)cp; - printf("name=%s\n", dp->d_name); - cp += dp->d_reclen; -} -... -/* Open/create a named attribute called "foo". */ -namedattr_fd = openat(file_fd, "foo", O_CREAT | O_RDWR | - O_TRUNC | O_NAMEDATTR, 0600); -... -/* Write foo's attribute value. */ -write(namedattr_fd, "xxxyyy", 6); -... -/* Read foo's attribute value. */ -lseek(namedattr_fd, 0, SEEK_SET); -siz = read(namedattr_fd, buf, sizeof(buf)); -... -/* And close "foo". */ -close(namedattr_fd); -... -/* Rename "foo" to "oldfoo". */ -renameat(nameddir_fd, "foo", nameddir_fd, "oldfoo"); -/* and delete "oldfoo". */ -unlinkat(nameddir_fd, "oldfoo", AT_RESOLVE_BENEATH);</pre> -</div> -<p class="Pp">The <a class="Xr">runat(1)</a> command may be used to perform - shell commands on named attributes. For example:</p> -<div class="Bd Pp Li"> -<pre>$ runat myfile cp /etc/hosts attrhosts # creates attrhosts -$ runat myfile cat attrhosts # displays contents of attrhosts -$ runat myfile ls -l # lists the attributes for myfile</pre> -</div> -<p class="Pp">If using the <a class="Xr">bash(1)</a> shell, the command - “cd -@ foo” enters the named attribute directory for the file - object “foo”.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">bash(1)</a>, <a class="Xr">runat(1)</a>, - <a class="Xr">tar(1)</a>, <a class="Xr">chdir(2)</a>, - <a class="Xr">extattr(2)</a>, <a class="Xr">lseek(2)</a>, - <a class="Xr">open(2)</a>, <a class="Xr">pathconf(2)</a>, - <a class="Xr">read(2)</a>, <a class="Xr">rename(2)</a>, - <a class="Xr">truncate(2)</a>, <a class="Xr">unlinkat(2)</a>, - <a class="Xr">write(2)</a>, <a class="Xr">zfsprops(7)</a>, - <a class="Xr">rmextattr(8)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">This interface first appeared in <span class="Ux">FreeBSD - 15.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 5, 2025</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |