From owner-freebsd-doc@FreeBSD.ORG Wed Oct 19 15:20:13 2011 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 6DDE4106566B for ; Wed, 19 Oct 2011 15:20:13 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 31E1E8FC1B for ; Wed, 19 Oct 2011 15:20:13 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id p9JFKDfO014385 for ; Wed, 19 Oct 2011 15:20:13 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id p9JFKDiQ014384; Wed, 19 Oct 2011 15:20:13 GMT (envelope-from gnats) Resent-Date: Wed, 19 Oct 2011 15:20:13 GMT Resent-Message-Id: <201110191520.p9JFKDiQ014384@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Jim Carroll Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 68DA6106564A for ; 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 ; 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 ; 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 To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Cc: Subject: docs/161808: Missing documentation critical to correct usage of uuid_to_string(3) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 19 Oct 2011 15:20:13 -0000 >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: