319 lines
6.9 KiB
Groff
319 lines
6.9 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.attr_list @(#)attr_list 1.1 of 6/12/95
|
|
.TH ATTR_LIST 2
|
|
.SH NAME
|
|
attr_list, attr_listf \- list the names of the user attributes of a filesystem object
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.PP
|
|
.sp
|
|
.nf
|
|
.B #include <sys/attributes.h>
|
|
.sp
|
|
.B "int attr_list (const char \(**path, char \(**buffer, "
|
|
.B " const int buffersize, int flags,"
|
|
.B " attrlist_cursor_t \(**cursor);"
|
|
.PP
|
|
.B "int attr_listf (int fd, char \(**buffer, "
|
|
.B " const int buffersize, int flags,"
|
|
.B " attrlist_cursor_t \(**cursor);"
|
|
.Op
|
|
.SH OVERVIEW
|
|
The
|
|
.I attr
|
|
group of system calls implement the ability for a user to attach
|
|
name/value pairs to objects within the filesystem.
|
|
.P
|
|
They could be used to store meta-information about the file.
|
|
For example "character-set=kanji" could tell a document browser to
|
|
use the Kanji character set when displaying that document
|
|
and "thumbnail=..." could provide a reduced resolution overview of a
|
|
high resolution graphic image.
|
|
.P
|
|
The
|
|
.I names
|
|
can be up to MAXNAMELEN bytes in length, terminated by the first 0 byte.
|
|
The intent is that they be printable ASCII (or other character set)
|
|
names for the attribute.
|
|
.P
|
|
The
|
|
.I values
|
|
can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary binary data.
|
|
.P
|
|
Attributes can be attached to all types of inodes:
|
|
regular files, directories, symbolic links, device nodes, etc.
|
|
.P
|
|
There are 2 disjoint attribute name spaces associated with every
|
|
filesystem object.
|
|
They are the
|
|
.B root
|
|
and
|
|
.B user
|
|
address spaces.
|
|
The
|
|
.B root
|
|
address space is accessable only to the super-user,
|
|
and then only by specifying a flag argument to the function call.
|
|
Other users will not see or be able to modify attributes in the
|
|
.B root
|
|
address space.
|
|
The
|
|
.B user
|
|
address space is protected by the normal file permissions mechanism,
|
|
so the owner of the file can decide who is able to see and/or modify
|
|
the value of attributes on any particular file.
|
|
.P
|
|
Attributes are currently supported only in the XFS filesystem type.
|
|
.SH DESCRIPTION
|
|
The
|
|
.I attr_list
|
|
and
|
|
.I attr_listf
|
|
functions provide a way to list the existing attributes of a
|
|
filesystem object.
|
|
.P
|
|
.I Path\^
|
|
points to a path name for a filesystem object, and
|
|
.I fd\^
|
|
refers to the file descriptor associated with a file.
|
|
The
|
|
.I buffer
|
|
will be filled with a structure describing at least a portion of the
|
|
attributes associated with the given filesystem object.
|
|
.I Buffer
|
|
will be overwritten with an \f4attrlist_t\fP structure
|
|
containing a list of the attributes associated with
|
|
that filesystem object, up to a maximum of
|
|
.I buffersize
|
|
bytes.
|
|
The
|
|
.I buffer
|
|
must be sufficiently large to hold the appropriate data structures
|
|
plus at least one maximally sized attribute name,
|
|
but cannot be more than ATTR_MAX_VALUELEN (currently 64KB) bytes in length.
|
|
.PP
|
|
.Op c p a
|
|
The contents of an \f4attrlist_t\fP structure include the following members:
|
|
.P
|
|
.RS 3
|
|
.nf
|
|
.ft 4
|
|
.ta 9n 22n
|
|
__int32_t al_count; /\(** number of entries in attrlist \(**/
|
|
__int32_t al_more; /\(** T/F: more attrs (do syscall again) \(**/
|
|
__int32_t al_offset[1]; /\(** byte offsets of attrs [var-sized] \(**/
|
|
.ft 1
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The
|
|
.I al_count
|
|
field shows the number of attributes represented in this buffer,
|
|
which is also the number of elements in the
|
|
.I al_offset
|
|
array.
|
|
The
|
|
.I al_more
|
|
field will be non-zero if another
|
|
.I attr_list
|
|
call would result in more attributes.
|
|
The
|
|
.I al_offset
|
|
array contains the byte offset within the
|
|
.I buffer
|
|
of the structure describing each of the attributes,
|
|
an \f4attrlist_ent_t\fP structure.
|
|
The \f4ATTR_ENTRY(buffer, index)\fP macro will help with decoding the list.
|
|
It takes a pointer to the
|
|
.I buffer
|
|
and an
|
|
.I index
|
|
into the
|
|
.I al_offset
|
|
array and returns a pointer to the corresponding
|
|
\f4attrlist_ent_t\fP structure.
|
|
.PP
|
|
The contents of an \f4attrlist_ent_t\fP structure
|
|
include the following members:
|
|
.P
|
|
.RS 3
|
|
.nf
|
|
.ft 4
|
|
.ta 9n 22n
|
|
u_int32_t a_valuelen; /\(** number bytes in value of attr \(**/
|
|
char a_name[]; /\(** attr name (NULL terminated) \(**/
|
|
.ft 1
|
|
.fi
|
|
.Op
|
|
.RE
|
|
.PP
|
|
The
|
|
.I a_valuelen
|
|
field shows the size in bytes of the value
|
|
associated with the attribute whose name is stored in the
|
|
.I a_name
|
|
field.
|
|
The name is a NULL terminated string.
|
|
.PP
|
|
Note that the value of the attribute cannot be obtained through
|
|
this interface, the
|
|
.I attr_get
|
|
call should be used to get the value.
|
|
The
|
|
.I attr_list
|
|
interface tells the calling process how large of a buffer
|
|
it must have in order to get the attribute\'s value.
|
|
.PP
|
|
The
|
|
.I flags
|
|
argument can contain the following symbols bitwise OR\'ed together:
|
|
.TP
|
|
.SM
|
|
\%ATTR_ROOT
|
|
List the attributes that are in the
|
|
.B root
|
|
address space, not in the
|
|
.B user
|
|
address space.
|
|
(limited to use by super-user only)
|
|
.TP
|
|
.SM
|
|
\%ATTR_DONTFOLLOW
|
|
Do not follow symbolic links when resolving a
|
|
.I path
|
|
on an
|
|
.I attr_list
|
|
function call.
|
|
The default is to follow symbolic links.
|
|
.PP
|
|
The
|
|
.I cursor
|
|
argument is a pointer to an opaque data structure that the kernel uses
|
|
to track the calling process\'s position in the attribute list.
|
|
The only valid operations on a
|
|
.I cursor
|
|
are to pass it into an
|
|
.I attr_list
|
|
function call or to zero it out.
|
|
It should be zero\'ed out before the first
|
|
.I attr_list
|
|
call.
|
|
Note that multi-threaded applications may keep more than one
|
|
.I cursor
|
|
in order to serve multiple contexts, ie: the
|
|
.I attr_list
|
|
call is "thread-safe".
|
|
.PP
|
|
.I attr_list
|
|
will fail if one or more of the following are true:
|
|
.TP 17
|
|
.SM
|
|
\%[ENOENT]
|
|
The named file does not exist.
|
|
.TP
|
|
.SM
|
|
\%[EPERM]
|
|
The effective user
|
|
.SM ID
|
|
does not match the owner of the file
|
|
and the effective user
|
|
.SM ID
|
|
is not super-user.
|
|
.TP
|
|
.SM
|
|
\%[ENOTDIR]
|
|
A component of the
|
|
path prefix
|
|
is not a directory.
|
|
.TP
|
|
.SM
|
|
\%[EACCES]
|
|
Search permission is denied on a
|
|
component of the
|
|
path prefix.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
A bit was set in the
|
|
.I flag
|
|
argument that is not defined for this system call,
|
|
or the buffer was too small or too large.
|
|
.TP
|
|
.SM
|
|
\%[EFAULT]
|
|
Either
|
|
.I Path
|
|
or
|
|
.I buffer
|
|
points outside the allocated address space of the process, or
|
|
.I buffer
|
|
or
|
|
.I bufsize
|
|
are not 32bit aligned.
|
|
.TP
|
|
.SM
|
|
\%[ELOOP]
|
|
A path name lookup involved too many symbolic links.
|
|
.TP
|
|
.SM
|
|
\%[ENAMETOOLONG]
|
|
The length of
|
|
.I path
|
|
exceeds
|
|
.SM
|
|
.RI { MAXPATHLEN },
|
|
or a pathname component is longer than
|
|
.SM
|
|
.RI { MAXNAMELEN }.
|
|
.TP
|
|
.SM
|
|
\%[ENOATTR]
|
|
.I attribute\^
|
|
does not exist for this file.
|
|
.PP
|
|
.I attr_listf\^
|
|
will fail if:
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
A bit was set in the
|
|
.I flag
|
|
argument that is not defined for this system call, or
|
|
.I fd\^
|
|
refers to a socket, not a file,
|
|
or the buffer was too small or too large.
|
|
.TP
|
|
.SM
|
|
\%[EFAULT]
|
|
Either
|
|
.I Path
|
|
or
|
|
.I buffer
|
|
points outside the allocated address space of the process, or
|
|
.I buffer
|
|
or
|
|
.I bufsize
|
|
are not 32bit aligned.
|
|
.TP
|
|
.SM
|
|
\%[EBADF]
|
|
.I Fd\^
|
|
does not refer to a valid descriptor.
|
|
.SH "SEE ALSO"
|
|
attr(1),
|
|
.br
|
|
attr_get(2), attr_getf(2),
|
|
.br
|
|
attr_multi(2), attr_multif(2)
|
|
.br
|
|
attr_remove(2), attr_removef(2),
|
|
.br
|
|
attr_set(2), attr_set(2)
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion, a value of 0 is returned.
|
|
Otherwise, a value of \-1 is returned and
|
|
.I errno\^
|
|
is set to indicate the error.
|
|
.\" @(#)attr_list.2 1.0 of 6.12.95
|
|
.Ee
|