Explanation about char* parameters in the C API

1 files changed, 13 insertions, 1 deletions

diff --git a/manual/manual.of b/manual/manual.of
index 09075346..893592da 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -2692,7 +2692,19 @@ which behaves like a nil value.
 
 @sect3{constchar|@title{Pointers to Strings}
 
-Several functions in the API return pointers (@T{const char*})
+Several functions in the API accept pointers (@T{const char*})
+to C strings.
+Some of there parameters have an associated length (@T{size_t}).
+Unless stated otherwise,
+when there is an associated length,
+the string can contain embedded zeros;
+moreover, the pointer can be @id{NULL} if the length is zero.
+When there is no associated length,
+the pointer must point to a zero-terminated string.
+In any case, the string contents should remain unchanged
+until the function returns.
+
+Several functions in the API also return pointers (@T{const char*})
 to Lua strings in the stack.
 (See @Lid{lua_pushfstring}, @Lid{lua_pushlstring},
 @Lid{lua_pushstring}, and @Lid{lua_tolstring}.