From b628f896e515c0b0303c2021a6f436a17bce974e Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 4 Dec 2018 09:35:39 +0100 Subject: [PATCH] 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 --- man3/dlsym.3 | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/man3/dlsym.3 b/man3/dlsym.3 index 9944888793..894d52f20a 100644 --- 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 () -- 2.47.2