d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document the new _open_FILE() and _open_memory() interfaces.

Browse Source 
PR: bin/86742
This commit is contained in:
kientzle 2006-11-24 05:34:23 +00:00
parent 2dc265a00d
commit ea391351c9
3 changed files with 75 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
lib/libarchive/archive_read.3
View File

@ -43,7 +43,9 @@
.Nm archive_read_open ,
.Nm archive_read_open2 ,
.Nm archive_read_open_fd ,
.Nm archive_read_open_FILE ,
.Nm archive_read_open_filename ,
.Nm archive_read_open_memory ,
.Nm archive_read_next_header ,
.Nm archive_read_data ,
.Nm archive_read_data_block ,
@ -86,10 +88,14 @@
.Ft int
.Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
.Ft int
.Fn archive_read_open_FILE "struct archive *" "FILE *file"
.Ft int
.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
.Ft int
.Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size"
.Ft int
.Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
.Ft int
.Fn archive_read_next_header "struct archive *" "struct archive_entry **"
.Ft ssize_t
.Fn archive_read_data "struct archive *" "void *buff" "size_t len"
@ -158,12 +164,22 @@ Freeze the settings, open the archive, and prepare for reading entries.
This is the most generic version of this call, which accepts
four callback functions.
Most clients will want to use
.Fn archive_read_open_filename
.Fn archive_read_open_filename ,
.Fn archive_read_open_FILE ,
.Fn archive_read_open_fd ,
or
.Fn archive_read_open_fd
.Fn archive_read_open_memory
instead.
The library invokes the client-provided functions to obtain
raw bytes from the archive.
.It Fn archive_read_open_FILE
Like
.Fn archive_read_open ,
except that it accepts a
.Ft "FILE *"
pointer.
This function should not be used with tape drives or other devices
that require strict I/O blocking.
.It Fn archive_read_open_fd
Like
.Fn archive_read_open ,
@ -181,6 +197,11 @@ Like
except that it accepts a simple filename and a block size.
A NULL filename represents standard input.
This function is safe for use with tape drives or other blocked devices.
.It Fn archive_read_open_memory
Like
.Fn archive_read_open ,
except that it accepts a pointer and size of a block of
memory containing the archive data.
.It Fn archive_read_next_header
Read the header for the next entry and return a pointer to
a

46
lib/libarchive/archive_write.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2003-2005 Tim Kientzle
.\" Copyright (c) 2003-2006 Tim Kientzle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 8, 2005
.Dd August 19, 2006
.Dt archive_write 3
.Os
.Sh NAME
@ -41,7 +41,9 @@
.Nm archive_write_set_compressor_bzip2 ,
.Nm archive_write_open ,
.Nm archive_write_open_fd ,
.Nm archive_write_open_FILE ,
.Nm archive_write_open_filename ,
.Nm archive_write_open_memory ,
.Nm archive_write_header ,
.Nm archive_write_data ,
.Nm archive_write_close ,
@ -76,8 +78,12 @@
.Ft int
.Fn archive_write_open_fd "struct archive *" "int fd"
.Ft int
.Fn archive_write_open_FILE "struct archive *" "FILE *file"
.Ft int
.Fn archive_write_open_filename "struct archive *" "const char *filename"
.Ft int
.Fn archive_write_open_memory "struct archive *" "void *buffer" "size_t bufferSize" "size_t *outUsed"
.Ft int
.Fn archive_write_header "struct archive *" "struct archive_entry *"
.Ft int
.Fn archive_write_data "struct archive *" "const void *" "size_t"
@ -155,15 +161,24 @@ 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 archive.
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.)
.It Fn archive_write_open_fd
A convenience form of
.Fn archive_write_open
that accepts a file descriptor.
The
.Fn archive_write_open_fd
function is safe for use with tape drives or other
block-oriented devices.
.It Fn archive_write_open_FILE
A convenience form of
.Fn archive_write_open
that accepts a
.Ft "FILE *"
pointer.
Note that
.Fn archive_write_open_FILE
is not safe for writing to tape drives or other devices
that require correct blocking.
.It Fn archive_write_open_file
A deprecated synonym for
.Fn archive_write_open_filename .
@ -186,6 +201,23 @@ You can override this by manually invoking
.Fn archive_write_set_bytes_in_last_block
either before or after calling
.Fn archive_write_open .
The
.Fn archive_write_open_filename
function is safe for use with tape drives or other
block-oriented devices.
.It Fn archive_write_open_memory
A convenience form of
.Fn archive_write_open
that accepts a pointer to a block of memory that will receive
the archive.
The final
.Ft "size_t *"
argument points to a variable that will be updated
after each write to reflect how much of the buffer
is currently in use.
You should be careful to ensure that this variable
remains allocated until after the archive is
closed.
.It Fn archive_write_header
Build and write a header using the data in the provided
.Tn struct archive_entry

15
lib/libarchive/libarchive.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2003-2005 Tim Kientzle
.\" Copyright (c) 2003-2006 Tim Kientzle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 8, 2005
.Dd August 19, 2006
.Dt LIBARCHIVE 3
.Os
.Sh NAME
@ -138,6 +138,17 @@ Once you have prepared the
object, you call
.Fn archive_read_open
to actually open the archive and prepare it for reading.
There are several variants of this function;
the most basic expects you to provide pointers to several
functions that can provide blocks of bytes from the archive.
There are convenience forms that allow you to
specify a filename, file descriptor,
.Ft "FILE *"
object, or a block of memory from which to read the archive data.
Note that the core library makes no assumptions about the
size of the blocks read;
callback functions are free to read whatever block size is
most appropriate for the medium.
.Pp
Each archive entry consists of a header followed by a certain
amount of data.