Mercurial > pub > dyncall > dyncall
annotate dynload/dynload.3 @ 663:127b569978cc default tip
- another tweak handling clang trying to be too smart (see last commit)
| author | Tassilo Philipp |
|---|---|
| date | Sun, 24 Mar 2024 13:52:44 +0100 |
| parents | dd5d03483314 |
| children |
| rev | line source |
|---|---|
|
382
dd5d03483314
- dynload changes to support macos >= 11.0.1 "built-in dynamic linker cache of all system-provided libraries" (those dylibs are no longer present on the fs)"
Tassilo Philipp
parents:
317
diff
changeset
|
1 .\" Copyright (c) 2007-2020 Daniel Adler <dadler AT uni-goettingen DOT de>, |
| 0 | 2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com> |
| 3 .\" | |
| 4 .\" Permission to use, copy, modify, and distribute this software for any | |
| 5 .\" purpose with or without fee is hereby granted, provided that the above | |
| 6 .\" copyright notice and this permission notice appear in all copies. | |
| 7 .\" | |
| 8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 15 .\" | |
| 16 .Dd $Mdocdate$ | |
| 17 .Dt dynload 3 | |
| 18 .Sh NAME | |
| 19 .Nm dynload | |
| 20 .Nd encapsulates dynamic loading mechanisms and | |
| 21 gives access to functions in foreign dynamic libraries and code modules. | |
| 22 .Sh SYNOPSIS | |
| 23 .In dynload.h | |
| 24 .Ft DLLib * | |
| 25 .Fn dlLoadLibrary "const char * libpath" | |
| 26 .Ft void | |
| 27 .Fn dlFreeLibrary "DLLib * pLib" | |
| 28 .Ft void * | |
|
216
28bf0b231bce
- dynload man page clarification about resolving own symbols
Tassilo Philipp
parents:
93
diff
changeset
|
29 .Fn dlFindSymbol "DLLib * pLib" "const char * pSymbolName" |
| 243 | 30 .Ft int |
| 31 .Fn dlGetLibraryPath "DLLib * pLib" "char * sOut" "int bufSize" | |
| 228 | 32 .Ft DLSyms* |
| 33 .Fn dlSymsInit "const char * libPath" | |
| 34 .Ft void | |
| 35 .Fn dlSymsCleanup "DLSyms * pSyms" | |
| 36 .Ft int | |
| 37 .Fn dlSymsCount "DLSyms * pSyms" | |
| 38 .Ft const char* | |
| 39 .Fn dlSymsName "DLSyms * pSyms" "int index" | |
| 40 .Ft const char* | |
| 41 .Fn dlSymsNameFromValue "DLSyms * pSyms" "void * value" | |
| 0 | 42 .Sh DESCRIPTION |
| 43 The | |
| 44 .Nm | |
| 45 library provides an interface to load foreign dynamic libraries and access | |
| 46 to their symbols. | |
| 47 .Pp | |
| 48 .Fn dlLoadLibrary | |
| 49 loads a dynamic library at | |
| 50 .Ar libpath | |
| 51 and returns a handle to it for use in | |
| 52 .Fn dlFreeLibrary | |
| 53 and | |
| 54 .Fn dlFindSymbol | |
|
216
28bf0b231bce
- dynload man page clarification about resolving own symbols
Tassilo Philipp
parents:
93
diff
changeset
|
55 calls. Passing a null pointer for the |
|
28bf0b231bce
- dynload man page clarification about resolving own symbols
Tassilo Philipp
parents:
93
diff
changeset
|
56 .Ar libpath |
| 308 | 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. The |
| 58 .Ar libPath | |
| 59 argument is expected to be UTF-8 encoded. Returns a null pointer on error. | |
| 0 | 60 .Pp |
| 61 .Fn dlFreeLibrary | |
| 62 frees the loaded library with handle | |
| 63 .Ar pLib . | |
| 64 .Pp | |
| 65 .Fn dlFindSymbol | |
| 66 returns a pointer to a symbol with name | |
| 67 .Ar pSymbolName | |
| 68 in the library with handle | |
| 69 .Ar pLib , | |
|
223
7076f551faf5
- dynload mach-o handling fixes for 64bit platforms
Tassilo Philipp
parents:
216
diff
changeset
|
70 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.). |
| 228 | 71 .Pp |
| 243 | 72 .Fn dlGetLibraryPath |
| 73 can be used to get a copy of the path to the library loaded with handle | |
| 74 .Ar pLib . | |
| 75 The parameter | |
| 76 .Ar sOut | |
| 77 is a pointer to a buffer of size | |
| 78 .Ar bufSize | |
| 308 | 79 (in bytes), to hold the output string (UTF-8 encoded). 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 |
| 243 | 80 .Ar bufSize |
| 308 | 81 >= return value >= 1, a null-terminted string with the path to the library should be in |
| 243 | 82 .Ar sOut . |
|
315
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
83 If it returns 0, the library name wasn't able to be found. Please note that this might happen in some rare cases, so make sure to always check. Passing a null pointer as |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
84 .Ar pLib |
|
317
3df50603afa9
- dynload fix to get proc name when elf relocation is in use
Tassilo Philipp
parents:
315
diff
changeset
|
85 returns the path to the executable (not guaranteed to be absolute - if it isn't it's relative to the working directory the process was started in, not the current one). |
| 243 | 86 .Pp |
| 87 The dlSyms* functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made | |
| 88 for symbol name lookups, not to get symbols' addresses. For that refer to | |
| 228 | 89 .Fn dlFindSymbol . |
| 90 .Fn dlSymsInit | |
| 91 will return a handle (or null pointer on error) to the shared object specified by | |
| 243 | 92 .Ar libPath , |
| 93 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 | |
| 228 | 94 .Fn dlSymsCleanup . |
| 95 .Fn dlSymsCount | |
| 96 returns the number of symbols in the shared object, | |
| 97 .Fn dlSymsName | |
| 98 and | |
| 99 .Fn dlSymsNameFromValue | |
| 100 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 | |
| 101 .Fn dlSymsNameFromValue | |
| 102 must point to a loaded symbol. | |
|
382
dd5d03483314
- dynload changes to support macos >= 11.0.1 "built-in dynamic linker cache of all system-provided libraries" (those dylibs are no longer present on the fs)"
Tassilo Philipp
parents:
317
diff
changeset
|
103 .Sh NOTES |
|
dd5d03483314
- dynload changes to support macos >= 11.0.1 "built-in dynamic linker cache of all system-provided libraries" (those dylibs are no longer present on the fs)"
Tassilo Philipp
parents:
317
diff
changeset
|
104 .Fn dlLoadLibrary |
|
dd5d03483314
- dynload changes to support macos >= 11.0.1 "built-in dynamic linker cache of all system-provided libraries" (those dylibs are no longer present on the fs)"
Tassilo Philipp
parents:
317
diff
changeset
|
105 does handle loading dylibs on macos >= 11.0.1 that aren't on the file system but are provided through the OS' "built-in dynamic linker cache of all system-provided libraries" (to load, use same "path" as one would with dlopen(3)). |
| 243 | 106 .Sh BUGS |
| 107 .Fn dlGetLibraryPath | |
| 248 | 108 is not thread-safe on Darwin (macOS, iOS, ...) and OpenBSD. |
|
315
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
109 .Pp |
| 243 | 110 .Fn dlSymsInit |
| 248 | 111 is not thread-safe on Darwin. |
|
315
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
112 .Pp |
| 248 | 113 .Fn dlGetLibraryPath |
|
253
5cfe4322c500
- improved support for older OS versions for dynloads dlGetLibraryPath
Tassilo Philipp
parents:
250
diff
changeset
|
114 will not work on the following platforms when the library in question doesn't have the (default) |
| 248 | 115 .Fn _init |
| 116 and | |
| 117 .Fn _fini | |
|
253
5cfe4322c500
- improved support for older OS versions for dynloads dlGetLibraryPath
Tassilo Philipp
parents:
250
diff
changeset
|
118 symbols exported (rare, but possible): Haiku (all versions), OpenBSD < 3.7, NetBSD < 5.1, FreeBSD < 4.8 |
|
315
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
119 .Pp |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
120 Getting the executable's path by passing NULL in |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
121 .Ar pLib |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
122 to |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
123 .Fn dlGetLibraryPath |
|
3840e0188520
- allowing lookup of running executable's path by passing NULL to dynload's dlGetLibraryPath()
Tassilo Philipp
parents:
308
diff
changeset
|
124 fails on the following platforms: Haiku (all versions), OpenBSD < 3.7, NetBSD < 5.1, FreeBSD < 4.8 |
|
250
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
248
diff
changeset
|
125 .Sh CONFORMING TO |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
248
diff
changeset
|
126 The dynload library conforms to c99. |
|
7cb8a0aaf638
- note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents:
248
diff
changeset
|
127 .Ed |
| 0 | 128 .Sh SEE ALSO |
| 129 .Xr dyncall 3 , | |
| 130 .Xr dyncallback 3 | |
| 93 | 131 and the dyncall manual (available in HTML and PDF format) for more information. |
| 0 | 132 .Sh AUTHORS |
| 133 .An "Daniel Adler" Aq dadler@uni-goettingen.de | |
| 134 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com |