retro-imager/dependencies/libarchive-3.5.2/doc/wiki/ManPageArchiveEntry3.wiki

ARCHIVE_ENTRY(3) manual page 
== NAME == 
'''archive_entry_clear''', 
'''archive_entry_clone''', 
'''archive_entry_free''', 
'''archive_entry_new''' 
- functions for managing archive entry descriptions 
== LIBRARY == 
Streaming Archive Library (libarchive, -larchive) 
== SYNOPSIS == 
'''<nowiki>#include <archive_entry.h></nowiki>''' 
<br> 
''struct archive_entry *'' 
<br> 
'''archive_entry_clear'''(''struct archive_entry *''); 
<br> 
''struct archive_entry *'' 
<br> 
'''archive_entry_clone'''(''struct archive_entry *''); 
<br> 
''void'' 
<br> 
'''archive_entry_free'''(''struct archive_entry *''); 
<br> 
''struct archive_entry *'' 
<br> 
'''archive_entry_new'''(''void''); 
== DESCRIPTION == 
These functions create and manipulate data objects that 
represent entries within an archive. 
You can think of a 
'''struct archive_entry''' 
as a heavy-duty version of 
'''struct stat :''' 
it includes everything from 
'''struct stat''' 
plus associated pathname, textual group and user names, etc. 
These objects are used by 
[[ManPageLibarchive3]] 
to represent the metadata associated with a particular 
entry in an archive. 
=== Create and Destroy=== 
There are functions to allocate, destroy, clear, and copy 
''archive_entry'' 
objects: 
<dl> 
<dt>'''archive_entry_clear'''()</dt><dd> 
Erases the object, resetting all internal fields to the 
same state as a newly-created object. 
This is provided to allow you to quickly recycle objects 
without thrashing the heap. 
</dd><dt>'''archive_entry_clone'''()</dt><dd> 
A deep copy operation; all text fields are duplicated. 
</dd><dt>'''archive_entry_free'''()</dt><dd> 
Releases the 
'''struct archive_entry''' 
object. 
</dd><dt>'''archive_entry_new'''()</dt><dd> 
Allocate and return a blank 
'''struct archive_entry''' 
object. 
</dd></dl> 
=== Function groups=== 
Due to high number of functions, the accessor functions can be found in 
man pages grouped by the purpose. 
<dl> 
<dt>[[ManPageArchiveEntryAcl3]]</dt><dd> 
Access Control List manipulation 
</dd><dt>[[ManPageArchiveEntryPaths3]]</dt><dd> 
Path name manipulation 
</dd><dt>[[ManPageArchiveEntryPerms3]]</dt><dd> 
User, group and mode manipulation 
</dd><dt>[[ManPageArchiveEntryStat3]]</dt><dd> 
Functions not in the other groups and copying to/from 
''struct'' stat. 
</dd><dt>[[ManPageArchiveEntryTime3]]</dt><dd> 
Time field manipulation 
</dd></dl> 

Most of the functions set or read entries in an object. 
Such functions have one of the following forms: 
<dl> 
<dt>'''archive_entry_set_XXXX'''()</dt><dd> 
Stores the provided data in the object. 
In particular, for strings, the pointer is stored, 
not the referenced string. 
</dd><dt>'''archive_entry_copy_XXXX'''()</dt><dd> 
As above, except that the referenced data is copied 
into the object. 
</dd><dt>'''archive_entry_XXXX'''()</dt><dd> 
Returns the specified data. 
In the case of strings, a const-qualified pointer to 
the string is returned. 
</dd></dl> 
String data can be set or accessed as wide character strings 
or normal 
''char'' 
strings. 
The functions that use wide character strings are suffixed with 
'''_w'''. 
Note that these are different representations of the same data: 
For example, if you store a narrow string and read the corresponding 
wide string, the object will transparently convert formats 
using the current locale. 
Similarly, if you store a wide string and then store a 
narrow string for the same data, the previously-set wide string will 
be discarded in favor of the new data. 
== SEE ALSO == 
[[ManPageArchiveEntryAcl3]], 
[[ManPageArchiveEntryPaths3]], 
[[ManPageArchiveEntryPerms3]], 
[[ManPageArchiveEntryTime3]], 
[[ManPageLibarchive3]] 
== HISTORY == 
The 
'''libarchive''' 
library first appeared in 
FreeBSD 5.3. 
== AUTHORS == 
The 
'''libarchive''' 
library was written by 
Tim Kientzle  &lt;kientzle@acm.org.&gt;