`ctypes` --- Python 用の外部関数ライブラリ¶

ソースコード: Lib/ctypes

ctypes は Python 用の外部関数ライブラリです。 C と互換性のあるデータ型を提供し、DLL や共有ライブラリの関数を呼び出せます。これらのライブラリを純粋な Python でラップするために使えます。

これは optional module です。お使いの CPython に含まれていない場合は、配布元 (Python を提供した組織や個人) のドキュメントを確認してください。配布する側の場合は、オプションのモジュールの要件を参照してください。

警告

ctypes は、Python の安全機構を迂回してネイティブライブラリやプロセスのメモリに低水準でアクセスし、任意のネイティブコードを実行できるようにします。使い方を誤ると、データやオブジェクトの破損、機密情報の漏えい、クラッシュなど、実行中のプロセスの安全性を損なう事態を引き起こす可能性があります。

ctypes チュートリアル¶

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

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

ctypes は、動的リンクライブラリをロードするための cdll オブジェクトをエクスポートします。 Windows では windll と oledll オブジェクトもエクスポートします。

これらのオブジェクトの属性にアクセスすると、ライブラリをロードできます。 cdll は標準の cdecl 呼び出し規約で関数をエクスポートするライブラリをロードし、windll のライブラリは stdcall 呼び出し規約で関数を呼び出します。 oledll も stdcall 呼び出し規約を使用し、関数が Windows の HRESULT エラーコードを返すと仮定します。関数呼び出しが失敗した場合は、このエラーコードを使って OSError 例外を自動的に送出します。

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

Windows での例を示します。 msvcrt は、標準 C 関数の大半を含む MS 標準 C ライブラリで、cdecl 呼び出し規約を使用します。

>>> 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 モジュールをインポートして使用してください。

ほかのシステムでは、ライブラリのロードに拡張子を含むファイル名が必要なため、属性へのアクセスではロードできません。 DLL ローダーの LoadLibrary() メソッドを使うか、コンストラクタを呼び出して CDLL インスタンスを作成し、ライブラリをロードしてください。

例えば、Linux では次のようにします。

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

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
>>>

kernel32 や user32 などの win32 システム DLL は、関数の ANSI 版と UNICODE 版を両方エクスポートすることがよくあります。 UNICODE 版は名前の末尾に W、ANSI 版は A を付けてエクスポートされます。指定したモジュール名の モジュールハンドル を返す win32 の GetModuleHandle 関数には、以下の C プロトタイプがあります。 UNICODE が定義されているかどうかに応じて、マクロが一方を GetModuleHandle として公開します。

/* ANSI 版 */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE 版 */
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
>>>

関数を呼び出す¶

これらの関数は、ほかの Python の呼び出し可能オブジェクトと同じように呼び出せます。この例では、引数を取らず疑似乱数の整数を返す rand() 関数を使います。

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

Windows では、win32 モジュールハンドルを返す GetModuleHandleA() 関数を呼び出せます (唯一の引数に None を渡すと、NULL ポインタを渡して呼び出せます)。

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

ctypes は関数の呼び出し規約やシグネチャを判定できません。関数の C ヘッダーファイルやドキュメントを確認して正しい呼び出し規約を選び、要求される引数の型を指定する (関数プロトタイプ) で説明する argtypes 属性を設定してください。 argtypes を指定しないと、引数の数は検査されません。誤った呼び出し規約や引数で関数を呼び出すと、メモリが破損したり Python がクラッシュしたりする可能性があります。

Windows では、ctypes は win32 の構造化例外処理を使い、無効な引数の値で関数を呼び出した際の一般保護違反によるクラッシュを防ぎます。

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

faulthandler モジュールは、C ライブラリの誤った呼び出しによるセグメンテーション違反などのクラッシュのデバッグに役立ちます。

これらの関数呼び出しに引数として直接渡せる Python 標準のオブジェクトは、None、整数、バイト列オブジェクト、(Unicode) 文字列だけです。 None は C の NULL ポインタとして渡され、バイト列オブジェクトと文字列は、データを格納するメモリブロックへのポインタ (char* または wchar_t*) として渡されます。 Python の整数は、プラットフォームのデフォルトの C int 型として渡され、その C 型に収まるよう値がマスクされます。

ほかの型の引数を使って関数を呼び出す前に、ctypes のデータ型を詳しく見ておく必要があります。

基本データ型¶

ctypes は、C と互換性のある基本データ型をいくつも定義しています:

ctypes の型	C の型	Python の型	`_type_`
`c_bool`	_Bool	`bool`	`'?'`
`c_char`	char	1 文字の `bytes`	`'c'`
`c_wchar`	`wchar_t`	1 文字の `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` または `None`	`'z'`
`c_wchar_p`	wchar_t* (NUL 終端)	`str` または `None`	`'Z'`
`c_void_p`	void*	`int` または `None`	`'P'`
`py_object`	PyObject*	`object`	`'O'`
VARIANT_BOOL	short int	`bool`	`'v'`

さらに、C と libffi の両方が IEC 60559 に準拠した複素数演算 (附属書 G) をサポートする場合、以下の複素数型を利用できます:

ctypes の型	C の型	Python の型	`_type_`
`c_float_complex`	float complex	`complex`	`'Zf'`
`c_double_complex`	double complex	`complex`	`'Zd'`
`c_longdouble_complex`	long double complex	`complex`	`'Zg'`

バージョン 3.15 で変更: _type_ の型 F、D、G は、Zf、Zd、Zg に置き換えられました。

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

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

数値型のコンストラクタは、__bool__()、__index__() (int の場合)、__float__()、__complex__() を使って入力を変換します。したがって、c_bool は真偽値を持つ任意のオブジェクトを受け付けます。

>>> 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
>>>

ポインタ型 c_char_p、c_wchar_p、c_void_p のインスタンスに新しい値を代入すると、そのポインタが指す メモリ位置 が変わり、メモリブロックの 内容は変わりません (Python の文字列オブジェクトは不変なので、当然の動作です)。

>>> 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)            # NUL バイトで初期化した 3 バイトのバッファを作成します
>>> print(sizeof(p), repr(p.raw))
3 b'\x00\x00\x00'
>>> p = create_string_buffer(b"Hello")     # NUL 終端文字列を含むバッファを作成します
>>> print(sizeof(p), repr(p.raw))
6 b'Hello\x00'
>>> print(repr(p.value))
b'Hello'
>>> p = create_string_buffer(b"Hello", 10) # 10 バイトのバッファを作成します
>>> 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'
>>>

create_string_buffer() 関数は、古い c_buffer() 関数を置き換えるものです (後者は別名として引き続き利用できます)。 C の wchar_t 型の Unicode 文字を格納する変更可能なメモリブロックを作成するには、create_unicode_buffer() 関数を使ってください。

続・関数を呼び出す¶

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
>>>

前述のとおり、整数、文字列、バイト列オブジェクト以外の Python の型は、必要な C のデータ型に変換できるよう、対応する ctypes の型でラップする必要があります。

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

可変長引数関数の呼び出し¶

多くのプラットフォームでは、ctypes を使った可変長引数関数の呼び出し方は、引数の数が固定の関数とまったく同じです。一部のプラットフォーム、特に Apple プラットフォームの ARM64 では、可変長引数関数の呼び出し規約が通常の関数とは異なります。

それらのプラットフォームでは、可変長ではない通常の引数について argtypes 属性を指定する必要があります:

libc.printf.argtypes = [ctypes.c_char_p]

この属性の指定は移植性を損なわないため、すべての可変長引数関数について常に argtypes を指定することを推奨します。

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

ctypes の引数変換をカスタマイズして、自作クラスのインスタンスを関数の引数として使うこともできます。 ctypes は _as_parameter_ 属性を探し、その値を関数の引数として使用します。この属性は、整数、文字列、バイト列、ctypes のインスタンス、または _as_parameter_ 属性を持つオブジェクトでなければなりません。

