12046 Provide /proc/<PID>/fdinfo/

Reviewed by: John Levon <john.levon@joyent.com>
Reviewed by: Robert Mustacchi <rm@fingolfin.org>
Approved by: Dan McDonald <danmcd@joyent.com>

5 files changed, 360 insertions, 1 deletions

diff --git a/usr/src/man/man3proc/Makefile b/usr/src/man/man3proc/Makefile
index 00403a19fa..1986a27ead 100644
--- a/usr/src/man/man3proc/Makefile
+++ b/usr/src/man/man3proc/Makefile
@@ -14,7 +14,7 @@
 # Copyright 2013 Nexenta Systems, Inc.  All rights reserved.
 # Copyright 2018 Joyent, Inc.
 # Copyright 2019, Carlos Neira <cneirabustos@gmail.com>
-# Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
+# Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
 
 include		$(SRC)/Makefile.master
 
@@ -123,10 +123,14 @@ MANFILES=					\
 		proc_arg_grab.3proc		\
 		proc_arg_psinfo.3proc		\
 		proc_content2str.3proc		\
+		proc_fdinfo_misc.3proc		\
+		proc_fdinfowalk.3proc		\
+		proc_fdwalk.3proc		\
 		proc_fltname.3proc		\
 		proc_fltset2str.3proc		\
 		proc_get_auxv.3proc		\
 		proc_get_cred.3proc		\
+		proc_get_fdinfo.3proc		\
 		proc_get_priv.3proc		\
 		proc_get_psinfo.3proc		\
 		proc_get_status.3proc		\
@@ -222,6 +226,7 @@ MANLINKS=					\
 		proc_arg_xgrab.3proc		\
 		proc_arg_xpsinfo.3proc		\
 		proc_dmodelname.3proc		\
+		proc_fdinfo_free.3proc		\
 		proc_finistdio.3proc		\
 		proc_flushstdio.3proc		\
 		proc_free_priv.3proc		\
@@ -394,6 +399,8 @@ proc_arg_xpsinfo.3proc		:= LINKSRC = proc_arg_psinfo.3proc
 
 proc_str2content.3proc		:= LINKSRC = proc_content2str.3proc
 
+proc_fdinfo_free.3proc		:= LINKSRC = proc_get_fdinfo.3proc
+
 proc_flushstdio.3proc		:= LINKSRC = proc_initstdio.3proc
 proc_finistdio.3proc		:= LINKSRC = proc_initstdio.3proc
 
