2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
256 lines
7.5 KiB
Groff
256 lines
7.5 KiB
Groff
.\" $NetBSD: extattr_get_file.2,v 1.3 2005/01/02 18:28:48 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org>
|
|
.\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.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: src/lib/libc/sys/extattr_get_file.2,v 1.14 2004/07/05 17:12:52 ru Exp
|
|
.\"
|
|
.Dd January 2, 2004
|
|
.Dt EXTATTR_GET_FILE 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm extattr_get_fd ,
|
|
.Nm extattr_set_fd ,
|
|
.Nm extattr_delete_fd ,
|
|
.Nm extattr_list_fd ,
|
|
.Nm extattr_get_file ,
|
|
.Nm extattr_set_file ,
|
|
.Nm extattr_delete_file ,
|
|
.Nm extattr_list_file ,
|
|
.Nm extattr_get_link ,
|
|
.Nm extattr_set_link ,
|
|
.Nm extattr_delete_link ,
|
|
.Nm extattr_list_link
|
|
.Nd system calls to manipulate VFS extended attributes
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/extattr.h
|
|
.Ft ssize_t
|
|
.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname"
|
|
.Ft ssize_t
|
|
.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes"
|
|
.Ft ssize_t
|
|
.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname"
|
|
.Ft ssize_t
|
|
.Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
|
|
.Ft ssize_t
|
|
.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes"
|
|
.Ft int
|
|
.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname"
|
|
.Ft ssize_t
|
|
.Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes"
|
|
.Sh DESCRIPTION
|
|
Named extended attributes are meta-data associated with vnodes
|
|
representing files and directories.
|
|
They exist as
|
|
.Qq Li name=value
|
|
pairs within a set of namespaces.
|
|
.Pp
|
|
The
|
|
.Fn extattr_get_file
|
|
system call retrieves the value of the specified extended attribute into
|
|
a buffer pointed to by
|
|
.Fa data
|
|
of size
|
|
.Fa nbytes .
|
|
The
|
|
.Fn extattr_set_file
|
|
system call sets the value of the specified extended attribute to the data
|
|
described by
|
|
.Fa data .
|
|
The
|
|
.Fn extattr_delete_file
|
|
system call deletes the extended attribute specified.
|
|
The
|
|
.Fn extattr_list_file
|
|
returns a list of attributes present in the requested namespace, separated
|
|
by ASCII 0 (nul) characters.
|
|
The
|
|
.Fn extattr_get_file
|
|
and
|
|
.Fn extattr_list_file
|
|
calls consume the
|
|
.Fa data
|
|
and
|
|
.Fa nbytes
|
|
arguments in the style of
|
|
.Xr read 2 ;
|
|
.Fn extattr_set_file
|
|
consumes these arguments in the style of
|
|
.Xr write 2 .
|
|
.Pp
|
|
If
|
|
.Fa data
|
|
is
|
|
.Dv NULL
|
|
in a call to
|
|
.Fn extattr_get_file
|
|
then the size of defined extended attribute data will be returned, rather
|
|
than the quantity read, permitting applications to test the size of the
|
|
data without performing a read.
|
|
.Pp
|
|
The
|
|
.Fn extattr_delete_link ,
|
|
.Fn extattr_get_link ,
|
|
and
|
|
.Fn extattr_set_link
|
|
system calls behave in the same way as their _file counterparts, except that
|
|
they do not follow symlinks.
|
|
.Pp
|
|
The
|
|
.Fn extattr_get_fd ,
|
|
.Fn extattr_set_fd ,
|
|
and
|
|
.Fn extattr_delete_fd
|
|
calls are identical to their
|
|
.Qq Li _file
|
|
counterparts except for the first argument.
|
|
The
|
|
.Qq Li _fd
|
|
functions take a file descriptor, while the
|
|
.Qq Li _file
|
|
functions take a path.
|
|
Both arguments describe a file associated with the extended attribute
|
|
that should be manipulated.
|
|
.Pp
|
|
The following arguments are common to all the system calls described here:
|
|
.Bl -tag -width attrnamespace
|
|
.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 file system implementing the call.
|
|
Not all operations may be supported for a particular attribute.
|
|
Additionally, the format of the data in
|
|
.Fa data
|
|
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
|
|
that were read or written from the
|
|
.Fa data ,
|
|
respectively, or if
|
|
.Fa data
|
|
was
|
|
.Dv NULL ,
|
|
then
|
|
.Fn extattr_get_file
|
|
returns the number of bytes available to read.
|
|
If any of the calls are unsuccessful, the value \-1 is returned
|
|
and the global variable
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Pp
|
|
.Rv -std extattr_delete_file
|
|
.Sh ERRORS
|
|
The following errors may be returned by the system calls themselves.
|
|
Additionally, the file system implementing the call may return any
|
|
other errors it desires.
|
|
.Bl -tag -width Er
|
|
.It Bq Er EFAULT
|
|
The
|
|
.Fa attrnamespace
|
|
and
|
|
.Fa attrname
|
|
arguments,
|
|
or the memory range defined by
|
|
.Fa data
|
|
and
|
|
.Fa nbytes
|
|
point outside the process's allocated address space.
|
|
.It Bq Er ENAMETOOLONG
|
|
The attribute name was longer than
|
|
.Dv EXTATTR_MAXNAMELEN .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn extattr_get_fd ,
|
|
.Fn extattr_set_fd ,
|
|
and
|
|
.Fn extattr_delete_fd
|
|
system calls may also fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The file descriptor referenced by
|
|
.Fa fd
|
|
was invalid.
|
|
.El
|
|
.Pp
|
|
Additionally, the
|
|
.Fn extattr_get_file ,
|
|
.Fn extattr_set_file ,
|
|
and
|
|
.Fn extattr_delete_file
|
|
calls may also fail due to the following errors:
|
|
.Bl -tag -width Er
|
|
.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 1 ,
|
|
.Xr extattr 3 ,
|
|
.Xr extattr 9
|
|
.Sh HISTORY
|
|
Extended attribute support was developed as part of the
|
|
.Tn TrustedBSD
|
|
Project, and introduced in
|
|
.Fx 5.0
|
|
and
|
|
.Nx 3.0 .
|
|
It was developed to support security extensions requiring additional labels
|
|
to be associated with each file or directory.
|
|
.Sh CAVEATS
|
|
This interface is under active development, and as such is subject to
|
|
change as applications are adapted to use it.
|
|
Developers are discouraged from relying on its stability.
|