>>> 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
>>>

インスタンスのデータを _as_parameter_ インスタンス変数に保存したくない場合は、アクセス時に属性値を提供する @property を定義できます。

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

DLL がエクスポートする関数の引数に必要な型は、argtypes 属性を設定して指定できます。

argtypes は C のデータ型のシーケンスでなければなりません (printf() 関数は、書式文字列に応じて引数の数や型が変わるので、ここでは良い例とはいえませんが、この機能を試すには便利です)。

>>> 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
>>>

argtypes を設定すると、渡された引数が少なすぎる場合に ctypes が TypeError を送出するようにもなります。

>>> printf(b"%s %d %f\n", b"X", 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: this function takes at least 4 arguments (3 given)

stdcall 呼び出し規約を使う関数には、argtypes の要素数とまったく同じ数の引数が必要です。 cdecl 呼び出し規約を使う関数は、可変長引数関数をサポートするため、追加の引数を受け付けます。宣言は関数の実際のシグネチャに一致する必要がありますが、ctypes はそれを検証できません。

関数呼び出しに渡すための独自クラスを定義した場合、そのクラスを argtypes シーケンスで使うには from_param() クラスメソッドを実装する必要があります。 from_param() クラスメソッドは、関数呼び出しに渡された Python オブジェクトを受け取ります。型検査など、オブジェクトを受け付けられることを確認するための処理を行い、オブジェクト自身、その _as_parameter_ 属性、または C 関数の引数として渡したい値を返してください。この場合も、戻り値は整数、文字列、バイト列、ctypes のインスタンス、または _as_parameter_ 属性を持つオブジェクトである必要があります。

戻り値の型¶

デフォルトでは、関数は C の int 型を返すと仮定します。関数オブジェクトの restype 属性を設定すれば、ほかの戻り値の型を指定できます。

time() の C プロトタイプは time_t time(time_t *) です。 time_t は、デフォルトの戻り値の型 int と異なる場合があるため、restype 属性を指定する必要があります。

>>> libc.time.restype = c_time_t

引数の型は argtypes を使って指定できます。

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

第 1 引数に NULL ポインタを渡して関数を呼び出すには、None を使います。

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

もう少し高度な例として、文字列へのポインタと char を受け取り、文字列へのポインタを返す strchr() 関数を使います。

>>> 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
>>>

上の例の ord("x") の呼び出しを省くには、argtypes 属性を設定します。これにより、第 2 引数が 1 文字の Python バイト列オブジェクトから 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'
>>>

外部関数が整数を返す場合、restype 属性に、関数やクラスなどの Python の呼び出し可能オブジェクトを使うこともできます。 C 関数が返した整数を引数としてそのオブジェクトが呼び出され、その結果が関数呼び出しの結果として使われます。これは、戻り値のエラーを検査して例外を自動的に送出するのに役立ちます。

>>> 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() を呼び出します。

errcheck 属性を使うと、さらに強力なエラー検査の仕組みを利用できます。詳細はリファレンスマニュアルを参照してください。

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

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

ctypes は、引数を参照渡しするための byref() 関数をエクスポートします。 pointer() 関数でも同じ効果を得られますが、pointer() は実際のポインタオブジェクトを構築するため、より多くの処理を行います。 Python 側でポインタオブジェクト自体が必要なければ、byref() の方が高速です。

>>> 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'
>>>

構造体と共用体¶

構造体と共用体は、ctypes モジュールが定義する Structure と Union の基底クラスから派生させる必要があります。各サブクラスには _fields_ 属性を定義する必要があります。 _fields_ は、フィールド名 と フィールドの型 を含む 2 要素のタプル のリストでなければなりません。

フィールドの型は、c_int などの ctypes の型、または構造体、共用体、配列、ポインタなど、ほかの派生した ctypes の型でなければなりません。

以下は、 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))

フィールドの descriptor は クラス から取得でき、有用な情報を提供するためデバッグに役立ちます。 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 は、共用体やビットフィールドを持つ構造体を関数に値渡しすることをサポートしていません。 32 ビットの x86 では動作することもありますが、一般に動作することはライブラリでは保証していません。共用体やビットフィールドを持つ構造体は、常にポインタとして関数に渡してください。

構造体と共用体のレイアウト、アラインメント、バイト順序¶

デフォルトでは、Structure と Union のフィールドは C コンパイラと同じ方法で配置されます。サブクラス定義で _layout_ クラス属性を指定すれば、この動作を完全に上書きできます。詳細はこの属性のドキュメントを参照してください。

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 は、構造体と共用体にネイティブのバイト順序を使用します。ネイティブでないバイト順序の構造体を作るには、BigEndianStructure、LittleEndianStructure、BigEndianUnion、LittleEndianUnion のいずれかを基底クラスとして使えます。これらのクラスにはポインタフィールドを含められません。

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

ビットフィールドを含む構造体や共用体も作成できます。ビットフィールドにできるのは整数フィールドだけで、ビット幅は _fields_ のタプルの第 3 要素として指定します。

>>> 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>

ビットフィールドのメモリ内での割り当てやレイアウトは C 標準では定義されておらず、コンパイラ固有の実装であることに注意してください。デフォルトでは、Python は現在のプラットフォームの「ネイティブ」コンパイラの動作に合わせようとします。デフォルトの動作とその変更方法については、_layout_ 属性を参照してください。

配列¶