diff --git a/usr/src/man/man3proc/proc_fdinfo_misc.3proc b/usr/src/man/man3proc/proc_fdinfo_misc.3proc
new file mode 100644
index 0000000000..c7cdd4e338
--- /dev/null
+++ b/usr/src/man/man3proc/proc_fdinfo_misc.3proc
@@ -0,0 +1,71 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
+.\"
+.Dd January 6, 2020
+.Dt PROC_FDINFO_MISC 3PROC
+.Os
+.Sh NAME
+.Nm proc_fdinfo_misc
+.Nd retrieve a miscellaneous information item from a prfdinfo_t structure
+.Sh SYNOPSIS
+.Lb libproc
+.In libproc.h
+.Ft const void *
+.Fo proc_fdinfo_misc
+.Fa "const prfdinfo_t *info"
+.Fa "uint_t type"
+.Fa "size_t *len"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn proc_fdinfo_misc
+function is a convenient way to retrieve a miscellaneous information item from
+a
+.Vt prfdinfo_t
+structure.
+.Pp
+If a miscellaneous item of type
+.Fa type
+is found, then this function returns a pointer to the data for that item and
+updates
+.Fa len
+with the item's size.
+.Pp
+In the case that there are multiple instances of the requested type in the
+structure, only the first is returned.
+To see all instances, use the
+.Xr proc_fdinfowalk 3PROC
+function.
+.Pp
+The definition of the
+.Vt prfdinfo_t
+structure may be found in the
+.Sx fdinfo
+section of
+.Xr proc 4 .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn proc_fdinfo_misc
+function returns a pointer to the first instance of data with the requested
+type.
+Otherwise,
+.Sy NULL
+is returned to indicate that the item was not found.
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr libproc 3LIB ,
+.Xr proc_fdinfowalk 3PROC ,
+.Xr proc 4
diff --git a/usr/src/man/man3proc/proc_fdinfowalk.3proc b/usr/src/man/man3proc/proc_fdinfowalk.3proc
new file mode 100644
index 0000000000..1a35e9d209
--- /dev/null
+++ b/usr/src/man/man3proc/proc_fdinfowalk.3proc
@@ -0,0 +1,95 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
+.\"
+.Dd January 6, 2020
+.Dt PROC_FDINFOWALK 3PROC
+.Os
+.Sh NAME
+.Nm proc_fdinfowalk
+.Nd walk the additional miscellaneous information in a prfdinfo_t structure
+.Sh SYNOPSIS
+.Lb libproc
+.In libproc.h
+.Ft int
+.Fo proc_fdinfowalk
+.Fa "const prfdinfo_t *info"
+.Fa "proc_fdinfowalk_f *func"
+.Fa "void *arg"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn proc_fdinfowalk
+function walks a
+.Vt prfdinfo_t
+structure and calls the callback function
+.Fa func
+once for each miscellaneous item of information present,
+along with the user-specified
+.Fa arg .
+The definition of
+.Sy proc_fdinfowalk_f
+is available in
+.Xr libproc 3LIB .
+The miscellaneous data types and structures are found in the
+.Sx fdinfo
+section of
+.Xr proc 4 .
+.Pp
+.Fa func
+will be called once for each miscellaneous item, providing the item's
+.Fa type ,
+.Fa size
+and
+.Fa address.
+The
+.Fa size
+may include trailing padding bytes which will be set to zero.
+.Pp
+The return value of the caller's
+.Fa func
+function determines whether or not iteration will continue.
+If
+.Fa func
+returns a non-zero value, then iteration will terminate and that
+return value will be returned to the caller.
+To distinguish between system errors and caller errors, it is recommended that
+the function only return positive integers in the event of an error.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn proc_fdinfowalk
+function returns
+.Sy 0 .
+Otherwise,
+.Sy -1
+is returned and
+.Sy errno
+is updated to reflect the error that occurred.
+.Sh ERRORS
+In addition to the errors listed below, the
+.Fn proc_fdinfowalk
+function may fail for the same reasons as the
+.Xr opendir 3C ,
+.Xr readdir 3C ,
+and
+.Xr malloc 3C
+functions.
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr malloc 3C ,
+.Xr opendir 3C ,
+.Xr readdir 3C ,
+.Xr libproc 3LIB ,
+.Xr proc 4
diff --git a/usr/src/man/man3proc/proc_fdwalk.3proc b/usr/src/man/man3proc/proc_fdwalk.3proc
new file mode 100644
index 0000000000..52bf29ed60
--- /dev/null
+++ b/usr/src/man/man3proc/proc_fdwalk.3proc
@@ -0,0 +1,87 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
+.\"
+.Dd January 6, 2020
+.Dt PROC_FDWALK 3PROC
+.Os
+.Sh NAME
+.Nm proc_fdwalk
+.Nd walk the open file descriptors for a process
+.Sh SYNOPSIS
+.Lb libproc
+.In libproc.h
+.Ft int
+.Fo proc_fdwalk
+.Fa "pid_t pid"
+.Fa "proc_fdwalk_f *func"
+.Fa "void *arg"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn proc_fdwalk
+function walks all file descriptors currently open in the process with ID
+.Fa pid
+and calls the callback function
+.Fa func
+once for each file descriptor with the user-specified
+.Fa arg .
+The definition of
+.Vt proc_fdwalk_f
+is available in
+.Xr libproc 3LIB .
+.Pp
+.Fa func
+will be called once for each file descriptor and will have its first
+argument filled in with the contents of the corresponding
+.Pa /proc
+.Sy fdinfo
+file for the file descriptor.
+.Pp
+The return value of the caller's
+.Fa func
+function determines whether or not iteration will continue.
+If
+.Fa func
+returns a non-zero value, then iteration will terminate and that
+return value will be returned to the caller.
+To distinguish between system errors and caller errors, it is recommended that
+the function only return positive integers in the event of an error.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn proc_fdwalk
+function returns
+.Sy 0 .
+Otherwise,
+.Sy -1
+is returned and
+.Sy errno
+is updated to reflect the error that occurred.
+.Sh ERRORS
+In addition to the errors listed below, the
+.Fn proc_fdwalk
+function may fail for the same reasons as the
+.Xr opendir 3C ,
+.Xr readdir 3C ,
+and
+.Xr malloc 3C
+functions.
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr malloc 3C ,
+.Xr opendir 3C ,
+.Xr readdir 3C ,
+.Xr libproc 3LIB ,
+.Xr proc 4
diff --git a/usr/src/man/man3proc/proc_get_fdinfo.3proc b/usr/src/man/man3proc/proc_get_fdinfo.3proc
new file mode 100644
index 0000000000..b85eef16f9
--- /dev/null
+++ b/usr/src/man/man3proc/proc_get_fdinfo.3proc
@@ -0,0 +1,99 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
+.\"
+.Dd January 6, 2020
+.Dt PROC_GET_FDINFO 3PROC
+.Os
+.Sh NAME
+.Nm proc_get_fdinfo ,
+.Nm proc_fdinfo_free
+.Nd get process file descriptor information
+.Sh LIBRARY
+.Lb libproc
+.Sh SYNOPSIS
+.In libproc.h
+.Ft prfdinfo_t *
+.Fo proc_get_fdinfo
+.Fa "pid_t pid"
+.Fa "int fd"
+.Fc
+.Ft "void"
+.Fo proc_fdinfo_free
+.Fa "prfdinfo_t *info"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn proc_get_fdinfo
+function is a convenient way to read the
+.Pa /proc/pid/fdinfo/fd
+file for the process
+.Fa pid
+and file descriptor
+.Fa fd .
+On success, the return value of the function is a pointer to a properly
+terminated
+.Sy prfdinfo_t
+structure.
+.Pp
+The definition of the
+.Vt prfdinfo_t
+structure may be found in
+.Xr proc 4 .
+.Pp
+The caller must free the returned memory by calling the
+.Fn proc_fdinfo_free
+function.
+.Pp
+The
+.Fn proc_fdinfo_free
+frees all memory associated with the
+.Vt prfdinfo_t
+structure passed as
+.Fa info .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn proc_get_fdinfo
+function returns a pointer to an allocated
+.Vt prfdinfo_t
+structure.
+Otherwise,
+.Dv NULL
+is returned to indicate an error occurred and
+.Vt errno
+is set to indicate the error.
+.Sh ERRORS
+In addition to the errors listed below, the
+.Fn proc_get_fdinfo
+function may fail for the same reasons as the
+.Xr fstat 2 ,
+.Xr malloc 3C ,
+.Xr open 2 ,
+and
+.Xr read 2
+functions.
+The
+.Fn proc_get_fdinfo
+function will fail if:
+.Bl -tag -width Er
+.It Er EIO
+The data read from the file under
+.Pa /proc
+is not properly terminated.
+.El
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr libproc 3LIB ,
+.Xr proc 4