liblinux

Section: Linux Simple I/O Library (2)
Updated: 23 January 2024
Index Return to Main Contents

NAME

liblinux -- Linux Simple I/O Library: Linux System Call Wrapper Module

SYNOPSIS

#include <libsimpleio/liblinux.h>

void LINUX_detach(int32_t *error);

void LINUX_drop_privileges(const char *username, int32_t *error);

void LINUX_openlog(const char *id, int32_t options, int32_t facility,
  int32_t *error);

void LINUX_syslog(int32_t priority, const char *msg, int32_t *error);

void LINUX_closelog(int32_t *error);

int32_t LINUX_errno(void);

void LINUX_strerror(int32_t error, char *buf, int32_t bufsize);

void LINUX_poll(int32_t numfiles, int32_t *files, int32_t *events,
  int32_t *results, int32_t timeout, int32_t *error);

void LINUX_usleep(int32_t microseconds, int32_t *error);

void LINUX_command(const char *cmd, int32_t *status, int32_t *error);

void LINUX_popen_read(const char *cmd, void **stream, int32_t *error);

void LINUX_popen_write(const char *cmd, void **stream, int32_t *error);

void LINUX_pclose(void *stream, int32_t *error);

void *LINUX_indexpp(void **p, int32_t i);

const char * const LINUX_model_name(void);

Link with -lsimpleio.

DESCRIPTION

These functions wrap certain useful Linux system calls for use by other programming languages such as Ada, C#, Free Pascal, and Go. They are provided for the convenience of devlopers using libsimpleio with those langauges. For the C programming language, they offer no particular benefit over the regular system call wrappers.

All functions return either 0 (upon success) or an errno value (upon failure) in *error.

LINUX_detach() detaches the calling process from its controlling terminal and continues execution in the background.

LINUX_drop_privileges() allows a process started by the superuser to drop its privileges to those of the user specified by the username parameter.

LINUX_openlog() opens a connection to the syslog message logger. The options and facility parameters accept the same values as the openlog() system library function.

LINUX_syslog() transmits a text message supplied in the msg parameter to the syslog message logger. The priority parameter accepts the same values as the syslog() system library function.

LINUX_closelog() closes the connection to the syslog message logger.

LINUX_errno() returns the current value of the errno variable.

LINUX_strerror() retrieves the error message for the errno value passed in the error parameter. A destination buffer address and size must be passed in the buf and bufsize parameters.

LINUX_poll() waits for events on an set of file descriptors. The number of file descriptors is passed in the numfiles parameter. An array of file descriptors is passed in the files parameter. An array of requested events, using the same values as the poll() system library function, is passed in the events parameter. The results for each file descriptor, also using the same values as the poll() system library function, will be returned in the results parameter. A timeout in milliseconds may be passed in the timeout parameter. A timeout of zero indicates an immediate return without waiting at all. A timeout of -1 indicates waiting forever. If the timeout expires without any event on any file descriptor occurring, then error will be set to EAGAIN.

LINUX_usleep() causes the calling program to sleep for the period indicated by microseconds, by calling the usleep() system library function.

LINUX_command() passes the shell command string specified by the cmd parameter to the system() system library function for execution. The return value from the shell command will be returned in status.

LINUX_popen_read() opens a pipe for reading standard output from another program. The shell command string for running the program must be passed in the cmd parameter. The FILE pointer for the pipe will be returned in the stream parameter.

LINUX_popen_read() opens a pipe for writing standard input to another program. The shell command string for running the program must be passed in the cmd parameter. The FILE pointer for the pipe will be returned in the stream parameter.

LINUX_pclose() closes a pipe opened by LINUX_popen_read() or Linux_popen_close(). The FILE pointer for the pipe must be passed in the stream parameter.

LINUX_indexpp() is a helper function that indexes a C pointer to pointer(s). It returns either the selected element or NULL if the p parameter is NULL or if the i parameter is less than zero.

LINUX_model_name() returns the contents of /proc/device-tree/model or an empty string if that file cannot be read.

AUTHOR

Philip Munts dba Munts Technologies.