[Bug manual/6907] New: [PATCH] strchr documentation concerning strchrnul

["fabrice dot bauzac at wanadoo dot fr" <sourceware-bugzilla at sourceware dot org>]

Hello,

This is a problem that I have reported on libc-help on 14sep08.

I think that the documentation for strchr is misleading in the
last paragraph:

 -- Function: char * strchr (const char *STRING, int C)
     The `strchr' function finds the first occurrence of the character
     C (converted to a `char') in the null-terminated string beginning
     at STRING.  The return value is a pointer to the located
     character, or a null pointer if no match was found.

     For example,
          strchr ("hello, world", 'l')
              => "llo, world"
          strchr ("hello, world", '?')
              => NULL

     The terminating null character is considered to be part of the
     string, so you can use this function get a pointer to the end of a
     string by specifying a null character as the value of the C
     argument.  It would be better (but less portable) to use
     `strchrnul' in this case, though.

As a reminder, here is the documentation for strchrnul:

 -- Function: char * strchrnul (const char *STRING, int C)
     `strchrnul' is the same as `strchr' except that if it does not
     find the character, it returns a pointer to string's terminating
     null character rather than a null pointer.

     This function is a GNU extension.

To me, the last sentence of strchr:

     It would be better (but less portable) to use
     `strchrnul' in this case, though.

suggests that whenever strchr is used with C = 0, strchrnul is a preferable alternative. It is not 
preferable in that case; in fact, it is the only case where it cannot be preferable!

When searching for the end of string (i.e. the nul character), either strchrnul or strlen can be used; the 
latter is preferable because it is more portable while being as performant.

It is when the programmer searches for a nonzero character that strchrnul is useful, because it can 
provide more information. In case strchr returns NULL, and the program then wants to know the string 
length, a second full string scan (with e.g. strlen) is necessary; this second scan is not needed if the 
program uses strchrnul in the first place.

I have made the below patch for string.texi.  Could you please have a
look at it?

diff -c /home/noon/prog/glibc-cvs/libc/manual/string.texi.orig /home/noon/prog/glibc-
cvs/libc/manual/string.texi
*** /home/noon/prog/glibc-cvs/libc/manual/string.texi.orig	Sat Sep  6 12:47:36 2008
--- /home/noon/prog/glibc-cvs/libc/manual/string.texi	Sat Sep  6 13:01:57 2008
***************
*** 1647,1655 ****

  The terminating null character is considered to be part of the string,
  so you can use this function get a pointer to the end of a string by
! specifying a null character as the value of the @var{c} argument.  It
! would be better (but less portable) to use @code{strchrnul} in this
! case, though.
  @end deftypefun

  @comment wchar.h
--- 1647,1658 ----

  The terminating null character is considered to be part of the string,
  so you can use this function get a pointer to the end of a string by
! specifying a null character as the value of the @var{c} argument.
! 
! When @code{strchr} returns a null pointer, it does not let you know
! the position of the terminating null character it has found.  If you
! need that information, it is better (but less portable) to use
! @code{strchrnul} than to search for it a second time.
  @end deftypefun

  @comment wchar.h

Thanks.

-- 
           Summary: [PATCH] strchr documentation concerning strchrnul
           Product: glibc
           Version: unspecified
            Status: NEW
          Severity: minor
          Priority: P3
         Component: manual
        AssignedTo: roland at gnu dot org
        ReportedBy: fabrice dot bauzac at wanadoo dot fr
                CC: glibc-bugs at sources dot redhat dot com
 GCC build triplet: any
  GCC host triplet: any
GCC target triplet: any


http://sourceware.org/bugzilla/show_bug.cgi?id=6907

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.