Doc/c-api/objbuffer.rst

   1 .. highlightlang:: c
   2
   3 .. _abstract-buffer:
   4
   5
   6 Old Buffer Protocol
   7 ===================
   8
   9 This section describes the legacy buffer protocol, which has been introduced
  10 in Python 1.6. It is still supported but deprecated in the Python 2.x series.
  11 Python 3.0 introduces a new buffer protocol which fixes weaknesses and
  12 shortcomings of the protocol, and has been backported to Python 2.6.  See
  13 :ref:`bufferobjects` for more information.
  14
  15
  16 .. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
  17
  18    Returns a pointer to a read-only memory location usable as character-based
  19    input.  The *obj* argument must support the single-segment character buffer
  20    interface.  On success, returns ``0``, sets *buffer* to the memory location
  21    and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
  22    :exc:`TypeError` on error.
  23
  24    .. versionadded:: 1.6
  25
  26    .. versionchanged:: 2.5
  27       This function used an :ctype:`int *` type for *buffer_len*. This might
  28       require changes in your code for properly supporting 64-bit systems.
  29
  30
  31 .. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
  32
  33    Returns a pointer to a read-only memory location containing arbitrary data.
  34    The *obj* argument must support the single-segment readable buffer
  35    interface.  On success, returns ``0``, sets *buffer* to the memory location
  36    and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
  37    :exc:`TypeError` on error.
  38
  39    .. versionadded:: 1.6
  40
  41    .. versionchanged:: 2.5
  42       This function used an :ctype:`int *` type for *buffer_len*. This might
  43       require changes in your code for properly supporting 64-bit systems.
  44
  45
  46 .. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
  47
  48    Returns ``1`` if *o* supports the single-segment readable buffer interface.
  49    Otherwise returns ``0``.
  50
  51    .. versionadded:: 2.2
  52
  53
  54 .. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
  55
  56    Returns a pointer to a writeable memory location.  The *obj* argument must
  57    support the single-segment, character buffer interface.  On success,
  58    returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
  59    buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
  60
  61    .. versionadded:: 1.6
  62
  63    .. versionchanged:: 2.5
  64       This function used an :ctype:`int *` type for *buffer_len*. This might
  65       require changes in your code for properly supporting 64-bit systems.
  66