INSTALL: add IBM i specific quirks

Fixes #6830
Closes #7013

1 files changed, 33 insertions, 0 deletions

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 30afe81f7..8e121bca9 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -369,6 +369,39 @@ Note, however, that you must target at least Android M (API level 23) or `config
 won't be able to detect OpenSSL since `stderr` (and the like) weren't defined
 before Android M.
 
+# IBM i
+
+For IBM i (formerly OS/400), you can use curl in two different ways:
+
+* Natively, running in the **ILE**. The obvious use is being able to call curl
+  from ILE C or RPG applications.
+  * You will need to build this from source. See `packages/OS400/README` for
+    the ILE specific build instructions.
+* In the **PASE** environment, which runs AIX programs. curl will be built as
+  it would be on AIX.
+  * IBM provides builds of curl in their Yum repository for PASE software.
+  * To build from source, follow the Unix instructions.
+
+There are some additional limitations and quirks with curl on this platform;
+they affect both environments.
+
+## Multithreading notes
+
+By default, jobs in IBM i won't start with threading enabled. (Exceptions
+include interactive PASE sessions started by `QP2TERM` or SSH.) If you use
+curl in an environment without threading when options like async DNS were
+enabled, you'll messages like:
+
+```
+getaddrinfo() thread failed to start
+```
+
+Don't panic! curl and your program aren't broken. You can fix this by:
+
+* Set the environment variable `QIBM_MULTI_THREADED` to `Y` before starting
+  your program. This can be done at whatever scope you feel is appropriate.
+* Alternatively, start the job with the `ALWMLTTHD` parameter set to `*YES`.
+
 # Cross compile
 
 Download and unpack the curl package.