Date: Wed, 19 Oct 2011 15:17:16 GMT From: Jim Carroll <jim@carroll.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/161808: Missing documentation critical to correct usage of uuid_to_string(3) Message-ID: <201110191517.p9JFHGuf050300@red.freebsd.org> Resent-Message-ID: <201110191520.p9JFKDiQ014384@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201110191517.p9JFHGuf050300>