logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

dlsym.3p (6072B)


  1. '\" et
  2. .TH DLSYM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. dlsym
  12. \(em get the address of a symbol from a symbol table handle
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <dlfcn.h>
  17. .P
  18. void *dlsym(void *restrict \fIhandle\fP, const char *restrict \fIname\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIdlsym\fR()
  23. function shall obtain the address of a symbol (a function identifier or
  24. a data object identifier) defined in the symbol table identified by the
  25. .IR handle
  26. argument. The
  27. .IR handle
  28. argument is a symbol table handle returned from a call to
  29. \fIdlopen\fR()
  30. (and which has not since been released by a call to
  31. \fIdlclose\fR()),
  32. and
  33. .IR name
  34. is the symbol's name as a character string. The return value from
  35. \fIdlsym\fR(),
  36. cast to a pointer to the type of the named symbol, can be used to call
  37. (in the case of a function) or access the contents of (in the case of
  38. a data object) the named symbol.
  39. .P
  40. The
  41. \fIdlsym\fR()
  42. function shall search for the named symbol in the symbol table
  43. referenced by
  44. .IR handle .
  45. If the symbol table was created with lazy loading
  46. (see RTLD_LAZY in
  47. \fIdlopen\fR()),
  48. load ordering shall be used in
  49. \fIdlsym\fR()
  50. operations to relocate executable object files needed to resolve the
  51. symbol. The symbol resolution algorithm used shall be dependency order
  52. as described in
  53. \fIdlopen\fR().
  54. .P
  55. The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined in
  56. .IR <dlfcn.h> )
  57. are reserved for future use as special values that applications may be
  58. allowed to use for
  59. .IR handle .
  60. .SH "RETURN VALUE"
  61. Upon successful completion, if
  62. .IR name
  63. names a function identifier,
  64. \fIdlsym\fR()
  65. shall return the address of the function converted from type pointer to
  66. function to type pointer to
  67. .BR void ;
  68. otherwise,
  69. \fIdlsym\fR()
  70. shall return the address of the data object associated with the data
  71. object identifier named by
  72. .IR name
  73. converted from a pointer to the type of the data object to a pointer to
  74. .BR void .
  75. If
  76. .IR handle
  77. does not refer to a valid symbol table handle or if the symbol named by
  78. .IR name
  79. cannot be found in the symbol table associated with
  80. .IR handle ,
  81. \fIdlsym\fR()
  82. shall return a null pointer.
  83. .P
  84. More detailed diagnostic information shall be available through
  85. \fIdlerror\fR().
  86. .SH ERRORS
  87. No errors are defined.
  88. .LP
  89. .IR "The following sections are informative."
  90. .SH "EXAMPLES"
  91. The following example shows how
  92. \fIdlopen\fR()
  93. and
  94. \fIdlsym\fR()
  95. can be used to access either a function or a data object. For simplicity,
  96. error checking has been omitted.
  97. .sp
  98. .RS 4
  99. .nf
  100. void *handle;
  101. int (*fptr)(int), *iptr, result;
  102. /* open the needed symbol table */
  103. handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY);
  104. /* find the address of the function my_function */
  105. fptr = (int (*)(int))dlsym(handle, "my_function");
  106. /* find the address of the data object my_object */
  107. iptr = (int *)dlsym(handle, "my_OBJ");
  108. /* invoke my_function, passing the value of my_OBJ as the parameter */
  109. result = (*fptr)(*iptr);
  110. .fi
  111. .P
  112. .RE
  113. .SH "APPLICATION USAGE"
  114. The following special purpose values for
  115. .IR handle
  116. are reserved for future use and have the indicated meanings:
  117. .IP RTLD_DEFAULT 12
  118. The identifier lookup happens in the normal global scope; that is,
  119. a search for an identifier using
  120. .IR handle
  121. would find the same definition as a direct use of this identifier in
  122. the program code.
  123. .IP RTLD_NEXT 12
  124. Specifies the next executable object file after this one that defines
  125. .IR name .
  126. This one refers to the executable object file containing the invocation of
  127. \fIdlsym\fR().
  128. The next executable object file is the one found upon the application
  129. of a load order symbol resolution algorithm (see
  130. \fIdlopen\fR()).
  131. The next symbol is either one of global scope (because it was introduced
  132. as part of the original process image or because it was added with a
  133. \fIdlopen\fR()
  134. operation including the RTLD_GLOBAL flag), or is in an executable object
  135. file that was included in the same
  136. \fIdlopen\fR()
  137. operation that loaded this one.
  138. .P
  139. The RTLD_NEXT flag is useful to navigate an intentionally created
  140. hierarchy of multiply-defined symbols created through interposition. For
  141. example, if a program wished to create an implementation of
  142. \fImalloc\fR()
  143. that embedded some statistics gathering about memory allocations, such
  144. an implementation could use the real
  145. \fImalloc\fR()
  146. definition to perform the memory allocation \(em and itself only embed
  147. the necessary logic to implement the statistics gathering function.
  148. .P
  149. Note that conversion from a
  150. .BR "void *"
  151. pointer to a function pointer as in:
  152. .sp
  153. .RS 4
  154. .nf
  155. fptr = (int (*)(int))dlsym(handle, "my_function");
  156. .fi
  157. .P
  158. .RE
  159. .P
  160. is not defined by the ISO\ C standard. This standard requires this conversion to
  161. work correctly on conforming implementations.
  162. .SH RATIONALE
  163. None.
  164. .SH "FUTURE DIRECTIONS"
  165. None.
  166. .SH "SEE ALSO"
  167. .IR "\fIdlclose\fR\^(\|)",
  168. .IR "\fIdlerror\fR\^(\|)",
  169. .IR "\fIdlopen\fR\^(\|)"
  170. .P
  171. The Base Definitions volume of POSIX.1\(hy2017,
  172. .IR "\fB<dlfcn.h>\fP"
  173. .\"
  174. .SH COPYRIGHT
  175. Portions of this text are reprinted and reproduced in electronic form
  176. from IEEE Std 1003.1-2017, Standard for Information Technology
  177. -- Portable Operating System Interface (POSIX), The Open Group Base
  178. Specifications Issue 7, 2018 Edition,
  179. Copyright (C) 2018 by the Institute of
  180. Electrical and Electronics Engineers, Inc and The Open Group.
  181. In the event of any discrepancy between this version and the original IEEE and
  182. The Open Group Standard, the original IEEE and The Open Group Standard
  183. is the referee document. The original Standard can be obtained online at
  184. http://www.opengroup.org/unix/online.html .
  185. .PP
  186. Any typographical or formatting errors that appear
  187. in this page are most likely
  188. to have been introduced during the conversion of the source files to
  189. man page format. To report such errors, see
  190. https://www.kernel.org/doc/man-pages/reporting_bugs.html .