1 .\" Copyright (c) 2010 Joerg Sonnenberger
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .Dt ARCHIVE_ENTRY_LINKIFY 3
29 .Nm archive_entry_linkresolver ,
30 .Nm archive_entry_linkresolver_new ,
31 .Nm archive_entry_linkresolver_set_strategy ,
32 .Nm archive_entry_linkresolver_free ,
33 .Nm archive_entry_linkify
34 .Nd hardlink resolver functions
36 Streaming Archive Library (libarchive, -larchive)
39 .Ft struct archive_entry_linkresolver *
40 .Fn archive_entry_linkresolver_new void
42 .Fo archive_entry_linkresolver_set_strategy
43 .Fa "struct archive_entry_linkresolver *resolver"
47 .Fo archive_entry_linkresolver_free
48 .Fa "struct archive_entry_linkresolver *resolver"
51 .Fo archive_entry_linkify
52 .Fa "struct archive_entry_linkresolver *resolver"
53 .Fa "struct archive_entry **entry"
54 .Fa "struct archive_entry **sparse"
57 Programs that want to create archives have to deal with hardlinks.
58 Hardlinks are handled in different ways by the archive formats.
59 The basic strategies are:
62 Ignore hardlinks and store the body for each reference (old cpio, zip).
64 Store the body the first time an inode is seen (ustar, pax).
66 Store the body the last time an inode is seen (new cpio).
71 functions help by providing a unified interface and handling the complexity
78 instances have valid nlinks, inode and device values.
79 The inode and device value is used to match entries.
80 The nlinks value is used to determined if all references have been found and
81 if the internal references can be recycled.
84 .Fn archive_entry_linkresolver_new
85 function allocates a new link resolver.
86 The instance can be freed using
87 .Fn archive_entry_linkresolver_free .
88 All deferred entries are flushed and the internal storage is freed.
91 .Fn archive_entry_linkresolver_set_strategy
92 function selects the optimal hardlink strategy for the given format.
93 The format code can be obtained from
94 .Xr archive_format 3 .
95 The function can be called more than once, but it is recommended to
96 flush all deferred entries first.
99 .Fn archive_entry_linkify
100 function is the core of
104 argument points to the
106 that should be written.
107 Depending on the strategy one of the following actions is taken:
110 For the simple archive formats
112 is left unmodified and
117 For tar like archive formats,
126 If the hardlink count of
128 is larger than 1 and the file type is a regular file or symbolic link,
129 the internal list is searched for a matching inode.
130 If such an inode is found, the link count is decremented and the file size
133 is set to 0 to notify that no body should be written.
134 If no such inode is found, a copy of the entry is added to the internal cache
135 with a link count reduced by one.
137 For new cpio like archive formats a value for
141 is used to flush deferred entries.
144 is set to an arbitrary deferred entry and the entry itself is removed from the
146 If the internal list is empty,
154 and the function returns.
155 If the hardlink count of
157 is one or the file type is a directory or device,
161 and no further action is taken.
162 Otherwise, the internal list is searched for a matching inode.
163 If such an inode is not found, the entry is added to the internal list,
170 and the function returns.
171 If such an inode is found, the link count is decremented.
172 If it remains larger than one, the existing entry on the internal list
175 after retaining the link count.
176 The existing entry is returned in
178 If the link count reached one, the new entry is also removed from the
179 internal list and returned in
187 The general usage is therefore:
190 For each new archive entry, call
191 .Fn archive_entry_linkify .
193 Keep in mind that the entries returned may have a size of 0 now.
207 After all entries have been written to disk, call
208 .Fn archive_entry_linkify
213 and archive the returned entry as long as it is not
217 .Fn archive_entry_linkresolver_new