proc.h File Reference

Prototypes for utilities for keeping track of jobs, processes and subshells, as well as signal handling functions for tracking children. More...

#include <wchar.h>
#include <signal.h>
#include <unistd.h>
#include <sys/time.h>
#include "util.h"
#include "io.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	process
	A structure representing a single fish process. More...
struct	job
	A struct represeting a job. More...
Defines
#define	STATUS_UNKNOWN_COMMAND   127
	The status code use when a command was not found.
#define	STATUS_NOT_EXECUTABLE   126
	The status code use when an unknown error occured during execution of a command.
#define	STATUS_EXEC_FAIL   125
	The status code use when an unknown error occured during execution of a command.
#define	STATUS_UNMATCHED_WILDCARD   124
	The status code use when a wildcard had no matches.
#define	STATUS_BUILTIN_OK   0
	The status code used for normal exit in a builtin.
#define	STATUS_BUILTIN_ERROR   1
	The status code used for erroneous argument combinations in a builtin.
#define	JOB_NOTIFIED   1
	Constant for the flag variable in the job struct.
#define	JOB_FOREGROUND   2
	Constant for the flag variable in the job struct.
#define	JOB_CONSTRUCTED   4
	Constant for the flag variable in the job struct.
#define	JOB_SKIP_NOTIFICATION   8
	Constant for the flag variable in the job struct.
#define	JOB_NEGATE   16
	Constant for the flag variable in the job struct.
#define	JOB_WILDCARD_ERROR   32
	Constant for the flag variable in the job struct.
#define	JOB_SKIP   64
	Constant for the flag variable in the job struct.
#define	JOB_CONTROL   128
	Constant for the flag variable in the job struct.
#define	JOB_TERMINAL   256
	Constant for the flag variable in the job struct.
Typedefs
typedef struct process	process_t
	A structure representing a single fish process.
typedef struct job	job_t
	A struct represeting a job.
Enumerations
enum	{   EXTERNAL, INTERNAL_BUILTIN, INTERNAL_FUNCTION, INTERNAL_BLOCK,   INTERNAL_EXEC, INTERNAL_BUFFER }
	Types of processes. More...
enum	{ JOB_CONTROL_ALL, JOB_CONTROL_INTERACTIVE, JOB_CONTROL_NONE }
Functions
void	job_set_flag (job_t *j, int flag, int set)
	Add the specified flag to the bitset of flags for the specified job.
int	job_get_flag (job_t *j, int flag)
	Returns one if the specified flag is set in the specified job, 0 otherwise.
void	proc_set_last_status (int s)
	Sets the status of the last process to exit.
int	proc_get_last_status ()
	Returns the status of the last process to exit.
void	job_free (job_t *j)
	Remove the specified job.
job_t *	job_create ()
	Create a new job.
job_t *	job_get (int id)
	Return the job with the specified job id.
job_t *	job_get_from_pid (int pid)
	Return the job with the specified pid.
int	job_is_stopped (const job_t *j)
	Tests if the job is stopped.
int	job_is_completed (const job_t *j)
	Tests if the job has completed, i.e.
void	job_continue (job_t *j, int cont)
	Reassume a (possibly) stopped job.
int	job_reap (int interactive)
	Notify the user about stopped or terminated jobs.
void	job_handle_signal (int signal, siginfo_t *info, void *con)
	Signal handler for SIGCHLD.
int	job_signal (job_t *j, int signal)
	Send the specified signal to all processes in the specified job.
void	proc_sanity_check ()
	Perform a set of simple sanity checks on the job list.
void	proc_fire_event (const wchar_t *msg, int type, pid_t pid, int status)
	Send a process/job exit event notification.
void	proc_init ()
	Initializations.
void	proc_destroy ()
	Clean up before exiting.
void	proc_push_interactive (int value)
	Set new value for is_interactive flag, saving previous value.
void	proc_pop_interactive ()
	Set is_interactive flag to the previous value.
int	proc_format_status (int status)
	Format an exit status code as returned by e.g.
Variables
int	is_subshell
	Whether we are running a subshell command.
int	is_block
	Whether we are running a block of commands.
int	is_interactive
	Whether we are reading from the keyboard right now.
int	is_interactive_session
	Whether this shell is attached to the keyboard at all.
int	is_login
	Whether we are a login shell.
int	is_event
	Whether we are running an event handler.
job_t *	first_job
	Linked list of all living jobs.
int	proc_had_barrier
	Whether a universal variable barrier roundtrip has already been made for the currently executing command.
pid_t	proc_last_bg_pid
	Pid of last process to be started in the background.
int	job_control_mode
	The current job control mode.
int	no_exec
	If this flag is set, fish will never fork or run execve.

---

Detailed Description

