Package dl

import "gopkgs.com/dl.v1" (referenced as dl)

Overview

Package dl implements dynamic of shared libraries, like dlopen() and dlsym() in C. This package supports the following type mapping between Go and C. Go - C (u)int - (unsigned) long (u)int8 - uint8_t / int8_t (u)int16 - uint16_t / int16_t (u)int32 - (unsigned) int (u)int64 - uint64_t / int64_t float32 - float float64 - double string - char * (read only) []byte - char * (readwrite) slices - pointer to first argument uintptr - void * unsafe.Pointer - void * No struct types are supported at this time.

Index

• Documentation
• Constants

Types

• DL
  • Open(name string, flag int) (*DL, error)
  • (d *DL) Close() error
  • (d *DL) Sym(symbol string, out interface{}) error

Functions

• Open(name string, flag int) (*DL, error)

Files

• amd64.c
• asm_amd64.S
• darwin.go
• dl.go
• doc.go
• gopkgs.go
• sysv.go
• trampoline.go
• trampoline.h

Documentation

Package dl implements dynamic of shared libraries, likedlopen() and dlsym() in C.

This package supports the following type mapping between Goand C.

Go		    -   C
(u)int	    -   (unsigned) long
(u)int8	    -   uint8_t / int8_t
(u)int16	    -   uint16_t / int16_t
(u)int32	    -   (unsigned) int
(u)int64	    -   uint64_t / int64_t
float32	    -	float
float64	    -	double
string	    -   char * (read only)
[]byte	    -   char * (readwrite)
slices	    -   pointer to first argument
uintptr	    -   void *
unsafe.Pointer  -	void *

No struct types are supported at this time.

Retrieving variable symbols

Symbols pointing to variables might be retrievedeither as values or pointers. Given a C librarywhich declares a symbol as:

int my_int = 8;

It might be retrieved as a value, returning a copy with:

 var myInt int32
 if err := lib.Sym("my_int", &myInt); err != nil {
	handle_error...
 }

Alternatively, a pointer to the variable might be obtained as:

 var myInt *int32
 if err := lib.Sym("my_int", &myInt); err != nil {
	handle_error...
 }

Note that changing the value via the pointer will change the symbolin the loaded library, while changing the value obtained without thepointer will not, since a copy is made at lookup time.

Retrieving function symbols

This package also supports dynamically loading functions from libraries. Todo so you must declare a function variable which matches the signature of theC function. Note that type mismatches will likely result in crashes, so use thisfeature with extreme care. Argument and return types must be of one of thesupported types. See the examples in this package for the complete code.

 var printf func(string, ...interface{}) int32
 if err := lib.Sym("printf", &printf); err != nil {
	handle_error...
 }
 printf("this string uses C format: %d\n", 7)

Functions retrieved from a symbol can be used as standard Go functions.

Overhead

Typically, calling functions via this package rather than using cgo directlytakes around 500ns more per call, due to reflection overhead. Future versionsmight adopt a JIT strategy which should make it as fast as cgo.

Constants

const (
	// dlopen() flags. See man dlopen.
	RTLD_LAZY	= int(C.RTLD_LAZY)
	RTLD_NOW	= int(C.RTLD_NOW)
	RTLD_GLOBAL	= int(C.RTLD_GLOBAL)
	RTLD_LOCAL	= int(C.RTLD_LOCAL)
	RTLD_NODELETE	= int(C.RTLD_NODELETE)
	RTLD_NOLOAD	= int(C.RTLD_NOLOAD)
)

const (
	LibExt = ".so"
)

Types

type DL

type DL struct {
	// contains filtered or unexported fields
}

DL represents an opened dynamic library. Use Opento initialize a DL and use DL.Close when you're finishedwith it. Note that when the DL is closed all its loadedsymbols become invalid.

func Open

func Open(name string, flag int) (*DL, error)

Open opens the shared library identified by the given namewith the given flags. See man dlopen for the available flagsand its meaning. Note that the only difference with dlopen is thatif nor RTLD_LAZY nor RTLD_NOW are specified, Open defaults toRTLD_NOW rather than returning an error. If the name argumentpassed to name does not have extension, the default for theplatform will be appended to it (e.g. .so, .dylib, etc...).

func (DL) Close

func (d *DL) Close() error

Close closes the shared library handle. All symbolsloaded from the library will become invalid.

func (DL) Sym

func (d *DL) Sym(symbol string, out interface{}) error

Sym loads the symbol identified by the given name intothe out parameter. Note that out must always be a pointer.See the package documentation to learn how types are mappedbetween Go and C.