Mercurial > pub > dyncall > dyncall

comparison dynload/dynload.3 @ 243:2a77747a5496

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
dynload doc: - improved overall - added dlGetLibraryPath description: - BUGS section to manpage
author Tassilo Philipp
date Thu, 04 May 2017 13:54:09 +0200
parents f8a6e60598cc
children ab23f9f2934a
comparison
equal deleted inserted replaced
242:85b61e8facfe 243:2a77747a5496
25 .Fn dlLoadLibrary "const char * libpath" 25 .Fn dlLoadLibrary "const char * libpath"
26 .Ft void 26 .Ft void
27 .Fn dlFreeLibrary "DLLib * pLib" 27 .Fn dlFreeLibrary "DLLib * pLib"
28 .Ft void * 28 .Ft void *
29 .Fn dlFindSymbol "DLLib * pLib" "const char * pSymbolName" 29 .Fn dlFindSymbol "DLLib * pLib" "const char * pSymbolName"
30 .Ft int
31 .Fn dlGetLibraryPath "DLLib * pLib" "char * sOut" "int bufSize"
30 .Ft DLSyms* 32 .Ft DLSyms*
31 .Fn dlSymsInit "const char * libPath" 33 .Fn dlSymsInit "const char * libPath"
32 .Ft void 34 .Ft void
33 .Fn dlSymsCleanup "DLSyms * pSyms" 35 .Fn dlSymsCleanup "DLSyms * pSyms"
34 .Ft int 36 .Ft int
50 .Fn dlFreeLibrary 52 .Fn dlFreeLibrary
51 and 53 and
52 .Fn dlFindSymbol 54 .Fn dlFindSymbol
53 calls. Passing a null pointer for the 55 calls. Passing a null pointer for the
54 .Ar libpath 56 .Ar libpath
55 argument is valid, and returns a handle to the main executable of the calling code. Returns a null pointer on error. 57 argument is valid, and returns a handle to the main executable of the calling code. Also, searching libraries in library paths (e.g. by just passing the library's leaf name) should work, however, they are OS specific. Returns a null pointer on error.
56 .Pp 58 .Pp
57 .Fn dlFreeLibrary 59 .Fn dlFreeLibrary
58 frees the loaded library with handle 60 frees the loaded library with handle
59 .Ar pLib . 61 .Ar pLib .
60 .Pp 62 .Pp
63 .Ar pSymbolName 65 .Ar pSymbolName
64 in the library with handle 66 in the library with handle
65 .Ar pLib , 67 .Ar pLib ,
66 or returns a null pointer if the symbol cannot be found. The name is specified as it would appear in C source code (mangled if C++, etc.). 68 or returns a null pointer if the symbol cannot be found. The name is specified as it would appear in C source code (mangled if C++, etc.).
67 .Pp 69 .Pp
68 The dlSyms* functions can be used to iterate over symbols. Note that they are made 70 .Fn dlGetLibraryPath
69 for symbol name lookups, not to get a symbol's address. For that refer to 71 can be used to get a copy of the path to the library loaded with handle
72 .Ar pLib .
73 The parameter
74 .Ar sOut
75 is a pointer to a buffer of size
76 .Ar bufSize
77 (in bytes), to hold the output string. The return value is the size of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be looked up. If
78 .Ar bufSize
79 >= return value > 1, a null-terminted string with the path to the library should be in
80 .Ar sOut .
81 .Pp
82 The dlSyms* functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made
83 for symbol name lookups, not to get symbols' addresses. For that refer to
70 .Fn dlFindSymbol . 84 .Fn dlFindSymbol .
71 .Fn dlSymsInit 85 .Fn dlSymsInit
72 will return a handle (or null pointer on error) to the shared object specified by 86 will return a handle (or null pointer on error) to the shared object specified by
73 .Ar libPath . 87 .Ar libPath ,
74 The returned handle is to be used with the other dlSyms* functions. The handle must be freed with 88 to be used with the other dlSyms* functions. Note that contrary to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with
75 .Fn dlSymsCleanup . 89 .Fn dlSymsCleanup .
76 .Fn dlSymsCount 90 .Fn dlSymsCount
77 returns the number of symbols in the shared object, 91 returns the number of symbols in the shared object,
78 .Fn dlSymsName 92 .Fn dlSymsName
79 and 93 and
80 .Fn dlSymsNameFromValue 94 .Fn dlSymsNameFromValue
81 are used to lookup symbol names using an index or symbol's address, respectively, returning a null pointer on error. The names are returned as they would appear in C source code (mangled if C++, etc.). The address passed to 95 are used to lookup symbol names using an index or symbol's address, respectively, returning a null pointer on error. The names are returned as they would appear in C source code (mangled if C++, etc.). The address passed to
82 .Fn dlSymsNameFromValue 96 .Fn dlSymsNameFromValue
83 must point to a loaded symbol. 97 must point to a loaded symbol.
98 .Sh BUGS
99 .Fn dlGetLibraryPath
100 and
101 .Fn dlSymsInit
102 are not thread-safe on Darwin (macOS, iOS, ...).
84 .Sh SEE ALSO 103 .Sh SEE ALSO
85 .Xr dyncall 3 , 104 .Xr dyncall 3 ,
86 .Xr dyncallback 3 105 .Xr dyncallback 3
87 and the dyncall manual (available in HTML and PDF format) for more information. 106 and the dyncall manual (available in HTML and PDF format) for more information.
88 .Sh AUTHORS 107 .Sh AUTHORS