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 22, 2010 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 SYNOPSIS 56.In archive_entry.h 57.Ft gid_t 58.Fn archive_entry_gid "struct archive_entry *a" 59.Ft void 60.Fn archive_entry_set_gid "struct archive_entry *a" "gid_t gid" 61.Ft uid_t 62.Fn archive_entry_uid "struct archive_entry *a" 63.Ft void 64.Fn archive_entry_set_uid "struct archive_entry *a" "uid_t uid" 65.Ft mode_t 66.Fn archive_entry_perm "struct archive_entry *a" 67.Ft void 68.Fn archive_entry_set_perm "struct archive_entry *a" "mode_t mode" 69.Ft const char * 70.Fn archive_entry_strmode "struct archive_entry *a" 71.Ft const char * 72.Fn archive_entry_gname "struct archive_entry *a" 73.Ft const wchar_t * 74.Fn archive_entry_gname_w "struct archive_entry *a" 75.Ft void 76.Fn archive_entry_set_gname "struct archive_entry *a" "const char *a" 77.Ft void 78.Fn archive_entry_copy_gname "struct archive_entry *a" "const char *name" 79.Ft void 80.Fn archive_entry_copy_gname_w "struct archive_entry *a" "const wchar_t *name" 81.Ft int 82.Fn archive_entry_update_gname_utf8 "struct archive_entry *a" "const char *name" 83.Ft const char * 84.Fn archive_entry_uname "struct archive_entry *a" 85.Ft const wchar_t * 86.Fn archive_entry_uname_w "struct archive_entry *a" 87.Ft void 88.Fn archive_entry_set_uname "struct archive_entry *a" "const char *name" 89.Ft void 90.Fn archive_entry_copy_uname "struct archive_entry *a" "const char *name" 91.Ft void 92.Fn archive_entry_copy_uname_w "struct archive_entry *a" "const wchar_t *name" 93.Ft int 94.Fn archive_entry_update_uname_utf8 "struct archive_entry *a" "const char *name" 95.Ft void 96.Fo archive_entry_fflags 97.Fa "struct archive_entry *a" 98.Fa "unsigned long *set_bits" 99.Fa "unsigned long *clear_bits" 100.Fc 101.Ft const char * 102.Fn archive_entry_fflags_text "struct archive_entry *a" 103.Ft void 104.Fo archive_entry_set_fflags 105.Fa "struct archive_entry *a" 106.Fa "unsigned long set_bits" 107.Fa "unsigned long clear_bits" 108.Fc 109.Ft const char * 110.Fn archive_entry_copy_fflags_text "struct archive_entry *a" "const char *text" 111.Ft const wchar_t * 112.Fn archive_entry_copy_fflags_text_w "struct archive_entry *a" "const wchar_t *text" 113.Sh DESCRIPTION 114.Ss User id, group id and mode 115The functions 116.Fn archive_entry_uid , 117.Fn archive_entry_gid , 118and 119.Fn archive_entry_perm 120can be used to extract the user id, group id and permission from the given entry. 121The corresponding functions 122.Fn archive_entry_set_uid , 123.Fn archive_entry_set_gid , 124and 125.Fn archive_entry_set_perm 126store the given user id, group id and permission in the entry. 127The permission is also set as side effect of calling 128.Fn archive_entry_set_mode . 129.Pp 130.Fn archive_entry_strmode 131returns a string representation of the permission as used by the long mode of 132.Xr ls 1 . 133.Ss User and group name 134User and group names can be provided in one of three different ways: 135.Bl -tag -width "wchar_t *" 136.It char * 137Multibyte strings in the current locale. 138.It wchar_t * 139Wide character strings in the current locale. 140The accessor functions are named 141.Fn XXX_w . 142.It UTF-8 143Unicode strings encoded as UTF-8. 144This are convience functions to update both the multibyte and wide 145character strings at the same time. 146.El 147.Pp 148.Fn archive_entry_set_XXX 149is an alias for 150.Fn archive_entry_copy_XXX . 151.Ss File Flags 152File flags are transparently converted between a bitmap 153representation and a textual format. 154For example, if you set the bitmap and ask for text, the library 155will build a canonical text format. 156However, if you set a text format and request a text format, 157you will get back the same text, even if it is ill-formed. 158If you need to canonicalize a textual flags string, you should first set the 159text form, then request the bitmap form, then use that to set the bitmap form. 160Setting the bitmap format will clear the internal text representation 161and force it to be reconstructed when you next request the text form. 162.Pp 163The bitmap format consists of two integers, one containing bits 164that should be set, the other specifying bits that should be 165cleared. 166Bits not mentioned in either bitmap will be ignored. 167Usually, the bitmap of bits to be cleared will be set to zero. 168In unusual circumstances, you can force a fully-specified set 169of file flags by setting the bitmap of flags to clear to the complement 170of the bitmap of flags to set. 171(This differs from 172.Xr fflagstostr 3 , 173which only includes names for set bits.) 174Converting a bitmap to a textual string is a platform-specific 175operation; bits that are not meaningful on the current platform 176will be ignored. 177.Pp 178The canonical text format is a comma-separated list of flag names. 179The 180.Fn archive_entry_copy_fflags_text 181and 182.Fn archive_entry_copy_fflags_text_w 183functions parse the provided text and sets the internal bitmap values. 184This is a platform-specific operation; names that are not meaningful 185on the current platform will be ignored. 186The function returns a pointer to the start of the first name that was not 187recognized, or NULL if every name was recognized. 188Note that every name \(em including names that follow an unrecognized 189name \(em will be evaluated, and the bitmaps will be set to reflect 190every name that is recognized. 191(In particular, this differs from 192.Xr strtofflags 3 , 193which stops parsing at the first unrecognized name.) 194.Sh SEE ALSO 195.Xr archive 3 , 196.Xr archive_entry 3 , 197.Xr archive_entry_acl 3 , 198.Xr archive_read_disk 3 , 199.Xr archive_write_disk 3 200.Sh BUGS 201The platform types 202.Vt uid_t 203and 204.Vt gid_t 205are often 16 or 32 bit wide. 206In this case it is possible that the ids can not be correctly restored 207from archives and get truncated. 208