GlueGen v2.6.0-rc-20250706
GlueGen, Native Binding Generator for Java™ (public API).
com.jogamp.common.os.NativeLibrary Class Reference

Provides low-level, relatively platform-independent access to shared ("native") libraries. More...

Inheritance diagram for com.jogamp.common.os.NativeLibrary:
Collaboration diagram for com.jogamp.common.os.NativeLibrary:

Public Member Functions

final String toString ()
 
final void claimAllLinkPermission () throws SecurityException
 
final void releaseAllLinkPermission () throws SecurityException
 
final long dynamicLookupFunction (final String funcName) throws SecurityException
 Returns the function handle for function 'funcName'. More...
 
final boolean isFunctionAvailable (final String funcName) throws SecurityException
 Queries whether function 'funcName' is available. More...
 
final long dynamicLookupFunctionGlobal (final String funcName) throws SecurityException
 Looks up the given function name in all loaded libraries. More...
 
final long getLibraryHandle ()
 Retrieves the low-level library handle from this NativeLibrary object. More...
 
final boolean isOpen ()
 Returns true if library is loaded and open, otherwise false. More...
 
final String getLibraryPath ()
 Retrieves the path under which this library was opened. More...
 
final String getNativeLibraryPath ()
 Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS. More...
 
final void close () throws SecurityException
 Closes this native library. More...
 
void claimAllLinkPermission () throws SecurityException
 
void releaseAllLinkPermission () throws SecurityException
 
boolean isOpen ()
 Returns true if library is loaded and open, otherwise false. More...
 
long dynamicLookupFunction (String funcName) throws SecurityException
 Returns the function handle for function 'funcName'. More...
 
boolean isFunctionAvailable (String funcName) throws SecurityException
 Queries whether function 'funcName' is available. More...
 

Static Public Member Functions

static final String getSystemEnvLibraryPathVarname ()
 Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g. More...
 
static final List< String > getSystemEnvLibraryPaths ()
 Returns a list of system paths, from the getSystemEnvLibraryPathVarname() variable. More...
 
static final NativeLibrary open (final String libName, final boolean searchSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global) throws SecurityException
 Opens the given native library, assuming it has the same base name on all platforms. More...
 
static final NativeLibrary open (final String libName, final boolean searchSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global, final String symbolName) throws SecurityException
 Opens the given native library, assuming it has the same base name on all platforms. More...
 
static final NativeLibrary open (final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global, final String symbolName) throws SecurityException
 Opens the given native library, assuming it has the given base names (no "lib" prefix or ".dll/.so/.dylib" suffix) on the Windows, Unix and Mac OS X platforms, respectively, and in the context of the specified ClassLoader, which is used to help find the library in the case of e.g. More...
 
static final String isValidNativeLibraryName (final String libName, final boolean isLowerCaseAlready)
 Comparison of prefix and suffix of the given libName's basename is performed case insensitive
More...
 
static final List< String > enumerateLibraryPaths (final String windowsLibName, final String unixLibName, final String macOSXLibName, final ClassLoader loader)
 Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system not using the system path. More...
 
static final List< String > enumerateLibraryPaths (final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final ClassLoader loader)
 Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system using the system path. More...
 
static final String findLibrary (final String libName, final ClassLoader loader)
 

Additional Inherited Members

- Static Public Attributes inherited from com.jogamp.common.os.DynamicLookupHelper
static final boolean DEBUG = Debug.debug("NativeLibrary")
 
static final boolean DEBUG_LOOKUP = Debug.debug("NativeLibrary.Lookup")
 

Detailed Description

Provides low-level, relatively platform-independent access to shared ("native") libraries.

The core library routines System.load() and System.loadLibrary() in general provide suitable functionality for applications using native code, but are not flexible enough to support certain kinds of glue code generation and deployment strategies. This class supports direct linking of native libraries to other shared objects not necessarily installed on the system (in particular, via the use of dlopen(RTLD_GLOBAL) on Unix platforms) as well as manual lookup of function names to support e.g. GlueGen's ProcAddressTable glue code generation style without additional supporting code needed in the generated library.

Definition at line 68 of file NativeLibrary.java.

Member Function Documentation

◆ claimAllLinkPermission()

final void com.jogamp.common.os.NativeLibrary.claimAllLinkPermission ( ) throws SecurityException
Exceptions
SecurityExceptionif user is not granted access for the library set.

Implements com.jogamp.common.os.DynamicLookupHelper.

Definition at line 322 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ close()

final void com.jogamp.common.os.NativeLibrary.close ( ) throws SecurityException

Closes this native library.

Further lookup operations are not allowed after calling this method.

Exceptions
SecurityExceptionif user is not granted access for the named library.

