diff options
author | Federico Vaga <federico.vaga@vaga.pv.it> | 2020-11-14 09:33:42 +0100 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2020-11-18 13:49:21 -0700 |
commit | ac7711427014a84ba08353df2b77f115565216d8 (patch) | |
tree | f3cb42c896cb175bd333c457812421b037b7ce4d /Documentation/translations/it_IT/process/deprecated.rst | |
parent | 992082d1dc5aea9557f3d197c1d5eff2b9b1f70d (diff) |
doc:it_IT: align Italian documentation
Translation for the following patches
commit 0aa78b105f57 ("Documentation/changes: Raise minimum supported binutils version to 2.23")
commit 7d7178873560 ("Documentation: include sign off for reverts")
commit 905705a8fd43 ("docs: programming-languages: refresh blurb on clang support")
commit 5ff4aa70bf34 ("docs: submitting-patches: use :doc: for references")
commit 030f066f677f ("docs: submitting-patches: describe preserving review/test tags")
commit 68e4cd17e218 ("docs: deprecated.rst: Add zero-length and one-element arrays")
commit 5429ef62bcf3 ("compiler/gcc: Raise minimum GCC version for kernel builds to 4.8")
commit 5b5bbb8cc51b ("docs: process: Add an example for creating a fixes tag")
commit 858e6845654d ("docs: dt: convert submitting-patches.txt to ReST format")
commit cca73e4946c4 ("docs: Correct the release date of 5.2 stable")
commit c170f2eb9648 ("docs: Document cross-referencing between documentation pages")
commit 7c8b9e3000f8 ("kernel-doc: Update "cross-referencing from rST" section to use automarkup")
commit 27def953b63b ("docs: deprecated.rst: Expand str*cpy() replacement notes")
commit 17dca0502314 ("docs: deprecated.rst: Update zero-length/one-element arrays section")
commit 3519c4d6e08e ("Documentation: add minimum clang/llvm version")
commit 0bddd227f3dc ("Documentation: update for gcc 4.9 requirement")
commit 9f364b605f34 ("submitting-patches.rst: presume git will be used")
commit 4ebdf7be21d6 ("Documentation/maintainer: rehome sign-off process")
commit 7433ff33e8ba ("Documentation/process: expand plain-text advice")
commit eb45fb2fb16d ("docs: process: Add cross-link to security-bugs")
commit bdc48fa11e46 ("checkpatch/coding-style: deprecate 80-column warning")
commit f67281a72b30 ("Documentation: process: step 2: Link to email list fixed")
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Link: https://lore.kernel.org/r/20201114083342.13935-1-federico.vaga@vaga.pv.it
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/translations/it_IT/process/deprecated.rst')
-rw-r--r-- | Documentation/translations/it_IT/process/deprecated.rst | 147 |
1 files changed, 143 insertions, 4 deletions
diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index a642ff3fdc8b..07c79d4bafca 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -95,6 +95,11 @@ 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 maggiori dettagli fate riferimento a array_size(), array3_size(), e struct_size(), così come la famiglia di funzioni check_add_overflow() e check_mul_overflow(). @@ -116,7 +121,11 @@ 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(). +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 -------------------------------------- @@ -127,8 +136,12 @@ 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(). (chi usa strscpy() e necessita di estendere la -terminazione con NUL deve aggiungere una chiamata a memset()) +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 @@ -140,7 +153,10 @@ 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(). +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 -------------------------------------- @@ -227,3 +243,126 @@ modi: * ``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)); |