CHECKPROC(8)

📦 version 3.14, in opensuse-leap 16.0

💅 CHECKPROC(8) — The SuSE boot concept, but make it make sense

okay so real talk, this is the CHECKPROC(8) page from the SuSE boot concept, and it's genuinely one of those tools that's lowkey iconic once you get what it's doing. Two programs live here: checkproc and pidofproc, and they're basically cousins.

✨ NAME ✨

  • Checkproc — checks for a process by full path name, bestie.
  • Pidofproc — checks for a process by exec base name instead.

🌸 SYNOPSIS 🌸

checkproc [-vLkNz] [-x] [-p pid_file] [-i ingnore_file] [-c root]
       /full/path/to/executable

checkproc -n [-vk] name_of_kernel_thread

checkproc    [-vk] [-x] basename_of_executable

pidofproc [-LkNz] [-x] [-p pid_file] [-i ingnore_file] [-c root]
       /full/path/to/executable

pidofproc -n [-k] name_of_kernel_thread

pidofproc    [-k] [-x] basename_of_executable

(yes, ingnore_file — that's literally how it's spelled in the synopsis, not me being chaotic 💀)

🧚 SYNOPSIS LSB 3.1

pidofproc [-p pid_file] /full/path/to/executable

💖 DESCRIPTION 💖

So checkproc goes looking for running processes that use the executable you pointed at. Slay.

Here's the thing though — checkproc does not use the pid to verify a process. It uses the full path of the corresponding program to identify the executable (see proc(5)). Very main character, very thorough. Only in these situations does it fall back:

  • if the inode number (/proc/<pid>/exe) and the full name are unavailable (/proc/<pid>/cmdline), or
  • if the executable changes its zeroth argument,

then checkproc uses the base name (/proc/<pid>/stat) to identify the running program. Ngl, that's the backup plan. And heads up: if you give the -n option for a kernel thread, only /proc/<pid>/stat gets used. In that case, an existing symbolic link (/proc/<pid>/exe) means the <pid> is not a kernel thread. Periodt.

Extended functionality comes from the -p pid_file option — that's the former -f option, changed due to the LSB specification, iykyk. If you specify it, checkproc tries to check the pid read from that file instead of the default /var/run/<basename>.pid. That pid read from the file gets compared against the pids of the processes using the specified binary. If you also throw in -k, checkproc works like killproc — meaning if the pid_file doesn't exist, checkproc assumes the daemon is not running. And yes, you can use a process identity number instead of a pid file. 💅

Now, for the situation where you've got two different sessions of one binary program — the -i ignore_file option lets you specify a pid file whose pid number is used to ignore all processes of the corresponding process session.

⚠️ okay so the behaviour above changes with -k. With this option, the pid read from the pid file is the only used pid (see killproc(8)), and with this option, exit codes like startproc(8) or killproc(8) are used too. Without -k, the pid read from the pid file is used to search the process table for a process with an executable that matches the specified pathname. And to avoid confusion with stale pid files, a not-up-to-date pid gets ignored (see startproc(8)). slay for not lying to us.

The -v option makes checkproc print out verbose messages — and the same happens if the pidofproc LSB variant is used. This version also accepts just the base name of an executable. Note that this disables the comparison of the inodes of the executable and the information found within the proc table (see proc(5)). 🫶

👑 REQUIRED 👑

  • /full/path/to/executable or name_of_kernel_thread — specifies the executable which processes should be found, or alternatively, if option -n is used, the name of the kernel thread. This argument is always required. No arguments, no vibe check, sorry bestie. 😭

💅 OPTIONS 💅

  • -k — makes checkproc work like killproc(8), which changes the operation mode, e.g. the exit status of the program will be that of killproc(8). Without this option, checkproc works like startproc(8) and finds all processes with an executable that matches the specified pathname, even if a given pid file (see option -p) isn't up-to-date. Nevertheless, it uses its own exit status (see the EXIT CODES section). 🔥
  • -L — causes symlinks to be followed, just like the like-named option in ls(1). Note: for the file name, the original name of the program is used instead of the name of the symbolic link. 🦋
  • -p pid_file — (former option -f, changed due to the LSB specification) use an alternate pid file instead of the default /var/run/<basename>.pid. If the option -k is specified and the pid_file does not exist, checkproc assumes that the daemon is not running. It is possible to use a process identity number instead of a pid file. ✨
  • -i ignore_file — the pid found in this file is used as the session id of the same binary program, which should be ignored by checkproc. 🙈
  • -c root — change root directory to root for services which have been started with this option by startproc(8). 🧚
  • -n — indicates that a kernel thread should be checked. In this case, you don't need the executable with its full path name — you need the name of the kernel thread instead. 🎀
  • -N — with this option, the location of the executable is checked for being on an NFS file system, and if true, the stat(2) system call is not applied on the exe symbolic link under /proc(5). Otherwise checkproc or pidofproc could be locked if the corresponding NFS server is currently not online or available. This implies that the inode number check between the executable on the command line and the executable of the exec symbolic link will be skipped. 🫶
  • -q — this option is ignored. literally nothing. it's giving decorative. 💀
  • -v — verbose output. 🗣️
  • -z — causes checkproc to see processes even if they're in the zombie state. Without this option, zombies are handled as not existent, because such a process isn't alive — it's just listed in the process table and waits on its parent process. 🧟‍♀️
  • -x — tells checkproc as well as pidofproc to use the up-to-15-byte-long filename name found in /proc/<pid>/stat, so it can identify scripts overwriting their command line. ⭐

🌈 EXAMPLE 🌈

checkproc /usr/sbin/sendmail

returns all pids of running sendmail processes. iconic.

checkproc -p /var/myrun/lpd.pid /usr/sbin/lpd

returns the command line or the basename of the process pid found in /var/run/lpd.pid.

🔥 EXIT CODES 🔥

without -k (LSB conform conditions, bestie)

      0    Program is running

      1    No process but pid file found

      3    No process and no pid file found

      4    Program is not installed

    101    Wrong syntax on command line

    102    Other errors

with -k (same energy as startproc(8) or killproc(8))

      0    Program is running

      1    Generic or unspecified error

      2    Invalid or excess argument(s)

      4    Insufficient privilege(s)

      5    Program is not installed

      7    Program is not running

in some cases a message is sent to standard error or, if no standard error is available, syslogd(8) is used. 📬

🍓 NOTE 🍓

checkproc together with the option -v just like pidof(8). The only difference is the usage of an available pid file. Only if no usable pid is given with a pid file, the process table will be scanned. 👑

💀 BUGS 💀

Identifying a process based on the executable file and the corresponding inode number only works if the process stays alive during startproc's execution. Processes rewriting their zeroth argument, or shell scripts (the inode number of the shell executable file is not identical to that of the script file), may not be identified by a filename path. sad but true. 😭

🦋 FILES 🦋

  • /proc/ — path to the proc file system (see proc(5)).
  • /etc/init.d/ — path to the SuSE boot concept script base directory as required by the Linux Standard Base Specification (LSB) (see init.d(7)).

🌸 SEE ALSO 🌸

startproc(8), killproc(8), insserv(8), init.d(7), kill(1), skill(1), killall(8), killall5(8), signal(7), proc(5).

1994-2005 Werner Fink, 1996-2005 SuSE GmbH Nuernberg, Germany.

🎀 AUTHOR 🎀

Werner Fink <werner@suse.de>

and that's the whole page, bestie — originally from the 3rd Berkeley Distribution, dated Nov 10, 2000, and signed CHECKPROC(8) at the bottom. go forth and check those procs 💖✨

📦 where this page comes from