"ctypes" --- Python 用の外部関数ライブラリ
******************************************

**ソースコード:** Lib/ctypes

======================================================================

"ctypes" is a foreign function library for Python.  It provides C
compatible data types, and allows calling functions in DLLs or shared
libraries.  It can be used to wrap these libraries in pure Python.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see オプ
ションのモジュールの要件.

警告:

  "ctypes" provides low-level access to native libraries and the
  process's memory, bypassing Python's safety mechanisms and allowing
  execution of arbitrary native code. Incorrect use can corrupt data
  and objects, reveal sensitive information, cause crashes, or
  otherwise compromise the running process.


ctypes チュートリアル
=====================

注意: いくつかのコードサンプルで ctypes の "c_int" 型を参照しています
。 "sizeof(long) == sizeof(int)" であるようなプラットフォームでは、こ
の型は "c_long" のエイリアスです。そのため、 "c_int" 型を想定している
ときに "c_long" が表示されたとしても、混乱しないようにしてください ---
実際には同じ型なのです。


動的リンクライブラリをロードする
--------------------------------

"ctypes" exports the "cdll", and on Windows "windll" and "oledll"
objects, for loading dynamic link libraries.

You load libraries by accessing them as attributes of these objects.
"cdll" loads libraries which export functions using the standard
"cdecl" calling convention, while "windll" libraries call functions
using the "stdcall" calling convention. "oledll" also uses the
"stdcall" calling convention, and assumes the functions return a
Windows "HRESULT" error code. The error code is used to automatically
raise an "OSError" exception when the function call fails.

バージョン 3.3 で変更: Windows エラーは以前は "WindowsError" を送出し
ていましたが、これは現在では "OSError" の別名になっています。

Here are some examples for Windows. Note that "msvcrt" is the MS
standard C library containing most standard C functions, and uses the
"cdecl" calling convention:

   >>> from ctypes import *
   >>> print(windll.kernel32)
   <WinDLL 'kernel32', handle ... at ...>
   >>> print(cdll.msvcrt)
   <CDLL 'msvcrt', handle ... at ...>
   >>> libc = cdll.msvcrt
   >>>

Windows では通常の ".dll" ファイル拡張子を自動的に追加します。

注釈:

  "cdll.msvcrt" 経由で標準 C ライブラリにアクセスすると、Python が使用
  しているライブラリとは互換性のない可能性のある、古いバージョンのライ
  ブラリが使用されます。可能な場合には、ネイティブ Python の機能を使用
  するか、"msvcrt" モジュールをインポートして使用してください。

Other systems require the filename *including* the extension to load a
library, so attribute access can not be used to load libraries. Either
the "LoadLibrary()" method of the dll loaders should be used, or you
should load the library by creating an instance of "CDLL" by calling
the constructor.

For example, on Linux:

   >>> cdll.LoadLibrary("libc.so.6")
   <CDLL 'libc.so.6', handle ... at ...>
   >>> libc = CDLL("libc.so.6")
   >>> libc
   <CDLL 'libc.so.6', handle ... at ...>
   >>>

On macOS:

   >>> cdll.LoadLibrary("libc.dylib")
   <CDLL 'libc.dylib', handle ... at ...>
   >>> libc = CDLL("libc.dylib")
   >>> libc
   <CDLL 'libc.dylib', handle ... at ...>


ロードしたdllから関数にアクセスする
-----------------------------------

dll オブジェクトの属性として関数にアクセスします:

   >>> libc.printf
   <_FuncPtr object at 0x...>
   >>> print(windll.kernel32.GetModuleHandleA)
   <_FuncPtr object at 0x...>
   >>> print(windll.kernel32.MyOwnFunction)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "ctypes.py", line 239, in __getattr__
       func = _StdcallFuncPtr(name, self)
   AttributeError: function 'MyOwnFunction' not found
   >>>

Note that win32 system dlls like "kernel32" and "user32" often export
ANSI as well as UNICODE versions of a function. The UNICODE version is
exported with a "W" appended to the name, while the ANSI version is
exported with an "A" appended to the name. The win32 "GetModuleHandle"
function, which returns a *module handle* for a given module name, has
the following C prototype, and a macro is used to expose one of them
as "GetModuleHandle" depending on whether UNICODE is defined or not:

   /* ANSI version */
   HMODULE GetModuleHandleA(LPCSTR lpModuleName);
   /* UNICODE version */
   HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

*windll* は魔法を使ってどちらか一つを選ぶようなことはしません。
"GetModuleHandleA" もしくは "GetModuleHandleW" を明示的に指定して必要
とするバージョンにアクセスし、バイト列か文字列を使ってそれぞれ呼び出さ
なければなりません。

時には、 dll が関数を ""??2@YAPAXI@Z"" のような Python 識別子として有
効でない名前でエクスポートすることがあります。このような場合に関数を取
り出すには、 "getattr()" を使わなければなりません。:

   >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")
   <_FuncPtr object at 0x...>
   >>>

Windows では、名前ではなく序数によって関数をエクスポートする dll もあ
ります。こうした関数には序数を使って dll オブジェクトにインデックス指
定することでアクセスします:

   >>> cdll.kernel32[1]
   <_FuncPtr object at 0x...>
   >>> cdll.kernel32[0]
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "ctypes.py", line 310, in __getitem__
       func = _StdcallFuncPtr(name, self)
   AttributeError: function ordinal 0 not found
   >>>


関数を呼び出す
--------------

You can call these functions like any other Python callable. This
example uses the "rand()" function, which takes no arguments and
returns a pseudo-random integer:

   >>> print(libc.rand())
   1804289383

On Windows, you can call the "GetModuleHandleA()" function, which
returns a win32 module handle (passing "None" as single argument to
call it with a "NULL" pointer):

   >>> print(hex(windll.kernel32.GetModuleHandleA(None)))
   0x1d000000
   >>>

"cdecl" 呼び出し規約を使って "stdcall" 関数を呼び出したときには、
"ValueError" が送出されます。逆の場合も同様です:

   >>> cdll.kernel32.GetModuleHandleA(None)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: Procedure probably called with not enough arguments (4 bytes missing)
   >>>

   >>> windll.msvcrt.printf(b"spam")
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ValueError: Procedure probably called with too many arguments (4 bytes in excess)
   >>>

正しい呼び出し規約を知るためには、呼び出したい関数についての C ヘッダ
ファイルもしくはドキュメントを見なければなりません。

On Windows, "ctypes" uses win32 structured exception handling to
prevent crashes from general protection faults when functions are
called with invalid argument values:

   >>> windll.kernel32.GetModuleHandleA(32)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   OSError: exception: access violation reading 0x00000020
   >>>

The "faulthandler" module can help debug crashes, such as segmentation
faults produced by erroneous C library calls.

"None", integers, bytes objects and (unicode) strings are the only
native Python objects that can directly be used as parameters in these
function calls. "None" is passed as a C "NULL" pointer, bytes objects
and strings are passed as pointer to the memory block that contains
their data (char* or wchar_t*).  Python integers are passed as the
platform's default C int type, their value is masked to fit into the C
type.

Before we move on calling functions with other parameter types, we
have to learn more about "ctypes" data types.


基本データ型
------------

"ctypes" defines a number of primitive C compatible data types:

+---------------------------+---------------------------+---------------------------+---------------------------+
| ctypes の型               | C の型                    | Python の型               | "_type_"                  |
|===========================|===========================|===========================|===========================|
| "c_bool"                  | _Bool                     | "bool"                    | "'?'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_char"                  | char                      | 1-character "bytes"       | "'c'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_wchar"                 | "wchar_t"                 | 1-character "str"         | "'u'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_byte"                  | char                      | "int"                     | "'b'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ubyte"                 | unsigned char             | "int"                     | "'B'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_short"                 | short                     | "int"                     | "'h'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ushort"                | unsigned short            | "int"                     | "'H'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int"                   | int                       | "int"                     | "'i'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int8"                  | "int8_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int16"                 | "int16_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int32"                 | "int32_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int64"                 | "int64_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint"                  | unsigned int              | "int"                     | "'I'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint8"                 | "uint8_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint16"                | "uint16_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint32"                | "uint32_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint64"                | "uint64_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_long"                  | long                      | "int"                     | "'l'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ulong"                 | unsigned long             | "int"                     | "'L'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longlong"              | long long                 | "int"                     | "'q'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ulonglong"             | unsigned long long        | "int"                     | "'Q'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_size_t"                | "size_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ssize_t"               | "Py_ssize_t"              | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_time_t"                | "time_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_float"                 | float                     | "float"                   | "'f'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_double"                | double                    | "float"                   | "'d'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longdouble"            | long double               | "float"                   | "'g'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_char_p"                | char* (NUL 終端)          | "bytes" or "None"         | "'z'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_wchar_p"               | wchar_t* (NUL 終端)       | "str" or "None"           | "'Z'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_void_p"                | void*                     | "int" or "None"           | "'P'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "py_object"               | PyObject*                 | "object"                  | "'O'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| VARIANT_BOOL              | short int                 | "bool"                    | "'v'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+

Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is
supported in both C and "libffi", the following complex types are
available:

+---------------------------+---------------------------+---------------------------+---------------------------+
| ctypes の型               | C の型                    | Python の型               | "_type_"                  |
|===========================|===========================|===========================|===========================|
| "c_float_complex"         | float complex             | "complex"                 | "'F'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_double_complex"        | double complex            | "complex"                 | "'D'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longdouble_complex"    | long double complex       | "complex"                 | "'G'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+

これら全ての型はその型を呼び出すことによって作成でき、オプションとして
型と値が合っている初期化子を指定することができます:

   >>> c_int()
   c_long(0)
   >>> c_wchar_p("Hello, World")
   c_wchar_p(140018365411392)
   >>> c_ushort(-3)
   c_ushort(65533)
   >>>

The constructors for numeric types will convert input using
"__bool__()", "__index__()" (for "int"), "__float__()" or
"__complex__()". This means "c_bool" accepts any object with a truth
value:

   >>> empty_list = []
   >>> c_bool(empty_list)
   c_bool(False)

これらの型は変更可能であり、値を後で変更することもできます:

   >>> i = c_int(42)
   >>> print(i)
   c_long(42)
   >>> print(i.value)
   42
   >>> i.value = -99
   >>> print(i.value)
   -99
   >>>

Assigning a new value to instances of the pointer types "c_char_p",
"c_wchar_p", and "c_void_p" changes the *memory location* they point
to, *not the contents* of the memory block (of course not, because
Python string objects are immutable):

   >>> s = "Hello, World"
   >>> c_s = c_wchar_p(s)
   >>> print(c_s)
   c_wchar_p(139966785747344)
   >>> print(c_s.value)
   Hello World
   >>> c_s.value = "Hi, there"
   >>> print(c_s)              # the memory location has changed
   c_wchar_p(139966783348904)
   >>> print(c_s.value)
   Hi, there
   >>> print(s)                # first object is unchanged
   Hello, World
   >>>

しかし、変更可能なメモリを指すポインタであることを想定している関数へそ
れらを渡さないように注意すべきです。もし変更可能なメモリブロックが必要
なら、 ctypes には "create_string_buffer()" 関数があり、いろいろな方法
で作成することできます。現在のメモリブロックの内容は "raw" プロパティ
を使ってアクセス (あるいは変更) することができます。もし現在のメモリブ
ロックに NUL 終端文字列としてアクセスしたいなら、 "value" プロパティを
使ってください:

   >>> from ctypes import *
   >>> p = create_string_buffer(3)            # create a 3 byte buffer, initialized to NUL bytes
   >>> print(sizeof(p), repr(p.raw))
   3 b'\x00\x00\x00'
   >>> p = create_string_buffer(b"Hello")     # create a buffer containing a NUL terminated string
   >>> print(sizeof(p), repr(p.raw))
   6 b'Hello\x00'
   >>> print(repr(p.value))
   b'Hello'
   >>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer
   >>> print(sizeof(p), repr(p.raw))
   10 b'Hello\x00\x00\x00\x00\x00'
   >>> p.value = b"Hi"
   >>> print(sizeof(p), repr(p.raw))
   10 b'Hi\x00lo\x00\x00\x00\x00\x00'
   >>>

