From nobody@FreeBSD.org  Wed Jun 22 02:51:13 2005
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 269CA16A41C
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 22 Jun 2005 02:51:13 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 1504143D1F
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 22 Jun 2005 02:51:13 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id j5M2p2sl022893
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 22 Jun 2005 02:51:02 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id j5M2p1UX022891;
	Wed, 22 Jun 2005 02:51:01 GMT
	(envelope-from nobody)
Message-Id: <200506220251.j5M2p1UX022891@www.freebsd.org>
Date: Wed, 22 Jun 2005 02:51:01 GMT
From: Vlad Skvortsov <vss@high.net.ru>
To: freebsd-gnats-submit@FreeBSD.org
Subject: misleading man page for basename/dirname
X-Send-Pr-Version: www-2.3

>Number:         82508
>Category:       docs
>Synopsis:       misleading man page for basename(3)/dirname(3)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ru
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jun 22 03:00:39 GMT 2005
>Closed-Date:    Thu Oct 12 14:31:55 GMT 2006
>Last-Modified:  Mon Oct 16 12:10:20 GMT 2006
>Originator:     Vlad Skvortsov
>Release:        5.2.1
>Organization:
Netli, Inc.
>Environment:
FreeBSD vlad.hq.netli.lan 5.2.1-RELEASE FreeBSD 5.2.1-RELEASE #0: Sat May 22 11:32:00 PDT 2004     root@vlad.hq.netli.lan:/usr/obj/usr/src/sys/VLAD  i386
>Description:
The man pages for both basename(3) and dirname(3) state that the functions
return pointers to the internal _static_ storage. However, those functions
actually perform malloc() call to allocate storage on the first invocation.
Thus, the memory pointer returned is actually a pointer to internal but
dynamically allocated storage.

I don't know whether this violates standard or not, but the documentation
is misleading.
>How-To-Repeat:
      Not applicable.
>Fix:
      Fix the docs.
>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Vlad Skvortsov <vss@high.net.ru>
Cc: bug-followup@freebsd.org
Subject: Re: docs/82508: misleading man page for basename/dirname
Date: Thu, 23 Jun 2005 15:55:52 +0300

 On 2005-06-22 02:51, Vlad Skvortsov <vss@high.net.ru> wrote:
 > The man pages for both basename(3) and dirname(3) state that the
 > functions return pointers to the internal _static_ storage. However,
 > those functions actually perform malloc() call to allocate storage on
 > the first invocation. Thus, the memory pointer returned is actually a
 > pointer to internal but dynamically allocated storage.
 >
 > I don't know whether this violates standard or not, but the
 > documentation is misleading.
 
 The term 'static' here is a warning that these functions are not thread-safe.
 
 It does NOT mean that the ``bname'' object that is internal to basename() is
 actually an array declared as:
 
 	char bname[MAXPATHLEN];
 
 It merely means that multiple invocations of the function from concurrent
 threads may clobber each other's data, so some form of locking should be used
 around calls to basename() from threaded applications or the function should
 be avoided altogether.
 

From: Vlad Skvortsov <vss@73rus.com>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: Vlad Skvortsov <vss@high.net.ru>, bug-followup@freebsd.org
Subject: Re: docs/82508: misleading man page for basename/dirname
Date: Thu, 30 Jun 2005 23:24:25 -0700

 Giorgos Keramidas wrote:
 > The term 'static' here is a warning that these functions are not thread-safe.
 > 
 > It does NOT mean that the ``bname'' object that is internal to basename() is
 > actually an array declared as:
 > 
 > 	char bname[MAXPATHLEN];
 > 
 > It merely means that multiple invocations of the function from concurrent
 > threads may clobber each other's data, so some form of locking should be used
 > around calls to basename() from threaded applications or the function should
 > be avoided altogether.
 > 
 
 Yes, I do understand what it supposed to mean. But, anyway, 'static' 
 means 'static', not (not only) 'thread-safe'. ;-)
 
 I've ran into this issue while running a testsuite checking for memory 
 leaks. I expected those values to be static, not thread-safe.
 
 
 -- 
 Vlad Skvortsov, vss@73rus.com, vss@high.net.ru

