From nobody@FreeBSD.org  Wed Oct 19 15:17:18 2011
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 68DA6106564A
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 19 Oct 2011 15:17:18 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 588148FC12
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 19 Oct 2011 15:17:18 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id p9JFHH9f050301
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 19 Oct 2011 15:17:17 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id p9JFHGuf050300;
	Wed, 19 Oct 2011 15:17:16 GMT
	(envelope-from nobody)
Message-Id: <201110191517.p9JFHGuf050300@red.freebsd.org>
Date: Wed, 19 Oct 2011 15:17:16 GMT
From: Jim Carroll <jim@carroll.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Missing documentation critical to correct usage of uuid_to_string(3)
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         161808
>Category:       docs
>Synopsis:       Missing documentation critical to correct usage of uuid_to_string(3)
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    ae
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Oct 19 15:20:12 UTC 2011
>Closed-Date:    Thu Mar 08 09:56:55 UTC 2012
>Last-Modified:  Thu Mar  8 10:00:44 UTC 2012
>Originator:     Jim Carroll
>Release:        7.4
>Organization:
Carroll-Net, Inc.
>Environment:
FreeBSD xxx.carroll.com 7.4-STABLE FreeBSD 7.4-STABLE #0: Fri Sep  9 12:00:03 EDT 2011     jim@xxx.carroll.com:/usr/obj/usr/src/sys/FSYNC  i386

>Description:
There is a key bit of information missing from the man page for uuid_to_string(3). Specifically that after calling this method, it is up to the caller to free the memory allocated.

Arguable, it probably should be obvious to most developers, but it was not 100% obvious to us whether or not the call was allocating memory or returning a reference to a static buffer.

A careful check of the libc source code showed us the error of our ways. But I thought it might be worthwhile to request a small addendum to the man page "caller needs to free buffer"

A quick example, might go a long way as well. May I offer the following:

char* str;
uint32_t status;

uuid_to_string(&u, &str, &status);
if (status == uuid_s_ok) {
    printf("%s\n", str);
    free(str);
}

>How-To-Repeat:

>Fix:
Small addendum to man page: 

"It is up to the caller to free the string returned by uuid_to_string()."


>Release-Note:
>Audit-Trail:

From: Niclas Zeising <niclas.zeising@gmail.com>
To: Jim Carroll <jim@carroll.com>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/161808: Missing documentation critical to correct usage
 of uuid_to_string(3)
Date: Wed, 19 Oct 2011 20:42:59 +0200

 This is a multi-part message in MIME format.
 --------------020509080204060605060408
 Content-Type: text/plain; charset=ISO-8859-1
 Content-Transfer-Encoding: 7bit
 
 Here is a patch that adds the mentioned notice.
 Regards!
 
 -- 
 Niclas Zeising
 
 --------------020509080204060605060408
 Content-Type: text/plain;
  name="uuid.3.diff"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="uuid.3.diff"
 
 Index: lib/libc/uuid/uuid.3
 ===================================================================
 --- lib/libc/uuid/uuid.3	(revision 226521)
 +++ lib/libc/uuid/uuid.3	(working copy)
 @@ -80,6 +80,9 @@
  or
  .Fn uuid_from_string
  respectively.
 +Please note that it is up to the caller of
 +.Fn uuid_to_string
 +to release the memory allocated to hold the returned string.
  A 16-bit hash value can be obtained by calling
  .Fn uuid_hash .
  .Pp
 
 --------------020509080204060605060408--
State-Changed-From-To: open->feedback 
State-Changed-By: bcr 
State-Changed-When: Wed Oct 19 18:57:37 UTC 2011 
State-Changed-Why:  
Set to feedback-state to see whether the patch submitted by Niclas 
is the intended change the submitter suggested. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=161808 
State-Changed-From-To: feedback->analyzed 
State-Changed-By: bcr 
State-Changed-When: Wed Oct 19 20:25:59 UTC 2011 
State-Changed-Why:  
Set to analyzed and assign to me. 