The "create_string_buffer()" function replaces the old "c_buffer()"
function (which is still available as an alias).  To create a mutable
memory block containing unicode characters of the C type "wchar_t",
use the "create_unicode_buffer()" function.


続・関数を呼び出す
------------------

printf は "sys.stdout" では *なく* 、本物の標準出力チャンネルへプリン
トすることに注意してください。したがって、これらの例はコンソールプロン
プトでのみ動作し、 *IDLE* や *PythonWin* では動作しません。:

   >>> printf = libc.printf
   >>> printf(b"Hello, %s\n", b"World!")
   Hello, World!
   14
   >>> printf(b"Hello, %S\n", "World!")
   Hello, World!
   14
   >>> printf(b"%d bottles of beer\n", 42)
   42 bottles of beer
   19
   >>> printf(b"%f bottles of beer\n", 42.5)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2
   >>>

As has been mentioned before, all Python types except integers,
strings, and bytes objects have to be wrapped in their corresponding
"ctypes" type, so that they can be converted to the required C data
type:

   >>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
   An int 1234, a double 3.140000
   31
   >>>


Calling variadic functions
--------------------------

On a lot of platforms calling variadic functions through ctypes is
exactly the same as calling functions with a fixed number of
parameters. On some platforms, and in particular ARM64 for Apple
Platforms, the calling convention for variadic functions is different
than that for regular functions.

On those platforms it is required to specify the "argtypes" attribute
for the regular, non-variadic, function arguments:

   libc.printf.argtypes = [ctypes.c_char_p]

Because specifying the attribute does not inhibit portability it is
advised to always specify "argtypes" for all variadic functions.


自作のデータ型とともに関数を呼び出す
------------------------------------

You can also customize "ctypes" argument conversion to allow instances
of your own classes be used as function arguments. "ctypes" looks for
an "_as_parameter_" attribute and uses this as the function argument.
The attribute must be an integer, string, bytes, a "ctypes" instance,
or an object with an "_as_parameter_" attribute:

   >>> class Bottles:
   ...     def __init__(self, number):
   ...         self._as_parameter_ = number
   ...
   >>> bottles = Bottles(42)
   >>> printf(b"%d bottles of beer\n", bottles)
   42 bottles of beer
   19
   >>>

If you don't want to store the instance's data in the "_as_parameter_"
instance variable, you could define a "@property" which makes the
attribute available on request.


要求される引数の型を指定する (関数プロトタイプ)
-----------------------------------------------

It is possible to specify the required argument types of functions
exported from DLLs by setting the "argtypes" attribute.

"argtypes" must be a sequence of C data types (the "printf()" function
is probably not a good example here, because it takes a variable
number and different types of parameters depending on the format
string, on the other hand this is quite handy to experiment with this
feature):

   >>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
   >>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
   String 'Hi', Int 10, Double 2.200000
   37
   >>>

(C の関数のプロトタイプのように) 書式を指定すると互換性のない引数型に
なるのを防ぎ、引数を有効な型へ変換しようとします。:

   >>> printf(b"%d %d %d", 1, 2, 3)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be interpreted as ctypes.c_char_p
   >>> printf(b"%s %d %f\n", b"X", 2, 3)
   X 2 3.000000
   13
   >>>

If you have defined your own classes which you pass to function calls,
you have to implement a "from_param()" class method for them to be
able to use them in the "argtypes" sequence. The "from_param()" class
method receives the Python object passed to the function call, it
should do a typecheck or whatever is needed to make sure this object
is acceptable, and then return the object itself, its "_as_parameter_"
attribute, or whatever you want to pass as the C function argument in
this case. Again, the result should be an integer, string, bytes, a
"ctypes" instance, or an object with an "_as_parameter_" attribute.


戻り値の型
----------

By default functions are assumed to return the C int type.  Other
return types can be specified by setting the "restype" attribute of
the function object.

The C prototype of "time()" is "time_t time(time_t *)". Because
"time_t" might be of a different type than the default return type
int, you should specify the "restype" attribute:

   >>> libc.time.restype = c_time_t

The argument types can be specified using "argtypes":

   >>> libc.time.argtypes = (POINTER(c_time_t),)

To call the function with a "NULL" pointer as first argument, use
"None":

   >>> print(libc.time(None))
   1150640792

Here is a more advanced example, it uses the "strchr()" function,
which expects a string pointer and a char, and returns a pointer to a
string:

   >>> strchr = libc.strchr
   >>> strchr(b"abcdef", ord("d"))
   8059983
   >>> strchr.restype = c_char_p    # c_char_p is a pointer to a string
   >>> strchr(b"abcdef", ord("d"))
   b'def'
   >>> print(strchr(b"abcdef", ord("x")))
   None
   >>>

If you want to avoid the "ord("x")" calls above, you can set the
"argtypes" attribute, and the second argument will be converted from a
single character Python bytes object into a C char:

   >>> strchr.restype = c_char_p
   >>> strchr.argtypes = [c_char_p, c_char]
   >>> strchr(b"abcdef", b"d")
   b'def'
   >>> strchr(b"abcdef", b"def")
   Traceback (most recent call last):
   ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected
   >>> print(strchr(b"abcdef", b"x"))
   None
   >>> strchr(b"abcdef", b"d")
   b'def'
   >>>

You can also use a callable Python object (a function or a class for
example) as the "restype" attribute, if the foreign function returns
an integer.  The callable will be called with the *integer* the C
function returns, and the result of this call will be used as the
result of your function call. This is useful to check for error return
values and automatically raise an exception:

   >>> GetModuleHandle = windll.kernel32.GetModuleHandleA
   >>> def ValidHandle(value):
   ...     if value == 0:
   ...         raise WinError()
   ...     return value
   ...
   >>>
   >>> GetModuleHandle.restype = ValidHandle
   >>> GetModuleHandle(None)
   486539264
   >>> GetModuleHandle("something silly")
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "<stdin>", line 3, in ValidHandle
   OSError: [Errno 126] The specified module could not be found.
   >>>

"WinError" はエラーコードの文字列表現を得るために Windows の
"FormatMessage()" api を呼び出し、例外を *返す* 関数です。 "WinError"
はオプションでエラーコードパラメータを取ります。このパラメータが使われ
ない場合は、エラーコードを取り出すために "GetLastError()" を呼び出しま
す。

Please note that a much more powerful error checking mechanism is
available through the "errcheck" attribute; see the reference manual
for details.


ポインタを渡す(または、パラメータの参照渡し)
--------------------------------------------

時には、 C api 関数がパラメータのデータ型として *ポインタ* を想定して
いることがあります。おそらくパラメータと同一の場所に書き込むためか、も
しくはそのデータが大きすぎて値渡しできない場合です。これは *パラメータ
の参照渡し* としても知られています。

"ctypes" exports the "byref()" function which is used to pass
parameters by reference.  The same effect can be achieved with the
"pointer()" function, although "pointer()" does a lot more work since
it constructs a real pointer object, so it is faster to use "byref()"
if you don't need the pointer object in Python itself:

   >>> i = c_int()
   >>> f = c_float()
   >>> s = create_string_buffer(b'\000' * 32)
   >>> print(i.value, f.value, repr(s.value))
   0 0.0 b''
   >>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
   ...             byref(i), byref(f), s)
   3
   >>> print(i.value, f.value, repr(s.value))
   1 3.1400001049 b'Hello'
   >>>


構造体と共用体
--------------

Structures and unions must derive from the "Structure" and "Union"
base classes which are defined in the "ctypes" module. Each subclass
must define a "_fields_" attribute.  "_fields_" must be a list of
*2-tuples*, containing a *field name* and a *field type*.

The field type must be a "ctypes" type like "c_int", or any other
derived "ctypes" type: structure, union, array, pointer.

以下は、 *x* と *y* という名前の二つの整数からなる簡単な POINT 構造体
の例です。コンストラクタで構造体を初期化する方法も説明しています:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = [("x", c_int),
   ...                 ("y", c_int)]
   ...
   >>> point = POINT(10, 20)
   >>> print(point.x, point.y)
   10 20
   >>> point = POINT(y=5)
   >>> print(point.x, point.y)
   0 5
   >>> POINT(1, 2, 3)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: too many initializers
   >>>

しかし、もっと複雑な構造体を構築することもできます。ある構造体は、他の
構造体をフィールド型として使うことで、他の構造体を含むことができます。

*upperleft* と *lowerright* という名前の二つの POINT を持つ RECT 構造
体です。:

   >>> class RECT(Structure):
   ...     _fields_ = [("upperleft", POINT),
   ...                 ("lowerright", POINT)]
   ...
   >>> rc = RECT(point)
   >>> print(rc.upperleft.x, rc.upperleft.y)
   0 5
   >>> print(rc.lowerright.x, rc.lowerright.y)
   0 0
   >>>

入れ子になった構造体はいくつかの方法を用いてコンストラクタで初期化する
ことができます。:

   >>> r = RECT(POINT(1, 2), POINT(3, 4))
   >>> r = RECT((1, 2), (3, 4))

Field *descriptor*s can be retrieved from the *class*, they are useful
for debugging because they can provide useful information. See
"CField":

   >>> POINT.x
   <ctypes.CField 'x' type=c_int, ofs=0, size=4>
   >>> POINT.y
   <ctypes.CField 'y' type=c_int, ofs=4, size=4>
   >>>

警告:

  "ctypes" does not support passing unions or structures with bit-
  fields to functions by value.  While this may work on 32-bit x86,
  it's not guaranteed by the library to work in the general case.
  Unions and structures with bit-fields should always be passed to
  functions by pointer.


Structure/union layout, alignment and byte order
------------------------------------------------

By default, Structure and Union fields are laid out in the same way
the C compiler does it.  It is possible to override this behavior
entirely by specifying a "_layout_" class attribute in the subclass
definition; see the attribute documentation for details.

It is possible to specify the maximum alignment for the fields and/or
for the structure itself by setting the class attributes "_pack_"
and/or "_align_", respectively. See the attribute documentation for
details.

"ctypes" uses the native byte order for Structures and Unions.  To
build structures with non-native byte order, you can use one of the
"BigEndianStructure", "LittleEndianStructure", "BigEndianUnion", and
"LittleEndianUnion" base classes.  These classes cannot contain
pointer fields.


構造体と共用体におけるビットフィールド
--------------------------------------

It is possible to create structures and unions containing bit fields.
Bit fields are only possible for integer fields, the bit width is
specified as the third item in the "_fields_" tuples:

   >>> class Int(Structure):
   ...     _fields_ = [("first_16", c_int, 16),
   ...                 ("second_16", c_int, 16)]
   ...
   >>> print(Int.first_16)
   <ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>
   >>> print(Int.second_16)
   <ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>

It is important to note that bit field allocation and layout in memory
are not defined as a C standard; their implementation is compiler-
specific. By default, Python will attempt to match the behavior of a
"native" compiler for the current platform. See the "_layout_"
attribute for details on the default behavior and how to change it.


配列
----

配列 (Array) はシーケンスであり、決まった数の同じ型のインスタンスを持
ちます。

推奨されている配列の作成方法はデータ型に正の整数を掛けることです。:

   TenPointsArrayType = POINT * 10

ややわざとらしいデータ型の例になりますが、他のものに混ざって 4 個の
POINT がある構造体です:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = ("x", c_int), ("y", c_int)
   ...
   >>> class MyStruct(Structure):
   ...     _fields_ = [("a", c_int),
   ...                 ("b", c_float),
   ...                 ("point_array", POINT * 4)]
   >>>
   >>> print(len(MyStruct().point_array))
   4
   >>>

