[binutils-gdb] Document -z unique/-z nounique in the ld man page and help output

[Alan Modra]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=c3805e4cef747655e15f620afe6279a96d8c3fae

commit c3805e4cef747655e15f620afe6279a96d8c3fae
Author: Vivek Das Mohapatra <vivek@collabora.com>
Date:   Mon Dec 14 17:25:52 2020 +0000

    Document -z unique/-z nounique in the ld man page and help output
    
            * ld.texi (Options): Document -z unique and -z nounique.
            * lexsup.c (elf_shlib_list_options): Likewise.

Diff:
---
 ld/ChangeLog |  2 ++
 ld/ld.texi   | 10 ++++++++++
 ld/lexsup.c  |  4 ++++
 3 files changed, 16 insertions(+)

diff --git a/ld/ChangeLog b/ld/ChangeLog
index 3db7fc6a864..9a0ff59dfce 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -2,6 +2,8 @@
 
 	* emultempl/elf.em (gld${EMULATION_NAME}_handle_option):
 	Parse -z unique / -z nounique options.
+	* ld.texi (Options): Document -z unique and -z nounique.
+	* lexsup.c (elf_shlib_list_options): Likewise.
 
 2020-12-14  Howard Chu  <hyc@symas.com>
 
diff --git a/ld/ld.texi b/ld/ld.texi
index 51c51a3ec1f..88b1687f1bb 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1306,6 +1306,16 @@ Specify that the dynamic loader should modify its symbol search order
 so that symbols in this shared library interpose all other shared
 libraries not so marked.
 
+@item unique
+@itemx nounique
+When generating a shared library or other dynamically loadable ELF
+object mark it as one that should (by default) only ever be loaded once,
+and only in the main namespace (when using @code{dlmopen}). This is
+primarily used to mark fundamental libraries such as libc, libpthread et
+al which do not usually function correctly unless they are the sole instances
+of themselves. This behaviour can be overridden by the @code{dlmopen} caller
+and does not apply to certain loading mechanisms (such as audit libraries).
+
 @item lazy
 When generating an executable or shared library, mark it to tell the
 dynamic linker to defer function call resolution to the point when
diff --git a/ld/lexsup.c b/ld/lexsup.c
index 78b1834e61e..1d01833b310 100644
--- a/ld/lexsup.c
+++ b/ld/lexsup.c
@@ -2022,6 +2022,10 @@ elf_shlib_list_options (FILE *file)
   fprintf (file, _("\
   -z interpose                Mark object to interpose all DSOs but executable\n"));
   fprintf (file, _("\
+  -z unique                   Mark DSO to be loaded at most once by default, and only in the main namespace\n"));
+  fprintf (file, _("\
+  -z nounique                 Don't mark DSO as a loadable at most once\n"));
+  fprintf (file, _("\
   -z lazy                     Mark object lazy runtime binding (default)\n"));
   fprintf (file, _("\
   -z loadfltr                 Mark object requiring immediate process\n"));