Linux fail return code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Теперь в случае успешного выполнения команды 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. Мнение администрации Хекслета может не совпадать с мнением автора оригинальной публикации.

Источник

How do I get the list of exit codes (and/or return codes) and meaning for a command/utility?

Is there a way I can do what stated in the title from the terminal commands, or will I have to look into the codes?

4 Answers 4

There is no «recipe» to get the meanings of an exit status of a given terminal command.

My first attempt would be the manpage:

Second: Google. See wget as an example.

Third: The exit statuses of the shell, for example bash. Bash and it’s builtins may use values above 125 specially. 127 for command not found, 126 for command not executable. For more information see the bash exit codes.

Exit codes indicates a failure condition when ending a program and they fall between 0 and 255. The shell and its builtins may use especially the values above 125 to indicate specific failure modes, so list of codes can vary between shells and operating systems (e.g. Bash uses the value 128+N as the exit status). See: Bash — 3.7.5 Exit Status or man bash .

In general a zero exit status indicates that a command succeeded, a non-zero exit status indicates failure.

To check which error code is returned by the command, you can print $? for the last exit code or $ which gives a list of exit status values from pipeline (in Bash) after a shell script exits.

There is no full list of all exit codes which can be found, however there has been an attempt to systematize exit status numbers in kernel source, but this is main intended for C/C++ programmers and similar standard for scripting might be appropriate.

Some list of sysexits on both Linux and BSD/OS X with preferable exit codes for programs (64-78) can be found in /usr/include/sysexits.h (or: man sysexits on BSD):

The above list allocates previously unused exit codes from 64-78. The range of unallotted exit codes will be further restricted in the future.

However above values are mainly used in sendmail and used by pretty much nobody else, so they aren’t anything remotely close to a standard (as pointed by @Gilles).

In shell the exit status are as follow (based on Bash):

1 — 125 — Command did not complete successfully. Check the command’s man page for the meaning of the status, few examples below:

1 — Catchall for general errors

Miscellaneous errors, such as «divide by zero» and other impermissible operations.

2 — Misuse of shell builtins (according to Bash documentation)

Missing keyword or command, or permission problem (and diff return code on a failed binary file comparison).

6 — No such device or address

124 — command times out

126 — if command is found but cannot be invoked (e.g. is not executable)

Permission problem or command is not an executable.

127 — if a command cannot be found, the child process created to execute it returns that status

Possible problem with $PATH or a typo.

128 — Invalid argument to exit

exit takes only integer args in the range 0 — 255.

128 — 254 — fatal error signal «n» — command died due to receiving a signal. The signal code is added to 128 (128 + SIGNAL) to get the status (Linux: man 7 signal , BSD: man signal ), few examples below:

130 — command terminated due to Ctrl-C being pressed, 130-128=2 (SIGINT)

137 — if command is sent the KILL(9) signal (128+9), the exit status of command otherwise

141 — SIGPIPE — write on a pipe with no reader

143 — command terminated by signal code 15 (128+15=143)

255 * — exit status out of range.

exit takes only integer args in the range 0 — 255.

According to the above table, exit codes 1 — 2, 126 — 165, and 255 have special meanings, and should therefore be avoided for user-specified exit parameters.

Источник

How can I negate the return-value of a process?

I’m looking for a simple, but cross-platform negate-process that negates the value a process returns. It should map 0 to some value != 0 and any value != 0 to 0, i.e. the following command should return «yes, nonexistingpath doesn’t exist»:

The ! — operator is great but unfortunately not shell-independent.

7 Answers 7

Previously, the answer was presented with what’s now the first section as the last section.

POSIX Shell includes a ! operator

Poking around the shell specification for other issues, I recently (September 2015) noticed that the POSIX shell supports a ! operator. For example, it is listed as a reserved word and can appear at the start of a pipeline — where a simple command is a special case of ‘pipeline’. It can, therefore, be used in if statements and while or until loops too — in POSIX-compliant shells. Consequently, despite my reservations, it is probably more widely available than I realized back in 2008. A quick check of POSIX 2004 and SUS/POSIX 1997 shows that ! was present in both those versions.

Note that the ! operator must appear at the beginning of the pipeline and negates the status code of the entire pipeline (i.e. the last command). Here are some examples.

Portable answer — works with antique shells

In a Bourne (Korn, POSIX, Bash) script, I use:

This is as portable as it gets. The ‘command and arguments’ can be a pipeline or other compound sequence of commands.

A not command

The ‘!’ operator, whether built-in to your shell or provided by the o/s, is not universally available. It isn’t dreadfully hard to write, though — the code below dates back to at least 1991 (though I think I wrote a previous version even longer ago). I don’t tend to use this in my scripts, though, because it is not reliably available.

Источник

Are there any standard exit status codes in Linux?

A process is considered to have completed correctly in Linux if its exit status was 0.

I’ve seen that segmentation faults often result in an exit status of 11, though I don’t know if this is simply the convention where I work (the apps that failed like that have all been internal) or a standard.

Are there standard exit codes for processes in Linux?

