Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
archive_write(3)       FreeBSD Library Functions Manual	      archive_write(3)

NAME
     archive_write_new,	archive_write_set_format_cpio,
     archive_write_set_format_pax, archive_write_set_format_pax_restricted,
     archive_write_set_format_shar, archive_write_set_format_shar_binary,
     archive_write_set_format_ustar, archive_write_set_bytes_per_block,
     archive_write_set_bytes_in_last_block, archive_write_set_compressor_gzip,
     archive_write_set_compressor_bzip2, archive_write_open,
     archive_write_open_fd, archive_write_open_file, archive_write_prepare,
     archive_write_header, archive_write_data, archive_write_close,
     archive_write_finish -- functions for creating archives

SYNOPSIS
     #include <archive.h>

     struct archive *
     archive_write_new(void);

     int
     archive_write_set_bytes_per_block(archive *, int bytes_per_block);

     int
     archive_write_set_bytes_in_last_block(archive *, int);

     int
     archive_write_set_compressor_gzip(struct archive *);

     int
     archive_write_set_compressor_bzip2(struct archive *);

     int
     archive_write_set_format_cpio(struct archive *);

     int
     archive_write_set_format_pax(struct archive *);

     int
     archive_write_set_format_pax_restricted(struct archive *);

     int
     archive_write_set_format_shar(struct archive *);

     int
     archive_write_set_format_shar_binary(struct archive *);

     int
     archive_write_set_format_ustar(struct archive *);

     int
     archive_write_open(struct archive *, void *client_data,
	 archive_write_archive_callback	*, archive_open_archive_callback *,
	 archive_close_archive_callback	*);

     int
     archive_write_open_fd(struct archive *, int fd);

     int
     archive_write_open_file(struct archive *, const char *filename);

     int
     archive_write_header(struct archive *);

     int
     archive_write_data(struct archive *, const	void *,	size_t);

     int
     archive_write_close(struct	archive	*);

     void
     archive_write_finish(struct archive *);

DESCRIPTION
     These functions provide a complete	API for	creating streaming archive
     files.  The general process is to first create the	struct archive object,
     set any desired options, initialize the archive, append entries, then
     close the archive and release all resources.  The following summary
     describes the functions in	approximately the order	they are ordinarily
     used:

     archive_write_new()
	     Allocates and initializes a struct	archive	object suitable	for
	     writing a tar archive.

     archive_write_set_bytes_per_block()
	     Sets the block size used for writing the archive data.  Every
	     call to the write callback	function, except possibly the last
	     one, will use this	value for the length.  The third parameter is
	     a boolean that specifies whether or not the final block written
	     will be padded to the full	block size.  If	it is zero, the	last
	     block will	not be padded.	If it is non-zero, padding will	be
	     added both	before and after compression.  The default is to use a
	     block size	of 10240 bytes and to pad the last block.

     archive_write_set_bytes_in_last_block()
	     Sets the block size used for writing the last block.  If this
	     value is zero, the	last block will	be padded to the same size as
	     the other blocks.	Otherwise, the final block will	be padded to a
	     multiple of this size.  In	particular, setting it to 1 will cause
	     the final block to	not be padded.	For compressed output, any
	     padding generated by this option is applied only after the	com-
	     pression.	The uncompressed data is always	unpadded.  The default
	     is	to pad the last	block to the full block	size (note that
	     archive_write_open_file() will set	this based on the file type).
	     Unlike the	other ``set'' functions, this function can be called
	     after the archive is opened.

     archive_write_set_format_cpio(), archive_write_set_format_pax(),
	     archive_write_set_format_pax_restricted(),
	     archive_write_set_format_shar(),
	     archive_write_set_format_shar_binary(),
	     archive_write_set_format_ustar()
	     Sets the format that will be used for the archive.	 The library
	     can write POSIX octet-oriented cpio format	archives, POSIX-stan-
	     dard ``pax	interchange'' format archives, traditional ``shar''
	     archives, enhanced	``binary'' shar	archives that store a variety
	     of	file attributes	and handle binary files, and POSIX-standard
	     ``ustar'' archives.  The pax interchange format is	a backwards-
	     compatible	tar format that	adds key/value attributes to each
	     entry and supports	arbitrary filenames, linknames,	uids, sizes,
	     etc.  ``Restricted	pax interchange	format'' is the	library
	     default; this is the same as pax format, but suppresses the pax
	     extended header for most normal files.  In	most cases, this will
	     result in ordinary	ustar archives.

     archive_write_set_compression_gzip(),
	     archive_write_set_compression_bzip2()
	     The resulting archive will	be compressed as specified.  Note that
	     the compressed output is always properly blocked.

     archive_write_open()
	     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	the compression	layer to write the constructed ar-
	     chive.  In	order to support external compression programs,	the
	     compression is permitted to fork and invoke the callbacks from a
	     separate process.	In particular, clients should not assume that
	     they can communicate between the callbacks	and the	mainline code
	     using shared variables.  (The standard gzip, bzip2, and "none"
	     compression methods do not	fork.)

     archive_write_open_fd()
	     A convenience form	of archive_write_open()	that accepts a file
	     descriptor.

     archive_write_open_file()
	     A convenience form	of archive_write_open()	that accepts a file-
	     name.  A NULL argument indicates that the output should be	writ-
	     ten to standard output; an	argument of ``-'' will open a file
	     with that name.  If you have not invoked
	     archive_write_set_bytes_in_last_block(), then
	     archive_write_open_file() will adjust the last-block padding
	     depending on the file: it will enable padding when	writing	to
	     standard output or	to a character or block	device node, it	will
	     disable padding otherwise.	 You can override this by manually
	     invoking archive_write_set_bytes_in_last_block() either before or
	     after calling archive_write_open().

     archive_write_header()
	     Build and write a header using the	data in	the provided struct
	     archive_entry structure.

     archive_write_data()
	     Write data	corresponding to the header just written.

     archive_write_close()
	     Complete the archive and invoke the close callback.

     archive_write_finish()
	     Invokes archive_write_close() if it wasn't	invoked	manually, then
	     release all resources.

     The callback functions are	defined	as follows:

	   typedef ssize_t archive_write_archive_callback(struct archive *,
	   void	*client_data, void *buffer, size_t length)

	   typedef int archive_open_archive_callback(struct archive *, void
	   *client_data)

	   typedef int archive_close_archive_callback(struct archive *,	void
	   *client_data)
     For correct blocking, each	call to	the write callback function should
     translate into a single write(2) system call.  This is especially criti-
     cal when writing tar archives to tape drives.

     More information about tar	archive	formats	and blocking can be found in
     the tar(5)	manual page.

     More information about the	struct archive object and the overall design
     of	the library can	be found in the	libarchive(3) overview.