Prototypes for utilities for keeping track of jobs, processes and subshells, as well as signal handling functions for tracking children.

These functions do not themselves launch new processes, the exec library will call proc to create representations of the running jobs as needed.

---

Define Documentation

#define JOB_CONSTRUCTED   4

Constant for the flag variable in the job struct.

Whether the specified job is completely constructed, i.e. completely parsed, and every process in the job has been forked, etc.

Referenced by builtin_fg(), builtin_jobs(), exec(), and proc_sanity_check().

#define JOB_CONTROL   128

Constant for the flag variable in the job struct.

Whether the job is under job control

Referenced by builtin_bg(), builtin_fg(), eval_job(), exec(), job_continue(), job_create(), send_to_bg(), and set_child_group().

#define JOB_FOREGROUND   2

Constant for the flag variable in the job struct.

Whether this job is in the foreground

Referenced by builtin_fg(), eval_job(), exec(), job_continue(), job_reap(), parse_job_argument_list(), proc_sanity_check(), send_to_bg(), and set_child_group().

#define JOB_NEGATE   16

Constant for the flag variable in the job struct.

Should the exit status be negated? This flag can only be set by the not builtin.

Referenced by exec(), job_continue(), and parse_job().

#define JOB_NOTIFIED   1

Constant for the flag variable in the job struct.

true if user was told about stopped job

Referenced by job_continue(), and job_reap().

#define JOB_SKIP   64

Constant for the flag variable in the job struct.

Skip executing this job. This flag is set by the short-circut builtins, i.e. and and or

Referenced by eval_job(), parse_job(), and parse_job_argument_list().

#define JOB_SKIP_NOTIFICATION   8

Constant for the flag variable in the job struct.

Whether the specified job is a part of a subshell, event handler or some other form of special job that should not be reported

Referenced by eval_job(), and job_reap().

#define JOB_TERMINAL   256

Constant for the flag variable in the job struct.

Whether the job wants to own the terminal when in the foreground

Referenced by eval_job(), job_continue(), and set_child_group().

#define JOB_WILDCARD_ERROR   32

Constant for the flag variable in the job struct.

This flag is set to one on wildcard expansion errors. It means that the current command should not be executed

Referenced by eval_job(), and parse_job_argument_list().

---

Typedef Documentation

typedef struct job job_t

A struct represeting a job.

A job is basically a pipeline of one or more processes and a couple of flags.

typedef struct process process_t

A structure representing a single fish process.

Contains variables for tracking process state and the process argument list. Actually, a fish process can be either a regular externa lrocess, an internal builtin which may or may not spawn a fake IO process during execution, a shellscript function or a block of commands to be evaluated by calling eval. Lastly, this process can be the result of an exec command. The role of this process_t is determined by the type field, which can be one of EXTERNAL, INTERNAL_BUILTIN, INTERNAL_FUNCTION, INTERNAL_BLOCK and INTERNAL_EXEC, INTERNAL_BUFFER

The process_t contains information on how the process should be started, such as command name and arguments, as well as runtime information on the status of the actual physical process which represents it. Shellscript functions, builtins and blocks of code may all need to spawn an external process that handles the piping and redirecting of IO for them.

If the process is of type EXTERNAL or INTERNAL_EXEC, argv is the argument array and actual_cmd is the absolute path of the command to execute.

If the process is of type INTERNAL_BUILTIN, argv is the argument vector, and argv[0] is the name of the builtin command.

If the process is of type INTERNAL_FUNCTION, argv is the argument vector, and argv[0] is the name of the shellscript function.

If the process is of type INTERNAL_BLOCK, argv has exactly one element, which is the block of commands to execute.

---

Enumeration Type Documentation

anonymous enum

Types of processes.

Enumerator:

EXTERNAL	A regular external command.
INTERNAL_BUILTIN	A builtin command.
INTERNAL_FUNCTION	A shellscript function.
INTERNAL_BLOCK	A block of commands.
INTERNAL_EXEC	The exec builtin.
INTERNAL_BUFFER	A buffer.

---

Function Documentation

void job_continue	(	job_t *	j,
		int	cont
	)

Reassume a (possibly) stopped job.

Put job j in the foreground. If cont is nonzero, restore the saved terminal modes and send the process group a SIGCONT signal to wake it up before we block.

Parameters:

	j	The job
	cont	Whether the function should wait for the job to complete before returning

References CHECK_BLOCK, job::command, debug(), job::first_process, got_signal, handle_child_status(), is_interactive, JOB_CONTROL, JOB_FOREGROUND, job_get_flag(), job::job_id, job_is_completed(), job_is_stopped(), JOB_NEGATE, JOB_NOTIFIED, job_remove(), job_set_flag(), JOB_TERMINAL, process::next, job::next, job::pgid, process::pid, proc_format_status(), proc_set_last_status(), quit, read_try(), reader_exit_forced(), select_try(), signal_block(), signal_unblock(), process::status, process::stopped, terminal_give_to_job(), terminal_return_from_job(), and wperror().

