1.\" Copyright (c) 2003-2007 Tim Kientzle 2.\" Copyright (c) 2010 Joerg Sonnenberger 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd February 2, 2012 27.Dt ARCHIVE_ENTRY_PERMS 3 28.Os 29.Sh NAME 30.Nm archive_entry_gid , 31.Nm archive_entry_set_gid , 32.Nm archive_entry_uid , 33.Nm archive_entry_set_uid , 34.Nm archive_entry_perm , 35.Nm archive_entry_set_perm , 36.Nm archive_entry_strmode , 37.Nm archive_entry_uname , 38.Nm archive_entry_uname_w , 39.Nm archive_entry_set_uname , 40.Nm archive_entry_copy_uname , 41.Nm archive_entry_copy_uname_w , 42.Nm archive_entry_update_uname_utf8 , 43.Nm archive_entry_gname , 44.Nm archive_entry_gname_w , 45.Nm archive_entry_set_gname , 46.Nm archive_entry_copy_gname , 47.Nm archive_entry_copy_gname_w , 48.Nm archive_entry_update_gname_utf8 , 49.Nm archive_entry_fflags , 50.Nm archive_entry_fflags_text , 51.Nm archive_entry_set_fflags , 52.Nm archive_entry_copy_fflags_text , 53.Nm archive_entry_copy_fflags_text_w 54.Nd functions for manipulating ownership and permissions in archive entry descriptions 55.Sh LIBRARY 56Streaming Archive Library (libarchive, -larchive) 57.Sh SYNOPSIS 58.In archive_entry.h 59.Ft gid_t 60.Fn archive_entry_gid "struct archive_entry *a" 61.Ft void 62.Fn archive_entry_set_gid "struct archive_entry *a" "gid_t gid" 63.Ft uid_t 64.Fn archive_entry_uid "struct archive_entry *a" 65.Ft void 66.Fn archive_entry_set_uid "struct archive_entry *a" "uid_t uid" 67.Ft mode_t 68.Fn archive_entry_perm "struct archive_entry *a" 69.Ft void 70.Fn archive_entry_set_perm "struct archive_entry *a" "mode_t mode" 71.Ft const char * 72.Fn archive_entry_strmode "struct archive_entry *a" 73.Ft const char * 74.Fn archive_entry_gname "struct archive_entry *a" 75.Ft const wchar_t * 76.Fn archive_entry_gname_w "struct archive_entry *a" 77.Ft void 78.Fn archive_entry_set_gname "struct archive_entry *a" "const char *a" 79.Ft void 80.Fn archive_entry_copy_gname "struct archive_entry *a" "const char *name" 81.Ft void 82.Fn archive_entry_copy_gname_w "struct archive_entry *a" "const wchar_t *name" 83.Ft int 84.Fn archive_entry_update_gname_utf8 "struct archive_entry *a" "const char *name" 85.Ft const char * 86.Fn archive_entry_uname "struct archive_entry *a" 87.Ft const wchar_t * 88.Fn archive_entry_uname_w "struct archive_entry *a" 89.Ft void 90.Fn archive_entry_set_uname "struct archive_entry *a" "const char *name" 91.Ft void 92.Fn archive_entry_copy_uname "struct archive_entry *a" "const char *name" 93.Ft void 94.Fn archive_entry_copy_uname_w "struct archive_entry *a" "const wchar_t *name" 95.Ft int 96.Fn archive_entry_update_uname_utf8 "struct archive_entry *a" "const char *name" 97.Ft void 98.Fo archive_entry_fflags 99.Fa "struct archive_entry *a" 100.Fa "unsigned long *set_bits" 101.Fa "unsigned long *clear_bits" 102.Fc 103.Ft const char * 104.Fn archive_entry_fflags_text "struct archive_entry *a" 105.Ft void 106.Fo archive_entry_set_fflags 107.Fa "struct archive_entry *a" 108.Fa "unsigned long set_bits" 109.Fa "unsigned long clear_bits" 110.Fc 111.Ft const char * 112.Fn archive_entry_copy_fflags_text "struct archive_entry *a" "const char *text" 113.Ft const wchar_t * 114.Fn archive_entry_copy_fflags_text_w "struct archive_entry *a" "const wchar_t *text" 115.Sh DESCRIPTION 116.Ss User id, group id and mode 117The functions 118.Fn archive_entry_uid , 119.Fn archive_entry_gid , 120and 121.Fn archive_entry_perm 122can be used to extract the user id, group id and permission from the given entry. 123The corresponding functions 124.Fn archive_entry_set_uid , 125.Fn archive_entry_set_gid , 126and 127.Fn archive_entry_set_perm 128store the given user id, group id and permission in the entry. 129The permission is also set as side effect of calling 130.Fn archive_entry_set_mode . 131.Pp 132.Fn archive_entry_strmode 133returns a string representation of the permission as used by the long mode of 134.Xr ls 1 . 135.Ss User and group name 136User and group names can be provided in one of three different ways: 137.Bl -tag -width "wchar_t *" 138.It char * 139Multibyte strings in the current locale. 140.It wchar_t * 141Wide character strings in the current locale. 142The accessor functions are named 143.Fn XXX_w . 144.It UTF-8 145Unicode strings encoded as UTF-8. 146This are convience functions to update both the multibyte and wide 147character strings at the same time. 148.El 149.Pp 150.Fn archive_entry_set_XXX 151is an alias for 152.Fn archive_entry_copy_XXX . 153.Ss File Flags 154File flags are transparently converted between a bitmap 155representation and a textual format. 156For example, if you set the bitmap and ask for text, the library 157will build a canonical text format. 158However, if you set a text format and request a text format, 159you will get back the same text, even if it is ill-formed. 160If you need to canonicalize a textual flags string, you should first set the 161text form, then request the bitmap form, then use that to set the bitmap form. 162Setting the bitmap format will clear the internal text representation 163and force it to be reconstructed when you next request the text form. 164.Pp 165The bitmap format consists of two integers, one containing bits 166that should be set, the other specifying bits that should be 167cleared. 168Bits not mentioned in either bitmap will be ignored. 169Usually, the bitmap of bits to be cleared will be set to zero. 170In unusual circumstances, you can force a fully-specified set 171of file flags by setting the bitmap of flags to clear to the complement 172of the bitmap of flags to set. 173(This differs from 174.Xr fflagstostr 3 , 175which only includes names for set bits.) 176Converting a bitmap to a textual string is a platform-specific 177operation; bits that are not meaningful on the current platform 178will be ignored. 179.Pp 180The canonical text format is a comma-separated list of flag names. 181The 182.Fn archive_entry_copy_fflags_text 183and 184.Fn archive_entry_copy_fflags_text_w 185functions parse the provided text and sets the internal bitmap values. 186This is a platform-specific operation; names that are not meaningful 187on the current platform will be ignored. 188The function returns a pointer to the start of the first name that was not 189recognized, or NULL if every name was recognized. 190Note that every name \(em including names that follow an unrecognized 191name \(em will be evaluated, and the bitmaps will be set to reflect 192every name that is recognized. 193(In particular, this differs from 194.Xr strtofflags 3 , 195which stops parsing at the first unrecognized name.) 196.Sh SEE ALSO 197.Xr archive 3 , 198.Xr archive_entry 3 , 199.Xr archive_entry_acl 3 , 200.Xr archive_read_disk 3 , 201.Xr archive_write_disk 3 202.Sh BUGS 203The platform types 204.Vt uid_t 205and 206.Vt gid_t 207are often 16 or 32 bit wide. 208In this case it is possible that the ids can not be correctly restored 209from archives and get truncated. 210