source/include/archive_entry.h

0001 /*-
0002  * Copyright (c) 2003-2008 Tim Kientzle
0003  * Copyright (c) 2016 Martin Matuska
0004  * All rights reserved.
0005  *
0006  * Redistribution and use in source and binary forms, with or without
0007  * modification, are permitted provided that the following conditions
0008  * are met:
0009  * 1. Redistributions of source code must retain the above copyright
0010  *    notice, this list of conditions and the following disclaimer.
0011  * 2. Redistributions in binary form must reproduce the above copyright
0012  *    notice, this list of conditions and the following disclaimer in the
0013  *    documentation and/or other materials provided with the distribution.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR
0016  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
0017  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
0018  * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
0019  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
0020  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0021  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0022  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0023  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
0024  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0025  */
0026
0027 #ifndef ARCHIVE_ENTRY_H_INCLUDED
0028 #define ARCHIVE_ENTRY_H_INCLUDED
0029
0030 /* Note: Compiler will complain if this does not match archive.h! */
0031 #define ARCHIVE_VERSION_NUMBER 3007006
0032
0033 /*
0034  * Note: archive_entry.h is for use outside of libarchive; the
0035  * configuration headers (config.h, archive_platform.h, etc.) are
0036  * purely internal.  Do NOT use HAVE_XXX configuration macros to
0037  * control the behavior of this header!  If you must conditionalize,
0038  * use predefined compiler and/or platform macros.
0039  */
0040
0041 #include <sys/types.h>
0042 #include <stddef.h>  /* for wchar_t */
0043 #include <stdint.h>
0044 #include <time.h>
0045
0046 #if defined(_WIN32) && !defined(__CYGWIN__)
0047 #include <windows.h>
0048 #endif
0049
0050 /* Get a suitable 64-bit integer type. */
0051 #if !defined(__LA_INT64_T_DEFINED)
0052 # if ARCHIVE_VERSION_NUMBER < 4000000
0053 #define __LA_INT64_T la_int64_t
0054 # endif
0055 #define __LA_INT64_T_DEFINED
0056 # if defined(_WIN32) && !defined(__CYGWIN__) && !defined(__WATCOMC__)
0057 typedef __int64 la_int64_t;
0058 # else
0059 #include <unistd.h>
0060 #  if defined(_SCO_DS) || defined(__osf__)
0061 typedef long long la_int64_t;
0062 #  else
0063 typedef int64_t la_int64_t;
0064 #  endif
0065 # endif
0066 #endif
0067
0068 /* The la_ssize_t should match the type used in 'struct stat' */
0069 #if !defined(__LA_SSIZE_T_DEFINED)
0070 /* Older code relied on the __LA_SSIZE_T macro; after 4.0 we'll switch to the typedef exclusively. */
0071 # if ARCHIVE_VERSION_NUMBER < 4000000
0072 #define __LA_SSIZE_T la_ssize_t
0073 # endif
0074 #define __LA_SSIZE_T_DEFINED
0075 # if defined(_WIN32) && !defined(__CYGWIN__) && !defined(__WATCOMC__)
0076 #  if defined(_SSIZE_T_DEFINED) || defined(_SSIZE_T_)
0077 typedef ssize_t la_ssize_t;
0078 #  elif defined(_WIN64)
0079 typedef __int64 la_ssize_t;
0080 #  else
0081 typedef long la_ssize_t;
0082 #  endif
0083 # else
0084 # include <unistd.h>  /* ssize_t */
0085 typedef ssize_t la_ssize_t;
0086 # endif
0087 #endif
0088
0089 /* Get a suitable definition for mode_t */
0090 #if ARCHIVE_VERSION_NUMBER >= 3999000
0091 /* Switch to plain 'int' for libarchive 4.0.  It's less broken than 'mode_t' */
0092 # define    __LA_MODE_T int
0093 #elif defined(_WIN32) && !defined(__CYGWIN__) && !defined(__BORLANDC__) && !defined(__WATCOMC__)
0094 # define    __LA_MODE_T unsigned short
0095 #else
0096 # define    __LA_MODE_T mode_t
0097 #endif
0098
0099 /* Large file support for Android */
0100 #if defined(__LIBARCHIVE_BUILD) && defined(__ANDROID__)
0101 #include "android_lf.h"
0102 #endif
0103
0104 /*
0105  * On Windows, define LIBARCHIVE_STATIC if you're building or using a
0106  * .lib.  The default here assumes you're building a DLL.  Only
0107  * libarchive source should ever define __LIBARCHIVE_BUILD.
0108  */
0109 #if ((defined __WIN32__) || (defined _WIN32) || defined(__CYGWIN__)) && (!defined LIBARCHIVE_STATIC)
0110 # ifdef __LIBARCHIVE_BUILD
0111 #  ifdef __GNUC__
0112 #   define __LA_DECL    __attribute__((dllexport)) extern
0113 #  else
0114 #   define __LA_DECL    __declspec(dllexport)
0115 #  endif
0116 # else
0117 #  ifdef __GNUC__
0118 #   define __LA_DECL
0119 #  else
0120 #   define __LA_DECL    __declspec(dllimport)
0121 #  endif
0122 # endif
0123 #elif defined __LIBARCHIVE_ENABLE_VISIBILITY
0124 #  define __LA_DECL __attribute__((visibility("default")))
0125 #else
0126 /* Static libraries on all platforms and shared libraries on non-Windows. */
0127 # define __LA_DECL
0128 #endif
0129
0130 #if defined(__GNUC__) && __GNUC__ >= 3 && __GNUC_MINOR__ >= 1
0131 # define __LA_DEPRECATED __attribute__((deprecated))
0132 #else
0133 # define __LA_DEPRECATED
0134 #endif
0135
0136 #ifdef __cplusplus
0137 extern "C" {
0138 #endif
0139
0140 /*
0141  * Description of an archive entry.
0142  *
0143  * You can think of this as "struct stat" with some text fields added in.
0144  *
0145  * TODO: Add "comment", "charset", and possibly other entries that are
0146  * supported by "pax interchange" format.  However, GNU, ustar, cpio,
0147  * and other variants don't support these features, so they're not an
0148  * excruciatingly high priority right now.
0149  *
0150  * TODO: "pax interchange" format allows essentially arbitrary
0151  * key/value attributes to be attached to any entry.  Supporting
0152  * such extensions may make this library useful for special
0153  * applications (e.g., a package manager could attach special
0154  * package-management attributes to each entry).
0155  */
0156 struct archive;
0157 struct archive_entry;
0158
0159 /*
0160  * File-type constants.  These are returned from archive_entry_filetype()
0161  * and passed to archive_entry_set_filetype().
0162  *
0163  * These values match S_XXX defines on every platform I've checked,
0164  * including Windows, AIX, Linux, Solaris, and BSD.  They're
0165  * (re)defined here because platforms generally don't define the ones
0166  * they don't support.  For example, Windows doesn't define S_IFLNK or
0167  * S_IFBLK.  Instead of having a mass of conditional logic and system
0168  * checks to define any S_XXX values that aren't supported locally,
0169  * I've just defined a new set of such constants so that
0170  * libarchive-based applications can manipulate and identify archive
0171  * entries properly even if the hosting platform can't store them on
0172  * disk.
0173  *
0174  * These values are also used directly within some portable formats,
0175  * such as cpio.  If you find a platform that varies from these, the
0176  * correct solution is to leave these alone and translate from these
0177  * portable values to platform-native values when entries are read from
0178  * or written to disk.
0179  */
0180 /*
0181  * In libarchive 4.0, we can drop the casts here.
0182  * They're needed to work around Borland C's broken mode_t.
0183  */
0184 #define AE_IFMT     ((__LA_MODE_T)0170000)
0185 #define AE_IFREG    ((__LA_MODE_T)0100000)
0186 #define AE_IFLNK    ((__LA_MODE_T)0120000)
0187 #define AE_IFSOCK   ((__LA_MODE_T)0140000)
0188 #define AE_IFCHR    ((__LA_MODE_T)0020000)
0189 #define AE_IFBLK    ((__LA_MODE_T)0060000)
0190 #define AE_IFDIR    ((__LA_MODE_T)0040000)
0191 #define AE_IFIFO    ((__LA_MODE_T)0010000)
0192
0193 /*
0194  * Symlink types
0195  */
0196 #define AE_SYMLINK_TYPE_UNDEFINED   0
0197 #define AE_SYMLINK_TYPE_FILE        1
0198 #define AE_SYMLINK_TYPE_DIRECTORY   2
0199
0200 /*
0201  * Basic object manipulation
0202  */
0203
0204 __LA_DECL struct archive_entry  *archive_entry_clear(struct archive_entry *);
0205 /* The 'clone' function does a deep copy; all of the strings are copied too. */
0206 __LA_DECL struct archive_entry  *archive_entry_clone(struct archive_entry *);
0207 __LA_DECL void           archive_entry_free(struct archive_entry *);
0208 __LA_DECL struct archive_entry  *archive_entry_new(void);
0209
0210 /*
0211  * This form of archive_entry_new2() will pull character-set
0212  * conversion information from the specified archive handle.  The
0213  * older archive_entry_new(void) form is equivalent to calling
0214  * archive_entry_new2(NULL) and will result in the use of an internal
0215  * default character-set conversion.
0216  */
0217 __LA_DECL struct archive_entry  *archive_entry_new2(struct archive *);
0218
0219 /*
0220  * Retrieve fields from an archive_entry.
0221  *
0222  * There are a number of implicit conversions among these fields.  For
0223  * example, if a regular string field is set and you read the _w wide
0224  * character field, the entry will implicitly convert narrow-to-wide
0225  * using the current locale.  Similarly, dev values are automatically
0226  * updated when you write devmajor or devminor and vice versa.
0227  *
0228  * In addition, fields can be "set" or "unset."  Unset string fields
0229  * return NULL, non-string fields have _is_set() functions to test
0230  * whether they've been set.  You can "unset" a string field by
0231  * assigning NULL; non-string fields have _unset() functions to
0232  * unset them.
0233  *
0234  * Note: There is one ambiguity in the above; string fields will
0235  * also return NULL when implicit character set conversions fail.
0236  * This is usually what you want.
0237  */
0238 __LA_DECL time_t     archive_entry_atime(struct archive_entry *);
0239 __LA_DECL long       archive_entry_atime_nsec(struct archive_entry *);
0240 __LA_DECL int        archive_entry_atime_is_set(struct archive_entry *);
0241 __LA_DECL time_t     archive_entry_birthtime(struct archive_entry *);
0242 __LA_DECL long       archive_entry_birthtime_nsec(struct archive_entry *);
0243 __LA_DECL int        archive_entry_birthtime_is_set(struct archive_entry *);
0244 __LA_DECL time_t     archive_entry_ctime(struct archive_entry *);
0245 __LA_DECL long       archive_entry_ctime_nsec(struct archive_entry *);
0246 __LA_DECL int        archive_entry_ctime_is_set(struct archive_entry *);
0247 __LA_DECL dev_t      archive_entry_dev(struct archive_entry *);
0248 __LA_DECL int        archive_entry_dev_is_set(struct archive_entry *);
0249 __LA_DECL dev_t      archive_entry_devmajor(struct archive_entry *);
0250 __LA_DECL dev_t      archive_entry_devminor(struct archive_entry *);
0251 __LA_DECL __LA_MODE_T    archive_entry_filetype(struct archive_entry *);
0252 __LA_DECL int        archive_entry_filetype_is_set(struct archive_entry *);
0253 __LA_DECL void       archive_entry_fflags(struct archive_entry *,
0254                 unsigned long * /* set */,
0255                 unsigned long * /* clear */);
0256 __LA_DECL const char    *archive_entry_fflags_text(struct archive_entry *);
0257 __LA_DECL la_int64_t     archive_entry_gid(struct archive_entry *);
0258 __LA_DECL int        archive_entry_gid_is_set(struct archive_entry *);
0259 __LA_DECL const char    *archive_entry_gname(struct archive_entry *);
0260 __LA_DECL const char    *archive_entry_gname_utf8(struct archive_entry *);
0261 __LA_DECL const wchar_t *archive_entry_gname_w(struct archive_entry *);
0262 __LA_DECL void       archive_entry_set_link_to_hardlink(struct archive_entry *);
0263 __LA_DECL const char    *archive_entry_hardlink(struct archive_entry *);
0264 __LA_DECL const char    *archive_entry_hardlink_utf8(struct archive_entry *);
0265 __LA_DECL const wchar_t *archive_entry_hardlink_w(struct archive_entry *);
0266 __LA_DECL int        archive_entry_hardlink_is_set(struct archive_entry *);
0267 __LA_DECL la_int64_t     archive_entry_ino(struct archive_entry *);
0268 __LA_DECL la_int64_t     archive_entry_ino64(struct archive_entry *);
0269 __LA_DECL int        archive_entry_ino_is_set(struct archive_entry *);
0270 __LA_DECL __LA_MODE_T    archive_entry_mode(struct archive_entry *);
0271 __LA_DECL time_t     archive_entry_mtime(struct archive_entry *);
0272 __LA_DECL long       archive_entry_mtime_nsec(struct archive_entry *);
0273 __LA_DECL int        archive_entry_mtime_is_set(struct archive_entry *);
0274 __LA_DECL unsigned int   archive_entry_nlink(struct archive_entry *);
0275 __LA_DECL const char    *archive_entry_pathname(struct archive_entry *);
0276 __LA_DECL const char    *archive_entry_pathname_utf8(struct archive_entry *);
0277 __LA_DECL const wchar_t *archive_entry_pathname_w(struct archive_entry *);
0278 __LA_DECL __LA_MODE_T    archive_entry_perm(struct archive_entry *);
0279 __LA_DECL int        archive_entry_perm_is_set(struct archive_entry *);
0280 __LA_DECL int        archive_entry_rdev_is_set(struct archive_entry *);
0281 __LA_DECL dev_t      archive_entry_rdev(struct archive_entry *);
0282 __LA_DECL dev_t      archive_entry_rdevmajor(struct archive_entry *);
0283 __LA_DECL dev_t      archive_entry_rdevminor(struct archive_entry *);
0284 __LA_DECL const char    *archive_entry_sourcepath(struct archive_entry *);
0285 __LA_DECL const wchar_t *archive_entry_sourcepath_w(struct archive_entry *);
0286 __LA_DECL la_int64_t     archive_entry_size(struct archive_entry *);
0287 __LA_DECL int        archive_entry_size_is_set(struct archive_entry *);
0288 __LA_DECL const char    *archive_entry_strmode(struct archive_entry *);
0289 __LA_DECL void       archive_entry_set_link_to_symlink(struct archive_entry *);
0290 __LA_DECL const char    *archive_entry_symlink(struct archive_entry *);
0291 __LA_DECL const char    *archive_entry_symlink_utf8(struct archive_entry *);
0292 __LA_DECL int        archive_entry_symlink_type(struct archive_entry *);
0293 __LA_DECL const wchar_t *archive_entry_symlink_w(struct archive_entry *);
0294 __LA_DECL la_int64_t     archive_entry_uid(struct archive_entry *);
0295 __LA_DECL int        archive_entry_uid_is_set(struct archive_entry *);
0296 __LA_DECL const char    *archive_entry_uname(struct archive_entry *);
0297 __LA_DECL const char    *archive_entry_uname_utf8(struct archive_entry *);
0298 __LA_DECL const wchar_t *archive_entry_uname_w(struct archive_entry *);
0299 __LA_DECL int archive_entry_is_data_encrypted(struct archive_entry *);
0300 __LA_DECL int archive_entry_is_metadata_encrypted(struct archive_entry *);
0301 __LA_DECL int archive_entry_is_encrypted(struct archive_entry *);
0302
0303 /*
0304  * Set fields in an archive_entry.
0305  *
0306  * Note: Before libarchive 2.4, there were 'set' and 'copy' versions
0307  * of the string setters.  'copy' copied the actual string, 'set' just
0308  * stored the pointer.  In libarchive 2.4 and later, strings are
0309  * always copied.
0310  */
0311
0312 __LA_DECL void  archive_entry_set_atime(struct archive_entry *, time_t, long);
0313 __LA_DECL void  archive_entry_unset_atime(struct archive_entry *);
0314 #if defined(_WIN32) && !defined(__CYGWIN__)
0315 __LA_DECL void archive_entry_copy_bhfi(struct archive_entry *, BY_HANDLE_FILE_INFORMATION *);
0316 #endif
0317 __LA_DECL void  archive_entry_set_birthtime(struct archive_entry *, time_t, long);
0318 __LA_DECL void  archive_entry_unset_birthtime(struct archive_entry *);
0319 __LA_DECL void  archive_entry_set_ctime(struct archive_entry *, time_t, long);
0320 __LA_DECL void  archive_entry_unset_ctime(struct archive_entry *);
0321 __LA_DECL void  archive_entry_set_dev(struct archive_entry *, dev_t);
0322 __LA_DECL void  archive_entry_set_devmajor(struct archive_entry *, dev_t);
0323 __LA_DECL void  archive_entry_set_devminor(struct archive_entry *, dev_t);
0324 __LA_DECL void  archive_entry_set_filetype(struct archive_entry *, unsigned int);
0325 __LA_DECL void  archive_entry_set_fflags(struct archive_entry *,
0326         unsigned long /* set */, unsigned long /* clear */);
0327 /* Returns pointer to start of first invalid token, or NULL if none. */
0328 /* Note that all recognized tokens are processed, regardless. */
0329 __LA_DECL const char *archive_entry_copy_fflags_text(struct archive_entry *,
0330         const char *);
0331 __LA_DECL const char *archive_entry_copy_fflags_text_len(struct archive_entry *,
0332         const char *, size_t);
0333 __LA_DECL const wchar_t *archive_entry_copy_fflags_text_w(struct archive_entry *,
0334         const wchar_t *);
0335 __LA_DECL void  archive_entry_set_gid(struct archive_entry *, la_int64_t);
0336 __LA_DECL void  archive_entry_set_gname(struct archive_entry *, const char *);
0337 __LA_DECL void  archive_entry_set_gname_utf8(struct archive_entry *, const char *);
0338 __LA_DECL void  archive_entry_copy_gname(struct archive_entry *, const char *);
0339 __LA_DECL void  archive_entry_copy_gname_w(struct archive_entry *, const wchar_t *);
0340 __LA_DECL int   archive_entry_update_gname_utf8(struct archive_entry *, const char *);
0341 __LA_DECL void  archive_entry_set_hardlink(struct archive_entry *, const char *);
0342 __LA_DECL void  archive_entry_set_hardlink_utf8(struct archive_entry *, const char *);
0343 __LA_DECL void  archive_entry_copy_hardlink(struct archive_entry *, const char *);
0344 __LA_DECL void  archive_entry_copy_hardlink_w(struct archive_entry *, const wchar_t *);
0345 __LA_DECL int   archive_entry_update_hardlink_utf8(struct archive_entry *, const char *);
0346 __LA_DECL void  archive_entry_set_ino(struct archive_entry *, la_int64_t);
0347 __LA_DECL void  archive_entry_set_ino64(struct archive_entry *, la_int64_t);
0348 __LA_DECL void  archive_entry_set_link(struct archive_entry *, const char *);
0349 __LA_DECL void  archive_entry_set_link_utf8(struct archive_entry *, const char *);
0350 __LA_DECL void  archive_entry_copy_link(struct archive_entry *, const char *);
0351 __LA_DECL void  archive_entry_copy_link_w(struct archive_entry *, const wchar_t *);
0352 __LA_DECL int   archive_entry_update_link_utf8(struct archive_entry *, const char *);
0353 __LA_DECL void  archive_entry_set_mode(struct archive_entry *, __LA_MODE_T);
0354 __LA_DECL void  archive_entry_set_mtime(struct archive_entry *, time_t, long);
0355 __LA_DECL void  archive_entry_unset_mtime(struct archive_entry *);
0356 __LA_DECL void  archive_entry_set_nlink(struct archive_entry *, unsigned int);
0357 __LA_DECL void  archive_entry_set_pathname(struct archive_entry *, const char *);
0358 __LA_DECL void  archive_entry_set_pathname_utf8(struct archive_entry *, const char *);
0359 __LA_DECL void  archive_entry_copy_pathname(struct archive_entry *, const char *);
0360 __LA_DECL void  archive_entry_copy_pathname_w(struct archive_entry *, const wchar_t *);
0361 __LA_DECL int   archive_entry_update_pathname_utf8(struct archive_entry *, const char *);
0362 __LA_DECL void  archive_entry_set_perm(struct archive_entry *, __LA_MODE_T);
0363 __LA_DECL void  archive_entry_set_rdev(struct archive_entry *, dev_t);
0364 __LA_DECL void  archive_entry_set_rdevmajor(struct archive_entry *, dev_t);
0365 __LA_DECL void  archive_entry_set_rdevminor(struct archive_entry *, dev_t);
0366 __LA_DECL void  archive_entry_set_size(struct archive_entry *, la_int64_t);
0367 __LA_DECL void  archive_entry_unset_size(struct archive_entry *);
0368 __LA_DECL void  archive_entry_copy_sourcepath(struct archive_entry *, const char *);
0369 __LA_DECL void  archive_entry_copy_sourcepath_w(struct archive_entry *, const wchar_t *);
0370 __LA_DECL void  archive_entry_set_symlink(struct archive_entry *, const char *);
0371 __LA_DECL void  archive_entry_set_symlink_type(struct archive_entry *, int);
0372 __LA_DECL void  archive_entry_set_symlink_utf8(struct archive_entry *, const char *);
0373 __LA_DECL void  archive_entry_copy_symlink(struct archive_entry *, const char *);
0374 __LA_DECL void  archive_entry_copy_symlink_w(struct archive_entry *, const wchar_t *);
0375 __LA_DECL int   archive_entry_update_symlink_utf8(struct archive_entry *, const char *);
0376 __LA_DECL void  archive_entry_set_uid(struct archive_entry *, la_int64_t);
0377 __LA_DECL void  archive_entry_set_uname(struct archive_entry *, const char *);
0378 __LA_DECL void  archive_entry_set_uname_utf8(struct archive_entry *, const char *);
0379 __LA_DECL void  archive_entry_copy_uname(struct archive_entry *, const char *);
0380 __LA_DECL void  archive_entry_copy_uname_w(struct archive_entry *, const wchar_t *);
0381 __LA_DECL int   archive_entry_update_uname_utf8(struct archive_entry *, const char *);
0382 __LA_DECL void  archive_entry_set_is_data_encrypted(struct archive_entry *, char is_encrypted);
0383 __LA_DECL void  archive_entry_set_is_metadata_encrypted(struct archive_entry *, char is_encrypted);
0384 /*
0385  * Routines to bulk copy fields to/from a platform-native "struct
0386  * stat."  Libarchive used to just store a struct stat inside of each
0387  * archive_entry object, but this created issues when trying to
0388  * manipulate archives on systems different than the ones they were
0389  * created on.
0390  *
0391  * TODO: On Linux and other LFS systems, provide both stat32 and
0392  * stat64 versions of these functions and all of the macro glue so
0393  * that archive_entry_stat is magically defined to
0394  * archive_entry_stat32 or archive_entry_stat64 as appropriate.
0395  */
0396 __LA_DECL const struct stat *archive_entry_stat(struct archive_entry *);
0397 __LA_DECL void  archive_entry_copy_stat(struct archive_entry *, const struct stat *);
0398
0399 /*
0400  * Storage for Mac OS-specific AppleDouble metadata information.
0401  * Apple-format tar files store a separate binary blob containing
0402  * encoded metadata with ACL, extended attributes, etc.
0403  * This provides a place to store that blob.
0404  */
0405
0406 __LA_DECL const void * archive_entry_mac_metadata(struct archive_entry *, size_t *);
0407 __LA_DECL void archive_entry_copy_mac_metadata(struct archive_entry *, const void *, size_t);
0408
0409 /*
0410  * Digest routine. This is used to query the raw hex digest for the
0411  * given entry. The type of digest is provided as an argument.
0412  */
0413 #define ARCHIVE_ENTRY_DIGEST_MD5              0x00000001
0414 #define ARCHIVE_ENTRY_DIGEST_RMD160           0x00000002
0415 #define ARCHIVE_ENTRY_DIGEST_SHA1             0x00000003
0416 #define ARCHIVE_ENTRY_DIGEST_SHA256           0x00000004
0417 #define ARCHIVE_ENTRY_DIGEST_SHA384           0x00000005
0418 #define ARCHIVE_ENTRY_DIGEST_SHA512           0x00000006
0419
0420 __LA_DECL const unsigned char * archive_entry_digest(struct archive_entry *, int /* type */);
0421
0422 /*
0423  * ACL routines.  This used to simply store and return text-format ACL
0424  * strings, but that proved insufficient for a number of reasons:
0425  *   = clients need control over uname/uid and gname/gid mappings
0426  *   = there are many different ACL text formats
0427  *   = would like to be able to read/convert archives containing ACLs
0428  *     on platforms that lack ACL libraries
0429  *
0430  *  This last point, in particular, forces me to implement a reasonably
0431  *  complete set of ACL support routines.
0432  */
0433
0434 /*
0435  * Permission bits.
0436  */
0437 #define ARCHIVE_ENTRY_ACL_EXECUTE             0x00000001
0438 #define ARCHIVE_ENTRY_ACL_WRITE               0x00000002
0439 #define ARCHIVE_ENTRY_ACL_READ                0x00000004
0440 #define ARCHIVE_ENTRY_ACL_READ_DATA           0x00000008
0441 #define ARCHIVE_ENTRY_ACL_LIST_DIRECTORY      0x00000008
0442 #define ARCHIVE_ENTRY_ACL_WRITE_DATA          0x00000010
0443 #define ARCHIVE_ENTRY_ACL_ADD_FILE            0x00000010
0444 #define ARCHIVE_ENTRY_ACL_APPEND_DATA         0x00000020
0445 #define ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY    0x00000020
0446 #define ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS    0x00000040
0447 #define ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS   0x00000080
0448 #define ARCHIVE_ENTRY_ACL_DELETE_CHILD        0x00000100
0449 #define ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES     0x00000200
0450 #define ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES    0x00000400
0451 #define ARCHIVE_ENTRY_ACL_DELETE              0x00000800
0452 #define ARCHIVE_ENTRY_ACL_READ_ACL            0x00001000
0453 #define ARCHIVE_ENTRY_ACL_WRITE_ACL           0x00002000
0454 #define ARCHIVE_ENTRY_ACL_WRITE_OWNER         0x00004000
0455 #define ARCHIVE_ENTRY_ACL_SYNCHRONIZE         0x00008000
0456
0457 #define ARCHIVE_ENTRY_ACL_PERMS_POSIX1E         \
0458     (ARCHIVE_ENTRY_ACL_EXECUTE          \
0459         | ARCHIVE_ENTRY_ACL_WRITE           \
0460         | ARCHIVE_ENTRY_ACL_READ)
0461
0462 #define ARCHIVE_ENTRY_ACL_PERMS_NFS4            \
0463     (ARCHIVE_ENTRY_ACL_EXECUTE          \
0464         | ARCHIVE_ENTRY_ACL_READ_DATA       \
0465         | ARCHIVE_ENTRY_ACL_LIST_DIRECTORY      \
0466         | ARCHIVE_ENTRY_ACL_WRITE_DATA      \
0467         | ARCHIVE_ENTRY_ACL_ADD_FILE        \
0468         | ARCHIVE_ENTRY_ACL_APPEND_DATA     \
0469         | ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY    \
0470         | ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS    \
0471         | ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS   \
0472         | ARCHIVE_ENTRY_ACL_DELETE_CHILD        \
0473         | ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES     \
0474         | ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES    \
0475         | ARCHIVE_ENTRY_ACL_DELETE          \
0476         | ARCHIVE_ENTRY_ACL_READ_ACL        \
0477         | ARCHIVE_ENTRY_ACL_WRITE_ACL       \
0478         | ARCHIVE_ENTRY_ACL_WRITE_OWNER     \
0479         | ARCHIVE_ENTRY_ACL_SYNCHRONIZE)
0480
0481 /*
0482  * Inheritance values (NFS4 ACLs only); included in permset.
0483  */
0484 #define ARCHIVE_ENTRY_ACL_ENTRY_INHERITED                   0x01000000
0485 #define ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT                0x02000000
0486 #define ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT           0x04000000
0487 #define ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT        0x08000000
0488 #define ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY                0x10000000
0489 #define ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS           0x20000000
0490 #define ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS               0x40000000
0491
0492 #define ARCHIVE_ENTRY_ACL_INHERITANCE_NFS4          \
0493     (ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT           \
0494         | ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT     \
0495         | ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT  \
0496         | ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY      \
0497         | ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS     \
0498         | ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS     \
0499         | ARCHIVE_ENTRY_ACL_ENTRY_INHERITED)
0500
0501 /* We need to be able to specify combinations of these. */
0502 #define ARCHIVE_ENTRY_ACL_TYPE_ACCESS   0x00000100  /* POSIX.1e only */
0503 #define ARCHIVE_ENTRY_ACL_TYPE_DEFAULT  0x00000200  /* POSIX.1e only */
0504 #define ARCHIVE_ENTRY_ACL_TYPE_ALLOW    0x00000400 /* NFS4 only */
0505 #define ARCHIVE_ENTRY_ACL_TYPE_DENY 0x00000800 /* NFS4 only */
0506 #define ARCHIVE_ENTRY_ACL_TYPE_AUDIT    0x00001000 /* NFS4 only */
0507 #define ARCHIVE_ENTRY_ACL_TYPE_ALARM    0x00002000 /* NFS4 only */
0508 #define ARCHIVE_ENTRY_ACL_TYPE_POSIX1E  (ARCHIVE_ENTRY_ACL_TYPE_ACCESS \
0509         | ARCHIVE_ENTRY_ACL_TYPE_DEFAULT)
0510 #define ARCHIVE_ENTRY_ACL_TYPE_NFS4 (ARCHIVE_ENTRY_ACL_TYPE_ALLOW \
0511         | ARCHIVE_ENTRY_ACL_TYPE_DENY \
0512         | ARCHIVE_ENTRY_ACL_TYPE_AUDIT \
0513         | ARCHIVE_ENTRY_ACL_TYPE_ALARM)
0514
0515 /* Tag values mimic POSIX.1e */
0516 #define ARCHIVE_ENTRY_ACL_USER      10001   /* Specified user. */
0517 #define ARCHIVE_ENTRY_ACL_USER_OBJ  10002   /* User who owns the file. */
0518 #define ARCHIVE_ENTRY_ACL_GROUP     10003   /* Specified group. */
0519 #define ARCHIVE_ENTRY_ACL_GROUP_OBJ 10004   /* Group who owns the file. */
0520 #define ARCHIVE_ENTRY_ACL_MASK      10005   /* Modify group access (POSIX.1e only) */
0521 #define ARCHIVE_ENTRY_ACL_OTHER     10006   /* Public (POSIX.1e only) */
0522 #define ARCHIVE_ENTRY_ACL_EVERYONE  10107   /* Everyone (NFS4 only) */
0523
0524 /*
0525  * Set the ACL by clearing it and adding entries one at a time.
0526  * Unlike the POSIX.1e ACL routines, you must specify the type
0527  * (access/default) for each entry.  Internally, the ACL data is just
0528  * a soup of entries.  API calls here allow you to retrieve just the
0529  * entries of interest.  This design (which goes against the spirit of
0530  * POSIX.1e) is useful for handling archive formats that combine
0531  * default and access information in a single ACL list.
0532  */
0533 __LA_DECL void   archive_entry_acl_clear(struct archive_entry *);
0534 __LA_DECL int    archive_entry_acl_add_entry(struct archive_entry *,
0535         int /* type */, int /* permset */, int /* tag */,
0536         int /* qual */, const char * /* name */);
0537 __LA_DECL int    archive_entry_acl_add_entry_w(struct archive_entry *,
0538         int /* type */, int /* permset */, int /* tag */,
0539         int /* qual */, const wchar_t * /* name */);
0540
0541 /*
0542  * To retrieve the ACL, first "reset", then repeatedly ask for the
0543  * "next" entry.  The want_type parameter allows you to request only
0544  * certain types of entries.
0545  */
0546 __LA_DECL int    archive_entry_acl_reset(struct archive_entry *, int /* want_type */);
0547 __LA_DECL int    archive_entry_acl_next(struct archive_entry *, int /* want_type */,
0548         int * /* type */, int * /* permset */, int * /* tag */,
0549         int * /* qual */, const char ** /* name */);
0550
0551 /*
0552  * Construct a text-format ACL.  The flags argument is a bitmask that
0553  * can include any of the following:
0554  *
0555  * Flags only for archive entries with POSIX.1e ACL:
0556  * ARCHIVE_ENTRY_ACL_TYPE_ACCESS - Include POSIX.1e "access" entries.
0557  * ARCHIVE_ENTRY_ACL_TYPE_DEFAULT - Include POSIX.1e "default" entries.
0558  * ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT - Include "default:" before each
0559  *    default ACL entry.
0560  * ARCHIVE_ENTRY_ACL_STYLE_SOLARIS - Output only one colon after "other" and
0561  *    "mask" entries.
0562  *
0563  * Flags only for archive entries with NFSv4 ACL:
0564  * ARCHIVE_ENTRY_ACL_STYLE_COMPACT - Do not output the minus character for
0565  *    unset permissions and flags in NFSv4 ACL permission and flag fields
0566  *
0567  * Flags for for archive entries with POSIX.1e ACL or NFSv4 ACL:
0568  * ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID - Include extra numeric ID field in
0569  *    each ACL entry.
0570  * ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA - Separate entries with comma
0571  *    instead of newline.
0572  */
0573 #define ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID    0x00000001
0574 #define ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT    0x00000002
0575 #define ARCHIVE_ENTRY_ACL_STYLE_SOLARIS     0x00000004
0576 #define ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA 0x00000008
0577 #define ARCHIVE_ENTRY_ACL_STYLE_COMPACT     0x00000010
0578
0579 __LA_DECL wchar_t *archive_entry_acl_to_text_w(struct archive_entry *,
0580         la_ssize_t * /* len */, int /* flags */);
0581 __LA_DECL char *archive_entry_acl_to_text(struct archive_entry *,
0582         la_ssize_t * /* len */, int /* flags */);
0583 __LA_DECL int archive_entry_acl_from_text_w(struct archive_entry *,
0584         const wchar_t * /* wtext */, int /* type */);
0585 __LA_DECL int archive_entry_acl_from_text(struct archive_entry *,
0586         const char * /* text */, int /* type */);
0587
0588 /* Deprecated constants */
0589 #define OLD_ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID        1024
0590 #define OLD_ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT    2048
0591
0592 /* Deprecated functions */
0593 __LA_DECL const wchar_t *archive_entry_acl_text_w(struct archive_entry *,
0594             int /* flags */) __LA_DEPRECATED;
0595 __LA_DECL const char *archive_entry_acl_text(struct archive_entry *,
0596             int /* flags */) __LA_DEPRECATED;
0597
0598 /* Return bitmask of ACL types in an archive entry */
0599 __LA_DECL int    archive_entry_acl_types(struct archive_entry *);
0600
0601 /* Return a count of entries matching 'want_type' */
0602 __LA_DECL int    archive_entry_acl_count(struct archive_entry *, int /* want_type */);
0603
0604 /* Return an opaque ACL object. */
0605 /* There's not yet anything clients can actually do with this... */
0606 struct archive_acl;
0607 __LA_DECL struct archive_acl *archive_entry_acl(struct archive_entry *);
0608
0609 /*
0610  * extended attributes
0611  */
0612
0613 __LA_DECL void   archive_entry_xattr_clear(struct archive_entry *);
0614 __LA_DECL void   archive_entry_xattr_add_entry(struct archive_entry *,
0615         const char * /* name */, const void * /* value */,
0616         size_t /* size */);
0617
0618 /*
0619  * To retrieve the xattr list, first "reset", then repeatedly ask for the
0620  * "next" entry.
0621  */
0622
0623 __LA_DECL int   archive_entry_xattr_count(struct archive_entry *);
0624 __LA_DECL int   archive_entry_xattr_reset(struct archive_entry *);
0625 __LA_DECL int   archive_entry_xattr_next(struct archive_entry *,
0626         const char ** /* name */, const void ** /* value */, size_t *);
0627
0628 /*
0629  * sparse
0630  */
0631
0632 __LA_DECL void   archive_entry_sparse_clear(struct archive_entry *);
0633 __LA_DECL void   archive_entry_sparse_add_entry(struct archive_entry *,
0634         la_int64_t /* offset */, la_int64_t /* length */);
0635
0636 /*
0637  * To retrieve the xattr list, first "reset", then repeatedly ask for the
0638  * "next" entry.
0639  */
0640
0641 __LA_DECL int   archive_entry_sparse_count(struct archive_entry *);
0642 __LA_DECL int   archive_entry_sparse_reset(struct archive_entry *);
0643 __LA_DECL int   archive_entry_sparse_next(struct archive_entry *,
0644         la_int64_t * /* offset */, la_int64_t * /* length */);
0645
0646 /*
0647  * Utility to match up hardlinks.
0648  *
0649  * The 'struct archive_entry_linkresolver' is a cache of archive entries
0650  * for files with multiple links.  Here's how to use it:
0651  *   1. Create a lookup object with archive_entry_linkresolver_new()
0652  *   2. Tell it the archive format you're using.
0653  *   3. Hand each archive_entry to archive_entry_linkify().
0654  *      That function will return 0, 1, or 2 entries that should
0655  *      be written.
0656  *   4. Call archive_entry_linkify(resolver, NULL) until
0657  *      no more entries are returned.
0658  *   5. Call archive_entry_linkresolver_free(resolver) to free resources.
0659  *
0660  * The entries returned have their hardlink and size fields updated
0661  * appropriately.  If an entry is passed in that does not refer to
0662  * a file with multiple links, it is returned unchanged.  The intention
0663  * is that you should be able to simply filter all entries through
0664  * this machine.
0665  *
0666  * To make things more efficient, be sure that each entry has a valid
0667  * nlinks value.  The hardlink cache uses this to track when all links
0668  * have been found.  If the nlinks value is zero, it will keep every
0669  * name in the cache indefinitely, which can use a lot of memory.
0670  *
0671  * Note that archive_entry_size() is reset to zero if the file
0672  * body should not be written to the archive.  Pay attention!
0673  */
0674 struct archive_entry_linkresolver;
0675
0676 /*
0677  * There are three different strategies for marking hardlinks.
0678  * The descriptions below name them after the best-known
0679  * formats that rely on each strategy:
0680  *
0681  * "Old cpio" is the simplest, it always returns any entry unmodified.
0682  *    As far as I know, only cpio formats use this.  Old cpio archives
0683  *    store every link with the full body; the onus is on the dearchiver
0684  *    to detect and properly link the files as they are restored.
0685  * "tar" is also pretty simple; it caches a copy the first time it sees
0686  *    any link.  Subsequent appearances are modified to be hardlink
0687  *    references to the first one without any body.  Used by all tar
0688  *    formats, although the newest tar formats permit the "old cpio" strategy
0689  *    as well.  This strategy is very simple for the dearchiver,
0690  *    and reasonably straightforward for the archiver.
0691  * "new cpio" is trickier.  It stores the body only with the last
0692  *    occurrence.  The complication is that we might not
0693  *    see every link to a particular file in a single session, so
0694  *    there's no easy way to know when we've seen the last occurrence.
0695  *    The solution here is to queue one link until we see the next.
0696  *    At the end of the session, you can enumerate any remaining
0697  *    entries by calling archive_entry_linkify(NULL) and store those
0698  *    bodies.  If you have a file with three links l1, l2, and l3,
0699  *    you'll get the following behavior if you see all three links:
0700  *           linkify(l1) => NULL   (the resolver stores l1 internally)
0701  *           linkify(l2) => l1     (resolver stores l2, you write l1)
0702  *           linkify(l3) => l2, l3 (all links seen, you can write both).
0703  *    If you only see l1 and l2, you'll get this behavior:
0704  *           linkify(l1) => NULL
0705  *           linkify(l2) => l1
0706  *           linkify(NULL) => l2   (at end, you retrieve remaining links)
0707  *    As the name suggests, this strategy is used by newer cpio variants.
0708  *    It's noticeably more complex for the archiver, slightly more complex
0709  *    for the dearchiver than the tar strategy, but makes it straightforward
0710  *    to restore a file using any link by simply continuing to scan until
0711  *    you see a link that is stored with a body.  In contrast, the tar
0712  *    strategy requires you to rescan the archive from the beginning to
0713  *    correctly extract an arbitrary link.
0714  */
0715
0716 __LA_DECL struct archive_entry_linkresolver *archive_entry_linkresolver_new(void);
0717 __LA_DECL void archive_entry_linkresolver_set_strategy(
0718     struct archive_entry_linkresolver *, int /* format_code */);
0719 __LA_DECL void archive_entry_linkresolver_free(struct archive_entry_linkresolver *);
0720 __LA_DECL void archive_entry_linkify(struct archive_entry_linkresolver *,
0721     struct archive_entry **, struct archive_entry **);
0722 __LA_DECL struct archive_entry *archive_entry_partial_links(
0723     struct archive_entry_linkresolver *res, unsigned int *links);
0724 #ifdef __cplusplus
0725 }
0726 #endif
0727
0728 /* This is meaningless outside of this header. */
0729 #undef __LA_DECL
0730
0731 #endif /* !ARCHIVE_ENTRY_H_INCLUDED */