Responsible-Changed-From-To: freebsd-doc->bcr 
Responsible-Changed-By: bcr 
Responsible-Changed-When: Wed Oct 19 20:25:59 UTC 2011 
Responsible-Changed-Why:  
Set to analyzed and assign to me. 

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

From: "Jim Carroll" <jim@carroll.com>
To: "'Niclas Zeising'" <niclas.zeising@gmail.com>
Cc: <freebsd-gnats-submit@FreeBSD.org>
Subject: RE: docs/161808: Missing documentation critical to correct usage of uuid_to_string(3)
Date: Wed, 19 Oct 2011 15:25:01 -0400

 This is perfect.
 
 Thanks so much!
 
 > -----Original Message-----
 > From: Niclas Zeising [mailto:niclas.zeising@gmail.com]
 > Sent: Wednesday, October 19, 2011 2:43 PM
 > To: Jim Carroll
 > Cc: freebsd-gnats-submit@FreeBSD.org
 > Subject: Re: docs/161808: Missing documentation critical to correct
 > usage of uuid_to_string(3)
 >
 > Here is a patch that adds the mentioned notice.
 > Regards!
 >
 > --
 > Niclas Zeising
 
 
Responsible-Changed-From-To: bcr->freebsd-doc 
Responsible-Changed-By: bcr 
Responsible-Changed-When: Mon Nov 7 11:07:56 UTC 2011 
Responsible-Changed-Why:  
Back to the pool, due to insufficient time on my part. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=161808 
State-Changed-From-To: analyzed->patched 
State-Changed-By: ae 
State-Changed-When: Fri Mar 2 13:13:29 UTC 2012 
State-Changed-Why:  
Patched in head/ with r232339. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=161808 
Responsible-Changed-From-To: freebsd-doc->ae 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Sun Mar 4 04:32:43 UTC 2012 
Responsible-Changed-Why:  
you committed it 

http://www.freebsd.org/cgi/query-pr.cgi?pr=161808 
State-Changed-From-To: patched->closed 
State-Changed-By: ae 
State-Changed-When: Thu Mar 8 09:56:25 UTC 2012 
State-Changed-Why:  
Merged to stable/9,8,7. Thanks! 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/161808: commit references a PR
Date: Thu,  8 Mar 2012 09:55:30 +0000 (UTC)

 Author: ae
 Date: Thu Mar  8 09:55:18 2012
 New Revision: 232686
 URL: http://svn.freebsd.org/changeset/base/232686
 
 Log:
   MFC r232339:
     Note that memory should be freed after uuid_to_string(3) call.
   
   PR:		docs/161808
 
 Modified:
   stable/9/lib/libc/uuid/uuid.3
 Directory Properties:
   stable/9/lib/libc/uuid/   (props changed)
 
 Modified: stable/9/lib/libc/uuid/uuid.3
 ==============================================================================
 --- stable/9/lib/libc/uuid/uuid.3	Thu Mar  8 09:20:00 2012	(r232685)
 +++ stable/9/lib/libc/uuid/uuid.3	Thu Mar  8 09:55:18 2012	(r232686)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd August 13, 2008
 +.Dd March 1, 2012
  .Dt UUID 3
  .Os
  .Sh NAME
 @@ -84,6 +84,15 @@ A 16-bit hash value can be obtained by c
  .Fn uuid_hash .
  .Pp
  The
 +.Fn uuid_to_string
 +function set
 +.Fa *str
 +to be a pointer to a buffer sufficiently large to hold the string.
 +This pointer should be passed to
 +.Xr free 3
 +to release the allocated storage when it is no longer needed.
 +.Pp
 +The
  .Fn uuid_enc_le
  and
  .Fn uuid_enc_be
 @@ -116,7 +125,7 @@ The UUID does not have a known version.
  .It Dv uuid_s_invalid_string_uuid
  The string representation of an UUID is not valid.
  .It Dv uuid_s_no_memory
 -The meaning of the code escaped the writers mind.
 +The function can not allocate memory to store an UUID representation.
  .El
  .Sh SEE ALSO
  .Xr uuidgen 1 ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/161808: commit references a PR