インスタンスはクラスを呼び出す通常の方法で作成します。:

   arr = TenPointsArrayType()
   for pt in arr:
       print(pt.x, pt.y)

上記のコードは "0 0" という行が並んだものを表示します。配列の要素がゼ
ロで初期化されているためです。

正しい型の初期化子を指定することもできます。:

   >>> from ctypes import *
   >>> TenIntegers = c_int * 10
   >>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
   >>> print(ii)
   <c_long_Array_10 object at 0x...>
   >>> for i in ii: print(i, end=" ")
   ...
   1 2 3 4 5 6 7 8 9 10
   >>>


ポインタ
--------

Pointer instances are created by calling the "pointer()" function on a
"ctypes" type:

   >>> from ctypes import *
   >>> i = c_int(42)
   >>> pi = pointer(i)
   >>>

次のように、ポインタインスタンスは、ポインタが指すオブジェクト (上の例
では "i") を返す "contents" 属性を持ちます:

   >>> pi.contents
   c_long(42)
   >>>

Note that "ctypes" does not have OOR (original object return), it
constructs a new, equivalent object each time you retrieve an
attribute:

   >>> pi.contents is i
   False
   >>> pi.contents is pi.contents
   False
   >>>

別の "c_int" インスタンスがポインタの contents 属性に代入されると、こ
れが記憶されているメモリ位置を指すポインタに変化します。:

   >>> i = c_int(99)
   >>> pi.contents = i
   >>> pi.contents
   c_long(99)
   >>>

ポインタインスタンスは整数でインデックス指定することもできます。:

   >>> pi[0]
   99
   >>>

整数インデックスへ代入するとポインタが指す値が変更されます。:

   >>> print(i)
   c_long(99)
   >>> pi[0] = 22
   >>> print(i)
   c_long(22)
   >>>

0 ではないインデックスを使うこともできますが、 C の場合と同じように自
分が何をしているかを理解している必要があります。任意のメモリ位置にアク
セスもしくは変更できるのです。一般的にこの機能を使うのは、 C 関数から
ポインタを受け取り、そのポインタが単一の要素ではなく実際に配列を指して
いると *分かっている* 場合だけです。

Behind the scenes, the "pointer()" function does more than simply
create pointer instances, it has to create pointer *types* first. This
is done with the "POINTER()" function, which accepts any "ctypes"
type, and returns a new type:

   >>> PI = POINTER(c_int)
   >>> PI
   <class 'ctypes.LP_c_long'>
   >>> PI(42)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: expected c_long instead of int
   >>> PI(c_int(42))
   <ctypes.LP_c_long object at 0x...>
   >>>

ポインタ型を引数なしで呼び出すと "NULL" ポインタを作成します。 "NULL"
ポインタは "False" ブール値を持っています。:

   >>> null_ptr = POINTER(c_int)()
   >>> print(bool(null_ptr))
   False
   >>>

"ctypes" checks for "NULL" when dereferencing pointers (but
dereferencing invalid non-"NULL" pointers would crash Python):

   >>> null_ptr[0]
   Traceback (most recent call last):
       ....
   ValueError: NULL pointer access
   >>>

   >>> null_ptr[0] = 1234
   Traceback (most recent call last):
       ....
   ValueError: NULL pointer access
   >>>


Thread safety without the GIL
-----------------------------

From Python 3.13 onward, the *GIL* can be disabled on the *free-
threaded build*. In ctypes, reads and writes to a single object
concurrently is safe, but not across multiple objects:

      >>> number = c_int(42)
      >>> pointer_a = pointer(number)
      >>> pointer_b = pointer(number)

In the above, it's only safe for one object to read and write to the
address at once if the GIL is disabled. So, "pointer_a" can be shared
and written to across multiple threads, but only if "pointer_b" is not
also attempting to do the same. If this is an issue, consider using a
"threading.Lock" to synchronize access to memory:

      >>> import threading
      >>> lock = threading.Lock()
      >>> # Thread 1
      >>> with lock:
      ...    pointer_a.contents = 24
      >>> # Thread 2
      >>> with lock:
      ...    pointer_b.contents = 42


型変換
------

Usually, ctypes does strict type checking.  This means, if you have
"POINTER(c_int)" in the "argtypes" list of a function or as the type
of a member field in a structure definition, only instances of exactly
the same type are accepted.  There are some exceptions to this rule,
where ctypes accepts other objects.  For example, you can pass
compatible array instances instead of pointer types.  So, for
"POINTER(c_int)", ctypes accepts an array of c_int:

   >>> class Bar(Structure):
   ...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
   ...
   >>> bar = Bar()
   >>> bar.values = (c_int * 3)(1, 2, 3)
   >>> bar.count = 3
   >>> for i in range(bar.count):
   ...     print(bar.values[i])
   ...
   1
   2
   3
   >>>

In addition, if a function argument is explicitly declared to be a
pointer type (such as "POINTER(c_int)") in "argtypes", an object of
the pointed type ("c_int" in this case) can be passed to the function.
ctypes will apply the required "byref()" conversion in this case
automatically.

POINTER型フィールドを "NULL" に設定するために、 "None" を代入してもか
まいません。:

   >>> bar.values = None
   >>>

Sometimes you have instances of incompatible types.  In C, you can
cast one type into another type.  "ctypes" provides a "cast()"
function which can be used in the same way.  The "Bar" structure
defined above accepts "POINTER(c_int)" pointers or "c_int" arrays for
its "values" field, but not instances of other types:

   >>> bar.values = (c_byte * 4)()
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
   >>>

このような場合には、 "cast()" 関数が便利です。

"cast()" 関数は ctypes インスタンスを異なる ctypes データ型を指すポイ
ンタへキャストするために使えます。 "cast()" は二つのパラメータ、ある種
のポインタかそのポインタへ変換できる ctypes オブジェクトと、 ctypes ポ
インタ型を取ります。そして、第二引数のインスタンスを返します。このイン
スタンスは第一引数と同じメモリブロックを参照しています:

   >>> a = (c_byte * 4)()
   >>> cast(a, POINTER(c_int))
   <ctypes.LP_c_long object at ...>
   >>>

したがって、 "cast()" を "Bar" 構造体の "values" フィールドへ代入する
ために使うことができます:

   >>> bar = Bar()
   >>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
   >>> print(bar.values[0])
   0
   >>>


不完全型
--------

*不完全型* はメンバーがまだ指定されていない構造体、共用体もしくは配列
です。 C では、前方宣言により指定され、後で定義されます。:

   struct cell; /* forward declaration */

   struct cell {
       char *name;
       struct cell *next;
   };

ctypes コードへの直接的な変換ではこうなるでしょう。しかし、動作しませ
ん:

   >>> class cell(Structure):
   ...     _fields_ = [("name", c_char_p),
   ...                 ("next", POINTER(cell))]
   ...
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "<stdin>", line 2, in cell
   NameError: name 'cell' is not defined
   >>>

because the new "class cell" is not available in the class statement
itself. In "ctypes", we can define the "cell" class and set the
"_fields_" attribute later, after the class statement:

   >>> from ctypes import *
   >>> class cell(Structure):
   ...     pass
   ...
   >>> cell._fields_ = [("name", c_char_p),
   ...                  ("next", POINTER(cell))]
   >>>

試してみましょう。 "cell" のインスタンスを二つ作り、互いに参照し合うよ
うにします。最後に、つながったポインタを何度かたどります。:

   >>> c1 = cell()
   >>> c1.name = b"foo"
   >>> c2 = cell()
   >>> c2.name = b"bar"
   >>> c1.next = pointer(c2)
   >>> c2.next = pointer(c1)
   >>> p = c1
   >>> for i in range(8):
   ...     print(p.name, end=" ")
   ...     p = p.next[0]
   ...
   foo bar foo bar foo bar foo bar
   >>>


コールバック関数
----------------

"ctypes" allows creating C callable function pointers from Python
callables. These are sometimes called *callback functions*.

最初に、コールバック関数のためのクラスを作る必要があります。そのクラス
には呼び出し規約、戻り値の型およびこの関数が受け取る引数の数と型につい
ての情報があります。

"CFUNCTYPE()" ファクトリ関数は通常の "cdecl" 呼び出し規約を用いてコー
ルバック関数のための型を作成します。 Windows では、 "WINFUNCTYPE()" フ
ァクトリ関数が "stdcall" 呼び出し規約を用いてコールバック関数の型を作
成します。

これらのファクトリ関数はともに最初の引数に戻り値の型、残りの引数として
コールバック関数が想定する引数の型を渡して呼び出されます。

I will present an example here which uses the standard C library's
"qsort()" function, that is used to sort items with the help of a
callback function.  "qsort()" will be used to sort an array of
integers:

   >>> IntArray5 = c_int * 5
   >>> ia = IntArray5(5, 1, 7, 33, 99)
   >>> qsort = libc.qsort
   >>> qsort.restype = None
   >>>

"qsort()" must be called with a pointer to the data to sort, the
number of items in the data array, the size of one item, and a pointer
to the comparison function, the callback. The callback will then be
called with two pointers to items, and it must return a negative
integer if the first item is smaller than the second, a zero if they
are equal, and a positive integer otherwise.

コールバック関数は整数へのポインタを受け取り、整数を返す必要があります
。まず、コールバック関数のための "type" を作成します。:

   >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
   >>>

まず初めに、これが受け取った変数を表示するだけのシンプルなコールバック
です:

   >>> def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return 0
   ...
   >>> cmp_func = CMPFUNC(py_cmp_func)
   >>>

結果は以下の通りです:

   >>> qsort(ia, len(ia), sizeof(c_int), cmp_func)
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 5 7
   py_cmp_func 1 7
   >>>

ここで 2 つの要素を実際に比較し、役に立つ結果を返します:

   >>> def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return a[0] - b[0]
   ...
   >>>
   >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 1 7
   py_cmp_func 5 7
   >>>

簡単に確認できるように、配列を次のようにソートしました:

   >>> for i in ia: print(i, end=" ")
   ...
   1 5 7 33 99
   >>>

関数ファクトリはデコレータファクトリとしても使えるので、次のようにも書
けます:

   >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
   ... def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return a[0] - b[0]
   ...
   >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 1 7
   py_cmp_func 5 7
   >>>

注釈:

  Make sure you keep references to "CFUNCTYPE()" objects as long as
  they are used from C code. "ctypes" doesn't, and if you don't, they
  may be garbage collected, crashing your program when a callback is
  made.同様に、コールバック関数が Python の管理外 (例えば、コールバッ
  クを呼び出す外部のコード) で作られたスレッドで呼び出された場合、
  ctypes は全ての呼び出しごとに新しいダミーの Python スレッドを作成す
  ることに注意してください。 この動作はほとんどの目的に対して正しいも
  のですが、同じ C スレッドからの呼び出しだったとしても、
  "threading.local" で格納された値は異なるコールバックをまたいで生存は
  *しません* 。


dllからエクスポートされた値へアクセスする
-----------------------------------------

Some shared libraries not only export functions, they also export
variables. An example in the Python library itself is the
"Py_Version", Python runtime version number encoded in a single
constant integer.

"ctypes" can access values like this with the "in_dll()" class methods
of the type.  *pythonapi* is a predefined symbol giving access to the
Python C api:

   >>> version = ctypes.c_int.in_dll(ctypes.pythonapi, "Py_Version")
   >>> print(hex(version.value))
   0x30c00a0

ポインタの使い方を説明する拡張例では、 Python がエクスポートする
"PyImport_FrozenModules" ポインタにアクセスします。

この値のドキュメントから引用すると:

   このポインタは "_frozen" のレコードからなり、終端の要素のメンバが
   "NULL" かゼロになっているような配列を指すよう初期化されます。 フリ
   ーズされたモジュールをインポートするとき、このテーブルを検索します
   。 サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に
   生成されたフリーズ化モジュールの集合を提供するようにできます。

