diff options
| author | Sandro Tosi <sandro.tosi@gmail.com> | 2012-01-14 15:42:02 (GMT) |
|---|---|---|
| committer | Sandro Tosi <sandro.tosi@gmail.com> | 2012-01-14 15:42:02 (GMT) |
| commit | 98ed08f24e4b7b7a5d82fb1e07ad5a0319291c2b (patch) | |
| tree | ea97c15200ee6221998e0ea6eb1ca5f1b3faccd7 /Doc/library | |
| parent | bbd41d0874c49f756b3a7bcdcbf1e5ac61137377 (diff) | |
| download | cpython-98ed08f24e4b7b7a5d82fb1e07ad5a0319291c2b.zip cpython-98ed08f24e4b7b7a5d82fb1e07ad5a0319291c2b.tar.gz cpython-98ed08f24e4b7b7a5d82fb1e07ad5a0319291c2b.tar.bz2 | |
update to new C roles and directives
Diffstat (limited to 'Doc/library')
46 files changed, 310 insertions, 310 deletions
diff --git a/Doc/library/al.rst b/Doc/library/al.rst index 12cec42..ad2eaea 100644 --- a/Doc/library/al.rst +++ b/Doc/library/al.rst @@ -53,7 +53,7 @@ The module defines the following functions: .. function:: queryparams(device) The device argument is an integer. The return value is a list of integers - containing the data returned by :cfunc:`ALqueryparams`. + containing the data returned by :c:func:`ALqueryparams`. .. function:: getparams(device, list) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index f7fb4e3..d34cf38 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -107,7 +107,7 @@ The following data items and methods are also supported: memory buffer in bytes can be computed as ``array.buffer_info()[1] * array.itemsize``. This is occasionally useful when working with low-level (and inherently unsafe) I/O interfaces that require memory addresses, such as certain - :cfunc:`ioctl` operations. The returned numbers are valid as long as the array + :c:func:`ioctl` operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it. .. note:: diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst index 6f4af41..37d001b 100644 --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -34,7 +34,7 @@ connection requests. Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events that are generated by an analysis of socket conditions after a - :cfunc:`select` call. Once the polling loop has been started the + :c:func:`select` call. Once the polling loop has been started the :class:`async_chat` object's methods are called by the event-processing framework with no action on the part of the programmer. diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst index 33f22d3..c108450 100644 --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -25,7 +25,7 @@ bound. If your program is processor bound, then pre-emptive scheduled threads are probably what you really need. Network servers are rarely processor bound, however. -If your operating system supports the :cfunc:`select` system call in its I/O +If your operating system supports the :c:func:`select` system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the "background." Although this strategy can seem strange and @@ -95,8 +95,8 @@ any that have been added to the map during asynchronous service) is closed. During asynchronous processing, each mapped channel's :meth:`readable` and :meth:`writable` methods are used to determine whether the channel's socket - should be added to the list of channels :cfunc:`select`\ ed or - :cfunc:`poll`\ ed for read and write events. + should be added to the list of channels :c:func:`select`\ ed or + :c:func:`poll`\ ed for read and write events. Thus, the set of channel events is larger than the basic socket events. The full set of methods that can be overridden in your subclass follows: @@ -238,9 +238,9 @@ any that have been added to the map during asynchronous service) is closed. .. class:: file_dispatcher() A file_dispatcher takes a file descriptor or file object along with an - optional map argument and wraps it for use with the :cfunc:`poll` or - :cfunc:`loop` functions. If provided a file object or anything with a - :cfunc:`fileno` method, that method will be called and passed to the + optional map argument and wraps it for use with the :c:func:`poll` or + :c:func:`loop` functions. If provided a file object or anything with a + :c:func:`fileno` method, that method will be called and passed to the :class:`file_wrapper` constructor. Availability: UNIX. .. class:: file_wrapper() diff --git a/Doc/library/bsddb.rst b/Doc/library/bsddb.rst index 612a4a8..cdd380a 100644 --- a/Doc/library/bsddb.rst +++ b/Doc/library/bsddb.rst @@ -54,7 +54,7 @@ arguments should be used in most instances. optional *flag* identifies the mode used to open the file. It may be ``'r'`` (read only), ``'w'`` (read-write) , ``'c'`` (read-write - create if necessary; the default) or ``'n'`` (read-write - truncate to zero length). The other - arguments are rarely used and are just passed to the low-level :cfunc:`dbopen` + arguments are rarely used and are just passed to the low-level :c:func:`dbopen` function. Consult the Berkeley DB documentation for their use and interpretation. diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 82cf912..62bb504 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -759,9 +759,9 @@ Encodings and Unicode --------------------- Unicode strings are stored internally as sequences of codepoints (to be precise -as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either +as :c:type:`Py_UNICODE` arrays). Depending on the way Python is compiled (either via ``--enable-unicode=ucs2`` or ``--enable-unicode=ucs4``, with the -former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data +former being the default) :c:type:`Py_UNICODE` is either a 16-bit or 32-bit data type. Once a Unicode object is used outside of CPU and memory, CPU endianness and how these arrays are stored as bytes become an issue. Transforming a unicode object into a sequence of bytes is called encoding and recreating the diff --git a/Doc/library/commands.rst b/Doc/library/commands.rst index 916e4a5..46ff823 100644 --- a/Doc/library/commands.rst +++ b/Doc/library/commands.rst @@ -38,7 +38,7 @@ The :mod:`commands` module defines the following functions: ``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the returned output will contain output or error messages. A trailing newline is stripped from the output. The exit status for the command can be interpreted - according to the rules for the C function :cfunc:`wait`. + according to the rules for the C function :c:func:`wait`. .. function:: getoutput(cmd) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 1a3e2f5..4913b82 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -40,7 +40,7 @@ You load libraries by accessing them as attributes of these objects. *cdll* loads libraries which export functions using the standard ``cdecl`` calling convention, while *windll* libraries call functions using the ``stdcall`` calling convention. *oledll* also uses the ``stdcall`` calling convention, and -assumes the functions return a Windows :ctype:`HRESULT` error code. The error +assumes the functions return a Windows :c:type:`HRESULT` error code. The error code is used to automatically raise a :class:`WindowsError` exception when the function call fails. @@ -201,9 +201,9 @@ should be careful anyway. ``None``, integers, longs, byte strings and unicode strings are the only native Python objects that can directly be used as parameters in these function calls. ``None`` is passed as a C ``NULL`` pointer, byte strings and unicode strings are -passed as pointer to the memory block that contains their data (:ctype:`char *` -or :ctype:`wchar_t *`). Python integers and Python longs are passed as the -platforms default C :ctype:`int` type, their value is masked to fit into the C +passed as pointer to the memory block that contains their data (:c:type:`char *` +or :c:type:`wchar_t *`). Python integers and Python longs are passed as the +platforms default C :c:type:`int` type, their value is masked to fit into the C type. Before we move on calling functions with other parameter types, we have to learn @@ -217,48 +217,48 @@ Fundamental data types :mod:`ctypes` defines a number of primitive C compatible data types : -+----------------------+----------------------------------------+----------------------------+ -| ctypes type | C type | Python type | -+======================+========================================+============================+ -| :class:`c_bool` | :ctype:`_Bool` | bool (1) | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_char` | :ctype:`char` | 1-character string | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_wchar` | :ctype:`wchar_t` | 1-character unicode string | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_byte` | :ctype:`char` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_ubyte` | :ctype:`unsigned char` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_short` | :ctype:`short` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_ushort` | :ctype:`unsigned short` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_int` | :ctype:`int` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_uint` | :ctype:`unsigned int` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_long` | :ctype:`long` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_ulong` | :ctype:`unsigned long` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_longlong` | :ctype:`__int64` or :ctype:`long long` | int/long | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_ulonglong` | :ctype:`unsigned __int64` or | int/long | -| | :ctype:`unsigned long long` | | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_float` | :ctype:`float` | float | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_double` | :ctype:`double` | float | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_longdouble`| :ctype:`long double` | float | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_char_p` | :ctype:`char *` (NUL terminated) | string or ``None`` | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_wchar_p` | :ctype:`wchar_t *` (NUL terminated) | unicode or ``None`` | -+----------------------+----------------------------------------+----------------------------+ -| :class:`c_void_p` | :ctype:`void *` | int/long or ``None`` | -+----------------------+----------------------------------------+----------------------------+ ++----------------------+------------------------------------------+----------------------------+ +| ctypes type | C type | Python type | ++======================+==========================================+============================+ +| :class:`c_bool` | :c:type:`_Bool` | bool (1) | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_char` | :c:type:`char` | 1-character string | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_wchar` | :c:type:`wchar_t` | 1-character unicode string | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_byte` | :c:type:`char` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_ubyte` | :c:type:`unsigned char` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_short` | :c:type:`short` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_ushort` | :c:type:`unsigned short` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_int` | :c:type:`int` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_uint` | :c:type:`unsigned int` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_long` | :c:type:`long` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_ulong` | :c:type:`unsigned long` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_longlong` | :c:type:`__int64` or :c:type:`long long` | int/long | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_ulonglong` | :c:type:`unsigned __int64` or | int/long | +| | :c:type:`unsigned long long` | | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_float` | :c:type:`float` | float | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_double` | :c:type:`double` | float | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_longdouble`| :c:type:`long double` | float | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_char_p` | :c:type:`char *` (NUL terminated) | string or ``None`` | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL terminated) | unicode or ``None`` | ++----------------------+------------------------------------------+----------------------------+ +| :class:`c_void_p` | :c:type:`void *` | int/long or ``None`` | ++----------------------+------------------------------------------+----------------------------+ (1) The constructor accepts any object with a truth value. @@ -329,7 +329,7 @@ property:: The :func:`create_string_buffer` function replaces the :func:`c_buffer` function (which is still available as an alias), as well as the :func:`c_string` function from earlier ctypes releases. To create a mutable memory block containing -unicode characters of the C type :ctype:`wchar_t` use the +unicode characters of the C type :c:type:`wchar_t` use the :func:`create_unicode_buffer` function. @@ -440,7 +440,7 @@ integer, string, unicode, a :mod:`ctypes` instance, or an object with an Return types ^^^^^^^^^^^^ -By default functions are assumed to return the C :ctype:`int` type. Other +By default functions are assumed to return the C :c:type:`int` type. Other return types can be specified by setting the :attr:`restype` attribute of the function object. @@ -1338,7 +1338,7 @@ way is to instantiate one of the following classes: Instances of this class represent loaded shared libraries. Functions in these libraries use the standard C calling convention, and are assumed to return - :ctype:`int`. + :c:type:`int`. .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False) @@ -1355,7 +1355,7 @@ way is to instantiate one of the following classes: Windows only: Instances of this class represent loaded shared libraries, functions in these libraries use the ``stdcall`` calling convention, and are - assumed to return :ctype:`int` by default. + assumed to return :c:type:`int` by default. On Windows CE only the standard calling convention is used, for convenience the :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this @@ -1500,7 +1500,7 @@ object is available: An instance of :class:`PyDLL` that exposes Python C API functions as attributes. Note that all these functions are assumed to return C - :ctype:`int`, which is of course not always the truth, so you have to assign + :c:type:`int`, which is of course not always the truth, so you have to assign the correct :attr:`restype` attribute to use these functions. @@ -1530,10 +1530,10 @@ They are instances of a private class: .. attribute:: restype Assign a ctypes type to specify the result type of the foreign function. - Use ``None`` for :ctype:`void`, a function not returning anything. + Use ``None`` for :c:type:`void`, a function not returning anything. It is possible to assign a callable Python object that is not a ctypes - type, in this case the function is assumed to return a C :ctype:`int`, and + type, in this case the function is assumed to return a C :c:type:`int`, and the callable will be called with this integer, allowing to do further processing or error checking. Using this is deprecated, for more flexible post processing or error checking use a ctypes data type as @@ -2159,21 +2159,21 @@ These are the fundamental ctypes data types: .. class:: c_byte - Represents the C :ctype:`signed char` datatype, and interprets the value as + Represents the C :c:type:`signed char` datatype, and interprets the value as small integer. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_char - Represents the C :ctype:`char` datatype, and interprets the value as a single + Represents the C :c:type:`char` datatype, and interprets the value as a single character. The constructor accepts an optional string initializer, the length of the string must be exactly one character. .. class:: c_char_p - Represents the C :ctype:`char *` datatype when it points to a zero-terminated + Represents the C :c:type:`char *` datatype when it points to a zero-terminated string. For a general character pointer that may also point to binary data, ``POINTER(c_char)`` must be used. The constructor accepts an integer address, or a string. @@ -2181,13 +2181,13 @@ These are the fundamental ctypes data types: .. class:: c_double - Represents the C :ctype:`double` datatype. The constructor accepts an + Represents the C :c:type:`double` datatype. The constructor accepts an optional float initializer. .. class:: c_longdouble - Represents the C :ctype:`long double` datatype. The constructor accepts an + Represents the C :c:type:`long double` datatype. The constructor accepts an optional float initializer. On platforms where ``sizeof(long double) == sizeof(double)`` it is an alias to :class:`c_double`. @@ -2195,150 +2195,150 @@ These are the fundamental ctypes data types: .. class:: c_float - Represents the C :ctype:`float` datatype. The constructor accepts an + Represents the C :c:type:`float` datatype. The constructor accepts an optional float initializer. .. class:: c_int - Represents the C :ctype:`signed int` datatype. The constructor accepts an + Represents the C :c:type:`signed int` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. On platforms where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`. .. class:: c_int8 - Represents the C 8-bit :ctype:`signed int` datatype. Usually an alias for + Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for :class:`c_byte`. .. class:: c_int16 - Represents the C 16-bit :ctype:`signed int` datatype. Usually an alias for + Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias for :class:`c_short`. .. class:: c_int32 - Represents the C 32-bit :ctype:`signed int` datatype. Usually an alias for + Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias for :class:`c_int`. .. class:: c_int64 - Represents the C 64-bit :ctype:`signed int` datatype. Usually an alias for + Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias for :class:`c_longlong`. .. class:: c_long - Represents the C :ctype:`signed long` datatype. The constructor accepts an + Represents the C :c:type:`signed long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_longlong - Represents the C :ctype:`signed long long` datatype. The constructor accepts + Represents the C :c:type:`signed long long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_short - Represents the C :ctype:`signed short` datatype. The constructor accepts an + Represents the C :c:type:`signed short` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_size_t - Represents the C :ctype:`size_t` datatype. + Represents the C :c:type:`size_t` datatype. .. class:: c_ssize_t - Represents the C :ctype:`ssize_t` datatype. + Represents the C :c:type:`ssize_t` datatype. .. versionadded:: 2.7 .. class:: c_ubyte - Represents the C :ctype:`unsigned char` datatype, it interprets the value as + Represents the C :c:type:`unsigned char` datatype, it interprets the value as small integer. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_uint - Represents the C :ctype:`unsigned int` datatype. The constructor accepts an + Represents the C :c:type:`unsigned int` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. On platforms where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`. .. class:: c_uint8 - Represents the C 8-bit :ctype:`unsigned int` datatype. Usually an alias for + Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias for :class:`c_ubyte`. .. class:: c_uint16 - Represents the C 16-bit :ctype:`unsigned int` datatype. Usually an alias for + Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias for :class:`c_ushort`. .. class:: c_uint32 - Represents the C 32-bit :ctype:`unsigned int` datatype. Usually an alias for + Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias for :class:`c_uint`. .. class:: c_uint64 - Represents the C 64-bit :ctype:`unsigned int` datatype. Usually an alias for + Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias for :class:`c_ulonglong`. .. class:: c_ulong - Represents the C :ctype:`unsigned long` datatype. The constructor accepts an + Represents the C :c:type:`unsigned long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_ulonglong - Represents the C :ctype:`unsigned long long` datatype. The constructor + Represents the C :c:type:`unsigned long long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_ushort - Represents the C :ctype:`unsigned short` datatype. The constructor accepts + Represents the C :c:type:`unsigned short` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. .. class:: c_void_p - Represents the C :ctype:`void *` type. The value is represented as integer. + Represents the C :c:type:`void *` type. The value is represented as integer. The constructor accepts an optional integer initializer. .. class:: c_wchar - Represents the C :ctype:`wchar_t` datatype, and interprets the value as a + Represents the C :c:type:`wchar_t` datatype, and interprets the value as a single character unicode string. The constructor accepts an optional string initializer, the length of the string must be exactly one character. .. class:: c_wchar_p - Represents the C :ctype:`wchar_t *` datatype, which must be a pointer to a + Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a zero-terminated wide character string. The constructor accepts an integer address, or a string. .. class:: c_bool - Represent the C :ctype:`bool` datatype (more accurately, :ctype:`_Bool` from + Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` from C99). Its value can be True or False, and the constructor accepts any object that has a truth value. @@ -2347,18 +2347,18 @@ These are the fundamental ctypes data types: .. class:: HRESULT - Windows only: Represents a :ctype:`HRESULT` value, which contains success or + Windows only: Represents a :c:type:`HRESULT` value, which contains success or error information for a function or method call. .. class:: py_object - Represents the C :ctype:`PyObject *` datatype. Calling this without an - argument creates a ``NULL`` :ctype:`PyObject *` pointer. + Represents the C :c:type:`PyObject *` datatype. Calling this without an + argument creates a ``NULL`` :c:type:`PyObject *` pointer. The :mod:`ctypes.wintypes` module provides quite some other Windows specific -data types, for example :ctype:`HWND`, :ctype:`WPARAM`, or :ctype:`DWORD`. Some -useful structures like :ctype:`MSG` or :ctype:`RECT` are also defined. +data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some +useful structures like :c:type:`MSG` or :c:type:`RECT` are also defined. .. _ctypes-structured-data-types: diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 55acf67..c94064d 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -360,7 +360,7 @@ Other constructors, all class methods: Return the local date corresponding to the POSIX timestamp, such as is returned by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out - of the range of values supported by the platform C :cfunc:`localtime` function. + of the range of values supported by the platform C :c:func:`localtime` function. It's common for this to be restricted to years from 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`. @@ -534,7 +534,7 @@ Instance methods: Return a string representing the date, for example ``date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C - :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which + :c:func:`ctime` function (which :func:`time.ctime` invokes, but which :meth:`date.ctime` does not invoke) conforms to the C standard. @@ -641,7 +641,7 @@ Other constructors, all class methods: or not specified, this is like :meth:`today`, but, if possible, supplies more precision than can be gotten from going through a :func:`time.time` timestamp (for example, this may be possible on platforms supplying the C - :cfunc:`gettimeofday` function). + :c:func:`gettimeofday` function). Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the current date and time are converted to *tz*'s time zone. In this case the @@ -669,8 +669,8 @@ Other constructors, all class methods: ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``. :meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of - the range of values supported by the platform C :cfunc:`localtime` or - :cfunc:`gmtime` functions. It's common for this to be restricted to years in + the range of values supported by the platform C :c:func:`localtime` or + :c:func:`gmtime` functions. It's common for this to be restricted to years in 1970 through 2038. Note that on non-POSIX systems that include leap seconds in their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`, and then it's possible to have two timestamps differing by a second that yield @@ -681,7 +681,7 @@ Other constructors, all class methods: Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is - out of the range of values supported by the platform C :cfunc:`gmtime` function. + out of the range of values supported by the platform C :c:func:`gmtime` function. It's common for this to be restricted to years in 1970 through 2038. See also :meth:`fromtimestamp`. @@ -1024,7 +1024,7 @@ Instance methods: Return a string representing the date and time, for example ``datetime(2002, 12, 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the - native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which + native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which :meth:`datetime.ctime` does not invoke) conforms to the C standard. diff --git a/Doc/library/dl.rst b/Doc/library/dl.rst index a383729..13510c5 100644 --- a/Doc/library/dl.rst +++ b/Doc/library/dl.rst @@ -13,7 +13,7 @@ .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> -The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which +The :mod:`dl` module defines an interface to the :c:func:`dlopen` function, which is the most common interface on Unix platforms for handling dynamically linked libraries. It allows the program to call arbitrary functions in such a library. @@ -105,10 +105,10 @@ Dl objects, as returned by :func:`.open` above, have the following methods: Call the function named *name* in the referenced shared object. The arguments must be either Python integers, which will be passed as is, Python strings, to which a pointer will be passed, or ``None``, which will be passed as *NULL*. - Note that strings should only be passed to functions as :ctype:`const char\*`, + Note that strings should only be passed to functions as :c:type:`const char\*`, as Python will not like its string mutated. There must be at most 10 arguments, and arguments not given will be treated as - ``None``. The function's return value must be a C :ctype:`long`, which is a + ``None``. The function's return value must be a C :c:type:`long`, which is a Python integer. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 8bd903a..6c80df7 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -220,7 +220,7 @@ The following exceptions are the exceptions that are actually raised. Raised when an operation runs out of memory but the situation may still be rescued (by deleting some objects). The associated value is a string indicating what kind of (internal) operation ran out of memory. Note that because of the - underlying memory management architecture (C's :cfunc:`malloc` function), the + underlying memory management architecture (C's :c:func:`malloc` function), the interpreter may not always be able to completely recover from this situation; it nevertheless raises an exception so that a stack traceback can be printed, in case a run-away program was the cause. @@ -249,8 +249,8 @@ The following exceptions are the exceptions that are actually raised. This exception is derived from :exc:`EnvironmentError`. It is raised when a function returns a system-related error (not for illegal argument types or other incidental errors). The :attr:`errno` attribute is a numeric error - code from :cdata:`errno`, and the :attr:`strerror` attribute is the - corresponding string, as would be printed by the C function :cfunc:`perror`. + code from :c:data:`errno`, and the :attr:`strerror` attribute is the + corresponding string, as would be printed by the C function :c:func:`perror`. See the module :mod:`errno`, which contains names for the error codes defined by the underlying operating system. @@ -342,7 +342,7 @@ The following exceptions are the exceptions that are actually raised. This exception is raised by the :func:`sys.exit` function. When it is not handled, the Python interpreter exits; no stack traceback is printed. If the associated value is a plain integer, it specifies the system exit status (passed - to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if + to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if it has another type (such as a string), the object's value is printed and the exit status is one. @@ -429,16 +429,16 @@ The following exceptions are the exceptions that are actually raised. .. exception:: WindowsError Raised when a Windows-specific error occurs or when the error number does not - correspond to an :cdata:`errno` value. The :attr:`winerror` and + correspond to an :c:data:`errno` value. The :attr:`winerror` and :attr:`strerror` values are created from the return values of the - :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows + :c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows Platform API. The :attr:`errno` value maps the :attr:`winerror` value to corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`. .. versionadded:: 2.0 .. versionchanged:: 2.5 - Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`. + Previous versions put the :c:func:`GetLastError` codes into :attr:`errno`. .. exception:: ZeroDivisionError diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index d0430c2..40ae08b 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -13,7 +13,7 @@ pair: UNIX; I/O control This module performs file control and I/O control on file descriptors. It is an -interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines. +interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. All functions in this module take a file descriptor *fd* as their first argument. This can be an integer file descriptor, such as returned by @@ -31,17 +31,17 @@ The module defines the following functions: :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer value ``0``. When present, it can either be an integer value, or a string. With the argument missing or an integer value, the return value of this function - is the integer return value of the C :cfunc:`fcntl` call. When the argument is + is the integer return value of the C :c:func:`fcntl` call. When the argument is a string it represents a binary structure, e.g. created by :func:`struct.pack`. The binary data is copied to a buffer whose address is passed to the C - :cfunc:`fcntl` call. The return value after a successful call is the contents + :c:func:`fcntl` call. The return value after a successful call is the contents of the buffer, converted to a string object. The length of the returned string will be the same as the length of the *arg* argument. This is limited to 1024 bytes. If the information returned in the buffer by the operating system is larger than 1024 bytes, this is most likely to result in a segmentation violation or a more subtle data corruption. - If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised. + If the :c:func:`fcntl` fails, an :exc:`IOError` is raised. .. function:: ioctl(fd, op[, arg[, mutate_flag]]) @@ -97,7 +97,7 @@ The module defines the following functions: Perform the lock operation *op* on file descriptor *fd* (file objects providing a :meth:`fileno` method are accepted as well). See the Unix manual :manpage:`flock(2)` for details. (On some systems, this function is emulated - using :cfunc:`fcntl`.) + using :c:func:`fcntl`.) .. function:: lockf(fd, operation, [length, [start, [whence]]]) diff --git a/Doc/library/fl.rst b/Doc/library/fl.rst index a5a426a..540cac9 100644 --- a/Doc/library/fl.rst +++ b/Doc/library/fl.rst @@ -29,8 +29,8 @@ The creation of objects is a little different in Python than in C: instead of the 'current form' maintained by the library to which new FORMS objects are added, all functions that add a FORMS object to a form are methods of the Python object representing the form. Consequently, there are no Python equivalents for -the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the -equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`. +the C functions :c:func:`fl_addto_form` and :c:func:`fl_end_form`, and the +equivalent of :c:func:`fl_bgn_form` is called :func:`fl.make_form`. Watch out for the somewhat confusing terminology: FORMS uses the word :dfn:`object` for the buttons, sliders etc. that you can place in a form. In @@ -44,7 +44,7 @@ easy way to add object classes written in Python. The FORMS interface to GL event handling is available, though, so you can mix FORMS with pure GL windows. **Please note:** importing :mod:`fl` implies a call to the GL function -:cfunc:`foreground` and to the FORMS routine :cfunc:`fl_init`. +:c:func:`foreground` and to the FORMS routine :c:func:`fl_init`. .. _fl-functions: @@ -88,7 +88,7 @@ documentation: .. function:: get_rgbmode() Return the current rgb mode. This is the value of the C global variable - :cdata:`fl_rgbmode`. + :c:data:`fl_rgbmode`. .. function:: show_message(str1, str2, str3) @@ -153,8 +153,8 @@ documentation: mapcolor() getmcolor() - See the description in the FORMS documentation of :cfunc:`fl_color`, - :cfunc:`fl_mapcolor` and :cfunc:`fl_getmcolor`. + See the description in the FORMS documentation of :c:func:`fl_color`, + :c:func:`fl_mapcolor` and :c:func:`fl_getmcolor`. .. _form-objects: diff --git a/Doc/library/fm.rst b/Doc/library/fm.rst index e46506b..6bf6808 100644 --- a/Doc/library/fm.rst +++ b/Doc/library/fm.rst @@ -30,7 +30,7 @@ It supports the following operations: .. function:: init() - Initialization function. Calls :cfunc:`fminit`. It is normally not necessary to + Initialization function. Calls :c:func:`fminit`. It is normally not necessary to call this function, since it is called automatically the first time the :mod:`fm` module is imported. @@ -43,7 +43,7 @@ It supports the following operations: .. function:: enumerate() Returns a list of available font names. This is an interface to - :cfunc:`fmenumerate`. + :c:func:`fmenumerate`. .. function:: prstr(string) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 739350b..6f3473e 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -808,7 +808,7 @@ available. They are listed here in alphabetical order. :exc:`IOError` is raised. When opening a file, it's preferable to use :func:`open` instead of invoking the :class:`file` constructor directly. - The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`: + The first two arguments are the same as for ``stdio``'s :c:func:`fopen`: *name* is the file name to be opened, and *mode* is a string indicating how the file is to be opened. @@ -841,7 +841,7 @@ available. They are listed here in alphabetical order. binary mode, on systems that differentiate between binary and text files; on systems that don't have this distinction, adding the ``'b'`` has no effect. - In addition to the standard :cfunc:`fopen` values *mode* may be ``'U'`` or + In addition to the standard :c:func:`fopen` values *mode* may be ``'U'`` or ``'rU'``. Python is usually built with universal newline support; supplying ``'U'`` opens the file as a text file, but lines may be terminated by any of the following: the Unix end-of-line convention ``'\n'``, the Macintosh convention @@ -1662,8 +1662,8 @@ bypass these functions without concerns about missing something important. .. [#] It is used relatively rarely so does not warrant being made into a statement. .. [#] Specifying a buffer size currently has no effect on systems that don't have - :cfunc:`setvbuf`. The interface to specify the buffer size is not done using a - method that calls :cfunc:`setvbuf`, because that may dump core when called after + :c:func:`setvbuf`. The interface to specify the buffer size is not done using a + method that calls :c:func:`setvbuf`, because that may dump core when called after any I/O has been performed, and there's no reliable way to determine whether this is the case. diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index 11385ff..b3ba614 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -11,13 +11,13 @@ .. note:: The :mod:`getopt` module is a parser for command line options whose API is - designed to be familiar to users of the C :cfunc:`getopt` function. Users who - are unfamiliar with the C :cfunc:`getopt` function or who would like to write + designed to be familiar to users of the C :c:func:`getopt` function. Users who + are unfamiliar with the C :c:func:`getopt` function or who would like to write less code and get better help and error messages should consider using the :mod:`argparse` module instead. This module helps scripts to parse the command line arguments in ``sys.argv``. -It supports the same conventions as the Unix :cfunc:`getopt` function (including +It supports the same conventions as the Unix :c:func:`getopt` function (including the special meanings of arguments of the form '``-``' and '``--``'). Long options similar to those supported by GNU software may be used as well via an optional third argument. @@ -32,11 +32,11 @@ exception: be parsed, without the leading reference to the running program. Typically, this means ``sys.argv[1:]``. *options* is the string of option letters that the script wants to recognize, with options that require an argument followed by a - colon (``':'``; i.e., the same format that Unix :cfunc:`getopt` uses). + colon (``':'``; i.e., the same format that Unix :c:func:`getopt` uses). .. note:: - Unlike GNU :cfunc:`getopt`, after a non-option argument, all further + Unlike GNU :c:func:`getopt`, after a non-option argument, all further arguments are considered also non-options. This is similar to the way non-GNU Unix systems work. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index e05618e..2b41bec 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -366,7 +366,7 @@ Note: .. impl-detail:: getsets are attributes defined in extension modules via - :ctype:`PyGetSetDef` structures. For Python implementations without such + :c:type:`PyGetSetDef` structures. For Python implementations without such types, this method will always return ``False``. .. versionadded:: 2.5 @@ -379,7 +379,7 @@ Note: .. impl-detail:: Member descriptors are attributes defined in extension modules via - :ctype:`PyMemberDef` structures. For Python implementations without such + :c:type:`PyMemberDef` structures. For Python implementations without such types, this method will always return ``False``. .. versionadded:: 2.5 diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index 9cc3ab5..36fbde8 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -219,7 +219,7 @@ The :mod:`locale` module defines the following exception and functions: .. note:: - The expression is in the syntax suitable for the :cfunc:`regex` function + The expression is in the syntax suitable for the :c:func:`regex` function from the C library, which might differ from the syntax used in :mod:`re`. .. data:: NOEXPR @@ -560,7 +560,7 @@ catalogs, and the C library's search algorithms for locating message catalogs. Python applications should normally find no need to invoke these functions, and should use :mod:`gettext` instead. A known exception to this rule are applications that link with additional C libraries which internally invoke -:cfunc:`gettext` or :func:`dcgettext`. For these applications, it may be +:c:func:`gettext` or :func:`dcgettext`. For these applications, it may be necessary to bind the text domain, so that the libraries can properly locate their message catalogs. diff --git a/Doc/library/macos.rst b/Doc/library/macos.rst index 75cbb19..119c2da 100644 --- a/Doc/library/macos.rst +++ b/Doc/library/macos.rst @@ -41,7 +41,7 @@ Note the capitalization of the module name; this is a historical artifact. This exception is raised on MacOS generated errors, either from functions in this module or from other mac-specific modules like the toolbox interfaces. The - arguments are the integer error code (the :cdata:`OSErr` value) and a textual + arguments are the integer error code (the :c:data:`OSErr` value) and a textual description of the error code. Symbolic names for all known error codes are defined in the standard module :mod:`macerrors`. diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index d51f340..7e6f44a 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -459,7 +459,7 @@ Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: @@ -573,7 +573,7 @@ Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking + :c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking the mailbox means locking the :file:`.mh_sequences` file and, only for the duration of any operations that affect them, locking individual message files. @@ -671,7 +671,7 @@ Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: @@ -722,7 +722,7 @@ Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :cfunc:`flock` and :cfunc:`lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst index a412609..59e9cf9 100644 --- a/Doc/library/msilib.rst +++ b/Doc/library/msilib.rst @@ -44,7 +44,7 @@ structures. .. function:: UuidCreate() Return the string representation of a new unique identifier. This wraps the - Windows API functions :cfunc:`UuidCreate` and :cfunc:`UuidToString`. + Windows API functions :c:func:`UuidCreate` and :c:func:`UuidToString`. .. function:: OpenDatabase(path, persist) @@ -60,7 +60,7 @@ structures. .. function:: CreateRecord(count) - Return a new record object by calling :cfunc:`MSICreateRecord`. *count* is the + Return a new record object by calling :c:func:`MSICreateRecord`. *count* is the number of fields of the record. @@ -135,20 +135,20 @@ Database Objects .. method:: Database.OpenView(sql) - Return a view object, by calling :cfunc:`MSIDatabaseOpenView`. *sql* is the SQL + Return a view object, by calling :c:func:`MSIDatabaseOpenView`. *sql* is the SQL statement to execute. .. method:: Database.Commit() Commit the changes pending in the current transaction, by calling - :cfunc:`MSIDatabaseCommit`. + :c:func:`MSIDatabaseCommit`. .. method:: Database.GetSummaryInformation(count) Return a new summary information object, by calling - :cfunc:`MsiGetSummaryInformation`. *count* is the maximum number of updated + :c:func:`MsiGetSummaryInformation`. *count* is the maximum number of updated values. @@ -166,7 +166,7 @@ View Objects .. method:: View.Execute(params) - Execute the SQL query of the view, through :cfunc:`MSIViewExecute`. If + Execute the SQL query of the view, through :c:func:`MSIViewExecute`. If *params* is not ``None``, it is a record describing actual values of the parameter tokens in the query. @@ -174,18 +174,18 @@ View Objects .. method:: View.GetColumnInfo(kind) Return a record describing the columns of the view, through calling - :cfunc:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or + :c:func:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or ``MSICOLINFO_TYPES``. .. method:: View.Fetch() - Return a result record of the query, through calling :cfunc:`MsiViewFetch`. + Return a result record of the query, through calling :c:func:`MsiViewFetch`. .. method:: View.Modify(kind, data) - Modify the view, by calling :cfunc:`MsiViewModify`. *kind* can be one of + Modify the view, by calling :c:func:`MsiViewModify`. *kind* can be one of ``MSIMODIFY_SEEK``, ``MSIMODIFY_REFRESH``, ``MSIMODIFY_INSERT``, ``MSIMODIFY_UPDATE``, ``MSIMODIFY_ASSIGN``, ``MSIMODIFY_REPLACE``, ``MSIMODIFY_MERGE``, ``MSIMODIFY_DELETE``, ``MSIMODIFY_INSERT_TEMPORARY``, @@ -197,7 +197,7 @@ View Objects .. method:: View.Close() - Close the view, through :cfunc:`MsiViewClose`. + Close the view, through :c:func:`MsiViewClose`. .. seealso:: @@ -216,7 +216,7 @@ Summary Information Objects .. method:: SummaryInformation.GetProperty(field) - Return a property of the summary, through :cfunc:`MsiSummaryInfoGetProperty`. + Return a property of the summary, through :c:func:`MsiSummaryInfoGetProperty`. *field* is the name of the property, and can be one of the constants ``PID_CODEPAGE``, ``PID_TITLE``, ``PID_SUBJECT``, ``PID_AUTHOR``, ``PID_KEYWORDS``, ``PID_COMMENTS``, ``PID_TEMPLATE``, ``PID_LASTAUTHOR``, @@ -228,12 +228,12 @@ Summary Information Objects .. method:: SummaryInformation.GetPropertyCount() Return the number of summary properties, through - :cfunc:`MsiSummaryInfoGetPropertyCount`. + :c:func:`MsiSummaryInfoGetPropertyCount`. .. method:: SummaryInformation.SetProperty(field, value) - Set a property through :cfunc:`MsiSummaryInfoSetProperty`. *field* can have the + Set a property through :c:func:`MsiSummaryInfoSetProperty`. *field* can have the same values as in :meth:`GetProperty`, *value* is the new value of the property. Possible value types are integer and string. @@ -241,7 +241,7 @@ Summary Information Objects .. method:: SummaryInformation.Persist() Write the modified properties to the summary information stream, using - :cfunc:`MsiSummaryInfoPersist`. + :c:func:`MsiSummaryInfoPersist`. .. seealso:: @@ -260,7 +260,7 @@ Record Objects .. method:: Record.GetFieldCount() Return the number of fields of the record, through - :cfunc:`MsiRecordGetFieldCount`. + :c:func:`MsiRecordGetFieldCount`. .. method:: Record.GetInteger(field) @@ -277,25 +277,25 @@ Record Objects .. method:: Record.SetString(field, value) - Set *field* to *value* through :cfunc:`MsiRecordSetString`. *field* must be an + Set *field* to *value* through :c:func:`MsiRecordSetString`. *field* must be an integer; *value* a string. .. method:: Record.SetStream(field, value) Set *field* to the contents of the file named *value*, through - :cfunc:`MsiRecordSetStream`. *field* must be an integer; *value* a string. + :c:func:`MsiRecordSetStream`. *field* must be an integer; *value* a string. .. method:: Record.SetInteger(field, value) - Set *field* to *value* through :cfunc:`MsiRecordSetInteger`. Both *field* and + Set *field* to *value* through :c:func:`MsiRecordSetInteger`. Both *field* and *value* must be an integer. .. method:: Record.ClearData() - Set all fields of the record to 0, through :cfunc:`MsiRecordClearData`. + Set all fields of the record to 0, through :c:func:`MsiRecordClearData`. .. seealso:: diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 4fc553f..d7fd3fb 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -152,5 +152,5 @@ Other Functions .. function:: heapmin() - Force the :cfunc:`malloc` heap to clean itself up and return unused blocks to + Force the :c:func:`malloc` heap to clean itself up and return unused blocks to the operating system. On failure, this raises :exc:`IOError`. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index c8c2ae8..c0f394b 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -408,7 +408,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the .. method:: terminate() Terminate the process. On Unix this is done using the ``SIGTERM`` signal; - on Windows :cfunc:`TerminateProcess` is used. Note that exit handlers and + on Windows :c:func:`TerminateProcess` is used. Note that exit handlers and finally clauses, etc., will not be executed. Note that descendant processes of the process will *not* be terminated -- diff --git a/Doc/library/new.rst b/Doc/library/new.rst index 670d3d7..8dd965e 100644 --- a/Doc/library/new.rst +++ b/Doc/library/new.rst @@ -48,7 +48,7 @@ The :mod:`new` module defines the following functions: .. function:: code(argcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab) - This function is an interface to the :cfunc:`PyCode_New` C function. + This function is an interface to the :c:func:`PyCode_New` C function. .. XXX This is still undocumented! diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 2c86076..8c63444 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -94,7 +94,7 @@ process and user. On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may cause memory leaks. Refer to the system documentation for - :cfunc:`putenv`. + :c:func:`putenv`. If :func:`putenv` is not provided, a modified copy of this mapping may be passed to the appropriate process-creation functions to cause child processes @@ -309,7 +309,7 @@ process and user. .. function:: setpgrp() - Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on + Call the system call :c:func:`setpgrp` or :c:func:`setpgrp(0, 0)` depending on which version is implemented (if any). See the Unix manual for the semantics. Availability: Unix. @@ -317,7 +317,7 @@ process and user. .. function:: setpgid(pid, pgrp) - Call the system call :cfunc:`setpgid` to set the process group id of the + Call the system call :c:func:`setpgid` to set the process group id of the process with id *pid* to the process group with id *pgrp*. See the Unix manual for the semantics. @@ -358,7 +358,7 @@ process and user. .. function:: getsid(pid) - Call the system call :cfunc:`getsid`. See the Unix manual for the semantics. + Call the system call :c:func:`getsid`. See the Unix manual for the semantics. Availability: Unix. @@ -367,7 +367,7 @@ process and user. .. function:: setsid() - Call the system call :cfunc:`setsid`. See the Unix manual for the semantics. + Call the system call :c:func:`setsid`. See the Unix manual for the semantics. Availability: Unix. @@ -385,7 +385,7 @@ process and user. .. function:: strerror(code) Return the error message corresponding to the error code in *code*. - On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown + On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown error number, :exc:`ValueError` is raised. Availability: Unix, Windows. @@ -454,7 +454,7 @@ These functions create new file objects. (See also :func:`open`.) .. versionchanged:: 2.5 On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is - set on the file descriptor (which the :cfunc:`fdopen` implementation already + set on the file descriptor (which the :c:func:`fdopen` implementation already does on most platforms). @@ -477,7 +477,7 @@ These functions create new file objects. (See also :func:`open`.) .. versionchanged:: 2.0 This function worked unreliably under Windows in earlier versions of Python. - This was due to the use of the :cfunc:`_popen` function from the libraries + This was due to the use of the :c:func:`_popen` function from the libraries provided with Windows. Newer versions of Python do not use the broken implementation from the Windows libraries. @@ -697,7 +697,7 @@ as internal buffering of data. .. function:: fsync(fd) Force write of file with filedescriptor *fd* to disk. On Unix, this calls the - native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function. + native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function. If you're starting with a Python file object *f*, first do ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated @@ -1142,7 +1142,7 @@ Files and Directories .. function:: lstat(path) - Perform the equivalent of an :cfunc:`lstat` system call on the given path. + Perform the equivalent of an :c:func:`lstat` system call on the given path. Similar to :func:`~os.stat`, but does not follow symbolic links. On platforms that do not support symbolic links, this is an alias for :func:`~os.stat`. @@ -1180,7 +1180,7 @@ Files and Directories .. function:: major(device) Extract the device major number from a raw device number (usually the - :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). + :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). .. versionadded:: 2.3 @@ -1188,7 +1188,7 @@ Files and Directories .. function:: minor(device) Extract the device minor number from a raw device number (usually the - :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). + :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). .. versionadded:: 2.3 @@ -1343,11 +1343,11 @@ Files and Directories .. function:: stat(path) - Perform the equivalent of a :cfunc:`stat` system call on the given path. + Perform the equivalent of a :c:func:`stat` system call on the given path. (This function follows symlinks; to stat a symlink use :func:`lstat`.) The return value is an object whose attributes correspond to the members - of the :ctype:`stat` structure, namely: + of the :c:type:`stat` structure, namely: * :attr:`st_mode` - protection bits, * :attr:`st_ino` - inode number, @@ -1404,7 +1404,7 @@ Files and Directories For backward compatibility, the return value of :func:`~os.stat` is also accessible as a tuple of at least 10 integers giving the most important (and portable) - members of the :ctype:`stat` structure, in the order :attr:`st_mode`, + members of the :c:type:`stat` structure, in the order :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by some implementations. @@ -1412,7 +1412,7 @@ Files and Directories .. index:: module: stat The standard module :mod:`stat` defines functions and constants that are useful - for extracting information from a :ctype:`stat` structure. (On Windows, some + for extracting information from a :c:type:`stat` structure. (On Windows, some items are filled with dummy values.) Example:: @@ -1461,9 +1461,9 @@ Files and Directories .. function:: statvfs(path) - Perform a :cfunc:`statvfs` system call on the given path. The return value is + Perform a :c:func:`statvfs` system call on the given path. The return value is an object whose attributes describe the filesystem on the given path, and - correspond to the members of the :ctype:`statvfs` structure, namely: + correspond to the members of the :c:type:`statvfs` structure, namely: :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`, :attr:`f_flag`, :attr:`f_namemax`. @@ -1473,7 +1473,7 @@ Files and Directories For backward compatibility, the return value is also accessible as a tuple whose values correspond to the attributes, in the order given above. The standard module :mod:`statvfs` defines constants that are useful for extracting - information from a :ctype:`statvfs` structure when accessing it as a sequence; + information from a :c:type:`statvfs` structure when accessing it as a sequence; this remains useful when writing code that needs to work with versions of Python that don't support accessing the fields as attributes. @@ -1664,7 +1664,7 @@ The various :func:`exec\*` functions take a list of arguments for the new program loaded into the process. In each case, the first of these arguments is passed to the new program as its own name rather than as an argument a user may have typed on a command line. For the C programmer, this is the ``argv[0]`` -passed to a program's :cfunc:`main`. For example, ``os.execv('/bin/echo', +passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem to be ignored. @@ -2117,7 +2117,7 @@ written in Python, such as a mail server's external command delivery program. There is no option to wait for the application to close, and no way to retrieve the application's exit status. The *path* parameter is relative to the current directory. If you want to use an absolute path, make sure the first character - is not a slash (``'/'``); the underlying Win32 :cfunc:`ShellExecute` function + is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that the path is properly encoded for Win32. @@ -2132,13 +2132,13 @@ written in Python, such as a mail server's external command delivery program. .. function:: system(command) Execute the command (a string) in a subshell. This is implemented by calling - the Standard C function :cfunc:`system`, and has the same limitations. + the Standard C function :c:func:`system`, and has the same limitations. Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the executed command. On Unix, the return value is the exit status of the process encoded in the format specified for :func:`wait`. Note that POSIX does not specify the meaning - of the return value of the C :cfunc:`system` function, so the return value of + of the return value of the C :c:func:`system` function, so the return value of the Python function is system-dependent. On Windows, the return value is that returned by the system shell after running diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst index 848eca5..00c113b 100644 --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -59,7 +59,7 @@ the standard audio interface for Linux and recent versions of FreeBSD. what went wrong. (If :mod:`ossaudiodev` receives an error from a system call such as - :cfunc:`open`, :cfunc:`write`, or :cfunc:`ioctl`, it raises :exc:`IOError`. + :c:func:`open`, :c:func:`write`, or :c:func:`ioctl`, it raises :exc:`IOError`. Errors detected directly by :mod:`ossaudiodev` result in :exc:`OSSAudioError`.) (For backwards compatibility, the exception class is also available as diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 0b78d49..49c617f 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -33,8 +33,8 @@ Cross Platform returned as strings. Values that cannot be determined are returned as given by the parameter presets. - If bits is given as ``''``, the :cfunc:`sizeof(pointer)` (or - :cfunc:`sizeof(long)` on Python version < 1.5.2) is used as indicator for the + If bits is given as ``''``, the :c:func:`sizeof(pointer)` (or + :c:func:`sizeof(long)` on Python version < 1.5.2) is used as indicator for the supported pointer size. The function relies on the system's :file:`file` command to do the actual work. diff --git a/Doc/library/popen2.rst b/Doc/library/popen2.rst index 4646dd9..628ec6e 100644 --- a/Doc/library/popen2.rst +++ b/Doc/library/popen2.rst @@ -104,7 +104,7 @@ methods: Waits for and returns the status code of the child process. The status code encodes both the return code of the process and information about whether it - exited using the :cfunc:`exit` system call or died due to a signal. Functions + exited using the :c:func:`exit` system call or died due to a signal. Functions to help interpret the status code are defined in the :mod:`os` module; see section :ref:`os-process` for the :func:`W\*` family of functions. diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst index 8c8ddde..8b5cac0 100644 --- a/Doc/library/posix.rst +++ b/Doc/library/posix.rst @@ -38,13 +38,13 @@ Large File Support Several operating systems (including AIX, HP-UX, Irix and Solaris) provide support for files that are larger than 2 GB from a C programming model where -:ctype:`int` and :ctype:`long` are 32-bit values. This is typically accomplished +:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished by defining the relevant size and offset types as 64-bit values. Such files are sometimes referred to as :dfn:`large files`. -Large file support is enabled in Python when the size of an :ctype:`off_t` is -larger than a :ctype:`long` and the :ctype:`long long` type is available and is -at least as large as an :ctype:`off_t`. Python longs are then used to represent +Large file support is enabled in Python when the size of an :c:type:`off_t` is +larger than a :c:type:`long` and the :c:type:`long long` type is available and is +at least as large as an :c:type:`off_t`. Python longs are then used to represent file sizes, offsets and other values that can exceed the range of a Python int. It may be necessary to configure and compile Python with certain compiler flags to enable this mode. For example, it is enabled by default with recent versions diff --git a/Doc/library/re.rst b/Doc/library/re.rst index fb497f2..df3f9e5 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -1053,14 +1053,14 @@ Simulating scanf() .. index:: single: scanf() -Python does not currently have an equivalent to :cfunc:`scanf`. Regular +Python does not currently have an equivalent to :c:func:`scanf`. Regular expressions are generally more powerful, though also more verbose, than -:cfunc:`scanf` format strings. The table below offers some more-or-less -equivalent mappings between :cfunc:`scanf` format tokens and regular +:c:func:`scanf` format strings. The table below offers some more-or-less +equivalent mappings between :c:func:`scanf` format tokens and regular expressions. +--------------------------------+---------------------------------------------+ -| :cfunc:`scanf` Token | Regular Expression | +| :c:func:`scanf` Token | Regular Expression | +================================+=============================================+ | ``%c`` | ``.`` | +--------------------------------+---------------------------------------------+ @@ -1085,7 +1085,7 @@ To extract the filename and numbers from a string like :: /usr/sbin/sendmail - 0 errors, 4 warnings -you would use a :cfunc:`scanf` format like :: +you would use a :c:func:`scanf` format like :: %s - %d errors, %d warnings diff --git a/Doc/library/restricted.rst b/Doc/library/restricted.rst index 28903b7..a40d1e9 100644 --- a/Doc/library/restricted.rst +++ b/Doc/library/restricted.rst @@ -31,7 +31,7 @@ restrictions can be imposed, depending on the application. For example, it might be deemed "safe" for untrusted code to read any file within a specified directory, but never to write a file. In this case, the supervisor may redefine the built-in :func:`open` function so that it raises an exception whenever the -*mode* parameter is ``'w'``. It might also perform a :cfunc:`chroot`\ -like +*mode* parameter is ``'w'``. It might also perform a :c:func:`chroot`\ -like operation on the *filename* parameter, such that root is always relative to some safe "sandbox" area of the filesystem. In this case, the untrusted code would still see an built-in :func:`open` function in its environment, with the same diff --git a/Doc/library/rfc822.rst b/Doc/library/rfc822.rst index 4c938f5..8e563dd 100644 --- a/Doc/library/rfc822.rst +++ b/Doc/library/rfc822.rst @@ -42,8 +42,8 @@ various end-user mail programs. from a buffered stream. The optional *seekable* argument is provided as a workaround for certain stdio - libraries in which :cfunc:`tell` discards buffered data before discovering that - the :cfunc:`lseek` system call doesn't work. For maximum portability, you + libraries in which :c:func:`tell` discards buffered data before discovering that + the :c:func:`lseek` system call doesn't work. For maximum portability, you should set the seekable argument to zero to prevent that initial :meth:`tell` when passing in an unseekable object such as a file object created from a socket object. diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 2e08b74..d131cb9 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -6,9 +6,9 @@ :synopsis: Wait for I/O completion on multiple streams. -This module provides access to the :cfunc:`select` and :cfunc:`poll` functions -available in most operating systems, :cfunc:`epoll` available on Linux 2.5+ and -:cfunc:`kqueue` available on most BSD. +This module provides access to the :c:func:`select` and :c:func:`poll` functions +available in most operating systems, :c:func:`epoll` available on Linux 2.5+ and +:c:func:`kqueue` available on most BSD. Note that on Windows, it only works for sockets; on other operating systems, it also works for other file types (in particular, on Unix, it works on pipes). It cannot be used on regular files to determine whether a file has grown since @@ -20,8 +20,8 @@ The module defines the following: .. exception:: error The exception raised when an error occurs. The accompanying value is a pair - containing the numeric error code from :cdata:`errno` and the corresponding - string, as would be printed by the C function :cfunc:`perror`. + containing the numeric error code from :c:data:`errno` and the corresponding + string, as would be printed by the C function :c:func:`perror`. .. function:: epoll([sizehint=-1]) @@ -60,7 +60,7 @@ The module defines the following: .. function:: select(rlist, wlist, xlist[, timeout]) - This is a straightforward interface to the Unix :cfunc:`select` system call. + This is a straightforward interface to the Unix :c:func:`select` system call. The first three arguments are sequences of 'waitable objects': either integers representing file descriptors or objects with a parameterless method named :meth:`fileno` returning such an integer: @@ -96,7 +96,7 @@ The module defines the following: .. index:: single: WinSock File objects on Windows are not acceptable, but sockets are. On Windows, - the underlying :cfunc:`select` function is provided by the WinSock + the underlying :c:func:`select` function is provided by the WinSock library, and does not handle file descriptors that don't originate from WinSock. @@ -195,13 +195,13 @@ Edge and Level Trigger Polling (epoll) Objects Polling Objects --------------- -The :cfunc:`poll` system call, supported on most Unix systems, provides better +The :c:func:`poll` system call, supported on most Unix systems, provides better scalability for network servers that service many, many clients at the same -time. :cfunc:`poll` scales better because the system call only requires listing -the file descriptors of interest, while :cfunc:`select` builds a bitmap, turns +time. :c:func:`poll` scales better because the system call only requires listing +the file descriptors of interest, while :c:func:`select` builds a bitmap, turns on bits for the fds of interest, and then afterward the whole bitmap has to be -linearly scanned again. :cfunc:`select` is O(highest file descriptor), while -:cfunc:`poll` is O(number of file descriptors). +linearly scanned again. :c:func:`select` is O(highest file descriptor), while +:c:func:`poll` is O(number of file descriptors). .. method:: poll.register(fd[, eventmask]) diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 9229117..29d56fc 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -69,7 +69,7 @@ The variables defined in the :mod:`signal` module are: All the signal numbers are defined symbolically. For example, the hangup signal is defined as :const:`signal.SIGHUP`; the variable names are identical to the names used in C programs, as found in ``<signal.h>``. The Unix man page for - ':cfunc:`signal`' lists the existing signals (on some systems this is + ':c:func:`signal`' lists the existing signals (on some systems this is :manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that not all systems define the same set of signal names; only those names defined by the system are defined by this module. @@ -216,7 +216,7 @@ The :mod:`signal` module defines the following functions: Note that installing a signal handler with :func:`signal` will reset the restart behaviour to interruptible by implicitly calling - :cfunc:`siginterrupt` with a true *flag* value for the given signal. + :c:func:`siginterrupt` with a true *flag* value for the given signal. .. versionadded:: 2.6 diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 6ace220..bcb317b 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -119,7 +119,7 @@ The module :mod:`socket` exports the following constants and functions: The accompanying value is a pair ``(h_errno, string)`` representing an error returned by a library call. *string* represents the description of *h_errno*, as - returned by the :cfunc:`hstrerror` C function. + returned by the :c:func:`hstrerror` C function. .. exception:: gaierror @@ -127,7 +127,7 @@ The module :mod:`socket` exports the following constants and functions: This exception is raised for address-related errors, for :func:`getaddrinfo` and :func:`getnameinfo`. The accompanying value is a pair ``(error, string)`` representing an error returned by a library call. *string* represents the - description of *error*, as returned by the :cfunc:`gai_strerror` C function. The + description of *error*, as returned by the :c:func:`gai_strerror` C function. The *error* value will match one of the :const:`EAI_\*` constants defined in this module. @@ -430,7 +430,7 @@ The module :mod:`socket` exports the following constants and functions: Convert an IPv4 address from dotted-quad string format (for example, '123.45.67.89') to 32-bit packed binary format, as a string four characters in length. This is useful when conversing with a program that uses the standard C - library and needs objects of type :ctype:`struct in_addr`, which is the C type + library and needs objects of type :c:type:`struct in_addr`, which is the C type for the 32-bit packed binary this function returns. :func:`inet_aton` also accepts strings with less than three dots; see the @@ -438,7 +438,7 @@ The module :mod:`socket` exports the following constants and functions: If the IPv4 address string passed to this function is invalid, :exc:`socket.error` will be raised. Note that exactly what is valid depends on - the underlying C implementation of :cfunc:`inet_aton`. + the underlying C implementation of :c:func:`inet_aton`. :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used instead for IPv4/v6 dual stack support. @@ -449,7 +449,7 @@ The module :mod:`socket` exports the following constants and functions: Convert a 32-bit packed IPv4 address (a string four characters in length) to its standard dotted-quad string representation (for example, '123.45.67.89'). This is useful when conversing with a program that uses the standard C library and - needs objects of type :ctype:`struct in_addr`, which is the C type for the + needs objects of type :c:type:`struct in_addr`, which is the C type for the 32-bit packed binary data this function takes as an argument. If the string passed to this function is not exactly 4 bytes in length, @@ -461,14 +461,14 @@ The module :mod:`socket` exports the following constants and functions: Convert an IP address from its family-specific string format to a packed, binary format. :func:`inet_pton` is useful when a library or network protocol calls for - an object of type :ctype:`struct in_addr` (similar to :func:`inet_aton`) or - :ctype:`struct in6_addr`. + an object of type :c:type:`struct in_addr` (similar to :func:`inet_aton`) or + :c:type:`struct in6_addr`. Supported values for *address_family* are currently :const:`AF_INET` and :const:`AF_INET6`. If the IP address string *ip_string* is invalid, :exc:`socket.error` will be raised. Note that exactly what is valid depends on both the value of *address_family* and the underlying implementation of - :cfunc:`inet_pton`. + :c:func:`inet_pton`. Availability: Unix (maybe not all platforms). @@ -480,8 +480,8 @@ The module :mod:`socket` exports the following constants and functions: Convert a packed IP address (a string of some number of characters) to its standard, family-specific string representation (for example, ``'7.10.0.5'`` or ``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol - returns an object of type :ctype:`struct in_addr` (similar to :func:`inet_ntoa`) - or :ctype:`struct in6_addr`. + returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) + or :c:type:`struct in6_addr`. Supported values for *address_family* are currently :const:`AF_INET` and :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the @@ -583,10 +583,10 @@ correspond to Unix system calls applicable to sockets. .. method:: socket.connect_ex(address) Like ``connect(address)``, but return an error indicator instead of raising an - exception for errors returned by the C-level :cfunc:`connect` call (other + exception for errors returned by the C-level :c:func:`connect` call (other problems, such as "host not found," can still raise exceptions). The error indicator is ``0`` if the operation succeeded, otherwise the value of the - :cdata:`errno` variable. This is useful to support, for example, asynchronous + :c:data:`errno` variable. This is useful to support, for example, asynchronous connects. .. note:: @@ -661,7 +661,7 @@ correspond to Unix system calls applicable to sockets. Return a :dfn:`file object` associated with the socket. (File objects are described in :ref:`bltin-file-objects`.) The file object - references a :cfunc:`dup`\ ped version of the socket file descriptor, so the + references a :c:func:`dup`\ ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently. The socket must be in blocking mode (it can not have a timeout). The optional *mode* and *bufsize* arguments are interpreted the same way as by the built-in diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst index 8fd90da..6b0e1b4 100644 --- a/Doc/library/stat.rst +++ b/Doc/library/stat.rst @@ -11,8 +11,8 @@ The :mod:`stat` module defines constants and functions for interpreting the results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they -exist). For complete details about the :cfunc:`stat`, :cfunc:`fstat` and -:cfunc:`lstat` calls, consult the documentation for your system. +exist). For complete details about the :c:func:`stat`, :c:func:`fstat` and +:c:func:`lstat` calls, consult the documentation for your system. The :mod:`stat` module defines the following functions to test for specific file types: @@ -70,7 +70,7 @@ mode: Normally, you would use the :func:`os.path.is\*` functions for testing the type of a file; the functions here are useful when you are doing multiple tests of -the same file and wish to avoid the overhead of the :cfunc:`stat` system call +the same file and wish to avoid the overhead of the :c:func:`stat` system call for each test. These are also useful when checking for information about a file that isn't handled by :mod:`os.path`, like the tests for block and character devices. diff --git a/Doc/library/statvfs.rst b/Doc/library/statvfs.rst index 25355bc..748b7f9 100644 --- a/Doc/library/statvfs.rst +++ b/Doc/library/statvfs.rst @@ -61,7 +61,7 @@ specified information. .. data:: F_FLAG - Flags. System dependent: see :cfunc:`statvfs` man page. + Flags. System dependent: see :c:func:`statvfs` man page. .. data:: F_NAMEMAX diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 629f08b..4929671 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -226,11 +226,11 @@ Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex` There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a subtype of plain integers. Plain integers (also just -called :dfn:`integers`) are implemented using :ctype:`long` in C, which gives +called :dfn:`integers`) are implemented using :c:type:`long` in C, which gives them at least 32 bits of precision (``sys.maxint`` is always set to the maximum plain integer value for the current platform, the minimum value is ``-sys.maxint - 1``). Long integers have unlimited precision. Floating point -numbers are usually implemented using :ctype:`double` in C; information about +numbers are usually implemented using :c:type:`double` in C; information about the precision and internal representation of floating point numbers for the machine on which your program is running is available in :data:`sys.float_info`. Complex numbers have a real and imaginary part, which @@ -1335,7 +1335,7 @@ operator (modulo). This is also known as the string *formatting* or *interpolation* operator. Given ``format % values`` (where *format* is a string or Unicode object), ``%`` conversion specifications in *format* are replaced with zero or more elements of *values*. The effect is similar to the using -:cfunc:`sprintf` in the C language. If *format* is a Unicode object, or if any +:c:func:`sprintf` in the C language. If *format* is a Unicode object, or if any of the objects being converted using the ``%s`` conversion are Unicode objects, the result will also be a Unicode object. @@ -2331,7 +2331,7 @@ Files have the following methods: .. method:: file.flush() - Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a + Flush the internal buffer, like ``stdio``'s :c:func:`fflush`. This may be a no-op on some file-like objects. .. note:: @@ -2392,14 +2392,14 @@ Files have the following methods: all data until EOF is reached. The bytes are returned as a string object. An empty string is returned when EOF is encountered immediately. (For certain files, like ttys, it makes sense to continue reading after an EOF is hit.) Note - that this method may call the underlying C function :cfunc:`fread` more than + that this method may call the underlying C function :c:func:`fread` more than once in an effort to acquire as close to *size* bytes as possible. Also note that when in non-blocking mode, less data than was requested may be returned, even if no *size* parameter was given. .. note:: This function is simply a wrapper for the underlying - :cfunc:`fread` C function, and will behave the same in corner cases, + :c:func:`fread` C function, and will behave the same in corner cases, such as whether the EOF value is cached. @@ -2414,7 +2414,7 @@ Files have the following methods: .. note:: - Unlike ``stdio``'s :cfunc:`fgets`, the returned string contains null characters + Unlike ``stdio``'s :c:func:`fgets`, the returned string contains null characters (``'\0'``) if they occurred in the input. @@ -2440,7 +2440,7 @@ Files have the following methods: .. method:: file.seek(offset[, whence]) - Set the file's current position, like ``stdio``'s :cfunc:`fseek`. The *whence* + Set the file's current position, like ``stdio``'s :c:func:`fseek`. The *whence* argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's @@ -2465,11 +2465,11 @@ Files have the following methods: .. method:: file.tell() - Return the file's current position, like ``stdio``'s :cfunc:`ftell`. + Return the file's current position, like ``stdio``'s :c:func:`ftell`. .. note:: - On Windows, :meth:`tell` can return illegal values (after an :cfunc:`fgets`) + On Windows, :meth:`tell` can return illegal values (after an :c:func:`fgets`) when reading files with Unix-style line-endings. Use binary mode (``'rb'``) to circumvent this problem. diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index 817c570..4331665 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -162,60 +162,60 @@ is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or ``'='``. When using native size, the size of the packed value is platform-dependent. -+--------+-------------------------+--------------------+----------------+------------+ -| Format | C Type | Python type | Standard size | Notes | -+========+=========================+====================+================+============+ -| ``x`` | pad byte | no value | | | -+--------+-------------------------+--------------------+----------------+------------+ -| ``c`` | :ctype:`char` | string of length 1 | 1 | | -+--------+-------------------------+--------------------+----------------+------------+ -| ``b`` | :ctype:`signed char` | integer | 1 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``B`` | :ctype:`unsigned char` | integer | 1 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``?`` | :ctype:`_Bool` | bool | 1 | \(1) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``h`` | :ctype:`short` | integer | 2 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``H`` | :ctype:`unsigned short` | integer | 2 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``i`` | :ctype:`int` | integer | 4 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``I`` | :ctype:`unsigned int` | integer | 4 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``l`` | :ctype:`long` | integer | 4 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``L`` | :ctype:`unsigned long` | integer | 4 | \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``q`` | :ctype:`long long` | integer | 8 | \(2), \(3) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``Q`` | :ctype:`unsigned long | integer | 8 | \(2), \(3) | -| | long` | | | | -+--------+-------------------------+--------------------+----------------+------------+ -| ``f`` | :ctype:`float` | float | 4 | \(4) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``d`` | :ctype:`double` | float | 8 | \(4) | -+--------+-------------------------+--------------------+----------------+------------+ -| ``s`` | :ctype:`char[]` | string | | | -+--------+-------------------------+--------------------+----------------+------------+ -| ``p`` | :ctype:`char[]` | string | | | -+--------+-------------------------+--------------------+----------------+------------+ -| ``P`` | :ctype:`void \*` | integer | | \(5), \(3) | -+--------+-------------------------+--------------------+----------------+------------+ ++--------+--------------------------+--------------------+----------------+------------+ +| Format | C Type | Python type | Standard size | Notes | ++========+==========================+====================+================+============+ +| ``x`` | pad byte | no value | | | ++--------+--------------------------+--------------------+----------------+------------+ +| ``c`` | :c:type:`char` | string of length 1 | 1 | | ++--------+--------------------------+--------------------+----------------+------------+ +| ``b`` | :c:type:`signed char` | integer | 1 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``B`` | :c:type:`unsigned char` | integer | 1 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``?`` | :c:type:`_Bool` | bool | 1 | \(1) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``h`` | :c:type:`short` | integer | 2 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``H`` | :c:type:`unsigned short` | integer | 2 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``i`` | :c:type:`int` | integer | 4 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``I`` | :c:type:`unsigned int` | integer | 4 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``l`` | :c:type:`long` | integer | 4 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``L`` | :c:type:`unsigned long` | integer | 4 | \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``q`` | :c:type:`long long` | integer | 8 | \(2), \(3) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``Q`` | :c:type:`unsigned long | integer | 8 | \(2), \(3) | +| | long` | | | | ++--------+--------------------------+--------------------+----------------+------------+ +| ``f`` | :c:type:`float` | float | 4 | \(4) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``d`` | :c:type:`double` | float | 8 | \(4) | ++--------+--------------------------+--------------------+----------------+------------+ +| ``s`` | :c:type:`char[]` | string | | | ++--------+--------------------------+--------------------+----------------+------------+ +| ``p`` | :c:type:`char[]` | string | | | ++--------+--------------------------+--------------------+----------------+------------+ +| ``P`` | :c:type:`void \*` | integer | | \(5), \(3) | ++--------+--------------------------+--------------------+----------------+------------+ Notes: (1) - The ``'?'`` conversion code corresponds to the :ctype:`_Bool` type defined by - C99. If this type is not available, it is simulated using a :ctype:`char`. In + The ``'?'`` conversion code corresponds to the :c:type:`_Bool` type defined by + C99. If this type is not available, it is simulated using a :c:type:`char`. In standard mode, it is always represented by one byte. .. versionadded:: 2.6 (2) The ``'q'`` and ``'Q'`` conversion codes are available in native mode only if - the platform C compiler supports C :ctype:`long long`, or, on Windows, - :ctype:`__int64`. They are always available in standard modes. + the platform C compiler supports C :c:type:`long long`, or, on Windows, + :c:type:`__int64`. They are always available in standard modes. .. versionadded:: 2.2 diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 274a6d9..2ba960a 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -472,7 +472,7 @@ Instances of the :class:`Popen` class have the following methods: .. method:: Popen.terminate() Stop the child. On Posix OSs the method sends SIGTERM to the - child. On Windows the Win32 API function :cfunc:`TerminateProcess` is called + child. On Windows the Win32 API function :c:func:`TerminateProcess` is called to stop the child. .. versionadded:: 2.6 diff --git a/Doc/library/sunaudio.rst b/Doc/library/sunaudio.rst index 9637b09..148eb5e 100644 --- a/Doc/library/sunaudio.rst +++ b/Doc/library/sunaudio.rst @@ -93,10 +93,10 @@ methods (except ``control`` objects which only provide :meth:`getinfo`, names and meanings of the attributes are described in ``<sun/audioio.h>`` and in the :manpage:`audio(7I)` manual page. Member names are slightly different from their C counterparts: a status object is only a single structure. Members of the - :cdata:`play` substructure have ``o_`` prepended to their name and members of - the :cdata:`record` structure have ``i_``. So, the C member - :cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`, - :cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as + :c:data:`play` substructure have ``o_`` prepended to their name and members of + the :c:data:`record` structure have ``i_``. So, the C member + :c:data:`play.sample_rate` is accessed as :attr:`o_sample_rate`, + :c:data:`record.gain` as :attr:`i_gain` and :c:data:`monitor_gain` plainly as :attr:`monitor_gain`. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index a8b62da..2ddf5a8 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -388,7 +388,7 @@ always available. .. function:: getdlopenflags() - Return the current value of the flags that are used for :cfunc:`dlopen` calls. + Return the current value of the flags that are used for :c:func:`dlopen` calls. The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules. Availability: Unix. @@ -533,8 +533,8 @@ always available. +---------------------------------------+---------------------------------+ - This function wraps the Win32 :cfunc:`GetVersionEx` function; see the - Microsoft documentation on :cfunc:`OSVERSIONINFOEX` for more information + This function wraps the Win32 :c:func:`GetVersionEx` function; see the + Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information about these fields. Availability: Windows. @@ -827,7 +827,7 @@ always available. .. function:: setdlopenflags(n) - Set the flags used by the interpreter for :cfunc:`dlopen` calls, such as when + Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when the interpreter loads extension modules. Among other things, this will enable a lazy resolving of symbols when importing a module, if called as ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 18a8bc6..56e9019 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -74,8 +74,8 @@ An explanation of some terminology and conventions is in order. * On the other hand, the precision of :func:`time` and :func:`sleep` is better than their Unix equivalents: times are expressed as floating point numbers, :func:`time` returns the most accurate time available (using Unix - :cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time - with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where + :c:func:`gettimeofday` where available), and :func:`sleep` will accept a time + with a nonzero fraction (Unix :c:func:`select` is used to implement this, where available). * The time value as returned by :func:`gmtime`, :func:`localtime`, and @@ -156,7 +156,7 @@ The module defines the following functions and data items: On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function - :cfunc:`QueryPerformanceCounter`. The resolution is typically better than one + :c:func:`QueryPerformanceCounter`. The resolution is typically better than one microsecond. diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index dbcf148..6f3c105 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -19,7 +19,7 @@ warrant raising an exception and terminating the program. For example, one might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the :func:`warn` function defined -in this module. (C programmers use :cfunc:`PyErr_WarnEx`; see +in this module. (C programmers use :c:func:`PyErr_WarnEx`; see :ref:`exceptionhandling` for details). Warning messages are normally written to ``sys.stderr``, but their disposition diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst index b4a3391..2325081 100644 --- a/Doc/library/winsound.rst +++ b/Doc/library/winsound.rst @@ -27,7 +27,7 @@ provided by Windows platforms. It includes functions and several constants. .. function:: PlaySound(sound, flags) - Call the underlying :cfunc:`PlaySound` function from the Platform API. The + Call the underlying :c:func:`PlaySound` function from the Platform API. The *sound* parameter may be a filename, audio data as a string, or ``None``. Its interpretation depends on the value of *flags*, which can be a bitwise ORed combination of the constants described below. If the *sound* parameter is @@ -37,7 +37,7 @@ provided by Windows platforms. It includes functions and several constants. .. function:: MessageBeep([type=MB_OK]) - Call the underlying :cfunc:`MessageBeep` function from the Platform API. This + Call the underlying :c:func:`MessageBeep` function from the Platform API. This plays a sound as specified in the registry. The *type* argument specifies which sound to play; possible values are ``-1``, ``MB_ICONASTERISK``, ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst index 0118704..92a3197 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -132,7 +132,7 @@ The available exception and functions in this module are: *bufsize* is the initial size of the buffer used to hold decompressed data. If more space is required, the buffer size will be increased as needed, so you don't have to get this value exactly right; tuning it will only save a few calls - to :cfunc:`malloc`. The default size is 16384. + to :c:func:`malloc`. The default size is 16384. .. function:: decompressobj([wbits]) |