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. 69.It Fn archive_write_open_fd 70A convenience form of 71.Fn archive_write_open 72that accepts a file descriptor. 73The 74.Fn archive_write_open_fd 75function is safe for use with tape drives or other 76block-oriented devices. 77.It Fn archive_write_open_FILE 78A convenience form of 79.Fn archive_write_open 80that accepts a 81.Ft "FILE *" 82pointer. 83Note that 84.Fn archive_write_open_FILE 85is not safe for writing to tape drives or other devices 86that require correct blocking. 87.It Fn archive_write_open_file 88A deprecated synonym for 89.Fn archive_write_open_filename . 90.It Fn archive_write_open_filename 91A convenience form of 92.Fn archive_write_open 93that accepts a filename. 94A NULL argument indicates that the output should be written to standard output; 95an argument of 96.Dq - 97will open a file with that name. 98If you have not invoked 99.Fn archive_write_set_bytes_in_last_block , 100then 101.Fn archive_write_open_filename 102will adjust the last-block padding depending on the file: 103it will enable padding when writing to standard output or 104to a character or block device node, it will disable padding otherwise. 105You can override this by manually invoking 106.Fn archive_write_set_bytes_in_last_block 107before calling 108.Fn archive_write_open . 109The 110.Fn archive_write_open_filename 111function is safe for use with tape drives or other 112block-oriented devices. 113.It Fn archive_write_open_memory 114A convenience form of 115.Fn archive_write_open 116that accepts a pointer to a block of memory that will receive 117the archive. 118The final 119.Ft "size_t *" 120argument points to a variable that will be updated 121after each write to reflect how much of the buffer 122is currently in use. 123You should be careful to ensure that this variable 124remains allocated until after the archive is 125closed. 126.El 127More information about the 128.Va struct archive 129object and the overall design of the library can be found in the 130.Xr libarchive 3 131overview. 132.\" 133.Sh CLIENT CALLBACKS 134To use this library, you will need to define and register 135callback functions that will be invoked to write data to the 136resulting archive. 137These functions are registered by calling 138.Fn archive_write_open : 139.Bl -item -offset indent 140.It 141.Ft typedef int 142.Fn archive_open_callback "struct archive *" "void *client_data" 143.El 144.Pp 145The open callback is invoked by 146.Fn archive_write_open . 147It should return 148.Cm ARCHIVE_OK 149if the underlying file or data source is successfully 150opened. 151If the open fails, it should call 152.Fn archive_set_error 153to register an error code and message and return 154.Cm ARCHIVE_FATAL . 155.Bl -item -offset indent 156.It 157.Ft typedef ssize_t 158.Fo archive_write_callback 159.Fa "struct archive *" 160.Fa "void *client_data" 161.Fa "const void *buffer" 162.Fa "size_t length" 163.Fc 164.El 165.Pp 166The write callback is invoked whenever the library 167needs to write raw bytes to the archive. 168For correct blocking, each call to the write callback function 169should translate into a single 170.Xr write 2 171system call. 172This is especially critical when writing archives to tape drives. 173On success, the write callback should return the 174number of bytes actually written. 175On error, the callback should invoke 176.Fn archive_set_error 177to register an error code and message and return -1. 178.Bl -item -offset indent 179.It 180.Ft typedef int 181.Fn archive_close_callback "struct archive *" "void *client_data" 182.El 183.Pp 184The close callback is invoked by archive_close when 185the archive processing is complete. 186The callback should return 187.Cm ARCHIVE_OK 188on success. 189On failure, the callback should invoke 190.Fn archive_set_error 191to register an error code and message and 192return 193.Cm ARCHIVE_FATAL. 194.Pp 195Note that if the client-provided write callback function 196returns a non-zero value, that error will be propagated back to the caller 197through whatever API function resulted in that call, which 198may include 199.Fn archive_write_header , 200.Fn archive_write_data , 201.Fn archive_write_close , 202.Fn archive_write_finish , 203or 204.Fn archive_write_free . 205The client callback can call 206.Fn archive_set_error 207to provide values that can then be retrieved by 208.Fn archive_errno 209and 210.Fn archive_error_string . 211.\" .Sh EXAMPLE 212.Sh RETURN VALUES 213These functions return 214.Cm ARCHIVE_OK 215on success, or 216.Cm ARCHIVE_FATAL . 217.\" 218.Sh ERRORS 219Detailed error codes and textual descriptions are available from the 220.Fn archive_errno 221and 222.Fn archive_error_string 223functions. 224.\" 225.Sh SEE ALSO 226.Xr tar 1 , 227.Xr libarchive 3 , 228.Xr archive_write 3 , 229.Xr archive_write_filter 3 , 230.Xr archive_write_format 3 , 231.Xr archive_write_new 3 , 232.Xr archive_write_set_options 3 , 233.Xr cpio 5 , 234.Xr mtree 5 , 235.Xr tar 5 236