<commit_before><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<!-- 
  Copyright 2007 <NAME>
-->
</head>

<HR>
<CENTER>
<H1>Java Native Access</H1>
</CENTER>
<body bgcolor="white">
This document is the API specification for the
<a href=http://jna.dev.java.net>JNA</a>
library for simplified native library access for Java.
<p>
<a href=#navbar_top>Top</a>&nbsp;
<a href=http://jna.dev.java.net>JNA Home</a>&nbsp;
<a href=index.html target=_top>API w/FRAMES</a>&nbsp;
<p>

<a name="overview"></a>
<h1>Java Native Access (JNA)</h1>
JNA provides simplified access to native library methods without requiring any
additional JNI or native code.
<p>

<a name="toc"></a>
<h2>Table of Contents</h2>
<ul>
<li><a href="#library-mapping">Library Mapping</a>
<li><a href="#function-mapping">Function Mapping</a>
<li><a href="#marshalling">Type Mapping</a>
  <ul>
  <li><a href="#marshalling">Primitive Types</a>
  <li><a href="#pointers">Pointers</a>
  <li><a href="#strings">Strings</a>
  <li><a href="#wide-strings">Wide (UNICODE) Strings</a>
  <li><a href="#arrays">Primitive Arrays</a>
  <li><a href="#buffers">Buffers/Memory Blocks</a>
  <li><a href="#callbacks">Callbacks/Function Pointers</a>
  <li><a href="#varargs">Variable Argument Lists (Varargs)</a>
  <li><a href="#structures">Structures</a>
  <li><a href="#unions">Unions</a>
  <li><a href="#java-objects">Java Objects</a>
  </ul>
<li><a href="#invocation-mapping">Invocation Mapping</a>
<li><a href="#global-data">Library Global Data</a>
<li><a href="#crash-protection">VM Crash Protection</a>
<li><a href="#performance">Performance</a>
</ul>

