Date: Wed, 28 Mar 2001 17:12:40 -0500 (EST) From: Robert Watson <rwatson@freebsd.org> To: Dima Dorfman <dima@unixfreak.org> Cc: doc@freebsd.org Subject: Re: extattr_(get|set|delete)_file manual page Message-ID: <Pine.NEB.3.96L.1010328170123.96088W-100000@fledge.watson.org> In-Reply-To: <20010328213548.3A2B53E09@bazooka.unixfreak.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 28 Mar 2001, Dima Dorfman wrote: > [ cross-posted for wider coverage; replies -doc, please ] > > There are no manual pages for the extattr_get_file, extattr_set_file, > and extattr_delete_file system calls. This is surprising, as rwatson > wrote a man page for just about everything else relating to extended > attributes. Attached is my attempt to write one. I'd appreciate > comments on technical accuracy and markup bogons. Thanks! I've been meaning to write and commit man pages, but just haven't gotten around to it. I had a partial set of first drafts, but then changed the interface for the system calls, so put it off further. These descriptions look fine to me, and I'd be happy to see them committed. It should be noted that this interface is highly likely to change again in -CURRENT as we adapt applications to use them, and so developers are discouraged from relying on the staticness of this interface. In particular, despite the existence of related calls in -STABLE, it's important the man pages not be MFC'd to there--there has already been divergence between -CURRENT and -STABLE with the attrnamespace arguments. Thanks again! Robert N M Watson FreeBSD Core Team, TrustedBSD Project robert@fledge.watson.org NAI Labs, Safeport Network Services > > --- /dev/null Wed Mar 28 13:02:30 2001 > +++ extattr_get_file.2 Wed Mar 28 13:26:08 2001 > @@ -0,0 +1,150 @@ > +.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> > +.\" All rights reserved. > +.\" > +.\" Redistribution and use in source and binary forms, with or without > +.\" modification, are permitted provided that the following conditions > +.\" are met: > +.\" 1. Redistributions of source code must retain the above copyright > +.\" notice, this list of conditions and the following disclaimer. > +.\" 2. Redistributions in binary form must reproduce the above copyright > +.\" notice, this list of conditions and the following disclaimer in the > +.\" documentation and/or other materials provided with the distribution. > +.\" > +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND > +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE > +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE > +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE > +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL > +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS > +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) > +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT > +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY > +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF > +.\" SUCH DAMAGE. > +.\" > +.\" $FreeBSD$ > +.\" > +.Dd Wednesday 28, 2001 > +.Dt EXTATTR_GET_FILE 2 > +.Os > +.Sh NAME > +.Nm extattr_get_file , > +.Nm extattr_set_file , > +.Nm extattr_delete_file > +.Nd manipulate VFS extended attributes > +.Sh LIBRARY > +.Lb libc > +.Sh SYNOPSIS > +.Fd #include <sys/uio.h> > +.Fd #include <sys/extattr.h> > +.Ft int > +.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt" > +.Ft int > +.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "struct iovec *iovp" "unsigned iovcnt" > +.Ft int > +.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname" > +.Sh DESCRIPTION > +Named extended attributes are meta-data associated with vnodes > +representing files and directories. > +They exist as "name=value" pairs within a set of namespaces. > +The > +.Fn extattr_get_file > +call retrieves the value of the specified extended attribute into > +.Fa iovp . > +The > +.Fn extattr_set_file > +call sets the value of the specified extended attribute to the data > +described by > +.Fa iovp . > +The > +.Fn extattr_delete_file > +call deletes the extended attribute specified. > +The > +.Fn extattr_get_file > +and > +.Fn extattr_set_file > +calls consume the > +.Fa iovp > +and > +.Fa iovcnt > +arguments in the style of > +.Xr readv 2 > +and > +.Xr writev 2 , > +respectively. > +.Pp > +The following arguments are common to the three system calls: > +.Bl -tag -width x > +.It Fa path > +path name to the file or directory associated with the extended > +attribute > +.It Fa attrnamespace > +the namespace in which the extended attribute resides; see > +.Xr extattr 9 > +.It Fa attrname > +the name of the extended attribute > +.El > +.Pp > +Named extended attribute semantics vary by filesystem implementing the call. > +Not all operation may be supported for a particular attribute. > +Additionally, the format of the data in > +.Fa iovp > +is attribute-specific. > +.Pp > +For more information on named extended attributes, please see > +.Xr extattr 9 . > +.Sh RETURN VALUES > +If successful, the > +.Fn extattr_get_file > +and > +.Fn extattr_set_file > +calls return the number of bytes of > +.Fa iovp > +were read or written, respectively. > +The > +.Fn extattr_delete_file > +call returns 0 on success. > +If any of the calls are unsuccessful, -1 is returned and the global > +variable > +.Va errno > +is set to indicate the error. > +.Sh ERRORS > +The following errors may be returned by the system calls themselves. > +Additionally, the filesystem implementing the call may return any > +other errors it desires. > +.Bl -tag -width Er > +.It Bq Er EFAULT > +.Fa attrnamespace , > +.Fa attrname , > +or > +.Fa iovp > +point outside the process's allocated address space. > +.It Bq Er ENAMETOOLONG > +The attribute name was longer than > +.Dv EXTATTR_MAXNAMELEN . > +.It Bq Er ENOTDIR > +A component of the path prefix is not a directory. > +.It Bq Er ENAMETOOLONG > +A component of a pathname exceeded 255 characters, > +or an entire path name exceeded 1023 characters. > +.It Bq Er ENOENT > +A component of the path name that must exist does not exist. > +.It Bq Er EACCES > +Search permission is denied for a component of the path prefix. > +.\" XXX are any missing? > +.El > +.Sh SEE ALSO > +.Xr getextattr 8 , > +.Xr setextattr 8 , > +.Xr extattr 9 , > +.Xr VOP_GETEXTATTR 9 , > +.Xr VOP_SETEXTATTR 9 > +.Sh HISTORY > +Extended attribute support was developed as part of the TrustedBSD Project, > +and introduced in > +.Fx 5.0 . > +It was developed to support security extensions requiring additional labels > +to be associated with each file or directory. > +.Sh AUTHORS > +This manual page was written by > +.An Dima Dorfman . > To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.NEB.3.96L.1010328170123.96088W-100000>