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 #if DARWIN_TAPI
  59 #include "tapi.h"
  60 #endif
  61
  62 __BEGIN_DECLS;
  63
  64 /*!
  65  * @function err_np
  66  * Writes a formatted error message to stderr(4) and exits the program.
  67  *
  68  * @param code
  69  * The error code to query in the output.
  70  *
  71  * @param fmt
  72  * The printf(3)-like format string representing the message to print.
  73  *
  74  * @param ...
  75  * The arguments corresponding to the format string.
  76  *
  77  * @discussion
  78  * This routine will look up an appropriate sysexits(3) code using the given
  79  * error code using {@link darwin_sysexit} and pass it to exit(3).
  80  */
  81 DARWIN_API_AVAILABLE_20170407
  82 OS_EXPORT OS_NORETURN OS_COLD OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
  83 void
  84 err_np(errno_t code, const char *fmt, ...);
  85
  86 /*!
  87  * @function errc_np
  88  * Writes a formatted error message to stderr(4) and exits the program.
  89  *
  90  * @param eval
  91  * The code to pass to exit(3). This should be a code defined in sysexits(3).
  92  *
  93  * @param code
  94  * The error code to query in the output.
  95  *
  96  * @param fmt
  97  * The printf(3)-like format string representing the message to print.
  98  *
  99  * @param ...
 100  * The arguments corresponding to the format string.
 101  */
 102 DARWIN_API_AVAILABLE_20170407
 103 OS_EXPORT OS_NORETURN OS_COLD OS_NONNULL3 OS_FORMAT_PRINTF(3, 4)
 104 void
 105 errc_np(int eval, errno_t code, const char *fmt, ...);
 106
 107 /*!
 108  * @function warn_np
 109  * Writes a formatted warning message to stderr(4).
 110  *
 111  * @param code
 112  * The error code to query in the output.
 113  *
 114  * @param fmt
 115  * The printf(3)-like format string representing the message to print.
 116  *
 117  * @param ...
 118  * The arguments corresponding to the format string.
 119  */
 120 DARWIN_API_AVAILABLE_20170407
 121 OS_EXPORT OS_COLD OS_NONNULL2 OS_FORMAT_PRINTF(2, 3)
 122 void
 123 warn_np(errno_t code, const char *fmt, ...);
 124
 125 /*!
 126  * @function verr_np
 127  * Writes a formatted error message to stderr(4) and exits the program.
 128  *
 129  * @param code
 130  * The error code to query in the output.
 131  *
 132  * @param fmt
 133  * The printf(3)-like format string representing the message to print.
 134  *
 135  * @param ap
 136  * The argument pointer corresponding to the format string.
 137  *
 138  * @discussion
 139  * This routine will look up an appropriate sysexits(3) code using the given
 140  * error code using {@link darwin_sysexit} and pass it to exit(3).
 141  */
 142 DARWIN_API_AVAILABLE_20170407
 143 OS_EXPORT OS_NORETURN OS_COLD OS_NONNULL2 OS_NONNULL3
 144 void
 145 verr_np(errno_t code, const char *fmt, va_list ap);
 146
 147 /*!
 148  * @function verrc_np
 149  * Writes a formatted error message to stderr(4) and exits the program.
 150  *
 151  * @param eval
 152  * The code to pass to exit(3). This should be a code defined in sysexits(3).
 153  *
 154  * @param code
 155  * The error code to query in the output.
 156  *
 157  * @param fmt
 158  * The printf(3)-like format string representing the message to print.
 159  *
 160  * @param ap
 161  * The argument pointer corresponding to the format string.
 162  */
 163 DARWIN_API_AVAILABLE_20170407
 164 OS_EXPORT OS_NORETURN OS_COLD OS_NONNULL3 OS_NONNULL4
 165 void
 166 verrc_np(int eval, errno_t code, const char *fmt, va_list ap);
 167
 168 /*!
 169  * @function vwarn_np
 170  * Writes a formatted warning message to stderr(4).
 171  *
 172  * @param code
 173  * The error code to query in the output.
 174  *
 175  * @param fmt
 176  * The printf(3)-like format string representing the message to print.
 177  *
 178  * @param ap
 179  * The arguments corresponding to the format string.
 180  */
 181 DARWIN_API_AVAILABLE_20170407
 182 OS_EXPORT OS_COLD OS_NONNULL2 OS_NONNULL3
 183 void
 184 vwarn_np(errno_t code, const char *fmt, va_list ap);
 185
 186 __END_DECLS;
 187
 188 #endif // __DARWIN_ERR_H