配列 (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
>>>

ポインタ¶

ctypes の型のオブジェクトに対して pointer() 関数を呼び出すと、ポインタインスタンスが作成されます。

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

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

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

ctypes は OOR (元のオブジェクトを返すこと) を行いません。属性を取得するたびに、同等の新しいオブジェクトを構築します。

>>> 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 関数からポインタを受け取り、そのポインタが単一の要素ではなく実際に配列を指していると 分かっている 場合だけです。

警告

ポインタオブジェクトは添字付けをサポートするため、暗黙に反復もサポートします。ただし、pointer() のイテレータに対して next() を手動で呼び出すなど、制御しながら使わないと、通常は無限ループやクラッシュを引き起こします。 ctypes には反復をどこで終了すればよいか判断する方法がないためです。つまり、pointer のイテレータは任意のメモリの内容を際限なく yield します。

pointer() 関数は、内部では単にポインタインスタンスを作るだけでなく、まずポインタの型を作る必要があります。これには、任意の ctypes の型を受け取り、新しい型を返す POINTER() 関数を使います。

>>> 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 は、ポインタを参照外しする際に NULL かどうかを検査します (ただし、NULL でない無効なポインタを参照外しすると 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
>>>

GIL のない環境でのスレッド安全性¶

Python 3.13 以降では、free-threaded build で GIL を無効にできます。 ctypes では、単一のオブジェクトに対する並行した読み書きは安全ですが、複数のオブジェクトを通じた並行した読み書きは安全ではありません:

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

上の例で GIL が無効の場合、同じアドレスに対して一度に安全に読み書きできるのは、1 つのオブジェクトだけです。したがって、複数のスレッドで pointer_a を共有して書き込むことはできますが、pointer_b が同じことをしようとしていない場合に限られます。これが問題になる場合は、threading.Lock を使ってメモリへのアクセスを同期することを検討してください:

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

型変換¶

通常、ctypes は厳密な型検査を行います。例えば、関数の argtypes リストや構造体定義のメンバーフィールドの型に POINTER(c_int) を指定した場合、まったく同じ型のインスタンスしか受け付けません。ただし、この規則には例外があり、ctypes がほかのオブジェクトを受け付ける場合もあります。例えば、ポインタ型の代わりに、互換性のある配列インスタンスを渡せます。そのため、POINTER(c_int) に対しては、ctypes は 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
>>>

さらに、argtypes で関数の引数を POINTER(c_int) などのポインタ型として明示的に宣言した場合、参照先の型 (この場合は c_int) のオブジェクトを関数に渡せます。この場合、ctypes は必要な byref() 変換を自動的に適用します。

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

>>> bar.values = None
>>>

互換性のない型のインスタンスを扱うこともあります。 C では、ある型を別の型にキャストできます。 ctypes には、同じように使える cast() 関数があります。上で定義した Bar 構造体の values フィールドは、POINTER(c_int) ポインタや c_int 配列を受け付けますが、ほかの型のインスタンスは受け付けません。

>>> 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; /* 前方宣言 */

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
>>>

これは、新しい class cell が、そのクラス文の内部ではまだ利用できないためです。 ctypes では、まず cell クラスを定義し、クラス文の後で _fields_ 属性を設定できます。

>>> 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 を使うと、Python の呼び出し可能オブジェクトから、C で呼び出せる関数ポインタを作成できます。これらは コールバック関数 と呼ばれることもあります。

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

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

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

ここでは、標準 C ライブラリの qsort() 関数を使う例を示します。この関数は、コールバック関数を使って要素をソートします。 qsort() で整数の配列をソートしてみます。

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

qsort() は、ソートするデータへのポインタ、データ配列の要素数、1 要素のサイズ、比較関数であるコールバックへのポインタを渡して呼び出す必要があります。コールバックは、要素への 2 つのポインタを引数として呼び出されます。最初の要素が 2 番目より小さければ負の整数、等しければゼロ、それ以外なら正の整数を返す必要があります。

コールバック関数は整数へのポインタを受け取り、整数を返す必要があります。まず、コールバック関数のための 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
>>>

注釈

C コードで使用されている間は、必ず CFUNCTYPE() オブジェクトへの参照を保持してください。 ctypes 自身は参照を保持しないため、参照を保持しないとオブジェクトがガベージコレクションされ、コールバックの呼び出し時にプログラムがクラッシュする可能性があります。

同様に、コールバック関数が Python の管理外 (例えば、コールバックを呼び出す外部のコード) で作られたスレッドで呼び出された場合、 ctypes は全ての呼び出しごとに新しいダミーの Python スレッドを作成することに注意してください。この動作はほとんどの目的に対して正しいものですが、同じ C スレッドからの呼び出しだったとしても、 threading.local で格納された値は異なるコールバックをまたいで生存は しません 。

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

共有ライブラリには、関数だけでなく変数もエクスポートするものがあります。 Python ライブラリ自体にも例があり、Py_Version は Python ランタイムのバージョン番号を単一の定数の整数に符号化したものです。

ctypes は、型の in_dll() クラスメソッドを使って、このような値にアクセスできます。 pythonapi は、Python C API へのアクセスを提供する定義済みのシンボルです。

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

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

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

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

したがって、このポインタの操作は役立つこともあります。例を短くするため、ここでは 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__ を試してみてください。

びっくり仰天¶

ctypes には、実際とは異なる動作を期待してしまいがちな部分がいくつかあります。

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

>>> 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
>>> # 2 つの点を交換します
>>> 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 は、可変サイズの配列や構造体をある程度サポートしています。

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
>>>

ctypes で可変サイズのデータ型を使うもう 1 つの方法は、Python の動的な性質を利用し、必要なサイズがわかった後で、場合に応じてデータ型を定義または再定義することです。

ctypesリファレンス¶

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

共有ライブラリを Python プロセスにロードする方法はいくつかあります。その 1 つは、CDLL またはそのサブクラスのインスタンスを作成する方法です:

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

ロード済みの共有ライブラリを表します。

このライブラリの関数は標準の C 呼び出し規約を使用し、int を返すと仮定されます。これらのライブラリがエクスポートする関数を呼び出す前に、Python の global interpreter lock を解放し、呼び出し後に再取得します。関数の動作を変えるには、サブクラス OleDLL、WinDLL、PyDLL を使用してください。

すでにロードした共有ライブラリの ハンドル がある場合、それを handle 引数に渡すと、開いているライブラリを新しい CDLL オブジェクトでラップできます。この場合、name は _name 属性の設定にのみ使われますが、調整や検証が行われることもあります。

handle が None の場合、プラットフォームの dlopen(3) または LoadLibraryExW 関数を使って、ライブラリをプロセスにロードし、そのハンドルを取得します。

name は開く共有ライブラリのパス名です。 name にパスの区切り文字が含まれない場合、プラットフォーム固有の方法でライブラリを探します。

Windows では、.DLL 接尾辞を省略できます (詳細は LoadLibraryExW のドキュメントを参照してください)。ほかのプラットフォーム固有の接頭辞や接尾辞 (lib、.so、.dylib、バージョン番号など) は name に含める必要があり、自動的には追加されません。詳しくは共有ライブラリを見つけるを参照してください。

Windows 以外では、name に None を指定できます。この場合、dlopen() を NULL を指定して呼び出し、メインプログラムを「ライブラリ」として開きます。 name が空の場合に同じ動作をするシステムもありますが、None / NULL の方が移植性に優れています。

CPython の実装の詳細

CPython は libc にリンクされるため、C 標準ライブラリへのアクセスには name に None を指定する方法がよく使われます。

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

Python C API にアクセスする場合は、各プラットフォームで動作する ctypes.pythonapi を優先してください。

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

use_errno 引数を真に設定すると、システムのエラー番号 errno に安全にアクセスする ctypes の仕組みが有効になります。 ctypes は、システムの errno 変数のコピーをスレッドローカルに保持します。 use_errno=True で作成した外部関数を呼び出すと、呼び出し前の errno 値を ctypes 内部のコピーと交換し、呼び出し直後にも同じ交換を行います。この仕組みは、インタープリタ自体と同じ C ランタイムライブラリを使うライブラリに対してのみ機能します。別の C ランタイム (例えば Windows 上の別の CRT) にリンクされたライブラリは、独自の errno を持ち、ctypes からは参照できません。

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

use_last_error 引数を真に設定すると、Windows API 関数の GetLastError() と SetLastError() が管理する Windows エラーコードについて同じ仕組みが有効になります。 ctypes 内部にある Windows エラーコードのコピーの取得と変更には、ctypes.get_last_error() と ctypes.set_last_error() を使います。

Windows では mode が無視されるため、winmode 引数でライブラリのロード方法を指定します。 Win32 API の LoadLibraryExW の flags 引数として有効な値を指定できます。省略時には、DLL ハイジャックなどの問題を避けるため、最も安全に DLL をロードするフラグが使われます。正しいライブラリと依存ライブラリがロードされることを確実にする最も安全な方法は、DLL のフルパスを渡すことです。

Windows では、DLL の名前が存在していても CDLL インスタンスの作成が失敗することがあります。ロードする DLL の依存先 DLL が見つからない場合、"[WinError 126] The specified module could not be found" というメッセージで OSError が送出されます。 Windows API がこの情報を返さないため、エラーメッセージには見つからない DLL の名前が含まれず、原因の特定が難しくなります。このエラーを解決し、見つからない DLL を特定するには、依存先 DLL の一覧を調べ、Windows のデバッグツールやトレースツールで、どれが見つからないのかを判定する必要があります。

参考

Microsoft の DUMPBIN ツール -- 依存先 DLL を調べるツールです。

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

バージョン 3.12 で変更: name 引数に path-like object を指定できるようになりました。

このクラスのインスタンスには公開メソッドがありません。共有ライブラリがエクスポートする関数には、属性やインデックスを使ってアクセスできます。属性を通じてアクセスすると結果がキャッシュされ、繰り返しアクセスしても毎回同じオブジェクトを返します。一方、インデックスを通じてアクセスすると、毎回新しいオブジェクトを返します。

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

以下の公開属性を利用できます。エクスポートされた関数名と衝突しないよう、名前はアンダースコアで始まります:

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

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

class ctypes.OleDLL¶

共通の情報については、スーパークラス CDLL を参照してください。

このライブラリの関数は stdcall 呼び出し規約を使用し、Windows 固有の HRESULT コードを返すと仮定されます。 HRESULT の値には、関数呼び出しの成功または失敗を示す情報と、追加のエラーコードが含まれます。戻り値が失敗を示す場合、OSError を自動的に送出します。

利用可能な環境: Windows

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

class ctypes.WinDLL¶

共通の情報については、スーパークラス CDLL を参照してください。

これらのライブラリの関数は stdcall 呼び出し規約を使用し、デフォルトでは int を返すと仮定されます。

利用可能な環境: Windows

class ctypes.PyDLL¶

共通の情報については、スーパークラス CDLL を参照してください。

このライブラリの関数を呼び出す場合、呼び出し中に Python の GIL は解放 されず、関数の実行後に Python のエラーフラグを検査します。エラーフラグが設定されている場合は、Python の例外を送出します。

したがって、これは Python C API 関数を直接呼び出す場合にのみ役立ちます。

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

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

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

あらかじめ作成されている LibraryLoader クラスのインスタンスを使って、共有ライブラリをロードすることもできます。 LoadLibrary() メソッドを呼び出すか、ローダーインスタンスの属性としてライブラリを取得します。

class ctypes.LibraryLoader(dlltype)¶

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

__getattr__() には特別な動作があります。ライブラリローダーインスタンスの属性にアクセスすると、共有ライブラリをロードできます。結果はキャッシュされるため、属性へのアクセスを繰り返しても毎回同じライブラリを返します。

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

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

ctypes.cdll¶

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

ctypes.windll¶

WinDLL インスタンスを作成します。

利用可能な環境: Windows

ctypes.oledll¶

OleDLL インスタンスを作成します。

利用可能な環境: Windows

ctypes.pydll¶

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

ctypes.pythonapi¶

Python C API 関数を属性として公開する PyDLL のインスタンスです。すべての関数が C の int を返すと仮定していますが、実際には常にそうとは限りません。これらの関数を使うには、restype 属性に正しい型を設定する必要があります。

注釈

Python インタープリタが静的にリンクされている場合、これは None になることがあります。

これらのオブジェクトを通じてライブラリをロードすると、ロードに使うライブラリ名を文字列引数 name とする監査イベント ctypes.dlopen が発生します。

ロード済みライブラリの関数にアクセスすると、引数 library (ライブラリオブジェクト) と name (文字列または整数のシンボル名) を持つ監査イベント ctypes.dlsym が発生します。

ライブラリオブジェクトではなくハンドルだけが利用できる場合、関数にアクセスすると、引数 handle (生のライブラリハンドル) と name を持つ監査イベント ctypes.dlsym/handle が発生します。

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

コンパイル型の言語でプログラミングする場合、共有ライブラリには、プログラムのコンパイルやリンクの際と、プログラムの実行時にアクセスします。プログラマーが短い名前を指定すると、C コンパイラ、リンカー、実行時の動的ライブラリローダーがシステム固有の方法で連携し、ロードするライブラリのファイル名を探します。

短い名前とファイル名の対応は、プラットフォーム間で一貫した形では公開されていませんが、ctypes.util モジュールは、その対応を求めようとする find_library() 関数を提供します。ただし、後方互換性の問題から新しいプラットフォームや設定に合わせて動作を調整するのは難しいため、この関数は soft deprecated です。

ctypes で共有ライブラリをラップする場合、実行時に find_library() で探す代わりに、開発時に共有ライブラリ名を決めてラッパーモジュールに直接記述することを検討してください。また、利用するライブラリをユーザーが選べる設定オプションや環境変数を追加し、find_library() はデフォルトや代替手段として使うことも検討してください。

ctypes.util.find_library(name)¶

ライブラリを探し、そのパス名を返します。

name は、lib などの接頭辞や、.so、.dylib、バージョン番号などの接尾辞を含まない、ライブラリの「短い」名前です (POSIX リンカーの -l オプションで使う形式です)。結果は CDLL に渡せる形式になります。

ライブラリが見つからない場合は None を返します。

厳密な動作はシステムに依存し、Python のために、または Python が使用するコンパイラ、リンカー、ローダーの動作と一致する 保証はありません。この関数はデフォルトや代替手段としてのみ使うことを推奨します。

バージョン 3.15 でソフト非推奨 <Soft deprecated>: この関数は、現在動作する環境での使用のために維持されますが、追加のプラットフォームや設定に対応する更新は予定されていません。

Linux では、find_library() は外部プログラム (/sbin/ldconfig、gcc、objdump、ld) を実行してライブラリファイルを探そうとします。これらのプログラムの出力が Python の使う動的リンカーに対応していない場合、この関数の結果は誤解を招くことがあります。

バージョン 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'
>>>

macOS と Android では、find_library() はシステム標準の命名規則とパスを使ってライブラリを探し、成功するとフルパス名を返します。

>>> 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'
>>>

Windows では、find_library() はシステムの検索パスに沿って探し、フルパス名を返します。ただし、定義済みの命名規則がないため、find_library("c") のような呼び出しは失敗して None を返します。

ctypes.util.find_msvcrt()¶

Python と拡張モジュールが使用する VC ランタイムライブラリのファイル名を返します。

ライブラリ名を判定できない場合は None を返します。特に、最近のバージョンの VC ランタイムライブラリは直接ロードできないため、この結果になります。

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

利用可能な環境: Windows

ロード済み共有ライブラリの一覧取得¶

共有ライブラリからロードしたコードに依存するコードを書く場合、現在のプロセスにどの共有ライブラリがすでにロードされているかを知ると役立つことがあります。

ctypes.util モジュールの dllist() 関数は、各プラットフォームが提供する異なる API を呼び出して、現在のプロセスにすでにロードされた共有ライブラリを調べます。

この関数の具体的な出力はシステムに依存します。ほとんどのプラットフォームでは、リストの最初の要素は現在のプロセス自体を表し、空文字列の場合もあります。例えば、glibc を使う Linux では次のような結果を返すことがあります。

>>> 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', ... ]

外部関数¶

前の節で説明したとおり、外部関数にはロード済み共有ライブラリの属性としてアクセスできます。この方法で作成した関数オブジェクトは、デフォルトで任意の数の引数を受け付け、任意の ctypes データインスタンスを引数に取ります。戻り値の型は、ライブラリローダーが指定するデフォルトの型になります。

これらは、非公開の _CFuncPtr クラスを継承する、非公開のローカルクラス _FuncPtr のインスタンスです (ctypes では公開されていません)。

>>> 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 を使います。

ctypes の型以外の、Python の呼び出し可能オブジェクトを代入することもできます。この場合、関数は C の int を返すと仮定され、その整数を渡して呼び出し可能オブジェクトを呼び出すことで、追加の処理やエラー検査を行えます。この使い方は非推奨です。より柔軟な後処理やエラー検査を行うには、restype に ctypes のデータ型を設定し、errcheck 属性に呼び出し可能オブジェクトを代入してください。

argtypes¶

関数が受け取る引数の型を指定するには、ctypes の型のタプルを代入します。タプルの長さより少ない引数で関数を呼び出すと、TypeError を送出します。 stdcall 呼び出し規約を使う関数は、引数が多すぎる場合にも TypeError を送出します。 cdecl 呼び出し規約を使う関数は、指定していない追加の引数も受け付けます。

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.

新機能: argtypes に ctypes の型以外の要素も指定できるようになりました。ただし、各要素には、引数として使える値 (整数、文字列、ctypes インスタンス) を返す from_param() メソッドが必要です。これにより、独自のオブジェクトを関数の引数に適合させるアダプターを定義できます。

errcheck¶

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

callable(result, func, arguments)

result は、restype 属性で指定された型で外部関数が返す値です。

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

arguments は、関数呼び出しに渡された引数を含むタプルです。 ctypes がその呼び出しのために作成した出力引数も含みます。これにより、使われた引数に応じて動作を調整できます。

呼び出し可能オブジェクトが受け取った arguments タプルを変更せずに返すと、ctypes は出力引数の返却を含む通常の結果処理を続けます (関数プロトタイプを参照)。ほかのオブジェクトを返した場合は、そのオブジェクトが外部関数呼び出しの戻り値になります。また、結果の値を検査し、外部関数呼び出しが失敗した場合に例外を送出することもできます。

例えば、次の呼び出し可能オブジェクトは、外部関数が負の戻り値で失敗を示した場合に例外を送出し、それ以外の場合は ctypes に結果の処理を任せます。

def errcheck(result, func, arguments):
    if result < 0:
        raise RuntimeError(f"call failed with error {result}")
    return arguments

次の例は、ブール値として使われる C の int を bool に変換して、結果を置き換えます。

def errcheck(result, func, arguments):
    return result != 0

Windows では、外部関数呼び出しがアクセス違反などのシステム例外を発生させると、それを捕捉して適切な Python 例外に置き換えます。さらに、引数 code を持つ監査イベント ctypes.set_exception が発生し、監査フックが独自の例外に置き換えられるようになります。

外部関数の呼び出し方によっては、またこのモジュールの一部の関数では、引数 function pointer と arguments を持つ監査イベント ctypes.call_function が発生する場合があります。

関数プロトタイプ¶

外部関数は関数プロトタイプをインスタンス化することによって作成されます。関数プロトタイプは 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)¶: 返された関数プロトタイプは、stdcall 呼び出し規約を使う関数を作成します。関数は呼び出し中に GIL を解放します。 use_errno と use_last_error の意味は上記と同じです。

利用可能な環境: Windows

ctypes.PYFUNCTYPE(restype, *argtypes)¶: 返された関数プロトタイプは、Python 呼び出し規約を使う関数を作成します。 CFUNCTYPE() や WINFUNCTYPE() と異なり、ctypes は外部関数を呼び出す前に GIL を解放 しない ので、その関数は Python C API を安全に使用できます。ただし、呼び出し中の 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 はオプションのインターフェイス識別子へのポインタで、拡張されたエラー情報の提供のために使われます。

iid を指定しない場合、COM メソッドの呼び出しが失敗すると OSError を送出します。 iid を指定した場合は、代わりに COMError を送出します。

COM メソッドは特別な呼び出し規約を使います。 argtypes タプルで指定した引数に加えて、第 1 引数として COM インターフェースへのポインタが必要です。

利用可能な環境: Windows

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

paramflags は、argtypes と同じ長さのタプルでなければなりません。

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

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

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

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

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

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

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

次の例では、Windows の MessageBoxW 関数をラップして、引数のデフォルト値と名前付き引数をサポートする方法を示します。 Windows ヘッダーファイルの C 宣言は次のとおりです。

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

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);

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 インスタンスを返します。

