Devolver resultados de una función

1. Dos clases de resultado

Cuando una función termina, puede tener que comunicar dos cosas distintas, y Bash tiene un canal para cada una:

Confundir los dos canales es el origen de la mayoría de los errores con funciones en Bash. La regla general: el código de salida es para el éxito o el fracaso; los datos van por otro lado.

2. return: el estado

return termina la función y fija su código de salida, como exit lo hace para el script. Sin return, la función termina al llegar al final, con el código de su último comando.

El valor está sujeto a los mismos límites que vimos en el tema 10: entre 0 y 255, tomado módulo 256. Por eso return no sirve para devolver datos numéricos:

$ tamano() { return 300; }
$ tamano; echo $?
44

Y aunque el número entrara en el rango, devolverlo por el código de salida sería un error de diseño: 0 significaría «éxito» para if y para set -e, y cualquier otro valor, un fallo. Una función que «devuelve» un tamaño de 0 bytes con return 0 y uno de 5 con return 5 estaría diciendo que el segundo falló.

3. Funciones que responden sí o no

El uso natural de return es el de las funciones que funcionan como preguntas, cuyo resultado se usa directamente en un if. A menudo ni siquiera necesitan return: basta con que la última línea sea la prueba, y su código pasa a ser el de la función.

# es_entero TEXTO — éxito si TEXTO es un número entero no negativo.
es_entero() {
  [[ "$1" =~ ^[0-9]+$ ]]
}

# existe_usuario NOMBRE — éxito si el usuario existe en el sistema.
existe_usuario() {
  id -u "$1" > /dev/null 2>&1
}

# en_horario_laboral — éxito de lunes a viernes, de 9 a 18.
en_horario_laboral() {
  local dia hora
  dia=$(date +%u)
  hora=$(date +%-H)
  (( dia <= 5 && hora >= 9 && hora < 18 ))
}

if es_entero "$dias" && existe_usuario "$usuario"; then …
en_horario_laboral || { echo "Fuera de horario: no se despliega" >&2; exit 0; }

Cuando la función tiene varios pasos, return permite salir antes con la respuesta, del mismo modo que las cláusulas de guarda del tema 12:

# respaldo_valido ARCHIVO — éxito si el archivo existe, no está vacío y tar puede leerlo.
respaldo_valido() {
  local archivo="$1"
  [[ -s "$archivo" ]] || return 1
  tar -tzf "$archivo" > /dev/null 2>&1 || return 1
  return 0
}

4. Datos por la salida: echo y $( )

La forma más común de devolver un dato es que la función lo escriba en su salida estándar, y que quien la llama lo capture con una sustitución de comandos, como haría con la salida de cualquier programa:

# extension ARCHIVO — escribe la extensión en minúsculas, o nada si no tiene.
extension() {
  local nombre="${1##*/}"
  [[ "$nombre" == ?*.* ]] || return 0
  local ext="${nombre##*.}"
  printf '%s\n' "${ext,,}"
}

ext=$(extension "/fotos/Playa.JPG")      # ext vale «jpg»

Es el mecanismo más natural en Bash, porque es el mismo que usan todos los comandos, y tiene ventajas reales: la función puede usarse en una tubería (extension "$f" | tr a-z A-Z), en una redirección o directamente en la terminal, y no necesita ninguna variable compartida. Su costo es que $( ) ejecuta la función en una subshell, un proceso aparte, con dos consecuencias que explican las dos secciones siguientes.

Para escribir el resultado se prefiere printf '%s\n' a echo, por la razón que vimos en el tema 4: con echo, un valor como -n se interpretaría como opción.

5. Los mensajes, a la salida de errores

Si la salida estándar es el canal de los datos, cualquier otra cosa que la función escriba allí se mezcla con el resultado. Un mensaje de progreso, inofensivo cuando se llama a la función directamente, contamina el valor capturado:

$ calcular() { echo "Calculando..."; echo 42; }
$ resultado=$(calcular); declare -p resultado
declare -- resultado=$'Calculando...\n42'
$ calcular() { echo "Calculando..." >&2; echo 42; }
$ resultado=$(calcular); declare -p resultado
Calculando...
declare -- resultado="42"

Con el mensaje en la salida de errores, el usuario lo sigue viendo en pantalla, pero la variable recibe solo el dato. Es la misma regla que venimos aplicando a los scripts, ahora en pequeño: en una función que devuelve datos por la salida, todo lo que no sea el dato va a >&2, y los comandos que escriben cosas que no interesan se silencian con > /dev/null.

6. Lo que se pierde dentro de $( )

La segunda consecuencia de la subshell es que los cambios que la función haga en variables globales no sobreviven. Es el mismo fenómeno que vimos con las tuberías en el tema 16:

$ contador=0
$ siguiente() { contador=$(( contador + 1 )); echo "$contador"; }
$ n=$(siguiente); echo "n=$n contador=$contador"
n=1 contador=0
$ siguiente > /dev/null; echo "contador=$contador"      # sin $( ): en la shell actual
contador=1

