Clarify Example section and Dl* windows equivalents (#274)

commit: 2d5afc8a4b0c49b48c2b6c37dad1512cb24c28a4
author: TotallyGamerJet · 2y ago · 2024-08-25 13:00 UTC
committer: GitHub · 2y ago · 2024-08-25 13:00 UTC
parent: 5905af5
signature: GPG UnverifiedB5690EEEBB952194 The key is unknown

3 files · +14 -1

M README.md +2 -1


@@ -35,7 +35,8 @@ except for float arguments and return values.
35	35
36	36		## Example
37	37
38		-	This example only works on macOS and Linux. For a complete example look at [libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports Windows and FreeBSD.
	38	+	The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can
	39	+	be seen in the complete example at [examples/libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports Windows and FreeBSD.
39	40
40	41		```go
41	42		package main


@@ -35,7 +35,8 @@ except for float arguments and return values.
35			35
36		## Example	36		## Example
37			37
38	-	This example only works on macOS and Linux. For a complete example look at [libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports Windows and FreeBSD.	38	+	The example below only showcases purego use for macOS and Linux. The other platforms require special handling which can
			39	+	be seen in the complete example at [examples/libc](https://github.com/ebitengine/purego/tree/main/examples/libc) which supports Windows and FreeBSD.
39			40
40		```go	41		```go
41		package main	42		package main

M dlerror.go +2 -0


@@ -6,6 +6,8 @@
6	6		package purego
7	7
8	8		// Dlerror represents an error value returned from Dlopen, Dlsym, or Dlclose.
	9	+	//
	10	+	// This type is not available on Windows as there is no counterpart to it on Windows.
9	11		type Dlerror struct {
10	12		s string
11	13		}


@@ -6,6 +6,8 @@
6	package purego	6		package purego
7		7
8	// Dlerror represents an error value returned from Dlopen, Dlsym, or Dlclose.	8		// Dlerror represents an error value returned from Dlopen, Dlsym, or Dlclose.
		9	+	//
		10	+	// This type is not available on Windows as there is no counterpart to it on Windows.
9	type Dlerror struct {	11		type Dlerror struct {
10	s string	12		s string
11	}	13		}

M dlfcn.go +10 -0


@@ -33,6 +33,10 @@ func init() {
33	33		// A second call to Dlopen with the same path will return the same handle, but the internal
34	34		// reference count for the handle will be incremented. Therefore, all
35	35		// Dlopen calls should be balanced with a Dlclose call.
	36	+	//
	37	+	// This function is not available on Windows.
	38	+	// Use [golang.org/x/sys/windows.LoadLibrary], [golang.org/x/sys/windows.NewLazyDLL], or
	39	+	// [golang.org/x/sys/windows.NewLazySystemDLL] for Windows instead.
36	40		func Dlopen(path string, mode int) (uintptr, error) {
37	41		u := fnDlopen(path, mode)
38	42		if u == 0 {

@@ -45,6 +49,9 @@ func Dlopen(path string, mode int) (uintptr, error) {
45	49		// It returns the address where that symbol is loaded into memory. If the symbol is not found,
46	50		// in the specified library or any of the libraries that were automatically loaded by Dlopen
47	51		// when that library was loaded, Dlsym returns zero.
	52	+	//
	53	+	// This function is not available on Windows.
	54	+	// Use [golang.org/x/sys/windows.GetProcAddress] for Windows instead.
48	55		func Dlsym(handle uintptr, name string) (uintptr, error) {
49	56		u := fnDlsym(handle, name)
50	57		if u == 0 {

@@ -56,6 +63,9 @@ func Dlsym(handle uintptr, name string) (uintptr, error) {
56	63		// Dlclose decrements the reference count on the dynamic library handle.
57	64		// If the reference count drops to zero and no other loaded libraries
58	65		// use symbols in it, then the dynamic library is unloaded.
	66	+	//
	67	+	// This function is not available on Windows.
	68	+	// Use [golang.org/x/sys/windows.FreeLibrary] for Windows instead.
59	69		func Dlclose(handle uintptr) error {
60	70		if fnDlclose(handle) {
61	71		return Dlerror{fnDlerror()}


@@ -33,6 +33,10 @@ func init() {
33	// A second call to Dlopen with the same path will return the same handle, but the internal	33		// A second call to Dlopen with the same path will return the same handle, but the internal
34	// reference count for the handle will be incremented. Therefore, all	34		// reference count for the handle will be incremented. Therefore, all
35	// Dlopen calls should be balanced with a Dlclose call.	35		// Dlopen calls should be balanced with a Dlclose call.
		36	+	//
		37	+	// This function is not available on Windows.
		38	+	// Use [golang.org/x/sys/windows.LoadLibrary], [golang.org/x/sys/windows.NewLazyDLL], or
		39	+	// [golang.org/x/sys/windows.NewLazySystemDLL] for Windows instead.
36	func Dlopen(path string, mode int) (uintptr, error) {	40		func Dlopen(path string, mode int) (uintptr, error) {
37	u := fnDlopen(path, mode)	41		u := fnDlopen(path, mode)
38	if u == 0 {	42		if u == 0 {

@@ -45,6 +49,9 @@ func Dlopen(path string, mode int) (uintptr, error) {
45	// It returns the address where that symbol is loaded into memory. If the symbol is not found,	49		// It returns the address where that symbol is loaded into memory. If the symbol is not found,
46	// in the specified library or any of the libraries that were automatically loaded by Dlopen	50		// in the specified library or any of the libraries that were automatically loaded by Dlopen
47	// when that library was loaded, Dlsym returns zero.	51		// when that library was loaded, Dlsym returns zero.
		52	+	//
		53	+	// This function is not available on Windows.
		54	+	// Use [golang.org/x/sys/windows.GetProcAddress] for Windows instead.
48	func Dlsym(handle uintptr, name string) (uintptr, error) {	55		func Dlsym(handle uintptr, name string) (uintptr, error) {
49	u := fnDlsym(handle, name)	56		u := fnDlsym(handle, name)
50	if u == 0 {	57		if u == 0 {

@@ -56,6 +63,9 @@ func Dlsym(handle uintptr, name string) (uintptr, error) {
56	// Dlclose decrements the reference count on the dynamic library handle.	63		// Dlclose decrements the reference count on the dynamic library handle.
57	// If the reference count drops to zero and no other loaded libraries	64		// If the reference count drops to zero and no other loaded libraries
58	// use symbols in it, then the dynamic library is unloaded.	65		// use symbols in it, then the dynamic library is unloaded.
		66	+	//
		67	+	// This function is not available on Windows.
		68	+	// Use [golang.org/x/sys/windows.FreeLibrary] for Windows instead.
59	func Dlclose(handle uintptr) error {	69		func Dlclose(handle uintptr) error {
60	if fnDlclose(handle) {	70		if fnDlclose(handle) {
61	return Dlerror{fnDlerror()}	71		return Dlerror{fnDlerror()}