libdarwin/h/mach_utils.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  * Defines additions to the Mach family of APIs.
  27  */
  28 #ifndef __DARWIN_MACH_UTILS_H
  29 #define __DARWIN_MACH_UTILS_H
  30
  31 #include <os/base.h>
  32 #include <os/api.h>
  33 #include <os/assumes.h>
  34
  35 #include <sys/cdefs.h>
  36
  37 #include <mach/mach.h>
  38 #include <mach/mach_init.h>
  39 #include <mach/port.h>
  40 #include <mach/mach_port.h>
  41 #include <mach/kern_return.h>
  42
  43 /*!
  44  * @define OS_MIG_SUBSYSTEM_MAXSIZE
  45  * A macro that evaluates to the maximum size of a request or reply message in
  46  * the given MIG subsystem.
  47  *
  48  * @param __subsystem
  49  * The name of the MIG subsystem, defined by the "subsystem" keyword.
  50  *
  51  * @param __serverprefix
  52  * The serverprefix of the MIG subsystem, defined by the "serverprefix" keyword.
  53  */
  54 #define OS_MIG_SUBSYSTEM_MAXSIZE(__subsystem, __serverprefix) __extension__({ \
  55         union __subsystem ## _RequestReplyUnion { \
  56                 union __RequestUnion__ ## __serverprefix ## __subsystem ## \
  57                         _subsystem requests; \
  58                 union __ReplyUnion__ ## __serverprefix ## __subsystem ## \
  59                         _subsystem replies; \
  60         }; \
  61         (sizeof(union __subsystem ## _RequestReplyUnion)); \
  62 })
  63
  64 __BEGIN_DECLS;
  65
  66 /*!
  67  * @function os_mach_msg_get_trailer
  68  * Obtains the trailer for the received Mach message.
  69  *
  70  * @param hdr
  71  * The message header of the received Mach message.
  72  *
  73  * @result
  74  * A pointer to the trailer that was received with the message.
  75  *
  76  * @discussion
  77  * Every received Mach message has a minimal trailer which identifies its format
  78  * and size (cf. mach_msg_trailer_t). Currently, there is one format,
  79  * MACH_MSG_TRAILER_FORMAT_0. The caller is responsible for validating the
  80  * returned trailer's format against this known value as well as the trailer's
  81  * size before using any additional trailer fields.
  82  *
  83  * The result of passing a header to a message that was not received from a port
  84  * is undefined.
  85  */
  86 DARWIN_API_AVAILABLE_20170407
  87 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
  88 const mach_msg_trailer_t *
  89 os_mach_msg_get_trailer(const mach_msg_header_t *hdr);
  90
  91 /*!
  92  * @function os_mach_msg_get_audit_trailer
  93  * Obtains the audit trailer for the received Mach message.
  94  *
  95  * @param hdr
  96  * The message header of the received Mach message.
  97  *
  98  * @result
  99  * A pointer to the audit trailer that was received with the message. If the
 100  * message was not received with an audit trailer (by passing
 101  * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT) in the mach_msg() options),
 102  * NULL is returned.
 103  *
 104  * @discussion
 105  * The result of passing a header to a message that was not received from a port
 106  * is undefined.
 107  */
 108 DARWIN_API_AVAILABLE_20170407
 109 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 110 const mach_msg_audit_trailer_t *
 111 os_mach_msg_get_audit_trailer(const mach_msg_header_t *hdr);
 112
 113 /*!
 114  * @function os_mach_msg_get_context_trailer
 115  * Obtains the context trailer for the received Mach message.
 116  *
 117  * @param hdr
 118  * The message header of the received Mach message.
 119  *
 120  * @result
 121  * A pointer to the context trailer that was received with the message. If the
 122  * message was not received with an context trailer (by passing
 123  * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_CTX) in the mach_msg() options),
 124  * NULL is returned.
 125  *
 126  * @discussion
 127  * The result of passing a header to a message that was not received from a port
 128  * is undefined.
 129  */
 130 DARWIN_API_AVAILABLE_20170407
 131 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 132 const mach_msg_context_trailer_t *
 133 os_mach_msg_get_context_trailer(const mach_msg_header_t *hdr);
 134
 135 /*!
 136  * @const os_mach_msg_copy_description
 137  * A routine for obtaining a human-readable description of a Mach message.
 138  *
 139  * @param msg
 140  * The message for which to obtain the description.
 141  *
 142  * @result
 143  * A human-readable string describing the given message header. This string is
 144  * not intended to be machine-parseable, and the exact output format is not
 145  * stable.
 146  *
 147  * The implementation does not attempt to introspect the contents of the
 148  * message. If the implementation detects that the message is complex, it will
 149  * examine the first 4 bytes past the header to obtain the descriptor count, as
 150  * is specified by the Mach APIs. Therefore, you should not pass a complex
 151  * header that is not part of a valid message buffer, or the output may contain
 152  * garbage information.
 153  *
 154  * The caller is responsible for free(3)ing this string when it is no longer
 155  * required.
 156  */
 157 DARWIN_API_AVAILABLE_20170407
 158 OS_EXPORT OS_WARN_RESULT OS_MALLOC OS_NONNULL1
 159 char *
 160 os_mach_msg_copy_description(const mach_msg_header_t *msg);
 161
 162 /*!
 163  * @function os_mach_msg_trailer_copy_description
 164  * A routine for obtaining a human-readable description of the trailer of a Mach
 165  * message.
 166  *
 167  * @param tlr
 168  * The trailer for which to obtain the description.
 169  *
 170  * @result
 171  * A human-readable string describing the given message trailer. This string is
 172  * not intended to be machine-parseable, and the exact output format is not
 173  * stable.
 174  *
 175  * The caller is responsible for free(3)ing this string when it is no longer
 176  * required.
 177  */
 178 DARWIN_API_AVAILABLE_20170407
 179 OS_EXPORT OS_WARN_RESULT OS_MALLOC OS_NONNULL1
 180 char *
 181 os_mach_msg_trailer_copy_description(const mach_msg_trailer_t *tlr);
 182
 183 /*!
 184  * @function os_mach_port_copy_description
 185  * A routine for obtaining a human-readable description string of a port right
 186  * handle.
 187  *
 188  * @param port
 189  * The port right for which to obtain the description.
 190  *
 191  * @result
 192  * A human-readable string describing the given port right. This string is not
 193  * intended to be machine-parseable, and the exact output format is not stable.
 194  *
 195  * The caller is responsible for free(3)ing this string when it is no longer
 196  * required.
 197  */
 198 DARWIN_API_AVAILABLE_20170407
 199 OS_EXPORT OS_WARN_RESULT OS_MALLOC
 200 char *
 201 os_mach_port_copy_description(mach_port_t port);
 202
 203 __END_DECLS;
 204
 205 #endif // __DARWIN_MACH_UTILS_H