Documentation/translations/it_IT/process/deprecated.rst - linux - Git at Google

 .. SPDX-License-Identifier: GPL-2.0

 .. include:: ../disclaimer-ita.rst

 :Original: :ref:`Documentation/process/deprecated.rst <deprecated>`
 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>

 .. _it_deprecated:

 ==============================================================================
 Interfacce deprecate, caratteristiche del linguaggio, attributi, e convenzioni
 ==============================================================================

 In un mondo perfetto, sarebbe possibile prendere tutti gli usi di
 un'interfaccia deprecata e convertirli in quella nuova, e così sarebbe
 possibile rimuovere la vecchia interfaccia in un singolo ciclo di sviluppo.
 Tuttavia, per via delle dimensioni del kernel, la gerarchia dei manutentori e
 le tempistiche, non è sempre possibile fare questo tipo di conversione tutta
 in una volta. Questo significa che nuove istanze di una vecchia interfaccia
 potrebbero aggiungersi al kernel proprio quando si sta cercando di rimuoverle,
 aumentando così il carico di lavoro. Al fine di istruire gli sviluppatori su
 cosa è considerato deprecato (e perché), è stata create la seguente lista a cui
 fare riferimento quando qualcuno propone modifiche che usano cose deprecate.

 __deprecated
 ------------
 Nonostante questo attributo marchi visibilmente un interfaccia come deprecata,
 `non produce più alcun avviso durante la compilazione
 <https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
 perché uno degli obiettivi del kernel è quello di compilare senza avvisi;
 inoltre, nessuno stava agendo per rimuovere queste interfacce. Nonostante l'uso
 di `__deprecated` in un file d'intestazione sia opportuno per segnare una
 interfaccia come 'vecchia', questa non è una soluzione completa. L'interfaccia
 deve essere rimossa dal kernel, o aggiunta a questo documento per scoraggiarne
 l'uso.

 BUG() e BUG_ON()
 ----------------
 Al loro posto usate WARN() e WARN_ON() per gestire le
 condizioni "impossibili" e gestitele come se fosse possibile farlo.
 Nonostante le funzioni della famiglia BUG() siano state progettate
 per asserire "situazioni impossibili" e interrompere in sicurezza un
 thread del kernel, queste si sono rivelate essere troppo rischiose
 (per esempio, in quale ordine rilasciare i *lock*? Ci sono stati che
 sono stati ripristinati?). Molto spesso l'uso di BUG()
 destabilizza il sistema o lo corrompe del tutto, il che rende
 impossibile un'attività di debug o anche solo leggere un rapporto
 circa l'errore.  Linus ha un'opinione molto critica al riguardo:
 `email 1
 <https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_,
 `email 2
 <https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_

 Tenete presente che la famiglia di funzioni WARN() dovrebbe essere
 usato solo per situazioni che si suppone siano "impossibili".  Se
 volete avvisare gli utenti riguardo a qualcosa di possibile anche se
 indesiderato, usare le funzioni della famiglia pr_warn().  Chi
 amministra il sistema potrebbe aver attivato l'opzione sysctl
 *panic_on_warn* per essere sicuri che il sistema smetta di funzionare
 in caso si verifichino delle condizioni "inaspettate". (per esempio,
 date un'occhiata al questo `commit
 <https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_)

 Calcoli codificati negli argomenti di un allocatore
 ----------------------------------------------------
 Il calcolo dinamico delle dimensioni (specialmente le moltiplicazioni) non
 dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria
 (o simili) per via del rischio di overflow. Questo può portare a valori più
 piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di
 allocare può portare ad un overflow della memoria di heap e altri
 malfunzionamenti. (Si fa eccezione per valori numerici per i quali il
 compilatore può generare avvisi circa un potenziale overflow. Tuttavia, anche in
 questi casi è preferibile riscrivere il codice come suggerito di seguito).

 Per esempio, non usate ``count * size`` come argomento::

 	foo = kmalloc(count * size, GFP_KERNEL);

 Al suo posto, si dovrebbe usare l'allocatore a due argomenti::

 	foo = kmalloc_array(count, size, GFP_KERNEL);

 Nello specifico, kmalloc() può essere sostituta da kmalloc_array(), e kzalloc()
 da kcalloc().

 Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate
 le funzioni del tipo *saturate-on-overflow*::

 	bar = vmalloc(array_size(count, size));

 Un altro tipico caso da evitare è quello di calcolare la dimensione di una
 struttura seguita da un vettore di altre strutture, come nel seguente caso::

 	header = kzalloc(sizeof(*header) + count * sizeof(*header->item),
 			 GFP_KERNEL);

 Invece, usate la seguente funzione::

 	header = kzalloc(struct_size(header, item, count), GFP_KERNEL);

 .. note:: Se per caso state usando struct_size() su una struttura dati che
 	  in coda contiene un array di lunghezza zero o uno, allora siete
 	  invitati a riorganizzare il vostro codice usando il
 	  `flexible array member <#zero-length-and-one-element-arrays>`_.

 Per altri calcoli, usate le funzioni size_mul(), size_add(), e size_sub(). Per
 esempio, al posto di::

        foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);

 dovreste scrivere:

        foo = krealloc(size_add(current_size,
                                size_mul(chunk_size,
                                         size_sub(count, 3))), GFP_KERNEL);

 Per maggiori dettagli fate riferimento a array3_size() e flex_array_size(), ma
 anche le funzioni della famiglia check_mul_overflow(), check_add_overflow(),
 check_sub_overflow(), e check_shl_overflow().

 simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
 ----------------------------------------------------------------------
 Le funzioni simple_strtol(), simple_strtoll(),
 simple_strtoul(), e simple_strtoull() ignorano volutamente
 i possibili overflow, e questo può portare il chiamante a generare risultati
 inaspettati. Le rispettive funzioni kstrtol(), kstrtoll(),
 kstrtoul(), e kstrtoull() sono da considerarsi le corrette
 sostitute; tuttavia va notato che queste richiedono che la stringa sia
 terminata con il carattere NUL o quello di nuova riga.

 strcpy()
 --------
 La funzione strcpy() non fa controlli agli estremi del buffer
 di destinazione. Questo può portare ad un overflow oltre i limiti del
 buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione
 `CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano
 a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare
 questa funzione. La versione sicura da usare è strscpy(), tuttavia va
 prestata attenzione a tutti quei casi dove viene usato il valore di
 ritorno di strcpy().  La funzione strscpy() non ritorna un puntatore
 alla destinazione, ma un contatore dei byte non NUL copiati (oppure
 un errno negativo se la stringa è stata troncata).

 strncpy() su stringe terminate con NUL
 --------------------------------------
 L'utilizzo di strncpy() non fornisce alcuna garanzia sul fatto che
 il buffer di destinazione verrà terminato con il carattere NUL. Questo
 potrebbe portare a diversi overflow di lettura o altri malfunzionamenti
 causati, appunto, dalla mancanza del terminatore. Questa estende la
 terminazione nel buffer di destinazione quando la stringa d'origine è più
 corta; questo potrebbe portare ad una penalizzazione delle prestazioni per
 chi usa solo stringe terminate. La versione sicura da usare è
 strscpy(), tuttavia va prestata attenzione a tutti quei casi dove
 viene usato il valore di ritorno di strncpy().  La funzione strscpy()
 non ritorna un puntatore alla destinazione, ma un contatore dei byte
 non NUL copiati (oppure un errno negativo se la stringa è stata
 troncata). Tutti i casi che necessitano di estendere la
 terminazione con NUL dovrebbero usare strscpy_pad().

 Se il chiamate no usa stringhe terminate con NUL, allore strncpy()
 può continuare ad essere usata, ma i buffer di destinazione devono essere
 marchiati con l'attributo `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_
 per evitare avvisi durante la compilazione.

 strlcpy()
 ---------
 La funzione strlcpy(), per prima cosa, legge interamente il buffer di
 origine, magari leggendo più di quanto verrà effettivamente copiato. Questo
 è inefficiente e può portare a overflow di lettura quando la stringa non è
 terminata con NUL. La versione sicura da usare è strscpy(), tuttavia
 va prestata attenzione a tutti quei casi dove viene usato il valore di
 ritorno di strlcpy(), dato che strscpy() ritorna un valore di errno
 negativo quanto la stringa viene troncata.

 Segnaposto %p nella stringa di formato
 --------------------------------------

 Tradizionalmente, l'uso del segnaposto "%p" nella stringa di formato
 esponne un indirizzo di memoria in dmesg, proc, sysfs, eccetera.  Per
 evitare che questi indirizzi vengano sfruttati da malintenzionati,
 tutto gli usi di "%p" nel kernel rappresentano l'hash dell'indirizzo,
 rendendolo di fatto inutilizzabile.  Nuovi usi di "%p" non dovrebbero
 essere aggiunti al kernel.  Per una rappresentazione testuale di un
 indirizzo usate "%pS", l'output è migliore perché mostrerà il nome del
 simbolo.  Per tutto il resto, semplicemente non usate "%p".

 Parafrasando la `guida
 <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_
 di Linus:

 - Se il valore hash di "%p" è inutile, chiediti se il puntatore stesso
   è importante. Forse dovrebbe essere rimosso del tutto?
 - Se credi davvero che il vero valore del puntatore sia importante,
   perché alcuni stati del sistema o i livelli di privilegi di un
   utente sono considerati "special"? Se pensi di poterlo giustificare
   (in un commento e nel messaggio del commit) abbastanza bene da
   affrontare il giudizio di Linus, allora forse potrai usare "%px",
   assicurandosi anche di averne il permesso.

 Potete disabilitare temporaneamente l'hashing di "%p" nel caso in cui questa
 funzionalità vi sia d'ostacolo durante una sessione di debug. Per farlo
 aggiungete l'opzione di debug "`no_hash_pointers
 <https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_" alla
 riga di comando del kernel.

 Vettori a dimensione variabile (VLA)
 ------------------------------------

 Usare VLA sullo stack produce codice molto peggiore rispetto a quando si usano
 vettori a dimensione fissa. Questi `problemi di prestazioni <https://git.kernel.org/linus/02361bc77888>`_,
 tutt'altro che banali, sono già un motivo valido per eliminare i VLA; in
 aggiunta sono anche un problema per la sicurezza. La crescita dinamica di un
 vettore nello stack potrebbe eccedere la memoria rimanente in tale segmento.
 Questo può portare a dei malfunzionamenti, potrebbe sovrascrivere
 dati importanti alla fine dello stack (quando il kernel è compilato senza
 `CONFIG_THREAD_INFO_IN_TASK=y`), o sovrascrivere un pezzo di memoria adiacente
 allo stack (quando il kernel è compilato senza `CONFIG_VMAP_STACK=y`).

 Salto implicito nell'istruzione switch-case
 -------------------------------------------

 Il linguaggio C permette ai casi di un'istruzione `switch` di saltare al
 prossimo caso quando l'istruzione "break" viene omessa alla fine del caso
 corrente. Tuttavia questo rende il codice ambiguo perché non è sempre ovvio se
 l'istruzione "break" viene omessa intenzionalmente o è un baco. Per esempio,
 osservando il seguente pezzo di codice non è chiaro se lo stato
 `STATE_ONE` è stato progettato apposta per eseguire anche `STATE_TWO`::

   switch (value) {
   case STATE_ONE:
           do_something();
   case STATE_TWO:
           do_other();
           break;
   default:
           WARN("unknown state");
   }

 Dato che c'è stata una lunga lista di problemi `dovuti alla mancanza dell'istruzione
 "break" <https://cwe.mitre.org/data/definitions/484.html>`_, oggigiorno non
 permettiamo più che vi sia un "salto implicito" (*fall-through*). Per
 identificare un salto implicito intenzionale abbiamo adottato la pseudo
 parola chiave 'fallthrough' che viene espansa nell'estensione di gcc
 `__attribute__((fallthrough))` `Statement Attributes
 <https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.
 (Quando la sintassi C17/C18 `[[fallthrough]]` sarà più comunemente
 supportata dai compilatori C, analizzatori statici, e dagli IDE,
 allora potremo usare quella sintassi per la pseudo parola chiave)

 Quando la sintassi [[fallthrough]] sarà più comunemente supportata dai
 compilatori, analizzatori statici, e ambienti di sviluppo IDE,
 allora potremo usarla anche noi.

 Ne consegue che tutti i blocchi switch/case devono finire in uno dei seguenti
 modi:

 * ``break;``
 * `fallthrough;``
 * ``continue;``
 * ``goto <label>;``
 * ``return [expression];``

 Array di lunghezza zero o con un solo elemento
 ----------------------------------------------
 All'interno del kernel ricorre spesso la necessita di avere membri
 di dimensione variabile all'interno di una struttura dati. In questi
 casi il codice del kernel dovrebbe usare sempre i `"flexible array
 member" <https://en.wikipedia.org/wiki/Flexible_array_member>`_. La
 tecnica degli array a lunghezza nulla o di un solo elemento non
 dovrebbe essere più usata.

 Nel codice C più vecchio, la dichiarazione di un membro di dimensione
 variabile in coda ad una struttura dati veniva fatto dichiarando un
 array di un solo elemento posizionato alla fine della struttura dati::

         struct something {
                 size_t count;
                 struct foo items[1];
         };

 Questo ha portato ad un calcolo di sizeof() traballante (dovrebbe
 rimuovere la dimensione del singolo elemento in coda per calcolare la
 dimensione esatta dell' "intestazione"). Per evitare questi problemi è
 stata introdotta un' `estensione a GNU C
 <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ che
 permettesse la dichiarazione di array a lungezza zero::

         struct something {
                 size_t count;
                 struct foo items[0];
         };

 Ma questo ha portato nuovi problemi, e non ha risolto alcuni dei
 problemi che affliggono entrambe le tecniche: per esempio
 l'impossibilità di riconoscere se un array di quel tipo viene usato
 nel mezzo di una struttura dati e _non_ alla fine (potrebbe accadere
 sia direttamente, sia indirettamente quando si usano le unioni o le
 strutture di strutture).

 Lo standard C99 introduce i "flexible array members". Questi array non
 hanno una dimensione nella loro dichiarazione::

         struct something {
                 size_t count;
                 struct foo items[];
         };

 Questo è il modo con cui ci si aspetta che vengano dichiarati gli
 elementi di lunghezza variabile in coda alle strutture dati.  Permette
 al compilatore di produrre errori quando gli array flessibili non si
 trovano alla fine della struttura dati, il che permette di prevenire
 alcuni tipi di bachi dovuti a `comportamenti inaspettati
 <https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_.
 Inoltre, permette al compilatore di analizzare correttamente le
 dimensioni degli array (attraverso sizeof(), `CONFIG_FORTIFY_SOURCE`,
 e `CONFIG_UBSAN_BOUNDS`). Per esempio, non esiste alcun meccanismo in
 grado di avvisarci che il seguente uso di sizeof() dia sempre come
 zero come risultato::

         struct something {
                 size_t count;
                 struct foo items[0];
         };

         struct something *instance;

         instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
         instance->count = count;

         size = sizeof(instance->items) * instance->count;
         memcpy(instance->items, source, size);

 Il valore di ``size`` nell'ultima riga sarà ``zero``, quando uno
 invece si aspetterebbe che il suo valore sia la dimensione totale in
 byte dell'allocazione dynamica che abbiamo appena fatto per l'array
 ``items``. Qui un paio di esempi reali del problema: `collegamento 1
 <https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
 `collegamento 2
 <https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
 Invece, `i flexible array members hanno un tipo incompleto, e quindi
 sizeof() non può essere applicato
 <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_; dunque ogni
 uso scorretto di questo operatore verrà identificato immediatamente
 durante la compilazione.

 Per quanto riguarda gli array di un solo elemento, bisogna essere
 consapevoli che `questi array occupano almeno quanto lo spazio di un
 singolo oggetti dello stesso tipo
 <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, e quindi
 contribuiscono al calcolo della dimensione della struttura che li
 contiene. In questo caso è facile commettere errori quando si vuole
 calcolare la dimensione totale della memoria totale da allocare per
 una struttura dati::

         struct something {
                 size_t count;
                 struct foo items[1];
         };

         struct something *instance;

         instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
         instance->count = count;

         size = sizeof(instance->items) * instance->count;
         memcpy(instance->items, source, size);

 In questo esempio ci siamo dovuti ricordare di usare ``count - 1`` in
 struct_size(), altrimenti avremmo --inavvertitamente-- allocato
 memoria per un oggetti ``items`` in più. Il modo più pulito e meno
 propenso agli errori è quello di usare i `flexible array member`, in
 combinazione con struct_size() e flex_array_size()::

         struct something {
                 size_t count;
                 struct foo items[];
         };

         struct something *instance;

         instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
         instance->count = count;

 	memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
	.. SPDX-License-Identifier: GPL-2.0

	.. include:: ../disclaimer-ita.rst

	:Original: :ref:`Documentation/process/deprecated.rst <deprecated>`
	:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

	.. _it_deprecated:

	==============================================================================
	Interfacce deprecate, caratteristiche del linguaggio, attributi, e convenzioni
	==============================================================================

	In un mondo perfetto, sarebbe possibile prendere tutti gli usi di
	un'interfaccia deprecata e convertirli in quella nuova, e così sarebbe
	possibile rimuovere la vecchia interfaccia in un singolo ciclo di sviluppo.
	Tuttavia, per via delle dimensioni del kernel, la gerarchia dei manutentori e
	le tempistiche, non è sempre possibile fare questo tipo di conversione tutta
	in una volta. Questo significa che nuove istanze di una vecchia interfaccia
	potrebbero aggiungersi al kernel proprio quando si sta cercando di rimuoverle,
	aumentando così il carico di lavoro. Al fine di istruire gli sviluppatori su
	cosa è considerato deprecato (e perché), è stata create la seguente lista a cui
	fare riferimento quando qualcuno propone modifiche che usano cose deprecate.

	__deprecated
	------------
	Nonostante questo attributo marchi visibilmente un interfaccia come deprecata,
	`non produce più alcun avviso durante la compilazione
	<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
	perché uno degli obiettivi del kernel è quello di compilare senza avvisi;
	inoltre, nessuno stava agendo per rimuovere queste interfacce. Nonostante l'uso
	di `__deprecated` in un file d'intestazione sia opportuno per segnare una
	interfaccia come 'vecchia', questa non è una soluzione completa. L'interfaccia
	deve essere rimossa dal kernel, o aggiunta a questo documento per scoraggiarne
	l'uso.

	BUG() e BUG_ON()
	----------------
	Al loro posto usate WARN() e WARN_ON() per gestire le
	condizioni "impossibili" e gestitele come se fosse possibile farlo.
	Nonostante le funzioni della famiglia BUG() siano state progettate
	per asserire "situazioni impossibili" e interrompere in sicurezza un
	thread del kernel, queste si sono rivelate essere troppo rischiose
	(per esempio, in quale ordine rilasciare i lock? Ci sono stati che
	sono stati ripristinati?). Molto spesso l'uso di BUG()
	destabilizza il sistema o lo corrompe del tutto, il che rende
	impossibile un'attività di debug o anche solo leggere un rapporto
	circa l'errore. Linus ha un'opinione molto critica al riguardo:
	`email 1
	<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_,
	`email 2
	<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_

	Tenete presente che la famiglia di funzioni WARN() dovrebbe essere
	usato solo per situazioni che si suppone siano "impossibili". Se
	volete avvisare gli utenti riguardo a qualcosa di possibile anche se
	indesiderato, usare le funzioni della famiglia pr_warn(). Chi
	amministra il sistema potrebbe aver attivato l'opzione sysctl
	panic_on_warn per essere sicuri che il sistema smetta di funzionare
	in caso si verifichino delle condizioni "inaspettate". (per esempio,
	date un'occhiata al questo `commit
	<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_)

	Calcoli codificati negli argomenti di un allocatore
	----------------------------------------------------
	Il calcolo dinamico delle dimensioni (specialmente le moltiplicazioni) non
	dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria
	(o simili) per via del rischio di overflow. Questo può portare a valori più
	piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di
	allocare può portare ad un overflow della memoria di heap e altri
	malfunzionamenti. (Si fa eccezione per valori numerici per i quali il
	compilatore può generare avvisi circa un potenziale overflow. Tuttavia, anche in
	questi casi è preferibile riscrivere il codice come suggerito di seguito).

	Per esempio, non usate ``count * size`` come argomento::

	foo = kmalloc(count * size, GFP_KERNEL);

	Al suo posto, si dovrebbe usare l'allocatore a due argomenti::

	foo = kmalloc_array(count, size, GFP_KERNEL);

	Nello specifico, kmalloc() può essere sostituta da kmalloc_array(), e kzalloc()
	da kcalloc().

	Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate
	le funzioni del tipo saturate-on-overflow::

	bar = vmalloc(array_size(count, size));

	Un altro tipico caso da evitare è quello di calcolare la dimensione di una
	struttura seguita da un vettore di altre strutture, come nel seguente caso::

	header = kzalloc(sizeof(header) + count sizeof(*header->item),
	GFP_KERNEL);

	Invece, usate la seguente funzione::

	header = kzalloc(struct_size(header, item, count), GFP_KERNEL);

	.. note:: Se per caso state usando struct_size() su una struttura dati che
	in coda contiene un array di lunghezza zero o uno, allora siete
	invitati a riorganizzare il vostro codice usando il
	`flexible array member <#zero-length-and-one-element-arrays>`_.

	Per altri calcoli, usate le funzioni size_mul(), size_add(), e size_sub(). Per
	esempio, al posto di::

	foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);

	dovreste scrivere:

	foo = krealloc(size_add(current_size,
	size_mul(chunk_size,
	size_sub(count, 3))), GFP_KERNEL);

	Per maggiori dettagli fate riferimento a array3_size() e flex_array_size(), ma
	anche le funzioni della famiglia check_mul_overflow(), check_add_overflow(),
	check_sub_overflow(), e check_shl_overflow().

	simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
	----------------------------------------------------------------------
	Le funzioni simple_strtol(), simple_strtoll(),
	simple_strtoul(), e simple_strtoull() ignorano volutamente
	i possibili overflow, e questo può portare il chiamante a generare risultati
	inaspettati. Le rispettive funzioni kstrtol(), kstrtoll(),
	kstrtoul(), e kstrtoull() sono da considerarsi le corrette
	sostitute; tuttavia va notato che queste richiedono che la stringa sia
	terminata con il carattere NUL o quello di nuova riga.

	strcpy()
	--------
	La funzione strcpy() non fa controlli agli estremi del buffer
	di destinazione. Questo può portare ad un overflow oltre i limiti del
	buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione
	`CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano
	a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare
	questa funzione. La versione sicura da usare è strscpy(), tuttavia va
	prestata attenzione a tutti quei casi dove viene usato il valore di
	ritorno di strcpy(). La funzione strscpy() non ritorna un puntatore
	alla destinazione, ma un contatore dei byte non NUL copiati (oppure
	un errno negativo se la stringa è stata troncata).

	strncpy() su stringe terminate con NUL
	--------------------------------------
	L'utilizzo di strncpy() non fornisce alcuna garanzia sul fatto che
	il buffer di destinazione verrà terminato con il carattere NUL. Questo
	potrebbe portare a diversi overflow di lettura o altri malfunzionamenti
	causati, appunto, dalla mancanza del terminatore. Questa estende la
	terminazione nel buffer di destinazione quando la stringa d'origine è più
	corta; questo potrebbe portare ad una penalizzazione delle prestazioni per
	chi usa solo stringe terminate. La versione sicura da usare è
	strscpy(), tuttavia va prestata attenzione a tutti quei casi dove
	viene usato il valore di ritorno di strncpy(). La funzione strscpy()
	non ritorna un puntatore alla destinazione, ma un contatore dei byte
	non NUL copiati (oppure un errno negativo se la stringa è stata
	troncata). Tutti i casi che necessitano di estendere la
	terminazione con NUL dovrebbero usare strscpy_pad().

	Se il chiamate no usa stringhe terminate con NUL, allore strncpy()
	può continuare ad essere usata, ma i buffer di destinazione devono essere
	marchiati con l'attributo `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_
	per evitare avvisi durante la compilazione.

	strlcpy()
	---------
	La funzione strlcpy(), per prima cosa, legge interamente il buffer di
	origine, magari leggendo più di quanto verrà effettivamente copiato. Questo
	è inefficiente e può portare a overflow di lettura quando la stringa non è
	terminata con NUL. La versione sicura da usare è strscpy(), tuttavia
	va prestata attenzione a tutti quei casi dove viene usato il valore di
	ritorno di strlcpy(), dato che strscpy() ritorna un valore di errno
	negativo quanto la stringa viene troncata.

	Segnaposto %p nella stringa di formato
	--------------------------------------

	Tradizionalmente, l'uso del segnaposto "%p" nella stringa di formato
	esponne un indirizzo di memoria in dmesg, proc, sysfs, eccetera. Per
	evitare che questi indirizzi vengano sfruttati da malintenzionati,
	tutto gli usi di "%p" nel kernel rappresentano l'hash dell'indirizzo,
	rendendolo di fatto inutilizzabile. Nuovi usi di "%p" non dovrebbero
	essere aggiunti al kernel. Per una rappresentazione testuale di un
	indirizzo usate "%pS", l'output è migliore perché mostrerà il nome del
	simbolo. Per tutto il resto, semplicemente non usate "%p".

	Parafrasando la `guida
	<https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_
	di Linus:

	- Se il valore hash di "%p" è inutile, chiediti se il puntatore stesso
	è importante. Forse dovrebbe essere rimosso del tutto?
	- Se credi davvero che il vero valore del puntatore sia importante,
	perché alcuni stati del sistema o i livelli di privilegi di un
	utente sono considerati "special"? Se pensi di poterlo giustificare
	(in un commento e nel messaggio del commit) abbastanza bene da
	affrontare il giudizio di Linus, allora forse potrai usare "%px",
	assicurandosi anche di averne il permesso.

	Potete disabilitare temporaneamente l'hashing di "%p" nel caso in cui questa
	funzionalità vi sia d'ostacolo durante una sessione di debug. Per farlo
	aggiungete l'opzione di debug "`no_hash_pointers
	<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_" alla
	riga di comando del kernel.

	Vettori a dimensione variabile (VLA)
	------------------------------------

	Usare VLA sullo stack produce codice molto peggiore rispetto a quando si usano
	vettori a dimensione fissa. Questi `problemi di prestazioni <https://git.kernel.org/linus/02361bc77888>`_,
	tutt'altro che banali, sono già un motivo valido per eliminare i VLA; in
	aggiunta sono anche un problema per la sicurezza. La crescita dinamica di un
	vettore nello stack potrebbe eccedere la memoria rimanente in tale segmento.
	Questo può portare a dei malfunzionamenti, potrebbe sovrascrivere
	dati importanti alla fine dello stack (quando il kernel è compilato senza
	`CONFIG_THREAD_INFO_IN_TASK=y`), o sovrascrivere un pezzo di memoria adiacente
	allo stack (quando il kernel è compilato senza `CONFIG_VMAP_STACK=y`).

	Salto implicito nell'istruzione switch-case
	-------------------------------------------

	Il linguaggio C permette ai casi di un'istruzione `switch` di saltare al
	prossimo caso quando l'istruzione "break" viene omessa alla fine del caso
	corrente. Tuttavia questo rende il codice ambiguo perché non è sempre ovvio se
	l'istruzione "break" viene omessa intenzionalmente o è un baco. Per esempio,
	osservando il seguente pezzo di codice non è chiaro se lo stato
	`STATE_ONE` è stato progettato apposta per eseguire anche `STATE_TWO`::

	switch (value) {
	case STATE_ONE:
	do_something();
	case STATE_TWO:
	do_other();
	break;
	default:
	WARN("unknown state");
	}

	Dato che c'è stata una lunga lista di problemi `dovuti alla mancanza dell'istruzione
	"break" <https://cwe.mitre.org/data/definitions/484.html>`_, oggigiorno non
	permettiamo più che vi sia un "salto implicito" (fall-through). Per
	identificare un salto implicito intenzionale abbiamo adottato la pseudo
	parola chiave 'fallthrough' che viene espansa nell'estensione di gcc
	`__attribute__((fallthrough))` `Statement Attributes
	<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_.
	(Quando la sintassi C17/C18 `[[fallthrough]]` sarà più comunemente
	supportata dai compilatori C, analizzatori statici, e dagli IDE,
	allora potremo usare quella sintassi per la pseudo parola chiave)

	Quando la sintassi [[fallthrough]] sarà più comunemente supportata dai
	compilatori, analizzatori statici, e ambienti di sviluppo IDE,
	allora potremo usarla anche noi.

	Ne consegue che tutti i blocchi switch/case devono finire in uno dei seguenti
	modi:

	* ``break;``
	* `fallthrough;``
	* ``continue;``
	* ``goto <label>;``
	* ``return [expression];``

	Array di lunghezza zero o con un solo elemento
	----------------------------------------------
	All'interno del kernel ricorre spesso la necessita di avere membri
	di dimensione variabile all'interno di una struttura dati. In questi
	casi il codice del kernel dovrebbe usare sempre i `"flexible array
	member" <https://en.wikipedia.org/wiki/Flexible_array_member>`_. La
	tecnica degli array a lunghezza nulla o di un solo elemento non
	dovrebbe essere più usata.

	Nel codice C più vecchio, la dichiarazione di un membro di dimensione
	variabile in coda ad una struttura dati veniva fatto dichiarando un
	array di un solo elemento posizionato alla fine della struttura dati::

	struct something {
	size_t count;
	struct foo items[1];
	};

	Questo ha portato ad un calcolo di sizeof() traballante (dovrebbe
	rimuovere la dimensione del singolo elemento in coda per calcolare la
	dimensione esatta dell' "intestazione"). Per evitare questi problemi è
	stata introdotta un' `estensione a GNU C
	<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ che
	permettesse la dichiarazione di array a lungezza zero::

	struct something {
	size_t count;
	struct foo items[0];
	};

	Ma questo ha portato nuovi problemi, e non ha risolto alcuni dei
	problemi che affliggono entrambe le tecniche: per esempio
	l'impossibilità di riconoscere se un array di quel tipo viene usato
	nel mezzo di una struttura dati e _non_ alla fine (potrebbe accadere
	sia direttamente, sia indirettamente quando si usano le unioni o le
	strutture di strutture).

	Lo standard C99 introduce i "flexible array members". Questi array non
	hanno una dimensione nella loro dichiarazione::

	struct something {
	size_t count;
	struct foo items[];
	};

	Questo è il modo con cui ci si aspetta che vengano dichiarati gli
	elementi di lunghezza variabile in coda alle strutture dati. Permette
	al compilatore di produrre errori quando gli array flessibili non si
	trovano alla fine della struttura dati, il che permette di prevenire
	alcuni tipi di bachi dovuti a `comportamenti inaspettati
	<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_.
	Inoltre, permette al compilatore di analizzare correttamente le
	dimensioni degli array (attraverso sizeof(), `CONFIG_FORTIFY_SOURCE`,
	e `CONFIG_UBSAN_BOUNDS`). Per esempio, non esiste alcun meccanismo in
	grado di avvisarci che il seguente uso di sizeof() dia sempre come
	zero come risultato::

	struct something {
	size_t count;
	struct foo items[0];
	};

	struct something *instance;

	instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
	instance->count = count;

	size = sizeof(instance->items) * instance->count;
	memcpy(instance->items, source, size);

	Il valore di ``size`` nell'ultima riga sarà ``zero``, quando uno
	invece si aspetterebbe che il suo valore sia la dimensione totale in
	byte dell'allocazione dynamica che abbiamo appena fatto per l'array
	``items``. Qui un paio di esempi reali del problema: `collegamento 1
	<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
	`collegamento 2
	<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
	Invece, `i flexible array members hanno un tipo incompleto, e quindi
	sizeof() non può essere applicato
	<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_; dunque ogni
	uso scorretto di questo operatore verrà identificato immediatamente
	durante la compilazione.

	Per quanto riguarda gli array di un solo elemento, bisogna essere
	consapevoli che `questi array occupano almeno quanto lo spazio di un
	singolo oggetti dello stesso tipo
	<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, e quindi
	contribuiscono al calcolo della dimensione della struttura che li
	contiene. In questo caso è facile commettere errori quando si vuole
	calcolare la dimensione totale della memoria totale da allocare per
	una struttura dati::

	struct something {
	size_t count;
	struct foo items[1];
	};

	struct something *instance;

	instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
	instance->count = count;

	size = sizeof(instance->items) * instance->count;
	memcpy(instance->items, source, size);

	In questo esempio ci siamo dovuti ricordare di usare ``count - 1`` in
	struct_size(), altrimenti avremmo --inavvertitamente-- allocato
	memoria per un oggetti ``items`` in più. Il modo più pulito e meno
	propenso agli errori è quello di usare i `flexible array member`, in
	combinazione con struct_size() e flex_array_size()::

	struct something {
	size_t count;
	struct foo items[];
	};

	struct something *instance;

	instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
	instance->count = count;

	memcpy(instance->items, source, flex_array_size(instance, items, instance->count));