1 .. highlight:: c
2 
3 Old Buffer Protocol
4 -------------------
5 
6 .. deprecated:: 3.0
7 
8 These functions were part of the "old buffer protocol" API in Python 2.
9 In Python 3, this protocol doesn't exist anymore but the functions are still
10 exposed to ease porting 2.x code.  They act as a compatibility wrapper
11 around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
12 you control over the lifetime of the resources acquired when a buffer is
13 exported.
14 
15 Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
16 (or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
17 :c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
18 an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
19 
20 
21 .. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
22 
23    Returns a pointer to a read-only memory location usable as character-based
24    input.  The *obj* argument must support the single-segment character buffer
25    interface.  On success, returns ``0``, sets *buffer* to the memory location
26    and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
27    :exc:`TypeError` on error.
28 
29 
30 .. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
31 
32    Returns a pointer to a read-only memory location containing arbitrary data.
33    The *obj* argument must support the single-segment readable buffer
34    interface.  On success, returns ``0``, sets *buffer* to the memory location
35    and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
36    :exc:`TypeError` on error.
37 
38 
39 .. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
40 
41    Returns ``1`` if *o* supports the single-segment readable buffer interface.
42    Otherwise returns ``0``.  This function always succeeds.
43 
44    Note that this function tries to get and release a buffer, and exceptions
45    which occur while calling corresponding functions will get suppressed.
46    To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
47 
48 
49 .. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
50 
51    Returns a pointer to a writable memory location.  The *obj* argument must
52    support the single-segment, character buffer interface.  On success,
53    returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
54    buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
55 
56