diff options
Diffstat (limited to 'Doc/help/zmodload')
| -rw-r--r-- | Doc/help/zmodload | 304 |
1 files changed, 152 insertions, 152 deletions
diff --git a/Doc/help/zmodload b/Doc/help/zmodload index a19159d71..735241b57 100644 --- a/Doc/help/zmodload +++ b/Doc/help/zmodload @@ -6,235 +6,235 @@ 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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- + 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 + 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- + 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- + 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 + 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 + + 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 + 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, + 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. + 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, + 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- + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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- + 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 + 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 + 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- + 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 + 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 + 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 + 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 + 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 + 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- + 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 + 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 + (as a series of zmodload commands if the -L option is given). - The -uc option removes definitions for autoloaded condi- + 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 + 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 + The -f option is like the -b, -p, and -c options, but makes zmodload work on autoloaded math functions instead. zmodload -a [ -L ] @@ -244,65 +244,65 @@ zmodload -R modalias ... 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 + 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 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- + 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 + 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 + 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 + 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 + 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 + 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 + 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, + 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 + 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. + 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 + 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. |