miff

package: GraphicsMagick-ImageMagick-compat

title: miff(4)

text:
# miff(4)

## NAME
MIFF - Magick Image File Format

## SYNOPSIS
\#include <image.h>

## DESCRIPTION
The Magick Image File Format (MIFF) is a platform-independent format for storing bitmap images. MIFF is a part of the ImageMagick toolkit of image manipulation utilities for the X Window System. ImageMagick is capable of converting many different image file formats to and from MIFF (e.g. JPEG, XPM, TIFF, etc.).

A MIFF image file consist of two sections. The first section is a header composed of keys describing the image in text form. The next section is the binary image data. The header is separated from the image data by a : character immediately followed by a newline.

The MIFF header is composed entirely of LATIN-1 characters. The fields in the header are key and value combination in the key=value format, with each key and value separated by an equal sign (=). Each key=value combination is delimited by at least one control or whitespace character. Comments may appear in the header section and are always delimited by braces. The MIFF header always ends with a colon (:) character, followed by a ctrl-Z character. It is also common to proceed the colon with a formfeed and a newline character. The formfeed prevents the listing of binary data when using more(1) under Unix where the ctrl-Z has the same effect with the type command on the Win32 command line.

The following is a list of key=value combinations that may be found in a MIFF file:

background-color=color