El dato se devolvió bien, pero el contador global no avanzó, porque se incrementó en la copia de la subshell. Una función pensada para usarse con $( ) no debe depender de modificar variables globales. Si necesita hacerlo, hay que usar uno de los mecanismos de las secciones 8 a 10.

La subshell tiene además un costo: crear un proceso por cada llamada. En una llamada suelta no importa; dentro de un bucle de miles de vueltas, sí, como vimos con basename en el tema 6.

7. Estado y datos a la vez

Una función puede devolver un dato por la salida y, a la vez, indicar con su código si lo consiguió. Como vimos en el tema 5, una asignación con $( ) toma el código de la función, y eso permite capturar y comprobar en la misma línea:

# ip_de HOST — escribe la primera dirección IP del host; falla si no se resuelve.
ip_de() {
  local ip
  ip=$(getent hosts "$1" | awk '{ print $1; exit }')
  [[ -n "$ip" ]] || return 1
  printf '%s\n' "$ip"
}

if ip=$(ip_de servidor.example.com); then
  echo "La dirección es $ip"
else
  echo "No se pudo resolver el nombre" >&2
fi

Aquí vuelve la advertencia del tema 18: si la variable que recibe el dato se declara con local en la misma línea, se pierde el código. Dentro de una función, se escribe local ip y, en la línea siguiente, if ip=$(ip_de …); then.

8. Una variable global como resultado

La alternativa más simple a la subshell es que la función deje el resultado en una variable global acordada. Es rápida, porque no crea procesos, y permite devolver varios valores o modificar el estado del script:

# medir_disco DIRECTORIO — deja en DISCO_USO y DISCO_LIBRE el porcentaje usado y los MB libres.
medir_disco() {
  local linea
  linea=$(df -BM --output=pcent,avail -- "$1" | tail -1)
  read -r DISCO_USO DISCO_LIBRE <<< "${linea//[%M]/}"
}

medir_disco /var
echo "Uso: $DISCO_USO %, libres: $DISCO_LIBRE MB"

El inconveniente es el de todas las variables globales: la función y quien la llama deben conocer el nombre, y cualquier otra parte del script puede pisarlo. Si se usa este mecanismo, conviene que los nombres sean inequívocos, por ejemplo con el nombre de la función como prefijo, como DISCO_USO, y documentarlo en el comentario de la función.

9. Referencias: declare -n

Bash ofrece una forma más limpia: que quien llama elija el nombre de la variable donde quiere el resultado, y se lo pase a la función como argumento. Dentro de la función, local -n (o declare -n) crea una referencia (nameref): una variable que es otro nombre para la variable indicada. Todo lo que se asigna a la referencia se asigna a la variable original.

$ obtener_fecha() { local -n _destino="$1"; _destino=$(date +%F); }
$ obtener_fecha hoy
$ echo "$hoy"
2026-10-14

La función no necesita conocer el nombre hoy: lo recibe. Y como no hay subshell, la asignación queda en la variable del llamador. Las referencias funcionan también con arrays, lo que las convierte en la forma más directa de devolver una lista:

# registros_viejos DIRECTORIO DIAS ARRAY — llena ARRAY con los .log de más de DIAS días.
registros_viejos() {
  local dir="$1" dias="$2"
  local -n _lista="$3"
  mapfile -t _lista < <(find "$dir" -name '*.log' -mtime +"$dias")
}

registros_viejos /var/log/app 30 viejos
echo "Hay ${#viejos[@]} registros para comprimir"

10. printf -v

Para el caso frecuente de dar formato a un valor y guardarlo, printf tiene una opción que escribe el resultado en una variable en lugar de en la salida, sin subshell:

printf -v nombre 'respaldo-%s-%03d.tar.gz' "$equipo" "$numero"   # respaldo-web01-007.tar.gz
printf -v hoy '%(%Y-%m-%d)T' -1                                  # la fecha, sin llamar a date

El formato %(…)T da formato a una fecha con los mismos códigos que date; el argumento -1 significa «ahora». Dentro de una función, printf -v combinado con una referencia, printf -v "$1" …, es otra forma de devolver un texto formateado en la variable que elija el llamador.

11. Devolver una lista

Una función no puede devolver un array por la salida, porque la salida es texto. Hay dos formas de devolver una lista:

listar_respaldos() {
  find "$1" -maxdepth 1 -name '*.tar.gz' -print0 | sort -z
}

mapfile -d '' -t respaldos < <(listar_respaldos /respaldos)
echo "Hay ${#respaldos[@]} respaldos; el más reciente es ${respaldos[-1]}"

La versión por la salida tiene la ventaja de que la función también sirve en una tubería, por ejemplo listar_respaldos /respaldos | xargs -0 ls -l, y de que puede escribirse en cualquier lenguaje si algún día se convierte en un programa aparte.

12. Cuál usar

13. Un script completo

Este script muestra, para cada directorio que recibe, cuánto ocupa y cuántos archivos contiene, en unidades legibles, y el total al final. Usa los tres mecanismos del tema: una función que responde sí o no, una que devuelve un texto por la salida, y una que llena dos variables del llamador por referencia.

