Bash scripting - funzioni

Da Guide@Debianizzati.Org.

Bash scripting

Sommario

  1. Introduzione
  2. Comandi essenziali
  3. Variabili (stringhe)
  4. Caratteri di escape, apici e virgolette
  5. Espansioni in stringhe quotate
  6. Espansioni non quotabili
  7. Istruzioni composte
  8. Funzioni
  9. File descriptor e redirezioni
  10. Segnali

Indice

Una funzione è un raggruppamento di comandi eseguito ogni volta che il nome della funzione è utilizzato come un comando. Per convenzione le definizioni delle funzioni precedono il corpo principale dello script.

All'interno del blocco di comandi (il corpo della funzione), le variabili speciali relative agli argomenti passati allo script ($# $1 $2 ... $* $@) fanno riferimento a quelli passati alla funzione.

Definizione di funzione

Sintassi:

nomefunzione () {
   ...
}

I comandi contenuti nel corpo della funzione sono eseguiti ogni volta che nomefunzione, che è una singola stringa senza spazi con le stesse limitazioni dei nomi delle variabili, è scritto come comando. Si noti che () dopo il nome della funzione serve a identificare l'istruzione composta come una definizione di funzione, e non accetta argomenti al suo interno come altri linguaggi di programmazione, ma resta sempre () invariata.

È buona prassi usare i commenti per specificare le opzioni richieste dalla funzione, in modo da rendere chiaro a chi legge il codice come verranno utilizzati.

In bash è possibile premettere function al nome della funzione, anche senza bisogno di (), ma questa possibilità non è prevista da POSIX.

Nel corpo di una funzione è possibile utilizzare il modificatore local prima di un'assegnazione per rendere la variabile locale, ossia non accessibile fuori dal corpo della funzione. È bene evitare le variabili globali il più possibile (se non sono costanti), ricorrendo ai passaggi di parametri, per evitare la modifica accidentale di variabili esistenti fuori dalla funzione. Questo modificatore non è previsto da POSIX, dove ogni variabile è globale, ma è comunque supportato da ogni moderna shell compatibile e caldamente consigliato.

Per esempio:

# Breve descrizione della funzione
# Numero argomenti: N (N+ per almeno N, oppure * per qualsiasi numero)
# $1 - descrizione del primo argomento
# $2 - descrizione del secondo argomento
# ...
# Input: se si aspetta qualcosa sullo standard input
# Output: cosa stampa sullo standard output
# Exit status: 0 se successo (possibili exit status)
nomefunzione () {
   # definisco variabili locali
   local var1; local var2; ...
   # leggo argomenti passati alla funzione
   var1=$1
   var2=$2
   ...
   # corpo della funzione
   ...
}

Valori di ritorno

Il valore di ritorno di una funzione è quello dell'ultimo blocco eseguito. In alternativa è possibile specificarlo all'interno dei blocchi direttamente con la parola riservata return seguito dall'exit status (un valore qualsiasi tra 0, l'unico per "successo", e 255), facendo terminare la funzione immediatamente.

Se la funzione deve restituire un valore diverso da successo/insuccesso, o comunque per cui basterebbe l'exit status, è possibile stamparlo come output, così da permettere anche l'interazione con comandi esterni tramite una pipe.

Se invece si vuole assegnare questo valore a una variabile possono sorgere delle complicazioni, come per l'assegnazione dell'espansione di un comando, ma esistono diverse possibilità:

Warning.png ATTENZIONE
Esiste anche la possibilità di ricorrere a eval, ma il suo uso non è trattato in questa guida per la sua potenziale pericolosità: possibile code injection e privilege escalation, se l'input non è controllato (sanitized). Su bash è molto meglio ricorrere all'espansione di parametro per l'accesso indiretto, per accedere a una variabile il cui nome è contenuto in un'altra; e ad array associativi per gli altri casi.


