File: //usr/share/zsh/help/zmodload
zmodload [ -dL ] [ -s ] [ ... ]
zmodload -F [ -alLme -P param ] module [ [+-]feature ... ]
zmodload -e [ -A ] [ ... ]
zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...
zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...
zmodload -A [ -L ] [ modalias[=module] ... ]
zmodload -R modalias ...
Performs operations relating to zsh's loadable modules. Loading
of modules while the shell is running (`dynamical loading') is
not available on all operating systems, or on all installations
on a particular operating system, although the zmodload command
itself is always available and can be used to manipulate modules
built into versions of the shell executable without dynamical
loading.
Without arguments the names of all currently loaded binary mod-
ules are printed. The -L option causes this list to be in the
form of a series of zmodload commands. Forms with arguments
are:
zmodload [ -is ] name ...
zmodload -u [ -i ] name ...
In the simplest case, zmodload loads a binary module.
The module must be in a file with a name consisting of
the specified name followed by a standard suffix, usually
`.so' (`.sl' on HPUX). If the module to be loaded is al-
ready loaded the duplicate module is ignored. If zmod-
load detects an inconsistency, such as an invalid module
name or circular dependency list, the current code block
is aborted. If it is available, the module is loaded if
necessary, while if it is not available, non-zero status
is silently returned. The option -i is accepted for com-
patibility but has no effect.
The named module is searched for in the same way a com-
mand is, using $module_path instead of $path. However,
the path search is performed even when the module name
contains a `/', which it usually does. There is no way
to prevent the path search.
If the module supports features (see below), zmodload
tries to enable all features when loading a module. If
the module was successfully loaded but not all features
could be enabled, zmodload returns status 2.
If the option -s is given, no error is printed if the
module was not available (though other errors indicating
a problem with the module are printed). The return sta-
tus indicates if the module was loaded. This is appro-
priate if the caller considers the module optional.
With -u, zmodload unloads modules. The same name must be
given that was given when the module was loaded, but it
is not necessary for the module to exist in the file sys-
tem. The -i option suppresses the error if the module is
already unloaded (or was never loaded).
Each module has a boot and a cleanup function. The mod-
ule will not be loaded if its boot function fails. Simi-
larly a module can only be unloaded if its cleanup func-
tion runs successfully.
zmodload -F [ -almLe -P param ] module [ [+-]feature ... ]
zmodload -F allows more selective control over the fea-
tures provided by modules. With no options apart from
-F, the module named module is loaded, if it was not al-
ready loaded, and the list of features is set to the re-
quired state. If no features are specified, the module
is loaded, if it was not already loaded, but the state of
features is unchanged. Each feature may be preceded by a
+ to turn the feature on, or - to turn it off; the + is
assumed if neither character is present. Any feature not
explicitly mentioned is left in its current state; if the
module was not previously loaded this means any such fea-
tures will remain disabled. The return status is zero if
all features were set, 1 if the module failed to load,
and 2 if some features could not be set (for example, a
parameter couldn't be added because there was a different
parameter of the same name) but the module was loaded.
The standard features are builtins, conditions, parame-
ters and math functions; these are indicated by the pre-
fix `b:', `c:' (`C:' for an infix condition), `p:' and
`f:', respectively, followed by the name that the corre-
sponding feature would have in the shell. For example,
`b:strftime' indicates a builtin named strftime and
p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS.
The module may provide other (`abstract') features of its
own as indicated by its documentation; these have no pre-
fix.
With -l or -L, features provided by the module are
listed. With -l alone, a list of features together with
their states is shown, one feature per line. With -L
alone, a zmodload -F command that would cause enabled
features of the module to be turned on is shown. With
-lL, a zmodload -F command that would cause all the fea-
tures to be set to their current state is shown. If one
of these combinations is given with the option -P param
then the parameter param is set to an array of features,
either features together with their state or (if -L alone
is given) enabled features.
With the option -L the module name may be omitted; then a
list of all enabled features for all modules providing
features is printed in the form of zmodload -F commands.
If -l is also given, the state of both enabled and dis-
abled features is output in that form.
A set of features may be provided together with -l or -L
and a module name; in that case only the state of those
features is considered. Each feature may be preceded by
+ or - but the character has no effect. If no set of
features is provided, all features are considered.
With -e, the command first tests that the module is
loaded; if it is not, status 1 is returned. If the mod-
ule is loaded, the list of features given as an argument
is examined. Any feature given with no prefix is simply
tested to see if the module provides it; any feature
given with a prefix + or - is tested to see if is pro-
vided and in the given state. If the tests on all fea-
tures in the list succeed, status 0 is returned, else
status 1.
With -m, each entry in the given list of features is
taken as a pattern to be matched against the list of fea-
tures provided by the module. An initial + or - must be
given explicitly. This may not be combined with the -a
option as autoloads must be specified explicitly.
With -a, the given list of features is marked for au-
toload from the specified module, which may not yet be
loaded. An optional + may appear before the feature
name. If the feature is prefixed with -, any existing
autoload is removed. The options -l and -L may be used
to list autoloads. Autoloading is specific to individual
features; when the module is loaded only the requested
feature is enabled. Autoload requests are preserved if
the module is subsequently unloaded until an explicit
`zmodload -Fa module -feature' is issued. It is not an
error to request an autoload for a feature of a module
that is already loaded.
When the module is loaded each autoload is checked
against the features actually provided by the module; if
the feature is not provided the autoload request is
deleted. A warning message is output; if the module is
being loaded to provide a different feature, and that au-
toload is successful, there is no effect on the status of
the current command. If the module is already loaded at
the time when zmodload -Fa is run, an error message is
printed and status 1 returned.
zmodload -Fa can be used with the -l, -L, -e and -P op-
tions for listing and testing the existence of autoload-
able features. In this case -l is ignored if -L is spec-
ified. zmodload -FaL with no module name lists autoloads
for all modules.
Note that only standard features as described above can
be autoloaded; other features require the module to be
loaded before enabling.
zmodload -d [ -L ] [ name ]
zmodload -d name dep ...
zmodload -ud name [ dep ... ]
The -d option can be used to specify module dependencies.
The modules named in the second and subsequent arguments
will be loaded before the module named in the first argu-
ment.
With -d and one argument, all dependencies for that mod-
ule are listed. With -d and no arguments, all module de-
pendencies are listed. This listing is by default in a
Makefile-like format. The -L option changes this format
to a list of zmodload -d commands.
If -d and -u are both used, dependencies are removed. If
only one argument is given, all dependencies for that
module are removed.
zmodload -ab [ -L ]
zmodload -ab [ -i ] name [ builtin ... ]
zmodload -ub [ -i ] builtin ...
The -ab option defines autoloaded builtins. It defines
the specified builtins. When any of those builtins is
called, the module specified in the first argument is
loaded and all its features are enabled (for selective
control of features use `zmodload -F -a' as described
above). If only the name is given, one builtin is de-
fined, with the same name as the module. -i suppresses
the error if the builtin is already defined or au-
toloaded, but not if another builtin of the same name is
already defined.
With -ab and no arguments, all autoloaded builtins are
listed, with the module name (if different) shown in
parentheses after the builtin name. The -L option
changes this format to a list of zmodload -a commands.
If -b is used together with the -u option, it removes
builtins previously defined with -ab. This is only pos-
sible if the builtin is not yet loaded. -i suppresses
the error if the builtin is already removed (or never ex-
isted).
Autoload requests are retained if the module is subse-
quently unloaded until an explicit `zmodload -ub builtin'
is issued.
zmodload -ac [ -IL ]
zmodload -ac [ -iI ] name [ cond ... ]
zmodload -uc [ -iI ] cond ...
The -ac option is used to define autoloaded condition
codes. The cond strings give the names of the conditions
defined by the module. The optional -I option is used to
define infix condition names. Without this option prefix
condition names are defined.
If given no condition names, all defined names are listed
(as a series of zmodload commands if the -L option is
given).
The -uc option removes definitions for autoloaded condi-
tions.
zmodload -ap [ -L ]
zmodload -ap [ -i ] name [ parameter ... ]
zmodload -up [ -i ] parameter ...
The -p option is like the -b and -c options, but makes
zmodload work on autoloaded parameters instead.
zmodload -af [ -L ]
zmodload -af [ -i ] name [ function ... ]
zmodload -uf [ -i ] function ...
The -f option is like the -b, -p, and -c options, but
makes zmodload work on autoloaded math functions instead.
zmodload -a [ -L ]
zmodload -a [ -i ] name [ builtin ... ]
zmodload -ua [ -i ] builtin ...
Equivalent to -ab and -ub.
zmodload -e [ -A ] [ string ... ]
The -e option without arguments lists all loaded modules;
if the -A option is also given, module aliases corre-
sponding to loaded modules are also shown. If arguments
are provided, nothing is printed; the return status is
set to zero if all strings given as arguments are names
of loaded modules and to one if at least on string is not
the name of a loaded module. This can be used to test
for the availability of things implemented by modules.
In this case, any aliases are automatically resolved and
the -A flag is not used.
zmodload -A [ -L ] [ modalias[=module] ... ]
For each argument, if both modalias and module are given,
define modalias to be an alias for the module module. If
the module modalias is ever subsequently requested, ei-
ther via a call to zmodload or implicitly, the shell will
attempt to load module instead. If module is not given,
show the definition of modalias. If no arguments are
given, list all defined module aliases. When listing, if
the -L flag was also given, list the definition as a
zmodload command to recreate the alias.
The existence of aliases for modules is completely inde-
pendent of whether the name resolved is actually loaded
as a module: while the alias exists, loading and unload-
ing the module under any alias has exactly the same ef-
fect as using the resolved name, and does not affect the
connection between the alias and the resolved name which
can be removed either by zmodload -R or by redefining the
alias. Chains of aliases (i.e. where the first resolved
name is itself an alias) are valid so long as these are
not circular. As the aliases take the same format as
module names, they may include path separators: in this
case, there is no requirement for any part of the path
named to exist as the alias will be resolved first. For
example, `any/old/alias' is always a valid alias.
Dependencies added to aliased modules are actually added
to the resolved module; these remain if the alias is re-
moved. It is valid to create an alias whose name is one
of the standard shell modules and which resolves to a
different module. However, if a module has dependencies,
it will not be possible to use the module name as an
alias as the module will already be marked as a loadable
module in its own right.
Apart from the above, aliases can be used in the zmodload
command anywhere module names are required. However,
aliases will not be shown in lists of loaded modules with
a bare `zmodload'.
zmodload -R modalias ...
For each modalias argument that was previously defined as
a module alias via zmodload -A, delete the alias. If any
was not defined, an error is caused and the remainder of
the line is ignored.
Note that zsh makes no distinction between modules that were
linked into the shell and modules that are loaded dynamically.
In both cases this builtin command has to be used to make avail-
able the builtins and other things defined by modules (unless
the module is autoloaded on these definitions). This is true
even for systems that don't support dynamic loading of modules.