So manipulating this pointer could even prove useful. To restrict the
example size, we show only how this table can be read with "ctypes":

   >>> from ctypes import *
   >>>
   >>> class struct_frozen(Structure):
   ...     _fields_ = [("name", c_char_p),
   ...                 ("code", POINTER(c_ubyte)),
   ...                 ("size", c_int),
   ...                 ("get_code", POINTER(c_ubyte)),  # Function pointer
   ...                ]
   ...
   >>>

私たちは "_frozen" データ型を定義済みなので、このテーブルを指すポイン
タを得ることができます。:

   >>> FrozenTable = POINTER(struct_frozen)
   >>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
   >>>

"table" が "struct_frozen" レコードの配列への "pointer" なので、その配
列に対して反復処理を行えます。しかし、ループが確実に終了するようにする
必要があります。なぜなら、ポインタに大きさの情報がないからです。遅かれ
早かれ、アクセス違反か何かでクラッシュすることになるでしょう。 "NULL"
エントリに達したときはループを抜ける方が良いです:

   >>> for item in table:
   ...     if item.name is None:
   ...         break
   ...     print(item.name.decode("ascii"), item.size)
   ...
   _frozen_importlib 31764
   _frozen_importlib_external 41499
   zipimport 12345
   >>>

標準 Python はフローズンモジュールとフローズンパッケージ (負の "size"
メンバーで表されています) を持っているという事実はあまり知られておらず
、テストにだけ使われています。例えば、 "import __hello__" を試してみて
ください。


びっくり仰天
------------

There are some edges in "ctypes" where you might expect something
other than what actually happens.

次に示す例について考えてみてください。:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = ("x", c_int), ("y", c_int)
   ...
   >>> class RECT(Structure):
   ...     _fields_ = ("a", POINT), ("b", POINT)
   ...
   >>> p1 = POINT(1, 2)
   >>> p2 = POINT(3, 4)
   >>> rc = RECT(p1, p2)
   >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
   1 2 3 4
   >>> # now swap the two points
   >>> rc.a, rc.b = rc.b, rc.a
   >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
   3 4 3 4
   >>>

うーん、最後の文に "3 4 1 2" と表示されることを期待していたはずです。
何が起きたのでしょうか? 上の行の "rc.a, rc.b = rc.b, rc.a" の各段階は
このようになります。:

   >>> temp0, temp1 = rc.b, rc.a
   >>> rc.a = temp0
   >>> rc.b = temp1
   >>>

"temp0" と "temp1" は前記の "rc" オブジェクトの内部バッファでまだ使わ
れているオブジェクトです。したがって、 "rc.a = temp0" を実行すると
"temp0" のバッファ内容が "rc" のバッファへコピーされます。さらに、これ
は "temp1" の内容を変更します。そのため、最後の代入 "rc.b = temp1" は
、期待する結果にはならないのです。

Structure 、 Union および Array のサブオブジェクトを取り出しても、その
サブオブジェクトが *コピー* されるわけではなく、ルートオブジェクトの内
部バッファにアクセスするラッパーオブジェクトを取り出すことを覚えておい
てください。

期待とは違う振る舞いをする別の例はこれです:

   >>> s = c_char_p()
   >>> s.value = b"abc def ghi"
   >>> s.value
   b'abc def ghi'
   >>> s.value is s.value
   False
   >>>

注釈:

  "c_char_p" からインスタンス化されたオブジェクトは、bytes または整数
  に設定された値しか持てません。

なぜ "False" と表示されるのでしょうか? ctypes インスタンスはメモリと、
メモリの内容にアクセスするいくつかの *descriptor* (記述子)を含むオブジ
ェクトです。メモリブロックに Python オブジェクトを保存してもオブジェク
ト自身が保存される訳ではなく、オブジェクトの "contents" が保存されます
。その contents に再アクセスすると新しい Python オブジェクトがその度に
作られます。


可変サイズのデータ型
--------------------

"ctypes" provides some support for variable-sized arrays and
structures.

"resize()" 関数は既存の ctypes オブジェクトのメモリバッファのサイズを
変更したい場合に使えます。この関数は第一引数にオブジェクト、第二引数に
要求されたサイズをバイト単位で指定します。メモリブロックはオブジェクト
型で指定される通常のメモリブロックより小さくすることはできません。これ
をやろうとすると、 "ValueError" が送出されます。:

   >>> short_array = (c_short * 4)()
   >>> print(sizeof(short_array))
   8
   >>> resize(short_array, 4)
   Traceback (most recent call last):
       ...
   ValueError: minimum size is 8
   >>> resize(short_array, 32)
   >>> sizeof(short_array)
   32
   >>> sizeof(type(short_array))
   8
   >>>

これはこれで上手くいっていますが、この配列の追加した要素へどうやってア
クセスするのでしょうか? この型は要素の数が 4 個であるとまだ認識してい
るので、他の要素にアクセスするとエラーになります。:

   >>> short_array[:]
   [0, 0, 0, 0]
   >>> short_array[7]
   Traceback (most recent call last):
       ...
   IndexError: invalid index
   >>>

Another way to use variable-sized data types with "ctypes" is to use
the dynamic nature of Python, and (re-)define the data type after the
required size is already known, on a case by case basis.


ctypesリファレンス
==================


共有ライブラリを見つける
------------------------

When programming in a compiled language, shared libraries are accessed
when compiling/linking a program, and when the program is run.

The purpose of the "find_library()" function is to locate a library in
a way similar to what the compiler or runtime loader does (on
platforms with several versions of a shared library the most recent
should be loaded), while the ctypes library loaders act like when a
program is run, and call the runtime loader directly.

The "ctypes.util" module provides a function which can help to
determine the library to load.

ctypes.util.find_library(name)

   Try to find a library and return a pathname.  *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").  If no library can be found, returns "None".

The exact functionality is system dependent.

On Linux, "find_library()" tries to run external programs
("/sbin/ldconfig", "gcc", "objdump" and "ld") to find the library
file. It returns the filename of the library file.

Note that if the output of these programs does not correspond to the
dynamic linker used by Python, the result of this function may be
misleading.

バージョン 3.6 で変更: Linux では、ライブラリを検索する際に、他の方法
でライブラリが見つけられない場合は、 "LD_LIBRARY_PATH" 環境変数の値が
使われます

ここに例があります:

   >>> from ctypes.util import find_library
   >>> find_library("m")
   'libm.so.6'
   >>> find_library("c")
   'libc.so.6'
   >>> find_library("bz2")
   'libbz2.so.1.0'
   >>>

On macOS and Android, "find_library()" uses the system's standard
naming schemes and paths to locate the library, and returns a full
pathname if successful:

   >>> from ctypes.util import find_library
   >>> find_library("c")
   '/usr/lib/libc.dylib'
   >>> find_library("m")
   '/usr/lib/libm.dylib'
   >>> find_library("bz2")
   '/usr/lib/libbz2.dylib'
   >>> find_library("AGL")
   '/System/Library/Frameworks/AGL.framework/AGL'
   >>>

On Windows, "find_library()" searches along the system search path,
and returns the full pathname, but since there is no predefined naming
scheme a call like "find_library("c")" will fail and return "None".

If wrapping a shared library with "ctypes", it *may* be better to
determine the shared library name at development time, and hardcode
that into the wrapper module instead of using "find_library()" to
locate the library at runtime.


Listing loaded shared libraries
-------------------------------

When writing code that relies on code loaded from shared libraries, it
can be useful to know which shared libraries have already been loaded
into the current process.

The "ctypes.util" module provides the "dllist()" function, which calls
the different APIs provided by the various platforms to help determine
which shared libraries have already been loaded into the current
process.

The exact output of this function will be system dependent. On most
platforms, the first entry of this list represents the current process
itself, which may be an empty string. For example, on glibc-based
Linux, the return may look like:

   >>> from ctypes.util import dllist
   >>> dllist()
   ['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-linux-gnu/libc.so.6', ... ]


共有ライブラリをロードする
--------------------------

There are several ways to load shared libraries into the Python
process.  One way is to instantiate "CDLL" or one of its subclasses:

class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

   Represents a loaded shared library.

   Functions in this library use the standard C calling convention,
   and are assumed to return int. The Python *global interpreter lock*
   is released before calling any function exported by these
   libraries, and reacquired afterwards. For different function
   behavior, use a subclass: "OleDLL", "WinDLL", or "PyDLL".

   If you have an existing "handle" to an already loaded shared
   library, it can be passed as the *handle* argument to wrap the
   opened library in a new "CDLL" object. In this case, *name* is only
   used to set the "_name" attribute, but it may be adjusted and/or
   validated.

   If *handle* is "None", the underlying platform's *dlopen(3)* or
   "LoadLibrary()" function is used to load the library into the
   process, and to get a handle to it.

   *name* is the pathname of the shared library to open. If *name*
   does not contain a path separator, the library is found in a
   platform-specific way.

   On non-Windows systems, *name* can  be "None". In this case,
   "dlopen()" is called with "NULL", which opens the main program as a
   "library". (Some systems do the same is *name* is empty;
   "None"/"NULL" is more portable.)

   CPython implementation detail: Since CPython is linked to "libc", a
   "None" *name* is often used to access the C standard library:

      >>> printf = ctypes.CDLL(None).printf
      >>> printf.argtypes = [ctypes.c_char_p]
      >>> printf(b"hello\n")
      hello
      6

   To access the Python C API, prefer "ctypes.pythonapi" which works
   across platforms.

   *mode* パラメータを使うと、ライブラリがどうやってロードされたかを特
   定できます。 詳細は *dlopen(3)* マニュアルページを参考にしてくださ
   い。 Windows では *mode* は無視されます。 POSIX システムでは
   RTLD_NOW が常に追加され、設定変更はできません。

   The *use_errno* parameter, when set to true, enables a ctypes
   mechanism that allows accessing the system "errno" error number in
   a safe way. "ctypes" maintains a thread-local copy of the system's
   "errno" variable; if you call foreign functions created with
   "use_errno=True" then the "errno" value before the function call is
   swapped with the ctypes private copy, the same happens immediately
   after the function call.

   "ctypes.get_errno()" 関数は ctypes のプライベートコピーの値を返しま
   す。そして、 "ctypes.set_errno()" 関数は ctypes のプライベートコピ
   ーを置き換え、以前の値を返します。

   The *use_last_error* parameter, when set to true, enables the same
   mechanism for the Windows error code which is managed by the
   "GetLastError()" and "SetLastError()" Windows API functions;
   "ctypes.get_last_error()" and "ctypes.set_last_error()" are used to
   request and change the ctypes private copy of the windows error
   code.

   The *winmode* parameter is used on Windows to specify how the
   library is loaded (since *mode* is ignored). It takes any value
   that is valid for the Win32 API "LoadLibraryEx" flags parameter.
   When omitted, the default is to use the flags that result in the
   most secure DLL load, which avoids issues such as DLL hijacking.
   Passing the full path to the DLL is the safest way to ensure the
   correct library and dependencies are loaded.

   On Windows creating a "CDLL" instance may fail even if the DLL name
   exists. When a dependent DLL of the loaded DLL is not found, a
   "OSError" error is raised with the message *"[WinError 126] The
   specified module could not be found".* This error message does not
   contain the name of the missing DLL because the Windows API does
   not return this information making this error hard to diagnose. To
   resolve this error and determine which DLL is not found, you need
   to find the list of dependent DLLs and determine which one is not
   found using Windows debugging and tracing tools.

   参考: Microsoft DUMPBIN tool -- A tool to find DLL dependents.

   バージョン 3.8 で変更: *winmode* 引数が追加されました。

   バージョン 3.12 で変更: The *name* parameter can now be a *path-
   like object*.

   Instances of this class have no public methods.  Functions exported
   by the shared library can be accessed as attributes or by index.
   Please note that accessing the function through an attribute caches
   the result and therefore accessing it repeatedly returns the same
   object each time.  On the other hand, accessing it through an index
   returns a new object each time:

      >>> from ctypes import CDLL
      >>> libc = CDLL("libc.so.6")  # On Linux
      >>> libc.time == libc.time
      True
      >>> libc['time'] == libc['time']
      False

   The following public attributes are available. Their name starts
   with an underscore to not clash with exported function names:

   _handle

      ライブラリへのアクセスに用いられるシステムハンドル。

   _name

      コンストラクタに渡されたライブラリの名前。

