libdarwin/h/err.h

   1 /*
   2  * Copyright (c) 2018 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25  * @header
  26  * Non-standard, Darwin-specific additions to the err(3) family of APIs. The
  27  * following additions are provided:
  28  *
  29  *    - support for the error code additions in os/errno.h
  30  *    - automatic conversion of an error code into a sysexits(3) code
  31  *    - a debug_*() family of routines
  32  *
  33  * There are no direct equivalents for err(3), warn(3), verr(3), or vwarn(3)
  34  * because those routines query errno for error information, and it is not valid
  35  * to store error codes from os/error.h in errno. Therefore when evaluating the
  36  * output of normal POSIX routines, use the err(1) family of routines. When
  37  * evaluating the output of routines that can return the error codes in
  38  * os/error.h, you may use these routines and always explicitly pass the error
  39  * code.
  40  *
  41  * There are no equivalents for errx(3), warnx(3), verrx(3), or vwarnx(3)
  42  * because those routines do not query error information.
  43  */
  44 #ifndef __DARWIN_ERR_H
  45 #define __DARWIN_ERR_H
  46
  47 #include <os/base.h>
  48 #include <os/api.h>
  49
  50 #include <sys/errno.h>
  51 #include <sys/types.h>
  52 #include <sys/cdefs.h>
  53 #include <uuid/uuid.h>
  54
  55 #include <stdarg.h>
  56 #include <stdio.h>
  57
  58 __BEGIN_DECLS;
  59
  60 /*!
  61  * @function err_np
  62  * Writes a formatted error message to stderr(4) and exits the program.
  63  *
  64  * @param code
  65  * The error code to query in the output.
  66  *
  67  * @param fmt
  68  * The printf(3)-like format string representing the message to print.
  69  *
  70  * @param ...
  71  * The arguments corresponding to the format string.
  72  *
  73  * @discussion
  74  * This routine will look up an appropriate sysexits(3) code using the given
  75  * error code using {@link darwin_sysexit} and pass it to exit(3).
  76  */
  77 DARWIN_API_AVAILABLE_20170407
  78 OS_EXPORT OS_NORETURN OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
  79 void
  80 err_np(errno_t code, const char *fmt, ...);
  81
  82 /*!
  83  * @function errc_np
  84  * Writes a formatted error message to stderr(4) and exits the program.
  85  *
  86  * @param eval
  87  * The code to pass to exit(3). This should be a code defined in sysexits(3).
  88  *
  89  * @param code
  90  * The error code to query in the output.
  91  *
  92  * @param fmt
  93  * The printf(3)-like format string representing the message to print.
  94  *
  95  * @param ...
  96  * The arguments corresponding to the format string.
  97  */
  98 DARWIN_API_AVAILABLE_20170407
  99 OS_EXPORT OS_NORETURN OS_NONNULL3 OS_FORMAT_PRINTF(3, 4)
 100 void
 101 errc_np(int eval, errno_t code, const char *fmt, ...);
 102
 103 /*!
 104  * @function warn_np
 105  * Writes a formatted warning message to stderr(4).
 106  *
 107  * @param code
 108  * The error code to query in the output.
 109  *
 110  * @param fmt
 111  * The printf(3)-like format string representing the message to print.
 112  *
 113  * @param ...
 114  * The arguments corresponding to the format string.
 115  */
 116 DARWIN_API_AVAILABLE_20170407
 117 OS_EXPORT OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
 118 void
 119 warn_np(errno_t code, const char *fmt, ...);
 120
 121 /*!
 122  * @function verr_np
 123  * Writes a formatted error message to stderr(4) and exits the program.
 124  *
 125  * @param code
 126  * The error code to query in the output.
 127  *
 128  * @param fmt
 129  * The printf(3)-like format string representing the message to print.
 130  *
 131  * @param ap
 132  * The argument pointer corresponding to the format string.
 133  *
 134  * @discussion
 135  * This routine will look up an appropriate sysexits(3) code using the given
 136  * error code using {@link darwin_sysexit} and pass it to exit(3).
 137  */
 138 DARWIN_API_AVAILABLE_20170407
 139 OS_EXPORT OS_NORETURN OS_NONNULL2 OS_NONNULL3
 140 void
 141 verr_np(errno_t code, const char *fmt, va_list ap);
 142
 143 /*!
 144  * @function verrc_np
 145  * Writes a formatted error message to stderr(4) and exits the program.
 146  *
 147  * @param eval
 148  * The code to pass to exit(3). This should be a code defined in sysexits(3).
 149  *
 150  * @param code
 151  * The error code to query in the output.
 152  *
 153  * @param fmt
 154  * The printf(3)-like format string representing the message to print.
 155  *
 156  * @param ap
 157  * The argument pointer corresponding to the format string.
 158  */
 159 DARWIN_API_AVAILABLE_20170407
 160 OS_EXPORT OS_NORETURN OS_NONNULL3 OS_NONNULL4
 161 void
 162 verrc_np(int eval, errno_t code, const char *fmt, va_list ap);
 163
 164 /*!
 165  * @function vwarn_np
 166  * Writes a formatted warning message to stderr(4).
 167  *
 168  * @param code
 169  * The error code to query in the output.
 170  *
 171  * @param fmt
 172  * The printf(3)-like format string representing the message to print.
 173  *
 174  * @param ap
 175  * The arguments corresponding to the format string.
 176  */
 177 DARWIN_API_AVAILABLE_20170407
 178 OS_EXPORT OS_NONNULL2 OS_NONNULL3
 179 void
 180 vwarn_np(errno_t code, const char *fmt, va_list ap);
 181
 182 __END_DECLS;
 183
 184 #endif // __DARWIN_ERR_H