From 3a119bf1f7e264592868067f8e2d93ca26b14026 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Tue, 22 Dec 1998 19:08:27 +0000 Subject: [PATCH] Update man pages based upon required use of ldap_memfree() instead of free() replace 'malloced' with 'dynamically allocated' State ldap_memfree(3) should be used instead of free() Still need ldap_memfree(3) man page. --- doc/man/man3/lber-decode.3 | 30 +++++++++++++++++------------ doc/man/man3/ldap.3 | 5 +---- doc/man/man3/ldap_charset.3 | 2 +- doc/man/man3/ldap_error.3 | 5 +++-- doc/man/man3/ldap_first_attribute.3 | 2 +- doc/man/man3/ldap_get_dn.3 | 19 +++++++++--------- doc/man/man3/ldap_get_values.3 | 3 ++- doc/man/man3/ldap_getfilter.3 | 4 +++- doc/man/man3/ldap_result.3 | 4 ++-- doc/man/man3/ldap_search.3 | 4 +++- doc/man/man3/ldap_sort.3 | 4 +++- doc/man/man3/ldap_ufn.3 | 4 +++- 12 files changed, 49 insertions(+), 37 deletions(-) diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3 index 025aba5c14..85039a8ae0 100644 --- a/doc/man/man3/lber-decode.3 +++ b/doc/man/man3/lber-decode.3 @@ -206,8 +206,9 @@ set to the actual size of the octet string. .TP .SM O Octet string. A struct ber_val ** should be supplied, which upon return -points to a malloced struct berval containing the octet string and its -length. ber_bvfree() can be called to free the malloced memory. +points to a dynamically allocated struct berval containing the octet string +and its length. ber_bvfree() can be called to free the dynamically +allocated memory. .TP .SM b Boolean. A pointer to an integer should be supplied. @@ -216,7 +217,8 @@ Boolean. A pointer to an integer should be supplied. Integer. A pointer to an integer should be supplied. .TP .SM B -Bitstring. A char ** should be supplied which will point to the malloced +Bitstring. A char ** should be supplied which will point to the +dynamically allocated bits, followed by an unsigned long *, which will point to the length (in bits) of the bitstring returned. .TP @@ -226,16 +228,17 @@ it is recognized. .TP .SM v Sequence of octet strings. A char *** should be supplied, which upon -return points to a malloced null-terminated array of char *'s +return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. .TP .SM V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon -return points to a malloced null-terminated array of struct berval *'s +return points to a dynamically allocated null-terminated array of +struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. ber_bvecfree() can be called -to free the malloced memory. +to free the dynamically allocated memory. .TP .SM x Skip element. The next element is skipped. @@ -265,12 +268,13 @@ the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP -The ber_get_stringa() routine is used to malloc space into which an octet +The ber_get_stringa() routine is used to dynamically allocate space into +which an octet string is read. .LP -The ber_get_stringal() routine is used to malloc space into which an octet -string and its length are read. It takes a struct berval **, and returns -the result in this parameter. +The ber_get_stringal() routine is used to dynamically allocate space +into which an octet string and its length are read. It takes a +struct berval **, and returns the result in this parameter. .LP The ber_get_null() routine is used to read a NULL element. It returns the tag of the element it skips over. @@ -279,7 +283,7 @@ The ber_get_boolean() routine is used to read a boolean value. It is called the same way that ber_get_int() is called. .LP The ber_get_bitstringa() routine is used to read a bitstring value. It -takes a char ** which will hold the malloced bits, followed by an +takes a char ** which will hold the dynamically allocated bits, followed by an unsigned long *, which will point to the length (in bits) of the bitstring returned. .LP @@ -330,7 +334,9 @@ If an error occurs during decoding, generally these routines return -1. .SH NOTES .LP The return values for all of these functions are declared in the - header file. Some routines may malloc memory. + header file. +Some routines may dynamically allocate memory +which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3) .BR ldap-parse (3) diff --git a/doc/man/man3/ldap.3 b/doc/man/man3/ldap.3 index 130f78516c..ff170f0bb1 100644 --- a/doc/man/man3/ldap.3 +++ b/doc/man/man3/ldap.3 @@ -192,10 +192,7 @@ equivalent to .BR ldap_unbind (3) .TP .SM ldap_memfree (3) -dispose of memory allocated by LDAP routines (this is only used on the -Microsoft Windows platforms; use -.BR free (3) -on all other platforms). +dispose of memory allocated by LDAP routines. .TP .SM ldap_enable_cache(3) enable LDAP client caching diff --git a/doc/man/man3/ldap_charset.3 b/doc/man/man3/ldap_charset.3 index 7cad320fee..b607f74455 100644 --- a/doc/man/man3/ldap_charset.3 +++ b/doc/man/man3/ldap_charset.3 @@ -95,7 +95,7 @@ to be translated and \fI*lenp\fP should contain the number of bytes to translate. If \fIfree_input\fP is non-zero, the input buffer will be freed if translation is a success. If the translation is a success, LDAP_SUCCESS will be returned, \fI*bufp\fP will point to a newly -malloc'd buffer that contains the translated characters, and +dynamically allocated buffer that contains the translated characters, and \fI*lenp\fP will contain the length of the result. If translation fails, an LDAP error code will be returned. diff --git a/doc/man/man3/ldap_error.3 b/doc/man/man3/ldap_error.3 index 8d3b9b68d8..b098f07822 100644 --- a/doc/man/man3/ldap_error.3 +++ b/doc/man/man3/ldap_error.3 @@ -189,7 +189,7 @@ An unknown error occurred. The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR -Some local error occurred. This is usually a failed malloc. +Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. @@ -212,7 +212,8 @@ An ldap routine was called with a bad parameter (e.g., a NULL ld pointer, etc.). .TP .SM LDAP_NO_MEMORY -An memory allocation (e.g., malloc(3)) call failed in an ldap +An memory allocation (e.g., malloc(3) or other dynamic memory +allocator) call failed in an ldap library routine. .SH SEE ALSO .BR ldap(3), diff --git a/doc/man/man3/ldap_first_attribute.3 b/doc/man/man3/ldap_first_attribute.3 index 8646ed364d..376c3f8fbe 100644 --- a/doc/man/man3/ldap_first_attribute.3 +++ b/doc/man/man3/ldap_first_attribute.3 @@ -69,7 +69,7 @@ for a description of possible error codes. .SH NOTES The .B ldap_first_attribute() -routine mallocs memory that may need to +routine dyanamically allocated memory that may need to be freed by the caller via .BR ber_free (3). .SH SEE ALSO diff --git a/doc/man/man3/ldap_get_dn.3 b/doc/man/man3/ldap_get_dn.3 index d6769d9388..3abf840abf 100644 --- a/doc/man/man3/ldap_get_dn.3 +++ b/doc/man/man3/ldap_get_dn.3 @@ -53,10 +53,9 @@ routine takes an \fIentry\fP as returned by or .BR ldap_next_entry (3) and returns a copy of -the entry's DN. Space for the DN will have been obtained via -.BR malloc (3), -and should be freed by the caller by a call to -.BR free (3). +the entry's DN. Space for the DN will be obtained dynamically +and should be freed by the caller using +.BR ldap_memfree (3). .LP The .B ldap_explode_dn() @@ -89,10 +88,9 @@ is used to turn a DN as returned by into a more user-friendly form, stripping off type names. See RFC 1781 "Using the Directory to Achieve User Friendly Naming" for more details on the UFN format. The space for the UFN returned -is obtained by a call to -.BR malloc (3), -and the user is responsible for freeing it via a call to -.BR free (3). +is obtained dynamically and the user is responsible for freeing it +via a call to +.BR ldap_memfree (3). .LP .B ldap_is_dns_dn() returns non-zero if the dn string is an experimental @@ -124,11 +122,12 @@ will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES -These routines malloc memory that the caller must free. +These routines dyanamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap(3), -.BR ldap_first_entry(3), .BR ldap_error(3), +.BR ldap_first_entry(3), +.BR ldap_memfree(3), .BR ldap_value_free(3) .SH ACKNOWLEDGEMENTS .B OpenLDAP diff --git a/doc/man/man3/ldap_get_values.3 b/doc/man/man3/ldap_get_values.3 index 794b172aee..b3709f6259 100644 --- a/doc/man/man3/ldap_get_values.3 +++ b/doc/man/man3/ldap_get_values.3 @@ -91,7 +91,8 @@ indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES -These routines malloc memory that the caller must free. +These routines dynamically allocate memory which the caller must free +using the supplied routines. .SH SEE ALSO .BR ldap(3), .BR ldap_first_entry(3), diff --git a/doc/man/man3/ldap_getfilter.3 b/doc/man/man3/ldap_getfilter.3 index c2562731e8..4b7d3691f4 100644 --- a/doc/man/man3/ldap_getfilter.3 +++ b/doc/man/man3/ldap_getfilter.3 @@ -185,7 +185,9 @@ are no more appropriate filters to return. .SH NOTES .LP The return values for all of these functions are declared in the - header file. Some routines may malloc memory. + header file. +Some routines may dynamically allocate memory +which the caller must free using the supplied deallocator routines. .SH FILES ETCDIR/ldapfilter.conf .SH SEE ALSO diff --git a/doc/man/man3/ldap_result.3 b/doc/man/man3/ldap_result.3 index 860e473199..cf8cadb5bf 100644 --- a/doc/man/man3/ldap_result.3 +++ b/doc/man/man3/ldap_result.3 @@ -119,8 +119,8 @@ and .B ldap_msgid() return -1 on error. .SH NOTES -This routine mallocs memory for results that it receives. The memory -can be freed by calling +This routine dynamically allocates memory for results that it receives. +The memory can be freed by the caller using .BR ldap_msgfree . .SH SEE ALSO .BR ldap (3), diff --git a/doc/man/man3/ldap_search.3 b/doc/man/man3/ldap_search.3 index 8a149aa9b6..55bd5dba9a 100644 --- a/doc/man/man3/ldap_search.3 +++ b/doc/man/man3/ldap_search.3 @@ -107,7 +107,9 @@ and list functionality are subsumed by these routines, by using a filter like "objectclass=*" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP -These routines may malloc memory. Return values are contained +These routines may dynamically allocate memory. The caller is +responsible for freeing such memory using supplied deallocation +routines. Return values are contained in . .SH SEE ALSO .BR ldap (3), diff --git a/doc/man/man3/ldap_sort.3 b/doc/man/man3/ldap_sort.3 index 2f2c173f54..25bd5341a7 100644 --- a/doc/man/man3/ldap_sort.3 +++ b/doc/man/man3/ldap_sort.3 @@ -93,7 +93,9 @@ may produce unexpected results for multi-valued attributes. When sorting by DN, the comparison function is applied to an exploded version of the DN, without types. The return values for all of these functions are declared in the - header file. Some routines may malloc memory. + header file. Some routines may dynamically allocate memory. +Callers are responsible for freeing such memory using the supplied +deallocation routines. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), diff --git a/doc/man/man3/ldap_ufn.3 b/doc/man/man3/ldap_ufn.3 index f2db01d764..ae3f04bf81 100644 --- a/doc/man/man3/ldap_ufn.3 +++ b/doc/man/man3/ldap_ufn.3 @@ -119,7 +119,9 @@ should actually be a pointer to a struct timeval (this is so .B ldap_ufn_timeout() can be used as a cancelproc in the above routines). .SH NOTES -These routines may malloc memory. Return values are contained +These routines may dynamically allocate memory. The caller is +required to free such memory using the supplied deallocation routines. +Return values are contained in . .SH SEE ALSO .BR gettimeofday (2), -- 2.39.5