class ctypes.OleDLL

   See "CDLL", the superclass, for common information.

   Functions in this library use the "stdcall" calling convention, and
   are assumed to return the windows specific "HRESULT" code.
   "HRESULT" values contain information specifying whether the
   function call failed or succeeded, together with additional error
   code.  If the return value signals a failure, an "OSError" is
   automatically raised.

   Availability: Windows

   バージョン 3.3 で変更: "WindowsError" used to be raised, which is
   now an alias of "OSError".

class ctypes.WinDLL

   See "CDLL", the superclass, for common information.

   Functions in these libraries use the "stdcall" calling convention,
   and are assumed to return int by default.

   Availability: Windows

class ctypes.PyDLL

   See "CDLL", the superclass, for common information.

   When functions in this library are called, the Python GIL is *not*
   released during the function call, and after the function execution
   the Python error flag is checked. If the error flag is set, a
   Python exception is raised.

   Thus, this is only useful to call Python C API functions directly.

ctypes.RTLD_GLOBAL

   *mode* パラメータとして使うフラグ。このフラグが利用できないプラット
   フォームでは、整数のゼロと定義されています。

ctypes.RTLD_LOCAL

   *mode* パラメータとして使うフラグ。これが利用できないプラットフォー
   ムでは、 *RTLD_GLOBAL* と同様です。

ctypes.DEFAULT_MODE

   共有ライブラリをロードするために使われるデフォルトモード。 OSX 10.3
   では *RTLD_GLOBAL* であり、そうでなければ *RTLD_LOCAL* と同じです。

Shared libraries can also be loaded by using one of the prefabricated
objects, which are instances of the "LibraryLoader" class, either by
calling the "LoadLibrary()" method, or by retrieving the library as
attribute of the loader instance.

class ctypes.LibraryLoader(dlltype)

   共有ライブラリをロードするクラス。 *dlltype* は "CDLL" 、 "PyDLL"
   、 "WinDLL" もしくは "OleDLL" 型の一つであるべきです。

   "__getattr__()" has special behavior: It allows loading a shared
   library by accessing it as attribute of a library loader instance.
   The result is cached, so repeated attribute accesses return the
   same library each time.

   LoadLibrary(name)

      共有ライブラリをプロセスへロードし、それを返します。このメソッド
      はライブラリの新しいインスタンスを常に返します。

これらの前もって作られたライブラリローダーを利用することができます。:

ctypes.cdll

   "CDLL" インスタンスを作ります。

ctypes.windll

   Creates "WinDLL" instances.

   Availability: Windows

ctypes.oledll

   Creates "OleDLL" instances.

   Availability: Windows

ctypes.pydll

   "PyDLL" インスタンスを作ります。

For accessing the C Python api directly, a ready-to-use Python shared
library object is available:

ctypes.pythonapi

   An instance of "PyDLL" that exposes Python C API functions as
   attributes.  Note that all these functions are assumed to return C
   int, which is of course not always the truth, so you have to assign
   the correct "restype" attribute to use these functions.

Loading a library through any of these objects raises an auditing
event "ctypes.dlopen" with string argument "name", the name used to
load the library.

Accessing a function on a loaded library raises an auditing event
"ctypes.dlsym" with arguments "library" (the library object) and
"name" (the symbol's name as a string or integer).

In cases when only the library handle is available rather than the
object, accessing a function raises an auditing event
"ctypes.dlsym/handle" with arguments "handle" (the raw library handle)
and "name".


外部関数
--------

As explained in the previous section, foreign functions can be
accessed as attributes of loaded shared libraries.  The function
objects created in this way by default accept any number of arguments,
accept any ctypes data instances as arguments, and return the default
result type specified by the library loader.

They are instances of a private local class "_FuncPtr" (not exposed in
"ctypes") which inherits from the private "_CFuncPtr" class:

   >>> import ctypes
   >>> lib = ctypes.CDLL(None)
   >>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)
   True
   >>> lib._FuncPtr is ctypes._CFuncPtr
   False

class ctypes._CFuncPtr

   C の呼び出し可能外部関数のためのベースクラス。

   外部関数のインスタンスも C 互換データ型です。それらは C の関数ポイ
   ンタを表しています。

   この振る舞いは外部関数オブジェクトの特別な属性に代入することによっ
   て、カスタマイズすることができます。

   restype

      外部関数の結果の型を指定するために ctypes 型を代入する。何も返さ
      ない関数を表す void に対しては "None" を使います。

      It is possible to assign a callable Python object that is not a
      ctypes type, in this case the function is assumed to return a C
      int, and the callable will be called with this integer, allowing
      further processing or error checking.  Using this is deprecated,
      for more flexible post processing or error checking use a ctypes
      data type as "restype" and assign a callable to the "errcheck"
      attribute.

   argtypes

      関数が受け取る引数の型を指定するために ctypes 型のタプルを代入し
      ます。"stdcall" 呼び出し規約を使う関数はこのタプルの長さと同じ数
      の引数で呼び出されます。C 呼び出し規約を使う関数は、追加の不特定
      の引数も取ります。

      When a foreign function is called, each actual argument is
      passed to the "from_param()" class method of the items in the
      "argtypes" tuple, this method allows adapting the actual
      argument to an object that the foreign function accepts.  For
      example, a "c_char_p" item in the "argtypes" tuple will convert
      a string passed as argument into a bytes object using ctypes
      conversion rules.

      New: It is now possible to put items in argtypes which are not
      ctypes types, but each item must have a "from_param()" method
      which returns a value usable as argument (integer, string,
      ctypes instance).  This allows defining adapters that can adapt
      custom objects as function parameters.

   errcheck

      Python 関数または他の呼び出し可能オブジェクトをこの属性に代入し
      ます。呼び出し可能オブジェクトは三つ以上の引数とともに呼び出され
      ます。

      callable(result, func, arguments)

         *result* is what the foreign function returns, as specified
         by the "restype" attribute.

         *func* は外部関数オブジェクト自身で、これにより複数の関数の処
         理結果をチェックまたは後処理するために、同じ呼び出し可能オブ
         ジェクトを再利用できるようになります。

         *arguments* は関数呼び出しに最初に渡されたパラメータが入った
         タプルです。これにより使われた引数に基づいた特別な振る舞いを
         させることができるようになります。

      この関数が返すオブジェクトは外部関数呼び出しから返された値でしょ
      う。しかし、戻り値をチェックして、外部関数呼び出しが失敗している
      なら例外を送出させることもできます。

On Windows, when a foreign function call raises a system exception
(for example, due to an access violation), it will be captured and
replaced with a suitable Python exception. Further, an auditing event
"ctypes.set_exception" with argument "code" will be raised, allowing
an audit hook to replace the exception with its own.

Some ways to invoke foreign function calls as well as some of the
functions in this module may raise an auditing event
"ctypes.call_function" with arguments "function pointer" and
"arguments".


関数プロトタイプ
----------------

外部関数は関数プロトタイプをインスタンス化することによって作成されます
。 関数プロトタイプは C の関数プロトタイプと似ています。実装は定義せず
に、関数 (返り値の型、引数の型、呼び出し規約) を記述します。 ファクト
リ関数は、その関数に要求される返り値の型と引数の型とともに呼び出されま
す。そしてこの関数はデコレータファクトリとしても使え、 "@wrapper" 構文
で他の関数に適用できます。 例については コールバック関数 を参照してく
ださい。

ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

   返された関数プロトタイプは標準 C 呼び出し規約をつかう関数を作成しま
   す。関数は呼び出されている間 GIL を解放します。 *use_errno* が真に
   設定されれば、呼び出しの前後で System 変数 "errno" の ctypesプライ
   ベートコピーは本当の "errno" の値と交換されます。 *use_last_error*
   も Windows エラーコードに対するのと同様です。

ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

   The returned function prototype creates functions that use the
   "stdcall" calling convention.  The function will release the GIL
   during the call.  *use_errno* and *use_last_error* have the same
   meaning as above.

   Availability: Windows

ctypes.PYFUNCTYPE(restype, *argtypes)

   返された関数プロトタイプは Python 呼び出し規約を使う関数を作成しま
   す。関数は呼び出されている間 GIL を解放 *しません*。

ファクトリ関数によって作られた関数プロトタイプは呼び出しのパラメータの
型と数に依存した別の方法でインスタンス化することができます。 :

prototype(address)

   指定されたアドレス(整数でなくてはなりません)の外部関数を返します。

prototype(callable)

   Python の *callable* から C の呼び出し可能関数(コールバック関数) を
   作成します。

prototype(func_spec[, paramflags])

   共有ライブラリがエクスポートしている外部関数を返します。
   *func_spec* は 2 要素タプル "(name_or_ordinal, library)" でなければ
   なりません。第一要素はエクスポートされた関数の名前である文字列、ま
   たはエクスポートされた関数の序数である小さい整数です。第二要素は共
   有ライブラリインスタンスです。

prototype(vtbl_index, name[, paramflags[, iid]])

   COM メソッドを呼び出す外部関数を返します。 *vtbl_index* は仮想関数
   テーブルのインデックスで、非負の小さい整数です。 *name* は COM メソ
   ッドの名前です。 *iid* はオプションのインターフェイス識別子へのポイ
   ンタで、拡張されたエラー情報の提供のために使われます。

   If *iid* is not specified, an "OSError" is raised if the COM method
   call fails. If *iid* is specified, a "COMError" is raised instead.

   COM methods use a special calling convention: They require a
   pointer to the COM interface as first argument, in addition to
   those parameters that are specified in the "argtypes" tuple.

   Availability: Windows

オプションの *paramflags* パラメータは上述した機能より多機能な外部関数
ラッパーを作成します。

*paramflags* must be a tuple of the same length as "argtypes".

このタプルの個々の要素はパラメータについてのより詳細な情報を持ち、 1
、 2 もしくは 3 要素を含むタプルでなければなりません。

第一要素はパラメータについてのフラグの組み合わせを含んだ整数です。

   1
      入力パラメータを関数に指定します。

   2
      出力パラメータ。外部関数が値を書き込みます。

   4
      デフォルトで整数ゼロになる入力パラメータ。

オプションの第二要素はパラメータ名の文字列です。これが指定された場合は
、外部関数を名前付きパラメータで呼び出すことができます。

オプションの第三要素はこのパラメータのデフォルト値です。

The following example demonstrates how to wrap the Windows
"MessageBoxW" function so that it supports default parameters and
named arguments. The C declaration from the windows header file is
this:

   WINUSERAPI int WINAPI
   MessageBoxW(
       HWND hWnd,
       LPCWSTR lpText,
       LPCWSTR lpCaption,
       UINT uType);

Here is the wrapping with "ctypes":

   >>> from ctypes import c_int, WINFUNCTYPE, windll
   >>> from ctypes.wintypes import HWND, LPCWSTR, UINT
   >>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)
   >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)
   >>> MessageBox = prototype(("MessageBoxW", windll.user32), paramflags)

これで外部関数の "MessageBox" を次のような方法で呼び出すことができるよ
うになりました:

   >>> MessageBox()
   >>> MessageBox(text="Spam, spam, spam")
   >>> MessageBox(flags=2, text="foo bar")

