[WIP] Add information for macOS into the user docs

Modify command line topics to indicate which ones
do/don't apply to OS X, plus any specific information
for this platform.

Updates also for the directory conventions topic,
environment variables topic, and messages.

Closes: eclipse-openj9#82

Signed-off-by: Sue Chaplain <[email protected]>

docs/dcomibmtoolsattachenable.md

@@ -30,7 +30,7 @@ Enable the Attach API for this application.
 
         -Dcom.ibm.tools.attach.enable=[yes|no]
 
-On AIX®, Linux®, and Windows™ systems, the following default applies:
+On AIX®, Linux®, OS X®, and Windows™ systems, the following default applies:
 
 | Value        | Effect  | Default                                                                            |
 |--------------|---------|:----------------------------------------------------------------------------------:|

docs/env_var.md

@@ -33,27 +33,27 @@ Although the OpenJ9 virtual machine (VM) recognizes many environment variables,
 To show the current environment, run:
 
 -   `set` (Windows™)
--   `env` (AIX®, Linux®, and macOS®)
+-   `env` (AIX®, Linux®, and OS X®)
 -   `set` (z/OS®)
 
 To show a particular environment variable, run:
 
 -   `echo %ENVNAME%` (Windows)
--   `echo $ENVNAME` (AIX, Linux, macOS, and z/OS)
+-   `echo $ENVNAME` (AIX, Linux, OS X, and z/OS)
 
-Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, macOS, and z/OS.
+Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, OS X, and z/OS.
 
 To set the environment variable **LOGIN\_NAME** to *Fred*, run:
 
 -   `set LOGIN_NAME=Fred` (Windows)
--   `export LOGIN_NAME=Fred` (AIX/Linux: ksh or bash shells)
--   `setenv LOGIN_NAME Fred` (macOS or csh shells)
+-   `export LOGIN_NAME=Fred` (AIX/Linux/OS X: ksh or bash shells)
+-   `setenv LOGIN_NAME Fred` (csh shells)
 
 These variables are set only for the current shell or command-line session.
 
 If you are setting multiple values for an environment variable in a list:
 
--   On AIX, Linux, macOS, and z/OS the separator is typically a colon (:).
+-   On AIX, Linux, OS X, and z/OS the separator is typically a colon (:).
 -   On Windows the separator is typically a semicolon (;).
 
 ## General options
@@ -134,7 +134,7 @@ Setting `JAVA_DUMP_OPTS` affects only those conditions that you specify. Actions
 
 When setting the `JAVA_DUMP_OPTS` environment variable, the mapping of operating system signals to the "condition" is shown in the following table:
 
-| Condition        | z/OS                                                      |  Windows                | Linux and AIX                                     |
+| Condition        | z/OS                                                      |  Windows                | Linux, OS X, and AIX                                     |
 |------------------|-----------------------------------------------------------|-------------------------|---------------------------------------------------|
 | **EXCEPTION**    | SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGSYS, SIGXFSV | SIGILL, SIGSEGV, SIGFPE | SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGXFSV |
 | **INTERRUPT**    | SIGINT, SIGTERM, SIGHUP                                   | SIGINT, SIGTERM         | SIGINT, SIGTERM, SIGHUP                           |
@@ -176,7 +176,7 @@ The following table lists other environment variables that can be set for diagno
 
 | Environment variable                          | Usage Instructions                                                                                              |
 |-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
-|`IBM_COREDIR=<directory>`                      | Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, `_CEE_DMPTARG` is used instead for snap trace, and transaction dumps are written to TSO according to `JAVA_DUMP_TDUMP_PATTERN`. On Linux, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location.|
+|`IBM_COREDIR=<directory>`                      | Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, `_CEE_DMPTARG` is used instead for snap trace, and transaction dumps are written to TSO according to `JAVA_DUMP_TDUMP_PATTERN`. On Linux and OS X, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location.|
 |`IBM_JAVA_ABEND_ON_FAILURE=Y` (z/OS only)      | This setting tells the Java launcher to mark the Task Control Block (TCB) with an abend code if the OpenJ9 VM fails to load or is terminated by an uncaught exception. By default, the Java launcher does not mark the TCB.|
 |`JAVA_DUMP_TDUMP_PATTERN=<string>` (z/OS only) | The specified `<string>` is passed to IEATDUMP to use as the data/set name for the Transaction Dump. The default `<string>` is `%uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S` (31-bit) or `%uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;DS` (64-bit), where `%uid` is found from the C code fragment shown in **Notes**.|
 |`JAVA_THREAD_MODEL=<string>`                   | `<string>` can be defined as one of the following values: *NATIVE* (all threads are created as `_MEDIUM_WEIGHT`), *HEAVY* (all threads are created as `_HEAVY_WEIGHT`), *MEDIUM* (same as *NATIVE*), or *NULL*. The default is *NATIVE*. |

