annotate dynload/dynload.3 @ 250:7cb8a0aaf638

- note about c99 (+ anon struct/union) requirements in doc
author Tassilo Philipp
date Sun, 14 May 2017 00:19:15 +0200
parents ab23f9f2934a
children 5cfe4322c500
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
216
28bf0b231bce - dynload man page clarification about resolving own symbols
Tassilo Philipp
parents: 93
diff changeset
1 .\" Copyright (c) 2007-2017 Daniel Adler <dadler AT uni-goettingen DOT de>,
0
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 .\" Tassilo Philipp <tphilipp AT potion-studios DOT com>
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 .\"
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 .\" Permission to use, copy, modify, and distribute this software for any
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 .\" purpose with or without fee is hereby granted, provided that the above
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 .\" copyright notice and this permission notice appear in all copies.
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 .\"
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 .\"
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 .Dd $Mdocdate$
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 .Dt dynload 3
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 .Sh NAME
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 .Nm dynload
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 .Nd encapsulates dynamic loading mechanisms and
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 gives access to functions in foreign dynamic libraries and code modules.
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 .Sh SYNOPSIS
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23 .In dynload.h
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 .Ft DLLib *
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 .Fn dlLoadLibrary "const char * libpath"
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 .Ft void
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 .Fn dlFreeLibrary "DLLib * pLib"
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
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
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
30 .Ft int
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
31 .Fn dlGetLibraryPath "DLLib * pLib" "char * sOut" "int bufSize"
228
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
32 .Ft DLSyms*
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
33 .Fn dlSymsInit "const char * libPath"
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
34 .Ft void
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
35 .Fn dlSymsCleanup "DLSyms * pSyms"
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
36 .Ft int
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
37 .Fn dlSymsCount "DLSyms * pSyms"
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
38 .Ft const char*
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
39 .Fn dlSymsName "DLSyms * pSyms" "int index"
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
40 .Ft const char*
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
41 .Fn dlSymsNameFromValue "DLSyms * pSyms" "void * value"
0
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 .Sh DESCRIPTION
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 The
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 .Nm
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 library provides an interface to load foreign dynamic libraries and access
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 to their symbols.
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 .Pp
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 .Fn dlLoadLibrary
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 loads a dynamic library at
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 .Ar libpath
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 and returns a handle to it for use in
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52 .Fn dlFreeLibrary
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 and
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
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
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
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.
0
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 .Pp
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 .Fn dlFreeLibrary
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60 frees the loaded library with handle
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61 .Ar pLib .
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 .Pp
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 .Fn dlFindSymbol
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64 returns a pointer to a symbol with name
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 .Ar pSymbolName
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 in the library with handle
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 .Ar pLib ,
223
7076f551faf5 - dynload mach-o handling fixes for 64bit platforms
Tassilo Philipp
parents: 216
diff changeset
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.).
228
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
69 .Pp
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
70 .Fn dlGetLibraryPath
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
71 can be used to get a copy of the path to the library loaded with handle
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
72 .Ar pLib .
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
73 The parameter
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
74 .Ar sOut
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
75 is a pointer to a buffer of size
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
76 .Ar bufSize
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
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
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
78 .Ar bufSize
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
79 >= return value > 1, a null-terminted string with the path to the library should be in
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
80 .Ar sOut .
248
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
81 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.
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
82 .Pp
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
83 The dlSyms* functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
84 for symbol name lookups, not to get symbols' addresses. For that refer to
228
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
85 .Fn dlFindSymbol .
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
86 .Fn dlSymsInit
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
87 will return a handle (or null pointer on error) to the shared object specified by
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
88 .Ar libPath ,
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
89 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
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
90 .Fn dlSymsCleanup .
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
91 .Fn dlSymsCount
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
92 returns the number of symbols in the shared object,
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
93 .Fn dlSymsName
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
94 and
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
95 .Fn dlSymsNameFromValue
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
96 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
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
97 .Fn dlSymsNameFromValue
f8a6e60598cc - completed dynload API doc
Tassilo Philipp
parents: 223
diff changeset
98 must point to a loaded symbol.
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
99 .Sh BUGS
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
100 .Fn dlGetLibraryPath
248
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
101 is not thread-safe on Darwin (macOS, iOS, ...) and OpenBSD.
243
2a77747a5496 dynload doc:
Tassilo Philipp
parents: 228
diff changeset
102 .Fn dlSymsInit
248
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
103 is not thread-safe on Darwin.
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
104 .Fn dlGetLibraryPath
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
105 will not work on Haiku when the library in question doesn't have the (default)
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
106 .Fn _init
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
107 and
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
108 .Fn _fini
ab23f9f2934a - BeOS impl for dlGetLibraryPath
Tassilo Philipp
parents: 243
diff changeset
109 symbols exported (rare, but possible).
250
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents: 248
diff changeset
110 .Sh CONFORMING TO
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents: 248
diff changeset
111 The dynload library conforms to c99.
7cb8a0aaf638 - note about c99 (+ anon struct/union) requirements in doc
Tassilo Philipp
parents: 248
diff changeset
112 .Ed
0
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
113 .Sh SEE ALSO
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
114 .Xr dyncall 3 ,
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
115 .Xr dyncallback 3
93
dfde5035d410 - better, more neutral .3 SEE ALSO
cslag
parents: 81
diff changeset
116 and the dyncall manual (available in HTML and PDF format) for more information.
0
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
117 .Sh AUTHORS
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
118 .An "Daniel Adler" Aq dadler@uni-goettingen.de
3e629dc19168 initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
119 .An "Tassilo Philipp" Aq tphilipp@potion-studios.com