Utilidades del sistema operativo
********************************

PyObject* PyOS_FSPath(PyObject *path)
    *Return value: New reference.*

   Retorna la representación del sistema de archivos para *path*. Si
   el objeto es "str" o "bytes", entonces su conteo de referencias se
   incrementa. Si el objeto implementa la interfaz "os.PathLike",
   entonces "__fspath__()" se retorna siempre que sea un objeto "str"
   o "bytes". De lo contrario "TypeError" se lanza y se retorna
   "NULL".

   Nuevo en la versión 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

   Retorna verdadero (distinto de cero) si el archivo de E/S (*I/O*)
   estándar *fp* con nombre *filename* se considera interactivo. Este
   es el caso de los archivos para los que "isatty(fileno(fp))" es
   verdadero. Si el indicador global "Py_InteractiveFlag" es
   verdadero, esta función también retorna verdadero si el puntero
   *filename* es "NULL" o si el nombre es igual a una de las cadenas
   de caracteres "'<stdin>'" o "'???'".

void PyOS_BeforeFork()

   Función para preparar algún estado interno antes de una bifurcación
   de proceso (*process fork*). Esto debería llamarse antes de llamar
   a "fork()" o cualquier función similar que clone el proceso actual.
   Solo disponible en sistemas donde "fork()" está definido.

   Advertencia:

     La llamada C "fork()" solo debe hacerse desde hilo "principal"
     (del intérprete "principal"). Lo mismo es cierto para
     "PyOS_BeforeFork()".

   Nuevo en la versión 3.7.

void PyOS_AfterFork_Parent()

   Función para actualizar algún estado interno después de una
   bifurcación de proceso. Se debe invocar desde el proceso principal
   después de llamar a "fork()" o cualquier función similar que clone
   el proceso actual, independientemente de si la clonación del
   proceso fue exitosa. Solo disponible en sistemas donde "fork()"
   está definido.

   Advertencia:

     La llamada C "fork()" solo debe hacerse desde hilo "principal"
     (del intérprete "principal"). Lo mismo es cierto para
     "PyOS_AfterFork_Parent()".

   Nuevo en la versión 3.7.

void PyOS_AfterFork_Child()

   Función para actualizar el estado del intérprete interno después de
   una bifurcación de proceso (*process fork*). Debe llamarse desde el
   proceso secundario después de llamar a "fork()", o cualquier
   función similar que clone el proceso actual, si existe alguna
   posibilidad de que el proceso vuelva a llamar al intérprete de
   Python. Solo disponible en sistemas donde "fork()" está definido.

   Advertencia:

     La llamada C "fork()" solo debe hacerse desde hilo "principal"
     (del intérprete "principal"). Lo mismo es cierto para
     "PyOS_AfterFork_Child()".

   Nuevo en la versión 3.7.

   Ver también:

     "os.register_at_fork()" permite registrar funciones
     personalizadas de Python a las que puede llamar
     "PyOS_BeforeFork()", "PyOS_AfterFork_Parent()" y
     "PyOS_AfterFork_Child()".

void PyOS_AfterFork()

   Función para actualizar algún estado interno después de una
   bifurcación de proceso (*process fork*); Esto debería llamarse en
   el nuevo proceso si el intérprete de Python continuará siendo
   utilizado. Si se carga un nuevo ejecutable en el nuevo proceso, no
   es necesario llamar a esta función.

   Obsoleto desde la versión 3.7: Esta función es reemplazada por
   "PyOS_AfterFork_Child()".

int PyOS_CheckStack()

   Retorna verdadero cuando el intérprete se queda sin espacio de pila
   (*stack space*). Esta es una verificación confiable, pero solo está
   disponible cuando "USE_STACKCHECK" está definido (actualmente en
   Windows usando el compilador *Microsoft Visual C++*).
   "USE_STACKCHECK" se definirá automáticamente; nunca debe cambiar la
   definición en su propio código.

