diff options
author | kientzle <kientzle@FreeBSD.org> | 2005-01-08 19:51:04 +0000 |
---|---|---|
committer | kientzle <kientzle@FreeBSD.org> | 2005-01-08 19:51:04 +0000 |
commit | 03cce8d9d572049df802a195d36cb41878a71009 (patch) | |
tree | 6c8bbe17328fd5e43120eb77084150652671750e /lib/libarchive/archive_write.3 | |
parent | 9bbb1dc91d20531dfeed610b7490a6db86f0049a (diff) | |
download | FreeBSD-src-03cce8d9d572049df802a195d36cb41878a71009.zip FreeBSD-src-03cce8d9d572049df802a195d36cb41878a71009.tar.gz |
Documentation improvements. In particular,
expand and clarify the description of the client
callback functions and how they should handle errors.
Thanks to: Antony Dovgal
Diffstat (limited to 'lib/libarchive/archive_write.3')
-rw-r--r-- | lib/libarchive/archive_write.3 | 78 |
1 files changed, 55 insertions, 23 deletions
diff --git a/lib/libarchive/archive_write.3 b/lib/libarchive/archive_write.3 index 337919b..033e8a5 100644 --- a/lib/libarchive/archive_write.3 +++ b/lib/libarchive/archive_write.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2003-2004 Tim Kientzle +.\" Copyright (c) 2003-2005 Tim Kientzle .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 1, 2003 +.Dd January 8, 2005 .Dt archive_write 3 .Os .Sh NAME @@ -198,38 +198,70 @@ Invokes .Fn archive_write_close if it wasn't invoked manually, then release all resources. .El -.Pp -The callback functions are defined as follows: +More information about the +.Va struct archive +object and the overall design of the library can be found in the +.Xr libarchive 3 +overview. +.Sh IMPLEMENTATION +Compression support is built-in to libarchive, which uses zlib and bzlib +to handle gzip and bzip2 compression, respectively. +.Sh CLIENT CALLBACKS +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 : .Bl -item -offset indent .It -.Ft typedef ssize_t -.Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length" -.It .Ft typedef int .Fn archive_open_archive_callback "struct archive *" "void *client_data" +.El +.Pp +The open callback is invoked by +.Fn archive_write_open . +It should return +.Cm ARCHIVE_OK +if the underlying file or data source is successfully +opened. +If the open fails, it should call +.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_close_archive_callback "struct archive *" "void *client_data" +.Ft typedef ssize_t +.Fn archive_write_archive_callback "struct archive *" "void *client_data" "void *buffer" "size_t length" .El +.Pp +The write callback is invoked whenever the library +needs to write raw bytes to the archive. For correct blocking, each call to the write callback function should translate into a single .Xr write 2 system call. -This is especially critical when writing tar archives to tape drives. -.Pp -More information about tar archive formats and blocking can be found -in the -.Xr tar 5 -manual page. +This is especially critical when writing archives to tape drives. +On success, the write callback should return the +number of bytes actually written. +On error, the callback should invoke +.Fn archive_set_error +to register an error code and message and return -1. +.Bl -item -offset indent +.It +.Ft typedef int +.Fn archive_close_archive_callback "struct archive *" "void *client_data" +.El .Pp -More information about the -.Va struct archive -object and the overall design of the library can be found in the -.Xr libarchive 3 -overview. -.Sh IMPLEMENTATION -Compression support is built-in to libarchive, which uses zlib and bzlib -to handle gzip and bzip2 compression, respectively. +The close callback is invoked by archive_close when +the archive processing is complete. +The callback should return +.Cm ARCHIVE_OK +on success. +On failure, the callback should invoke +.Fn archive_set_error +to register an error code and message and +regurn +.Cm ARCHIVE_FATAL. .Sh EXAMPLE The following sketch illustrates basic usage of the library. In this example, |