Riguardo il carattere ASCII n. 0 va ribadito che una funzione può generarlo e stamparlo senza problemi, perfino con printf, e quindi anche inviarlo tramite una pipe a comandi esterni. I problemi si riscontrano soltanto nella sua lettura, senza passare per comandi esterni, e nell'assegnazione dell'output della funzione a una variabile. Sarebbe possibile soltanto trasformando tutto in un'altra codifica (per esempio base64, esadecimale o ottale), come già visto in precedenza.

Esempi: funzioni di controllo

# Ha un exit status di 0 (successo) solo se l'utente è root
# Numero argomenti: 0
is_root () {
    [ "$(id -u)" = 0 ]
}

# Ha un exit status di 0 solo se l'utente corrente è membro del gruppo scelto
# Numero argomenti: 1
# $1: nome gruppo
is_user_member_of () {
    local name; local groups
    name=$1
    # se l'utente è root non controllo il suo gruppo (invoca is_root)
    if is_root; then
        return 0
    fi
    # controlli
    groups=$(groups) &&
    case "$groups" in
        "$name" | "${name} "* | *" ${name} "* | *" ${name}" )
            true
            ;;
        * ) false
            ;;
    esac
}

In questi esempi di funzione il valore di ritorno della funzione è soltanto il suo exit status, che può essere controllato:

Si noti che questi controlli servono soltanto a gestire il caso in cui uno script pensato per un amministratore, o per membri di un determinato gruppo, venga eseguito per errore da un utente senza gli adeguati privilegi. E permette di informare l'utente prima di eseguire qualsiasi operazione, altrimenti non sarebbe in grado di eseguire operazioni che richiedono privilegi più elevati.

Esempi: funzioni che restituiscono interi

#! /bin/bash

# Conta il numero di stringhe passate come argomento
# Numero argomenti: *
# $* - stringhe qualsiasi
# Output: stampa il numero di stringhe
count () {
    printf %s\\n $#
}

# esegue la funzione con diversi argoment
# e la assegna con espansione di comando
testQ1=$(count "$*")
testN1=$(count $*)
testN2=$(count $@)
testQ2=$(count "$@")

printf %s\\n "Argomenti contati: ${testQ1},${testN1},${testQ2},${testN2}"

exit 0