PyOS_sighandler_t PyOS_getsig(int i)

   Retorna el controlador de señal actual para la señal *i*. Esta es
   una pequeña envoltura alrededor de "sigaction()" o "signal()". ¡No
   llame a esas funciones directamente! "PyOS_sighandler_t" es un
   alias *typedef* para "void (*)(int)".

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

   Configura el controlador de señal para la señal *i* como *h*;
   retorna el antiguo manejador de señal. Esta es una pequeña
   envoltura alrededor de "sigaction()" o "signal()". ¡No llame a esas
   funciones directamente! "PyOS_sighandler_t" es un alias *typedef*
   para "void (*)(int)".

wchar_t* Py_DecodeLocale(const char* arg, size_t *size)

   Decodifica una cadena de bytes de la codificación de configuración
   regional con controlador de error de subrogateescape: los bytes no
   codificables se decodifican como caracteres en el rango
   U+DC80..U+DCFF. Si una secuencia de bytes se puede decodificar como
   un carácter sustituto, escape los bytes usando el controlador de
   error de escape sustituto en lugar de decodificarlos.

   Codificación, de máxima prioridad a menor prioridad:

   * `` UTF-8`` en macOS, Android y VxWorks;

   * "UTF-8" en Windows si "Py_LegacyWindowsFSEncodingFlag" es cero;

   * `` UTF-8`` si el modo Python UTF-8 está habilitado;

   * "ASCII" si la configuración regional "LC_CTYPE" es ""C"",
     "nl_langinfo (CODESET)" retorna la codificación "ASCII" (o un
     alias) y las funciones "mbstowcs()" y "wcstombs()" utilizan la
     codificación "ISO-8859-1".

   * la codificación de la configuración regional actual.

   Retorna un puntero a una cadena de caracteres anchos recientemente
   asignada, use "PyMem_RawFree()" para liberar la memoria. Si el
   tamaño no es "NULL", escribe el número de caracteres anchos
   excluyendo el carácter nulo en "*size"

   Retorna "NULL" en caso de error de decodificación o error de
   asignación de memoria. Si *size* no es "NULL", "*size" se establece
   en "(size_t) -1" en caso de error de memoria o en "(size_t) -2" en
   caso de error de decodificación.

   Los errores de decodificación nunca deberían ocurrir, a menos que
   haya un error en la biblioteca C.

   Utilice la función "Py_EncodeLocale()" para codificar la cadena de
   caracteres en una cadena de bytes.

   Ver también:

     Las funciones "PyUnicode_DecodeFSDefaultAndSize()" y
     "PyUnicode_DecodeLocaleAndSize()".

   Nuevo en la versión 3.5.

   Distinto en la versión 3.7: La función ahora usa la codificación
   UTF-8 en el modo UTF-8.

   Distinto en la versión 3.8: La función ahora usa la codificación
   UTF-8 en Windows si "Py_LegacyWindowsFSEncodingFlag" es cero;

char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

   Codifica una cadena de caracteres anchos en la codificación de
   configuración regional con controlador de error de surrogateescape:
   los caracteres sustitutos en el rango U+DC80..U+DCFF se convierten
   en bytes 0x80..0xFF.

   Codificación, de máxima prioridad a menor prioridad:

   * `` UTF-8`` en macOS, Android y VxWorks;

   * "UTF-8" en Windows si "Py_LegacyWindowsFSEncodingFlag" es cero;

   * `` UTF-8`` si el modo Python UTF-8 está habilitado;

   * "ASCII" si la configuración regional "LC_CTYPE" es ""C"",
     "nl_langinfo (CODESET)" retorna la codificación "ASCII" (o un
     alias) y las funciones "mbstowcs()" y "wcstombs()" utilizan la
     codificación "ISO-8859-1".

   * la codificación de la configuración regional actual.

   La función utiliza la codificación UTF-8 en el modo Python UTF-8.

   Return a pointer to a newly allocated byte string, use
   "PyMem_Free()" to free the memory. Return "NULL" on encoding error
   or memory allocation error.

   Si *error_pos* no es "NULL", "*error_pos" se establece en
   "(size_t)-1" en caso de éxito, o se establece en el índice del
   carácter no válido en el error de codificación.

   Use la función "Py_DecodeLocale()" para decodificar la cadena de
   bytes en una cadena de caracteres anchos.

   Ver también:

     Las funciones "PyUnicode_EncodeFSDefault()" y
     "PyUnicode_EncodeLocale()".

   Nuevo en la versión 3.5.

   Distinto en la versión 3.7: La función ahora usa la codificación
   UTF-8 en el modo UTF-8.

   Distinto en la versión 3.8: The function now uses the UTF-8
   encoding on Windows if "Py_LegacyWindowsFSEncodingFlag" is zero.


