libdarwin/h/string.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 string(3) family of APIs.
  27  */
  28 #ifndef __DARWIN_STRING_H
  29 #define __DARWIN_STRING_H
  30
  31 #include <os/base.h>
  32 #include <os/api.h>
  33 #include <sys/cdefs.h>
  34
  35 #if DARWIN_TAPI
  36 #include "tapi.h"
  37 #endif
  38
  39 __BEGIN_DECLS;
  40
  41 /*!
  42  * @typedef os_flag_t
  43  * A type describing a flag's human-readable name.
  44  *
  45  * @property ohf_flag
  46  * The flag value.
  47  *
  48  * @property ohf_human
  49  * The human-readable, string representation of the flag value.
  50  */
  51 DARWIN_API_AVAILABLE_20170407
  52 typedef struct _os_flag {
  53         const uint64_t ohf_flag;
  54         const char *const ohf_human_flag;
  55 } os_flag_t;
  56
  57 /*!
  58  * @define OS_FLAGSET_COUNT
  59  * The maximum number of flags that a flagset can represent.
  60  */
  61 #define OS_FLAGSET_COUNT (sizeof(uint64_t) * BYTE_SIZE)
  62
  63 /*!
  64  * @typedef os_flagset_t
  65  * A type describing an array of human flags. Can accommodate up to 64 flags.
  66  */
  67 DARWIN_API_AVAILABLE_20170407
  68 typedef os_flag_t os_flagset_t[OS_FLAGSET_COUNT];
  69
  70 /*!
  71  * @macro os_flag_init
  72  * Initializer for a {@link os_flag_t} structure which stringifies the
  73  * flag value.
  74  *
  75  * @param __flag
  76  * The name of the flag to initialize.
  77  */
  78 #define os_flag_init(__flag) { \
  79         .ohf_flag = __flag, \
  80         .ohf_human_flag = #__flag, \
  81 }
  82
  83 /*!
  84  * @function strerror_np
  85  * Returns a human-readable string for the given {@link errno_t} or
  86  * POSIX error code.
  87  *
  88  * @param code
  89  * The error code for which to obtain the string.
  90  *
  91  * @result
  92  * A human-readable string describing the error condition. If a POSIX error code
  93  * is given, this is equivalent to a call to strerror(3).
  94  */
  95 DARWIN_API_AVAILABLE_20170407
  96 OS_EXPORT OS_COLD OS_WARN_RESULT OS_PURE
  97 const char *
  98 strerror_np(int code);
  99
 100 /*!
 101  * @function strexit_np
 102  * Returns a human-readable string for the given sysexits(3) code.
 103  *
 104  * @param code
 105  * The exit code for which to obtain the string.
 106  *
 107  * @result
 108  * A human-readable string describing the exit condition.
 109  */
 110 DARWIN_API_AVAILABLE_20190830
 111 OS_EXPORT OS_COLD OS_WARN_RESULT OS_PURE
 112 const char *
 113 strexit_np(int code);
 114
 115 /*!
 116  * @function symerror_np
 117  * Returns the token name of the given {@link errno_t} or POSIX error
 118  * code.
 119  *
 120  * @param code
 121  * The error code for which to obtain the token string.
 122  *
 123  * @result
 124  * The string describing the error token. For example, if code 2 is passed, the
 125  * string "EPERM" is returned.
 126  */
 127 DARWIN_API_AVAILABLE_20170407
 128 OS_EXPORT OS_COLD OS_WARN_RESULT OS_PURE
 129 const char *
 130 symerror_np(int code);
 131
 132 /*!
 133  * @function symexit_np
 134  * Returns the token name of the given sysexits(3) code.
 135  *
 136  * @param code
 137  * The sysexits(3) code for which to obtain the token string.
 138  *
 139  * @result
 140  * The string describing the exit code. For example, if 64 is passed, the string
 141  * "EX_USAGE" is returned. If the code is unrecognized, "EX_UNAVAILABLE" is
 142  * returned, which is more or less documented in sysexits(3) as the ¯\_(ツ)_/¯
 143  * exit code.
 144  */
 145 DARWIN_API_AVAILABLE_20170407
 146 OS_EXPORT OS_COLD OS_WARN_RESULT OS_PURE
 147 const char *
 148 symexit_np(int code);
 149
 150 /*!
 151  * @function os_flagset_copy_string
 152  * Returns a human-readable representation of the flags set for a given word.
 153  *
 154  * @param flagset
 155  * The human flagset which describes how to interpret the {@link flags}
 156  * parameter.
 157  *
 158  * @param flags
 159  * The flags to interpret.
 160  *
 161  * @result
 162  * The human-readable representation of all flags set in the {@link flags}
 163  * parameter, separated by the pipe character. The caller is responsible for
 164  * calling free(3) on this object when it is no longer needed.
 165  *
 166  * @discussion
 167  * This API is to be used in combination with {@link os_flag_init} to make
 168  * printing the contents of flags fields simple. For example, this code can
 169  * easily print a human-readable representation of the bits set in a Mach
 170  * message header:
 171  *
 172  *     static const os_flagset_t _mach_msgh_bits = {
 173  *          os_flag_init(MACH_MSGH_BITS_COMPLEX),
 174  *          os_flag_init(MACH_MSGH_BITS_RAISEIMP),
 175  *          os_flag_init(MACH_MSGH_BITS_IMPHOLDASRT),
 176  *    };
 177  *
 178  *    char *flags_string = os_flagset_copy_string(&_mach_msgh_bits,
 179  *            hdr->msgh_bits);
 180  *
 181  * For a message header with the MACH_MSGH_BITS_COMPLEX and
 182  * MACH_MSGH_BITS_RAISEIMP bits set, this will return the string
 183  *
 184  *     MACH_MSGH_BITS_COMPLEX|MACH_MSGH_BITS_RAISEIMP
 185  */
 186 DARWIN_API_AVAILABLE_20170407
 187 OS_EXPORT OS_WARN_RESULT OS_MALLOC
 188 char *
 189 os_flagset_copy_string(const os_flagset_t flagset, uint64_t flags);
 190
 191 __END_DECLS;
 192
 193 #endif // __DARWIN_STRING_H