diff options
Diffstat (limited to 'secure/lib/libcrypto/man/OPENSSL_malloc.3')
| -rw-r--r-- | secure/lib/libcrypto/man/OPENSSL_malloc.3 | 124 |
1 files changed, 63 insertions, 61 deletions
diff --git a/secure/lib/libcrypto/man/OPENSSL_malloc.3 b/secure/lib/libcrypto/man/OPENSSL_malloc.3 index 9cbc74b039738..3d96bef8a902b 100644 --- a/secure/lib/libcrypto/man/OPENSSL_malloc.3 +++ b/secure/lib/libcrypto/man/OPENSSL_malloc.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -54,16 +54,20 @@ .\" Avoid warning from groff about undefined register 'F'. .de IX .. -.if !\nF .nr F 0 -.if \nF>0 \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} . \} .\} +.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "OPENSSL_MALLOC 3" -.TH OPENSSL_MALLOC 3 "2018-11-20" "1.1.1a" "OpenSSL" +.TH OPENSSL_MALLOC 3 "2019-02-26" "1.1.1b" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -206,56 +210,54 @@ generally macro's that add the standard C \fB_\|_FILE_\|_\fR and \fB_\|_LINE_\|_ parameters and call a lower-level \fBCRYPTO_xxx\fR \s-1API.\s0 Some functions do not add those parameters, but exist for consistency. .PP -\&\fIOPENSSL_malloc_init()\fR sets the lower-level memory allocation functions -to their default implementation. -It is generally not necessary to call this, except perhaps in certain -shared-library situations. +\&\fBOPENSSL_malloc_init()\fR does nothing and does not need to be called. It is +included for compatibility with older versions of OpenSSL. .PP -\&\fIOPENSSL_malloc()\fR, \fIOPENSSL_realloc()\fR, and \fIOPENSSL_free()\fR are like the -C \fImalloc()\fR, \fIrealloc()\fR, and \fIfree()\fR functions. -\&\fIOPENSSL_zalloc()\fR calls \fImemset()\fR to zero the memory before returning. +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_realloc()\fR, and \fBOPENSSL_free()\fR are like the +C \fBmalloc()\fR, \fBrealloc()\fR, and \fBfree()\fR functions. +\&\fBOPENSSL_zalloc()\fR calls \fBmemset()\fR to zero the memory before returning. .PP -\&\fIOPENSSL_clear_realloc()\fR and \fIOPENSSL_clear_free()\fR should be used +\&\fBOPENSSL_clear_realloc()\fR and \fBOPENSSL_clear_free()\fR should be used when the buffer at \fBaddr\fR holds sensitive information. -The old buffer is filled with zero's by calling \fIOPENSSL_cleanse()\fR -before ultimately calling \fIOPENSSL_free()\fR. +The old buffer is filled with zero's by calling \fBOPENSSL_cleanse()\fR +before ultimately calling \fBOPENSSL_free()\fR. .PP -\&\fIOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0's. -Use \fIOPENSSL_cleanse()\fR with care if the memory is a mapping of a file. +\&\fBOPENSSL_cleanse()\fR fills \fBptr\fR of size \fBlen\fR with a string of 0's. +Use \fBOPENSSL_cleanse()\fR with care if the memory is a mapping of a file. If the storage controller uses write compression, then its possible that sensitive tail bytes will survive zeroization because the block of zeros will be compressed. If the storage controller uses wear leveling, then the old sensitive data will not be overwritten; rather, a block of 0's will be written at a new physical location. .PP -\&\fIOPENSSL_strdup()\fR, \fIOPENSSL_strndup()\fR and \fIOPENSSL_memdup()\fR are like the +\&\fBOPENSSL_strdup()\fR, \fBOPENSSL_strndup()\fR and \fBOPENSSL_memdup()\fR are like the equivalent C functions, except that memory is allocated by calling the -\&\fIOPENSSL_malloc()\fR and should be released by calling \fIOPENSSL_free()\fR. +\&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR. .PP -\&\fIOPENSSL_strlcpy()\fR, -\&\fIOPENSSL_strlcat()\fR and \fIOPENSSL_strnlen()\fR are equivalents of the common C +\&\fBOPENSSL_strlcpy()\fR, +\&\fBOPENSSL_strlcat()\fR and \fBOPENSSL_strnlen()\fR are equivalents of the common C library functions and are provided for portability. .PP -\&\fIOPENSSL_hexstr2buf()\fR parses \fBstr\fR as a hex string and returns a +\&\fBOPENSSL_hexstr2buf()\fR parses \fBstr\fR as a hex string and returns a pointer to the parsed value. The memory is allocated by calling -\&\fIOPENSSL_malloc()\fR and should be released by calling \fIOPENSSL_free()\fR. +\&\fBOPENSSL_malloc()\fR and should be released by calling \fBOPENSSL_free()\fR. If \fBlen\fR is not \s-1NULL,\s0 it is filled in with the output length. Colons between two-character hex \*(L"bytes\*(R" are ignored. An odd number of hex digits is an error. .PP -\&\fIOPENSSL_buf2hexstr()\fR takes the specified buffer and length, and returns +\&\fBOPENSSL_buf2hexstr()\fR takes the specified buffer and length, and returns a hex string for value, or \s-1NULL\s0 on error. \&\fBBuffer\fR cannot be \s-1NULL\s0; if \fBlen\fR is 0 an empty string is returned. .PP -\&\fIOPENSSL_hexchar2int()\fR converts a character to the hexadecimal equivalent, +\&\fBOPENSSL_hexchar2int()\fR converts a character to the hexadecimal equivalent, or returns \-1 on error. .PP If no allocations have been done, it is possible to \*(L"swap out\*(R" the default -implementations for \fIOPENSSL_malloc()\fR, OPENSSL_realloc and \fIOPENSSL_free()\fR +implementations for \fBOPENSSL_malloc()\fR, OPENSSL_realloc and \fBOPENSSL_free()\fR and replace them with alternate versions (hooks). -\&\fICRYPTO_get_mem_functions()\fR function fills in the given arguments with the +\&\fBCRYPTO_get_mem_functions()\fR function fills in the given arguments with the function pointers for the current implementations. -With \fICRYPTO_set_mem_functions()\fR, you can specify a different set of functions. +With \fBCRYPTO_set_mem_functions()\fR, you can specify a different set of functions. If any of \fBm\fR, \fBr\fR, or \fBf\fR are \s-1NULL,\s0 then the function is not changed. .PP The default implementation can include some debugging capability (if enabled @@ -263,42 +265,42 @@ at build-time). This adds some overhead by keeping a list of all memory allocations, and removes items from the list when they are free'd. This is most useful for identifying memory leaks. -\&\fICRYPTO_set_mem_debug()\fR turns this tracking on and off. In order to have +\&\fBCRYPTO_set_mem_debug()\fR turns this tracking on and off. In order to have any effect, is must be called before any of the allocation functions -(e.g., \fICRYPTO_malloc()\fR) are called, and is therefore normally one of the -first lines of \fImain()\fR in an application. -\&\fICRYPTO_mem_ctrl()\fR provides fine-grained control of memory leak tracking. -To enable tracking call \fICRYPTO_mem_ctrl()\fR with a \fBmode\fR argument of +(e.g., \fBCRYPTO_malloc()\fR) are called, and is therefore normally one of the +first lines of \fBmain()\fR in an application. +\&\fBCRYPTO_mem_ctrl()\fR provides fine-grained control of memory leak tracking. +To enable tracking call \fBCRYPTO_mem_ctrl()\fR with a \fBmode\fR argument of the \fB\s-1CRYPTO_MEM_CHECK_ON\s0\fR. -To disable tracking call \fICRYPTO_mem_ctrl()\fR with a \fBmode\fR argument of +To disable tracking call \fBCRYPTO_mem_ctrl()\fR with a \fBmode\fR argument of the \fB\s-1CRYPTO_MEM_CHECK_OFF\s0\fR. .PP While checking memory, it can be useful to store additional context about what is being done. For example, identifying the field names when parsing a complicated data structure. -\&\fIOPENSSL_mem_debug_push()\fR (which calls \fICRYPTO_mem_debug_push()\fR) +\&\fBOPENSSL_mem_debug_push()\fR (which calls \fBCRYPTO_mem_debug_push()\fR) attachs an identifying string to the allocation stack. This must be a global or other static string; it is not copied. -\&\fIOPENSSL_mem_debug_pop()\fR removes identifying state from the stack. +\&\fBOPENSSL_mem_debug_pop()\fR removes identifying state from the stack. .PP -At the end of the program, calling \fICRYPTO_mem_leaks()\fR or -\&\fICRYPTO_mem_leaks_fp()\fR will report all \*(L"leaked\*(R" memory, writing it +At the end of the program, calling \fBCRYPTO_mem_leaks()\fR or +\&\fBCRYPTO_mem_leaks_fp()\fR will report all \*(L"leaked\*(R" memory, writing it to the specified \s-1BIO\s0 \fBb\fR or \s-1FILE\s0 \fBfp\fR. These functions return 1 if there are no leaks, 0 if there are leaks and \-1 if an error occurred. .PP -\&\fICRYPTO_mem_leaks_cb()\fR does the same as \fICRYPTO_mem_leaks()\fR, but instead +\&\fBCRYPTO_mem_leaks_cb()\fR does the same as \fBCRYPTO_mem_leaks()\fR, but instead of writing to a given \s-1BIO,\s0 the callback function is called for each output string with the string, length, and userdata \fBu\fR as the callback parameters. .PP If the library is built with the \f(CW\*(C`crypto\-mdebug\*(C'\fR option, then one -function, \fICRYPTO_get_alloc_counts()\fR, and two additional environment +function, \fBCRYPTO_get_alloc_counts()\fR, and two additional environment variables, \fB\s-1OPENSSL_MALLOC_FAILURES\s0\fR and \fB\s-1OPENSSL_MALLOC_FD\s0\fR, are available. .PP -The function \fICRYPTO_get_alloc_counts()\fR fills in the number of times -each of \fICRYPTO_malloc()\fR, \fICRYPTO_realloc()\fR, and \fICRYPTO_free()\fR have been +The function \fBCRYPTO_get_alloc_counts()\fR fills in the number of times +each of \fBCRYPTO_malloc()\fR, \fBCRYPTO_realloc()\fR, and \fBCRYPTO_free()\fR have been called, into the values pointed to by \fBmcount\fR, \fBrcount\fR, and \fBfcount\fR, respectively. If a pointer is \s-1NULL,\s0 then the corresponding count is not stored. .PP @@ -328,40 +330,40 @@ to use this (will not work on all platforms): .Ve .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fIOPENSSL_malloc_init()\fR, \fIOPENSSL_free()\fR, \fIOPENSSL_clear_free()\fR -\&\fICRYPTO_free()\fR, \fICRYPTO_clear_free()\fR and \fICRYPTO_get_mem_functions()\fR +\&\fBOPENSSL_malloc_init()\fR, \fBOPENSSL_free()\fR, \fBOPENSSL_clear_free()\fR +\&\fBCRYPTO_free()\fR, \fBCRYPTO_clear_free()\fR and \fBCRYPTO_get_mem_functions()\fR return no value. .PP -\&\fICRYPTO_mem_leaks()\fR, \fICRYPTO_mem_leaks_fp()\fR and \fICRYPTO_mem_leaks_cb()\fR return 1 if +\&\fBCRYPTO_mem_leaks()\fR, \fBCRYPTO_mem_leaks_fp()\fR and \fBCRYPTO_mem_leaks_cb()\fR return 1 if there are no leaks, 0 if there are leaks and \-1 if an error occurred. .PP -\&\fIOPENSSL_malloc()\fR, \fIOPENSSL_zalloc()\fR, \fIOPENSSL_realloc()\fR, -\&\fIOPENSSL_clear_realloc()\fR, -\&\fICRYPTO_malloc()\fR, \fICRYPTO_zalloc()\fR, \fICRYPTO_realloc()\fR, -\&\fICRYPTO_clear_realloc()\fR, -\&\fIOPENSSL_buf2hexstr()\fR, \fIOPENSSL_hexstr2buf()\fR, -\&\fIOPENSSL_strdup()\fR, and \fIOPENSSL_strndup()\fR +\&\fBOPENSSL_malloc()\fR, \fBOPENSSL_zalloc()\fR, \fBOPENSSL_realloc()\fR, +\&\fBOPENSSL_clear_realloc()\fR, +\&\fBCRYPTO_malloc()\fR, \fBCRYPTO_zalloc()\fR, \fBCRYPTO_realloc()\fR, +\&\fBCRYPTO_clear_realloc()\fR, +\&\fBOPENSSL_buf2hexstr()\fR, \fBOPENSSL_hexstr2buf()\fR, +\&\fBOPENSSL_strdup()\fR, and \fBOPENSSL_strndup()\fR return a pointer to allocated memory or \s-1NULL\s0 on error. .PP -\&\fICRYPTO_set_mem_functions()\fR and \fICRYPTO_set_mem_debug()\fR +\&\fBCRYPTO_set_mem_functions()\fR and \fBCRYPTO_set_mem_debug()\fR return 1 on success or 0 on failure (almost always because allocations have already happened). .PP -\&\fICRYPTO_mem_ctrl()\fR returns \-1 if an error occurred, otherwise the +\&\fBCRYPTO_mem_ctrl()\fR returns \-1 if an error occurred, otherwise the previous value of the mode. .PP -\&\fIOPENSSL_mem_debug_push()\fR and \fIOPENSSL_mem_debug_pop()\fR +\&\fBOPENSSL_mem_debug_push()\fR and \fBOPENSSL_mem_debug_pop()\fR return 1 on success or 0 on failure. .SH "NOTES" .IX Header "NOTES" While it's permitted to swap out only a few and not all the functions -with \fICRYPTO_set_mem_functions()\fR, it's recommended to swap them all out +with \fBCRYPTO_set_mem_functions()\fR, it's recommended to swap them all out at once. \fIThis applies specially if OpenSSL was built with the configuration option\fR \f(CW\*(C`crypto\-mdebug\*(C'\fR \fIenabled. In case, swapping out -only, say, the \fImalloc()\fI implementation is outright dangerous.\fR +only, say, the \f(BImalloc()\fI implementation is outright dangerous.\fR .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy |