1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25 
  26 #ifndef _SPCS_S_U_H
  27 #define _SPCS_S_U_H
  28 
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32 
  33 /*
  34  *      USER level status support utilities
  35  */
  36 
  37 #include <stdio.h>
  38 
  39 /*
  40  *      Create and initialize local status. Call this prior to invoking
  41  *      an ioctl
  42  *      @return The status or NULL if malloc failed
  43  */
  44 
  45 spcs_s_info_t
  46 spcs_s_ucreate();
  47 
  48 /*
  49  *      Initialize ioctl status storage to "remove" any status present
  50  *      @param ustatus The status
  51  */
  52 
  53 void
  54 spcs_s_uinit(spcs_s_info_t ustatus);
  55 
  56 /*
  57  *      Return a string with the module label and next status message text or
  58  *      NULL if none left. Supplemental values are edited into the text and
  59  *      the used status and values are removed so that subsequent calls will
  60  *      access the next piece of information.
  61  *      Note that status codes and supplemental values are processed in
  62  *      the reverse order of their insertion by SPCS kernel code. That is,
  63  *      spcs_s_string returns the "youngest" status information first (i.e.
  64  *      LIFO).
  65  *      Note that spcs_s_string will not have any error information in
  66  *      the special case where Solaris has aborted an ioctl and returned an
  67  *      error code via errno or the ioctl service code had an "early" error
  68  *      from copyin or could not allocate its status area. In this case
  69  *      spcs_s_string will return NULL the first time it is called and a
  70  *      positive integer error code will be present in errno and should get
  71  *      handled by the spcs_s_string caller appropriately by using strerror.
  72  *      @param ustatus  The status
  73  *      @param msg      A char array of at least SPCS_S_MAXTEXT length
  74  *      @return status message string or NULL if no more status present
  75  */
  76 
  77 char *spcs_s_string(spcs_s_info_t ustatus, char *msg);
  78 
  79 /*
  80  *      Write status info to the file specified
  81  *      Uses spsc_s_string to edit status into strings and output them
  82  *      to the file specifed in the same order that the status was inserted.
  83  *      If there is no status present but errno contains a positive value
  84  *      then it will be treated as a Solaris error code and its message text
  85  *      will be written. Note that this routine does NOT remove status
  86  *      information so it can be called more than once.
  87  *      @param ustatus  The status
  88  *      @param fd       The file descriptor to use for output
  89  */
  90 
  91 void spcs_s_report(spcs_s_info_t ustatus, FILE *fd);
  92 
  93 /*
  94  *      Release (free) ioctl status storage.
  95  *      Note that this interface is an extension to SPARC 1998/038 10/22/98
  96  *      commitment.
  97  *      @param ustatus_a The address of the status (set to NULL)
  98  */
  99 
 100 void
 101 spcs_s_ufree(spcs_s_info_t *ustatus_a);
 102 
 103 /*
 104  *      Write message to log file.
 105  *      @param product  Product code for tagging in log file.
 106  *      @param ustatus  The status - may be NULL.
 107  *      @param format   printf style format.
 108  */
 109 
 110 void
 111 spcs_log(const char *product, spcs_s_info_t *ustatus, const char *format, ...);
 112 
 113 #ifdef __cplusplus
 114 }
 115 #endif
 116 
 117 #endif /* _SPCS_S_U_H */