border-color=color matte-color=color these optional keys reflects the image background, border, and matte colors respectively. A color can be a name (e.g. white) or a hex value (e.g. #ccc).

class=DirectClass

class=PseudoClass the type of binary image data stored in the MIFF file. If this key is not present, DirectClass image data is assumed.

colors=value

the number of colors in a DirectClass image. For a PseudoClass image, this key specifies the size of the colormap. If this key is not present in the header, and the image is PseudoClass, a linear 256 color grayscale colormap is used with the image data. The maximum number of colormap entries is 65535. colorspace=CMYK the colorspace of the pixel data. The default is RGB.

columns=value

the width of the image in pixels. This is a required key and has no default.

compression=BZip

compression=Fax compression=JPEG compression=LZW compression=RLE compression=Zip the type of algorithm used to compress the image data. If this key is not present, the image data is assumed to be uncompressed.

delay <1/100ths of a second>

the interframe delay in an image sequence. The maximum delay is 65535.

depth=8

depth=16 the depth of a single color value representing values from 0 to 255 (depth 8) or 65535 (depth 16). If this key is absent, a depth of 8 is assumed.

dispose value

GIF disposal method. Here are the valid methods:

```
     0  No disposal specified.

     1  Do not dispose between frames.

     2  Overwrite frame with background color from header.

     3  Overwrite with previous frame.
```

gamma=value

the gamma of the image. If it is not specified, a gamma of 1.0 (linear brightness response) is assumed,

id=ImageMagick

identifies the file as a MIFF-format image file. This key is required and has no default. Although this key can appear anywhere in the header, it should start as the first key of the header in column 1. This will allow programs like file(1) to easily identify the file as MIFF.

iterations value

the number of times an image sequence loops before stopping.

label={value}

defines a short title or caption for the image. If any whitespace appears in the label, it must be enclosed within braces.

matte=True

matte=False specifies whether a DirectClass image has matte data. Matte data is generally useful for image compositing. This key has no meaning for pseudo-color images.

montage=<width>x<height>{+-}<x offset>{+-}<y offset>

size and location of the individual tiles of a composite image. See X(1) for details about the geometry specification. Use this key when the image is a composite of a number of different tiles. A tile consists of an image and optionally a border and a label. <width> is the size in pixels of each individual tile in the horizontal direction and <height> is the size in the vertical direction. Each tile must have an equal number of pixels in width and equal in height. However, the width can differ from the height. <x offset> is the offset in number of pixels from the vertical edge of the composite image where the first tile of a row begins and <y offset> is the offset from the horizontal edge where the first tile of a column begins.

If this key is specified, a directory of tile names must follow the image header. The format of the directory is explained below.

page=value

preferred size and location of an image canvas.

profile-icc=value

the number of bytes in the International Color Consortium color profile. The profile is defined by the ICC profile specification located at ftp://sgigate.sgi.com/pub/icc/icc34.ps.

colorspace=RGB

red-primary=x,y

green-primary=x,y blue-primary=x,y white-point=x,y this optional key reflects the chromaticity primaries and white point.

rendering-intent=saturation

rendering-intent=perceptual rendering-intent=absolute rendering-intent=relative Rendering intent is the CSS-1 property that has been defined by the International Color Consortium (http://www.color.org).

resolution=<x-resolution>x<y-resolution>

vertical and horizontal resolution of the image. See units for the specific resolution units (e.g. pixels per inch).

rows=value

the height of the image in pixels. This is a required key and has no default.

scene=value

the sequence number for this MIFF image file. This optional key is used when a MIFF image file is one in a sequence of files used in an animation.

signature=value

this optional key contains a string that uniquely identifies the image pixel contents. NIST's SHA-256 message digest algorithm is recommended.

units=pixels-per-inch

units=pixels-per-centimeter image resolution units. Other key value pairs are permitted. If a value contains whitespace it must be enclosed with braces as illustrated here:

id=ImageMagick

class=PseudoClass colors=256

compression=RunlengthEncoded packets=27601

columns=1280 rows=1024

signature=d79e1c308aa5bbcdeea8ed63df412da9

copyright={Copyright (c) 2001 ImageMagick Studio}

<FF>

:

Note that key=value combinations may be separated by newlines or spaces and may occur in any order within the header. Comments (within braces) may appear anywhere before the colon.

If you specify the montage key in the header, follow the header with a directory of image tiles. This directory consists of a name for each tile of the composite image separated by a newline character. The list is terminated with a NULL character.

If you specify the color-profile key in the header, follow the header (or montage directory if the montage key is in the header) with the binary color profile.

Next comes the binary image data itself. How the image data is formatted depends upon the class of the image as specified (or not specified) by the value of the class key in the header.

DirectClass images (class=DirectClass) are continuous-tone, images stored as RGB (red, green, blue), RGBA (red, green, blue, alpha), or CMYK (cyan, yellow, magenta, black) intensity values as defined by the colorspace key. Each intensity value is one byte in length for images of depth 8 (0..255), whereas, images of depth 16 (0..65535) require two bytes in most significant byte first order.

PseudoClass images (class=PseudoClass) are colormapped RGB images. The colormap is stored as a series of red, green, and blue pixel values, each value being a byte in size. If the image depth is 16, each colormap entry consumes two bytes with the most significant byte being first. The number of colormap entries is defined by the colors key. The colormap data occurs immediately following the header (or image directory if the montage key is in the header). PseudoClass image data is an array of index values into the color map. If there are 256 or fewer colors in the image, each byte of image data contains an index value. If the image contains more than 256 colors or the image depth is 16, the index value is stored as two contiguous bytes with the most significant byte being first. If matte is true, each colormap index is followed by a 1 or 2-byte alpha value.

The image data in a MIFF file may be uncompressed, runlength encoded, Zip compressed, or BZip compressed. The compression key in the header defines how the image data is compressed. Uncompressed pixels are just stored one scanline at a time in row order. Runlength encoded compression counts runs of identical adjacent pixels and stores the pixels followed by a length byte (the number of identical pixels minus 1). Zip and BZip compression compresses each row of an image and preceeds the compressed row with the length of compressed pixel bytes as a word in most significant byte first order.

MIFF files may contain more than one image. Simply concatenate each individual image (composed of a header and image data) into one file.

## SEE ALSO
display(1), animate(1), import(1), montage(1), mogrify(1), convert(1), more(1), compress(1)

## COPYRIGHT
Copyright (C) 2000 ImageMagick Studio, a non-profit organization dedicated to making software imaging solutions freely available.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files ("ImageMagick"), to deal in ImageMagick without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of ImageMagick, and to permit persons to whom the ImageMagick is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of ImageMagick.

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall ImageMagick Studio be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with ImageMagick or the use or other dealings in ImageMagick.

Except as contained in this notice, the name of the ImageMagick Studio shall not be used in advertising or otherwise to promote the sale, use or other dealings in ImageMagick without prior written authorization from the ImageMagick Studio.

## AUTHORS
John Cristy, ImageMagick Studio


modulefile

package: environment-modules

title: modulefile(4)

text:
# modulefile(4)

## NAME
modulefile - files containing Tcl code for the Modules package

## DESCRIPTION
modulefiles are written in the Tool Command Language, Tcl(n) and are interpreted by the modulecmd.tcl program via the module(1) user interface. modulefiles can be loaded, unloaded, or switched on-the-fly while the user is working; and can be used to implement site policies regarding the access and use of applications.

A modulefile begins with the magic cookie, #%Module. A version number may be placed after this string. The version number is useful as the modulefile format may change thus it reflects the minimum version of modulecmd.tcl required to interpret the modulefile. If a version number doesn't exist, then modulecmd.tcl will assume the modulefile is compatible. Files without the magic cookie or with a version number greater than the current version of modulecmd.tcl will not be interpreted. If the mcookie_version_check configuration is disabled the version number set is not checked.

Each modulefile contains the changes to a user's environment needed to access an application. Tcl is a simple programming language which permits modulefiles to be arbitrarily complex, depending upon the application's and the modulefile writer's needs. If support for extended tcl (tclX) has been configured for your installation of the Modules package, you may use all the extended commands provided by tclX, too.

A typical modulefile is a simple bit of code that set or add entries to the PATH, MANPATH, or other environment variables. A Modulefile is evaluated against current modulecmd.tcl's mode which leads to specific evaluation results. For instance if the modulefile sets a value to an environment variable, this variable is set when modulefile is loaded and unset when modulefile is unloaded.

Tcl has conditional statements that are evaluated when the modulefile is interpreted. This is very effective for managing path or environment changes due to different OS releases or architectures. The user environment information is encapsulated into a single modulefile kept in a central location. The same modulefile is used by every user on any machine. So, from the user's perspective, starting an application is exactly the same irrespective of the machine or platform they are on.

modulefiles also hide the notion of different types of shells. From the user's perspective, changing the environment for one shell looks exactly the same as changing the environment for another shell. This is useful for new or novice users and eliminates the need for statements such as "if you're using the C Shell do this ..., otherwise if you're using the Bourne shell do this ...". Announcing and accessing new software is uniform and independent of the user's shell. From the modulefile writer's perspective, this means one set of information will take care of every type of shell.

## MODULES SPECIFIC TCL COMMANDS
The Modules Package uses commands which are extensions to the "standard" Tool Command Language Tcl(n) package. Unless otherwise specified, the Module commands return the empty string. Some commands behave differently when a modulefile is loaded or unloaded. The command descriptions assume the modulefile is being loaded.

append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...

See prepend-path.

break

This is not a Modules-specific command, it's actually part of Tcl, which has been overloaded similar to the continue and exit commands to have the effect of causing the module not to be listed as loaded and not affect other modules being loaded concurrently. All non-environment commands within the module will be performed up to this point and processing will continue on to the next module on the command line. The break command will only have this effect if not used within a Tcl loop though. An example: Suppose that a full selection of modulefiles are needed for various different architectures, but some of the modulefiles are not needed and the user should be alerted. Having the unnecessary modulefile be a link to the following notavail modulefile will perform the task as required.

```
#%Module1.0
## notavail modulefile
##
proc ModulesHelp { } {

    puts stderr "This module does nothing but alert the user"

    puts stderr "that the [module-info name] module is not available"
}
module-whatis "Notifies user that module is not available."
set curMod [module-info name]
if { [ module-info mode load ] } {

    puts stderr "Note: '$curMod' is not available for [uname sysname]."
}
break
```

chdir directory

Set the current working directory to directory.

conflict modulefile...

prereq and conflict control whether or not the modulefile will be loaded. The prereq command lists modulefiles which must have been previously loaded before the current modulefile will be loaded. Similarly, the conflict command lists modulefiles which conflict with the current modulefile. If a list contains more than one modulefile, then each member of the list acts as a Boolean OR operation. Multiple prereq and conflict commands may be used to create a Boolean AND operation. If one of the requirements have not been satisfied, an error is reported and the current modulefile makes no changes to the user's environment. If an argument for prereq is a directory and any modulefile from the directory has been loaded, then the prerequisite is met. For example, specifying X11 as a prereq means that any version of X11, X11/R4 or X11/R5, must be loaded before proceeding.

If an argument for conflict is a directory and any other modulefile from that directory has been loaded, then a conflict will occur. For example, specifying X11 as a conflict will stop X11/R4 and X11/R5 from being loaded at the same time.

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

continue

This is not a modules specific command but another overloaded Tcl command and is similar to the break or exit commands except the module will be listed as loaded as well as performing any environment or Tcl commands up to this point and then continuing on to the next module on the command line. The continue command will only have this effect if not used within a Tcl loop though.

exit [N]

This is not a modules specific command but another overloaded Tcl command and is similar to the break or continue commands. However, this command will cause the immediate cessation of this module and any additional ones on the command line. This module and the subsequent modules will not be listed as loaded. No environment commands will be performed in the current module.

getenv variable [value]

Returns value of environment variable. If variable is not defined, value is returned if set, _UNDEFINED_ is returned otherwise. The getenv command should be preferred over the Tcl global variable env to query environment variables.

is-avail modulefile...

The is-avail command returns a true value if any of the listed modulefiles exists in enabled MODULEPATH. If a list contains more than one modulefile, then each member acts as a boolean OR operation. If an argument for is-avail is a directory and a modulefile exists in the directory is-avail would return a true value. The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

is-loaded [modulefile...]

The is-loaded command returns a true value if any of the listed modulefiles has been loaded or if any modulefile is loaded in case no argument is provided. If a list contains more than one modulefile, then each member acts as a boolean OR operation. If an argument for is-loaded is a directory and any modulefile from the directory has been loaded is-loaded would return a true value. The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

is-saved [collection...]

The is-saved command returns a true value if any of the listed collections exists or if any collection exists in case no argument is provided. If a list contains more than one collection, then each member acts as a boolean OR operation. If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable is appended to the passed collection name. In case no collection argument is provided, a true value will only be returned if a collection matching currently set target exists.

is-used [directory...]

The is-used command returns a true value if any of the listed directories has been enabled in MODULEPATH or if any directory is enabled in case no argument is provided. If a list contains more than one directory, then each member acts as a boolean OR operation.

module [sub-command] [sub-command-options] [sub-command-args]

Contains the same sub-commands as described in the module(1) man page in the Module Sub-Commands section. This command permits a modulefile to load or unload other modulefiles. No checks are made to ensure that the modulefile does not try to load itself. Often it is useful to have a single modulefile that performs a number of module load commands. For example, if every user on the system requires a basic set of applications loaded, then a core modulefile would contain the necessary module load commands. The --not-req option may be set for the load, unload and switch sub-commands to inhibit the definition of an implicit prereq or conflict requirement onto specified modules.

Command line switches --auto, --no-auto and --force are ignored when passed to a module command set in a modulefile.

module-alias name modulefile

Assigns the modulefile to the alias name. This command should be placed in one of the modulecmd.tcl rc files in order to provide shorthand invocations of frequently used modulefile names. The parameter modulefile may be either

- a fully qualified modulefile with name and version

- a symbolic modulefile name

- another modulefile alias

module-forbid [options] modulefile...

Forbid use of modulefile. An error is obtained when trying to evaluate a forbidden module. This command should be placed in one of the modulecmd.tcl rc files. module-forbid command accepts the following options:

- --after datetime

- --before datetime

- --not-user {user...}

- --not-group {group...}

- --message {text message}

- --nearly-message {text message}

If --after option is set, forbidding is only effective after specified date time. Following the same principle, if --before option is set, forbidding is only effective before specified date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If no time (HH:MM) is specified, 00:00 is assumed. --after and --before options are not supported on Tcl versions prior to 8.5.

If --not-user option is set, forbidding is not applied if the username of the user currently running modulecmd.tcl is part of the list of username specified. Following the same approach, if --not-group option is set, forbidding is not applied if current user is member of one the group specified. When both options are set, forbidding is not applied if a match is found for --not-user or --not-group.

Error message returned when trying to evaluate a forbidden module can be supplemented with the text message set through --message option.

If --after option is set, modules are considered nearly forbidden during a number of days defined by the nearly_forbidden_days modulecmd.tcl configuration option (see MODULES_NEARLY_FORBIDDEN_DAYS), prior reaching the expiry date fixed by --after option. When a nearly forbidden module is evaluated a warning message is issued to inform module will soon be forbidden. This warning message can be supplemented with the text message set through --nearly-message option.

If a module-forbid command applies to a modulefile also targeted by a module-hide --hard command, this module is unveiled when precisely named to return an access error.

Forbidden modules included in the result of an avail sub-command are reported with a forbidden tag applied to them. Nearly forbidden modules included in the result of an avail or a list sub-command are reported with a nearly-forbidden tag applied to them. See Module tags section in module(1).

The parameter modulefile may leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

module-hide [options] modulefile...

Hide modulefile to exclude it from available module search or module selection unless query refers to modulefile by its exact name. This command should be placed in one of the modulecmd.tcl rc files. module-hide command accepts the following options:

- --soft|--hard

- --hidden-loaded

- --after datetime

- --before datetime

- --not-user {user...}

- --not-group {group...}

When --soft option is set, modulefile is also set hidden, but hiding is disabled when search or selection query's root name matches module's root name. This soft hiding mode enables to hide modulefiles from bare module availability listing yet keeping the ability to select such module for load with the regular resolution mechanism (i.e., no need to use module exact name to select it)

When --hard option is set, modulefile is also set hidden and stays hidden even if search or selection query refers to modulefile by its exact name.

When --hidden-loaded option is set, hidden state also applies to the modulefile when it is loaded. Hidden loaded modules do not appear on list sub-command output, unless --all option is set. Their loading or unloading informational messages are not reported unless the verbosity of Modules is set to a level higher than verbose. Hidden loaded modules are detected in any cases by state query commands like is-loaded.

If --after option is set, hiding is only effective after specified date time. Following the same principle, if --before option is set, hiding is only effective before specified date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If no time (HH:MM) is specified, 00:00 is assumed. --after and --before options are not supported on Tcl versions prior to 8.5.

If --not-user option is set, hiding is not applied if the username of the user currently running modulecmd.tcl is part of the list of username specified. Following the same approach, if --not-group option is set, hiding is not applied if current user is member of one the group specified. When both options are set, hiding is not applied if a match is found for --not-user or --not-group.

If the --all option is set on avail, aliases, whatis or search sub-commands, hiding is disabled thus hidden modulefiles are included in module search. Hard-hidden modules (i.e., declared hidden with --hard option) are not affected by --all and stay hidden even if option is set. --all option does not apply to module selection sub-commands like load. Thus in such context a hidden module should always be referred by its exact full name (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft mode. A hard-hidden module cannot be unveiled or selected in any case.

If several module-hide commands target the same modulefile, the strongest hiding level is retained which means if both a regular, a --soft hiding command match a given module, regular hiding mode is considered. If both a regular and a --hard hiding command match a given module, hard hiding mode is retained. A set --hidden-loaded option is retained even if the module-hide statement on which it is declared is superseded by a stronger module-hide statement with no --hidden-loaded option set.

Hidden modules included in the result of an avail sub-command are reported with a hidden tag applied to them. Hidden loaded modules included in the result of a list sub-command are reported with a hidden-loaded tag applied to them. This tag is not reported on avail sub-command context. See Module tags section in module(1).

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

module-info option [info-args]

Provide information about the modulecmd.tcl program's state. Some of the information is specific to the internals of modulecmd.tcl. option is the type of information to be provided, and info-args are any arguments needed. module-info alias name

Returns the full modulefile name to which the modulefile alias name is assigned

module-info command [commandname]

Returns the currently running modulecmd.tcl's command as a string if no commandname is given. Returns 1 if modulecmd.tcl's command is commandname. commandname can be: load, unload, reload, source, switch, display, avail, aliases, list, whatis, search, purge, restore, help or test.

module-info loaded modulefile

Returns the names of currently loaded modules matching passed modulefile. The parameter modulefile might either be a fully qualified modulefile with name and version or just a directory which in case all loaded modulefiles from the directory will be returned. The parameter modulefile may also be a symbolic modulefile name or a modulefile alias.

module-info mode [modetype]

Returns the current modulecmd.tcl's mode as a string if no modetype is given. Returns 1 if modulecmd.tcl's mode is modetype. modetype can be: load, unload, remove, switch, display, help, test or whatis.

module-info name

Return the name of the modulefile. This is not the full pathname for modulefile. See the Modules Variables section for information on the full pathname.

module-info shell [shellname]

Return the current shell under which modulecmd.tcl was invoked if no shellname is given. The current shell is the first parameter of modulecmd.tcl, which is normally hidden by the module alias. If a shellname is given, returns 1 if modulecmd.tcl's current shell is shellname, returns 0 otherwise. shellname can be: sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby, lisp, cmake, r.

module-info shelltype [shelltypename]

Return the family of the shell under which modulefile was invoked if no shelltypename is given. As of module-info shell this depends on the first parameter of modulecmd.tcl. The output reflects a shell type determining the shell syntax of the commands produced by modulecmd.tcl. If a shelltypename is given, returns 1 if modulecmd.tcl's current shell type is shelltypename, returns 0 otherwise. shelltypename can be: sh, csh, fish, tcl, perl, python, ruby, lisp, cmake, r.

module-info specified

Return the name of the modulefile specified on the command line.

module-info symbols modulefile

Returns a list of all symbolic versions assigned to the passed modulefile. The parameter modulefile might either be a full qualified modulefile with name and version, another symbolic modulefile name or a modulefile alias.

module-info tags [tag]

Returns all tags assigned to currently evaluated modulefile as a list of strings if no tag name is given (see Module tags section in module(1)) Returns 1 if one of the tags applying to currently evaluated modulefile is tag. Returns 0 otherwise.

module-info type

Returns either C or Tcl to indicate which module command is being executed, either the C version or the Tcl-only version, to allow the modulefile writer to handle any differences between the two.

module-info usergroups [name]

Returns all the groups the user currently running modulecmd.tcl is member of as a list of strings if no name is given. Returns 1 if one of the group current user running modulecmd.tcl is member of is name. Returns 0 otherwise.

If the Modules Tcl extension library is disabled, the id(1) command is invoked to fetch groups of current user.

module-info username [name]

Returns the username of the user currently running modulecmd.tcl as a string if no name is given. Returns 1 if username of current user running modulecmd.tcl is name. Returns 0 otherwise.

If the Modules Tcl extension library is disabled, the id(1) command is invoked to fetch username of current user.

module-info version modulefile

Returns the physical module name and version of the passed symbolic version modulefile. The parameter modulefile might either be a full qualified modulefile with name and version, another symbolic modulefile name or a modulefile alias.

module-tag [options] tag modulefile...

Associate tag to designated modulefile. This tag information will be reported along modulefile on avail and list sub-commands (see Module tags section in module(1)). Tag information can be queried during modulefile evaluation with the module-info tags modulefile command. module-tag commands should be placed in one of the modulecmd.tcl rc files. module-tag command accepts the following options:

- --not-user {user...}

- --not-group {group...}

If --not-user option is set, the tag is not applied if the username of the user currently running modulecmd.tcl is part of the list of username specified. Following the same approach, if --not-group option is set, the tag is not applied if current user is member of one the group specified. When both options are set, the tag is not applied if a match is found for --not-user or --not-group.

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

Tags inherited from other modulefile commands or module states cannot be set with module-tag. Otherwise an error is returned. Those special tags are: auto-loaded, forbidden, hidden, hidden-loaded, loaded and nearly-forbidden.

When tag equals sticky or super-sticky, designated modulefile are defined Sticky modules.

module-version modulefile version-name...

Assigns the symbolic version-name to the modulefile. This command should be placed in one of the modulecmd.tcl rc files in order to provide shorthand invocations of frequently used modulefile names. The special version-name default specifies the default version to be used for module commands, if no specific version is given. This replaces the definitions made in the .version file in former modulecmd.tcl releases.

The parameter modulefile may be either

- a fully or partially qualified modulefile with name / version. If name is . (dot) then the current directory name is assumed to be the module name. (Use this for deep modulefile directories.)

- a symbolic modulefile name

- another modulefile alias

module-virtual name modulefile

Assigns the modulefile to the virtual module name. This command should be placed in rc files in order to define virtual modules. A virtual module stands for a module name associated to a modulefile. The modulefile is the script interpreted when loading or unloading the virtual module which appears or can be found with its virtual name.

The parameter modulefile corresponds to the relative or absolute file location of a modulefile.

module-whatis string

Defines a string which is displayed in case of the invocation of the module whatis command. There may be more than one module-whatis line in a modulefile. This command takes no actions in case of load, display, etc. invocations of modulecmd.tcl. The string parameter has to be enclosed in double-quotes if there's more than one word specified. Words are defined to be separated by whitespace characters (space, tab, cr).

prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable value...

Append or prepend value to environment variable. The variable is a colon, or delimiter, separated list such as PATH=directory:directory:directory. The default delimiter is a colon :, but an arbitrary one can be given by the --delim option. For example a space can be used instead (which will need to be handled in the Tcl specially by enclosing it in " " or { }). A space, however, can not be specified by the --delim=C form. A reference counter environment variable is also set to increase the number of times value has been added to environment variable. This reference counter environment variable is named by suffixing variable by _modshare.

When value is already defined in environment variable, it is not added again except if --duplicates option is set.

If the variable is not set, it is created. When a modulefile is unloaded, append-path and prepend-path become remove-path.

If value corresponds to the concatenation of multiple elements separated by colon, or delimiter, character, each element is treated separately.

prereq modulefile...

See conflict.

remove-path [-d C|--delim C|--delim=C] [--index] variable value...

Remove value from the colon, or delimiter, separated list in variable. See prepend-path or append-path for further explanation of using an arbitrary delimiter. Every string between colons, or delimiters, in variable is compared to value. If the two match, value is removed from variable if its reference counter is equal to 1 or unknown. When --index option is set, value refers to an index in variable list. The string element pointed by this index is set for removal.

Reference counter of value in variable denotes the number of times value has been added to variable. This information is stored in environment variable_modshare. When attempting to remove value from variable, relative reference counter is checked and value is removed only if counter is equal to 1 or not defined. Otherwise value is kept in variable and reference counter is decreased by 1.

If value corresponds to the concatenation of multiple elements separated by colon, or delimiter, character, each element is treated separately.

set-alias alias-name alias-string

Sets an alias or function with the name alias-name in the user's environment to the string alias-string. For some shells, aliases are not possible and the command has no effect. When a modulefile is unloaded, set-alias becomes unset-alias.

set-function function-name function-string

Creates a function with the name function-name in the user's environment with the function body function-string. For some shells, functions are not possible and the command has no effect. When a modulefile is unloaded, set-function becomes unset-function.

setenv variable value

Set environment variable to value. The setenv command will also change the process' environment. A reference using Tcl's env associative array will reference changes made with the setenv command. Changes made using Tcl's env associative array will NOT change the user's environment variable like the setenv command. An environment change made this way will only affect the module parsing process. The setenv command is also useful for changing the environment prior to the exec or system command. When a modulefile is unloaded, setenv becomes unsetenv. If the environment variable had been defined it will be overwritten while loading the modulefile. A subsequent unload will unset the environment variable - the previous value cannot be restored! (Unless you handle it explicitly ... see below.)

source-sh shell script [arg...]

Evaluate with shell the designated script with defined arguments to find out the environment changes it does. Those changes obtained by comparing environment prior and after script evaluation are then translated into corresponding modulefile commands, which are then applied during modulefile evaluation as if they were directly written in it. When modulefile is unloaded, environment changes done are reserved by evaluating in the unload context the resulting modulefile commands, which were recorded in the MODULES_LMSOURCESH environment variable at load time.

Changes on environment variables, shell aliases, shell functions and current working directory are tracked.

Shell could be specified as a command name or a fully qualified pathname. The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93, zsh and fish.

system string

Run string command through shell. On Unix, command is passed to the /bin/sh shell whereas on Windows it is passed to cmd.exe. modulecmd.tcl redirects stdout to stderr since stdout would be parsed by the evaluating shell. The exit status of the executed command is returned.

uname field

Provide lookup of system information. Most field information are retrieved from the tcl_platform array (see the tclvars(n) man page). Uname will return the string unknown if information is unavailable for the field. uname will invoke the uname(1) command in order to get the operating system version and domainname(1) to figure out the name of the domain.

field values are:

- sysname: the operating system name

- nodename: the hostname

- domain: the name of the domain

- release: the operating system release

- version: the operating system version

- machine: a standard name that identifies the system's hardware

unset-alias alias-name

Unsets an alias with the name alias-name in the user's environment.

unset-function function-name

Removes a function with the name function-name from the user's environment.

unsetenv variable [value]

Unsets environment variable. However, if there is an optional value, then when unloading a module, it will set variable to value. The unsetenv command changes the process' environment like setenv.

versioncmp version1 version2

Compare version string version1 against version string version2. Returns -1, 0 or 1 respectively if version1 is less than, equal to or greater than version2.

x-resource [resource-string|filename]

Merge resources into the X11 resource database. The resources are used to control look and behavior of X11 applications. The command will attempt to read resources from filename. If the argument isn't a valid file name, then string will be interpreted as a resource. Either filename or resource-string is then passed down to be xrdb(1) command. modulefiles that use this command, should in most cases contain one or more x-resource lines, each defining one X11 resource. The DISPLAY environment variable should be properly set and the X11 server should be accessible. If x-resource can't manipulate the X11 resource database, the modulefile will exit with an error message.

Examples:

x-resource /u2/staff/leif/.xres/Ileaf

The content of the Ileaf file is merged into the X11 resource database.

x-resource [glob ~/.xres/ileaf]

The Tcl glob function is used to have the modulefile read different resource files for different users.

x-resource {Ileaf.popup.saveUnder: True}

Merge the Ileaf resource into the X11 resource database.

## MODULES VARIABLES
ModulesCurrentModulefile

The ModulesCurrentModulefile variable contains the full pathname of the modulefile being interpreted.

ModuleTool

The ModuleTool variable contains the name of the module implementation currently in use. The value of this variable is set to Modules for this implementation.

ModuleToolVersion

The ModuleToolVersion variable contains the version of the module implementation currently in use. The value of this variable is set to 4.7.1 for this version of Modules.

## LOCATING MODULEFILES
Every directory in MODULEPATH is searched to find the modulefile. A directory in MODULEPATH can have an arbitrary number of sub-directories. If the user names a modulefile to be loaded which is actually a directory, the directory is opened and a search begins for an actual modulefile. First, modulecmd.tcl looks for a file with the name .modulerc in the directory. If this file exists, its contents will be evaluated as if it was a modulefile to be loaded. You may place module-version, module-alias and module-virtual commands inside this file.

Additionally, before seeking for .modulerc files in the module directory, the global modulerc file and the .modulerc file found at the root of the modulepath directory are sourced, too. If a named version default now exists for the modulefile to be loaded, the assigned modulefile now will be sourced. Otherwise the file .version is looked up in the module directory.

If the .version file exists, it is opened and interpreted as Tcl code and takes precedence over a .modulerc file in the same directory. If the Tcl variable ModulesVersion is set by the .version file, modulecmd.tcl will use the name as if it specifies a modulefile in this directory. This will become the default modulefile in this case. ModulesVersion cannot refer to a modulefile located in a different directory.

If ModulesVersion is a directory, the search begins anew down that directory. If the name does not match any files located in the current directory, the search continues through the remaining directories in MODULEPATH.

Every .version and .modulerc file found is interpreted as Tcl code. The difference is that .version only applies to the current directory, and the .modulerc applies to the current directory and all subdirectories. Changes made in these files will affect the subsequently interpreted modulefile.

If no default version may be figured out, an implicit default is selected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in module(1)). If disabled, module names should be fully qualified when no explicit default is defined for them, otherwise no default version is found and an error is returned. If enabled, then the highest numerically sorted modulefile, virtual module or module alias under the directory will be used. The dictionary comparison method of the lsort(n) Tcl command is used to achieve this sort. If highest numerically sorted element is an alias, search continues on its modulefile target.

For example, it is possible for a user to have a directory named X11 which simply contains a .version file specifying which version of X11 is to be loaded. Such a file would look like:

```
#%Module1.0
##
##  The desired version of X11
##
set ModulesVersion "R4"
```

The equivalent .modulerc would look like:

```
#%Module1.0
##
##  The desired version of X11
##
module-version "./R4" default
```

If the extended default mechanism is enabled (see MODULES_EXTENDED_DEFAULT in module(1)) the module version specified is matched against starting portion of existing module versions, where portion is a substring separated from the rest of version string by a . character.

When the implicit default mechanism and the Advanced module version specifiers are both enabled, a default and latest symbolic versions are automatically defined for each module name (also at each directory level in case of deep modulefile). Unless a symbolic version, alias, or regular module version already exists for these version names.

If user names a modulefile that cannot be found in the first modulepath directory, modulefile will be searched in next modulepath directory and so on until a matching modulefile is found. If search goes through a module alias or a symbolic version, this alias or symbol is resolved by first looking at the modulefiles in the modulepath where this alias or symbol is defined. If not found, resolution looks at the other modulepaths in their definition order.

When locating modulefiles, if a .modulerc, a .version, a directory or a modulefile cannot be read during the search it is simply ignored with no error message produced. Visibility of modulefiles can thus be adapted to the rights the user has been granted. Exception is made when trying to directly access a directory or a modulefile. In this case, the access issue is returned as an error message.

Depending on their name, their file permissions or the use of specific modulefile commands, modulefile, virtual module, module alias or symbolic version may be set hidden which impacts available modules search or module selection processes (see Hiding modulefiles section below).

## HIDING MODULEFILES
A modulefile, virtual module, module alias or symbolic version whose name or element in their name starts with a dot character (.) or who are targeted by a module-hide command are considered hidden. Hidden modules are not displayed or taken into account except if they are explicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has been hidden with the --soft option of the module-hide command set, it is not considered hidden if the root name of the query to search it matches module root name (e.g., searching foo will return a foo/1.2.3 modulefile targeted by a module-hide --soft command). If module has been hidden with the --hard option of the module-hide command set, it is always considered hidden thus it is never displayed nor taken into account even if it is explicitly named.

A modulefile, virtual module, module alias or symbolic version who are targeted by a module-hide --hard command and a module-forbid command or whose file access permissions are restricted are considered hard-hidden and forbidden. Such modules are not displayed or taken into account. When explicitly named for evaluation selection, such modules are unveiled to return an access error.

A symbolic version-name assigned to a hidden module is displayed or taken into account only if explicitly named and if module is not hard-hidden. Non-hidden module alias targeting a hidden modulefile appears like any other non-hidden module alias. Finally, a hidden symbolic version targeting a non-hidden module is displayed or taken into account only if not hard-hidden and explicitly named to refer to its non-hidden target.

The automatic version symbols (e.g., default and latest) are unaffected by hiding. Moreover when a regular default or latest version is set hidden, the corresponding automatic version symbol takes the left spot. For instance, if foo/default which targets foo/1.2.3 is set hard-hidden, the default automatic version symbol will be set onto foo/2.1.3, the highest available version of foo.

When loading a modulefile or a virtual module targeted by a module-hide --hidden-loaded command, this module inherits the hidden-loaded tag. Hidden loaded modules are not reported among list sub-command results.

If the --all is set on avail, aliases, whatis or search sub-commands, hidden modules are taken into account in search. Hard-hidden modules are unaffected by this option.

If the --all is set on list sub-command, hidden loaded modules are included in result output.

## ADVANCED MODULE VERSION SPECIFIERS
When the advanced module version specifiers mechanism is enabled (see MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of modulefile passed on Modules specific Tcl commands changes. After the module name a version constraint prefixed by the @ character may be added. It could be directly appended to the module name or separated from it with a space character.

Constraints can be expressed to refine the selection of module version to:

- a single version with the @version syntax, for instance foo@1.2.3 syntax will select module foo/1.2.3

- a list of versions with the @version1,version2,... syntax, for instance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10

- a range of versions with the @version1:, @:version2 and @version1:version2 syntaxes, for instance foo@1.2: will select all versions of module foo greater than or equal to 1.2, foo@:1.3 will select all versions less than or equal to 1.3 and foo@1.2:1.3 matches all versions between 1.2 and 1.3 including 1.2 and 1.3 versions

Advanced specification of single version or list of versions may benefit from the activation of the extended default mechanism (see MODULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like @1 to refer to more precise version numbers like 1.2.3. Range of versions on its side natively handles abbreviated versions.

In order to be specified in a range of versions or compared to a range of versions, the version major element should corresponds to a number. For instance 10a, 1.2.3, 1.foo are versions valid for range comparison whereas default or foo.2 versions are invalid for range comparison.

If the implicit default mechanism is also enabled (see MODULES_IMPLICIT_DEFAULT in module(1)), a default and latest symbolic versions are automatically defined for each module name (also at each directory level for deep modulefiles). These automatic version symbols are defined unless a symbolic version, alias, or regular module version already exists for these default or latest version names. Using the mod@latest (or mod/latest) syntax ensures highest available version will be selected.

## MODULEFILE SPECIFIC HELP
Users can request help about a specific modulefile through the module(1) command. The modulefile can print helpful information or start help oriented programs by defining a ModulesHelp subroutine. The subroutine will be called when the module help modulefile command is used.

## MODULEFILE SPECIFIC TEST
Users can request test of a specific modulefile through the module(1) command. The modulefile can perform some sanity checks on its definition or on its underlying programs by defining a ModulesTest subroutine. The subroutine will be called when the module test modulefile command is used. The subroutine should return 1 in case of success. If no or any other value is returned, test is considered failed.

## MODULEFILE DISPLAY
The module display modulefile command will detail all changes that will be made to the environment. After displaying all of the environment changes modulecmd.tcl will call the ModulesDisplay subroutine. The ModulesDisplay subroutine is a good place to put additional descriptive information about the modulefile.

## ENVIRONMENT
See the ENVIRONMENT section in the module(1) man page.

## SEE ALSO
module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domainname(1), tclvars(n), lsort(n)

## NOTES
Tcl was developed by John Ousterhout at the University of California at Berkeley.

TclX was developed by Karl Lehenbauer and Mark Diekhans.

## COPYRIGHT
1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2021 Xavier Delaruelle


modulefile-compat

package: environment-modules-compat

title: modulefile-compat(4)

text:
# modulefile-compat(4)

## NAME
modulefile - files containing Tcl code for the Modules package

## DESCRIPTION
modulefiles are written in the Tool Command Language, Tcl(3) and are interpreted by the modulecmd program via the module(1) user interface. modulefiles can be loaded, unloaded, or switched on-the-fly while the user is working; and can be used to implement site policies regarding the access and use of applications.

A modulefile begins with the magic cookie, '#%Module'. A version number may be placed after this string. The version number is useful as the modulefile format may change. If a version number doesn't exist, then modulecmd will assume the modulefile is compatible with the latest version. The current modulefile version is 1.0. Files without the magic cookie will not be interpreted by modulecmd.

Each modulefile contains the changes to a user's environment needed to access an application. Tcl is a simple programming language which permits modulefiles to be arbitrarily complex, depending upon the application's and the modulefile writer's needs. If support for extended tcl (tclX) has been configured for your installation of the Modules package, you may use all the extended commands provided by tclX, too.

A typical modulefile is a simple bit of code that set or add entries to the PATH, MANPATH, or other environment variables. Tcl has conditional statements that are evaluated when the modulefile is loaded. This is very effective for managing path or environment changes due to different OS releases or architectures. The user environment information is encapsulated into a single modulefile kept in a central location. The same modulefile is used by every user on any machine. So, from the user's perspective, starting an application is exactly the same irrespective of the machine or platform they are on.

modulefiles also hide the notion of different types of shells. From the user's perspective, changing the environment for one shell looks exactly the same as changing the environment for another shell. This is useful for new or novice users and eliminates the need for statements such as "if you're using the C Shell do this ..., otherwise if you're using the Bourne shell do this ..." Announcing and accessing new software is uniform and independent of the user's shell. From the modulefile writer's perspective, this means one set of information will take care of every type of shell.

## Modules Specific Tcl Commands
The Modules Package uses commands which are extensions to the "standard" Tool Command Language Tcl(3) package. Unless otherwise specified, the Module commands return the empty string. Some commands behave differently when a modulefile is loaded or unloaded. The command descriptions assume the modulefile is being loaded.

break

This is not a Modules-specific command, it's actually part of Tcl, which has been overloaded similar to the continue and exit commands to have the effect of causing the module not to be listed as loaded and not affect other modules being loaded concurrently. All non-environment commands within the module will be performed up to this point and processing will continue on to the next module on the command line. The break command will only have this effect if not used within a Tcl loop though. An example: Suppose that a full selection of modulefiles are needed for various different architectures, but some of the modulefiles are not needed and the user should be alerted. Having the unnecessary modulefile be a link to the following notavail modulefile will perform the task as required.

```
#%Module1.0
## notavail modulefile
##
proc ModulesHelp { } {

    puts stderr	"This module does nothing but alert the user"

    puts stderr	"that the [module-info name] module is not available"
}
module-whatis	"Notifies user that module is not available."
set curMod [module-info name]
if { [ module-info mode load ] } {

    puts stderr	"Note: '$curMod' is not available for [uname sysname]."
}
break
```

chdir directory

Set the current working directory to directory.

continue

This is not a modules specific command but another overloaded Tcl command and is similar to the break or exit commands except the module will be listed as loaded as well as performing any environment or Tcl commands up to this point and then continuing on to the next module on the command line. The continue command will only have this effect if not used within a Tcl loop though.

exit [N]

This is not a modules specific command but another overloaded Tcl command and is similar to the break or continue commands. However, this command will cause the immediate cessation of this module and any additional ones on the command line. This module and the subsequent modules will not be listed as loaded. No environment commands will be performed in the current module. The integer value N after the exit command will be used as an command exit value; however, some shells (bash being one of them) do not carry this value through an eval though. For bash and those Bourne shells (/bin/sh) being emulated by the bash will have return a non-zero value as a result of test 0 = 1 being appended to the evaluate string.

setenv variable value

Set environment variable to value. The setenv command will also change the process' environment. A reference using Tcl's env associative array will reference changes made with the setenv command. Changes made using Tcl's env associative array will NOT change the user's environment variable like the setenv command. An environment change made this way will only affect the module parsing process. The setenv command is also useful for changing the environment prior to the exec or system command. When a modulefile is unloaded, setenv becomes unsetenv. If the environment variable had been defined it will be overwritten while loading the modulefile. A subsequent unload will unset the environment variable - the previous value cannot be restored! (Unless you handle it explicitly ... see below.)

unsetenv variable [value]

Unsets environment variable. However, if there is an optional value, then when unloading a module, it will set variable to value. The unsetenv command changes the process' environment like setenv.

append-path [ -d C | --delim C | --delim=C ] variable value

prepend-path [ -d C | --delim C | --delim=C ] variable value

Append or prepend value to environment variable. The variable is a colon, or delimiter, separated list such as

"PATH=directory:directory:directory". The default delimiter is a colon ':', but an arbitrary one can be given by the --delim option. For example a space can be used instead (which will need to be handled in the Tcl specially by enclosing it in " " or { }). A space, however, can not be specified by the --delim=C form. If the variable is not set, it is created. When a modulefile is unloaded, append-path and prepend-path become remove-path.

remove-path [ -d C | --delim C | --delim=C ] variable value

Remove value from the colon, or delimiter, separated list in variable. See prepend-path or append-path for further explanation of using an arbitrary delimiter. Every string between colons, or delimiters, in variable is compared to value. If the two match, value is removed from variable.

prereq modulefile [ modulefile ... ]

conflict modulefile [ modulefile ... ]

prereq and conflict control whether or not the modulefile will be loaded. The prereq command lists modulefiles which must have been previously loaded before the current modulefile will be loaded. Similarly, the conflict command lists modulefiles which conflict with the current modulefile. If a list contains more than one modulefile, then each member of the list acts as a Boolean OR operation. Multiple prereq and conflict commands may be used to create a Boolean AND operation. If one of the requirements have not been satisfied, an error is reported and the current modulefile makes no changes to the user's environment. If an argument for prereq is a directory and any modulefile from the directory has been loaded, then the prerequisite is met. For example, specifying X11 as a prereq means that any version of X11, X11/R4 or X11/R5, must be loaded before proceeding.

If an argument for conflict is a directory and any other modulefile from that directory has been loaded, then a conflict will occur. For example, specifying X11 as a conflict will stop X11/R4 and X11/R5 from being loaded at the same time.

is-loaded modulefile [ modulefile ... ]

The is-loaded command returns a true value if any of the listed modulefiles has been loaded. If a list contains more than one modulefile, then each member acts as a boolean OR operation. If an argument for is-loaded is a directory and any modulefile from the directory has been loaded is-loaded would return a true value.

module [ sub-command ] [ sub-command-args ]

Contains the same sub-commands as described in the module(1) man page in the Module Sub-Commands section. This command permits a modulefile to load or remove other modulefiles. No checks are made to ensure that the modulefile does not try to load itself. Often it is useful to have a single modulefile that performs a number of module load commands. For example, if every user on the system requires a basic set of applications loaded, then a core modulefile would contain the necessary module load commands.

module-info option [ info-args ]

Provide information about the modulecmd program's state. Some of the information is specific to the internals of modulecmd. option is the type of information to be provided, and info-args are any arguments needed. module-info type

Returns either "C" or "Tcl" to indicate which module command is being executed, either the "C" version or the Tcl-only version, to allow the modulefile writer to handle any differences between the two.

module-info flags Returns the integer value of modulecmd's flags state.

module-info mode [modetype] Returns the current modulecmd's mode as a string if no modetype is given. Returns 1 if modulecmd's mode is modetype. modetype can be: load, remove, display, help, whatis, switch, switch1, switch2, or switch3.

module-info name

Return the name of the modulefile. This is not the full pathname for modulefile. See the Modules Variables section for information on the full pathname.

module-info specified

Return the name of the modulefile specified on the command line.

module-info shell

Return the current shell under which modulecmd was invoked. This is the first parameter of modulecmd, which is normally hidden by the module alias.

module-info shelltype

Return the family of the shell under which modulefile was invoked. As of module-info shell this depends on the first parameter of modulecmd. The output reflects a shell type determining the shell syntax of the commands produced by modulecmd.

module-info alias name

Returns the full module file name to which the module file alias name is assigned

module-info version module-file

Returns a list of all symbolic versions assigned to the passed module-file. The paremeter module-file might either be a full qualified module file with name and version, another symbolic module file name or a module file alias.

module-version module-file version-name [version-name ...]

Assigns the symbolic version-name to the module file module-file This command should be placed in one of the modulecmd rc files in order to provide shorthand invocations of frequently used module file names. The special version-name default specifies the default version to be used for module commands, if no specific version is given. This replaces the definitions made in the .version file in former modulecmd releases.

The parameter module-file may be either

a fully qualified modulefile with name and version

a symbolic module file name

another module file alias

module-alias name module-file

Assignes the module file module-file to the alias name. This command should be placed in one of the modulecmd rc files in order to provide shorthand invocations of frequently used module file names. The parameter module-file may be either

a fully qualified modulefile with name and version

a symbolic module file name

another module file alias

module-trace {on|off} [command [command ...]] [-module modulefile [modulefile ...]]

Switches tracing on or off. Without parameters this command will affect globally all tracing setups for all commands and modulefiles. The command parameter may be used to affect tracing of specified module commands only and the switch -module finally limits the affect of the module-trace command to a well defined set of module files. The command may be one of the following

avail - 'module avail' command

clear - 'module clear' command

display - 'module display' command

init - 'module init' command

help - 'module help' command

list - 'module list' command

load - 'module load' command

purge - 'module purge' command

switch - 'module switch' command

unuse - 'module unuse' command

unload - 'module unload' command

update - 'module update' command

use - 'module use' command

The module parameter specifies a set of module files using TCL regular expressions. For example

.* will affect all module files

*/2.0 affects all module files at version 2.0

gnu/.* affects all versions of the gnu modulefile

gnu/2.0 affects only version 2.0 of the gnu modulefile

The module parameter is prepended to the current tracing pattern list for the specified module command. It is evaluated from the left to the right. The first matching pattern defines the tracing parameter.

The internal trace pattern list is stored as a colon separated list. In advanced user level only, colons may be specified on the module parameter of the module-trace command. This will directly take effect in the internal trace pattern list. In novice or expert user level a warning messge will be generated.

module-user level

Defines the user level under wich module-cmd runs. This takes effect on the error messages being produced and on the behavior of modulecmd in case of detecting an outage. The level parameter specifies the user level and may be one of the following values:

advanced, adv - advanced user level

expert, exp - expert user level

novice, nov - novice user level

module-verbosity {on|off}

Switches verbose modulecmd message display on or off.

module-log error-weight log-facility

Defines whether error messages of the specified weight should be logged and conditionally assignes a log-facility. The error-weight parameter specifies the error level to be logged. It may be one of the following values:

verb - verbose messages

info - informal messages

debug - debugging messages

trace - tracing output

warn - warnings

prob - problems (normally the modulecmd may be completed)

error - errors (which normally leads to unsuccessful end of the modulecmd)

fatal - fatal system errors

panic - very fatal system errors, e.g. internal program inconsistencies.

The log-facility parameter specifies the log destination. This may either switch off logging for the specified error-weight, direct log messages to a special stream or a file or specify a syslog facility for logging. The following values are allowed:

stderr, stdout - predefined output streams for normal and error outputs. Note, that stdout is normally used for passing parameters to the invoking shell. Directing error output to this stream might screw up the modulecmd integration to your shell.

a syslog facility - directs logging to the syslog. See syslog.conf(4) for detailed description of the valid syslog facilities.

null, none - will suppress logging of the specified error-weight.

a filename - is recognized by the first character being either a '.' or a '/'. You must have write permission to the file you specify.

module-whatis string

Defines a string which is displayed in case of the invocation of the 'module whatis' command. There may be more than one module-whatis line in a modulefile. This command takes no actions in case of load, display, etc. invocations of modulecmd. The string parameter has to be enclosed in double-quotes if there's more than one word specified. Words are defined to be separated by whitespace characters (space, tab, cr).

set-alias alias-name alias-string

Sets an alias or function with the name alias-name in the user's environment to the string alias-string. Arguments can be specified using the Bourne Shell style of function arguments. If the string contains "$1", then this will become the first argument when the alias is interpreted by the shell. The string "$*" corresponds to all of the arguments given to the alias. The character '$' may be escaped using the '\' character. For some shells, aliases are not possible and the command has no effect. For Bourne shell derivatives, a shell function will be written (if supported) to give the impression of an alias. When a modulefile is unloaded, set-alias becomes unset-alias.

unset-alias alias-name

Unsets an alias with the name alias-name in the user's environment. If the shell supports functions then the shell is instructed to unset function alias-name.

system string

Pass string to the C library routine system(3). For the system(3) call modulecmd redirects stdout to stderr since stdout would be parsed by the evaluating shell. The exit status of the executed command is returned.

uname field

Provide fast lookup of system information on systems that support uname(3). uname is significantly faster than using system to execute a program to return host information. If uname(3) is not available, gethostname(3) or some program will make the nodename available. uname will return the string "unknown" if information is unavailable for the field. uname will invoke getdomainname in order to figure out the name of the domain.

field values are:

sysname - the operating system name

nodename - the hostname

domain - the name of the domain

release - the operating system release

version - the operating system version

machine - a standard name that identifies the system's hardware

x-resource resource-string

x-resource filename

Merge resources into the X11 resource database. The resources are used to control look and behavior of X11 applications. The command will attempt to read resources from filename. If the argument isn't a valid file name, then string will be interpreted as a resource. If a file is found, it will be filtered through the cpp(1) preprocessor, just as xrdb(1) would do. modulefiles that use this command, should in most cases contain one or more x-resource lines, each defining one X11 resource. Reading resources from filename is much slower, due to the preprocessing. The DISPLAY environment variable should be properly set and the X11 server should be accessible. If x-resource can't manipulate the X11 resource database, the modulefile will exit with an error message.

Examples:

x-resource /u2/staff/leif/.xres/Ileaf

The file Ileaf is preprocessed by cpp(1) and the result is merged into the X11 resource database.

x-resource [glob ~/.xres/ileaf]

The Tcl glob function is used to have the modulefile read different resource files for different users.

x-resource {Ileaf.popup.saveUnder: True}

Merge the Ileaf resource into the X11 resource database.

## Modules Variables
The ModulesCurrentModulefile variable contains the full pathname of the modulefile being interpreted.

## Locating Modulefiles
Every directory in MODULEPATH is searched to find the modulefile. A directory in MODULEPATH can have an arbitrary number of sub-directories. If the user names a modulefile to be loaded which is actually a directory, the directory is opened and a search begins for an actual modulefile. First, modulecmd looks for a file with the name .modulerc in the directory. If this file exists, its contents will be evaluated as if it was a module file to be loaded. You may place module-version and module-alias commands inside this file. Additionally, before seeking for .modulerc files in the module directory, the global .modulerc file is sourced, too. If a named version default now exists for the module file to be loaded, the assigned modulefile now will be sourced. Otherwise the file .version is looked up in the directory. If the .version file exists, it is opened and interpreted as Tcl code and takes precedence over a .modulerc file in the same directory. If the Tcl variable ModulesVersion is set by the .version file, modulecmd will use the name as if it specifies a modulefile in the directory. This will become the default module file in this case. If ModulesVersion is a directory, the search begins anew down that directory. If the name does not match any files located in the current directory, the search continues through the remaining directories in MODULEPATH.

Every .version and .modulerc file found is Tcl interpreted. So, changes made in these file will affect the subsequently interpreted modulefile.

If no default version may be figured out, then the highest lexicographically sorted modulefile under the directory using the 'C' locale will be used.

For example, it is possible for a user to have a directory named X11 which simply contains a .version file specifying which version of X11 is to be loaded. Such a file would look like:

```
#%Module1.0
##
##  The desired version of X11
##
set ModulesVersion "R4"
```

## Modulefile Specific Help
Users can request help about a specific modulefile through the module(1) command. The modulefile can print helpful information or start help oriented programs by defining a ModulesHelp subroutine. The subroutine will be called when the 'module help modulefile' command is used.

## Modulefile Display
The 'module display modulefile' command will detail all changes that will be made to the environment. After displaying all of the environment changes modulecmd will call the ModulesDisplay subroutine. The ModulesDisplay subroutine is a good place to put additional descriptive information about the modulefile.

## ENVIRONMENT
${MODULEPATH}

Path of directories containing modulefiles.

## VERSION
3.2.13

## SEE ALSO
module(1), Tcl(3), TclX(3), xrdb(1), cpp(1), system(3), uname(3), gethostname(3) getdomainname(3)

## NOTES
Tcl was developed by John Ousterhout at the University of California at Berkeley.

TclX was developed by Karl Lehenbauer and Mark Diekhans.


title: magic5(4)

summary: file command's magic pattern file

text:
# magic5(4)

## NAME
magic — file command's magic pattern file

## DESCRIPTION
This manual page documents the format of magic files as used by the file(1) command, version 5.36. The file(1) command identifies the type of a file using, among other tests, a test for whether the file contains certain “magic patterns”. The database of these “magic patterns” is usually located in a binary file in /usr/share/file5/magic.mgc or a directory of source text magic pattern fragment files in /usr/share/file5/magic. The database specifies what patterns are to be tested for, what message or MIME type to print if a particular pattern is found, and additional information to extract from the file.

The format of the source fragment files that are used to build this database is as follows: Each line of a fragment file specifies a test to be performed. A test compares the data starting at a particular offset in the file with a byte value, a string or a numeric value. If the test succeeds, a message is printed. The line consists of the following fields:

offset

A number specifying the offset (in bytes) into the file of the data which is to be tested. This offset can be a negative number if it is:

- The first direct offset of the magic entry (at continuation level 0), in which case it is interpreted an offset from end end of the file going backwards. This works only when a file descriptor to the file is a available and it is a regular file.

- A continuation offset relative to the end of the last up-level field (&).

type

The type of the data to be tested. The possible values are: byte

A one-byte value.

short

A two-byte value in this machine's native byte order.

long

A four-byte value in this machine's native byte order.

quad

An eight-byte value in this machine's native byte order.

float

A 32-bit single precision IEEE floating point number in this machine's native byte order.

double

A 64-bit double precision IEEE floating point number in this machine's native byte order.

string

A string of bytes. The string type specification can be optionally followed by /[WwcCtbT]*. The “W” flag compacts whitespace in the target, which must contain at least one whitespace character. If the magic has n consecutive blanks, the target needs at least n consecutive blanks to match. The “w” flag treats every blank in the magic as an optional blank. The “c” flag specifies case insensitive matching: lower case characters in the magic match both lower and upper case characters in the target, whereas upper case characters in the magic only match upper case characters in the target. The “C” flag specifies case insensitive matching: upper case characters in the magic match both lower and upper case characters in the target, whereas lower case characters in the magic only match upper case characters in the target. To do a complete case insensitive match, specify both “c” and “C”. The “t” flag forces the test to be done for text files, while the “b” flag forces the test to be done for binary files. The “T” flag causes the string to be trimmed, i.e. leading and trailing whitespace is deleted before the string is printed.

pstring

A Pascal-style string where the first byte/short/int is interpreted as the unsigned length. The length defaults to byte and can be specified as a modifier. The following modifiers are supported: B

A byte length (default).

H

A 2 byte big endian length.

h

A 2 byte little endian length.

L

A 4 byte big endian length.

l

A 4 byte little endian length.

J

The length includes itself in its count.

The string is not NUL terminated. “J” is used rather than the more valuable “I” because this type of length is a feature of the JPEG format.

date

A four-byte value interpreted as a UNIX date.

qdate

A eight-byte value interpreted as a UNIX date.

ldate

A four-byte value interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

qldate

An eight-byte value interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

qwdate

An eight-byte value interpreted as a Windows-style date.

beid3

A 32-bit ID3 length in big-endian byte order.

beshort

A two-byte value in big-endian byte order.

belong

A four-byte value in big-endian byte order.

bequad

An eight-byte value in big-endian byte order.

befloat

A 32-bit single precision IEEE floating point number in big-endian byte order.

bedouble

A 64-bit double precision IEEE floating point number in big-endian byte order.

bedate

A four-byte value in big-endian byte order, interpreted as a Unix date.

beqdate

An eight-byte value in big-endian byte order, interpreted as a Unix date.

beldate

A four-byte value in big-endian byte order, interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

beqldate

An eight-byte value in big-endian byte order, interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

beqwdate

An eight-byte value in big-endian byte order, interpreted as a Windows-style date.

bestring16

A two-byte unicode (UCS16) string in big-endian byte order.

leid3

A 32-bit ID3 length in little-endian byte order.

leshort

A two-byte value in little-endian byte order.

lelong

A four-byte value in little-endian byte order.

lequad

An eight-byte value in little-endian byte order.

lefloat

A 32-bit single precision IEEE floating point number in little-endian byte order.

ledouble

A 64-bit double precision IEEE floating point number in little-endian byte order.

ledate

A four-byte value in little-endian byte order, interpreted as a UNIX date.

leqdate

An eight-byte value in little-endian byte order, interpreted as a UNIX date.

leldate

A four-byte value in little-endian byte order, interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

leqldate

An eight-byte value in little-endian byte order, interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

leqwdate

An eight-byte value in little-endian byte order, interpreted as a Windows-style date.

lestring16

A two-byte unicode (UCS16) string in little-endian byte order.

melong

A four-byte value in middle-endian (PDP-11) byte order.

medate

A four-byte value in middle-endian (PDP-11) byte order, interpreted as a UNIX date.

meldate

A four-byte value in middle-endian (PDP-11) byte order, interpreted as a UNIX-style date, but interpreted as local time rather than UTC.

indirect

Starting at the given offset, consult the magic database again. The offset of the indirect magic is by default absolute in the file, but one can specify /r to indicate that the offset is relative from the beginning of the entry.

name

Define a “named” magic instance that can be called from another use magic entry, like a subroutine call. Named instance direct magic offsets are relative to the offset of the previous matched entry, but indirect offsets are relative to the beginning of the file as usual. Named magic entries always match.

use

Recursively call the named magic starting from the current offset. If the name of the referenced begins with a ^ then the endianness of the magic is switched; if the magic mentioned leshort for example, it is treated as beshort and vice versa. This is useful to avoid duplicating the rules for different endianness.

regex

A regular expression match in extended POSIX regular expression syntax (like egrep). Regular expressions can take exponential time to process, and their performance is hard to predict, so their use is discouraged. When used in production environments, their performance should be carefully checked. The size of the string to search should also be limited by specifying /<length>, to avoid performance issues scanning long files. The type specification can also be optionally followed by /[c][s][l]. The “c” flag makes the match case insensitive, while the “s” flag update the offset to the start offset of the match, rather than the end. The “l” modifier, changes the limit of length to mean number of lines instead of a byte count. Lines are delimited by the platforms native line delimiter. When a line count is specified, an implicit byte count also computed assuming each line is 80 characters long. If neither a byte or line count is specified, the search is limited automatically to 8KiB. ^ and $ match the beginning and end of individual lines, respectively, not beginning and end of file.

search

A literal string search starting at the given offset. The same modifier flags can be used as for string patterns. The search expression must contain the range in the form /number, that is the number of positions at which the match will be attempted, starting from the start offset. This is suitable for searching larger binary expressions with variable offsets, using \ escapes for special characters. The order of modifier and number is not relevant.

default

This is intended to be used with the test x (which is always true) and it has no type. It matches when no other test at that continuation level has matched before. Clearing that matched tests for a continuation level, can be done using the clear test.

clear

This test is always true and clears the match flag for that continuation level. It is intended to be used with the default test.

For compatibility with the Single UNIX Standard, the type specifiers dC and d1 are equivalent to byte, the type specifiers uC and u1 are equivalent to ubyte, the type specifiers dS and d2 are equivalent to short, the type specifiers uS and u2 are equivalent to ushort, the type specifiers dI, dL, and d4 are equivalent to long, the type specifiers uI, uL, and u4 are equivalent to ulong, the type specifier d8 is equivalent to quad, the type specifier u8 is equivalent to uquad, and the type specifier s is equivalent to string. In addition, the type specifier dQ is equivalent to quad and the type specifier uQ is equivalent to uquad.

Each top-level magic pattern (see below for an explanation of levels) is classified as text or binary according to the types used. Types “regex” and “search” are classified as text tests, unless non-printable characters are used in the pattern. All other tests are classified as binary. A top-level pattern is considered to be a test text when all its patterns are text patterns; otherwise, it is considered to be a binary pattern. When matching a file, binary patterns are tried first; if no match is found, and the file looks like text, then its encoding is determined and the text patterns are tried.

The numeric types may optionally be followed by & and a numeric value, to specify that the value is to be AND'ed with the numeric value before any comparisons are done. Prepending a u to the type indicates that ordered comparisons should be unsigned.

test

The value to be compared with the value from the file. If the type is numeric, this value is specified in C form; if it is a string, it is specified as a C string with the usual escapes permitted (e.g. \n for new-line). Numeric values may be preceded by a character indicating the operation to be performed. It may be =, to specify that the value from the file must equal the specified value, <, to specify that the value from the file must be less than the specified value, >, to specify that the value from the file must be greater than the specified value, &, to specify that the value from the file must have set all of the bits that are set in the specified value, ^, to specify that the value from the file must have clear any of the bits that are set in the specified value, or ~, the value specified after is negated before tested. x, to specify that any value will match. If the character is omitted, it is assumed to be =. Operators &, ^, and ~ don't work with floats and doubles. The operator ! specifies that the line matches if the test does not succeed.

Numeric values are specified in C form; e.g. 13 is decimal, 013 is octal, and 0x13 is hexadecimal.

Numeric operations are not performed on date types, instead the numeric value is interpreted as an offset.

For string values, the string from the file must match the specified string. The operators =, < and > (but not &) can be applied to strings. The length used for matching is that of the string argument in the magic file. This means that a line can match any non-empty string (usually used to then print the string), with >\0 (because all non-empty strings are greater than the empty string).

Dates are treated as numerical values in the respective internal representation.

The special test x always evaluates to true.

message

The message to be printed if the comparison succeeds. If the string contains a printf(3) format specification, the value from the file (with any specified masking performed) is printed using the message as the format string. If the string begins with “\b”, the message printed is the remainder of the string with no whitespace added before it: multiple matches are normally separated by a single space.

An APPLE 4+4 character APPLE creator and type can be specified as:

```
!:apple	CREATYPE
```

A MIME type is given on a separate line, which must be the next non-blank or comment line after the magic line that identifies the file type, and has the following format:

```
!:mime	MIMETYPE
```

i.e. the literal string “!:mime” followed by the MIME type.

An optional strength can be supplied on a separate line which refers to the current magic description using the following format:

```
!:strength OP VALUE
```

The operand OP can be: +, -, *, or / and VALUE is a constant between 0 and 255. This constant is applied using the specified operand to the currently computed default magic strength.

Some file formats contain additional information which is to be printed along with the file type or need additional tests to determine the true file type. These additional tests are introduced by one or more > characters preceding the offset. The number of > on the line indicates the level of the test; a line with no > at the beginning is considered to be at level 0. Tests are arranged in a tree-like hierarchy: if the test on a line at level n succeeds, all following tests at level n+1 are performed, and the messages printed if the tests succeed, until a line with level n (or less) appears. For more complex files, one can use empty messages to get just the "if/then" effect, in the following way:

```
0      string   MZ
>0x18  leshort  <0x40   MS-DOS executable
>0x18  leshort  >0x3f   extended PC executable (e.g., MS Windows)
```

Offsets do not need to be constant, but can also be read from the file being examined. If the first character following the last > is a ( then the string after the parenthesis is interpreted as an indirect offset. That means that the number after the parenthesis is used as an offset in the file. The value at that offset is read, and is used again as an offset in the file. Indirect offsets are of the form: (( x [[.,][bBcCeEfFgGhHiIlmsSqQ]][+-][ y ]). The value of x is used as an offset in the file. A byte, id3 length, short or long is read at that offset depending on the [bBcCeEfFgGhHiIlmsSqQ] type specifier. The value is treated as signed if “”, is specified or unsigned if “”. is specified. The capitalized types interpret the number as a big endian value, whereas the small letter versions interpret the number as a little endian value; the m type interprets the number as a middle endian (PDP-11) value. To that number the value of y is added and the result is used as an offset in the file. The default type if one is not specified is long. The following types are recognized:

Type

Sy Mnemonic

Sy Endian

Sy Size

bcBc

Byte/Char

N/A

1

efg

Double

Little

8

EFG

Double

Big

8

hs

Half/Short

Little

2

HS

Half/Short

Big

2

i

ID3

Little

4

I

ID3

Big

4

m

Middle

Middle

4

q

Quad

Little

8

Q

Quad

Big

8

That way variable length structures can be examined:

```
# MS Windows executables are also valid MS-DOS executables
0           string  MZ
>0x18       leshort <0x40   MZ executable (MS-DOS)
# skip the whole block below if it is not an extended executable
>0x18       leshort >0x3f
>>(0x3c.l)  string  PE\0\0  PE executable (MS-Windows)
>>(0x3c.l)  string  LX\0\0  LX executable (OS/2)
```

This strategy of examining has a drawback: you must make sure that you eventually print something, or users may get empty output (such as when there is neither PE\0\0 nor LE\0\0 in the above example).

If this indirect offset cannot be used directly, simple calculations are possible: appending [+-*/%&|^]number inside parentheses allows one to modify the value read from the file before it is used as an offset:

```
# MS Windows executables are also valid MS-DOS executables
0           string  MZ
# sometimes, the value at 0x18 is less that 0x40 but there's still an
# extended executable, simply appended to the file
>0x18       leshort <0x40
>>(4.s*512) leshort 0x014c  COFF executable (MS-DOS, DJGPP)
>>(4.s*512) leshort !0x014c MZ executable (MS-DOS)
```

Sometimes you do not know the exact offset as this depends on the length or position (when indirection was used before) of preceding fields. You can specify an offset relative to the end of the last up-level field using ‘&’ as a prefix to the offset:

```
0           string  MZ
>0x18       leshort >0x3f
>>(0x3c.l)  string  PE\0\0    PE executable (MS-Windows)
# immediately following the PE signature is the CPU type
>>>&0       leshort 0x14c     for Intel 80386
>>>&0       leshort 0x184     for DEC Alpha
```

Indirect and relative offsets can be combined:

```
0             string  MZ
>0x18         leshort <0x40
>>(4.s*512)   leshort !0x014c MZ executable (MS-DOS)
# if it's not COFF, go back 512 bytes and add the offset taken
# from byte 2/3, which is yet another way of finding the start
# of the extended executable
>>>&(2.s-514) string  LE      LE executable (MS Windows VxD driver)
```

Or the other way around:

```
0                 string  MZ
>0x18             leshort >0x3f
>>(0x3c.l)        string  LE\0\0  LE executable (MS-Windows)
# at offset 0x80 (-4, since relative offsets start at the end
# of the up-level match) inside the LE header, we find the absolute
# offset to the code area, where we look for a specific signature
>>>(&0x7c.l+0x26) string  UPX     \b, UPX compressed
```

Or even both!

```
0                string  MZ
>0x18            leshort >0x3f
>>(0x3c.l)       string  LE\0\0 LE executable (MS-Windows)
# at offset 0x58 inside the LE header, we find the relative offset
# to a data area where we look for a specific signature
>>>&(&0x54.l-3)  string  UNACE  \b, ACE self-extracting archive
```

If you have to deal with offset/length pairs in your file, even the second value in a parenthesized expression can be taken from the file itself, using another set of parentheses. Note that this additional indirect offset is always relative to the start of the main indirect offset.

```
0                 string       MZ
>0x18             leshort      >0x3f
>>(0x3c.l)        string       PE\0\0 PE executable (MS-Windows)
# search for the PE section called ".idata"...
>>>&0xf4          search/0x140 .idata
# ...and go to the end of it, calculated from start+length;
# these are located 14 and 10 bytes after the section name
>>>>(&0xe.l+(-4)) string       PK\3\4 \b, ZIP self-extracting archive
```

If you have a list of known values at a particular continuation level, and you want to provide a switch-like default case:

```
# clear that continuation level match
>18	clear
>18	lelong	1	one
>18	lelong	2	two
>18	default	x
# print default match
>>18	lelong	x	unmatched 0x%x
```

## SEE ALSO
file(1) - the command that reads this file.

## BUGS
The formats long, belong, lelong, melong, short, beshort, and leshort do not depend on the length of the C data types short and long on the platform, even though the Single UNIX Specification implies that they do. However, as OS X Mountain Lion has passed the Single UNIX Specification validation suite, and supplies a version of file(1) in which they do not depend on the sizes of the C data types and that is built for a 64-bit environment in which long is 8 bytes rather than 4 bytes, presumably the validation suite does not test whether, for example long refers to an item with the same size as the C data type long. There should probably be type names int8, uint8, int16, uint16, int32, uint32, int64, and uint64, and specified-byte-order variants of them, to make it clearer that those types have specified widths.