出力引数は errcheck プロトコルと組み合わせて、出力の追加処理やエラー検査を行えます。 win32 API の GetWindowRect 関数は成功か失敗かを BOOL で返すので、次の関数でエラーを検査し、API 呼び出しが失敗した場合に例外を送出できます。

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

errcheck 関数が受け取った引数タプルをそのまま返すと、ctypes は出力引数に対する通常の処理を続けます。 RECT インスタンスの代わりにウィンドウ座標のタプルを返したい場合は、関数内でフィールドを取得してそれらを返せます。この場合、通常の処理は行われなくなります。

>>> 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)¶

COM ポインタを src から dst にコピーし、Windows 固有の HRESULT 値を返します。

src が NULL でない場合、その AddRef メソッドを呼び出して参照カウントを増やします。

一方、新しい値を代入する前に dst の参照カウントを減らすことはありません。 dst が NULL でなければ、呼び出し側が必要に応じてその Release メソッドを呼び出し、参照カウントを減らす責任を持ちます。

利用可能な環境: 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 配列です。

size を指定する場合 (None 以外の場合)、int でなければなりません。返す配列のサイズを指定します。

init 引数を指定する場合、bytes でなければなりません。配列の要素の初期化に使います。この方法で初期化されないバイトは、ゼロ (NUL) に設定されます。