Definition at line 406 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ dynamicLookupFunction()

final long com.jogamp.common.os.NativeLibrary.dynamicLookupFunction ( final String  funcName) throws SecurityException

Returns the function handle for function 'funcName'.

Exceptions
SecurityExceptionif user is not granted access for the library set.

Implements com.jogamp.common.os.DynamicLookupHelper.

Definition at line 331 of file NativeLibrary.java.

Here is the call graph for this function:

◆ dynamicLookupFunctionGlobal()

final long com.jogamp.common.os.NativeLibrary.dynamicLookupFunctionGlobal ( final String  funcName) throws SecurityException

Looks up the given function name in all loaded libraries.

Exceptions
SecurityExceptionif user is not granted access for the named library.

Definition at line 349 of file NativeLibrary.java.

Here is the call graph for this function:

◆ enumerateLibraryPaths() [1/2]

static final List< String > com.jogamp.common.os.NativeLibrary.enumerateLibraryPaths ( final String  windowsLibName,
final String  unixLibName,
final String  macOSXLibName,
final boolean  searchSystemPathFirst,
final ClassLoader  loader 
)
static

Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system using the system path.

Definition at line 471 of file NativeLibrary.java.

Here is the call graph for this function:

◆ enumerateLibraryPaths() [2/2]

static final List< String > com.jogamp.common.os.NativeLibrary.enumerateLibraryPaths ( final String  windowsLibName,
final String  unixLibName,
final String  macOSXLibName,
final ClassLoader  loader 
)
static

Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system not using the system path.

Definition at line 460 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ findLibrary()

static final String com.jogamp.common.os.NativeLibrary.findLibrary ( final String  libName,
final ClassLoader  loader 
)
static

Definition at line 783 of file NativeLibrary.java.

Here is the call graph for this function:

◆ getLibraryHandle()

final long com.jogamp.common.os.NativeLibrary.getLibraryHandle ( )

Retrieves the low-level library handle from this NativeLibrary object.

On the Windows platform this is an HMODULE, and on Unix and Mac OS X platforms the void* result of calling dlopen().

Definition at line 385 of file NativeLibrary.java.

◆ getLibraryPath()

final String com.jogamp.common.os.NativeLibrary.getLibraryPath ( )

Retrieves the path under which this library was opened.

Definition at line 393 of file NativeLibrary.java.

◆ getNativeLibraryPath()

final String com.jogamp.common.os.NativeLibrary.getNativeLibraryPath ( )

Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS.

Definition at line 398 of file NativeLibrary.java.

◆ getSystemEnvLibraryPaths()

static final List< String > com.jogamp.common.os.NativeLibrary.getSystemEnvLibraryPaths ( )
static

Returns a list of system paths, from the getSystemEnvLibraryPathVarname() variable.

Definition at line 153 of file NativeLibrary.java.

Here is the call graph for this function:

◆ getSystemEnvLibraryPathVarname()

static final String com.jogamp.common.os.NativeLibrary.getSystemEnvLibraryPathVarname ( )
static

Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g.

  • Windows: PATH
  • MacOS: DYLD_LIBRARY_PATH
  • Unix: LD_LIBRARY_PATH

Definition at line 148 of file NativeLibrary.java.

Here is the caller graph for this function:

◆ isFunctionAvailable()

final boolean com.jogamp.common.os.NativeLibrary.isFunctionAvailable ( final String  funcName) throws SecurityException

Queries whether function 'funcName' is available.

Exceptions
SecurityExceptionif user is not granted access for the library set.

Implements com.jogamp.common.os.DynamicLookupHelper.

Definition at line 339 of file NativeLibrary.java.

Here is the call graph for this function:

◆ isOpen()

final boolean com.jogamp.common.os.NativeLibrary.isOpen ( )

Returns true if library is loaded and open, otherwise false.

Implements com.jogamp.common.os.DynamicLookupHelper.

Definition at line 390 of file NativeLibrary.java.

◆ isValidNativeLibraryName()

static final String com.jogamp.common.os.NativeLibrary.isValidNativeLibraryName ( final String  libName,
final boolean  isLowerCaseAlready 
)
static

Comparison of prefix and suffix of the given libName's basename is performed case insensitive

Parameters
libNamethe full path library name with prefix and suffix
isLowerCaseAlreadyindicates if libName is already lower-case
Returns
basename of libName w/o path, ie. /usr/lib/libDrinkBeer.so -> DrinkBeer on Unix systems, but null on Windows.

Definition at line 431 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ open() [1/3]

static final NativeLibrary com.jogamp.common.os.NativeLibrary.open ( final String  libName,
final boolean  searchSystemPath,
final boolean  searchSystemPathFirst,
final ClassLoader  loader,
final boolean  global 
) throws SecurityException
static