二番目の例は出力パラメータについて説明します。 win32 の
"GetWindowRect" 関数は、指定されたウィンドウの大きさを呼び出し側が与え
る "RECT" 構造体へコピーすることで取り出します。 C の宣言はこうです。:

   WINUSERAPI BOOL WINAPI
   GetWindowRect(
        HWND hWnd,
        LPRECT lpRect);

Here is the wrapping with "ctypes":

   >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
   >>> from ctypes.wintypes import BOOL, HWND, RECT
   >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
   >>> paramflags = (1, "hwnd"), (2, "lprect")
   >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
   >>>

出力パラメータを持つ関数は、単一のパラメータがある場合にはその出力パラ
メータ値を、複数のパラメータがある場合には出力パラメータ値が入ったタプ
ルを、それぞれ自動的に返します。そのため、GetWindowRect 関数は呼び出さ
れると RECT インスタンスを返します。

Output parameters can be combined with the "errcheck" protocol to do
further output processing and error checking.  The win32
"GetWindowRect" api function returns a "BOOL" to signal success or
failure, so this function could do the error checking, and raises an
exception when the api call failed:

   >>> def errcheck(result, func, args):
   ...     if not result:
   ...         raise WinError()
   ...     return args
   ...
   >>> GetWindowRect.errcheck = errcheck
   >>>

If the "errcheck" function returns the argument tuple it receives
unchanged, "ctypes" continues the normal processing it does on the
output parameters.  If you want to return a tuple of window
coordinates instead of a "RECT" instance, you can retrieve the fields
in the function and return them instead, the normal processing will no
longer take place:

   >>> def errcheck(result, func, args):
   ...     if not result:
   ...         raise WinError()
   ...     rc = args[1]
   ...     return rc.left, rc.top, rc.bottom, rc.right
   ...
   >>> GetWindowRect.errcheck = errcheck
   >>>


ユーティリティー関数
--------------------

ctypes.addressof(obj)

   メモリバッファのアドレスを示す整数を返します。 *obj* は ctypes 型の
   インスタンスでなければなりません。

   引数 "obj" を指定して 監査イベント "ctypes.addressof" を送出します
   。

ctypes.alignment(obj_or_type)

   ctypes 型のアライメントの必要条件を返します。 *obj_or_type* は
   ctypes 型またはインスタンスでなければなりません。

ctypes.byref(obj[, offset])

   *obj* (ctypes 型のインスタンスでなければならない) への軽量ポインタ
   を返します。 *offset* はデフォルトでは 0 で、内部ポインターへ加算さ
   れる整数です。

   "byref(obj, offset)" は、 C コードとしては、以下のようにみなされま
   す。:

      (((char *)&obj) + offset)

   返されるオブジェクトは外部関数呼び出しのパラメータとしてのみ使用で
   きます。"pointer(obj)" と似たふるまいをしますが、作成が非常に速く行
   えます。

ctypes.CopyComPointer(src, dst)

   Copies a COM pointer from *src* to *dst* and returns the Windows
   specific "HRESULT" value.

   If *src* is not "NULL", its "AddRef" method is called, incrementing
   the reference count.

   In contrast, the reference count of *dst* will not be decremented
   before assigning the new value. Unless *dst* is "NULL", the caller
   is responsible for decrementing the reference count by calling its
   "Release" method when necessary.

   Availability: Windows

   Added in version 3.14.

ctypes.cast(obj, type)

   この関数は C のキャスト演算子に似ています。*obj* と同じメモリブロッ
   クを指している *type* の新しいインスタンスを返します。*type* はポイ
   ンタ型でなければならず、*obj* はポインタとして解釈できるオブジェク
   トでなければなりません。

ctypes.create_string_buffer(init, size=None)
ctypes.create_string_buffer(size)

   この関数は変更可能な文字バッファを作成します。返されるオブジェクト
   は "c_char" の ctypes 配列です。

   If *size* is given (and not "None"), it must be an "int". It
   specifies the size of the returned array.

   If the *init* argument is given, it must be "bytes". It is used to
   initialize the array items. Bytes not initialized this way are set
   to zero (NUL).

   If *size* is not given (or if it is "None"), the buffer is made one
   element larger than *init*, effectively adding a NUL terminator.

   If both arguments are given, *size* must not be less than
   "len(init)".

   警告:

     If *size* is equal to "len(init)", a NUL terminator is not added.
     Do not treat such a buffer as a C string.

   例えば:

      >>> bytes(create_string_buffer(2))
      b'\x00\x00'
      >>> bytes(create_string_buffer(b'ab'))
      b'ab\x00'
      >>> bytes(create_string_buffer(b'ab', 2))
      b'ab'
      >>> bytes(create_string_buffer(b'ab', 4))
      b'ab\x00\x00'
      >>> bytes(create_string_buffer(b'abcdef', 2))
      Traceback (most recent call last):
         ...
      ValueError: byte string too long

   引数 "init", "size" を指定して 監査イベント
   "ctypes.create_string_buffer" を送出します。

ctypes.create_unicode_buffer(init, size=None)
ctypes.create_unicode_buffer(size)

   この関数は変更可能な Unicode 文字バッファを作成します。返されるオブ
   ジェクトは "c_wchar" の ctypes 配列です。

   The function takes the same arguments as "create_string_buffer()"
   except *init* must be a string and *size* counts "c_wchar".

   引数 "init", "size" を指定して 監査イベント
   "ctypes.create_unicode_buffer" を送出します。

ctypes.DllCanUnloadNow()

   This function is a hook which allows implementing in-process COM
   servers with ctypes.  It is called from the DllCanUnloadNow
   function that the _ctypes extension dll exports.

   Availability: Windows

ctypes.DllGetClassObject()

   This function is a hook which allows implementing in-process COM
   servers with ctypes.  It is called from the DllGetClassObject
   function that the "_ctypes" extension dll exports.

   Availability: Windows

ctypes.util.find_library(name)

   Try to find a library and return a pathname.  *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").  If no library can be found, returns "None".

   The exact functionality is system dependent.

   See 共有ライブラリを見つける for complete documentation.

ctypes.util.find_msvcrt()

   Returns the filename of the VC runtime library used by Python, and
   by the extension modules.  If the name of the library cannot be
   determined, "None" is returned.

   もし、例えば拡張モジュールにより割り付けられたメモリを "free(void
   *)" で解放する必要があるなら、メモリ割り付けを行ったのと同じライブ
   ラリの関数を使うことが重要です。

   Availability: Windows

ctypes.util.dllist()

   Try to provide a list of paths of the shared libraries loaded into
   the current process.  These paths are not normalized or processed
   in any way.  The function can raise "OSError" if the underlying
   platform APIs fail. The exact functionality is system dependent.

   On most platforms, the first element of the list represents the
   current executable file. It may be an empty string.

   Availability: Windows, macOS, iOS, glibc, BSD libc, musl

   Added in version 3.14.

ctypes.FormatError([code])

   Returns a textual description of the error code *code*.  If no
   error code is specified, the last error code is used by calling the
   Windows API function "GetLastError()".

   Availability: Windows

ctypes.GetLastError()

   Returns the last error code set by Windows in the calling thread.
   This function calls the Windows "GetLastError()" function directly,
   it does not return the ctypes-private copy of the error code.

   Availability: Windows

ctypes.get_errno()

   システムの "errno" 変数の、スレッドローカルなプライベートコピーを返
   します。

   引数無しで 監査イベント "ctypes.get_errno" を送出します。

ctypes.get_last_error()

   Returns the current value of the ctypes-private copy of the system
   "LastError" variable in the calling thread.

   Availability: Windows

   引数無しで 監査イベント "ctypes.get_last_error" を送出します。

ctypes.memmove(dst, src, count)

   標準 C の memmove ライブラリ関数と同じものです。: *count* バイトを
   *src* から *dst* へコピーします。 *dst* と *src* はポインタへ変換可
   能な整数または ctypes インスタンスでなければなりません。

ctypes.memset(dst, c, count)

   標準 C の memset ライブラリ関数と同じものです。: アドレス *dst* の
   メモリブロックを値 *c* を *count* バイト分書き込みます。 *dst* はア
   ドレスを指定する整数または ctypes インスタンスである必要があります
   。

ctypes.POINTER(type, /)

   Create or return a ctypes pointer type. Pointer types are cached
   and reused internally, so calling this function repeatedly is
   cheap. *type* must be a ctypes type.

   **CPython 実装の詳細:** The resulting pointer type is cached in the
   "__pointer_type__" attribute of *type*. It is possible to set this
   attribute before the first call to "POINTER" in order to set a
   custom pointer type. However, doing this is discouraged: manually
   creating a suitable pointer type is difficult without relying on
   implementation details that may change in future Python versions.

ctypes.pointer(obj, /)

   Create a new pointer instance, pointing to *obj*. The returned
   object is of the type "POINTER(type(obj))".

   注意: 外部関数呼び出しへオブジェクトへのポインタを渡したいだけなら
   、はるかに高速な "byref(obj)" を使うべきです。

ctypes.resize(obj, size)

   この関数は *obj* の内部メモリバッファのサイズを変更します。 *obj*
   は ctypes 型のインスタンスでなければなりません。バッファを
   "sizeof(type(obj))" で与えられるオブジェクト型の本来のサイズより小
   さくすることはできませんが、バッファを拡大することはできます。

ctypes.set_errno(value)

   システム変数 "errno" の、呼び出し元スレッドでの ctypes のプライベー
   トコピーの現在値を *value* に設定し、前の値を返します。

   引数 "errno" を指定して 監査イベント "ctypes.set_errno" を送出しま
   す。

ctypes.set_last_error(value)

   Sets the current value of the ctypes-private copy of the system
   "LastError" variable in the calling thread to *value* and return
   the previous value.

   Availability: Windows

   引数 "error" を指定して 監査イベント "ctypes.set_last_error" を送出
   します。

ctypes.sizeof(obj_or_type)

   ctypes の型やインスタンスのメモリバッファのサイズをバイト数で返しま
   す。C の "sizeof" 演算子と同様の動きをします。

ctypes.string_at(ptr, size=-1)

   Return the byte string at *void *ptr*. If *size* is specified, it
   is used as size, otherwise the string is assumed to be zero-
   terminated.

   Raises an auditing event "ctypes.string_at" with arguments "ptr",
   "size".

ctypes.WinError(code=None, descr=None)

   Creates an instance of "OSError".  If *code* is not specified,
   "GetLastError()" is called to determine the error code. If *descr*
   is not specified, "FormatError()" is called to get a textual
   description of the error.

   Availability: Windows

   バージョン 3.3 で変更: An instance of "WindowsError" used to be
   created, which is now an alias of "OSError".

ctypes.wstring_at(ptr, size=-1)

   Return the wide-character string at *void *ptr*. If *size* is
   specified, it is used as the number of characters of the string,
   otherwise the string is assumed to be zero-terminated.

   Raises an auditing event "ctypes.wstring_at" with arguments "ptr",
   "size".

ctypes.memoryview_at(ptr, size, readonly=False)

   Return a "memoryview" object of length *size* that references
   memory starting at *void *ptr*.

   If *readonly* is true, the returned "memoryview" object can not be
   used to modify the underlying memory. (Changes made by other means
   will still be reflected in the returned object.)

   This function is similar to "string_at()" with the key difference
   of not making a copy of the specified memory. It is a semantically
   equivalent (but more efficient) alternative to "memoryview((c_byte
   * size).from_address(ptr))". (While "from_address()" only takes
   integers, *ptr* can also be given as a "ctypes.POINTER" or a
   "byref()" object.)

   Raises an auditing event "ctypes.memoryview_at" with arguments
   "address", "size", "readonly".

   Added in version 3.14.


データ型
--------

