1.\" Copyright (c) 2010 Joerg Sonnenberger 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd February 2, 2012 26.Dt ARCHIVE_ENTRY_STAT 3 27.Os 28.Sh NAME 29.Nm archive_entry_stat , 30.Nm archive_entry_copy_stat , 31.Nm archive_entry_filetype , 32.Nm archive_entry_set_filetype , 33.Nm archive_entry_mode , 34.Nm archive_entry_set_mode , 35.Nm archive_entry_size , 36.Nm archive_entry_size_is_set , 37.Nm archive_entry_set_size , 38.Nm archive_entry_unset_size , 39.Nm archive_entry_dev , 40.Nm archive_entry_set_dev , 41.Nm archive_entry_dev_is_set , 42.Nm archive_entry_devmajor , 43.Nm archive_entry_set_devmajor , 44.Nm archive_entry_devminor , 45.Nm archive_entry_set_devminor , 46.Nm archive_entry_ino , 47.Nm archive_entry_set_ino , 48.Nm archive_entry_ino_is_set , 49.Nm archive_entry_ino64 , 50.Nm archive_entry_set_ino64 , 51.Nm archive_entry_nlink , 52.Nm archive_entry_rdev , 53.Nm archive_entry_set_rdev , 54.Nm archive_entry_rdevmajor , 55.Nm archive_entry_set_rdevmajor , 56.Nm archive_entry_rdevminor , 57.Nm archive_entry_set_rdevminor 58.Nd accessor functions for manipulating archive entry descriptions 59.Sh LIBRARY 60Streaming Archive Library (libarchive, -larchive) 61.Sh SYNOPSIS 62.In archive_entry.h 63.Ft const struct stat * 64.Fn archive_entry_stat "struct archive_entry *a" 65.Ft void 66.Fn archive_entry_copy_stat "struct archive_entry *a" "const struct stat *sb" 67.Ft mode_t 68.Fn archive_entry_filetype "struct archive_entry *a" 69.Ft void 70.Fn archive_entry_set_filetype "struct archive_entry *a" "unsigned int type" 71.Ft mode_t 72.Fn archive_entry_mode "struct archive_entry *a" 73.Ft void 74.Fn archive_entry_set_mode "struct archive_entry *a" "mode_t mode" 75.Ft int64_t 76.Fn archive_entry_size "struct archive_entry *a" 77.Ft int 78.Fn archive_entry_size_is_set "struct archive_entry *a" 79.Ft void 80.Fn archive_entry_set_size "struct archive_entry *a" "int64_t size" 81.Ft void 82.Fn archive_entry_unset_size "struct archive_entry *a" 83.Ft dev_t 84.Fn archive_entry_dev "struct archive_entry *a" 85.Ft void 86.Fn archive_entry_set_dev "struct archive_entry *a" "dev_t dev" 87.Ft int 88.Fn archive_entry_dev_is_set "struct archive_entry *a" 89.Ft dev_t 90.Fn archive_entry_devmajor "struct archive_entry *a" 91.Ft void 92.Fn archive_entry_set_devmajor "struct archive_entry *a" "dev_t major" 93.Ft dev_t 94.Fn archive_entry_devminor "struct archive_entry *a" 95.Ft void 96.Fn archive_entry_set_devminor "struct archive_entry *a" "dev_t minor" 97.Ft ino_t 98.Fn archive_entry_ino "struct archive_entry *a" 99.Ft void 100.Fn archive_entry_set_ino "struct archive_entry *a" "unsigned long ino" 101.Ft int 102.Fn archive_entry_ino_is_set "struct archive_entry *a" 103.Ft int64_t 104.Fn archive_entry_ino64 "struct archive_entry *a" 105.Ft void 106.Fn archive_entry_set_ino64 "struct archive_entry *a" "int64_t ino" 107.Ft unsigned int 108.Fn archive_entry_nlink "struct archive_entry *a" 109.Ft void 110.Fn archive_entry_set_nlink "struct archive_entry *a" "unsigned int count" 111.Ft dev_t 112.Fn archive_entry_rdev "struct archive_entry *a" 113.Ft dev_t 114.Fn archive_entry_rdevmajor "struct archive_entry *a" 115.Ft dev_t 116.Fn archive_entry_rdevminor "struct archive_entry *a" 117.Ft void 118.Fn archive_entry_set_rdev "struct archive_entry *a" "dev_t dev" 119.Ft void 120.Fn archive_entry_set_rdevmajor "struct archive_entry *a" "dev_t major" 121.Ft void 122.Fn archive_entry_set_rdevminor "struct archive_entry *a" "dev_t minor" 123.Sh DESCRIPTION 124.Ss Copying to and from Vt struct stat 125The function 126.Fn archive_entry_stat 127converts the various fields stored in the archive entry to the format 128used by 129.Xr stat 2 . 130The return value remains valid until either 131.Fn archive_entry_clear 132or 133.Fn archive_entry_free 134is called. 135It is not affected by calls to the set accessor functions. 136It currently sets the following values in 137.Vt struct stat : 138.Vt st_atime , 139.Vt st_ctime , 140.Vt st_dev , 141.Vt st_gid , 142.Vt st_ino , 143.Vt st_mode , 144.Vt st_mtime , 145.Vt st_nlink , 146.Vt st_rdev , 147.Vt st_size , 148.Vt st_uid . 149In addition, 150.Vt st_birthtime 151and high-precision information for time-related fields 152will be included on platforms that support it. 153.Pp 154The function 155.Fn archive_entry_copy_stat 156copies fields from the platform's 157.Vt struct stat . 158Fields not provided by 159.Vt struct stat 160are unchanged. 161.Ss General accessor functions 162The functions 163.Fn archive_entry_filetype 164and 165.Fn archive_entry_set_filetype 166get respectively set the filetype. 167The file type is one of the following constants: 168.Bl -tag -width "AE_IFSOCK" -compact -offset indent 169.It AE_IFREG 170Regular file 171.It AE_IFLNK 172Symbolic link 173.It AE_IFSOCK 174Socket 175.It AE_IFCHR 176Character device 177.It AE_IFBLK 178Block device 179.It AE_IFDIR 180Directory 181.It AE_IFIFO 182Named pipe (fifo) 183.El 184Not all file types are supported by all platforms. 185The constants used by 186.Xr stat 2 187may have different numeric values from the 188corresponding constants above. 189.Pp 190The functions 191.Fn archive_entry_mode 192and 193.Fn archive_entry_set_mode 194get/set a combination of file type and permissions and provide the 195equivalent of 196.Va st_mode . 197Use of 198.Fn archive_entry_filetype 199and 200.Fn archive_entry_perm 201for getting and 202.Fn archive_entry_set_filetype 203and 204.Fn archive_entry_set_perm 205for setting is recommended. 206.Pp 207The function 208.Fn archive_entry_size 209returns the file size, if it has been set, and 0 otherwise. 210.Fn archive_entry_size 211can be used to query that status. 212.Fn archive_entry_set_size 213and 214.Fn archive_entry_unset_size 215set and unset the size, respectively. 216.Pp 217The number of references (hardlinks) can be obtained by calling 218.Fn archive_entry_nlinks 219and set with 220.Fn archive_entry_set_nlinks . 221.Ss Identifying unique files 222The functions 223.Fn archive_entry_dev 224and 225.Fn archive_entry_ino64 226are used by 227.Xr archive_entry_linkify 3 228to find hardlinks. 229The pair of device and inode is suppossed to identify hardlinked files. 230.Pp 231The device major and minor number can be obtained independently using 232.Fn archive_entry_devmajor 233and 234.Fn archive_entry_devminor . 235The device can be set either via 236.Fn archive_entry_set_dev 237or by the combination of major and minor number using 238.Fn archive_entry_set_devmajor 239and 240.Fn archive_entry_set_devminor . 241.Pp 242The inode number can be obtained using 243.Fn archive_entry_ino . 244This is a legacy interface that uses the platform 245.Vt ino_t , 246which may be very small. 247To set the inode number, 248.Fn archive_entry_set_ino64 249is the preferred interface. 250.Ss Accessor functions for block and character devices 251Block and character devices are characterised either using a device number 252or a pair of major and minor number. 253The combined device number can be obtained with 254.Fn archive_device_rdev 255and set with 256.Fn archive_device_set_rdev . 257The major and minor numbers are accessed by 258.Fn archive_device_rdevmajor , 259.Fn archive_device_rdevminor 260.Fn archive_device_set_rdevmajor 261and 262.Fn archive_device_set_rdevminor . 263.Pp 264The process of splitting the combined device number into major and 265minor number and the reverse process of combing them differs between 266platforms. 267Some archive formats use the combined form, while other formats use 268the split form. 269.Sh SEE ALSO 270.Xr archive 3 , 271.Xr archive_entry_acl 3 , 272.Xr archive_entry_perms 3 , 273.Xr archive_entry_time 3 , 274.Xr stat 2 275