File 1153-Clarify-and-simplify-documentation-for-the-os-module.patch of Package erlang
From ad2b9771a7015a8b531f63a9947904a364a1e793 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Fri, 15 Jan 2021 09:45:46 +0100
Subject: [PATCH] Clarify and simplify documentation for the os module
I have done the following changes:
* Deleted the notes about null characters and `=` having been allowed
but are now being rejected. That change happened three years ago.
* Documented that an environment variable name is allowed to contain
`=` as the first character on Windows.
* Removed the vague warnings that "not all invalid characters
necessarily will cause the primitive operations to fail, but may
instead produce invalid results".
* Added a single note to note that the functions will fail with `badarg`
if the arguments contains invalid characters.
---
lib/kernel/doc/src/os.xml | 70 +++++++++------------------------------
1 file changed, 16 insertions(+), 54 deletions(-)
diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml
index 666aca988f..fc172b4306 100644
--- a/lib/kernel/doc/src/os.xml
+++ b/lib/kernel/doc/src/os.xml
@@ -37,27 +37,11 @@
use, these functions can be of help in enabling a program to run on
most platforms.</p>
- <note>
- <p>
- File operations used to accept filenames containing
- null characters (integer value zero). This caused
- the name to be truncated and in some cases arguments
- to primitive operations to be mixed up. Filenames
- containing null characters inside the filename
- are now <em>rejected</em> and will cause primitive
- file operations to fail.
- </p>
- <p>
- Also environment variable operations used to accept
- names and values of environment variables containing
- null characters (integer value zero). This caused
- operations to silently produce erroneous results.
- Environment variable names and values containing
- null characters inside the name or value are now
- <em>rejected</em> and will cause environment variable
- operations to fail.
- </p>
- </note>
+ <note>
+ <p>The functions in this module will raise a <c>badarg</c> exception
+ if their arguments contain invalid characters according to the
+ description in the "Data Types" section.</p>
+ </note>
</description>
<datatypes>
@@ -67,11 +51,9 @@
<p>A string containing valid characters on the specific
OS for environment variable names using
<seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding()</c></seealso>
- encoding. Note that specifically null characters (integer
- value zero) and <c>$=</c> characters are not allowed.
- However, note that not all invalid characters necessarily
- will cause the primitiv operations to fail, but may instead
- produce invalid results.
+ encoding. Null characters (integer value zero) are not allowed. On Unix,
+ <c>=</c> characters are not allowed. On Windows, a <c>=</c> character is only
+ allowed as the very first character in the string.
</p>
</desc>
</datatype>
@@ -81,10 +63,7 @@
<p>A string containing valid characters on the specific
OS for environment variable values using
<seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding()</c></seealso>
- encoding. Note that specifically null characters (integer
- value zero) are not allowed. However, note that not all
- invalid characters necessarily will cause the primitiv
- operations to fail, but may instead produce invalid results.
+ encoding. Null characters (integer value zero) are not allowed.
</p>
</desc>
</datatype>
@@ -96,7 +75,7 @@
set, a strings containing valid characters on the specific
OS for environment variable names and values using
<seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding()</c></seealso>
- encoding. The first <c>$=</c> characters appearing in
+ encoding. The first <c>=</c> characters appearing in
the string separates environment variable name (on the
left) from environment variable value (on the right).
</p>
@@ -105,14 +84,11 @@
<datatype>
<name name="os_command"/>
<desc>
- <p>All characters needs to be valid characters on the
- specific OS using
- <seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding()</c></seealso>
- encoding. Note that specifically null characters (integer
- value zero) are not allowed. However, note that not all
- invalid characters not necessarily will cause
- <seealso marker="#cmd/1"><c>os:cmd/1</c></seealso>
- to fail, but may instead produce invalid results.
+ <p>All characters needs to be valid characters on the specific
+ OS using <seealso
+ marker="file#native_name_encoding/0"><c>file:native_name_encoding()</c></seealso>
+ encoding. Null characters (integer value zero) are not
+ allowed.
</p>
</desc>
</datatype>
@@ -123,7 +99,7 @@
<taglist>
<tag><c>max_size</c></tag>
<item>
- <p>The maximum size of the data returned by the <c>os:cmd</c> call.
+ <p>The maximum size of the data returned by the <c>os:cmd/2</c> call.
See the <seealso marker="#cmd/2"><c>os:cmd/2</c></seealso>
documentation for more details.</p>
</item>
@@ -141,11 +117,6 @@
<p>Executes <c><anno>Command</anno></c> in a command shell of the
target OS, captures the standard output of the command,
and returns this result as a string.</p>
- <warning><p>Previous implementation used to allow all characters
- as long as they were integer values greater than or equal to zero.
- This sometimes lead to unwanted results since null characters
- (integer value zero) often are interpreted as string termination. The
- current implementation rejects these.</p></warning>
<p><em>Examples:</em></p>
<code type="none">
LsOut = os:cmd("ls"), % on unix platform
@@ -264,15 +235,6 @@ DirOut = os:cmd("dir"), % on Win32 platform</code>
<p>On Unix platforms, the environment is set using UTF-8 encoding
if Unicode filename translation is in effect. On Windows, the
environment is set using wide character interfaces.</p>
- <note>
- <p>
- <c><anno>VarName</anno></c> is not allowed to contain
- an <c>$=</c> character. Previous implementations used
- to just let the <c>$=</c> character through which
- silently caused erroneous results. Current implementation
- will instead throw a <c>badarg</c> exception.
- </p>
- </note>
</desc>
</func>
--
2.26.2
