← Back to branch summary

~pythonregexp2.7/python/issue2636-01

« back to all changes in this revision

Viewing changes to Doc/library/ctypes.rst

  • Committer: Jeffrey C. "The TimeHorse" Jacobs
  • Date: 2008-06-09 14:37:21 UTC
  • mfrom: (39022.1.14 Regexp-2.6)
  • Revision ID: darklord@timehorse.com-20080609143721-bj0g1mwta28038da
Merged in changes from the core Regexp branch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/ctypes.rst
1337
1337
way is to instantiate one of the following classes:
1338
1338
 
1339
1339
 
1340
 
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None)
 
1340
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
1341
1341
 
1342
1342
   Instances of this class represent loaded shared libraries. Functions in these
1343
1343
   libraries use the standard C calling convention, and are assumed to return
1344
1344
   ``int``.
1345
1345
 
1346
1346
 
1347
 
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None)
 
1347
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
1348
1348
 
1349
1349
   Windows only: Instances of this class represent loaded shared libraries,
1350
1350
   functions in these libraries use the ``stdcall`` calling convention, and are
1354
1354
   failure, an :class:`WindowsError` is automatically raised.
1355
1355
 
1356
1356
 
1357
 
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None)
 
1357
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
1358
1358
 
1359
1359
   Windows only: Instances of this class represent loaded shared libraries,
1360
1360
   functions in these libraries use the ``stdcall`` calling convention, and are
1387
1387
The *mode* parameter can be used to specify how the library is loaded.  For
1388
1388
details, consult the ``dlopen(3)`` manpage, on Windows, *mode* is ignored.
1389
1389
 
 
1390
The *use_errno* parameter, when set to True, enables a ctypes
 
1391
mechanism that allows to access the system `errno` error number in a
 
1392
safe way.  `ctypes` maintains a thread-local copy of the systems
 
1393
`errno` variable; if you call foreign functions created with
 
1394
`use_errno=True` then the `errno` value before the function call is
 
1395
swapped with the ctypes private copy, the same happens immediately
 
1396
after the function call.
 
1397
 
 
1398
The function `ctypes.get_errno()` returns the value of the ctypes
 
1399
private copy, and the function `ctypes.set_errno(value)` changes the
 
1400
ctypes private copy to `value` and returns the former value.
 
1401
 
 
1402
The *use_last_error* parameter, when set to True, enables the same
 
1403
mechanism for the Windows error code which is managed by the
 
1404
GetLastError() and SetLastError() Windows api functions;
 
1405
`ctypes.get_last_error()` and `ctypes.set_last_error(value)` are used
 
1406
to request and change the ctypes private copy of the windows error
 
1407
code.
 
1408
 
 
1409
.. versionchanged:: 2.6
 
1410
 
 
1411
The `use_errno` and `use_last_error` parameters were added in Python
 
1412
2.6.
1390
1413
 
1391
1414
.. data:: RTLD_GLOBAL
1392
1415
   :noindex:
1585
1608
type and the argument types of the function.
1586
1609
 
1587
1610
 
1588
 
.. function:: CFUNCTYPE(restype, *argtypes)
 
1611
.. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)
1589
1612
 
1590
1613
   The returned function prototype creates functions that use the standard C
1591
1614
   calling convention.  The function will release the GIL during the call.
1592
 
 
1593
 
 
1594
 
.. function:: WINFUNCTYPE(restype, *argtypes)
 
1615
   If `use_errno` is set to True, the ctypes private copy of the system `errno`
 
1616
   variable is exchanged with the real `errno` value bafore and after the call;
 
1617
   `use_last_error` does the same for the Windows error code.
 
1618
 
 
1619
   .. versionchanged:: 2.6
 
1620
 
 
1621
   The optional `use_errno` and `use_last_error` parameters were added
 
1622
   in Python 2.6.
 
1623
 
 
1624
 
 
1625
.. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)
1595
1626
 
1596
1627
   Windows only: The returned function prototype creates functions that use the
1597
1628
   ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE`
1598
1629
   is the same as :func:`CFUNCTYPE`.  The function will release the GIL during the
1599
 
   call.
 
1630
   call. `use_errno` and `use_last_error` have the same meaning as above.
1600
1631
 
1601
1632
 
1602
1633
.. function:: PYFUNCTYPE(restype, *argtypes)
1848
1879
.. function:: GetLastError()
1849
1880
 
1850
1881
   Windows only: Returns the last error code set by Windows in the calling thread.
1851
 
 
 
1882
   This function calls the Windows `GetLastError()` function directly,
 
1883
   it does not return the ctypes-private copy of the error code.
 
1884
 
 
1885
.. function:: get_errno()
 
1886
 
 
1887
   Returns the current value of the ctypes-private copy of the system
 
1888
   `errno` variable in the calling thread.
 
1889
 
 
1890
   .. versionadded:: 2.6
 
1891
 
 
1892
.. function:: get_last_error()
 
1893
 
 
1894
   Windows only: returns the current value of the ctypes-private copy of the system
 
1895
   `LastError` variable in the calling thread.
 
1896
 
 
1897
   .. versionadded:: 2.6
1852
1898
 
1853
1899
.. function:: memmove(dst, src, count)
1854
1900
 
1901
1947
   other systems ``('ascii', 'strict')``.
1902
1948
 
1903
1949
 
 
1950
.. function:: set_errno(value)
 
1951
 
 
1952
   Set the  current value of the ctypes-private copy of the system
 
1953
   `errno` variable in the calling thread to `value` and return the
 
1954
   previous value.
 
1955
 
 
1956
   .. versionadded:: 2.6
 
1957
 
 
1958
.. function:: set_last_error(value)
 
1959
 
 
1960
   Windows only: set the current value of the ctypes-private copy of
 
1961
   the system `LastError` variable in the calling thread to `value`
 
1962
   and return the previous value.
 
1963
 
 
1964
   .. versionadded:: 2.6
 
1965
 
1904
1966
.. function:: sizeof(obj_or_type)
1905
1967
 
1906
1968
   Returns the size in bytes of a ctypes type or instance memory buffer. Does the