From: Giorgos Keramidas <keramida@freebsd.org>
To: Vlad Skvortsov <vss@73rus.com>
Cc: Vlad Skvortsov <vss@high.net.ru>, bug-followup@freebsd.org
Subject: Re: docs/82508: misleading man page for basename/dirname
Date: Fri, 1 Jul 2005 11:37:17 +0300

 On 2005-06-30 23:24, Vlad Skvortsov <vss@73rus.com> wrote:
 >Giorgos Keramidas wrote:
 > Yes, I do understand what it supposed to mean. But, anyway, 'static'
 > means 'static', not (not only) 'thread-safe'. ;-)
 
 The storage *IS* accessed through a static pointer:
 
   42: char *
   43: dirname(path)
   44:        const char *path;
   45: {
   46:        static char *bname = NULL;
   47:        const char *endp;
   48:
   49:        if (bname == NULL) {
   50:                bname = (char *)malloc(MAXPATHLEN);
   51:                if (bname == NULL)
   52:                        return(NULL);
   53:        }
 
 > I've ran into this issue while running a testsuite checking for memory leaks.
 > I expected those values to be static, not thread-safe.
 
 Oh, I see I think.  So, basically, you're saying that dirname() and
 basename() trigger false positives in the memory leak detection tools
 you used.
 
 I think the reason `bname' is not declared as:
 
 	static char bname[MAXPATHLEN];
 
 is to avoid actually allocating this array in the BSS area of programs
 that link with libc (practically every dynamic/shared executable on
 FreeBSD).
 
 This is exactly what the rationale for the change was, according to the
 CVS log of src/lib/libc/gen/dirname.c (rev. 1.6).
 
 AFAICT, there isn't an easy/clean way to have this automagically
 deallocated on program exit, which would let us keep both the malloc()
 call *and* make your memory leak detection tools happy :-/
 

From: Vlad Skvortsov <vss@73rus.com>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: Vlad Skvortsov <vss@high.net.ru>, bug-followup@freebsd.org
Subject: Re: docs/82508: misleading man page for basename/dirname
Date: Fri, 01 Jul 2005 22:45:48 -0700

 Hey, I understand everything about that - and I don't ask to rework the 
 implementation of the functions. What I want is just to make the 
 documentaion more accurate on that point. If the man page would state 
 that those functions allocate storage and are not thread-safe, I 
 wouldn't have to look into the source code for the explanation of their 
 behaviour. That's my point. :-)
 -- 
 Vlad Skvortsov, vss@73rus.com, vss@high.net.ru
State-Changed-From-To: open->closed 
State-Changed-By: ru 
State-Changed-When: Thu Oct 12 14:31:24 UTC 2006 
State-Changed-Why:  
Documentation has been fixed (in 7.0-CURRENT). 


Responsible-Changed-From-To: freebsd-doc->ru 
Responsible-Changed-By: ru 
Responsible-Changed-When: Thu Oct 12 14:31:24 UTC 2006 
Responsible-Changed-Why:  

http://www.freebsd.org/cgi/query-pr.cgi?pr=82508 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/82508: commit references a PR
Date: Thu, 12 Oct 2006 14:33:05 +0000 (UTC)

 ru          2006-10-12 14:31:17 UTC
 
   FreeBSD src repository
 
   Modified files:
     lib/libc/gen         basename.3 dirname.3 
   Log:
   More accurately document the implementation details of internal storage.
   
   PR:             docs/82508
   
   Revision  Changes    Path
   1.8       +8 -7      src/lib/libc/gen/basename.3
   1.9       +15 -14    src/lib/libc/gen/dirname.3
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/82508: commit references a PR
Date: Mon, 16 Oct 2006 12:00:59 +0000 (UTC)

 ru          2006-10-16 12:00:17 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_6)
     lib/libc/gen         basename.3 dirname.3 
   Log:
   MFC More accurately document the implementation details of internal storage.
   
   PR:             docs/82508
   Approved by:    re (hrs)
   
   Revision  Changes    Path
   1.7.8.1   +8 -7      src/lib/libc/gen/basename.3
   1.8.8.1   +15 -14    src/lib/libc/gen/dirname.3
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
