/*
* Copyright (c) 2018 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_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. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* 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_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef __MACH_RIGHT_PRIVATE_H
#define __MACH_RIGHT_PRIVATE_H
#include <os/base.h>
#include <mach/mach.h>
#include <mach/port.h>
#include <mach/mach_port.h>
#include <sys/cdefs.h>
#include <stdbool.h>
__BEGIN_DECLS;
/*!
* @typedef mach_right_recv_t
* A type representing the receive right to a Mach port.
*/
typedef struct _mach_right_recv {
mach_port_t mrr_name;
} mach_right_recv_t;
/*!
* @const MACH_RIGHT_RECV_NULL
* A convenience initializer for a receive right object.
*/
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
#define MACH_RIGHT_RECV_NULL ((mach_right_recv_t){MACH_PORT_NULL})
#elif defined(__cplusplus) && __cplusplus >= 201103L
#define MACH_RIGHT_RECV_NULL (mach_right_recv_t{MACH_PORT_NULL})
#elif defined(__cplusplus)
#define MACH_RIGHT_RECV_NULL \
(mach_right_recv_t((mach_right_recv_t){MACH_PORT_NULL}))
#else
#define MACH_RIGHT_RECV_NULL {MACH_PORT_NULL}
#endif
/*!
* @typedef mach_right_send_t
* A type representing a send right to a Mach port.
*/
typedef struct _mach_right_send {
mach_port_t mrs_name;
} mach_right_send_t;
/*!
* @const MACH_RIGHT_SEND_NULL
* A convenience initializer for a send right object.
*/
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
#define MACH_RIGHT_SEND_NULL ((mach_right_send_t){MACH_PORT_NULL})
#elif defined(__cplusplus) && __cplusplus >= 201103L
#define MACH_RIGHT_SEND_NULL (mach_right_send_t{MACH_PORT_NULL})
#elif defined(__cplusplus)
#define MACH_RIGHT_SEND_NULL \
(mach_right_send_t((mach_right_send_t){MACH_PORT_NULL}))
#else
#define MACH_RIGHT_SEND_NULL {MACH_PORT_NULL}
#endif
/*!
* @typedef mach_right_send_once_t
* A type representing a send-once right to a Mach port.
*/
typedef struct _mach_right_send_once {
mach_port_t mrso_name;
} mach_right_send_once_t;
/*!
* @const MACH_RIGHT_SEND_ONCE_NULL
* A convenience initializer for a send-once right object.
*/
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
#define MACH_RIGHT_SEND_ONCE_NULL ((mach_right_send_once_t){MACH_PORT_NULL})
#elif defined(__cplusplus) && __cplusplus >= 201103L
#define MACH_RIGHT_SEND_ONCE_NULL (mach_right_send_once_t{MACH_PORT_NULL})
#elif defined(__cplusplus)
#define MACH_RIGHT_SEND_ONCE_NULL \
(mach_right_send_once_t((mach_right_send_once_t){MACH_PORT_NULL}))
#else
#define MACH_RIGHT_SEND_ONCE_NULL {MACH_PORT_NULL}
#endif
/*!
* @function mach_right_recv
* Wraps a port name as a receive right object.
*
* @param pn
* The port name. If this name is valid but does not represent a receive right,
* the behavior of mach_right_recv_* implementations is undefined.
*
* @result
* A new receive right object.
*/
OS_ALWAYS_INLINE OS_WARN_RESULT
static inline mach_right_recv_t
mach_right_recv(mach_port_name_t pn)
{
mach_right_recv_t mrr = {pn};
return mrr;
}
/*!
* @function mach_right_send
* Wraps a port name as a send right object.
*
* @param pn
* The port name. If this name is valid but does not represent a send right, the
* behavior of mach_right_send_* implementations is undefined.
*
* @result
* A new send right object.
*/
OS_ALWAYS_INLINE OS_WARN_RESULT
static inline mach_right_send_t
mach_right_send(mach_port_name_t pn)
{
mach_right_send_t mrs = {pn};
return mrs;
}
/*!
* @function mach_right_send_valid
* Checks if the given send right object is valid.
*
* @param mrs
* The send right object to check.
*
* @result
* A Boolean indicating whether the right is valid.
*/
OS_ALWAYS_INLINE OS_WARN_RESULT
static inline bool
mach_right_send_valid(mach_right_send_t mrs)
{
return MACH_PORT_VALID(mrs.mrs_name);
}
/*!
* @function mach_right_send_once
* Wraps a port name as a send-once right object.
*
* @param pn
* The port name. If this name is valid but does not represent a send-once
* right, the behavior of mach_right_send_once_* implementations is undefined.
*
* @result
* A new send-once right object.
*/
OS_ALWAYS_INLINE OS_WARN_RESULT
static inline mach_right_send_once_t
mach_right_send_once(mach_port_name_t pn)
{
mach_right_send_once_t mrso = {pn};
return mrso;
}
/*!
* @function mach_right_send_once_valid
* Checks if the given send-once right object is valid.
*
* @param mrso
* The send-once right object to check.
*
* @result
* A Boolean indicating whether the right is valid.
*/
OS_ALWAYS_INLINE OS_WARN_RESULT
static inline bool
mach_right_send_once_valid(mach_right_send_once_t mrso)
{
return MACH_PORT_VALID(mrso.mrso_name);
}
/*!
* @typedef mach_right_flags_t
* Flags influencing the behavior of a constructed Mach port.
*
* @const MACH_RIGHT_RECV_INIT
* No flags set. This value is suitable for initialization purposes.
*
* @const MACH_RIGHT_RECV_UNGUARDED
* The given context should not serve as a guard for the underlying port's
* destruction.
*
* @const MACH_RIGHT_RECV_FLAG_STRICT
* Apply strict guarding for the constructed Mach port.
*
* @const MACH_RIGHT_RECV_FLAG_IMMOVABLE
* The constructed Mach port's receive right will be immovable.
*/
OS_ENUM(mach_right_flags, uint64_t,
MACH_RIGHT_RECV_FLAG_INIT = 0,
MACH_RIGHT_RECV_FLAG_UNGUARDED = (1 << 0),
MACH_RIGHT_RECV_FLAG_STRICT = (1 << 1),
MACH_RIGHT_RECV_FLAG_IMMOVABLE = (1 << 2),
);
/*!
* @function mach_right_recv_construct
* Allocates a new Mach port and returns the receive right to the caller.
*
* @param flags
* Flags to influence the behavior of the new port.
*
* @param sr
* If non-NULL, will be filled in with the name of a send right which
* corresponds to the new port. The caller is responsible for disposing of this
* send right with {@link mach_right_send_release}.
*
* @param ctx
* Context to be associated with the new port. By default, this context must be
* passed to {@link mach_right_recv_destruct} in order to destroy the underlying
* port. This requirement may be elided with the
* {@link MACH_RIGHT_RECV_UNGUARDED} flag.
*
* @result
* A new port handle which refers to the receive right for the newly-created
* port. The caller is responsible for disposing of this handle with
* {@link mach_right_recv_destruct}.
*
* @discussion
* The implementation will abort on any failure to allocate a new port object in
* the kernel. Thus the caller may assert that a new, valid receive right is
* always returned.
*/
OS_EXPORT OS_WARN_RESULT
mach_right_recv_t
mach_right_recv_construct(mach_right_flags_t flags,
mach_right_send_t *_Nullable sr, uintptr_t ctx);
/*!
* @function mach_right_recv_destruct
* Closes the port referred to by the given receive right.
*
* @param r
* The receive right for the port to manipulate.
*
* @param s
* A pointer to the send right to dispose of. If NULL is given, no attempt will
* be made to clean up any send right associated with the port. If the name of
* the given send right does not match the name of the given receive right, the
* implementation's behavior is undefined.
*
* @param ctx
* The context which guards the underlying port destruction. If the receive
* right was created with {@link MACH_RIGHT_RECV_UNGUARDED}, this parameter is
* ignored.
*
* @discussion
* If a send right is passed, the implementation performs the moral equivalent
* of
*
* mach_right_recv_destruct(r, MACH_PORT_NULL, ctx);
* mach_right_send_release(s);
*
* except in a more efficient manner, requiring only one system call.
*
* The implementation will abort on any failure to dispose of the port. As such,
* this routine should only be used on ports that are known to be under the
* caller's complete control.
*/
OS_EXPORT
void
mach_right_recv_destruct(mach_right_recv_t r, mach_right_send_t *_Nullable s,
uintptr_t ctx);
/*!
* @function mach_right_send_create
* Creates a send right to the port referenced by the given receive right.
*
* @param r
* The receive right for the port for which to create the send right.
*
* @result
* The name of the new send right. The caller is responsible for disposing of
* this send right with {@link mach_right_send_release}.
*
* This operation will increment the make-send count of the port referenced by
* the given receive right.
*
* @discussion
* The implementation will abort on any failure to create the send right. As
* such, this routine should only be used on ports that are known to be under
* the caller's complete control.
*/
OS_EXPORT OS_WARN_RESULT
mach_right_send_t
mach_right_send_create(mach_right_recv_t r);
/*!
* @function mach_right_send_retain
* Increments the user reference count for the given send right.
*
* @param s
* The send right to manipulate.
*
* @result
* If the reference count was successfully incremented, the given port name is
* returned. If either MACH_PORT_NULL or MACH_PORT_DEAD are given, the given
* value is returned. If the given send right became a dead name before or
* during the attempt to retain the send right, MACH_PORT_DEAD is returned.
*
* If the implementation encounters any other failure condition, it will abort.
*/
OS_EXPORT OS_WARN_RESULT
mach_right_send_t
mach_right_send_retain(mach_right_send_t s);
/*!
* @function mach_right_send_release
* Decrements the user reference count for the given send right.
*
* @param s
* The send right to manipulate.
*
* @discussion
* If the given send right became a dead name before or during the attempt to
* release it, the implementation will dispose of that dead name.
*
* If the implementation encounters any other failure condition, it will abort.
*/
OS_EXPORT
void
mach_right_send_release(mach_right_send_t s);
/*!
* @function mach_right_send_once_create
* Creates a send-once right from the given receive right.
*
* @param r
* The receive right for the port for which to create the send-once right.
*
* @result
* The newly-created send-once right.
*
* @discussion
* The implementation will abort on any failure to allocate a new send-once
* right, and therefore the caller should only provide a receive right which is
* under its complete control. The caller may assert that a new, valid send-once
* right is always returned.
*
* The returned send-once right will never share a name with the given receive
* right. A send-once right must be consumed either by using it to send a
* message or by consuming it with {@link mach_right_send_once_consume}.
*
* The returned right does not support retain/release semantics despite the
* presence of "create" in the name.
*/
OS_EXPORT OS_WARN_RESULT
mach_right_send_once_t
mach_right_send_once_create(mach_right_recv_t r);
/*!
* @function mach_right_send_once_consume
* Consumes the given send-once right.
*
* @param so
* The send-once right to manipulate.
*
* @discussion
* If the given send-once right became a dead name before or during the attempt
* to release it, the implementation will dispose of that dead name.
*
* If the implementation encounters any other failure condition, it will abort.
*
* This operation will cause a send-once notification to be delivered to the
* port to which the send-once right refers unless the right is a dead name, in
* which case there are no side effects.
*/
OS_EXPORT
void
mach_right_send_once_consume(mach_right_send_once_t so);
__END_DECLS;
#endif // __MACH_RIGHT_PRIVATE_H