contrib/libarchive/libarchive/archive_read_header.3

   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_READ_HEADER 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_read_next_header ,
  32 .Nm archive_read_next_header2
  33 .Nd functions for reading streaming archives
  34 .Sh LIBRARY
  35 Streaming Archive Library (libarchive, -larchive)
  36 .Sh SYNOPSIS
  37 .In archive.h
  38 .Ft int
  39 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
  40 .Ft int
  41 .Fn archive_read_next_header2 "struct archive *" "struct archive_entry *"
  42 .\"
  43 .Sh DESCRIPTION
  44 .Bl -tag -compact -width indent
  45 .It Fn archive_read_next_header
  46 Read the header for the next entry and return a pointer to
  47 a
  48 .Tn struct archive_entry .
  49 This is a convenience wrapper around
  50 .Fn archive_read_next_header2
  51 that reuses an internal
  52 .Tn struct archive_entry
  53 object for each request.
  54 .It Fn archive_read_next_header2
  55 Read the header for the next entry and populate the provided
  56 .Tn struct archive_entry .
  57 .El
  58 .\"
  59 .Sh RETURN VALUES
  60 These functions return
  61 .Cm ARCHIVE_OK
  62 (the operation succeeded),
  63 .Cm ARCHIVE_WARN
  64 (the operation succeeded but a non-critical error was encountered),
  65 .Cm ARCHIVE_EOF
  66 (end-of-archive was encountered),
  67 .Cm ARCHIVE_RETRY
  68 (the operation failed but can be retried),
  69 and
  70 .Cm ARCHIVE_FATAL
  71 (there was a fatal error; the archive should be closed immediately).
  72 .\"
  73 .Sh ERRORS
  74 Detailed error codes and textual descriptions are available from the
  75 .Fn archive_errno
  76 and
  77 .Fn archive_error_string
  78 functions.
  79 .\"
  80 .Sh SEE ALSO
  81 .Xr tar 1 ,
  82 .Xr archive_read 3 ,
  83 .Xr archive_read_data 3 ,
  84 .Xr archive_read_extract 3 ,
  85 .Xr archive_read_filter 3 ,
  86 .Xr archive_read_format 3 ,
  87 .Xr archive_read_open 3 ,
  88 .Xr archive_read_set_options 3 ,
  89 .Xr archive_util 3 ,
  90 .Xr libarchive 3 ,
  91 .Xr tar 5