class ctypes._CData

   この非公開クラスはすべての ctypes データ型の共通のベースクラスです
   。他のことはさておき、すべての ctypes 型インスタンスは C 互換データ
   を保持するメモリブロックを内部に持ちます。このメモリブロックのアド
   レスは "addressof()" ヘルパー関数が返します。別のインスタンス変数が
   "_objects" として公開されます。これはメモリブロックがポインタを含む
   場合に存続し続ける必要のある他の Python オブジェクトを含んでいます
   。

   ctypes データ型の共通メソッド、すべてのクラスメソッドが存在します (
   正確には、 *メタクラス* のメソッドです):

   from_buffer(source[, offset])

      このメソッドは *source* オブジェクトのバッファを共有する ctypes
      のインスタンスを返します。 *source* オブジェクトは書き込み可能バ
      ッファインターフェースをサポートしている必要があります。オプショ
      ンの *offset* 引数では *source* バッファのオフセットをバイト単位
      で指定します。デフォルトではゼロです。もし *source* バッファが十
      分に大きくなければ、 "ValueError" が送出されます。

      引数 "pointer", "size", "offset" を指定して 監査イベント
      "ctypes.cdata/buffer" を送出します。

   from_buffer_copy(source[, offset])

      このメソッドは *source* オブジェクトの読み出し可能バッファをコピ
      ーすることで、ctypes のインスタンスを生成します。オプションの
      *offset* 引数では *source* バッファのオフセットをバイト単位で指
      定します。デフォルトではゼロです。もし *source* バッファが十分に
      大きくなければ、 "ValueError" が送出されます。

      引数 "pointer", "size", "offset" を指定して 監査イベント
      "ctypes.cdata/buffer" を送出します。

   from_address(address)

      このメソッドは *address* で指定されたメモリを使って ctypes 型の
      インスタンスを返します。 *address* は整数でなければなりません。

      This method, and others that indirectly call this method, raises
      an auditing event "ctypes.cdata" with argument "address".

   from_param(obj)

      This method adapts *obj* to a ctypes type.  It is called with
      the actual object used in a foreign function call when the type
      is present in the foreign function's "argtypes" tuple; it must
      return an object that can be used as a function call parameter.

      すべての ctypes のデータ型は、それが型のインスタンスであれば、
      *obj* を返すこのクラスメソッドのデフォルトの実装を持ちます。いく
      つかの型は、別のオブジェクトも受け付けます。

   in_dll(library, name)

      このメソッドは、共有ライブラリによってエクスポートされた ctypes
      型のインスタンスを返します。 *name* はエクスポートされたデータの
      名前で、 *library* はロードされた共有ライブラリです。

   Common class variables of ctypes data types:

   __pointer_type__

      The pointer type that was created by calling "POINTER()" for
      corresponding ctypes data type. If a pointer type was not yet
      created, the attribute is missing.

      Added in version 3.14.

   ctypes データ型共通のインスタンス変数:

   _b_base_

      ctypes 型データのインスタンスは、それ自身のメモリブロックを持た
      ず、基底オブジェクトのメモリブロックの一部を共有することがありま
      す。 "_b_base_" 読み出し専用属性は、メモリブロックを保持する
      ctypes の基底オブジェクトです。

   _b_needsfree_

      この読み出し専用の変数は、 ctypes データインスタンスが、それ自身
      に割り当てられたメモリブロックを持つとき true になります。それ以
      外の場合は false になります。

   _objects

      このメンバは "None" 、または、メモリブロックの内容が正しく保つた
      めに、生存させておかなくてはならない Python オブジェクトを持つデ
      ィクショナリです。このオブジェクトはデバッグでのみ使われます。決
      してディクショナリの内容を変更しないで下さい。


基本データ型
------------

class ctypes._SimpleCData

   この非公開クラスは、全ての基本的な ctypes データ型の基底クラスです
   。これは基本的な ctypes データ型に共通の属性を持っているので、ここ
   で触れておきます。 "_SimpleCData" は "_CData" の子クラスなので、そ
   のメソッドと属性を継承しています。ポインタでないかポインタを含まな
   い ctypes データ型は、現在は pickle 化できます。

   インスタンスは一つだけ属性を持ちます:

   value

      この属性は、インスタンスの実際の値を持ちます。整数型とポインタ型
      に対しては整数型、文字型に対しては一文字のバイト列オブジェクト、
      文字へのポインタに対しては Python のバイト列オブジェクトもしくは
      文字列となります。

      When the "value" attribute is retrieved from a ctypes instance,
      usually a new object is returned each time.  "ctypes" does *not*
      implement original object return, always a new object is
      constructed.  The same is true for all other ctypes object
      instances.

   Each subclass has a class attribute:

   _type_

      Class attribute that contains an internal type code, as a
      single-character string. See 基本データ型 for a summary.

      Types marked * in the summary may be (or always are) aliases of
      a different "_SimpleCData" subclass, and will not necessarily
      use the listed type code. For example, if the platform's long,
      long long and time_t C types are the same, then "c_long",
      "c_longlong" and "c_time_t" all refer to a single class,
      "c_long", whose "_type_" code is "'l'". The "'L'" code will be
      unused.

      参考:

        The "array" and struct modules, as well as third-party modules
        like numpy, use similar -- but slightly different -- type
        codes.

Fundamental data types, when returned as foreign function call
results, or, for example, by retrieving structure field members or
array items, are transparently converted to native Python types.  In
other words, if a foreign function has a "restype" of "c_char_p", you
will always receive a Python bytes object, *not* a "c_char_p"
instance.

Subclasses of fundamental data types do *not* inherit this behavior.
So, if a foreign functions "restype" is a subclass of "c_void_p", you
will receive an instance of this subclass from the function call. Of
course, you can get the value of the pointer by accessing the "value"
attribute.

これらが基本 ctypes データ型です:

class ctypes.c_byte

   C の signed char データ型を表し、小整数として値を解釈します。コンス
   トラクタはオプションの整数初期化子を受け取ります。オーバーフローの
   チェックは行われません。

class ctypes.c_char

   C char データ型を表し、単一の文字として値を解釈します。コンストラク
   タはオプションの文字列初期化子を受け取り、その文字列の長さちょうど
   一文字である必要があります。

class ctypes.c_char_p

   C char* データ型を表し、ゼロ終端文字列へのポインタでなければなりま
   せん。バイナリデータを指す可能性のある一般的なポインタに対しては
   "POINTER(c_char)" を使わなければなりません。コンストラクタは整数の
   アドレスもしくはバイト列オブジェクトを受け取ります。

class ctypes.c_double

   C double データ型を表します。コンストラクタはオプションの浮動小数点
   数初期化子を受け取ります。

class ctypes.c_longdouble

   C long double データ型を表します。コンストラクタはオプションで浮動
   小数点数初期化子を受け取ります。 "sizeof(long double) ==
   sizeof(double)" であるプラットフォームでは "c_double" の別名です。

class ctypes.c_float

   C float データ型を表します。コンストラクタはオプションの浮動小数点
   数初期化子を受け取ります。

class ctypes.c_double_complex

   Represents the C double complex datatype, if available.  The
   constructor accepts an optional "complex" initializer.

   Added in version 3.14.

class ctypes.c_float_complex

   Represents the C float complex datatype, if available.  The
   constructor accepts an optional "complex" initializer.

   Added in version 3.14.

class ctypes.c_longdouble_complex

   Represents the C long double complex datatype, if available.  The
   constructor accepts an optional "complex" initializer.

   Added in version 3.14.

class ctypes.c_int

   C signed int データ型を表します。コンストラクタはオプションの整数初
   期化子を受け取ります。オーバーフローのチェックは行われません。
   "sizeof(int) == sizeof(long)" であるプラットフォームでは、 "c_long"
   の別名です。

class ctypes.c_int8

   Represents the C 8-bit signed int datatype.  It is an alias for
   "c_byte".

class ctypes.c_int16

   C 16-bit signed int データ型を表します。たいていは、 "c_short" の別
   名です。

class ctypes.c_int32

   C 32-bit signed int データ型を表します。たいていは、 "c_int" の別名
   です。

class ctypes.c_int64

   C 64-bit signed int データ型を表します。たいていは、 "c_longlong"
   の別名です。

class ctypes.c_long

   C signed long データ型を表します。コンストラクタはオプションの整数
   初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_longlong

   Represents the C signed long long datatype.  The constructor
   accepts an optional integer initializer; no overflow checking is
   done. On platforms where "sizeof(long long) == sizeof(long)" it is
   an alias to "c_long".

class ctypes.c_short

   C signed short データ型を表します。コンストラクタはオプションの整数
   初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_size_t

   Represents the C "size_t" datatype. Usually an alias for another
   unsigned integer type.

class ctypes.c_ssize_t

   Represents the "Py_ssize_t" datatype. This is a signed version of
   "size_t"; that is, the POSIX "ssize_t" type. Usually an alias for
   another integer type.

   Added in version 3.2.

class ctypes.c_time_t

   Represents the C "time_t" datatype. Usually an alias for another
   integer type.

   Added in version 3.12.

class ctypes.c_ubyte

   C の unsigned char データ型を表し、小さな整数として値を解釈します。
   コンストラクタはオプションの整数初期化子を受け取ります; オーバーフ
   ローのチェックは行われません。

class ctypes.c_uint

   C の  unsigned int データ型を表します。コンストラクタはオプションの
   整数初期化子を受け取ります; オーバーフローのチェックは行われません
   。これは、 "sizeof(int) == sizeof(long)" であるプラットフォームでは
   "c_ulong" の別名です。

class ctypes.c_uint8

   Represents the C 8-bit unsigned int datatype.  It is an alias for
   "c_ubyte".

class ctypes.c_uint16

   C 16-bit unsigned int データ型を表します。たいていは、 "c_ushort"
   の別名です。

class ctypes.c_uint32

   C 32-bit unsigned int データ型を表します。たいていは、 "c_uint" の
   別名です。

class ctypes.c_uint64

   C 64-bit unsigned int データ型を表します。たいていは、
   "c_ulonglong" の別名です。

class ctypes.c_ulong

   C unsigned long データ型を表します。コンストラクタはオプションの整
   数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_ulonglong

   Represents the C unsigned long long datatype.  The constructor
   accepts an optional integer initializer; no overflow checking is
   done. On platforms where "sizeof(long long) == sizeof(long)" it is
   an alias to "c_long".

class ctypes.c_ushort

   C unsigned short データ型を表します。コンストラクタはオプションの整
   数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_void_p

   C void* データ型を表します。値は整数として表されます。コンストラク
   タはオプションの整数初期化子を受け取ります。

class ctypes.c_wchar

   C "wchar_t" データ型を表し、値は Unicode 文字列の単一の文字として解
   釈されます。コンストラクタはオプションの文字列初期化子を受け取り、
   その文字列の長さはちょうど一文字である必要があります。

class ctypes.c_wchar_p

   C wchar_t* データ型を表し、ゼロ終端ワイド文字列へのポインタでなけれ
   ばなりません。コンストラクタは整数のアドレスもしくは文字列を受け取
   ります。

class ctypes.c_bool

   C の bool データ型 (より正確には、 C99 以降の  _Bool) を表します。
   "True" または "False" の値を持ち、コンストラクタは真偽値と解釈でき
   るオブジェクトを受け取ります。

class ctypes.HRESULT

   Represents a "HRESULT" value, which contains success or error
   information for a function or method call.

   Availability: Windows

class ctypes.py_object

   C PyObject* データ型を表します。引数なしでこれを呼び出すと "NULL"
   PyObject* ポインタを作成します。

   バージョン 3.14 で変更: "py_object" is now a *generic type*.

The "ctypes.wintypes" module provides quite some other Windows
specific data types, for example "HWND", "WPARAM", "VARIANT_BOOL" or
"DWORD". Some useful structures like "MSG" or "RECT" are also defined.


構造化データ型
--------------

class ctypes.Union(*args, **kw)

   ネイティブのバイトオーダーでの共用体のための抽象ベースクラス。

   Unions share common attributes and behavior with structures; see
   "Structure" documentation for details.