docs/openj9_directories.md

@@ -28,10 +28,11 @@ The following tables provide a quick reference to the OpenJ9 VM directory locati
 pages refer to the VM directory location as `<vm_dir>`.
 
 
-| Operating system            | Java 8                                  | Java 10 and later                          |
-|-----------------------------|-----------------------------------------|-------------------------------------------|
+| Operating system | Java 8                                  | Java 10 and later                          |
+|------------------|-----------------------------------------|--------------------------------------------|
 | AIX&reg;         | `<install_dir>/jre/lib/ppc[64]/default` | `<install_dir>/` |
-| Linux&reg;     | `<install_dir>/jre/lib/<arch>/default`  | `<install_dir>/` |
+| Linux&reg;       | `<install_dir>/jre/lib/<arch>/default`  | `<install_dir>/` |
+| OS X&reg;        | `<install_dir>/jre/lib/default`         | `<install_dir>/` |
 | Windows&trade;   | `<install_dir>\jre\bin\default`         | `<install_dir>\` |
 | z/OS&reg;        | `<install_dir>/jre/lib/s390[x]/default` | `<install_dir>/` |
 

docs/xcodecache.md

@@ -22,7 +22,7 @@
 * Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
 -->
 
-# -Xcodecache 
+# -Xcodecache
 
 Use this option to tune performance.
 
@@ -33,12 +33,11 @@ This option sets the size of each block of memory that is allocated to store the
 
 ## Syntax
 
-        -Xcodecache <size>
+        -Xcodecache<size>
 
 : See [Using -X command-line options](x_jvm_commands) for more information about specifying the `<size>` parameter.
 
 
 
 
 <!-- ==== END OF TOPIC ==== xcodecache.md ==== -->
-

docs/xdiagnosticscollector.md

@@ -22,9 +22,15 @@
 * Classpath-exception-2.0 OR LicenseRef-GPL-2.0 WITH Assembly-exception
 -->
 
-# -Xdiagnosticscollector 
+# -Xdiagnosticscollector
 
-This option is now redundant, and only generates a warning message. Use the [IBM® Support Assistant Data Collector](http://www-01.ibm.com/software/support/isa/#isa-dc-dl) instead.
+This option is now redundant and generates only the following warning message:
+
+```
+JVMJ9VM138W The -Xdiagnosticscollector option is not supported by this JVM.
+```
+
+Use the [IBM® Support Assistant Data Collector](http://www-01.ibm.com/software/support/isa/#isa-dc-dl) instead.
 
 
 ## Syntax
@@ -34,4 +40,3 @@ This option is now redundant, and only generates a warning message. Use the [IBM
 
 
 <!-- ==== END OF TOPIC ==== xdiagnosticscollector.md ==== -->
-

docs/xdump.md

@@ -277,7 +277,7 @@ The following table shows the events that are available as dump agent triggers:
 | Event           |  Triggered when....                                                         | Filters on ....                                                |
 | ----------------|-----------------------------------------------------------------------------|----------------------------------------------------------------|
 | **gpf**         | A General Protection Fault (GPF) occurs.                                    | Not applicable                                                 |
-| **user**        | The VM receives the SIGQUIT (Linux, AIX®, z/OS) or SIGBREAK (Windows™) signal from the operating system.|  Not applicable                      |
+| **user**        | The VM receives the SIGQUIT (Linux, OS X®, AIX®, z/OS) or SIGBREAK (Windows™) signal from the operating system.|  Not applicable                      |
 | **abort**       | The VM receives the SIGABRT signal from the operating system.               | Not applicable                                                 |
 | **vmstart**     | The virtual machine is started.                                             | Not applicable                                                 |
 | **vmstop**      | The virtual machine stops.                                                  | Exit code; for example, `filter=#129..#192#-42#255`            |