size を省略した場合 (または None の場合)、バッファを init より 1 要素分大きくすることで、実質的に NUL 終端文字を追加します。

両方の引数を指定する場合、size は len(init) 以上でなければなりません。

警告

size が len(init) と等しい場合、NUL 終端文字は追加されません。そのようなバッファを C 文字列として扱わないでください。

例えば:

>>> 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 配列です。

この関数は create_string_buffer() と同じ引数を取りますが、init は文字列である必要があり、size は c_wchar の個数を表します。

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

ctypes.DllCanUnloadNow()¶: この関数は、ctypes でプロセス内 COM サーバーを実装するためのフックです。 _ctypes 拡張 DLL がエクスポートする DllCanUnloadNow() 関数から呼び出されます。

利用可能な環境: Windows

ctypes.DllGetClassObject()¶: この関数は、ctypes でプロセス内 COM サーバーを実装するためのフックです。 _ctypes 拡張 DLL がエクスポートする DllGetClassObject() 関数から呼び出されます。

利用可能な環境: Windows

ctypes.util.dllist()¶

現在のプロセスにロードされた共有ライブラリのパスの一覧を取得しようとします。これらのパスには正規化などの処理は一切行いません。基盤となるプラットフォーム API が失敗した場合、OSError を送出することがあります。厳密な動作はシステムに依存します。

ほとんどのプラットフォームでは、リストの最初の要素は現在の実行ファイルを表します。空文字列の場合もあります。

利用可能な環境: Windows, macOS, iOS, glibc, BSD libc, musl

Added in version 3.14.

ctypes.FormatError([code])¶: エラーコード code の説明文を返します。エラーコードを指定しない場合は、Windows API 関数 GetLastError() を呼び出して最後のエラーコードを取得し、それを使用します。

利用可能な環境: Windows

ctypes.GetLastError()¶: 呼び出し元スレッドで Windows が設定した最後のエラーコードを返します。 Windows の GetLastError() 関数を直接呼び出し、ctypes 内部のエラーコードのコピーは返しません。

利用可能な環境: Windows

ctypes.get_errno()¶

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

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

ctypes.get_last_error()¶

呼び出し元スレッドにある、システムの LastError 変数の ctypes 内部のコピーの現在値を返します。

利用可能な環境: 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, /)¶: ctypes のポインタ型を作成するか、既存の型を返します。ポインタ型は内部でキャッシュされて再利用されるため、繰り返し呼び出しても負荷は小さくなります。 type は ctypes の型でなければなりません。

結果のポインタ型は、type の __pointer_type__ 属性にキャッシュされます。最初に POINTER を呼び出す前にこの属性を設定すれば、独自のポインタ型を指定できます。ただし、この方法は推奨しません。将来の Python バージョンで変わりうる実装の詳細に依存せず、適切なポインタ型を手動で作成することは難しいためです。

ctypes.pointer(obj, /)¶

obj を指す新しいポインタインスタンスを作成します。返されるオブジェクトの型は 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)¶

呼び出し元スレッドにある、システムの LastError 変数の ctypes 内部のコピーの現在値を value に設定し、以前の値を返します。

利用可能な環境: Windows

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

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

ctypes.string_at(ptr, size=-1)¶

void *ptr にあるバイト文字列を返します。 size を指定した場合はそのサイズを使い、省略した場合はゼロ終端文字列と仮定します。

引数 ptr、size を持つ監査イベント ctypes.string_at が発生します。