class ctypes.BigEndianUnion(*args, **kw)

   *ビックエンディアン* バイトオーダーでの共用体のための抽象ベースクラ
   ス。

   Added in version 3.11.

class ctypes.LittleEndianUnion(*args, **kw)

   *リトルエンディアン* バイトオーダーでの共用体のための抽象ベースクラ
   ス。

   Added in version 3.11.

class ctypes.BigEndianStructure(*args, **kw)

   *ビックエンディアン* バイトオーダーでの構造体のための抽象ベースクラ
   ス。

class ctypes.LittleEndianStructure(*args, **kw)

   *リトルエンディアン* バイトオーダーでの構造体のための抽象ベースクラ
   ス。

ネイティブではないバイトオーダーを持つ構造体および共用体にポインタ型フ
ィールドあるいはポインタ型フィールドを含む他のどんなデータ型をも入れる
ことはできません。

class ctypes.Structure(*args, **kw)

   *ネイティブ* のバイトオーダーでの構造体のための抽象ベースクラス。

   Concrete structure and union types must be created by subclassing
   one of these types, and at least define a "_fields_" class
   variable. "ctypes" will create *descriptor*s which allow reading
   and writing the fields by direct attribute accesses.  These are the

   _fields_

      構造体のフィールドを定義するシーケンス。要素は2要素タプルか3要素
      タプルでなければなりません。第一要素はフィールドの名前です。第二
      要素はフィールドの型を指定します。それはどんな ctypes データ型で
      も構いません。

      "c_int" のような整数型のために、オプションの第三要素を与えること
      ができます。フィールドのビット幅を定義する正の小整数である必要が
      あります。

      一つの構造体と共用体の中で、フィールド名はただ一つである必要があ
      ります。これはチェックされません。名前が繰り返しでてきたときにア
      クセスできるのは一つのフィールドだけです。

      Structure サブクラスを定義するクラス文の *後で* 、 "_fields_" ク
      ラス変数を定義することができます。これにより、次のように自身を直
      接または間接的に参照するデータ型を作成できるようになります:

         class List(Structure):
             pass
         List._fields_ = [("pnext", POINTER(List)),
                          ...
                         ]

      The "_fields_" class variable can only be set once. Later
      assignments will raise an "AttributeError".

      Additionally, the "_fields_" class variable must be defined
      before the structure or union type is first used: an instance or
      subclass is created, "sizeof()" is called on it, and so on.
      Later assignments to "_fields_" will raise an "AttributeError".
      If "_fields_" has not been set before such use, the structure or
      union will have no own fields, as if "_fields_" was empty.

      Sub-subclasses of structure types inherit the fields of the base
      class plus the "_fields_" defined in the sub-subclass, if any.

   _pack_

      An optional small integer that allows overriding the alignment
      of structure fields in the instance.

      This is only implemented for the MSVC-compatible memory layout
      (see "_layout_").

      Setting "_pack_" to 0 is the same as not setting it at all.
      Otherwise, the value must be a positive power of two. The effect
      is equivalent to "#pragma pack(N)" in C, except "ctypes" may
      allow larger *n* than what the compiler accepts.

      "_pack_" must already be defined when "_fields_" is assigned,
      otherwise it will have no effect.

      バージョン 3.14 で非推奨、バージョン 3.19 で削除予定: For
      historical reasons, if "_pack_" is non-zero, the MSVC-compatible
      layout will be used by default. On non-Windows platforms, this
      default is deprecated and is slated to become an error in Python
      3.19. If it is intended, set "_layout_" to "'ms'" explicitly.

   _align_

      An optional small integer that allows increasing the alignment
      of the structure when being packed or unpacked to/from memory.

      The value must not be negative. The effect is equivalent to
      "__attribute__((aligned(N)))" on GCC or "#pragma align(N)" on
      MSVC, except "ctypes" may allow values that the compiler would
      reject.

      "_align_" can only *increase* a structure's alignment
      requirements. Setting it to 0 or 1 has no effect.

      Using values that are not powers of two is discouraged and may
      lead to surprising behavior.

      "_align_" must already be defined when "_fields_" is assigned,
      otherwise it will have no effect.

      Added in version 3.13.

   _layout_

      An optional string naming the struct/union layout. It can
      currently be set to:

      * ""ms"": the layout used by the Microsoft compiler (MSVC). On
        GCC and Clang, this layout can be selected with
        "__attribute__((ms_struct))".

      * ""gcc-sysv"": the layout used by GCC with the System V or
        “SysV-like” data model, as used on Linux and macOS. With this
        layout, "_pack_" must be unset or zero.

      If not set explicitly, "ctypes" will use a default that matches
      the platform conventions. This default may change in future
      Python releases (for example, when a new platform gains official
      support, or when a difference between similar platforms is
      found). Currently the default will be:

      * On Windows: ""ms""

      * When "_pack_" is specified: ""ms"". (This is deprecated; see
        "_pack_" documentation.)

      * Otherwise: ""gcc-sysv""

      "_layout_" must already be defined when "_fields_" is assigned,
      otherwise it will have no effect.

      Added in version 3.14.

   _anonymous_

      無名 (匿名) フィールドの名前が並べあげられたオプションのシーケン
      ス。 "_fields_" が代入されたとき、 "_anonymous_" がすでに定義さ
      れていなければなりません。そうでなければ、何ら影響はありません。

      The fields listed in this variable must be structure or union
      type fields. "ctypes" will create descriptors in the structure
      type that allows accessing the nested fields directly, without
      the need to create the structure or union field.

      型の例です (Windows):

         class _U(Union):
             _fields_ = [("lptdesc", POINTER(TYPEDESC)),
                         ("lpadesc", POINTER(ARRAYDESC)),
                         ("hreftype", HREFTYPE)]

         class TYPEDESC(Structure):
             _anonymous_ = ("u",)
             _fields_ = [("u", _U),
                         ("vt", VARTYPE)]

      "TYPEDESC" 構造体はCOMデータ型を表現しており、 "vt" フィールドは
      共用体フィールドのどれが有効であるかを指定します。 "u" フィール
      ドは匿名フィールドとして定義されているため、 TYPEDESC インスタン
      スから取り除かれてそのメンバーへ直接アクセスできます。
      "td.lptdesc" と "td.u.lptdesc" は同等ですが、前者がより高速です
      。なぜなら一時的な共用体インスタンスを作る必要がないためです。:

         td = TYPEDESC()
         td.vt = VT_PTR
         td.lptdesc = POINTER(some_type)
         td.u.lptdesc = POINTER(some_type)

   構造体のサブクラスのサブクラスを定義することができ、基底クラスのフ
   ィールドを継承します。 サブクラス定義に別の "_fields_" 変数がある場
   合は、この中で指定されたフィールドは基底クラスのフィールドへ追加さ
   れます。

   構造体と共用体のコンストラクタは位置引数とキーワード引数の両方を受
   け取ります。位置引数は "_fields_" の中に現れたのと同じ順番でメンバ
   ーフィールドを初期化するために使われます。コンストラクタのキーワー
   ド引数は属性代入として解釈され、そのため、同じ名前をもつ "_fields_"
   を初期化するか、 "_fields_" に存在しない名前に対しては新しい属性を
   作ります。

class ctypes.CField(*args, **kw)

   Descriptor for fields of a "Structure" and "Union". For example:

      >>> class Color(Structure):
      ...     _fields_ = (
      ...         ('red', c_uint8),
      ...         ('green', c_uint8),
      ...         ('blue', c_uint8),
      ...         ('intense', c_bool, 1),
      ...         ('blinking', c_bool, 1),
      ...    )
      ...
      >>> Color.red
      <ctypes.CField 'red' type=c_ubyte, ofs=0, size=1>
      >>> Color.green.type
      <class 'ctypes.c_ubyte'>
      >>> Color.blue.byte_offset
      2
      >>> Color.intense
      <ctypes.CField 'intense' type=c_bool, ofs=3, bit_size=1, bit_offset=0>
      >>> Color.blinking.bit_offset
      1

   All attributes are read-only.

   "CField" objects are created via "_fields_"; do not instantiate the
   class directly.

   Added in version 3.14: Previously, descriptors only had "offset"
   and "size" attributes and a readable string representation; the
   "CField" class was not available directly.

   name

      Name of the field, as a string.

   type

      Type of the field, as a ctypes class.

   offset
   byte_offset

      Offset of the field, in bytes.

      For bitfields, this is the offset of the underlying byte-aligned
      *storage unit*; see "bit_offset".

   byte_size

      Size of the field, in bytes.

      For bitfields, this is the size of the underlying *storage
      unit*. Typically, it has the same size as the bitfield's type.

   size

      For non-bitfields, equivalent to "byte_size".

      For bitfields, this contains a backwards-compatible bit-packed
      value that combines "bit_size" and "bit_offset". Prefer using
      the explicit attributes instead.

   is_bitfield

      True if this is a bitfield.

   bit_offset
   bit_size

      The location of a bitfield within its *storage unit*, that is,
      within "byte_size" bytes of memory starting at "byte_offset".

      To get the field's value, read the storage unit as an integer,
      shift left by "bit_offset" and take the "bit_size" least
      significant bits.

      For non-bitfields, "bit_offset" is zero and "bit_size" is equal
      to "byte_size * 8".

   is_anonymous

      True if this field is anonymous, that is, it contains nested
      sub-fields that should be merged into a containing structure or
      union.


配列とポインタ
--------------

class ctypes.Array(*args)

   配列のための抽象基底クラスです。

   The recommended way to create concrete array types is by
   multiplying any "ctypes" data type with a non-negative integer.
   Alternatively, you can subclass this type and define "_length_" and
   "_type_" class variables. Array elements can be read and written
   using standard subscript and slice accesses; for slice reads, the
   resulting object is *not* itself an "Array".

   Arrays are generic over the type of their elements.

   _length_

      配列の要素数を指定する正の整数。範囲外の添え字を指定すると、
      "IndexError" が送出されます。"len()" がこの整数を返します。

   _type_

      配列内の各要素の型を指定します。

   配列のサブクラスのコンストラクタは、位置引数を受け付けて、配列を順
   番に初期化するために使用します。

ctypes.ARRAY(type, length)

   Create an array. Equivalent to "type * length", where *type* is a
   "ctypes" data type and *length* an integer.

   Soft deprecated since version 3.14: In favor of multiplication.

class ctypes._Pointer

   ポインタのためのプライベートな抽象基底クラスです。

   具象ポインタ型は、ポイント先の型を持つ "POINTER()" を呼び出すことで
   、作成できます。これは、 "pointer()" により自動的に行われます。

   ポインタが配列を指す場合、その配列の要素は、標準の添え字とスライス
   によるアクセスを使用して読み書きが行えます。ポインタオブジェクトに
   は、サイズがないため、 "len()" 関数は "TypeError" を送出します。負
   の添え字は、(C と同様に) ポインタの *前* のメモリから読み込み、範囲
   外の添え字はおそらく (幸運な場合でも) アクセス違反によりクラッシュ
   を起こします。

   _type_

      ポイント先の型を指定します。

   contents

      ポインタが指すオブジェクトを返します。この属性に割り当てると、ポ
      インタが割り当てられたオブジェクトを指すようになります。


例外
----

exception ctypes.ArgumentError

   この例外は外部関数呼び出しが渡された引数を変換できなかったときに送
   出されます。

exception ctypes.COMError(hresult, text, details)

   This exception is raised when a COM method call failed.

   hresult

      The integer value representing the error code.

   text

      The error message.

   details

      The 5-tuple "(descr, source, helpfile, helpcontext, progid)".

      *descr* is the textual description.  *source* is the language-
      dependent "ProgID" for the class or application that raised the
      error.  *helpfile* is the path of the help file.  *helpcontext*
      is the help context identifier.  *progid* is the "ProgID" of the
      interface that defined the error.

   Availability: Windows

   Added in version 3.14.
