Adding upstream version 23.7.upstream/23.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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).