1zmodload [ -dL ] [ ... ] 2zmodload -F [ -lLme -P param ] module [+-]feature... 3zmodload -e [ -A ] [ ... ] 4zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ... 5zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ... 6zmodload -A [ -L ] [ modalias[=module] ... ] 7zmodload -R modalias ... 8 Performs operations relating to zsh's loadable modules. Loading 9 of modules while the shell is running (`dynamical loading') is 10 not available on all operating systems, or on all installations 11 on a particular operating system, although the zmodload command 12 itself is always available and can be used to manipulate modules 13 built into versions of the shell executable without dynamical 14 loading. 15 16 Without arguments the names of all currently loaded binary mod- 17 ules are printed. The -L option causes this list to be in the 18 form of a series of zmodload commands. Forms with arguments 19 are: 20 21 zmodload [ -i ] name ... 22 zmodload -u [ -i ] name ... 23 In the simplest case, zmodload loads a binary module. 24 The module must be in a file with a name consisting of 25 the specified name followed by a standard suffix, usually 26 `.so' (`.sl' on HPUX). If the module to be loaded is 27 already loaded the duplicate module is ignored. If zmod- 28 load detects an inconsistency, such as an invalid module 29 name or circular dependency list, the current code block 30 is aborted. Hence `zmodload module 2>/dev/null' is suf- 31 ficient to test whether a module is available. If it is 32 available, the module is loaded if necessary, while if it 33 is not available, non-zero status is silently returned. 34 The option -i is accepted for compatibility but has no 35 effect. 36 37 The named module is searched for in the same way a com- 38 mand is, using $module path instead of $path. However, 39 - 40 the path search is performed even when the module name 41 contains a `/', which it usually does. There is no way 42 to prevent the path search. 43 44 If the module supports features (see below), zmodload 45 tries to enable all features when loading a module. If 46 the module was successfully loaded but not all features 47 could be enabled, zmodload returns status 2. 48 49 With -u, zmodload unloads modules. The same name must be 50 given that was given when the module was loaded, but it 51 is not necessary for the module to exist in the file sys- 52 tem. The -i option suppresses the error if the module is 53 already unloaded (or was never loaded). 54 55 Each module has a boot and a cleanup function. The mod- 56 ule will not be loaded if its boot function fails. Simi- 57 larly a module can only be unloaded if its cleanup func- 58 tion runs successfully. 59 60 zmodload -F [ -almLe -P param ] module [+-]feature... 61 zmodload -F allows more selective control over the fea- 62 tures provided by modules. With no options apart from 63 -F, the module named module is loaded, if it was not 64 already loaded, and the list of features is set to the 65 required state. If no features are specified, the module 66 is loaded, if it was not already loaded, but the state of 67 features is unchanged. Each feature may be preceded by a 68 + to turn the feature on, or - to turn it off; the + is 69 assumed if neither character is present. Any feature not 70 explicitly mentioned is left in its current state; if the 71 module was not previously loaded this means any such fea- 72 tures will remain disabled. The return status is zero if 73 all features were set, 1 if the module failed to load, 74 and 2 if some features could not be set (for example, a 75 parameter couldn't be added because there was a different 76 parameter of the same name) but the module was loaded. 77 78 The standard features are builtins, conditions, parame- 79 ters and math functions; these are indicated by the pre- 80 fix `b:', `c:' (`C:' for an infix condition), `p:' and 81 `f:', respectively, followed by the name that the corre- 82 sponding feature would have in the shell. For example, 83 `b:strftime' indicates a builtin named strftime and 84 p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS. 85 The module may provide other (`abstract') features of its 86 own as indicated by its documentation; these have no pre- 87 fix. 88 89 With -l or -L, features provided by the module are 90 listed. With -l alone, a list of features together with 91 their states is shown, one feature per line. With -L 92 alone, a zmodload -F command that would cause enabled 93 features of the module to be turned on is shown. With 94 -lL, a zmodload -F command that would cause all the fea- 95 tures to be set to their current state is shown. If one 96 of these combinations is given the option -P param then 97 the parameter param is set to an array of features, 98 either features together with their state or (if -L alone 99 is given) enabled features. 100 101 With the option -L the module name may be omitted; then a 102 list of all enabled features for all modules providing 103 features is printed in the form of zmodload -F commands. 104 If -l is also given, the state of both enabled and dis- 105 abled features is output in that form. 106 107 A set of features may be provided together with -l or -L 108 and a module name; in that case only the state of those 109 features is considered. Each feature may be preceded by 110 + or - but the character has no effect. If no set of 111 features is provided, all features are considered. 112 113 With -e, the command first tests that the module is 114 loaded; if it is not, status 1 is returned. If the mod- 115 ule is loaded, the list of features given as an argument 116 is examined. Any feature given with no prefix is simply 117 tested to see if the module provides it; any feature 118 given with a prefix + or - is tested to see if is pro- 119 vided and in the given state. If the tests on all fea- 120 tures in the list succeed, status 0 is returned, else 121 status 1. 122 123 With -m, each entry in the given list of features is 124 taken as a pattern to be matched against the list of fea- 125 tures provided by the module. An initial + or - must be 126 given explicitly. This may not be combined with the -a 127 option as autoloads must be specified explicitly. 128 129 With -a, the given list of features is marked for 130 autoload from the specified module, which may not yet be 131 loaded. An optional + may appear before the feature 132 name. If the feature is prefixed with -, any existing 133 autoload is removed. The options -l and -L may be used 134 to list autoloads. Autoloading is specific to individual 135 features; when the module is loaded only the requested 136 feature is enabled. Autoload requests are preserved if 137 the module is subsequently unloaded until an explicit 138 `zmodload -Fa module -feature' is issued. It is not an 139 error to request an autoload for a feature of a module 140 that is already loaded. 141 142 When the module is loaded each autoload is checked 143 against the features actually provided by the module; if 144 the feature is not provided the autoload request is 145 deleted. A warning message is output; if the module is 146 being loaded to provide a different feature, and that 147 autoload is successful, there is no effect on the status 148 of the current command. If the module is already loaded 149 at the time when zmodload -Fa is run, an error message is 150 printed and status 1 returned. 151 152 zmodload -Fa can be used with the -l, -L, -e and -P 153 options for listing and testing the existence of 154 autoloadable features. In this case -l is ignored if -L 155 is specified. zmodload -FaL with no module name lists 156 autoloads for all modules. 157 158 Note that only standard features as described above can 159 be autoloaded; other features require the module to be 160 loaded before enabling. 161 162 zmodload -d [ -L ] [ name ] 163 zmodload -d name dep ... 164 zmodload -ud name [ dep ... ] 165 The -d option can be used to specify module dependencies. 166 The modules named in the second and subsequent arguments 167 will be loaded before the module named in the first argu- 168 ment. 169 170 With -d and one argument, all dependencies for that mod- 171 ule are listed. With -d and no arguments, all module 172 dependencies are listed. This listing is by default in a 173 Makefile-like format. The -L option changes this format 174 to a list of zmodload -d commands. 175 176 If -d and -u are both used, dependencies are removed. If 177 only one argument is given, all dependencies for that 178 module are removed. 179 180 zmodload -ab [ -L ] 181 zmodload -ab [ -i ] name [ builtin ... ] 182 zmodload -ub [ -i ] builtin ... 183 The -ab option defines autoloaded builtins. It defines 184 the specified builtins. When any of those builtins is 185 called, the module specified in the first argument is 186 loaded and all its features are enabled (for selective 187 control of features use `zmodload -F -a' as described 188 above). If only the name is given, one builtin is 189 defined, with the same name as the module. -i suppresses 190 the error if the builtin is already defined or 191 autoloaded, but not if another builtin of the same name 192 is already defined. 193 194 With -ab and no arguments, all autoloaded builtins are 195 listed, with the module name (if different) shown in 196 parentheses after the builtin name. The -L option 197 changes this format to a list of zmodload -a commands. 198 199 If -b is used together with the -u option, it removes 200 builtins previously defined with -ab. This is only pos- 201 sible if the builtin is not yet loaded. -i suppresses 202 the error if the builtin is already removed (or never 203 existed). 204 205 Autoload requests are retained if the module is subse- 206 quently unloaded until an explicit `zmodload -ub builtin' 207 is issued. 208 209 zmodload -ac [ -IL ] 210 zmodload -ac [ -iI ] name [ cond ... ] 211 zmodload -uc [ -iI ] cond ... 212 The -ac option is used to define autoloaded condition 213 codes. The cond strings give the names of the conditions 214 defined by the module. The optional -I option is used to 215 define infix condition names. Without this option prefix 216 condition names are defined. 217 218 If given no condition names, all defined names are listed 219 (as a series of zmodload commands if the -L option is 220 given). 221 222 The -uc option removes definitions for autoloaded condi- 223 tions. 224 225 zmodload -ap [ -L ] 226 zmodload -ap [ -i ] name [ parameter ... ] 227 zmodload -up [ -i ] parameter ... 228 The -p option is like the -b and -c options, but makes 229 zmodload work on autoloaded parameters instead. 230 231 zmodload -af [ -L ] 232 zmodload -af [ -i ] name [ function ... ] 233 zmodload -uf [ -i ] function ... 234 The -f option is like the -b, -p, and -c options, but 235 makes zmodload work on autoloaded math functions instead. 236 237 zmodload -a [ -L ] 238 zmodload -a [ -i ] name [ builtin ... ] 239 zmodload -ua [ -i ] builtin ... 240 Equivalent to -ab and -ub. 241 242 zmodload -e [ -A ] [ string ... ] 243 The -e option without arguments lists all loaded modules; 244 if the -A option is also given, module aliases corre- 245 sponding to loaded modules are also shown. If arguments 246 are provided, nothing is printed; the return status is 247 set to zero if all strings given as arguments are names 248 of loaded modules and to one if at least on string is not 249 the name of a loaded module. This can be used to test 250 for the availability of things implemented by modules. 251 In this case, any aliases are automatically resolved and 252 the -A flag is not used. 253 254 zmodload -A [ -L ] [ modalias[=module] ... ] 255 For each argument, if both modalias and module are given, 256 define modalias to be an alias for the module module. If 257 the module modalias is ever subsequently requested, 258 either via a call to zmodload or implicitly, the shell 259 will attempt to load module instead. If module is not 260 given, show the definition of modalias. If no arguments 261 are given, list all defined module aliases. When list- 262 ing, if the -L flag was also given, list the definition 263 as a zmodload command to recreate the alias. 264 265 The existence of aliases for modules is completely inde- 266 pendent of whether the name resolved is actually loaded 267 as a module: while the alias exists, loading and unload- 268 ing the module under any alias has exactly the same 269 effect as using the resolved name, and does not affect 270 the connection between the alias and the resolved name 271 which can be removed either by zmodload -R or by redefin- 272 ing the alias. Chains of aliases (i.e. where the first 273 resolved name is itself an alias) are valid so long as 274 these are not circular. As the aliases take the same 275 format as module names, they may include path separators: 276 in this case, there is no requirement for any part of the 277 path named to exist as the alias will be resolved first. 278 For example, `any/old/alias' is always a valid alias. 279 280 Dependencies added to aliased modules are actually added 281 to the resolved module; these remain if the alias is 282 removed. It is valid to create an alias whose name is 283 one of the standard shell modules and which resolves to a 284 different module. However, if a module has dependencies, 285 it will not be possible to use the module name as an 286 alias as the module will already be marked as a loadable 287 module in its own right. 288 289 Apart from the above, aliases can be used in the zmodload 290 command anywhere module names are required. However, 291 aliases will not be shown in lists of loaded modules with 292 a bare `zmodload'. 293 294 zmodload -R modalias ... 295 For each modalias argument that was previously defined as 296 a module alias via zmodload -A, delete the alias. If any 297 was not defined, an error is caused and the remainder of 298 the line is ignored. 299 300 Note that zsh makes no distinction between modules that were 301 linked into the shell and modules that are loaded dynamically. 302 In both cases this builtin command has to be used to make avail- 303 able the builtins and other things defined by modules (unless 304 the module is autoloaded on these definitions). This is true 305 even for systems that don't support dynamic loading of modules. 306