1<!-- Creator : groff version 1.22.4 --> 2<!-- CreationDate: Sun Aug 22 23:03:24 2021 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title></title> 17</head> 18<body> 19 20<hr> 21 22 23<p>ARCHIVE_ENTRY_LINKIFY(3) BSD Library Functions Manual 24ARCHIVE_ENTRY_LINKIFY(3)</p> 25 26<p style="margin-top: 1em"><b>NAME</b></p> 27 28 29<p style="margin-left:6%;"><b>archive_entry_linkresolver</b>, 30<b>archive_entry_linkresolver_new</b>, 31<b>archive_entry_linkresolver_set_strategy</b>, 32<b>archive_entry_linkresolver_free</b>, 33<b>archive_entry_linkify</b> — hardlink resolver 34functions</p> 35 36<p style="margin-top: 1em"><b>LIBRARY</b></p> 37 38<p style="margin-left:6%;">Streaming Archive Library 39(libarchive, -larchive)</p> 40 41<p style="margin-top: 1em"><b>SYNOPSIS</b></p> 42 43<p style="margin-left:6%;"><b>#include 44<archive_entry.h></b></p> 45 46<p style="margin-left:6%; margin-top: 1em"><i>struct 47archive_entry_linkresolver *</i></p> 48 49 50<p style="margin-left:12%;"><b>archive_entry_linkresolver_new</b>(<i>void</i>);</p> 51 52<p style="margin-left:6%; margin-top: 1em"><i>void</i></p> 53 54 55<p><b>archive_entry_linkresolver_set_strategy</b>(<i>struct archive_entry_linkresolver *resolver</i>, 56<i>int format</i>);</p> 57 58<p style="margin-left:6%; margin-top: 1em"><i>void</i></p> 59 60 61<p><b>archive_entry_linkresolver_free</b>(<i>struct archive_entry_linkresolver *resolver</i>);</p> 62 63<p style="margin-left:6%; margin-top: 1em"><i>void</i></p> 64 65 66<p><b>archive_entry_linkify</b>(<i>struct archive_entry_linkresolver *resolver</i>, 67<i>struct archive_entry **entry</i>, 68<i>struct archive_entry **sparse</i>);</p> 69 70<p style="margin-top: 1em"><b>DESCRIPTION</b></p> 71 72<p style="margin-left:6%;">Programs that want to create 73archives have to deal with hardlinks. Hardlinks are handled 74in different ways by the archive formats. The basic 75strategies are:</p> 76 77<p style="margin-top: 1em">1.</p> 78 79<p style="margin-left:13%;">Ignore hardlinks and store the 80body for each reference (old cpio, zip).</p> 81 82<p style="margin-top: 1em">2.</p> 83 84<p style="margin-left:13%;">Store the body the first time 85an inode is seen (ustar, pax).</p> 86 87<p style="margin-top: 1em">3.</p> 88 89<p style="margin-left:13%;">Store the body the last time an 90inode is seen (new cpio).</p> 91 92<p style="margin-left:6%; margin-top: 1em">The 93<b>archive_entry_linkresolver</b> functions help by 94providing a unified interface and handling the complexity 95behind the scene.</p> 96 97<p style="margin-left:6%; margin-top: 1em">The 98<b>archive_entry_linkresolver</b> functions assume that 99<i>archive_entry</i> instances have valid nlinks, inode and 100device values. The inode and device value is used to match 101entries. The nlinks value is used to determined if all 102references have been found and if the internal references 103can be recycled.</p> 104 105<p style="margin-left:6%; margin-top: 1em">The 106<b>archive_entry_linkresolver_new</b>() function allocates a 107new link resolver. The instance can be freed using 108<b>archive_entry_linkresolver_free</b>(). All deferred 109entries are flushed and the internal storage is freed.</p> 110 111<p style="margin-left:6%; margin-top: 1em">The 112<b>archive_entry_linkresolver_set_strategy</b>() function 113selects the optimal hardlink strategy for the given format. 114The format code can be obtained from archive_format(3). The 115function can be called more than once, but it is recommended 116to flush all deferred entries first.</p> 117 118<p style="margin-left:6%; margin-top: 1em">The 119<b>archive_entry_linkify</b>() function is the core of 120<b>archive_entry_linkresolver</b>. The <b>entry</b>() 121argument points to the <i>archive_entry</i> that should be 122written. Depending on the strategy one of the following 123actions is taken:</p> 124 125<p style="margin-top: 1em">1.</p> 126 127<p style="margin-left:13%;">For the simple archive formats 128<i>*entry</i> is left unmodified and <i>*sparse</i> is set 129to NULL.</p> 130 131<p style="margin-top: 1em">2.</p> 132 133<p style="margin-left:13%;">For tar like archive formats, 134<i>*sparse</i> is set to NULL. If <i>*entry</i> is NULL, no 135action is taken. If the hardlink count of <i>*entry</i> is 136larger than 1 and the file type is a regular file or 137symbolic link, the internal list is searched for a matching 138inode. If such an inode is found, the link count is 139decremented and the file size of <i>*entry</i> is set to 0 140to notify that no body should be written. If no such inode 141is found, a copy of the entry is added to the internal cache 142with a link count reduced by one.</p> 143 144<p style="margin-top: 1em">3.</p> 145 146<p style="margin-left:13%;">For new cpio like archive 147formats a value for <i>*entry</i> of NULL is used to flush 148deferred entries. In that case <i>*entry</i> is set to an 149arbitrary deferred entry and the entry itself is removed 150from the internal list. If the internal list is empty, 151<i>*entry</i> is set to NULL. In either case, <i>*sparse</i> 152is set to NULL and the function returns. If the hardlink 153count of <i>*entry</i> is one or the file type is a 154directory or device, <i>*sparse</i> is set to NULL and no 155further action is taken. Otherwise, the internal list is 156searched for a matching inode. If such an inode is not 157found, the entry is added to the internal list, both 158<i>*entry</i> and <i>*sparse</i> are set to NULL and the 159function returns. If such an inode is found, the link count 160is decremented. If it remains larger than one, the existing 161entry on the internal list is swapped with <i>*entry</i> 162after retaining the link count. The existing entry is 163returned in <i>*entry</i>. If the link count reached one, 164the new entry is also removed from the internal list and 165returned in <i>*sparse</i>. Otherwise <i>*sparse</i> is set 166to NULL.</p> 167 168<p style="margin-left:6%; margin-top: 1em">The general 169usage is therefore:</p> 170 171<p style="margin-top: 1em">1.</p> 172 173<p style="margin-left:13%;">For each new archive entry, 174call <b>archive_entry_linkify</b>().</p> 175 176<p style="margin-top: 1em">2.</p> 177 178<p style="margin-left:13%;">Keep in mind that the entries 179returned may have a size of 0 now.</p> 180 181<p style="margin-top: 1em">3.</p> 182 183<p style="margin-left:13%;">If <i>*entry</i> is not NULL, 184archive it.</p> 185 186<p style="margin-top: 1em">4.</p> 187 188<p style="margin-left:13%;">If <i>*sparse</i> is not NULL, 189archive it.</p> 190 191<p style="margin-top: 1em">5.</p> 192 193<p style="margin-left:13%;">After all entries have been 194written to disk, call <b>archive_entry_linkify</b>() with 195<i>*entry</i> set to NULL and archive the returned entry as 196long as it is not NULL.</p> 197 198<p style="margin-top: 1em"><b>RETURN VALUES</b></p> 199 200 201<p style="margin-left:6%;"><b>archive_entry_linkresolver_new</b>() 202returns NULL on malloc(3) failures.</p> 203 204<p style="margin-top: 1em"><b>SEE ALSO</b></p> 205 206<p style="margin-left:6%;">archive_entry(3)</p> 207 208<p style="margin-left:6%; margin-top: 1em">BSD 209February 2, 2012 BSD</p> 210<hr> 211</body> 212</html> 213