diff options
author | Andy Polyakov <appro@openssl.org> | 2016-06-26 13:40:15 +0200 |
---|---|---|
committer | Andy Polyakov <appro@openssl.org> | 2016-07-08 11:49:44 +0200 |
commit | f1f5ee17b64397eecfde39960ca11e94064297bd (patch) | |
tree | 811a0a155a461065aecca798e7b7e090de7b80d9 /doc | |
parent | ab6a591caa561017f881ed36028177f9582a74c6 (diff) |
include/openssl: don't include <windows.h> in public headers.
If application uses any of Windows-specific interfaces, make it
application developer's respondibility to include <windows.h>.
Rationale is that <windows.h> is quite "toxic" and is sensitive
to inclusion order (most notably in relation to <winsock2.h>).
It's only natural to give complete control to the application developer.
Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/ASYNC_WAIT_CTX_new.pod | 9 | ||||
-rw-r--r-- | doc/crypto/ASYNC_start_job.pod | 12 | ||||
-rw-r--r-- | doc/crypto/CRYPTO_THREAD_run_once.pod | 13 | ||||
-rw-r--r-- | doc/ssl/SSL_get_all_async_fds.pod | 10 |
4 files changed, 44 insertions, 0 deletions
diff --git a/doc/crypto/ASYNC_WAIT_CTX_new.pod b/doc/crypto/ASYNC_WAIT_CTX_new.pod index 364cbb4e30..de1bd5777d 100644 --- a/doc/crypto/ASYNC_WAIT_CTX_new.pod +++ b/doc/crypto/ASYNC_WAIT_CTX_new.pod @@ -112,6 +112,15 @@ ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on success or 0 on error. +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + =head1 SEE ALSO L<crypto(3)>, L<ASYNC_start_job(3)> diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod index 20bc1ad2aa..eb12da8cb9 100644 --- a/doc/crypto/ASYNC_start_job.pod +++ b/doc/crypto/ASYNC_start_job.pod @@ -161,10 +161,22 @@ ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job. ASYNC_is_capable() returns 1 if the current platform is async capable or 0 otherwise. +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + =head1 EXAMPLE The following example demonstrates how to use most of the core async APIs: + #ifdef _WIN32 + # include <windows.h> + #endif #include <stdio.h> #include <unistd.h> #include <openssl/async.h> diff --git a/doc/crypto/CRYPTO_THREAD_run_once.pod b/doc/crypto/CRYPTO_THREAD_run_once.pod index 37671b90eb..7795a04477 100644 --- a/doc/crypto/CRYPTO_THREAD_run_once.pod +++ b/doc/crypto/CRYPTO_THREAD_run_once.pod @@ -79,10 +79,23 @@ CRYPTO_THREAD_lock_frees() returns no value. The other functions return 1 on success or 0 on error. +=head1 NOTES + +On Windows platforms the CRYPTO_THREAD_* types and functions in the +openssl/crypto.h header are dependent on some of the types customarily +made available by including windows.h. The application developer is +likely to require control over when the latter is included, commonly as +one of the first included headers. Therefore it is defined as an +application developer's responsibility to include windows.h prior to +crypto.h where use of CRYPTO_THREAD_* types and functions is required. + =head1 EXAMPLE This example safely initializes and uses a lock. + #ifdef _WIN32 + # include <windows.h> + #endif #include <openssl/crypto.h> static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; diff --git a/doc/ssl/SSL_get_all_async_fds.pod b/doc/ssl/SSL_get_all_async_fds.pod index deb81e1fdf..636f765508 100644 --- a/doc/ssl/SSL_get_all_async_fds.pod +++ b/doc/ssl/SSL_get_all_async_fds.pod @@ -7,6 +7,7 @@ asynchronous operations =head1 SYNOPSIS + #include <openssl/async.h> #include <openssl/ssl.h> int SSL_waiting_for_async(SSL *s); @@ -53,6 +54,15 @@ for an async operation to complete and 0 otherwise. SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or 0 on error. +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + =head1 SEE ALSO L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)> |