From 9f903f6031ff40e415c8807aca19f699d0b553f1 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson
Date: Mon, 13 Apr 2015 18:30:18 +0200
Subject: erts: Clearify erl_nif documentation about badarg exception
Also state that maximum atom length is 255 characters.
---
erts/doc/src/erl_nif.xml | 44 +++++++++++++++++++++++++++-----------------
1 file 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 {
Create an atom term
Create an atom term from the null-terminated C-string name
with iso-latin-1 encoding. If the length of name exceeds the maximum length
- allowed for an atom, enif_make_atom returns a badarg exception.
+ allowed for an atom (255 characters), enif_make_atom invokes
+ enif_make_badarg.
+
ERL_NIF_TERMenif_make_atom_len(ErlNifEnv* env, const char* name, size_t len)
Create an atom term
Create an atom term from the string name with length len.
Null-characters are treated as any other characters. If len is greater than the maximum length
- allowed for an atom, enif_make_atom returns a badarg exception.
+ allowed for an atom (255 characters), enif_make_atom invokes
+ enif_make_badarg.
+
ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env)
Make a badarg exception.
- Make a badarg exception to be returned from a NIF, and set
- an associated exception reason in env. If
- enif_make_badarg is called, the term it returns must
- be returned from the function that called it. No other return value
- is allowed. Once a NIF or any function it calls invokes enif_make_badarg,
- the runtime ensures that a badarg exception is raised when the NIF
- returns, even if the NIF attempts to return a non-exception term instead.
- Also, the term returned from enif_make_badarg may be passed only to
- enif_is_exception and
- not to any other NIF API function.
+ Make a badarg exception to be returned from a NIF, and associate
+ it with the environment env. Once a NIF or any function
+ it calls invokes enif_make_badarg, the runtime ensures that a
+ badarg exception is raised when the NIF returns, even if the NIF
+ attempts to return a non-exception term instead.
+ The return value from enif_make_badarg may only be used as
+ return value from the NIF that invoked it (direct or indirectly)
+ or be passed to
+ enif_is_exception, but
+ not to any other NIF API function.
+ In earlier versions (older than erts-7.0, OTP 18) the return value
+ from enif_make_badarg had to be returned from the NIF. This
+ requirement is now lifted as the return value from the NIF is ignored
+ if enif_make_badarg has been invoked.
ERL_NIF_TERMenif_make_binary(ErlNifEnv* env, ErlNifBinary* bin)
Make a binary term.
@@ -936,8 +944,9 @@ typedef enum {
ERL_NIF_TERMenif_make_double(ErlNifEnv* env, double d)
Create a floating-point term
Create a floating-point term from a double. If the double argument is
- not finite or is NaN, enif_make_double returns a badarg exception.
-
+ not finite or is NaN, enif_make_double invokes
+ enif_make_badarg.
+
intenif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode)
Create an existing atom term
@@ -946,7 +955,8 @@ typedef enum {
encode. If the atom
already exists store the term in *atom and return true, otherwise
return false. If the length of name exceeds the maximum length
- allowed for an atom, enif_make_existing_atom returns false.
+ allowed for an atom (255 characters), enif_make_existing_atom
+ returns false.
intenif_make_existing_atom_len(ErlNifEnv* env, const char* name, size_t len, ERL_NIF_TERM* atom, ErlNifCharEncoding encoding)
Create an existing atom term
@@ -955,8 +965,8 @@ typedef enum {
encode. Null-characters
are treated as any other characters. If the atom already exists store the term
in *atom and return true, otherwise return false. If len is greater
- than the maximum length allowed for an atom, enif_make_existing_atom_len
- returns false.
+ than the maximum length allowed for an atom (255 characters),
+ enif_make_existing_atom_len returns false.
ERL_NIF_TERMenif_make_int(ErlNifEnv* env, int i)
Create an integer term
--
cgit v1.2.3