10 Answers 10

Part 1: Advanced Bash Scripting Guide

As always, the Advanced Bash Scripting Guide has great information: (This was linked in another answer, but to a non-canonical URL.)

1: Catchall for general errors
2: Misuse of shell builtins (according to Bash documentation)
126: Command invoked cannot execute
127: «command not found»
128: Invalid argument to exit
128+n: Fatal error signal «n»
255: Exit status out of range (exit takes only integer args in the range 0 — 255)

Part 2: sysexits.h

The ABSG references sysexits.h .

8 bits of the return code and 8 bits of the number of the killing signal are mixed into a single value on the return from wait(2) & co..

How are you determining the exit status? Traditionally, the shell only stores an 8-bit return code, but sets the high bit if the process was abnormally terminated.

If you’re seeing anything other than this, then the program probably has a SIGSEGV signal handler which then calls exit normally, so it isn’t actually getting killed by the signal. (Programs can chose to handle any signals aside from SIGKILL and SIGSTOP .)

‘1’ >>> Catchall for general errors

‘2’ >>> Misuse of shell builtins (according to Bash documentation)

‘126’>>> Command invoked cannot execute

‘127’>>>»command not found»

‘128’>>> Invalid argument to exit

‘128+n’>>>Fatal error signal «n»

‘130’>>> Script terminated by Control-C

‘255’>>>Exit status out of range

This is for bash. However, for other applications, there are different exit codes.

None of the older answers describe exit status 2 correctly. Contrary to what they claim, status 2 is what your command line utilities actually return when called improperly. (Yes, an answer can be nine years old, have hundreds of upvotes, and still be wrong.)

Here is the real, long-standing exit status convention for normal termination, i.e. not by signal:

• Exit status 0: success
• Exit status 1: «failure», as defined by the program
• Exit status 2: command line usage error

For example, diff returns 0 if the files it compares are identical, and 1 if they differ. By long-standing convention, unix programs return exit status 2 when called incorrectly (unknown options, wrong number of arguments, etc.) For example, diff -N , grep -Y or diff a b c will all result in $? being set to 2. This is and has been the practice since the early days of Unix in the 1970s.

The accepted answer explains what happens when a command is terminated by a signal. In brief, termination due to an uncaught signal results in exit status 128+[ . E.g., termination by SIGINT (signal 2) results in exit status 130.

Notes

Several answers define exit status 2 as «Misuse of bash builtins». This applies only when bash (or a bash script) exits with status 2. Consider it a special case of incorrect usage error.

In sysexits.h , mentioned in the most popular answer, exit status EX_USAGE («command line usage error») is defined to be 64. But this does not reflect reality: I am not aware of any common Unix utility that returns 64 on incorrect invocation (examples welcome). Careful reading of the source code reveals that sysexits.h is aspirational, rather than a reflection of true usage:

In other words, these definitions do not reflect the common practice at the time (1993) but were intentionally incompatible with it. More’s the pity.

There are no standard exit codes, aside from 0 meaning success. Non-zero doesn’t necessarily mean failure either.

stdlib.h does define EXIT_FAILURE as 1 and EXIT_SUCCESS as 0, but that’s about it.

The 11 on segfault is interesting, as 11 is the signal number that the kernel uses to kill the process in the event of a segfault. There is likely some mechanism, either in the kernel or in the shell, that translates that into the exit code.

sysexits.h has a list of standard exit codes. It seems to date back to at least 1993 and some big projects like Postfix use it, so I imagine it’s the way to go.

From the OpenBSD man page:

According to style(9), it is not good practice to call exit(3) with arbi- trary values to indicate a failure condition when ending a program. In- stead, the pre-defined exit codes from sysexits should be used, so the caller of the process can get a rough estimation about the failure class without looking up the source code.

To a first approximation, 0 is success, non-zero is failure, with 1 being general failure, and anything larger than one being a specific failure. Aside from the trivial exceptions of false and test, which are both designed to give 1 for success, there’s a few other exceptions I found.

More realistically, 0 means success or maybe failure, 1 means general failure or maybe success, 2 means general failure if 1 and 0 are both used for success, but maybe sucess as well.

The diff command gives 0 if files compared are identical, 1 if they differ, and 2 if binaries are different. 2 also means failure. The less command gives 1 for failure unless you fail to supply an argument, in which case, it exits 0 despite failing.

The more command and the spell command give 1 for failure, unless the failure is a result of permission denied, nonexistent file, or attempt to read a directory. In any of these cases, they exit 0 despite failing.

Then the expr command gives 1 for success unless the output is the empty string or zero, in which case, 0 is success. 2 and 3 are failure.

Then there’s cases where success or failure is ambiguous. When grep fails to find a pattern, it exits 1, but it exits 2 for a genuine failure (like permission denied). Klist also exits 1 when it fails to find a ticket, although this isn’t really any more of a failure than when grep doesn’t find a pattern, or when you ls an empty directory.

So, unfortunately, the unix powers that be don’t seem to enforce any logical set of rules, even on very commonly used executables.

Источник