[ctypes-commit] ctypes/docs/manual manual.txt,NONE,1.1.2.1 manual.html,NONE,1.1.2.1 make.bat,NONE,1.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/ctypes/ctypes/docs/manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21043

Added Files:
      Tag: branch_1_0
	manual.txt manual.html make.bat 
Log Message:
Document LibraryLoader objects.

--- NEW FILE: manual.txt ---
=============
ctypes manual
=============

(work in progress)

Loading shared libraries
++++++++++++++++++++++++

Shared libraries are accessed when compiling/linking a program, and
when the program is run. The purpose of the ``find`` method is to
locate a library in a way similar to what the compiler does (on
platforms with several versions of a shared library the most recent
should be loaded), while ``load`` acts like when a program is run, and
uses the runtime loader directly. ``load_version`` works like ``load``
but tries to be platform independent (for cases where this makes
sense). Loading via attribute access is a shorthand notation
especially usefull for interactive use, it is equivalent to calling
``load_version`` with no version specified.

class LibraryLoader
+++++++++++++++++++

Instances of this ``LibraryLoader`` are used to load shared libraries.
They have the following methods:

``load(libname, mode=None)``

    Load and return the library with the given libname.  On most
    systems ``libname`` is the filename of the shared library; when
    it's not a pathname it will be searched in a system dependend list
    of locations (on many systems additional search paths can be
    specified by an environemtn variable).  Sometimes the file
    extension (like ``.dll`` pon Windows) can be omitted.

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function.  ``RTLD_LOCAL`` and ``RTLD_GLOBAL`` are
    typical values.  On Windows, ``mode`` is ignored.

``load_version(name, version=None, mode=None)``

    Build a system dependend filename from ``name`` and optionally
    ``version``, then load and return it.  ``name`` is the library
    name without any prefix like ``lib`` and suffix like ``.so`` or
    ``.dylib``.  This method should be used if a library is available
    on different platforms, using the particular naming convention of
    each platform.

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function, ignored on Windows.

    Example: calling ``loader.load_version('z', '1.1.3')`` would
    possibly load ``/usr/lib/libz.1.1.3.dylib`` on Mac OS X, and
    ``/lib/libz.so.1.1.3`` on a Linux system.

``find(name, mode=None)``

    Try to find a library, load and return it.  ``name`` is the
    library name without any prefix like ``lib``, suffix like ``.so``,
    ``.dylib`` or version number (this is the form used for the posix
    linker option ``-l``).

    ``mode`` allows to override the default flags passed to the
    ``dlopen()`` function, ignored on Windows.

     On windows, this method does exactly the same as the ``load``
     method.

     On other platforms, this function might call other programs like
     the compiler to find the library.  When using ctypes to write a
     shared library wrapping, consider using ``load_version`` or
     ``load`` instead.

Libaries can also be loaded by accessing them as attributes of the
loader instance, internally this calls ``load_version`` without
specifying ``version`` or ``mode``.  Obviously this only works for
libraries with names that are valid Python identifiers, and when the
name does not start with a ``_`` character.

Predefined library loaders
++++++++++++++++++++++++++

ctypes provides some LibraryLoader instances, the differences are the
calling conventions the functions will use, the default return type of
the functions, and other stuff.  All these loaders use the
``RTLD_LOCAL`` mode flag.

Functions can be accessed as named attributes of loaded libraries.

On Windows, structured exception handling is used around the function
call to protect Python from crashing in case you pass invalid
parameters to the function.

``cdll``

    Functions provided by libraries loaded using the ``cdll`` loader
    will be called with the standard C calling convention, and have a
    default return type of ``int``.  ctypes does release the Python
    global interpreter lock (GIL) just before calling the actual
    function, and reaquire it before returing, so a chance is given to
    other threads to run.

``windll``

    Windows only.  Functions provided by libraries loaded by
    ``windll`` will be called using the Windows ``__stdcall`` calling
    convention.  ctypes can to detect the case that the wrong number
    of parameters have been passed to the function call by examining
    the stack pointer before and after the function call.  If the
    wrong parameter count was used, an exception is raised (although
    the function really *has* been called).  The return value of the
    function is lost in this case.  Again, the GIL is released during
    the call.

