dlsym.3: Move dlsym() and dlvsym3() content to their own page

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

diff --git a/man3/dlsym.3 b/man3/dlsym.3
index 15d096806fd16b2f8bc7939b41557cc9b6bc3bbb..7277a6a3b9f8f617b61d64e5f75c3476182489e9 100644 (file)
--- a/man3/dlsym.3
+++ b/man3/dlsym.3
@@ -1 +1,135 @@
-.so man3/dlopen.3
+.\" Copyright 1995 Yggdrasil Computing, Incorporated.
+.\" and Copyright 2003, 2015 Michael Kerrisk (mtk.manpages@gmail.com).
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH DLSYM 3 2015-07-16 "Linux" "Linux Programmer's Manual"
+.SH NAME
+dlsym, dlvsym \- obtain address of a symbol in a shared object or executable
+.SH SYNOPSIS
+.B #include <dlfcn.h>
+.sp
+.BI "void *dlsym(void *" handle ", const char *" symbol );
+.sp
+.B #define _GNU_SOURCE
+.br
+.B #include <dlfcn.h>
+.sp
+.BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version );
+.sp
+Link with \fI\-ldl\fP.
+.SH DESCRIPTION
+The function
+.BR dlsym ()
+takes a "handle" of a dynamic loaded shared object returned by
+.BR dlopen (3)
+along with a null-terminated symbol name,
+and returns the address where that symbol is
+loaded into memory.
+If the symbol is not found, in the specified
+object or any of the shared objects that were automatically loaded by
+.BR dlopen (3)
+when that object was loaded,
+.BR dlsym ()
+returns NULL.
+(The search performed by
+.BR dlsym ()
+is breadth first through the dependency tree of these shared objects.)
+
+Since the value of the symbol could actually be NULL (so that a
+NULL return from
+.BR dlsym ()
+need not indicate an error), the correct way to test for an error
+is to call
+.BR dlerror (3)
+to clear any old error conditions, then call
+.BR dlsym (),
+and then call
+.BR dlerror (3)
+again, saving its return value into a variable, and check whether
+this saved value is not NULL.
+.PP
+There are two special pseudo-handles that may be specified in
+.IR handle :
+.TP
+.B RTLD_DEFAULT
+Find the first occurrence of the desired symbol
+using the default shared object search order.
+The search will include global symbols in the executable
+and its dependencies,
+as well as symbols in shared objects that were dynamically loaded with the
+.BR RTLD_GLOBAL
+flag.
+.TP
+.BR RTLD_NEXT
+Find the next occurrence of the desired symbol in the search order
+after the current object.
+This allows one to provide a wrapper
+around a function in another shared object, so that, for example,
+the definition of a function in a preloaded shared object
+(see
+.B LD_PRELOAD
+in
+.BR ld.so (8))
+can find and invoke the "real" function provided in another shared object
+(or for that matter, the "next" definition of the function in cases
+where there are multiple layers of preloading).
+
+The function
+.BR dlvsym ()
+does the same as
+.BR dlsym ()
+but takes a version string as an additional argument.
+.SH RETURN VALUE
+On success,
+these functions return the address associated with
+.IR symbol .
+On failure, they return NULL;
+the cause of the error can be diagnosed using
+.BR dlerror (3).
+.SH VERSIONS
+.BR dlsym ()
+is present in glibc 2.0 and later.
+.BR dlvsym ()
+first appeared in glibc 2.1.
+.SH CONFORMING TO
+POSIX.1-2001 describes
+.BR dlsym ().
+The
+.BR dlvsym ()
+function is a GNU extension.
+.SH NOTES
+.SS History
+The
+.BR dlsym ()
+function is part of the dlopen API, derived from SunOS.
+That system does not have
+.BR dlvsym ().
+.SH EXAMPLE
+See
+.BR dlopen (3).
+.SH SEE ALSO
+.BR dl_iterate_phdr (3),
+.BR dladdr (3),
+.BR dlinfo (3),
+.BR dlopen (3),
+.BR ld.so (8)