dlsym.3: Describe a case where a symbol value may be NULL

Remove a longstanding mystery in the text of the page, by
explaining a case where the value returned for a symbol may be
NULL. (However, there are presumably other cases, since the text
in the dlsym(3) manual page pre-dates the invention of IFUNCs.)

See also
https://stackoverflow.com/questions/13941944/why-can-the-value-of-the-symbol-returned-by-dlsym-be-null

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/dlsym.3 b/man3/dlsym.3
index 994488879333d8fc025f447579d448767b385982..894d52f20a45707a4c10ca779aa4bbb007f576bd 100644 (file)
--- a/man3/dlsym.3
+++ b/man3/dlsym.3
@@ -55,10 +55,11 @@ returns NULL.
 .BR dlsym ()
 is breadth first through the dependency tree of these shared objects.)
 .PP
-Since the value of the symbol could actually be NULL (so that a
-NULL return from
+In unusual cases (see NOTES) the value of the symbol could actually be NULL.
+Therefore, a NULL return from
 .BR dlsym ()
-need not indicate an error), the correct way to test for an error
+need not indicate an error.
+The correct way to distinguish an error from a symbol whose value is NULL
 is to call
 .BR dlerror (3)
 to clear any old error conditions, then call
@@ -142,6 +143,17 @@ The
 .BR dlvsym ()
 function is a GNU extension.
 .SH NOTES
+The value of a symbol returned by
+.BR dlsym ()
+will never be NULL if the shared object is the result of normal compilation,
+since a global symbol is never placed at the NULL address.
+There are nevertheless cases where a lookup using
+.BR dlsym ()
+may return NULL as the value of a symbol.
+For example, the symbol value may be the result of
+a GNU indirect function (IFUNC) resolver function that returns
+NULL as the resolved value.
+.\"
 .SS History
 The
 .BR dlsym ()