22.20 The zsh/parameter Module

The zsh/parameter module gives access to some of the internal hash tables used by the shell by defining some special parameters.

options

The keys for this associative array are the names of the options that can be set and unset using the setopt and unsetopt builtins. The value of each key is either the string on if the option is currently set, or the string off if the option is unset. Setting a key to one of these strings is like setting or unsetting the option, respectively. Unsetting a key in this array is like setting it to the value off.

commands

This array gives access to the command hash table. The keys are the names of external commands, the values are the pathnames of the files that would be executed when the command would be invoked. Setting a key in this array defines a new entry in this table in the same way as with the hash builtin. Unsetting a key as in ‘unset "commands[foo]"’ removes the entry for the given key from the command hash table.

functions

This associative array maps names of enabled functions to their definitions. Setting a key in it is like defining a function with the name given by the key and the body given by the value. Unsetting a key removes the definition for the function named by the key.

dis_functions

Like functions but for disabled functions.

functions_source

This readonly associative array maps names of enabled functions to the name of the file containing the source of the function.

For an autoloaded function that has already been loaded, or marked for autoload with an absolute path, or that has had its path resolved with ‘functions -r’, this is the file found for autoloading, resolved to an absolute path.

For a function defined within the body of a script or sourced file, this is the name of that file. In this case, this is the exact path originally used to that file, which may be a relative path.

For any other function, including any defined at an interactive prompt or an autoload function whose path has not yet been resolved, this is the empty string. However, the hash element is reported as defined just so long as the function is present: the keys to this hash are the same as those to $functions.

dis_functions_source

Like functions_source but for disabled functions.

builtins

This associative array gives information about the builtin commands currently enabled. The keys are the names of the builtin commands and the values are either ‘undefined’ for builtin commands that will automatically be loaded from a module if invoked or ‘defined’ for builtin commands that are already loaded.

dis_builtins

Like builtins but for disabled builtin commands.

reswords

This array contains the enabled reserved words.

dis_reswords

Like reswords but for disabled reserved words.

patchars

This array contains the enabled pattern characters.

dis_patchars

Like patchars but for disabled pattern characters.

aliases

This maps the names of the regular aliases currently enabled to their expansions.

dis_aliases

Like aliases but for disabled regular aliases.

galiases

Like aliases, but for global aliases.

dis_galiases

Like galiases but for disabled global aliases.

saliases

Like raliases, but for suffix aliases.

dis_saliases

Like saliases but for disabled suffix aliases.

parameters

The keys in this associative array are the names of the parameters currently defined. The values are strings describing the type of the parameter, in the same format used by the t parameter flag, see Parameter Expansion . Setting or unsetting keys in this array is not possible.

modules

An associative array giving information about modules. The keys are the names of the modules loaded, registered to be autoloaded, or aliased. The value says which state the named module is in and is one of the strings ‘loaded’, ‘autoloaded’, or ‘alias:name’, where name is the name the module is aliased to.

Setting or unsetting keys in this array is not possible.

dirstack

A normal array holding the elements of the directory stack. Note that the output of the dirs builtin command includes one more directory, the current working directory.

history

This associative array maps history event numbers to the full history lines. Although it is presented as an associative array, the array of all values (${history[@]}) is guaranteed to be returned in order from most recent to oldest history event, that is, by decreasing history event number.

historywords

A special array containing the words stored in the history. These also appear in most to least recent order.

jobdirs

This associative array maps job numbers to the directories from which the job was started (which may not be the current directory of the job).

The keys of the associative arrays are usually valid job numbers, and these are the values output with, for example, ${(k)jobdirs}. Non-numeric job references may be used when looking up a value; for example, ${jobdirs[%+]} refers to the current job.

See the jobs builtin for how job information is provided in a subshell.

jobtexts

This associative array maps job numbers to the texts of the command lines that were used to start the jobs.

Handling of the keys of the associative array is as described for jobdirs above.

See the jobs builtin for how job information is provided in a subshell.

jobstates

This associative array gives information about the states of the jobs currently known. The keys are the job numbers and the values are strings of the form ‘job-state:mark:pid=state...’. The job-state gives the state the whole job is currently in, one of ‘running’, ‘suspended’, or ‘done’. The mark is ‘+’ for the current job, ‘-’ for the previous job and empty otherwise. This is followed by one ‘:pid=state’ for every process in the job. The pids are, of course, the process IDs and the state describes the state of that process.

Handling of the keys of the associative array is as described for jobdirs above.

See the jobs builtin for how job information is provided in a subshell.

nameddirs

This associative array maps the names of named directories to the pathnames they stand for.

userdirs

This associative array maps user names to the pathnames of their home directories.

usergroups

This associative array maps names of system groups of which the current user is a member to the corresponding group identifiers. The contents are the same as the groups output by the id command.

funcfiletrace

This array contains the absolute line numbers and corresponding file names for the point where the current function, sourced file, or (if EVAL_LINENO is set) eval command was called. The array is of the same length as funcsourcetrace and functrace, but differs from funcsourcetrace in that the line and file are the point of call, not the point of definition, and differs from functrace in that all values are absolute line numbers in files, rather than relative to the start of a function, if any.

funcsourcetrace

This array contains the file names and line numbers of the points where the functions, sourced files, and (if EVAL_LINENO is set) eval commands currently being executed were defined. The line number is the line where the ‘function name’ or ‘name ()’ started. In the case of an autoloaded function the line number is reported as zero. The format of each element is filename:lineno.

For functions autoloaded from a file in native zsh format, where only the body of the function occurs in the file, or for files that have been executed by the source or ‘.’ builtins, the trace information is shown as filename:0, since the entire file is the definition. The source file name is resolved to an absolute path when the function is loaded or the path to it otherwise resolved.

Most users will be interested in the information in the funcfiletrace array instead.

funcstack

This array contains the names of the functions, sourced files, and (if EVAL_LINENO is set) eval commands. currently being executed. The first element is the name of the function using the parameter.

The standard shell array zsh_eval_context can be used to determine the type of shell construct being executed at each depth: note, however, that is in the opposite order, with the most recent item last, and it is more detailed, for example including an entry for toplevel, the main shell code being executed either interactively or from a script, which is not present in $funcstack.

functrace

This array contains the names and line numbers of the callers corresponding to the functions currently being executed. The format of each element is name:lineno. Callers are also shown for sourced files; the caller is the point where the source or ‘.’ command was executed.