Si provi a creare lo script (per esempio count.sh), rendendolo eseguibile (si veda l'introduzione) e a provare a chiamarlo con diversi argomenti. In particolare:

$ ./script.sh 1 2 3

Argomenti contati: 1,3,3,3

$ ./script.sh "1 stringa" "2 stringa" "3 stringa"

Argomenti contati: 1,6,6,3

$ ./script.sh "/*/"

Argomenti contati: 1,N,N,1 (dove N è il numero di cartelle presenti in /).

Ovviamente la seconda e la terza posizione combacia sempre perché l'espansione di $* e $@ differisce solo quando queste variabili speciali sono quotate. E soltanto "$@" (quotata) preserva la lista degli argomenti, così com'era stata passata allo script o alla funzione.

Si noti che è possibile assegnare l'output della funzione con un'espansione di comando perché l'output è sempre un valore numerico, e quindi ovviamente senza caratteri ASCII n. 0 e "a capo" finali che vanno preservati.

Esempi: funzioni che restituiscono informazioni su pacchetti Debian

Si noti che i nomi dei pacchetti seguono convenzioni note a priori (per maggiori informazioni si legga il Debian Policy Manual), e in particolare non possono contenere né il carattere ASCII n. 0 né "a capo" finali. Quindi sono stampabili normalmente da una funzione e utilizzabili in un'espansione di comando.

# Stampa la lista di tutti i pacchetti installati, uno per riga
# Numero argomenti: 0
# Output: la lista dei pacchetti installati, uno per riga
#         ogni riga contiene solo i caratteri [a-zA-Z0-9.+:-]
lista_pacchetti_installati () {
    dpkg --get-selections |  # lista i pacchetti noti e il loro stato
        awk '$2 ~ /^install$/ { print $1 }' # stampa il primo campo (pacchetto)
                                            # se il secondo (stato) è: install
}

Si noti che non si controllano gli errori, perché il comando non dipende da condizioni specificate dall'utente e in condizioni normali non può fallire.

# Stampa la versione di Debian, la sezione e l'architettura del pacchetto
# Numero argomenti: 1
# $1 - nome pacchetto Debian
# Output: versione sezione architettura
#         (tre stringhe con i soli caratteri [a-zA-Z0-9.+:/-])
# Exit status: 
#  0 (successo) solo se il pacchetto è installato
#  1 se il pacchetto è installato ma nessuna informazione è trovata
#  2 se il pacchetto non è installato
#  3 se il pacchetto non esiste / non è stato trovato
#  4 nome di pacchetto non valido
stampa_info_pacchetto () {
    local pacchetto; local policy; local info; local versione; local arch
    # inizializzazione
    pacchetto=$1
    policy=
    info=
    versione=
    arch=
    # controlla nome del pacchetto (classe dei caratteri ammessi: [a-z0-9.+:-])
    if [ -z "${pacchetto##*[!a-z0-9.+:-]*}" ]; then
        return 4  # nome del pacchetto non valido
    fi
    # leggi la policy del pacchetto
    if ! policy=$(apt-cache policy "$pacchetto" 2> /dev/null); then
        return 3  # pacchetto non trovato
    fi
    # estrae informazioni nel formato versione/sezione:architettura
    # ma non stampa niente se non è installato
    info=$(printf %s\\n "$policy" |
        awk '$1 ~ /^\*\*\*$/ {
                getline
                print $3":"$4
            }')
        # Spiegazione righe con awk:
        # 1- estraggo la riga in cui il primo campo è: *** (scritto con escape)
        #    corrispondente alla versione attualmente installata
        # 2- leggo la riga successiva (getline)
        #    corrispondente a quella con maggiore priorità o in base all'ordine
        #    in /etc/apt/sources.list ed /etc/apt/sources.list.d/*
        # 3- stampo il terzo e il quarto campo, unendoli con ":"
        #    (campi: priorità origine versione/sezione architettura ...)
        # Risultato (stampato):
        # - se installato: versione/sezione:architettura
        # - se non installato: (niente)
    # controlla output
    if [ -z "$info" ]; then
        return 2            # non installato
    fi
    # estrai campi
    arch=${info##*:}        # estrai architettura (amd64, i386)
    info=${info%${arch}}    # rimuovi architettura
    info=${info%:}          # rimuovi : (non è equivalente a farlo assieme!)
    sezione=${info##*/}     # estrai sezione (main, contrib, non-free)
    info=${info%${sezione}} # rimuovi sezione
    info=${info%/}          # rimuovi /
    versione=$info          # quello che resta è la versione
    # controlla campi (che non siano vuoti e non contengano caratteri invalidi)
    if [ -z "$versione" ] || [ -z "$sezione" ] || [ -z "$arch" ] ||
       [ -z "${info##*[!a-zA-Z0-9.+:/-]*}" ]
    then
        return 1            # informazioni non trovate
    else
        # stampa campi del pacchetto
        printf %s\\n "${versione} ${sezione} ${arch}"
        return 0            # successo
    fi
}

Si noti che il pacchetto preso come argomento dalla funzione potrebbe non esistere oppure non essere installato. Per creare una funzione generale, riusabile in altri script e accettante qualsiasi argomento, è necessario controllare lo stato di uscita dei comandi richiamati, e terminare la funzione con un valore di uscita maggiore di zero, così che possano essere gestiti nel corpo principale dello script. E fare uso di diversi valori di uscita permette inoltre di gestire i diversi errori in modo personalizzato.

#! /bin/bash


### funzioni

lista_pacchetti_installati () {
    # il contenuto della funzione definita precedentemente
    ...
}

stampa_info_pacchetti () {
    # il contenuto della funzione definita precedentemente
    ...
}


### main

# invia l'output della funzione a un blocco con una pipe
lista_pacchetti_installati | {
    # subshell perché il blocco è dopo una pipe

    # exit status di default
    status=0
    # leggilo riga per riga (si veda la parte sui file descriptor)
    while read -r pacchetto
    do
        # assegna l'output della funzione (3 campi, salvo errore) a $info
        info=$(stampa_info_pacchetto "$pacchetto") || {
            # gestisci errore
            nuovo_status=$?
            # mantieni sempre lo stesso numero di campi nell'output
            if [ "$nuovo_status" = 1 ]; then
                # ignoro l'errore, perché potrebbe essere stato installato
                # con dpkg/gdebi oppure da APT ma non essere più presente
                info="NOTFOUND NOTFOUND NOTFOUND"
            else
                # gestisco l'errore, aggiornando $status
                info="ERROR ERROR ERROR"
                # se ci sono più errori tieni quello più grave (maggiore)
                if [ "$nuovo_status" -gt "$status" ]; then
                    status=$nuovo_status
                fi
            fi
        }
        # stampa il nome del pacchetto (1 campo) e le informazioni (3 campi)
        printf %s\\n "${pacchetto} ${info}"
    done

    # restituisce l'exit status
    exit $status  # non termina lo script, ma solo la subshell
                  # (non farebbe differenza, se non ci fosse nient'altro
                  #  dopo il blocco, ma è meglio renderlo esplicito, in caso
                  #  il codice venga esteso in un secondo momento)

} || exit $?      # termina lo script, con l'exit status della subshell
                  # (se diverso da zero, perché si usa l'operatore logico OR)

exit 0            # altrimenti exit status 0 (successo)
                  # tutti i pacchetti installati trovati o non trovati
                  # ma senza altri errori

Lo sforzo di mantenere sempre lo stesso numero di campi, dato che i pacchetti non contengono spazi, permette di utilizzare l'output dello script con altri comandi, per eseguire funzioni ancora più avanzate (ordinamento, ricerca, selezione, ecc...).

Nella sezione successiva, che tratterà i nomi di file qualsiasi (che possono contenere anche il carattere "a capo"), la gestione dell'output di una funzione diventa molto più complicata.

Esempi: funzioni che restituiscono nomi di file

Restituire nomi di file permette di sapere in anticipo che non contengono il carattere ASCII n. 0, ed è un vantaggio rispetto a una stringa qualsiasi. Infatti, come rimarcato più volte, non è possibile in generale assegnare il contenuto di un file binario a una variabile, ma solo leggere riga per riga un file di testo (che non contiene il carattere ASCII n. 0). Quindi quando si gestiscono stringhe bisogna sempre chiedersi quali caratteri permettono.

Con i nomi di file, anche se non esiste il problema del carattere ASCII n. 0, sono possibili caratteri "a capo" che, se in ultima posizione, verrebbero rimossi dall'espansione di comando. Il problema ovviamente non si pone per i file che seguono convenzioni note a priori, come i file di sistema (ma se lo script si occupa di controllare che non ci siano anomalie nei file di sistema, non può partire da questa assunzione!), o i file creati dallo script stesso, purché:

Per esempio, funzione che crea un file temporaneo e ne restituisce il nome:

# Crea un file regolare temporaneo con nome qualsiasi o scelto come argomento
# Numero argomenti: 0-1
# [ $1: nome del file ]
# Output: stringa contenente il nome del file creato (se è creato)
# Exit status: 
#  0 (successo) se il file è stato creato
#  1 se la creazione del file è fallita
#  2 se il file già esisteva
#  3 se il nome scelto non è valido (solo caratteri [a-zA-Z0-9.,_-])
crea_file_temporaneo () {
    local tmpfile
    if [ $# -eq 0 ]; then
        # mktemp segue convenzioni note a priori (senza argomenti)
        tmpfile=$(mktemp) ||
            return 1          # creazione fallita
    # posso scegliere regole meno stringenti, è solo un esempio...
    elif [ -z "${1##*[!a-zA-Z0-9.,_-]*}" ]; then
        return 3              # nome non valido
    # devo controllare che non esista nulla con quel nome per poterlo creare
    # non basterebbe controllare che non esiste un file regolare
    elif [ -e "$1" ]; then
        return 2              # file già esistente
    else
        tmpfile="/tmp/${1}"   # lo creo in /tmp
        touch -- "$tmpfile" ||
            return 1          # creazione fallita
    fi
    printf %s\\n "$tmpfile"   # stampo il nome del file creato, con percorso
    return 0                  # successo
}

La restituzione di un valore invece è più complessa se il nome del file o percorso da restituire non è:

Esempi più complessi con nomi di file arbitrari

I nomi di file possono contenere tutti i caratteri, tranne / e il carattere ASCII n. 0, mentre i percorsi non possono contenere il solo carattere ASCII n. 0. In questa sezione si presenteranno tre metodi per definire funzioni robuste in grado di gestire nomi di file e percorsi arbitrari da assegnare a una variabile, tra quelli già discussi brevemente.

#! /bin/bash

# Stampa il nome della directory parent in cui è contenuto un file
# Numero argomenti: 1
# $1 - file (permesso percorso relativo, assoluto o anche assente/implicito)
# Output: nome della directory parent (/ è considerata parent di sé stesso)
# Exit status: 0 solo se il file esiste
print_parent () {
    # variabili locali
    local file; local dir
    file=$1
    if ! [ -e "$file" ]; then
        return 1 # ritorna 1 se il file non esiste
    fi
    # dirname rimuove il nome del file dal percorso
    dir=$(dirname -- "$file" && printf %s X) # NOTA: aggiungo un carattere qualsiasi alla fine!
                                             # altrimenti eventuali "a capo" finali verrebbero rimossi
    dir=${dir%??}  # rimuovo gli ultimi *DUE* caratteri
                   # infatti va rimossa anche la nuova riga creata da dirname
                   # preservata aggiungendo X
    # readlink cerca il percorso assoluto e lo stampa sullo standard output
    readlink -e -- "$dir"  # determina l'exit status
}

if [ $# -ne 1 ]; then
    {
        printf %s\\n "Usage:"
        printf \\t%s\\n "$0 file"
    } >&2
    exit 1
fi

# assegno a una variabile, aggiungendo un carattere qualsiasi come delimitatore
# per impedire la rimozione di caratteri "a capo" finali (che sono possibili)
parent_dir=$(print_parent "$1" && printf %s X) || {
    # errore (la funzione ha restituito un exit status diverso da 0!)
    retval=$?
    printf %s\\n "ERRORE: file (\"$1\") non esistente!" >&2
    exit $retval
}
# rimuovo gli ultimi DUE caratteri (il delimitatore e il carattere "a capo" aggiunto dalla funzione)
parent_dir=${parent_dir%??}

printf %s\\n "Parent dir:"
printf %s\\n "$parent_dir"

exit 0

Per semplificare le cose è sempre bene che ogni funzione, così come fanno i comandi esterni, stampino sempre con un "a capo" finale, permettendo così di aggiungere un delimitatore e rimuovere gli ultimi due caratteri.

Si noti che sarebbe sbagliato scrivere nella funzione, o anche direttamente nel corpo principale dello script:

readlink -e -- "$(dirname -- "$file")" # SBAGLIATO!

L'espansione di comando con dirname non garantisce che i caratteri "a capo" finali siano preservati. Quando un comando qualsiasi (interno, funzione o comando esterno) restituisce un nome di file arbitrario, che non segue convenzioni note a priori (come i file di sistema), non può essere usato senza accorgimenti in un'espansione di comando.

#! /bin/bash

# Assegna a retval_parent la directory parent di un file
# Numero argomenti: 1
# $1 - file (permesso percorso relativo, assoluto o anche assente/implicito)
# Exit status: 0 solo se il file esiste
parent () {
    # variabili locali
    local file; local dir
    # variabile globale (perché non preceduta da local)
    retval_parent="" # inizializzata ogni volta
    # leggi argomenti
    file=$1
    # inizio funzione
    if ! [ -e "$file" ]; then
        return 1 # ritorna 1 se il file non esiste
    fi
    # dirname rimuove il nome del file dal percorso
    dir=$(dirname -- "$file" && printf %s X) # aggiungo un carattere qualsiasi alla fine!
                                             # altrimenti eventuali "a capo" finali verrebbero rimossi
    dir=${dir%??}  # rimuovo gli ultimi *DUE* caratteri
                   # infatti va rimossa anche la nuova riga creata da dirname
                   # preservata aggiungendo X
    # readlink cerca il percorso assoluto e lo stampa sullo standard output
    dir=$(readlink -e -- "$dir" && printf %s X) ||
          return $?     # in caso di errori restituisce quell'exit status
    dir=${dir%??}       # rimuovo gli ultimi due caratteri
    retval_parent=$dir  # assegno il risultato alla variabile globale
}

if [ $# -ne 1 ]; then
    {
        printf %s\\n "Usage:"
        printf \\t%s\\n "$0 file"
    } >&2
    exit 1
fi

# chiamo la funzione, *SENZA* usare l'espansione di comando
parent "$1" || {
    retval=$?
    printf %s\\n "ERRORE: file (\"$1\") non esistente!" >&2
    exit $retval
}
# assegno la variabile globale (è sempre bene farlo subito, così da poter richiamare parent)
parent_dir=$retval_parent

printf %s\\n "Parent dir:"
printf %s\\n "$parent_dir"

exit 0

In questo caso è necessario ricordarsi dei due caratteri finali da rimuovere unicamente all'interno della funzione stessa, e non a ogni chiamata. Lo svantaggio è nell'uso di una variabile globale per ogni funzione, per questo è bene usare una forma non ambigua, contenente il nome della funzione e un prefisso comune, usato solo per queste variabili.

Si noti che tutte le variabili sono globali, tranne quelle in una funzione definite con local. È bene però non usare mai altre variabili globali, se non sono costanti definite con readonly, all'interno di una funzione e ricorrere invece ai parametri, per rendere più semplice la comprensione del codice ed evitare modifiche accidentali con effetti a catena in più parti del codice. Inoltre va sempre considerato che una variabile non è globale, se è assegnata in una subshell: pertanto per esempio la funzione non può essere impiegata in una pipe con altri comandi, per leggerne l'output.

#! /bin/bash

# Stampa il nome della directory parent in cui è contenuto un file
# Numero argomenti: 1
# $1 - file (permesso percorso relativo, assoluto o anche assente/implicito)
# Output: nome della directory parent (/ è considerata parent di sé stesso)
# Exit status: 0 solo se il file esiste
print_parent () {
    local dir
    dir=$(dirname -- "$1") &&
    dir=$(readlink -e -- "$dir") &&
    printf %s\\n "$dir" ||
        return $?  # è implicito, ma aumenta la leggibilità del codice
}

if [ $# -ne 1 ]; then
    {
        printf %s\\n "Usage:"
        printf \\t%s\\n "$0 file"
    } >&2
    exit 1
fi
parent_dir=$(print_parent "$1") || {
    printf %s\\n "Percorso non esistente o contenente caratteri non validi!" >&2
    exit 1
}

printf %s\\n "Parent dir:"
printf %s\\n "$parent_dir"

exit 0

Quest'ultimo metodo è più veloce da scrivere, e anche più facile da leggere e capire. Si noti però che se esistessero multipli file con lo stesso nome, a parte per la presenza degli "a capo" finali, non verrebbe mai restituito errore con nessuno di loro, ma ogni volta che si specifica uno dei file con "a capo" si finirebbe per usare sempre il file senza "a capo" finali senza possibilità di accorgersene. E il controllo sugli argomenti non garantirebbe da quelli esistenti nel percorso reale restituito da readlink.

Può essere tollerabile o meno, e lo è nella maggior parte delle situazioni, ma dipende dallo scopo dello script. A ogni modo soltanto i metodi precedenti sono adatti a tutte le situazioni possibili.

Strumenti personali
Namespace
Varianti
Azioni
Navigazione
Risorse
Strumenti