aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSverker Eriksson <[email protected]>2015-04-13 18:30:18 +0200
committerSverker Eriksson <[email protected]>2015-04-15 19:02:13 +0200
commit9f903f6031ff40e415c8807aca19f699d0b553f1 (patch)
tree2ca7ce401b6b6dd7859f834a982569ad6a26b3e2
parent80683a598eda7bea94eb54f9f9557e020b2fdb2c (diff)
downloadotp-9f903f6031ff40e415c8807aca19f699d0b553f1.tar.gz
otp-9f903f6031ff40e415c8807aca19f699d0b553f1.tar.bz2
otp-9f903f6031ff40e415c8807aca19f699d0b553f1.zip
erts: Clearify erl_nif documentation about badarg exception
Also state that maximum atom length is 255 characters.
-rw-r--r--erts/doc/src/erl_nif.xml44
1 files changed, 27 insertions, 17 deletions
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index feba6daaa0..afeec69f02 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -899,26 +899,34 @@ typedef enum {
<fsummary>Create an atom term</fsummary>
<desc><p>Create an atom term from the null-terminated C-string <c>name</c>
with iso-latin-1 encoding. If the length of <c>name</c> exceeds the maximum length
- allowed for an atom, <c>enif_make_atom</c> returns a <c>badarg</c> exception.</p></desc>
+ allowed for an atom (255 characters), <c>enif_make_atom</c> invokes
+ <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.
+ </p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)</nametext></name>
<fsummary>Create an atom term</fsummary>
<desc><p>Create an atom term from the string <c>name</c> with length <c>len</c>.
Null-characters are treated as any other characters. If <c>len</c> is greater than the maximum length
- allowed for an atom, <c>enif_make_atom</c> returns a <c>badarg</c> exception.</p></desc>
+ allowed for an atom (255 characters), <c>enif_make_atom</c> invokes
+ <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.
+ </p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_badarg(ErlNifEnv* env)</nametext></name>
<fsummary>Make a badarg exception.</fsummary>
- <desc><p>Make a badarg exception to be returned from a NIF, and set
- an associated exception reason in <c>env</c>. If
- <c>enif_make_badarg</c> is called, the term it returns <em>must</em>
- be returned from the function that called it. No other return value
- is allowed. Once a NIF or any function it calls invokes <c>enif_make_badarg</c>,
- the runtime ensures that a <c>badarg</c> exception is raised when the NIF
- returns, even if the NIF attempts to return a non-exception term instead.
- Also, the term returned from <c>enif_make_badarg</c> may be passed only to
- <seealso marker="#enif_is_exception">enif_is_exception</seealso> and
- not to any other NIF API function.</p></desc>
+ <desc><p>Make a badarg exception to be returned from a NIF, and associate
+ it with the environment <c>env</c>. Once a NIF or any function
+ it calls invokes <c>enif_make_badarg</c>, the runtime ensures that a
+ <c>badarg</c> exception is raised when the NIF returns, even if the NIF
+ attempts to return a non-exception term instead.
+ The return value from <c>enif_make_badarg</c> may only be used as
+ return value from the NIF that invoked it (direct or indirectly)
+ or be passed to
+ <seealso marker="#enif_is_exception">enif_is_exception</seealso>, but
+ not to any other NIF API function.</p>
+ <note><p>In earlier versions (older than erts-7.0, OTP 18) the return value
+ from <c>enif_make_badarg</c> had to be returned from the NIF. This
+ requirement is now lifted as the return value from the NIF is ignored
+ if <c>enif_make_badarg</c> has been invoked.</p></note></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)</nametext></name>
<fsummary>Make a binary term.</fsummary>
@@ -936,8 +944,9 @@ typedef enum {
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_double(ErlNifEnv* env, double d)</nametext></name>
<fsummary>Create a floating-point term</fsummary>
<desc><p>Create a floating-point term from a <c>double</c>. If the <c>double</c> argument is
- not finite or is NaN, <c>enif_make_double</c> returns a <c>badarg</c> exception.</p>
- </desc>
+ not finite or is NaN, <c>enif_make_double</c> invokes
+ <seealso marker="#enif_make_badarg">enif_make_badarg</seealso>.
+ </p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)</nametext></name>
<fsummary>Create an existing atom term</fsummary>
@@ -946,7 +955,8 @@ typedef enum {
<seealso marker="#ErlNifCharEncoding">encode</seealso>. If the atom
already exists store the term in <c>*atom</c> and return true, otherwise
return false. If the length of <c>name</c> exceeds the maximum length
- allowed for an atom, <c>enif_make_existing_atom</c> returns false.</p></desc>
+ allowed for an atom (255 characters), <c>enif_make_existing_atom</c>
+ returns false.</p></desc>
</func>
<func><name><ret>int</ret><nametext>enif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)</nametext></name>
<fsummary>Create an existing atom term</fsummary>
@@ -955,8 +965,8 @@ typedef enum {
<seealso marker="#ErlNifCharEncoding">encode</seealso>. Null-characters
are treated as any other characters. If the atom already exists store the term
in <c>*atom</c> and return true, otherwise return false. If <c>len</c> is greater
- than the maximum length allowed for an atom, <c>enif_make_existing_atom_len</c>
- returns false.</p></desc>
+ than the maximum length allowed for an atom (255 characters),
+ <c>enif_make_existing_atom_len</c> returns false.</p></desc>
</func>
<func><name><ret>ERL_NIF_TERM</ret><nametext>enif_make_int(ErlNifEnv* env, int i)</nametext></name>
<fsummary>Create an integer term</fsummary>