Java Native Access 5.14.0 · com.sun.jna.NativeLibrary

Provides management of native library resources. One instance of this class corresponds to a single loaded native library. May also be used to map to the current process (see NativeLibrary#getProcess()).

Library Search Paths A search for a given library will scan the following locations:

jna.library.path User-customizable path
jna.platform.library.path Platform-specific paths
On OSX, ~/Library/Frameworks, /Library/Frameworks, and /System/Library/Frameworks will be searched for a framework with a name corresponding to that requested. Absolute paths to frameworks are also accepted, either ending at the framework name (sans ".framework") or the full path to the framework shared library (e.g. CoreServices.framework/CoreServices).
Context class loader classpath. Deployed native libraries may be installed on the classpath under ${os-prefix}/LIBRARY_FILENAME, where ${os-prefix} is the OS/Arch prefix returned by Platform#getNativeLibraryResourcePrefix(). If bundled in a jar file, the resource will be extracted to jna.tmpdir for loading, and later removed (but only if jna.nounpack is false or not set).

You may set the system property jna.debug_load=true to make JNA print the steps of its library search to the console.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	NativeLibrary.NativeLibraryDisposer

Field Summary

Modifier and Type	Field and Description
private static Method	addSuppressedMethod
private final int	callFlags
private final Cleaner.Cleanable	cleanable
private static final Level	DEBUG_LOAD_LEVEL
private static final int	DEFAULT_OPEN_OPTIONS
private final String	encoding
private final Map<String, Function>	functions
private volatile long	handle
private static final Map<String, Reference<NativeLibrary>>	libraries
private final String	libraryName
private final String	libraryPath
private static final LinkedHashSet<String>	librarySearchPath
private static final Logger	LOG
private static final SymbolProvider	NATIVE_SYMBOL_PROVIDER
private final Map<String, ?>	options
private static final Map<String, List<String>>	searchPaths
private final SymbolProvider	symbolProvider

Constructor Summary

Access	Constructor and Description
private	NativeLibrary(String libraryName, String libraryPath, long handle, Map<String, ?> options)

Method Summary

Modifier and Type	Method and Description
public static final void	addSearchPath(String The name of the library to use the path for libraryName, String The path to use when trying to load the library path) Add a path to search for the specified library, ahead of any system paths.
private static void	addSuppressedReflected(Throwable target, Throwable suppressed)
public void	close() Implements java.io.Closeable.close. Close the native library we're mapped to.
public void	dispose() Deprecated
pack-priv static void	disposeAll() Close all open native libraries.
private static String	findLibraryPath(String libName, Collection<String> searchPath) Use standard library search paths to find the library.
private static String	functionKey(String name, int flags, String encoding)
public File	getFile() Returns the file on disk corresponding to this NativeLibrary instance.
public Function	getFunction(String Name of the native function to be linked with functionName) Create a new `Function` that is linked with a native function that follows the NativeLibrary's calling convention.
pack-priv Function	getFunction(String Name of the native function to be linked with. Uses a function mapper option if one was provided to transform the name. name, Method Method to which the native function is to be mapped method) Create a new `Function` that is linked with a native function that follows the NativeLibrary's calling convention.
public Function	getFunction(String Name of the native function to be linked with functionName, int Flags affecting the function invocation callFlags) Create a new `Function` that is linked with a native function that follows a given calling flags.
public Function	getFunction(String Name of the native function to be linked with functionName, int Flags affecting the function invocation callFlags, String Encoding to use to convert between Java and native strings. encoding) Create a new `Function` that is linked with a native function that follows a given calling flags.
public Pointer	Returns: Pointer representing the global variable address getGlobalVariableAddress(String symbolName) Look up the given global variable within this library.
public static final NativeLibrary	getInstance(String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6"). libraryName) Returns an instance of NativeLibrary for the specified name.
public static final NativeLibrary	getInstance(String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6"). libraryName, ClassLoader The class loader to use to load the native library. This only affects library loading when the native library is included somewhere in the classpath, either bundled in a jar file or as a plain file within the classpath. classLoader) Returns an instance of NativeLibrary for the specified name.
public static final NativeLibrary	getInstance(String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6" or "QuickTime.framework/Versions/Current/QuickTime"), or the full (absolute) path to the library (e.g. "/lib/libc.so.6"). libraryName, Map<String, ?> Native library options for the given library (see `Library`). libraryOptions) Returns an instance of NativeLibrary for the specified name.
private String	getLibraryName(String libraryName)
private static ArrayList<String>	getLinuxLdPaths() Get the library paths from ldconfig cache.
private static String	getMultiArchPath()
public String	getName() Returns the simple name of this library.
public Map<String, ?>	Returns: this native library instance's options. getOptions()
public static final synchronized NativeLibrary	getProcess() Returns an instance of NativeLibrary which refers to the current process.
public static final synchronized NativeLibrary	getProcess(Map<String, ?> options) Returns an instance of NativeLibrary which refers to the current process.
pack-priv long	getSymbolAddress(String name) Used by the Function class to locate a symbol
private static List<String>	initPaths(String key)
private static boolean	isVersionedName(String name)
private static NativeLibrary	loadLibrary(final String libraryName, final Map<String, ?> options)
pack-priv static String	mapSharedLibraryName(String base (undecorated) name of library libName) Similar to `System#mapLibraryName`, except that it maps to standard shared library formats rather than specifically JNI formats.
pack-priv static String[]	matchFramework(String libraryName) Look for a matching framework (OSX)
pack-priv static String	matchLibrary(final String libName, Collection<String> searchPath) matchLibrary() is very Linux specific.
private static int	openFlags(Map<String, ?> options)
pack-priv static double	parseVersion(String ver)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

addSuppressedMethod	back to summary
private static Method addSuppressedMethod

callFlags	back to summary
private final int callFlags

cleanable	back to summary
private final Cleaner.Cleanable cleanable

DEBUG_LOAD_LEVEL	back to summary
private static final Level DEBUG_LOAD_LEVEL

DEFAULT_OPEN_OPTIONS	back to summary
private static final int DEFAULT_OPEN_OPTIONS

encoding	back to summary
private final String encoding

functions	back to summary
private final Map<String, Function> functions

handle	back to summary
private volatile long handle

libraries	back to summary
private static final Map<String, Reference<NativeLibrary>> libraries

libraryName	back to summary
private final String libraryName

libraryPath	back to summary
private final String libraryPath

librarySearchPath	back to summary
private static final LinkedHashSet<String> librarySearchPath

LOG	back to summary
private static final Logger LOG

NATIVE_SYMBOL_PROVIDER	back to summary
private static final SymbolProvider NATIVE_SYMBOL_PROVIDER

options	back to summary
private final Map<String, ?> options

searchPaths	back to summary
private static final Map<String, List<String>> searchPaths

symbolProvider	back to summary
private final SymbolProvider symbolProvider

Constructor Detail

NativeLibrary	back to summary
private NativeLibrary(String libraryName, String libraryPath, long handle, Map<String, ?> options) Annotations @SuppressWarnings:LeakingThisInConstructor

Method Detail

addSearchPath back to summary

addSearchPath	back to summary
public static final void addSearchPath(String libraryName, String path) Add a path to search for the specified library, ahead of any system paths. This is similar to setting `jna.library.path`, but only extends the search path for a single library. Parameters libraryName:String The name of the library to use the path for path:String The path to use when trying to load the library

public static final void addSearchPath(String libraryName, String path)

Add a path to search for the specified library, ahead of any system paths. This is similar to setting jna.library.path, but only extends the search path for a single library.

Parameters

libraryName:String: The name of the library to use the path for
path:String: The path to use when trying to load the library

addSuppressedReflected	back to summary
private static void addSuppressedReflected(Throwable target, Throwable suppressed)

close	back to summary
public void close() Implements java.io.Closeable.close. Close the native library we're mapped to.

back to summary

public void close()

Implements java.io.Closeable.close.

Close the native library we're mapped to.

dispose	back to summary
public void dispose() Deprecated Annotations @Deprecated

disposeAll	back to summary
pack-priv static void disposeAll() Close all open native libraries.

findLibraryPath	back to summary
private static String findLibraryPath(String libName, Collection<String> searchPath) Use standard library search paths to find the library.

functionKey	back to summary
private static String functionKey(String name, int flags, String encoding)

getFile	back to summary
public File getFile() Returns the file on disk corresponding to this NativeLibrary instance. If this NativeLibrary represents the current process, this function will return null.

getFunction back to summary

getFunction	back to summary
public Function getFunction(String functionName) Create a new `Function` that is linked with a native function that follows the NativeLibrary's calling convention. The allocated instance represents a pointer to the named native function from the library. Parameters functionName:String Name of the native function to be linked with Exceptions UnsatisfiedLinkError: if the function is not found

public Function getFunction(String functionName)

Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.

The allocated instance represents a pointer to the named native function from the library.

Parameters

functionName:String: Name of the native function to be linked with

Exceptions

UnsatisfiedLinkError:: if the function is not found

getFunction back to summary

getFunction	back to summary
pack-priv Function getFunction(String name, Method method) Create a new `Function` that is linked with a native function that follows the NativeLibrary's calling convention. The allocated instance represents a pointer to the named native function from the library. Parameters name:String Name of the native function to be linked with. Uses a function mapper option if one was provided to transform the name. method:Method Method to which the native function is to be mapped Exceptions UnsatisfiedLinkError: if the function is not found

pack-priv Function getFunction(String name, Method method)

Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.

The allocated instance represents a pointer to the named native function from the library.

Parameters

name:String: Name of the native function to be linked with. Uses a function mapper option if one was provided to transform the name.
method:Method: Method to which the native function is to be mapped

Exceptions

UnsatisfiedLinkError:: if the function is not found

getFunction back to summary

getFunction	back to summary
public Function getFunction(String functionName, int callFlags) Create a new `Function` that is linked with a native function that follows a given calling flags. Parameters functionName:String Name of the native function to be linked with callFlags:int Flags affecting the function invocation Exceptions UnsatisfiedLinkError: if the function is not found

public Function getFunction(String functionName, int callFlags)

Create a new Function that is linked with a native function that follows a given calling flags.

Parameters

functionName:String: Name of the native function to be linked with
callFlags:int: Flags affecting the function invocation

Exceptions

UnsatisfiedLinkError:: if the function is not found

getFunction back to summary

getFunction	back to summary
public Function getFunction(String functionName, int callFlags, String encoding) Create a new `Function` that is linked with a native function that follows a given calling flags. Parameters functionName:String Name of the native function to be linked with callFlags:int Flags affecting the function invocation encoding:String Encoding to use to convert between Java and native strings. Exceptions UnsatisfiedLinkError: if the function is not found

public Function getFunction(String functionName, int callFlags, String encoding)

Create a new Function that is linked with a native function that follows a given calling flags.

Parameters

functionName:String: Name of the native function to be linked with
callFlags:int: Flags affecting the function invocation
encoding:String: Encoding to use to convert between Java and native strings.

Exceptions

UnsatisfiedLinkError:: if the function is not found

getGlobalVariableAddress	back to summary
public Pointer getGlobalVariableAddress(String symbolName) Look up the given global variable within this library. Returns:Pointer Pointer representing the global variable address Exceptions UnsatisfiedLinkError: if the symbol is not found

getGlobalVariableAddress

back to summary

public Pointer getGlobalVariableAddress(String symbolName)

Look up the given global variable within this library.

Returns:Pointer

Pointer representing the global variable address

Exceptions

UnsatisfiedLinkError:: if the symbol is not found

getInstance	back to summary
public static final NativeLibrary getInstance(String libraryName) Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned. More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path. Parameters libraryName:String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6").

getInstance

back to summary

public static final NativeLibrary getInstance(String libraryName)

Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned.

More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.

Parameters

libraryName:String: The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6").

getInstance	back to summary
public static final NativeLibrary getInstance(String libraryName, ClassLoader classLoader) Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned. More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path. Parameters libraryName:String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6"). classLoader:ClassLoader The class loader to use to load the native library. This only affects library loading when the native library is included somewhere in the classpath, either bundled in a jar file or as a plain file within the classpath.

getInstance

back to summary

public static final NativeLibrary getInstance(String libraryName, ClassLoader classLoader)

Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned.

More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.

Parameters

libraryName:String: The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6"), or the full path to the library (e.g. "/lib/libc.so.6").
classLoader:ClassLoader: The class loader to use to load the native library. This only affects library loading when the native library is included somewhere in the classpath, either bundled in a jar file or as a plain file within the classpath.

getInstance back to summary

getInstance	back to summary
public static final NativeLibrary getInstance(String libraryName, Map<String, ?> libraryOptions) Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned. More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path. Parameters libraryName:String The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6" or "QuickTime.framework/Versions/Current/QuickTime"), or the full (absolute) path to the library (e.g. "/lib/libc.so.6"). libraryOptions:Map<String, ?> Native library options for the given library (see `Library`).

public static final NativeLibrary getInstance(String libraryName, Map<String, ?> libraryOptions)

Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned.

More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.

Parameters

libraryName:String: The library name to load. This can be short form (e.g. "c"), an explicit version (e.g. "libc.so.6" or "QuickTime.framework/Versions/Current/QuickTime"), or the full (absolute) path to the library (e.g. "/lib/libc.so.6").
libraryOptions:Map<String, ?>: Native library options for the given library (see Library).

getLibraryName	back to summary
private String getLibraryName(String libraryName)

getLinuxLdPaths	back to summary
private static ArrayList<String> getLinuxLdPaths() Get the library paths from ldconfig cache. Tested against ldconfig 2.13.

getMultiArchPath	back to summary
private static String getMultiArchPath()

getName	back to summary
public String getName() Returns the simple name of this library.

getOptions	back to summary
public Map<String, ?> getOptions() Returns:Map<String, ?> this native library instance's options.

getProcess	back to summary
public static final synchronized NativeLibrary getProcess() Returns an instance of NativeLibrary which refers to the current process. This is useful for accessing functions which were already mapped by some other mechanism, without having to reference or even know the exact name of the native library.

getProcess	back to summary
public static final synchronized NativeLibrary getProcess(Map<String, ?> options) Returns an instance of NativeLibrary which refers to the current process. This is useful for accessing functions which were already mapped by some other mechanism, without having to reference or even know the exact name of the native library.

getSymbolAddress	back to summary
pack-priv long getSymbolAddress(String name) Used by the Function class to locate a symbol Exceptions UnsatisfiedLinkError: if the symbol can't be found

getSymbolAddress

back to summary

pack-priv long getSymbolAddress(String name)

Used by the Function class to locate a symbol

Exceptions

UnsatisfiedLinkError:: if the symbol can't be found

initPaths	back to summary
private static List<String> initPaths(String key)

isVersionedName	back to summary
private static boolean isVersionedName(String name)

loadLibrary	back to summary
private static NativeLibrary loadLibrary(final String libraryName, final Map<String, ?> options)

mapSharedLibraryName back to summary

mapSharedLibraryName	back to summary
pack-priv static String mapSharedLibraryName(String libName) Similar to `System#mapLibraryName`, except that it maps to standard shared library formats rather than specifically JNI formats. Parameters libName:String base (undecorated) name of library

pack-priv static String mapSharedLibraryName(String libName)

Similar to System#mapLibraryName, except that it maps to standard shared library formats rather than specifically JNI formats.

Parameters

libName:String: base (undecorated) name of library

matchFramework	back to summary
pack-priv static String[] matchFramework(String libraryName) Look for a matching framework (OSX)

matchLibrary	back to summary
pack-priv static String matchLibrary(final String libName, Collection<String> searchPath) matchLibrary() is very Linux specific. It is here to deal with the case where /usr/lib/libc.so does not exist, or it is not a valid symlink to a versioned file (e.g. /lib/libc.so.6).

openFlags	back to summary
private static int openFlags(Map<String, ?> options)

parseVersion	back to summary
pack-priv static double parseVersion(String ver)

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations

@Override

public Class NativeLibrary

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class NativeLibrary.NativeLibraryDisposer

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail