Files
file	stdlib.h

file	string.h

file	types.h

file	wait.h

file	unistd.h

Functions
void	exit (int status)
	Terminate process. More...

char *	strtok (char str, const char delim)
	Tokenize string. More...

pid_t	wait (int *wstatus)
	Wait for a child process. More...

pid_t	waitpid (pid_t pid, int *wstatus, int options)
	Wait for a child process. More...

pid_t	fork (void)
	Fork new process. More...

int	execl (const char path, const char arg0,..., NULL)
	Execute a program. More...

int	execv (const char path, char const argv[])
	Execute a program. More...

int	execlp (const char file, const char arg0,..., NULL)
	Execute a program. More...

int	execvp (const char file, char const argv[])
	Execute a program. More...

Detailed Description

Example of how to create a new process, which executes a program, and wait for the new process to terminate.

// create new process
pid_t pid = fork();
if (pid == 0) {
    // child executes new program
    execlp("ls", "ls", "-A", NULL);
    // execlp() only returns on error
    perror("exec");
    exit(EXIT_FAILURE);
} else if (pid < 0) {
    // fork had an error
    perror("fork");
    exit(EXIT_FAILURE);
}
  
// parent waits for child to terminate
int status;
if (waitpid(pid, &status, 0) < 0) {
     perror("waitpid");
     exit(EXIT_FAILURE);
}

The exec*() function family allows for the execution of a new executable within a process. The differences are:

Function	Searches `PATH`	Array of Arguments	List of Arguments
execl()	✗	✗	✓
execlp()	✓	✗	✓
execv()	✗	✓	✗
execvp()	✓	✓	✗

Function Documentation

void exit ( int status )

The exit() function terminates the current process with the exit code as specified in status. This function does not return.

Examples for typically used exit codes: EXIT_SUCCESS (0), EXIT_FAILURE.

Parameters

status exit code

char* strtok	(	char *	str,
		const char *	delim
	)

The strtok() (string tokenize) function tokenizes the string pointed to by str. For the first call the pointer to the string to be tokenized must be provided. For all subsequent tokens for the same string NULL must be used for str. Be aware, that strtok() manipulates the parsed string (e.g., inserts \0). Each call of strtok() returns a pointer to the next token or NULL if no more tokens are available.

The strtok() function is especially useful to prepare the arguments for a execv() or execvp() system call.

Example:

