mirror of
https://github.com/boostorg/outcome.git
synced 2026-02-02 09:02:11 +00:00
118 lines
7.1 KiB
HTML
118 lines
7.1 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>C system error results - Boost.Outcome documentation</title>
|
|
<link rel="stylesheet" href="../../../css/boost.css" type="text/css">
|
|
<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
|
|
|
|
<link rel="icon" href="../../../images/favicon.ico" type="image/ico"/>
|
|
<body><div class="spirit-nav">
|
|
<a accesskey="p" href="../../../experimental/c-api/from-c.html"><img src="../../../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../../../experimental/c-api/from-c.html"><img src="../../../images/up.png" alt="Up"></a>
|
|
<a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../../../experimental/c-api/from-c/declare.html"><img src="../../../images/next.png" alt="Next"></a></div><div id="content">
|
|
<div class="titlepage"><div><div><h1 style="clear: both">C system error results</h1></div></div></div>
|
|
<p>In v2.2.11, C Result support went from second tier to first tier status, and
|
|
now you can create, query and manipulate a subset of Result types entirely from
|
|
within C by including <code><boost/outcome/experimental/result.h></code>.</p>
|
|
|
|
<p>The subset supported are those <code>result<T, E></code> which are <a href="../../../experimental/status_result.html">a <code>status_result<T></code></a>
|
|
i.e. the <code>E</code> is hardcoded to <code>experimental::error</code> which is the type erased runtime
|
|
polymorphic holder for any errored <code>status_code</code> whose payload is not bigger
|
|
than an <code>intptr_t</code>. This is the most useful subset of Outcome Experimental’s
|
|
possible Result types, allowing arbitrary custom error coding schemes from
|
|
any unknown source to work seamlessly with all others, including errors from
|
|
the system or third party libraries.</p>
|
|
|
|
<p>The operations available to C are:</p>
|
|
|
|
<dl>
|
|
<dt><code>BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T)</code>
|
|
<dd>Declares to C a <code>status_result<T></code> type uniquely
|
|
identified by <code>ident</code>. <code>T</code> is available at the
|
|
member variable <code>.value</code>, and <code>struct cxx_status_code_system</code>
|
|
is available at the member variable <code>.error</code>. If in C++,
|
|
implements C extern functions for making successful and failure results
|
|
of this type. If you call this from within
|
|
C++, make SURE it is not within a <code>extern "C"</code> block!
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM(ident)</code>
|
|
<dd>A reference to a previously declared <code>status_result</code> type with
|
|
unique <code>ident</code>.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_SUCCESS(ident, expr)</code> (needs C++ counterpart linked into final binary)
|
|
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
|
|
with a successful value of type <code>T</code>.
|
|
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_POSIX(ident, expr)</code> (needs C++ counterpart linked into final binary)
|
|
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
|
|
with a failure of type <code>posix_code</code> representing a POSIX <code>errno</code>.
|
|
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_SYSTEM(ident, expr)</code> (needs C++ counterpart linked into final binary)
|
|
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
|
|
with a failure of type <code>posix_code</code> representing a POSIX <code>errno</code>
|
|
if on POSIX; if on Windows then a failure of type <code>win32_code</code>
|
|
representing a Win32 error code from a Windows API.
|
|
|
|
<br><br>
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_HAS_VALUE(r)</code>
|
|
<dd>Evaluates to 1 (true) if the input <code>result</code> has a value.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_HAS_ERROR(r)</code>
|
|
<dd>Evaluates to 1 (true) if the input <code>result</code> has an error.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)</code>
|
|
<dd>Evaluates to 1 (true) if the input <code>result</code>'s error value
|
|
is a code in the POSIX <code>errno</code> domain.
|
|
<br><br>
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(expr)</code>
|
|
<dd>If the <code>status_result</code> returned by <code>expr</code> is
|
|
errored, exit the current function returning the result. This obviously
|
|
requires that the return type of the current function matches that of <code>
|
|
expr</code>.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(cleanup, expr)</code>
|
|
<dd>Same as the above, but execute <code>cleanup</code> just before exiting the function
|
|
if returning failure.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, cleanup, expr)</code>
|
|
<dd>Same as the above, but set <code>var</code> equal to the result's <code>.value</code> on success.
|
|
|
|
<dt><code>BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, ident, cleanup, expr)</code>
|
|
<dd>Same as the above, but use <code>ident</code> as the return type instead. This allows
|
|
the return type of the calling function to differ from that of <code>expr</code>.
|
|
<br><br>
|
|
<dt><code>BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, uuid, {enum mapping-sequence, ...})</code>
|
|
<dd>This declares to C an extern function which creates a <code>status_result</code>
|
|
from a C enum. If in C++, it implements a <code>quick_status_code_from_enum</code> for
|
|
the C enum and the associated extern function, and you will need to supply <code>uuid</code>
|
|
and the appropriate enum value mapping sequence <a href="../../../experimental/worked-example.html">
|
|
as per the <code>quick_status_code_from_enum</code> documentation</a>.
|
|
<dt><code>BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, expr)</code> (needs C++ counterpart linked into final binary)
|
|
<dd>This invokes the aforementioned extern function which creates a <code>status_result</code>
|
|
from a C enum.
|
|
</dl>
|
|
|
|
<p>The operations available to C++ are:</p>
|
|
|
|
<dl>
|
|
<dt><code>BOOST_OUTCOME_C_TO_RESULT_SYSTEM_CODE(ident, status_code<T>)</code>
|
|
<dd>Returns a previously declared C Result from its matching C++ <code>status_code</code>.
|
|
NOTE that the destructor of the C++ status code is NOT called. If this is important
|
|
to your status code, it is 100% on you to ensure that your C Result reenters a C++
|
|
Result at the end of its lifetime.
|
|
|
|
<dt><code>to_result(any C Result)</code>
|
|
<dd>This is an overloaded C++ free function which returns the C++ status_code<T>
|
|
matching its input C Result.
|
|
</dl>
|
|
|
|
<p>Using the above you can write C code using Outcome.Experimental’s Result type
|
|
quite effectively. Let’s look at an example of use next.</p>
|
|
|
|
|
|
</div><p><small>Last revised: July 17, 2024 at 17:54:05 +0100</small></p>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="../../../experimental/c-api/from-c.html"><img src="../../../images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="../../../experimental/c-api/from-c.html"><img src="../../../images/up.png" alt="Up"></a>
|
|
<a accesskey="h" href="../../../index.html"><img src="../../../images/home.png" alt="Home"></a><a accesskey="n" href="../../../experimental/c-api/from-c/declare.html"><img src="../../../images/next.png" alt="Next"></a></div></body>
|
|
</html>
|