Re: [MTASCsft PATCH 31/??] MT-, AS- and AC-Safety docs: manual/string.texi

[Alexandre Oliva <aoliva at redhat dot com>]

On Feb  1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:

> On 01/27/2014 11:02 PM, Alexandre Oliva wrote:
>> There are some fixes regarding wcstok in this patch that have to do with
>> safety issues, but that are not safety remarks proper.  Should I split
>> them out?
 
> Please split out the wcstok and strtok_r fixes.

Here's a patch that fixes the prototype of wcstok to match the
implementation; fixes the incorrect notes that suggest it's not
reentrant, and drop the paragraph on non-wide characters after a
definition that speaks only about wide characters.

Ok to install?


Fix wcstok prototype, adjust reentrancy notes

From: Alexandre Oliva <aoliva@redhat.com>

for ChangeLog

	* manual/string.texi (wcstok): Fix prototype.
	(wcstok, strtok, strtok_r): Adjust reentrancy remarks.
---
 manual/string.texi |   33 ++++++++++++++-------------------
 1 file changed, 14 insertions(+), 19 deletions(-)

diff --git a/manual/string.texi b/manual/string.texi
index c98840e..6dcd4af 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -2062,7 +2062,7 @@ separately.  The function is not locale-dependent.
 
 @comment wchar.h
 @comment ISO
-@deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const wchar_t *@var{delimiters})
+@deftypefun {wchar_t *} wcstok (wchar_t *@var{newstring}, const wchar_t *@var{delimiters}, wchar_t **@var{save_ptr})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 A string can be split into tokens by making a series of calls to the
 function @code{wcstok}.
@@ -2071,11 +2071,8 @@ The string to be split up is passed as the @var{newstring} argument on
 the first call only.  The @code{wcstok} function uses this to set up
 some internal state information.  Subsequent calls to get additional
 tokens from the same wide character string are indicated by passing a
-null pointer as the @var{newstring} argument.  Calling @code{wcstok}
-with another non-null @var{newstring} argument reinitializes the state
-information.  It is guaranteed that no other library function ever calls
-@code{wcstok} behind your back (which would mess up this internal state
-information).
+null pointer as the @var{newstring} argument, which causes the pointer
+previously stored in @var{save_ptr} to be used instead.
 
 The @var{delimiters} argument is a wide character string that specifies
 a set of delimiters that may surround the token being extracted.  All
@@ -2084,8 +2081,10 @@ The first wide character that is @emph{not} a member of this set of
 delimiters marks the beginning of the next token.  The end of the token
 is found by looking for the next wide character that is a member of the
 delimiter set.  This wide character in the original wide character
-string @var{newstring} is overwritten by a null wide character, and the
-pointer to the beginning of the token in @var{newstring} is returned.
+string @var{newstring} is overwritten by a null wide character, the
+pointer past the overwritten wide character is saved in @var{save_ptr},
+and the pointer to the beginning of the token in @var{newstring} is
+returned.
 
 On the next call to @code{wcstok}, the searching begins at the next
 wide character beyond the one that marked the end of the previous token.
@@ -2095,11 +2094,6 @@ same on every call in a series of calls to @code{wcstok}.
 If the end of the wide character string @var{newstring} is reached, or
 if the remainder of string consists only of delimiter wide characters,
 @code{wcstok} returns a null pointer.
-
-Note that ``character'' is here used in the sense of byte.  In a string
-using a multibyte character encoding (abstract) character consisting of
-more than one byte are not treated as an entity.  Each byte is treated
-separately.  The function is not locale-dependent.
 @end deftypefun
 
 @strong{Warning:} Since @code{strtok} and @code{wcstok} alter the string
@@ -2124,7 +2118,7 @@ does not have as its purpose the modification of a certain data
 structure, then it is error-prone to modify the data structure
 temporarily.
 
-The functions @code{strtok} and @code{wcstok} are not reentrant.
+The function @code{strtok} is not reentrant, whereas @code{wcstok} is.
 @xref{Nonreentrancy}, for a discussion of where and why reentrancy is
 important.
 
@@ -2163,11 +2157,12 @@ available for multibyte character strings.
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Just like @code{strtok}, this function splits the string into several
 tokens which can be accessed by successive calls to @code{strtok_r}.
-The difference is that the information about the next token is stored in
-the space pointed to by the third argument, @var{save_ptr}, which is a
-pointer to a string pointer.  Calling @code{strtok_r} with a null
-pointer for @var{newstring} and leaving @var{save_ptr} between the calls
-unchanged does the job without hindering reentrancy.
+The difference is that, as in @code{wcstok}, the information about the
+next token is stored in the space pointed to by the third argument,
+@var{save_ptr}, which is a pointer to a string pointer.  Calling
+@code{strtok_r} with a null pointer for @var{newstring} and leaving
+@var{save_ptr} between the calls unchanged does the job without
+hindering reentrancy.
 
 This function is defined in POSIX.1 and can be found on many systems
 which support multi-threading.


-- 
Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/   FSF Latin America board member
Free Software Evangelist     Red Hat Brazil Toolchain Engineer