contrib/libarchive/libarchive/archive_entry.3

   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 .\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.18 2008/05/26 17:00:22 kientzle Exp $
  27 .\"
  28 .Dd Feburary 22, 2010
  29 .Dt ARCHIVE_ENTRY 3
  30 .Os
  31 .Sh NAME
  32 .Nm archive_entry_clear ,
  33 .Nm archive_entry_clone ,
  34 .Nm archive_entry_free ,
  35 .Nm archive_entry_new ,
  36 .Nd functions for managing archive entry descriptions
  37 .Sh SYNOPSIS
  38 .In archive_entry.h
  39 .Ft "struct archive_entry *"
  40 .Fn archive_entry_clear "struct archive_entry *"
  41 .Ft struct archive_entry *
  42 .Fn archive_entry_clone "struct archive_entry *"
  43 .Ft void
  44 .Fn archive_entry_free "struct archive_entry *"
  45 .Ft struct archive_entry *
  46 .Fn archive_entry_new "void"
  47 .Sh DESCRIPTION
  48 These functions create and manipulate data objects that
  49 represent entries within an archive.
  50 You can think of a
  51 .Tn struct archive_entry
  52 as a heavy-duty version of
  53 .Tn struct stat :
  54 it includes everything from
  55 .Tn struct stat
  56 plus associated pathname, textual group and user names, etc.
  57 These objects are used by
  58 .Xr libarchive 3
  59 to represent the metadata associated with a particular
  60 entry in an archive.
  61 .Ss Create and Destroy
  62 There are functions to allocate, destroy, clear, and copy
  63 .Va archive_entry
  64 objects:
  65 .Bl -tag -compact -width indent
  66 .It Fn archive_entry_clear
  67 Erases the object, resetting all internal fields to the
  68 same state as a newly-created object.
  69 This is provided to allow you to quickly recycle objects
  70 without thrashing the heap.
  71 .It Fn archive_entry_clone
  72 A deep copy operation; all text fields are duplicated.
  73 .It Fn archive_entry_free
  74 Releases the
  75 .Tn struct archive_entry
  76 object.
  77 .It Fn archive_entry_new
  78 Allocate and return a blank
  79 .Tn struct archive_entry
  80 object.
  81 .El
  82 .Ss Function groups
  83 Due to high number of functions, the accessor functions can be found in
  84 man pages grouped by the purpose.
  85 .Bl -tag -width ".Xr archive_entry_perms 3"
  86 .It Xr archive_entry_acl 3
  87 Access Control List manipulation
  88 .It Xr archive_entry_paths 3
  89 Path name manipulation
  90 .It Xr archive_entry_perms 3
  91 User, group and mode manipulation
  92 .It Xr archive_entry_stat 3
  93 Functions not in the other groups and copying to/from
  94 .Vt struct stat .
  95 .It Xr archive_entry_time 3
  96 Time field manipulation
  97 .El
  98 .Pp
  99 Most of the functions set or read entries in an object.
 100 Such functions have one of the following forms:
 101 .Bl -tag -compact -width indent
 102 .It Fn archive_entry_set_XXXX
 103 Stores the provided data in the object.
 104 In particular, for strings, the pointer is stored,
 105 not the referenced string.
 106 .It Fn archive_entry_copy_XXXX
 107 As above, except that the referenced data is copied
 108 into the object.
 109 .It Fn archive_entry_XXXX
 110 Returns the specified data.
 111 In the case of strings, a const-qualified pointer to
 112 the string is returned.
 113 .El
 114 String data can be set or accessed as wide character strings
 115 or normal
 116 .Va char
 117 strings.
 118 The functions that use wide character strings are suffixed with
 119 .Cm _w .
 120 Note that these are different representations of the same data:
 121 For example, if you store a narrow string and read the corresponding
 122 wide string, the object will transparently convert formats
 123 using the current locale.
 124 Similarly, if you store a wide string and then store a
 125 narrow string for the same data, the previously-set wide string will
 126 be discarded in favor of the new data.
 127 .Pp
 128 .\" .Sh EXAMPLE
 129 .\" .Sh RETURN VALUES
 130 .\" .Sh ERRORS
 131 .Sh SEE ALSO
 132 .Xr archive 3 ,
 133 .Xr archive_entry_acl 3 ,
 134 .Xr archive_entry_paths 3 ,
 135 .Xr archive_entry_perms 3 ,
 136 .Xr archive_entry_time 3
 137 .Sh HISTORY
 138 The
 139 .Nm libarchive
 140 library first appeared in
 141 .Fx 5.3 .
 142 .Sh AUTHORS
 143 .An -nosplit
 144 The
 145 .Nm libarchive
 146 library was written by
 147 .An Tim Kientzle Aq kientzle@acm.org .
 148 .\" .Sh BUGS