|
rush
Revamped UNIX Shell
|
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 ProcInfo * | plistAdd (pid_t pid, const char cmdLine[], bool background) |
| Adds a new process to the list. More... | |
| const ProcInfo * | plistGet (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... | |
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().
| 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().
| pid | Process ID of the entry that is to be created. |
| cmdLine | Command line corresponding to the process with ID pid. |
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.malloc() to allocate memory on the heap. | 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).
| 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.
| callback | Pointer to the function to be invoked for each list element. |
| 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.
| callback | Pointer to the function to be invoked for each list element. |
| 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.
| pid | ID of the process. |
| event | Event that changed the process status as retrieved from waitpid(). |
| 0 | Success. |
| -1 | No process with the given PID was found in the list. |
| int plistRemove | ( | pid_t | pid | ) |
Removes a specific process from the list.
| pid | ID of the process to be removed. |
| 0 | Success. |
| -1 | No process with the given PID was found in the list. |
free() to release memory to the heap. 1.9.4