<p>
<a href=#navbar_top>Top</a>
<a name="library-mapping"></a>
<h2>Library Mapping</h2>
When you've determined which shared library holds the methods to which you
need access, create an interface class corresponding to that library.  For
example, a mapping for the C library itself would look like this:<br>
<blockquote><code><pre>
public interface CLibrary extends Library {
    CLibrary INSTANCE = (CLibrary)Native.loadLibrary("c", CLibrary.class);
}
</pre></code></blockquote>
The <code>String</code> passed to the <code>Native.loadLibrary</code> method
is the undecorated name of the shared library file.  Here are some examples of
library name mappings.<p>  
<style type="text/css">
table.styled { border-collapse:collapse; background-color:#EAEAEA; }
td { padding-left: 10px; padding-right: 10px; }
blockquote { background-color:#EAEAEA; }
</style>
<table border=1 borderColor=white class=styled>
<tr><td><b>OS</b></td><td><b>Library Name</b></td><td><b>String</b></td></tr>
<tr><td>Windows</td><td>user32.dll</td><td>user32</td></tr>
<tr><td>Linux</td><td>libX11.so</td><td>X11</td></tr>
<tr><td>Mac OS X</td><td>libm.dylib</td><td>m</td></tr>
<tr><td>Mac OS X Framework</td><td>/System/Library/Frameworks/Carbon.framework/Carbon</td><td>Carbon</td></tr>
</table>
<p>
Any given native library with a unique filesystem path is represented by a single instance of {@link com.sun.jna.NativeLibrary} and obtained via {@link com.sun.jna.NativeLibrary#getInstance(String)}.  The native library will be unloaded when no longer referenced by any Java code.
<p>
The search path for loaded native libraries may be modified by setting <code>jna.library.path</code>.  See {@link com.sun.jna.NativeLibrary} for details.
<p>
<a href="#toc">Table of Contents</a>
<a name="function-mapping"></a>
<h2>Function Mapping</h2>
Function names are mapped directly from their Java interface name to the
symbol exported by the native library.  For instance, the function to convert
an ASCII string into an integer would look like this:<br>
<blockquote><code><pre>
public interface CLibrary extends Library {
    int atol(String s);
}
</pre></code></blockquote>
If you prefer to rename the Java methods to conform to Java coding conventions, then you can provide an entry ({@link com.sun.jna.Library#OPTION_FUNCTION_MAPPER}/{@link com.sun.jna.FunctionMapper}) in the options {@link java.util.Map} passed to {@link com.sun.jna.Native#loadLibrary(String,Class,java.util.Map) Native.loadLibrary()} which maps the Java names to the native names.  While this keeps your Java code a little cleaner, the additional mapping of names may make it a little less obvious the native functions being called.<p>
An instance of the {@link com.sun.jna.Function} class is obtained through the {@link com.sun.jna.NativeLibrary} instance corresponding to the containing native library.  This {@link com.sun.jna.Function} instance handles argument marshalling and delegation to the native function. 

<!-- TODO: when to use primitive array vs NIO Buffer vs Memory -->

<p>
<a href="#toc">Table of Contents</a>
<a name="marshalling"></a>
<h2>Marshalling/Unmarshalling (Java/Native Type Conversions)</h2>
Java types must be chosen to match native types of the same size.  Following are the types supported by the JNA library.<p>
<center>
<table border=1 borderColor=white class=styled width="100%">
<tr><td><b>Java Type</b></td><td><b>C Type</b></td><td><b>Native Representation</b></td></tr>
<tr><td>boolean</td><td>int</td><td>32-bit integer (customizable)</td>
<tr><td>byte</td><td>char</td><td>8-bit integer</td>
<tr><td>char</td><td>wchar_t</td><td>platform-dependent</td>
<tr><td>short</td><td>short</td><td>16-bit integer</td>
<tr><td>int</td><td>int</td><td>32-bit integer</td>
<tr><td>long</td><td>long long, __int64</td><td>64-bit integer</td>
<tr><td>float</td><td>float</td><td>32-bit floating point</td>
<tr><td>double</td><td>double</td><td>64-bit floating point</td>
<tr><td>{@link java.nio.Buffer}<br>
{@link com.sun.jna.Pointer}<td>pointer</td><td>platform-dependent (32- or 64-bit pointer to memory)</td>
<tr><td>&lt;T&gt;[] (array of primitive type)</td><td>pointer<br>array</td><td>32- or 64-bit pointer to memory (argument/return)<br>contiguous memory (struct member)</td>
<tr><td colspan=3>In addition to the above types, which are supported at the native layer, the JNA Java library automatically handles the following types.  All but <code>NativeMapped</code> and <code>NativeLong</code> are converted to {@link com.sun.jna.Pointer} before being passed to the native layer.</td></tr>
<tr><td>{@link java.lang.String}</td><td>char*</td><td>NUL-terminated array (native encoding or <code>jna.encoding</code>)</td>
<tr><td>{@link com.sun.jna.WString}</td><td>wchar_t*</td><td>NUL-terminated array (unicode)</td>
<tr><td>{@link java.lang.String String[]}</td><td>char**</td><td>NULL-terminated array of C strings</td>
<tr><td>{@link com.sun.jna.WString WString[]}</td><td>wchar_t**</td><td>NULL-terminated array of wide C strings</td>
<tr><td>{@link com.sun.jna.Structure}</td><td>struct*<br>struct</td><td>pointer to struct (argument or return) ({@link com.sun.jna.Structure.ByReference or explicitly})<br>struct by value (member of struct) ({@link com.sun.jna.Structure.ByValue or explicitly})</td>
<tr><td>{@link com.sun.jna.Union}</td><td>union</td><td>same as <code>Structure</code></td>
<tr><td>{@link com.sun.jna.Structure Structure[]}</td><td>struct[]</td><td>array of structs, contiguous in memory</td>
<tr><td>{@link com.sun.jna.Callback}</td><td>&lt;T&gt; (*fp)()</td><td>function pointer (Java or native)</td>
<tr><td>{@link com.sun.jna.NativeMapped}</td><td>varies</td><td>depends on definition</td>
<tr><td>{@link com.sun.jna.NativeLong}</td><td>long</td><td>platform-dependent (32- or 64-bit integer)</td>
<tr><td>{@link com.sun.jna.PointerType}</td><td>pointer</td><td>same as <code>Pointer</code></td>
</table>
</center>
<p>
<b>NOTES</b>
<ul>
<li>Unsigned values may be passed by assigning the corresponding
  two's-complement representation to the signed type of the same size.  
<li>Java arrays of primitive type may be wrapped by {@link java.nio.Buffer} in order to access a subset of the array (changing the effective size and/or offest).
<li>Primitive arrays and structures as members of a structure are overlaid on the parent structure memory.  <commit_msg>note Memory vs primitive array usage<commit_after><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<!-- 
  Copyright 2007 <NAME>
-->
</head>

<HR>
<CENTER>
<H1>Java Native Access</H1>
</CENTER>
<body bgcolor="white">
This document is the API specification for the
<a href=http://jna.dev.java.net>JNA</a>
library for simplified native library access for Java.
<p>
<a href=#navbar_top>Top</a>&nbsp;
<a href=http://jna.dev.java.net>JNA Home</a>&nbsp;
<a href=index.html target=_top>API w/FRAMES</a>&nbsp;
<p>

<a name="overview"></a>
<h1>Java Native Access (JNA)</h1>
JNA provides simplified access to native library methods without requiring any
additional JNI or native code.
<p>

<a name="toc"></a>
<h2>Table of Contents</h2>
<ul>
<li><a href="#library-mapping">Library Mapping</a>
<li><a href="#function-mapping">Function Mapping</a>
<li><a href="#marshalling">Type Mapping</a>
  <ul>
  <li><a href="#marshalling">Primitive Types</a>
  <li><a href="#pointers">Pointers</a>
  <li><a href="#strings">Strings</a>
  <li><a href="#wide-strings">Wide (UNICODE) Strings</a>
  <li><a href="#arrays">Primitive Arrays</a>
  <li><a href="#buffers">Buffers/Memory Blocks</a>
  <li><a href="#callbacks">Callbacks/Function Pointers</a>
  <li><a href="#varargs">Variable Argument Lists (Varargs)</a>
  <li><a href="#structures">Structures</a>
  <li><a href="#unions">Unions</a>
  <li><a href="#java-objects">Java Objects</a>
  </ul>
<li><a href="#invocation-mapping">Invocation Mapping</a>
<li><a href="#global-data">Library Global Data</a>
<li><a href="#crash-protection">VM Crash Protection</a>
<li><a href="#performance">Performance</a>
</ul>

<p>
<a href=#navbar_top>Top</a>
<a name="library-mapping"></a>
<h2>Library Mapping</h2>
When you've determined which shared library holds the methods to which you
need access, create an interface class corresponding to that library.  For
example, a mapping for the C library itself would look like this:<br>
<blockquote><code><pre>
public interface CLibrary extends Library {
    CLibrary INSTANCE = (CLibrary)Native.loadLibrary("c", CLibrary.class);
}
</pre></code></blockquote>
The <code>String</code> passed to the <code>Native.loadLibrary</code> method
is the undecorated name of the shared library file.  Here are some examples of
library name mappings.<p>  
<style type="text/css">
table.styled { border-collapse:collapse; background-color:#EAEAEA; }
td { padding-left: 10px; padding-right: 10px; }
blockquote { background-color:#EAEAEA; }
</style>
<table border=1 borderColor=white class=styled>
<tr><td><b>OS</b></td><td><b>Library Name</b></td><td><b>String</b></td></tr>
<tr><td>Windows</td><td>user32.dll</td><td>user32</td></tr>
<tr><td>Linux</td><td>libX11.so</td><td>X11</td></tr>
<tr><td>Mac OS X</td><td>libm.dylib</td><td>m</td></tr>
<tr><td>Mac OS X Framework</td><td>/System/Library/Frameworks/Carbon.framework/Carbon</td><td>Carbon</td></tr>
</table>
<p>
Any given native library with a unique filesystem path is represented by a single instance of {@link com.sun.jna.NativeLibrary} and obtained via {@link com.sun.jna.NativeLibrary#getInstance(String)}.  The native library will be unloaded when no longer referenced by any Java code.
<p>
The search path for loaded native libraries may be modified by setting <code>jna.library.path</code>.  See {@link com.sun.jna.NativeLibrary} for details.
<p>
<a href="#toc">Table of Contents</a>
<a name="function-mapping"></a>
<h2>Function Mapping</h2>
Function names are mapped directly from their Java interface name to the
symbol exported by the native library.  For instance, the function to convert
an ASCII string into an integer would look like this:<br>
<blockquote><code><pre>
public interface CLibrary extends Library {
    int atol(String s);
}
</pre></code></blockquote>
If you prefer to rename the Java methods to conform to Java coding conventions, then you can provide an entry ({@link com.sun.jna.Library#OPTION_FUNCTION_MAPPER}/{@link com.sun.jna.FunctionMapper}) in the options {@link java.util.Map} passed to {@link com.sun.jna.Native#loadLibrary(String,Class,java.util.Map) Native.loadLibrary()} which maps the Java names to the native names.  While this keeps your Java code a little cleaner, the additional mapping of names may make it a little less obvious the native functions being called.<p>
An instance of the {@link com.sun.jna.Function} class is obtained through the {@link com.sun.jna.NativeLibrary} instance corresponding to the containing native library.  This {@link com.sun.jna.Function} instance handles argument marshalling and delegation to the native function. 

<!-- TODO: when to use primitive array vs NIO Buffer vs Memory -->

<p>
<a href="#toc">Table of Contents</a>
<a name="marshalling"></a>
<h2>Marshalling/Unmarshalling (Java/Native Type Conversions)</h2>
Java types must be chosen to match native types of the same size.  Following are the types supported by the JNA library.<p>
<center>
<table border=1 borderColor=white class=styled width="100%">
<tr><td><b>Java Type</b></td><td><b>C Type</b></td><td><b>Native Representation</b></td></tr>
<tr><td>boolean</td><td>int</td><td>32-bit integer (customizable)</td>
<tr><td>byte</td><td>char</td><td>8-bit integer</td>
<tr><td>char</td><td>wchar_t</td><td>platform-dependent</td>
<tr><td>short</td><td>short</td><td>16-bit integer</td>
<tr><td>int</td><td>int</td><td>32-bit integer</td>
<tr><td>long</td><td>long long, __int64</td><td>64-bit integer</td>
<tr><td>float</td><td>float</td><td>32-bit floating point</td>
<tr><td>double</td><td>double</td><td>64-bit floating point</td>
<tr><td>{@link java.nio.Buffer}<br>
{@link com.sun.jna.Pointer}<td>pointer</td><td>platform-dependent (32- or 64-bit pointer to memory)</td>
<tr><td>&lt;T&gt;[] (array of primitive type)</td><td>pointer<br>array</td><td>32- or 64-bit pointer to memory (argument/return)<br>contiguous memory (struct member)</td>
<tr><td colspan=3>In addition to the above types, which are supported at the native layer, the JNA Java library automatically handles the following types.  All but <code>NativeMapped</code> and <code>NativeLong</code> are converted to {@link com.sun.jna.Pointer} before being passed to the native layer.</td></tr>
<tr><td>{@link java.lang.String}</td><td>char*</td><td>NUL-terminated array (native encoding or <code>jna.encoding</code>)</td>
<tr><td>{@link com.sun.jna.WString}</td><td>wchar_t*</td><td>NUL-terminated array (unicode)</td>
<tr><td>{@link java.lang.String String[]}</td><td>char**</td><td>NULL-terminated array of C strings</td>
<tr><td>{@link com.sun.jna.WString WString[]}</td><td>wchar_t**</td><td>NULL-terminated array of wide C strings</td>
<tr><td>{@link com.sun.jna.Structure}</td><td>struct*<br>struct</td><td>pointer to struct (argument or return) ({@link com.sun.jna.Structure.ByReference or explicitly})<br>struct by value (member of struct) ({@link com.sun.jna.Structure.ByValue or explicitly})</td>
<tr><td>{@link com.sun.jna.Union}</td><td>union</td><td>same as <code>Structure</code></td>
<tr><td>{@link com.sun.jna.Structure Structure[]}</td><td>struct[]</td><td>array of structs, contiguous in memory</td>
<tr><td>{@link com.sun.jna.Callback}</td><td>&lt;T&gt; (*fp)()</td><td>function pointer (Java or native)</td>
<tr><td>{@link com.sun.jna.NativeMapped}</td><td>varies</td><td>depends on definition</td>
<tr><td>{@link com.sun.jna.NativeLong}</td><td>long</td><td>platform-dependent (32- or 64-bit integer)</td>
<tr><td>{@link com.sun.jna.PointerType}</td><td>pointer</td><td>same as <code>Pointer</code></td>
</table>
</center>
<p>
<b>NOTES</b>
<ul>
<li>Unsigned values may be passed by assigning the corresponding
  two's-complement representation to the signed type of the same size.  
<li>Java arrays of primitive type may be wrapped by {@link java.nio.Buffer} in
  order to access a subset of the array (changing the effective size and/or
  offest).
<li>Java arrays of primitive type are only valid for use within the scope of a
  single call.  If the native code keeps a reference to the memory, use {@link
  Memory} or {@link java.nio.Buffer} instead.
<li>Primitive arrays and structures as members of a structure are overlaid on the parent structure memory.  
{'fraction_non_alphanumeric': 0.17841042425739517, 'fraction_numerical': 0.008028160316186006, 'mean_word_length': 5.8647732089868585, 'pattern_counts': {'":': 0, '<': 756, '<?xml version=': 0, '>': 756, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6942938', 'n_tokens_mistral': 5578, 'n_tokens_neox': 5425, 'n_words': 1511}