|
Packit |
08bd4c |
.\" Copyright (c) 2003-2007 Tim Kientzle
|
|
Packit |
08bd4c |
.\" Copyright (c) 2010 Joerg Sonnenberger
|
|
Packit |
08bd4c |
.\" All rights reserved.
|
|
Packit |
08bd4c |
.\"
|
|
Packit |
08bd4c |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit |
08bd4c |
.\" modification, are permitted provided that the following conditions
|
|
Packit |
08bd4c |
.\" are met:
|
|
Packit |
08bd4c |
.\" 1. Redistributions of source code must retain the above copyright
|
|
Packit |
08bd4c |
.\" notice, this list of conditions and the following disclaimer.
|
|
Packit |
08bd4c |
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
Packit |
08bd4c |
.\" notice, this list of conditions and the following disclaimer in the
|
|
Packit |
08bd4c |
.\" documentation and/or other materials provided with the distribution.
|
|
Packit |
08bd4c |
.\"
|
|
Packit |
08bd4c |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
Packit |
08bd4c |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
08bd4c |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
08bd4c |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
Packit |
08bd4c |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
Packit |
08bd4c |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
Packit |
08bd4c |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
Packit |
08bd4c |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
Packit |
08bd4c |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
Packit |
08bd4c |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
Packit |
08bd4c |
.\" SUCH DAMAGE.
|
|
Packit |
08bd4c |
.\"
|
|
Packit |
08bd4c |
.Dd February 2, 2012
|
|
Packit |
08bd4c |
.Dt ARCHIVE_ENTRY_PERMS 3
|
|
Packit |
08bd4c |
.Os
|
|
Packit |
08bd4c |
.Sh NAME
|
|
Packit |
08bd4c |
.Nm archive_entry_gid ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_gid ,
|
|
Packit |
08bd4c |
.Nm archive_entry_uid ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_uid ,
|
|
Packit |
08bd4c |
.Nm archive_entry_perm ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_perm ,
|
|
Packit |
08bd4c |
.Nm archive_entry_strmode ,
|
|
Packit |
08bd4c |
.Nm archive_entry_uname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_uname_w ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_uname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_uname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_uname_w ,
|
|
Packit |
08bd4c |
.Nm archive_entry_update_uname_utf8 ,
|
|
Packit |
08bd4c |
.Nm archive_entry_gname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_gname_w ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_gname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_gname ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_gname_w ,
|
|
Packit |
08bd4c |
.Nm archive_entry_update_gname_utf8 ,
|
|
Packit |
08bd4c |
.Nm archive_entry_fflags ,
|
|
Packit |
08bd4c |
.Nm archive_entry_fflags_text ,
|
|
Packit |
08bd4c |
.Nm archive_entry_set_fflags ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_fflags_text ,
|
|
Packit |
08bd4c |
.Nm archive_entry_copy_fflags_text_w
|
|
Packit |
08bd4c |
.Nd functions for manipulating ownership and permissions in archive entry descriptions
|
|
Packit |
08bd4c |
.Sh LIBRARY
|
|
Packit |
08bd4c |
Streaming Archive Library (libarchive, -larchive)
|
|
Packit |
08bd4c |
.Sh SYNOPSIS
|
|
Packit |
08bd4c |
.In archive_entry.h
|
|
Packit |
08bd4c |
.Ft gid_t
|
|
Packit |
08bd4c |
.Fn archive_entry_gid "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_set_gid "struct archive_entry *a" "gid_t gid"
|
|
Packit |
08bd4c |
.Ft uid_t
|
|
Packit |
08bd4c |
.Fn archive_entry_uid "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_set_uid "struct archive_entry *a" "uid_t uid"
|
|
Packit |
08bd4c |
.Ft mode_t
|
|
Packit |
08bd4c |
.Fn archive_entry_perm "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_set_perm "struct archive_entry *a" "mode_t mode"
|
|
Packit |
08bd4c |
.Ft const char *
|
|
Packit |
08bd4c |
.Fn archive_entry_strmode "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft const char *
|
|
Packit |
08bd4c |
.Fn archive_entry_gname "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft const wchar_t *
|
|
Packit |
08bd4c |
.Fn archive_entry_gname_w "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_set_gname "struct archive_entry *a" "const char *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_gname "struct archive_entry *a" "const char *name"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_gname_w "struct archive_entry *a" "const wchar_t *name"
|
|
Packit |
08bd4c |
.Ft int
|
|
Packit |
08bd4c |
.Fn archive_entry_update_gname_utf8 "struct archive_entry *a" "const char *name"
|
|
Packit |
08bd4c |
.Ft const char *
|
|
Packit |
08bd4c |
.Fn archive_entry_uname "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft const wchar_t *
|
|
Packit |
08bd4c |
.Fn archive_entry_uname_w "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_set_uname "struct archive_entry *a" "const char *name"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_uname "struct archive_entry *a" "const char *name"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_uname_w "struct archive_entry *a" "const wchar_t *name"
|
|
Packit |
08bd4c |
.Ft int
|
|
Packit |
08bd4c |
.Fn archive_entry_update_uname_utf8 "struct archive_entry *a" "const char *name"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fo archive_entry_fflags
|
|
Packit |
08bd4c |
.Fa "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Fa "unsigned long *set_bits"
|
|
Packit |
08bd4c |
.Fa "unsigned long *clear_bits"
|
|
Packit |
08bd4c |
.Fc
|
|
Packit |
08bd4c |
.Ft const char *
|
|
Packit |
08bd4c |
.Fn archive_entry_fflags_text "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Ft void
|
|
Packit |
08bd4c |
.Fo archive_entry_set_fflags
|
|
Packit |
08bd4c |
.Fa "struct archive_entry *a"
|
|
Packit |
08bd4c |
.Fa "unsigned long set_bits"
|
|
Packit |
08bd4c |
.Fa "unsigned long clear_bits"
|
|
Packit |
08bd4c |
.Fc
|
|
Packit |
08bd4c |
.Ft const char *
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_fflags_text "struct archive_entry *a" "const char *text"
|
|
Packit |
08bd4c |
.Ft const wchar_t *
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_fflags_text_w "struct archive_entry *a" "const wchar_t *text"
|
|
Packit |
08bd4c |
.Sh DESCRIPTION
|
|
Packit |
08bd4c |
.Ss User id, group id and mode
|
|
Packit |
08bd4c |
The functions
|
|
Packit |
08bd4c |
.Fn archive_entry_uid ,
|
|
Packit |
08bd4c |
.Fn archive_entry_gid ,
|
|
Packit |
08bd4c |
and
|
|
Packit |
08bd4c |
.Fn archive_entry_perm
|
|
Packit |
08bd4c |
can be used to extract the user id, group id and permission from the given entry.
|
|
Packit |
08bd4c |
The corresponding functions
|
|
Packit |
08bd4c |
.Fn archive_entry_set_uid ,
|
|
Packit |
08bd4c |
.Fn archive_entry_set_gid ,
|
|
Packit |
08bd4c |
and
|
|
Packit |
08bd4c |
.Fn archive_entry_set_perm
|
|
Packit |
08bd4c |
store the given user id, group id and permission in the entry.
|
|
Packit |
08bd4c |
The permission is also set as side effect of calling
|
|
Packit |
08bd4c |
.Fn archive_entry_set_mode .
|
|
Packit |
08bd4c |
.Pp
|
|
Packit |
08bd4c |
.Fn archive_entry_strmode
|
|
Packit |
08bd4c |
returns a string representation of the permission as used by the long mode of
|
|
Packit |
08bd4c |
.Xr ls 1 .
|
|
Packit |
08bd4c |
.Ss User and group name
|
|
Packit |
08bd4c |
User and group names can be provided in one of three different ways:
|
|
Packit |
08bd4c |
.Bl -tag -width "wchar_t *"
|
|
Packit |
08bd4c |
.It char *
|
|
Packit |
08bd4c |
Multibyte strings in the current locale.
|
|
Packit |
08bd4c |
.It wchar_t *
|
|
Packit |
08bd4c |
Wide character strings in the current locale.
|
|
Packit |
08bd4c |
The accessor functions are named
|
|
Packit |
08bd4c |
.Fn XXX_w .
|
|
Packit |
08bd4c |
.It UTF-8
|
|
Packit |
08bd4c |
Unicode strings encoded as UTF-8.
|
|
Packit |
08bd4c |
This are convience functions to update both the multibyte and wide
|
|
Packit |
08bd4c |
character strings at the same time.
|
|
Packit |
08bd4c |
.El
|
|
Packit |
08bd4c |
.Pp
|
|
Packit |
08bd4c |
.Fn archive_entry_set_XXX
|
|
Packit |
08bd4c |
is an alias for
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_XXX .
|
|
Packit |
08bd4c |
.Ss File Flags
|
|
Packit |
08bd4c |
File flags are transparently converted between a bitmap
|
|
Packit |
08bd4c |
representation and a textual format.
|
|
Packit |
08bd4c |
For example, if you set the bitmap and ask for text, the library
|
|
Packit |
08bd4c |
will build a canonical text format.
|
|
Packit |
08bd4c |
However, if you set a text format and request a text format,
|
|
Packit |
08bd4c |
you will get back the same text, even if it is ill-formed.
|
|
Packit |
08bd4c |
If you need to canonicalize a textual flags string, you should first set the
|
|
Packit |
08bd4c |
text form, then request the bitmap form, then use that to set the bitmap form.
|
|
Packit |
08bd4c |
Setting the bitmap format will clear the internal text representation
|
|
Packit |
08bd4c |
and force it to be reconstructed when you next request the text form.
|
|
Packit |
08bd4c |
.Pp
|
|
Packit |
08bd4c |
The bitmap format consists of two integers, one containing bits
|
|
Packit |
08bd4c |
that should be set, the other specifying bits that should be
|
|
Packit |
08bd4c |
cleared.
|
|
Packit |
08bd4c |
Bits not mentioned in either bitmap will be ignored.
|
|
Packit |
08bd4c |
Usually, the bitmap of bits to be cleared will be set to zero.
|
|
Packit |
08bd4c |
In unusual circumstances, you can force a fully-specified set
|
|
Packit |
08bd4c |
of file flags by setting the bitmap of flags to clear to the complement
|
|
Packit |
08bd4c |
of the bitmap of flags to set.
|
|
Packit |
08bd4c |
(This differs from
|
|
Packit |
08bd4c |
.Xr fflagstostr 3 ,
|
|
Packit |
08bd4c |
which only includes names for set bits.)
|
|
Packit |
08bd4c |
Converting a bitmap to a textual string is a platform-specific
|
|
Packit |
08bd4c |
operation; bits that are not meaningful on the current platform
|
|
Packit |
08bd4c |
will be ignored.
|
|
Packit |
08bd4c |
.Pp
|
|
Packit |
08bd4c |
The canonical text format is a comma-separated list of flag names.
|
|
Packit |
08bd4c |
The
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_fflags_text
|
|
Packit |
08bd4c |
and
|
|
Packit |
08bd4c |
.Fn archive_entry_copy_fflags_text_w
|
|
Packit |
08bd4c |
functions parse the provided text and sets the internal bitmap values.
|
|
Packit |
08bd4c |
This is a platform-specific operation; names that are not meaningful
|
|
Packit |
08bd4c |
on the current platform will be ignored.
|
|
Packit |
08bd4c |
The function returns a pointer to the start of the first name that was not
|
|
Packit |
08bd4c |
recognized, or NULL if every name was recognized.
|
|
Packit |
08bd4c |
Note that every name \(em including names that follow an unrecognized
|
|
Packit |
08bd4c |
name \(em will be evaluated, and the bitmaps will be set to reflect
|
|
Packit |
08bd4c |
every name that is recognized.
|
|
Packit |
08bd4c |
(In particular, this differs from
|
|
Packit |
08bd4c |
.Xr strtofflags 3 ,
|
|
Packit |
08bd4c |
which stops parsing at the first unrecognized name.)
|
|
Packit |
08bd4c |
.Sh SEE ALSO
|
|
Packit |
08bd4c |
.Xr archive_entry 3 ,
|
|
Packit |
08bd4c |
.Xr archive_entry_acl 3 ,
|
|
Packit |
08bd4c |
.Xr archive_read_disk 3 ,
|
|
Packit |
08bd4c |
.Xr archive_write_disk 3
|
|
Packit |
08bd4c |
.Xr libarchive 3 ,
|
|
Packit |
08bd4c |
.Sh BUGS
|
|
Packit |
08bd4c |
The platform types
|
|
Packit |
08bd4c |
.Vt uid_t
|
|
Packit |
08bd4c |
and
|
|
Packit |
08bd4c |
.Vt gid_t
|
|
Packit |
08bd4c |
are often 16 or 32 bit wide.
|
|
Packit |
08bd4c |
In this case it is possible that the ids can not be correctly restored
|
|
Packit |
08bd4c |
from archives and get truncated.
|