.. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/deprecated.rst ` :Translator: Sergio Gonzalez .. _sp_deprecated: ============================================================================ Interfaces obsoletos, Características del lenguaje, Atributos y Convenciones ============================================================================ En un mundo perfecto, sería posible convertir todas las instancias de alguna API obsoleta en una nueva API y quitar la API anterior en un único ciclo de desarrollo. Desafortunadamente, debido al tamaño del kernel, la jerarquía de mantenimiento, y el tiempo, no siempre es posible hacer estos cambios de una única vez. Esto significa que las nuevas instancias han de ir creándose en el kernel, mientras que las antiguas se quitan, haciendo que la cantidad de trabajo para limpiar las APIs crezca. Para informar a los desarrolladores sobre qué ha sido declarado obsoleto y por qué, ha sido creada esta lista como un lugar donde indicar cuando los usos obsoletos son propuestos para incluir en el kernel. __deprecated ------------ Mientras que este atributo señala visualmente que un interface ha sido declarado obsoleto, este `no produce más avisos durante las compilaciones `_ porque uno de los objetivos del kernel es que compile sin avisos, y nadie ha hecho nada para quitar estos interfaces obsoletos. Mientras que usar `__deprecated` es sencillo para anotar una API obsoleta en un archivo de cabecera, no es la solución completa. Dichos interfaces deben o bien ser quitados por completo, o añadidos a este archivo para desanimar a otros a usarla en el futuro. BUG() y BUG_ON() ---------------- Use WARN() y WARN_ON() en su lugar, y gestione las condiciones de error "imposibles" tan elegantemente como se pueda. Mientras que la familia de funciones BUG() fueron originalmente diseñadas para actuar como una "situación imposible", confirmar y disponer de un hilo del kernel de forma "segura", estas funciones han resultado ser demasiado arriesgadas. (e.g. "¿en qué orden se necesitan liberar los locks? ¿Se han restaurado sus estados?). La popular función BUG() desestabilizará el sistema o lo romperá totalmente, lo cual hace imposible depurarlo o incluso generar reportes de crash. Linus tiene una `opinión muy fuerte `_ y sentimientos `sobre esto `_. Nótese que la familia de funciones WARN() únicamente debería ser usada en situaciones que se "esperan no sean alcanzables". Si se quiere avisar sobre situaciones "alcanzables pero no deseadas", úsese la familia de funciones pr_warn(). Los responsables del sistema pueden haber definido *panic_on_warn* sysctl para asegurarse que sus sistemas no continúan ejecutándose en presencia del condiciones "no alcanzables". (Por ejemplo, véase commits como `este `_.) Operaciones aritméticas en los argumentos de reserva de memoria --------------------------------------------------------------- Los cálculos dinámicos de tamaño (especialmente multiplicaciones) no deberían realizarse en los argumentos de reserva de memoria (o similares) debido al riesgo de desbordamiento. Esto puede llevar a valores rotando y que se realicen reservas de memoria menores que las que se esperaban. El uso de esas reservas puede llevar a desbordamientos en el 'heap' de memoria y otros funcionamientos incorrectos. (Una excepción a esto son los valores literales donde el compilador si puede avisar si estos puede desbordarse. De todos modos, el método recomendado en estos caso es reescribir el código como se sugiere a continuación para evitar las operaciones aritméticas en la reserva de memoria.) Por ejemplo, no utilice `count * size`` como argumento, como en:: foo = kmalloc(count * size, GFP_KERNEL); En vez de eso, utilice la reserva con dos argumentos:: foo = kmalloc_array(count, size, GFP_KERNEL); Específicamente, kmalloc() puede ser sustituido con kmalloc_array(), kzalloc() puede ser sustituido con kcalloc(). Si no existen funciones con dos argumentos, utilice las funciones que se saturan, en caso de desbordamiento:: bar = vmalloc(array_size(count, size)); Otro caso común a evitar es calcular el tamaño de una estructura com la suma de otras estructuras, como en:: header = kzalloc(sizeof(*header) + count * sizeof(*header->item), GFP_KERNEL); En vez de eso emplee:: header = kzalloc(struct_size(header, item, count), GFP_KERNEL); .. note:: Si se usa struct_size() en una estructura que contiene un elemento de longitud cero o un array de un único elemento como un array miembro, por favor reescribir ese uso y cambiar a un `miembro array flexible <#zero-length-and-one-element-arrays>`_ Para otros cálculos, por favor use las funciones de ayuda: size_mul(), size_add(), and size_sub(). Por ejemplo, en el caso de:: foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); Re-escríbase, como:: foo = krealloc(size_add(current_size, size_mul(chunk_size, size_sub(count, 3))), GFP_KERNEL); Para más detalles, mire también array3_size() y flex_array_size(), como también la familia de funciones relacionadas check_mul_overflow(), check_add_overflow(), check_sub_overflow(), y check_shl_overflow(). simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() ---------------------------------------------------------------------- Las funciones: simple_strtol(), simple_strtoll(), simple_strtoul(), y simple_strtoull() explícitamente ignoran los desbordamientos, lo que puede llevar a resultados inesperados por las funciones que las llaman. Las funciones respectivas kstrtol(), kstrtoll(), kstrtoul(), y kstrtoull() tienden a ser reemplazos correctos, aunque nótese que necesitarán que la cadena de caracteres termine en NUL o en el carácter de línea nueva. strcpy() -------- strcpy() no realiza verificaciones de los límites del buffer de destino. Esto puede resultar en desbordamientos lineals más allá del fin del buffer, causando todo tipo de errores. Mientras `CONFIG_FORTIFY_SOURCE=y` otras varias opciones de compilación reducen el riesgo de usar esta función, no hay ninguna buena razón para añadir nuevos usos de esta. El remplazo seguro es la función strscpy(), aunque se ha de tener cuidado con cualquier caso en el el valor retornado por strcpy() sea usado, ya que strscpy() no devuelve un puntero a el destino, sino el número de caracteres no nulos compilados (o el valor negativo de errno cuando se trunca la cadena de caracteres). strncpy() en cadenas de caracteres terminadas en NUL ---------------------------------------------------- El uso de strncpy() no garantiza que el buffer de destino esté terminado en NUL. Esto puede causar varios errores de desbordamiento en lectura y otros tipos de funcionamiento erróneo debido a que falta la terminación en NUL. Esta función también termina la cadena de caracteres en NUL en el buffer de destino si la cadena de origen es más corta que el buffer de destino, lo cual puede ser una penalización innecesaria para funciones usen esta función con cadenas de caracteres que sí están terminadas en NUL. Cuando se necesita que la cadena de destino sea terminada en NUL, el mejor reemplazo es usar la función strscpy(), aunque se ha de tener cuidado en los casos en los que el valor de strncpy() fuera usado, ya que strscpy() no devuelve un puntero al destino, sino el número de caracteres no nulos copiados (o el valor negativo de errno cuando se trunca la cadena de caracteres). Cualquier caso restante que necesitase todavía ser terminado en el caracter nulo, debería usar strscpy_pad(). Si una función usa cadenas de caracteres que no necesitan terminar en NUL, debería usarse strtomem(), y el destino debería señalarse con el atributo `__nonstring `_ para evitar avisos futuros en el compilador. Para casos que todavía necesitan cadenas de caracteres que se rellenen al final con el caracter NUL, usar strtomem_pad(). strlcpy() --------- strlcpy() primero lee por completo el buffer de origen (ya que el valor devuelto intenta ser el mismo que el de strlen()). Esta lectura puede sobrepasar el límite de tamaño del destino. Esto ineficiente y puede causar desbordamientos de lectura si la cadena de origen no está terminada en el carácter NUL. El reemplazo seguro de esta función es strscpy(), pero se ha de tener cuidado que en los casos en lso que se usase el valor devuelto de strlcpy(), ya que strscpy() devolverá valores negativos de erno cuando se produzcan truncados. Especificación de formato %p ---------------------------- Tradicionalmente,el uso de "%p" en el formato de cadenas de caracteres resultaría en exponer esas direcciones en dmesg, proc, sysfs, etc. En vez de dejar que sean una vulnerabilidad, todos los "%p" que se usan en el kernel se imprimen como un hash, haciéndolos efectivamente inutilizables para usarlos como direcciones de memoria. Nuevos usos de "%p" no deberían ser añadidos al kernel. Para textos de direcciones, usar "%pS" es mejor, ya que resulta en el nombre del símbolo. Para prácticamente el resto de casos, mejor no usar "%p" en absoluto. Parafraseando las actuales `direcciones de Linus `_: - Si el valor "hasheado" "%p" no tienen ninguna finalidad, preguntarse si el puntero es realmente importante. ¿Quizás se podría quitar totalmente? - Si realmente se piensa que el valor del puntero es importante, ¿porqué algún estado del sistema o nivel de privilegio de usuario es considerado "especial"? Si piensa que puede justificarse (en comentarios y mensajes del commit), de forma suficiente como para pasar el escrutinio de Linux, quizás pueda usar el "%p", a la vez que se asegura que tiene los permisos correspondientes. Si está depurando algo donde el "%p" hasheado está causando problemas, se puede arrancar temporalmente con la opción de depuración "`no_hash_pointers `_". Arrays de longitud variable (VLAs) ---------------------------------- Usando VLA en la pila (stack) produce un código mucho peor que los arrays de tamaño estático. Mientras que estos errores no triviales de `rendimiento `_ son razón suficiente para no usar VLAs, esto además son un riesgo de seguridad. El crecimiento dinámico del array en la pila, puede exceder la memoria restante en el segmento de la pila. Esto podría llevara a un fallo, posible sobre-escritura de contenido al final de la pila (cuando se construye sin `CONFIG_THREAD_INFO_IN_TASK=y`), o sobre-escritura de la memoria adyacente a la pila (cuando se construye sin `CONFIG_VMAP_STACK=y`). Switch case fall-through implícito ---------------------------------- El lenguaje C permite a las sentencias 'switch' saltar de un caso al siguiente caso cuando la sentencia de ruptura "break" no aparece al final del caso. Esto, introduce ambigüedad en el código, ya que no siempre está claro si el 'break' que falta es intencionado o un olvido. Por ejemplo, no es obvio solamente mirando al código si `STATE_ONE` está escrito para intencionadamente saltar en `STATE_TWO`:: switch (value) { case STATE_ONE: do_something(); case STATE_TWO: do_other(); break; default: WARN("unknown state"); } Ya que ha habido una larga lista de defectos `debidos a declaraciones de "break" que faltan `_, no se permiten 'fall-through' implícitos. Para identificar 'fall-through' intencionados, se ha adoptado la pseudo-palabra-clave macro "falltrhrough", que expande las extensiones de gcc `__attribute__((__fallthrough__)) `_. (Cuando la sintaxis de C17/c18 `[[fallthrough]]` sea más comúnmente soportadas por los compiladores de C, analizadores estáticos, e IDEs, se puede cambiar a usar esa sintaxis para esa pseudo-palabra-clave. Todos los bloques switch/case deben acabar en uno de: * break; * fallthrough; * continue; * goto