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