From f0cfce64b6a061ffeafeda254734f0b1f2f452fd Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Sun, 1 Mar 2015 12:33:20 -0500 Subject: Ensure NIF term creation disallows illegal values Add a check to enif_make_double to see if its double argument is infinity or NaN, returning a badarg exception if it is. Change the erl_nif documentation to specify that enif_make_double returns a badarg exception if its double argument is either infinity or NaN. Add tests to nif_SUITE for this change. Add checks to the enif_make* functions for atoms to prevent the creation of atoms whose name lengths are greater than the allowed maximum atom length. The enif_make_atom and enif_make_atom_len functions now return a badarg exception if the input string is too long. The enif_make_existing_atom and enif_make_existing_atom_len functions return false if the input string is too long. Change the erl_nif documentation to reflect the changes to these functions. Add tests to nif_SUITE for these changes. Add a field to ErlNifEnv to track that a NIF has raised an exception via enif_make_badarg. If a NIF calls enif_make_badarg but then ignores its return value and instead tries to return a non-exception term as its return value, the runtime still raises a badarg. This is needed to prevent enif_make_badarg values resulting from calls to enif_make_double, enif_make_atom, or enif_make_atom_len from being erroneously stored within other terms and returned from a NIF. Calling enif_make_badarg but not returning its return value has been documented as being illegal ever since enif_make_badarg was added, but the runtime has not enforced it until now. Add tests for regular and dirty NIFs to ensure that calls to enif_make_badarg result in badarg exceptions even if a NIF fails to return the result of enif_make_badarg as its return value. Add documentation to enif_make_badarg to specify that calling it raises a badarg even if a NIF ignores its return value. --- erts/doc/src/erl_nif.xml | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 3de94be9ff..feba6daaa0 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -898,12 +898,14 @@ typedef enum { ERL_NIF_TERMenif_make_atom(ErlNifEnv* env, const char* name) Create an atom term

Create an atom term from the null-terminated C-string name - with iso-latin-1 encoding.

 + 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.

 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.

 + 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.

 ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env) Make a badarg exception. @@ -911,8 +913,10 @@ typedef enum { 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. Also, the term returned from enif_make_badarg may - be passed only to + 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.

 @@ -931,7 +935,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.

 +

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.

+ intenif_make_existing_atom(ErlNifEnv* env, const char* name, ERL_NIF_TERM* atom, ErlNifCharEncoding encode) Create an existing atom term @@ -939,7 +945,8 @@ typedef enum { the null-terminated C-string name with encoding encode. If the atom already exists store the term in *atom and return true, otherwise - return false.

+ return false. If the length of name exceeds the maximum length + allowed for an atom, 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 @@ -947,7 +954,9 @@ typedef enum { string name with length len and encoding 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.

+ 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.

 ERL_NIF_TERMenif_make_int(ErlNifEnv* env, int i) Create an integer term -- cgit v1.2.3 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(-) (limited to 'erts/doc/src/erl_nif.xml') 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 From 80e15112a6e31e053ad0670096c23bda2fc341e4 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 14 Apr 2015 15:18:33 +0200 Subject: erts: Add enif_has_pending_exception --- erts/doc/src/erl_nif.xml | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index afeec69f02..5c912e0fe3 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -806,6 +806,12 @@ typedef enum { and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned long.

 + intenif_has_pending_exception(ErlNifEnv* env) + Check if an exception has been raised. +

Return true if a pending exception is associated + with the environment env. The only possible exception is currently + badarg (see enif_make_badarg).

 + intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) Inspect the content of a binary

Initialize the structure pointed to by bin with @@ -923,6 +929,8 @@ typedef enum { or be passed to enif_is_exception, but not to any other NIF API function.

+

See also: enif_has_pending_exception. +

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 -- cgit v1.2.3 From 308b03e8afa14e03973330942e7aacf0cc925bf2 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 14 Apr 2015 15:43:40 +0200 Subject: erts: Remove old docs about experimental NIF versions. --- erts/doc/src/erl_nif.xml | 28 ---------------------------- 1 file changed, 28 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 5c912e0fe3..4bad8b253c 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -66,34 +66,6 @@ -

The NIF concept is officially supported from R14B. NIF source code - written for earlier experimental versions might need adaption to run on R14B - or later versions:

- - No incompatible changes between R14B and R14A. - Incompatible changes between R14A and R13B04: - - Environment argument removed for enif_alloc, - enif_realloc, enif_free, enif_alloc_binary, - enif_realloc_binary, enif_release_binary, - enif_alloc_resource, enif_release_resource, - enif_is_identical and enif_compare. - Character encoding argument added to enif_get_atom - and enif_make_existing_atom. - Module argument added to enif_open_resource_type - while changing name spaces of resource types from global to module local. - - - Incompatible changes between R13B04 and R13B03: - - The function prototypes of the NIFs have changed to expect argc and argv - arguments. The arity of a NIF is by that no longer limited to 3. - enif_get_data renamed as enif_priv_data. - enif_make_string got a third argument for character encoding. - - - -

A minimal example of a NIF library can look like this:

-- cgit v1.2.3 From 884afd8efb8672df2889df98b5b94f3dbb53952c Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Mon, 27 Apr 2015 23:39:37 -0400 Subject: Enhance enif_has_pending_exception Sverker Eriksson came up with the following idea: to handle a future ability for NIFs to raise more than just badarg exceptions, modify the recently-added enif_has_pending_exception function to take a second argument: a pointer to ERL_NIF_TERM. If this argument is a null pointer, ignore it. Otherwise, if the first argument, an ErlNifEnv*, has an associated exception, set the pointed-to ERL_NIF_TERM of the second argument to the value of the exception term. Add new tests and documentation for this modification. --- erts/doc/src/erl_nif.xml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 4bad8b253c..155aee2f42 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -778,11 +778,17 @@ typedef enum { and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned long.

 - intenif_has_pending_exception(ErlNifEnv* env) + intenif_has_pending_exception(ErlNifEnv* env, ERL_NIF_TERM* reason) Check if an exception has been raised.

Return true if a pending exception is associated - with the environment env. The only possible exception is currently - badarg (see enif_make_badarg).

 + with the environment env. If reason is a null pointer, ignore it. + Otherwise, if there's a pending exception associated with env, set the ERL_NIF_TERM + to which reason points to the value of the exception's term. For example, if + enif_make_badarg is called to set a + pending badarg exception, a subsequent call to enif_has_pending_exception(env, &reason) + will set reason to the atom badarg, then return true.

+

See also: enif_make_badarg.

+ intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) Inspect the content of a binary -- cgit v1.2.3 From 17735c9f3879145f43a3e4be0369b7117b1b7b84 Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Wed, 6 May 2015 23:15:04 -0400 Subject: Add enif_raise_exception Add enif_raise_exception function to allow NIFs to raise error exceptions holding any Erlang terms. This does not replace or deprecate the enif_make_badarg function, though, because raising badarg errors is so idiomatic in NIFs. Reimplement enif_make_badarg on top of enif_raise_exception. Add new tests for enif_raise_exception for both normal and dirty NIFs. Add documentation for enif_raise_exception. --- erts/doc/src/erl_nif.xml | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 155aee2f42..104d90c937 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -787,7 +787,8 @@ typedef enum { enif_make_badarg is called to set a pending badarg exception, a subsequent call to enif_has_pending_exception(env, &reason) will set reason to the atom badarg, then return true.

-

See also: enif_make_badarg.

+

See also: enif_make_badarg + and enif_raise_exception.

 intenif_inspect_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, ErlNifBinary* bin) @@ -902,12 +903,13 @@ typedef enum { 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) + The return value from enif_make_badarg may be used only as the + return value from the NIF that invoked it (directly or indirectly) or be passed to enif_is_exception, but not to any other NIF API function.

-

See also: enif_has_pending_exception. +

See also: enif_has_pending_exception + and enif_raise_exception

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 @@ -1174,6 +1176,19 @@ typedef enum { reload or upgrade.

Was previously named enif_get_data.

 + ERL_NIF_TERMenif_raise_exception(ErlNifEnv* env, ERL_NIF_TERM reason) + Raise a NIF error exception +

Create an error exception with the term reason to be returned from a NIF, + and associate it with the environment env. Once a NIF or any function it calls + invokes enif_raise_exception, the runtime ensures that the exception it creates + is raised when the NIF returns, even if the NIF attempts to return a non-exception + term instead. The return value from enif_raise_exception may be used only as + the return value from the NIF that invoked it (directly or indirectly) or be passed + to enif_is_exception, but + not to any other NIF API function.

+

See also: enif_has_pending_exception + and enif_make_badarg.

 + intenif_realloc_binary(ErlNifBinary* bin, size_t size) Change the size of a binary.

Change the size of a binary bin. The source binary -- cgit v1.2.3 From 264c4d037618a5ca8f55001855cb422d0bb5d136 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 27 May 2015 17:55:08 +0200 Subject: erts: Add docs for map functions in nif API --- erts/doc/src/erl_nif.xml | 129 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 121 insertions(+), 8 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 4bad8b253c..2cc06de0e0 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -461,8 +461,9 @@ ok independent environment with all its terms is valid until you explicitly invalidates it with enif_free_env or enif_send.

-

All elements of a list/tuple must belong to the same environment as the - list/tuple itself. Terms can be copied between environments with +

All contained terms of a list/tuple/map must belong to the same + environment as the list/tuple/map itself. Terms can be copied between + environments with enif_make_copy.

ErlNifFunc @@ -729,7 +730,18 @@ typedef enum { return true, or return false if term is not an integer or is outside the bounds of type long int.

 - intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) + intenif_get_map_size(ErlNifEnv* env, ERL_NIF_TERM term, size_t *size) + Read the size of a map term +

Set *size to the number of key-value pairs in the map term and + return true, or return false if term is not a map.

 + + intenif_get_map_value(ErlNifEnv* env, ERL_NIF_TERM map, ERL_NIF_TERM key, ERL_NIF_TERM* value) + Get the value of a key in a map +

Set *value to the value associated with key in the + map map and return true. Return false if map is not a map + or if map does not contain key.

 + + intenif_get_resource(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifResourceType* type, void** objp) Get the pointer to a resource object

Set *objp to point to the resource object referred to by term.

Return true on success or false if term is not a handle to a resource object @@ -817,6 +829,10 @@ typedef enum { Determine if a term is an exception

Return true if term is an exception.

 + intenif_is_map(ErlNifEnv* env, ERL_NIF_TERM term) + Determine if a term is a map +

Return true if term is a map, false otherwise.

 + intenif_is_number(ErlNifEnv* env, ERL_NIF_TERM term) Determine if a term is a number (integer or float)

Return true if term is a number.

 @@ -986,12 +1002,13 @@ typedef enum {

Create an ordinary list containing the elements of array arr of length cnt. An empty list is returned if cnt is 0.

 - intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM term, ERL_NIF_TERM *list) - Create the reverse list of the list term. -

Set *list to the reverse list of the list term and return true, - or return false if term is not a list. This function should only be used on + intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) + Create the reverse of a list +

Set *list_out to the reverse list of the list list_in and return true, + or return false if list_in is not a list. This function should only be used on short lists as a copy will be created of the list which will not be released until after the - nif returns.

 + nif returns.

+

The list_in term must belong to the environment env.

 ERL_NIF_TERMenif_make_long(ErlNifEnv* env, long int i) Create an integer term from a long int @@ -1007,6 +1024,36 @@ typedef enum { reallocated.

Return a pointer to the raw binary data and set *termp to the binary term.

 + ERL_NIF_TERMenif_make_new_map(ErlNifEnv* env) + Make an empty map term +

Make an empty map term.

 + + intenif_make_map_put(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM value, ERL_NIF_TERM* map_out) + Insert key-value pair in map +

Make a copy of map map_in and insert key with + value. If key already exists in map_in, the old + associated value is replaced by value. If successful set + *map_out to the new map and return true. Return false if + map_in is not a map.

+

The map_in term must belong to the environment env.

 + + intenif_make_map_update(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM new_value, ERL_NIF_TERM* map_out) + Replace value for key in map +

Make a copy of map map_in and replace the old associated + value for key with new_value. If successful set + *map_out to the new map and return true. Return false if + map_in is not a map or if it does no contain key.

+

The map_in term must belong to the environment env.

 + + intenif_make_map_remove(ErlNifEnv* env, ERL_NIF_TERM map_in, ERL_NIF_TERM key, ERL_NIF_TERM* map_out) + Remove key from map +

If map map_in contains key, make a copy of + map_in in *map_out and remove key and associated + value. If map map_in does not contain key, set + *map_out to map_in. Return true for success or false if + map_in is not a map.

+

The map_in term must belong to the environment env.

 + ERL_NIF_TERMenif_make_pid(ErlNifEnv* env, const ErlNifPid* pid) Make a pid term

Make a pid term from *pid.

 @@ -1108,6 +1155,72 @@ typedef enum { Create an integer term from an unsigned long int

Create an integer term from an unsigned long int.

 + intenif_map_iterator_create(ErlNifEnv *env, ERL_NIF_TERM map, ErlNifMapIterator *iter, ErlNifMapIteratorEntry entry) + Create a map iterator +

Create an iterator for the map map by initializing the + structure pointed to by iter. The entry argument determines + the start position of the iterator: ERL_NIF_MAP_ITERATOR_FIRST or + ERL_NIF_MAP_ITERATOR_LAST. Return true on success or false if + map is not a map.

+

A map iterator is only useful during the lifetime of the environment + env that the map belongs to. The iterator must be destroyed by + calling + enif_map_iterator_destroy.

+ +ERL_NIF_TERM key, value; +ErlNifMapIterator iter; +enif_map_iterator_create(env, my_map, ERL_NIF_MAP_ITERATOR_FIRST); + +while (enif_map_iterator_get_pair(env, &iter, &key, &value)) { + do_something(key,value); + enif_map_iterator_next(env, &iter); +} +enif_map_iterator_destroy(env, &iter); + +

The key-value pairs of a map have no defined iteration + order. The only guarantee is that the iteration order of a single map + instance is preserved during the lifetime of the environment that the map + belongs to.

+ + + + voidenif_map_iterator_destroy(ErlNifEnv *env, ErlNifMapIterator *iter) + Destroy a map iterator +

Destroy a map iterator created by + enif_map_iterator_create. +

+ + intenif_map_iterator_get_pair(ErlNifEnv *env, ErlNifMapIterator *iter, ERL_NIF_TERM *key, ERL_NIF_TERM *value) + Get key and value at current map iterator position +

Get key and value terms at current map iterator position. + On success set *key and *value and return true. + Return false if the iterator is positioned at head (before first entry) + or tail (beyond last entry).

 + + intenif_map_iterator_is_head(ErlNifEnv *env, ErlNifMapIterator *iter) + Check if map iterator is positioned before first +

Return true if map iterator iter is positioned + before first entry.

 + + intenif_map_iterator_is_tail(ErlNifEnv *env, ErlNifMapIterator *iter) + Check if map iterator is positioned after last +

Return true if map iterator iter is positioned + after last entry.

 + + intenif_map_iterator_next(ErlNifEnv *env, ErlNifMapIterator *iter) + Increment map iterator to point to next entry +

Increment map iterator to point to next key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the tail (beyond the last + entry).

 + + intenif_map_iterator_prev(ErlNifEnv *env, ErlNifMapIterator *iter) + Decrement map iterator to point to previous entry +

Decrement map iterator to point to previous key-value entry. + Return true if the iterator is now positioned at a valid key-value entry, + or false if the iterator is positioned at the head (before the first + entry).

 + ErlNifMutex *enif_mutex_create(char *name)

Same as erl_drv_mutex_create. -- cgit v1.2.3 From 7d60e4c592399c2e375a10338015e168a09d16a3 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 28 May 2015 12:30:15 +0200 Subject: erts: Fix alphabetic order in erl_nif doc enif_make_reverse_list was at the wrong place --- erts/doc/src/erl_nif.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 2cc06de0e0..6a4fe5f8b7 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1002,14 +1002,6 @@ typedef enum {

Create an ordinary list containing the elements of array arr of length cnt. An empty list is returned if cnt is 0.

 - intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) - Create the reverse of a list -

Set *list_out to the reverse list of the list list_in and return true, - or return false if list_in is not a list. This function should only be used on - short lists as a copy will be created of the list which will not be released until after the - nif returns.

-

The list_in term must belong to the environment env.

 - ERL_NIF_TERMenif_make_long(ErlNifEnv* env, long int i) Create an integer term from a long int

Create an integer term from a long int.

 @@ -1097,6 +1089,14 @@ typedef enum { enif_release_resource.

 + intenif_make_reverse_list(ErlNifEnv* env, ERL_NIF_TERM list_in, ERL_NIF_TERM *list_out) + Create the reverse of a list +

Set *list_out to the reverse list of the list list_in and return true, + or return false if list_in is not a list. This function should only be used on + short lists as a copy will be created of the list which will not be released until after the + nif returns.

+

The list_in term must belong to the environment env.

 + ERL_NIF_TERMenif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding) Create a string.

Create a list containing the characters of the -- cgit v1.2.3 From a519a52617a6a5bbdb8b17bdd892ab012cf8080b Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 28 May 2015 12:33:11 +0200 Subject: erts: Cleanup fsummary lines in erl_nif docs by removing all full stop. --- erts/doc/src/erl_nif.xml | 64 ++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 32 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 6a4fe5f8b7..e915c3b693 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -565,11 +565,11 @@ typedef enum { void *enif_alloc(size_t size) - Allocate dynamic memory. + Allocate dynamic memory

Allocate memory of size bytes. Return NULL if allocation failed.

 intenif_alloc_binary(size_t size, ErlNifBinary* bin) - Create a new binary. + Create a new binary

Allocate a new binary of size size bytes. Initialize the structure pointed to by bin to refer to the allocated binary. The binary must either be released by @@ -596,7 +596,7 @@ typedef enum {

Allocate a memory managed resource object of type type and size size bytes.

 voidenif_clear_env(ErlNifEnv* env) - Clear an environment for reuse. + Clear an environment for reuse

Free all terms in an environment and clear it for reuse. The environment must have been allocated with enif_alloc_env.

@@ -684,14 +684,14 @@ typedef enum { size-1.

 intenif_get_atom_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len, ErlNifCharEncoding encode) - Get the length of atom term. + Get the length of atom term

Set *len to the length (number of bytes excluding terminating null character) of the atom term with encoding encode. Return true on success or false if term is not an atom.

 intenif_get_double(ErlNifEnv* env, ERL_NIF_TERM term, double* dp) - Read a floating-point number term. + Read a floating-point number term

Set *dp to the floating point value of term. Return true on success or false if term is not a float.

 @@ -720,12 +720,12 @@ typedef enum { non-empty list.

 intenif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len) - Get the length of list term. + Get the length of list term

Set *len to the length of list term and return true, or return false if term is not a list.

 intenif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip) - Read an long integer term. + Read an long integer term

Set *ip to the long integer value of term and return true, or return false if term is not an integer or is outside the bounds of type long int.

 @@ -750,7 +750,7 @@ typedef enum { intenif_get_string(ErlNifEnv* env, ERL_NIF_TERM list, char* buf, unsigned size, ErlNifCharEncoding encode) - Get a C-string from a list. + Get a C-string from a list

Write a null-terminated string, in the buffer pointed to by buf with size size, consisting of the characters in the string list. The characters are written using encoding @@ -763,7 +763,7 @@ typedef enum { size is less than 1.

 intenif_get_tuple(ErlNifEnv* env, ERL_NIF_TERM term, int* arity, const ERL_NIF_TERM** array) - Inspect the elements of a tuple. + Inspect the elements of a tuple

If term is a tuple, set *array to point to an array containing the elements of the tuple and set *arity to the number of elements. Note that the array @@ -773,25 +773,25 @@ typedef enum { tuple.

 intenif_get_uint(ErlNifEnv* env, ERL_NIF_TERM term, unsigned int* ip) - Read an unsigned integer term. + Read an unsigned integer term

Set *ip to the unsigned integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned int.

 intenif_get_uint64(ErlNifEnv* env, ERL_NIF_TERM term, ErlNifUInt64* ip) - Read an unsigned 64-bit integer term. + Read an unsigned 64-bit integer term

Set *ip to the unsigned integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of an unsigned 64-bit integer.

 intenif_get_ulong(ErlNifEnv* env, ERL_NIF_TERM term, unsigned long* ip) - Read an unsigned integer term. + Read an unsigned integer term

Set *ip to the unsigned long integer value of term and return true, or return false if term is not an unsigned integer or is outside the bounds of type unsigned long.

 intenif_has_pending_exception(ErlNifEnv* env) - Check if an exception has been raised. + Check if an exception has been raised

Return true if a pending exception is associated with the environment env. The only possible exception is currently badarg (see enif_make_badarg).

 @@ -906,7 +906,7 @@ typedef enum {

ERL_NIF_TERMenif_make_badarg(ErlNifEnv* env) - Make a badarg exception. + Make a badarg exception

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 @@ -925,14 +925,14 @@ typedef enum { if enif_make_badarg has been invoked.

 ERL_NIF_TERMenif_make_binary(ErlNifEnv* env, ErlNifBinary* bin) - Make a binary term. + Make a binary term

Make a binary term from bin. Any ownership of the binary data will be transferred to the created term and bin should be considered read-only for the rest of the NIF call and then as released.

 ERL_NIF_TERMenif_make_copy(ErlNifEnv* dst_env, ERL_NIF_TERM src_term) - Make a copy of a term. + Make a copy of a term

Make a copy of term src_term. The copy will be created in environment dst_env. The source term may be located in any environment.

 @@ -973,7 +973,7 @@ typedef enum {

Create an integer term from a signed 64-bit integer.

 ERL_NIF_TERMenif_make_list(ErlNifEnv* env, unsigned cnt, ...) - Create a list term. + Create a list term

Create an ordinary list term of length cnt. Expects cnt number of arguments (after cnt) of type ERL_NIF_TERM as the elements of the list. An empty list is returned if cnt is 0.

 @@ -987,18 +987,18 @@ typedef enum { ERL_NIF_TERMenif_make_list7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7) ERL_NIF_TERMenif_make_list8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8) ERL_NIF_TERMenif_make_list9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9) - Create a list term. + Create a list term

Create an ordinary list term with length indicated by the function name. Prefer these functions (macros) over the variadic enif_make_list to get a compile time error if the number of arguments does not match.

 ERL_NIF_TERMenif_make_list_cell(ErlNifEnv* env, ERL_NIF_TERM head, ERL_NIF_TERM tail) - Create a list cell. + Create a list cell

Create a list cell [head | tail].

 ERL_NIF_TERMenif_make_list_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) - Create a list term from an array. + Create a list term from an array

Create an ordinary list containing the elements of array arr of length cnt. An empty list is returned if cnt is 0.

 @@ -1051,7 +1051,7 @@ typedef enum {

Make a pid term from *pid.

 ERL_NIF_TERMenif_make_ref(ErlNifEnv* env) - Create a reference. + Create a reference

Create a reference like erlang:make_ref/0.

 ERL_NIF_TERMenif_make_resource(ErlNifEnv* env, void* obj) @@ -1098,19 +1098,19 @@ typedef enum {

The list_in term must belong to the environment env.

 ERL_NIF_TERMenif_make_string(ErlNifEnv* env, const char* string, ErlNifCharEncoding encoding) - Create a string. + Create a string

Create a list containing the characters of the null-terminated string string with encoding encoding.

 ERL_NIF_TERMenif_make_string_len(ErlNifEnv* env, const char* string, size_t len, ErlNifCharEncoding encoding) - Create a string. + Create a string

Create a list containing the characters of the string string with length len and encoding encoding. Null-characters are treated as any other characters.

 ERL_NIF_TERMenif_make_sub_binary(ErlNifEnv* env, ERL_NIF_TERM bin_term, size_t pos, size_t size) - Make a subbinary term. + Make a subbinary term

Make a subbinary of binary bin_term, starting at zero-based position pos with a length of size bytes. bin_term must be a binary or bitstring and @@ -1118,7 +1118,7 @@ typedef enum { bytes in bin_term.

 ERL_NIF_TERMenif_make_tuple(ErlNifEnv* env, unsigned cnt, ...) - Create a tuple term. + Create a tuple term

Create a tuple term of arity cnt. Expects cnt number of arguments (after cnt) of type ERL_NIF_TERM as the elements of the tuple.

 @@ -1132,14 +1132,14 @@ typedef enum { ERL_NIF_TERMenif_make_tuple7(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e7) ERL_NIF_TERMenif_make_tuple8(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e8) ERL_NIF_TERMenif_make_tuple9(ErlNifEnv* env, ERL_NIF_TERM e1, ..., ERL_NIF_TERM e9) - Create a tuple term. + Create a tuple term

Create a tuple term with length indicated by the function name. Prefer these functions (macros) over the variadic enif_make_tuple to get a compile time error if the number of arguments does not match.

 ERL_NIF_TERMenif_make_tuple_from_array(ErlNifEnv* env, const ERL_NIF_TERM arr[], unsigned cnt) - Create a tuple term from an array. + Create a tuple term from an array

Create a tuple containing the elements of array arr of length cnt.

 @@ -1282,18 +1282,18 @@ enif_map_iterator_destroy(env, &iter);

Was previously named enif_get_data.

 intenif_realloc_binary(ErlNifBinary* bin, size_t size) - Change the size of a binary. + Change the size of a binary

Change the size of a binary bin. The source binary may be read-only, in which case it will be left untouched and a mutable copy is allocated and assigned to *bin. Return true on success, false if memory allocation failed.

 voidenif_release_binary(ErlNifBinary* bin) - Release a binary. + Release a binary

Release a binary obtained from enif_alloc_binary.

 voidenif_release_resource(void* obj) - Release a resource object. + Release a resource object

Remove a reference to resource object objobtained from enif_alloc_resource. The resource object will be destructed when the last reference is removed. @@ -1369,12 +1369,12 @@ enif_map_iterator_destroy(env, &iter); ErlNifPid *enif_self(ErlNifEnv* caller_env, ErlNifPid* pid) - Get the pid of the calling process. + Get the pid of the calling process

Initialize the pid variable *pid to represent the calling process. Return pid.

 intenif_send(ErlNifEnv* env, ErlNifPid* to_pid, ErlNifEnv* msg_env, ERL_NIF_TERM msg) - Send a message to a process. + Send a message to a process

Send a message to a process.

env -- cgit v1.2.3 From 03ae2f86e6a6a4b013fc89a814221fbfe1fe5cf3 Mon Sep 17 00:00:00 2001 From: Tomas Abrahamsson Date: Fri, 5 Jun 2015 18:38:40 +0200 Subject: Add forgotten argument to example in erl_nif doc In the documentation for erl_nif, in the map iterator example, the iterator argument was forgotten in the call to function enif_map_iterator_create. This is now fixed. --- erts/doc/src/erl_nif.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index f64381c99d..412c0e02ac 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -1177,7 +1177,7 @@ typedef enum { ERL_NIF_TERM key, value; ErlNifMapIterator iter; -enif_map_iterator_create(env, my_map, ERL_NIF_MAP_ITERATOR_FIRST); +enif_map_iterator_create(env, my_map, &iter, ERL_NIF_MAP_ITERATOR_FIRST); while (enif_map_iterator_get_pair(env, &iter, &key, &value)) { do_something(key,value); -- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- erts/doc/src/erl_nif.xml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'erts/doc/src/erl_nif.xml') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 412c0e02ac..23c3d5fcee 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -8,16 +8,17 @@ Ericsson AB. All Rights Reserved. - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. -- cgit v1.2.3