Referenced by builtin_fg(), exec(), and send_to_bg().

job_t* job_create

(

)

Create a new job.

Job struct is allocated using halloc, so anything that should be freed with the job can uset it as a halloc context when allocating.

References halloc(), is_interactive, JOB_CONTROL, job_control_mode, job_get(), job::job_id, job_set_flag(), and job::next.

Referenced by eval_job().

job_t* job_get

(

int

id

)

Return the job with the specified job id.

If id is 0 or less, return the last job used.

References job::job_id, and job::next.

Referenced by event_get_desc(), find_process(), functions_def(), and job_create().

void job_handle_signal	(	int	signal,
		siginfo_t *	info,
		void *	con
	)

Signal handler for SIGCHLD.

Mark any processes with relevant information.

References got_signal, and handle_child_status().

Referenced by handle_chld().

int job_is_completed

(

const job_t *

j

)

Tests if the job has completed, i.e.

if the last process of the pipeline has ended.

References process::completed, job::first_process, and process::next.

Referenced by builtin_bg(), builtin_fg(), builtin_jobs(), handle_end_loop(), job_continue(), job_reap(), and proc_sanity_check().

int job_reap

(

int

interactive

)

Notify the user about stopped or terminated jobs.

Delete terminated jobs from the job list.

Parameters:

interactive

whether interactive jobs should be reaped as well

References _, process::argv, job::command, process::completed, EVENT_EXIT, EVENT_JOB_ID, job::first_process, format_job_info(), JOB_FOREGROUND, job_free(), job_get_flag(), job::job_id, job_is_completed(), job_is_stopped(), JOB_NOTIFIED, job_set_flag(), JOB_SKIP_NOTIFICATION, process::next, job::next, job::pgid, process::pid, proc_fire_event(), program_name, sig2wcs(), signal_get_desc(), process::status, and writeb().

Referenced by eval(), eval_job(), internal_exec_helper(), interrupt_handler(), and reader_run_command().

void proc_fire_event	(	const wchar_t *	msg,
		int	type,
		pid_t	pid,
		int	status
	)

Send a process/job exit event notification.

This function is a conveniance wrapper around event_fire().

References al_push(), al_truncate(), event_t::arguments, buffer::buff, event_fire(), sb_clear(), and sb_printf().

Referenced by job_reap(), and main().

int proc_format_status

(

int

status

)

Format an exit status code as returned by e.g.

wait into a fish exit code number as accepted by proc_set_last_status.

Referenced by exec(), and job_continue().

void proc_pop_interactive

(

)

Set is_interactive flag to the previous value.

If needed, update signal handlers.

References al_pop_long(), is_interactive, and signal_set_handlers().

Referenced by builtin_read(), complete_from_args(), eval_args(), event_fire_internal(), exec_prompt(), reader_read(), and reader_write_title().

void proc_push_interactive

(

int

value

)

Set new value for is_interactive flag, saving previous value.

If needed, update signal handlers.

References al_push_long(), is_interactive, and signal_set_handlers().

Referenced by builtin_read(), complete_from_args(), eval_args(), event_fire_internal(), exec_prompt(), proc_init(), reader_read(), and reader_write_title().

void proc_sanity_check

(

)

Perform a set of simple sanity checks on the job list.

This includes making sure that only one job is in the foreground, that every process is in a valid state, etc.

References _, process::actual_cmd, process::argv, job::command, process::completed, debug(), job::first_process, JOB_CONSTRUCTED, JOB_FOREGROUND, job_get_flag(), job_is_completed(), job_is_stopped(), process::next, job::next, sanity_lose(), process::stopped, and validate_pointer().

Referenced by sanity_check().

---

Variable Documentation

int job_control_mode

The current job control mode.

Must be one of JOB_CONTROL_ALL, JOB_CONTROL_INTERACTIVE and JOB_CONTROL_NONE

Referenced by builtin_status(), and job_create().

int no_exec

If this flag is set, fish will never fork or run execve.

It is used to put fish into a syntax verifier mode where fish tries to validate the syntax of a file but doesn't actually do anything.

Referenced by exec(), fish_parse_opt(), and main().

int proc_had_barrier

Whether a universal variable barrier roundtrip has already been made for the currently executing command.

Such a roundtrip only needs to be done once on a given command, unless a universal variable value is changed. Once this has been done, this variable is set to 1, so that no more roundtrips need to be done.

Both setting it to one when it should be zero and the opposite may cause concurrency bugs.

Referenced by env_exist(), env_export_arr(), env_get(), env_set(), and eval_job().