[apple/libc.git] / libdarwin / h / mach_utils.h

/*
 * 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>

/*!
 * @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_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_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_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_WARN_RESULT OS_MALLOC
char *
os_mach_port_copy_description(mach_port_t port);

__END_DECLS;

#endif // __DARWIN_MACH_UTILS_H
Commit	Line	Data
70ad1dc8 A	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