Debian Codegraph @

include/lsof.h

raw
1 /** @file
2 * lsof.h - header file for lsof
3 */
4
5 /*
6 * Copyright 1994 Purdue Research Foundation, West Lafayette, Indiana
7 * 47907. All rights reserved.
8 *
9 * Written by Victor A. Abell
10 *
11 * This software is not subject to any license of the American Telephone
12 * and Telegraph Company or the Regents of the University of California.
13 *
14 * Permission is granted to anyone to use this software for any purpose on
15 * any computer system, and to alter it and redistribute it freely, subject
16 * to the following restrictions:
17 *
18 * 1. Neither the authors nor Purdue University are responsible for any
19 * consequences of the use of this software.
20 *
21 * 2. The origin of this software must not be misrepresented, either by
22 * explicit claim or by omission. Credit to the authors and Purdue
23 * University must appear in documentation and sources.
24 *
25 * 3. Altered versions must be plainly marked as such, and must not be
26 * misrepresented as being the original software.
27 *
28 * 4. This notice may not be removed or altered.
29 */
30
31 /*
32 * $Id: lsof.h,v 1.70 2018/03/26 21:50:45 abe Exp $
33 */
34
35 #if !defined(LSOF_H)
36 # define LSOF_H 1
37
38 # include <stdint.h>
39 # include <stdio.h>
40
41 /** lsof error returns */
42 enum lsof_error {
43 LSOF_SUCCESS = 0, /**< Success */
44 LSOF_ERROR_INVALID_ARGUMENT, /**< Invalid argument */
45 LSOF_ERROR_NO_MEMORY, /**< No memory */
46 LSOF_ERROR_UNSUPPORTED, /**< Unsupported operation */
47 };
48
49 /** File access mode */
50 enum lsof_file_access_mode {
51 LSOF_FILE_ACCESS_NONE = 0, /**< None */
52 LSOF_FILE_ACCESS_READ = 1, /**< Read */
53 LSOF_FILE_ACCESS_WRITE = 2, /**< Write */
54 LSOF_FILE_ACCESS_READ_WRITE =
55 LSOF_FILE_ACCESS_READ | LSOF_FILE_ACCESS_WRITE, /**< Read and write */
56 };
57
58 /** File lock mode */
59 enum lsof_lock_mode {
60 LSOF_LOCK_NONE, /**< None */
61 LSOF_LOCK_UNKNOWN, /**< Unknown */
62 LSOF_LOCK_READ_PARTIAL, /**< Read lock on part of the file */
63 LSOF_LOCK_READ_FULL, /**< Read lock on the entire file */
64 LSOF_LOCK_WRITE_PARTIAL, /**< Write lock on part of the file */
65 LSOF_LOCK_WRITE_FULL, /**< Write lock on the entire file */
66 LSOF_LOCK_READ_WRITE, /**< Read and write lock */
67 LSOF_LOCK_SOLARIS_NFS, /**< Solaris NFS lock */
68 LSOF_LOCK_SCO_PARTIAL, /**< SCO OpenServer lock on part of the file */
69 LSOF_LOCK_SCO_FULL, /**< SCO OpenServer lock on the entire file */
70 };
71
72 /** File descriptor type */
73 enum lsof_fd_type {
74 LSOF_FD_NUMERIC, /**< Numeric fd opened in process */
75 LSOF_FD_UNKNOWN, /**< Unknown fd type */
76 LSOF_FD_CWD, /**< Current working directory */
77 LSOF_FD_ERROR, /**< Failed to get fd information */
78 LSOF_FD_NOFD, /**< No file descriptors */
79 LSOF_FD_ROOT_DIR, /**< Root directory */
80 LSOF_FD_PARENT_DIR, /**< Parent directory */
81 LSOF_FD_PROGRAM_TEXT, /**< Program text */
82 LSOF_FD_LIBRARY_TEXT, /**< Library text */
83 LSOF_FD_MEMORY, /**< Memory-mapped file */
84 LSOF_FD_DELETED, /**< Deleted file */
85 LSOF_FD_FILEPORT, /**< Darwin fileport */
86 LSOF_FD_TASK_CWD, /**< Per task/thread cwd */
87 LSOF_FD_CTTY, /**< Character TTY */
88 LSOF_FD_JAIL_DIR, /**< Jail directory */
89 LSOF_FD_VIRTUAL_8086, /**< Virtual 8086 */
90 LSOF_FD_MERGE_386, /**< MERGE386 vm86 region */
91 LSOF_FD_MMAP_DEVICE, /**< Memory-mapped device */
92 LSOF_FD_LIBRARY_REF, /**< Library references */
93 LSOF_FD_MMAP_UNKNOWN, /**< Unknown memory-mapped file */
94 LSOF_FD_PREGION_UNKNOWN, /**< Unknown HP-UX pregion */
95 };
96
97 /** File type */
98 enum lsof_file_type {
99 LSOF_FILE_NONE, /**< No file type */
100
101 /* struct stat S_IFMT modes */
102 LSOF_FILE_FIFO, /**< FIFO special file */
103 LSOF_FILE_CHAR, /**< Character special file */
104 LSOF_FILE_DIR, /**< Directory */
105 LSOF_FILE_BLOCK, /**< Block special file */
106 LSOF_FILE_REGULAR, /**< Regular file */
107 LSOF_FILE_LINK, /**< Symolic link */
108 LSOF_FILE_SOCKET, /**< Socket of unknown domain */
109
110 /* Network */
111 LSOF_FILE_IPV4, /**< IPv4 socket */
112 LSOF_FILE_IPV6, /**< IPv6 socket */
113 LSOF_FILE_AX25, /**< AX.25 socket */
114 LSOF_FILE_INET, /**< Internet(either IPv4 or IPv6) socket */
115 LSOF_FILE_LINK_LEVEL_ACCESS, /**< HP-UX link level access file */
116 LSOF_FILE_ROUTE, /**< AF_ROUTE socket */
117 LSOF_FILE_UNIX, /**< UNIX domain socket */
118 LSOF_FILE_X25, /**< HP-UX x.25 socket */
119 LSOF_FILE_APPLETALK, /**< Appletalk socket */
120 LSOF_FILE_NET_DRIVER, /**< AF_NDRV network driver raw socket */
121 LSOF_FILE_INTERNAL_KEY, /**< Darwin internal key-management socket */
122 LSOF_FILE_SYSTEM, /**< AF_SYSTEM kernel event messages socket */
123 LSOF_FILE_PPP, /**< PPP socket */
124 LSOF_FILE_IPX, /**< IPX socket */
125 LSOF_FILE_RAW, /**< raw socket */
126 LSOF_FILE_RAW6, /**< raw IPv6 socket */
127 LSOF_FILE_NETLINK, /**< netlink socket */
128 LSOF_FILE_PACKET, /**< packet socket */
129 LSOF_FILE_ICMP, /**< icmp socket */
130
131 /* procfs */
132 LSOF_FILE_PROC_AS, /**< Solaris /proc/<PID>/as file */
133 LSOF_FILE_PROC_AUXV, /**< /proc/<PID>/auxv file */
134 LSOF_FILE_PROC_CRED, /**< Solaris /proc/<PID>/cred file */
135 LSOF_FILE_PROC_CTRL, /**< /proc/<PID>/ctl control file */
136 LSOF_FILE_PROC_CUR_PROC, /**< NetBSD /proc/curproc file */
137 LSOF_FILE_PROC_CWD, /**< Solaris /proc/<PID>/cwd folder */
138 LSOF_FILE_PROC_DIR, /**< /proc directory */
139 LSOF_FILE_PROC_EXEC_TYPE, /**< FreeBSD /proc executable type (etype) */
140 LSOF_FILE_PROC_FD, /**< /proc/<PID>/fd/<FD> file */
141 LSOF_FILE_PROC_FD_DIR, /**< /proc/<PID>/fd directory */
142 LSOF_FILE_PROC_FILE, /**< /proc/<PID>/file executable file */
143 LSOF_FILE_PROC_FP_REGS, /**< /proc/<PID>/fpregs fp registers */
144 LSOF_FILE_PROC_PAGE_DATA, /**< Solaris /proc/<PID>/pagedata file */
145 LSOF_FILE_PROC_GROUP_NOTIFIER, /**< /proc/<PID>/notepg group notifier */
146 LSOF_FILE_PROC_LDT, /**< Solaris /proc/<PID>/ldt file */
147 LSOF_FILE_PROC_LPS_INFO, /**< Solaris /proc/<PID>/lpsinfo file */
148 LSOF_FILE_PROC_LSTATUS, /**< Solaris /proc/<PID>/lstatus file */
149 LSOF_FILE_PROC_LUSAGE, /**< Solaris /proc/<PID>/lusage file */
150 LSOF_FILE_PROC_LWP_GWINDOWS, /**< Solaris /proc/<PID>/lwp/<LWPID>/gwindows
151 */
152 LSOF_FILE_PROC_LWP_CTL, /**< Solaris /proc/<PID>/lwp/<LWPID>/lwpctl file */
153 LSOF_FILE_PROC_LWP_DIR, /**< Solaris /proc/<PID>/lwp or
154 /proc/<PID>/lwp/<LWPID> directory */
155 LSOF_FILE_PROC_LWP_SINFO, /**< Solaris /proc/<PID>/lwp/<LWPID>/lwpsinfo file
156 */
157 LSOF_FILE_PROC_LWP_STATUS, /**< Solaris /proc/<PID>/lwp/<LWPID>/lwpstatus
158 file */
159 LSOF_FILE_PROC_LWP_USAGE, /**< Solaris /proc/<PID>/lwp/<LWPID>/lwpusage file
160 */
161 LSOF_FILE_PROC_LWP_XREGS, /**< Solaris /proc/<PID>/lwp/<LWPID>/xregs file */
162 LSOF_FILE_PROC_MAP, /**< /proc/<PID>/map memory mapping file */
163 LSOF_FILE_PROC_MAPS, /**< /proc/<PID>/maps memory mapping file */
164 LSOF_FILE_PROC_MEMORY, /**< /proc/<PID>/mem memory image file */
165 LSOF_FILE_PROC_PROC_NOTIFIER, /**< /proc/<PID>/note process notifier file */
166 LSOF_FILE_PROC_OBJ, /**< Solaris /proc/<PID>/object file */
167 LSOF_FILE_PROC_OBJ_DIR, /**< Solaris /proc/<PID>/object directory */
168 LSOF_FILE_PROC_OLD_LWP, /**< Solaris old format /proc/<LWPID> file */
169 LSOF_FILE_PROC_OLD_PID, /**< Solaris old format /proc/<PID> file */
170 LSOF_FILE_PROC_OLD_PAGE, /**< Solaris old /proc/<PID> page data file */
171 LSOF_FILE_PROC_REGS, /**< /proc/<PID>/regs register set */
172 LSOF_FILE_PROC_RMAP, /**< Solaris /proc/<PID>/rmap file */
173 LSOF_FILE_PROC_ROOT, /**< Solaris /proc/<PID>/root directory */
174 LSOF_FILE_PROC_SIGACT, /**< Solaris /proc/<PID>/sigact file */
175 LSOF_FILE_PROC_PSINFO, /**< Solaris /proc/<PID>/psinfo file */
176 LSOF_FILE_PROC_STATUS, /**< /proc/<PID>/status status file */
177 LSOF_FILE_PROC_USAGE, /**< Solaris /proc/<PID>/usage file */
178 LSOF_FILE_PROC_WATCH, /**< Solaris /proc/<PID>/watch file */
179 LSOF_FILE_PROC_XMAP, /**< Solaris /proc/<PID>/xmap file */
180
181 /* Others */
182 LSOF_FILE_ANON_INODE, /**< anonymous inode */
183 LSOF_FILE_DEL, /**< Linux map file that has been deleted */
184 LSOF_FILE_DOOR, /**< Solaris VDOOR file */
185 LSOF_FILE_KQUEUE, /**< BSD style kernel event file */
186 LSOF_FILE_FSEVENTS, /**< fsevents file */
187 LSOF_FILE_EVENTFD, /**< eventfd file */
188 LSOF_FILE_PROCDESC, /**< process descriptor file */
189 LSOF_FILE_MULTIPLEXED_BLOCK, /**< SCO OpenServer multiplexed block file */
190 LSOF_FILE_MULTIPLEXED_CHAR, /**< SCO OpenServer multiplexed char file */
191 LSOF_FILE_UNKNOWN_DELETED, /**< Linux unknown deleted file */
192 LSOF_FILE_UNKNOWN_MEMORY, /**< Linux unknown memory file */
193 LSOF_FILE_UNKNOWN_FD, /**< Linux unknown fd */
194 LSOF_FILE_UNKNOWN_CWD, /**< Linux unknown cwd */
195 LSOF_FILE_UNKNOWN_ROOT_DIR, /**< Linux unknown root dir */
196 LSOF_FILE_UNKNOWN_PROGRAM_TEXT, /**< Linux unknown program text */
197 LSOF_FILE_UNKNOWN_STAT, /**< Linux unknown due to failed stat() */
198 LSOF_FILE_UNKNOWN_RAW, /**< Unknown file type, raw numbers provided in
199 unknown_file_type_number */
200 LSOF_FILE_UNKNOWN, /**< Unknown file type without raw number */
201 LSOF_FILE_PIPE, /**< pipes */
202 LSOF_FILE_PORT, /**< Solaris SYSV named pipe */
203 LSOF_FILE_POSIX_MQ, /**< POSIX named message queue file */
204 LSOF_FILE_POSIX_SEMA, /**< POSIX named semaphore file */
205 LSOF_FILE_POSIX_SHM, /**< POSIX named shared memory file */
206 LSOF_FILE_SHM, /**< SystemV shared memory file */
207 LSOF_FILE_PTS, /**< FreeBSD /dev/pts file */
208 LSOF_FILE_SHARED_MEM_TRANSPORT, /**< AIX Shared memory transport file */
209 LSOF_FILE_STREAM, /**< HP-UX streams */
210 LSOF_FILE_STREAM_SOCKET, /**< HP-UX stream socket */
211 LSOF_FILE_SCO_UNKNOWN, /**< SCO OpenServer Xenix special file of unknown
212 type */
213 LSOF_FILE_SCO_SEMA, /**< SCO OpenServer Xenix semaphore file */
214 LSOF_FILE_SCO_SHARED, /**< SCO OpenServer Xenix shared data file */
215 LSOF_FILE_UNSUPPORTED, /**< unsupported file type */
216
217 /* types from struct vnode */
218 LSOF_FILE_VNODE_VNON, /**< The vnode has no type */
219 LSOF_FILE_VNODE_VREG, /**< The vnode represents a regular file */
220 LSOF_FILE_VNODE_VDIR, /**< The vnode represents a directory */
221 LSOF_FILE_VNODE_VBLK, /**< The vnode represents a block special device */
222 LSOF_FILE_VNODE_VCHR, /**< The vnode represents a char special device */
223 LSOF_FILE_VNODE_VLNK, /**< The vnode represents a symbolic link */
224 LSOF_FILE_VNODE_VSOCK, /**< The vnode represents a socket */
225 LSOF_FILE_VNODE_VBAD, /**< The vnode represents a bad file */
226 LSOF_FILE_VNODE_VMPC, /**< The vnode represents a multiplexed character
227 special device */
228 LSOF_FILE_VNODE_VFIFO, /**< The vnode represents a FIFO file */
229 LSOF_FILE_VNODE_VUNNAMED, /**< The vnode represents an unnamed file */
230 LSOF_FILE_VNODE_VDOOR, /**< The vnode represents a door */
231 LSOF_FILE_VNODE_VPORT, /**< The vnode represents a port */
232 };
233
234 /** @struct lsof_context
235 * Hidden struct of lsof context, use `lsof_new()` to get one
236 */
237 struct lsof_context;
238
239 /** @enum struct lsof_file flags */
240 enum lsof_file_flag {
241 LSOF_FILE_FLAG_NONE,
242 /** \ref struct lsof_file.dev field is valid */
243 LSOF_FILE_FLAG_DEV_VALID = 0x00000001,
244 /** \ref struct lsof_file.rdev field is valid */
245 LSOF_FILE_FLAG_RDEV_VALID = 0x00000002,
246 /** \ref struct lsof_file.size field is valid */
247 LSOF_FILE_FLAG_SIZE_VALID = 0x00000004,
248 /** \ref struct lsof_file.offset field is valid */
249 LSOF_FILE_FLAG_OFFSET_VALID = 0x00000008,
250 /** \ref struct lsof_file.num_links field is valid */
251 LSOF_FILE_FLAG_NUM_LINKS_VALID = 0x00000010,
252 /** \ref struct lsof_file.inode field is valid */
253 LSOF_FILE_FLAG_INODE_VALID = 0x00000020,
254 };
255
256 /** An open file
257 */
258 struct lsof_file {
259 /** Flags, see \ref lsof_file_flag */
260 uint64_t flags;
261
262 /* FD column */
263 /** File descriptor type */
264 enum lsof_fd_type fd_type;
265
266 /** File descriptor number, valid if \ref fd_type == \ref LSOF_FD_NUMERIC */
267 uint32_t fd_num;
268
269 /** File access mode */
270 enum lsof_file_access_mode access;
271
272 /** File lock mode */
273 enum lsof_lock_mode lock;
274
275 /* TYPE column */
276 /** File type */
277 enum lsof_file_type file_type;
278 /** Store raw file type number when \ref file_type == \ref LSOF_FILE_UNKNOWN
279 */
280 uint32_t unknown_file_type_number;
281
282 /* DEVICE column */
283 /** Device ID of device containing file, use major() and minor() to extract
284 * components. Valid if \ref flags & \ref LSOF_FILE_FLAG_DEV_VALID */
285 uint64_t dev;
286 /** Device ID of special character/block file, use major() and minor() to
287 * extract components. Valid if \ref flags & \ref
288 * LSOF_FILE_FLAG_RDEV_VALID */
289 uint64_t rdev;
290
291 /* SIZE, SIZE/OFF, OFFSET column */
292 /** File size, valid if \ref flags & \ref LSOF_FILE_FLAG_SIZE_VALID */
293 uint64_t size;
294
295 /** File offset, valid if \ref flags & \ref LSOF_FILE_FLAG_OFFSET_VALID */
296 uint64_t offset;
297
298 /* NLINK column */
299 /** Link count, valid if \ref flags & \ref LSOF_FILE_FLAG_NUM_LINKS_VALID */
300 uint64_t num_links;
301
302 /* NODE column */
303 /** File inode, valid if \ref flags & \ref LSOF_FILE_FLAG_INODE_VALID */
304 uint64_t inode;
305
306 /* NAME column */
307 /** File name or description */
308 char *name;
309 };
310
311 /** The result of lsof_gather(), grouped by process
312 *
313 * For each process, you can find a linked list of open files at `files`
314 */
315 struct lsof_process {
316 /* COMMAND column */
317 char *command; /**< command name */
318 /* PID column */
319 uint32_t pid; /**< process ID */
320
321 /* TID column */
322 uint32_t tid; /**< task ID */
323 /* TASKCMD column */
324 char *task_cmd; /**< task command name */
325
326 /* ZONES column */
327 char *solaris_zone; /**< solaris zone name */
328 /* SECURITY-CONTEXT column */
329 char *selinux_context; /**< seLinux context name */
330
331 /* PGID column */
332 uint32_t pgid; /**< process group ID */
333 /* PPID column */
334 uint32_t ppid; /**< parent process ID */
335 /* USER column */
336 uint32_t uid; /**< user ID */
337
338 uint32_t num_files; /**< length of files array */
339 struct lsof_file *files; /**< array of open files */
340 };
341
342 /** selection types */
343 enum lsof_selection_type {
344 LSOF_SELECTION_COMMAND, /**< select by command */
345 LSOF_SELECTION_COMMAND_REGEX, /**< select by command regex */
346 LSOF_SELECTION_PATH, /**< select by file path */
347 LSOF_SELECTION_FILE_SYSTEM, /**< select by file system */
348 LSOF_SELECTION_NETWORK_ADDRESS, /**< select by network address */
349 LSOF_SELECTION_INTERNET, /**< select by internet protocol */
350 LSOF_SELECTION_PROTOCOL_STATE, /**< select by tcp/tpi state */
351 LSOF_SELECTION_NFS, /**< select by nfs */
352 LSOF_SELECTION_PID, /**< select by pid */
353 LSOF_SELECTION_PGID, /**< select by pgid */
354 LSOF_SELECTION_UID, /**< select by uid */
355 LSOF_SELECTION_TASK, /**< select by tasks */
356 LSOF_SELECTION_SOLARIS_ZONE, /**< select by Solaris zones */
357 LSOF_SELECTION_SELINUX_CONTEXT, /**< select by SELinux context */
358 };
359
360 /** Report selection status */
361 struct lsof_selection {
362 enum lsof_selection_type type; /**< selection type */
363 int found; /**< whether selection matches file */
364 /** string selection argument, valid if type is one of
365 * LSOF_SELECTION_COMMAND, LSOF_SELECTION_COMMAND_REGEX,
366 * LSOF_SELECTION_PATH, LSOF_SELECTION_FILE_SYSTEM,
367 * LSOF_SELECTION_NETWORK_ADDRESS, LSOF_SELECTION_PROTOCOL_STATE,
368 * LSOF_SELECTION_UID, LSOF_SELECTION_SOLARIS_ZONE,
369 * LSOF_SELECTION_SELINUX_CONTEXT
370 */
371 char *string;
372 /** integer selection argument, valid if type is one of
373 * LSOF_SELECTION_PID, LSOF_SELECTION_PGID, LSOF_SELECTION_UID
374 */
375 uint64_t integer;
376 };
377
378 /** The result of lsof_gather() */
379 struct lsof_result {
380 size_t num_processes; /**< length of processes array */
381 struct lsof_process *processes; /**< array of processes */
382
383 /* Report selection status */
384 size_t num_selections; /**< length of selections array */
385 struct lsof_selection *selections; /**< array of selections */
386 };
387
388 /** API version of liblsof
389 * you may use this macro to check the existence of
390 * functions
391 */
392 # define LSOF_API_VERSION 1
393
394 /** Get runtime API version of liblsof
395 *
396 * liblsof might not function properly if API version mismatched between compile
397 * time and runtime.
398 *
399 * \since API version 1
400 */
401 int lsof_get_api_version();
402
403 /** Get library version of liblsof
404 *
405 * \return a string like "4.xx.x". The caller must not free it.
406 *
407 * \since API version 1
408 */
409 char *lsof_get_library_version();
410
411 /** Create a new lsof context
412 *
413 * The context should be freed via `lsof_destroy()`.
414 *
415 * \since API version 1
416 */
417 struct lsof_context *lsof_new();
418
419 /** Set output stream for warning and error messages
420 *
421 * lsof may want to print warning and error messages to the user. You can allow
422 * printing by setting the output stream and whether prints warning or not. You
423 * should also supply `program_name` so that the output starts with your program
424 * name.
425 *
426 * By default, the output is suppressed. You can set fp to NULL to suppress
427 * output.
428 *
429 * \since API version 1
430 */
431 enum lsof_error lsof_set_output_stream(struct lsof_context *ctx, FILE *fp,
432 char *program_name, int warn);
433
434 /** Ask lsof to avoid using blocking functions
435 *
436 * lsof may block when calling lstat(), readlink() or stat(). Call this function
437 * with `avoid=1` to let lsof avoid calling these functions.
438 *
439 * \since API version 1
440 */
441 enum lsof_error lsof_avoid_blocking(struct lsof_context *ctx, int avoid);
442
443 /** Ask lsof to avoid forking
444 *
445 * To avoid being blocked by some kernel operations, liblsof does them in forked
446 * child processes. Call this function to change this behavior.
447 *
448 * \since API version 1
449 */
450 enum lsof_error lsof_avoid_forking(struct lsof_context *ctx, int avoid);
451
452 /** Ask lsof to AND the selections
453 *
454 * By default, lsof OR the selections, for example, if you call
455 * lsof_select_unix_socket() and lsof_select_login(), it will report unix
456 * sockets OR open files by the user. If lsof_logic_and() is called, it will
457 * report unix sockets open by the specified user.
458 *
459 * \since API version 1
460 */
461 enum lsof_error lsof_logic_and(struct lsof_context *ctx);
462
463 /** Ask lsof to select process by command
464 *
465 * Select process executing the command that begins with the characters of
466 * `command`. You can specify exclusion by setting `exclude` to 1.
467 *
468 * You can call this function multiple times to add more search conditions.
469 *
470 * \since API version 1
471 */
472 enum lsof_error lsof_select_process(struct lsof_context *ctx, char *command,
473 int exclude);
474
475 /** Ask lsof to select process by matching regex
476 *
477 * Select process executing the command that matches with the
478 * `regex`.
479 *
480 * `regex` must begin and end with a slash ('/'), the characters between the
481 * slashes are interpreted as a regular expression.
482 *
483 * The closing slash may be followed by these modifiers:
484 * - b the regular expression is a basic one.
485 * - i ignore the case of letters.
486 * - x the regular expression is an extended one (default).
487 *
488 * You can call this function multiple times to add more search conditions.
489 *
490 * \since API version 1
491 */
492 enum lsof_error lsof_select_process_regex(struct lsof_context *ctx,
493 char *regex);
494
495 /** Ask lsof to select process by pid (process id)
496 *
497 * Select process by comparing pid. You can specify exclusion by setting
498 * `exclude` to 1.
499 *
500 * You can call this function multiple times to add more search conditions.
501 *
502 * \since API version 1
503 */
504 enum lsof_error lsof_select_pid(struct lsof_context *ctx, uint32_t pid,
505 int exclude);
506
507 /** Ask lsof to select process by pgid (process group id)
508 *
509 * Select process by comparing pgid. You can specify exclusion by setting
510 * `exclude` to 1.
511 *
512 * You can call this function multiple times to add more search conditions.
513 *
514 * \since API version 1
515 */
516 enum lsof_error lsof_select_pgid(struct lsof_context *ctx, uint32_t pgid,
517 int exclude);
518
519 /** Ask lsof to select process by uid
520 *
521 * Select process whose user id equals to or not equals to `uid`
522 *
523 * You can call this function multiple times to add more search conditions.
524 *
525 * \since API version 1
526 */
527 enum lsof_error lsof_select_uid(struct lsof_context *ctx, uint32_t uid,
528 int exclude);
529
530 /** Ask lsof to select process by user login
531 *
532 * Select process whose user login name equals to or not equals to `login`
533 *
534 * You can call this function multiple times to add more search conditions.
535 *
536 * \since API version 1
537 */
538 enum lsof_error lsof_select_login(struct lsof_context *ctx, char *login,
539 int exclude);
540
541 /** Freeze the lsof context
542 *
543 * You can only call it once per context. After this call, no more options can
544 * be changed.
545 *
546 * The function allows liblsof to do some preprocessing to improve performance.
547 *
548 * \since API version 1
549 */
550 enum lsof_error lsof_freeze(struct lsof_context *ctx);
551
552 /** List open files, grouped by processes
553 *
554 * The result is a struct lsof_result, saved into `result` parameter.
555 *
556 * You should not alter the content of `result`, nor call `free()` to
557 * pointers within. You should free `result` by calling
558 * `lsof_free_result()`
559 *
560 * If the context is not frozen, lsof_freeze() will be called.
561 *
562 * \return LSOF_INVALID_ARGUMENT if either pointer argument is NULL
563 *
564 * \since API version 1
565 */
566 enum lsof_error lsof_gather(struct lsof_context *ctx,
567 struct lsof_result **result);
568
569 /** Destroy a lsof context
570 *
571 * You should call `lsof_free_result` to free all `struct lsof_result`
572 * before destroying the context.
573 *
574 * You must not use the context anymore after this call.
575 *
576 * \since API version 1
577 */
578 void lsof_destroy(struct lsof_context *ctx);
579
580 /** Free struct lsof_result
581 *
582 * \since API version 1
583 */
584 void lsof_free_result(struct lsof_result *result);
585
586 #endif