diff options
Diffstat (limited to 'Doc/help/zmodload')
| -rw-r--r-- | Doc/help/zmodload | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/Doc/help/zmodload b/Doc/help/zmodload new file mode 100644 index 000000000..a19159d71 --- /dev/null +++ b/Doc/help/zmodload @@ -0,0 +1,308 @@ +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. |