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 #if DARWIN_TAPI
  44 #include "tapi.h"
  45 #endif
  46
  47 /*!
  48  * @define OS_MIG_SUBSYSTEM_MAXSIZE
  49  * A macro that evaluates to the maximum size of a request or reply message in
  50  * the given MIG subsystem.
  51  *
  52  * @param __subsystem
  53  * The name of the MIG subsystem, defined by the "subsystem" keyword.
  54  *
  55  * @param __serverprefix
  56  * The serverprefix of the MIG subsystem, defined by the "serverprefix" keyword.
  57  */
  58 #define OS_MIG_SUBSYSTEM_MAXSIZE(__subsystem, __serverprefix) __extension__({ \
  59         union __subsystem ## _RequestReplyUnion { \
  60                 union __RequestUnion__ ## __serverprefix ## __subsystem ## \
  61                         _subsystem requests; \
  62                 union __ReplyUnion__ ## __serverprefix ## __subsystem ## \
  63                         _subsystem replies; \
  64         }; \
  65         (sizeof(union __subsystem ## _RequestReplyUnion)); \
  66 })
  67
  68 __BEGIN_DECLS;
  69
  70 /*!
  71  * @function os_vm_address_from_ptr
  72  * Converts the given pointer to a vm_address_t.
  73  *
  74  * @param p
  75  * The pointer to convert.
  76  *
  77  * @result
  78  * The pointer as a vm_address_t.
  79  */
  80 DARWIN_API_AVAILABLE_20190830
  81 OS_ALWAYS_INLINE OS_WARN_RESULT
  82 static inline vm_address_t
  83 os_vm_address_from_ptr(const void *p)
  84 {
  85         return (vm_address_t)(uintptr_t)p;
  86 }
  87
  88 /*!
  89  * @function os_mach_vm_address_from_ptr
  90  * Converts the given pointer to a mach_vm_address_t.
  91  *
  92  * @param p
  93  * The pointer to convert.
  94  *
  95  * @result
  96  * The pointer as a mach_vm_address_t.
  97  */
  98 DARWIN_API_AVAILABLE_20190830
  99 OS_ALWAYS_INLINE OS_WARN_RESULT
 100 static inline mach_vm_address_t
 101 os_mach_vm_address_from_ptr(const void *p)
 102 {
 103         return (mach_vm_address_t)(uintptr_t)p;
 104 }
 105
 106 /*!
 107  * @function os_mach_msg_get_trailer
 108  * Obtains the trailer for the received Mach message.
 109  *
 110  * @param hdr
 111  * The message header of the received Mach message.
 112  *
 113  * @result
 114  * A pointer to the trailer that was received with the message.
 115  *
 116  * @discussion
 117  * Every received Mach message has a minimal trailer which identifies its format
 118  * and size (cf. mach_msg_trailer_t). Currently, there is one format,
 119  * MACH_MSG_TRAILER_FORMAT_0. The caller is responsible for validating the
 120  * returned trailer's format against this known value as well as the trailer's
 121  * size before using any additional trailer fields.
 122  *
 123  * The result of passing a header to a message that was not received from a port
 124  * is undefined.
 125  */
 126 DARWIN_API_AVAILABLE_20170407
 127 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 128 const mach_msg_trailer_t *
 129 os_mach_msg_get_trailer(const mach_msg_header_t *hdr);
 130
 131 /*!
 132  * @function os_mach_msg_get_audit_trailer
 133  * Obtains the audit trailer for the received Mach message.
 134  *
 135  * @param hdr
 136  * The message header of the received Mach message.
 137  *
 138  * @result
 139  * A pointer to the audit trailer that was received with the message. If the
 140  * message was not received with an audit trailer (by passing
 141  * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT) in the mach_msg() options),
 142  * NULL is returned.
 143  *
 144  * @discussion
 145  * The result of passing a header to a message that was not received from a port
 146  * is undefined.
 147  */
 148 DARWIN_API_AVAILABLE_20170407
 149 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 150 const mach_msg_audit_trailer_t *
 151 os_mach_msg_get_audit_trailer(const mach_msg_header_t *hdr);
 152
 153 /*!
 154  * @function os_mach_msg_get_context_trailer
 155  * Obtains the context trailer for the received Mach message.
 156  *
 157  * @param hdr
 158  * The message header of the received Mach message.
 159  *
 160  * @result
 161  * A pointer to the context trailer that was received with the message. If the
 162  * message was not received with an context trailer (by passing
 163  * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_CTX) in the mach_msg() options),
 164  * NULL is returned.
 165  *
 166  * @discussion
 167  * The result of passing a header to a message that was not received from a port
 168  * is undefined.
 169  */
 170 DARWIN_API_AVAILABLE_20170407
 171 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 172 const mach_msg_context_trailer_t *
 173 os_mach_msg_get_context_trailer(const mach_msg_header_t *hdr);
 174
 175 /*!
 176  * @const os_mach_msg_copy_description
 177  * A routine for obtaining a human-readable description of a Mach message.
 178  *
 179  * @param msg
 180  * The message for which to obtain the description.
 181  *
 182  * @result
 183  * A human-readable string describing the given message header. This string is
 184  * not intended to be machine-parseable, and the exact output format is not
 185  * stable.
 186  *
 187  * The implementation does not attempt to introspect the contents of the
 188  * message. If the implementation detects that the message is complex, it will
 189  * examine the first 4 bytes past the header to obtain the descriptor count, as
 190  * is specified by the Mach APIs. Therefore, you should not pass a complex
 191  * header that is not part of a valid message buffer, or the output may contain
 192  * garbage information.
 193  *
 194  * The caller is responsible for free(3)ing this string when it is no longer
 195  * required.
 196  */
 197 DARWIN_API_AVAILABLE_20170407
 198 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC OS_NONNULL1
 199 char *
 200 os_mach_msg_copy_description(const mach_msg_header_t *msg);
 201
 202 /*!
 203  * @function os_mach_msg_trailer_copy_description
 204  * A routine for obtaining a human-readable description of the trailer of a Mach
 205  * message.
 206  *
 207  * @param tlr
 208  * The trailer for which to obtain the description.
 209  *
 210  * @result
 211  * A human-readable string describing the given message trailer. This string is
 212  * not intended to be machine-parseable, and the exact output format is not
 213  * stable.
 214  *
 215  * The caller is responsible for free(3)ing this string when it is no longer
 216  * required.
 217  */
 218 DARWIN_API_AVAILABLE_20170407
 219 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC OS_NONNULL1
 220 char *
 221 os_mach_msg_trailer_copy_description(const mach_msg_trailer_t *tlr);
 222
 223 /*!
 224  * @function os_mach_port_copy_description
 225  * A routine for obtaining a human-readable description string of a port right
 226  * handle.
 227  *
 228  * @param port
 229  * The port right for which to obtain the description.
 230  *
 231  * @result
 232  * A human-readable string describing the given port right. This string is not
 233  * intended to be machine-parseable, and the exact output format is not stable.
 234  *
 235  * The caller is responsible for free(3)ing this string when it is no longer
 236  * required.
 237  */
 238 DARWIN_API_AVAILABLE_20170407
 239 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC
 240 char *
 241 os_mach_port_copy_description(mach_port_t port);
 242
 243 __END_DECLS;
 244
 245 #endif // __DARWIN_MACH_UTILS_H