purego: add documentation for dlfcn functions (#17)

commit: 05ec841cf131ee33d1ad4794807ddf2a53f253e3
author: TotallyGamerJet · 4y ago · 2022-08-12 02:49 UTC
committer: GitHub · 4y ago · 2022-08-12 02:49 UTC
parent: ab59a38
signature: GPG Unverified4AEE18F83AFDEB23 The key is unknown

1 file · +20 -0

M dlfcn.go +20 -0


@@ -18,6 +18,14 @@ const RTLD_GLOBAL = 0x8
18	18
19	19		const RTLD_DEFAULT = ^uintptr(1)
20	20
	21	+	// Dlopen examines the dynamic library or bundle file specified by path. If the file is compatible
	22	+	// with the current process and has not already been loaded into the
	23	+	// current process, it is loaded and linked. After being linked, if it contains
	24	+	// any initializer functions, they are called, before Dlopen
	25	+	// returns. It returns a handle that can be used with Dlsym and Dlclose.
	26	+	// A second call to Dlopen with the same path will return the same handle, but the internal
	27	+	// reference count for the handle will be incremented. Therefore, all
	28	+	// Dlopen calls should be balanced with a Dlclose call.
21	29		func Dlopen(path string, mode int) uintptr {
22	30		bs := strings.CString(path)
23	31		ret, _, _ := SyscallN(dlopenABI0, uintptr(unsafe.Pointer(bs)), uintptr(mode), 0)

@@ -25,6 +33,10 @@ func Dlopen(path string, mode int) uintptr {
25	33		return ret
26	34		}
27	35
	36	+	// Dlsym takes a "handle" of a dynamic library returned by Dlopen and the symbol name.
	37	+	// It returns the address where that symbol is loaded into memory. If the symbol is not found,
	38	+	// in the specified library or any of the libraries that were automatically loaded by Dlopen
	39	+	// when that library was loaded, Dlsym returns zero.
28	40		func Dlsym(handle uintptr, name string) uintptr {
29	41		bs := strings.CString(name)
30	42		ret, _, _ := SyscallN(dlsymABI0, handle, uintptr(unsafe.Pointer(bs)), 0)

@@ -32,6 +44,10 @@ func Dlsym(handle uintptr, name string) uintptr {
32	44		return ret
33	45		}
34	46
	47	+	// Dlerror returns a human-readable string describing the most recent error that
	48	+	// occurred from Dlopen, Dlsym or Dlclose since the last call to Dlerror. It
	49	+	// returns an empty string if no errors have occurred since initialization or
	50	+	// since it was last called.
35	51		func Dlerror() string {
36	52		// msg is only valid until the next call to Dlerror
37	53		// which is why it gets copied into a Go string

@@ -53,6 +69,10 @@ func Dlerror() string {
53	69		return string(s)
54	70		}
55	71
	72	+	// Dlclose decrements the reference count on the dynamic library handle.
	73	+	// If the reference count drops to zero and no other loaded libraries
	74	+	// use symbols in it, then the dynamic library is unloaded.
	75	+	// Dlclose returns false on success, and true on error.
56	76		func Dlclose(handle uintptr) bool {
57	77		ret, _, _ := SyscallN(dlcloseABI0, handle)
58	78		return ret != 0


@@ -18,6 +18,14 @@ const RTLD_GLOBAL = 0x8
18		18
19	const RTLD_DEFAULT = ^uintptr(1)	19		const RTLD_DEFAULT = ^uintptr(1)
20		20
		21	+	// Dlopen examines the dynamic library or bundle file specified by path. If the file is compatible
		22	+	// with the current process and has not already been loaded into the
		23	+	// current process, it is loaded and linked. After being linked, if it contains
		24	+	// any initializer functions, they are called, before Dlopen
		25	+	// returns. It returns a handle that can be used with Dlsym and Dlclose.
		26	+	// A second call to Dlopen with the same path will return the same handle, but the internal
		27	+	// reference count for the handle will be incremented. Therefore, all
		28	+	// Dlopen calls should be balanced with a Dlclose call.
21	func Dlopen(path string, mode int) uintptr {	29		func Dlopen(path string, mode int) uintptr {
22	bs := strings.CString(path)	30		bs := strings.CString(path)
23	ret, _, _ := SyscallN(dlopenABI0, uintptr(unsafe.Pointer(bs)), uintptr(mode), 0)	31		ret, _, _ := SyscallN(dlopenABI0, uintptr(unsafe.Pointer(bs)), uintptr(mode), 0)

@@ -25,6 +33,10 @@ func Dlopen(path string, mode int) uintptr {
25	return ret	33		return ret
26	}	34		}
27		35
		36	+	// Dlsym takes a "handle" of a dynamic library returned by Dlopen and the symbol name.
		37	+	// It returns the address where that symbol is loaded into memory. If the symbol is not found,
		38	+	// in the specified library or any of the libraries that were automatically loaded by Dlopen
		39	+	// when that library was loaded, Dlsym returns zero.
28	func Dlsym(handle uintptr, name string) uintptr {	40		func Dlsym(handle uintptr, name string) uintptr {
29	bs := strings.CString(name)	41		bs := strings.CString(name)
30	ret, _, _ := SyscallN(dlsymABI0, handle, uintptr(unsafe.Pointer(bs)), 0)	42		ret, _, _ := SyscallN(dlsymABI0, handle, uintptr(unsafe.Pointer(bs)), 0)

@@ -32,6 +44,10 @@ func Dlsym(handle uintptr, name string) uintptr {
32	return ret	44		return ret
33	}	45		}
34		46
		47	+	// Dlerror returns a human-readable string describing the most recent error that
		48	+	// occurred from Dlopen, Dlsym or Dlclose since the last call to Dlerror. It
		49	+	// returns an empty string if no errors have occurred since initialization or
		50	+	// since it was last called.
35	func Dlerror() string {	51		func Dlerror() string {
36	// msg is only valid until the next call to Dlerror	52		// msg is only valid until the next call to Dlerror
37	// which is why it gets copied into a Go string	53		// which is why it gets copied into a Go string

@@ -53,6 +69,10 @@ func Dlerror() string {
53	return string(s)	69		return string(s)
54	}	70		}
55		71
		72	+	// Dlclose decrements the reference count on the dynamic library handle.
		73	+	// If the reference count drops to zero and no other loaded libraries
		74	+	// use symbols in it, then the dynamic library is unloaded.
		75	+	// Dlclose returns false on success, and true on error.
56	func Dlclose(handle uintptr) bool {	76		func Dlclose(handle uintptr) bool {
57	ret, _, _ := SyscallN(dlcloseABI0, handle)	77		ret, _, _ := SyscallN(dlcloseABI0, handle)
58	return ret != 0	78		return ret != 0