2 files changed, 168 insertions, 10 deletions
diff --git a/share/man/man7/d.7 b/share/man/man7/d.7
index 4b00d3d71c79..59b3389b121b 100644
--- a/share/man/man7/d.7
+++ b/share/man/man7/d.7
@@ -198,6 +198,130 @@ The number of nanoseconds since the Epoch
 Suitable for timestamping logs.
 .El
 .Sh BUILT-IN FUNCTIONS
+.\" Keep the indentation wide enough for the reader to be able to skim through
+.\" function names quickly.
+.Bl -tag -width "size_t strlen"
+.It Ft string Fn strchr "string s" "char c"
+Return a substring of
+.Fa s
+starting at the first occurance of
+.Fa c
+in
+.Fa s .
+Return
+.Dv NULL
+if
+.Fa c
+does not occur in
+.Fa s .
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+strchr("abc", 'b');
+.Ed
+returns
+.Ql "bc"
+and
+.Bd -literal -compact -offset indent
+strchr("abc", 'd');
+.Ed
+returns
+.Dv NULL .
+.It Ft string Fn strjoin "string s1" "string s2"
+Return a string resulting from concatenating
+.Fa s1
+and
+.Fa s2 .
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+strjoin("abc", "def")
+.Ed
+returns
+.Ql abcdef .
+.It Ft string Fn strrchr "string s" "char c"
+Return a substring of
+.Fa s
+starting at the last occurance of
+.Fa c
+in
+.Fa s .
+Similar to
+.Fn strchr .
+.It Ft string Fn strstr "string haystack" "string needle"
+Return a substring of
+.Fa haystack
+starting at the first occurrence of
+.Fa needle .
+Return
+.Dv NULL
+if
+.Fa needle
+is not a substring of
+.Fa haystack .
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+strstr("abc1bc2", "bc")
+.Ed
+returns
+.Ql bc1bc2
+and
+.Bd -literal -compact -offset indent
+strstr("abc", "xy")
+.Ed
+returns
+.Dv NULL .
+.It Ft string Fn strtok "string s" "string separators"
+Tokenize
+.Fa s
+with
+.Fa separators .
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+strtok("abcdefg", "xyzd")
+.Ed
+returns
+.Ql abc .
+.It Ft size_t Fn strlen "string s"
+Return the length of string
+.Fa s .
+.It Ft string Fn substr "string s" "int position" "[int length]"
+Return a
+substring of string
+.Fa s
+starting at
+.Fa position .
+The substring will be at most
+.Fa length Ns -long .
+If
+.Fa length
+is not specified, use the rest of the string.
+If
+.Fa position
+is greater than
+the size of
+.Fa s ,
+return an empty string.
+.Pp
+For example,
+.Bd -literal -compact -offset indent
+substr("abcd", 2)
+.Ed
+returns
+.Ql cd ,
+.Bd -literal -compact -offset indent
+substr("abcd", 2, 1)
+.Ed
+returns
+.Ql c ,
+and
+.Bd -literal -compact -offset indent
+substr("abcd", 99)
+.Ed
+returns an empty string.
+.El
 .Ss Aggregation Functions
 .Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)"
 .It Fn avg value
diff --git a/share/man/man9/atomic.9 b/share/man/man9/atomic.9
index c9133c6311a5..b027a0ff0bca 100644
--- a/share/man/man9/atomic.9
+++ b/share/man/man9/atomic.9
@@ -182,35 +182,42 @@ This variant is the default.
 The second variant has acquire semantics, and the third variant has release
 semantics.
 .Pp
-When an atomic operation has acquire semantics, the operation must have
+An atomic operation can only have
+.Em acquire
+semantics if it performs a load
+from memory.
+When an atomic operation has acquire semantics, a load performed as
+part of the operation must have
 completed before any subsequent load or store (by program order) is
 performed.
 Conversely, acquire semantics do not require that prior loads or stores have
-completed before the atomic operation is performed.
-An atomic operation can only have acquire semantics if it performs a load
-from memory.
+completed before a load from the atomic operation is performed.
 To denote acquire semantics, the suffix
 .Dq Li _acq
 is inserted into the function name immediately prior to the
 .Dq Li _ Ns Aq Fa type
 suffix.
-For example, to subtract two integers ensuring that the subtraction is
+For example, to subtract two integers ensuring that the load of
+the value from memory is
 completed before any subsequent loads and stores are performed, use
 .Fn atomic_subtract_acq_int .
 .Pp
+An atomic operation can only have
+.Em release
+semantics if it performs a store to memory.
 When an atomic operation has release semantics, all prior loads or stores
-(by program order) must have completed before the operation is performed.
-Conversely, release semantics do not require that the atomic operation must
+(by program order) must have completed before a store executed as part of
+the operation that is performed.
+Conversely, release semantics do not require that a store from the atomic
+operation must
 have completed before any subsequent load or store is performed.
-An atomic operation can only have release semantics if it performs a store
-to memory.
 To denote release semantics, the suffix
 .Dq Li _rel
 is inserted into the function name immediately prior to the
 .Dq Li _ Ns Aq Fa type
 suffix.
 For example, to add two long integers ensuring that all prior loads and
-stores are completed before the addition is performed, use
+stores are completed before the store of the result is performed, use
 .Fn atomic_add_rel_long .
 .Pp
 When a release operation by one thread
@@ -235,6 +242,33 @@ section.
 However, they will not prevent the compiler or processor from moving loads
 or stores into the critical section, which does not violate the semantics of
 a mutex.
+.Ss Architecture-dependent caveats for compare-and-swap
+The
+.Fn atomic_[f]cmpset_<type>
+operations, specifically those without explicitly specified memory
+ordering, are defined as relaxed.
+Consequently, a thread's accesses to memory locations different from
+that of the atomic operation can be reordered in relation to the
+atomic operation.
+.Pp
+However, the implementation on the
+.Sy amd64
+and
+.Sy i386
+architectures provide sequentially consistent semantics.
+In particular, the reordering mentioned above cannot occur.
+.Pp
+On the
+.Sy arm64/aarch64
+architecture, the operation may include either acquire
+semantics on the constituent load or release semantics
+on the constituent store.
+This means that accesses to other locations in program order
+before the atomic, might be observed as executed after the load
+that is the part of the atomic operation (but not after the store
+from the operation due to release).
+Similarly, accesses after the atomic might be observed as executed
+before the store.
 .Ss Thread Fence Operations
 Alternatively, a programmer can use atomic thread fence operations to
 constrain the reordering of accesses.