pytho****@googl*****
pytho****@googl*****
2011年 4月 2日 (土) 20:45:22 JST
Revision: 87905301ffd2 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Sat Apr 2 04:43:45 2011 Log: 2.6.6: library/ctypes http://code.google.com/p/python-doc-ja/source/detail?r=87905301ffd2 Modified: /library/ctypes.rst ======================================= --- /library/ctypes.rst Sun Nov 28 10:27:58 2010 +++ /library/ctypes.rst Sat Apr 2 04:43:45 2011 @@ -1,6 +1,5 @@ - -:mod:`ctypes` --- Pythonのための外部関数ライブラリ。 -==================================================== +:mod:`ctypes` --- Pythonのための外部関数ライブラリ +================================================== .. module:: ctypes :synopsis: A foreign function library for Python. @@ -9,8 +8,8 @@ .. versionadded:: 2.5 -``ctypes`` は Python のための外部関数ライブラリです。このライブラリは -Cと互換性のあるデータ型を提供し、動的リンク/共有ライブラリ内の関数呼び +:mod:`ctypes` は Python のための外部関数ライブラリです。このライブラリは +C と互換性のあるデータ型を提供し、動的リンク/共有ライブラリ内の関数呼び 出しを可能にします。動的リンク/共有ライブラリを純粋な Python でラップ するために使うことができます。 @@ -20,9 +19,9 @@ ctypesチュートリアル -------------------- -注意: このチュートリアルのコードサンプルは動作確認のために ``doctest`` -を使います。コードサンプルの中には Linux 、 Windows 、あるいは Mac OS -X上で異なる動作をするものがあるため、サンプルのコメントに doctest 命令 +注意: このチュートリアルのコードサンプルは動作確認のために :mod:`doctest` +を使います。コードサンプルの中には Linux、 Windows、あるいは Mac OS X +上で異なる動作をするものがあるため、サンプルのコメントに doctest 命令 を入れてあります。 注意: いくつかのコードサンプルで ctypes の :class:`c_int` 型を参照して @@ -37,18 +36,18 @@ 動的リンクライブラリをロードする ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -動的リンクライブラリをロードするために、 ``ctypes`` は *cdll* をエクス -ポートします。 +動的リンクライブラリをロードするために、 :mod:`ctypes` は *cdll* を +エクスポートします。 Windows では *windll* と *oledll* オブジェクトをエクスポートします。 これらのオブジェクトの属性としてライブラリにアクセスすることでライブラ リをロードします。 *cdll* は標準 ``cdecl`` 呼び出し規約を用いて関数を エクスポートしているライブラリをロードします。それに対して、 *windll* ライブラリは ``stdcall`` 呼び出し規約を用いる関数を呼び出します。 -*oledll* も ``stdcall`` 呼び出し規約を使いますが、関数がWindows -:class:`HRESULT` エラーコードを返すことを想定しています。このエラーコー -ドは関数呼び出しが失敗したとき、 :class:`WindowsError` 例外を自動的に -送出させるために使われます。 +*oledll* も ``stdcall`` 呼び出し規約を使いますが、関数が Windows +:c:type:`HRESULT` エラーコードを返すことを想定しています。 +このエラーコードは関数呼び出しが失敗したとき、 +:class:`WindowsError` 例外を自動的に送出させるために使われます。 Windows用の例ですが、 ``msvcrt`` はほとんどの標準 C 関数が含まれている MS 標準 C ライブラリであり、 cdecl 呼び出し規約を使うことに注意してく @@ -123,7 +122,7 @@ 時には、 dll が関数を ``"??2 ＠ YAPAXI@Z"`` のような Python 識別子として 有効でない名前でエクスポートすることがあります。このような場合に関数を -取り出すには、 ``getattr`` を使わなければなりません。:: +取り出すには、 :func:`getattr` を使わなければなりません。:: >>> getattr(cdll.msvcrt, "??2 ＠ YAPAXI@Z") # doctest: +WINDOWS <_FuncPtr object at 0x...> @@ -164,7 +163,7 @@ 0x1d000000 >>> -``ctypes`` は引数の数を間違えたり、あるいは呼び出し規約を間違えた関数 +:mod:`ctypes` は引数の数を間違えたり、あるいは呼び出し規約を間違えた関数 呼び出しからあなたを守ろうとします。残念ながら、これは Windows でしか 機能しません。関数が返った後にスタックを調べることでこれを行います。し たがって、エラーは発生しますが、その関数は呼び出された *後です*:: @@ -197,9 +196,8 @@ 正しい呼び出し規約を知るためには、呼び出したい関数についての C ヘッダ ファイルもしくはドキュメントを見なければなりません。 -Windows では、関数が無効な引数とともに呼び出された場合の一般保護例外に -よるクラッシュを防ぐために、 ``ctypes`` は win32 構造化例外処理を使い -ます:: +Windows では、関数が無効な引数とともに呼び出された場合の一般保護例外による +クラッシュを防ぐために、 :mod:`ctypes` は win32 構造化例外処理を使います:: >>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS Traceback (most recent call last): @@ -207,18 +205,18 @@ WindowsError: exception: access violation reading 0x00000020 >>> -しかし、 ``ctypes`` を使って Python をクラッシュさせる方法は十分なほど +しかし、 :mod:`ctypes` を使って Python をクラッシュさせる方法は十分なほど あるので、よく注意すべきです。 -``None`` 、整数、長整数、バイト文字列およびユニコード文字列だけが、こ -うした関数呼び出しにおいてパラメータとして直接使えるネイティブの +``None`` 、整数、長整数、バイト文字列およびユニコード文字列だけが、 +こうした関数呼び出しにおいてパラメータとして直接使えるネイティブの Python オブジェクトです。 ``None`` は C の ``NULL`` ポインタとして渡さ れ、バイト文字列とユニコード文字列はそのデータを含むメモリブロックへの -ポインタ (``char *`` または ``wchar_t *``) として渡されます。 Python -整数と Python 長整数はプラットホームのデフォルトの C ``int`` 型として -渡され、その値は C ``int`` 型に合うようにマスクされます。 - -他のパラメータ型をもつ関数呼び出しに移る前に、 ``ctypes`` データ型につ +ポインタ (:c:type:`char *` または :c:type:`wchar_t *`) として渡されます。 +Python 整数と Python 長整数はプラットホームのデフォルトの C :c:type:`int` 型として +渡され、その値は C :c:type:`int` 型に合うようにマスクされます。 + +他のパラメータ型をもつ関数呼び出しに移る前に、 :mod:`ctypes` データ型につ いてさらに学ぶ必要があります。 @@ -227,48 +225,49 @@ 基本のデータ型 ^^^^^^^^^^^^^^ -``ctypes`` はたくさんの C と互換性のあるデータ型を定義しています : - - +-----------------------+------------------------------+----------------------------+ - | ctypesの型 | Cの型 | Pythonの 型 | - +=======================+==============================+============================+ - | :class:`c_char` | ``char`` | 1文字の文字 列 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_wchar` | ``wchar_t`` | 1文字のユニコー ド文字列 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_byte` | ``char`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_ubyte` | ``unsigned char`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_short` | ``short`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_ushort` | ``unsigned short`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_int` | ``int`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_uint` | ``unsigned int`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_long` | ``long`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_ulong` | ``unsigned long`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_longlong` | ``__int64`` or ``long long`` | 整数/長整 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_ulonglong` | ``unsigned __int64`` or | 整数/長整 数 | - | | ``unsigned long long`` | | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_float` | ``float`` | 浮動小数点 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_double` | ``double`` | 浮動小数点 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_longdouble` | ``longdouble`` | 浮動小数点 数 | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_char_p` | ``char *`` (NUL 終端) | 文字列または ``None`` | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_wchar_p` | ``wchar_t *`` (NUL 終端) | ユニコードまた は ``None`` | - +-----------------------+------------------------------+----------------------------+ - | :class:`c_void_p` | ``void *`` | 整数/長整数また は ``None`` | - +-----------------------+------------------------------+----------------------------+ +:mod:`ctypes` はたくさんの C と互換性のあるデータ型を定義しています : + + +-----------------------+-----------------------------------+----------------------------+ + | ctypes の型 | C の型 | Python の 型 | + +=======================+===================================+============================+ + | :class:`c_char` | :c:type:`char` | 1文字の文 字列 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_wchar` | :c:type:`wchar_t` | 1文字のユ ニコード文字列 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_byte` | :c:type:`char` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_ubyte` | :c:type:`unsigned char` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_short` | :c:type:`short` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_ushort` | :c:type:`unsigned short` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_int` | :c:type:`int` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_uint` | :c:type:`unsigned int` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_long` | :c:type:`long` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_ulong` | :c:type:`unsigned long` | 整数/長整 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_longlong` | :c:type:`__int64` または | 整数/長整 数 | + | | :c:type:`long long` | | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_ulonglong` | :c:type:`unsigned __int64` または | 整数/長整 数 | + | | :c:type:`unsigned long long` | | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_float` | :c:type:`float` | 浮動小数点 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_double` | :c:type:`double` | 浮動小数点 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_longdouble` | :c:type:`longdouble` | 浮動小数点 数 | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_char_p` | :c:type:`char *` (NUL 終端) | 文字列また は ``None`` | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL 終端) | ユニコード または ``None`` | + +-----------------------+-----------------------------------+----------------------------+ + | :class:`c_void_p` | :c:type:`void *` | 整数/長整 数または ``None`` | + +-----------------------+-----------------------------------+----------------------------+ これら全ての型はその型を呼び出すことによって作成でき、オプションとして @@ -294,10 +293,10 @@ -99 >>> -新しい値をポインタ型 :class:`c_char_p` 、 :class:`c_wchar_p` 、および -:class:`c_void_p` のインスタンスへ代入すると、メモリブロックの *内容で -はなく* 指している *メモリ位置* が変わります、 (もちろんできません。な -ぜなら、 Python 文字列は変更不可能だからです):: +新しい値をポインタ型 :class:`c_char_p`, :class:`c_wchar_p` および +:class:`c_void_p` のインスタンスへ代入すると、変わるのは指している +*メモリ位置* であって、メモリブロックの *内容ではありません* +(これは当然で、なぜなら、 Python 文字列は変更不可能だからです):: >>> s = "Hello, World" >>> c_s = c_char_p(s) @@ -310,10 +309,10 @@ Hello, World >>> -しかし、変更可能なメモリを指すポインタであることを想定している関数へそ -れらを渡さないように注意すべきです。もし変更可能なメモリブロックが必要 -なら、 ctypes には ``create_string_buffer`` 関数があり、いろいろな方法 -で作成することできます。 +しかし、変更可能なメモリを指すポインタであることを想定している関数へ +それらを渡さないように注意すべきです。もし変更可能なメモリブロックが必要 +なら、 ctypes には :func:`create_string_buffer` 関数があり、 +いろいろな方法で作成することできます。 現在のメモリブロックの内容は ``raw`` プロパティを使ってアクセス (ある いは変更) することができます。もし現在のメモリブロックに NUL 終端文字 列としてアクセスしたいなら、 ``value`` プロパティを使ってください:: @@ -335,11 +334,11 @@ 10 'Hi\x00lo\x00\x00\x00\x00\x00' >>> -``create_string_buffer`` 関数は初期の ctypes リリースにあった -``c_string`` 関数だけでなく、 (エイリアスとしてはまだ利用できる) -``c_buffer`` 関数をも置き換えるものです。 -C の型 ``wchar_t`` のユニコード文字を含む変更可能なメモリブロックを作 -成するには、 ``create_unicode_buffer`` 関数を使ってください。 +:func:`create_string_buffer` 関数は初期の ctypes リリースにあった +:func:`c_string` 関数だけでなく、 (エイリアスとしてはまだ利用できる) +:func:`c_buffer` 関数をも置き換えるものです。 +C の型 :c:type:`wchar_t` のユニコード文字を含む変更可能なメモリブロックを +作成するには、 :func:`create_unicode_buffer` 関数を使ってください。 .. _ctypes-calling-functions-continued: @@ -347,17 +346,17 @@ 続・関数を呼び出す ^^^^^^^^^^^^^^^^^^ -printf は ``sys.stdout`` では *なく* 、本物の標準出力チャンネルへプリ -ントすることに注意してください。したがって、これらの例はコンソールプロ +printf は :data:`sys.stdout` では *なく* 、本物の標準出力チャンネルへ +プリントすることに注意してください。したがって、これらの例はコンソールプロ ンプトでのみ動作し、 *IDLE* や *PythonWin* では動作しません。:: >>> printf = libc.printf >>> printf("Hello, %s\n", "World!") Hello, World! 14 - >>> printf("Hello, %S", u"World!") + >>> printf("Hello, %S\n", u"World!") Hello, World! - 13 + 14 >>> printf("%d bottles of beer\n", 42) 42 bottles of beer 19 @@ -369,10 +368,10 @@ 前に述べたように、必要な C のデータ型へ変換できるようにするためには、 整数、文字列およびユニコード文字列を除くすべての Python 型を対応する -``ctypes`` 型でラップしなければなりません。:: +:mod:`ctypes` 型でラップしなければなりません。:: >>> printf("An int %d, a double %f\n", 1234, c_double(3.14)) - Integer 1234, double 3.1400001049 + An int 1234, a double 3.140000 31 >>> @@ -382,12 +381,10 @@ 自作のデータ型とともに関数を呼び出す ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -自作のクラスのインスタンスを関数引数として使えるように、 ``ctypes`` 引 -数変換をカスタマイズすることもできます。 -``ctypes`` は :attr:`_as_parameter_` 属性を探し出し、関数引数として使 -います。 -もちろん、整数、文字列もしくはユニコードの中の一つでなければなりませ -ん。:: +自作のクラスのインスタンスを関数引数として使えるように、 :mod:`ctypes` +引数変換をカスタマイズすることもできます。 +:mod:`ctypes` は :attr:`_as_parameter_` 属性を探し出し、関数引数として使い ます。 +もちろん、整数、文字列もしくはユニコードの中の一つでなければなりません。:: >>> class Bottles(object): ... def __init__(self, number): @@ -400,8 +397,8 @@ >>> インスタンスのデータを :attr:`_as_parameter_` インスタンス変数の中に入 -れたくない場合には、そのデータを利用できるようにする ``property`` を定 -義することができます。 +れたくない場合には、そのデータを利用できるようにする :func:`property` +を定義することができます。 .. _ctypes-specifying-required-argument-types: @@ -423,16 +420,16 @@ 37 >>> -( C の関数のプロトタイプのように) 書式を指定すると互換性のない引数型に +(C の関数のプロトタイプのように) 書式を指定すると互換性のない引数型に なるのを防ぎ、引数を有効な型へ変換しようとします。:: >>> printf("%d %d %d", 1, 2, 3) Traceback (most recent call last): File "<stdin>", line 1, in ? ArgumentError: argument 2: exceptions.TypeError: wrong type - >>> printf("%s %d %f", "X", 2, 3) - X 2 3.00000012 - 12 + >>> printf("%s %d %f\n", "X", 2, 3) + X 2 3.000000 + 13 >>> 関数呼び出しへ渡す自作のクラスを定義した場合には、 :attr:`argtypes` シー @@ -444,8 +441,8 @@ :attr:`_as_parameter_` 属性、あるいは、この場合に C 関数引数として渡し たい何かの値を返さなければなりません。 繰り返しになりますが、その返される結果は整数、文字列、ユニコード、 -``ctypes`` インスタンス、あるいは :attr:`_as_parameter_` 属性をもつオ -ブジェクトであるべきです。 +:mod:`ctypes` インスタンス、あるいは :attr:`_as_parameter_` 属性をもつ +オブジェクトであるべきです。 .. _ctypes-return-types: @@ -453,7 +450,7 @@ 戻り値の型 ^^^^^^^^^^ -デフォルトでは、関数は C ``int`` を返すと仮定されます。他の戻り値の型 +デフォルトでは、関数は C :c:type:`int` を返すと仮定されます。他の戻り値の型 を指定するには、関数オブジェクトの :attr:`restype` 属性に設定します。 さらに高度な例として、 ``strchr`` 関数を使います。この関数は文字列ポイ @@ -489,7 +486,7 @@ 外部関数が整数を返す場合は、 :attr:`restype` 属性として呼び出し可能な Python オブジェクト (例えば、関数またはクラス) を使うこともできます。 -呼び出し可能オブジェクトは C 関数が返す ``integer`` とともに呼び出され、 +呼び出し可能オブジェクトは C 関数が返す *整数* とともに呼び出され、 この呼び出しの結果は関数呼び出しの結果として使われるでしょう。 これはエラーの戻り値をチェックして自動的に例外を送出させるために役に立 ちます。:: @@ -532,11 +529,11 @@ しくはそのデータが大きすぎて値渡しできない場合です。これは *パラメータ の参照渡し* としても知られています。 -``ctypes`` は :func:`byref` 関数をエクスポートしており、パラメータを参 -照渡しするために使用します。 ``pointer`` 関数を使っても同じ効果が得ら +:mod:`ctypes` は :func:`byref` 関数をエクスポートしており、パラメータを +参照渡しするために使用します。 :func:`pointer` 関数を使っても同じ効果が得ら れます。 -しかし、 ``pointer`` は本当のポインタオブジェクトを構築するためより多 -くの処理を行うことから、 Python 側でポインタオブジェクト自体を必要とし +しかし、 :func:`pointer` は本当のポインタオブジェクトを構築するためより +多くの処理を行うことから、 Python 側でポインタオブジェクト自体を必要とし ないならば :func:`byref` を使う方がより高速です。:: >>> i = c_int() @@ -557,16 +554,16 @@ 構造体と共用体 ^^^^^^^^^^^^^^ -構造体と共用体は ``ctypes`` モジュールに定義されている +構造体と共用体は :mod:`ctypes` モジュールに定義されている :class:`Structure` および :class:`Union` ベースクラスから導出されなけ ればなりません。それぞれのサブクラスは :attr:`_fields_` 属性を定義する 必要があります。 :attr:`_fields_` は *フィールド名* と *フィールド型* を持つ *2要素タプル* のリストでなければなりません。 -フィールド型は :class:`c_int` か他の ``ctypes`` 型 (構造体、共用体、配 -列、ポインタ) から導出された ``ctypes`` 型である必要があります。 - -``x`` と ``y`` という名前の二つの整数からなる簡単な POINT 構造体の例で +フィールド型は :class:`c_int` か他の :mod:`ctypes` 型 (構造体、共用体、 +配列、ポインタ) から導出された :mod:`ctypes` 型である必要があります。 + +*x* と *y* という名前の二つの整数からなる簡単な POINT 構造体の例で す。コンストラクタで構造体の初期化する方法の説明にもなっています。:: >>> from ctypes import * @@ -590,7 +587,7 @@ 体がフィールド型に構造体を使うことで他の構造体を内部に持つことができま す。 -``upperleft`` と ``lowerright`` という名前の二つの POINT を持つ RECT +*upperleft* と *lowerright* という名前の二つの POINT を持つ RECT 構造体です。:: >>> class RECT(Structure): @@ -629,15 +626,16 @@ のと同じ方法でアライメントされています。サブクラスを定義するときに :attr:`_pack_` クラス属性を指定することでこの動作を変えることは可能です。 このクラス属性には正の整数を設定する必要があり、フィールドの最大アライ -メントを指定します。これは MSVC で ``#pragmapack(n)`` が行っていること +メントを指定します。これは MSVC で ``#pragma pack(n)`` が行っていること 同じです。 -``ctypes`` は Structure と Union に対してネイティブのバイトオーダーを +:mod:`ctypes` は Structure と Union に対してネイティブのバイトオーダーを 使います。 ネイティブではないバイトオーダーの構造体を作成するには、 -BigEndianStructure 、 LittleEndianStructure 、 BigEndianUnion および -LittleEndianUnion ベースクラスの中の一つを使います。これらのクラスにポ -インタフィールドを持たせることはできません。 +:class:`BigEndianStructure`, :class:`LittleEndianStructure`, +:class:`BigEndianUnion` および :class:`LittleEndianUnion` +ベースクラスの中の一つを使います。これらのクラスに +ポインタフィールドを持たせることはできません。 .. _ctypes-bit-fields-in-structures-unions: @@ -714,7 +712,7 @@ ポインタ ^^^^^^^^ -ポインタのインスタンスは ``ctypes`` 型に対して ``pointer`` 関数を呼び +ポインタのインスタンスは :mod:`ctypes` 型に対して :func:`pointer` 関数を呼 び 出して作成します。:: >>> from ctypes import * @@ -723,13 +721,13 @@ >>> ポインタインスタンスはポインタが指すオブジェクト (上の例では ``i`` ) -を返す ``contents`` 属性を持ちます。:: +を返す :attr:`contents` 属性を持ちます。:: >>> pi.contents c_long(42) >>> -``ctypes`` は OOR (original object return 、元のオブジェクトを返すこと) +:mod:`ctypes` は OOR (original object return 、元のオブジェクトを返すこと) ではないことに注意してください。属性を取り出す度に、新しい同等のオブジェ クトを作成しているのです。:: @@ -748,7 +746,8 @@ c_long(99) >>> -.. XXX Document dereferencing pointers, and that it is preferred over the .contents attribute. +.. XXX Document dereferencing pointers, and that it is preferred over the + .contents attribute. ポインタインスタンスは整数でインデックス指定することもできます。:: @@ -771,10 +770,10 @@ 使うのは、 C 関数からポインタを受け取り、そのポインタが単一の要素では なく実際に配列を指していると *分かっている* 場合だけです。 -舞台裏では、 ``pointer`` 関数は単にポインタインスタンスを作成するとい +舞台裏では、 :func:`pointer` 関数は単にポインタインスタンスを作成するとい う以上のことを行っています。はじめにポインタ *型* を作成する必要があり ます。 -これは任意の ``ctypes`` 型を受け取る ``POINTER`` 関数を使って行われ、 +これは任意の :mod:`ctypes` 型を受け取る :func:`POINTER` 関数を使って行わ れ、 新しい型を返します。:: >>> PI = POINTER(c_int) @@ -796,7 +795,7 @@ False >>> -``ctypes`` はポインタの指す値を取り出すときに ``NULL`` かどうかを調べ +:mod:`ctypes` はポインタの指す値を取り出すときに ``NULL`` かどうかを調べ ます(しかし、 ``NULL`` でない不正なポインタの指す値の取り出す行為は Python をクラッシュさせるでしょう)。:: @@ -847,11 +846,11 @@ >>> bar.values = None >>> -XXX list other conversions... +.. XXX list other conversions... 時には、非互換な型のインスタンスであることもあります。 C では、ある型 -を他の型へキャストすることができます。 ``ctypes`` は同じやり方で使える -``cast`` 関数を提供しています。上で定義した ``Bar`` 構造体は +を他の型へキャストすることができます。 :mod:`ctypes` は同じやり方で使える +:func:`cast` 関数を提供しています。上で定義した ``Bar`` 構造体は ``POINTER(c_int)`` ポインタまたは :class:`c_int` 配列を ``values`` フィー ルドに対して受け取り、他の型のインスタンスは受け取りません:: @@ -861,10 +860,10 @@ TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance >>> -このような場合には、 ``cast`` 関数が便利です。 - -``cast`` 関数は ctypes インスタンスを異なる ctypes データ型を指すポイ -ンタへキャストするために使えます。 ``cast`` は二つのパラメータ、ある種 +このような場合には、 :func:`cast` 関数が便利です。 + +:func:`cast` 関数は ctypes インスタンスを異なる ctypes データ型を指すポイ +ンタへキャストするために使えます。 :func:`cast` は二つのパラメータ、ある種 のポインタかそのポインタへ変換できる ctypes オブジェクトと、 ctypes ポ インタ型を取ります。そして、第二引数のインスタンスを返します。 このインスタンスは第一引数と同じメモリブロックを参照しています:: @@ -874,7 +873,7 @@ <ctypes.LP_c_long object at ...> >>> -したがって、 ``cast`` を ``Bar`` 構造体の ``values`` フィールドへ代入 +したがって、 :func:`cast` を ``Bar`` 構造体の ``values`` フィールドへ代入 するために使うことができます:: >>> bar = Bar() @@ -913,7 +912,7 @@ >>> なぜなら、新しい ``class cell`` はクラス文自体の中では利用できないから -です。 ``ctypes`` では、 ``cell`` クラスを定義して、 :attr:`_fields_` +です。 :mod:`ctypes` では、 ``cell`` クラスを定義して、 :attr:`_fields_` 属性をクラス文の後で設定することができます。:: >>> from ctypes import * @@ -947,7 +946,7 @@ コールバック関数 ^^^^^^^^^^^^^^^^ -``ctypes`` は C の呼び出し可能な関数ポインタを Python 呼び出し可能オブ +:mod:`ctypes` は C の呼び出し可能な関数ポインタを Python 呼び出し可能オブ ジェクトから作成できるようにします。これらは *コールバック関数* と呼ば れることがあります。 @@ -1098,7 +1097,7 @@ C コードから使われる限り、 CFUNCTYPE オブジェクトへの参照を確実に保持 してください。 -``ctypes`` は保持しません。もしあなたがやらなければ、オブジェクトはゴ +:mod:`ctypes` は保持しません。もしあなたがやらなければ、オブジェクトはゴ ミ集めされてしまい、コールバックしたときにあなたのプログラムをクラッシュ させるかもしれません。 @@ -1113,7 +1112,7 @@ :option:`-O` または :option:`-OO` フラグに依存して、 0 , 1 または 2 が 設定される整数があります。 -``ctypes`` は型の :meth:`in_dll` クラスメソッドを使ってこのように値に +:mod:`ctypes` は型の :meth:`in_dll` クラスメソッドを使ってこのように値に アクセスできます。 *pythonapi* はPython C api へアクセスできるようにす るための予め定義されたシンボルです。:: @@ -1129,15 +1128,17 @@ ポインタの使い方を説明する拡張例では、 Python がエクスポートする ``PyImport_FrozenModules`` ポインタにアクセスします。 -Pythonドキュメントからの引用すると: *このポインタはメンバーがすべて -NULLまたはゼロであるレコードを最後に持つ "struct_frozen" レコードの配 -列を指すように初期化されます。フローズン (frozen) モジュールがインポー -トされたとき、このテーブルから探索されます。サードパーティ製コードは動 -的に作成されたフローズンモジュールの集合を提供するためと、これにいた -ずらすることができます。* +Python ドキュメントから引用すると: *このポインタは +"struct _frozen" のレコードからなり、 +終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化され ます。 +フリーズされたモジュールを import するとき、このテーブルを検索します。 +サードパーティ製のコードからこのポインタに仕掛けを講じて、 +動的に生成されたフリーズ化モジュールの集合を提供するようにできます。* + +.. 注: c-api/import より引用 これで、このポインタを操作することが役に立つことを証明できるでしょう。 -例の大きさを制限するために、このテーブルを ``ctypes`` を使って読む方法 +例の大きさを制限するために、このテーブルを :mod:`ctypes` を使って読む方法 だけを示します。:: >>> from ctypes import * @@ -1184,7 +1185,7 @@ 予期しないこと ^^^^^^^^^^^^^^ -``ctypes`` には別のことを期待しているのに実際に起きる起きることは違う +:mod:`ctypes` には別のことを期待しているのに実際に起きることは違う という場合があります。 次に示す例について考えてみてください。:: @@ -1251,14 +1252,13 @@ 可変サイズのデータ型 ^^^^^^^^^^^^^^^^^^^^ -``ctypes`` は可変サイズの配列と構造体をサポートしています (バージョン -0.9.9.7で追加されました)。 - -``resize`` 関数は既存の ctypes オブジェクトのメモリバッファのサイズを +:mod:`ctypes` は可変サイズの配列と構造体をサポートしています。 + +:func:`resize` 関数は既存の ctypes オブジェクトのメモリバッファのサイズを 変更したい場合に使えます。この関数は第一引数にオブジェクト、第二引数に 要求されたサイズをバイト単位で指定します。メモリブロックはオブジェクト 型で指定される通常のメモリブロックより小さくすることはできません。 -これをやろうとすると、 ``ValueError`` が送出されます。:: +これをやろうとすると、 :exc:`ValueError` が送出されます。:: >>> short_array = (c_short * 4)() >>> print sizeof(short_array) @@ -1286,7 +1286,7 @@ IndexError: invalid index >>> -``ctypes`` で可変サイズのデータ型を使うもう一つの方法は、必要なサイズ +:mod:`ctypes` で可変サイズのデータ型を使うもう一つの方法は、必要なサイズ が分かった後に Python の動的性質を使って一つ一つデータ型を(再)定義する ことです。 @@ -1307,12 +1307,12 @@ ときにアクセスされます。 ctypes ライブラリローダーはプログラムが動作しているときのように振る舞 -い、ランタイムローダーを直接呼び出すのに対し、 ``find_library`` 関数の +い、ランタイムローダーを直接呼び出すのに対し、 :func:`find_library` 関数の 目的はコンパイラが行うのと似た方法でライブラリを探し出すことです。 (複数のバージョンの共有ライブラリがあるプラットホームでは、一番最近に 見つかったものがロードされます)。 -``ctypes.util`` モジュールはロードするライブラリを決めるのに役立つ関数 +:mod:`ctypes.util` モジュールはロードするライブラリを決めるのに役立つ関数 を提供します。 @@ -1320,17 +1320,17 @@ :module: ctypes.util :noindex: - ライブラリを見つけてパス名を返そうと試みます。 *name* は *lib* のよ - うな接頭辞、 ``.so`` 、 ``.dylib`` のような接尾辞、あるいは、バージョ - ン番号が何も付いていないライブラリの名前です (これは posix リンカの + ライブラリを見つけてパス名を返そうと試みます。 *name* は ``lib`` のよ + うな接頭辞、 ``.so``, ``.dylib`` のような接尾辞、あるいは、バージョン + 番号が何も付いていないライブラリの名前です (これは posix リンカの オプション :option:`-l` に使われている形式です)。 もしライブラリが見つからなければ、 ``None`` を返します。 厳密な機能はシステムに依存します。 -Linux では、 ``find_library`` はライブラリファイルを見つけるために外部 -プログラム ( /sbin/ldconfig 、 gcc および objdump ) を実行しようとしま -す。ライブラリファイルのファイル名を返します。いくつか例があります。:: +Linux では、 :func:`find_library` はライブラリファイルを見つけるために外部 +プログラム (``/sbin/ldconfig``, ``gcc`` および ``objdump``) を +実行しようとします。ライブラリファイルのファイル名を返します。いくつか例が あります。:: >>> from ctypes.util import find_library >>> find_library("m") @@ -1341,7 +1341,7 @@ 'libbz2.so.1.0' >>> -OS Xでは、 ``find_library`` はライブラリの位置を探すために、予め定義さ +OS X では、 :func:`find_library` はライブラリの位置を探すために、予め定義さ れた複数の命名方法とパスを試し、成功すればフルパスを返します。:: >>> from ctypes.util import find_library @@ -1355,12 +1355,12 @@ '/System/Library/Frameworks/AGL.framework/AGL' >>> -Windows では、 ``find_library`` はシステムの探索パスに沿って探し、フル -パスを返します。しかし、予め定義された命名方法がないため、 +Windows では、 :func:`find_library` はシステムの探索パスに沿って探し、 +フルパスを返します。しかし、予め定義された命名方法がないため、 ``find_library("c")`` のような呼び出しは失敗し、 ``None`` を返します。 -もし ``ctypes`` を使って共有ライブラリをラップするなら、実行時にライブ -ラリを探すために ``find_library`` を使う代わりに、開発時に共有ライブラ +もし :mod:`ctypes` を使って共有ライブラリをラップするなら、実行時にライブ +ラリを探すために :func:`find_library` を使う代わりに、開発時に共有ライブラ リ名を決めて、ラッパーモジュールにハードコードした方が良い *かもしれません * 。 @@ -1376,7 +1376,7 @@ .. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) このクラスのインスタンスはロードされた共有ライブラリをあらわします。 - これらのライブラリの関数は標準 C 呼び出し規約を使用し、 ``int`` を + これらのライブラリの関数は標準 C 呼び出し規約を使用し、 :c:type:`int` を 返すと仮定されます。 @@ -1394,14 +1394,14 @@ Windows用: このクラスのインスタンスはロードされた共有ライブラリをあ らわします。これらのライブラリの関数は ``stdcall`` 呼び出し規約を使 - 用し、デフォルトでは ``int`` を返すと仮定されます。 + 用し、デフォルトでは :c:type:`int` を返すと仮定されます。 Windows CE では標準呼び出し規約だけが使われます。便宜上、このプラッ トホームでは、 :class:`WinDLL` と :class:`OleDLL` が標準呼び出し規 約を使用します。 これらのライブラリがエクスポートするどの関数でも呼び出す前に Python -:term:`global interpreter lock` (GIL) は解放され、後でまた獲得されます。 +GIL (:term:`global interpreter lock`) は解放され、後でまた獲得されます。 .. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None) @@ -1418,16 +1418,16 @@ ブラリのパスを渡して呼び出すことでインスタンス化されます。すでにロード 済みの共有ライブラリへのハンドルがあるなら、 ``handle`` 名前付き引数と して渡すことができます。土台となっているプラットホームの ``dlopen`` ま -たは :meth:`LoadLibrary` 関数がプロセスへライブラリをロードするために +たは ``LoadLibrary`` 関数がプロセスへライブラリをロードするために 使われ、そのライブラリに対するハンドルを得ます。 *mode* パラメータはライブラリがどうやってロードされたかを特定するため -に使うことができます。詳細は、 ``dlopen(3)`` マニュアルページを参考に +に使うことができます。詳細は、 :manpage:`dlopen(3)` マニュアルページを参考 に してください。 Windows では *mode* は無視されます。 *use_errno* 変数が True に設定されたとき、システムの :data:`errno` エラーナ ンバーに安全にアクセスする ctypes の仕組みが有効化されます。 -:mod:`ctypes` はシステムの :data:`errno` 変数のスレッド限定のコピーを管理し ます。; +:mod:`ctypes` はシステムの :data:`errno` 変数のスレッド限定のコピーを管理し ます。 もし、 ``use_errno=True`` の状態で作られた外部関数を呼び出したなら、 関数呼び出し前の :data:`errno` 変数は ctypes のプライベートコピーと置き換え られ、同じことが関数呼び出しの直後にも発生します。 @@ -1438,13 +1438,13 @@ *use_last_error* パラメータは、 True に設定されたとき、 :func:`GetLastError` と :func:`SetLastError` Windows API によって管理 -される Windows エラーコードに対するのと同じ仕組みが有効化されます。 ; +される Windows エラーコードに対するのと同じ仕組みが有効化されます。 :func:`ctypes.get_last_error` と :func:`ctypes.set_last_error` は Windows エラーコードの ctypes プライベートコピーを変更したり要求したりするのに 使われます。 .. versionadded:: 2.6 - ``use_last_error`` と ``use_errno`` オプション変数が追加されました。 + *use_last_error* と *use_errno* オプション変数が追加されました。 .. data:: RTLD_GLOBAL :noindex: @@ -1495,7 +1495,7 @@ .. class:: LibraryLoader(dlltype) - 共有ライブラリをロードするクラス。 ``dlltype`` は :class:`CDLL` 、 + 共有ライブラリをロードするクラス。 *dlltype* は :class:`CDLL` 、 :class:`PyDLL` 、 :class:`WinDLL` もしくは :class:`OleDLL` 型の一つ であるべきです。 @@ -1544,7 +1544,7 @@ :noindex: 属性として Python C api 関数を公開する :class:`PyDLL` のインスタン - ス。これらすべての関数は C ``int`` を返すと仮定されますが、もちろん + ス。これらすべての関数は C :c:type:`int` を返すと仮定されますが、もちろ ん 常に正しいとは限りません。そのため、これらの関数を使うためには正し い :attr:`restype` 属性を代入しなければなりません。 @@ -1576,10 +1576,10 @@ .. attribute:: restype 外部関数の結果の型を指定するために ctypes 型を代入する。何も返さ - ない関数を表す ``void`` に対しては ``None`` を使います。 + ない関数を表す :c:type:`void` に対しては ``None`` を使います。 ctypes 型ではない呼び出し可能な Python オブジェクトを代入するこ - とは可能です。このような場合、関数が C ``int`` を返すと仮定され、 + とは可能です。このような場合、関数が C :c:type:`int` を返すと仮定さ れ、 呼び出し可能オブジェクトはこの整数を引数に呼び出されます。さらに 処理を行ったり、エラーチェックをしたりできるようにするためです。 これの使用は推奨されません。より柔軟な後処理やエラーチェックのた @@ -1619,14 +1619,14 @@ .. function:: callable(result, func, arguments) :noindex: - ``result`` は外部関数が返すもので、 :attr:`restype` 属性で指定さ + *result* は外部関数が返すもので、 :attr:`restype` 属性で指定さ れます。 - ``func`` は外部関数オブジェクト自身で、これにより複数の関数の処 + *func* は外部関数オブジェクト自身で、これにより複数の関数の処 理結果をチェックまたは後処理するために、同じ呼び出し可能オブジェ クトを再利用できるようになります。 - ``arguments`` は関数呼び出しに最初に渡されたパラメータが入っ + *arguments* は関数呼び出しに最初に渡されたパラメータが入っ たタプルです。これにより使われた引数に基づた特別な振る舞いを させることができるようになります。 @@ -1658,7 +1658,7 @@ す。関数は呼び出されている間 GIL を解放します。 *use_errno* が True に設定されれば、呼び出しの前後で System 変数 :data:`errno` の ctypesプライベートコピーは本当の :data:`errno` の値と交 換され - ます。; + ます。 *use_last_error* も Windows エラーコードに対するのと同様です。 .. versionchanged:: 2.6 @@ -1693,8 +1693,8 @@ :noindex: :module: - Python の ``callable`` から C の呼び出し可能関数(コールバック関 - 数)を作成します。 + Python の *callable* から C の呼び出し可能関数(コールバック関数) + を作成します。 .. function:: prototype(func_spec[, paramflags]) @@ -1702,7 +1702,7 @@ :module: 共有ライブラリがエクスポートしている外部関数を返します。 - ``func_spec`` は 2 要素タプル ``(name_or_ordinal, library)`` でなけ + *func_spec* は 2 要素タプル ``(name_or_ordinal, library)`` でなけ ればなりません。第一要素はエクスポートされた関数の名前である文字列、 またはエクスポートされた関数の序数である小さい整数です。第二要素は 共有ライブラリインスタンスです。 @@ -1712,7 +1712,7 @@ :noindex: :module: - COM メソッドを呼び出す外部関数を返します。 ``vtbl_index`` は仮想 + COM メソッドを呼び出す外部関数を返します。 *vtbl_index* は仮想 関数テーブルのインデックスで、非負の小さい整数です。 *name* は COM メソッドの名前です。 *iid* はオプションのインター フェイス識別子へのポインタで、拡張されたエラー情報の提供のために @@ -1759,7 +1759,7 @@ LPCSTR lpCaption, UINT uType); -``ctypes`` を使ってラップします。:: +:mod:`ctypes` を使ってラップします。:: >>> from ctypes import c_int, WINFUNCTYPE, windll >>> from ctypes.wintypes import HWND, LPCSTR, UINT @@ -1785,7 +1785,7 @@ HWND hWnd, LPRECT lpRect); -``ctypes`` を使ってラップします。:: +:mod:`ctypes` を使ってラップします。:: >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError >>> from ctypes.wintypes import BOOL, HWND, RECT @@ -1815,7 +1815,7 @@ >>> :attr:`errcheck` 関数が変更なしに受け取った引数タプルを返したならば、 -``ctypes`` は出力パラメータに対して通常の処理を続けます。 +:mod:`ctypes` は出力パラメータに対して通常の処理を続けます。 ``RECT`` インスタンスの代わりに window 座標のタプルを返してほしいなら、 関数のフィールドを取り出し、代わりにそれらを返すことができます。 通常処理はもはや行われないでしょう。:: @@ -1838,21 +1838,21 @@ .. function:: addressof(obj) - メモリバッファのアドレスを示す整数を返します。 ``obj`` は ctypes 型 + メモリバッファのアドレスを示す整数を返します。 *obj* は ctypes 型 のインスタンスでなければなりません。 .. function:: alignment(obj_or_type) - ctypes 型のアライメントの必要条件を返します。 ``obj_or_type`` は + ctypes 型のアライメントの必要条件を返します。 *obj_or_type* は ctypes 型またはインスタンスでなければなりません。 .. function:: byref(obj[, offset]) - ``obj`` (ctypes 型のインスタンスでなければならない) への軽量ポイン - タを返します。 ``offset`` はデフォルトでは 0 で、内部ポインターへ加 - 算される整数です。 + *obj* (ctypes 型のインスタンスでなければならない) への軽量ポインタを + 返します。 *offset* はデフォルトでは 0 で、内部ポインターへ加算される + 整数です。 ``byref(obj, offset)`` は、 C コードとしては、以下のようにみなされ ます。:: @@ -1864,14 +1864,14 @@ く行えます。 .. versionadded:: 2.6 - ``offset`` オプション引数が追加れました。 + *offset* オプション引数が追加されました。 .. function:: cast(obj, type) - この関数は C のキャスト演算子に似ています。 ``obj`` と同じメモリブ - ロックを指している ``type`` の新しいインスタンスを返します。 - ``type`` はポインタ型でなければならず、 ``obj`` はポインタとして解 + この関数は C のキャスト演算子に似ています。 *obj* と同じメモリブ + ロックを指している *type* の新しいインスタンスを返します。 + *type* はポインタ型でなければならず、 *obj* はポインタとして解 釈できるオブジェクトでなければなりません。 @@ -1880,7 +1880,7 @@ この関数は変更可能な文字バッファを作成します。返されるオブジェクト は :class:`c_char` の ctypes 配列です。 - ``init_or_size`` は配列のサイズを指定する整数もしくは配列要素を初期 + *init_or_size* は配列のサイズを指定する整数もしくは配列要素を初期 化するために使われる文字列である必要があります。 第一引数として文字列が指定された場合は、バッファが文字列の長さより @@ -1898,7 +1898,7 @@ この関数は変更可能なユニコード文字バッファを作成します。返されるオ ブジェクトは :class:`c_wchar` の ctypes 配列です。 - ``init_or_size`` は配列のサイズを指定する整数もしくは配列要素を初期 + *init_or_size* は配列のサイズを指定する整数もしくは配列要素を初期 化するために使われるユニコード文字列です。 第一引数としてユニコード文字列が指定された場合は、バッファが文字列 @@ -1954,9 +1954,10 @@ .. versionadded:: 2.6 + .. function:: FormatError([code]) - Windows用: エラーコードの説明文を返します。エラーコードが指定されな + Windows用: エラーコード *code* の説明文を返します。エラーコードが指定さ れな い場合は、 Windows api 関数 GetLastError を呼び出して、もっとも新し いエラーコードが使われます。 @@ -1984,7 +1985,7 @@ .. function:: memmove(dst, src, count) 標準 C の memmove ライブラリ関数と同じものです。: *count* バイトを - ``src`` から *dst* へコピーします。 *dst* と ``src`` はポインタへ変 + *src* から *dst* へコピーします。 *dst* と *src* はポインタへ変 換可能な整数または ctypes インスタンスでなければなりません。 @@ -2000,14 +2001,14 @@ このファクトリ関数は新しい ctypes ポインタ型を作成して返します。ポ インタ型はキャッシュされ、内部で再利用されます。したがって、この関 - 数を繰り返し呼び出してもコストは小さいです。型は ctypes 型でなけれ + 数を繰り返し呼び出してもコストは小さいです。 *type* は ctypes 型でなけれ ばなりません。 .. function:: pointer(obj) - この関数は ``obj`` を指す新しいポインタインスタンスを作成します。戻 - り値は POINTER(type(obj)) 型のオブジェクトです。 + この関数は *obj* を指す新しいポインタインスタンスを作成します。戻 + り値は ``POINTER(type(obj))`` 型のオブジェクトです。 注意: 外部関数呼び出しへオブジェクトへのポインタを渡したいだけなら、 はるかに高速な ``byref(obj)`` を使うべきです。 @@ -2015,25 +2016,24 @@ .. function:: resize(obj, size) - この関数は obj の内部メモリバッファのサイズを変更します。 obj は - ctypes 型のインスタンスでなければなりません。 - バッファを sizeof(type(obj)) で与えられるオブジェクト型の本来のサイ - ズより小さくすることはできませんが、バッファを拡大することはできま - す。 + この関数は *obj* の内部メモリバッファのサイズを変更します。 *obj* + は ctypes 型のインスタンスでなければなりません。 + バッファを ``sizeof(type(obj))`` で与えられるオブジェクト型の本来の + サイズより小さくすることはできませんが、バッファを拡大することはできま す。 .. function:: set_conversion_mode(encoding, errors) この関数は 8 ビット文字列とユニコード文字列の間で変換するときに使わ - れる規則を設定します。 encoding は ``'utf-8'`` や ``'mbcs'`` のよう - なエンコーディングを指定する文字列でなければなりません。 errors は + れる規則を設定します。 *encoding* は ``'utf-8'`` や ``'mbcs'`` のよう + なエンコーディングを指定する文字列でなければなりません。 *errors* は エンコーディング/デコーディングエラーについてのエラー処理を指定する - 文字列でなければなりません。指定可能な値の例としては、 ``"strict"`` - 、 ``"replace"`` または ``"ignore"`` があります。 ***The diff for this file has been truncated for email.***
