Shared Libraries, DLLs ---------------------- 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 ``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 dependent list of locations (on many systems additional search paths can be specified by an environment variable). Sometimes the file extension (like ``.dll`` on 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 dependent 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 reacquire 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 detect when the wrong number of parameters has 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. The GIL is 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. Library objects ~~~~~~~~~~~~~~~ The library loaders create instances of ``CDLL``, ``WinDLL``, ``OleDLL``, or ``PyDLL`` classes. You can, however, also load a library by constructing one of these classes by calling the constructor with the pathname of the library and an optional ``mode`` argument as described in the previous section. Library objects implement ``__getattr__`` and ``__getitem__`` methods that allow to access foreign functions by attribute access or indexing. The latter is useful if the name of the function is not a valid Python identifier, or clashes with special Python method names that start and end with two underscore characters. Library objects have two private attributes: ``_name`` is the pathname of the library, ``_handle`` is the handle to the library that ``dlopen`` has returned.