--- /dev/null
+/*
+ * Copyright (c) 2018 Apple Inc. All rights reserved.
+ *
+ * @APPLE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_LICENSE_HEADER_END@
+ */
+
+/*!
+ * @header
+ * Non-standard, Darwin-specific additions to the string(3) family of APIs.
+ */
+#ifndef __DARWIN_STRING_H
+#define __DARWIN_STRING_H
+
+#include <os/base.h>
+#include <os/api.h>
+#include <sys/cdefs.h>
+
+__BEGIN_DECLS;
+
+/*!
+ * @typedef os_flag_t
+ * A type describing a flag's human-readable name.
+ *
+ * @property ohf_flag
+ * The flag value.
+ *
+ * @property ohf_human
+ * The human-readable, string representation of the flag value.
+ */
+DARWIN_API_AVAILABLE_20170407
+typedef struct _os_flag {
+ const uint64_t ohf_flag;
+ const char *const ohf_human_flag;
+} os_flag_t;
+
+/*!
+ * @define OS_FLAGSET_COUNT
+ * The maximum number of flags that a flagset can represent.
+ */
+#define OS_FLAGSET_COUNT (sizeof(uint64_t) * BYTE_SIZE)
+
+/*!
+ * @typedef os_flagset_t
+ * A type describing an array of human flags. Can accommodate up to 64 flags.
+ */
+DARWIN_API_AVAILABLE_20170407
+typedef os_flag_t os_flagset_t[OS_FLAGSET_COUNT];
+
+/*!
+ * @macro os_flag_init
+ * Initializer for a {@link os_flag_t} structure which stringifies the
+ * flag value.
+ *
+ * @param __flag
+ * The name of the flag to initialize.
+ */
+#define os_flag_init(__flag) { \
+ .ohf_flag = __flag, \
+ .ohf_human_flag = #__flag, \
+}
+
+/*!
+ * @function strerror_np
+ * Returns a human-readable string for the given {@link errno_t} or
+ * POSIX error code.
+ *
+ * @param code
+ * The error code for which to obtain the string.
+ *
+ * @result
+ * A human-readable string describing the error condition. If a POSIX error code
+ * is given, this is equivalent to a call to strerror(3).
+ */
+DARWIN_API_AVAILABLE_20170407
+OS_EXPORT OS_WARN_RESULT OS_PURE
+const char *
+strerror_np(int code);
+
+/*!
+ * @function symerror_np
+ * Returns the token name of the given {@link errno_t} or POSIX error
+ * code.
+ *
+ * @param code
+ * The error code for which to obtain the token string.
+ *
+ * @result
+ * The string describing the error token. For example, if code 2 is passed, the
+ * string "EPERM" is returned.
+ */
+DARWIN_API_AVAILABLE_20170407
+OS_EXPORT OS_WARN_RESULT OS_PURE
+const char *
+symerror_np(int code);
+
+/*!
+ * @function symexit_np
+ * Returns the token name of the given sysexits(3) code.
+ *
+ * @param code
+ * The sysexits(3) code for which to obtain the token string.
+ *
+ * @result
+ * The string describing the exit code. For example, if 64 is passed, the string
+ * "EX_USAGE" is returned. If the code is unrecognized, "EX_UNAVAILABLE" is
+ * returned, which is more or less documented in sysexits(3) as the ¯\_(ツ)_/¯
+ * exit code.
+ */
+DARWIN_API_AVAILABLE_20170407
+OS_EXPORT OS_WARN_RESULT OS_PURE
+const char *
+symexit_np(int code);
+
+/*!
+ * @function os_flagset_copy_string
+ * Returns a human-readable representation of the flags set for a given word.
+ *
+ * @param flagset
+ * The human flagset which describes how to interpret the {@link flags}
+ * parameter.
+ *
+ * @param flags
+ * The flags to interpret.
+ *
+ * @result
+ * The human-readable representation of all flags set in the {@link flags}
+ * parameter, separated by the pipe character. The caller is responsible for
+ * calling free(3) on this object when it is no longer needed.
+ *
+ * @discussion
+ * This API is to be used in combination with {@link os_flag_init} to make
+ * printing the contents of flags fields simple. For example, this code can
+ * easily print a human-readable representation of the bits set in a Mach
+ * message header:
+ *
+ * static const os_flagset_t _mach_msgh_bits = {
+ * os_flag_init(MACH_MSGH_BITS_COMPLEX),
+ * os_flag_init(MACH_MSGH_BITS_RAISEIMP),
+ * os_flag_init(MACH_MSGH_BITS_IMPHOLDASRT),
+ * };
+ *
+ * char *flags_string = os_flagset_copy_string(&_mach_msgh_bits,
+ * hdr->msgh_bits);
+ *
+ * For a message header with the MACH_MSGH_BITS_COMPLEX and
+ * MACH_MSGH_BITS_RAISEIMP bits set, this will return the string
+ *
+ * MACH_MSGH_BITS_COMPLEX|MACH_MSGH_BITS_RAISEIMP
+ */
+DARWIN_API_AVAILABLE_20170407
+OS_EXPORT OS_WARN_RESULT OS_MALLOC
+char *
+os_flagset_copy_string(const os_flagset_t flagset, uint64_t flags);
+
+__END_DECLS;
+
+#endif // __DARWIN_STRING_H
projects / apple / libc.git / blobdiff