Ref: https://gcc.gnu.org/pipermail/fortran/2026-February/063551.html
See attached.
Awaiting approval.
From b6c47d9cebece9aed34d4a46f884130eb878eca0 Mon Sep 17 00:00:00 2001
From: Jerry DeLisle <[email protected]>
Date: Sun, 15 Feb 2026 15:27:59 -0800
Subject: [PATCH] Fortran: Cleanup documentation for coarray -lcaf_shmem.
PR fortran/88076
gcc/fortran/ChangeLog:
* invoke.texi: Use corrected english.
---
gcc/fortran/invoke.texi | 73 ++++++++++++++++++++---------------------
1 file changed, 36 insertions(+), 37 deletions(-)
diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi
index c544037033a..90836657af1 100644
--- a/gcc/fortran/invoke.texi
+++ b/gcc/fortran/invoke.texi
@@ -104,7 +104,7 @@ one is not the default.
* Interoperability Options:: Options for interoperability with other
languages.
* Environment Variables:: Environment variables that affect @command{gfortran}.
-* Shared Memory Coarrays:: Multi process shared memory coarray support.
+* Shared-memory Coarrays:: Multiprocess shared-memory coarray support.
@end menu
@node Option Summary
@@ -2307,64 +2307,63 @@ variables.
run-time behavior of programs compiled with GNU Fortran.
@c man end
-@node Shared Memory Coarrays
-@section Shared Memory Coarrays
+@node Shared-memory Coarrays
+@section Shared-memory Coarrays
-@c man begin SHARED MEMORY COARRAYS
+@c man begin SHARED-MEMORY COARRAYS
-@command{gfortran} supplies a runtime library for running coarray enabled
-programs using a shared memory multi process approach. The library is supplied
-as a static link library with the @command{libgfortran} library and is fully
-compatible with the ABI enabled when @command{gfortran} is called with
-@code{-fcoarray=lib}. The shared memory coarray library then just needs to be
-linked to the executable produced by @command{gfortran} using
-@code{-lcaf_shmem}.
+@command{gfortran} supplies a runtime library for running coarray-enabled
+programs using a shared-memory multiprocess approach. The library is supplied
+as a static link library with the @command{libgfortran} library, and is fully
+compatible with the ABI enabled when @command{gfortran} is invoked with
+@option{-fcoarray=lib}. Link the shared-memory coarray to the executable
+produced by @command{gfortran} using @option{-lcaf_shmem}.
The library @code{caf_shmem} can only be used on architectures that allow
multiple processes to use the same memory at the same virtual memory address in
-each process' memory space. This is the case on most Unix and Windows based
+each process' memory space. This is the case on most Unix- and Windows-based
systems.
-The resulting executable can be started without any driver and does not provide
-any additional command line options. Limited control is possible by
+One can control some aspects of the library behavior at run time using
environment variables:
@env{GFORTRAN_NUM_IMAGES}: The number of images to spawn when running the
-executable. Note, there will always be one additional supervisor process, which
+executable. Note, there is always one additional supervisor process, which
does not participate in the computation, but is only responsible for starting
the images and catching any (ab-)normal termination. When the environment
-variable is not set, then the number of hardware threads reported by the OS will
-be taken. Over-provisioning is possible. The number of images is limited only
+variable is not set, then the number of hardware threads reported by the OS is
+used. Over-provisioning is possible. The number of images is limited only
by the OS and the size of an integer variable on the architecture the program is
-to be run on.
+running on.
-@env{GFORTRAN_SHARED_MEMORY_SIZE}: The size of the shared memory segment made
-available to all images is fixed and needs to be set at program start. It can
-not grow or shrink. The size can be given in bytes (no suffix), kilobytes
+@env{GFORTRAN_SHARED_MEMORY_SIZE}: The size of the shared-memory segment made
+available to all images is fixed and needs to be set at program start. It
+cannot grow or shrink. The size can be given in bytes (no suffix), kilobytes
(@code{k} or @code{K} suffix), megabytes (@code{m} or @code{M}) or gigabytes
(@code{g} or @code{G}). If the variable is not set, or not parseable, then on
-32-bit architectures 2^28 bytes and on 64-bit 2^34 bytes are choosen. Note,
+32-bit architectures 2^28 bytes and on 64-bit 2^34 bytes are chosen. Note,
although the size is set, most modern systems do not allocate the memory at
-program start. This allows to choose a shared memory size larger than available
-memory.
+program start. This allows one to choose a shared-memory size larger than
+available memory.
-Warning: Choosing a large shared memory size may produce large coredumps!
+Warning: Choosing a large shared-memory size may produce large core dumps!
@env{GFORTRAN_IMAGE_RESTARTS_LIMIT}: On certain platforms, esp. MacOS, the
-shared memory segment needs to be placed on the same (virtual) address in every
-image or synchronisation primitives do not work as expected. Unfortunately are
-some OSes somewhat arbitrary on when they can do this. When the OS is not able
-to fullfill the request, then the image aborts itsself and is restarted by the
-supervisor untill the OS complies. This environment variable limits the total
-number of restarts of all images having an issue with shared memory segment
+shared-memory segment needs to be placed on the same (virtual) address in every
+image or synchronization primitives do not work as expected. Unfortunately some
+operating systems are somewhat arbitrary on when they can do this. When the OS
+is not able to fulfill the request, the image aborts itself and is restarted by the
+supervisor until the OS complies. This environment variable limits the total
+number of restarts of all images having an issue with shared-memory segment
placement. The default value is 4000.
-The shared memory coarray library internally uses some additional environment
-variables, which will be overwritten without notice or may result in failure to
-start. These are: @code{GFORTRAN_IMAGE_NUM}, @code{GFORTRAN_SHMEM_PID} and
-@code{GFORTRAN_SHMEM_BASE}. It is strongly discouraged to use these variables.
-Special care needs to be taken, when one coarray program starts another coarray
+The shared-memory coarray library internally uses some additional environment
+variables, which are overwritten without notice or may result in failure to
+start. These are: @code{GFORTRAN_IMAGE_NUM}, @code{GFORTRAN_SHMEM_PID}, and
+@code{GFORTRAN_SHMEM_BASE}. Using these variables is strongly discouraged.
+Special care needs to be taken when one coarray program starts another coarray
program as a child process. In this case it is the spawning process'
-responsibility to remove above variables from the environment.
+responsibility to remove the above variables from the environment.
@c man end
+
--
2.53.0