Opens the given native library, assuming it has the same base name on all platforms.

The searchSystemPath argument changes the behavior to either use the default system path or not at all.

Assuming searchSystemPath is true, the searchSystemPathFirst argument changes the behavior to first search the default system path rather than searching it last.

Parameters
libNamelibrary name, with or without prefix and suffix
searchSystemPathif true library shall be searched in the system path (default), otherwise false.
searchSystemPathFirstif true system path shall be searched first (default), rather than searching it last. if searchSystemPath is false this argument is ignored.
loaderClassLoader to locate the library
globalif true allows system wide access of the loaded library, otherwise access is restricted to the process.
Returns
NativeLibrary instance or null if library could not be loaded.
Exceptions
SecurityExceptionif user is not granted access for the named library.
Since
2.4.0

Definition at line 192 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ open() [2/3]

static final NativeLibrary com.jogamp.common.os.NativeLibrary.open ( final String  libName,
final boolean  searchSystemPath,
final boolean  searchSystemPathFirst,
final ClassLoader  loader,
final boolean  global,
final String  symbolName 
) throws SecurityException
static

Opens the given native library, assuming it has the same base name on all platforms.

The searchSystemPath argument changes the behavior to either use the default system path or not at all.

Assuming searchSystemPath is true, the searchSystemPathFirst argument changes the behavior to first search the default system path rather than searching it last.

Parameters
libNamelibrary name, with or without prefix and suffix
searchSystemPathif true library shall be searched in the system path (default), otherwise false.
searchSystemPathFirstif true system path shall be searched first (default), rather than searching it last. if searchSystemPath is false this argument is ignored.
loaderClassLoader to locate the library
globalif true allows system wide access of the loaded library, otherwise access is restricted to the process.
symbolNameoptional symbol name for an OS which requires the symbol's address to retrieve the path of the containing library
Returns
NativeLibrary instance or null if library could not be loaded.
Exceptions
SecurityExceptionif user is not granted access for the named library.
Since
2.4.0

Definition at line 221 of file NativeLibrary.java.

Here is the call graph for this function:

◆ open() [3/3]

static final NativeLibrary com.jogamp.common.os.NativeLibrary.open ( final String  windowsLibName,
final String  unixLibName,
final String  macOSXLibName,
final boolean  searchSystemPath,
final boolean  searchSystemPathFirst,
final ClassLoader  loader,
final boolean  global,
final String  symbolName 
) throws SecurityException
static

Opens the given native library, assuming it has the given base names (no "lib" prefix or ".dll/.so/.dylib" suffix) on the Windows, Unix and Mac OS X platforms, respectively, and in the context of the specified ClassLoader, which is used to help find the library in the case of e.g.

Java Web Start.

The searchSystemPath argument changes the behavior to either use the default system path or not at all.

Assuming searchSystemPath is true, the searchSystemPathFirst argument changes the behavior to first search the default system path rather than searching it last.

Note that we do not currently handle DSO versioning on Unix. Experience with JOAL and OpenAL has shown that it is extremely problematic to rely on a specific .so version (for one thing, ClassLoader.findLibrary on Unix doesn't work with files not ending in .so, for example .so.0), and in general if this dynamic loading facility is used correctly the version number will be irrelevant.

Parameters
windowsLibNamewindows library name, with or without prefix and suffix
unixLibNameunix library name, with or without prefix and suffix
macOSXLibNamemac-osx library name, with or without prefix and suffix
searchSystemPathif true library shall be searched in the system path (default), otherwise false.
searchSystemPathFirstif true system path shall be searched first (default), rather than searching it last. if searchSystemPath is false this argument is ignored.
loaderClassLoader to locate the library
globalif true allows system wide access of the loaded library, otherwise access is restricted to the process.
symbolNameoptional symbol name for an OS which requires the symbol's address to retrieve the path of the containing library
Returns
NativeLibrary instance or null if library could not be loaded.
Exceptions
SecurityExceptionif user is not granted access for the named library.

Definition at line 261 of file NativeLibrary.java.

Here is the call graph for this function:

◆ releaseAllLinkPermission()

final void com.jogamp.common.os.NativeLibrary.releaseAllLinkPermission ( ) throws SecurityException
Exceptions
SecurityExceptionif user is not granted access for the library set.

Implements com.jogamp.common.os.DynamicLookupHelper.

Definition at line 326 of file NativeLibrary.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString()

final String com.jogamp.common.os.NativeLibrary.toString ( )

Definition at line 136 of file NativeLibrary.java.


The documentation for this class was generated from the following file: