--- uuid.pod 2006/08/01 19:35:07 1.40
+++ uuid.pod 2006/10/06 08:32:40 1.41
@@ -328,21 +328,34 @@
minimum expected length in I<data_len> depends on it. Valid values for
I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR> and B<UUID_FMT_SIV>.
-=item uuid_rc_t B<uuid_export>(const uuid_t *I<uuid>, uuid_fmt_t I<fmt>, void **I<data_ptr>, size_t *I<data_len>);
+=item uuid_rc_t B<uuid_export>(const uuid_t *I<uuid>, uuid_fmt_t I<fmt>, void *I<data_ptr>, size_t *I<data_len>);
-Exports a UUID I<uuid> into an external representation of format I<fmt>.
-The data is written to the buffer at C<*>I<data_ptr> which has to
-be room for at least C<*>I<data_len> bytes. If C<*>I<data_ptr> is
-C<NULL>, I<data_len> is ignored as input and a new buffer is allocated
-and returned in C<*>I<data_ptr> (the caller has to free(3) it later
-on). If I<data_len> is not C<NULL>, the number of available bytes at
-C<*>I<data_ptr> has to be provided in C<*>I<data_len> and the number of
-actually written bytes are returned in C<*>I<data_len> again.
-
-The format of the external representation is specified by I<fmt> and the
-minimum required length in C<*>I<data_len> depends on it. Valid values
-for I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR>, B<UUID_FMT_SIV> and
-B<UUID_FMT_TXT>.
+Exports a UUID I<uuid> into an external representation of format
+I<fmt>. Valid values for I<fmt> are B<UUID_FMT_BIN>, B<UUID_FMT_STR>,
+B<UUID_FMT_SIV> and B<UUID_FMT_TXT>.
+
+The data is written to the buffer whose location is obtained
+by dereferencing I<data_ptr> after a "cast" to the appropriate
+pointer-to-pointer type. Hence the generic pointer argument I<data_ptr>
+is expected to be a pointer to a "pointer of a particular type", i.e.,
+it has to be of type "C<unsigned char **>" for B<UUID_FMT_BIN> and
+"C<char **>" for B<UUID_FMT_STR>, B<UUID_FMT_SIV> and B<UUID_FMT_TXT>.
+
+The buffer has to be room for at least C<*>I<data_len> bytes. If the
+value of the pointer after "casting" and dereferencing I<data_ptr>
+is C<NULL>, I<data_len> is ignored as input and a new buffer is
+allocated and returned in the pointer after "casting" and dereferencing
+I<data_ptr> (the caller has to free(3) it later on).
+
+If I<data_len> is not C<NULL>, the number of available bytes in the
+buffer has to be provided in C<*>I<data_len> and the number of actually
+written bytes are returned in C<*>I<data_len> again. The minimum
+required buffer length depends on the external representation as
+specified by I<fmt> and is at least B<UUID_LEN_BIN> for B<UUID_FMT_BIN>,
+B<UUID_LEN_STR> for B<UUID_FMT_STR> and B<UUID_LEN_SIV> for
+B<UUID_FMT_SIV>. For B<UUID_FMT_TXT> a buffer of unspecified length is
+required and hence it is recommended to allow B<OSSP uuid> to allocate
+the buffer as necessary.
=item uuid_rc_t B<uuid_load>(uuid_t *I<uuid>, const char *I<name>);
@@ -418,7 +431,7 @@
uuid_create(&uuid);
uuid_make(uuid, UUID_MAKE_V1);
str = NULL;
- uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL);
+ uuid_export(uuid, UUID_FMT_STR, &str, NULL);
uuid_destroy(uuid);
return str;
}
@@ -435,7 +448,7 @@
uuid_load(uuid_ns, "ns:URL");
uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url);
str = NULL;
- uuid_export(uuid, UUID_FMT_STR, (void **)&str, NULL);
+ uuid_export(uuid, UUID_FMT_STR, &str, NULL);
uuid_destroy(uuid_ns);
uuid_destroy(uuid);
return str;
|
