From: Roman Neuhauser <neuhauser@sigpipe.cz>
Date: Mon, 28 Mar 2011 09:19:08 +0000 (-0400)
Subject: archive_errno, archive_error_string info in man pages unified a bit
X-Git-Tag: v3.0.0a~571
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f74c5f05faccec9b0946faa3f3fbe41fab276a26;p=thirdparty%2Flibarchive.git

archive_errno, archive_error_string info in man pages unified a bit

SVN-Revision: 3107
---

diff --git a/libarchive/archive_read_data.3 b/libarchive/archive_read_data.3
index 9896c9694..a5898e7b8 100644
--- a/libarchive/archive_read_data.3
+++ b/libarchive/archive_read_data.3
@@ -111,11 +111,6 @@ The possible return codes include:
 and
 .Cm ARCHIVE_FATAL
 (there was a fatal error; the archive should be closed immediately).
-Detailed error codes and textual descriptions are available from the
-.Fn archive_errno
-and
-.Fn archive_error_string
-functions.
 .Pp
 .Fn archive_read_data
 returns a count of bytes actually read or zero at the end of the entry.
@@ -124,12 +119,15 @@ On error, a value of
 .Cm ARCHIVE_WARN ,
 or
 .Cm ARCHIVE_RETRY
-is returned and an error code and textual description can be retrieved from the
+is returned.
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_read_disk.3 b/libarchive/archive_read_disk.3
index 2c9c4e53d..d3b6101d7 100644
--- a/libarchive/archive_read_disk.3
+++ b/libarchive/archive_read_disk.3
@@ -237,15 +237,6 @@ for operations that might succeed if retried,
 for unusual conditions that do not prevent further operations, and
 .Cm ARCHIVE_FATAL
 for serious errors that make remaining operations impossible.
-The
-.Xr archive_errno 3
-and
-.Xr archive_error_string 3
-functions can be used to retrieve an appropriate error code and a
-textual error message.
-(See
-.Xr archive_util 3
-for details.)
 .Pp
 .Fn archive_read_disk_new
 returns a pointer to a newly-allocated
@@ -261,9 +252,17 @@ pointers to the textual name or NULL if the lookup failed for any reason.
 The returned pointer points to internal storage that
 may be reused on the next call to either of these functions;
 callers should copy the string if they need to continue accessing it.
-.Pp
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.\"
 .Sh SEE ALSO
 .Xr archive_read 3 ,
+.Xr archive_util 3 ,
 .Xr archive_write 3 ,
 .Xr archive_write_disk 3 ,
 .Xr tar 1 ,
diff --git a/libarchive/archive_read_extract.3 b/libarchive/archive_read_extract.3
index 1f9f13d05..950248e07 100644
--- a/libarchive/archive_read_extract.3
+++ b/libarchive/archive_read_extract.3
@@ -116,13 +116,12 @@ The possible return codes include:
 and
 .Cm ARCHIVE_FATAL
 (there was a fatal error; the archive should be closed immediately).
-.Pp
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_read_filter.3 b/libarchive/archive_read_filter.3
index bf514cf1a..7b506ccc2 100644
--- a/libarchive/archive_read_filter.3
+++ b/libarchive/archive_read_filter.3
@@ -111,15 +111,14 @@ if the compression is supported only through an external program.
 .Pp
 .Fn archive_read_support_filter_none
 always succeeds.
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
 .\"
-.\" .Sh ERRORS
-.\"
 .Sh SEE ALSO
 .Xr libarchive 3 ,
 .Xr archive_read 3 ,
diff --git a/libarchive/archive_read_format.3 b/libarchive/archive_read_format.3
index 4fde5b925..b33d714ef 100644
--- a/libarchive/archive_read_format.3
+++ b/libarchive/archive_read_format.3
@@ -100,13 +100,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_read_free.3 b/libarchive/archive_read_free.3
index 1d6fa1b91..5838e20c9 100644
--- a/libarchive/archive_read_free.3
+++ b/libarchive/archive_read_free.3
@@ -72,13 +72,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr libarchive 3 ,
 .Xr archive_read_new 3 ,
diff --git a/libarchive/archive_read_header.3 b/libarchive/archive_read_header.3
index 4879ffd3e..f8543f7ac 100644
--- a/libarchive/archive_read_header.3
+++ b/libarchive/archive_read_header.3
@@ -67,13 +67,14 @@ These functions return
 and
 .Cm ARCHIVE_FATAL
 (there was a fatal error; the archive should be closed immediately).
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_read_open.3 b/libarchive/archive_read_open.3
index 847a624b4..ff156416f 100644
--- a/libarchive/archive_read_open.3
+++ b/libarchive/archive_read_open.3
@@ -211,25 +211,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.Pp
-The library expects the client callbacks to behave similarly.
-If there is an error, you can use
-.Fn archive_set_error
-to set an appropriate error code and description,
-then return one of the non-zero values above.
-(Note that the value eventually returned to the client may
-not be the same; many errors that are not critical at the level
-of basic I/O can prevent the archive from being properly read,
-thus most I/O errors eventually cause
-.Cm ARCHIVE_FATAL
-to be returned.)
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_read_set_options.3 b/libarchive/archive_read_set_options.3
index 7ddb00b70..2079d2e26 100644
--- a/libarchive/archive_read_set_options.3
+++ b/libarchive/archive_read_set_options.3
@@ -192,6 +192,14 @@ Defaults to enabled, use
 to disable.
 .El
 .El
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_blocksize.3 b/libarchive/archive_write_blocksize.3
index 10ec249ff..239fa922a 100644
--- a/libarchive/archive_write_blocksize.3
+++ b/libarchive/archive_write_blocksize.3
@@ -95,12 +95,14 @@ indicates the default block size
 .Pc ,
 or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_data.3 b/libarchive/archive_write_data.3
