GlueGen v2.6.0-rc-20250712
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:

Classes

class  LibPath
 Native Library Path Specification. More...
 

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 LibPath getLibPath ()
 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 String getSystemEnvLibraryPaths ()
 Returns a system paths separated with File#pathSeparator, from the getSystemEnvLibraryPathVarname() variable. More...
 
static final String getJogAmpPrimaryLibraryPaths ()
 Returns JogAmp's primary library path jogamp.primary.library.path separated with File#pathSeparator. More...
 
static final NativeLibrary open (final String libName, final boolean searchOSSystemPath, 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 searchOSSystemPath, 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 searchOSSystemPath, 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< LibPathenumerateLibraryPaths (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 OS system path. More...
 
static final List< LibPathenumerateLibraryPaths (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 OS 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.

System Search Resolution

System search's behavior depends on searchOSSystemPath and searchSystemPathFirst.

OS System Search

  • System search path direct lookup (absolute path)
    • Windows: PATH
    • MacOS: DYLD_LIBRARY_PATH
    • Unix: LD_LIBRARY_PATH
  • System search path implicit lookup (relative path)
  • OSX System search path direct lookup (absolute path)
    • /Library/Frameworks/
    • /System/Library/Frameworks/

System Search

  • if searchSystemPathFirst
    • If searchOSSystemPath
      • Perform described OS System Search above
    • Java's ClassLoader findLibrary mechanism
    • Java's Java system library path property
      • sun.boot.library.path
  • if !searchSystemPathFirst
    • Java's Java system library path property
      • sun.boot.library.path
    • Java's ClassLoader findLibrary mechanism
    • If searchOSSystemPath
      • Perform described OS System Search above

Native Library Search Resolution

  • Absolute path only, if given
  • JogAmp's optional primary search path from Java property jogamp.primary.library.path
    • path is separated via File.pathseparator
  • if searchSystemPathFirst
    • Perform described System Search Resolution above
  • Java's Java user library path property
    • java.library.path
  • Java's Java user current working directory
    • user: user.dir
    • user+fat: user.dir + File.separator + natives + File.separator + PlatformPropsImpl.os_and_arch
  • if !searchSystemPathFirst
    • Perform described System Search Resolution above

Definition at line 112 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 480 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 569 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 489 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 507 of file NativeLibrary.java.

Here is the call graph for this function:

◆ enumerateLibraryPaths() [1/2]

static final List< LibPath > 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 OS system path.

Definition at line 634 of file NativeLibrary.java.

Here is the call graph for this function:

◆ enumerateLibraryPaths() [2/2]

static final List< LibPath > 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 OS system path.

Definition at line 623 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 930 of file NativeLibrary.java.

Here is the call graph for this function:

◆ getJogAmpPrimaryLibraryPaths()

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

Returns JogAmp's primary library path jogamp.primary.library.path separated with File#pathSeparator.

Definition at line 283 of file NativeLibrary.java.

Here is the call graph for this function:

◆ getLibPath()

final LibPath com.jogamp.common.os.NativeLibrary.getLibPath ( )

Retrieves the path under which this library was opened.

Definition at line 556 of file NativeLibrary.java.

◆ 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 543 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 551 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 561 of file NativeLibrary.java.

◆ getSystemEnvLibraryPaths()

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

Returns a system paths separated with File#pathSeparator, from the getSystemEnvLibraryPathVarname() variable.

Definition at line 273 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 268 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 497 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 548 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 594 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  searchOSSystemPath,
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 searchOSSystemPath argument changes the behavior to either use the default system path or not at all.

Assuming searchOSSystemPath 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
searchOSSystemPathif 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 searchOSSystemPath is true this includes the order of the OS system path as well.
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 350 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  searchOSSystemPath,
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 searchOSSystemPath argument changes the behavior to either use the default system path or not at all.

Assuming searchOSSystemPath 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
searchOSSystemPathif true library shall be searched in the OS system path (default), otherwise false.
searchSystemPathFirstif true system path shall be searched first (default), rather than searching it last. if searchOSSystemPath is true this includes the order of the OS system path as well.
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 379 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  searchOSSystemPath,
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 searchOSSystemPath argument changes the behavior to either use the default OS system path or not at all.

Assuming searchOSSystemPath 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
searchOSSystemPathif true library shall be searched in the OS system path (default), otherwise false.
searchSystemPathFirstif true system path shall be searched first (default), rather than searching it last. if searchOSSystemPath is true this includes the order of the OS system path as well.
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 419 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 484 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 256 of file NativeLibrary.java.


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