ctypes.WinError(code=None, descr=None)¶: OSError のインスタンスを作成します。 code を指定しない場合は、GetLastError() を呼び出してエラーコードを取得します。 descr を指定しない場合は、FormatError() を呼び出してエラーの説明文を取得します。

利用可能な環境: Windows

バージョン 3.3 で変更: 以前は WindowsError のインスタンスを作成していましたが、現在は OSError の別名になっています。

ctypes.wstring_at(ptr, size=-1)¶

void *ptr にあるワイド文字列を返します。 size を指定した場合は文字数として使い、省略した場合はゼロ終端文字列と仮定します。

引数 ptr、size を持つ監査イベント ctypes.wstring_at が発生します。

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

void *ptr から始まるメモリを参照する、長さ size の memoryview オブジェクトを返します。

readonly が真の場合、返される memoryview オブジェクトを使って参照先のメモリを変更することはできません (ほかの方法で行った変更は、返されたオブジェクトにも反映されます)。

この関数は string_at() に似ていますが、指定したメモリのコピーを作成しない点が大きく異なります。 memoryview((c_byte * size).from_address(ptr)) と意味的に同等で、より効率的な代替手段です。 from_address() は整数のみを受け付けますが、ptr には ctypes.POINTER や byref() のオブジェクトも指定できます。

引数 address、size、readonly を持つ監査イベント ctypes.memoryview_at が発生します。

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 は整数でなければなりません。

このメソッドと、それを間接的に呼び出すメソッドは、引数 address を持つ監査イベント ctypes.cdata を発生させます。

from_param(obj)¶

obj を ctypes の型に適合させるメソッドです。外部関数の argtypes タプルにその型が含まれている場合、実際の関数呼び出しで使われるオブジェクトを渡して呼び出されます。関数呼び出しの引数として使えるオブジェクトを返す必要があります。

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

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

ctypes データ型に共通のクラス変数:

__pointer_type__¶: 対応する ctypes データ型に対して POINTER() を呼び出して作成したポインタ型です。まだポインタ型を作成していない場合、この属性は存在しません。

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¶

この属性はインスタンスの実際の値を保持します。整数型とポインタ型では整数、文字型では一文字の bytes オブジェクトまたは文字列、文字へのポインタ型では Python の bytes オブジェクトまたは文字列です。

ctypes インスタンスから value 属性を取得すると、通常は毎回新しいオブジェクトが返されます。 ctypes は元のオブジェクトを返す機能を実装 しておらず、常に新しいオブジェクトを構築します。これは、ほかのすべての ctypes オブジェクトのインスタンスにも当てはまります。

各サブクラスには、以下のクラス属性があります:

_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.

参考

array モジュールや struct モジュール、numpy などのサードパーティー製モジュールでも、似てはいるものの少し異なる型コードを使用しています。

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.

基本データ型のサブクラスは、この動作を継承 しません。したがって、外部関数の restype が c_void_p のサブクラスの場合、関数呼び出しからそのサブクラスのインスタンスを受け取ります。もちろん、value 属性にアクセスすればポインタの値を取得できます。

これらが基本 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¶: 利用可能な場合に、C の double complex データ型を表します。コンストラクタは省略可能な complex の初期値を受け付けます。

Added in version 3.14.

class ctypes.c_float_complex¶: 利用可能な場合に、C の float complex データ型を表します。コンストラクタは省略可能な complex の初期値を受け付けます。

Added in version 3.14.

class ctypes.c_longdouble_complex¶: 利用可能な場合に、C の long double complex データ型を表します。コンストラクタは省略可能な complex の初期値を受け付けます。

Added in version 3.14.

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

class ctypes.c_int8¶: C の 8 ビットの signed int データ型を表します。 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¶: C の signed long long データ型を表します。コンストラクタは省略可能な整数の初期値を受け付けますが、オーバーフローの検査は行いません。 sizeof(long long) == sizeof(long) となるプラットフォームでは、c_long の別名です。

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

class ctypes.c_size_t¶: C の size_t データ型を表します。通常は、ほかの符号なし整数型の別名です。

class ctypes.c_ssize_t¶: Py_ssize_t データ型を表します。これは size_t の符号付き版、すなわち POSIX の ssize_t 型です。通常は、ほかの整数型の別名です。

Added in version 3.2.

class ctypes.c_time_t¶: C の time_t データ型を表します。通常は、ほかの整数型の別名です。

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¶: C の 8 ビットの unsigned int データ型を表します。 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¶: 関数やメソッドの呼び出しの成功またはエラーに関する情報を含む HRESULT 値を表します。

利用可能な環境: Windows

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

バージョン 3.14 で変更: py_object が generic type になりました。

Windows のデータ型¶

ソースコード: Lib/ctypes/wintypes.py

ctypes.wintypes モジュールは、Windows API で使う型を提供します。多くは ctypes で定義された型の別名です。対応する C の定義は、Microsoft の Windows のデータ型のドキュメントを参照してください。 Windows 以外のプラットフォームでは、これらの型のサイズやレイアウトが Windows のものと異なる場合があります。

バージョン 3.14 で変更: HCONV、HCONVLIST、HCURSOR、HDDEDATA、HDROP、HFILE、HRESULT、HSZ が追加されました。

例えば:

>>> from ctypes import POINTER
>>> from ctypes.wintypes import LPRECT, RECT, SHORT
>>> SHORT(-1).value
-1
>>> rect = RECT(0, 0, 100, 50)
>>> rect.right, rect.bottom
(100, 50)
>>> LPRECT is POINTER(RECT)
True

単純型¶

以下の名前は、ctypes の基本型の別名です:

Windows の型	`ctypes` の型
class ctypes.wintypes.BYTE¶ class ctypes.wintypes.BOOLEAN¶	`c_ubyte`
class ctypes.wintypes.CHAR¶	`c_char`
class ctypes.wintypes.WCHAR¶	`c_wchar`
class ctypes.wintypes.WORD¶ class ctypes.wintypes.USHORT¶ class ctypes.wintypes.ATOM¶ class ctypes.wintypes.LANGID¶	`c_ushort`
class ctypes.wintypes.DWORD¶ class ctypes.wintypes.ULONG¶ class ctypes.wintypes.COLORREF¶ class ctypes.wintypes.LCID¶ class ctypes.wintypes.LCTYPE¶ class ctypes.wintypes.LGRPID¶	`c_ulong`
class ctypes.wintypes.BOOL¶ class ctypes.wintypes.LONG¶ class ctypes.wintypes.HRESULT¶	`c_long`
class ctypes.wintypes.INT¶ class ctypes.wintypes.HFILE¶	`c_int`
class ctypes.wintypes.UINT¶	`c_uint`
class ctypes.wintypes.SHORT¶	`c_short`
class ctypes.wintypes.DOUBLE¶	`c_double`
class ctypes.wintypes.FLOAT¶	`c_float`
class ctypes.wintypes.LARGE_INTEGER¶	`c_longlong`
class ctypes.wintypes.ULARGE_INTEGER¶	`c_ulonglong`
class ctypes.wintypes.LPCSTR¶ class ctypes.wintypes.LPSTR¶	`c_char_p`
class ctypes.wintypes.LPCOLESTR¶ class ctypes.wintypes.LPOLESTR¶ class ctypes.wintypes.OLESTR¶ class ctypes.wintypes.LPCWSTR¶ class ctypes.wintypes.LPWSTR¶	`c_wchar_p`
class ctypes.wintypes.LPCVOID¶ class ctypes.wintypes.LPVOID¶	`c_void_p`

LARGE_INTEGER と ULARGE_INTEGER は整数の value 属性を公開し、LowPart、HighPart、QuadPart フィールドは持ちません。

class ctypes.wintypes.WPARAM¶: c_void_p と同じサイズの符号なし整数型です。

class ctypes.wintypes.LPARAM¶: c_void_p と同じサイズの符号付き整数型です。

