util/mach/exc_client_variants.h

// Copyright 2014 The Crashpad Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef CRASHPAD_UTIL_MACH_EXC_CLIENT_VARIANTS_H_
#define CRASHPAD_UTIL_MACH_EXC_CLIENT_VARIANTS_H_

#include <mach/mach.h>

#include "util/mach/mach_extensions.h"

namespace crashpad {

//! \brief Calls the appropriate `*exception_raise*()` function for the
//!     specified \a behavior.
//!
//! The function called will be `exception_raise()` for `EXCEPTION_DEFAULT`,
//! `exception_raise_state()` for `EXCEPTION_STATE`, or
//! `exception_raise_state_identity()` for `EXCEPTION_STATE_IDENTITY`. If
//! `MACH_EXCEPTION_CODES` is also set, the function called will instead be
//! `mach_exception_raise()`, `mach_exception_raise_state()` or
//! `mach_exception_raise_state_identity()`, respectively.
//!
//! This function does not fetch the existing thread state for \a behavior
//! values that require a thread state. The caller must provide the existing
//! thread state in the \a flavor, \a old_state, and \a old_state_count
//! parameters for \a behavior values that require a thread state. Thread states
//! may be obtained by calling `thread_get_state()` if needed. Similarly, this
//! function does not do anything with the new thread state returned for these
//! \a behavior values. Callers that wish to make use of the new thread state
//! may do so by using the returned \a flavor, \a new_state, and \a
//! new_state_count values. Thread states may be set by calling
//! `thread_set_state()` if needed.
//!
//! \a thread and \a task are only used when \a behavior indicates that the
//! exception message will carry identity information, when it has the value
//! `EXCEPTION_DEFAULT` or `EXCEPTION_STATE_IDENTITY`, possibly with
//! `MACH_EXCEPTION_CODES` also set. In other cases, these parameters are unused
//! and may be set to `THREAD_NULL` and `TASK_NULL`, respectively.
//!
//! \a flavor, \a old_state, \a old_state_count, \a new_state, and \a
//! new_state_count are only used when \a behavior indicates that the exception
//! message will carry thread state information, when it has the value
//! `EXCEPTION_STATE` or `EXCEPTION_STATE_IDENTITY`, possibly with
//! `MACH_EXCEPTION_CODES` also set. In other cases, these parameters are unused
//! and may be set to `0` (\a old_state_count) or `nullptr` (the remaining
//! parameters).
//!
//! Except as noted, the parameters and return value are equivalent to those of
//! the `*exception_raise*()` family of functions.
//!
//! \param[in] behavior The exception behavior, which dictates which function
//!     will be called. It is an error to call this function with an invalid
//!     value for \a behavior.
//! \param[in] exception_port
//! \param[in] thread
//! \param[in] task
//! \param[in] exception
//! \param[in] code If \a behavior indicates a behavior without
//!     `MACH_EXCEPTION_CODES`, the elements of \a code will be truncated in
//!     order to be passed to the appropriate exception handler.
//! \param[in] code_count
//! \param[in,out] flavor
//! \param[in] old_state
//! \param[in] old_state_count
//! \param[out] new_state
//! \param[out] new_state_count
//!
//! \return The return value of the function called.
kern_return_t UniversalExceptionRaise(exception_behavior_t behavior,
                                      exception_handler_t exception_port,
                                      thread_t thread,
                                      task_t task,
                                      exception_type_t exception,
                                      const mach_exception_data_type_t* code,
                                      mach_msg_type_number_t code_count,
                                      thread_state_flavor_t* flavor,
                                      ConstThreadState old_state,
                                      mach_msg_type_number_t old_state_count,
                                      thread_state_t new_state,
                                      mach_msg_type_number_t* new_state_count);

}  // namespace crashpad

#endif  // CRASHPAD_UTIL_MACH_EXC_CLIENT_VARIANTS_H_