Funciones del Sistema
*********************

Estas son funciones de utilidad que hacen que la funcionalidad del
módulo "sys" sea accesible para el código C. Todos funcionan con el
diccionario del módulo "sys" del subproceso actual del intérprete, que
está contenido en la estructura interna del estado del subproceso.

PyObject *PySys_GetObject(const char *name)
    *Return value: Borrowed reference.*

   Retorna el objeto *name* del módulo "sys" o "NULL" si no existe,
   sin establecer una excepción.

int PySys_SetObject(const char *name, PyObject *v)

   Establece *name* en el módulo "sys" en *v* a menos que *v* sea
   "NULL", en cuyo caso *name* se elimina del módulo *sys*. Retorna
   "0" en caso de éxito, "-1" en caso de error.

void PySys_ResetWarnOptions()

   Restablece "sys.warnoptions" a una lista vacía. Esta función puede
   llamarse antes de "Py_Initialize()".

void PySys_AddWarnOption(const wchar_t *s)

   Agrega *s* a "sys.warnoptions". Esta función debe llamarse antes de
   "Py_Initialize()" para afectar la lista de filtros de advertencias.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

   Agrega *unicode* a "sys.warnoptions".

   Nota: esta función no se puede utilizar actualmente desde fuera de
   la implementación de CPython, ya que debe llamarse antes de la
   importación implícita de "warnings" en "Py_Initialize()" para que
   sea efectiva, pero no se puede llamar hasta que se haya
   inicializado suficiente tiempo de ejecución para permitir la
   creación de objetos Unicode.

void PySys_SetPath(const wchar_t *path)

   Establece "sys.path" en un objeto lista de rutas que se encuentra
   en *path*, que debería ser una lista de rutas separadas con el
   delimitador de ruta de búsqueda de la plataforma (":" en Unix, ";"
   en Windows )

void PySys_WriteStdout(const char *format, ...)

   Escribe la cadena de caracteres de salida descrita por *format* en
   "sys.stdout". No se lanzan excepciones, incluso si se produce el
   truncamiento (ver más abajo).

   *format* debe limitar el tamaño total de la cadena de caracteres de
   salida formateada a 1000 bytes o menos; después de 1000 bytes, la
   cadena de caracteres de salida se trunca. En particular, esto
   significa que no deben existir formatos "%s" sin restricciones;
   estos deben limitarse usando "%.<N>s" donde <N> es un número
   decimal calculado de modo que <N> más el tamaño máximo de otro
   texto formateado no exceda los 1000 bytes. También tenga cuidado
   con "%f", que puede imprimir cientos de dígitos para números muy
   grandes.

   Si ocurre un problema, o "sys.stdout" no está configurado, el
   mensaje formateado se escribe en el real (nivel C) *stdout*.

void PySys_WriteStderr(const char *format, ...)

   Como "PySys_WriteStdout()", pero escribe a "sys.stderr" o *stderr*
   en su lugar.

void PySys_FormatStdout(const char *format, ...)

   Función similar a "PySys_WriteStdout()" pero formatea el mensaje
   usando "PyUnicode_FromFormatV()" y no trunca el mensaje a una
   longitud arbitraria.

   Nuevo en la versión 3.2.

void PySys_FormatStderr(const char *format, ...)

   Como "PySys_FormatStdout()", pero escribe a "sys.stderr" o *stderr*
   en su lugar.

   Nuevo en la versión 3.2.

void PySys_AddXOption(const wchar_t *s)

   Analiza (*parse*) *s* como un conjunto de opciones "-X" y los
   agrega a la asignación de opciones actual tal como lo retorna
   "PySys_GetXOptions()". Esta función puede llamarse antes de
   "Py_Initialize()".

   Nuevo en la versión 3.2.

PyObject *PySys_GetXOptions()
    *Return value: Borrowed reference.*

   Retorna el diccionario actual de opciones "-X", de manera similar a
   "sys._xoptions". En caso de error, se retorna "NULL" y se establece
   una excepción.

   Nuevo en la versión 3.2.

