process_lookup.h File Reference

#include <wireshark.h>
#include <wsutil/inet_addr.h>

Go to the source code of this file.

Classes
struct	ws_process_info
	What the operating system knows about a process. More...
struct	ws_socket_endpoint
	One end of a socket: an IPv4 or IPv6 address and a port. More...

Typedefs
typedef struct ws_process_info	ws_process_info_t
	What the operating system knows about a process.
typedef struct ws_socket_endpoint	ws_socket_endpoint_t
	One end of a socket: an IPv4 or IPv6 address and a port.
typedef struct ws_process_lookup	ws_process_lookup_t
	A lookup context.

Enumerations
enum	ws_process_lookup_protocol_t { WS_PROCESS_LOOKUP_TCP = 6 , WS_PROCESS_LOOKUP_UDP = 17 }
	The transport protocols of the sockets that can be looked up. More...
enum	ws_process_detail_t { WS_PROCESS_DETAIL_BASIC , WS_PROCESS_DETAIL_FULL }
	How much is found out about a process. More...

Functions
WS_DLL_PUBLIC bool	ws_process_lookup_supported (void)
	Whether the operating system's socket tables can be read on this platform.
WS_DLL_PUBLIC ws_process_lookup_t *	ws_process_lookup_new (char **err_msg)
	Create a lookup context.
WS_DLL_PUBLIC void	ws_process_lookup_free (ws_process_lookup_t *lookup)
	Free a lookup context and every ws_process_info_t it returned.
WS_DLL_PUBLIC void	ws_process_lookup_set_detail (ws_process_lookup_t *lookup, ws_process_detail_t detail)
	Set how much is found out about the processes.
WS_DLL_PUBLIC void	ws_process_lookup_set_refresh_interval (ws_process_lookup_t *lookup, unsigned interval_ms)
	Set how soon the socket tables may be read again after a miss.
WS_DLL_PUBLIC bool	ws_process_lookup_refresh (ws_process_lookup_t *lookup, char **err_msg)
	Read the operating system's socket tables again now.
WS_DLL_PUBLIC unsigned	ws_process_lookup_socket (ws_process_lookup_t *lookup, ws_process_lookup_protocol_t protocol, const ws_socket_endpoint_t *local, const ws_socket_endpoint_t *remote, GPtrArray *processes)
	Find the processes that have a socket open.
WS_DLL_PUBLIC const ws_process_info_t *	ws_process_lookup_pid (ws_process_lookup_t *lookup, uint32_t pid)
	Describe a process by its ID.

Detailed Description

Look up the processes that have a network socket open, from the operating system's socket tables, and describe them.

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Typedef Documentation

ws_process_info_t

typedef struct ws_process_info ws_process_info_t

What the operating system knows about a process.

Whatever the operating system does not provide, or does not let the calling user see, or was not asked for (see ws_process_detail_t), is NULL (strings), 0 (the start time) or flagged as absent. Strings are UTF-8.

ws_process_lookup_t

typedef struct ws_process_lookup ws_process_lookup_t

A lookup context.

It holds a snapshot of the operating system's socket tables, refreshed on demand but not more often than a configurable interval, and a cache of what is known about the processes found. It is not thread-safe.

Enumeration Type Documentation

ws_process_detail_t

enum ws_process_detail_t

How much is found out about a process.

The path, the command line and the user of a process can be sensitive: a command line can contain a password, and a path the name of a user. With WS_PROCESS_DETAIL_BASIC they are not even read.

Enumerator
WS_PROCESS_DETAIL_BASIC	What identifies a process: its ID, name and start time.
WS_PROCESS_DETAIL_FULL	Also its path, command line, parent and user.

ws_process_lookup_protocol_t

enum ws_process_lookup_protocol_t

The transport protocols of the sockets that can be looked up.

The values are the IP protocol numbers, so the protocol field of an IP header can be passed as is.

Function Documentation

ws_process_lookup_free()

WS_DLL_PUBLIC void ws_process_lookup_free

(

ws_process_lookup_t *

lookup

)

Free a lookup context and every ws_process_info_t it returned.

Parameters

lookup

The context; NULL is allowed.

ws_process_lookup_new()

WS_DLL_PUBLIC ws_process_lookup_t * ws_process_lookup_new

(

char **

err_msg

)

Create a lookup context.

Parameters

err_msg

Set to a g_malloc()ed message on failure, if not NULL.

Returns

The context, to be freed with ws_process_lookup_free(), or NULL if the platform is not supported or the socket tables cannot be read.

ws_process_lookup_pid()

WS_DLL_PUBLIC const ws_process_info_t * ws_process_lookup_pid	(	ws_process_lookup_t *	lookup,
		uint32_t	pid )

Describe a process by its ID.

Parameters

lookup	The context.
pid	The process ID.

Returns

What is known about the process, valid until the context is freed, or NULL if there is no such process.

ws_process_lookup_refresh()

WS_DLL_PUBLIC bool ws_process_lookup_refresh	(	ws_process_lookup_t *	lookup,
		char **	err_msg )

Read the operating system's socket tables again now.

Parameters

lookup	The context.
err_msg	Set to a g_malloc()ed message on failure, if not NULL.

Returns

true on success.

ws_process_lookup_set_detail()

WS_DLL_PUBLIC void ws_process_lookup_set_detail	(	ws_process_lookup_t *	lookup,
		ws_process_detail_t	detail )

Set how much is found out about the processes.

The default is WS_PROCESS_DETAIL_BASIC. Set it before looking anything up: the records that have been returned are not changed.

Parameters

lookup	The context.
detail	The level of detail.

ws_process_lookup_set_refresh_interval()

WS_DLL_PUBLIC void ws_process_lookup_set_refresh_interval	(	ws_process_lookup_t *	lookup,
		unsigned	interval_ms )

Set how soon the socket tables may be read again after a miss.

A socket that is not in the snapshot triggers a refresh only if the previous refresh is at least this old, which bounds the cost of packets that belong to no local socket. The default is 250 ms.

Parameters

lookup	The context.
interval_ms	The minimum interval between refreshes, in milliseconds. Whatever it is, refreshes are also kept at least ten times as far apart as the last one took, so that a host with very many sockets, where reading the tables is slow, still gets most of the caller's time.

ws_process_lookup_socket()

WS_DLL_PUBLIC unsigned ws_process_lookup_socket	(	ws_process_lookup_t *	lookup,
		ws_process_lookup_protocol_t	protocol,
		const ws_socket_endpoint_t *	local,
		const ws_socket_endpoint_t *	remote,
		GPtrArray *	processes )

Find the processes that have a socket open.

The socket is identified by its local end and, for a connected socket, its remote end. If no socket matches both, a socket bound to the local end alone (listening, or an unconnected UDP socket) is looked for, and then one bound to the local port on any address, of either IP version. Every process that has a matching socket open is reported: a socket can be inherited across fork() or passed between processes, and several sockets can match, e.g. with SO_REUSEPORT. On Windows the system reports one process per socket, the one that bound it.

Parameters

lookup	The context.
protocol	The transport protocol.
local	The end of the socket on this host.
remote	The other end, or NULL if the socket is not connected or the other end is unknown.
processes	Array to which what is known about each process is appended, as const ws_process_info_t pointers valid until the context is freed, the process that has had the socket open longest first, normally the one that created it.

Returns

The number of processes appended: 0 if no socket matches or none can be attributed to a process.

ws_process_lookup_supported()

WS_DLL_PUBLIC bool ws_process_lookup_supported

(

void

)

Whether the operating system's socket tables can be read on this platform.

Returns

true if ws_process_lookup_new() can succeed here.