class ctypes.wintypes.VARIANT_BOOL¶: value 属性が Python の bool である、16 ビットのブール型です。 value に代入すると、真の値には -1、偽の値には 0 を格納します。

ハンドル型¶

class ctypes.wintypes.HANDLE¶: Windows ハンドルを表すために使う c_void_p の別名です。

class ctypes.wintypes.HACCEL¶
class ctypes.wintypes.HBITMAP¶
class ctypes.wintypes.HBRUSH¶
class ctypes.wintypes.HCOLORSPACE¶
class ctypes.wintypes.HCONV¶
class ctypes.wintypes.HCONVLIST¶
class ctypes.wintypes.HCURSOR¶
class ctypes.wintypes.HDC¶
class ctypes.wintypes.HDDEDATA¶
class ctypes.wintypes.HDESK¶
class ctypes.wintypes.HDROP¶
class ctypes.wintypes.HDWP¶
class ctypes.wintypes.HENHMETAFILE¶
class ctypes.wintypes.HFONT¶
class ctypes.wintypes.HGDIOBJ¶
class ctypes.wintypes.HGLOBAL¶
class ctypes.wintypes.HHOOK¶
class ctypes.wintypes.HICON¶
class ctypes.wintypes.HINSTANCE¶
class ctypes.wintypes.HKEY¶
class ctypes.wintypes.HKL¶
class ctypes.wintypes.HLOCAL¶
class ctypes.wintypes.HMENU¶
class ctypes.wintypes.HMETAFILE¶
class ctypes.wintypes.HMODULE¶
class ctypes.wintypes.HMONITOR¶
class ctypes.wintypes.HPALETTE¶
class ctypes.wintypes.HPEN¶
class ctypes.wintypes.HRGN¶
class ctypes.wintypes.HRSRC¶
class ctypes.wintypes.HSTR¶
class ctypes.wintypes.HSZ¶
class ctypes.wintypes.HTASK¶
class ctypes.wintypes.HWINSTA¶
class ctypes.wintypes.HWND¶
class ctypes.wintypes.SC_HANDLE¶
class ctypes.wintypes.SERVICE_STATUS_HANDLE¶: 特定の Windows API で使う HANDLE の別名です。 HFILE は INT の別名であり、上の単純型の一覧に含まれます。

構造体¶

以下の型は ctypes.Structure のサブクラスです。

class ctypes.wintypes.RECT¶
class ctypes.wintypes.RECTL¶
class ctypes.wintypes.tagRECT¶: left、top、right、bottom フィールドを持つ長方形です。すべてのフィールドは LONG 型です。

class ctypes.wintypes.SMALL_RECT¶: Left、Top、Right、Bottom フィールドを持つ長方形です。すべてのフィールドは SHORT 型です。

class ctypes.wintypes.POINT¶
class ctypes.wintypes.POINTL¶
class ctypes.wintypes.tagPOINT¶: x と y フィールドを持つ点です。どちらのフィールドも LONG 型です。

class ctypes.wintypes.SIZE¶
class ctypes.wintypes.SIZEL¶
class ctypes.wintypes.tagSIZE¶: cx と cy フィールドを持つ寸法です。どちらのフィールドも LONG 型です。

class ctypes.wintypes.FILETIME¶: dwLowDateTime と dwHighDateTime フィールドを持つファイル時刻です。どちらのフィールドも DWORD 型です。

class ctypes.wintypes.MSG¶

class ctypes.wintypes.tagMSG¶

以下のフィールドを持つ Windows メッセージです:

フィールド	型
`hWnd`	`HWND`
`message`	`UINT`
`wParam`	`WPARAM`
`lParam`	`LPARAM`
`time`	`DWORD`
`pt`	`POINT`

class ctypes.wintypes.WIN32_FIND_DATAA¶

class ctypes.wintypes.WIN32_FIND_DATAW¶

Windows のファイル検索関数が使う構造体で、以下のフィールドを持ちます。ファイル名に WIN32_FIND_DATAA は CHAR、WIN32_FIND_DATAW は WCHAR を使います。

フィールド	型
`dwFileAttributes`	`DWORD`
`ftCreationTime`, `ftLastAccessTime`, `ftLastWriteTime`	`FILETIME`
`nFileSizeHigh`, `nFileSizeLow`	`DWORD`
`dwReserved0`, `dwReserved1`	`DWORD`
`cFileName`	`MAX_PATH` 文字の配列
`cAlternateFileName`	14 文字の配列

ポインタ型¶

以下の名前は、2 列目の型を T とする ctypes.POINTER(T) の別名です:

ポインタ型	参照先の型
class ctypes.wintypes.LPBOOL¶ class ctypes.wintypes.PBOOL¶	`BOOL`
class ctypes.wintypes.PBOOLEAN¶	`BOOLEAN`
class ctypes.wintypes.LPBYTE¶ class ctypes.wintypes.PBYTE¶	`BYTE`
class ctypes.wintypes.PCHAR¶	`CHAR`
class ctypes.wintypes.LPCOLORREF¶	`COLORREF`
class ctypes.wintypes.LPDWORD¶ class ctypes.wintypes.PDWORD¶	`DWORD`
class ctypes.wintypes.LPFILETIME¶ class ctypes.wintypes.PFILETIME¶	`FILETIME`
class ctypes.wintypes.PFLOAT¶	`FLOAT`
class ctypes.wintypes.LPHANDLE¶ class ctypes.wintypes.PHANDLE¶	`HANDLE`
class ctypes.wintypes.PHKEY¶	`HKEY`
class ctypes.wintypes.LPHKL¶	`HKL`
class ctypes.wintypes.LPINT¶ class ctypes.wintypes.PINT¶	`INT`
class ctypes.wintypes.PLARGE_INTEGER¶	`LARGE_INTEGER`
class ctypes.wintypes.PLCID¶	`LCID`
class ctypes.wintypes.LPLONG¶ class ctypes.wintypes.PLONG¶	`LONG`
class ctypes.wintypes.LPMSG¶ class ctypes.wintypes.PMSG¶	`MSG`
class ctypes.wintypes.LPPOINT¶ class ctypes.wintypes.PPOINT¶	`POINT`
class ctypes.wintypes.PPOINTL¶	`POINTL`
class ctypes.wintypes.LPRECT¶ class ctypes.wintypes.PRECT¶	`RECT`
class ctypes.wintypes.LPRECTL¶ class ctypes.wintypes.PRECTL¶	`RECTL`
class ctypes.wintypes.LPSC_HANDLE¶	`SC_HANDLE`
class ctypes.wintypes.PSHORT¶	`SHORT`
class ctypes.wintypes.LPSIZE¶ class ctypes.wintypes.PSIZE¶	`SIZE`
class ctypes.wintypes.LPSIZEL¶ class ctypes.wintypes.PSIZEL¶	`SIZEL`
class ctypes.wintypes.PSMALL_RECT¶	`SMALL_RECT`
class ctypes.wintypes.LPUINT¶ class ctypes.wintypes.PUINT¶	`UINT`
class ctypes.wintypes.PULARGE_INTEGER¶	`ULARGE_INTEGER`
class ctypes.wintypes.PULONG¶	`ULONG`
class ctypes.wintypes.PUSHORT¶	`USHORT`
class ctypes.wintypes.PWCHAR¶	`WCHAR`
class ctypes.wintypes.LPWIN32_FIND_DATAA¶ class ctypes.wintypes.PWIN32_FIND_DATAA¶	`WIN32_FIND_DATAA`
class ctypes.wintypes.LPWIN32_FIND_DATAW¶ class ctypes.wintypes.PWIN32_FIND_DATAW¶	`WIN32_FIND_DATAW`
class ctypes.wintypes.LPWORD¶ class ctypes.wintypes.PWORD¶	`WORD`

定数と関数¶

ctypes.wintypes.MAX_PATH¶: WIN32_FIND_DATAA と WIN32_FIND_DATAW のファイル名配列のサイズとして使う値 260 です。

