native_client_sdk/src/libraries/error_handling/error_handling.h

   1 /*
   2  * Copyright (c) 2013 The Chromium Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 #ifndef ERROR_HANDLING_ERROR_HANDLING_H_
   8 #define ERROR_HANDLING_ERROR_HANDLING_H_
   9
  10 #include "error_handling/string_stream.h"
  11 #include "sdk_util/macros.h"
  12
  13 EXTERN_C_BEGIN
  14
  15 struct NaClExceptionContext;
  16
  17 typedef void (*EHRawHandler)(struct NaClExceptionContext* context);
  18 typedef void (*EHJsonHandler)(const char* str);
  19
  20 typedef struct {
  21   uint32_t prog_ctr;
  22   uint32_t frame_ptr;
  23   uint32_t next_ptr;
  24 } EHFrame;
  25
  26
  27 /** Initialize error handling.
  28  *
  29  * Initializes the error handling to catch untrusted exceptions.  The init
  30  * functions will install an untrusted exception handler.
  31  *
  32  * The raw form will install the provided handler directly to the exception
  33  * system.
  34  *
  35  * The json form will install a default handler which will walk the stack
  36  * creating a valid JSON string which is passed to the provided handler.
  37  *
  38  * NOTE: Exception handling is enabled process wide.
  39  * NOTE: Exception handling is not guaranteed to be available so it should
  40  * not be considered an error if the request fails.
  41  */
  42 void EHRequestExceptionsRaw(EHRawHandler callback);
  43 void EHRequestExceptionsJson(EHJsonHandler callback);
  44
  45
  46 /** Request an alternate signal handling stack for this thread.
  47  *
  48  * Specifies an alternate stack which will be used when this thread enters
  49  * the exception handler.  This is useful in cases when the threads original
  50  * stack may have overflowed or may be too small to handler the exception.
  51  *
  52  * Returns the allocated stack or MAP_FAILED.
  53  *
  54  * NOTE: Unlike the handler, this is a per thread call.
  55  * NOTE: If the allocation fails, the exception will still take place on the
  56  * thread's original stack.
  57  */
  58 void *EHRequestExceptionStackOnThread(size_t stack_size);
  59
  60
  61 /** Determine if NaCl will forward exceptions.
  62  *
  63  * Returns non-zero if a hander has been installed and exceptions will
  64  * be forwarded.
  65  *
  66  * NOTE: Exception handling is not guarenteed to be available so it should
  67  * not be considered an error if the request fails.
  68  */
  69 int EHHanderInstalled();
  70
  71
  72 /** Fill an exception frame from an exception context. */
  73 int EHGetTopFrame(sstream_t* ss, struct NaClExceptionContext* context,
  74                   EHFrame* frame);
  75
  76
  77 /** Unwind the stack by one frame.
  78  *
  79  * Returns zero once it failes to unwind.
  80  */
  81 int EHUnwindFrame(EHFrame* frame);
  82
  83 EXTERN_C_END
  84
  85 #endif  // ERROR_HANDLING_ERROR_HANDLING_H_
  86