``oledll``

    Windows only.  ``oledll`` behaves in the same way as ``windll``,
    except that the called function is expected to return a
    ``HRESULT`` value.  These are long values containing error or
    success codes.  In case the function return an error ``HRESULT``
    value, a `WindowsError`` is raised.  GIL released during the
    function call.

``pydll``

    This loader allows to call functions in libraries using the
    *Python* calling convention, for example Python C API functions.
    The GIL is *not* released during the function call, and the state
    of the Python error flag is examined after the function returns.
    If the error flag is set, an exception is raised.

    ctypes provides a prefabricated instance of ``pydll`` exposing the
    Python C api as the ``pythonapi`` symbol, you should however make
    sure to set the correct ``restype`` for the functions you use.

--- NEW FILE: manual.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>ctypes manual</title>
<style type="text/css">

/*
:Author: David Goodger
:Contact: go...@us...
:Date: $Date: 2006/01/27 20:28:54 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="ctypes-manual">
<h1 class="title">ctypes manual</h1>
(work in progress)
<div class="section">
<h1><a id="loading-shared-libraries" name="loading-shared-libraries">Loading shared libraries</a></h1>
Shared libraries are accessed when compiling/linking a program, and
when the program is run. The purpose of the <tt class="docutils literal">find</tt> method is to
locate a library in a way similar to what the compiler does (on
platforms with several versions of a shared library the most recent
should be loaded), while <tt class="docutils literal">load</tt> acts like when a program is run, and
uses the runtime loader directly. <tt class="docutils literal">load_version</tt> works like <tt class="docutils literal">load</tt>
but tries to be platform independent (for cases where this makes
sense). Loading via attribute access is a shorthand notation
especially usefull for interactive use, it is equivalent to calling
<tt class="docutils literal">load_version</tt> with no version specified.
</div>
<div class="section">
<h1><a id="class-libraryloader" name="class-libraryloader">class LibraryLoader</a></h1>
Instances of this <tt class="docutils literal">LibraryLoader</tt> are used to load shared libraries.
They have the following methods:
<tt class="docutils literal">load(libname, mode=None)</tt>
<blockquote>
Load and return the library with the given libname. On most
systems <tt class="docutils literal">libname</tt> is the filename of the shared library; when
it's not a pathname it will be searched in a system dependend list
of locations (on many systems additional search paths can be
specified by an environemtn variable). Sometimes the file
extension (like <tt class="docutils literal">.dll</tt> pon Windows) can be omitted.
<tt class="docutils literal">mode</tt> allows to override the default flags passed to the
<tt class="docutils literal">dlopen()</tt> function. <tt class="docutils literal">RTLD_LOCAL</tt> and <tt class="docutils literal">RTLD_GLOBAL</tt> are
typical values. On Windows, <tt class="docutils literal">mode</tt> is ignored.
</blockquote>
<tt class="docutils literal">load_version(name, version=None, mode=None)</tt>
<blockquote>
Build a system dependend filename from <tt class="docutils literal">name</tt> and optionally
<tt class="docutils literal">version</tt>, then load and return it. <tt class="docutils literal">name</tt> is the library
name without any prefix like <tt class="docutils literal">lib</tt> and suffix like <tt class="docutils literal">.so</tt> or
<tt class="docutils literal">.dylib</tt>. This method should be used if a library is available
on different platforms, using the particular naming convention of
each platform.
<tt class="docutils literal">mode</tt> allows to override the default flags passed to the
<tt class="docutils literal">dlopen()</tt> function, ignored on Windows.
Example: calling <tt class="docutils literal">loader.load_version('z', '1.1.3')</tt> would
possibly load <tt class="docutils literal">/usr/lib/libz.1.1.3.dylib</tt> on Mac OS X, and
<tt class="docutils literal">/lib/libz.so.1.1.3</tt> on a Linux system.
</blockquote>
<tt class="docutils literal">find(name, mode=None)</tt>
<blockquote>
Try to find a library, load and return it. <tt class="docutils literal">name</tt> is the
library name without any prefix like <tt class="docutils literal">lib</tt>, suffix like <tt class="docutils literal">.so</tt>,
<tt class="docutils literal">.dylib</tt> or version number (this is the form used for the posix
linker option <tt class="docutils literal">-l</tt>).
<tt class="docutils literal">mode</tt> allows to override the default flags passed to the
<tt class="docutils literal">dlopen()</tt> function, ignored on Windows.
<blockquote>
On windows, this method does exactly the same as the <tt class="docutils literal">load</tt>
method.
On other platforms, this function might call other programs like
the compiler to find the library. When using ctypes to write a
shared library wrapping, consider using <tt class="docutils literal">load_version</tt> or
<tt class="docutils literal">load</tt> instead.
</blockquote>
</blockquote>
Libaries can also be loaded by accessing them as attributes of the
loader instance, internally this calls <tt class="docutils literal">load_version</tt> without
specifying <tt class="docutils literal">version</tt> or <tt class="docutils literal">mode</tt>. Obviously this only works for
libraries with names that are valid Python identifiers, and when the
name does not start with a <tt class="docutils literal">_</tt> character.
</div>
<div class="section">
<h1><a id="predefined-library-loaders" name="predefined-library-loaders">Predefined library loaders</a></h1>
ctypes provides some LibraryLoader instances, the differences are the
calling conventions the functions will use, the default return type of
the functions, and other stuff. All these loaders use the
<tt class="docutils literal">RTLD_LOCAL</tt> mode flag.
Functions can be accessed as named attributes of loaded libraries.
On Windows, structured exception handling is used around the function
call to protect Python from crashing in case you pass invalid
parameters to the function.
<tt class="docutils literal">cdll</tt>
<blockquote>
Functions provided by libraries loaded using the <tt class="docutils literal">cdll</tt> loader
will be called with the standard C calling convention, and have a
default return type of <tt class="docutils literal">int</tt>. ctypes does release the Python
global interpreter lock (GIL) just before calling the actual
function, and reaquire it before returing, so a chance is given to
other threads to run.</blockquote>
<tt class="docutils literal">windll</tt>
<blockquote>
Windows only. Functions provided by libraries loaded by
<tt class="docutils literal">windll</tt> will be called using the Windows <tt class="docutils literal">__stdcall</tt> calling
convention. ctypes can to detect the case that the wrong number
of parameters have been passed to the function call by examining
the stack pointer before and after the function call. If the
wrong parameter count was used, an exception is raised (although
the function really has been called). The return value of the
function is lost in this case. Again, the GIL is released during
the call.</blockquote>
<tt class="docutils literal">oledll</tt>
<blockquote>
Windows only. <tt class="docutils literal">oledll</tt> behaves in the same way as <tt class="docutils literal">windll</tt>,
except that the called function is expected to return a
<tt class="docutils literal">HRESULT</tt> value. These are long values containing error or
success codes. In case the function return an error <tt class="docutils literal">HRESULT</tt>
value, a <cite>WindowsError`</cite> is raised. GIL released during the
function call.</blockquote>
<tt class="docutils literal">pydll</tt>
<blockquote>
This loader allows to call functions in libraries using the
Python calling convention, for example Python C API functions.
The GIL is not released during the function call, and the state
of the Python error flag is examined after the function returns.
If the error flag is set, an exception is raised.
ctypes provides a prefabricated instance of <tt class="docutils literal">pydll</tt> exposing the
Python C api as the <tt class="docutils literal">pythonapi</tt> symbol, you should however make
sure to set the correct <tt class="docutils literal">restype</tt> for the functions you use.
</blockquote>
</div>
</div>
</body>
</html>

--- NEW FILE: make.bat ---
c:\python24\scripts\rst2html.py manual.txt manual.html

[ctypes-commit] ctypes/docs/manual manual.txt,NONE,1.1.2.1 manual.html,NONE,1.1.2.1 make.bat,NONE,1.

[ctypes-commit] ctypes/docs/manual manual.txt,NONE,1.1.2.1 manual.html,NONE,1.1.2.1 make.bat,NONE,1.1.2.1