4mARCHIVE_ENTRY_LINKIFY24m(3)	 Library Functions Manual  4mARCHIVE_ENTRY_LINKIFY24m(3)

1mNAME0m
       archive_entry_linkresolver,	       archive_entry_linkresolver_new,
       archive_entry_linkresolver_set_strategy,
       archive_entry_linkresolver_free, archive_entry_linkify —	 hardlink  re‐
       solver functions

1mLIBRARY0m
       Streaming Archive Library (libarchive, -larchive)

1mSYNOPSIS0m
       1m#include <archive_entry.h>0m

       4mstruct24m 4marchive_entry_linkresolver24m 4m*0m
       1marchive_entry_linkresolver_new22m(4mvoid24m);

       4mvoid0m
       1marchive_entry_linkresolver_set_strategy22m(4mstruct24m 4marchive_entry_linkresolver24m 4m*resolver24m,
	   4mint24m 4mformat24m);

       4mvoid0m
       1marchive_entry_linkresolver_free22m(4mstruct24m 4marchive_entry_linkresolver24m 4m*resolver24m);

       4mvoid0m
       1marchive_entry_linkify22m(4mstruct24m 4marchive_entry_linkresolver24m 4m*resolver24m,
	   4mstruct24m 4marchive_entry24m 4m**entry24m, 4mstruct24m 4marchive_entry24m 4m**sparse24m);

1mDESCRIPTION0m
       Programs	 that  want  to	 create	 archives have to deal with hardlinks.
       Hardlinks are handled in different ways by the  archive	formats.   The
       basic strategies are:

       1.   Ignore  hardlinks and store the body for each reference (old cpio,
	    zip).

       2.   Store the body the first time an inode is seen (ustar, pax).

       3.   Store the body the last time an inode is seen (new cpio).

       The 1marchive_entry_linkresolver 22mfunctions help by  providing	 a  unified
       interface and handling the complexity behind the scene.

       The  1marchive_entry_linkresolver 22mfunctions assume that 4marchive_entry24m in‐
       stances have valid nlinks, inode and device values.  The inode and  de‐
       vice  value  is used to match entries.  The nlinks value is used to de‐
       termined if all references have been found and if the  internal	refer‐
       ences can be recycled.

       The  1marchive_entry_linkresolver_new22m() function allocates a new link re‐
       solver.	     The      instance	    can	     be	     freed	 using
       1marchive_entry_linkresolver_free22m().	 All  deferred	entries are flushed
       and the internal storage is freed.

       The 1marchive_entry_linkresolver_set_strategy22m() function selects the	op‐
       timal  hardlink	strategy for the given format.	The format code can be
       obtained from 4marchive_format24m(3).  The function can be called more  than
       once, but it is recommended to flush all deferred entries first.

       The     1marchive_entry_linkify22m()	function    is	  the	 core	 of
       1marchive_entry_linkresolver22m.	  The  1mentry22m()  argument  points	to   the
       4marchive_entry24m that should be written.  Depending on the strategy one of
       the following actions is taken:

       1.   For	 the  simple  archive  formats	4m*entry24m  is left unmodified and
	    4m*sparse24m is set to NULL.

       2.   For tar like archive formats, 4m*sparse24m is set to NULL.	 If  4m*entry0m
	    is	NULL,  no action is taken.  If the hardlink count of 4m*entry24m is
	    larger than 1 and the file type is	a  regular  file  or  symbolic
	    link, the internal list is searched for a matching inode.  If such
	    an inode is found, the link count is decremented and the file size
	    of	4m*entry24m  is	 set to 0 to notify that no body should be written.
	    If no such inode is found, a copy of the entry is added to the in‐
	    ternal cache with a link count reduced by one.

       3.   For new cpio like archive formats a value for 4m*entry24m  of  NULL	 is
	    used  to flush deferred entries.  In that case 4m*entry24m is set to an
	    arbitrary deferred entry and the entry itself is removed from  the
	    internal  list.   If  the internal list is empty, 4m*entry24m is set to
	    NULL.  In either case, 4m*sparse24m is set to NULL and the function re‐
	    turns.  If the hardlink count of 4m*entry24m is one or the file type is
	    a directory or device, 4m*sparse24m is set to NULL and no  further	ac‐
	    tion  is  taken.   Otherwise,  the internal list is searched for a
	    matching inode.  If such an inode is not found, the entry is added
	    to the internal list, both 4m*entry24m and 4m*sparse24m are set to NULL  and
	    the	 function  returns.  If such an inode is found, the link count
	    is decremented.  If it remains larger than one, the existing entry
	    on the internal list is swapped with 4m*entry24m  after  retaining	the
	    link  count.   The	existing  entry is returned in 4m*entry24m.  If the
	    link count reached one, the new entry is also removed from the in‐
	    ternal list and returned in 4m*sparse24m.  Otherwise 4m*sparse24m is set  to
	    NULL.

       The general usage is therefore:

       1.   For each new archive entry, call 1marchive_entry_linkify22m().

       2.   Keep in mind that the entries returned may have a size of 0 now.

       3.   If 4m*entry24m is not NULL, archive it.

       4.   If 4m*sparse24m is not NULL, archive it.

       5.   After    all   entries   have   been   written   to	  disk,	  call
	    1marchive_entry_linkify22m() with 4m*entry24m set to NULL  and  archive  the
	    returned entry as long as it is not NULL.

1mRETURN VALUES0m
       1marchive_entry_linkresolver_new22m() returns NULL on 4mmalloc24m(3) failures.

1mSEE ALSO0m
       4marchive_entry24m(3)

Debian			       February 2, 2012	      4mARCHIVE_ENTRY_LINKIFY24m(3)