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> &mdash; 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&lt;archive_entry.h&gt;</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&nbsp;archive_entry_linkresolver&nbsp;*resolver</i>,
56<i>int&nbsp;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&nbsp;archive_entry_linkresolver&nbsp;*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&nbsp;archive_entry_linkresolver&nbsp;*resolver</i>,
67<i>struct&nbsp;archive_entry&nbsp;**entry</i>,
68<i>struct&nbsp;archive_entry&nbsp;**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&nbsp;2, 2012 BSD</p>
210<hr>
211</body>
212</html>
213