ctypes.wintypes.RGB(red, green, blue)¶

COLORREF の値を Python の整数として返します。 red、green、blue 引数は 0 から 255 までの整数で、各色成分の強度を指定します。

>>> from ctypes.wintypes import RGB
>>> hex(RGB(255, 128, 0))
'0x80ff'

構造化データ型¶

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

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

共用体は構造体と共通の属性と動作を持ちます。詳細は Structure のドキュメントを参照してください。

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 descriptors 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)),
                 ...
                ]

_fields_ クラス変数は 1 回だけ設定できます。その後の代入では 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.

構造体型のサブクラスのサブクラスは、基底クラスのフィールドを継承し、さらに自身で _fields_ を定義していれば、そのフィールドも持ちます。

_pack_¶

インスタンス内の構造体フィールドのアラインメントを上書きするための、省略可能な小さな整数です。

これは MSVC 互換のメモリレイアウトでのみ実装されています (_layout_ を参照)。

_pack_ に 0 を設定することは、設定しないことと同じです。それ以外の場合、値は 2 のべき乗の正の整数でなければなりません。効果は C の #pragma pack(N) と同じですが、ctypes はコンパイラが受け付けるより大きな n を許可する場合があります。

_fields_ に代入する時点で _pack_ が定義されていないと、効果はありません。

バージョン 3.14 で非推奨、バージョン 3.19 で削除予定: 歴史的な理由から、_pack_ がゼロ以外の場合、デフォルトで MSVC 互換のレイアウトを使用します。 Windows 以外のプラットフォームでは、このデフォルトの動作は非推奨であり、Python 3.19 ではエラーになる予定です。このレイアウトを意図している場合は、_layout_ に 'ms' を明示的に設定してください。

_align_¶

構造体をメモリへパックしたりメモリからアンパックしたりするときのアラインメントを大きくする、省略可能な小さな整数です。

値は負であってはなりません。効果は GCC の __attribute__((aligned(N))) や MSVC の #pragma align(N) と同じですが、ctypes はコンパイラが拒否する値を許可する場合があります。

_align_ は、構造体のアラインメント要件を 大きくする ことしかできません。 0 や 1 に設定しても効果はありません。

2 のべき乗でない値の使用は推奨されず、予想外の動作を引き起こす場合があります。

_fields_ に代入する時点で _align_ が定義されていないと、効果はありません。

Added in version 3.13.

_layout_¶

構造体や共用体のレイアウト名を指定する、省略可能な文字列です。現在は以下の値を指定できます:

"ms": Microsoft コンパイラ (MSVC) が使うレイアウトです。 GCC と Clang では、__attribute__((ms_struct)) でこのレイアウトを選べます。
"gcc-sysv": Linux や macOS で使われる、System V または「SysV に似た」データモデルで GCC が使うレイアウトです。このレイアウトでは、_pack_ を設定しないか、ゼロにする必要があります。

明示的に設定しない場合、ctypes はプラットフォームの慣例に合うデフォルト値を使います。このデフォルト値は、例えば新しいプラットフォームが正式にサポートされたり、似たプラットフォーム間の違いが見つかったりした場合など、将来の Python リリースで変わる可能性があります。現在のデフォルト値は次のとおりです:

Windows の場合: "ms"
_pack_ を指定した場合: "ms" (この動作は非推奨です。 _pack_ のドキュメントを参照してください)。
それ以外の場合: "gcc-sysv"

_fields_ に代入する時点で _layout_ が定義されていないと、効果はありません。

Added in version 3.14.

_anonymous_¶

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

この変数に列挙するフィールドは、構造体型または共用体型のフィールドでなければなりません。 ctypes は、構造体型にデスクリプタを作成し、構造体や共用体のフィールドを作成せずに、入れ子のフィールドへ直接アクセスできるようにします。

型の例です (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)¶

Structure と Union のフィールドのデスクリプタです。例えば次のように使います。

>>> 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

すべての属性は読み出し専用です。

CField オブジェクトは _fields_ を通じて作成されます。このクラスを直接インスタンス化しないでください。

Added in version 3.14: 以前のデスクリプタは offset と size 属性、および読みやすい文字列表現だけを持ち、CField クラスは直接利用できませんでした。

name¶: 文字列で表したフィールド名です。

type¶: ctypes のクラスで表したフィールドの型です。

offset¶

byte_offset¶

フィールドのオフセット (バイト単位) です。

ビットフィールドでは、これはバイト境界に整列した、元になる 格納単位 のオフセットです。 bit_offset を参照してください。

byte_size¶

フィールドのサイズ (バイト単位) です。

ビットフィールドでは、これは元になる 格納単位 のサイズです。通常はビットフィールドの型と同じサイズです。

size¶

ビットフィールドでない場合は、byte_size と同じです。

ビットフィールドでは、bit_size と bit_offset をビット単位でまとめた、後方互換性のための値を格納します。代わりに、これらの明示的な属性を使ってください。

is_bitfield¶: ビットフィールドであれば真です。

bit_offset¶

bit_size¶

ビットフィールドの 格納単位 内での位置です。つまり、byte_offset から始まる byte_size バイトのメモリ内での位置です。

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.

ビットフィールドでない場合、bit_offset はゼロで、bit_size は byte_size * 8 に等しくなります。

is_anonymous¶: このフィールドが匿名であれば真です。つまり、外側の構造体や共用体に統合される入れ子のサブフィールドを含む場合です。

配列とポインタ¶

class ctypes.Array(*args)¶

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

具体的な配列型を作成する推奨の方法は、任意の ctypes データ型に非負の整数を掛けることです。この型をサブクラス化し、_length_ と _type_ クラス変数を定義する方法もあります。配列の要素は、通常の添字やスライスによるアクセスで読み書きできます。スライスを読み出した場合、結果のオブジェクト自体は Array では ありません。

配列は、要素の型についてジェネリックです。

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

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

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

ctypes.ARRAY(type, length)¶: 配列を作成します。 type を ctypes のデータ型、length を整数とした type * length と同じです。

バージョン 3.14 でソフト非推奨 <Soft deprecated>: 代わりに乗算を使用してください。

class ctypes._Pointer¶

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

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

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

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

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

例外¶

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

exception ctypes.COMError(hresult, text, details)¶

COM メソッドの呼び出しが失敗した場合に送出される例外です。

hresult¶: エラーコードを表す整数値です。

text¶: エラーメッセージです。

details¶

5 要素のタプル (descr, source, helpfile, helpcontext, progid) です。

descr は説明文です。 source は、エラーを発生させたクラスやアプリケーションの、言語に依存する ProgID です。 helpfile はヘルプファイルのパスです。 helpcontext はヘルプコンテキスト識別子です。 progid は、エラーを定義したインターフェースの ProgID です。

利用可能な環境: Windows

Added in version 3.14.

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

ctypes チュートリアル¶

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

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

関数を呼び出す¶

基本データ型¶

続・関数を呼び出す¶

可変長引数関数の呼び出し¶

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

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

戻り値の型¶

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

構造体と共用体¶

構造体と共用体のレイアウト、アラインメント、バイト順序¶

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

配列¶

ポインタ¶

GIL のない環境でのスレッド安全性¶

型変換¶

不完全型¶

コールバック関数¶

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

びっくり仰天¶

可変サイズのデータ型¶

ctypesリファレンス¶

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

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

ロード済み共有ライブラリの一覧取得¶

外部関数¶

関数プロトタイプ¶

ユーティリティー関数¶

データ型¶

基本データ型¶

Windows のデータ型¶

単純型¶

ハンドル型¶

構造体¶

ポインタ型¶

定数と関数¶

構造化データ型¶

配列とポインタ¶

例外¶

`ctypes` --- Python 用の外部関数ライブラリ¶