@@ -535,7 +535,7 @@ You can filter the **slow** event to change the time threshold from the default
 ```
 
 #### allocation event
-**(Linux and Windows only)**
+**(Linux, OS X, and Windows only)**
 
 You must filter the **allocation** event to specify the size of objects that cause a trigger. You can set the filter size from zero up to the maximum value of a 32-bit pointer on 32-bit platforms, or the maximum value of a 64-bit pointer on 64-bit platforms. Setting the lower filter value to zero triggers a dump on all allocations.
 
@@ -725,7 +725,7 @@ In general, the default request options are sufficient.
 
 Dump output is written to different files, depending on the type of dump and the platform. File names include a time stamp.
 
-| Dump type      | File name  (AIX, Linux, Windows)                                | File name (z/OS)                                                                                         |
+| Dump type      | File name  (AIX, Linux, OS X, Windows)                                | File name (z/OS)                                                                                         |
 |----------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
 | System dump    | core.%Y%m%d.%H%M%S.%pid.dmp                                     |  %uid.JVM.TDUMP.%job.D%Y%m%d.T%H%M%S (31-bit),  %uid.JVM.%job.D%y%m%d.T%H%M%S.X&DS (64-bit) See **Note** |
 | Java dump      | javacore.%Y%m%d.%H%M%S.%pid.%seq.txt                            | javacore.%Y%m%d.%H%M%S.%pid.%seq.txt                                                                     |

docs/xgc.md

@@ -41,7 +41,7 @@ Options that change the behavior of the Garbage Collector (GC).
 | [`minContractPercent`          ](#mincontractpercent          ) | Sets the minimum percentage of the heap that can be contracted at any given time.                       |
 | [`maxContractPercent`          ](#maxcontractpercent          ) | Sets the maximum percentage of the heap that can be contracted at any given time.                       |
 | [`overrideHiresTimerCheck`     ](#overridehirestimercheck     ) | Overrides GC operating system checks for timer resolution.                                              |
-| [`preferredHeapBase`           ](#preferredheapbase           ) | Sets a memory range for the Java™ heap. (AIX®, Linux®, and Windows™ only) |
+| [`preferredHeapBase`           ](#preferredheapbase           ) | Sets a memory range for the Java™ heap. (AIX®, Linux®, OS X®, and Windows™ only) |
 | [`scvNoAdaptiveTenure`         ](#scvnoadaptivetenure         ) | Turns off the adaptive tenure age in the generational concurrent GC policy.                             |
 | [`scvTenureAge`                ](#scvtenureage                ) | Sets the initial scavenger tenure age in the generational concurrent GC policy.                         |
 | [`tlhIncrementSize`            ](#tlhincrementsize            ) | Sets the size of the thread local heap (TLH)  increment                                      |
@@ -142,7 +142,7 @@ Options that change the behavior of the Garbage Collector (GC).
 
 ### `preferredHeapBase`
 
-**(AIX, Linux, Windows only)**
+**(AIX, Linux, OS X, and Windows only)**
 
         -Xgc:preferredHeapBase=<address>
 
@@ -152,8 +152,7 @@ Options that change the behavior of the Garbage Collector (GC).
 
 : where, `<address>` is the base memory address for the heap. Use this option with the `-Xcompressedrefs` option to allocate the heap you specify with the [`-Xmx`](xms.md) option, in a memory range of your choice. If `-Xcompressedrefs` is not specified, this option has no effect. In the following example, the heap is located at the 4 GB mark, leaving the lowest 4 GB of address space for use by other processes.
 
-        :::java
-        -Xgc:preferredHeapBase=0x100000000
+      -Xgc:preferredHeapBase=0x100000000
 
     If the heap cannot be allocated in a contiguous block at the `preferredHeapBase` address you specified, an error occurs detailing a Garbage Collection (GC) allocation failure startup. When the `preferredHeapBase` option is used with the [`-Xlp`](xlp.md) option, the `preferredHeapBase` address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.
 

docs/xgcpolicy.md

@@ -123,7 +123,7 @@ The following options are ignored when specified with `-Xgcpolicy:balanced`:
 
 : The generational concurrent policy (default) uses a concurrent mark phase combined with generational garbage collection to help minimize the time that is spent in any garbage collection pause. This policy is particularly useful for applications with many short-lived objects, such as transactional applications. Pause times can be significantly shorter than with the `optthruput` policy, while still producing good throughput. Heap fragmentation is also reduced.
 
-### `metronome` (AIX®, Linux® only)
+### `metronome` (AIX®, Linux® x86 only)
 
         -Xgcpolicy:metronome
 

docs/xjit.md

@@ -48,7 +48,7 @@ These parameters can be used to modify the behavior of `-Xjit`:
 | [`count`         ](#count         ) | Forces compilation of methods on first invocation.                                      |
 | [`disableRMODE64`](#disablermode64) | Allows the JIT to allocate executable code caches above the 2 GB memory bar.            |
 | [`exclude`       ](#exclude       ) | Excludes the specified method from compilation.                                         |
-| [`<limitFile>`    ](#limitfile      ) | Compile methods that are listed in the limit file.                                      |
+| [`<limitFile>`   ](#limitfile     ) | Compile methods that are listed in the limit file.                                      |
 | [`optlevel`      ](#optlevel      ) | Forces the JIT compiler to compile all methods at a specific optimization level.        |
 | [`verbose`       ](#verbose       ) | Reports information about the JIT and AOT compiler configuration and method compilation.|
 | [`vlog`          ](#vlog          ) | Sends verbose output to a file.                                                         |

docs/xlp.md

@@ -26,7 +26,9 @@
 
 Requests the OpenJ9 VM to allocate the Java™ object heap and JIT code cache memory with large pages.
 
-**Note:** This option is deprecated in all versions later than Java 8. Use the [`-Xlp:codecache`](xlpcodecache.md) and [`-Xlp:objectheap`](xlpobjectheap.md) options instead.
+<i class="fa fa-pencil-square-o" aria-hidden="true"></i> **Note:** This option is deprecated in all versions later than Java 8. Use the [`-Xlp:codecache`](xlpcodecache.md) and [`-Xlp:objectheap`](xlpobjectheap.md) options instead.
+
+<i class="fa fa-exclamation-triangle" aria-hidden="true"></i> **Restriction:** This option does not work on OS X&reg;.
 
 If you use the [`-Xgc:preferredHeapBase`](xgc.md#preferredheapbase) option with `-Xlp`, the preferredHeapBase address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.
 

docs/xlpcodecache.md

@@ -32,7 +32,7 @@ To find out the large page sizes available and the current setting, use the `-ve
 
 ## Syntax
 