index c773400d9..2c98b3e78 100644
--- a/libarchive/archive_write_data.3
+++ b/libarchive/archive_write_data.3
@@ -42,12 +42,14 @@ Write data corresponding to the header just written.
 This function returns the number of bytes actually written, or
 .Li -1
 on error.
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_disk.3 b/libarchive/archive_write_disk.3
index 708ed3110..90bbdcf95 100644
--- a/libarchive/archive_write_disk.3
+++ b/libarchive/archive_write_disk.3
@@ -289,12 +289,6 @@ for operations that might succeed if retried,
 for unusual conditions that do not prevent further operations, and
 .Cm ARCHIVE_FATAL
 for serious errors that make remaining operations impossible.
-The
-.Fn archive_errno
-and
-.Fn archive_error_string
-functions can be used to retrieve an appropriate error code and a
-textual error message.
 .Pp
 .Fn archive_write_disk_new
 returns a pointer to a newly-allocated
@@ -302,12 +296,18 @@ returns a pointer to a newly-allocated
 object.
 .Pp
 .Fn archive_write_data
-returns a count of the number of bytes actually written.
-On error, -1 is returned and the
+returns a count of the number of bytes actually written,
+or
+.Li -1
+on error.
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
-functions will return appropriate values.
+functions.
+.\"
 .Sh SEE ALSO
 .Xr archive_read 3 ,
 .Xr archive_write 3 ,
diff --git a/libarchive/archive_write_filter.3 b/libarchive/archive_write_filter.3
index cd2474ae6..f084a51db 100644
--- a/libarchive/archive_write_filter.3
+++ b/libarchive/archive_write_filter.3
@@ -79,12 +79,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_finish_entry.3 b/libarchive/archive_write_finish_entry.3
index 4b80f762f..06c002ebe 100644
--- a/libarchive/archive_write_finish_entry.3
+++ b/libarchive/archive_write_finish_entry.3
@@ -56,12 +56,14 @@ for operations that might succeed if retried,
 for unusual conditions that do not prevent further operations, and
 .Cm ARCHIVE_FATAL
 for serious errors that make remaining operations impossible.
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_format.3 b/libarchive/archive_write_format.3
index 3ef0d3252..b3e7e3535 100644
--- a/libarchive/archive_write_format.3
+++ b/libarchive/archive_write_format.3
@@ -80,12 +80,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_free.3 b/libarchive/archive_write_free.3
index fdd0aa013..d939780dd 100644
--- a/libarchive/archive_write_free.3
+++ b/libarchive/archive_write_free.3
@@ -64,13 +64,14 @@ These functions return
 .Cm ARCHIVE_OK
 on success, or
 .Cm ARCHIVE_FATAL .
-.Pp
+.\"
+.Sh ERRORS
 Detailed error codes and textual descriptions are available from the
 .Fn archive_errno
 and
 .Fn archive_error_string
 functions.
-.\" .Sh ERRORS
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_header.3 b/libarchive/archive_write_header.3
index 0e759148d..f76175b0f 100644
--- a/libarchive/archive_write_header.3
+++ b/libarchive/archive_write_header.3
@@ -54,6 +54,14 @@ for operations that might succeed if retried,
 for unusual conditions that do not prevent further operations, and
 .Cm ARCHIVE_FATAL
 for serious errors that make remaining operations impossible.
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_open.3 b/libarchive/archive_write_open.3
index 4e03b19c1..ab2d4841c 100644
--- a/libarchive/archive_write_open.3
+++ b/libarchive/archive_write_open.3
@@ -189,18 +189,6 @@ On failure, the callback should invoke
 to register an error code and message and
 return
 .Cm ARCHIVE_FATAL.
-.\" .Sh EXAMPLE
-.Sh RETURN VALUES
-These functions return
-.Cm ARCHIVE_OK
-on success, or
-.Cm ARCHIVE_FATAL .
-.Pp
-Detailed error codes and textual descriptions are available from the
-.Fn archive_errno
-and
-.Fn archive_error_string
-functions.
 .Pp
 Note that if the client-provided write callback function
 returns a non-zero value, that error will be propagated back to the caller
@@ -218,6 +206,20 @@ to provide values that can then be retrieved by
 .Fn archive_errno
 and
 .Fn archive_error_string .
+.\" .Sh EXAMPLE
+.Sh RETURN VALUES
+These functions return
+.Cm ARCHIVE_OK
+on success, or
+.Cm ARCHIVE_FATAL .
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
diff --git a/libarchive/archive_write_set_options.3 b/libarchive/archive_write_set_options.3
index c0a73b9d0..7e5cf212b 100644
--- a/libarchive/archive_write_set_options.3
+++ b/libarchive/archive_write_set_options.3
@@ -412,6 +412,14 @@ archive_write_set_format_iso9660(a);
 archive_write_set_options(a, "boot=kernel.img,compression=9");
 archive_write_open_filename(a, filename, blocksize);
 .Ed
+.\"
+.Sh ERRORS
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.\"
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,