File 0709-references-erl_nif-clear-up-NULL-NUL-confusion.patch of Package erlang
From 8ea2346b05493a988db98d9126e1b4fff18a039e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=BD=D0=B0=D0=B1?= <nabijaczleweli@nabijaczleweli.xyz>
Date: Wed, 10 Dec 2025 18:53:28 +0100
Subject: [PATCH] references/erl_nif: clear up `NULL`/NUL confusion
NULL is a C macro (thus, ``) that evaluates to a null pointer literal.
NUL is what ASCII calls the 0 byte.
C strings consist of bytes (not characters),
especially when you have non-single-byte encodings.
---
erts/doc/references/erl_nif.md | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 6f3e81aae3..90d689b5af 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -1469,12 +1469,12 @@ enif_free_iovec(iovec);]]></code>
</name>
<fsummary>Get the text representation of an atom term.</fsummary>
<desc>
- <p>Writes a <c>NULL</c>-terminated string in the buffer pointed to by
+ <p>Writes a NUL-terminated string in the buffer pointed to by
<c>buf</c> of size <c>size</c> bytes, consisting of the string
representation of the atom <c>term</c> with
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
<p>Returns the number of bytes written (including terminating
- <c>NULL</c> character) or <c>0</c> if <c>term</c> is not an atom with
+ NUL byte) or <c>0</c> if <c>term</c> is not an atom with
maximum length of <c>size-1</c> bytes in <c>encoding</c>.</p>
</desc>
</func>
@@ -1486,7 +1486,7 @@ enif_free_iovec(iovec);]]></code>
<fsummary>Get the length of atom <c>term</c>.</fsummary>
<desc>
<p>Sets <c>*len</c> to the length (number of bytes excluding
- terminating <c>NULL</c> character) of the atom <c>term</c> with
+ terminating NUL byte) of the atom <c>term</c> with
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
<p>Returns <c>true</c> on success, or <c>false</c> if <c>term</c> is not
an atom or if the atom cannot be encoded using <c>encoding</c>.</p>
@@ -1634,21 +1634,21 @@ enif_free_iovec(iovec);]]></code>
ErlNifCharEncoding encoding)</nametext></name>
<fsummary>Get a C-string from a list.</fsummary>
<desc>
- <p>Writes a <c>NULL</c>-terminated string in the buffer pointed to by
+ <p>Writes a NUL-terminated string in the buffer pointed to by
<c>buf</c> with size <c>size</c>, consisting of the characters
in the string <c>list</c>. The characters are written using
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
<p>Returns one of the following:</p>
<list type="bulleted">
- <item>The number of bytes written (including terminating <c>NULL</c>
- character)</item>
+ <item>The number of bytes written (including terminating NUL
+ byte)</item>
<item><c>-size</c> if the string was truncated because of buffer
space</item>
<item><c>0</c> if <c>list</c> is not a string that can be encoded
with <c>encoding</c> or if <c>size</c> was < <c>1</c>.</item>
</list>
- <p>The written string is always <c>NULL</c>-terminated, unless buffer
- <c>size</c> is < <c>1</c>.</p>
+ <p>The written string is always NUL-terminated, unless buffer
+ <c>size</c> is <c>0</c>.</p>
</desc>
</func>
@@ -1660,7 +1660,7 @@ enif_free_iovec(iovec);]]></code>
<fsummary>Get the length of a C-string <c>list</c>.</fsummary>
<desc>
<p>Sets <c>*len</c> to the length (number of bytes excluding
- terminating <c>NULL</c> character) of the string <c>list</c> with
+ terminating NUL byte) of the string <c>list</c> with
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
<p>Returns <c>true</c> on success, or <c>false</c> if <c>list</c> is not
a string that can be encoded with <c>encoding</c>.</p>
@@ -2118,7 +2118,7 @@ enif_inspect_iovec(env, max_elements, te
</name>
<fsummary>Create an atom term.</fsummary>
<desc>
- <p>Creates an atom term from the <c>NULL</c>-terminated C-string
+ <p>Creates an atom term from the NUL-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 (255 characters),
<c>enif_make_atom</c> invokes <seecref marker="#enif_make_badarg">
@@ -2132,7 +2132,7 @@ enif_inspect_iovec(env, max_elements, te
<fsummary>Create an atom term.</fsummary>
<desc>
<p>Create an atom term from the string <c>name</c> with length
- <c>len</c> and ISO Latin-1 encoding. <c>NULL</c> characters are
+ <c>len</c> and ISO Latin-1 encoding. <c>NUL</c> bytes are
treated as any other characters. If <c>len</c> exceeds the maximum
length allowed for an atom (255 characters), <c>enif_make_atom</c>
invokes <seecref marker="#enif_make_badarg"><c>enif_make_badarg</c>
@@ -2211,7 +2211,7 @@ enif_inspect_iovec(env, max_elements, te
<fsummary>Create an existing atom term.</fsummary>
<desc>
<p>Tries to create the term of an already existing atom from
- the <c>NULL</c>-terminated C-string <c>name</c> with
+ the NUL-terminated C-string <c>name</c> with
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
<p>If the atom already exists, this function stores the term in
<c>*atom</c> and returns <c>true</c>, otherwise returns <c>false</c>.
@@ -2229,8 +2229,8 @@ enif_inspect_iovec(env, max_elements, te
<desc>
<p>Tries to create the term of an already existing atom from the
string <c>name</c> with length <c>len</c> bytes and
- <seecref marker="#ErlNifCharEncoding">encoding</seecref>. <c>NULL</c>
- characters are treated as any other characters.</p>
+ <seecref marker="#ErlNifCharEncoding">encoding</seecref>. <c>NUL</c>
+ bytes are treated as any other characters.</p>
<p>If the atom already exists, this function stores the term in
<c>*atom</c> and returns <c>true</c>, otherwise returns <c>false</c>.
It also returns <c>false</c> if the string <c>name</c> exceeds the
@@ -2578,7 +2578,7 @@ enif_inspect_iovec(env, max_elements, te
<fsummary>Create a string.</fsummary>
<desc>
<p>Creates a list containing the characters of the
- <c>NULL</c>-terminated string <c>string</c> with
+ NUL-terminated string <c>string</c> with
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.</p>
</desc>
</func>
@@ -2592,7 +2592,7 @@ enif_inspect_iovec(env, max_elements, te
<p>Creates a list containing the characters of the string <c>string</c>
with length <c>len</c> and
<seecref marker="#ErlNifCharEncoding">encoding</seecref>.
- <c>NULL</c> characters are treated as any other characters.</p>
+ NUL bytes are treated as any other characters.</p>
</desc>
</func>
--
2.51.0
