Linux command exit codes

What are Exit Codes in Linux?

Unraveling the mystery of exit codes in Linux. Learn what are the exit codes and why and how they are used.

An exit code or exit status tells us about the status of the last executed command. Whether the command was completed successfully or ended with an error. This is obtained after the command terminates. The basic ideology is that programs return the exit code 0 to indicate that it executed successfully without issues. Code 1 or anything other than 0 is considered unsuccessful. There are many more exit codes other than 0 and 1, which I’ll cover in this article.

Various exit codes in Linux shell

Let us take a quick look at the prominent exit codes in the Linux shell:

Exit code	Meaning of the code
0	Command executed with no errors
1	Code for generic errors
2	Incorrect command (or argument) usage
126	Permission denied (or) unable to execute
127	Command not found, or PATH error
128+n	Command terminated externally by passing signals, or it encountered a fatal error
130	Termination by Ctrl+C or SIGINT (termination code 2 or keyboard interrupt)
143	Termination by SIGTERM (default termination)
255/*	Exit code exceeded the range 0-255, hence wrapped up

The termination signals like 130 (SIGINT or ^C ) and 143 (SIGTERM) are prominent, which are just 128+n signals with n standing for the termination code.

Retrieving the exit code

The exit code of the previously executed command is stored in the special variable $? . You can retrieve the exit status by running:

This will be used in all our demonstrations to retrieve the exit code. Note that the exit command supports carrying the same exit code of the previous command executed.

Exit code 0

Exit code 0 means that the command is executed without errors. This is ideally the best case for the completion of commands. For example, let us run a basic command like this

This exit code 0 means that the particular command was executed successfully, nothing more or less. Let us demonstrate some more examples. You may try killing a process; it will also return the code 0 .

Viewing a file’s contents will also return an exit code 0, which implies only that the ‘cat’ command executed successfully.

Exit code 1

Exit code 1 is also a common one. It generally means the command terminated with a generic error. For example, using the package manager without sudo permissions results in code 1. In Arch Linux, if I try this:

It will give me exist code as 1 meaning the last command resulted in error.

If you try this in Ubuntu-based distros ( apt update without sudo), you get 100 as an error code for running ‘apt’ without permissions. This is not a standardized error code, but one specific to apt.

While this is a general understanding, we can also interpret this as «operation impermissible». Operations like dividing by zero also result in code 1.

Exit code 2

This exit code is given out when the command executed has a syntax error. Misusing the arguments of commands also results in this error. It generally suggests that the command could not execute due to incorrect usage. For example, I added two hyphens to an option that’s supposed to have one hyphen. Code 2 was given out.

When permission is denied, like accessing the /root folder, you get error code 2.

Exit code 126

126 is a peculiar exit code since it is used to indicate a command or script was not executed due to a permission error. This error can be found when you try executing a shell script without giving execution permissions. Note that this exit code appears only for the ‘execution‘ of scripts/commands without sufficient permissions, which is different from a generic Permission Denied error. So, on’t confuse it with the previous example you saw with exit code 2. There, ls command ran and the permission issue came with the directory it was trying to execute. Here, the permission issues came from the script itself.

Exit code 127

This is another common one. Exit code 127 refers to «command not found». It usually occurs when there’s a typo in the command executed or the required executable is not in the $PATH variable. For example, I often see this error when I try executing a script without its path. Or when the executable file you’re trying to run, is not listed in the $PATH variable. You can rectify this by adding the parent directory to the PATH variable. You’ll also get this exit code when you type commands that do not exist.

Exit code series 128+n

When an application or command is terminated or its execution fails due to a fatal error, the adjacent code to 128 is produced (128+n), where n is the signal number. This includes all types of termination codes, like SIGTERM , SIGKILL , etc that apply to the value ‘n’ here.

Code 130 or SIGINT

SIGINT or Signal for Keyboard Interrupt is induced by interrupting the process by termination signal 2, or by Ctrl+C. Since the termination signal is 2, we get a code 130 (128+2). Here’s a video demonstrating the interrupt signal for lxappearance .

Note that these signals may not appear if terminated from the same session from which the process was started. If you’re reproducing these, terminate from a different shell.

On a personal note, signal 128 was impossible to reproduce.

What if the code exceeds 255?

Recent versions of Bash retain the original exit code value even beyond 255, but generally, if the code exceeds 255, then it is wrapped up. That is, code 256 becomes ‘0’, 257 becomes ‘1’, 383 becomes ‘127’, and so on and so forth. To ensure better compatibility, keep the exit codes between 0 and 255.

Wrapping up

I hope you learned something about the exit codes in the Linux shell. Using them can come in handy for troubleshooting various issues. If you are using these codes in a shell script, make sure you understand the meaning of each code in order to make it easier for troubleshooting. In case you need a reference, check out the Bash series here: That’s all about the article. Feel free to let me know in the comments section if I have missed anything.

Источник

Как использовать коды завершения в Bash-скриптах

Инструменты автоматизации и мониторинга удобны тем, что разработчик может взять готовые скрипты, при необходимости адаптировать и использовать в своём проекте. Можно заметить, что в некоторых скриптах используются коды завершения (exit codes), а в других нет. О коде завершения легко забыть, но это очень полезный инструмент. Особенно важно использовать его в скриптах командной строки.

Что такое коды завершения

В Linux и других Unix-подобных операционных системах программы во время завершения могут передавать значение родительскому процессу. Это значение называется кодом завершения или состоянием завершения. В POSIX по соглашению действует стандарт: программа передаёт 0 при успешном исполнении и 1 или большее число при неудачном исполнении.

Почему это важно? Если смотреть на коды завершения в контексте скриптов для командной строки, ответ очевиден. Любой полезный Bash-скрипт неизбежно будет использоваться в других скриптах или его обернут в однострочник Bash. Это особенно актуально при использовании инструментов автоматизации типа SaltStack или инструментов мониторинга типа Nagios. Эти программы исполняют скрипт и проверяют статус завершения, чтобы определить, было ли исполнение успешным.

Кроме того, даже если вы не определяете коды завершения, они всё равно есть в ваших скриптах. Но без корректного определения кодов выхода можно столкнуться с проблемами: ложными сообщениями об успешном исполнении, которые могут повлиять на работу скрипта.

Что происходит, когда коды завершения не определены

В Linux любой код, запущенный в командной строке, имеет код завершения. Если код завершения не определён, Bash-скрипты используют код выхода последней запущенной команды. Чтобы лучше понять суть, обратите внимание на пример.

#!/bin/bash touch /root/test echo created file 

Этот скрипт запускает команды touch и echo . Если запустить этот скрипт без прав суперпользователя, команда touch не выполнится. В этот момент мы хотели бы получить информацию об ошибке с помощью соответствующего кода завершения. Чтобы проверить код выхода, достаточно ввести в командную строку специальную переменную $? . Она печатает код возврата последней запущенной команды.

Как видно, после запуска команды ./tmp.sh получаем код завершения 0 . Этот код говорит об успешном выполнении команды, хотя на самом деле команда не выполнилась. Скрипт из примера выше исполняет две команды: touch и echo . Поскольку код завершения не определён, получаем код выхода последней запущенной команды. Это команда echo , которая успешно выполнилась.

Если убрать из скрипта команду echo , можно получить код завершения команды touch .

Поскольку touch в данном случае — последняя запущенная команда, и она не выполнилась, получаем код возврата 1 .

Как использовать коды завершения в Bash-скриптах

Удаление из скрипта команды echo позволило нам получить код завершения. Что делать, если нужно сделать разные действия в случае успешного и неуспешного выполнения команды touch ? Речь идёт о печати stdout в случае успеха и stderr в случае неуспеха.

Проверяем коды завершения

Выше мы пользовались специальной переменной $? , чтобы получить код завершения скрипта. Также с помощью этой переменной можно проверить, выполнилась ли команда touch успешно.

#!/bin/bash touch /root/test 2> /dev/null if [ $? -eq 0 ] then echo "Successfully created file" else echo "Could not create file" >&2 fi 

После рефакторинга скрипта получаем такое поведение:

• Если команда touch выполняется с кодом 0 , скрипт с помощью echo сообщает об успешно созданном файле.
• Если команда touch выполняется с другим кодом, скрипт сообщает, что не смог создать файл.

Любой код завершения кроме 0 значит неудачную попытку создать файл. Скрипт с помощью echo отправляет сообщение о неудаче в stderr .

Создаём собственный код завершения

Наш скрипт уже сообщает об ошибке, если команда touch выполняется с ошибкой. Но в случае успешного выполнения команды мы всё также получаем код 0 .

Поскольку скрипт завершился с ошибкой, было бы не очень хорошей идеей передавать код успешного завершения в другую программу, которая использует этот скрипт. Чтобы добавить собственный код завершения, можно воспользоваться командой exit .

#!/bin/bash touch /root/test 2> /dev/null if [ $? -eq 0 ] then echo "Successfully created file" exit 0 else echo "Could not create file" >&2 exit 1 fi 

Теперь в случае успешного выполнения команды touch скрипт с помощью echo сообщает об успехе и завершается с кодом 0 . В противном случае скрипт печатает сообщение об ошибке при попытке создать файл и завершается с кодом 1 .

Как использовать коды завершения в командной строке

Скрипт уже умеет сообщать пользователям и программам об успешном или неуспешном выполнении. Теперь его можно использовать с другими инструментами администрирования или однострочниками командной строки.

В примере выше && используется для обозначения «и», а || для обозначения «или». В данном случае команда выполняет скрипт ./tmp.sh , а затем выполняет echo «bam» , если код завершения 0 . Если код завершения 1 , выполняется следующая команда в круглых скобках. Как видно, в скобках для группировки команд снова используются && и || .

Скрипт использует коды завершения, чтобы понять, была ли команда успешно выполнена. Если коды завершения используются некорректно, пользователь скрипта может получить неожиданные результаты при неудачном выполнении команды.

Дополнительные коды завершения

Команда exit принимает числа от 0 до 255 . В большинстве случаев можно обойтись кодами 0 и 1 . Однако есть зарезервированные коды, которые обозначают конкретные ошибки. Список зарезервированных кодов можно посмотреть в документации.

Адаптированный перевод статьи Understanding Exit Codes and how to use them in bash scripts by Benjamin Cane. Мнение администрации Хекслета может не совпадать с мнением автора оригинальной публикации.

Источник