Add ExcServerCopyState()

util/mach/exc_server_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,
@@ skipping 181 matching lines @@
 //!     a state-carrying behavior.
 //!
 //! \return `KERN_SUCCESS` or `MACH_RCV_PORT_DIED`. `KERN_SUCCESS` is used when
 //!     \a behavior is not a state-carrying behavior, or when it is a
 //!     state-carrying behavior and \a set_thread_state is `true`.
 //!     `MACH_RCV_PORT_DIED` is used when \a behavior is a state-carrying
 //!     behavior and \a set_thread_state is `false`.
 kern_return_t ExcServerSuccessfulReturnValue(exception_behavior_t behavior,
                                              bool set_thread_state);
 
+//! \brief Copies the old state to the new state for state-carrying exceptions.
+//!
+//! When the kernel sends a state-carrying exception request and the response is
+//! successful (`MACH_MSG_SUCCESS`, a synonym for `KERN_SUCCESS`), it will set
+//! a new thread state based on \a new_state and \a new_state_count. To ease
+//! initialization of the new state, this function copies \a old_state and
+//! \a old_state_count. This is only done if \a behavior indicates a
+//! state-carrying exception.
+//!
+//! \param[in] behavior The behavior of the exception handler as invoked. This
+//!     may be taken directly from the \a behavior parameter of
+//!     internal::SimplifiedExcServer::Interface::CatchException(), for example.
+//! \param[in] old_state The original state value. This may be taken directly
+//!     from the \a old_state parameter of
+//!     internal::SimplifiedExcServer::Interface::CatchException(), for example.
+//! \param[in] old_state_count The number of significant `natural_t` words in \a
+//!     old_state. This may be taken directly from the \a old_state_count
+//!     parameter of internal::SimplifiedExcServer::Interface::CatchException(),
+//!     for example.
+//! \param[out] new_state The state value to be set. This may be taken directly
+//!     from the \a new_state parameter of
+//!     internal::SimplifiedExcServer::Interface::CatchException(), for example.
+//!     This parameter is untouched if \a behavior is not state-carrying.
+//! \param[inout] new_state_count On entry, the number of `natural_t` words
+//!     available to be written to in \a new_state. On return, the number of
+//!     significant `natural_t` words in \a new_state. This may be taken
+//!     directly from the \a new_state_count parameter of
+//!     internal::SimplifiedExcServer::Interface::CatchException(), for example.
+//!     This parameter is untouched if \a behavior is not state-carrying. If \a
+//!     \a behavior is state-carrying, this parameter should be at least as
+//!     large as \a old_state_count.
+void ExcServerCopyState(exception_behavior_t behavior,
+                        const natural_t* old_state,

[Robert Sesek, 2015/03/31 23:03:31]

Why use natural_t here instead of thread_state_t ?

[Mark Mentovai, 2015/03/31 23:13:23]

Robert Sesek wrote:
Same as everywhere else this exists as an in-parameter: I want the data to be
const, not the pointer. thread_state_t is defined as natural_t*.

Do you think it’s worth a ConstThreadState typedef defined as const natural_t*?

[Robert Sesek, 2015/04/01 16:07:00]

It's a little subtle, but no I think it's fine.

+                        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_SERVER_VARIANTS_H_