1.\" Copyright (c) 2003-2011 Tim Kientzle 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd November 12, 2020 28.Dt ARCHIVE_WRITE_OPEN 3 29.Os 30.Sh NAME 31.Nm archive_write_open , 32.Nm archive_write_open2 , 33.Nm archive_write_open_fd , 34.Nm archive_write_open_FILE , 35.Nm archive_write_open_filename , 36.Nm archive_write_open_memory 37.Nd functions for creating archives 38.Sh LIBRARY 39Streaming Archive Library (libarchive, -larchive) 40.Sh SYNOPSIS 41.In archive.h 42.Ft int 43.Fo archive_write_open 44.Fa "struct archive *" 45.Fa "void *client_data" 46.Fa "archive_open_callback *" 47.Fa "archive_write_callback *" 48.Fa "archive_close_callback *" 49.Fc 50.Ft int 51.Fo archive_write_open2 52.Fa "struct archive *" 53.Fa "void *client_data" 54.Fa "archive_open_callback *" 55.Fa "archive_write_callback *" 56.Fa "archive_close_callback *" 57.Fa "archive_free_callback *" 58.Fc 59.Ft int 60.Fn archive_write_open_fd "struct archive *" "int fd" 61.Ft int 62.Fn archive_write_open_FILE "struct archive *" "FILE *file" 63.Ft int 64.Fn archive_write_open_filename "struct archive *" "const char *filename" 65.Ft int 66.Fo archive_write_open_memory 67.Fa "struct archive *" 68.Fa "void *buffer" 69.Fa "size_t bufferSize" 70.Fa "size_t *outUsed" 71.Fc 72.Sh DESCRIPTION 73.Bl -tag -width indent 74.It Fn archive_write_open 75Freeze the settings, open the archive, and prepare for writing entries. 76This is the most generic form of this function, which accepts 77pointers to three callback functions which will be invoked by 78the compression layer to write the constructed archive. 79This does not alter the default archive padding. 80.It Fn archive_write_open2 81Same as 82.Fn archive_write_open 83with an additional fourth free callback. This function should be preferred to 84.Fn archive_write_open . 85.It Fn archive_write_open_fd 86A convenience form of 87.Fn archive_write_open 88that accepts a file descriptor. 89The 90.Fn archive_write_open_fd 91function is safe for use with tape drives or other 92block-oriented devices. 93.It Fn archive_write_open_FILE 94A convenience form of 95.Fn archive_write_open 96that accepts a 97.Ft "FILE *" 98pointer. 99Note that 100.Fn archive_write_open_FILE 101is not safe for writing to tape drives or other devices 102that require correct blocking. 103.It Fn archive_write_open_file 104A deprecated synonym for 105.Fn archive_write_open_filename . 106.It Fn archive_write_open_filename 107A convenience form of 108.Fn archive_write_open 109that accepts a filename. 110A NULL argument indicates that the output should be written to standard output; 111an argument of 112.Dq - 113will open a file with that name. 114If you have not invoked 115.Fn archive_write_set_bytes_in_last_block , 116then 117.Fn archive_write_open_filename 118will adjust the last-block padding depending on the file: 119it will enable padding when writing to standard output or 120to a character or block device node, it will disable padding otherwise. 121You can override this by manually invoking 122.Fn archive_write_set_bytes_in_last_block 123before calling 124.Fn archive_write_open2 . 125The 126.Fn archive_write_open_filename 127function is safe for use with tape drives or other 128block-oriented devices. 129.It Fn archive_write_open_memory 130A convenience form of 131.Fn archive_write_open2 132that accepts a pointer to a block of memory that will receive 133the archive. 134The final 135.Ft "size_t *" 136argument points to a variable that will be updated 137after each write to reflect how much of the buffer 138is currently in use. 139You should be careful to ensure that this variable 140remains allocated until after the archive is 141closed. 142This function will disable padding unless you 143have specifically set the block size. 144.El 145More information about the 146.Va struct archive 147object and the overall design of the library can be found in the 148.Xr libarchive 3 149overview. 150.Pp 151Note that the convenience forms above vary in how 152they block the output. 153See 154.Xr archive_write_blocksize 3 155if you need to control the block size used for writes 156or the end-of-file padding behavior. 157.\" 158.Sh CLIENT CALLBACKS 159To use this library, you will need to define and register 160callback functions that will be invoked to write data to the 161resulting archive. 162These functions are registered by calling 163.Fn archive_write_open2 : 164.Bl -item -offset indent 165.It 166.Ft typedef int 167.Fn archive_open_callback "struct archive *" "void *client_data" 168.El 169.Pp 170The open callback is invoked by 171.Fn archive_write_open . 172It should return 173.Cm ARCHIVE_OK 174if the underlying file or data source is successfully 175opened. 176If the open fails, it should call 177.Fn archive_set_error 178to register an error code and message and return 179.Cm ARCHIVE_FATAL . 180Please note that if open fails, close is not called and resources must be 181freed inside the open callback or with the free callback. 182.Bl -item -offset indent 183.It 184.Ft typedef la_ssize_t 185.Fo archive_write_callback 186.Fa "struct archive *" 187.Fa "void *client_data" 188.Fa "const void *buffer" 189.Fa "size_t length" 190.Fc 191.El 192.Pp 193The write callback is invoked whenever the library 194needs to write raw bytes to the archive. 195For correct blocking, each call to the write callback function 196should translate into a single 197.Xr write 2 198system call. 199This is especially critical when writing archives to tape drives. 200On success, the write callback should return the 201number of bytes actually written. 202On error, the callback should invoke 203.Fn archive_set_error 204to register an error code and message and return -1. 205.Bl -item -offset indent 206.It 207.Ft typedef int 208.Fn archive_close_callback "struct archive *" "void *client_data" 209.El 210.Pp 211The close callback is invoked by archive_close when 212the archive processing is complete. If the open callback fails, the close 213callback is not invoked. 214The callback should return 215.Cm ARCHIVE_OK 216on success. 217On failure, the callback should invoke 218.Fn archive_set_error 219to register an error code and message and 220return 221.Bl -item -offset indent 222.It 223.Ft typedef int 224.Fn archive_free_callback "struct archive *" "void *client_data" 225.El 226.Pp 227The free callback is always invoked on archive_free. 228The return code of this callback is not processed. 229.Pp 230Note that if the client-provided write callback function 231returns a non-zero value, that error will be propagated back to the caller 232through whatever API function resulted in that call, which 233may include 234.Fn archive_write_header , 235.Fn archive_write_data , 236.Fn archive_write_close , 237.Fn archive_write_finish , 238or 239.Fn archive_write_free . 240The client callback can call 241.Fn archive_set_error 242to provide values that can then be retrieved by 243.Fn archive_errno 244and 245.Fn archive_error_string . 246.\" .Sh EXAMPLE 247.Sh RETURN VALUES 248These functions return 249.Cm ARCHIVE_OK 250on success, or 251.Cm ARCHIVE_FATAL . 252.\" 253.Sh ERRORS 254Detailed error codes and textual descriptions are available from the 255.Fn archive_errno 256and 257.Fn archive_error_string 258functions. 259.\" 260.Sh SEE ALSO 261.Xr tar 1 , 262.Xr archive_write 3 , 263.Xr archive_write_blocksize 3 , 264.Xr archive_write_filter 3 , 265.Xr archive_write_format 3 , 266.Xr archive_write_new 3 , 267.Xr archive_write_set_options 3 , 268.Xr libarchive 3 , 269.Xr cpio 5 , 270.Xr mtree 5 , 271.Xr tar 5 272