tweak transport error handling in Linux; sg_compare_and_write: add examples section to its manpage; testing

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@866 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 19 insertions, 13 deletions

diff --git a/include/sg_io_linux.h b/include/sg_io_linux.h
index 4766e2ae..7b3567cd 100644
--- a/include/sg_io_linux.h
+++ b/include/sg_io_linux.h
@@ -2,7 +2,7 @@
 #define SG_IO_LINUX_H
 
 /*
- * Copyright (c) 2004-2018 Douglas Gilbert.
+ * Copyright (c) 2004-2020 Douglas Gilbert.
  * All rights reserved.
  * Use of this source code is governed by a BSD-style
  * license that can be found in the BSD_LICENSE file.
@@ -11,7 +11,7 @@
  */
 
 /*
- * Version 1.07 [20181211]
+ * Version 1.08 [20201102]
  */
 
 /*
@@ -145,18 +145,20 @@ void sg_print_host_status(int host_status);
 void sg_print_driver_status(int driver_status);
 
 /* sg_chk_n_print() returns 1 quietly if there are no errors/warnings
-   else it prints errors/warnings (prefixed by 'leadin') to
-   'sg_warnings_fd' and returns 0. raw_sinfo indicates whether the
-   raw sense buffer (in ASCII hex) should be printed. */
+ * else it prints errors/warnings (prefixed by 'leadin') to
+ * 'sg_warnings_fd' and returns 0. raw_sinfo indicates whether the
+ * raw sense buffer (in ASCII hex) should be printed. */
 int sg_chk_n_print(const char * leadin, int masked_status, int host_status,
                    int driver_status, const uint8_t * sense_buffer,
                    int sb_len, bool raw_sinfo);
 
 /* The following function declaration is for the sg version 3 driver. */
 struct sg_io_hdr;
+
 /* sg_chk_n_print3() returns 1 quietly if there are no errors/warnings;
-   else it prints errors/warnings (prefixed by 'leadin') to
-   'sg_warnings_fd' and returns 0. */
+ * else it prints errors/warnings (prefixed by 'leadin') to
+ * 'sg_warnings_fd' and returns 0. For sg_io_v4 interface use
+ * sg_linux_sense_print() instead. */
 int sg_chk_n_print3(const char * leadin, struct sg_io_hdr * hp,
                     bool raw_sinfo);
 
@@ -169,25 +171,29 @@ int sg_linux_sense_print(const char * leadin, int scsi_status,
                          bool raw_sinfo);
 
 /* Calls sg_scsi_normalize_sense() after obtaining the sense buffer and
-   its length from the struct sg_io_hdr pointer. If these cannot be
-   obtained, false is returned. */
+ * its length from the struct sg_io_hdr pointer. If these cannot be
+ * obtained, false is returned. For sg_io_v4 interface use
+ * sg_scsi_normalize_sense() function instead [see sg_lib.h].  */
 bool sg_normalize_sense(const struct sg_io_hdr * hp,
                         struct sg_scsi_sense_hdr * sshp);
 
+/* Returns SG_LIB_CAT_* value. */
 int sg_err_category(int masked_status, int host_status, int driver_status,
                     const uint8_t * sense_buffer, int sb_len);
 
+/* Returns SG_LIB_CAT_* value. */
 int sg_err_category_new(int scsi_status, int host_status, int driver_status,
                         const uint8_t * sense_buffer, int sb_len);
 
-/* The following function declaration is for the sg version 3 driver. */
+/* The following function declaration is for the sg version 3 driver. for
+ * sg_io_v4 interface use sg_err_category_new() function instead */
 int sg_err_category3(struct sg_io_hdr * hp);
 
 
 /* Note about SCSI status codes found in older versions of Linux.
-   Linux has traditionally used a 1 bit right shifted and masked
-   version of SCSI standard status codes. Now CHECK_CONDITION
-   and friends (in <scsi/scsi.h>) are deprecated. */
+ * Linux has traditionally used a 1 bit right shifted and masked
+ * version of SCSI standard status codes. Now CHECK_CONDITION
+ * and friends (in <scsi/scsi.h>) are deprecated. */
 
 #ifdef __cplusplus
 }