Skip to content

Reject NULL contexts in liblsof API (#378) #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hugojosealmeida wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Reject NULL contexts in liblsof API (#378) #381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6f11b5
Reject NULL contexts at liblsof API entry points
hugojosealmeida Nov 2, 2026
d47d9d4
Document invalid-argument returns across the public API
hugojosealmeida Nov 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ lib/dialects/netbsd/include
#
LTbasic
LTbasic2
LTnull
LTbigf
LTdnlc
LTlock
Expand Down
8 changes: 5 additions & 3 deletions Makefile.am
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,12 +212,14 @@ tests_LTszoff_CFLAGS = @LSOF_TEST_CFLAGS@ -I$(top_srcdir)/include
tests_LTunix_SOURCES = tests/LTunix.c tests/LTlib.c
tests_LTunix_CFLAGS = @LSOF_TEST_CFLAGS@ -I$(top_srcdir)/include

# LTbasic2 links against liblsof, only build when liblsof is enabled
# Library tests, only build when liblsof is enabled
if INSTALL_LIBLSOF
TESTS += tests/LTbasic2
check_PROGRAMS += tests/LTbasic2
TESTS += tests/LTbasic2 tests/LTnull
check_PROGRAMS += tests/LTbasic2 tests/LTnull
tests_LTbasic2_CFLAGS = @LSOF_TEST_CFLAGS@ -I$(top_srcdir)/include
tests_LTbasic2_LDADD = liblsof.la
tests_LTnull_CFLAGS = -I$(top_srcdir)/include
tests_LTnull_LDADD = liblsof.la
endif

# Documentation
Expand Down
30 changes: 29 additions & 1 deletion include/lsof.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,6 +427,8 @@ struct lsof_context *lsof_new();
* By default, the output is suppressed. You can set fp to NULL to suppress
* output.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL
*
* \since API version 1
*/
enum lsof_error lsof_set_output_stream(struct lsof_context *ctx, FILE *fp,
Expand All @@ -437,6 +439,8 @@ enum lsof_error lsof_set_output_stream(struct lsof_context *ctx, FILE *fp,
* lsof may block when calling lstat(), readlink() or stat(). Call this function
* with `avoid=1` to let lsof avoid calling these functions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen
*
* \since API version 1
*/
enum lsof_error lsof_avoid_blocking(struct lsof_context *ctx, int avoid);
Expand All @@ -446,6 +450,8 @@ enum lsof_error lsof_avoid_blocking(struct lsof_context *ctx, int avoid);
* To avoid being blocked by some kernel operations, liblsof does them in forked
* child processes. Call this function to change this behavior.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen
*
* \since API version 1
*/
enum lsof_error lsof_avoid_forking(struct lsof_context *ctx, int avoid);
Expand All @@ -457,6 +463,8 @@ enum lsof_error lsof_avoid_forking(struct lsof_context *ctx, int avoid);
* sockets OR open files by the user. If lsof_logic_and() is called, it will
* report unix sockets open by the specified user.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen
*
* \since API version 1
*/
enum lsof_error lsof_logic_and(struct lsof_context *ctx);
Expand All @@ -468,6 +476,9 @@ enum lsof_error lsof_logic_and(struct lsof_context *ctx);
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, command is
* both included and excluded, or command exceeds the system's supported length
*
* \since API version 1
*/
enum lsof_error lsof_select_process(struct lsof_context *ctx, char *command,
Expand All @@ -488,6 +499,9 @@ enum lsof_error lsof_select_process(struct lsof_context *ctx, char *command,
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, or the regular
* expression or its modifiers are invalid
*
* \since API version 1
*/
enum lsof_error lsof_select_process_regex(struct lsof_context *ctx,
Expand All @@ -500,6 +514,9 @@ enum lsof_error lsof_select_process_regex(struct lsof_context *ctx,
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, or pid is
* both included and excluded
*
* \since API version 1
*/
enum lsof_error lsof_select_pid(struct lsof_context *ctx, uint32_t pid,
Expand All @@ -512,6 +529,9 @@ enum lsof_error lsof_select_pid(struct lsof_context *ctx, uint32_t pid,
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, or pgid is
* both included and excluded
*
* \since API version 1
*/
enum lsof_error lsof_select_pgid(struct lsof_context *ctx, uint32_t pgid,
Expand All @@ -523,6 +543,9 @@ enum lsof_error lsof_select_pgid(struct lsof_context *ctx, uint32_t pgid,
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, or uid is
* both included and excluded
*
* \since API version 1
*/
enum lsof_error lsof_select_uid(struct lsof_context *ctx, uint32_t uid,
Expand All @@ -534,6 +557,9 @@ enum lsof_error lsof_select_uid(struct lsof_context *ctx, uint32_t uid,
*
* You can call this function multiple times to add more search conditions.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or frozen, login cannot
* be resolved to a UID, or that UID is both included and excluded
*
* \since API version 1
*/
enum lsof_error lsof_select_login(struct lsof_context *ctx, char *login,
Expand All @@ -546,6 +572,8 @@ enum lsof_error lsof_select_login(struct lsof_context *ctx, char *login,
*
* The function allows liblsof to do some preprocessing to improve performance.
*
* \return LSOF_ERROR_INVALID_ARGUMENT if ctx is NULL or already frozen
*
* \since API version 1
*/
enum lsof_error lsof_freeze(struct lsof_context *ctx);
Expand All @@ -560,7 +588,7 @@ enum lsof_error lsof_freeze(struct lsof_context *ctx);
*
* If the context is not frozen, lsof_freeze() will be called.
*
* \return LSOF_INVALID_ARGUMENT if either pointer argument is NULL
* \return LSOF_ERROR_INVALID_ARGUMENT if either pointer argument is NULL

@jiegec jiegec Nov 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add this annotation to other functions?

@hugojosealmeida hugojosealmeida Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LSOF_INVALID_ARGUMENT is not used by any function and is not defined. It was only a typo in this one documentation comment.

@jiegec jiegec Nov 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean, other functions could have \return annotations like this as well.

*
* \since API version 1
*/
Expand Down
15 changes: 11 additions & 4 deletions lib/lsof.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@ enum lsof_error lsof_set_output_stream(struct lsof_context *ctx, FILE *fp,

API_EXPORT
enum lsof_error lsof_freeze(struct lsof_context *ctx) {
if (ctx->frozen) {
if (!ctx || ctx->frozen) {
return LSOF_ERROR_INVALID_ARGUMENT;
}

Expand Down Expand Up @@ -283,7 +283,7 @@ enum lsof_error lsof_gather(struct lsof_context *ctx,
struct lsof_process *user_procs = NULL;
struct lsof_result *res = NULL;

if (!result) {
if (!ctx || !result) {
ret = LSOF_ERROR_INVALID_ARGUMENT;
return ret;
} else if (!ctx->frozen) {
Expand Down Expand Up @@ -1192,8 +1192,12 @@ enum lsof_error lsof_select_pid_pgid(struct lsof_context *ctx, int32_t id,
API_EXPORT
enum lsof_error lsof_select_pid(struct lsof_context *ctx, uint32_t pid,
int exclude) {
enum lsof_error res = lsof_select_pid_pgid(ctx, pid, &Spid, &Mxpid, &Npid,
&Npidi, &Npidx, exclude, 1);
enum lsof_error res;
if (!ctx) {
return LSOF_ERROR_INVALID_ARGUMENT;
}
res = lsof_select_pid_pgid(ctx, pid, &Spid, &Mxpid, &Npid, &Npidi, &Npidx,
exclude, 1);
/* Record number of unselected PIDs for optimization */
Npuns = Npid;
return res;
Expand All @@ -1202,6 +1206,9 @@ enum lsof_error lsof_select_pid(struct lsof_context *ctx, uint32_t pid,
API_EXPORT
enum lsof_error lsof_select_pgid(struct lsof_context *ctx, uint32_t pgid,
int exclude) {
if (!ctx) {
return LSOF_ERROR_INVALID_ARGUMENT;
}
return lsof_select_pid_pgid(ctx, pgid, &Spgid, &Mxpgid, &Npgid, &Npgidi,
&Npgidx, exclude, 0);
}
Expand Down
38 changes: 38 additions & 0 deletions tests/LTnull.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/* LTnull.c -- public liblsof entry points must reject NULL arguments. */

#include "lsof.h"
#include <stdio.h>

static int expect_invalid(const char *name, enum lsof_error result) {
if (result == LSOF_ERROR_INVALID_ARGUMENT)
return 0;
fprintf(stderr, "%s: expected invalid argument, got %d\n", name, result);
return 1;
}

int main(void) {
struct lsof_context *ctx;
struct lsof_result *result = NULL;
int failed = 0;

failed |= expect_invalid("gather(NULL, &result)", lsof_gather(NULL, &result));
failed |= expect_invalid("gather(NULL, NULL)", lsof_gather(NULL, NULL));
failed |= expect_invalid("freeze(NULL)", lsof_freeze(NULL));
failed |= expect_invalid("select_pid(NULL)", lsof_select_pid(NULL, 1, 0));
failed |= expect_invalid("select_pgid(NULL)", lsof_select_pgid(NULL, 1, 0));

ctx = lsof_new();
if (!ctx) {
fprintf(stderr, "lsof_new failed\n");
return 1;
}
failed |= expect_invalid("gather(ctx, NULL)", lsof_gather(ctx, NULL));
/* Rejected arguments must not freeze or otherwise invalidate the context. */
if (lsof_select_pid(ctx, 1, 0) != LSOF_SUCCESS ||
lsof_select_pgid(ctx, 1, 0) != LSOF_SUCCESS) {
fprintf(stderr, "context is unusable after rejected gather\n");
failed = 1;
}
lsof_destroy(ctx);
return failed;
}
Loading