1/*===------- llvm-c/Error.h - llvm::Error class C Interface -------*- C -*-===*\
2|* *|
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4|* Exceptions. *|
5|* See https://llvm.org/LICENSE.txt for license information. *|
6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7|* *|
8|*===----------------------------------------------------------------------===*|
9|* *|
10|* This file defines the C interface to LLVM's Error class. *|
11|* *|
12\*===----------------------------------------------------------------------===*/
13
14#ifndef LLVM_C_ERROR_H
15#define LLVM_C_ERROR_H
16
17#include "llvm-c/ExternC.h"
18#include "llvm-c/Visibility.h"
19
20LLVM_C_EXTERN_C_BEGIN
21
22/**
23 * @defgroup LLVMCError Error Handling
24 * @ingroup LLVMC
25 *
26 * @{
27 */
28
29#define LLVMErrorSuccess 0
30
31/**
32 * Opaque reference to an error instance. Null serves as the 'success' value.
33 */
34typedef struct LLVMOpaqueError *LLVMErrorRef;
35
36/**
37 * Error type identifier.
38 */
39typedef const void *LLVMErrorTypeId;
40
41/**
42 * Returns the type id for the given error instance, which must be a failure
43 * value (i.e. non-null).
44 */
45LLVM_C_ABI LLVMErrorTypeId LLVMGetErrorTypeId(LLVMErrorRef Err);
46
47/**
48 * Dispose of the given error without handling it. This operation consumes the
49 * error, and the given LLVMErrorRef value is not usable once this call returns.
50 * Note: This method *only* needs to be called if the error is not being passed
51 * to some other consuming operation, e.g. LLVMGetErrorMessage.
52 */
53LLVM_C_ABI void LLVMConsumeError(LLVMErrorRef Err);
54
55/**
56 * Report a fatal error if Err is a failure value.
57 *
58 * This function can be used to wrap calls to fallible functions ONLY when it is
59 * known that the Error will always be a success value.
60 */
61LLVM_C_ABI void LLVMCantFail(LLVMErrorRef Err);
62
63/**
64 * Returns the given string's error message. This operation consumes the error,
65 * and the given LLVMErrorRef value is not usable once this call returns.
66 * The caller is responsible for disposing of the string by calling
67 * LLVMDisposeErrorMessage.
68 */
69LLVM_C_ABI char *LLVMGetErrorMessage(LLVMErrorRef Err);
70
71/**
72 * Dispose of the given error message.
73 */
74LLVM_C_ABI void LLVMDisposeErrorMessage(char *ErrMsg);
75
76/**
77 * Returns the type id for llvm StringError.
78 */
79LLVM_C_ABI LLVMErrorTypeId LLVMGetStringErrorTypeId(void);
80
81/**
82 * Create a StringError.
83 */
84LLVM_C_ABI LLVMErrorRef LLVMCreateStringError(const char *ErrMsg);
85
86/**
87 * @}
88 */
89
90LLVM_C_EXTERN_C_END
91
92#endif
93