add OPENSSL_FUNC.pod documenting OPENSSL_MSTR, OPENSSL_FUNC, and friends

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/10236)

diff --git a/doc/man3/OPENSSL_FILE.pod b/doc/man3/OPENSSL_FILE.pod
new file mode 100644 (file)
index 0000000..9f18081
--- /dev/null
+++ b/doc/man3/OPENSSL_FILE.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_FILE, OPENSSL_LINE, OPENSSL_FUNC,
+OPENSSL_MSTR, OPENSSL_MSTR_HELPER
+- generic C programming utility macros
+
+=head1 SYNOPSIS
+
+ #include <openssl/macros.h>
+
+ #define OPENSSL_FILE /* typically: __FILE__ */
+ #define OPENSSL_LINE /* typically: __LINE__ */
+ #define OPENSSL_FUNC /* typically: __func__ */
+
+ #define OPENSSL_MSTR_HELPER(x) #x
+ #define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)
+
+=head1 DESCRIPTION
+
+The macros B<OPENSSL_FILE> and B<OPENSSL_LINE>
+typically yield the current filename and line number during C compilation.
+When B<OPENSSL_NO_FILENAMES> is defined they yield B<""> and B<0>, respectively.
+
+The macro B<OPENSSL_FUNC> attempts to yield the name of the C function
+currently being compiled, as far as language and compiler versions allow.
+Otherwise, it yields "(unknown function)".
+
+The macro B<OPENSSL_MSTR> yields the expansion of the macro given as argument,
+which is useful for concatentation with string constants.
+The macro B<OPENSSL_MSTR_HELPER> is an auxiliary macro for this purpose.
+
+=head1 RETURN VALUES
+
+see above
+
+=head1 SEE ALSO
+
+L<crypto(7)>
+
+=head1 HISTORY
+
+B<OPENSSL_FUNC>, B<OPENSSL_MSTR>, and B<OPENSSL_MSTR_HELPER>
+were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut

diff --git a/util/other.syms b/util/other.syms
index 8cb980ef8c2511cda063b9749e7463e54b2bc737..c5575ac151e6ca7a93c712b30961ac8df9e24e62 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -300,6 +300,11 @@ EVP_rc5_32_12_16_cfb                    define
 EVP_seed_cfb                            define
 EVP_sm4_cfb                             define
 OBJ_cleanup                             define deprecated 1.1.0
+OPENSSL_FILE                            define
+OPENSSL_FUNC                            define
+OPENSSL_LINE                            define
+OPENSSL_MSTR                            define
+OPENSSL_MSTR_HELPER                     define
 OPENSSL_VERSION_MAJOR                   define
 OPENSSL_VERSION_MINOR                   define
 OPENSSL_VERSION_NUMBER                  define deprecated 3.0.0