Add installation documentation and notes on ANSI C and POSIX

Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24173)

INSTALL.md

@@ -52,6 +52,8 @@ To install OpenSSL, you will need:
  * Perl 5 with core modules (please read [NOTES-PERL.md](NOTES-PERL.md))
  * The Perl module `Text::Template` (please read [NOTES-PERL.md](NOTES-PERL.md))
  * an ANSI C compiler
+ * POSIX C library (at least POSIX.1-2008), or compatible types and
+   functionality.
  * a development environment in the form of development libraries and C
    header files
  * a supported operating system
@@ -65,6 +67,7 @@ issues and other details, please read one of these:
  * [Notes for the DOS platform with DJGPP](NOTES-DJGPP.md)
  * [Notes for the OpenVMS platform](NOTES-VMS.md)
  * [Notes for the HPE NonStop platform](NOTES-NONSTOP.md)
+ * [Notes on POSIX](NOTES-POSIX.md)
  * [Notes on Perl](NOTES-PERL.md)
  * [Notes on Valgrind](NOTES-VALGRIND.md)
 

NOTES-ANSI.md

@@ -0,0 +1,33 @@
+Notes on ANSI C
+===============
+
+When building for pure ANSI C (C89/C90), you must configure with at least
+the following configuration settings:
+
+-   `no-asm`
+
+    There are cases of `asm()` calls in our C source, which isn't supported
+    in pure ANSI C.
+
+-   `no-secure-memory`
+
+    The secure memory calls aren't supported with ANSI C.
+
+-   `-D_XOPEN_SOURCE=1`
+
+    This macro enables the use of the following types, functions and global
+    variables:
+
+    -   `timezone`
+
+-   `-D_POSIX_C_SOURCE=200809L`
+
+    This macro enables the use of the following types, functions and global
+    variables:
+
+    -   `ssize_t`
+    -   `strdup()`
+
+It's arguable that with gcc and clang, all of these issues are removed when
+defining the macro `_DEFAULT_SOURCE`.  However, that effectively sets the C
+language level to C99, which isn't ANSI C.

NOTES-POSIX.md

@@ -0,0 +1,20 @@
+Notes on POSIX
+==============
+
+There are few instances where OpenSSL requires a POSIX C library, at least
+version 1-2008, or compatible enough functionality.
+
+There are exceptions, though, for platforms that do not have a POSIX
+library, or where there are quirks that need working around.  A notable
+platform is Windows, where POSIX functionality may be available, but where
+the function names are prefixed with an underscore, and where some POSIX
+types are not present (such as `ssize_t`).
+
+Platforms that do have a POSIX library may still not have them accessible
+unless the following macros are defined:
+
+    _POSIX_C_SOURCE=200809L
+    _XOPEN_SOURCE=1
+
+This is, for example, the case when building with gcc or clang and using the
+flag `-ansi`.