Date: Thu,  8 Mar 2012 09:56:01 +0000 (UTC)

 Author: ae
 Date: Thu Mar  8 09:55:47 2012
 New Revision: 232687
 URL: http://svn.freebsd.org/changeset/base/232687
 
 Log:
   MFC r232339:
     Note that memory should be freed after uuid_to_string(3) call.
   
   PR:		docs/161808
 
 Modified:
   stable/8/lib/libc/uuid/uuid.3
 Directory Properties:
   stable/8/lib/libc/uuid/   (props changed)
 
 Modified: stable/8/lib/libc/uuid/uuid.3
 ==============================================================================
 --- stable/8/lib/libc/uuid/uuid.3	Thu Mar  8 09:55:18 2012	(r232686)
 +++ stable/8/lib/libc/uuid/uuid.3	Thu Mar  8 09:55:47 2012	(r232687)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd August 13, 2008
 +.Dd March 1, 2012
  .Dt UUID 3
  .Os
  .Sh NAME
 @@ -84,6 +84,15 @@ A 16-bit hash value can be obtained by c
  .Fn uuid_hash .
  .Pp
  The
 +.Fn uuid_to_string
 +function set
 +.Fa *str
 +to be a pointer to a buffer sufficiently large to hold the string.
 +This pointer should be passed to
 +.Xr free 3
 +to release the allocated storage when it is no longer needed.
 +.Pp
 +The
  .Fn uuid_enc_le
  and
  .Fn uuid_enc_be
 @@ -117,7 +126,7 @@ The UUID does not have a known version.
  .It Dv uuid_s_invalid_string_uuid
  The string representation of an UUID is not valid.
  .It Dv uuid_s_no_memory
 -The meaning of the code escaped the writers mind.
 +The function can not allocate memory to store an UUID representation.
  .El
  .Sh SEE ALSO
  .Xr uuidgen 1 ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/161808: commit references a PR
Date: Thu,  8 Mar 2012 09:56:26 +0000 (UTC)

 Author: ae
 Date: Thu Mar  8 09:56:07 2012
 New Revision: 232688
 URL: http://svn.freebsd.org/changeset/base/232688
 
 Log:
   MFC r232339:
     Note that memory should be freed after uuid_to_string(3) call.
   
   PR:		docs/161808
 
 Modified:
   stable/7/lib/libc/uuid/uuid.3
 Directory Properties:
   stable/7/lib/libc/uuid/   (props changed)
 
 Modified: stable/7/lib/libc/uuid/uuid.3
 ==============================================================================
 --- stable/7/lib/libc/uuid/uuid.3	Thu Mar  8 09:55:47 2012	(r232687)
 +++ stable/7/lib/libc/uuid/uuid.3	Thu Mar  8 09:56:07 2012	(r232688)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd August 13, 2008
 +.Dd March 1, 2012
  .Dt UUID 3
  .Os
  .Sh NAME
 @@ -84,6 +84,15 @@ A 16-bit hash value can be obtained by c
  .Fn uuid_hash .
  .Pp
  The
 +.Fn uuid_to_string
 +function set
 +.Fa *str
 +to be a pointer to a buffer sufficiently large to hold the string.
 +This pointer should be passed to
 +.Xr free 3
 +to release the allocated storage when it is no longer needed.
 +.Pp
 +The
  .Fn uuid_enc_le
  and
  .Fn uuid_enc_be
 @@ -117,7 +126,7 @@ The UUID does not have a known version.
  .It Dv uuid_s_invalid_string_uuid
  The string representation of an UUID is not valid.
  .It Dv uuid_s_no_memory
 -The meaning of the code escaped the writers mind.
 +The function can not allocate memory to store an UUID representation.
  .El
  .Sh SEE ALSO
  .Xr uuidgen 1 ,
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