int PySys_Audit(const char *event, const char *format, ...)

   Lanza un evento de auditoría con cualquier gancho activo. Retorna
   cero para el éxito y no cero con una excepción establecida en caso
   de error.

   Si se han agregado ganchos, *format* y otros argumentos se
   utilizarán para construir una tupla para pasar. Además de "N",
   están disponibles los mismos caracteres de formato que los
   utilizados en "Py_BuildValue()". Si el valor generado no es una
   tupla, se agregará a una tupla de un solo elemento. (La opción de
   formato "N" consume una referencia, pero dado que no hay forma de
   saber si se consumirán argumentos para esta función, su uso puede
   causar fugas de referencia).

   Note that "#" format characters should always be treated as
   "Py_ssize_t", regardless of whether "PY_SSIZE_T_CLEAN" was defined.

   "sys.audit()" realiza la misma función del código Python.

   Nuevo en la versión 3.8.

   Distinto en la versión 3.8.2: Require "Py_ssize_t" for "#" format
   characters. Previously, an unavoidable deprecation warning was
   raised.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

   Append the callable *hook* to the list of active auditing hooks.
   Return zero on success and non-zero on failure. If the runtime has
   been initialized, also set an error on failure. Hooks added through
   this API are called for all interpreters created by the runtime.

   El puntero *userData* se pasa a la función gancho. Dado que las
   funciones de enlace pueden llamarse desde diferentes tiempos de
   ejecución, este puntero no debe referirse directamente al estado de
   Python.

   Es seguro llamar a esta función antes de "Py_Initialize()". Cuando
   se llama después de la inicialización del tiempo de ejecución, se
   notifican los enlaces de auditoría existentes y pueden anular
   silenciosamente la operación al generar un error subclasificado de
   "Excepción" (otros errores no se silenciarán).

   La función gancho (*hook*) es de tipo "int (*)(const char *event,
   PyObject *args, void *userData)", donde *args* está garantizado
   como un "PyTupleObject". La función gancho siempre se llama con el
   GIL en poder del intérprete de Python que lanzó el evento.

   Ver **PEP 578** para una descripción detallada de la auditoría. Las
   funciones en el tiempo de ejecución y la biblioteca estándar que
   generan eventos se enumeran en table de eventos de auditoria. Los
   detalles se encuentran en la documentación de cada función.

   Lanza un evento de auditoria "sys.addaudithook" sin argumentos.

   Nuevo en la versión 3.8.


Control de procesos
*******************

void Py_FatalError(const char *message)

   Imprime un mensaje de error fatal y elimina el proceso. No se
   realiza limpieza. Esta función solo debe invocarse cuando se
   detecta una condición que haría peligroso continuar usando el
   intérprete de Python; por ejemplo, cuando la administración del
   objeto parece estar dañada. En Unix, se llama a la función de
   biblioteca C estándar "abort()" que intentará producir un archivo
   "core".

   La función "Py_FatalError()" se reemplaza con una macro que
   registra automáticamente el nombre de la función actual, a menos
   que se defina la macro "Py_LIMITED_API".

   Distinto en la versión 3.9: Registra el nombre de la función
   automáticamente.

void Py_Exit(int status)

   Sale del proceso actual. Esto llama "Py_FinalizeEx()" y luego llama
   a la función estándar de la biblioteca C "exit(status)". Si
   "Py_FinalizeEx()" indica un error, el estado de salida se establece
   en 120.

   Distinto en la versión 3.6: Los errores de finalización ya no se
   ignoran.

int Py_AtExit(void (*func)())

   Registra una función de limpieza a la que llamará
   "Py_FinalizeEx()". Se llamará a la función de limpieza sin
   argumentos y no debería retornar ningún valor. Como máximo se
   pueden registrar 32 funciones de limpieza. Cuando el registro es
   exitoso, "Py_AtExit()" retorna "0"; en caso de error, retorna "-1".
   La última función de limpieza registrada se llama primero. Cada
   función de limpieza se llamará como máximo una vez. Dado que la
   finalización interna de Python se habrá completado antes de la
   función de limpieza, *func* no debería llamar a las API de Python.