#!/usr/bin/env bash
#
# uso-directorios — cuánto ocupa cada directorio y cuántos archivos contiene.
#
# Uso:    uso-directorios DIRECTORIO...
# Salida: 0 si se midieron todos; 1 si alguno no se pudo leer; 2 sin argumentos.
#
set -euo pipefail

# es_directorio_legible DIR — estado: éxito si DIR es un directorio que se puede recorrer.
es_directorio_legible() {
  [[ -d "$1" && -r "$1" && -x "$1" ]]
}

# a_legible BYTES — dato por la salida: «1.5 KiB», «2.7 MiB»…
a_legible() {
  local bytes="$1"
  local -a unidades=(B KiB MiB GiB TiB)
  local i=0 decimas=$(( bytes * 10 ))
  while (( decimas >= 10240 && i < ${#unidades[@]} - 1 )); do
    decimas=$(( decimas / 1024 ))
    i=$(( i + 1 ))
  done
  if (( i == 0 )); then
    printf '%d B\n' "$bytes"
  else
    printf '%d.%d %s\n' $(( decimas / 10 )) $(( decimas % 10 )) "${unidades[i]}"
  fi
}

# medir DIR VAR_BYTES VAR_ARCHIVOS — datos por referencia: tamaño y cantidad de archivos.
medir() {
  local dir="$1"
  local -n _bytes="$2" _archivos="$3"
  _bytes=$(du -sb -- "$dir" | cut -f1)
  _archivos=$(find "$dir" -type f | wc -l)
}

main() {
  if (( $# == 0 )); then
    echo "Uso: ${0##*/} DIRECTORIO..." >&2
    exit 2
  fi

  local dir bytes archivos total=0 errores=0
  for dir in "$@"; do
    if ! es_directorio_legible "$dir"; then
      echo "${0##*/}: no es un directorio legible: $dir" >&2
      errores=$(( errores + 1 ))
      continue
    fi
    medir "$dir" bytes archivos
    total=$(( total + bytes ))
    printf '%10s  %6d archivos  %s\n' "$(a_legible "$bytes")" "$archivos" "$dir"
  done
  printf '%10s  en total\n' "$(a_legible "$total")"

  (( errores == 0 ))
}

main "$@"

$ uso-directorios ~/documentos ~/fotos ~/no-existe; echo "código $?"
  48.3 MiB     412 archivos  /home/ana/documentos
   1.2 GiB    2210 archivos  /home/ana/fotos
uso-directorios: no es un directorio legible: /home/ana/no-existe
   1.2 GiB  en total
código 1

• es_directorio_legible devuelve solo un estado, y se usa con if !. Su única línea es la prueba, y su código es el de la función.
• a_legible devuelve un texto por la salida, y se usa con $( ) directamente como argumento de printf. Trabaja en décimas para conservar un decimal con aritmética entera, la técnica del tema 7, y como no escribe nada más, la captura recibe solo el dato.
• medir devuelve dos valores a la vez, cosa que la salida no permite con comodidad, y lo hace por referencia: main le pasa los nombres bytes y archivos, y la función los llena. Sus referencias llevan guion bajo para no chocar con esas variables, que justamente se llaman casi igual.
• main devuelve el estado del script con su última línea, como en los temas anteriores.

14. Errores frecuentes

15. Resumen

• Una función puede devolver un estado, por su código de salida, o datos, por otro canal. No hay que mezclarlos.
• return n termina la función con el código n, entre 0 y 255; no sirve para devolver datos.
• Las funciones-pregunta terminan con una prueba, y se usan directamente en if, && y ||.
• Un dato se devuelve escribiéndolo con printf y se recibe con var=$(función).
• En esas funciones, todo lo que no sea el dato va a la salida de errores.
• $( ) ejecuta la función en una subshell: los cambios en variables globales se pierden, y cada llamada crea un proceso.
• if x=$(f); then recibe el dato y comprueba el estado a la vez.
• Una variable global acordada es rápida, pero acopla la función con el resto del script.
• local -n ref="$1" crea una referencia a la variable que elige el llamador; sirve para textos, varios valores y arrays.
• printf -v var formato … guarda un texto formateado sin subshell; %(…)T da formato a fechas.
• Una lista se devuelve por referencia, o por la salida, línea por línea o separada por nulos, para leerla con mapfile.

16. Preguntas de repaso

Intenta responder cada una antes de abrir la respuesta.

Para practicar

1. Escribe es_par, es_entero y es_archivo_vacio como funciones-pregunta y úsalas en condiciones.
2. Escribe una función sin_extension que devuelva por la salida un nombre de archivo sin su extensión, y úsala en un bucle sobre *.txt.
3. Reproduce el problema del contador dentro de $( ), y resuélvelo con una referencia.
4. Escribe una función dividir que reciba dos números y los nombres de dos variables, y deje en ellas el cociente y el resto.
5. Escribe una función que llene, por referencia, un array con los usuarios del sistema con UID mayor o igual que 1000.
6. Mide con time la diferencia entre llamar diez mil veces a una función con $( ) y con printf -v o una referencia.
7. Prueba uso-directorios con varios directorios, y agrega una columna con el tamaño medio por archivo, usando a_legible.