IMPLEMENTATION
     Compression support is built-in to	libarchive, which uses zlib and	bzlib
     to	handle gzip and	bzip2 compression, respectively.

EXAMPLE
     The following sketch illustrates basic usage of the library.  In this
     example, the callback functions are simply	wrappers around	the standard
     open(2), write(2),	and close(2) system calls.

	   void
	   write_archive(const char **filename)
	   {
	     struct mydata *mydata = malloc(sizeof(struct mydata));
	     struct archive *a;
	     struct archive_entry *entry;
	     struct stat st;
	     char buff[8192];
	     int len;

	     a = archive_write_new();
	     mydata->name = name;
	     archive_write_set_compression_gzip(a);
	     archive_write_set_format_ustar(a);
	     archive_write_open(a, mydata, myopen, mywrite, myclose);
	     while (*filename) {
	       stat(*filename, &st);
	       entry = archive_entry_new();
	       archive_entry_copy_stat(entry, &st);
	       archive_entry_set_pathname(entry, *filename);
	       archive_write_header(a, entry);
	       fd = open(*filename, O_RDONLY);
	       len = read(fd, buff, sizeof(buff));
	       while ( len >= 0	) {
		   archive_write_data(a, buff, len);
		   len = read(fd, buff,	sizeof(buff));
	       }
	       archive_entry_free(entry);
	       filename++;
	     }
	     archive_write_finish(a);
	   }

	   int
	   myopen(struct archive *a, void *client_data)
	   {
	     struct mydata *mydata = client_data;

	     mydata->fd	= open(mydata->name, O_WRONLY |	O_CREAT, 0644);
	     return (mydata->fd	>= 0);
	   }

	   ssize_t
	   mywrite(struct archive *a, void *client_data, void *buff, size_t n)
	   {
	     struct mydata *mydata = client_data;

	     return (write(mydata->fd, buff, n));
	   }

	   int
	   myclose(struct archive *a, void *client_data)
	   {
	     struct mydata *mydata = client_data;

	     if	(mydata->fd > 0)
	       close(mydata->fd);
	     return (0);
	   }

RETURN VALUES
     Most functions return zero	on success, non-zero on	error.	The
     archive_errno() and archive_error_string()	functions can be used to
     retrieve an appropriate error code	and a textual error message.

     archive_write_new() returns a pointer to a	newly-allocated	struct archive
     object.

     archive_write_data() returns a count of the number	of bytes actually
     written.  On error, -1 is returned	and the	archive_errno()	and
     archive_error_string() functions will return appropriate values.  Note
     that if the client-provided write callback	function returns -1, that
     error will	be propagated back to the caller through whatever API function
     resulted in that call, which may include archive_write_header(),
     archive_write_data(), or archive_write_close().  In such a	case, the
     archive_errno() or	archive_error_string() fields will not return useful
     information; you should use client-private	data to	return error informa-
     tion back to your mainline	code.

SEE ALSO
     tar(1), libarchive(3), tar(5)

HISTORY
     The libarchive library first appeared in FreeBSD 5.3.

AUTHORS
     The libarchive library was	written	by Tim Kientzle	<kientzle@acm.org>.

BUGS
     There are many peculiar bugs in historic tar implementations that may
     cause certain programs to reject archives written by this library.	 For
     example, several historic implementations calculated header checksums
     incorrectly and will thus reject valid archives; GNU tar does not fully
     support pax interchange format; some old tar implementations required
     specific field terminations.

     The default pax interchange format	eliminates most	of the historic	tar
     limitations and provides a	generic	key/value attribute facility for ven-
     dor-defined extensions.  One oversight in POSIX is	the failure to provide
     a standard	attribute for large device numbers.  This library uses
     ``SCHILY.devminor'' and ``SCHILY.devmajor'' for device numbers that
     exceed the	range supported	by the backwards-compatible ustar header.
     These keys	are compatible with Joerg Schilling's star archiver.  Other
     implementations may not recognize these keys and will thus	be unable to
     correctly restore large device numbers archived by	this library.

FreeBSD	9.2			October	1, 2003			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION | EXAMPLE | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=archive_write&sektion=3&manpath=FreeBSD+5.3-RELEASE>

home | help