// Copyright 2026 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. //go:build goexperiment.cgobindings package cgo import ( "errors" "sync" "unsafe" ) // Library is a C shared library loaded at run time. // // Library is meant to be embedded in a struct type declared with a // //cgo:dynload pragma, whose methods, bound with //cgo:func and //cgo:var // pragmas, call functions and access variables in the library. See the // cgo command documentation for details. // // The zero value of Library is not usable; use [Open] to load a library. // For now, a library is never unloaded. type Library struct { handle uintptr // dlopen or LoadLibrary handle; 0 if not loaded by Open // syms holds the addresses of the symbols that cmd/cgo registered for // the type embedding the Library, indexed by a per-type symbol index // assigned by cmd/cgo. Open resolves all of them before it returns, and // they are never written again. syms []unsafe.Pointer } func (lib *Library) library() *Library { return lib } // Open loads the C shared library at path and returns a new *T for it. // // T must be a struct type that embeds Library, normally one declared with // a //cgo:dynload pragma. Open resolves all of the symbols bound to T's // methods, and fails if any of them is missing from the library. Each call // to Open returns a new instance, with its own symbol table, even if the // same library is opened more than once. On Unix, the library is loaded // with RTLD_NOW | RTLD_LOCAL, so its symbols are bound eagerly and are not // added to the global symbol namespace. // For now, libraries are never unloaded. func Open[T any, PT interface { *T library() *Library }](path string) (PT, error) { if path == "" { return nil, errors.New("cgo: Open: empty library path") } p := PT(new(T)) lib := p.library() if lib == nil { return nil, errors.New("cgo: Open: type must embed cgo.Library by value") } h, err := dlopen(path) if err != nil { return nil, err } names := registeredSymbols(any((*T)(nil))) syms := make([]unsafe.Pointer, len(names)) for i, name := range names { addr, errMsg := dlsym(h, name) if addr == nil { return nil, errors.New("cgo: Open " + path + ": cannot resolve symbol " + name + ": " + errMsg) } syms[i] = addr } lib.handle = h lib.syms = syms return p, nil } var ( librariesMu sync.Mutex libraries map[any][]string // (*T)(nil) -> T's symbol names ) // registerLibrary records the names of the symbols bound to the methods of // the type T embedding Library, where typ is (*T)(nil). The index of a name // in syms is the index that cmd/cgo assigned to the symbol, which is passed // to librarySymbol. // // registerLibrary is called by code generated by cmd/cgo, from package // initialization. // //go:linkname registerLibrary func registerLibrary(typ any, syms []string) { librariesMu.Lock() defer librariesMu.Unlock() if libraries == nil { libraries = make(map[any][]string) } libraries[typ] = syms } // registeredSymbols returns the symbol names registered for typ. func registeredSymbols(typ any) []string { librariesMu.Lock() defer librariesMu.Unlock() return libraries[typ] } // librarySymbol returns the address of the symbol with the given index in // lib, as resolved by Open. It panics if lib was not returned by Open. // // librarySymbol is called by code generated by cmd/cgo. // //go:linkname librarySymbol func librarySymbol(lib *Library, index int) unsafe.Pointer { if lib.handle == 0 { panic("cgo: use of Library not returned by cgo.Open") } if uint(index) >= uint(len(lib.syms)) { panic("cgo: internal error: bad symbol index") } return lib.syms[index] }