-AIX®, Linux®, and Windows™:
+AIX®, Linux®, OS X®, and Windows™:
 
         -Xlp:codecache:pagesize=<size>
 
@@ -59,6 +59,10 @@ See [Using -X command-line options](x_jvm_commands.md) for more information abou
     - Linux on Power Systems&trade;: The code cache page size cannot be controlled by the `-Xlp:codecache:pagesize=<size>` option. Specifying any other page size results in a warning that the page size is not available. The `-verbose:sizes` output reflects the current operating system setting.
     - On other architectures, the VM uses the default operating system page size.
 
+### OS X
+
+: The default size for the code cache is 4 K large pages.
+
 ### z/OS
 
 : 1 M pageable pages, when available, are the default size for the code cache.

docs/xlpobjectheap.md

@@ -31,7 +31,7 @@ To find out the large page sizes available and the current setting, use the `-ve
 
 ## Syntax
 
-AIX®, Linux®, and Windows™:
+AIX®, Linux®, OS X®, and Windows™:
 
         -Xlp:objectheap:pagesize=<size>[,strict|warn]
 
@@ -59,6 +59,8 @@ See [Using -X command-line options](x_jvm_commands.md) for more information abou
     - Linux on IBM Z&reg;: 1 MB large pages
     - On other architectures, the VM uses the default operating system page size.
 
+: On OS X, the default page size is 4 K.
+
 ### `strict` | `warn`
 
         -Xlp:objectheap:strict

docs/xrs.md

@@ -39,8 +39,9 @@ Disabling signal handling in the OpenJ9 VM reduces performance by approximately
 
 : If you specify the `sync` parameter:
 
-    - **On AIX® systems:** Disables signal handling in the VM for `SIGSEGV`, `SIGFPE`, `SIGBUS`, `SIGILL`, `SIGTRAP`, and `SIGABRT` signals. However, the VM still handles the `SIGQUIT` and `SIGTERM` signals, among others.
+    - **On AIX®, Linux®, OS X®, and z/OS® systems:** Disables signal handling in the VM for `SIGSEGV`, `SIGFPE`, `SIGBUS`, `SIGILL`, `SIGTRAP`, and `SIGABRT` signals. However, the VM still handles the `SIGQUIT` and `SIGTERM` signals, among others.
     - **On Windows™ systems:** Hardware exceptions are not handled by the OpenJ9 VM when this option is specified. However, the Windows CTRL\_BREAK\_EVENT signal, triggered by the Ctrl-Break key combination, is still handled by the VM.
-    - **Linux® systems** always use the `SIGUSR1` signal.
+
+    **Linux and OS X systems** always use the `SIGUSR1` signal.
 
 <!-- ==== END OF TOPIC ==== xrs.md ==== -->