Bug 161808
| Summary: | Missing documentation critical to correct usage of uuid_to_string(3) | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Jim Carroll <jim> | ||||
| Component: | Books & Articles | Assignee: | Andrey V. Elsukov <ae> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
Here is a patch that adds the mentioned notice. Regards! -- Niclas Zeising State Changed From-To: open->feedback Set to feedback-state to see whether the patch submitted by Niclas is the intended change the submitter suggested. 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 State Changed From-To: feedback->analyzed Set to analyzed and assign to me. Responsible Changed From-To: freebsd-doc->bcr Set to analyzed and assign to me. Responsible Changed From-To: bcr->freebsd-doc Back to the pool, due to insufficient time on my part. State Changed From-To: analyzed->patched Patched in head/ with r232339. Responsible Changed From-To: freebsd-doc->ae you committed it 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" 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" State Changed From-To: patched->closed Merged to stable/9,8,7. Thanks! 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" |
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); } Fix: Small addendum to man page: "It is up to the caller to free the string returned by uuid_to_string()."