/* * 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 * Defines additions to the Mach family of APIs. */ #ifndef __DARWIN_MACH_UTILS_H #define __DARWIN_MACH_UTILS_H #include <os/base.h> #include <os/api.h> #include <os/assumes.h> #include <sys/cdefs.h> #include <mach/mach.h> #include <mach/mach_init.h> #include <mach/port.h> #include <mach/mach_port.h> #include <mach/kern_return.h> #if DARWIN_TAPI #include "tapi.h" #endif /*! * @define OS_MIG_SUBSYSTEM_MAXSIZE * A macro that evaluates to the maximum size of a request or reply message in * the given MIG subsystem. * * @param __subsystem * The name of the MIG subsystem, defined by the "subsystem" keyword. * * @param __serverprefix * The serverprefix of the MIG subsystem, defined by the "serverprefix" keyword. */ #define OS_MIG_SUBSYSTEM_MAXSIZE(__subsystem, __serverprefix) __extension__({ \ union __subsystem ## _RequestReplyUnion { \ union __RequestUnion__ ## __serverprefix ## __subsystem ## \ _subsystem requests; \ union __ReplyUnion__ ## __serverprefix ## __subsystem ## \ _subsystem replies; \ }; \ (sizeof(union __subsystem ## _RequestReplyUnion)); \ }) __BEGIN_DECLS; /*! * @function os_vm_address_from_ptr * Converts the given pointer to a vm_address_t. * * @param p * The pointer to convert. * * @result * The pointer as a vm_address_t. */ DARWIN_API_AVAILABLE_20190830 OS_ALWAYS_INLINE OS_WARN_RESULT static inline vm_address_t os_vm_address_from_ptr(const void *p) { return (vm_address_t)(uintptr_t)p; } /*! * @function os_mach_vm_address_from_ptr * Converts the given pointer to a mach_vm_address_t. * * @param p * The pointer to convert. * * @result * The pointer as a mach_vm_address_t. */ DARWIN_API_AVAILABLE_20190830 OS_ALWAYS_INLINE OS_WARN_RESULT static inline mach_vm_address_t os_mach_vm_address_from_ptr(const void *p) { return (mach_vm_address_t)(uintptr_t)p; } /*! * @function os_mach_msg_get_trailer * Obtains the trailer for the received Mach message. * * @param hdr * The message header of the received Mach message. * * @result * A pointer to the trailer that was received with the message. * * @discussion * Every received Mach message has a minimal trailer which identifies its format * and size (cf. mach_msg_trailer_t). Currently, there is one format, * MACH_MSG_TRAILER_FORMAT_0. The caller is responsible for validating the * returned trailer's format against this known value as well as the trailer's * size before using any additional trailer fields. * * The result of passing a header to a message that was not received from a port * is undefined. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 const mach_msg_trailer_t * os_mach_msg_get_trailer(const mach_msg_header_t *hdr); /*! * @function os_mach_msg_get_audit_trailer * Obtains the audit trailer for the received Mach message. * * @param hdr * The message header of the received Mach message. * * @result * A pointer to the audit trailer that was received with the message. If the * message was not received with an audit trailer (by passing * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT) in the mach_msg() options), * NULL is returned. * * @discussion * The result of passing a header to a message that was not received from a port * is undefined. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 const mach_msg_audit_trailer_t * os_mach_msg_get_audit_trailer(const mach_msg_header_t *hdr); /*! * @function os_mach_msg_get_context_trailer * Obtains the context trailer for the received Mach message. * * @param hdr * The message header of the received Mach message. * * @result * A pointer to the context trailer that was received with the message. If the * message was not received with an context trailer (by passing * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_CTX) in the mach_msg() options), * NULL is returned. * * @discussion * The result of passing a header to a message that was not received from a port * is undefined. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_WARN_RESULT OS_NONNULL1 const mach_msg_context_trailer_t * os_mach_msg_get_context_trailer(const mach_msg_header_t *hdr); /*! * @const os_mach_msg_copy_description * A routine for obtaining a human-readable description of a Mach message. * * @param msg * The message for which to obtain the description. * * @result * A human-readable string describing the given message header. This string is * not intended to be machine-parseable, and the exact output format is not * stable. * * The implementation does not attempt to introspect the contents of the * message. If the implementation detects that the message is complex, it will * examine the first 4 bytes past the header to obtain the descriptor count, as * is specified by the Mach APIs. Therefore, you should not pass a complex * header that is not part of a valid message buffer, or the output may contain * garbage information. * * The caller is responsible for free(3)ing this string when it is no longer * required. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC OS_NONNULL1 char * os_mach_msg_copy_description(const mach_msg_header_t *msg); /*! * @function os_mach_msg_trailer_copy_description * A routine for obtaining a human-readable description of the trailer of a Mach * message. * * @param tlr * The trailer for which to obtain the description. * * @result * A human-readable string describing the given message trailer. This string is * not intended to be machine-parseable, and the exact output format is not * stable. * * The caller is responsible for free(3)ing this string when it is no longer * required. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC OS_NONNULL1 char * os_mach_msg_trailer_copy_description(const mach_msg_trailer_t *tlr); /*! * @function os_mach_port_copy_description * A routine for obtaining a human-readable description string of a port right * handle. * * @param port * The port right for which to obtain the description. * * @result * A human-readable string describing the given port right. This string is not * intended to be machine-parseable, and the exact output format is not stable. * * The caller is responsible for free(3)ing this string when it is no longer * required. */ DARWIN_API_AVAILABLE_20170407 OS_EXPORT OS_COLD OS_WARN_RESULT OS_MALLOC char * os_mach_port_copy_description(mach_port_t port); __END_DECLS; #endif // __DARWIN_MACH_UTILS_H