const char *delim = "|-";
strcpy(buffer, "This|is-an|example!";
printf("%s\n", buffer);
  
char *tok = strtok(buffer, delim);
while (tok != NULL) {
    printf("%s ", tok);
    tok = strtok(NULL, delim);
}
printf("\n");

// produces
$> This|is-an|example!
$> This is an example!

Parameters

str	string to be tokenized
delim	delimiter

Return values

NULL	no more token
!=NULL	pointer to next token

pid_t wait ( int * wstatus )

The wait() function blocks, until at least one child process has been terminated. The call of wait(&status) is equivalent to waitpid(-1, &status, 0). For more information see waitpid().

Parameters

wstatus pointer to an integer value, where wait() will store further information

Return values

pid	of the terminated child process
-1	on error, `errno` is set

pid_t waitpid	(	pid_t	pid,
		int *	wstatus,
		int	options
	)

The waitpid() function blocks until the child process defined by pid terminates. The value of pid can be one of the following values:

Value	Description
`< -1`	wait for any child process where the process group ID equals the absolute value of `pid`
`-1`	wait for any child process
`0`	wait for any child process where the process group ID equals the ID of the calling process
`> 0`	wait for the child process with the defined `pid`

The value in options can be used to further manipulate the behavior of waitpid().

Value	Description
`WNOHANG`	do not block if no child has been terminated (immediately return)
`WUNTRACED`	also return if a child has been stopped
`WCONTINUED`	also return if a child has been resumed (`SIGCONT`)

If wstatus is not NULL, waitpid() stores further information about the termination of the child process in the underlying int. Be aware that the caller must provide the memory for the int and only hands over a pointer! Some macros can be used to extract these information.

Macro	Description
`WIFEXITED(wstatus)`	True if child terminated by calling exit()
`WEXITSTATUS(wstatus)`	Returns the exit code if `WIFEXITED` is true
`WIFSIGNALED(wstatus)`	True if child terminated because of a signal
`WTERMSIG(wstatus)`	Returns the signal number if `WIFSIGNALED` is true

Example:

int status;
if (waitpid(child, &status, WNOHANG) < 0) {
    perror("waitpid");
    exit(EXIT_FAILURE);
}

Parameters

pid	defines child process to wait for
wstatus	pointer to an integer value, where waitpid() will store further information
options	further options

Return values

0	on success
-1	on error, `errno` is set

pid_t fork ( void )

fork() creates a new process by duplicating the calling process. Duplicating means it executes the same program and has the same state (variable values, opened files, ...). The child and parent process can be distinguished by the return value of fork(). For detailed information about differences between the child and the parent see the manpage of fork() (man 2 fork).

If a child process terminates it must be collected by using wait() or waitpid(), otherwise it remains in a zombie state and consumes system resources.

pid_t pid = fork();
if (pid == 0) printf("child\n");
if (pid < 0)  printf("error\n");
if (pid > 0)  printf("parent\n");

Return values

0	child process
>0	child's pid
<0	on error, `errno` is set

int execl	(	const char *	path,
		const char *	arg0,
			...,
		NULL
	)

The execl() function (exec arg list) replaces the currently executed program with the program as specified in path. It hands over all parameters after the path parameter (i.e., arg0, arg1, ...) as arguments for the newly executed program. By convention the first argument is the name of the program itself and the last parameter must be a NULL pointer. Because all arguments are handed over in a list, the number of arguments is fixed at compile time. This is the most important difference to the execv() and execvp() function.

Any exec*() function only returns, if an error occurs. The errno is set appropriately, so call perror("exec"); after the call to a exec*() function.

Example to execute the program ls -lA:

execl("/bin/ls", "/bin/ls", "-lA", NULL);

perror("exec");

execl

int execl(const char *path, const char *arg0,..., NULL)

Execute a program.

Parameters

path	path to the executable
arg0	first argument (by convention: executable file name)
...	all further arguments (terminated by a `NULL` pointer)

Returns: -1 on error, errno is set

int execv	(	const char *	path,
		char *const	argv[]
	)

The execv() function (exec arg vector) replaces the currently executed program with the program as specified in path. It hands over the argv parameter as arguments to the newly executed program. By convention the first argument (argv[0]) is the name of the program itself and the last parameter must be a NULL pointer. Because of the usage of a array for the arguments, the number of arguments is not fixed at compile time, but can be determined at run time. This is the most important difference to the execl() and execlp() function.

Any exec*() function only returns, if an error occurs. The errno is set appropriately, so call perror("exec"); after the call to a exec*() function.

Example to execute the program ls -lA:

char *args[3];
args[0] = "/bin/ls";
args[1] = "-lA";
args[2] = NULL;
  
execv(args[0], args);
perror("exec");

Parameters

path	path to the executable
argv	array of arguments (terminated by `NULL` pointer)

Returns: -1 on error, errno is set

int execlp	(	const char *	file,
		const char *	arg0,
			...,
		NULL
	)

Same as execl(), but also searches the PATH environment variable if file does not contain a slash /. This means regular shell commands like ls are available.

See execl() for further information.

Returns: -1 on error, errno is set

int execvp	(	const char *	file,
		char *const	argv[]
	)

Same as execv(), but also searches the PATH environment variable if file does not contain a slash /. This means regular shell commands like ls are available.

See execv() for further information.

Returns: -1 on error, errno is set

Linux libc-doc

Files

Functions

Detailed Description

Function Documentation