diff options
Diffstat (limited to 'devdocs/python~3.12/c-api%2Ffile.html')
| -rw-r--r-- | devdocs/python~3.12/c-api%2Ffile.html | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/devdocs/python~3.12/c-api%2Ffile.html b/devdocs/python~3.12/c-api%2Ffile.html new file mode 100644 index 00000000..acdf1a23 --- /dev/null +++ b/devdocs/python~3.12/c-api%2Ffile.html @@ -0,0 +1,24 @@ + <span id="fileobjects"></span><h1>File Objects</h1> <p id="index-0">These APIs are a minimal emulation of the Python 2 C API for built-in file objects, which used to rely on the buffered I/O (<span class="c-expr sig sig-inline c"><span class="n">FILE</span><span class="p">*</span></span>) support from the C standard library. In Python 3, files and streams use the new <a class="reference internal" href="../library/io#module-io" title="io: Core tools for working with streams."><code>io</code></a> module, which defines several layers over the low-level unbuffered I/O of the operating system. The functions described below are convenience C wrappers over these new APIs, and meant mostly for internal error reporting in the interpreter; third-party code is advised to access the <a class="reference internal" href="../library/io#module-io" title="io: Core tools for working with streams."><code>io</code></a> APIs instead.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFile_FromFd"> +<code>PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Python file object from the file descriptor of an already opened file <em>fd</em>. The arguments <em>name</em>, <em>encoding</em>, <em>errors</em> and <em>newline</em> can be <code>NULL</code> to use the defaults; <em>buffering</em> can be <em>-1</em> to use the default. <em>name</em> is ignored and kept for backward compatibility. Return <code>NULL</code> on failure. For a more comprehensive description of the arguments, please refer to the <a class="reference internal" href="../library/io#io.open" title="io.open"><code>io.open()</code></a> function documentation.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>Since Python streams have their own buffering layer, mixing them with OS-level file descriptors can produce various issues (such as unexpected ordering of data).</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Ignore <em>name</em> attribute.</p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_AsFileDescriptor"> +<code>int PyObject_AsFileDescriptor(PyObject *p)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the file descriptor associated with <em>p</em> as an <span class="c-expr sig sig-inline c"><span class="kt">int</span></span>. If the object is an integer, its value is returned. If not, the object’s <a class="reference internal" href="../library/io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method is called if it exists; the method must return an integer, which is returned as the file descriptor value. Sets an exception and returns <code>-1</code> on failure.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFile_GetLine"> +<code>PyObject *PyFile_GetLine(PyObject *p, int n)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">Equivalent to <code>p.readline([n])</code>, this function reads one line from the object <em>p</em>. <em>p</em> may be a file object or any object with a <a class="reference internal" href="../library/io#io.IOBase.readline" title="io.IOBase.readline"><code>readline()</code></a> method. If <em>n</em> is <code>0</code>, exactly one line is read, regardless of the length of the line. If <em>n</em> is greater than <code>0</code>, no more than <em>n</em> bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If <em>n</em> is less than <code>0</code>, however, one line is read regardless of length, but <a class="reference internal" href="../library/exceptions#EOFError" title="EOFError"><code>EOFError</code></a> is raised if the end of the file is reached immediately.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFile_SetOpenCodeHook"> +<code>int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)</code> </dt> <dd> +<p>Overrides the normal behavior of <a class="reference internal" href="../library/io#io.open_code" title="io.open_code"><code>io.open_code()</code></a> to pass its parameter through the provided handler.</p> <p>The handler is a function of type <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="w"> </span><span class="p">*</span><span class="p">(</span><span class="p">*</span><span class="p">)</span><span class="p">(</span><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="w"> </span><span class="p">*</span><span class="n">path</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="p">*</span><span class="n">userData</span><span class="p">)</span></span>, where <em>path</em> is guaranteed to be <a class="reference internal" href="unicode#c.PyUnicodeObject" title="PyUnicodeObject"><code>PyUnicodeObject</code></a>.</p> <p>The <em>userData</em> pointer is passed into the hook function. Since hook functions may be called from different runtimes, this pointer should not refer directly to Python state.</p> <p>As this hook is intentionally used during import, avoid importing new modules during its execution unless they are known to be frozen or available in <code>sys.modules</code>.</p> <p>Once a hook has been set, it cannot be removed or replaced, and later calls to <a class="reference internal" href="#c.PyFile_SetOpenCodeHook" title="PyFile_SetOpenCodeHook"><code>PyFile_SetOpenCodeHook()</code></a> will fail. On failure, the function returns -1 and sets an exception if the interpreter has been initialized.</p> <p>This function is safe to call before <a class="reference internal" href="init#c.Py_Initialize" title="Py_Initialize"><code>Py_Initialize()</code></a>.</p> <p class="audit-hook">Raises an <a class="reference internal" href="../library/sys#auditing"><span class="std std-ref">auditing event</span></a> <code>setopencodehook</code> with no arguments.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFile_WriteObject"> +<code>int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-2">Write object <em>obj</em> to file object <em>p</em>. The only supported flag for <em>flags</em> is <code>Py_PRINT_RAW</code>; if given, the <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str()</code></a> of the object is written instead of the <a class="reference internal" href="../library/functions#repr" title="repr"><code>repr()</code></a>. Return <code>0</code> on success or <code>-1</code> on failure; the appropriate exception will be set.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyFile_WriteString"> +<code>int PyFile_WriteString(const char *s, PyObject *p)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Write string <em>s</em> to file object <em>p</em>. Return <code>0</code> on success or <code>-1</code> on failure; the appropriate exception will be set.</p> </dd> +</dl> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/c-api/file.html" class="_attribution-link">https://docs.python.org/3.12/c-api/file.html</a> + </p> +</div> |