rush
Revamped UNIX Shell
Data Structures | Functions
plist.h File Reference

List for bookkeeping of a shell's child processes. More...

#include <stdbool.h>
#include <sys/types.h>

Go to the source code of this file.

Data Structures

struct  ProcInfo
 Process-information structure. More...
 

Functions

const ProcInfoplistAdd (pid_t pid, const char cmdLine[], bool background)
 Adds a new process to the list. More...
 
const ProcInfoplistGet (pid_t pid)
 
int plistRemove (pid_t pid)
 Removes a specific process from the list. More...
 
int plistIterate (int(*callback)(const ProcInfo *))
 Invokes a callback function on each element in the list whose state has not changed since the last call to plistHandleEvents(). More...
 
int plistNotifyEvent (pid_t pid, int event)
 Notifies the process list that a process has changed its state. More...
 
int plistHandleEvents (int(*callback)(const ProcInfo *, int))
 Invokes a callback function on each element in the list whose state has changed since the last call to plistHandleEvents(). More...
 

Detailed Description

List for bookkeeping of a shell's child processes.

Since SUSv4 offers no portable way to determine the current state of a process, the shell itself has to keep a record of its child processes and their current states.

Newly created processes can be added with plistAdd(), while terminated processes can be removed with plistRemove().

Information about a specific process can be obtained by calling plistGet(). To iterate over the entire list of child processes, plistIterate() can be used.

When a child process has changed its state (which is signaled to the shell via SIGCHLD), the shell must update the process entry by calling plistNotifyEvent(). The processes which have recently changed their state can be obtained and processed with plistHandleEvents().

Function Documentation

◆ plistAdd()

const ProcInfo* plistAdd ( pid_t  pid,
const char  cmdLine[],
bool  background 
)

Adds a new process to the list.

The process is assumed to be in the running state.

During the insert operation, the passed cmdLine is copied to an internally allocated buffer. The caller may free or otherwise reuse the memory occupied by cmdLine after return from plistAdd().

Parameters
pidProcess ID of the entry that is to be created.
cmdLineCommand line corresponding to the process with ID pid.
Returns
Pointer to the created entry. If an error occurs, NULL is returned and errno is set accordingly:
  • EINVAL: An entry with the given PID already exists in the list.
  • ENOMEM: A memory allocation has failed.
Note
This function should not be used in a signal handler since it uses malloc() to allocate memory on the heap.

◆ plistGet()

const ProcInfo* plistGet ( pid_t  pid)

Returns the process information for a specific PID.

If no entry with that PID exists or if the respective entry has changed its state since the last call to plistHandleEvents(), NULL is returned.

The data returned by this function will only be valid until the respective entry has been removed from the list. It is the caller's responsibility to copy data that is needed for a longer period of time (if any).

Note
This function can be safely used in a signal handler provided it does not overlap any other calls to a plist operation.

◆ plistHandleEvents()

int plistHandleEvents ( int(*)(const ProcInfo *, int)  callback)

Invokes a callback function on each element in the list whose state has changed since the last call to plistHandleEvents().

This function only handles processes whose status change has been signaled via plistNotifyEvent(). Newly added processes are not regarded. If a process has changed its state multiple times, only the last change is handled.

For each element that is processed, the state-change flag is reset.

The callback function is passed the process information of the current list element, along with the event that has caused the state change. It shall return 0 to request further processing of the list. Any other return value will cause the early termination of the list walk.

The callback function may remove the current element by calling plistRemove(), but must not modify the process list in any other way.

Parameters
callbackPointer to the function to be invoked for each list element.
Returns
0 if the entire process list was walked, otherwise the value returned by the last invocation of the callback function.
Note
This function can be safely used in a signal handler provided it does not overlap any other calls to a plist operation.

◆ plistIterate()

int plistIterate ( int(*)(const ProcInfo *)  callback)

Invokes a callback function on each element in the list whose state has not changed since the last call to plistHandleEvents().

The callback function is passed the process information of the current list element. It shall return 0 to request further processing of the list. Any other return value will cause the early termination of the list walk.

The callback function may remove the current element by calling plistRemove(), but must not modify the process list in any other way.

Parameters
callbackPointer to the function to be invoked for each list element.
Returns
0 if the entire process list was walked, otherwise the value returned by the last invocation of the callback function.
Note
This function can be safely used in a signal handler provided it does not overlap any other calls to a plist operation.

◆ plistNotifyEvent()

int plistNotifyEvent ( pid_t  pid,
int  event 
)

Notifies the process list that a process has changed its state.

The process's new state is determined by evaluating event, which should be retrieved using waitpid().

A flag is set for the list element to indicate the change. plistHandleEvents() can be used to query the processes whose state-change flag is set.

Parameters
pidID of the process.
eventEvent that changed the process status as retrieved from waitpid().
Return values
0Success.
-1No process with the given PID was found in the list.
Note
This function can be safely used in a signal handler provided it does not overlap any other calls to a plist operation.

◆ plistRemove()

int plistRemove ( pid_t  pid)

Removes a specific process from the list.

Parameters
pidID of the process to be removed.
Return values
0Success.
-1No process with the given PID was found in the list.
Note
This function should not be used in a signal handler since it uses free() to release memory to the heap.