docs/161808: Missing documentation critical to correct usage of uuid_to_string(3)

[Jim Carroll]

>Number:         161808
>Category:       docs
>Synopsis:       Missing documentation critical to correct usage of uuid_to_string(3)
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Oct 19 15:20:12 UTC 2011
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted: