diff options
Diffstat (limited to 'doc/fuser.1')
-rw-r--r-- | doc/fuser.1 | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/doc/fuser.1 b/doc/fuser.1 new file mode 100644 index 0000000..37191c0 --- /dev/null +++ b/doc/fuser.1 @@ -0,0 +1,310 @@ +.\" +.\" Copyright 1993-2005 Werner Almesberger +.\" 2005-2023 Craig Small +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.TH FUSER 1 "2022-11-02" "psmisc" "User Commands" +.SH NAME +fuser \- identify processes using files or sockets +.SH SYNOPSIS +.ad l +.B fuser +.RB [ \-fuv ] +.RB [ \-a | \-s ] +.RB [ \-4 | \-6 ] +.RB [ \-c | \-m | \-n +.IR space ] +.RB [ \ \-k +.RB [ \-i ] +.RB [ \-M ] +.RB [ \-w ] +.RB [ \-\c +.IR SIGNAL ] +] +.IR name " ..." +.br +.B fuser \-l +.br +.B fuser \-V +.ad b +.SH DESCRIPTION +.B fuser +displays the PIDs of processes using the specified files or file +systems. In the default display mode, each file name is followed by a +letter denoting the type of access: +.PP +.RS +.PD 0 +.TP +.B c +current directory. +.TP +.B e +executable being run. +.TP +.B f +open file. +.B f +is omitted in default display mode. +.TP +.B F +open file for writing. +.B F +is omitted in default display mode. +.TP +.B r +root directory. +.TP +.B m +mmap'ed file or shared library. +.TP +.B . +Placeholder, omitted in default display mode. +.PD +.RE +.LP +.B fuser +returns a non-zero return code if none of the specified files is +accessed or in case of a fatal error. If at least one access has been +found, +.B fuser +returns zero. +.PP +In order to look up processes using TCP and UDP sockets, the +corresponding name space has to be selected with the +.B \-n +option. By default +.B fuser +will look in both IPv6 and IPv4 sockets. To change the default +behavior, use the +.B \-4 +and +.B \-6 +options. The socket(s) can be specified by the local and remote port, +and the remote address. All fields are optional, but commas in front +of missing fields must be present: +.PP +.RI [ lcl_port ][,[ rmt_host ][,[ rmt_port ]]] +.PP +Either symbolic or numeric values can be used for IP addresses and port +numbers. +.PP +.B fuser +outputs only the PIDs to stdout, everything else is sent to stderr. +.SH OPTIONS +.TP +.BR \-a ", " \-\-all +Show all files specified on the command line. By default, only files +that are accessed by at least one process are shown. +.TP +.B \-c +Same as \fB\-m\fR option, used for POSIX compatibility. +.TP +.B \-f +Silently ignored, used for POSIX compatibility. +.TP +.BR \-k ", "\-\-kill +Kill processes accessing the file. Unless changed with +.BI \- SIGNAL\/\c +, SIGKILL is sent. +An +.B fuser +process never kills itself, but may kill other +.B fuser +processes. The effective user ID of the process executing +.B fuser +is set to its real user ID before attempting to kill. +.TP +.BR \-i ", " \-\-interactive +Ask the user for confirmation before killing a process. +This option is +silently ignored if +.B \-k +is not present too. +.TP +.BR \-I ", " \-\-inode +For the name space +.B file +let all comparisons be based on the inodes of the specified file(s) +and never on the file names even on network based file systems. +.TP +.BR \-l ", " \-\-list\-signals +List all known signal names. +.TP +.BI -m " NAME\fR, " "\-\-mount " NAME +.I NAME +specifies a file on a mounted file system or a block device that is +mounted. All processes accessing files on that file system are listed. +If a directory is specified, it is automatically changed to +.IR NAME / +to use any file system that might be mounted on that directory. +.TP +.BR \-M ", " \-\-ismountpoint +Request will be fulfilled only if +.I NAME +specifies a mountpoint. This is an invaluable seat belt which prevents +you from killing the machine if +.I NAME +happens to not be a filesystem. +.TP +.B \-w +Kill only processes which have write access. This option is silently +ignored if +.B \-k +is not present too. +.TP +.BI \-n " NAMESPACE\fR, " "\-\-namespace " NAMESPACE +Select a different name space. The name spaces +.B file +(file names, the default), +.B udp +(local UDP ports), and +.B tcp +(local TCP ports) are supported. For ports, either the port number or +the symbolic name can be specified. If there is no ambiguity, the +shortcut notation +.IB name / space +(e.g., +.IB 80 / tcp \fR) +can be used. +.TP +.BR \-s ", " \-\-silent +Silent operation. +.B \-u +and +.B \-v +are ignored in this mode. +.B \-a +must not be used with +.BR \-s . +.TP +.BI \- SIGNAL +Use the specified signal instead of SIGKILL when killing processes. +Signals can be specified either by name (e.g., +.BR \-HUP ) +or by number (e.g., +.BR \-1 ). +This option is silently ignored if the +.B \-k +option is not used. +.TP +.BR \-u ", " \-\-user +Append the user name of the process owner to each PID. +.TP +.BR \-v ", " \-\-verbose +Verbose mode. Processes are shown in a +.BR ps -like +style. The fields PID, USER and COMMAND are similar to +.BR ps . +ACCESS shows how the process accesses the file. Verbose mode will also +show when a particular file is being accessed as a mount point, knfs +export or swap file. In this case +.B kernel +is shown instead of the PID. +.TP +.BR \-V ", " \-\-version +Display version information. +.TP +.BR \-4 ", " \-\-ipv4 +Search only for IPv4 sockets. This option must not be used with the +.B \-6 +option and only has an effect with the tcp and udp namespaces. +.TP +.BR \-6 ", " \-\-ipv6 +Search only for IPv6 sockets. This option must not be used with the +.B \-4 +option and only has an effect with the tcp and udp namespaces. +.SH FILES +.TP +/proc +location of the proc file system +.SH EXAMPLES +.TP +.B fuser \-km /home +kills all processes accessing the file system /home in any way. +.TP +.BI "if fuser \-s /dev/ttyS1; then :; else " command "; fi" +invokes +.I command +if no other process is using /dev/ttyS1. +.TP +.B fuser telnet/tcp +shows all processes at the (local) TELNET port. +.SH RESTRICTIONS +Processes accessing the same file or file system several times in the +same way are only shown once. +.PP +If the same object is specified several times on the command line, some +of those entries may be ignored. +.PP +.B fuser +may only be able to gather partial information unless run with +privileges. As a consequence, files opened by processes belonging to +other users may not be listed and executables may be classified as +mapped only. +.PP +.B fuser +cannot report on any processes that it doesn't have permission to look +at the file descriptor table for. The most common time this problem +occurs is when looking for TCP or UDP sockets when running +.B fuser +as a non-root user. In this case +.B fuser +will report no access. +.PP +Installing +.B fuser +SUID root will avoid problems associated with partial information, but +may be undesirable for security and privacy reasons. +.PP +.B udp +and +.B tcp +name spaces, and UNIX domain sockets can't be searched with kernels +older than 1.3.78. +.PP +Accesses by the kernel are only shown with the +.B \-v +option. +.PP +The +.B \-k +option only works on processes. If the user is the kernel, +.B fuser +will print an advice, but take no action beyond that. +.PP +.B fuser +will not see block devices mounted by processes in a different mount namespace. +This is due to the device ID shown in the process' file descriptor table being +from the process namespace, not fuser's; meaning it won't match. +.SH BUGS +.PP +.B fuser \-m /dev/sgX +will show (or kill with the \fB\-k\fR flag) all processes, +even if you don't have that device configured. There may be other +devices it does this for too. +.PP +The mount \fB\-m\fR option will match any file within the same device as the +specified file, use the \fB\-M\fR option as well if you mean to specify only +the mount point. +.PP +.B fuser +will not match mapped files, such as a process' shared libraries if they are +on a +.BR btrfs (5) +filesystem due to the device IDs being different for +.BR stat (2) +and \fI/proc/<PID>/maps\fR. +.SH "SEE ALSO" +.BR kill (1), +.BR killall (1), +.BR stat (2), +.BR btrfs (5), +.BR lsof (8), +.BR mount_namespaces (7), +.BR pkill (1), +.BR ps (1), +.BR kill (2). |