Introduce archive_write_open2() with free callback

The archive_write_open() function does not provide a free callback.
Freeing was done by the close callback. When the open callback fails,
the client filter is left in ARCHIVE_WRITE_FILTER_STATE_FATAL,
the close callback is not called and unfreed resources may be left behind.

Fixes #1456

1 files changed, 18 insertions, 9 deletions

diff --git a/libarchive/archive_write_open.3 b/libarchive/archive_write_open.3
index 0129d10b..2f6e6270 100644
--- a/libarchive/archive_write_open.3
+++ b/libarchive/archive_write_open.3
@@ -28,7 +28,7 @@
 .Dt ARCHIVE_WRITE_OPEN 3
 .Os
 .Sh NAME
-.Nm archive_write_open ,
+.Nm archive_write_open2 ,
 .Nm archive_write_open_fd ,
 .Nm archive_write_open_FILE ,
 .Nm archive_write_open_filename ,
@@ -39,12 +39,13 @@ Streaming Archive Library (libarchive, -larchive)
 .Sh SYNOPSIS
 .In archive.h
 .Ft int
-.Fo archive_write_open
+.Fo archive_write_open2
 .Fa "struct archive *"
 .Fa "void *client_data"
 .Fa "archive_open_callback *"
 .Fa "archive_write_callback *"
 .Fa "archive_close_callback *"
+.Fa "archive_free_callback *"
 .Fc
 .Ft int
 .Fn archive_write_open_fd "struct archive *" "int fd"
@@ -61,10 +62,10 @@ Streaming Archive Library (libarchive, -larchive)
 .Fc
 .Sh DESCRIPTION
 .Bl -tag -width indent
-.It Fn archive_write_open
+.It Fn archive_write_open2
 Freeze the settings, open the archive, and prepare for writing entries.
 This is the most generic form of this function, which accepts
-pointers to three callback functions which will be invoked by
+pointers to four callback functions which will be invoked by
 the compression layer to write the constructed archive.
 This does not alter the default archive padding.
 .It Fn archive_write_open_fd
@@ -106,14 +107,14 @@ to a character or block device node, it will disable padding otherwise.
 You can override this by manually invoking
 .Fn archive_write_set_bytes_in_last_block
 before calling
-.Fn archive_write_open .
+.Fn archive_write_open2 .
 The
 .Fn archive_write_open_filename
 function is safe for use with tape drives or other
 block-oriented devices.
 .It Fn archive_write_open_memory
 A convenience form of
-.Fn archive_write_open
+.Fn archive_write_open2
 that accepts a pointer to a block of memory that will receive
 the archive.
 The final
@@ -145,7 +146,7 @@ To use this library, you will need to define and register
 callback functions that will be invoked to write data to the
 resulting archive.
 These functions are registered by calling
-.Fn archive_write_open :
+.Fn archive_write_open2 :
 .Bl -item -offset indent
 .It
 .Ft typedef int
@@ -192,7 +193,8 @@ to register an error code and message and return -1.
 .El
 .Pp
 The close callback is invoked by archive_close when
-the archive processing is complete.
+the archive processing is complete. If the open callback fails, the close
+callback is not invoked.
 The callback should return
 .Cm ARCHIVE_OK
 on success.
@@ -200,7 +202,14 @@ On failure, the callback should invoke
 .Fn archive_set_error
 to register an error code and message and
 return
-.Cm ARCHIVE_FATAL .
+.Bl -item -offset indent
+.It
+.Ft typedef int
+.Fn archive_free_callback "struct archive *" "void *client_data"
+.El
+.Pp
+The free callback is always invoked on archive_free.
+The return code of this callback is not processed.
 .Pp
 Note that if the client-provided write callback function
 returns a non-zero value, that error will be propagated back to the caller